@hirobius/design-system 0.12.0 → 0.13.1

package/NOTICE.md

@@ -0,0 +1,9 @@
+# License notice
+
+`@hirobius/design-system` is not under a single license.
+
+- **HDS code** (components, compiled JavaScript, types, CSS, and token files): MIT. See [LICENSE](LICENSE).
+- **Satoshi** (weights 500 and 700, by Indian Type Foundry, distributed through [Fontshare](https://www.fontshare.com/fonts/satoshi)): ITF Free Font License.
+- **Geist Mono** (weight 400, by Vercel, [source](https://github.com/vercel/geist-font)): SIL Open Font License 1.1.
+
+Both fonts are embedded as base64 `@font-face` data in `dist/tokens.css` and `dist/styles.css`. The MIT license does not cover them; each font keeps its own license. `dist/variables.css` embeds no fonts.

package/README.md

@@ -1,6 +1,27 @@
 # Hirobius Design System
 
-A publishable React + TypeScript component library, backed by a governed design-token pipeline, a documentation site, and an automated verification suite — all in one repository.
+A publishable React + TypeScript component library backed by a governed design-token pipeline, published to npm as `@hirobius/design-system`.
+
+<!--
+  PLACEHOLDER — ADRIAN TO WRITE (hds front-door PR).
+  If you want the README to mention the July–September 2026 pause, put one or
+  two sentences here in your own words, then delete this comment. Leaving the
+  comment in place publishes nothing. Do not restore the old status line this
+  PR removed: CI, release, and Chromatic triggers were restored in #204.
+-->
+
+<!-- auto:start:front-door-counts -->
+
+- **108** public component modules, exported from `src/index.ts`
+- **362** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
+- **442** Storybook stories in **112** story files, reviewed visually in Chromatic
+
+<!-- auto:end:front-door-counts -->
+
+- Theming through four root attributes and CSS variables (theme, density, brand, font) that need no JavaScript
+- Deterministic gates in git hooks and CI: typecheck, zero-warning ESLint, token validity and contrast, Vitest unit and contract tests, bundle budgets, a consumer smoke build, and a Storybook build
+
+The counts are generated from source by `pnpm readme:counts`, which `pnpm tokens` also runs. `scripts/__tests__/front-door.test.mjs` fails if this README claims more than the source has.
 
 ## Using the published package
 
@@ -46,17 +67,22 @@ HDS theming is driven by root attributes + CSS variables, so it works with **zer
 JavaScript** — set them on any element (React, Astro, plain HTML) and every HDS
 descendant re-skins:
 
-| Dial | Attribute / var | Values | Default |
-| --- | --- | --- | --- |
-| theme | `data-theme` | `dark` | light (unset) |
-| density | `data-density` | `compact` | comfortable (unset) |
-| brand | `data-brand` (+ `data-tenant` alias) | overlay slug | base (unset) |
-| font | `--hds-font-family` / `--hds-font-family-mono` | any font-family | Satoshi / Geist Mono |
+| Dial    | Attribute / var                                | Values          | Default              |
+| ------- | ---------------------------------------------- | --------------- | -------------------- |
+| theme   | `data-theme`                                   | `dark`          | light (unset)        |
+| density | `data-density`                                 | `compact`       | comfortable (unset)  |
+| brand   | `data-brand` (+ `data-tenant` alias)           | overlay slug    | base (unset)         |
+| font    | `--hds-font-family` / `--hds-font-family-mono` | any font-family | Satoshi / Geist Mono |
 
 ```html
 <!-- zero-JS: static markup (e.g. an Astro layout) -->
-<div data-hds data-theme="dark" data-density="compact" data-brand="acme"
-     style="--hds-font-family: 'Inter', sans-serif">
+<div
+  data-hds
+  data-theme="dark"
+  data-density="compact"
+  data-brand="acme"
+  style="--hds-font-family: 'Inter', sans-serif"
+>
   …
 </div>
 ```
@@ -73,27 +99,43 @@ import { HdsThemeProvider } from '@hirobius/design-system';
 </HdsThemeProvider>;
 ```
 
+## Figma ↔ code
+
+Code is the source of truth, and sync runs one way, from code to Figma. What exists today:
+
+- **Tokens → Figma model:** `pnpm figma:model` projects `hirobius.tokens.json` into `figma/model.json` — the Primitives, Semantic (Light/Dark), Component, Role, Brand and Density collections, plus text and effect styles. Light and Dark keep their own values.
+- **Model → Figma file:** `pnpm figma:push` writes the upsert scripts that apply that model to a Figma file, and `pnpm figma:native-import` writes DTCG files for Figma's own Variables ▸ Import. Both are run by hand — no workflow pushes to Figma. The runbook is [`figma/README.md`](figma/README.md).
+- **Figma → repo:** `pnpm figma:snapshot --ingest` records the file's state in `figma/snapshot.json`, and `pnpm check:figma-drift` compares the model against that committed snapshot. A hand edit in Figma is drift, not a source change.
+- **Legacy export:** `pnpm figma-variables` still writes the older plugin and REST export files, now projected from the same model.
+- **Components → Code Connect:** the v2 templates live in the repo, but no Code Connect mapping is published, so Dev Mode shows no snippets. Publishing Code Connect needs a Figma Organization plan.
+
+What each Figma plan allows, and the Pro-plan architecture this follows, are in [ADR-025](docs/adr/025-figma-sync-pro-architecture.md).
+
 ## Developing this repo
 
 ```bash
 pnpm install
-pnpm dev
+# Generated data files are gitignored; create them once (the same step CI runs):
+node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs && node scripts/sync-icons.mjs && node scripts/audit-tokens.mjs --full
+pnpm storybook   # component workbench on http://localhost:6006
 ```
 
 Core verification commands:
 
 ```bash
 pnpm typecheck
-pnpm run heal
-pnpm test:layout
+pnpm lint
+pnpm exec vitest run   # unit + contract tests, as the pre-push hook and CI run them
+pnpm tokens:verify
 pnpm check:size
+pnpm build-storybook
 ```
 
 ## Architecture
 
 HDS is built around three structural rules:
 
-- **Strict semantics** — public surfaces prefer system primitives such as `HdsStack`, `HdsGrid`, `HdsSurface`, `HdsTextLockup`, `DocLayout`, and `CaseStudyLayout` instead of raw layout divs or ad hoc CSS.
+- **Strict semantics** — public surfaces prefer system primitives such as `Stack`, `Grid`, `Surface`, and `TextLockup` instead of raw layout divs or ad hoc CSS.
 - **Polymorphism** — primitives preserve semantic HTML while staying composable through governed APIs such as `forwardRef`, `as`, and layout slots.
 - **12-column grid** — page structure follows a consistent editorial grid: readable center columns, intentional breakout zones, and explicit `gap` ownership rather than one-off spacing math.
 
@@ -105,6 +147,20 @@ Source-of-truth files:
 - `DESIGN.md` — lean visual spec for agents and engineers.
 - `DESIGN-HANDOFF.md` — verbose visual mirror for handoff and review.
 
+<!-- design-links:start (generated by `pnpm figma:links`; edit the @figma JSDoc tag, not this section) -->
+
+## Design ↔ Code links
+
+Each component has one Figma source: `figmaUrl` in `public/hds-manifest.json`, which `pnpm manifest:generate` sets from the `@figma` tag in the component JSDoc. `pnpm figma:links` keeps this table current and Storybook reads the same field (`parameters.design`). The Figma-side links (dev resources and component descriptions) exist only once someone runs their steps in [`figma/README.md`](figma/README.md).
+
+**1 of 120** components link a Figma node.
+
+| Component | Figma node                                                                                       | Story                                              | Source                                    |
+| --------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ----------------------------------------- |
+| `Alert`   | [33:34](https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=33-34) | [alert.stories.tsx](src/stories/alert.stories.tsx) | [alert.tsx](src/app/components/alert.tsx) |
+
+<!-- design-links:end -->
+
 ## Visual direction: Editorial Enterprise
 
 The governing direction is "Editorial Enterprise" — enterprise rigor with editorial pacing. It favors sharp hierarchy, open whitespace, monochrome neutrals, and a single electric-blue accent. In practice:
@@ -116,26 +172,20 @@ The governing direction is "Editorial Enterprise" — enterprise rigor with edit
 
 ## Verification workflow
 
-Regression prevention is layered:
-
-- `CLAUDE.md` is the operating contract — agent execution protocol, UI guardrails, required validation steps, and the self-heal requirement before a task is considered done.
-- `scripts/self-heal.mjs` (`pnpm run heal`) runs the local static and smoke checks, captures failures, and gives a consistent path to fix type, layout, and runtime drift.
-- The Playwright suite covers accessibility, layout integrity, collision detection, responsiveness, and visual regression, so changes that break containment, overlap, or responsive behavior fail automatically.
+The gates are deterministic and need no browser or live site:
 
-Typical loop:
+- **pre-commit** (`.husky/pre-commit`): secrets scan, Prettier on staged files, typecheck, zero-warning ESLint, and token validity and contrast.
+- **pre-push** (`.husky/pre-push`): Vitest unit and contract tests, then the consumer smoke build (library build, subpath resolution, publint, consumer typecheck).
+- **CI** (`.github/workflows/ci.yml`): typecheck, zero-warning ESLint, token validity and contrast, Vitest, and the consumer smoke build, plus bundle budgets and a Storybook build.
+- **Visual review:** Storybook is the visual verification surface, and Chromatic (`.github/workflows/chromatic.yml`) runs it on pull requests. The earlier browser test suite drove a docs site that no longer exists; it is archived in `tests-archive/`.
 
-1. Change code within the token and component constraints.
-2. Run `pnpm typecheck` and `pnpm run heal`.
-3. Let Playwright catch runtime and visual regressions.
-4. If self-healing fixes a regression, log the root cause and resolution.
-5. Update the verification checklist and ship.
+`CLAUDE.md` is the operating contract for agents working in this repo.
 
 ## Bundle and release hygiene
 
 - `pnpm check:size` builds the library bundle and runs `size-limit`.
-- `pnpm check:release` runs the full release gate (accessibility, responsive, collision, visual, and bundle-size checks).
 
-Releases are cut with [Changesets](https://github.com/changesets/changesets): a merged changeset opens a "Version Packages" PR, and merging that PR publishes the new version to public npm via `.github/workflows/release.yml`.
+Releases are cut with [Changesets](https://github.com/changesets/changesets). A pull request that changes the published package adds a changeset (`pnpm changeset:add`). On a push to `main`, `.github/workflows/release.yml` opens or updates a "Version Packages" PR, and merging that PR publishes the new version to public npm.
 
 ## Repository shape
 
@@ -159,3 +209,7 @@ public/
 - `DESIGN-HANDOFF.md` — verbose visual mirror
 - `TOKEN_GOVERNANCE.md` — token system rules
 - `SYSTEMS_REGISTRY.md` — systems & guardrail registry
+
+## License
+
+The HDS code is MIT ([LICENSE](LICENSE)). The package CSS also embeds the Satoshi and Geist Mono fonts, which keep their own licenses and are not covered by MIT. See [NOTICE.md](NOTICE.md).