banhaten 0.1.2 → 0.2.0

package/docs/design-system/README.md

@@ -0,0 +1,20 @@
+# Banhaten Design System Docs
+
+Use these docs with the live playground.
+
+- [Registry and CLI](./registry-and-cli.md): registry formats, generated-file ownership, CLI commands, and schema behavior.
+- [Installation](./installation.md): Vite, Next.js/framework-neutral setup, fonts, direction, and safe updates.
+- [Token Governance](./token-governance.md): token-only component rules, exception ledger, and public override surface.
+- [Appearance Presets](./appearance-presets.md): theme and radius mode guidance.
+- [Direction and Localization](./direction-and-localization.md): inherited LTR/RTL and product localization responsibilities.
+- [Form Recipes](./form-recipes.md): accessible Field composition, validation, selection, dates, and RTL.
+- [Density and Elevation](./density-and-elevation.md): supported size contracts and semantic shadow layers.
+- [Support Matrix](./support-matrix.md): framework, runtime, browser, font, and package-manager baseline.
+- [Release Policy](./release-policy.md): stability tiers, versioning, deprecation, and launch gates.
+- [Roadmap](./roadmap.md): explicitly deferred product-specific components and promotion gates.
+- [Launch Comparison](./launch-comparison-shadcn.md): the complete shadcn/ui benchmark, remediation register, and deliberate differences.
+- [Component Docs Pattern](./component-docs-pattern.md): the Base / Anatomy / Alternatives shape every playground component page follows.
+- [Components](./components/README.md): component markdown catalog.
+- [Icon System](./icons.md): icon guidance and explorer notes.
+
+The playground remains the primary documentation surface because it renders live registry-backed previews, source snippets, copyable code panels, API tables, file links, and RTL behavior.

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

@@ -0,0 +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.

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

@@ -0,0 +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).

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

@@ -0,0 +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

package/docs/design-system/appearances/default.md

@@ -0,0 +1,94 @@
+# Default Appearance
+
+`default` is the baseline product appearance.
+
+It should feel practical, calm, and balanced: a gray application background, white cards, modest radius, restrained elevation, and conservative spacing.
+
+## Visual Character
+
+- Application background is gray or off-white.
+- Cards and primary content areas are white.
+- Actions and controls have a modest radius.
+- Spacing is comfortable but compact enough for daily product use.
+- Shadows are subtle and used only to separate floating or raised elements.
+
+## Token Direction
+
+```ts
+export const defaultAppearance = {
+  content: {
+    default: "#171717",
+    primary: "#000000",
+    subtle: "#404040",
+    muted: "#737373",
+    disabled: "#a3a3a3",
+    inverse: "#ffffff",
+    link: "#1d4ed8",
+    linkHover: "#1e40af",
+    onColor: "#ffffff",
+    onLight: "#171717",
+    onBrand: "#ffffff",
+  },
+  background: {
+    app: "#f4f4f5",
+    default: "#ffffff",
+    card: "#ffffff",
+    subtle: "#fafafa",
+    muted: "#f5f5f5",
+    disabled: "#e5e5e5",
+    inverse: "#171717",
+    overlay: "rgba(23, 23, 23, 0.48)",
+    brand: "#171717",
+    brandHover: "#262626",
+    brandPressed: "#0a0a0a",
+    selected: "#e5e7eb",
+    hover: "#f5f5f5",
+    pressed: "#e5e5e5",
+  },
+  border: {
+    default: "#d4d4d4",
+    subtle: "#e5e5e5",
+    strong: "#a3a3a3",
+    disabled: "#e5e5e5",
+    focus: "#2563eb",
+    brand: "#171717",
+  },
+  shape: {
+    action: "10px",
+    control: "10px",
+    card: "12px",
+    panel: "12px",
+    modal: "16px",
+    popover: "12px",
+    badge: "999px",
+    avatar: "999px",
+  },
+  density: {
+    controlHeight: "40px",
+    controlPaddingX: "14px",
+    cardPadding: "20px",
+    panelPadding: "20px",
+    sectionGap: "24px",
+    listRowHeight: "44px",
+    tableRowHeight: "44px",
+  },
+  elevation: {
+    card: "0 1px 2px rgba(0, 0, 0, 0.04)",
+    panel: "0 1px 3px rgba(0, 0, 0, 0.06)",
+    popover: "0 12px 28px rgba(0, 0, 0, 0.14)",
+    modal: "0 24px 64px rgba(0, 0, 0, 0.20)",
+    none: "none",
+  },
+};
+```
+
+## Component Impact
+
+- Buttons: modest radius, dark primary action, balanced padding.
+- Breadcrumbs: inline trails stay quiet; raised trails use `background.card`, `border.subtle`, and the modest control radius.
+- Inputs: modest radius, visible but quiet border.
+- Cards: white on gray app background, subtle border or shadow.
+- Dividers: quiet 1px separators using `border.subtle`, with compact spacing around labels or inline actions.
+- File uploads: subtle dashed drop zones with white queued rows, modest radius, and quiet row elevation.
+- Modals and popovers: slightly more radius than inline components.
+- Tables and lists: normal row height for readable operational screens.

