@misoto22/design 0.3.1 → 0.6.0

package/README.md

@@ -0,0 +1,124 @@
+# @misoto22/design
+
+A monochrome design system for software, writing and photography: portable CSS
+tokens and accessible React 19 primitives. Paper ground, near-black mark, and
+status is the only chroma in the file.
+
+Components ship compiled — you import them, you do not copy them into your
+project.
+
+**[ui.misoto22.com](https://ui.misoto22.com)** · [Changelog](./CHANGELOG.md)
+
+## Install
+
+```bash
+npm install @misoto22/design
+```
+
+```tsx
+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
+layers instead:
+
+```tsx
+import '@misoto22/design/tokens.css'    // primitives
+import '@misoto22/design/semantic.css'  // roles
+import '@misoto22/design/keyframes.css' // motion
+```
+
+## Theming
+
+Seven independent axes, each an attribute, each working on **any** element
+rather than only on the root. An unset axis is the default.
+
+| Attribute | Values |
+| --- | --- |
+| `data-mode` | `light` `dark` |
+| `data-surface` | `warm` `cool` `glass` |
+| `data-radius` | `sharp` `round` |
+| `data-rules` | `quiet` `firm` |
+| `data-type` | `grotesk` `bookish` |
+| `data-motion` | `still` `snappy` |
+| `data-density` | `compact` |
+
+```tsx
+<section data-surface="warm" data-radius="sharp">…</section>
+```
+
+No component reads any of them, and none of them introduces a token. To
+re-accent the system, re-point one custom property:
+
+```css
+:root { --accent: var(--ok); }
+```
+
+## For agents
+
+This package is documented for the reader that installed it, not only for the
+one that can open a browser — and the two need different things. Everything
+below is generated from the source in this same tarball, so it describes the
+version you actually have rather than whatever the website shipped last.
+
+**One component, in full** — every prop with its type and default, the exported
+unions, the keyboard contract, the accessibility promises, the examples:
+
+```bash
+npx misoto22-design docs Button
+```
+
+The median component is about 500 tokens. It resolves parts and types too, so
+`docs CardBody`, `docs TH` and `docs ButtonVariant` all land on the right file —
+useful when an import just failed.
+
+**What is installed here**, as a few hundred tokens rather than fifty prop
+tables:
+
+```bash
+npx misoto22-design docs --installed
+```
+
+**Install the skill** into your project, so a coding agent picks up the
+conventions without being told each time:
+
+```bash
+npx misoto22-design init --agents-md
+```
+
+That writes `.claude/skills/misoto22-design/` and points your `AGENTS.md` at it.
+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.
+
+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
+`DialogTitle` child. The skill leads with that table, and
+`src/__tests__/skill.test.ts` fails the build if any of it stops being true.
+
+On the web, the same content is at
+[`/llms.txt`](https://ui.misoto22.com/llms.txt) (index),
+[`/llms-full.txt`](https://ui.misoto22.com/llms-full.txt) (everything inline),
+and `/components/<slug>/llms.txt` (one component).
+
+## Accessibility
+
+Every component is tested against `axe-core` best-practice rules, keyboard
+contracts are asserted key by key, and a prop that is required for
+accessibility is required in the type — `Table.caption`, `Progress.label`,
+`Avatar.alt`, `FloatingIconButton.label`. If it can be forgotten, it will be.
+
+Logical properties throughout, so the system is RTL-correct; motion is gated
+behind `prefers-reduced-motion`.
+
+## Requirements
+
+React 19, Node 24+. ESM only.
+
+## Licence
+
+MIT © Henry Chen

package/bin/misoto22-design.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * The package's own documentation, for the reader that installed it.
+ *
+ * A website is the wrong source for an agent writing against a pinned version:
+ * it documents whatever shipped last, the agent is holding whatever is in
+ * `node_modules`, and neither side can see the disagreement. Everything printed
+ * here is generated at build time from the source in the same tarball, so the
+ * answer is always about the version actually installed.
+ *
+ * It is also the cheap half of the deal. `docs --installed` is a few hundred
+ * tokens and says what exists; `docs <Component>` is under a thousand and says
+ * everything about one of them. The alternative an agent reaches for otherwise
+ * is the whole of `llms-full.txt`, which is fifty times that and mostly about
+ * components it is not using.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const AGENT = join(ROOT, 'dist', 'agent')
+const SKILL = join(ROOT, 'skills', 'misoto22-design')
+
+const { version } = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+
+const USAGE = `@misoto22/design ${version}
+
+  misoto22-design docs <Component>    One component, in full — props, types,
+                                      keyboard, accessibility, examples.
+  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.
+
+Docs on the web: https://ui.misoto22.com`
+
+function fail(message) {
+  process.stderr.write(`${message}\n`)
+  process.exit(1)
+}
+
+/** The emitted docs are a build artifact; a source checkout may not have them. */
+function requireBuilt() {
+  if (!existsSync(AGENT)) {
+    fail(
+      'No generated docs found. This package ships them in dist/agent/;\n' +
+        'in a source checkout, run `pnpm build:agent` first.',
+    )
+  }
+}
+
+function componentNames() {
+  return readdirSync(AGENT)
+    .filter((file) => file.endsWith('.md') && file !== 'index.md')
+    .map((file) => file.replace(/\.md$/, ''))
+    .sort()
+}
+
+function catalog() {
+  return JSON.parse(readFileSync(join(AGENT, 'catalog.json'), 'utf8'))
+}
+
+/**
+ * What a skill injects at the top of a session: the version in this project and
+ * the names it can ask about. Deliberately names-only — the point is that the
+ * agent then fetches the one component it needs, rather than being handed all
+ * fifty-two prop tables it does not.
+ */
+function installed(asJson) {
+  requireBuilt()
+  const { groups, components } = catalog()
+  if (asJson) {
+    const byGroup = Object.fromEntries(
+      groups
+        .map((group) => [group, components.filter((c) => c.group === group).map((c) => c.name)])
+        .filter(([, names]) => names.length > 0),
+    )
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          package: '@misoto22/design',
+          version,
+          components: byGroup,
+          styles: [
+            '@misoto22/design/styles.css',
+            '@misoto22/design/tokens.css',
+            '@misoto22/design/semantic.css',
+            '@misoto22/design/keyframes.css',
+          ],
+          detail: 'npx misoto22-design docs <Component>',
+        },
+        null,
+        2,
+      )}\n`,
+    )
+    return
+  }
+  const lines = [`@misoto22/design ${version} — ${components.length} components`, '']
+  for (const group of groups) {
+    const names = components.filter((c) => c.group === group).map((c) => c.name)
+    if (names.length > 0) lines.push(`${group}: ${names.join(', ')}`)
+  }
+  lines.push('', 'One in full: npx misoto22-design docs <Component>')
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+function docs(args) {
+  if (args.includes('--installed')) return installed(args.includes('--json'))
+  requireBuilt()
+  if (args.includes('--list')) {
+    process.stdout.write(readFileSync(join(AGENT, 'index.md'), 'utf8'))
+    return
+  }
+
+  const name = args.find((arg) => !arg.startsWith('-'))
+  if (!name) fail(`Which component? Try one of:\n\n  ${componentNames().join(', ')}`)
+
+  // What the caller holds is usually the identifier it just failed to import —
+  // a part (`CardBody`, `TH`) or a type (`ButtonVariant`) rather than the
+  // component that owns it. Resolve those rather than making it guess again.
+  const owner = catalog().exports?.[name]
+  const file = join(AGENT, `${owner ?? name}.md`)
+  if (existsSync(file)) {
+    if (owner && owner !== name) {
+      process.stderr.write(`\`${name}\` is part of ${owner}.\n`)
+    }
+    process.stdout.write(readFileSync(file, 'utf8'))
+    return
+  }
+
+  // A miss is usually a near miss — a habit from another library, or a part
+  // name rather than the component that owns it. Say what exists instead.
+  const wanted = name.toLowerCase()
+  const near = componentNames().filter(
+    (candidate) =>
+      candidate.toLowerCase().startsWith(wanted.slice(0, 3)) ||
+      wanted.startsWith(candidate.toLowerCase()),
+  )
+  fail(
+    near.length > 0
+      ? `No component named "${name}". Did you mean: ${near.join(', ')}?`
+      : `No component named "${name}". Run \`misoto22-design docs --list\` for all ${componentNames().length}.`,
+  )
+}
+
+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.
+
+- One component in full: \`npx misoto22-design docs <Component>\`
+- Everything it ships: \`npx misoto22-design docs --installed\`
+`
+
+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`,
+  )
+
+  if (!args.includes('--agents-md')) {
+    process.stdout.write('Pass --agents-md to also point AGENTS.md at it.\n')
+    return
+  }
+
+  const agentsFile = join(process.cwd(), 'AGENTS.md')
+  const current = existsSync(agentsFile) ? readFileSync(agentsFile, 'utf8') : '# AGENTS.md\n'
+  if (current.includes('@misoto22/design')) {
+    process.stdout.write('AGENTS.md already mentions the package; left alone.\n')
+    return
+  }
+  writeFileSync(agentsFile, `${current.trimEnd()}\n${AGENTS_BLOCK}`)
+  process.stdout.write(`Appended a section to ${resolve(agentsFile)}\n`)
+}
+
+const [command, ...args] = process.argv.slice(2)
+switch (command) {
+  case 'docs':
+    docs(args)
+    break
+  case 'init':
+    init(args)
+    break
+  case undefined:
+  case '--help':
+  case '-h':
+    process.stdout.write(`${USAGE}\n`)
+    break
+  case '--version':
+  case '-v':
+    process.stdout.write(`${version}\n`)
+    break
+  default:
+    fail(`Unknown command "${command}".\n\n${USAGE}`)
+}

package/dist/agent/Accordion.md

@@ -0,0 +1,41 @@
+# Accordion
+
+Disclosure rows that open in place.
+
+- Group: Navigation
+- Import: `import { Accordion } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/accordion/
+- Related: tabs
+
+## When to reach for it
+
+The marker is a plus, not a chevron: a plus says “this opens”, a chevron says “there is more below”.
+
+## Keyboard
+
+- Tab — Moves between rows.
+- Enter / Space — Opens or closes the focused row.
+
+## Accordion
+
+Radix root, re-exported. Pass `type="single" collapsible` for an FAQ and `type="multiple"` for a settings stack; Radix's own discriminated union then types `value` correctly for each.
+
+## AccordionItem
+
+One disclosure row: a hairline-ruled trigger and its panel. The marker is a plus that rotates into a minus, not a chevron. A chevron says "there is more below"; a plus says "this opens" — and in a stack of rows the difference decides whether the reader expects navigation or expansion. The panel animates on Radix's own `--radix-accordion-content-height`, so it opens to its real height without measuring anything at the call site.
+
+### Props
+
+- `title` (required) — `ReactNode`. The row's summary — what the reader clicks. Named `title` rather than inherited from the DOM attribute of the same name, which is a tooltip.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `Omit<ComponentProps<typeof AccordionPrimitive.Item>, 'children' | 'title'>`.
+
+## Examples
+
+```tsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="ship" title="How do I ship it?">Push to main.</AccordionItem>
+</Accordion>
+```

