Design System Explorer

This folder contains the in-app Goose Design System Explorer. Treat it as a real product surface, not a docs dump.

Repeatable Component Page Contract

Every component page should use the same structure unless Morgan explicitly asks for a different treatment:

1. PageIntro with a short human-readable purpose.
2. ComponentSpec using the component name. This pulls source, variants, and slots from the generated manifest. Do not hand-write those facts.
3. ComponentPlayground for the live component preview and controls.
4. ComponentTokenDetails for the current preview's color states and text styling.

The generated manifest owns facts that can be read from code: source file, exports, data-slots, CVA variants, state classes, token classes, and source token classes. The page owns designer judgment: what the preview should render, which controls matter, anatomy labels, state rows, and the plain-language description.

Populating Component Pages

The manifest is an inventory scanner, not a page generator. Use it to keep generated facts honest and to prevent docs drift, but do not expect it to infer the best live demo.

When populating a component page:

• Always use ComponentSpec for manifest-owned facts. Do not duplicate source paths, slots, variants, or generated token facts by hand.
• Render the actual shared UI primitive in the playground whenever it can be safely shown in-page. A manifest summary card is only a fallback for helper modules or components that cannot be meaningfully rendered without app state.
• Author playground controls around meaningful product states, even when the manifest reports Variants: None. Useful controls may include selected value, open/closed, disabled, invalid, loading, placeholder text, option count, orientation, density-sensitive size, or empty state.
• For trigger/portal components, include the full composition, not only the trigger. For example, a Dialog playground needs DialogTrigger and DialogContent; a Popover playground needs PopoverTrigger and PopoverContent.
• Keep the token details aligned to the current preview state. If a control changes disabled, invalid, open, selected, or destructive state, the token rows should describe that state.

Playground Control Heuristics

Playground controls should help designers inspect meaningful component behavior, not turn the preview into a remote-controlled demo.

• Prefer controls for props, modes, composition choices, and states that cannot be easily inspected by directly interacting with the preview.
• Do not add a control for state the user can naturally change in the preview, such as an accordion's open section, unless the state is otherwise hard to reach or compare.
• Keep controls scoped to real component API or real product states. Do not invent visual variants just to fill the control panel.
• Do not add scenario/content presets when they only swap demo copy. Add them only when each preset exposes a distinct component behavior, layout stress, or product state.
• Hide controls when they do not apply to the selected mode instead of showing a disabled control with unclear meaning.
• Remove impossible options when another control changes the valid state space. For example, if a single accordion cannot collapse, the open-section choices should not include None.
• Use the smallest set of controls that explains the component. A strong page usually exposes 3-6 high-signal controls rather than every possible state.

Token Table Rules

• Color rows answer: what background, text/icon, and border color is visible for each anatomy/state combination?
• Text rows answer: what typography styling is visible? Keep color out of the text table.
• Do not show visible label text as token metadata.
• Do not show raw Tailwind utility pills in the Tokens section.
• Prefer explicit values over vague values like inherited, state-dependent, or disabled opacity.
• Disabled states should name the base token plus opacity, for example --foreground / 50%.

Token Usage

Component source should use the shadcn semantic token contract first: bg-background, text-foreground, bg-card, bg-popover, bg-muted, text-muted-foreground, bg-accent, bg-primary, bg-destructive, border-border, border-input, and ring-ring.

Use Goose extension tokens only for product-specific surfaces and identities, such as bg-surface-composer, bg-canvas-base, chip colors, status colors, and composer placeholder color. Use bg-card-glass for floating chrome glass (nav panes, right rail, the global composer pill).

Do not use raw palette utilities like bg-gray-100, direct hex colors, or component-specific one-off color tokens without first adding them to the design system.

Validation

After changing component source or explorer pages, run:

pnpm design-system:generate
pnpm design-system:coverage
just check

Then visually verify the changed page in the in-app explorer.