package/docs/design-system/appearances/rounded.md

@@ -0,0 +1,95 @@
+# Rounded Appearance
+
+`rounded` is the softer appearance.
+
+It should feel open, approachable, and more polished: a white application background, larger radii, softer borders, relaxed spacing, and less visual heaviness.
+
+## Visual Character
+
+- Application background is white.
+- Cards use white or near-white backgrounds with light borders.
+- Primary actions can be pill-shaped.
+- Panels and cards have visibly larger radius.
+- Spacing is a little more relaxed than `default`.
+- Shadows are soft and optional.
+
+## Token Direction
+
+```ts
+export const roundedAppearance = {
+  content: {
+    default: "#18181b",
+    primary: "#09090b",
+    subtle: "#52525b",
+    muted: "#71717a",
+    disabled: "#a1a1aa",
+    inverse: "#ffffff",
+    link: "#0f766e",
+    linkHover: "#115e59",
+    onColor: "#ffffff",
+    onLight: "#18181b",
+    onBrand: "#ffffff",
+  },
+  background: {
+    app: "#ffffff",
+    default: "#ffffff",
+    card: "#ffffff",
+    subtle: "#fafafa",
+    muted: "#f6f7f7",
+    disabled: "#e4e4e7",
+    inverse: "#18181b",
+    overlay: "rgba(24, 24, 27, 0.42)",
+    brand: "#0f766e",
+    brandHover: "#115e59",
+    brandPressed: "#134e4a",
+    selected: "#ccfbf1",
+    hover: "#f4f7f6",
+    pressed: "#e7f3f0",
+  },
+  border: {
+    default: "#dedede",
+    subtle: "#eeeeee",
+    strong: "#b8b8b8",
+    disabled: "#e4e4e7",
+    focus: "#0f766e",
+    brand: "#0f766e",
+  },
+  shape: {
+    action: "999px",
+    control: "16px",
+    card: "22px",
+    panel: "24px",
+    modal: "28px",
+    popover: "20px",
+    badge: "999px",
+    avatar: "999px",
+  },
+  density: {
+    controlHeight: "44px",
+    controlPaddingX: "18px",
+    cardPadding: "24px",
+    panelPadding: "24px",
+    sectionGap: "32px",
+    listRowHeight: "48px",
+    tableRowHeight: "48px",
+  },
+  elevation: {
+    card: "0 8px 24px rgba(15, 23, 42, 0.06)",
+    panel: "0 10px 32px rgba(15, 23, 42, 0.08)",
+    popover: "0 18px 40px rgba(15, 23, 42, 0.16)",
+    modal: "0 28px 72px rgba(15, 23, 42, 0.22)",
+    none: "none",
+  },
+};
+```
+
+## Component Impact
+
+- Buttons: pill-like primary and action buttons.
+- Breadcrumbs: raised trails inherit the softer control radius and can use slightly more relaxed spacing.
+- Inputs: rounded controls with slightly taller height.
+- Cards: larger radius with light borders and soft separation.
+- Dividers: quiet 1px separators using `border.subtle`, with softer action backgrounds and the preset control radius.
+- File uploads: softer drop zones and queued rows, relaxed padding, and gentle borders.
+- Modals and popovers: rounded, friendly containers.
+- Tables and lists: slightly more vertical breathing room.

package/docs/design-system/appearances/sharp.md

