banhaten 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable Banhaten changes are recorded here. Releases follow the policy in `docs/design-system/release-policy.md`.
+
+## 0.3.0 - 2026-08-21
+
+### Added
+
+- `ActivityHeatmap`, a token-only expanded component with five intensity levels, accessible summary semantics, responsive overflow, inherited RTL behavior, registry metadata, documentation, and an installable example.
+- Public `CardSurface`, semantic table-element exports, and `ProgressSteps` APIs for owned product composition without bypassing Banhaten primitives.
+- An AST-backed component-ownership gate plus route-wide accessibility, inherited-RTL containment, and deterministic visual-regression coverage for every component page.
+
+### Changed
+
+- Expanded components and all 38 audited playground backgrounds now compose Banhaten-owned controls; Alert, Page Header, and Slideout declare their new Button and Breadcrumbs registry dependencies.
+- Direction inheritance, narrow-layout containment, focus behavior, and machine-readable RTL contracts were completed across the 68-component catalog.
+- Elevation and color-mode sources were consolidated around shared semantic effects, and the canonical contrast audit was expanded to 910 passing scenarios.
+- Page Header accepts `headingLevel`; Timeline labels and captions accept React nodes; horizontal timelines are keyboard-scrollable and standalone `TimelineItem` semantics are now caller-controlled.
+
+### Fixed
+
+- ARIA ownership, naming, focus, landmark, and relationship defects across Date Picker, Select, Command, Tabs, Field, Table, Menu, Carousel, Sidebar, Slideout, Timeline, and composed documentation examples.
+- Contrast failures across component states and themes, including focus indicators, selected states, badges, tags, alerts, banners, toggles, social buttons, and tables.
+- Inherited-RTL and 324px containment defects in activity, navigation, form, data-display, and expanded layout components.
+
+### Migration
+
+- `SidebarInset` now renders a neutral `div` instead of an implicit `main`. When the inset is the page landmark, render your own `<main>` through `<SidebarInset asChild><main>...</main></SidebarInset>`.
+- `Slideout` is an explicitly named presentational region. Use `Sheet` or `Modal` when the experience requires a portal, overlay, focus trap, Escape dismissal, and focus return.
+- A standalone `TimelineItem` no longer assumes `role="listitem"`; use it inside `Timeline` or pass an explicit role when composing your own list.
+- Run `npx banhaten diff` before `npx banhaten update`, then review locally customized generated files before using `--force`.
+
+## 0.2.0 - 2026-08-08
+
+### Added
+
+- Canonical JSON-driven token generation and strict component token enforcement.
+- Color Contrast documentation covering every audited theme, mode, foreground, and background scenario.
+- Item and Toggle Group primitives, inherited direction context, Arabic font installation, and named categorical chart tokens.
+- Receipt-backed CLI drift protection, unified diffs, and isolated compilation for every registry component.
+- Documentation search, token search/copy, stable component and pattern separation, and dedicated lab navigation.
+- `SegmentedControl` and `KbdShortcut` primitives with accessibility, RTL, registry metadata, examples, and tests.
+- Semantic `compact`, `default`, and `comfortable` density across Button, Input, Select, DatePicker, ButtonGroup, SegmentedControl, and Toolbar controls.
+- Canonical collection-filter, results-toolbar, and control-density recipes with accessibility and visual-regression coverage.
+- Install-time coding-agent guidance, a read-only `banhaten doctor` adoption audit, and recurring-gap promotion reporting.
+
+### Changed
+
+- Production components no longer invent demo content, fake actions, or fixed sample dates.
+- Input and Select no longer invent optional leading, information, or trailing icons when those props are omitted; explicit flags retain the previous built-in adornments.
+- Registry component metadata now publishes machine-readable prop types, rendered defaults, and descriptions for optional visual slots.
+- Registry component token metadata is generated from source references.
+- Pagination, OTP, Carousel, Alert, and Toast direction behavior now resolves from explicit props, provider context, or the nearest document boundary.
+- The default appearance keeps blue brand roles but now composes all neutral surfaces, borders, content, and interaction roles from the reviewed gray ramp in light and dark modes.
+- Registry metadata now declares capability defaults, recommended uses, avoid guidance, recipes, and deprecated props instead of inferring defaults from array order.
+- Toolbar controls default to the shared 36px density; use `density="comfortable"` for the previous 40px toolbar height.
+
+### Fixed
+
+- Undefined token references, raw component values, inaccessible progress semantics, no-op controls, and the Arabic Pagination “Previous” label.
+- Documentation section anchors, narrow Input preview overflow, Popover arrow sizing, Slideout icon geometry, and playground bundle chunking.
+- High-severity playground advisories in Nano ID, PostCSS, and Undici through patched lockfile versions.
+
+### Migration
+
+- Prefer `density` over legacy component-specific sizes when controls share a row. Legacy size props continue to work.
+- Replace Input `hasLeadingIcon` and `hasInformationIcon` with explicit `leadingIcon`/`trailingIcon`, or use `showAtSign`/`showInfo` for those exact affordances. The legacy flags remain supported for this deprecation window.
+- Replace single-glyph Input shortcuts with `shortcutKeys={["Mod", "K"]}` or `KbdShortcut` for platform-aware keycaps.
+- Run `npx banhaten init` to install `.banhaten/USAGE.md`, then run `npx banhaten doctor` and `npx banhaten diff` before updating consumer components.
+
+## 0.1.3
+
+- Pre-launch registry and documentation baseline.

