@misoto22/folio 0.0.0 → 0.16.0

package/skills/folio-design/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: folio-design
+description: Builds UI with @misoto22/folio — a monochrome design system of CSS tokens and 83 accessible React primitives, charts and diagrams included. Use when a project imports '@misoto22/folio', '@misoto22/folio/charts' '@misoto22/folio/diagrams' or '@misoto22/folio/website', sets data-mode / data-surface / data-radius / data-density, or uses cn(), CONTROL_BASE, or isInvalid. Also applies when adding a component, theming, plotting data, drawing an architecture, workflow, sequence, data-flow or lifecycle diagram, or fixing a form, table, dialog, or toast in such a project.
+allowed-tools: Bash(npx @misoto22/folio *), Bash(pnpm exec folio-design *), Bash(bunx @misoto22/folio *)
+---
+
+# @misoto22/folio
+
+CSS tokens plus React 19 primitives. Components ship compiled — you import them,
+you do not copy them into the project.
+
+```tsx
+import { Button, Field, Input } from '@misoto22/folio'
+import '@misoto22/folio/styles.css'
+```
+
+## Four entry points
+
+The root entry has no dependencies a consumer has to install. Two groups live
+behind their own specifier instead, each for weight the root should not carry:
+
+```tsx
+import { AreaChart, BarList, BigNumber } from '@misoto22/folio/charts'
+import { ArchitectureFigure, DiagramCanvas } from '@misoto22/folio/diagrams'
+import { SiteShell, Portfolio, CollectionIntro, SearchPalette } from '@misoto22/folio/website'
+```
+
+Charts need a rendering engine and an animation runtime that nothing else in
+the package does:
+
+```bash
+pnpm add recharts motion      # optional peers, only for the charts entry
+```
+
+That separation is the reason an app that renders a Badge never resolves
+`recharts` — so importing a chart from the root specifier does not render a
+blank component, it throws. `docs <Component>` prints the right line for each
+one; the `Import:` header is derived from the tree the component lives in, not
+written by hand.
+
+Some of the charts need no engine at all — `Heatmap` is a `<table>`,
+`Sparkline` is one `<path>`, `BarList`, `BigNumber` and `BulletChart` are plain
+HTML — but they ship from the charts entry all the same, so the boundary stays
+one line rather than a list to memorise.
+
+Diagrams need no peer at all; they carry an orthogonal routing engine instead,
+which has no business in a bundle that renders a Badge. Reach for that entry
+when the task is to DRAW a system rather than to build a screen:
+`ArchitectureFigure` for what talks to what, `WorkflowFigure` for a process in
+lanes, `SequenceFigure` for a call chain over time, `DataflowFigure` for a
+pipeline, `LifecycleFigure` for a state machine. Each takes a typed JSON
+specification and renders on a server. `Diagram` is a different thing and stays
+on the root: a nesting CSS diagram for an article, not an SVG figure with
+routed edges.
+
+One more, for surfaces that cannot read a custom property — an OpenGraph card, a
+`theme-color`, a canvas:
+
+```ts
+import { TOKENS } from '@misoto22/folio/tokens'
+```
+
+Never for styling a component. A literal in a stylesheet is a value that stops
+following the theme, and every one of these mirrors a token that does.
+
+## What this project has installed
+
+```
+!`npx @misoto22/folio docs --installed`
+```
+
+That is the version resolved in this project and every component it ships. Get
+one component's full contract — every prop with its type and default, its
+exported unions, its keyboard map, its accessibility promises, its examples —
+with:
+
+```bash
+npx @misoto22/folio docs Button
+```
+
+Run that before writing against a component you have not used in this session.
+The median component is ~500 tokens and the largest is ~1,300, against far more
+for all eighty-three. It is generated from the installed source, so it cannot be
+out of date the way the website can — and each file names the specifier it
+ships from on its `Import:` line, which is the half that matters below.
+
+It also resolves parts and types, not just components: `docs CardBody`,
+`docs TH` and `docs ButtonVariant` all land on the right file. When an import
+fails, ask it about the identifier you tried.
+
+## The one thing to internalise
+
+**This is not shadcn/ui, and the names differ where it matters most.** A model
+writing from habit produces imports that do not exist. The full table is in
+[naming.md](./rules/naming.md); these four are the ones that come up every time:
+
+| Habit | Here |
+| --- | --- |
+| `CardContent` | **`CardBody`** |
+| `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` | **`THead` / `TBody` / `TR` / `TH` / `TD`** |
+| `<DialogTitle>` as a child | **`<DialogContent title="…">`** — a prop, not a child |
+| `<AlertTitle>` / `<AlertDescription>` | **`<Alert tone title="…">`** — props, not children |
+
+## Critical rules
+
+Always enforced. Each links to a file with Incorrect/Correct pairs — read it when
+you are about to do that thing, not before.
+
+### Colour and theming → [tokens.md](./rules/tokens.md)
+
+- **Never write a raw colour.** No `bg-neutral-900`, no `text-gray-500`, no hex.
+  Read the semantic layer: `bg-(--background)`, `text-(--foreground-muted)`,
+  `border-(--border-color)`.
+- **Never write a `dark:` variant.** Dark mode is a value swap behind
+  `data-mode="dark"`; a `dark:` override fights it and wins in only one theme.
+- **Theme with the `data-*` axes**, set on any element, not just `:root`.
+  `data-mode`, `data-accent`, `data-surface`, `data-radius`, `data-rules`,
+  `data-type`, `data-motion`, `data-density`, `data-table-density`,
+  `data-chart-palette`. `npx @misoto22/folio docs --installed` prints the
+  current list; it is read out of the stylesheets rather than kept by hand here.
+- **Durations and radii come from tokens.** `duration-(--duration-fast)`,
+  `rounded-(--radius)` — not `duration-150`, not `rounded-lg`.
+- **No blurred shadow.** `--shadow*` resolves to `none` on purpose. Depth is a
+  hairline, a change of ground, or `--lift`.
+
+### Composition → [composition.md](./rules/composition.md)
+
+- **`className` adjusts layout, never appearance.** Margin, width, grid
+  placement — yes. Colour, border, radius, font — no; that is what the props and
+  the axes are for.
+- **Use `cn()` for conditional classes.** It is exported. Plain template
+  literals emit both sides of a Tailwind conflict and let stylesheet order pick
+  the winner.
+- **Card uses the full set.** `Card` → `CardHeader` / `CardTitle` / `CardBody` /
+  `CardFooter`. Do not dump everything into one div.
+- **`Select` is one component, not a compound.** It takes `label`, `placeholder`
+  and `SelectItem` children. There is no `SelectTrigger` or `SelectValue`.
+- **Logical properties, always.** `ps-` / `pe-` / `start-` / `end-` /
+  `text-start`. The package is RTL-correct and a physical property breaks it.
+
+### Forms → [forms.md](./rules/forms.md)
+
+- **A labelled control is a `Field`.** `<Field label hint error required>` wraps
+  one control and wires `aria-describedby`, `aria-required` and `aria-invalid`
+  onto it. Never hand-roll `<label>` + input + error div.
+- **Errors go in `Field`'s `error` prop.** It replaces `hint` — they are one
+  slot, not two stacked messages — and it sets `aria-invalid` on the control for
+  you, so do not also pass `invalid`.
+- **Outside a `Field`, invalid state is `invalid` or `aria-invalid`** on the
+  control. Never a red border class.
+- **One control per `Field`.** The wiring clones a single element child; a
+  wrapper div around two controls silently wires nothing.
+- **Build custom controls on `CONTROL_BASE` + `CONTROL_BORDER`** and read the
+  state with `isInvalid()`. All three are exported.
+
+### Accessibility → [a11y.md](./rules/a11y.md)
+
+- **Four props are required by the type because forgetting them ships an
+  unusable control**: `Table.caption`, `Progress.label`, `Avatar.alt`,
+  `FloatingIconButton.label`. `Select.label` and `Badge.children` too.
+- **`<Button iconOnly>` needs `aria-label`.** There is no text to read.
+- **Decoration is `aria-hidden`.** A status dot beside the word "Available"
+  repeats it.
+- **Colour is never the only carrier** of a status. Every tone is doubled by an
+  icon or by the words.
+
+### Imports
+
+- **`toast` comes from `@misoto22/folio`, not from `sonner`.** Render `<Toaster />`
+  once at the app root.
+- **Styles are a separate import.** `@misoto22/folio/styles.css` for the whole
+  compiled sheet, or `tokens.css` + `semantic.css` + `keyframes.css` when the app
+  compiles its own Tailwind. Compositions from `@misoto22/folio/website` also
+  need `website.css`, plus `website-base.css` when the whole page is a website.
+
+## Key patterns
+
+```tsx
+// A labelled, validated field. Field does the ARIA wiring, including
+// aria-invalid — do not also pass `invalid` on the control.
+<Field label="Email" required error={errors.email}>
+  <Input type="email" />
+</Field>
+
+// A select. One component; label is required.
+<Select label="Region" placeholder="Choose one">
+  <SelectItem value="au">Australia</SelectItem>
+</Select>
+
+// A dialog. The title is a prop, and it is not optional for a screen reader.
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent title="Delete project" description="This cannot be undone.">
+    <Button variant="danger">Delete</Button>
+  </DialogContent>
+</Dialog>
+
+// A table. caption is required; it is what a screen reader announces.
+<Table caption="Open invoices" borders="rows">
+  <THead><TR><TH>Client</TH><TH align="end">Amount</TH></TR></THead>
+  <TBody><TR><TD>Acme</TD><TD align="end">$1,200</TD></TR></TBody>
+</Table>
+
+// Colour: semantic tokens, no raw values, no dark: variant.
+<div className="bg-(--card-background) text-(--foreground-muted)">  // correct
+<div className="bg-white text-gray-500 dark:bg-neutral-900">        // wrong
+
+// Theming: an axis on any element themes the subtree below it.
+<section data-surface="warm" data-radius="round">…</section>
+```
+
+## Variants, in full
+
+Short enough to inline; everything else comes from `docs <Component>`.
+
+Every union is exported under the name in brackets, so a wrapper can take one
+without retyping it.
+
+- `Button` — `variant` [`ButtonVariant`]: `primary` `secondary` `ghost` `danger` · `size` [`ButtonSize`]: `sm` `md` `lg` · also `href`, `asChild`, `loading`, `iconOnly`, `keycap`
+- `Badge` — `tone` [`BadgeTone`]: `neutral` `success` `warning` `danger` `outline`
+- `Alert` — `tone` [`AlertTone`]: `info` `success` `warning` `danger`
+- `Card` — `variant`: `outline` `plate` `flat`
+- `Table` — `borders` [`TableBorders`]: `rows` `grid` `bordered` `bordered-grid` `none` · `density`: `comfortable` `compact`
+- `TH` / `TD` — `align` [`TableAlign`]: `start` `center` `end`
+
+For metadata and Node build scripts, `import { BRAND } from '@misoto22/folio/brand'`
+loads the canonical color mirror without React. This is a data-only subpath,
+separate from the four React entry points above.

