@hirobius/design-system 0.8.1 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
-# Hirobius Design System V2
+# Hirobius Design System
 
-Hirobius is a portfolio-grade design-system product surface: a React and TypeScript site, a governed component library, a token pipeline, and an autonomous verification loop living in one repository.
+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.
 
 ## Using the published package
 
@@ -46,58 +46,54 @@ pnpm test:layout
 pnpm check:size
 ```
 
-## HDS V2 architecture
+## Architecture
 
-HDS V2 is built around three structural rules:
+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.
-- Polymorphism: primitives are expected to preserve semantic HTML while staying composable through governed APIs such as `forwardRef`, `as`, and layout slots.
-- 12-column grid: page structure is organized around a consistent editorial grid, with readable center columns, intentional breakout zones, and explicit `gap` ownership rather than one-off spacing math.
+- **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.
+- **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.
 
-This repo treats the following files as source of truth:
+Source-of-truth files:
 
-- `hirobius.tokens.json`: token values and alias chain.
-- `public/hds-manifest.json`: machine-readable system inventory, metadata, and docs linkage.
-- `src/app/data/component-api.json`: generated prop tables and reflected component API.
-- `DESIGN.md`: lean visual spec for agents and engineers.
-- `DESIGN-HANDOFF.md`: verbose visual mirror for handoff and review.
+- `hirobius.tokens.json` — token values and alias chain.
+- `public/hds-manifest.json` — machine-readable system inventory, metadata, and docs linkage.
+- `src/app/data/component-api.json` — generated prop tables and reflected component API.
+- `DESIGN.md` — lean visual spec for agents and engineers.
+- `DESIGN-HANDOFF.md` — verbose visual mirror for handoff and review.
 
-## Editorial Enterprise philosophy
+## Visual direction: Editorial Enterprise
 
-The governing visual direction is "Editorial Enterprise": enterprise-grade rigor with editorial pacing and restraint. The system favors sharp hierarchy, open whitespace, disciplined monochrome neutrals, and a single electric-blue accent. Layouts should feel authored rather than templated.
-
-In practice that means:
+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:
 
 - documentation reads like a designed publication, not a component dump
 - cards are used sparingly; whitespace, rails, dividers, and bands carry structure first
-- motion teaches or clarifies instead of decorating
-- surfaces, spacing, and type are token-governed so the visual language stays coherent across portfolio pages and HDS docs
-
-## Autonomous agentic workflow
-
-Regression prevention is intentionally layered.
+- motion clarifies rather than decorates
+- surfaces, spacing, and type are token-governed, so the visual language stays coherent across the docs site and any consuming app
 
-`CLAUDE.md` is the operating contract. It defines the agent execution protocol, permanent UI guardrails, required validation steps, and the self-heal requirement before a task can be marked complete.
+## Verification workflow
 
-`scripts/self-heal.mjs` is the automated repair loop. It runs the local static and smoke checks, captures failures, and gives the agent a consistent path to diagnose and fix type, layout, and runtime drift before reporting completion.
+Regression prevention is layered:
 
-The Playwright guardrails enforce the visual constitution at runtime. The current suite covers accessibility, layout integrity, collision detection, responsiveness, and visual regression so changes that violate containment, overlap, or responsive behavior fail automatically.
+- `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.
 
-Together the workflow is:
+Typical loop:
 
-1. Change code inside the token and component constraints.
+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 a regression is fixed through self-healing, log the root cause and resolution.
-5. Only then update the verification checklist and ship the change.
+4. If self-healing fixes a regression, log the root cause and resolution.
+5. Update the verification checklist and ship.
 
 ## Bundle and release hygiene
 
-This repo tracks both runtime quality and size drift:
-
 - `pnpm check:size` builds the library bundle and runs `size-limit`.
 - `pnpm perf:budget` runs Lighthouse CI assertions for page performance budgets.
-- `pnpm check:release` runs the full release gate, including accessibility, responsive, collision, visual, and bundle-size checks.
+- `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`.
 
 ## Repository shape
 
@@ -116,9 +112,8 @@ public/
 ## Primary docs
 
 - [`docs/CONSUMING.md`](docs/CONSUMING.md) — installing & using the published package
-- `CLAUDE.md`
-- `DESIGN.md`
-- `DESIGN-HANDOFF.md`
-- `TASKS.md`
-- `TOKEN_GOVERNANCE.md`
-- `SYSTEMS_REGISTRY.md`
+- `CLAUDE.md` — agent operating contract
+- `DESIGN.md` — lean visual spec
+- `DESIGN-HANDOFF.md` — verbose visual mirror
+- `TOKEN_GOVERNANCE.md` — token system rules
+- `SYSTEMS_REGISTRY.md` — systems & guardrail registry