@@ -0,0 +1,95 @@
+# Sharp Appearance
+
+`sharp` is the precise appearance.
+
+It should feel structured, architectural, and efficient: square edges, tighter spacing, stronger borders, flatter surfaces, and minimal elevation.
+
+## Visual Character
+
+- Application background can be white or a very light gray.
+- Cards are flat panels with clear borders.
+- Radius is zero or nearly zero across most UI.
+- Spacing is tighter than `default`.
+- Borders carry most of the separation work.
+- Shadows are reserved for overlays only.
+
+## Token Direction
+
+```ts
+export const sharpAppearance = {
+  content: {
+    default: "#111111",
+    primary: "#000000",
+    subtle: "#3f3f46",
+    muted: "#6b7280",
+    disabled: "#9ca3af",
+    inverse: "#ffffff",
+    link: "#7c2d12",
+    linkHover: "#431407",
+    onColor: "#ffffff",
+    onLight: "#111111",
+    onBrand: "#ffffff",
+  },
+  background: {
+    app: "#f7f7f7",
+    default: "#ffffff",
+    card: "#ffffff",
+    subtle: "#f9fafb",
+    muted: "#f3f4f6",
+    disabled: "#e5e7eb",
+    inverse: "#111111",
+    overlay: "rgba(17, 17, 17, 0.52)",
+    brand: "#111111",
+    brandHover: "#262626",
+    brandPressed: "#000000",
+    selected: "#e5e7eb",
+    hover: "#f3f4f6",
+    pressed: "#e5e7eb",
+  },
+  border: {
+    default: "#c7c7c7",
+    subtle: "#dedede",
+    strong: "#737373",
+    disabled: "#dedede",
+    focus: "#111111",
+    brand: "#111111",
+  },
+  shape: {
+    action: "0px",
+    control: "0px",
+    card: "0px",
+    panel: "0px",
+    modal: "0px",
+    popover: "0px",
+    badge: "2px",
+    avatar: "0px",
+  },
+  density: {
+    controlHeight: "38px",
+    controlPaddingX: "12px",
+    cardPadding: "16px",
+    panelPadding: "16px",
+    sectionGap: "20px",
+    listRowHeight: "40px",
+    tableRowHeight: "38px",
+  },
+  elevation: {
+    card: "none",
+    panel: "none",
+    popover: "0 12px 24px rgba(0, 0, 0, 0.18)",
+    modal: "0 20px 56px rgba(0, 0, 0, 0.24)",
+    none: "none",
+  },
+};
+```
+
+## Component Impact
+
+- Buttons: square edges, compact padding, strong hover and pressed states.
+- Breadcrumbs: raised trails use square or near-square corners with tight separator rhythm.
+- Inputs: square controls with clear border states.
+- Cards: flat panels with borders instead of visible rounding.
+- Dividers: clear 1px separators using `border.subtle`, with square action treatment and tight spacing.
+- File uploads: precise dashed drop zones, square queued rows, tighter spacing, and border-led error states.
+- Modals and popovers: square containers with overlay separation.
+- Tables and lists: denser rows for scanning and comparison.

package/docs/design-system/component-docs-pattern.md

@@ -0,0 +1,81 @@
+# Component documentation pattern
+
+Every component page in the playground renders through one shell so the docs
+read the same way from component to component. A page is not "documented" until
+it follows this shape.
+
+## The shape
+
+```
+Header
+Anchor nav
+1. Base           the component with no options applied
+2. Anatomy        live-measured specs, mapped back to tokens
+3. Alternatives   every supported variation, one card each
+4. Installation / Usage / Composition / API / RTL / Live Variants
+```
+
+Sections 4 and below are generated from `registry/index.json` by
+`RegistryComponentDocs`. Sections 1 to 3 are authored per component.
+
+## Writing a page
+
+```tsx
+import { ComponentDocPage, type DocAlternative } from "./shared/component-doc-page"
+
+export function BadgePage({ tokens }: { tokens: Record<string, string> }) {
+  return (
+    <ComponentDocPage
+      componentId="badge"
+      title="Badge"
+      description="…"
+      tokens={tokens}
+      base={{ children: <Badge>Badge</Badge>, code: baseCode }}
+      anatomy={{
+        options: [
+          { id: "size", label: "Size", values: [{ id: "sm", label: "sm" }, { id: "lg", label: "lg" }] },
+          { id: "type", label: "Type", values: […] },
+        ],
+        render: (selection) => <Badge size={selection.size as "sm" | "lg"}>Badge</Badge>,
+      }}
+      alternatives={badgeAlternatives}
+    />
+  )
+}
+```
+
+`playground/src/pages/BadgePage.tsx` is the reference implementation.
+
+## Anatomy
+
+The inspector in `playground/src/pages/shared/anatomy/` measures the rendered
+DOM rather than reading hand-written numbers, so a spec can never drift from the
+component that ships.
+
+- The **first** option group becomes the rows of the spec matrix. Every value in
+  it is rendered off-screen and measured, so the matrix shows all sizes at once.
+- Remaining groups become scrub toggles.
+- Hovering a spec value highlights the matching segment on the diagram; hovering
+  a row switches the diagram to that variant.
+- Each measured value is reverse-mapped to the `--bh-*` token that produced it.
+  A value with no matching token renders in the warning color with a `!` — that
+  is a real finding, not a display bug: it means the component hard-codes a
+  length instead of using the scale.
+- Rulers and offsets are logical, so the whole diagram mirrors correctly in RTL
+  while the measurements stay identical.
+
+Pass `measureSelector` when the rendered root is a wrapper rather than the
+component itself.
+
+Omit `anatomy` only for components with no inline measurable root: portal-only
+overlays and canvas-style components.
+
+## Enforcement
+
+`playground/e2e/docs-consistency.spec.ts` asserts that every component and
+pattern page renders a Base section, an Alternatives section, and an Anatomy
+inspector with at least one measured row, and logs no console errors.
+
+```bash
+npm --prefix playground run test:browser
+```