# Foundations

Shared design decisions for colors, typography, spacing and geometry. Choose tokens by their role; use the live examples to inspect their current values and local overrides.

A token names a decision that several parts of an interface should share. Equal values alone do not make two usages the same role. Primitive scales supply values; functional tokens express why those values belong together.

Each subject page documents its token roles, classes and usage.

- [Document defaults](document.md): cascade layers and the layer each rule belongs to, reset, native element defaults and focus.
- [Colors & themes](colors.md): surfaces, text, borders, accent, feedback and theme selection.
- [Typography](typography.md): families, type scale, heading, body, prose, UI, metadata and code roles, editorial composition and local type scales.
- [Spacing](spacing.md): spacing scale and functional layout, content and control roles.
- [Stack and row](stack-and-row.md): direction, spacing and alignment classes.
- [Frames & surfaces](surfaces.md): control size, borders, shared lines, corner crosses and half-crosses, capsules and floating surfaces.
- [Native forms](native-forms.md): native select, text fields, choice groups, labels and feedback.
- [Interaction & motion](interaction.md): keyboard focus, unavailable controls and short motion.
- [Responsive](responsive.md): shared viewport breakpoints and the choice between rem and px.

## Naming

- **Primitives** name their category, then a step or variant without a role: `--space-3`, `--font-size-base`, `--font-sans`, `--radius-full`.
- **Functional tokens** name the role or styled element, then the property: `--body-font-size`, `--focus-width`, `--floating-shadow`. A level or variant qualifies the role, before the property: `--heading-1-font-size`, `--focus-inset-offset`. A bare name holds a color, and its levels follow it: `--border`, `--border-subtle`, `--focus`, `--text`.
- **Property suffixes** use the CSS property name when the token sets one property, such as `-font-weight`, `-line-height` or `-width`, and otherwise the common design term: `-shadow`, `-layer`, `-duration`, `-easing`.

## Choose and override

Start with the owning component's defaults or named presets. Use a functional token when its role fits; use a primitive step for component-specific spacing. The capsule uses `--radius-full`; other radii, drawing geometry, circular icons and optical adjustments stay local. Custom spacing needs a concrete layout constraint, described beside the exception.

Override a functional token on the element that owns the composition. CSS aliases resolve where they are defined: changing a primitive only on a descendant does not rebind an inherited functional alias.

```css
.collection {
  --content-gap-block: var(--space-5);
}
```

Keep theme values shared and scope experimental overrides to their specimen. The live typography and spacing examples provide a reset to inherited defaults.

## Where values live

`tokens.css` is authoritative for values and light/dark palettes; `breakpoints.css` defines build-time viewport thresholds. The subject pages document token roles without copying those values. The live reference reads both CSS files and presents their current definitions beside this Markdown guidance.