| name | spectra-component-authoring |
| description | Implement a component from its Spectra spec. Use when building a new component (or a framework port of an existing one) so it satisfies the shared contract — variants, sizes, states, a11y — in React/Chakra or Svelte. |
spectra-component-authoring
A Spectra component is defined once as a framework-neutral spec and implemented per framework. Start from the spec; don't invent the contract.
Steps
- Read the spec in
foundations/specs/<Component>/ — variants, sizes, states, interaction/keyboard behavior, a11y requirements, and the embedded components: token-mapping (its visual half).
- Check for an existing implementation first. On React/Chakra, the component likely already lives in the monorepo (
apps/ui/libs/spectra) — extend it, don't duplicate. Ground truth for behavior is the monorepo.
- Wire visuals to tokens via
spectra-tokens — semantic tokens, never hardcoded values. Every variant/size/state maps to tokens from the spec's mapping block.
- Cover the full state matrix — default, hover, active, focus, disabled (with a reason), loading, and the data edge cases from
spectra-design-review.
- Accessibility per
spectra-accessibility — correct element (button vs link), keyboard operability, focus visibility, labels.
- Review against
spectra-design-review before done.
Framework notes
- React / Chakra — one component per file; named export; Chakra style props with semantic tokens; theme-level variants in the component's theme file. The spec is descriptive of the monorepo — if they disagree, the monorepo wins and the spec gets flagged.
- Svelte — build behavior on a headless primitive (Melt/Bits UI); style with
--spectra-* CSS vars; satisfy the same contract. Component code does not port from React — the spec is what's shared.
When the spec and reality diverge
Specs track the monorepo. If a component's real behavior lives in runtime theme functions (e.g. astro-theme/.../Button.ts), that file is ground truth; note the divergence so the spec can be updated (a checksum flag on those files triggers spec review).
