@synap-core/cli 1.10.0 → 1.12.2

package/skills/synap-design/SKILL.md

@@ -0,0 +1,474 @@
+---
+name: synap-design
+description: >
+  Use this skill whenever you design, review or build user interface for
+  Synap, or a UI for a user's pod: a screen, page, panel, section, card,
+  component, empty state or dashboard. Triggers: "design this screen", "mock
+  up a page", "review this UI", "critique this design", "build this
+  component", "implement this ui-design", "why does this screen feel off",
+  "what should this page show". It holds the composition principles, the
+  design system (real components, tokens, labels, named motion) and the
+  design-to-code loop (ui-design entity, three variants, critique, human
+  approval, implement, compare). For views, bento dashboards and workspaces
+  over pod data, pair it with synap-ui.
+metadata:
+  synap:
+    requires:
+      env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
+    primaryEnv: SYNAP_HUB_API_KEY
+    homepage: https://synap.live
+    capabilities: [design, ui, critique, components]
+    os: [macos, linux, windows]
+    userInvocable: false
+---
+
+# Synap design
+
+Load this when you design, review or build any Synap UI, or a UI for a user's pod: a screen, page,
+panel, section, card, component, empty state or dashboard. It is the one place the design rules live
+for every agent. For views, bento dashboards and workspaces over pod data, also load `synap-ui`.
+
+Most bad screens here are not styling failures. They are modelling failures: the object was never
+named, so the screen borrowed a foreign card and inherited its verbs. Get the object and the job right
+first; the layout follows from them.
+
+## Before anything: name the object and the job
+
+- Write one sentence: "This surface renders ONE ___." Check that the card, row or panel you plan to
+  use was built for that object. If none fits, model the object; never bend a foreign one.
+- Write the reader's primary job as the question they arrive with, then the secondary one. A surface
+  that serves its secondary job by default has failed.
+- Ground truth first. Read the component that renders it today and the data the backend really
+  returns. Never design from a description or from memory.
+
+## The loop (six steps)
+
+1. **Discover what exists.** Query the component catalog before you design or build anything
+   (`system.md`). If the thing exists, even imperfectly, the work is adopt, extend or consolidate,
+   and the diff should shrink.
+2. **Design with real components.** A design is data, not a picture: Puck JSON whose every block is a
+   real component from the catalog, saved as a `ui-design` entity. Three genuinely different variants
+   by default. Lay out every state (`loop.md`).
+3. **Critique.** Run the three-tier rubric on each variant: Checked, Pattern, Opinion. Fix every
+   Checked and Pattern blocker and critique again. Opinions go to the person, never applied by you.
+4. **Human review gate.** Move the design to `in-review` and wait. `approved` is a person's call; you
+   never set it, and you never implement from a draft.
+5. **Implement.** Build exactly the approved design from the same components and tokens. Do not
+   reinterpret it.
+6. **Verify against the design.** Run the gates yourself, then compare Today, Design and Built side
+   by side, and walk the screen in the running app. Report what is VERIFIED (a gate proved it)
+   separately from what NEEDS-DOGFOOD (only a running app can show it).
+
+## Files
+
+| File            | Read it for                                                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `principles.md` | how a screen is arranged: marks, empty states, doors, lists, order, actions, disclosure, colour, depth                 |
+| `system.md`     | what you build with: the catalog, tokens, the primitive table, labels, motion presets                                  |
+| `loop.md`       | the design-to-code loop: the `ui-design` entity, variants, critique tiers, approval, implement, compare, where to view |
+
+---
+
+# Design principles: how a screen is arranged
+
+Every rule here was dictated after dogfooding a screen that broke it. Apply all of them; a reviewer
+checks each one.
+
+## 1. State is a mark, not a sentence
+
+A reader must know where a thing stands without reading. Colour and icon first; text only to
+disambiguate what the mark cannot carry.
+
+- Derive state once, from the shared unit state: it returns a tone and a glyph, never a colour and
+  never a sentence. Never re-derive it locally.
+- A tone has two values: a FILL for marks, dots and rails (3:1) and an INK for text and icons (4.5:1).
+  Never use a fill as text; it fails contrast on light palettes.
+- A status that is only ever prose is a defect. If you wrote a sentence to convey state, you owed a chip.
+- Reduce text everywhere. Two lines that a chip plus four words would say is slop.
+
+## 2. Classify every section's empty answer
+
+Never a bare grey caption. Pick one deliberately:
+
+| Answer       | When                                                  | Render                                                                  |
+| ------------ | ----------------------------------------------------- | ----------------------------------------------------------------------- |
+| **OMIT**     | absence already says zero and the user cannot fill it | nothing at all, not even the heading                                    |
+| **INVITE**   | the user can fill it                                  | quiet empty state with the one action that fills it                     |
+| **EXPLAIN**  | only an agent fills it                                | why it is empty plus an escape hatch (ask the AI, open the source chat) |
+| **REASSURE** | empty is the good outcome                             | an "All clear" state                                                    |
+
+A failed read is none of these: it is a failed state with the retry inside it. A read in flight is a
+skeleton of the real row shape. Never fold a failure into calm empty copy, and never let a failed
+lookup render as "empty".
+
+## 3. Everything named is a door
+
+- A count, chip, card or provenance line that names an object opens that object's own page through
+  the one route table. Never a scroll-to-anchor; a scroll is the absence of a detail page.
+- Provenance is a door, not a caption: "Started from a chat" opens the chat; "in project X" opens X.
+- Show objects, not identifiers. An object with a title is a chip that opens it. A bare id with no
+  title is a short mono chip with copy; never invent a label for it.
+- Anything the reader is told about and cannot act on is either missing its door or should not be
+  on the screen.
+
+## 4. Lists are bounded and shaped
+
+- Never an unbounded list in a detail screen. Cap it, then "Show all N" into a dedicated page that
+  carries its scope in the address.
+- Shape from the item: a horizontal row of cards for browseable peers (outputs, sessions,
+  projects); a column for things that need a verb on each row (decisions, blocks).
+
+## 5. No carousel over content the page already has
+
+A swipeable deck is undiscoverable on a phone and, when its slides repeat sections below, pure
+redundancy. Slides are only for content that exists nowhere else.
+
+## 6. What it produced outranks how it worked
+
+Order by what the reader came for. Outcomes sit above steps, narrative and context, never at the
+bottom. Fold context, never outcomes.
+
+## 7. One primary action, sized like an action
+
+- Each section has ONE primary action at `md`; secondary actions are `sm`; `xs` is only for inline,
+  row and toolbar actions.
+- A full-width filled bar is a billboard. A single "start something" affordance is a round `+` that
+  opens a picker of what can be started.
+- Put the primary job's remedy next to the problem, with primary weight.
+- One action grammar everywhere: the same verbs through hover menu, right-click and keyboard.
+  Inapplicable verbs are absent, never disabled. A door the host did not supply means the affordance
+  does not render; never a dead button.
+- No warning buttons. Warnings are banners or callouts; a risky action is `tone="danger"`.
+
+## 8. Progressive disclosure ladder
+
+Write the rungs before building. Each answers one question and leads to the next: what happened,
+then where, then why, then the thing itself.
+
+- The default state answers the primary question on arrival. A triage surface pre-selects the
+  failure; a summary surface shows the summary.
+- The last rung is always the real object, never a description of it. Raw JSON is never a rung,
+  only an escape hatch under a menu.
+- Nothing that shows nothing at rest: collapsed boxes that cost height and deliver zero information
+  get a pane they deserve, or go behind a rung that earns them.
+- Calm default: surface attention only when it exists. An attention strip that is absent when
+  nothing waits beats a permanent status panel.
+- Configuration is the last rung, never the first. Controls that configure the system (renderer,
+  layout, schema, governance) live behind a menu or in Settings. Editing the data itself (a title, a
+  status, a date) stays easy and inline.
+- Max two levels of disclosure on a dashboard.
+
+## 9. Object creation: the minimum to exist, then the detail page
+
+Ask only what the object needs to exist, land on its detail page, configure there. No wizards. A
+"+ New" that does not actually create is a lie; a create menu offers the types, and each lands on
+the new object.
+
+## 10. Honesty
+
+- No empty shells, no fabricated labels, provenance or defaults, no success state the data cannot
+  prove. A rejected clipboard write never shows "Copied".
+- Aggregates state their scope ("across the 20 most recent runs").
+- Enumerate states before building: loading, each kind of empty, failed, one item, very long label,
+  very many items, live, narrow. Truncated text needs a way to read it whole.
+
+## 11. Colour, depth and shape
+
+- **Tokens only.** Colours, spacing, radius, type and motion come from `--synap-*` tokens (or the
+  components that use them). Never a hex, rgba, px, ratio, weight or font-family literal.
+- **90% neutral, 10% accent.** Colour is earned: an element gets accent only when it is selected,
+  focused, primary or AI. Icons rest neutral. Colour and icon are redundant encodings of one state,
+  which is what makes a mark glanceable and accessible.
+- **One accent for control states.** Switches, checkboxes and selected segments use
+  `--synap-primary` when on, including on AI settings. Human selection is `--synap-primary`.
+- **AI colour is provenance only.** `--synap-ai` (the logo yellow) marks AI-attributed or
+  agent-touched work, and an action that starts AI work is `primary tone="ai"`. Nothing else wears it,
+  and AI never wears another colour. To mark an AI section, colour its icon or heading, not its
+  controls. A filled AI surface is `--synap-ai-surface` under `--synap-ai-foreground`.
+- **Contrast by measurement.** Text on a colour fill is picked by measured contrast (WCAG 4.5:1),
+  never by a luma threshold or a hard-coded white. Compute it; do not eyeball or trust a claimed ratio.
+- **No shadows on in-flow surfaces.** Depth is `--synap-border-color` plus a luminance step. Only
+  floating layers get a restrained glass lift (glass tokens, blur, 1px border).
+- **A page never paints a background.** Only the app plane and the desk ground paint
+  `--synap-background`; `--synap-background-surface` is a card film, never a page. A full-bleed canvas
+  is the one exception: it is the ground.
+- **Concentric radius.** `parent_radius = child_radius + gap`. Nested rounded surfaces nest; they
+  never collide.
+- **Interaction states.** Hover is an opacity or background change; press is `scale(0.96 to 0.98)` on
+  a control; focus is an outline only, never a border-width change.
+- **Floating menus** take a min and a max width, never a fixed width, and use the menu or anchored
+  popover primitives, which portal and own focus, dismiss and keyboard.
+- **Targets** are at least 24px (WCAG 2.2).
+
+---
+
+# The design system: it probably exists
+
+The recurring defect here is "built, not mounted": the right component shipped and the screen still
+hand-rolls a copy. Before you design or write a component, prove it does not already exist. If it
+exists, adopt or extend it (an additive variant or optional prop), never build a parallel one.
+
+## 1. Query the catalog first, never your memory
+
+The component catalog is the truth for which components exist, their imports, props and examples.
+Never use a component or prop it does not document. Read it in tiers, smallest first, never a whole
+manifest.
+
+1. **Tier 1: `synap-app/apps/storybook/inventory/CATALOG.md`** (~3.6k tokens, committed, always
+   fresh). One line per family: need, canonical, import, status, verdict, docs id. Find the family
+   for your need here. `consolidate` = build on the canonical, never on a copy; `missing` = none yet,
+   propose it (story first); "no public entry" = export it before using it, never deep-import;
+   `deprecated: Old → New` = never import Old (a tripwire fails on new imports).
+2. **Tier 2: the family card** `apps/storybook/storybook-static/agent/cards/<family-id>.md`
+   (≤ 800 tokens, written by `pnpm --filter @synap-core/storybook build-storybook`): the import
+   line, the key props with types and defaults, one or two story snippets, the copies you must not
+   hand-roll, the plan.
+3. **Storybook MCP** (`storybook` in `.mcp.json`): `docs-show <docs id>` from the tier-1 line for
+   full props and every story; `stories-find-by-component` for real usage.
+4. **Last resort: the full manifest** `/manifests/components.json` in the Storybook build
+   (~1.8 MB). Search it; never read it whole.
+
+- The inventory behind tier 1 (`apps/storybook/inventory/components.json`) and its audit
+  (`/component-audit.json`, the `#/map` canvas) say which families have a story and which copies
+  still live. Storybook covers only part of the library: a family absent from Storybook is not proof
+  that nothing exists.
+- If you can read none of these, stop and say so. Never design from what you remember a component
+  looks like.
+- The library lacks what you need? Say so and propose the component, story first. Never fake it with
+  a generic box.
+- A new or changed primitive ships with its story and JSDoc on the component and its props in the
+  same change; the story is what feeds the catalog.
+
+## 2. Stack by surface
+
+| Surface                | Build with                                                                                               |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| shared `@synap-core/*` | headless logic plus `--synap-*` tokens; no UI-library imports                                            |
+| desktop workbench      | plain CSS plus spatial-ui primitives; a third-party widget only when wrapped and themed with `--synap-*` |
+| standalone apps        | HeroUI plus the Synap HeroUI preset                                                                      |
+| mobile (relay)         | its own native kit on the native design tokens                                                           |
+
+Tamagui (`@synap-core/ui-system`) was removed. Never reintroduce it.
+
+## 3. The primitives (short form; the catalog is the truth)
+
+| Need                                           | Use                                                                                           | Not                              |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------- |
+| button, icon button                            | `SpatialButton`, `SpatialIconButton`                                                          | a raw `<button>`                 |
+| menu, context menu, stepped picker             | `SpatialMenu`                                                                                 | a positioned div + outside click |
+| popover, floating panel, toolbar               | `SpatialAnchoredPopover`                                                                      | a positioned div                 |
+| search-as-you-type list under an input         | `SpatialComboBoxPopover`                                                                      | an anchored popover              |
+| modal, drawer, confirm, form dialog            | `SpatialModal`, `SpatialDrawer`, `SpatialConfirmDialog`, `SpatialFormDialog`                  | `role="dialog"` by hand          |
+| input, select, combo, number, date             | `SpatialInput`, `SpatialSelect`, `SpatialComboBox`, `SpatialNumberField`, `SpatialDatePicker` | raw inputs                       |
+| panel, card, clickable card, tabs              | `SpatialPanel`, `SpatialCard` + `SpatialCardAction`, `SpatialTabStrip`, `SpatialTabs`         | positioned divs                  |
+| badge, chip, tag, avatar, progress             | `SpatialStatusBadge`, `SpatialChip`, `SpatialTag`, `SpatialAvatar`, `SpatialProgressBar`      | hand-rolled marks                |
+| image or file preview                          | `SpatialMediaPreview`                                                                         | a raw `<img>` on a stored blob   |
+| dashboard page (Home, project, track, session) | the lens-page components                                                                      | a local section shell or row     |
+| an AI turn's process                           | the shared turn-activity component                                                            | a local thinking box or dots     |
+
+- Overlays stay mounted to close: pass `isOpen` / `open` and let the component play its exit. Never
+  `{cond && <Modal/>}`.
+- `SpatialMediaPreview` is a security boundary: never point an `<img>`, `<video>`, `<iframe>` or
+  `<object>` at a stored blob yourself.
+- Third-party service marks (Telegram, Gmail, GitHub) come from the one service-mark registry. Never a
+  generic glyph or a hand-written service map.
+
+## 4. Tokens
+
+- **Colour:** `--synap-*` only. Ink, muted, surface, border, `--synap-primary` (the one accent),
+  `--synap-ai` (AI provenance only), and the status tones, each a fill plus its matching ink. Filled
+  primary surfaces use `--synap-primary-button`, not `--synap-primary`. Brand marks and canvas shape
+  colours are content, exempt from tokens; everything around them tokenizes.
+- **Spacing:** ONE 4px scale, web and mobile. `--synap-space-025` 2, `050` 4, `075` 6, `100` 8, `125`
+  10, `150` 12, `200` 16, `250` 20, `300` 24, `400` 32, `500` 40, `600` 48, `800` 64, `1000` 80,
+  `1200` 96. The old 6px-base names are deprecated; never use them in new work.
+- **Row heights:** `--synap-row-compact` 32 (navigation), `--synap-row` 40 (index rows),
+  `--synap-row-roomy` 48 (lens rows, one-line cards). Controls inside a row stay on the button scale.
+- **Control sizes:** `xs` 28, `sm` 34, `md` 40, `lg` 46. Never redraw a local small button.
+- **Type roles:** `display` and `title` (Fraunces), `heading`, `body`, `caption`, `label`, `num`,
+  `num-large`, `row-title`. In CSS use the longhand quartet
+  `var(--synap-type-<role>-family|-size|-weight|-leading)`; inline, spread the role object. A size alone
+  is `--synap-text-*`; line height `--synap-leading-*`; weight `--synap-weight-*`. When size, weight and
+  leading together match a role, use the role.
+- **Radius:** `--synap-radius-1` 6 (keycaps, smallest chips), `-2` 8 (icon tiles, small badges), `-3`
+  12 (rows, menu items), `-4` 16 (cards, panels), `--synap-radius-round` for pills (buttons, chips,
+  search bars, avatars). Same component class, same radius, everywhere; then apply concentric radius.
+- **Grid chrome on a canvas:** `--synap-grid` and `--synap-grid-strong`, never a grey literal.
+
+## 5. Labels go through the vocabulary door
+
+Never hand-write a label map for an object kind, action or status, and never capitalise a raw token
+at the call site. One door, `@synap-core/types/vocabulary`:
+
+| Need                     | Use                                |
+| ------------------------ | ---------------------------------- |
+| object kind to noun      | `resolveObjectNoun(kind)`          |
+| action to verb           | `resolveActionLabel(action, mood)` |
+| lifecycle state to label | `resolveStatusLabel(status)`       |
+| tool name to words       | `resolveToolLabel(toolName, mood)` |
+| any token to words       | `humanizeToken(token)`             |
+| "verb noun" title        | `buildObjectActionTitle({...})`    |
+| third-party service name | `resolveServiceName(id)`           |
+
+- Verbs have two moods: imperative ("Create") for buttons and pending proposals; past ("Created") for
+  history, feeds and receipts. Never collapse them.
+- Unknown values humanize, never leak. A raw token (`entity.create`, `in_review`) shown to a person
+  is a defect.
+- Dates, durations, sizes, empty-state sentences and domain-specific phrasings are not vocabulary;
+  keep them local.
+
+## 6. Motion: the named presets only
+
+Motion is one closed, named menu. A design or an agent says "fade-rise on enter", never a duration,
+easing or keyframe. Each preset carries a REQUIRED reduced-motion fallback, and the reader's OS
+setting always applies.
+
+| Preset          | Use it for                                                       | Reduced motion      |
+| --------------- | ---------------------------------------------------------------- | ------------------- |
+| `fade`          | backdrops, swapped content, anything that appears without moving | plays as-is         |
+| `fade-rise`     | a card, dialog or toast arriving in the reading flow             | `fade`              |
+| `scale-in`      | menus, popovers, pickers                                         | `fade`              |
+| `slide-in-side` | drawers and side panels                                          | `fade`              |
+| `collapse`      | accordions, disclosures                                          | instant (end state) |
+| `list-stagger`  | lists, boards, grids                                             | `fade`, no stagger  |
+
+- Code uses the preset component and the preset names from `@synap-core/web/motion`; never a raw
+  duration or easing in a `transition` or `animation` (a guard ratchets them).
+- Adding a preset is a design decision for a person, not something you do inline.
+
+---
+
+# The design-to-code loop
+
+```
+catalog ──► Puck JSON ──► 3 ui-design variants ──► critique ──► a person picks one, approves
+                                                                        │
+             merged + verified ◄── gates + compare + dogfood ◄── implement from the approved design
+```
+
+The process "Design to implementation" (Builder space) carries a design from draft to merged. A
+person, or an agent asked to, starts it on the request design with `synap_run_playbook`; it does not
+start itself on every new `ui-design`, because sibling variants are `ui-design`s too.
+
+## 1. The design is Puck JSON from real components
+
+```json
+{
+  "content": [
+    {
+      "type": "SpatialPanel",
+      "props": { "id": "SpatialPanel-1", "title": "Agents" }
+    },
+    {
+      "type": "SpatialButton",
+      "props": {
+        "id": "SpatialButton-1",
+        "children": "Add agent",
+        "size": "md"
+      }
+    }
+  ],
+  "root": { "props": { "title": "Settings › Agents" } },
+  "zones": {}
+}
+```
+
+- `content[]` is the page, top to bottom. Each item is `{ type, props }`; `props.id` is required and
+  unique (`<Type>-<n>` is fine).
+- `type` is a component name from the manifest, spelled exactly, and placeable (it has a story tagged
+  `canvas`). `props` are props it declares, with values of the declared type: an enum takes one of its
+  literals. Function props, `className`, `style`, `as` and raw HTML are never accepted.
+- A `children` prop of type ReactNode is a slot that holds an array of blocks. Other ReactNode props
+  (`label`, `title`) are plain text. Keep `zones` as `{}`. `root.props` holds page settings only.
+- No hex, rgb, px or font family in a prop; colour, spacing and type come from components and tokens.
+- Motion is not in the props. List it in the design's `motion` property as
+  `[{ "trigger": "enter", "target": "SpatialPanel-1", "preset": "fade-rise" }]` with named presets only.
+- Lay out every state the screen has: empty, loading, failed, full, long content. Each empty state is
+  OMIT, INVITE, EXPLAIN or REASSURE; a failed read is its own state with a retry.
+- The canvas validates on load: an unknown `type` refuses the whole design; an undeclared or wrong prop
+  is stripped and listed. Check yours with the canvas's Paste JSON.
+
+## 2. Save it as a `ui-design` entity
+
+Find before you create: `synap_find` for an existing `ui-design` on the same `target-surface`.
+
+- Create with `synap_create_entity`, `profileSlug: "ui-design"`, a title, and properties:
+  `target-surface` (app and screen), `design-scope` (`component` or `page`), `design-goal` (the job the
+  screen does; the critique judges against it), `design-json`, `components-used` (the distinct `type`
+  values, derived from the JSON, never typed by hand), `schema-version` (`1`), `motion`,
+  `current-story-id` (the story of the screen as it is today, when it exists), `design-notes`.
+- **Three variants by default.** One request is three designs: the request plus two siblings, sharing
+  one `variant-group`, `target-surface`, `design-scope` and `design-goal`. Make them genuinely
+  different answers (structure, density, order), not three colourings. Link each sibling to the
+  request with `relates_to`. If the person asks for one, make one.
+- Read the person's references first (linked with `references` via `synap_link_entities`).
+- Revise with `synap_update_entity`, writing `design-json` and `components-used` together.
+- `proposed` is success: a person reviews the write. Do not retry.
+- Never save a screenshot as the design, and never mirror components into the pod as entities.
+
+## 3. Critique: three tiers, not equally trusted
+
+Every finding names a rule id from the critique rubric (`design-critique` skill); no rule id, no
+finding. Write the list into each variant's `critique`.
+
+| Tier        | Who decides                                                                                                                                                        | May block | Applied automatically       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------------------- |
+| **Checked** | a tool or a measurement (axe, contrast, target size, tokens only, manifest only, named motion)                                                                     | yes       | the generator fixes it      |
+| **Pattern** | you classify what is on screen; a fixed house rule judges (marks, empty answers, doors, caps, order, one primary, AI colour, creation, raw tokens, states covered) | yes       | the generator fixes it      |
+| **Opinion** | your judgement, tied to one named Nielsen heuristic, low confidence                                                                                                | never     | **never**; a person decides |
+
+- Run the tool for a Checked rule; never estimate. Unmeasured is low confidence, never a pass.
+- The gate passes when every variant going to review has its critique and no open Checked or Pattern
+  blocker. Opinions never decide it.
+- A failing gate goes back to generation; then critique again from scratch. Never edit or delete a
+  finding to clear the gate. Only a person dismisses.
+
+## 4. The human gate
+
+`design-status`: `draft`, `in-review`, `approved`, `implementing`, `implemented`, `archived`.
+
+- Every move is `synap_update_entity` with the new `design-status` AND `expectedStatus` set to the
+  status you read. A conflict means someone moved it: re-read, decide again.
+- **`approved` is a person's call.** Put the design `in-review`, ask for the review, wait. A rejection
+  sends you back to revise.
+- The person picks ONE variant. Inside the process, if they choose a sibling, write its
+  `design-json`, `components-used` and `motion` into the request design before approval. Archiving
+  the others is the person's call.
+
+## 5. Implement from the approved design
+
+- Start only from `approved` (or `implementing` when the process already moved it). Draft or in
+  review: stop and say so. Move `approved` to `implementing` with `expectedStatus: "approved"`.
+- Read it with `synap_get_entity`. For each distinct `type`, confirm the component and its props in
+  the catalog. A missing type or prop: stop, record it in `design-notes`, propose the component.
+- Build only those components, in the order of `content[]` and its slots, with tokens only and the
+  named motion presets. The design gives layout, not data wiring: data still flows through the layers.
+- Give the screen a story and record its id in `implemented-story-id`. Never edit `design-json` to
+  match what you built; revise as a new draft instead.
+
+## 6. Verify against the design
+
+- Run the gates yourself and quote them: type-check, story tests (render, interaction, axe), visual
+  regression when a primitive changed (a moved pixel is a finding first, never a baseline update),
+  the token, hex and motion guards.
+- **Compare Today, Design and Built.** Capture the built story and, when set, the `current-story-id`
+  (today) with `pnpm --filter @synap-core/storybook capture`, the one capture door; render the design on
+  the canvas; list every difference. Then run the Checked tier on the built story.
+- Walk the screen in the running app with screenshots: WORKS, BROKEN or CANNOT-TELL.
+- Open the PR and record its URL in `implementation-pr`. Inside the process stop there: Done is a
+  person's gate that writes `implemented`. Outside it, a move to `implemented` proposes and a person
+  confirms the merge. Report VERIFIED separately from NEEDS-DOGFOOD.
+
+## 7. Where designs are viewed
+
+- **Team devbox, always on, built from `main`:** an index at `http://devbox:3000`, Storybook, the
+  Design app at `http://devbox:3007`: the Map (`#/`, every component Figma-style; tokens on its
+  Foundations page, also at `#/design-tokens`), the design canvas (`#/design`) and the Lab
+  (`#/lab`, live full experiences), and the
+  Storybook MCP at `http://devbox:3006/mcp`. These hosts are on the founder's private tailnet only:
+  an agent or pod outside it cannot reach them.
+- **Locally, for unmerged work:** `pnpm --filter @synap-core/storybook storybook` from the monorepo
+  root (127.0.0.1:6006, MCP at `/mcp`).
+- The Storybook MCP has no authentication. Reach it only on your own machine or over a private
+  network, never register it as a public pod MCP server. An agent on a remote pod reads the static
+  `/manifests/components.json` of a Storybook build instead.

