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 carries the values themselves, generated from the token files, and the 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.

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. The accents are shown carrying meaning on the gallery.

Accent is a custom property, not a prop

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.

--helia-text-metaDense metadata and counters

Intelligence at the edge

--helia-text-labelUppercase labels

Intelligence at the edge

--helia-text-captionCaptions, chips, table cells

Intelligence at the edge

--helia-text-smallSupporting text

Intelligence at the edge

--helia-text-bodyBody copy

Intelligence at the edge

--helia-text-card-titleCard titles

Intelligence at the edge

--helia-text-leadLead paragraphs

Intelligence at the edge

--helia-text-subheadSubheads

Intelligence at the edge

--helia-text-headingComponent headings

Intelligence at the edge

--helia-text-sectionSection titles

Intelligence at the edge

--helia-text-pagePage titles

Intelligence at the edge

--helia-text-displayDisplay type

Intelligence at the edge

--helia-text-heroHome hero

Intelligence at the edge

--helia-weight-regularBody and long-form copy

Intelligence at the edge

--helia-weight-mediumLabels and dense metadata

Intelligence at the edge

--helia-weight-semiboldTitles and headings

Intelligence at the edge

--helia-weight-strongEmphasis inside a title

Intelligence at the edge

--helia-weight-boldUppercase eyebrows

Intelligence at the edge

--helia-leading-tightDisplay and hero type

A model reaches the board through a runtime, a compiler, and a profile of what it costs there.

--helia-leading-headingHeadings over one line

A model reaches the board through a runtime, a compiler, and a profile of what it costs there.

--helia-leading-bodyParagraphs

A model reaches the board through a runtime, a compiler, and a profile of what it costs there.

--helia-tracking-displayDisplay and hero

Intelligence at the edge

--helia-tracking-pagePage titles

Intelligence at the edge

--helia-tracking-sectionSection titles

Intelligence at the edge

--helia-tracking-headingComponent headings

Intelligence at the edge

--helia-tracking-capsUppercase labels

Intelligence at the edge

--helia-tracking-labelMixed-case labels such as badges

Intelligence at the edge

--helia-tracking-wordmarkWordmark lockups

Intelligence at the edge

The 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.

DisplaySystem sans · 650

Intelligence at the edge

Page titleSystem sans · 650

Deploy a model

Section titleSystem sans · 650

Choose a runtime

Content hierarchyLead · body · supporting

Start with the workflow that matches how your model will ship.

Use heliaRT for a familiar runtime path or heliaAOT when build-time control is the priority.

Supporting text adds constraints, provenance, or secondary context.

Utility rolesLabel · code

Released runtimeprofile_model(board="apollo510")

PrimaryTitles and essential values

SecondaryDescriptions and guidance

MutedMetadata and supporting text

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.

--helia-space-px

--helia-space-1

--helia-space-2

--helia-space-3

--helia-space-4

--helia-space-5

--helia-space-6

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.

--helia-radius-xs

--helia-radius-sm

--helia-radius-md

--helia-radius-lg

--helia-radius-pill

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 page measures that they do.

--helia-control-smButton

--helia-control-mdButton

--helia-control-lgButton

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.

--helia-surface-canvasThe page behind everything

--helia-surface-paperA section band on the canvas

--helia-surface-cardA card, a panel, a callout

--helia-surface-card-mutedA card at rest under hover

--helia-shadow-1A card sitting on the page

--helia-shadow-2A card under the pointer

--helia-shadow-3A menu or dialog over the page

The tones are shown on the parts that carry them under Surface, and the whole card family sits on them on the 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.

• --helia-motion-fastHover, focus, and press feedback
• --helia-motion-baseEntry and exit of a block
• --helia-motion-slowA whole section arriving
• --helia-ease-outThe one easing curve
• --helia-motion-lift-distanceHow far a card lifts
• --helia-motion-cue-distanceHow far a cue nudges
• --helia-motion-reveal-distanceHow far an entry rises
• --helia-motion-scaleThe site's tempo dial
• --helia-motion-enabledThe visitor's half of it

Hover or focus this cardIt lifts by --helia-motion-lift-distance over--helia-motion-fast.

This block rises into viewIt travels --helia-motion-reveal-distance over--helia-motion-base. Replay it below.

Replay

The gallery carries every named transition on one page, and Layout 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, and 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