prototypes

# Prototypes `prototypes/README.md` is the index: one folder per template, each prototype's artifact link, the kit, and the build. Read it first. Each prototype is one `source.html` that `node prototypes/kit/build.ts <name>` turns into a single page, published as a Claude artifact. Designers and PMs ask the agent to open a prototype; there is no gallery page. ## What a prototype shows - Shipped-app prototypes (Chat, Slides, Clips web and desktop, Analytics) match the code exactly: the menus' icons, state colors (red where the code uses destructive), copy verbatim (em dashes and emoji included), and the app's custom SVG icons. Check the component before claiming what ships. - The Design prototype is a redesign. Redesign rules apply there: text-only menus, amber warnings with red only for destructive actions, 24px controls, everything on the 8pt grid. Mark controls the code doesn't have as new. - Tokens come from the code at build time. Use the code's names (`--color-border`, `--design-editor-accent-color`) and never copy values in. ## Edit and republish 1. Change `<name>/source.html`. Shared needs go in `prototypes/kit/` (menus, Settings, icons via `kit/add-icons.ts`), not copied between prototypes. 2. Add a dated, past-tense entry at the top of `<name>/changes.json`. The prototype's Changes drawer shows it. 3. Build, then load `dist/index.html` headlessly (Playwright, via the main checkout's `node_modules/.pnpm/playwright@*`) in light and dark. Zero page and console errors, and look at a screenshot of what changed. 4. Republish to the link in the README (the Artifact tool's `url`), so the link stays. Publishing only stamps a new version. 5. Commit and push on the current branch. Building the experience in the app (design to code) is a separate handoff: work in `templates/<app>` from the prototype, its Changes log, and the Figma frames, then follow `adding-a-feature` and `ship`. ## Figma The Agent-Native file is `oJQ7t9q4e8oHzLZKuki7k1`. Every app already has a page there, because design usually starts in Figma. `<name>/prototype.json` names it under `figma.page` (with `pageId`), lists any `figma.related` pages (Chat's agent chat surface lives on AgentKit, shared by every app), and records `figma.sections`, the sections and frames this prototype maps to. If an app has no page, ask. Don't create one. Load `figma-use` before every `use_figma` call, and `figma-design-to-code` before `get_design_context`. ### Push: prototype to Figma Rebuild the screens and states with the file's design system so they stay editable and on-system. Never push screenshots or SVG conversions. - **Components:** the shadcn UI kit (Nova variants: Button, Icon Button, Toggle Icon Button, Dropdown Menu, Input, and so on). Find them with `search_design_system`, then import by key with `importComponentSetByKeyAsync` or `importComponentByKeyAsync`. The plugin API can't list team libraries. - **Reuse:** components already on the app's page come first, such as Design's `Editor/*` parts. Anything reused becomes a component or variant set, with properties named like the code's props. - **Icons:** the kit's icon components, swapped through instance properties. Match the code's glyphs. - **Color:** bind every paint to the file's variables with `figma.variables.setBoundVariableForPaint`, such as Design's `Design/Tokens` collection, or the variable `search_design_system` finds for the app's token. Use raw hex only where the code has no token. - **Text and geometry:** Inter, with sizes, weights, and spacing from the code. 24px controls and the 8pt grid. - **Placement:** one section per surface on the app's page. Update an existing section in place by node id, so links from Jira and docs keep working. Put new sections below existing content, and check bounding boxes for overlap. Don't edit sections someone else made, or a baseline, without asking. - **Calls:** - Make each call idempotent by name, and return the node ids. - Run `setCurrentPageAsync` first: new nodes land on the current page, which may be the cover. - A failed script rolls back, so re-read before retrying. - Call `loadFontAsync` for every font a text node uses. - Only slots accept `appendChild` on an instance. - **Verify:** screenshot the section with `get_screenshot`, and fix what's off. Record new section and frame ids in `prototype.json`. ### Pull: Figma to prototype 1. Find what changed. Use `get_screenshot` for the section or frame the person names, and `use_figma` to read the nodes involved: text, fills and their bound variables, sizes, auto layout, and component properties. Use `get_design_context` when you need code-shaped detail. 2. Map each change into `source.html`: - Copy goes in verbatim. - A bound variable becomes the matching code token. - Sizes snap to the 8pt grid. - Components become the prototype's existing parts. 3. Ask when a change is ambiguous or the code can't do it yet. Say which controls are new. 4. Add a Changes entry ("Updated … from Figma"), then build, verify, republish, and commit as above.