banhaten 0.5.0 → 0.6.0

package/docs/design-system/adoption-quality-remediation.md

@@ -1,87 +1,87 @@
-# Adoption Quality Remediation
-
-This checklist turns the Field Index audit into an implementation program. The
-work is ordered so application recipes depend on stable component contracts,
-and enforcement depends on documented recipes.
-
-## 1. Shared control density
-
-- [x] Add the semantic densities `compact` (32px), `default` (36px), and
-  `comfortable` (40px) to Input, Select, Date Picker, Button, Button Group,
-  Segmented Control, and Toolbar controls.
-- [x] Keep existing component-specific `size` props as compatibility aliases.
-- [x] Add a cross-component conformance example and automated height checks.
-- [x] Document the semantic density matrix and precedence rules.
-
-Acceptance: controls using the same `density` render at the same physical
-height, regardless of their legacy size names.
-
-## 2. Truthful machine-readable defaults
-
-- [x] Add explicit capability defaults to the registry schema.
-- [x] Stop inferring defaults from the first capability value.
-- [x] Record explicit defaults for the control family.
-- [x] Validate that every recorded default belongs to its capability list.
-
-Acceptance: generated API documentation agrees with runtime defaults.
-
-## 3. Input icon and shortcut contracts
-
-- [x] Replace ambiguous icon booleans with explicit `showAtSign` and `showInfo`
-  props while retaining deprecated aliases.
-- [x] Add a reusable keyboard-shortcut composition to Kbd.
-- [x] Make Input and Toolbar Search use the shared shortcut composition.
-- [x] Document search fields and date fields without implicit icons.
-
-Acceptance: a generic leading-icon request can no longer accidentally produce
-an at-sign in new code, and shortcuts use consistent keycaps.
-
-## 4. Segmented selection and application recipes
-
-- [x] Add a content-width Segmented Control with an optional non-interactive
-  label segment.
-- [x] Add a canonical Collection Filter Bar recipe.
-- [x] Add a canonical Results Toolbar recipe with cards-per-row selection.
-- [x] Cover responsive, LTR, and RTL compositions.
-
-Acceptance: the controls visible in the Field Index screenshot can be composed
-without raw heights, padding, radii, or bespoke segmented buttons.
-
-## 5. Agent and consumer adoption contract
-
-- [x] Install `.banhaten/USAGE.md` during `banhaten init`.
-- [x] Add machine-readable recommendation and avoidance guidance to relevant
-  registry entries.
-- [x] Add a read-only `banhaten doctor` command for version, drift, raw control
-  geometry, ambiguous icon props, and native-control diagnostics.
-- [x] Test text and JSON doctor output.
-
-Acceptance: an agent receives actionable rules before composing a page, and a
-consumer can detect the most common forms of design-system drift.
-
-## 6. Documentation reliability
-
-- [x] Replace fixed multi-column component grids with container-safe layouts.
-- [x] Make documentation section anchors compatible with the hash router.
-- [x] Stabilize calendar tests by controlling the displayed month.
-- [x] Add navigation and overflow regression tests.
-
-Acceptance: documentation examples do not overlap and section links preserve
-the active component page.
-
-## 7. Visual and governance gates
-
-- [x] Add visual baselines for the control family and the two golden recipes.
-- [x] Add critical control-text contrast checks rather than relying only on the
-  frozen global contrast debt.
-- [x] Generate a recurring-gap promotion report from background scenarios.
-- [x] Document the promotion rule for gaps that recur in three or more
-  backgrounds.
-
-Acceptance: component-family drift fails CI, critical controls have explicit
-contrast protection, and recurring application gaps become owned system work.
-
-## Validation
-
-- [x] Registry, token, documentation, CLI, component, and browser checks pass.
-- [x] The repository remains free of generated-artifact drift.
+# Adoption Quality Remediation
+
+This checklist turns the Field Index audit into an implementation program. The
+work is ordered so application recipes depend on stable component contracts,
+and enforcement depends on documented recipes.
+
+## 1. Shared control density
+
+- [x] Add the semantic densities `compact` (32px), `default` (36px), and
+  `comfortable` (40px) to Input, Select, Date Picker, Button, Button Group,
+  Segmented Control, and Toolbar controls.
+- [x] Keep existing component-specific `size` props as compatibility aliases.
+- [x] Add a cross-component conformance example and automated height checks.
+- [x] Document the semantic density matrix and precedence rules.
+
+Acceptance: controls using the same `density` render at the same physical
+height, regardless of their legacy size names.
+
+## 2. Truthful machine-readable defaults
+
+- [x] Add explicit capability defaults to the registry schema.
+- [x] Stop inferring defaults from the first capability value.
+- [x] Record explicit defaults for the control family.
+- [x] Validate that every recorded default belongs to its capability list.
+
+Acceptance: generated API documentation agrees with runtime defaults.
+
+## 3. Input icon and shortcut contracts
+
+- [x] Replace ambiguous icon booleans with explicit `showAtSign` and `showInfo`
+  props while retaining deprecated aliases.
+- [x] Add a reusable keyboard-shortcut composition to Kbd.
+- [x] Make Input and Toolbar Search use the shared shortcut composition.
+- [x] Document search fields and date fields without implicit icons.
+
+Acceptance: a generic leading-icon request can no longer accidentally produce
+an at-sign in new code, and shortcuts use consistent keycaps.
+
+## 4. Segmented selection and application recipes
+
+- [x] Add a content-width Segmented Control with an optional non-interactive
+  label segment.
+- [x] Add a canonical Collection Filter Bar recipe.
+- [x] Add a canonical Results Toolbar recipe with cards-per-row selection.
+- [x] Cover responsive, LTR, and RTL compositions.
+
+Acceptance: the controls visible in the Field Index screenshot can be composed
+without raw heights, padding, radii, or bespoke segmented buttons.
+
+## 5. Agent and consumer adoption contract
+
+- [x] Install `.banhaten/USAGE.md` during `banhaten init`.
+- [x] Add machine-readable recommendation and avoidance guidance to relevant
+  registry entries.
+- [x] Add a read-only `banhaten doctor` command for version, drift, raw control
+  geometry, ambiguous icon props, and native-control diagnostics.
+- [x] Test text and JSON doctor output.
+
+Acceptance: an agent receives actionable rules before composing a page, and a
+consumer can detect the most common forms of design-system drift.
+
+## 6. Documentation reliability
+
+- [x] Replace fixed multi-column component grids with container-safe layouts.
+- [x] Make documentation section anchors compatible with the hash router.
+- [x] Stabilize calendar tests by controlling the displayed month.
+- [x] Add navigation and overflow regression tests.
+
+Acceptance: documentation examples do not overlap and section links preserve
+the active component page.
+
+## 7. Visual and governance gates
+
+- [x] Add visual baselines for the control family and the two golden recipes.
+- [x] Add critical control-text contrast checks rather than relying only on the
+  frozen global contrast debt.
+- [x] Generate a recurring-gap promotion report from background scenarios.
+- [x] Document the promotion rule for gaps that recur in three or more
+  backgrounds.
+
+Acceptance: component-family drift fails CI, critical controls have explicit
+contrast protection, and recurring application gaps become owned system work.
+
+## Validation
+
+- [x] Registry, token, documentation, CLI, component, and browser checks pass.
+- [x] The repository remains free of generated-artifact drift.

