new-component

name	new-component
description	Add a new component to Construct's design system (atom, molecule, or organism) following every house convention — placement, props contract, token styling, demo page, registration, docs. Use whenever building a component from a roadmap/design issue or from scratch.

New Construct Component

The ritual for adding a component so it lands indistinguishable from the ones already here. Work through the sections in order; the Verify section gates the finish.

1. Placement

• 1-atom/ — renders one thing, composes nothing of ours (Text, Pic, Code).
• 2-molecule/ — composes atoms, owns a small interaction (BaseInput, Chip).
• 3-organism/ — multi-molecule machinery (Overlay, Accordion).
• Root of app/components/ — behavioral/choreography components with no visual substance of their own (Reveal, P5).
• No namespace prefixes — all dirs register with pathPrefix: false.

2. Props contract (match the Base molecules)

• Controlled component: modelValue + emit("update:modelValue"). The component never mutates its own open/value state directly — one code path, driven by the prop (see Overlay.vue for the reference pattern).
• withDefaults(defineProps<Props>()), TypeScript interface, no runtime validators.
• Size variants where sensible: size?: "small" | "medium" | "large" mapping to t-micro-1 / t-caption-2 / t-body-2 classes. These names are component variants, not spacing units — the unit scale is numeric (--unit-8, pb-16).
• Ids: useId() per instance, never label-derived (const uid = useId() — see BaseSelect for why: label-derived ids collide the moment two instances share a label).
• Labels: the component owns its own <label :for> pairing, class input-label t-caption-2 pb-8 (all four Base molecules use exactly this).
• Form controls must speak the FormField contract: accept invalid?: boolean and describedBy?: string, bind them as :aria-invalid="invalid || undefined" and :aria-describedby="describedBy" on the real control element, not the wrapper div (attrs fallthrough hits the wrapper — bind explicitly). Add is-invalid class for the --status-error border.
• Icon props type from the single source: import type { IconName } from "~/components/1-atom/Iconography.vue" — never hand-copy the union.

3. Styling rules

• Tokens only. Colors from foundations/color.scss custom properties; spacing from the numeric unit scale (var(--unit-8), utility classes pb-8/mt-32); radii from --radii-*. Zero hex values in component styles.
• Both themes, automatically. If you only use tokens, themes come free. If you need a new token (e.g. a status color), add it at :root (dark) AND mirror it in the theme-light mixin at the mirrored scale position (gray-50↔950, violet-300↔700, red-300↔700) — verify ≥4.5:1 contrast on both --background-primary values.
• Focus rings gate on input modality: [data-input="keyboard"] &:focus-visible (mouse clicks match :focus-visible on text inputs too — spec heuristic).
• touch-action: manipulation comes free from reset.scss on interactive elements; don't undo it.
• Motion: every tween branches on deviceStore.userMotionReduced — gsap.set (snap) instead of gsap.to. No exceptions; this is the house rule that also makes hidden-tab browser verification possible.
• Never add CSS-emitting code to _global.scss. Shared form styles live in atoms/inputs.scss / atoms/buttons.scss, imported per-SFC.

4. Demo page (app/pages/demo/<rung>/<name>.vue)

Structure every existing page follows — copy the skeleton from a recent one (breakpoint.vue, theme.vue):

1. DemoPageHeader with the component name.
2. Overview DemoPageBody: what it is, the one-sentence design rationale, a Code usage snippet.
3. Live example(s): real working instances in an .example-box. Cover every variant and state (default / with label / disabled / error via FormField for form controls).
4. API Reference DemoPageBody: a Code block listing every prop, emit, and slot with types, plus a /* Contracts worth knowing */ comment for the non-obvious rules.

Gotchas:

• Code blocks: no theme prop (they adapt to light/dark automatically; a theme="github-dark" locks it). No backticks inside :code template literals — they terminate the attribute expression and break the page compile; use quotes in snippet code.
• Page boilerplate: useSeoMeta(pageSEO({ title: "<Name> Documentation" })) + definePageMeta({ pageTransition: pageTransitionDefault() }), both imported explicitly (not auto-imported).

5. Registration

• app/assets/scripts/navigation.ts — add the demo page entry (feeds both SectionNav and the header menu).
• scripts/smoke.mjs — add the demo route to the routes array. Every shipped feature's demo page is smoke-covered.

6. Docs

• CLAUDE.md: add the component to its rung's list in "Component hierarchy". If it introduces a contract others must follow (like FormField's slot props), give it a short ### section.
• README.md: add to the relevant list if it's scaffolding future forks should know about.

7. Verify

npm run build && npm run smoke

Then verify in the browser (see the verify-browser skill): every interactive state, keyboard operation, both themes, and reduced-motion behavior. A component isn't done because it compiles — it's done when its demo page proves every claim its API reference makes.