package/skills/synap-design/_order.txt

@@ -0,0 +1,4 @@
+overview.md
+principles.md
+system.md
+loop.md

package/skills/synap-design/_skill.yaml

@@ -0,0 +1,21 @@
+name: synap-design
+description: >
+  Use this skill whenever you design, review or build user interface for
+  Synap, or a UI for a user's pod: a screen, page, panel, section, card,
+  component, empty state or dashboard. Triggers: "design this screen", "mock
+  up a page", "review this UI", "critique this design", "build this
+  component", "implement this ui-design", "why does this screen feel off",
+  "what should this page show". It holds the composition principles, the
+  design system (real components, tokens, labels, named motion) and the
+  design-to-code loop (ui-design entity, three variants, critique, human
+  approval, implement, compare). For views, bento dashboards and workspaces
+  over pod data, pair it with synap-ui.
+metadata:
+  synap:
+    requires:
+      env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
+    primaryEnv: SYNAP_HUB_API_KEY
+    homepage: https://synap.live
+    capabilities: [design, ui, critique, components]
+    os: [macos, linux, windows]
+    userInvocable: false

package/skills/synap-design/loop.md

@@ -0,0 +1,134 @@
+# The design-to-code loop
+
+```
+catalog ──► Puck JSON ──► 3 ui-design variants ──► critique ──► a person picks one, approves
+                                                                        │
+             merged + verified ◄── gates + compare + dogfood ◄── implement from the approved design
+```
+
+The process "Design to implementation" (Builder space) carries a design from draft to merged. A
+person, or an agent asked to, starts it on the request design with `synap_run_playbook`; it does not
+start itself on every new `ui-design`, because sibling variants are `ui-design`s too.
+
+## 1. The design is Puck JSON from real components
+
+```json
+{
+  "content": [
+    {
+      "type": "SpatialPanel",
+      "props": { "id": "SpatialPanel-1", "title": "Agents" }
+    },
+    {
+      "type": "SpatialButton",
+      "props": {
+        "id": "SpatialButton-1",
+        "children": "Add agent",
+        "size": "md"
+      }
+    }
+  ],
+  "root": { "props": { "title": "Settings › Agents" } },
+  "zones": {}
+}
+```
+
+- `content[]` is the page, top to bottom. Each item is `{ type, props }`; `props.id` is required and
+  unique (`<Type>-<n>` is fine).
+- `type` is a component name from the manifest, spelled exactly, and placeable (it has a story tagged
+  `canvas`). `props` are props it declares, with values of the declared type: an enum takes one of its
+  literals. Function props, `className`, `style`, `as` and raw HTML are never accepted.
+- A `children` prop of type ReactNode is a slot that holds an array of blocks. Other ReactNode props
+  (`label`, `title`) are plain text. Keep `zones` as `{}`. `root.props` holds page settings only.
+- No hex, rgb, px or font family in a prop; colour, spacing and type come from components and tokens.
+- Motion is not in the props. List it in the design's `motion` property as
+  `[{ "trigger": "enter", "target": "SpatialPanel-1", "preset": "fade-rise" }]` with named presets only.
+- Lay out every state the screen has: empty, loading, failed, full, long content. Each empty state is
+  OMIT, INVITE, EXPLAIN or REASSURE; a failed read is its own state with a retry.
+- The canvas validates on load: an unknown `type` refuses the whole design; an undeclared or wrong prop
+  is stripped and listed. Check yours with the canvas's Paste JSON.
+
+## 2. Save it as a `ui-design` entity
+
+Find before you create: `synap_find` for an existing `ui-design` on the same `target-surface`.
+
+- Create with `synap_create_entity`, `profileSlug: "ui-design"`, a title, and properties:
+  `target-surface` (app and screen), `design-scope` (`component` or `page`), `design-goal` (the job the
+  screen does; the critique judges against it), `design-json`, `components-used` (the distinct `type`
+  values, derived from the JSON, never typed by hand), `schema-version` (`1`), `motion`,
+  `current-story-id` (the story of the screen as it is today, when it exists), `design-notes`.
+- **Three variants by default.** One request is three designs: the request plus two siblings, sharing
+  one `variant-group`, `target-surface`, `design-scope` and `design-goal`. Make them genuinely
+  different answers (structure, density, order), not three colourings. Link each sibling to the
+  request with `relates_to`. If the person asks for one, make one.
+- Read the person's references first (linked with `references` via `synap_link_entities`).
+- Revise with `synap_update_entity`, writing `design-json` and `components-used` together.
+- `proposed` is success: a person reviews the write. Do not retry.
+- Never save a screenshot as the design, and never mirror components into the pod as entities.
+
+## 3. Critique: three tiers, not equally trusted
+
+Every finding names a rule id from the critique rubric (`design-critique` skill); no rule id, no
+finding. Write the list into each variant's `critique`.
+
+| Tier        | Who decides                                                                                                                                                        | May block | Applied automatically       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------------------- |
+| **Checked** | a tool or a measurement (axe, contrast, target size, tokens only, manifest only, named motion)                                                                     | yes       | the generator fixes it      |
+| **Pattern** | you classify what is on screen; a fixed house rule judges (marks, empty answers, doors, caps, order, one primary, AI colour, creation, raw tokens, states covered) | yes       | the generator fixes it      |
+| **Opinion** | your judgement, tied to one named Nielsen heuristic, low confidence                                                                                                | never     | **never**; a person decides |
+
+- Run the tool for a Checked rule; never estimate. Unmeasured is low confidence, never a pass.
+- The gate passes when every variant going to review has its critique and no open Checked or Pattern
+  blocker. Opinions never decide it.
+- A failing gate goes back to generation; then critique again from scratch. Never edit or delete a
+  finding to clear the gate. Only a person dismisses.
+
+## 4. The human gate
+
+`design-status`: `draft`, `in-review`, `approved`, `implementing`, `implemented`, `archived`.
+
+- Every move is `synap_update_entity` with the new `design-status` AND `expectedStatus` set to the
+  status you read. A conflict means someone moved it: re-read, decide again.
+- **`approved` is a person's call.** Put the design `in-review`, ask for the review, wait. A rejection
+  sends you back to revise.
+- The person picks ONE variant. Inside the process, if they choose a sibling, write its
+  `design-json`, `components-used` and `motion` into the request design before approval. Archiving
+  the others is the person's call.
+
+## 5. Implement from the approved design
+
+- Start only from `approved` (or `implementing` when the process already moved it). Draft or in
+  review: stop and say so. Move `approved` to `implementing` with `expectedStatus: "approved"`.
+- Read it with `synap_get_entity`. For each distinct `type`, confirm the component and its props in
+  the catalog. A missing type or prop: stop, record it in `design-notes`, propose the component.
+- Build only those components, in the order of `content[]` and its slots, with tokens only and the
+  named motion presets. The design gives layout, not data wiring: data still flows through the layers.
+- Give the screen a story and record its id in `implemented-story-id`. Never edit `design-json` to
+  match what you built; revise as a new draft instead.
+
+## 6. Verify against the design
+
+- Run the gates yourself and quote them: type-check, story tests (render, interaction, axe), visual
+  regression when a primitive changed (a moved pixel is a finding first, never a baseline update),
+  the token, hex and motion guards.
+- **Compare Today, Design and Built.** Capture the built story and, when set, the `current-story-id`
+  (today) with `pnpm --filter @synap-core/storybook capture`, the one capture door; render the design on
+  the canvas; list every difference. Then run the Checked tier on the built story.
+- Walk the screen in the running app with screenshots: WORKS, BROKEN or CANNOT-TELL.
+- Open the PR and record its URL in `implementation-pr`. Inside the process stop there: Done is a
+  person's gate that writes `implemented`. Outside it, a move to `implemented` proposes and a person
+  confirms the merge. Report VERIFIED separately from NEEDS-DOGFOOD.
+
+## 7. Where designs are viewed
+
+- **Team devbox, always on, built from `main`:** an index at `http://devbox:3000`, Storybook, the
+  Design app at `http://devbox:3007`: the Map (`#/`, every component Figma-style; tokens on its
+  Foundations page, also at `#/design-tokens`), the design canvas (`#/design`) and the Lab
+  (`#/lab`, live full experiences), and the
+  Storybook MCP at `http://devbox:3006/mcp`. These hosts are on the founder's private tailnet only:
+  an agent or pod outside it cannot reach them.
+- **Locally, for unmerged work:** `pnpm --filter @synap-core/storybook storybook` from the monorepo
+  root (127.0.0.1:6006, MCP at `/mcp`).
+- The Storybook MCP has no authentication. Reach it only on your own machine or over a private
+  network, never register it as a public pod MCP server. An agent on a remote pod reads the static
+  `/manifests/components.json` of a Storybook build instead.