@misoto22/design 0.7.0 → 0.8.0

package/AGENTS.md

@@ -0,0 +1,87 @@
+# @misoto22/design — for agents
+
+Pointers, not content. Everything below is generated from the source in this
+same tarball, so nothing here can describe a version that is not installed.
+
+## You have installed this package
+
+You are probably reading this because you searched `node_modules` for a filename
+you recognise. The three commands are what you came for:
+
+```bash
+npx misoto22-design docs Button        # one component, in full
+npx misoto22-design docs --installed   # this version, and every component in it
+npx misoto22-design init --agents-md   # install the skill into this project
+```
+
+`docs` resolves parts and types as well as components, so `docs CardBody`,
+`docs TH` and `docs ButtonVariant` all land on the right file. When an import
+fails, ask it about the identifier you tried.
+
+Read `skills/misoto22-design/SKILL.md` in this package before writing components
+against it. The names diverge from shadcn/ui in several places, and colour is
+never written as a raw class; the skill leads with both.
+
+`init` writes it to `.agents/skills/` — the path Codex, Cursor, Copilot, Gemini
+CLI, OpenCode, Cline, Zed and Warp share — and to `.claude/skills/` when the
+project already has one. For anything else, `npx skills add
+Misoto22/misoto22-design` finds this skill with no configuration.
+
+Some misuse fails silently, so the components say so in development:
+`FIELD_CONTROL_NOT_LABELLABLE` when a wrapper takes the label instead of the
+control, `BUTTON_ICON_ONLY_UNNAMED` when an icon-only button has no accessible
+name, `REQUIRED_NAME_BLANK` when a required name is an empty string. Each prints
+the field and an imperative fix, once per problem, and none reaches a production
+bundle.
+
+Nineteen codes in all. Eight on the primitives —
+`ARTICLE_HTML_AND_CHILDREN`, `BREADCRUMB_CRUMB_NOT_LINKED`,
+`BUTTON_ICON_ONLY_UNNAMED`, `DIALOG_TITLE_MISSING`,
+`FIELD_CONTROL_NOT_LABELLABLE`, `FIELD_CONTROL_NOT_WIRED`,
+`REQUIRED_NAME_BLANK`, `SEARCHABLE_MENU_LABEL_UNREADABLE`. Five on `Diagram`,
+which checks the spec it was handed because a figure that ignores an edge still
+renders beautifully — `DIAGRAM_ACCENT_ON_CONTAINER`, `DIAGRAM_DIRECTION_ON_LEAF`,
+`DIAGRAM_DUPLICATE_ID`, `DIAGRAM_EDGE_NOT_ADJACENT`,
+`DIAGRAM_EDGE_UNKNOWN_NODE`. And six on the figures in
+`@misoto22/design/diagrams` — `DIAGRAM_CELL_COLLISION`, `DIAGRAM_EDGE_DANGLING`,
+`DIAGRAM_LANE_UNKNOWN`, `DIAGRAM_REF_UNKNOWN`, `DIAGRAM_SPEC_MUTATED`,
+`DIAGRAM_STAGE_OUT_OF_RANGE`. `skills/misoto22-design/rules/a11y.md` tables what
+each one fires on; `src/lib/warn.ts` is where they are printed.
+
+Three entry points, and importing from the wrong one throws rather than renders
+blank. Each `docs` file names its own on the `Import:` line.
+
+| Specifier | What ships from it |
+| --- | --- |
+| `@misoto22/design` | The primitives |
+| `@misoto22/design/charts` | Charts — needs the `recharts` and `motion` peers |
+| `@misoto22/design/diagrams` | Figures with routed edges |
+
+## You are working ON this package, in its repository
+
+The repository root `AGENTS.md` still applies in full — this file is additive,
+not a replacement, and the Harness rules there (`HAR-*`, `DESIGN-*`) govern this
+directory as much as any other. Read it first.
+
+What is specific to here:
+
+- **`dist/` is generated.** `dist/agent/**` included — it is written by
+  `scripts/emit-agent.mjs` at build time. Edit the source, then rebuild.
+- **`agent/catalog.mjs` is the one hand-written description** of what each
+  component IS: its group, summary, when to reach for it, accessibility
+  promises and keyboard contract. Everything mechanical is parsed out of
+  `src/**` by `scripts/extract-props.mjs`. `src/__tests__/catalog.test.ts`
+  fails when the two disagree.
+- **The skill is tested.** `src/__tests__/skill.test.ts` asserts every claim in
+  `skills/` against the extracted source, in both directions — an identifier the
+  rules tell an agent to write must exist, and one they say to avoid must not.
+  Renaming an export without updating the rules fails the build, on purpose.
+- **Gates:** `pnpm lint && pnpm typecheck && pnpm test && pnpm build`, from the
+  repository root.
+
+## On the web
+
+`https://ui.misoto22.com` — and `/llms.txt`, `/llms-full.txt`, and
+`/components/<slug>/llms.txt` for the same content without the CSS. Prefer the
+CLI above when the package is installed: it is version-locked and needs no
+network.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -20,16 +20,24 @@ import { Button, Field, Input } from '@misoto22/design'
 import '@misoto22/design/styles.css'
 ```
 
-`styles.css` is the whole compiled sheet — tokens, roles, motion and the
-vendored faces. An app that compiles its own Tailwind can take the portable
+`styles.css` is the whole compiled sheet — tokens, roles, themes, motion and
+the vendored faces. An app that compiles its own Tailwind can take the portable
 layers instead:
 
 ```tsx