package/dist/agent/Alert.md

@@ -0,0 +1,42 @@
+# Alert
+
+A message about the page, in place.
+
+- Group: Feedback
+- Import: `import { Alert } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/alert/
+- Related: toast, error-state
+
+## When to reach for it
+
+Something the reader needs to see and may need to act on. Something they only need to notice is a Toast.
+
+## Accessibility
+
+- danger is role="alert" and interrupts; the other three are role="status" and wait for a pause.
+- Colour is doubled by an icon and by the words.
+
+## Alert
+
+A message about the page, in place. Carries `role="alert"` for the danger tone and `role="status"` for the rest, which is the difference between interrupting the reader and waiting for a pause. Getting that backwards is the usual accessibility failure here: a "saved" toast that talks over someone mid-sentence, or a payment error that is never announced at all. The tone is the message's SEVERITY, not its decoration. Colour is doubled by an icon and by the words, so the meaning survives both monochrome printing and colour-blindness.
+
+### Props
+
+- `tone` — `AlertTone` default `'info'`.
+- `title` — `ReactNode`.
+- `children` — `ReactNode`.
+- `action` — `ReactNode`. Optional action — a retry, a link to the settings that fix this.
+- `hideIcon` — `boolean` default `false`. Hides the leading icon for a dense inline notice.
+
+Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## Types
+
+- `AlertTone` = `'info' | 'success' | 'warning' | 'danger'`
+
+## Examples
+
+```tsx
+<Alert tone="danger" title="Upload failed">The file exceeds 25 MB.</Alert>
+```

package/dist/agent/AppShell.md

@@ -0,0 +1,40 @@
+# AppShell
+
+Two columns on a desktop, a drawer on a phone.
+
+- Group: Surfaces
+- Import: `import { AppShell } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/app-shell/
+- Related: nav-item
+
+## 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.
+
+## 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.
+
+### Props
+
+- `sidebar` (required) — `ReactNode`. Navigation content for the sidebar (e.g. a stack of `NavItem`s).
+- `topbar` — `ReactNode`. Optional content for the sticky topbar, laid out after the mobile toggle.
+- `brand` — `ReactNode`. Optional brand lockup pinned to the top of the sidebar.
+- `contentAs` — `'main' | 'div'`. Which element the content well renders as. `main` is right for the shell of an application, and is the default. A document may contain exactly one `main` landmark, so an AppShell rendered INSIDE another page — a preview on a documentation site, a screenshot harness — must pass `div`, or the page has two and assistive tech can no longer answer "where is the content".
+- `sidebarLabel` — `string` default `'Sidebar'`. Names the sidebar landmark. Two `complementary` landmarks with the same name cannot be told apart, and a shell rendered inside another page — a preview, a screenshot harness — makes exactly that pair. It is also the only way a non-English app gets a landmark name its readers can read.
+- `navLabel` — `string` default `'Primary'`. Names the navigation landmark inside the sidebar.
+- `openLabel` — `string` default `'Open navigation'`. The drawer toggle, closed and open.
+- `closeLabel` — `string` default `'Close navigation'`.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<AppShell brand={<Wordmark />} sidebar={<NavItem href="/">Home</NavItem>}>
+  <Card>…</Card>
+</AppShell>
+```

package/dist/agent/AreaChart.md

@@ -0,0 +1,68 @@
+# AreaChart
+
+A filled series over a continuous axis, where the area means something.
+
+- Group: Charts
+- Import: `import { AreaChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/area-chart/
+- Related: line-chart, bar-chart, composed-chart
+
+## When to reach for it
+
+Reading one magnitude over time. Comparing several series against each other is a LineChart — four translucent fills stacked on each other answer neither question.
+
+## Accessibility
+
+- title is required and becomes the figure’s accessible name, printed or not.
+- The rows are rendered again as a visually hidden table, so the numbers are reachable rather than only drawn. hideDataTable opts out when the page already prints them.
+- Six fill variants exist because in the monochrome default TEXTURE is the primary carrier of identity and the grey ramp is the second — which is also what keeps two series apart in greyscale print and under forced colours.
+- The intro reveal is a per-frame SVG mask and is dropped entirely under prefers-reduced-motion, as is the crawling dash.
+
+## Keyboard
+
+- Tab — Reaches the plot, which Recharts’ accessibility layer makes navigable.
+- ← / → — Moves the cursor between points, announcing each.
+
+## AreaChart
+
+A filled series over a category axis — the shape for a magnitude that is continuous, where the area under the line means something. Composed rather than configured: axes, grid, tooltip, legend and the areas themselves are children, so a chart renders exactly the parts it asked for and nothing is switched on by a prop nobody can see. Reach for `<LineChart>` instead when the reader is comparing several series against each other rather than reading one total, and for `<BarChart>` when the categories are discrete.
+
+### Props
+
+- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`. Series keys → their label and paint. Declaration order is ramp order.
+- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsAreaChart>`. Escape hatch onto the raw Recharts chart element.
+- `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.
+- `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.
+- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `ChartCurveType` = `ComponentProps<typeof RechartsArea>['type']`
+- `AreaVariant` = `'gradient' | 'gradient-reverse' | 'solid' | 'dotted' | 'lines' | 'hatched'`
+- `AreaStrokeVariant` = `'solid' | 'dashed' | 'animated-dashed'`
+- `AreaStackType` = `'default' | 'stacked' | 'expanded'`
+
+## Examples
+
+```tsx
+<AreaChart title="Visitors per month" config={config} data={data} xDataKey="month">
+  <AreaChart.Grid />
+  <AreaChart.XAxis dataKey="month" />
+  <AreaChart.Tooltip />
+  <AreaChart.Area dataKey="desktop" variant="gradient" />
+</AreaChart>
+```

package/dist/agent/Article.md

@@ -0,0 +1,41 @@
+# Article
+
+The long-form reading surface — everything a Markdown pipeline emits, in this system’s type.
+
+- Group: Surfaces
+- Import: `import { Article } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/article/
+- Related: diagram, card
+
+## When to reach for it
+
+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.
+
+## 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.
+
+## 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.
+
+### Props
+
+- `html` — `string`. Rendered HTML from a Markdown or MDX pipeline. Trusted markup only. This sets `dangerouslySetInnerHTML`, so it must come from content you control — a repository's own posts, a CMS you author — and never from a reader. Untrusted Markdown has to be sanitised before it reaches here; that is a pipeline decision, not a component one, and a sanitiser bolted on inside a styling primitive would be the wrong place to make it and the easiest place to get it wrong.
+- `as` — `'article' | 'div' | 'section'`. The element to render. `article` by default; pass `div` for a fragment.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+<Article html={renderedMarkdown} />
+<Article>
+  <h1>The White Reset</h1>
+  <p className="lead">A monochrome system for software and writing.</p>
+  <Diagram spec={spec} />
+</Article>
+```

package/dist/agent/Avatar.md

@@ -0,0 +1,32 @@
+# Avatar
+
+A person, as a circle, with initials until the image lands.
+
+- Group: Display
+- Import: `import { Avatar } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/avatar/
+
+## Accessibility
+
+- alt describes the person, not the picture. An empty string is correct when the name is already printed beside it.
+- The initials are aria-hidden — read aloud they are noise.
+
+## Avatar
+
+A person, as a circle. Wraps Radix so the fallback appears only after the image has actually failed or is still loading — a hand-rolled `onError` swap flashes the initials on every render before the cache answers.
+
+### Props
+
+- `src` — `string`.
+- `alt` (required) — `string`. Describes the person, not the picture. Empty string is correct and deliberate when the name is already printed beside the avatar — repeating it makes a screen reader say it twice.
+- `fallback` (required) — `string`. Shown while the image loads and if it never does. Usually initials.
+- `size` — `'sm' | 'md' | 'lg'` default `'md'`.
+
+Also accepts: `Omit<ComponentProps<typeof AvatarPrimitive.Root>, 'children'>`.
+
+## Examples
+
+```tsx
+<Avatar src={user.photo} alt={user.name} fallback="HC" />
+```

package/dist/agent/Badge.md

@@ -0,0 +1,40 @@
+# Badge
+
+A count or a state, set in mono so it reads as metadata.
+
+- Group: Display
+- Import: `import { Badge } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/badge/
+- Related: tag, status-pill
+
+## When to reach for it
+
+One fact about one record. If it names what something is ABOUT, that is a Tag.
+
+## Accessibility
+
+- Not interactive. A badge with an onClick is a control a keyboard cannot reach.
+- The status tones double their colour with words, so the meaning survives monochrome and colour-blindness.
+
+## Badge
+
+A count, a state, a small inline marker. Mono and small, so it reads as metadata rather than as content. A badge is not interactive — if it can be clicked or dismissed it is a `Tag` or a button, and giving this one an `onClick` produces a control a keyboard cannot reach.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `tone` — `BadgeTone` default `'neutral'`. `neutral` is the default and the right answer nearly always. The three status tones are the system's only chroma and are bound to STATE — a badge that is red because the design wanted a red badge is the thing this scale exists to prevent.
+
+Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+
+## Types
+
+- `BadgeTone` = `'neutral' | 'success' | 'warning' | 'danger' | 'outline'`
+
+## Examples
+
+```tsx
+<Badge>12</Badge>
+<Badge tone="success">Deployed</Badge>
+```