banhaten 0.3.0 → 0.5.0

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

@@ -1,81 +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
-```
+# 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
+```