package/skills/folio-design/evals/claims.json

@@ -0,0 +1,95 @@
+{
+  "$comment": "Every identifier the skill tells an agent to write, paired with the habit it replaces. `skill.test.ts` asserts that each `use` is really exported, that each `avoid` really is not, and that both still appear in the rules — so a rename in the package, or a rule quietly deleted from the prose, fails the build instead of teaching the next agent something that stopped being true.",
+  "naming": [
+    { "use": "CardBody", "avoid": "CardContent" },
+    { "use": "THead", "avoid": "TableHeader" },
+    { "use": "TBody", "avoid": "TableBody" },
+    { "use": "TR", "avoid": "TableRow" },
+    { "use": "TH", "avoid": "TableHead" },
+    { "use": "TD", "avoid": "TableCell" },
+    { "use": "DialogContent", "avoid": "DialogTitle" },
+    { "use": "DialogContent", "avoid": "DialogHeader" },
+    { "use": "SheetContent", "avoid": "SheetTitle" },
+    { "use": "Tooltip", "avoid": "TooltipTrigger" },
+    { "use": "Tooltip", "avoid": "TooltipContent" },
+    { "use": "Alert", "avoid": "AlertTitle" },
+    { "use": "Alert", "avoid": "AlertDescription" },
+    { "use": "AccordionItem", "avoid": "AccordionTrigger" },
+    { "use": "AccordionItem", "avoid": "AccordionContent" },
+    { "use": "Select", "avoid": "SelectTrigger" },
+    { "use": "Select", "avoid": "SelectValue" },
+    { "use": "Select", "avoid": "SelectContent" }
+  ],
+  "$comment2": "Identifiers the skill names as real and reachable, without pairing them against a habit. Same guarantee: named in the prose, exported by the package.",
+  "exported": [
+    "cn",
+    "toast",
+    "Toaster",
+    "CONTROL_BASE",
+    "CONTROL_BORDER",
+    "isInvalid",
+    "Field",
+    "Input",
+    "Textarea",
+    "NativeSelect",
+    "Combobox",
+    "Checkbox",
+    "Switch",
+    "RadioGroup",
+    "RadioGroupItem",
+    "ToggleGroup",
+    "ToggleGroupItem",
+    "Slider",
+    "DatePicker",
+    "DateRangePicker",
+    "Card",
+    "CardHeader",
+    "CardTitle",
+    "CardFooter",
+    "Table",
+    "EmptyState",
+    "ErrorState",
+    "Separator",
+    "Skeleton",
+    "SkeletonLine",
+    "SkeletonText",
+    "SkeletonPage",
+    "Badge",
+    "StatusPill",
+    "Kbd",
+    "Breadcrumb",
+    "AppShell",
+    "Steps",
+    "Article",
+    "SelectItem",
+    "TooltipProvider",
+    "DialogTrigger",
+    "ButtonVariant",
+    "ButtonSize",
+    "BadgeTone",
+    "AlertTone",
+    "TableAlign",
+    "TableBorders"
+  ],
+  "$comment3": "Required-by-the-type props the a11y rule promises. `skill.test.ts` checks each against the extracted source, so a prop that stops being required stops being advertised as required.",
+  "requiredProps": [
+    { "component": "Table", "part": "Table", "prop": "caption" },
+    { "component": "Progress", "part": "Progress", "prop": "label" },
+    { "component": "Avatar", "part": "Avatar", "prop": "alt" },
+    { "component": "Avatar", "part": "Avatar", "prop": "fallback" },
+    { "component": "FloatingIconButton", "part": "FloatingIconButton", "prop": "label" },
+    { "component": "FloatingIconButton", "part": "FloatingIconButton", "prop": "position" },
+    { "component": "Select", "part": "Select", "prop": "label" },
+    { "component": "Combobox", "part": "Combobox", "prop": "label" },
+    { "component": "Combobox", "part": "Combobox", "prop": "options" },
+    { "component": "Sheet", "part": "SheetContent", "prop": "title" },
+    { "component": "Accordion", "part": "AccordionItem", "prop": "title" },
+    { "component": "EmptyState", "part": "EmptyState", "prop": "title" },
+    { "component": "Badge", "part": "Badge", "prop": "children" }
+  ],
+  "$comment4": "Props the skill describes as OPTIONAL where a reader would assume otherwise. Guarded in the same direction: if one becomes required, the prose that says it is not has to change with it.",
+  "optionalProps": [
+    { "component": "Dialog", "part": "DialogContent", "prop": "title" },
+    { "component": "Alert", "part": "Alert", "prop": "title" }
+  ]
+}