package/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to Banhaten
+
+## Local checks
+
+Use Node 18.18 or newer, install the root and playground dependencies, then run:
+
+```bash
+npm run check
+```
+
+The full check validates schemas, CLI behavior, token generation, token-only component styling, registry mirrors, isolated installs, documentation coverage, browser tests, and the production bundle.
+
+## Component rules
+
+- Build component styling from canonical `--bh-*` and `--shadow-*` tokens. Add
+  new values to the appropriate owned fragment under `tokens/source/` before
+  using them in component source.
+- Keep product copy, sample dates, and product actions in examples rather than production defaults.
+- Preserve inherited direction and use logical CSS properties. Test both LTR and RTL keyboard behavior.
+- Use native semantics or proven accessible primitives, and document the public API, examples, tokens, RTL behavior, and accessibility contract.
+- Keep stable primitives in Components, larger compositions in Patterns, and experiments in Lab.
+
+## Generated artifacts
+
+Edit the owned fragments under `tokens/source/` for structured tokens and
+aliases, and edit `registry/catalog/components/<id>.json` for component registry
+metadata. `tokens/banhaten.tokens.json` and `registry/index.json` are compiled
+publication artifacts. Edit `tokens/banhaten.utilities.css` for authored
+Tailwind mappings, keyframes, global rules, accessibility rules, and typography
+utilities. The generated `registry/styles/globals.css` is rebuilt from the
+compiled token catalog and that authored CSS source.
+
+After token or registry metadata changes, run:
+
+```bash
+npm run tokens:build
+npm run components:tokens:metadata -- --write
+npm run registry:export
+npm run docs:normalize
+```
+
+Do not hand-edit `tokens/banhaten.tokens.json`, `registry/index.json`,
+`registry/styles/globals.css`, `registry.json`, or generated registry contract
+tables.

package/README.md

@@ -26,6 +26,7 @@ bun install
 
 - `banhaten.config.json` with schema-backed aliases.
 - The base `cn` utility and `use-direction` hook.
+- `.banhaten/USAGE.md` with agent-readable defaults, recipes, and component-selection rules.
 - The generated Banhaten token stylesheet in your configured CSS file.
 - Tailwind v4 and Vite alias setup when those files are detected.
 - Required package dependencies.
