@hirobius/design-system 0.20.0 → 0.22.0

package/AGENTS.md

@@ -0,0 +1,125 @@
+# AGENTS.md — @hirobius/design-system
+
+<!-- Generated by scripts/generate-agents-md.mjs from mcp/guide.mjs and src/app/data/component-api.json. Do not hand-edit above the repo-notes marker: pnpm agents:generate -->
+
+For agents building UI with `@hirobius/design-system`. Read this first. It settles the choices the rest of the docs leave open, so two agents given the same screen build it the same way.
+
+## Look things up, do not guess
+
+- **MCP server `hds`** (stdio, ships in this package, no network): `npx hds-mcp` from an app that has the package installed. Client config:
+  `{ "mcpServers": { "hds": { "command": "npx", "args": ["hds-mcp"] } } }`
+- Tools: `list_core` (call first), `search_components` (by name or need), `get_component` (props, usage contract, compound parts), `search_tokens` (by path, prefix or words). Each answer is under 2 KB.
+- Without the server, the same data is in `src/app/data/component-api.json` (props, `usage`), `public/hds-manifest.json` (tokens, compound parts), `llms.txt` and `DESIGN.md` in this package.
+
+## Imports
+
+These are the recommended components: the ratified core set plus every component the needs below name. The ratified core alone is the `core: true` flag in the manifest.
+
+- `@hirobius/design-system`: `Alert`, `AlertDialog`, `Avatar`, `AvatarGroup`, `Badge`, `Blockquote`, `Box`, `Breadcrumb`, `Button`, `Card`, `Checkbox`, `Combobox`, `Container`, `Dialog`, `Disclosure`, `Divider`, `EmptyState`, `Field`, `Grid`, `HdsRouterProvider`, `HdsThemeProvider`, `Icon`, `InlineLink`, `Input`, `Kbd`, `Menu`, `MetadataList`, `Pagination`, `Pin`, `Popover`, `Progress`, `Radio`, `SegmentedControl`, `Select`, `Sidebar`, `Skeleton`, `Slider`, `Spinner`, `Stack`, `Surface`, `Switcher`, `Table`, `Tabs`, `TabsContent`, `TabsList`, `TabsTrigger`, `Tag`, `Text`, `Textarea`, `Timestamp`, `ToastProvider`, `Toggle`, `Tooltip`, `VisuallyHidden`, `useToast`.
+- `@hirobius/design-system/patterns`: `DataTableSection`, `DestructiveSection`, `Form`, `FormActions`, `MetricTile`, `MetricTiles`, `Page`, `PageHeader`. These are not in the root barrel.
+- Load one stylesheet once at the app root and put `data-hds` on the root element (`CONSUMING.md`).
+
+## Pick by need
+
+One answer per need. Use the components after the arrow; what follows "Not:" is what agents reached for instead, which is the wrong answer for that need even where it has a purpose of its own.
+
+- **Outermost wrapper of a screen** → `Page`, `Stack`. Not: `Container`, `Box`, a bare Stack as the root.
+  `<Page><Stack gap="spacious">…one child per section…</Stack></Page>`. `Container` is for a full-bleed surface that is not a page.
+- **Screen title with breadcrumb, status and actions** → `PageHeader`, `Breadcrumb`, `Badge`. Not: Text as the page title, a Stack row of Text and Badge.
+  Exactly one per screen: `<PageHeader breadcrumb={<Breadcrumb items={[{ label, href }, { label }]} />} title="…" status={<Badge tone="success">Active</Badge>} />`.
+- **Row of headline numbers (stats, KPIs, counts, totals)** → `MetricTiles`, `MetricTile`. Not: `Stat`, `StatusTile`, `CardMetric`, Card with Text.
+  `<MetricTiles><MetricTile label="Open projects" value="5" />…</MetricTiles>`; one MetricTile per number. `Stat` is for a number inside prose or a dense list, `Card.Metric` for one inside an existing `Card`, `StatusTile` for a state with notes (never a number).
+- **Table of records with row actions** → `DataTableSection`, `Badge`, `Button`. Not: Table on its own, Card around a Table.
+  `<DataTableSection title="Projects" columns={[{ key, label }]} rows={[{ key, cells: [...], actions: <Stack direction="row" gap="tight">…</Stack> }]} />`; leave the actions column out of `columns`.
+- **Switch between panels of related content** → `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. Not: `SegmentedControl`, Button rows.
+  `<Tabs defaultValue="a"><TabsList><TabsTrigger value="a">A</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent></Tabs>`.
+- **Status label in a header or table cell** → `Badge`. Not: `Tag`, `Text`.
+  `<Badge tone="success|info|warning|danger|neutral|inProgress">…</Badge>`; tone is the only styling input.
+- **Form with fields and a submit button** → `Form`, `Textarea`, `Input`, `FormActions`, `Button`. Not: a raw `<form>`, a Stack of Buttons as the footer.
+  `<Form onSubmit={…}><Textarea label="Notes" … /><FormActions primary={<Button type="submit">Save note</Button>} /></Form>`; every field takes its own `label`.
+- **Confirm a destructive or irreversible action (delete, archive, remove)** → `AlertDialog`, `Button`. Not: `Dialog`, `window.confirm`.
+  Trigger, title, description, Cancel and Action parts: `<AlertDialog><AlertDialog.Trigger asChild><Button …>Archive</Button></AlertDialog.Trigger><AlertDialog.Content><AlertDialog.Header><AlertDialog.Title>…</AlertDialog.Title><AlertDialog.Description>…</AlertDialog.Description></AlertDialog.Header><AlertDialog.Footer><AlertDialog.Cancel asChild><Button variant="secondary">Cancel</Button></AlertDialog.Cancel><AlertDialog.Action asChild><Button tone="danger" onClick={…}>Archive</Button></AlertDialog.Action></AlertDialog.Footer></AlertDialog.Content></AlertDialog>`. Focus moves in and returns to the trigger for you.
+- **Brief confirmation after an action (saved, archived, sent)** → `ToastProvider`, `useToast`. Not: `Badge`, `Alert`, `Text`.
+  Wrap the app root once in `<ToastProvider>`, then `toast({ title: "Note saved", tone: "success" })` from `useToast()`.
+- **Message that stays next to its content (error, warning, info)** → `Alert`. Not: Text in a coloured Surface.
+  `<Alert tone="warning">…</Alert>`.
+- **Button or row action** → `Button`. Not: a raw `<button>`, InlineLink for an action.
+  Row actions: `<Button variant="tertiary" size="sm" aria-label="View Brand refresh">View</Button>`; the destructive one adds `tone="danger"`.
+- **Space between sections or items** → `Stack`, `Grid`. Not: margins on children, raw px gaps such as px8.
+  Stack `gap`: `spacious` between page sections, `normal` inside a section, `tight` between buttons. `Grid` for two-dimensional layout.
+- **Padded background or a titled content object** → `Surface`, `Card`. Not: a Box with background and padding.
+  `Surface` for a plain padded background; `Card` only when the content has a title or can be pressed.
+- **Progress bar or ring** → `Progress`. Not: a hand-built bar.
+  `<Progress value={60} label="Upload" />`; inside an existing `Card`, `CardProgress`.
+- **Body copy** → `Text`. Not: Text as a section heading.
+  Section headings come from the pattern that owns the section (`PageHeader` `title`, `DataTableSection` `title`), not from extra Text.
+- **Empty state for a list or section** → `EmptyState`. Not: Text saying "No items".
+  `DataTableSection` shows its own through `emptyTitle`; use `EmptyState` elsewhere.
+- **The one irreversible action of a screen (delete the client, close the account)** → `DestructiveSection`. Not: a danger Button that acts without a confirm.
+  Last on the screen: `<DestructiveSection title="Delete client" description="…" actionLabel="Delete" onConfirm={…} />`; it opens its own AlertDialog. A per-row destructive action uses AlertDialog directly.
+- **Read-only details as label and value pairs** → `MetadataList`, `Field`. Not: a Table with two columns, Text pairs in a Stack.
+  `<MetadataList items={[{ term: "Owner", description: "Ada" }]} />` for a set; `Field` for one pair.
+- **A person, or a group of people** → `Avatar`, `AvatarGroup`. Not: an image in a rounded Box.
+  `<Avatar src alt initials />`; several in a row: `<AvatarGroup max={3}>…Avatars…</AvatarGroup>`.
+- **A date or time** → `Timestamp`. Not: a formatted string in Text.
+  `<Timestamp date="2026-10-14" />` renders a `<time dateTime>`; a date in a table cell may stay plain text.
+- **A keyboard key or shortcut hint** → `Kbd`. Not: `InlineCode`, Text in a Box.
+  `<Kbd>⌘K</Kbd>`.
+- **A quotation with attribution** → `Blockquote`. Not: Callout for a quote, italic Text.
+  `<Blockquote attribution="Ada Lovelace">…</Blockquote>`.
+- **A fixed-width side rail beside fluid content, or a row that stacks when narrow** → `Sidebar`, `Switcher`. Not: a Grid with media queries.
+  `Sidebar` (`side`, `sideWidth`) for rail + content; `Switcher` (`threshold`) for a row that flips to a column. Neither needs a media query.
+- **Keep an element stuck while its region scrolls** → `Pin`. Not: position: sticky in style.
+  `<Pin top="…">…</Pin>` inside the scrolling region.
+
+## Rules
+
+- Tokens only: no raw hex or rgb, no raw `px`, no Tailwind classes, no custom CSS files. Spacing comes from component props (`Stack` `gap`), colour from component `tone` props or `semantic.*` tokens (`search_tokens`).
+- No raw `<button>`, `<input>`, `<select>`, `<textarea>` or `<form>`: use `Button`, `Input`, `Select`, `Textarea`, `Form`.
+- Every control has an accessible name: fields take `label`, a repeated row action takes an `aria-label` naming its row.
+- Section headings come from the pattern that owns the section (`title` props). Do not add a `Text` heading the screen does not ask for.
+
+## Finish with the lint plugin
+
+The ESLint plugin ships in this package. Pass its `recommended` rules before you report done:
+
+```js
+// eslint.config.mjs
+import hds from '@hirobius/design-system/eslint-plugin';
+
+export default [...hds.configs.recommended];
+```
+
+<!-- hds:repo-notes — everything below is hand-written, for agents working in the hds repo itself; consumers can stop here. -->
+
+## Working in the hds repo
+
+Notes for agents working on this repository, not with the package. Read `CLAUDE.md` for
+the full engineering protocol; this section is the home for autonomous-loop rules.
+
+## Ralph quality bar
+
+REPO_TYPE: library
+QUALITY BAR: Public npm package. Backward compatibility matters. Tests + Storybook stories required.
+
+Rules for any autonomous loop in this repo:
+
+- One issue per PR. Small steps. Never push to main.
+- The gate (ralph/gate.sh) must pass before any PR. No exceptions.
+- Fight entropy: leave the code better than you found it.
+- No shortcut that creates debt someone else pays for.
+- Merges are HUMAN-approved: `ralph-approved` on the PR, or the issue
+  pre-tagged `ralph-auto` (batch approval). Never merge yourself.
+
+Loop mechanics (see `ralph/README.md` for the full contract):
+
+- Labels: `ralph-ready` (queue, human) · `p0`–`p3` (priority, human) ·
+  `ralph-auto`/`ralph-approved` (merge approval, human) · `ralph-wip`
+  (claimed, loop) · `ralph-parked`/`needs-adrian` (parked with reason, loop) ·
+  `ralph-selfheal-attempted` (gate's one bounded repair, spent).
+- Selection is deterministic (`ralph/next.sh`: priority label, then issue #);
+  claims are atomic (`refs/heads/ralph/claim-<n>`); the loop's exit codes are
+  a contract (`ralph/run.sh` header). Agents never touch `ralph-*` labels,
+  claim refs, or `ralph/{.lock,runs.jsonl,logs/}` — the harness owns those.
+- The engine is org-level: workflows are thin callers into
+  `hirobius/ralph/.github/workflows/ralph-{run,gate}-reusable.yml@v1`.