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 <details> per item, the first one open.

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

AsciiTerminal

Use it for: A terminal transcript: a fixed set of lines, optionally typed out on entry, with optional copy and replay controls.

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

Badge

Use it for: A read-only label on the Chip recipe, tinted by an advisory tone.

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

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.

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

Bars

Use it for: A few labeled bars against a shared scale, drawn as tracks rather than as a plot.

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

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.

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

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.

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

BlockDiagram

Use it for: The canvas a set of Blocks is drawn on: a figure, an optional caption, and the arrangement of the blocks directly inside it.

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

Button

Use it for: The call to action: a pill-shaped link or button.

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<HTMLAttributes<'a'>, 'href'>, HTMLAttributes<'button'>.

Slots

• default — The label, and the accessible name of the control.

See it rendered on Primitives

Callout

Use it for: An aside on a Surface: a titled block with a tone and the icon that tone implies.

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

Card

Use it for: The card container: a Surface that carries no padding of its own.

import Card from '@ambiqai/helia-ui/astro/Card';

Prop	Type	Default	Description
as	Exclude<HTMLTag, 'a'>	'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

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.

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

CardContent

Use it for: The body of a card: a padding region around whatever the consumer writes.

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

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.

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

CardHeader

Use it for: The title block of a card: an optional eyebrow, the title, optional metadata under it, and an optional trailing action.

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

CardList

Use it for: A short list inside a card: what a plan includes, what a guide covers, the order a flow runs in.

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

CardMedia

Use it for: The media region of a card: a fixed-ratio frame around whatever the consumer puts in it — an <img>, a <Media>, an inline SVG, a video poster.

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 <img>, a <Media>, an inline SVG, a poster.

See it rendered on Cards

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.

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

Chart

Use it for: A chart drawn at build and shipped as inline SVG. No client script.

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

ChartGroup

Use it for: A row of two or three charts that read as one figure.

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

Chip

Use it for: The pill: a rounded inline label or link.

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<HTMLAttributes<'a'>, 'href'>, HTMLAttributes<'span'>.

Slots

• default — The label, and the link text when href is set.

See it rendered on Primitives

CodeBlock

Use it for: A code sample rendered through Expressive Code: the highlighted source in a frame, with the frame’s own copy control.

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

CodeTabs

Use it for: One code sample shown several ways: a tab per language or per toolchain, with only the selected panel visible.

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

DataTable

Use it for: A scrollable data table with an optional client-side pager.

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

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.

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

Eyebrow

Use it for: The uppercase label that sits above a heading.

import Eyebrow from '@ambiqai/helia-ui/astro/Eyebrow';

Prop	Type	Default	Description
as	HTMLTag	'p'	Element to render. Use a <span> where a paragraph would break the outline.

Also accepts HTMLAttributes<'p'>.

Slots

• default — The label text.

See it rendered on Primitives

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.

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 <em>.
• 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 Buttons. 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 StatCards, 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

Icon

Use it for: A named icon from Font Awesome’s free solid set, resolved at build time.

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

IconRow

Use it for: A linked row: an IconTile, a title with the directional cue, and one line about where the row goes.

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<HTMLAttributes<'a'>, '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

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.

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 <svg>, a brand mark, a numeral.

See it rendered on Gallery

Landing

Use it for: Bounded composition for product landing pages shared by HPX and AOT.

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

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.

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<HTMLAttributes<'div'>, '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

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.

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

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.

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

MediaEmbed

Use it for: A hosted video, held behind its poster until someone asks for it.

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

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.

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

RefIndex

Use it for: A searchable, filterable index of every symbol in a generated reference.

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<string, string>	—	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

RefMembers

Use it for: The index of what is on a reference page: every symbol, its kind, and a sentence, each one an anchor.

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 <ul> rather than a <nav> landmark. A page-level index of symbols sits inside the article, and a second navigation landmark called “On this page” collides with the one Starlight already puts in the page.
layout	'grid' | 'list'	'grid'	grid lays the items out in columns on a wide screen; list keeps one per row.
class	string	—	Forwarded to the wrapper.

RefMemberItem

Prop	Type	Default	Description
id (req.)	string	—	The symbol’s fully qualified path. Used as the anchor unless href is set.
name (req.)	string	—	The short name, shown as the link text.
kind	string	—	What the symbol is, shown beside the name.
summary	string	—	One line about it.
href	string	—	Where the link goes, when the target is not an anchor on this page.