@@ -35,36 +36,57 @@ bun install
 ## CLI
 
 ```bash
-npx banhaten init [--cwd <path>] [--force] [--dry-run]
-npx banhaten add <component...> [--cwd <path>] [--force] [--dry-run]
-npx banhaten diff [component...] [--cwd <path>] [--force]
-npx banhaten update [component...] [--cwd <path>] [--force] [--dry-run]
+npx banhaten init [--cwd <path>] [--force] [--dry-run] [--json]
+npx banhaten add <component...> [--cwd <path>] [--force] [--dry-run] [--json]
+npx banhaten diff [component...] [--cwd <path>] [--json]
+npx banhaten update [component...] [--cwd <path>] [--force] [--dry-run] [--json]
 npx banhaten list [--json]
 npx banhaten search <query> [--json]
 npx banhaten docs <component> [--json]
 npx banhaten view <component> [--file <registry-source>] [--json]
+npx banhaten doctor [--cwd <path>] [--json]
 npx banhaten version
 ```
 
+The CLI validates each command before doing project work: unknown flags, missing
+flag values, duplicate flags, and unexpected arguments fail without writing.
+Mutating commands then compute one install plan from the configured destinations
+and the existing TypeScript/Vite root aliases. An alias declared on only one side
+is mirrored to the other; conflicting, ambiguous, or dynamic aliases stop before
+files are staged. The install receipt records the resolved destinations so later
+runs cannot silently create a second generated tree.
+
+Dependency ranges follow a guarantee policy: every version admitted by the
+consumer declaration must satisfy Banhaten's requirement. Broader semver ranges
+are safely narrowed when possible and trigger an install hint; partial overlaps,
+disjoint ranges, and opaque package protocols fail without writes. A lockfile is
+never accepted instead of that manifest guarantee. When the manifest is already
+safe, the CLI verifies the bounded installed resolution and npm lock state;
+stale or unverifiable lock state keeps a project-rooted install action visible.
+
+Command flags:
+
+- `--cwd <path>` runs `init`, `add`, `diff`, `update`, or `doctor` against another project directory.
+- `--dry-run` previews `init`, `add`, or `update` writes.
+- `--force` replaces locally modified generated files after you review `banhaten diff`.
+- `--json` prints machine-readable output for commands that show it above.
+
 Global flags:
 
-- `--cwd <path>` runs against another project directory.
-- `--dry-run` previews writes.
-- `--force` rewrites generated files even when already current.
-- `--json` prints machine-readable output where supported.
+- `--help` or `-h` prints help.
 - `--silent` or `-s` suppresses normal command output.
 - `--yes` or `-y` is accepted for non-interactive scripts.
 - `--version` or `-v` prints the CLI version.
 
 ## Generated File Ownership
 
-Banhaten is a source registry. Installed component files are generated from the registry and are replaceable by `banhaten add` or `banhaten update` when registry content differs.
+Banhaten is a source registry. The install receipt records the exact generated hash for every managed file. Unmodified files update automatically; locally modified component files and token blocks are never replaced unless you pass `--force`.
 
 Use `banhaten diff` before updating if you edit generated component files locally:
 
 ```bash
 npx banhaten diff
-npx banhaten update button
+npx banhaten update button --force # only after reviewing intentional replacement
 ```
 
 Keep product-specific composition outside generated files when possible. Use local wrapper components for app behavior and keep Banhaten files focused on tokens, layout, accessibility primitives, and direction behavior.
@@ -73,6 +95,13 @@ Keep product-specific composition outside generated files when possible. Use loc
 
 Every component must style through Banhaten CSS variables, component aliases, or documented exception-ledger values. Raw colors, pixel values, opacity utilities, z-index utilities, durations, and shadow literals are blocked by the component token check.
 
+Structured token values and aliases are authored in the owned fragments under
+`tokens/source/`; `tokens/banhaten.tokens.json` is their compiled publication
+artifact. Tailwind mappings, keyframes, global and accessibility rules, and
+typography utilities are authored in `tokens/banhaten.utilities.css`.
+`registry/styles/globals.css` is generated from the compiled token catalog and
+the utility source; neither generated file should be edited directly.
+
 Token modes:
 
 - Color mode: light and dark.
@@ -80,6 +109,11 @@ Token modes:
 - Radius mode: `default`, `rounded`, `sharp`.
 - Direction: inherited LTR or RTL, with component-level `dir` support where needed.
 
