9. Figma deliverable
File name: SoftForge UI Designer — Editor UI.
9.1 File#
File name: SoftForge UI Designer — Editor UI. Four pages, in this order: Foundations, Components, Screens, Flows.
9.2 Page “Foundations”#
Variables:
Two collections, as built (SRS-001 Appendix D #8, decided):
| Collection | Modes | Variables |
|---|---|---|
Theme |
Dark Modern, Light Modern, Dark High Contrast, Light High Contrast | Colour variables, one value per mode: the VS Code tokens of §2.1, named with / for . (editor/background, sideBar/background, focusBorder, …), and the semantic roles of §2.1 as ud/<role> (ud/background, ud/focus, …) aliased to them. Values from “Developer: Generate Color Theme From Current Settings” in each of the four reference themes. Code syntax (Web) set to the themeColor('focus') role names. Screens and theme checks switch mode per frame; theme is never a component variant (§9.3). |
Size |
single | space/4 … space/48, radius/2 … radius/12, and the §2.7 sizes: size/row, size/field, size/toolButton 32, size/sectionHeader 32, size/tabs 36, size/panelHeader 40, size/status 22, size/leftPanel 240, size/rightPanel 264 |
Text styles ud/display, ud/heading, ud/subheading, ud/body, ud/strong, ud/small, ud/caption, ud/tiny, ud/code (§2.4). Effect styles shadow/floating, shadow/popover, shadow/modal.
Frames:
| Frame | Contents |
|---|---|
| Colour tokens | Table of §2.1 with swatches in all four modes |
| Type scale | §2.4 samples |
| Spacing, radii and sizes | §2.5–§2.7 |
| Icons | Codicons used and the custom icon set (§2.9) on a 16 px grid |
| Canvas overlays | §2.2 and §4.31 in context |
| Actor colours | §2.3 with avatars and name tags |
| Elevation | §2.8 |
9.3 Page “Components”#
| Convention | Rule |
|---|---|
| Component set names | The custom element tag: ud-tool-button, ud-number-field, … Canvas overlays: overlay/selection-box, overlay/size-label, overlay/smart-guide, overlay/redline, overlay/auto-layout-padding, overlay/auto-layout-gap, overlay/noodle, overlay/agent-flash, overlay/frame-title, overlay/diff |
| Variant properties | state = default, hover, pressed, focus, disabled (plus selected, mixed, invalid, open where §4 lists them); size; variant; theme is never a variant (use variable modes) |
| Component properties | Booleans hasIcon, hasTrail; text label, value; instance swap icon |
| Layer names | camelCase, matching the JS field names in the class (scrubLabel, valueInput, trail) |
| Auto layout | Every component uses auto layout with space/* and radius/* variables; no fixed-position children except overlays |
| Code Connect | Each set maps to media/views/UdThing.js (§4) |
| Documentation-only components | panel/left, panel/design and the VS Code chrome vscode/* (title bar, activity bar, status bar, used in S12) exist to assemble screens quickly. They are not product components: no Ud* class, no Code Connect mapping, and their layer names need not match JS fields. They are marked with a Doc/* text style caption in the file. |
| Kept for the backlog | overlay/agent-cursor (a remote cursor with the actor’s name tag) stays in the file for COL-6, which is backlog. It is not a 0.1–1.0 deliverable, is not used by any S-frame, and has no §4 entry or renderer counterpart until COL-6 is scheduled. |
Frames (one per group, components laid out with their states):
| Frame | Components |
|---|---|
| Buttons and tool bar | ud-toolbar, ud-tool-button, ud-tool-group, ud-icon-button, ud-button, ud-key-cap |
| Fields | ud-number-field, ud-text-field, ud-search-field, ud-dropdown, ud-segmented, ud-checkbox, ud-toggle, ud-swatch, ud-paint-row, colour picker |
| Panels | ud-tabs, ud-zoom-controls, ud-section, ud-property-row, ud-status-strip, ud-banner |
| Lists and trees | ud-layer-row, ud-page-row, ud-asset-tile, ud-step-row, ud-code-block |
| Overlays and feedback | ud-menu, ud-tooltip, ud-toast, ud-modal, ud-badge, ud-avatar, ud-chip |
| Agent and comments | ud-agent-badge, ud-comment-pin, comment thread popover |
| Canvas overlays | overlay/* |
9.4 Page “Screens”#
Every frame is 1440 × 900 (except S12 at 1440 × 922 with the VS Code status bar inset, and T03 at 960 × 640), named exactly as below, laid out left to right in rows of five with 200 px gaps, built only from instances of the Components page and bound to variables (mode Dark Modern unless the name says otherwise).
| Frame | §5 | Milestone of the feature |
|---|---|---|
| S01 Empty file | S01 | 0.1 |
| S02 Editor with selection | S02 | 0.1 |
| S03 Design auto layout frame | S03 | 0.1 (subset), 0.3 |
| S04 Design text | S04 | 0.2 |
| S05 Design instance | S05 | 0.4 |
| S06 Variables | S06 | 0.4 |
| S07a Assets | S07a | 0.4 |
| S07b Libraries | S07b | 0.4 |
| S07c Library updates | S07c | 0.4 |
| S08 Prototype | S08 | 0.5 |
| S09 Preview player | S09 | 0.5 |
| S10 Inspect | S10 | 0.6 |
| S11a AI prompt | S11a | 0.7 |
| S11b AI streaming | S11b | 0.7 |
| S11c AI proposal review | S11c | 0.7 |
| S12 Agent working live | S12 | 0.1 (flash), 0.2 (status item, Stop) |
| S13 History and versions | S13 | 0.3 |
| S14 Comments | S14 | 0.6 |
| S15 Quick actions | S15 | 0.2 |
| S16 Export | S16 | 0.6 |
| S17 Figma import report | S17 | 0.8 |
| S18a Trial | S18 | 1.0 |
| S18b Sign in | S18 | 1.0 |
| S18c Read-only | S18 | 1.0 |
| S19 Run Script output | S19 | 0.2 |
| T01 S03 Light Modern | §8 | 0.1 |
| T02 S03 Dark High Contrast | §8 | 0.1 |
| T03 S02 Narrow 960 × 640 | §3.4 | 0.1 (frame size 960 × 640) |
9.5 Page “Flows”#
Prototype flows connecting the Screens frames (duplicated as instances or linked by prototype connections), each with a flow starting point:
| Flow | Frames |
|---|---|
| F01 First design | S01 → S02 → S03 |
| F02 Agent builds a screen | S11a → S11b → S11c → S12 |
| F03 Prototype | S08 → S09 |
| F04 Handoff | S10 → S16 |
| F05 Licence expiry | S18a → S18b → S18c |
| F06 Figma import | S17 → S02 |
9.6 Naming conventions#
| Item | Convention |
|---|---|
| Screen frames | S<nn><letter?> <Title in sentence case> |
| Theme checks | T<nn> <screen> <theme> |
| Flows | F<nn> <Title> |
| Variables | collection/group/name, lower camelCase for multiword (size/panelHeader) |
| Components | Tag name; overlays overlay/<kebab-name> |
| Layers in screens | Region names from §3.2: leftPanel, canvas, rightPanel, statusStrip, toolbar, agentPill |
9.7 Definition of done for milestone 0.0#
Milestone 0.0 closes with the subset below (review decision D2, 2026-10-06). It is the 0.0 exit criterion “UI-001 Figma frames per UI-001 §9.7”. Every other frame of §9.4 and §9.5 is drawn in the design pass of its own milestone (the “Milestone of the feature” column), at the fidelity that milestone needs; it is not a 0.0 requirement that they exist.
| # | Done for 0.0 | Fidelity |
|---|---|---|
| 1 | Foundations: the Colour tokens frame of §9.2, with the Theme collection in its four modes |
High |
| 2 | The 0.1 components: ud-toolbar, ud-tool-button, ud-tool-group, ud-icon-button, ud-button, ud-tabs, ud-zoom-controls, ud-section, ud-property-row, ud-number-field, ud-dropdown, ud-segmented, ud-checkbox, ud-swatch, ud-paint-row, ud-layer-row, ud-page-row, ud-menu, ud-tooltip, ud-key-cap, ud-toast, ud-status-strip, ud-agent-badge, ud-avatar, overlay/selection-box, overlay/size-label, overlay/smart-guide, overlay/frame-title, overlay/agent-flash, with the states §4 lists |
High |
| 3 | S01 Empty file, S02 Editor with selection, S03 Design auto layout frame in its 0.1 subset (Position, W/H, Appearance, solid Fill; the later sections drawn and marked “later”) | High |
| 4 | T01 S03 Light Modern, drawn on S03 (not on S05); T02 S03 Dark High Contrast, drawn by switching the Theme collection to its Dark High Contrast mode (the Light High Contrast mode is checked in the Colour tokens frame, which shows all four); T03 S02 Narrow 960 × 640 |
High |
| 5 | S04 Design text, S13 History and versions, S19 Run Script output | Wireframe |
Not required for 0.0: S05–S12, S14–S18, their flows, and components used only by them. S12 is the 0.1 exit scenario (Claude Code, through use_figma, creates a frame of rectangles in the open file while the user watches: S12 followed by S02), so it is the first frame of the 0.1 design pass.
State on 2026-10-10: the file already contains every frame of §9.4 and §9.5, including the ones 0.0 does not require, with S01–S03, S12 and T01–T03 at high fidelity and the rest at wireframe fidelity (§9.8). The definition of done above is therefore met; what remains for later milestones is raising the wireframes to high fidelity, screen by screen, in each milestone’s design pass.
9.8 Status of the Figma file#
State on 2026-10-10. File: SoftForge UI Designer — Editor UI,
key kkYWepMrew5dUaj3nixcn1. Every page in §9.1–§9.5 is built and was checked against screenshots.
| Page | Built |
|---|---|
| Cover (added, first page) | Title card for the file. |
| Foundations | Collections Theme (91 colour variables, four modes) and Size (29 variables); text styles ud/* and Doc/*; effect styles shadow/floating, shadow/popover, shadow/modal; the seven frames of §9.2; icon sheet of 114 Icon/<codicon> components (16 px, swapped through instance-swap properties). |
| Components | Every component in §9.3, in the seven group frames, with the state / variant properties of §4. |
| Screens | All 28 frames of §9.4, in index order, rows of five. S01–S03, S12 and T01–T03 at high fidelity (0.1); the rest at wireframe fidelity. |
| Flows | F01–F06 as prototype connections between the Screens frames (one flow starting point each, on click, smart animate) plus one overview board per flow with thumbnails; F07 Claude designs through ud. |
Differences from §9.1–§9.7:
| Item | Specified | In the file | Why |
|---|---|---|---|
| Pages | Four | Five, with Cover first | A cover gives the file a thumbnail and an index. |
| Sizes | size/row 24 (§2.7) |
size/row 22, size/field 26 |
Matches the measured VS Code list row and input heights; §2.7 still says 24. |
| Text styles | ud/* |
ud/* plus ud/overline, and Doc/* for annotation frames |
Separates product type from documentation type. |
| Icons | Codicons used and custom set | 114 icon components, including custom ones (al-wrap, pad-h, bool-union, …) |
Every icon the screens need is a component. |
| Components | Sets in §9.3 | Also ud-quick-actions (the S15 palette, no §4 entry yet), sub-components ud-segmented/segment and ud-menu/item, and overlay/agent-cursor |
Sub-components keep sets small; ud-zoom-controls, panel/*, vscode/* and the agent cursor are now covered by §4.30 and §9.3. |
| Screens | Chrome-less editor | Chrome-less, as specified; only S12 shows the VS Code status bar | The earlier chrome screens were replaced. |
| Overlays (scrims, dimmed canvas, measure areas) | — | Layer opacity, not paint opacity | Paint opacity does not survive on instances. |
| S03 | 0.1 subset, the rest “later” | Sections after 0.1 carry a later badge |
Shows the 0.1 scope in place. |
| Modals (S06, S16, S17, S18b) | — | Drawn over a dimmed copy of S02 | Shows the modal in context. |
| Flows | F01–F06 | F07 added | Documents the agent path of CLI-001 and AI-001. |
Known wireframe nits, to fix when each screen moves to high fidelity: the S04 size label overlaps the subtitle; the S06 edit panel border does not reach the bottom; the S08 “On click” labels overlap frame content; S11b flash labels overlap the input text.
The figma-use scripts that built the file use the same helpers an agent would use against ud mcp
(variables bound with setBoundVariableForPaint and setBoundVariable, auto layout with explicit
layoutSizingHorizontal), so the file also serves as a sample for CMD-9.