Slots — none.

See it rendered on Gallery

RefNav

Use it for: The module tree of a reference, as nested lists of links.

import RefNav from '@ambiqai/helia-ui/astro/RefNav';

Prop	Type	Default	Description
items (req.)	readonly RefNavItem[]	—	The tree, in the order the reference publishes it.
label	string	—	Accessible name for the navigation, for example “API reference”.
current	string	—	The href of the page being viewed, marked with aria-current="page".
depth	number	0	Nesting depth. The part sets this on itself as it recurses so that only the outermost call renders the <nav> element; a caller leaves it alone.
class	string	—	Forwarded to the outermost element.

RefNavItem

Prop	Type	Default	Description
label (req.)	string	—	What the entry is called. Usually the last segment of a module path.
href	string	—	Where it goes. An entry with no link is a grouping label.
items	readonly RefNavItem[]	—	Submodules.

Slots — none.

See it rendered on Gallery

RefParams

Use it for: The table under a symbol: its parameters, its return values, or the errors it raises.

import RefParams from '@ambiqai/helia-ui/astro/RefParams';

Prop	Type	Default	Description
caption (req.)	string	—	What the table lists. Rendered as the table’s <caption>, so it is the accessible name.
rows (req.)	readonly RefParamsRow[]	—	The rows, in declaration order. Order is the extractor’s decision, not this part’s.
density	'comfortable' | 'default' | 'compact'	'default'	compact for a long generated reference, comfortable for a short hand-written one.
nameLabel	string	'Name'	Header for the name column. Property and Field are the usual overrides.
typeLabel	string	'Type'	Header for the type column.
defaultLabel	string	'Default'	Header for the default column. Requirement is the usual override.
descriptionLabel	string	'Description'	Header for the description column.
class	string	—	Forwarded to the scroll box, so a layout can size it without reaching inside.

RefParamsRow

Prop	Type	Default	Description
name	string	—	The parameter, field or return label. Omit for an unnamed return.
type	string	—	The declared type, as source text.
default	string	—	The default as written, or a requirement note such as “Required”.
description (req.)	string	—	What it is for, in a sentence. The only column that is always shown.

Slots — none.

See it rendered on Gallery

RefSection

Use it for: A labeled block inside a reference entry: “Parameters”, “Returns”, “Examples”.

import RefSection from '@ambiqai/helia-ui/astro/RefSection';

Prop	Type	Default	Description
title (req.)	string	—	The label above the content.
id	string	—	Anchor, when something needs to link straight to this section.
class	string	—	Forwarded to the wrapper, so a page can space sections without reaching inside.

Slots

• default — The section’s content: a table, a code block, or prose.

See it rendered on Gallery

RefSymbol

Use it for: One entry in an API reference: the symbol’s header, its signature, and whatever the caller puts in the body.

import RefSymbol from '@ambiqai/helia-ui/astro/RefSymbol';

Prop	Type	Default	Description
id (req.)	string	—	The symbol’s fully qualified path. Doubles as the anchor and the self-link target.
name (req.)	string	—	The short name shown in the header.
kind (req.)	SymbolKind	—	What the symbol is. Rendered as the leading badge.
language (req.)	ReferenceLanguage	—	Which language it belongs to. Rendered as the trailing chip and, unless signatureLanguage overrides it, picks the grammar.
signature (req.)	string	—	The declaration, as source text. Already wrapped by the extractor.
signatureLanguage	'bash' | 'c' | 'cpp' | 'json' | 'plaintext' | 'python' | 'tsx' | 'typescript'	—	Grammar override, for a signature that is not written in the symbol’s own language.
summary	string	—	One sentence under the header. Everything longer belongs in the body.
source	{ path: string; line?: number; url?: string }	—	Where the symbol is declared. Shown as a link when url is set, as plain text otherwise.
since	string	—	The release it first appeared in.
deprecated	string	—	The deprecation notice, already one sentence. Its presence is what marks the symbol.
level	2 | 3 | 4	2	Heading rank. A module page puts its symbols at 2 and their members at 3.
class	string	—	Forwarded to the article.

Slots

• default — The body: description, parameter tables, examples, members.

See it rendered on Gallery

