Immutable. This exact content is served forever at /api/v1/blob/d6f084a1ae0e3797.
# 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-slot`s, 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: ```bash pnpm design-system:generate pnpm design-system:coverage just check ``` Then visually verify the changed page in the in-app explorer.