@synap-core/cli 1.10.0 → 1.12.2

package/skills/synap-design/overview.md

@@ -0,0 +1,44 @@
+# 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 |

package/skills/synap-design/principles.md

@@ -0,0 +1,130 @@
+# 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).

package/skills/synap-design/system.md

@@ -0,0 +1,133 @@
+# 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.