23. Appendices
Ctrl means Cmd on macOS.
Esta página está em inglês; a tradução está a caminho.
A. Figma parity matrix#
| Figma feature | UI Designer | Requirement |
|---|---|---|
| Frames, groups, sections | yes | DOC-2, DOC-7, DOC-8 |
| Shapes, pen, vector networks, booleans | yes | DRW-3 – DRW-6 |
| Fills, strokes, effects, blend modes | yes | STY-1 – STY-7 |
| Progressive blur, noise, texture | later | STY-9 |
| Text with mixed styles, OpenType, variable fonts | yes | TXT-1 – TXT-6 |
| Constraints, auto layout, grid layout | yes | LAY-1 – LAY-5 |
| Components, variants, properties, slots | yes (slots Should) | CMP-1 – CMP-6 |
| Styles, variables, modes, libraries | yes | VAR-1 – VAR-8 |
| Prototyping, smart animate, variables in prototypes | yes | PRO-1 – PRO-8 |
| Dev Mode, Code Connect | yes (Inspect, code map) | DEV-1 – DEV-4 |
| Comments | yes, in file | COL-3 |
| Version history, branching | yes, through the WAL and git | COL-1, COL-2, COL-4 |
| Multiplayer cursors | Live Share, later | COL-6 |
| Plugin API | use_figma scripts and “Run Script…” against a compatible figma global; no plugin UI or marketplace |
CMD-10 – CMD-16 |
| Figma MCP server | same tool names and parameters through ud and ud mcp |
CMD-1 – CMD-9 |
| Figma AI (First Draft, rename layers, …) | Claude Code through skills | AI-1 – AI-10 |
| FigJam, Slides, Sites, Buzz, Make | no | §1.2 |
B. Default keyboard shortcuts#
Ctrl means Cmd on macOS. Every shortcut runs a registry command and can be rebound in keybindings.json.
Rules (Appendix D, issue 2): every binding is contributed with
when: activeCustomEditorId == 'softforge.design' && !inputFocus, so it never shadows a VS Code or OS binding
outside the design editor or while a text field has focus; keys are matched by KeyboardEvent.code (physical
key), so Alt+letter aligns work on every layout; F6 cycles the editor’s regions only while focus is already
inside the editor, and Ctrl+F6 leaves it to VS Code’s next part. An audit in 0.1 produces a conflict table (key,
VS Code command, resolution) against VS Code 1.108 and adjusts the defaults below where a conflict remains.
| Keys | Command |
|---|---|
| V / K / F / R / O / L / Shift+L / P / T / H / C / S | Move / Scale / Frame / Rectangle / Ellipse / Line / Arrow / Pen / Text / Hand / Comment / Slice |
| Ctrl+G / Ctrl+Shift+G / Ctrl+Alt+G | Group / Ungroup / Frame selection |
| Shift+A | Add auto layout |
| Ctrl+Alt+K / Ctrl+Alt+B | Create component / Detach instance |
| Ctrl+D | Duplicate |
| Ctrl+] / Ctrl+[ / Ctrl+Shift+] / Ctrl+Shift+[ | Bring forward / Send backward / Bring to front / Send to back |
| Alt+A / Alt+D / Alt+W / Alt+S / Alt+H / Alt+V | Align left / right / top / bottom / horizontal centres / vertical centres |
| Ctrl+Alt+Shift+H / V | Distribute horizontal / vertical spacing |
| Shift+H / Shift+V | Flip horizontal / vertical |
| Ctrl+E / Ctrl+Shift+O | Flatten / Outline stroke |
| Ctrl+Alt+M | Use as mask |
| Shift+0 / Shift+1 / Shift+2 | Zoom 100 % / fit all / fit selection |
| Shift+R / Ctrl+’ / Ctrl+Y | Rulers / Layout guides / Outline mode |
| Ctrl+/ | Quick actions |
| Shift+D | Inspect mode |
| Ctrl+Alt+Enter | Preview prototype |
| Ctrl+Alt+C / Ctrl+Alt+V | Copy / paste properties |
| Ctrl+\ | Show / hide panels (see Appendix D, issue 2) |
| Ctrl+Shift+4 | Show / hide layout guides |
| Ctrl+Shift+Escape | Stop agent (UI-7, AI-14) |
| Ctrl+Shift+? | Keyboard shortcuts |
C. Glossary#
See section 1.3. Terms of the file format are defined in FMT-001 §1, terms of the CLI in CLI-001 §1.
D. Open issues#
Questions raised while writing the companion documents. Each needs a decision before the milestone named; the proposal is what the documents assume until then.
| # | Issue | Proposal | Decide by |
|---|---|---|---|
| 1 | The 0.1 exit criterion uses Figma’s figma-use skill, whose examples also create text (0.2) and use figma.createAutoLayout (0.3). |
Keep the criterion to frames and rectangles, and have the ui-designer skill tell the agent which API is there (ud plugin-api). Alternatively bring text and auto layout into 0.1. |
0.1 |
| 2 | Ctrl+\ (show / hide panels) is VS Code’s Split Editor, and other Appendix B keys collide with VS Code or OS bindings (Ctrl+G, Ctrl+Shift+G, Ctrl+E, Ctrl+Shift+O, Ctrl+Y, Ctrl+Alt+B, Alt+letter, Ctrl+Alt+letter, F6). | Every binding carries when: activeCustomEditorId == 'softforge.design' && !inputFocus and is matched by KeyboardEvent.code; F6 cycles regions only inside the editor, Ctrl+F6 leaves; a conflict-table audit in 0.1 settles the remaining defaults (Appendix B rules). Decided 2026-10-10: D19 of the SRS-001 review. |
0.1 |
| 3 | NFR-8 compares the Canvas 2D renderer with resvg. Blurs and shadows will differ by more than 2/255 at the edges, SVG filters and Canvas differ in colour space, and the GPU canvas differs again. | resvg is the reference; the Canvas 2D renderer with GPU off, PNG exports and get_screenshot are bound at 2/255 (8/255 inside blur and shadow bounds), PDF/SVG are compared after rasterising with resvg, JPG/WebP are excluded, the GPU canvas gets a smoke tolerance, and the player joins at 0.5. Decided 2026-10-10: D5 of the SRS-001 review. |
0.1 |
| 4 | DOC-2 Arrow and Image have no Plugin API node type. | Image is a RECTANGLE with an image fill (as in Figma). Arrow is a VECTOR with an arrow stroke cap (ARROW_LINES, ARROW_EQUILATERAL), as FMT-001 already says, so scripts see Figma’s types. Decided 2026-10-10: D13 of the SRS-001 review, VECTOR. |
0.1 |
| 5 | The Dark Modern and Light Modern colours in UI-001 §2.1 were written from memory. | Check them against the theme files of VS Code 1.108 and update UI-001 and the Figma file together. | 0.1 |
| 6 | Node versions disagree: ARC-001 and §2.4 promised the CLI on Node 20+, package.json has @types/node ^18, release.yml uses Node 24; Node 20 reached end of life on 2026-04-30. |
Node.js 22 or newer (§2.4); @types/node ^22; CI tests on 22 and 24. Decided 2026-10-10: D24 of the SRS-001 review. |
0.1 |
| 7 | Repository set-up: test.yml runs on pushes to main but the branch is master; package.json and release.yml still say vscode-extension-scaffold and your-publisher-name; the deprecated vsce package is a dev dependency while release.yml uses @vscode/vsce. |
Rename to softforge-ui-designer / SoftForge, trigger CI on master, replace vsce with @vscode/vsce. |
0.1 |
| 8 | The Figma file of UI-001 uses two variable collections (Theme with 2 modes, Size) instead of the vscode (4 modes), ud and size collections of UI-001 §9. |
Keep the simpler set for the specification; add High Contrast modes when T02 and T03 are drawn (UI-001 §9.8). Decided 2026-10-06: proposal accepted. | 0.0 |
| 9 | The first CMD-8 snapshot (test/fixtures/figma-mcp-tools.json, 41 tools, taken 2026-10-06 through the claude.ai Figma connector) has no generate_figma_design and no html_to_figma, which §3.2, CMD-6 and CLI-001 name. The connector may hide them, or Figma may have removed or renamed them. |
Refresh the snapshot with a direct tools/list (scripts/refresh-figma-tools.mjs with the maintainer’s token, and --url for the desktop server) before 0.1. If they are gone, take generate_figma_design out of §3.2 and EXP-6 and keep ud import html as the native form. |
0.1 |
| 10 | Figma’s server has a get_figma_skill tool (reads skill:// resources by URI) that §3.2 and CLI-001 §3 do not list. The CMD-8 test fails on a Figma tool that is neither supported nor marked unsupported (ARC-001 §9.2). |
Support it from 0.1: it returns the skill://ui-designer/… resources of AI-001 §5, so clients that cannot read MCP resources still get the skills. Add it to §3.2 and CLI-001 §3. |
0.1 |
| 11 | The 0.2 exit criterion (“an agent builds a login screen from UDX”) pointed at the CLI-001 §7 reference screen, which uses auto layout (0.3) and instances, variants, variables and styles (0.4). | The 0.2 criterion is restricted to absolute-positioned frames, shapes, text and images, and CLI-001 §7 gets a 0.2-valid example. Decided 2026-10-10: D11 of the SRS-001 review. | 0.0 |
| 12 | Legal exposure: the product reuses Figma’s tool names and descriptions and a subset of the MIT-licensed @figma/plugin-typings (notice required); there is no inventory of third-party licences (resvg-wasm, the WASM encoders, ICU4X data). Reading .fig files would mean reverse engineering a proprietary format. |
A trademark and terms-of-service check of the Figma names and copied descriptions before 0.1 ships; a THIRD-PARTY-NOTICES file and a CI licence allowlist (ARC-001 ADR); .fig import removed from EXP-5 for 1.0 (Figma import goes through the REST API) and kept in the backlog. |
0.1 |