ReferenceBrowser

Use it for: A compact reference index with consumer-owned rows and filters. All entries are present without JavaScript.

import ReferenceBrowser from '@ambiqai/helia-ui/astro/ReferenceBrowser';

Prop	Type	Default	Description
rows (req.)	readonly RefIndexRow[]	—	Consumer-owned reference entries, including their existing destinations.
filters	readonly RefIndexFacet[]	—	Ordered filters with consumer-defined meanings and values.
label (req.)	string	—	Search field and region label.
nameLabel	string	—	First column heading.
itemsLabel	string	—	Plural noun in result counts and empty state.
placeholder	string	—	Search hint.
pageSize	number	—	Rows per page after hydration; without JavaScript all rows remain visible.

Slots — none.

See it rendered on Reference browser

Reveal

Use it for: Entry animation for whatever it wraps: a short fade and rise the first time the element reaches the viewport.

import Reveal from '@ambiqai/helia-ui/astro/Reveal';

Prop	Type	Default	Description
threshold	number	0.15	How much of the element has to be in view before it reveals, 0 to 1. Lower it for a tall section that would otherwise never cross the mark.
stagger	boolean	false	Cascade the direct children instead of revealing the wrapper as one block: each child waits one --helia-motion-fast step longer than the one before it, to a ceiling of six. Use it on a grid of cards.

Also accepts HTMLAttributes<'div'>.

Slots

• default — The content to reveal. Visible without JavaScript.

See it rendered on Gallery

SectionHeader

Use it for: The heading of a page section: an optional label, the title, an optional line under it, and an optional link to the fuller view.

import SectionHeader from '@ambiqai/helia-ui/astro/SectionHeader';

Prop	Type	Default	Description
eyebrow	string	—	The uppercase label above the title.
title (req.)	string	—	The section’s heading. Required.
titleAs	'h2' | 'h3' | 'h4'	'h2'	Heading level for the title. Pick the one the page outline needs.
description	string	—	One line about the section, under the title.
href	string	—	Where the trailing link goes. Without it, no link renders.
linkLabel	string	'View all'	The trailing link’s text. Ignored without href.

Also accepts Omit<HTMLAttributes<'header'>, 'title'>.

Slots — none.

See it rendered on Layout

ShowcaseCarousel

Use it for: The card rail: a scroll-snapping track of whatever cards the consumer slots in, with one tab per card and previous/next controls.

import ShowcaseCarousel from '@ambiqai/helia-ui/astro/ShowcaseCarousel';

Prop	Type	Default	Description
tabs (req.)	readonly string[]	—	One label per card, in the order the cards are slotted.
variant	'feature' | 'compact'	'feature'	feature is the large-media default used by the demos and catalog pages. compact is the text-forward variant: a short media band above eyebrow, title, description, and date, all inside a single bordered card.

Slots

• default — The cards, in the same order as tabs.

See it rendered on Layout

Sparkline

Use it for: A trend at control size, drawn at build and shipped as inline SVG.

import Sparkline from '@ambiqai/helia-ui/astro/Sparkline';

Prop	Type	Default	Description
values (req.)	readonly number[]	—	The series, in order. The index is the horizontal position.
ariaLabel (req.)	string	—	What the trend says, as one sentence. The accessible name of the SVG.
kind	'line' | 'area'	'line'	line draws the stroke alone; area fills under it as well.
width	number	SPARKLINE_WIDTH	The width, in pixels, Plot lays the sparkline out at. It ships at that size.
height	number	SPARKLINE_HEIGHT	The height, in pixels, Plot lays the sparkline out at.
marker	boolean	false	Draws a dot on the last point, where a reader looks first.
lastValue	string	—	The last point written out, set beside the line. The caller formats it, units and all.

Also accepts HTMLAttributes<'span'>.

Slots — none.

See it rendered on Gallery

SplitPanel

Use it for: A wide panel holding a short piece of writing beside the thing it describes: a quickstart, a release note, an API call with the call shown.

import SplitPanel from '@ambiqai/helia-ui/astro/SplitPanel';

