Skip to content

Commit 91fd2b4

Browse files
mchwangclaude
andauthored
Design system and plan format (#1)
* Add Evidence Desk design system and design review specs - DESIGN.md: tokens, type, layout, components (provenance gutter, file-change cards, logo), motion, and a decisions log. - CLAUDE.md: point UI work at DESIGN.md. - Design doc: screen specifications from the design review (D12-D28) and mark D22 done. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Add plan schema, import format, and plan-author prompt - schema/plan.schema.json: plan format v1, strict-mode compatible, used by claude --json-schema and codex exec --output-schema and for imports. - schema/plan-edit.schema.json: typed plan-assistant suggestions. - schema/examples/: #412 r3 plan (YAML) and a suggestion reply. - docs/plan-format.md: plain-language guide, checks after import, versions. - prompts/plan-author.md: one prompt for both agents. - Design doc: rewrite "The plan format", add decision P1 and task T18, list the four new approved mockups. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Fix clone isolation and plan validation contracts * Address automated review of plan safety and design docs * Address second Copilot review: container lock-down, symlinks, cmd wording - Design doc: lock down agent containers (read-only root, tmpfs scratch, non-root, no capabilities, no host mounts, resource limits) with a start-up self-test; /work is the only lasting writable place. T1 verify steps extended. Fix the last "three checks" to four. - plan-format.md: reject symlink components and .git targets in path and renamed_from; after each run, reject undeclared symlinks, symlinks that leave the repo, and any .git change; run codeboost's git with hooks off. - Both schemas, the guide, and the prompt describe cmd as one program with literal arguments run without a shell. Example P2 command no longer contains a quoted pipe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Add Copilot instructions from guardyx-gstack Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Address remaining design review contracts for approval and import * Specify schema retention and serialize repository prompt data * Close phase enforcement and merge validation contract gaps * Qualify retained schema identities and reject directory declarations * Require full argv approval across plan command contracts * Specify disk quotas and link and submodule execution boundaries * Specify invocation trust and guarded merge requirements * Align attribution and scope summaries with review contracts * Clarify review-only gitlinks and immutable suggestion file paths * Define deterministic JSON-compatible plan parsing * Define foreign ledger ownership and out-of-scope continuation * Align accepted decision summaries with typed ledger contracts * Branch rebase conflict handling on ledger ownership first * Reconcile recovery and rebase flows with review invariants * Version semantic contracts and bind suggestions to captured plan identity * Use shell-free adapter examples and pin v1 reference links * Keep stdin guidance consistent with direct process launching * Close metadata aliases, link target audits, and prompt data gaps * Bind non-text approvals and clarify runtime symlink guarantees * Specify suggestion refresh after apply and identity regression cases * Bind approval IDs and require bounded validated planning launches * Bound command capture and isolate registry schema registration --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 5036e0f commit 91fd2b4

16 files changed

Lines changed: 3658 additions & 67 deletions

‎.github/copilot-instructions.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# GitHub Copilot Instructions
2+
3+
# Rules
4+
- **Output:** Code only. No conversational filler, explanations, or markdown commentary unless explicitly requested.
5+
- **Format:** Return raw code blocks or terse, single-sentence bullets.
6+
- **Style:** Match the existing codebase architecture, formatting, and naming conventions exactly.
7+
8+
# Context Control
9+
- **Scope:** Provide solutions targeting only the highlighted code or specified file. Do not assume or generate surrounding boilerplate.

‎CLAUDE.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,9 @@ Key routing rules:
1616
- Save progress → invoke /context-save
1717
- Resume context → invoke /context-restore
1818
- Author a backlog-ready spec/issue → invoke /spec
19+
20+
## Design System
21+
Always read DESIGN.md before making any visual or UI decisions.
22+
All font choices, colors, spacing, and aesthetic direction are defined there.
23+
Do not deviate without explicit user approval.
24+
In QA mode, flag any code that doesn't match DESIGN.md.

‎DESIGN.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
---
2+
# gstack: design-md-format=spec
3+
name: codeboost
4+
description: Evidence Desk. A near-black inspection surface with fine lines, where every changed line shows which plan item it belongs to.
5+
colors:
6+
canvas: "#101216"
7+
surface: "#171B21"
8+
surface-raised: "#20262E"
9+
surface-selected: "#213448"
10+
line: "#343D49"
11+
control-outline: "#758295"
12+
text: "#E8ECF1"
13+
text-muted: "#A5AFBD"
14+
primary: "#8ABFFF"
15+
on-primary: "#101216"
16+
primary-hover: "#A6CEFF"
17+
focus-ring: "#8ABFFF"
18+
success: "#8FDDA8"
19+
warning: "#E9BE6E"
20+
error: "#F2847E"
21+
neutral-status: "#9AA3B0"
22+
diff-added-bg: "#1B2C24"
23+
diff-removed-bg: "#33201F"
24+
unplanned-hatch: "#F2847E"
25+
typography:
26+
display:
27+
fontFamily: IBM Plex Sans
28+
fontWeight: 600
29+
fontSize: 1.25rem
30+
lineHeight: 1.4
31+
letterSpacing: 0em
32+
heading:
33+
fontFamily: IBM Plex Sans
34+
fontWeight: 600
35+
fontSize: 1rem
36+
lineHeight: 1.5
37+
body:
38+
fontFamily: IBM Plex Sans
39+
fontWeight: 400
40+
fontSize: 0.8125rem
41+
lineHeight: 1.385
42+
reading:
43+
fontFamily: IBM Plex Sans
44+
fontWeight: 400
45+
fontSize: 0.875rem
46+
lineHeight: 1.5
47+
label:
48+
fontFamily: IBM Plex Sans
49+
fontWeight: 500
50+
fontSize: 0.75rem
51+
letterSpacing: 0em
52+
mono:
53+
fontFamily: IBM Plex Mono
54+
fontWeight: 400
55+
fontSize: 0.75rem
56+
lineHeight: 1.5
57+
fontFeature: tnum
58+
rounded:
59+
none: 0px
60+
sm: 4px
61+
md: 6px
62+
full: 9999px
63+
spacing:
64+
xs: 4px
65+
sm: 8px
66+
md: 12px
67+
lg: 16px
68+
xl: 24px
69+
2xl: 32px
70+
row: 32px
71+
app-bar: 44px
72+
review-strip: 48px
73+
components:
74+
button-primary:
75+
backgroundColor: "{colors.primary}"
76+
textColor: "{colors.on-primary}"
77+
rounded: "{rounded.sm}"
78+
height: 28px
79+
button-primary-hover:
80+
backgroundColor: "{colors.primary-hover}"
81+
button-secondary:
82+
backgroundColor: "{colors.surface-raised}"
83+
textColor: "{colors.text}"
84+
borderColor: "{colors.line}"
85+
rounded: "{rounded.sm}"
86+
height: 28px
87+
input:
88+
backgroundColor: "{colors.surface}"
89+
borderColor: "{colors.control-outline}"
90+
textColor: "{colors.text}"
91+
rounded: "{rounded.sm}"
92+
list-row:
93+
height: "{spacing.row}"
94+
backgroundColor: "{colors.surface}"
95+
selectedBackgroundColor: "{colors.surface-selected}"
96+
pane:
97+
backgroundColor: "{colors.surface}"
98+
borderColor: "{colors.line}"
99+
rounded: "{rounded.none}"
100+
nav-link:
101+
textColor: "{colors.text-muted}"
102+
activeTextColor: "{colors.text}"
103+
logo:
104+
size: 20px
105+
color: "{colors.text}"
106+
provenance-gutter:
107+
width: 56px
108+
textColor: "{colors.text-muted}"
109+
unplannedColor: "{colors.unplanned-hatch}"
110+
---
111+
112+
# codeboost
113+
114+
**Who this is for.** Anyone building or changing a codeboost screen. **What it is for.** It is the single source of truth for fonts, colors, spacing, and screen character. Exact values live in the header above. This text explains how and why to use them. It is written in plain language (ISO 24495-1:2023).
115+
116+
## Overview
117+
118+
**Creative North Star:** "Evidence Desk". A calm, near-black inspection surface where the code is the main thing and every change shows its reason. It serves the one thing users should remember: *"I can see exactly what the agent did."*
119+
120+
**Product context:** codeboost is a single-user, local, open-source developer tool. It turns GitHub issues into plans, runs AI agents on each plan item, and lets you review the pull request one plan item at a time. Its peers are Linear, GitHub's review screen, and code editors. See `docs/designs/codeboost-plan-indexed-review.md`.
121+
122+
**Mode per surface:** every screen is **Operate**. You come to finish a task, not to be persuaded.
123+
124+
**Reference sites:** [Linear's UI redesign](https://linear.app/now/how-we-redesigned-the-linear-ui) for restraint in how much color is used. [Dark-mode accessibility guidance](https://atmos.style/blog/dark-mode-ui-best-practices) for status colors.
125+
126+
**Key characteristics (first five seconds):**
127+
- The code pane is the largest, brightest thing on the screen.
128+
- Lines, not boxes. Panes are divided by 1px lines, never by cards or shadows.
129+
- Blue means "you can click this". Nothing else is blue.
130+
- Status is always an icon plus a word plus a color.
131+
- Unplanned code carries a red hatched strip that is visible before you read a single line.
132+
133+
## Colors
134+
135+
**Strategy:** Restrained. Neutral grey-blue surfaces, one accent, and four status colors. Color is rare, so it always means something.
136+
137+
**Light or dark:** Dark. You review code at your desk, often at night after an overnight run, for long stretches beside a dark code editor. A dark surface reduces glare and keeps diff colors readable.
138+
139+
**How to use the colors:**
140+
- **Surfaces step up in brightness:** canvas → surface → surface-raised → surface-selected. Hierarchy comes from these steps and from the `line` color, not from shadows.
141+
- **`primary` (light blue) marks only things you can act on:** buttons, links, the current tab, and focus rings. Never use it for status or decoration. Text on a primary button uses `on-primary` (dark), which gives 9.8:1 contrast.
142+
- **Status colors carry meaning:**
143+
144+
| Token | Meaning | Icon and word |
145+
|---|---|---|
146+
| `success` | OK: passed, in scope, approved | ✓ plus a word such as "OK" or "Passed" |
147+
| `warning` | Attribution warning, stale | ! plus a word such as "Stale" or "Ambiguous" |
148+
| `error` | Scope or test failure, blocker, unplanned | ✕ plus a word such as "Fail" or "Unplanned" |
149+
| `neutral-status` | Not applicable | – plus "N/A" |
150+
151+
- `success` is much lighter than `error`. This lets red-green color-blind users still tell them apart by brightness. Never rely on hue alone.
152+
- **Contrast (checked 2026-09-22):** every text and status color is at least 5.0:1 on every surface. Body text is 14.6:1 on `surface`.
153+
- **Diff backgrounds:** `diff-added-bg` and `diff-removed-bg` are quiet tints. The `+` and `−` signs carry the meaning, not the tint.
154+
155+
## Typography
156+
157+
**Faces:** IBM Plex Sans for the interface, and IBM Plex Mono for code, file paths, commit IDs, plan-item IDs, and numbers. Plex was drawn for engineering documentation, which suits a tool about inspecting evidence. The two faces share proportions, so code and interface sit together calmly.
158+
159+
**Why Plex is allowed here:** IBM Plex Sans is on the "too common for headlines" list. It is used here only as interface text on an Operate surface, which the rule permits. There are no marketing headlines in codeboost.
160+
161+
**Loading:** self-host both families (weights 400, 500, and 600 for Sans; 400 and 500 for Mono) with `font-display: swap`, so codeboost works offline. Fallbacks: `"IBM Plex Sans", "Segoe UI", sans-serif` and `"IBM Plex Mono", Menlo, Consolas, monospace`.
162+
163+
**Scale:** 12px labels and code, 13px interface text, 14px reading text (conversation and lesson details), 16px section headings, 20px page titles. Levels differ by size and weight, not by weight alone. Use tabular numbers (`tnum`) wherever numbers line up in columns.
164+
165+
**Small text on purpose:** 13px interface text is below the common 16px body guideline. The user chose a compact, dense tool. High contrast (at least 5:1) and a 32px row height keep it readable. Longer reading text uses 14px.
166+
167+
## Layout
168+
169+
**Desktop only, from 1280px** (design review D25).
170+
171+
| Width | Layout |
172+
|---|---|
173+
| 1440px and wider | Three panes. Plan list 232px, code fills the rest, conversation 344px |
174+
| 1280–1439px | The conversation pane collapses to a tab. The plan list narrows to 208px |
175+
| Below 1280px | A notice asks for a wider window |
176+
177+
**Frame:** a 44px app bar (the shared menu, design review D13), then a 48px review strip (issue, PR, revision, progress, blockers), then full-height panes. Panes can be resized and collapsed.
178+
179+
**Rhythm:** a 4px base grid. Rows are 32px. Pane padding is 12px. Space between sections is 16px or 24px. Keep density tight inside lists and give the code pane the most room.
180+
181+
## Elevation & Depth
182+
183+
There are no shadows and no glows. Depth comes from the surface brightness steps and 1px `line` borders. A popover or menu uses `surface-raised` with a 1px `line` border. If a real shadow is ever needed for a floating menu, it must be offset (for example 0 4px 12px at 40% of canvas), never a zero-offset colored halo.
184+
185+
## Shapes
186+
187+
- Panes, lists, and the code area have square corners (`rounded.none`). They are layout, not cards.
188+
- Buttons, inputs, tags, and chips use `rounded.sm` (4px).
189+
- Menus and popovers use `rounded.md` (6px). An element inside one uses 6px minus its inset.
190+
- `rounded.full` is only for small status dots.
191+
192+
## Components
193+
194+
**Every interactive component has these states:**
195+
- **Hover:** background one surface step brighter, or `primary-hover` for primary buttons.
196+
- **Focus-visible:** a 2px `focus-ring` outline with a 2px gap. It must look different from the selected-row fill.
197+
- **Active:** the same as hover, with the outline kept while focused.
198+
- **Disabled:** text in `text-muted` and no hover change. A disabled button still explains itself; for example, the merge button reads "3 blockers".
199+
200+
**Logo.** A terminal prompt (`>_`) inside a rounded square, followed by the word "codeboost".
201+
- It sits at the left of the app bar on every screen, 20px square, with 8px between the mark and the word.
202+
- The mark and the word use `text`. They are never blue, because blue means "you can click this".
203+
- The mark is drawn with 1.4px to 1.5px strokes and round caps, so it matches Plex's weight at 13px.
204+
- Screen readers skip the mark (`aria-hidden`) and read the word.
205+
206+
```svg
207+
<svg viewBox="0 0 20 20" width="20" height="20" aria-hidden="true">
208+
<rect x="1.5" y="2.5" width="17" height="15" rx="3" fill="none" stroke="currentColor" stroke-width="1.4"/>
209+
<path d="M5.5 7.5l3 2.5-3 2.5" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
210+
<path d="M10.5 13h4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
211+
</svg>
212+
```
213+
214+
**List row:** 32px high. Shows ID, title, count, and status icons. The selected row uses `surface-selected`.
215+
216+
**Status mark:** icon + word + color, with a screen-reader label such as "In scope: fail, 1 file outside declared files".
217+
218+
**Provenance gutter (the signature component).** A 56px column to the left of the line numbers in every diff.
219+
- Each changed block shows the ID of the plan item that made it, such as `P2`, in Plex Mono with `text-muted`.
220+
- A block that belongs to no plan item gets a red diagonal-hatched strip in `unplanned-hatch` and the word "Unplanned" beside it.
221+
- An ambiguous block shows "Ambiguous" with the ! icon in `warning`.
222+
- The gutter is read aloud with its block, for example "Lines 118 to 129, plan item P2".
223+
224+
**File-change card:** sits inside the code pane in change order. It has a `line` border, `rounded.sm`, an icon for the kind of change, old → new values in Plex Mono, and a "Details" expander.
225+
226+
**Tables (Lessons, Learning):** 32px rows, sortable headers with a visible sort arrow, and a filter bar above the table. Rows expand in place, with no side panel.
227+
228+
## Do's and Don'ts
229+
230+
- **Do** use `primary` only for things you can act on.
231+
- **Do** pair every status color with its icon and a word.
232+
- **Do** give the code pane the most width and the brightest text.
233+
- **Do** show the provenance gutter on every diff, including file-change cards.
234+
- **Do** check any new color pair for at least 4.5:1 contrast before using it.
235+
- **Don't** wrap panes, messages, or files in cards, and never put a card inside a card.
236+
- **Don't** use shadows, glows, gradients, or colored halos.
237+
- **Don't** use blue, purple, or accent colors to decorate.
238+
- **Don't** add a colored left border to a card to show state. Use the status mark instead. The provenance gutter is a column in the diff, not a card border.
239+
- **Don't** use a serif or italic display face. All text is Plex.
240+
241+
## Motion
242+
243+
- **Approach:** minimal and functional. Motion only explains a change of state.
244+
- **Easing:** enter ease-out, exit ease-in, move ease-in-out.
245+
- **Duration:** micro 80ms (hover and focus), short 150ms (expand a row, switch a tab), medium 250ms (open or collapse a pane). Nothing longer.
246+
- **The one designed moment:** when you approve a plan item, its status mark fills from an outline to a solid ✓ in 150ms, and the progress count updates.
247+
- **Reduced motion:** if the user asks for reduced motion, all transitions are instant.
248+
249+
## Decisions Log
250+
251+
| Date | Decision | Rationale |
252+
|---|---|---|
253+
| 2026-09-22 | Initial design system, "Evidence Desk", created | Created by /design-consultation from the design review (D22), the approved mockups, 2026 dev-tool research, and two outside proposals (Codex "Evidence Desk", Claude subagent "Flight Recorder") |
254+
| 2026-09-22 | IBM Plex Sans and IBM Plex Mono, verified on Google Fonts; self-hosted | One engineering-document family. Readable at 13px, with tabular numbers |
255+
| 2026-09-22 | Light-blue accent #8ABFFF with dark text | Keeps the accent readable (9.8:1) and separate from the status colors |
256+
| 2026-09-22 | Provenance gutter adopted (preview variant B) | Makes "I can see exactly what the agent did" visible. Idea from the Claude subagent |
257+
| 2026-09-22 | The serif "second voice" for the user's own words was not adopted | The user chose variant B. Two faces are enough |
258+
| 2026-09-22 | Logo: terminal-prompt mark (`>_`) in a rounded square, in `text` color | Taken from the approved review-screen mockup. It was left out of the first HTML screen and restored at the user's request |
259+
| 2026-09-22 | Contrast-checked values kept instead of values extracted from the mockup image | The extracted values (for example error #DA1E28) failed contrast on dark surfaces |

0 commit comments

Comments
 (0)