package/docs/design-system/agent-usage.md

@@ -1,13 +1,13 @@
-# Agent usage
-
-`banhaten init` installs `.banhaten/USAGE.md` into every consumer project. Include that file in coding-agent context so generated and redesigned screens use registry defaults and recipes instead of reconstructing the visual language from memory.
-
-The workflow is intentionally inspectable:
-
-1. `banhaten search <need>` discovers the intended primitive.
-2. `banhaten docs <component>` returns explicit defaults, fit guidance, avoid rules, and recipes.
-3. `banhaten view <component>` exposes the installed source contract.
-4. `banhaten doctor` reports installed-version drift, local managed-file drift, deprecated ambiguous props, raw geometry overrides, native date/select controls, and missing guidance.
-5. `banhaten diff` previews registry updates without writing.
-
-For collection screens, start with the filter-bar and results-toolbar recipes in [Form Recipes](./form-recipes.md). For mixed control rows, follow [Density and Elevation](./density-and-elevation.md).
+# Agent usage
+
+`banhaten init` installs `.banhaten/USAGE.md` into every consumer project. Include that file in coding-agent context so generated and redesigned screens use registry defaults and recipes instead of reconstructing the visual language from memory.
+
+The workflow is intentionally inspectable:
+
+1. `banhaten search <need>` discovers the intended primitive.
+2. `banhaten docs <component>` returns explicit defaults, fit guidance, avoid rules, and recipes.
+3. `banhaten view <component>` exposes the installed source contract.
+4. `banhaten doctor` reports installed-version drift, local managed-file drift, deprecated ambiguous props, raw geometry overrides, native date/select controls, and missing guidance.
+5. `banhaten diff` previews registry updates without writing.
+
+For collection screens, start with the filter-bar and results-toolbar recipes in [Form Recipes](./form-recipes.md). For mixed control rows, follow [Density and Elevation](./density-and-elevation.md).

