Astronomer's design system. This repository is the framework-neutral source of truth for the design language — tokens, principles, and component specs — structured so that both people and AI agents can implement against it without drifting.
Spectra's React components live in the Astro monorepo and are published from there. This repo holds the layers beneath the components: the values, the reasoning, and the contracts that any surface — React, Svelte, or otherwise — can share.
| Layer | Path | What it is |
|---|---|---|
| Tokens | foundations/tokens/ |
The token origin. Hand-authored tokens.json (core + astro-app tiers) plus generators that emit CSS variables, a Chakra theme fragment, and a DESIGN.md. |
| Principles | foundations/principles/ |
The design language in prose — color, typography, layout, elevation, shape, motion, and the do's and don'ts that encode taste. |
| Specs | foundations/specs/ |
Implementation-agnostic component contracts: one spec, many framework implementations. |
| Rules & skills | .cursor/rules/, skills/ |
Portable, agent-loadable guardrails. |
| Benchmarks | bench/ |
Reserved for the eval harness that measures whether agents actually conform. |
| Consumer | Gets | From |
|---|---|---|
| Astro UI (React/Chakra) | Everything — theme generated from these tokens; components and stories unchanged | astro-theme generated from here; components stay workspace:* in the monorepo |
| Astro Desktop (Svelte) | CSS variables, principles, specs, rules | this repo directly (agent context + dist/ outputs) |
| Airflow OSS | Design guidance, tokens, rules as agent context | this repo directly |
| APC / other React surfaces | Versioned components | @astronomer/spectra* published from monorepo CI |
| Recruiting / public | The public design language | spectra.astronomer.io (monorepo docs build) + this repo |
| Agents (any repo) | Router + skills + folder rules + bench-validated guardrails | this repo (--add-dir / checkout) |
Every surface consumes the generated outputs, never the raw values:
pnpm install
pnpm generate # emits foundations/tokens/dist/- Any framework →
foundations/tokens/dist/css-vars.css(CSS custom properties,--spectra-*) - React / Chakra → the generated Chakra theme fragment
- Interchange / tooling → the generated
DESIGN.md
Start at AGENTS.md (or CLAUDE.md — same content, generated pair). It routes you to the right layer and framework adapter for your task.
The token origin (tokens.json) and the prose in foundations/ are the only hand-authored surfaces. Everything under a dist/ directory is generated — run pnpm generate instead of editing it. CI regenerates and fails on drift.
The legacy @astronomer/spectra component library (v0.0.27, 2020-era) is preserved at the legacy/v0.0.27 tag and its published npm versions are untouched.