Prop	Type	Default	Description
tone	'tinted' | 'muted' | 'plain'	'tinted'	The ground. tinted carries the accent at tint weight, muted the recessed fill, plain a hairline and no fill.
ratio	'1:1' | '2:3' | '3:2'	'1:1'	The share of the width the text column and the code column take at the wide end.
density	'compact' | 'default' | 'comfortable'	'default'	Inner padding.
titleAs	'h2' | 'h3' | 'h4'	'h2'	Heading level for the title. Pick the one the page outline needs.
as	'section' | 'div' | 'aside'	'section'	Element to render. A panel that is a section of the page should stay a section.

Also accepts HTMLAttributes<'section'>.

Slots

• eyebrow — The label above the title, rendered in an Eyebrow.
• title — The heading’s text. The panel renders the heading element itself, so keep the slot phrasing.
• body — The line or two under the title.
• actions — The controls under the body, usually Buttons.
• code — The block beside the text: a CodeBlock, a CodeTabs, or anything that frames itself.

See it rendered on Gallery

Stack

Use it for: A chain of labeled layers read along the page: what sits above a thing, the thing itself, and what it runs on.

import Stack from '@ambiqai/helia-ui/astro/Stack';

Prop	Type	Default	Description
layers (req.)	StackLayer[]	—	The layers, ordered from the top of the stack to the bottom.
ariaLabel	string	'Stack'	Accessible name for the diagram.

Also accepts HTMLAttributes<'ol'>.

StackLayer

Prop	Type	Default	Description
label (req.)	string	—	What the layer is, rendered as the eyebrow over its chips.
chips	StackChip[]	—	The pills in the layer, in display order.
accent	boolean	—	Marks this layer as the page’s own. At most one across the stack.

Slots — none.

See it rendered on Gallery

StatCard

Use it for: A single figure with its label, and an optional change beside it.

import StatCard from '@ambiqai/helia-ui/astro/StatCard';

Prop	Type	Default	Description
label (req.)	string	—	What the figure counts. Rendered as the eyebrow above it.
delta	string	—	The change beside the figure. Omit it and no badge renders.
deltaTone	BadgeTone	'neutral'	Which way the change reads. The component does not decide.
tone	CardTone	—	What stands in for the card’s edge and fill. Passed straight to Card.
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.
interactive	boolean	—	Adds the hover shift and the focus-visible ring. Passed straight to Card.

Also accepts HTMLAttributes<'div'>.

Slots

• default — The figure itself, with whatever unit or markup it needs.
• sparkline — A Sparkline under the figure, showing how it got there.

See it rendered on Gallery

Surface

Use it for: The card surface: hairline border, shared radius, one of three backgrounds.

import Surface from '@ambiqai/helia-ui/astro/Surface';

Prop	Type	Default	Description
as	HTMLTag	'div'	Element to render. Ignored when href is set.
tone	'card' | 'muted' | 'paper'	'card'	Background: the raised card, the recessed muted fill, or paper.
padding	'none' | 'card' | 'px' | '1' | '2' | '3' | '4' | '5' | '6'	'4'	Inner padding, named by spacing step.
interactive	boolean	false	Adds the shared hover background shift and the focus-visible ring.
href	string	—	Renders an <a> regardless of as.

Also accepts HTMLAttributes<'div'>.

Slots

• default — Whatever the surface holds.

See it rendered on Primitives

Timeline

Use it for: A dated list of grouped entries: releases, changes, or planned work.

import Timeline from '@ambiqai/helia-ui/astro/Timeline';

Prop	Type	Default	Description
groups (req.)	TimelineGroup[]	—	The groups, in display order.
heading	string	—	Heading above the rail. Omit it where the page already has one.
actionLabel	string	—	Text of the trailing link in the header. Needs actionHref to render.
actionHref	string	—	Where the trailing link goes. Needs actionLabel to render.
ariaLabel	string	heading ?? 'Timeline'	Accessible name for the rail. Defaults to heading, then to Timeline.
variant	'updates' | 'roadmap'	'updates'	updates reads as history, roadmap as planned work.

TimelineGroup

Prop	Type	Default	Description
label (req.)	string	—	The group’s marker text, usually a date or a milestone.
datetime	string	—	Machine-readable date for the label, as an HTML datetime value.
tone	'neutral' | 'blue' | 'cyan' | 'green' | 'orange' | 'purple'	—	Advisory tint for the group’s marker. The caller decides what it means.
items (req.)	TimelineItem[]	—	The group’s entries, in display order.

Slots — none.

See it rendered on Timeline