# Foundations

Every value a part draws with comes from a token, and every token belongs to
one of four files. This page is the tour of them: what each scale is for, what
each step looks like, and which page shows the token doing its job. The
[color reference](https://ambiqai.github.io/helia-ui/foundations/tokens/) carries the values themselves,
generated from the token files, and the
[site theme](https://ambiqai.github.io/helia-ui/foundations/site-theme/) page lists the dials a site is
free to move.

## How the layers stack

`tokens.css` holds the primitives both HELIA sites share and maps them onto
Starlight's `--sl-*` variables. `semantic.css` names the steps authoring uses:
spacing, radius, type, weight, leading, ink, surfaces, tones, accents.
`recipes.css` turns those into the shapes the parts share. `site-theme.css` is
the contract of dials a consuming site sets, which move the two layers under it
without forking either.

```mermaid
flowchart LR
  T["tokens.css<br/>primitives, both themes"] --> S["semantic.css<br/>named steps"]
  S --> R["recipes.css<br/>shared shapes"]
  R --> P["Astro parts, React components, pages"]
  D["site-theme.css<br/>the dials a site sets"] -.-> S
  D -.-> R
```

The three package sheets are unlayered on purpose, so they outrank every
cascade layer a Tailwind entry declares. That is what keeps a token
authoritative over whatever the Starlight Tailwind compat package wires up
underneath.

## Color

Four surfaces and four inks, both sets swapped by the theme flip. Nothing in
the package writes a color literal outside the token files; everything else
resolves through these.

--helia-surface-canvas

--helia-surface-paper

--helia-surface-card

--helia-surface-card-muted

--helia-ink-primary

--helia-ink-secondary

--helia-ink-muted

--helia-ink-caution

The accent set is the package's whole color vocabulary. There are no product
names in it: a consuming site maps its own subjects onto an accent in the
composition that knows what they mean, and hands it to a part as `--accent`.

blue

cyan

green

orange

pink

purple

red

slate

Every color token, its value in each theme, and the contrast each ink reaches
on the canvas and on the card are on the
[color reference](https://ambiqai.github.io/helia-ui/foundations/tokens/). The accents are shown
carrying meaning on the [gallery](https://ambiqai.github.io/helia-ui/gallery/#content-first).

`Media` takes its color as `style="--accent: var(--helia-accent-cyan)"` rather
than `accent="cyan"`. That is deliberate: a prop would be an enumeration the
package has to own, and owning it would mean owning what each name is for. As
a custom property the part never learns the vocabulary.

## Type

One ramp of thirteen sizes, five weights, three leadings, and seven tracking
steps. A role is named before a size is chosen: `--helia-text-body` says what
the text is, where `0.94rem` says only how big it is. Tracking belongs to the
face rather than to the size, so a component that sets a letter-spacing of its
own is holding a value the ramp should own: uppercase labels take
`--helia-tracking-caps` and a wordmark takes `--helia-tracking-wordmark`, the
two steps that are roles rather than sizes.

The [Primitives](https://ambiqai.github.io/helia-ui/primitives/) page shows the ramp inside the parts
that use it, and the roles below read the same tokens as a page of copy does.

## Space, radius, and control height

One spacing scale, six steps and a hairline. A part that takes a spacing prop
names a step rather than a length, so the same value reaches the part, the
recipe, and the Tailwind utility: the Tailwind entry maps each step onto
`--spacing-*`, which makes `p-3` and `padding: var(--helia-space-3)` the same
value by construction rather than by convention.

Four radius steps derive from the `--helia-radius` primitive, so a site that
turns that one dial moves the whole set together. The pill sits outside the
scale, because a pill is a shape rather than a step.

Control heights belong to the size step rather than to the recipe that draws
it. The Astro button and the React one are separate code paths, and reading the
same token is what puts them on the same row; the
[Cohesion](https://ambiqai.github.io/helia-ui/react/cohesion/) page measures that they do.

## Elevation and surface tones

Depth is a surface tone first and a shadow second. A panel changes what it is
filled with to separate from the page, and casts one of three shadow steps when
it also has to sit above it. A hover lift moves one step, never two.

The tones are shown on the parts that carry them under
[Surface](https://ambiqai.github.io/helia-ui/primitives/#surface), and the whole card family sits on
them on the [gallery](https://ambiqai.github.io/helia-ui/gallery/).

## Motion

Three durations, one easing, and three travel distances, each duration
multiplied by a per-site dial and by the visitor's own. Reduced motion zeroes
both the dial and the distances, so a transition that survives has nothing left
to animate.

The [gallery](https://ambiqai.github.io/helia-ui/gallery/#reveal-on-scroll) carries every named
transition on one page, and [Layout](https://ambiqai.github.io/helia-ui/layout/#showcase-carousel) shows
the reveal used at section scale.

## Status inks

Advisory color comes in pairs. The tone is the fill an icon, a rim, or an edge
takes, and the ink is the same meaning chosen as text: each ink clears 4.5:1
against the raised surface of the theme it is declared in. Anything that sets a
status color on a word takes the ink, never the fill.

--helia-tone-success-ink

--helia-tone-warning-ink

--helia-tone-critical-ink

--helia-tone-important-ink

The measured ratios are on the
[color reference](https://ambiqai.github.io/helia-ui/foundations/tokens/#ink-on-surface), and
[Callouts](https://ambiqai.github.io/helia-ui/callouts/) shows each tone and its ink in the part they
belong to.

## The Ambiq wordmark

The plugin's footer renders the approved Ambiq wordmark, and the component is
available on its own at `@ambiqai/helia-ui/starlight/AmbiqLogo.astro`. It keeps
the supplied official vector artwork, with empty canvas trimmed for layout.

The footer defaults to blue in light mode and white in dark mode. Set
`footer: { links: [], logoLightTone: 'black' }` in `heliaStarlight()` to use
black in light mode instead. Direct component users can select
`tone="adaptive" lightTone="blue"` or `tone="adaptive" lightTone="black"`.
Explicit `blue`, `black`, and `white` tones remain fixed colors.

Blue

Black

White