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

Neutral
Accent
Static
Linked
Medium

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](https://ambiqai.github.io/helia-ui/primitives/#button)
[Secondary](https://ambiqai.github.io/helia-ui/primitives/#button)
[Ghost](https://ambiqai.github.io/helia-ui/primitives/#button)
[Small](https://ambiqai.github.io/helia-ui/primitives/#button)

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 &nbsp;
memory &nbsp;
circle-info

```mdx
<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.