Primitives

Four primitives carry the shapes that every other component builds on: the card surface, the pill, the uppercase label, and the call to action. Each one renders a class defined in @ambiqai/helia-ui/recipes.css, so an element that cannot be produced by the component — a grid <li>, a Starlight shell override, a scroll frame — reaches the same recipe by applying the class.

Surface

One border, one radius, three backgrounds. Reach for tone="muted" when the surface sits on the card background and has to recede, and tone="paper" for a full-width band.

Card

The default raised surface for a discrete interface object.

Muted

A recessed fill for a panel inside another surface.

Paper

The quiet canvas used for page bands.

padding names a spacing step rather than a length, so a surface cannot drift off the scale. interactive adds the shared hover background and the focus ring; href renders an anchor.

Interactive

Hover and focus this card to see the shared affordance.

Tight padding

Step 2 instead of the default step 4.

Chip

neutral is the outlined default and reacts to pointer state when it links. accent is the filled badge. static is read-only metadata and never suggests it can be clicked.

NeutralAccentStaticLinkedMedium

Medium static

Horizontal padding sits one step above vertical at both sizes, which is what makes the shape read as a pill rather than a rounded box.

Eyebrow

The uppercase label above a heading. It renders a <p> by default; pass as="span" inside a link or a flow that already owns the paragraph.

Section label

Button

Primary

Secondary

Ghost

Small

Without href the component renders a <button type="button">.

Shared recipes

Two classes exist on their own because components apply them to elements the primitives do not own.

• .helia-focus-ring is the site’s single focus-visible treatment. Add .helia-focus-ring--inset when the control sits flush inside a clipping parent, where an outset ring would be cut off.
• .helia-hover-surface is the hover and focus affordance for a card: the background steps to the muted fill and the border lightens. It never transforms, because a card that moves under the pointer inside a grid reflows its neighbors.

Icon

Icon is the one part here that backs no recipe. It resolves a name from Font Awesome’s free solid set at build time and writes the SVG into the page, so an icon costs nothing at runtime and an unknown name fails the build instead of rendering an empty box.

gauge-high   memory   circle-info

<Icon name="gauge-high" /> Latency
<Icon name="triangle-exclamation" label="Warning" />

It sizes and colors itself from the text it sits in, so it needs no rule at the call site. Leave label off when the icon repeats the adjacent text, which is most uses; supply it when the icon is alone in a cell or a heading and is carrying the meaning by itself.