-import '@misoto22/design/tokens.css'    // primitives
+import '@misoto22/design/tokens.css'    // primitives, plus data-mode and data-density
 import '@misoto22/design/semantic.css'  // roles
+import '@misoto22/design/themes.css'    // the other six theming axes
 import '@misoto22/design/keyframes.css' // motion
 ```
 
+All four, or the theming table below is a table of attributes that do nothing.
+`data-mode` and `data-density` are declared in `tokens.css`; every other axis
+lives only in `themes.css`, and an app that skips it writes `data-radius="sharp"`
+and gets no error, no warning, and no corner. Two more layers are opt-in rather
+than missing: `@misoto22/design/fonts.css` carries the vendored faces, and
+`@misoto22/design/article.css` styles long-form prose.
+
 Diagrams ship from their own specifier, so a page that renders a `Badge` does
 not pay for a routing engine:
 
@@ -44,7 +52,7 @@ authored for that tool renders here with no translation step.
 
 ## Theming
 
-Seven independent axes, each an attribute, each working on **any** element
+Eight independent axes, each an attribute, each working on **any** element
 rather than only on the root. An unset axis is the default.
 
 | Attribute | Values |
@@ -56,6 +64,7 @@ rather than only on the root. An unset axis is the default.
 | `data-type` | `grotesk` `bookish` |
 | `data-motion` | `still` `snappy` |
 | `data-density` | `compact` |
+| `data-chart-palette` | `chroma` |
 
 ```tsx
 <section data-surface="warm" data-radius="sharp">…</section>
@@ -100,12 +109,26 @@ conventions without being told each time:
 npx misoto22-design init --agents-md
 ```
 
-That writes `.claude/skills/misoto22-design/` and points your `AGENTS.md` at it.
+That writes the skill to `.agents/skills/` — the path Codex, Cursor, GitHub
+Copilot, Gemini CLI, OpenCode, Cline, Zed and Warp all read — and to
+`.claude/skills/` as well when the project already has a `.claude/`. Use
+`--agent agents` or `--agent claude` to pick one. For any other agent,
+[`skills`](https://github.com/vercel-labs/skills) covers around seventy of them
+and finds this one without any configuration:
+
+```bash
+npx skills add Misoto22/misoto22-design
+```
+
 The skill is progressive: its name and description are about 110 tokens and are
 all that sits in a session until something actually touches this package. The
 body is around 2,200, and the five rule files load one at a time, only when the
 work reaches them.
 
+An agent that explores `node_modules` by filename rather than by command finds
+`AGENTS.md`, `CLAUDE.md` and `llms.txt` at the package root. They are pointers
+to the above and nothing else, so they cannot go stale between releases.
+
 The names diverge from shadcn/ui in a handful of places that a model writing
 from habit gets wrong — `CardBody` not `CardContent`, `THead`/`TBody`/`TR`/`TH`/`TD`
 not `TableHeader`/…, and `title` as a prop on `DialogContent` rather than a
@@ -117,6 +140,28 @@ On the web, the same content is at
 [`/llms-full.txt`](https://ui.misoto22.com/llms-full.txt) (everything inline),
 and `/components/<slug>/llms.txt` (one component).
 
+### It tells you when you get it wrong
+
+Some ways of misusing a component fail silently — a `Field` whose child is a
+wrapper wires the label onto the box, an icon-only `Button` with no accessible
+name renders perfectly and is invisible to a screen reader. Development warns on
+those where it happens, with a stable code, the offending field and an
+imperative fix:
+
+```
+[@misoto22/design] FIELD_CONTROL_NOT_LABELLABLE
+  Field's child is a <div>, which cannot take a label — so the id,
+  aria-describedby, aria-required and aria-invalid were applied to it rather
+  than to a control.
+  field: children
+  fix:   Put the control itself directly inside Field, with no wrapper. For a
+         row of controls, give each its own Field and lay them out around it.
+  docs:  npx misoto22-design docs Field
+```
+
+Every call site is behind `process.env.NODE_ENV`, so none of it reaches a
+production bundle.
+
 ## Accessibility
 
 Every component is tested against `axe-core` best-practice rules, keyboard

package/bin/misoto22-design.mjs

@@ -31,9 +31,10 @@ const USAGE = `@misoto22/design ${version}
   misoto22-design docs --list         Every component, one line each.
   misoto22-design docs --installed    This package's version and what it ships.
                        [--json]
