import { authoringChecklist, commonSlotNames, commonStateNames, cvaConventions } from "@ai-ui/ui"; import type { Meta, StoryObj } from "@storybook/react"; const docsCoverage = [ { name: "Playground", note: "One opinionated default example that shows the component in its most typical role." }, { name: "States", note: "Only when the component has meaningful disabled, invalid, checked, selected, or open-state behavior worth comparing." }, { name: "Anatomy", note: "Name the stable slots and public data attributes that designers and engineers can style against." }, { name: "Accessibility or Motion", note: "Choose the dimension that is most likely to be misunderstood by contributors and consumers." } ] as const; const docsWritingRules = [ "Use `docs.description.component` to explain when the component should be chosen, not to restate its name.", "Show real product language instead of lorem ipsum so states and hierarchy feel intentional.", "Keep examples narrow. One good scenario teaches more than six generic permutations.", "If a story exists only to explain slots or motion, say that directly in the story description." ] as const; function ComponentAuthoringGuide() { return (

AI UI / Docs Guide

Component docs should explain usage, structure, and behavior without drifting away from the actual source contract.

This page turns the repo's component contract into a repeatable Storybook recipe. The goal is not maximum story count. The goal is a small set of stories that makes API, anatomy, and behavioral intent obvious to the next contributor.

Minimum Story Recipe

{docsCoverage.map((item) => (

{item.name}

docs lane

{item.note}

))}

Writing Rules

{docsWritingRules.map((rule) => (

{rule}

))}

Component Contract Inputs

The docs should mirror the same public hooks that the components expose in source.

{authoringChecklist.map((item) => (

{item}

))}

CVA Guardrails

Docs should reinforce the variant surface that engineering already considers stable.

{cvaConventions.map((item) => (

{item}

))}

Slots Worth Calling Out

Anatomy stories should name only the slots a consumer can reasonably style or inspect in tests.

{commonSlotNames.map((item) => (
{`data-slot="${item.slot}"`} slot

{item.guidance}

))}

States Worth Explaining

State stories should match the durable `data-*` surface, not one-off visual tweaks.

{commonStateNames.map((item) => (
{`data-${item.state}`} state

{item.guidance}

))}

Before Opening The PR

Ask if the docs tell a consumer when to choose the component.

If the answer is "not really", the component description is still too generic.

Ask if the anatomy story names the real public styling hooks.

If the story only explains visuals, it is not yet useful to another engineer.

Ask if the most failure-prone behavior is explicitly documented.

For overlays that usually means accessibility. For animated surfaces it may be motion.

Ask if the story count stayed disciplined.

The docs should feel intentional, not encyclopedic.

); } const meta = { title: "Foundation/Component Authoring", component: ComponentAuthoringGuide, parameters: { docs: { description: { component: "Use this page as the Storybook-side companion to the repo's component contract. It defines the minimum documentation recipe for a new component and keeps docs work aligned with slots, states, variants, and motion semantics that already exist in source." } }, layout: "fullscreen" } } satisfies Meta; export default meta; type Story = StoryObj; export const Overview: Story = {};