package/skills/folio-design/evals/evals.json

@@ -0,0 +1,84 @@
+{
+  "$comment": "Prompts a real agent runs against this skill, and what its output has to show. This is the half `claims.json` cannot reach: that file proves the rules match the package, which is necessary and does not prove an agent given the rules writes correct code. Each `must_use` identifier is checked for existence by `skill.test.ts`, so an eval cannot quietly start expecting something the package no longer exports.",
+  "skill_name": "folio-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Using @misoto22/folio, build a settings form with fields for full name and email address, and show a validation error under email when it is invalid.",
+      "expected_output": "A React component using one Field per control, the error prop rather than a red border, and gap-* on the form.",
+      "must_use": ["Field", "Input", "Button"],
+      "must_not_contain": ["space-y-", "border-red", "text-red-", "<label", "aria-describedby="],
+      "expectations": [
+        "Wraps each control in its own Field with a label, not a hand-rolled <label> plus input plus error div",
+        "Puts the validation message in Field's error prop, which sets aria-invalid on the control for it",
+        "Does not also pass invalid on the Input inside a Field with an error — that is redundant",
+        "Never a wrapper div between Field and its control, which would wire the div instead",
+        "Lays the form out with flex and gap-*, not space-y-*"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Using @misoto22/folio, add a confirmation dialog for deleting a project. It needs a heading, an explanation, and Cancel and Delete buttons.",
+      "expected_output": "A Dialog whose title and description are props on DialogContent, with a danger-variant Delete button.",
+      "must_use": ["Dialog", "DialogTrigger", "DialogContent", "Button"],
+      "must_not_contain": ["DialogTitle", "DialogHeader", "DialogDescription", "DialogFooter"],
+      "expectations": [
+        "Passes title and description as props on DialogContent — there is no DialogTitle or DialogHeader export here",
+        "Uses variant=\"danger\" for the destructive action",
+        "Wraps the trigger with asChild rather than nesting a button inside a button",
+        "Sets no z-index: the overlay handles its own stacking"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Using @misoto22/folio, render a table of open invoices with client, due date and amount, with the amount column right-aligned.",
+      "expected_output": "A Table with a real caption and the short part names, amount aligned with the align prop.",
+      "must_use": ["Table", "THead", "TBody", "TR", "TH", "TD"],
+      "must_not_contain": ["TableHeader", "TableBody", "TableRow", "TableHead", "TableCell", "text-right"],
+      "expectations": [
+        "Uses THead / TBody / TR / TH / TD — the shadcn/ui names are not exported here",
+        "Gives caption a real sentence saying what the table lists, not an empty string and not the word \"Table\"",
+        "Right-aligns with align=\"end\" on TH and TD, not a text-right class, so the table stays RTL-correct"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Using @misoto22/folio, build a dashboard row of four stat cards. Each shows a title, a big number, a change badge, and a loading state.",
+      "expected_output": "Full Card composition, Skeleton for loading, Badge for the change, semantic tokens throughout.",
+      "must_use": ["Card", "CardHeader", "CardTitle", "CardBody", "Badge", "Skeleton"],
+      "must_not_contain": ["CardContent", "animate-pulse", "bg-green-", "text-red-", "dark:"],
+      "expectations": [
+        "Uses CardBody, not CardContent",
+        "Composes CardHeader and CardTitle rather than putting everything in one block",
+        "Uses Skeleton for the loading placeholder, not a custom animate-pulse div",
+        "Uses Badge for the change rather than a styled span",
+        "Writes no raw colour and no dark: variant — semantic tokens resolve in both modes"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Using @misoto22/folio, add a small area chart of monthly revenue above the stat cards.",
+      "expected_output": "A chart imported from the charts entry point, with the peers named.",
+      "must_use": ["AreaChart"],
+      "must_not_contain": ["from '@misoto22/folio'\nimport { AreaChart"],
+      "expectations": [
+        "Imports the chart from '@misoto22/folio/charts', not from the root specifier — the root does not export it and the import throws",
+        "Mentions that recharts and motion are peer dependencies the project needs installed",
+        "Does not reach for recharts directly to build the chart by hand"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Using @misoto22/folio, add an icon-only button that copies the current URL, and a toast confirming it.",
+      "expected_output": "An iconOnly Button with an accessible name, and toast imported from this package.",
+      "must_use": ["Button", "toast", "Toaster"],
+      "must_not_contain": ["from 'sonner'"],
+      "expectations": [
+        "Gives the iconOnly Button an aria-label naming the action — without one it is announced as \"button\" and nothing else",
+        "Imports toast from '@misoto22/folio', not from sonner",
+        "Renders Toaster once at the app root rather than beside the button",
+        "Puts no sizing class on the icon"
+      ]
+    }
+  ]
+}

package/skills/folio-design/rules/a11y.md

@@ -0,0 +1,167 @@
+# Accessibility
+
+The package keeps these promises so a call site does not have to. What is left
+is the handful of things only the call site knows — and every one of them is a
+prop that is easy to leave off and impossible to notice afterwards.
+
+## Props the type makes required, and why
+
+These are required in TypeScript because forgetting them ships a control that
+cannot be used without sight. Do not satisfy the type with a placeholder.
+
+| Prop | What it is |
+| --- | --- |
+| `Table.caption` | What the table is a table *of*. Announced before the rows. |
+| `Progress.label` | What is progressing. `aria-valuetext` has nothing else to say. |
+| `Avatar.alt` + `Avatar.fallback` | Who it is, and the initials shown when the image fails. |
+| `FloatingIconButton.label` | There is no text in the button at all. |
+| `Select.label` | The trigger is a button; this is its accessible name. |
+| `Combobox.label` | Same. |
+| `SheetContent.title` | A panel with no name drops a screen reader into an unnamed region. |
+| `AccordionItem.title` | The heading that is also the trigger. |
+| `EmptyState.title` | The state's own name. |
+| `Alert.title` | Optional, but an alert with no title is a coloured paragraph. |
+
+```tsx
+// Incorrect — the type is satisfied and the table is still anonymous
+<Table caption="">
+
+// Incorrect — the caption is not a label for the reader, it is the reader's only orientation
+<Table caption="Table">
+
+// Correct
+<Table caption="Invoices awaiting payment">
+```
+
+Use `showCaption={false}` when the design has no room for a visible caption. The
+caption still reaches assistive tech.
+
+## An icon-only control needs a name
+
+Development warns on both failures in this section rather than leaving them to
+review: `BUTTON_ICON_ONLY_UNNAMED` when an `iconOnly` Button has neither
+`aria-label` nor `aria-labelledby`, and `REQUIRED_NAME_BLANK` when a name that
+is required for accessibility is an empty string. Each names the field and the
+fix, so a failed render tells you what to change.
+
+They are two of nineteen. The whole set, so a code you meet in a console is
+findable:
+
+| Code | Fires when |
+| --- | --- |
+| `ARTICLE_HTML_AND_CHILDREN` | `Article` is given both `html` and `children`. |
+| `BREADCRUMB_CRUMB_NOT_LINKED` | A crumb before the last carries no `href`. |
+| `BUTTON_ICON_ONLY_UNNAMED` | An icon-only `Button` has no accessible name. |
+| `DIALOG_TITLE_MISSING` | `DialogContent` has no `title`. |
+| `FIELD_CONTROL_NOT_LABELLABLE` | A `Field`'s child is a host element that cannot take a label. |
+| `FIELD_CONTROL_NOT_WIRED` | A `Field`'s child is not a single element, so nothing was wired. |
+| `REQUIRED_NAME_BLANK` | A name required for accessibility is an empty string. |
+| `SEARCHABLE_MENU_LABEL_UNREADABLE` | A `SearchableMenu` action's label has no text and no `keywords`, so typing can never find it. |
+
+`Diagram` checks the spec it was handed, because a figure that ignores an edge
+still renders beautifully:
+
+| Code | Fires when |
+| --- | --- |
+| `DIAGRAM_ACCENT_ON_CONTAINER` | `accent` on a node with children, drawn as a band with no fill to take. |
+| `DIAGRAM_DIRECTION_ON_LEAF` | `direction` on a node with no children. |
+| `DIAGRAM_DUPLICATE_ID` | Two nodes carry the same `id`. |
+| `DIAGRAM_EDGE_NOT_ADJACENT` | An edge names two nodes that are never consecutive siblings. |
+| `DIAGRAM_EDGE_UNKNOWN_NODE` | An edge names an `id` no node carries. |
+
+And the figures in `@misoto22/folio/diagrams` check theirs:
+
+| Code | Fires when |
+| --- | --- |
+| `DIAGRAM_CELL_COLLISION` | Two nodes land at the same coordinate, so one plate is drawn on top of the other. |
+| `DIAGRAM_EDGE_DANGLING` | A relationship names an id the specification does not declare, so it is left out of the picture and the summary. |
+| `DIAGRAM_LANE_UNKNOWN` | A node names a lane no lane in the specification declares; it falls back to the first. |
+| `DIAGRAM_REF_UNKNOWN` | A field references an id no node in the specification declares. |
+| `DIAGRAM_SPEC_MUTATED` | The same spec object arrives with different contents; the model is memoised on identity, so the figure still draws the first. |
+| `DIAGRAM_STAGE_OUT_OF_RANGE` | A node's `stage` falls past the last declared stage, so it is drawn in a column the axis does not label. |
+
+All of them are development-only — every call site is behind
+`process.env.NODE_ENV`, so nothing here reaches a production bundle — and each
+prints once per problem, the field that caused it, and an imperative fix.
+
+```tsx
+// Incorrect — reads as "button"
+<Button iconOnly><TrashIcon /></Button>
+
+// Correct
+<Button iconOnly aria-label="Delete invoice"><TrashIcon /></Button>
+```
+
+The same applies to any `Button` whose children are only an icon, whether or not
+`iconOnly` is set. `FloatingIconButton` cannot get this wrong — its `label` is
+required.
+
+## Decoration is `aria-hidden`
+
+An icon that repeats the words beside it is noise; an arrow inside a link is
+read out as "north east arrow".
+
+```tsx
+// Incorrect
+<StatusPill tone="success"><CheckIcon /> Available</StatusPill>
+
+// Correct
+<StatusPill tone="success"><CheckIcon aria-hidden="true" /> Available</StatusPill>
+```
+
+## Colour is never the only carrier
+
+Every status tone in the system is doubled by an icon, by the words, or by both.
+Keep that when you compose.
+
+```tsx
+// Incorrect — the only difference between these two rows is a hue
+<TD><span className="text-(--danger)">●</span></TD>
+
+// Correct
+<TD><StatusPill tone="danger">Overdue</StatusPill></TD>
+```
+
+## Do not re-implement a pattern Radix already owns
+
+Focus traps, roving tabindex, typeahead, portal placement and scroll locking are
+where a hand-rolled component quietly becomes unusable with a keyboard. `Dialog`,
+`Sheet`, `Popover`, `DropdownMenu`, `ContextMenu`, `Tabs`, `Accordion`,
+`RadioGroup`, `ToggleGroup`, `Select`, `Slider` and `Tooltip` already wrap it.
+
+```tsx
+// Incorrect
+<div role="dialog" className="fixed inset-0 …" onKeyDown={handleEscape}>
+
+// Correct
+<Dialog><DialogContent title="…">…</DialogContent></Dialog>
+```
+
+## Motion is gated
+
+Anything animated is behind `motion-safe` and carries `data-folio-animated`. Do
+both when you animate something yourself — but know what each one buys. The
+GUARANTEE is a universal rule in `keyframes.css`: under
+`prefers-reduced-motion: reduce`, `animation-duration` and `transition-duration`
+are clamped to 0.01ms on `*`, so your animation is covered whether or not you
+remember the attribute. `data-folio-animated` goes further, removing the
+animation outright rather than running an instant frame of it — read it as the
+component asserting its motion is decorative, not as the thing that does the
+cancelling.
+
+```tsx
+// Correct — the package's keyframes are all prefixed `folio-`
+<div data-folio-animated className="motion-safe:animate-[folio-fade-in_200ms_var(--ease-out-expo)]">
+```
+
+`data-motion="still"` on any ancestor stops motion in that subtree.
+
+## The keyboard contract is documented per component
+
+```bash
+npx @misoto22/folio docs Combobox
+```
+
+prints the key-by-key contract. It is the part that quietly regresses — a
+wrapper that swallows a key looks identical until someone tries it — so check it
+before you wrap one of these in your own handler.