package/docs/design-system/appearance-presets.md

@@ -1,189 +1,189 @@
-# Appearance Presets
-
-Appearance presets change the feel of the design system without changing component APIs.
-
-Components keep semantic variants such as `primary`, `secondary`, `subtle`, `danger`, and `ghost`. Presets decide how those meanings look through design tokens: color, radius, density, border, and elevation.
-
-## Presets
-
-- `default`: The baseline product UI. Gray application background, white cards, modest radius, conservative spacing.
-- `rounded`: A softer UI. White application background, stronger radius, relaxed spacing, gentler separation.
-- `sharp`: A precise UI. Square edges, tighter spacing, clearer borders, minimal elevation.
-
-Each preset has its own markdown file:
-
-- [Default](./appearances/default.md)
-- [Rounded](./appearances/rounded.md)
-- [Sharp](./appearances/sharp.md)
-
-Component specs:
-
-- [Icons](./icons.md)
-- [Tabs](./tabs.md)
-- [Tag](./components/tag.md)
-- [Timeline](./components/timeline.md)
-
-Component guidance lives in:
-
-- [Components](./components/README.md)
-- [Banner](./components/banner.md)
-- [Breadcrumbs](./components/breadcrumbs.md)
-- [Divider](./components/divider.md)
-- [File Upload](./components/file-upload.md)
-- [Tag](./components/tag.md)
-- [Timeline](./components/timeline.md)
-
-## Token Contract
-
-The design system should use semantic tokens instead of importing naming patterns from a framework. Tokens describe where they are used, not how they happen to look in one theme.
-
-### Content
-
-`content` tokens apply to text and icons.
-
-- `content.default`
-- `content.primary`
-- `content.subtle`
-- `content.muted`
-- `content.disabled`
-- `content.inverse`
-- `content.link`
-- `content.linkHover`
-- `content.onColor`
-- `content.onLight`
-- `content.onBrand`
-- `content.success`
-- `content.warning`
-- `content.danger`
-
-### Background
-
-`background` tokens apply to page, layout, component, and interactive fills.
-
-- `background.app`
-- `background.default`
-- `background.card`
-- `background.subtle`
-- `background.muted`
-- `background.disabled`
-- `background.inverse`
-- `background.overlay`
-- `background.brand`
-- `background.brandHover`
-- `background.brandPressed`
-- `background.selected`
-- `background.hover`
-- `background.pressed`
-- `background.success`
-- `background.warning`
-- `background.danger`
-
-### Border
-
-`border` tokens apply to component outlines, dividers, focus states, and validation states.
-
-- `border.default`
-- `border.subtle`
-- `border.strong`
-- `border.disabled`
-- `border.focus`
-- `border.brand`
-- `border.success`
-- `border.warning`
-- `border.danger`
-
-### Shape
-
-`shape` tokens control radius by usage, not component name.
-
-- `shape.action`
-- `shape.control`
-- `shape.card`
-- `shape.panel`
-- `shape.modal`
-- `shape.popover`
-- `shape.badge`
-- `shape.avatar`
-
-### Density
-
-`density` tokens control repeated spacing and sizing decisions.
-
-- `density.controlHeight`
-- `density.controlPaddingX`
-- `density.cardPadding`
-- `density.panelPadding`
-- `density.sectionGap`
-- `density.listRowHeight`
-- `density.tableRowHeight`
-
-### Elevation
-
-`elevation` tokens control shadows and stacking treatment.
-
-- `elevation.card`
-- `elevation.panel`
-- `elevation.popover`
-- `elevation.modal`
-- `elevation.none`
-
-## Component Rule
-
-Components consume semantic tokens and component-scoped aliases. They must not hard-code preset-specific values or Figma fallback literals in component source.
-
-If a Figma reference exposes a literal color, size, radius, shadow, or opacity,
-promote it into the appropriate owned fragment under `tokens/source/`, then
-consume that token from the component. Reserve `tokens/banhaten.utilities.css`
-for authored global CSS that cannot be represented as token data. Component
-docs may record Figma references for audit and QA, but those literals are not
-implementation fallbacks.
-
-Good:
-
-```tsx
-<Button variant="primary" />
-<Card />
-```
-
-Avoid:
-
-```tsx
-<Button rounded />
-<Card sharp />
-<Card className="rounded-[16px]" />
-```
-
-The preset is selected at the design-system root:
-
-```tsx
-<DesignSystemProvider appearance="default">
-  <App />
-</DesignSystemProvider>
-```
-
-or through a root attribute:
-
-```html
-<body data-appearance="default">
-```
-
-## Preset Responsibilities
-
-An appearance preset may change:
-
-- Page and layout background treatment
-- Card and panel background treatment
-- Radius for actions, controls, cards, modals, popovers, badges, and tabs
-- Component density and padding
-- Border prominence
-- Elevation and shadow strength
-- Hover, pressed, selected, and disabled treatment
-
-An appearance preset should not change:
-
-- Component behavior
-- Component variant names
-- Accessibility requirements
-- Interaction contracts
-- Information hierarchy
-- Meaning of semantic color roles
+# Appearance Presets
+
+Appearance presets change the feel of the design system without changing component APIs.
+
+Components keep semantic variants such as `primary`, `secondary`, `subtle`, `danger`, and `ghost`. Presets decide how those meanings look through design tokens: color, radius, density, border, and elevation.
+
+## Presets
+
+- `default`: The baseline product UI. Gray application background, white cards, modest radius, conservative spacing.
+- `rounded`: A softer UI. White application background, stronger radius, relaxed spacing, gentler separation.
+- `sharp`: A precise UI. Square edges, tighter spacing, clearer borders, minimal elevation.
+
+Each preset has its own markdown file:
+
+- [Default](./appearances/default.md)
+- [Rounded](./appearances/rounded.md)
+- [Sharp](./appearances/sharp.md)
+
+Component specs:
+
+- [Icons](./icons.md)
+- [Tabs](./tabs.md)
+- [Tag](./components/tag.md)
+- [Timeline](./components/timeline.md)
+
+Component guidance lives in:
+
+- [Components](./components/README.md)
+- [Banner](./components/banner.md)
+- [Breadcrumbs](./components/breadcrumbs.md)
+- [Divider](./components/divider.md)
+- [File Upload](./components/file-upload.md)
+- [Tag](./components/tag.md)
+- [Timeline](./components/timeline.md)
+
+## Token Contract
+
+The design system should use semantic tokens instead of importing naming patterns from a framework. Tokens describe where they are used, not how they happen to look in one theme.
+
+### Content
+
+`content` tokens apply to text and icons.
+
+- `content.default`
+- `content.primary`
+- `content.subtle`
+- `content.muted`
+- `content.disabled`
+- `content.inverse`
+- `content.link`
+- `content.linkHover`
+- `content.onColor`
+- `content.onLight`
+- `content.onBrand`
+- `content.success`
+- `content.warning`
+- `content.danger`
+
+### Background
+
+`background` tokens apply to page, layout, component, and interactive fills.
+
+- `background.app`
+- `background.default`
+- `background.card`
+- `background.subtle`
+- `background.muted`
+- `background.disabled`
+- `background.inverse`
+- `background.overlay`
+- `background.brand`
+- `background.brandHover`
+- `background.brandPressed`
+- `background.selected`
+- `background.hover`
+- `background.pressed`
+- `background.success`
+- `background.warning`
+- `background.danger`
+
+### Border
+
+`border` tokens apply to component outlines, dividers, focus states, and validation states.
+
+- `border.default`
+- `border.subtle`
+- `border.strong`
+- `border.disabled`
+- `border.focus`
+- `border.brand`
+- `border.success`
+- `border.warning`
+- `border.danger`
+
+### Shape
+
+`shape` tokens control radius by usage, not component name.
+
+- `shape.action`
+- `shape.control`
+- `shape.card`
+- `shape.panel`
+- `shape.modal`
+- `shape.popover`
+- `shape.badge`
+- `shape.avatar`
+
+### Density
+
+`density` tokens control repeated spacing and sizing decisions.
+
+- `density.controlHeight`
+- `density.controlPaddingX`
+- `density.cardPadding`
+- `density.panelPadding`
+- `density.sectionGap`
+- `density.listRowHeight`
+- `density.tableRowHeight`
+
+### Elevation
+
+`elevation` tokens control shadows and stacking treatment.
+
+- `elevation.card`
+- `elevation.panel`
+- `elevation.popover`
+- `elevation.modal`
+- `elevation.none`
+
+## Component Rule
+
+Components consume semantic tokens and component-scoped aliases. They must not hard-code preset-specific values or Figma fallback literals in component source.
+
+If a Figma reference exposes a literal color, size, radius, shadow, or opacity,
+promote it into the appropriate owned fragment under `tokens/source/`, then
+consume that token from the component. Reserve `tokens/banhaten.utilities.css`
+for authored global CSS that cannot be represented as token data. Component
+docs may record Figma references for audit and QA, but those literals are not
+implementation fallbacks.
+
+Good:
+
+```tsx
+<Button variant="primary" />
+<Card />
+```
+
+Avoid:
+
+```tsx
+<Button rounded />
+<Card sharp />
+<Card className="rounded-[16px]" />
+```
+
+The preset is selected at the design-system root:
+
+```tsx
+<DesignSystemProvider appearance="default">
+  <App />
+</DesignSystemProvider>
+```
+
+or through a root attribute:
+
+```html
+<body data-appearance="default">
+```
+
+## Preset Responsibilities
+
+An appearance preset may change:
+
+- Page and layout background treatment
+- Card and panel background treatment
+- Radius for actions, controls, cards, modals, popovers, badges, and tabs
+- Component density and padding
+- Border prominence
+- Elevation and shadow strength
+- Hover, pressed, selected, and disabled treatment
+
+An appearance preset should not change:
+
+- Component behavior
+- Component variant names
+- Accessibility requirements
+- Interaction contracts
+- Information hierarchy
+- Meaning of semantic color roles