-  misoto22-design init [--agents-md]  Install the agent skill into this project
-                                      under .claude/skills/, and optionally
-                                      point AGENTS.md at it.
+  misoto22-design init                Install the agent skill into this project.
+                      [--agents-md]   Also point AGENTS.md at it.
+                      [--agent <id>]  Write only to one agent's directory:
+                                      "agents" (the shared path) or "claude".
 
 Docs on the web: https://ui.misoto22.com`
 
@@ -149,24 +150,69 @@ function docs(args) {
 const AGENTS_BLOCK = `
 ## @misoto22/design
 
-UI comes from \`@misoto22/design\`. Read \`.claude/skills/misoto22-design/SKILL.md\`
-before writing components against it — the names diverge from shadcn/ui in
-several places, and colour is never written as a raw class.
+UI comes from \`@misoto22/design\`. Read \`SKILL.md\` in the installed skill
+directory before writing components against it — the names diverge from
+shadcn/ui in several places, and colour is never written as a raw class.
 
 - One component in full: \`npx misoto22-design docs <Component>\`
 - Everything it ships: \`npx misoto22-design docs --installed\`
 `
 
+/**
+ * Where a skill goes, for the agents worth covering directly.
+ *
+ * `.agents/skills/` is the shared path — Codex, Cursor, GitHub Copilot, Gemini
+ * CLI, OpenCode, Cline, Zed, Warp, Amp and Replit all read it — and Claude Code
+ * is the one common agent with its own. Writing only to `.claude/` handed every
+ * other agent nothing, which was the bug.
+ *
+ * Deliberately two entries rather than the whole ecosystem. `npx skills` tracks
+ * around seventy directories and is one command away; a copy of that table kept
+ * here would be stale within a release, and this package's own rules are about
+ * not keeping copies of things that move.
+ */
+const AGENT_DIRS = {
+  agents: '.agents/skills',
+  claude: '.claude/skills',
+}
+
+/**
+ * Which directories to write, given the flags and what the project already has.
+ *
+ * The shared path is unconditional — it is the one an unknown agent is most
+ * likely to read. Claude's is added when the project already has a `.claude/`,
+ * so a project that does not use it does not grow a directory it will never
+ * open.
+ */
+function initTargets(args) {
+  const wanted = args[args.indexOf('--agent') + 1]
+  if (args.includes('--agent')) {
+    if (!wanted || !AGENT_DIRS[wanted]) {
+      fail(
+        `Unknown --agent "${wanted ?? ''}". Known: ${Object.keys(AGENT_DIRS).join(', ')}.\n` +
+          'For any other agent, `npx skills add Misoto22/misoto22-design` covers ~70 of them.',
+      )
+    }
+    return [AGENT_DIRS[wanted]]
+  }
+
+  const targets = [AGENT_DIRS.agents]
+  if (existsSync(join(process.cwd(), '.claude'))) targets.push(AGENT_DIRS.claude)
+  return targets
+}
+
 function init(args) {
-  const target = join(process.cwd(), '.claude', 'skills', 'misoto22-design')
   if (!existsSync(SKILL)) fail('This build has no skills/ directory.')
 
-  const existed = existsSync(target)
-  mkdirSync(dirname(target), { recursive: true })
-  cpSync(SKILL, target, { recursive: true })
-  process.stdout.write(
-    `${existed ? 'Updated' : 'Installed'} the skill at ${resolve(target)}\n`,
-  )
+  const written = []
+  for (const dir of initTargets(args)) {
+    const target = join(process.cwd(), dir, 'misoto22-design')
+    const existed = existsSync(target)
+    mkdirSync(dirname(target), { recursive: true })
+    cpSync(SKILL, target, { recursive: true })
+    written.push(`  ${existed ? 'updated' : 'installed'}  ${resolve(target)}`)
+  }
+  process.stdout.write(`${written.join('\n')}\n`)
 
   if (!args.includes('--agents-md')) {
     process.stdout.write('Pass --agents-md to also point AGENTS.md at it.\n')

package/dist/agent/Accordion.md

@@ -4,7 +4,7 @@ Disclosure rows that open in place.
 
 - Group: Navigation
 - Import: `import { Accordion } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/accordion/
 - Related: tabs
 
@@ -12,6 +12,29 @@ Disclosure rows that open in place.
 
 The marker is a plus, not a chevron: a plus says “this opens”, a chevron says “there is more below”.
 
+## Anatomy
+
+- **Row** (required) — AccordionItem — one hairline-ruled record, keyed by the value Radix opens and closes it by. The set is the root above it: type="single" with collapsible for an FAQ, type="multiple" for a stack of settings.
+- **Heading** (required) — Radix’s Accordion.Header, which is an <h3> and takes no level prop. Every row therefore adds an h3 to the document outline, wherever the accordion happens to sit.
+- **Trigger** (required) — The full-width button inside that heading: title against the start edge, marker against the end, py-4. It is also what names the open panel.
+- **Marker** (required) — A 16px plus, aria-hidden, rotating 45° into a minus when the row opens. The state it draws is carried for everyone else by aria-expanded on the trigger.
+- **Panel** — Radix’s Content — a role="region" labelled by its trigger, mounted only while open, overflow-hidden so its measured height can animate, with pb-4 pe-8 inside so the text stops short of the marker’s column. It carries data-m22-animated, so the open and close are dropped outright for a reader who asked for less motion.
+
+## Best practices
+
+### Do
+
+- Pass collapsible alongside type="single": without it there is no empty value to return to, so the first row the reader opens is a row they can never close again.
+- Key each item by something stable rather than by its position — Radix tracks the open row by value, so re-ordering or filtering the list leaves whatever now sits in that slot standing open.
+- Write the title as the whole question: it is the accessible name of the panel as well as of the trigger, so a row titled “More” opens a region called “More”.
+- Reach for type="multiple" when two rows have to be read against each other — single closes the one the reader was holding in order to open the one they wanted to compare it with.
+
+### Don’t
+
+- A closed row’s content is not in the DOM, so an FAQ built out of these is invisible to find-in-page and prints as a list of questions — anything that has to be searchable or printable belongs in the page.
+- The trigger is fixed at h3 by Radix’s header, so an accordion under an <h3> lists its rows as that heading’s siblings and the outline goes flat exactly where it should have nested.
+- The panel is overflow-hidden — that is what lets the open height animate — so anything inside that must escape the row’s box has to portal out of it; a menu that renders in place is cut off at the row’s edge.
+
 ## Keyboard
 
 - Tab — Moves between rows.

package/dist/agent/Alert.md

@@ -4,7 +4,7 @@ A message about the page, in place.
 
 - Group: Feedback
 - Import: `import { Alert } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/alert/
 - Related: toast, error-state
 
@@ -12,6 +12,28 @@ A message about the page, in place.
 
 Something the reader needs to see and may need to act on. Something they only need to notice is a Toast.
 
+## Anatomy
+
+- **Region** (required) — The container, carrying the role and the aria-live the tone chooses, plus the tone’s ground. It is not focusable and it is not a landmark, so it exists for the reader who is already there and for the announcement.
+- **Mark** — The tone’s lucide icon at 18px — Info, CheckCircle2, AlertTriangle or XCircle — aria-hidden, so it doubles the colour for sighted readers only. hideIcon removes it.
+- **Title** — title, as a medium-weight paragraph in --ink. A p and not a heading, so it never appears in a screen reader’s heading list.
+- **Body** — children, in --ink-2 at relaxed leading, offset from the title only when there is a title to offset from.
+- **Action** — action, below the body and inside the region — so its label is read out with the message rather than being something the reader has to go looking for.
+
+## Best practices
+
+### Do
+
+- Mount the Alert when there is something to say and unmount it when there is not. A region kept permanently in the page announces only when its words change, so a second failed submit carrying the same message is announced to nobody.
+- Move focus after a failed submit — to the Alert or to the field it names. The component announces and then stays put, so a keyboard reader hears the error from wherever they were standing and has no way back to it.
+- Put the retry, the link or the escape in action rather than describing it in the prose. It sits inside the live region, which is the difference between the announcement telling the reader what to do and merely telling them something is wrong.
+
+### Don’t
+
+- hideIcon takes away one of the two things that double the colour, and the tinted grounds are 13–16% alpha over paper. With the mark gone the severity is carried by a wash the reader may not resolve at all, so the words have to say it outright.
+- info is the default and the only tone with a border and no tint — --paper-2 inside a --rule-2 hairline, which is a card. An Alert written without tone therefore looks like page furniture rather than like a notice.
+- Do not stack alerts as a running log. Each one is its own live region, so five on a page are five announcements competing for the same speech queue, and a danger among them is assertive enough to cut off the four that explain it.
+
 ## Accessibility
 
 - danger is role="alert" and interrupts; the other three are role="status" and wait for a pause.

package/dist/agent/AppShell.md

@@ -4,18 +4,46 @@ Two columns on a desktop, a drawer on a phone.
 
 - Group: Surfaces
 - Import: `import { AppShell } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/app-shell/
 - Related: nav-item
 
+## Anatomy
+
+- **Frame** (required) — The root: min-h-svh on --paper, one column on a phone and a 15rem sidebar beside a 1fr content column from md up. It is the grid and nothing else — no padding, no measure.
+- **Sidebar** (required) — An <aside> named by sidebarLabel, 15rem wide. A static grid column on a desktop; on a phone a fixed drawer that slides in from the edge reading STARTS at, so it comes from the right in a right-to-left document.
+- **Brand** — brand, in a 3.5rem row at the top of the sidebar above a hairline — the same height as the topbar, so the two rules meet across the column boundary. Omit it and the nav starts at the top and that line is gone.
+- **Nav** (required) — A <nav> named by navLabel, “Primary” by default, holding the sidebar prop. It is the part that scrolls, with scroll-slim, so a list that outgrows the column moves under a brand that stays put.
+- **Topbar** (required) — A sticky 3.5rem header at --paper/85 with a backdrop blur and a hairline under it, holding the toggle and then topbar. It is rendered whether or not you pass one.
+- **Drawer toggle** — A 44px button, phone-only, swapping Menu for X and carrying aria-expanded plus aria-controls pointing at the sidebar. Its only name is openLabel or closeLabel.
+- **Scrim** — A full-screen <button> named by closeLabel, mounted only while the drawer is open and hidden from md up.
+- **Content well** (required) — contentAs — a <main> by default — centred at --w-page with --page-pad either side and py-8. The measure and the page padding are the shell’s, so a child that adds its own puts a second measure inside the first.
+
+## Best practices
+
+### Do
+
+- Pass contentAs="div" for a shell rendered inside another page — a documentation preview, a screenshot harness. A document may hold exactly one main, and the second one leaves assistive tech unable to answer “where is the content”.
+- Name both landmarks when a page could hold two shells: sidebarLabel and navLabel are the only way one complementary is told from another, and the only way a non-English app gets landmark names its readers can read.
+- Translate openLabel and closeLabel with everything else — the toggle holds an icon and no text, so those strings are its entire accessible name on every page of the app.
+- Put the whole sidebar in the sidebar prop and let the nav scroll it: build the column yourself with the brand inside it and a long list carries the brand off the top of the screen with it.
+
+### Don’t
+
+- Do not treat the closed drawer as unmounted: below md it is translated off-screen and marked inert, not removed, so everything inside it still renders and still runs its effects — a nav item that measures itself measures a box nobody can see.
+- Do not assume no topbar means no bar: the header renders regardless, so a shell with nothing to put up there still costs 3.5rem and a rule across the page.
+- Do not wrap the children in your own max-width and page padding — the well already applies both, and the content ends up in the middle of the middle.
+
 ## Accessibility
 
 - The drawer closes on Escape as well as on the scrim, so a keyboard user is not stranded inside it.
 - The scrim is a <button>, because a div with an onClick is neither reachable nor announced.
+- Below md the closed drawer carries inert, so its links are out of the tab order and out of the accessibility tree rather than merely off screen. Above md it never is: there the sidebar is the page’s navigation column.
+- Both ways out return focus to the toggle. Focus left inside an inert subtree is focus the browser throws away, and the scrim is worse — it is the focused element and it unmounts.
 
 ## AppShell
 
-Two columns on a desktop, one column and a drawer on a phone. The drawer closes on Escape as well as on the scrim, because a drawer that only closes by tapping outside it strands a keyboard user inside a menu they cannot leave. The scrim is a `<button>` for the same reason — a `<div>` with an `onClick` is not reachable by keyboard and not announced as anything.
+Two columns on a desktop, one column and a drawer on a phone. The drawer closes on Escape as well as on the scrim, because a drawer that only closes by tapping outside it strands a keyboard user inside a menu they cannot leave. The scrim is a `<button>` for the same reason — a `<div>` with an `onClick` is not reachable by keyboard and not announced as anything. Below `md` the closed drawer is `inert`. Sliding it off-screen is a visual state and nothing more: without that attribute every link in it stays focusable and stays in the accessibility tree, so Tab from the toggle walks into a menu nobody can see. Closing it also returns focus to the toggle, because the element focus was on is the element that just left.
 
 ### Props
 

package/dist/agent/ArchitectureFigure.md

@@ -4,7 +4,7 @@ A component map: services, datastores, trust boundaries, and what talks to what.
 
 - Group: Diagrams
 - Import: `import { ArchitectureFigure } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/architecture-figure/
 - Related: dataflow-figure, diagram, diagram-canvas
 
@@ -12,6 +12,29 @@ A component map: services, datastores, trust boundaries, and what talks to what.
 
 Reach for it when the question is "what talks to what". If the question is "in what order", that is a workflow or a sequence; if it is "what is in this arrow", that is a data flow.
 
+## Anatomy
+
+- **Figure shell** (required) — The frame all five figures sit in — a serif title, the scrolling paper surface, the role="img" svg. What a map hands it is the relationship list: every connection published as "CloudFront → API: HTTPS", which is the sentence this diagram type exists to make.
+- **Grid** (required) — What row and col index into: a 184 × 72 cell with 64 and 76 unit gutters, overridable per figure through spec.layout — where cellW is the pitch AND the width of the plates drawn at it. A component declaring neither row nor col flows into the next free cell, wrapping at layout.cols; pos replaces the grid entirely and puts the box at an absolute coordinate.
+- **Component plate** (required) — One box per component: a sigil and an eyebrow on the top line, the name at reading size, the sublabel in mono under it. The eyebrow prints the component’s own tag when it has one and the kind word otherwise, and the box grows past a declared height rather than printing through its own bottom rule.
+- **Boundary frame** — A labelled rule around the union of the boxes its wraps names, inflated by pad — 28 units by default. Solid for a region, dashed for a security-group, so where a thing runs and what may reach it are two different lines before either label is read.
+- **Connections** — Lines that leave and arrive perpendicular to a face, spread across that face when several share it, each with its wording on a mask that punches the line out from under itself.
+- **Key** — The kinds actually drawn, each shown with the same sigil the plates carry. legend="all" names all seven instead; legend="hidden" prints none.
+
+## Best practices
+
+### Do
+
+- Build a new spec object when something changes. The model is memoised on the spec’s identity, so mutating spec.components in place leaves the same reference and the figure goes on drawing the picture it was first given — development prints DIAGRAM_SPEC_MUTATED when it catches that, and a production build prints nothing and still draws the old picture.
+- Place both ends with pos when a connection carries a hand-tuned via, channelX or channelY. Those are honoured only when both endpoints were placed absolutely — on the grid they are coordinates in a space this renderer did not choose, so a route between two row/col components is dropped and re-routed.
+- Drive a guided reading yourself. meta.views typechecks and no renderer reads it — a chapter is a control rather than a layout — so the chapter’s focus ids have to arrive as activeIds, which is what dims everything else and adds the "n highlighted" status line.
+- Leave row and col off the components you have no opinion about. They flow into the next free cell in declaration order, wrapping at layout.cols and stepping around whatever the placed ones claimed — a component declaring neither used to mean row 0, column 0, which is one plate with the rest of them underneath it.
+
+### Don’t
+
+- Two components on one cell are still two plates at one coordinate, one drawn over the other: there is no second place to put the second plate. Development prints DIAGRAM_CELL_COLLISION naming both, which is the only signal — the picture is identical either way.
+- A boundary silently shrinks to the components it can find. A wraps id no component declares is skipped, and a boundary whose ids are all missing draws no frame at all — a trust boundary can leave the picture while the specification still claims it.
+
 ## Accessibility
 
 - The <svg> is role="img" with a name, so a screen reader announces a picture instead of walking two hundred <text> nodes in drawing order.
@@ -20,7 +43,7 @@ Reach for it when the question is "what talks to what". If the question is "in w
 
 ## ArchitectureFigure
 
-A component map: services, datastores, boundaries, and what talks to what. Takes the same JSON an archify `architecture` specification carries — `components`, `boundaries`, `connections` — and draws it in this system's own terms: paper plates on a hairline, one reversed plate for the component the diagram is about, and seven drawn sigils where archify uses seven hues. IT RENDERS ON A SERVER because every position is already in the specification. A component gives a `row` and a `col` into a grid whose cell size is either declared or defaulted, or it gives an absolute `pos` — nothing here is solved for, relaxed, or measured. So the markup is a pure function of the input, it is identical on the server and in the browser, and there is no layout shift on hydration because there is no layout to do. BOUNDARIES ARE DRAWN FIRST, AND DRAWN DIFFERENTLY. A `region` is where something RUNS — a VPC, a zone, a cluster — and is a solid frame. A `security-group` is what may REACH it, and is dashed. That is not decoration: an infrastructure diagram is very often read for exactly one of those two questions, and a reader should be able to tell which line answers which without reading either label.
+A component map: services, datastores, boundaries, and what talks to what. Takes the same JSON an archify `architecture` specification carries — `components`, `boundaries`, `connections` — and draws it in this system's own terms: paper plates on a hairline, one reversed plate for the component the diagram is about, and seven drawn sigils where archify uses seven hues. IT RENDERS ON A SERVER because every position is already in the specification. A component gives a `row` and a `col` into a grid whose cell size is either declared or defaulted, or it gives an absolute `pos` — nothing here is solved for, relaxed, or measured. So the markup is a pure function of the input, it is identical on the server and in the browser, and there is no layout shift on hydration because there is no layout to do. A component that declares NEITHER flows: it takes the next free cell in declaration order, wrapping at `layout.cols`. That is still arithmetic on numbers the specification carries rather than a solver — and the alternative was every unplaced component defaulting to row 0, column 0 and stacking into one plate. BOUNDARIES ARE DRAWN FIRST, AND DRAWN DIFFERENTLY. A `region` is where something RUNS — a VPC, a zone, a cluster — and is a solid frame. A `security-group` is what may REACH it, and is dashed. That is not decoration: an infrastructure diagram is very often read for exactly one of those two questions, and a reader should be able to tell which line answers which without reading either label.
 
 ### Props
 

package/dist/agent/AreaChart.md

@@ -4,7 +4,7 @@ A filled series over a continuous axis, where the area means something.
 
 - Group: Charts
 - Import: `import { AreaChart } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/area-chart/
 - Related: line-chart, bar-chart, composed-chart
 
@@ -12,6 +12,30 @@ A filled series over a continuous axis, where the area means something.
 
 Reading one magnitude over time. Comparing several series against each other is a LineChart — four translucent fills stacked on each other answer neither question.
 
+## Anatomy
+
+- **Figure frame** (required) — The <figure> ChartFigure draws, named through aria-labelledby rather than left to the figcaption, because deriving a name from a <figcaption> resolves in only some screen readers. The caption holds title and description together and is sr-only until showTitle is set, so a caveat written into description is announced and never printed.
+- **Plot** (required) — ChartContainer: a 16:9 box floored at 13rem and capped at 26rem, and the one place Recharts’ hard-coded #ccc axis and grid strokes are re-pointed at --chart-grid and --chart-axis.
+- **Areas** (required) — <AreaChart.Area>, one per series. Each generates its own id and scopes its gradient, its texture pattern and its reveal mask under it, so six variants share a plot without one overwriting another’s definitions.
+- **Brush strip** — <AreaChart.Brush>, rendered in the container’s footer rather than inside the SVG. Both handles are role="slider" with aria-valuetext naming the row they sit on, so the window is reachable by arrow key.
+- **Toolbar** — <AreaChart.Toolbar>, a role="group" row of at most five 44px icon buttons above the plot. Composing it also switches the plot’s own wheel, drag and keyboard zoom on, and the two drive one window rather than two.
+- **Hidden data table** — An sr-only <table> built from the FULL data rather than the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.
+
+## Best practices
+
+### Do
+
+- Stack only quantities that genuinely add up. Under stackType="stacked" a band’s HEIGHT is its own value but its POSITION is the sum of everything under it, so stacking four independent rates draws a running total nobody measured.
+- Reach for stackType="expanded" when the reading is share rather than volume: it sets Recharts’ expand offset and <AreaChart.YAxis> swaps in percentTick on its own, so the axis reads 0% to 100% without a formatter at the call site. A tickFormatter of your own still wins — the axis defers to it rather than dropping it, which it used to do without a word.
+- Vary variant before the ramp on a two-area chart. The six fills are the primary encoding in the monochrome default, and under forced colours every --series-* token resolves to CanvasText — at which point the texture is the only thing left separating two areas.
+- Pass xDataKey. It is the rowKey of the hidden table, and without it the table renders no row-header column at all: a screen reader gets a column of numbers with no month beside them.
+
+### Don’t
+
+- Four translucent fills over each other is this form’s failure mode — the third area is read through two layers of --chart-fill and its own height stops being recoverable. Several series compared against each other is a LineChart, where nothing occludes anything.
+- connectNulls defaults to false for a reason: turned on, a gap in the data is drawn as a straight segment indistinguishable from a measured flat period. Set it only where the gap is a rendering artefact rather than a missing observation.
+- A single row draws nothing. One point has no segment to fill, dot is false unless <AreaChart.Dot> is composed, and the empty state does not fire because there IS a row — so the axes render over a blank plot.
+
 ## Accessibility
 
 - title is required and becomes the figure’s accessible name, printed or not.
@@ -41,7 +65,8 @@ A filled series over a category axis — the shape for a magnitude that is conti
 - `curveType` — `ChartCurveType` default `'linear'`. The curve every `<AreaChart.Area>` inherits.
 - `animationType` — `ChartRevealType` default `'forward'`. The intro wipe every `<AreaChart.Area>` inherits.
 - `stackType` — `AreaStackType` default `'default'`. How several marks combine: side by side, stacked, or normalised to 100%.
-- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render. Selection dims every other series.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
+- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
 - `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
 - `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
 - `loadingPoints` — `number`. How many points the skeleton draws.

package/dist/agent/Article.md

@@ -4,7 +4,7 @@ The long-form reading surface — everything a Markdown pipeline emits, in this
 
 - Group: Surfaces
 - Import: `import { Article } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/article/
 - Related: diagram, card
 
@@ -12,15 +12,38 @@ The long-form reading surface — everything a Markdown pipeline emits, in this
 
 A post, a changelog entry, a document. Not for interface copy: a paragraph inside a card is a paragraph, and this is a whole reading column with its own rhythm.
 
+## Anatomy
+
+- **The column** (required) — Whatever as names — article, section or div — tagged data-m22-article, which is what every rule in article.css is scoped to. A 46rem measure and no inline margins of its own, so it sits wherever its parent puts it.
+- **Blocks** (required) — The DIRECT children, and where the rhythm lives: air above every block, more above a heading, none on the first. A block one level deeper is outside that rule and outside its spacing.
+- **Rendered HTML** — html, written with dangerouslySetInnerHTML. Present it and children are not rendered at all — the trust boundary is the pipeline that produced the string, because there is nothing here that will catch a script tag on the way through.
+- **Lead** — p.lead — the standfirst, at --fs-item in full --ink. Marked by the author or the pipeline, never inferred: the stylesheet does not promote whatever happened to come first.
+- **Wide blocks** — figure, table and .m22-wide are the three things allowed out of the measure, because a six-column table and an image with a subject in it are both unreadable at 46rem.
+
+## Best practices
+
+### Do
+
+- Centre it yourself. It sets a measure, not a layout — with no auto margins it sits against the start edge of a wide page until a parent centres it.
+- Keep every block a direct child: the rhythm is a child combinator, so a <div> wrapped around a run of paragraphs — even a display:contents one, which removes the box but not the node — costs all of them their spacing.
+- Have the pipeline wrap a wide table in .m22-table-scroll. A table is allowed out of the measure and has nothing of its own to scroll inside, so eight columns push the whole page sideways instead.
+- Sanitise before the string arrives, and mark the boundary where you do it: html is set as innerHTML, so a CMS field that reaches this prop unsanitised is stored XSS with a reading measure.
+
+### Don’t
+
+- Do not pass html and children together — html wins and the children are dropped. It says so in development now, but html="" is still html, so a pipeline that rendered nothing takes the children down with it. A post that mixes prose with components is two Articles in order, not one holding both.
+- Do not count on a nested component’s utilities holding inside one: article.css is imported unlayered and beats Tailwind’s @layer utilities whatever the specificity, so any property these rules also set is overridden. A component that must keep one needs an inline style, or a tag the stylesheet does not reach.
+- Do not nest six heading levels: h5 and h6 are set as mono uppercase 11px eyebrows rather than as smaller headings, so a document loses its type hierarchy at exactly the depth that needed one.
+
 ## Accessibility
 
 - An <article> by default, so the piece is a landmark a reader can jump to.
 - Every heading carries scroll-margin, so an anchored link does not park the heading under a fixed masthead.
-- The styles are element selectors at low specificity, so a component dropped inside keeps its own.
+- The styles are imported unlayered, so inside an article they beat a component’s layered utilities — which is what lets a Markdown paragraph give its margin up to the article’s rhythm.
 
 ## Article
 
-The long-form reading surface. Everything a Markdown pipeline can emit — headings, prose, lists, tables, quotations, code, figures, footnotes, MathML — set in this system's type, colour and rules. The styles live in `article.css` rather than in a class string, because the input is not JSX: there is no component to hang a class on when the markup arrived as a string, so the contract has to be the element names themselves. That file is published on its own as `@misoto22/design/article.css`, so a site with its own Markdown pipeline can take the reading surface without taking the components — which is the case this exists for. Three sites hand-rolling a prose stylesheet is three prose stylesheets that drift. Composable either way: pass `html` for a rendered string, or children for real elements. A post that mixes the two — prose with a `Diagram` dropped into the middle — renders its blocks in order and gives each one an `Article`; a component inside keeps its own classes, because every rule in the layer is a bare element selector that a utility outranks.
+The long-form reading surface. Everything a Markdown pipeline can emit — headings, prose, lists, tables, quotations, code, figures, footnotes, MathML — set in this system's type, colour and rules. The styles live in `article.css` rather than in a class string, because the input is not JSX: there is no component to hang a class on when the markup arrived as a string, so the contract has to be the element names themselves. That file is published on its own as `@misoto22/design/article.css`, so a site with its own Markdown pipeline can take the reading surface without taking the components — which is the case this exists for. Three sites hand-rolling a prose stylesheet is three prose stylesheets that drift. Composable either way: pass `html` for a rendered string, or children for real elements — one or the other, never both. `html` wins when both arrive, and says so in development: `html=""` is still `html`, which made losing a page of children a thing that could happen without a word. A post that mixes the two — prose with a `Diagram` dropped into the middle — renders its blocks in order and gives each one an `Article`. Inside one, these rules BEAT a component's utilities: `article.css` is imported unlayered while Tailwind's utilities sit in `@layer utilities`, and an unlayered rule wins over a layered one whatever either one's specificity is. That is the mechanism rather than an accident — it is what lets a `Markdown` paragraph, a `Text` carrying `m-0`, give its margin up to the article's rhythm. A component that has to hold a property inside an article needs an inline style, not a class.
 
 ### Props