+The default appearance is the `blue` brand theme composed with the achromatic
+`gray` neutral scale. This keeps page, card, border, and muted surfaces neutral
+while links, focus states, and primary actions remain blue. The `gray` theme is
+still a separate monochrome brand option; it changes the brand roles as well.
+
 Example:
 
 ```tsx
@@ -95,23 +129,41 @@ Typography utilities are generated as `.bh-text-*` classes and map directly to t
 
 ## Registry Formats
 
-Banhaten maintains two registry artifacts:
+Banhaten maintains component-owned registry sources and two compiled
+publication artifacts:
 
-- `registry/index.json` is the Banhaten source of truth used by the Banhaten CLI. It includes rich metadata for RTL behavior, parts, examples, files, and dependencies.
+- `registry/catalog/components/<id>.json` owns each component contract, while
+  `registry/catalog/base.json` and `manifest.json` own the shared contract and
+  publication order.
+- `registry/index.json` is the compiled Banhaten artifact used by the CLI. It
+  includes an exhaustive, module-aware `supportedExports` runtime contract plus
+  non-exhaustive `parts` anatomy, RTL behavior, examples, files, and
+  dependencies.
 - `registry.json` is a generated shadcn-compatible export for tools that expect the public shadcn registry schema.
 
-Regenerate the shadcn-compatible export after registry changes:
+Compile both registry publication artifacts after authored catalog changes:
 
 ```bash
 npm run registry:export
 ```
 
+`supportedExports` is checked against the installed TypeScript modules during
+`npm run registry:check`; a renamed, moved, added, or removed runtime export
+fails the release gate. Run `npm run registry:exports` only after reviewing an
+intentional public runtime API change. Type-only exports are outside this
+manifest. `parts` remains an ordered composition aid and does not claim API
+completeness.
+
 ## Documentation
 
 Primary docs live in the playground and render live registry-backed previews, install commands, source snippets, API tables, registry files, RTL behavior, and copyable code panels.
 
 Markdown docs live in `docs/design-system/components`. They are checked for install, API, examples, token contract, RTL rules, and accessibility sections.
 
+Launch guides cover [installation](docs/design-system/installation.md), [direction and localization](docs/design-system/direction-and-localization.md), [form recipes](docs/design-system/form-recipes.md), [density and elevation](docs/design-system/density-and-elevation.md), the [support matrix](docs/design-system/support-matrix.md), and the [release policy](docs/design-system/release-policy.md).
+
+The durable [launch comparison with shadcn/ui](docs/design-system/launch-comparison-shadcn.md) records every audited area, remediation, verification gate, the closed 910/910 contrast contract, and deliberate non-copying decisions.
+
 Useful commands:
 
 ```bash

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported versions
+
+Until Banhaten reaches 1.0, security fixes are applied to the latest published minor release. Consumers should keep the CLI and copied registry components current.
+
+## Reporting a vulnerability
+
+Report vulnerabilities privately through GitHub’s security-advisory workflow for this repository. Do not open a public issue containing exploit details, credentials, or consumer data.
+
+Include the affected Banhaten version, component or CLI command, reproduction steps, impact, and any known mitigation. Maintainers will acknowledge a complete report, assess severity, and coordinate a fix and disclosure.
+
+## Scope
+
+The CLI, registry source, generated CSS, dependency declarations, documentation application, and release artifacts are in scope. Vulnerabilities in an upstream dependency should also be reported to that upstream project when appropriate.

package/banhaten.config.example.json

@@ -1,7 +1,5 @@
 {
   "$schema": ".banhaten/schema/config.schema.json",
-  "style": "default",
-  "tsx": true,
   "tailwind": {
     "css": "app/globals.css"
   },

package/docs/design-system/README.md

@@ -3,8 +3,17 @@
 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.
 

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

@@ -131,7 +131,12 @@ The design system should use semantic tokens instead of importing naming pattern
 
 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 generated token contract or a component-level `--bh-*` alias in `registry/styles/globals.css`, then consume that token from the component. Component docs may record Figma references for audit and QA, but those literals are not implementation fallbacks.
+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:
 

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
+```