# Color tokens

Every `--helia-` token that resolves to a color, read out of `tokens.css`
and `semantic.css`: the name, the value each theme gives it, and the ratio
each ink reaches on the two grounds a page draws text on. A palette that
moves without this page moving fails `validate`, so what is here is what the
package ships.

The [overview](https://ambiqai.github.io/helia-ui/foundations/) says what the layers are for and
shows the rest of the scales. A value written as a `var()` chain or a
`color-mix()` is resolved here to the color it computes to, and an ink that
reads a Starlight variable resolves through the fallback `tokens.css`
declares, which restates Starlight's own value.

## Primitives

The shared layer in `tokens.css`. Every other color resolves to one of these or sits beside them, and the theme flip moves them rather than moving what reads them.

## Surfaces

The grounds a page draws on, from the canvas behind everything to the muted card. A site tints the whole set through `--helia-surface-tint`, so a product surface stays on the scale.

## Inks

Text color by role rather than by hue. Primary carries titles and values, secondary carries description, muted carries metadata.

## Status inks

The advisory meanings chosen as text. Anything that sets a status color on a word takes one of these; the fills below are for an icon, a rim, or an edge.

## Accents

The whole color vocabulary a part is handed. A part never learns a subject name: a composition maps its own subjects onto an accent and passes it as `--accent`.

## Advisory tones

One fill per callout and badge variant, plus the theme-aware set a chip rim reads. These are strokes and fills, not text.

## Chart palette

Six series colors, plus the gridline and the tick ink. None of them is an advisory tone: a series color carries no meaning, and aliasing the tones put a chart in the callout vocabulary. The order is the order a chart uses them, so the first two are the pair that has to separate at a glance -- a blue against the page ink -- and the rest is a slate ramp at decreasing weight; a chart that needs a seventh hue is a chart that needs splitting.

## Shadow inks

The three shadow colors the elevation steps are built from. Each one is a black at a low alpha, so a shadow darkens whatever it falls on rather than tinting it.

## Generative art

Surfaces, strokes, and planes for the abstract media treatments. They are a palette for artwork rather than for interface, which is why they sit apart from the accents.

## Ink on surface

Each ink drawn on the canvas and on the card, in both themes, with the
contrast ratio computed from the two resolved values. `AA` marks a pair at
or above 4.5:1, which is the WCAG AA threshold for body text.