@hirobius/design-system 0.17.0 → 0.19.0

package/public/llms.txt

@@ -0,0 +1,261 @@
+# Hirobius Design System
+
+Generated: 2026-09-30T14:27:19.090Z
+Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`, `hirobius.tokens.json`
+
+## System Architecture
+
+- Engine: React + TypeScript
+- Icons: Lucide React
+- Tokens: W3C DTCG
+- Styling: CSS Variables
+- Token pipeline: `hirobius.tokens.json` -> `pnpm tokens` -> generated CSS vars + generated TS constants
+- Docs pipeline: `public/hds-manifest.json` + `src/app/data/component-api.json` -> reflective docs pages
+- AI entrypoint: read `public/llms.txt` before editing code
+
+## Phase Snapshot
+
+- foundation. Foundations - 63% - Token architecture, CSS pipeline, accessibility, and primitive scales.
+  - Criteria: done: W3C DTCG three-tier token architecture; done: CSS variable pipeline + token verify; partial: Primitive scales complete (color, type, space); todo: Token audit clean
+- components. Components - 75% - Accessible React UI built from foundations and mapped toward Figma parity.
+  - Criteria: done: Component inventory with typed props; done: Action system architecture (buttons, links, groups); done: Prop tables and API doc coverage; todo: Figma parity mapping
+- infrastructure-operations. Architecture - 55% - System delivery, Figma sync, automation, quality gates, and operational hygiene.
+  - Criteria: done: System manifest + llms.txt AI context; done: Release gate + full audit gate; done: Documentation automation (AST pipeline, LLMS sync); partial: Payload sweep + orphan cleanup; partial: Motion system foundations; todo: Figma library generated from tokens; todo: Code Connect CI + reverse sync; partial: AST gatekeeper + token schema validation; partial: A11y CI + visual regression pipeline; partial: Operational feedback loop + AI retrospective
+
+## Component Inventory (Source Of Truth)
+
+This file intentionally does not embed the full component list to avoid duplication and excess context.
+
+- Canonical inventory + metadata: read `public/hds-manifest.json`.
+- If you see references to `public/manifest.json`, treat it as an optional alias; in this repo prefer `public/hds-manifest.json`.
+
+## Component API (Source Of Truth)
+
+This file intentionally does not embed prop tables or long-form API docs.
+
+- Detailed prop types, unions, defaults, and descriptions: read `src/app/data/component-api.json`.
+- Runtime behavior: read the actual component source under `src/app/components/` (and associated styles).
+
+## Which one when
+
+One line per component that declares when to use it (`@usage` / `@useInstead` in its JSDoc). Full detail, including `usage.whenNot`, `keyboard` and `aiRules`, is in `public/hds-manifest.json` and `src/app/data/component-api.json`.
+
+Alert: Show a persistent inline message with a severity, next to the content it concerns. Use instead: ToastProvider, Badge
+Avatar: Show a person or entity as an image with an initials fallback. Use instead: Icon, Badge
+Badge: Label a status, state or count with a compact neutral or semantic chip. Use instead: Tag, Alert
+Box: Build one-off layout that no named layout primitive covers, using token keys through `sx`. Use instead: Stack, Grid, Container
+Breadcrumb: Show where the current page sits in a hierarchy and link back up it. Use instead: Tabs, Pagination
+Button: Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft. Use instead: InlineLink
+ButtonGroup: Attach related Buttons into one segmented row or column that reads as a single control. Use instead: SegmentedControl, Stack
+Card: Group related content on a raised surface with header, body, footer and metric slots. Use instead: Surface, Card.Metric
+CardMetric: Show one headline figure (a KPI, a count, a total) with its label inside a Card.
+Checkbox: Let people tick one or more independent options, or a parent choice that is partly selected. Use instead: Toggle, Radio
+Combobox: Pick one value from a long list of options, with a search field that filters as you type. Use instead: Select, Menu
+Container: Constrain a page region to the content or maximum width and centre it. Use instead: Stack, Grid, Box
+ContextMenu: Offer actions for an item on right-click, or the equivalent keyboard gesture. Use instead: Menu
+Dialog: Interrupt the page with a modal that needs a decision or focused input before people continue. Use instead: HoverCard, Alert, ToastProvider
+Disclosure: Hide optional explanatory content behind a heading that people can expand. Use instead: Tabs
+Divider: Separate two regions of content with a thin semantic rule. Use instead: Stack, Surface
+EmptyState: Say that a list, grid or section has no data yet, with a title and an optional description. Use instead: Skeleton, Alert
+Field: Show a labelled read-only value, such as a name and its value in a detail view. Use instead: Input, Card.Metric
+Grid: Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid. Use instead: Stack, Box
+HdsThemeProvider: Wrap an app or region once to set theme, density and other root attributes for everything inside it. Use instead: Surface
+HoverCard: Preview extra detail about a link or mention when it is hovered or focused, without navigating. Use instead: Dialog, Tooltip
+Icon: Draw a Lucide glyph at a size and colour from the design tokens. Use instead: Button, Avatar
+IconButton: Trigger an action from a compact icon-only control, always with an accessible label. Use instead: Button
+InlineLink: Link to a route or external URL from inside body copy. Use instead: Button, Text
+Input: Collect a single line of text, a number, an email or a password, with label, helper and error slots. Use instead: Textarea, Select, Combobox
+Kbd: Show a keyboard key or shortcut hint inline, as a native kbd element. Use instead: Text
+Menu: Offer a list of actions from a trigger, closed until opened. Use instead: Select
+Pagination: Move between pages of a long result set, with truncated page numbers. Use instead: Breadcrumb
+Progress: Show how far a task has got, as a bar that is determinate or indeterminate. Use instead: Spinner, Skeleton
+Radio: Choose exactly one option from a small set that should stay visible together. Use instead: Checkbox, Select, SegmentedControl
+SegmentedControl: Switch between two to five mutually exclusive views or modes in a compact row. Use instead: Radio, Tabs, Select
+Select: Choose one value from a short list of options in a form field. Use instead: Menu, Combobox
+Skeleton: Reserve the shape of content that is still loading, so the layout does not jump. Use instead: Progress, Spinner
+Slider: Pick a number within a known range by dragging, when the exact value matters less than the position. Use instead: Input
+Spinner: Show that something is loading when the wait is short or has no measurable end. Use instead: Progress, Skeleton
+Stack: Space a row or column of content with token gaps and simple flex alignment. Use instead: Grid, Surface
+Stat: Show one standalone headline figure with its label and an optional sub-line. Use instead: Card.Metric, StatusTile
+StatusTile: Show a titled status block with optional notes and a trailing badge or affordance. Use instead: Card.Metric, StatusListItem
+Surface: Wrap content in a padded, background-bearing inset surface with no header or footer anatomy. Use instead: Card, Stack
+Table: Show rows of structured data in aligned columns, with optional sorting. Use instead: Field, Stack
+Tabs: Switch between panels of related content in the same place, one visible at a time. Use instead: SegmentedControl, Disclosure
+Tag: Show an interactive filter or category chip that people can toggle. Use instead: Badge
+Text: Set any text on the type ramp, with the element chosen by `as`. Use instead: InlineLink, Kbd
+Textarea: Collect multi-line free text such as a message, note or description. Use instead: Input
+ToastProvider: Confirm an action with a brief message that appears and dismisses itself, through useToast. Use instead: Alert, Dialog
+Toggle: Switch one setting on or off, with the effect applying immediately. Use instead: Checkbox, Radio
+VisuallyHidden: Give assistive technology a label or description that sighted people do not need to see. Use instead: Text
+
+## Tokens (Primary Source Of Truth)
+
+- Primary token source of truth: `hirobius.tokens.json` (W3C DTCG).
+- Prefer `semantic.*` and `component.*` tokens for product UI. Use `primitive.*` only when editing the token system itself.
+- CSS variable naming convention: token path `semantic.color.surface.page` maps to `var(--semantic-color-surface-page)`.
+
+## Quick Token Reference
+
+| Need | Token path examples | CSS var examples |
+| --- | --- | --- |
+| Page/background surfaces | `semantic.color.surface.page`, `semantic.color.surface.raised` | `--semantic-color-surface-page`, `--semantic-color-surface-raised` |
+| Text/content colors | `semantic.color.content.primary`, `semantic.color.content.secondary` | `--semantic-color-content-primary`, `--semantic-color-content-secondary` |
+| Borders/dividers | `semantic.color.border.default`, `semantic.color.border.interactive` | `--semantic-color-border-default`, `--semantic-color-border-interactive` |
+| Feedback states | `semantic.color.feedback.error`, `semantic.color.feedback.success` | `--semantic-color-feedback-error`, `--semantic-color-feedback-success` |
+| Spacing (semantic tiers) | `semantic.space.scale.xs`, `semantic.space.surface.padding`, `semantic.space.region.gutter` | use semantic tokens or `--hds-space-px12` style vars |
+| Radius | `semantic.radius.action` | `--semantic-radius-action` |
+| Motion | `semantic.motion.productive`, `semantic.motion.expressive`, `semantic.motion.exit` | use token refs; values are structured (duration/easing) |
+| Typography | `semantic.typography.body`, `semantic.typography.h2`, `semantic.typography.caption` | use token refs; values are structured (family/size/weight/etc) |
+
+## How To Lay Out A Screen
+
+Canonical skeleton, outermost to innermost:
+
+1. `Page` (or `Container`/`Center` for a full-bleed, non-page surface) for the outermost width constraint. Never import `Container` directly inside `src/app/pages/**` — use `Page`, which wraps it and owns vertical rhythm.
+2. `Stack` (vertical rhythm between sections) or `Grid` (two-dimensional/column layout) for the structural skeleton. One section = one Section/Stack — never add a second wrapper to fake a section boundary.
+3. Reach for a named every-layout primitive before hand-rolling flex/grid math for a common intent: `Cluster` (wrapping row of same-ish things), `Center` (centered max-width column with optional gutter), `Sidebar` (fixed-width rail + fluid content, no media query), `Switcher` (row that flips to a column below a threshold, no media query), `Cover` (full-height shell with a centered main region), `Frame` (aspect-ratio-locked clipped media box), `Bleed` (controlled negative margin to escape a parent padding).
+4. `Surface` for any background-bearing, padded wrapper (card, panel, inset). Never a raw element with backgroundColor + padding hand-rolled inline.
+5. Use the screen patterns (`@hirobius/design-system/patterns`) for the parts every screen repeats: `PageHeader` once at the top (breadcrumb, `heading2` title, status, actions), `MetricTiles` for any row of headline numbers, `FormActions` for a form footer (primary right-most and last in DOM order, destructive on the far left), `DataTableSection` for a titled table (toolbar slot, consumer row actions, empty state, scrolls on narrow widths without a caller `minWidth`), and `DestructiveSection` last for an irreversible action (danger button, then an `AlertDialog` confirm). Pick between `MetricTiles`, `Stat`, `Card.Metric` and `StatusTile`, and between `Card` and `Surface`, with the "Which one, when" table in `DESIGN.md`.
+6. `Box` `sx` LAST — only for genuinely one-off layout that no named primitive covers. `sx` spacing/color keys MUST be HDS token keys, never raw hex/px.
+
+Negative rules (apply everywhere, checked by `scripts/audit-tokens.mjs --full`, `check-hardcoded-spacing.mjs`, `check-hardcoded-colors.mjs`):
+
+- No inline margins on children to fake spacing between siblings — gap/spacing on the parent (Stack/Grid/Cluster/Switcher/Sidebar/Cover) owns rhythm, not margin on the child.
+- No raw px or hex values in any layout or color prop — every spacing value comes from the semantic gap scale (`tight | normal | inset | spacious`, or a component/subgrid step) and every color comes from a `semantic.color.*` token.
+- No repeated outlined cards as the default structure for roadmap/status/process/overview UI — use open bands, dividers, rails, disclosures, and whitespace instead.
+
+Density: put `data-density="compact"` on the same `[data-hds]` scope element (or `<html>`) to tighten `semantic.space.scale.*`, surface padding and region gutter; `Table` follows it unless given a `density` prop.
+
+Reference: `docs/architecture/variant-contract.md` for structural/semantic/size/density variance; `src/app/data/component-api.json` for every layout primitive's full prop table and `@ai-rules` guidance.
+
+## How To Build A Scroll-Driven Section
+
+Canonical primitives, cheapest-first (CSS before JS, JS before an opt-in dependency):
+
+1. `Reveal` (CSS `animation-timeline: view()`) for fade/slide/scale-in-on-enter — zero JS, zero deps. Pick `animation` from `fade | fade-up | fade-down | scale`. Content is visible by DEFAULT; the effect applies only where `animation-timeline` is supported and the user has not requested reduced motion — never gate visibility behind either.
+2. `Pin` (`position: sticky`) for a pinned scroll scene — the dependency-free basis for the "tall section + sticky child" pattern (GSAP's `pin: true`, done with zero JS). Give the pinned element a TALLER scrolling parent (e.g. `height: 300vh`) so it has room to travel; `top` is a CSS length offset, not a spacing token.
+3. `useScrollProgress` (from `@hirobius/design-system/scroll`) only when the 0→1 scroll value is needed in React — cross-element choreography, canvas/WebGL, or a Motion (`motion/react`) `useTransform` binding that CSS `animation-timeline` cannot express. Thin, SSR-guarded wrapper over Motion `useScroll`; adds no new dependency.
+4. `SmoothScroll` (from `@hirobius/design-system/scroll`, `lenis` as an OPTIONAL peer dep) only for opt-in momentum ("inertia") scrolling, mounted once at the app/site root. Never imported from the main barrel — consumers who skip it pay nothing. Reduced-motion-first: Lenis is not instantiated when the user prefers reduced motion, unless `ignoreReducedMotion` is set for a deliberate art-directed exception.
+5. Do not adopt GSAP/ScrollTrigger, and do not wire Lenis directly outside `SmoothScroll`, inside the core library — the CSS + Motion stack above covers reveal/pin/scrub without new dependencies. Bespoke GSAP/Lenis/WebGL scenes stay app-level/downstream (marketing sites, the clients factory), composed from these primitives (ADR-021, #116).
+
+Negative rules:
+
+- No hand-rolled IntersectionObserver reveal-on-scroll logic — use `Reveal`.
+- No hand-rolled `position: sticky` scroll scenes — use `Pin`.
+- No GSAP/ScrollTrigger or bespoke Lenis wiring inside `@hirobius/design-system` — those stay app-level/downstream, composed from `Reveal`/`Pin`/`useScrollProgress`/`SmoothScroll`.
+- Every scroll effect must degrade to fully visible/static content — never gate content visibility behind `animation-timeline` support or a scroll listener with no fallback.
+
+Reference: `src/app/components/reveal.tsx`, `src/app/components/pin.tsx`, `src/scroll/` (`use-scroll-progress.ts`, `smooth-scroll.tsx`), ADR-021, and `src/stories/patterns-scroll.stories.tsx` for golden-path examples.
+
+## HDS Card Anatomy (mandatory — every property is non-negotiable)
+
+When building any card component or card-like surface, ALL of the following rules apply. There is no creative latitude here — deviation from any property is a bug.
+
+| Property | Required value | Forbidden |
+| --- | --- | --- |
+| Background | `var(--semantic-color-surface-raised)` | Custom colors, gradients, tinted fills, any non-token value |
+| Border | `1px solid var(--semantic-color-border-default)` | `box-shadow` as an elevation substitute |
+| Border radius | `rounded-lg` (`role.radius` + 4 px: 12 px by default, follows the tenant) | `var(--component-card-radius)`, `rounded-full`, or any hard-coded value |
+| Padding | `var(--semantic-space-surface-padding)` or `<Surface padding="component">` | Raw pixel values, Tailwind spacing classes, ad hoc insets |
+| Shadow | Resting cards: none (`elevation.flat`). Interactive lifted state: `shadow.subtle` via `elevation.raised`. Never reach for shadow values directly — bind via `var(--semantic-elevation-{role}-shadow)` | Raw `box-shadow` values, `drop-shadow`, glow, or any depth effect not bound to a role token |
+| Title | `hds.typeStyles.heading3` / `<Text variant="heading3">` | Any other type style for the primary card heading |
+| Subtitle / meta | `hds.typeStyles.caption` / `<Text variant="caption">` + `var(--semantic-color-content-secondary)` | Primary color, body size, or custom color for secondary text |
+| Hover (interactive cards only) | `transform: scale(1.02)` CSS transform | Background color change, fill swap, border color shift on hover |
+
+**NEVER on any card surface:** gradient backgrounds, glow effects, frosted glass (`backdrop-filter: blur`), decorative overlays, gradient borders, colored or tinted card backgrounds, inner shadows, patterned backgrounds, AI-aesthetic shimmer or particle effects. Never reach for shadow values directly — bind to a `semantic.elevation.*` role bundle so surface + shadow + border stay coherent.
+
+## Elevation roles
+
+| Surface | Role token | Background | Shadow | Border |
+| --- | --- | --- | --- | --- |
+| Card / panel resting | `semantic.elevation.flat` | `surface.page` | none | `border.subtle` 1px |
+| Card / panel lifted (interactive only) | `semantic.elevation.raised` | `surface.raised` | `shadow.subtle` | none |
+| Popover / dropdown / tooltip | `semantic.elevation.floating` | `surface.raised` | `shadow.floating` | none |
+| Dialog / sheet / modal | `semantic.elevation.overlay` | `surface.overlay` | `shadow.overlay` | none |
+
+Cards default to `elevation.flat`. Popovers/tooltips/dropdowns use `elevation.floating`. Dialogs/sheets use `elevation.overlay`. Interactive cards lift to `elevation.raised` on hover. Never combine `raised` with a border — depth is one mechanism (border OR shadow), not both stacked.
+
+Overlays (Dialog, AlertDialog, Menu, ContextMenu, Popover, Select, HoverCard, Tooltip) portal into the nearest `data-hds` scope, so they inherit its theme (for example `<div data-hds data-theme="dark">`); pass `container` on the Content part to override.
+
+## Slices And Full Bundle
+
+Load only what the task needs. Same text as this file, split by topic:
+
+- `public/llms/layout.txt` - screen layout recipe, card anatomy, elevation roles
+- `public/llms/tokens.txt` - token rules and the quick token reference
+- `public/llms/scroll.txt` - scroll-driven section recipe
+- `public/llms/components.txt` - component inventory pointer, API pointer, props digest
+
+- `public/llms-full.txt` - this file + the full `DESIGN.md` + a compact props digest for every component.
+
+Paths in this file that begin with `docs/architecture/`, `src/app/components/`, `src/scroll/`, `src/stories/` or under `scripts/`, or that name `public/manifest.json`, `DESIGN-HANDOFF.md`, `TOKEN_GOVERNANCE.md` or `SYSTEMS_REGISTRY.md` exist only in the source repo, not in the npm package. Everything under "Default context" below ships in the package.
+
+## Context Loading Rules (Credit Efficiency)
+
+Default context (load first):
+
+- `public/llms.txt`
+- `public/hds-manifest.json`
+- `src/app/data/component-api.json`
+- `hirobius.tokens.json`
+- `DESIGN.md`
+
+On-demand only (load only if explicitly requested or the task clearly requires it):
+
+- `DESIGN-HANDOFF.md`
+- `TOKEN_GOVERNANCE.md`
+- `SYSTEMS_REGISTRY.md`
+
+## Pattern Inventory
+
+- DataTableSection
+- DestructiveSection
+- FormActions
+- MetricTiles
+- PageHeader
+
+## Icons
+
+Icons come from the curated subpath `@hirobius/design-system/icons`; nothing extra to install.
+
+```tsx
+import { IconButton } from '@hirobius/design-system';
+import { Ellipsis } from '@hirobius/design-system/icons';
+
+<IconButton icon={Ellipsis} label="Row actions" />
+```
+
+Rule: icon-only actions (row menus, close, edit) use `IconButton`; do not hand-roll a button with a glyph or text "...".
+
+Names: Archive, ArrowDown, ArrowLeft, ArrowRight, ArrowUp, Bell, Bookmark, Calendar, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, CircleAlert, CircleCheck, CircleHelp, Clock, Copy, Download, Ellipsis, EllipsisVertical, ExternalLink, Eye, EyeOff, FileText, Funnel, Heart, House, Image, Info, Link, Lock, LogIn, LogOut, Mail, Menu, Minus, Pencil, Plus, RefreshCw, Save, Search, Settings, Share, Star, Trash2, TriangleAlert, Upload, User, X
+
+Legacy names map to canonical ones: MoreHorizontal -> Ellipsis, MoreVertical -> EllipsisVertical, AlertTriangle -> TriangleAlert, Home -> House, Filter -> Funnel.
+
+Name collisions: `Calendar` and `Menu` share names with HDS components; alias the icon: `import { Calendar as CalendarIcon, Menu as MenuIcon } from '@hirobius/design-system/icons'`. For an icon outside the set, install `lucide-react@0.487.0` (same version keeps the `LucideIcon` type identical).
+
+## Token Rules
+
+- Component inventory: read `public/hds-manifest.json`. Do not duplicate inventories in markdown.
+- Component prop API: read `src/app/data/component-api.json`. Do not inline prop tables in `llms.txt`.
+- Token source of truth: read `hirobius.tokens.json` (W3C DTCG). Prefer `semantic.*` and `component.*` tokens over `primitive.*` for product UI.
+- CSS variables: token path `semantic.color.surface.page` maps to `var(--semantic-color-surface-page)` (see generated token refs).
+- Docs: use `DESIGN.md` as the default lean visual spec. Load `DESIGN-HANDOFF.md` only on-demand.
+- Load `TOKEN_GOVERNANCE.md` and `SYSTEMS_REGISTRY.md` only on-demand (when explicitly requested or required by the task).
+- Read `public/llms.txt` before touching code so AI workflows start from the same system map as humans.
+
+## Agent Workflow
+
+1. Read `public/llms.txt` and the relevant source files.
+2. Check `public/hds-manifest.json` for component metadata and phase status.
+3. Check `src/app/data/component-api.json` for prop names, unions, defaults, and descriptions.
+4. Use `hirobius.tokens.json` (and generated CSS vars) for styling decisions, never raw hex or ad hoc values.
+5. Run `pnpm tokens:audit` or `pnpm build` after changes that affect docs, tokens, or manifests.
+
+## Key Files
+
+- `public/hds-manifest.json` - canonical machine-readable system inventory, metadata, and token snapshot
+- `src/app/data/component-api.json` - generated prop reference (source of truth for prop docs)
+- `hirobius.tokens.json` - token source of truth (W3C DTCG)
+- `public/llms.txt` - machine-readable AI context index
+- `DESIGN.md` - lean agent-facing visual spec (default)
+- `DESIGN-HANDOFF.md` - verbose visual language mirror (on-demand only)