# Astro part contracts Every part exported under `@ambiqai/helia-ui/astro/*`, read out of the parts themselves: the `Props` interface, the defaults in the destructure, and the slots each one documents. A part whose contract changes without this page changing fails `validate`, so what is here is what the package ships. Props marked `(req.)` have no default and must be passed. A part that also lists inherited attributes forwards them to its root element. ## Card family | Component | Class | Props | Slots | | ------------- | ---------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | `Card` | `.helia-card` | `as`, `tone`, `media`, `density`, `lift`, `interactive` | `default` | | `CardMedia` | `.helia-card-media` | `ratio`, `fit` | `default` | | `CardHeader` | `.helia-card-header` | `titleAs`, `padding`, `href`, `eyebrow`, `step`, `scale`, `rendition` | `default`, `icon`, `eyebrow`, `meta`, `action` | | `CardContent` | `.helia-card-content` | `padding`, `variant` | `default` | | `CardActions` | `.helia-card-actions` | `align`, `padding` | `default` | | `CardList` | `.helia-card-list` | `items`, `marker`, `icon`, `padding` | none | | `CardQuote` | `.helia-card-quote` | `attribution`, `detail`, `initials`, `padding` | `default`, `attribution` | | `Badge` | `.helia-badge` | `tone`, `dot`, `size` | `default` | | `Media` | `.helia-media` | `treatment`, `ratio` | none | | `Reveal` | `.helia-motion-reveal` | `threshold`, `stagger` | `default` | | `StatCard` | `.helia-stat-card` | `label`, `delta`, `deltaTone`, `tone`, `density`, `lift`, `interactive` | `default`, `sparkline` | | `LinkCard` | `.helia-link-card` | `href`, `title`, `titleAs`, `eyebrow`, `meta`, `tone`, `density`, `lift` | `default`, `icon` | | `IconTile` | `.helia-icon-tile` | `name`, `label`, `size`, `variant` | `default` | | `IconRow` | `.helia-icon-row` | `title`, `href`, `titleAs`, `icon`, `variant`, `size` | `default`, `icon` | | `SplitPanel` | `.helia-split-panel` | `tone`, `ratio`, `density`, `titleAs`, `as` | `eyebrow`, `title`, `body`, `actions`, `code` | | `BigNumber` | `.helia-big-number` | `label`, `labelPosition`, `step`, `unit`, `accent`, `delta`, `direction`, `deltaTone`, `caption` | `default`, `sparkline` | | `Sparkline` | `.helia-sparkline` | `values`, `ariaLabel`, `kind`, `width`, `height`, `marker`, `lastValue` | none | ## Card variant values | Component | Prop | Values | Default | | ------------- | --------------- | -------------------------------------------------------------------------- | ------------- | | `Card` | `tone` | `card`, `muted`, `paper`, `outlined`, `filled`, `elevated`, `ghost`, `ink` | `card` | | `Card` | `media` | `top`, `side`, `background` | `top` | | `Card` | `density` | `default`, `compact`, `comfortable` | `default` | | `CardMedia` | `ratio` | `16/9`, `4/3`, `1/1` | `16/9` | | `CardMedia` | `fit` | `cover`, `contain` | `cover` | | `CardHeader` | `titleAs` | `h2`, `h3`, `h4` | `h3` | | `CardHeader` | `scale` | `default`, `display` | `default` | | `CardContent` | `variant` | `prose`, `stats` | `prose` | | `CardActions` | `align` | `start`, `end`, `between` | `start` | | `CardList` | `marker` | `check`, `bullet`, `number` | `check` | | `Badge` | `tone` | `neutral`, `info`, `success`, `warning`, `danger`, `accent`, `secondary` | `neutral` | | `Badge` | `size` | `sm`, `md` | `sm` | | `Media` | `treatment` | `color-field`, `graphite`, `slate`, `wire` | `color-field` | | `Media` | `ratio` | `16/9`, `4/3`, `1/1` | -- | | `StatCard` | `density` | `default`, `compact`, `comfortable` | -- | | `LinkCard` | `titleAs` | `h2`, `h3`, `h4` | `h3` | | `LinkCard` | `density` | `default`, `compact`, `comfortable` | -- | | `IconTile` | `size` | `sm`, `md`, `lg` | `md` | | `IconTile` | `variant` | `outlined`, `tinted`, `filled` | `tinted` | | `IconRow` | `titleAs` | `h2`, `h3`, `h4` | `h3` | | `IconRow` | `variant` | `outlined`, `tinted`, `filled` | `tinted` | | `IconRow` | `size` | `sm`, `md`, `lg` | `md` | | `SplitPanel` | `tone` | `tinted`, `muted`, `plain` | `tinted` | | `SplitPanel` | `ratio` | `1:1`, `2:3`, `3:2` | `1:1` | | `SplitPanel` | `density` | `compact`, `default`, `comfortable` | `default` | | `SplitPanel` | `titleAs` | `h2`, `h3`, `h4` | `h2` | | `SplitPanel` | `as` | `section`, `div`, `aside` | `section` | | `BigNumber` | `labelPosition` | `above`, `below` | `above` | | `BigNumber` | `step` | `display`, `heading` | `display` | | `BigNumber` | `direction` | `up`, `down`, `flat` | `flat` | | `Sparkline` | `kind` | `line`, `area` | `line` | ## AccordionGroup **Use it for:** A stack of disclosure rows: one `
` per item, the first one open. ```ts import AccordionGroup from '@ambiqai/helia-ui/astro/AccordionGroup'; ``` | Prop | Type | Default | Description | | -------------- | -------------------------- | ------- | ------------------------------------------------------- | | `items` (req.) | `readonly AccordionItem[]` | -- | The rows, in display order. The first one renders open. | **AccordionItem** | Prop | Type | Default | Description | | ---------------- | -------- | ------- | ---------------------------------------------------------- | | `title` (req.) | `string` | -- | The summary line, and the control that opens the row. | | `content` (req.) | `string` | -- | The row body. Plain text: it is rendered as one paragraph. | **Slots** -- none. [See it rendered on Disclosure](https://ambiqai.github.io/helia-ui/disclosure/) ## AsciiTerminal **Use it for:** A terminal transcript: a fixed set of lines, optionally typed out on entry, with optional copy and replay controls. ```ts import AsciiTerminal from '@ambiqai/helia-ui/astro/AsciiTerminal'; ``` | Prop | Type | Default | Description | | -------------- | --------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lines` (req.) | `readonly AsciiTerminalLine[]` | -- | The transcript, in order. | | `frame` | `'plain' \| 'window'` | `'plain'` | Optional decorative window frame; the default retains the plain transcript. | | `title` | `string` | `'Terminal'` | The frame's caption. | | `ariaLabel` | `string` | `` `${title} transcript` `` | Accessible name for the frame. Defaults to the title plus `transcript`. | | `animated` | `boolean` | `false` | Types the command lines out on entry. Reduced motion shows them at once. | | `autoplay` | `boolean` | `true` | Starts the animation when the frame scrolls into view. Needs `animated`. | | `copy` | `boolean \| 'transcript' \| 'commands'` | `false` | Adds the copy control. `true` or `'transcript'` copies the whole transcript as plain text, prompts included; `'commands'` copies only the command lines, without prompts, which is what a reader pastes into a shell. | | `replay` | `boolean` | `animated` | Adds the replay control. Defaults to whatever `animated` is. | | `tone` | `'adaptive' \| 'light' \| 'dark'` | `'adaptive'` | `adaptive` follows the site theme; `light` and `dark` are fixed. | | `typingSpeed` | `number` | `28` | Milliseconds per typed character. 0 types a command line instantly. | | `lineDelay` | `number` | `130` | Milliseconds of pause after each line. 0 runs the lines together. | **AsciiTerminalLine** | Prop | Type | Default | Description | | ------------- | ----------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- | | `text` (req.) | `string` | -- | The line as it is read and as it is copied, without the prompt. | | `kind` | `'command' \| 'muted' \| 'output' \| 'success' \| 'warning' \| 'error'` | -- | What the line is. Only `command` is typed out and given a prompt. | | `prompt` | `string` | -- | Prompt in front of a `command` line. Ignored on every other kind. | **Slots** -- none. [See it rendered on Code](https://ambiqai.github.io/helia-ui/code/#ascii-terminal) ## Badge **Use it for:** A read-only label on the `Chip` recipe, tinted by an advisory tone. ```ts import Badge from '@ambiqai/helia-ui/astro/Badge'; ``` | Prop | Type | Default | Description | | ------ | ----------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `tone` | `\| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'accent' \| 'secondary'` | `'neutral'` | The advisory tint. `neutral` and `accent` reuse the chip tones; the rest are tinted. `secondary` takes `--helia-accent-secondary`. | | `dot` | `boolean` | `false` | Leading status dot, drawn in the badge ink. Decorative: the label carries the meaning. | | `size` | `'sm' \| 'md'` | `'sm'` | `sm` is the in-content metadata size, `md` the standalone one. | Also accepts `HTMLAttributes<'span'>`. **Slots** - `default` -- The label. Required: without it the badge renders nothing. [See it rendered on Cards](https://ambiqai.github.io/helia-ui/cards/#badge) ## Band **Use it for:** A full-bleed page section: the ground reaches the edges of the reading frame while the content stays on the readable measure. ```ts import Band from '@ambiqai/helia-ui/astro/Band'; ``` | Prop | Type | Default | Description | | --------- | ---------------------------------------------- | ----------- | -------------------------------------------------------------------- | | `tone` | `'plain' \| 'muted' \| 'contrast' \| 'tinted'` | `'plain'` | The ground. `plain` paints none and leaves the page showing through. | | `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | Vertical rhythm above and below the content. | Also accepts `HTMLAttributes<'section'>`. **Slots** - `header` -- The section heading, above the content and on the same measure. - `default` -- The section's content, held to the readable width. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#band) ## Bars **Use it for:** A few labeled bars against a shared scale, drawn as tracks rather than as a plot. ```ts import Bars from '@ambiqai/helia-ui/astro/Bars'; ``` | Prop | Type | Default | Description | | ------------- | ---------- | ------------------------------------------- | ------------------------------------------------------------------ | | `rows` (req.) | `BarRow[]` | -- | The rows, in display order. | | `max` | `number` | `Math.max(...rows.map((row) => row.value))` | The length a full track stands for. Defaults to the largest value. | | `ticks` | `string[]` | -- | Labels along the axis, spread from its start to its end. | | `caption` | `string` | -- | A note under the chart: provenance, units, a caveat. | Also accepts `HTMLAttributes<'div'>`. **BarRow** | Prop | Type | Default | Description | | -------------- | --------- | ------- | ----------------------------------------------------------------- | | `label` (req.) | `string` | -- | What the bar measures. | | `value` (req.) | `number` | -- | The bar's length, on the same scale as `max`. | | `display` | `string` | -- | The reading printed beside the bar. Defaults to `value`. | | `accent` | `boolean` | -- | Draws this bar in the product accent. At most one across the set. | **Slots** -- none. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#bars) ## BigNumber **Use it for:** One figure at the top of the type scale, with its label, its change, and room for a trend under it. ```ts import BigNumber from '@ambiqai/helia-ui/astro/BigNumber'; ``` | Prop | Type | Default | Description | | --------------- | -------------------------- | ----------- | ----------------------------------------------------------------------------------- | | `label` (req.) | `string` | -- | What the figure counts. Rendered as the eyebrow. | | `labelPosition` | `'above' \| 'below'` | `'above'` | Which end of the figure the label sits at. | | `step` | `'display' \| 'heading'` | `'display'` | Which rung of the type ladder the figure is set at. | | `unit` | `string` | -- | What the figure is measured in, set beside it a step down. | | `accent` | `boolean` | `false` | Draws the unit glyph in the product accent. The figure stays ink. | | `delta` | `string` | -- | The change beside the figure. Omit it and nothing renders. | | `direction` | `'up' \| 'down' \| 'flat'` | `'flat'` | Which way the change went. Draws the arrow; says nothing about whether it is good. | | `deltaTone` | `BadgeTone` | `'neutral'` | Whether the change reads well or badly. The composition decides, not the direction. | | `caption` | `string` | -- | A note under the figure: provenance, units, a caveat. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The figure itself, with whatever markup it needs. - `sparkline` -- A `Sparkline` under the figure, showing how it got there. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#figures) ## Block **Use it for:** One node of a `BlockDiagram`: a label, an optional second line, and, when it is given children, the set of blocks inside it. ```ts import Block from '@ambiqai/helia-ui/astro/Block'; ``` | Prop | Type | Default | Description | | -------------- | ----------------------------------- | ----------- | -------------------------------------------------------------------------------------- | | `label` (req.) | `string` | -- | What the block is. One to three words. | | `sublabel` | `string` | -- | A second line under the label: a qualifier, a count, a unit. | | `tone` | `'neutral' \| 'muted' \| 'accent'` | `'neutral'` | The ground. `accent` takes the product color of whatever subtree it sits in. | | `emphasis` | `'outline' \| 'filled' \| 'dashed'` | `'outline'` | The edge. `filled` drops it for a stronger ground, `dashed` marks a block as proposed. | | `span` | `2 \| 3 \| 4` | -- | Columns the block covers in a `row` or `grid` set. Dropped when the set stacks. | | `flow` | `'row' \| 'column' \| 'grid'` | `'column'` | How the blocks inside this one are laid out. | | `columns` | `2 \| 3 \| 4 \| 5` | `3` | Columns at the wide end of the `grid` flow. | | `href` | `string` | -- | Makes the label a link. The block itself stays a list item. | | `icon` | `IconName` | -- | Font Awesome solid name, drawn before the label as decoration. | Also accepts `HTMLAttributes<'li'>`. **Slots** - `default` -- The blocks inside this one. A block with no slot is a leaf. [See it rendered on Block diagrams](https://ambiqai.github.io/helia-ui/block-diagrams/#nesting) ## BlockDiagram **Use it for:** The canvas a set of `Block`s is drawn on: a figure, an optional caption, and the arrangement of the blocks directly inside it. ```ts import BlockDiagram from '@ambiqai/helia-ui/astro/BlockDiagram'; ``` | Prop | Type | Default | Description | | ----------- | ------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- | | `title` | `string` | -- | The diagram's name, set over it as the first line of the caption. | | `caption` | `string` | -- | A sentence under the title. What the diagram is of, not what it shows. | | `flow` | `'row' \| 'column' \| 'grid' \| 'sequence'` | `'row'` | Top-level layout. Row and sequence stack below 42rem; sequence adds ordered stages and connectors. | | `columns` | `2 \| 3 \| 4 \| 5` | `3` | Columns at the wide end of the `grid` flow. Halves at 62rem, stacks at 42rem. | | `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | The gap between the top-level blocks, and the tighter one inside them. | | `tone` | `'plain' \| 'muted'` | `'plain'` | The ground under the diagram. `muted` frames it; `plain` lets the page through. | | `ariaLabel` | `string` | -- | Accessible name for the figure when it carries no `title`. | Also accepts `HTMLAttributes<'figure'>`. **Slots** - `default` -- The top-level blocks, in reading order. [See it rendered on Block diagrams](https://ambiqai.github.io/helia-ui/block-diagrams/#a-flat-row) ## Button **Use it for:** The call to action: a pill-shaped link or button. ```ts import Button from '@ambiqai/helia-ui/astro/Button'; ``` | Prop | Type | Default | Description | | --------- | ------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | | `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `'primary'` | `primary` is the filled ink pill, `secondary` outlined, `ghost` bare, `danger` the destructive fill. | | `size` | `'sm' \| 'md'` | `'md'` | `md` is the hero and page-level size, `sm` the in-content one. | | `href` | `string` | -- | Where it goes. Its presence is what makes this an anchor. | Also accepts `Omit, 'href'>`, `HTMLAttributes<'button'>`. **Slots** - `default` -- The label, and the accessible name of the control. [See it rendered on Primitives](https://ambiqai.github.io/helia-ui/primitives/#button) ## Callout **Use it for:** An aside on a `Surface`: a titled block with a tone and the icon that tone implies. ```ts import Callout from '@ambiqai/helia-ui/astro/Callout'; ``` | Prop | Type | Default | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `title` (req.) | `string` | -- | The heading of the aside, and its accessible name. | | `tone` | `\| 'note' \| 'tip' \| 'success' \| 'important' \| 'warning' \| 'critical' \| 'compatibility' \| 'experimental' \| 'deprecated'` | `'note'` | What the aside means. Picks the tint and the icon together. | **Slots** - `default` -- The body of the aside. Prose, not a bare sentence fragment. [See it rendered on Callouts](https://ambiqai.github.io/helia-ui/callouts/#core-guidance) ## Card **Use it for:** The card container: a `Surface` that carries no padding of its own. ```ts import Card from '@ambiqai/helia-ui/astro/Card'; ``` | Prop | Type | Default | Description | | ------------- | --------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------- | | `as` | `Exclude` | `'div'` | Element to render. Never an anchor: the whole-card link is `CardHeader href`. | | `tone` | `\| 'card' \| 'muted' \| 'paper' \| 'outlined' \| 'filled' \| 'elevated' \| 'ghost' \| 'ink'` | `'card'` | What stands in for the card's edge and fill. | | `media` | `'top' \| 'side' \| 'background'` | `'top'` | Where a slotted `CardMedia` sits. `side` stacks again below 42rem. | | `density` | `'default' \| 'compact' \| 'comfortable'` | `'default'` | Moves the padding step the parts default to: 3, 4, or 5. | | `lift` | `boolean` | `false` | Adds the hover lift. Pair it with `interactive` only when the card links. | | `interactive` | `boolean` | `false` | Adds the shared hover background shift and the focus-visible ring. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The card parts, in the order they should stack. [See it rendered on Cards](https://ambiqai.github.io/helia-ui/cards/#the-card-parts) ## CardActions **Use it for:** The action row of a card: a flex row around whatever the consumer hands it — a `Button`, a `Chip`, a plain link, a pair of them. ```ts import CardActions from '@ambiqai/helia-ui/astro/CardActions'; ``` | Prop | Type | Default | Description | | --------- | ------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `align` | `'start' \| 'end' \| 'between'` | `'start'` | Row alignment. `between` pushes the first and last child apart. | | `padding` | `PaddingStep` | `'card'` | Inner padding, named by spacing step. `card` follows the density dial; `none` leaves the part to own its gaps. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The actions, in reading order. [See it rendered on Cards](https://ambiqai.github.io/helia-ui/cards/#a-card-with-every-part) ## CardContent **Use it for:** The body of a card: a padding region around whatever the consumer writes. ```ts import CardContent from '@ambiqai/helia-ui/astro/CardContent'; ``` | Prop | Type | Default | Description | | --------- | -------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `padding` | `PaddingStep` | `'card'` | Inner padding, named by spacing step. `card` follows the density dial; `none` leaves the part to own its gaps. | | `variant` | `'prose' \| 'stats'` | `'prose'` | `stats` lays the slotted figures out as a row that wraps rather than as prose. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The card's prose, or the figures when `variant` is `stats`. [See it rendered on Cards](https://ambiqai.github.io/helia-ui/cards/#a-card-with-every-part) ## CardGrid **Use it for:** A grid of peer cards. The cards are the consumer's; this owns the columns, the gap and, when asked, the arrival. ```ts import CardGrid from '@ambiqai/helia-ui/astro/CardGrid'; ``` | Prop | Type | Default | Description | | ---------- | ----------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- | | `columns` | `2 \| 3 \| 4 \| 'auto'` | `'auto'` | Columns at the wide end. A named count halves at 62rem and stacks below 42rem; `auto` fits as many as `min` allows. | | `min` | `string` | -- | The narrowest a card may get before `auto` drops a column. Any CSS length; ignored by the named counts. | | `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | The gap between cards. | | `stagger` | `boolean` | `false` | Cascade the cards in as the grid arrives, one `--helia-motion-fast` step apart. | | `equalize` | `boolean` | `false` | Give every row the height of the tallest card on the grid, so a row of uneven cards still lines up. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The cards, in reading order. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#card-grid) ## CardHeader **Use it for:** The title block of a card: an optional eyebrow, the title, optional metadata under it, and an optional trailing action. ```ts import CardHeader from '@ambiqai/helia-ui/astro/CardHeader'; ``` | Prop | Type | Default | Description | | ----------- | ------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `titleAs` | `'h2' \| 'h3' \| 'h4'` | `'h3'` | Heading level for the title. Pick the one the page outline needs. | | `padding` | `PaddingStep` | `'card'` | Inner padding, named by spacing step. `card` follows the density dial; `none` leaves the part to own its gaps. | | `href` | `string` | -- | Links the title, and stretches that link over the whole card. | | `eyebrow` | `string` | -- | The eyebrow text. Prefer this to the `eyebrow` slot in MDX: MDX merges a slotted element and the title text that follows it into one paragraph, which drops the `slot` attribute and folds the eyebrow into the heading's accessible name. The slot stays for markup an attribute cannot carry. | | `step` | `number \| string` | -- | The position in an ordered flow, rendered as a numeral in the leading disc. | | `scale` | `'default' \| 'display'` | `'default'` | `display` takes the title and eyebrow up a step, for a card standing in for a hero. | | `rendition` | `boolean` | `true` | Whether the header states the card's line for the page's markdown rendition. Set it false in a part that wraps this one and states the whole card itself, the way `LinkCard` does; a card stated twice reaches an agent as two cards. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The title text. Omit it and no heading is rendered. - `icon` -- A glyph for the tonal disc before the title, usually an `Icon`. - `eyebrow` -- The label above the title, for markup `eyebrow` cannot carry. - `meta` -- Metadata under the title, such as a date or an author. - `action` -- A trailing control, aligned to the top right of the header. [See it rendered on Cards](https://ambiqai.github.io/helia-ui/cards/#a-card-with-every-part) ## CardList **Use it for:** A short list inside a card: what a plan includes, what a guide covers, the order a flow runs in. ```ts import CardList from '@ambiqai/helia-ui/astro/CardList'; ``` | Prop | Type | Default | Description | | -------------- | --------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `items` (req.) | `string[]` | -- | The lines, in reading order. Plain text: an item needing markup is a composition. | | `marker` | `'check' \| 'bullet' \| 'number'` | `'check'` | What sits before each line. `number` renders an ordered list. | | `icon` | `IconName` | -- | Replaces the glyph on a `check` or `bullet` list. Ignored when `marker` is `number`. | | `padding` | `PaddingStep` | `'card'` | Inner padding, named by spacing step. `card` follows the density dial; `none` leaves the part to own its gaps. | Also accepts `HTMLAttributes<'ul'>`. **Slots** -- none. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#content-first) ## CardMedia **Use it for:** The media region of a card: a fixed-ratio frame around whatever the consumer puts in it — an ``, a ``, an inline SVG, a video poster. ```ts import CardMedia from '@ambiqai/helia-ui/astro/CardMedia'; ``` | Prop | Type | Default | Description | | ------- | -------------------------- | --------- | ---------------------------------- | | `ratio` | `'16/9' \| '4/3' \| '1/1'` | `'16/9'` | Aspect ratio of the frame. | | `fit` | `'cover' \| 'contain'` | `'cover'` | How slotted media fills the frame. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The media. An ``, a ``, an inline SVG, a poster. [See it rendered on Cards](https://ambiqai.github.io/helia-ui/cards/#a-card-with-every-part) ## CardQuote **Use it for:** A quotation as a card part: the line, who said it, and an optional initials mark where a photograph would otherwise have to be found. ```ts import CardQuote from '@ambiqai/helia-ui/astro/CardQuote'; ``` | Prop | Type | Default | Description | | ------------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `attribution` | `string` | -- | Who said it. Rendered beside the mark. | | `detail` | `string` | -- | The line under the attribution: a role, a team, a release. | | `initials` | `string` | -- | One or two letters standing in for a portrait. Decorative. | | `padding` | `PaddingStep` | `'card'` | Inner padding, named by spacing step. `card` follows the density dial; `none` leaves the part to own its gaps. | Also accepts `HTMLAttributes<'figure'>`. **Slots** - `default` -- The quotation. Keep it inline so MDX leaves it phrasing. - `attribution` -- Attribution markup an attribute cannot carry, such as a link. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#content-first) ## Chart **Use it for:** A chart drawn at build and shipped as inline SVG. No client script. ```ts import Chart from '@ambiqai/helia-ui/astro/Chart'; ``` | Prop | Type | Default | Description | | ---------------- | ------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` (req.) | `string` | -- | The chart's heading. Also the accessible name of the SVG. | | `subtitle` | `string` | -- | What is plotted against what. Stands in for the axis titles. | | `caption` | `string` | -- | A note under the chart: provenance, units, a caveat. | | `kind` | `'line' \| 'area' \| 'bar' \| 'scatter' \| 'dot'` | `'line'` | Which marks to draw. `dot` and `scatter` draw the same mark; only `scatter` grids both axes. | | `data` (req.) | `readonly ChartRecord[]` | -- | The rows. Every row carries the `x`, `y` and `series` keys. | | `x` (req.) | `string` | -- | Key on each row for the horizontal position. | | `y` (req.) | `string` | -- | Key on each row for the vertical position. | | `series` | `string` | -- | Key whose distinct values split the rows into series. Omit it for one series. | | `height` | `number` | `CHART_HEIGHT` | The height, in pixels, Plot lays the chart out at. | | `width` | `number` | `CHART_WIDTH` | The width, in pixels, Plot lays the chart out at. The SVG then scales to its container and keeps that aspect ratio, so pick a width near the one it is shown at. | | `density` | `'default' \| 'compact' \| 'comfortable'` | `'default'` | Moves the margins and the tick count. | | `legend` | `'auto' \| 'none'` | `'auto'` | `auto` names the series when there is more than one; `none` never does. | | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Which way the bars run. `horizontal` puts the categories on the y axis and takes the left margin from the longest label. | | `scale` | `ChartScale` | -- | The measure's scale. A `log` axis over a value at or below zero is drawn linear, and the build says so. | | `axis` | `ChartAxisTitles` | -- | Axis titles, for the chart whose unit will not fit in the subtitle. | | `valueLabels` | `boolean` | `false` | Writes each bar's value at its end, where the bands leave room for it. | | `valueFormat` | `(value: number) => string` | -- | How a value is written, on a bar and on a titled or logarithmic axis. | | `referenceLines` | `readonly ChartReferenceLine[]` | -- | Rules across the measure: a baseline, a target, a budget. | Also accepts `HTMLAttributes<'figure'>`. **Slots** - `default` -- Anything that belongs under the chart and above the caption. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#charts) ## ChartGroup **Use it for:** A row of two or three charts that read as one figure. ```ts import ChartGroup from '@ambiqai/helia-ui/astro/ChartGroup'; ``` | Prop | Type | Default | Description | | --------- | ----------------------------------------- | ----------- | ------------------------------ | | `columns` | `2 \| 3` | `3` | Charts across at the wide end. | | `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | The gap between charts. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The charts, in reading order. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#three-across) ## Chip **Use it for:** The pill: a rounded inline label or link. ```ts import Chip from '@ambiqai/helia-ui/astro/Chip'; ``` | Prop | Type | Default | Description | | ------ | ----------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `tone` | `'neutral' \| 'accent' \| 'static'` | `'neutral'` | `neutral` is the default outlined pill and reacts to pointer state when it links; `accent` is the filled badge; `static` is read-only metadata. | | `size` | `'sm' \| 'md'` | `'sm'` | `sm` is the metadata size, `md` the standalone one. | | `href` | `string` | -- | Where it goes. Its presence is what makes this an anchor. | Also accepts `Omit, 'href'>`, `HTMLAttributes<'span'>`. **Slots** - `default` -- The label, and the link text when `href` is set. [See it rendered on Primitives](https://ambiqai.github.io/helia-ui/primitives/#chip) ## CodeBlock **Use it for:** A code sample rendered through Expressive Code: the highlighted source in a frame, with the frame's own copy control. ```ts import CodeBlock from '@ambiqai/helia-ui/astro/CodeBlock'; ``` | Prop | Type | Default | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` (req.) | `string` | -- | The source, verbatim. It is also what the copy control puts on the clipboard. | | `tone` | `'default' \| 'muted'` | -- | Background surface, independent of the frame variant. Omit to inherit the site default. | | `language` | `\| 'bash' \| 'c' \| 'cpp' \| 'diff' \| 'json' \| 'plaintext' \| 'python' \| 'sh' \| 'tsx' \| 'typescript'` | `'plaintext'` | Grammar to highlight with. | | `filename` | `string` | -- | Path shown in the frame's title. Takes precedence over `label`. | | `label` | `string` | -- | Frame title when there is no `filename`. With neither, the frame carries no visible title; a terminal frame is still named to assistive technology. | | `highlightLines` | `readonly number[]` | `[]` | 1-based line numbers to mark as changed or worth reading first. | | `lineNumbers` | `boolean` | `false` | Renders the line-number gutter. | | `variant` | `'bare' \| 'code' \| 'terminal'` | `'code'` | `code` is the framed default, `terminal` the shell form, `bare` drops the frame, leaving the highlighted source on its own. | | `class` | `string` | -- | Forwarded to the frame, so a layout can size it without reaching inside. | **Slots** -- none. [See it rendered on Code](https://ambiqai.github.io/helia-ui/code/#file-example) ## CodeTabs **Use it for:** One code sample shown several ways: a tab per language or per toolchain, with only the selected panel visible. ```ts import CodeTabs from '@ambiqai/helia-ui/astro/CodeTabs'; ``` | Prop | Type | Default | Description | | ------------- | -------------------- | ----------------- | ------------------------------------------------------------------------ | | `tabs` (req.) | `readonly CodeTab[]` | -- | The samples, in tab order. The first one renders selected. | | `ariaLabel` | `string` | `'Code examples'` | Accessible name for the tab list or the select. | | `variant` | `'tabs' \| 'select'` | `'tabs'` | `tabs` is the row of tabs; `select` is the dropdown for a narrow column. | **CodeTab** | Prop | Type | Default | Description | | ----------------- | ------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- | | `label` (req.) | `string` | -- | The tab's text, and how the panel is named to assistive technology. | | `language` (req.) | `\| 'bash' \| 'c' \| 'cpp' \| 'json' \| 'plaintext' \| 'python' \| 'sh' \| 'tsx' \| 'typescript'` | -- | Grammar to highlight this tab's source with. | | `code` (req.) | `string` | -- | The source for this tab, verbatim. | **Slots** -- none. [See it rendered on Code](https://ambiqai.github.io/helia-ui/code/#language-tabs) ## DataTable **Use it for:** A scrollable data table with an optional client-side pager. ```ts import DataTable from '@ambiqai/helia-ui/astro/DataTable'; ``` | Prop | Type | Default | Description | | ---------------- | -------------------------------- | ------- | -------------------------------------------------------------------- | | `columns` (req.) | `readonly string[]` | -- | Header cells, left to right. Sets the column count. | | `rows` (req.) | `readonly (readonly string[])[]` | -- | Body rows, each one cell per column, in column order. | | `caption` (req.) | `string` | -- | The table's caption, and the accessible name of its pager. Required. | | `pageSize` | `number` | `0` | Rows per page. 0 renders every row and no pager. | **Slots** -- none. [See it rendered on Layout](https://ambiqai.github.io/helia-ui/layout/#data-table) ## EditorialBand **Use it for:** A full-bleed band across the content column: the paint reaches the viewport edges while the text stays on the readable measure. ```ts import EditorialBand from '@ambiqai/helia-ui/astro/EditorialBand'; ``` | Prop | Type | Default | Description | | ------ | ------------------- | -------- | ------------------------------------------------------------------------- | | `tone` | `'base' \| 'paper'` | `'base'` | The ground. `base` is the page background; `paper` paints the paper fill. | | `id` | `string` | -- | Anchor for the section, so a nav or a deep link can reach it. | **Slots** - `default` -- The band's content, held to the readable width. [See it rendered on Layout](https://ambiqai.github.io/helia-ui/layout/#editorial-band) ## Eyebrow **Use it for:** The uppercase label that sits above a heading. ```ts import Eyebrow from '@ambiqai/helia-ui/astro/Eyebrow'; ``` | Prop | Type | Default | Description | | ---- | --------- | ------- | ---------------------------------------------------------------------------- | | `as` | `HTMLTag` | `'p'` | Element to render. Use a `` where a paragraph would break the outline. | Also accepts `HTMLAttributes<'p'>`. **Slots** - `default` -- The label text. [See it rendered on Primitives](https://ambiqai.github.io/helia-ui/primitives/#eyebrow) ## Hero **Use it for:** The top of a landing page: what the thing is, in one headline, with the ways in under it and the evidence beside it. ```ts import Hero from '@ambiqai/helia-ui/astro/Hero'; ``` | Prop | Type | Default | Description | | -------------- | ------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- | | `variant` | `'plain' \| 'contrast'` | `'plain'` | The ground. `contrast` is the inked card, `plain` the same layout with nothing behind it. | | `align` | `'start' \| 'center'` | `'start'` | Centers a standalone headline and its actions. | | `size` | `'default' \| 'compact' \| 'section'` | `'default'` | Compact uses the page heading scale; section uses the smaller section heading scale. | | `eyebrow` | `string` | -- | The label above the headline, rendered in an `Eyebrow` with the accent dot. | | `eyebrowIcon` | `string` | -- | Decorative product mark replacing the eyebrow accent dot. | | `eyebrowStyle` | `'label' \| 'brand'` | `'label'` | Product identity uses the landing brand scale; labels keep compact eyebrow type. | | `summary` | `string` | -- | The claim under the headline: one sentence, not a paragraph. The `summary` slot wins over it. | | `palette` | `'product' \| 'neutral'` | `'product'` | Neutral emphasis and filled primary action, without changing semantic colors elsewhere. | | `badge` | `string` | -- | A short standing label under the headline, rendered as an accent `Badge`. | | `titleAs` | `'h1' \| 'h2'` | `'h1'` | Heading level for the headline. A page's own hero is the `h1`; a section hero is not. | | `as` | `'section' \| 'div'` | `'section'` | Element to render. A hero that opens the page should stay a `section`. | Also accepts `HTMLAttributes<'section'>`. **Slots** - `default` -- The headline. Wrap the word that takes the product accent in ``. - `summary` -- The lede as markup rather than as the `summary` prop, for one that carries bold or inline code. It wins over the prop. - `actions` -- The ways in, usually `Button`s. The `primary` one is drawn as the accent outline rather than the ink pill. - `aside` -- A framed panel at the top of the side column: a grid of `StatCard`s, a short list of figures. - `media` -- The rest of the side column: a `CodeBlock`, a diagram, artwork. Anything that owns its own frame fits. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#hero) ## Icon **Use it for:** A named icon from Font Awesome's free solid set, resolved at build time. ```ts import Icon from '@ambiqai/helia-ui/astro/Icon'; ``` | Prop | Type | Default | Description | | ------------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` (req.) | `IconName` | -- | Font Awesome solid name in kebab case, e.g. `gauge-high`. | | `label` | `string` | -- | Accessible name. Omit it for decoration next to text that already says the same thing; supply it when the icon is the only thing carrying the meaning. `text` is already that name, so the two are not combined. | | `text` | `string` | -- | The word the glyph belongs to, drawn after it. It names the pair, so the glyph goes to the accessibility tree as decoration. | | `size` | `'sm' \| 'md' \| 'lg'` | -- | A step on the type scale for the glyph and, in the `text` form, for the word with it. Left off, the icon is `1em` of whatever it sits in, which is what an icon in a sentence wants. | Also accepts `HTMLAttributes<'span'>`. **Slots** -- none. [See it rendered on Primitives](https://ambiqai.github.io/helia-ui/primitives/#icon) ## IconRow **Use it for:** A linked row: an `IconTile`, a title with the directional cue, and one line about where the row goes. ```ts import IconRow from '@ambiqai/helia-ui/astro/IconRow'; ``` | Prop | Type | Default | Description | | -------------- | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------- | | `title` (req.) | `string` | -- | The row's text, and the link's accessible name. | | `href` | `string` | -- | Where the row goes. Without it the row renders as plain content, with no link and no hover. | | `titleAs` | `'h2' \| 'h3' \| 'h4'` | `'h3'` | Heading level for the title. Pick the one the page outline needs. | | `icon` | `IconName` | -- | Font Awesome solid name for the tile. Omit it and the `icon` slot carries the glyph. | | `variant` | `'outlined' \| 'tinted' \| 'filled'` | `'tinted'` | The tile's frame. Passed straight to `IconTile`. | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The tile's box. Passed straight to `IconTile`. | Also accepts `Omit, 'title'>`. **Slots** - `default` -- The one line under the title. - `icon` -- A glyph for the tile, when `icon` is not the way to reach it. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#icon-rows) ## IconTile **Use it for:** A square frame around one glyph: the mark that lets a row, a card or a panel stand up without artwork. ```ts import IconTile from '@ambiqai/helia-ui/astro/IconTile'; ``` | Prop | Type | Default | Description | | --------- | ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------- | | `name` | `IconName` | -- | Font Awesome solid name in kebab case, e.g. `gauge-high`. Omit it and the slot carries the glyph. | | `label` | `string` | -- | Accessible name for the glyph. Omit it where the text beside the tile already says the same thing. | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The box, on the control-height scale. | | `variant` | `'outlined' \| 'tinted' \| 'filled'` | `'tinted'` | What stands in for the frame: a hairline edge, the accent at tint weight, or the accent solid. | Also accepts `HTMLAttributes<'span'>`. **Slots** - `default` -- The glyph, when `name` is not the way to reach it: an inline ``, a brand mark, a numeral. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#icon-tiles) ## Landing **Use it for:** Bounded composition for product landing pages shared by HPX and AOT. ```ts import Landing from '@ambiqai/helia-ui/astro/Landing'; ``` No props. Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The product introduction and feature sections. [See it rendered on Landing pages](https://ambiqai.github.io/helia-ui/landing/) ## LinkCard **Use it for:** A whole card that is one link: a title, a line about it, and a cue that moves when the card is under the pointer. ```ts import LinkCard from '@ambiqai/helia-ui/astro/LinkCard'; ``` | Prop | Type | Default | Description | | -------------- | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `href` (req.) | `string` | -- | Where the card goes. | | `title` (req.) | `string` | -- | The link text, and the card's accessible name. | | `titleAs` | `'h2' \| 'h3' \| 'h4'` | `'h3'` | Heading level. Pick the one the page outline needs. | | `eyebrow` | `string` | -- | The label above the title. | | `meta` | `string` | -- | One line of metadata under the title, such as a date or a source. | | `tone` | `CardTone` | -- | What stands in for the card's edge and fill. Passed straight to `Card`. `ink` takes the accent on the title. | | `density` | `'default' \| 'compact' \| 'comfortable'` | -- | Moves the padding step the parts default to. Passed straight to `Card`. | | `lift` | `boolean` | -- | Adds the hover lift. Passed straight to `Card`. | Also accepts `Omit, 'title'>`. **Slots** - `default` -- The line of description under the title. - `icon` -- A glyph for the tonal disc before the title, usually an `Icon`. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#linkcard) ## Masonry **Use it for:** Cards of unequal height packed into columns, with no dead space under the short ones. For a content-first set -- quotes, notes, lists -- where forcing every card to one height is what makes the set look padded. ```ts import Masonry from '@ambiqai/helia-ui/astro/Masonry'; ``` | Prop | Type | Default | Description | | --------- | ----------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- | | `columns` | `2 \| 3 \| 4` | `3` | Columns at the wide end. Three and four halve at 62rem, and everything is one column below 42rem. | | `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | The gap between cards. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The cards. Each one is kept whole across a column break. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#masonry) ## Media **Use it for:** Generative artwork for a card that has no real image: oversized blurred forms, or a sparse field of planes, orbits and wires. ```ts import Media from '@ambiqai/helia-ui/astro/Media'; ``` | Prop | Type | Default | Description | | ----------- | -------------------------------------------------- | --------------- | -------------------------------------------------------------- | | `treatment` | `'color-field' \| 'graphite' \| 'slate' \| 'wire'` | `'color-field'` | Which artwork the surface draws. | | `ratio` | `'16/9' \| '4/3' \| '1/1'` | -- | Aspect ratio. Omit inside a `CardMedia`, which owns the frame. | Also accepts `HTMLAttributes<'div'>`. **Slots** -- none. [See it rendered on Media](https://ambiqai.github.io/helia-ui/media/#generative-artwork) ## MediaEmbed **Use it for:** A hosted video, held behind its poster until someone asks for it. ```ts import MediaEmbed from '@ambiqai/helia-ui/astro/MediaEmbed'; ``` | Prop | Type | Default | Description | | ---------------- | -------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` (req.) | `string` | -- | What the video is. Names the frame, the play control, and the fallback link. | | `videoId` (req.) | `string` | -- | The YouTube video ID, not a URL. Validated at build. | | `posterSrc` | `string` | -- | Poster image. A bare path is resolved against the site's base; an absolute path, a URL, or a data URI is used as given. Omit it for the abstract placeholder. | | `posterAlt` | `string` | `''` | Alternative text for the poster. Leave it empty where the title already says the same thing. | | `caption` | `string` | -- | Caption under the figure. Omit it and no figcaption renders. | | `duration` | `string` | -- | Running time, shown over the poster. Free text, for example `4:12`. | | `href` | `string` | `` `https://www.youtube.com/watch?v=${videoId}` `` | Where the fallback and caption links go. Defaults to the watch URL for `videoId`. | | `class` | `string` | -- | Forwarded to the figure, so a layout can size it without reaching inside. | **Slots** -- none. [See it rendered on Media](https://ambiqai.github.io/helia-ui/media/#hosted-video) ## Mosaic **Use it for:** One card given the room to carry artwork, with the rest of the set beside it. For the head of a section, where a grid of equals says nothing about which of them is the point. ```ts import Mosaic from '@ambiqai/helia-ui/astro/Mosaic'; ``` | Prop | Type | Default | Description | | --------- | --------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `pattern` | `'feature-start' \| 'feature-end' \| 'feature-top'` | `'feature-start'` | Where the feature sits on the wide layout: two columns by two rows at the start or the end of the set, or one row across the top. | | `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | The gap between cards. | Also accepts `HTMLAttributes<'div'>`. **Slots** - `default` -- The cards. The first is the feature; the rest fill around it. [See it rendered on Gallery](https://ambiqai.github.io/helia-ui/gallery/#mosaic) ## RefIndex **Use it for:** A searchable, filterable index of every symbol in a generated reference. ```ts import RefIndex from '@ambiqai/helia-ui/astro/RefIndex'; ``` | Prop | Type | Default | Description | | ------------------ | -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | | `reference` (req.) | `ReferenceModel` | -- | The parsed `reference.json`, imported by the page. | | `label` | `string` | `'Symbol index'` | The table's caption and the accessible name of the search box. | | `base` | `string` | `'/'` | Site base path, so a row's link resolves. Pass the same value the reference was rendered with. | | `routePrefix` | `string` | `'reference/api'` | Where the generated pages live under the content root. | | `groups` | `readonly RefIndexGroup[]` | -- | The symbol families, in the order they are offered. Without them every row is ungrouped and no group filter appears. | | `ungrouped` | `string` | `'Other'` | What a symbol no group matches is called. | | `kinds` | `readonly SymbolKind[]` | -- | Which kinds to index. An empty array indexes every kind. | | `includeMembers` | `boolean` | `false` | Whether struct fields and enum values get rows of their own. | | `overlay` | `RefIndexOverlay` | -- | The kernel manifest: facet values and contract fields, keyed by symbol name. | | `facetLabels` | `Record` | -- | Facet labels by facet id, for a vocabulary the defaults do not cover. | | `placeholder` | `string` | `'Filter by name'` | Placeholder for the search box. | | `height` | `string` | `'32rem'` | Height of the scroll frame the rows sit in, as a CSS length. Filtering moves nothing below it. | | `class` | `string` | -- | Forwarded to the island's root element. | **Slots** -- none. [See it rendered on Data display](https://ambiqai.github.io/helia-ui/react/data-display/#symbol-index) ## RefMembers **Use it for:** The index of what is on a reference page: every symbol, its kind, and a sentence, each one an anchor. ```ts import RefMembers from '@ambiqai/helia-ui/astro/RefMembers'; ``` | Prop | Type | Default | Description | | -------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` (req.) | `readonly RefMemberItem[]` | -- | The items, in the order the page renders them. | | `label` | `string` | -- | Accessible name for the list, for example "On this page". It names the `
    ` rather than a `