System / Docs
How to modify the system
The foundation is three layers plus a per-site theme. Change values at the right layer and every site stays consistent. Full rules in CLAUDE.md and FRONTEND-FOUNDATION.md at the repo root.
Token layers
Data flows one direction. Never reference a layer above where you are.
primitives.cssraw scales — --p-*. Never used directly.↓
semantic.cssroles — --color-*, --text-*, --space-*. Components use these.↓
theme.cssper-site art direction. Overrides semantic tokens to brand a site.Common changes
- Rebrand this site
- Override semantic tokens in
apps/<site>/src/styles/theme.css— fonts,--color-accent, surfaces. Add@font-faceabove the:rootblock for brand fonts. - Add a new token
- Add the raw value to
packages/tokens/primitives.cssas--p-*, then expose a role insemantic.css. Never inline a raw value in a component. - Add a component
- Create
packages/ui/src/Name.astro. Use semantic tokens only — no raw hex, no magic px. Add it to the Components page. - Change spacing rhythm
- Section padding is
--space-section/--space-section-sm. Block gaps use the numeric--space-*scale. Both defined insemantic.css.
Rules
- Semantic tokens only — no raw hex, no arbitrary px in pages or components.
- Reuse primitives before writing new CSS. Need a button?
@studio/ui/Button.astro. - Surfaces come in pairs — a background token always has a matching
--color-on-*text token. - Different sites should look different — that is
theme.css, not forked components. - The foundation is protected. Don't redesign it unless explicitly asked.
Commands
| Command | What it does |
|---|---|
pnpm dev | Run all sites (hot reload) |
pnpm check | Type + template check — must be 0 errors before commit |
pnpm build | Production build of every site |