# Gallery This page is for choosing. Every option the card parts and the motion system offer is on it, side by side, each one showing the exact source that produces it behind "Show code". Nothing here is a new component: the variants are modifiers on `Card` and the transitions are classes in `recipes.css`. The reference tables are on [Cards](https://ambiqai.github.io/helia-ui/cards/) for the parts and in `docs/design-system.md` for the motion tokens and the site theme. ## Tone Four tones, each of them a different answer to "what stands in for the edge". `outlined` is the default and `card` is its older name; `filled` and `muted` are likewise the same tone. Padding and radius do not move between them, so a row can mix tones and still line up. A shadow instead of a border. The hairline card, unchanged. The muted fill, for a card inside a surface. Nothing at rest. Point at it for the fill. ## Tone and density together `density` moves the step the card parts pad to: 3 for `compact`, 4 by default, 5 for `comfortable`. A part that names its own step opts out and keeps it. ### Compact Elevated, compact. Outlined, compact. Filled, compact. Ghost, compact. ### Default Elevated, default. Outlined, default. Filled, default. Ghost, default. ### Comfortable Elevated, comfortable. Outlined, comfortable. Filled, comfortable. Ghost, comfortable. ## Media placement `top` is the stacked card. `side` puts the frame down the leading edge at 40% of the card and stacks again below 42rem, so a narrow viewport gets the top placement whatever is asked for. `background` fills the card with the frame, draws an overlay over it, and inverts the ink onto the fixed paper tone. ### The three placements Media on top The frame owns the ratio and the card stacks. Media beside The frame leaves the flow and the card reserves its width, so the header, the body and the actions stay stacked. Media behind The ink inverts to the fixed paper tone, because the overlay is dark in both themes. ## StatCard A figure, its label, and an optional change. The number is the child, so it can carry a unit or markup; the delta is a `Badge` and its tone is the caller's, because the component has no idea whether up is good. 206 41s 12 84 kB ## Figures `BigNumber` is the figure with no card around it: the number at the display step, the unit beside it a step down, and the label above or below. `Sparkline` is the trend at control size, drawn by the same Plot-at-build path as `Chart` and shipped as inline SVG -- no axes, no gridlines, one series in `--helia-chart-1` unless the composition sets `--accent`. The arrow and the ink are two props. `direction` says which way the number went; `deltaTone` says whether that reads well, and only the composition knows, because a figure that counts open findings goes up and that is not good news. Both parts set their figures in tabular numerals, so a row of them lines up on the digit. Every number below is invented and describes this documentation site. Nothing here is a measurement of any part. 206 41 128 41s 84 ## Accent and ink The accent is a hint, not a field, and so is the ink. A page spends both a few times: the accent word in the hero, one inked tile in a mosaic, the layer of a stack the page is about, the leading bar in a comparison, and the link out to the hub. The parts below are what make those moments cheap to write. What a page may spend, and how often, is the accent budget in the design system. ### The inked tile `tone="ink"` puts one card of a set on the ground the contrast hero uses, pinned dark in both themes, with the inks and the accent re-derived against it. The title, which is the link, takes the accent. One of them in a set: two inked tiles is a dark row with a gap in it. - [The card parts](https://ambiqai.github.io/helia-ui/cards/): What each part owns, and how a subset of them composes. - [Bands and grids](https://ambiqai.github.io/helia-ui/layout/): Bands, grids and mosaics, and which one a section wants. - [Tokens and scales](https://ambiqai.github.io/helia-ui/foundations/): The spacing, radius and type ladders every part is built from. ### The accent figure `accent` on a `BigNumber` colors the unit and nothing else. The glyph is the smallest thing on a figure that still reads across a section, so it is what the budget can afford here; the number stays ink. Every number below is invented and measures nothing. 12 8 3 ### Stack `Stack` is the chain of layers a product page opens with: what sits above the thing, the thing, and what it runs on. One layer carries `accent`, and it is the page's own. Below 62rem the chain folds to two columns, because four columns of wrapped pills on a phone is not a diagram. ### Bars `Bars` is the comparison a heading needs and a chart is too heavy for: labeled tracks against one scale, an axis under them, and one accented row. Every row is text as well as a bar, so the reading survives without the tracks. Past a handful of rows, or with a series that has a shape, reach for `Chart`. The figures below are invented and measure nothing. ## LinkCard Title, one line, and a cue that moves when the card is under the pointer. The link lives on the title and the recipe stretches it over the card, so the whole card is the target and the cue is inside the same hit area. ### Four link cards - [The card parts](https://ambiqai.github.io/helia-ui/cards/): What each part owns, and how a subset of them composes. - [Foundations](https://ambiqai.github.io/helia-ui/foundations/): The scales every part compiles against. - [Primitives](https://ambiqai.github.io/helia-ui/primitives/): The four shapes the rest of the system reuses. - [Gallery](https://ambiqai.github.io/helia-ui/gallery/): Every variant on one page, with its source beside it. ### From a model A page that renders its cards from a record writes none of their words in its source. The parts state their own line for the page's Markdown twin, so an agent reading the rendition gets the card the page shows rather than the props it was written with. - [Cards from a model](https://ambiqai.github.io/helia-ui/cards/): Every word of this card comes from a record the page imports. - [Foundations from a model](https://ambiqai.github.io/helia-ui/foundations/) [Read the discoverability guide](https://ambiqai.github.io/helia-ui/starlight-plugin/discoverability/) ## Content-first Six cards that need no image. Good artwork is the scarcest thing a card family depends on, so each of these carries itself on type, a mark or a figure instead. None of them is a new component: they are the `CardHeader` marks and scale, two parts (`CardList`, `CardQuote`) and one `CardContent` variant, so tone, density and the lift reach all of them unchanged. ### Comfortable Latency you can budget Every kernel reports its own cycle count, so a regression has a name before it has a bug report. What the SDK ships with Quantise the graph The converter keeps the calibration set with the artifact, so the same numbers come back on the next run. The profile told us where the cycles went on the first afternoon, which is a week we did not spend guessing. Keyword spotting 18 ms 2.4 mJ 96 kB Ship the model, not the toolchain One card standing in for a hero, with nothing behind it but the type. ### Compact The same six with `density="compact"`. The mark, the list gap and the figure row all come off the density hook, so nothing here is restyled per size. Latency you can budget Every kernel reports its own cycle count. What the SDK ships with Quantise the graph Calibration travels with the artifact. A week we did not spend guessing. Keyword spotting 18 ms 2.4 mJ Ship the model, not the toolchain The type carries it at any density. ## Named transitions Five transitions, each built from the motion tokens and nothing else, so the per-site dial and the reduced-motion rule reach all of them at once. Point at the cards below; none of them does anything at rest. ### Hover targets Hover me: the fill shifts Background and border, 120ms. No transform: a card that moves under the pointer inside a grid reflows the row it shares. Hover me: the card lifts 2px up and one shadow step, 200ms. Never a scale, which would resample the media and the text. - [Hover me: the arrow nudges](https://ambiqai.github.io/helia-ui/gallery/#named-transitions): 2px along, 120ms. The cue moves and the card holds still. [Hover me: the button fills](https://ambiqai.github.io/helia-ui/gallery/#named-transitions) And the pill Button and Chip are on the same 120ms step as the surface, so a card and the controls inside it settle together. ### The carousel glide The fifth transition. The rail reads the same dial the CSS does, so a site with motion switched off gets the jump rather than the slide. Compile Profile Deploy Measure ## Theme knobs The site theme is nine dials in one file. `:root` is where a site sets them; a section that wants its own treatment sets them on a wrapper that carries `data-helia-theme`, which is the hook `semantic.css` re-derives the composed tokens on. That is the mechanism every example below uses, and it is why they can sit next to each other on one page. A wrapper without the attribute moves only the dials themselves, not the radius steps and tinted surfaces built out of them. Square, compact, tinted orange. [Start](https://ambiqai.github.io/helia-ui/gallery/#theme-knobs) Paired The package defaults, for comparison. [Start](https://ambiqai.github.io/helia-ui/gallery/#theme-knobs) Paired Round, comfortable, tinted cyan. [Start](https://ambiqai.github.io/helia-ui/gallery/#theme-knobs) Paired The accent dial reaches a card through its artwork rather than its edge: no card part carries an accent rule or brim, so a subtree that names an accent shows it in the media, the badges and the type. The second accent is the one that pairs with it, and a link card spends it on the cue under the pointer. An orange site. A purple site. Motion off: the lift arrives instantly. ## Reveal on scroll `Reveal` fades and rises what it wraps the first time it reaches the viewport. Use it on a section, not on every card in one: a page where each element arrives separately reads as a page that is still loading. `stagger` is the one exception, and it is still one wrapper. The hidden state is a class the script adds, so the content is visible without JavaScript, and the script returns before arming anything when the motion scale is 0. Replay re-arms every reveal on this page, so the entry can be watched without scrolling away and back. It does nothing for a visitor who asked for reduced motion, because nothing armed. Scroll on. The cards below start hidden and arrive as they reach the viewport. One section, one reveal. The cards inside it arrive together. Which is the point of wrapping the section. A gap, so the staggered grid below is still out of view when the group above arrives. The cascade is on the direct children, so the grid is the `Reveal` rather than a `div` inside it: one wrapper with a grid class on it, and the cards are the children that arrive. With stagger, the children arrive in order. Each one waits a fast step longer than the last. The wrapper itself does not move. The cascade stops at the sixth child. A second gap, so the group below is still out of view when the first arrives. A higher threshold waits until more of the section is in view. Lower it for a section too tall to ever cross the mark. ## Page layout Four parts that arrange a page rather than fill one. None of them knows what it is carrying: the ground, the cards and the artwork are all handed in, so the same four cover a product page, a release note and a landing. ### Band `Band` takes a section to the edges of the reading frame and keeps its content on the readable measure. `tone` picks the ground and `density` the rhythm above and below it. None of the four grounds draws an edge or an elevation: a section that carried either would be a very wide card. Ground A section with a ground of its own The paint runs to the edges of the frame and the words stay on the measure. Nothing is drawn around it. ### Card grid `CardGrid` is the row of peers. A named count steps down at the two breakpoints; `auto` fits whatever `min` allows, which is the answer for a set whose length the page does not know. `stagger` makes the grid the reveal itself, so the cards cascade in rather than the block arriving as one. Columns Two, three, four, or as many as the minimum allows. Equalise Every row takes the height of the tallest card on the grid. Stagger One wrapper, one arrival, told across the row. ### Masonry `Masonry` packs cards of unequal height into columns with no dead space under the short ones. It is CSS columns, so the packing is right in the first paint; the cost is a reading order that runs down each column before it moves across. Masonry packs by column with no JavaScript; use `CardGrid` when rows must align. The profile told us where the cycles went on the first afternoon. Uneven by design A short card next to a long one is what the layout is for. Forcing the two to one height is what makes a set of notes look padded. What the column keeps ### Mosaic `Mosaic` gives one card the room to carry artwork and fills the rest of the set around it. The feature is the first child rather than a prop, so the arrangement follows reading order. `pattern` moves it to the end of the set or across the top. The feature Two columns by two rows, with somewhere to put the artwork. The rest fill the remaining cells. In the order they were written. Nothing here is placed by hand. ### The four together The rest of this section is not an example on a stage: the bands are on the page itself, which is the only way to see a ground actually run to the edges and a run of sections read as one rhythm. Scroll it as a page rather than as a set of parts. Overview One feature and the set around it The one the section is about Artwork needs room, and a grid of equals says nothing about which card is the point. Beside it Peers, at the size a peer deserves. Under it Filled in document order. And on The set is as long as the page needs. Capabilities Three peers on a ground The ground changes The section above it has none, so this one reads as a step rather than as a box. The measure does not Paint to the edges, text on the same width as the prose above it. Nothing is drawn No edge, no brim, no shadow. The ground is the whole of the signal. Notes What came back from the field We stopped arguing about section spacing the week the bands landed. Content first Good artwork is the scarcest thing a card family depends on, so the options that carry a card without an image are the ones a long page leans on. What a note can hold Three columns, no measuring, no layout shift when the font lands. The close The inked ground is pinned dark in both themes, because ink that follows the theme over a ground that does not is a section that reads half the time. Code slotted into it holds the dark syntax theme on either page theme, for the same reason. ```ts title="band.ts" import { Band } from '@ambiqai/helia-ui/astro'; ``` ## Charts `Chart` draws with Observable Plot at build and ships the result as inline SVG, so a page with five charts on it still ships no chart JavaScript. The palette is written as `var(--helia-chart-*)`, which is what lets a figure that will never be redrawn follow the theme toggle. The title and the subtitle are the part's HTML rather than Plot's type, and the subtitle says what is plotted against what — which is why no axis is titled. Gridlines run across the measure; only a scatter, which has a measure on both axes, gets the second set. Every number below is invented and describes this documentation site. Nothing here is a measurement of any part. ### Long names, wide ranges, and a baseline A chart with more categories than a row of bars can name, and a measure that spans more than a decade, needs four options the defaults do not give it. The set below is invented — the routines do not exist and neither do the ratios — but it is shaped like the one the options were written for: fourteen long names, three series, and speedups from under one to twelve. `orientation="horizontal"` puts the categories on the vertical axis and takes the left margin from the longest label, so a name is never cut. The data contract does not move with the drawing: `x` still names the categories and `y` still names the measure. `scale` moves the measure. A log axis ticks at 1, 2 and 5 through each decade it spans and rounds its own ends to that sequence unless `min` and `max` say otherwise, which is what stops a set with one twelve-times result in it from drawing every other bar as a stub. A log axis cannot draw a zero or a negative number: given one, the chart is drawn linear and the build log says why. Inside a group the bars run in the order the rows first name the series, not in the order those names sort in, and the legend lists them in that same order. The series here are written fastest first — `vector path`, `scalar path`, `reference` — which is not alphabetical, so the two orders agreeing is the assertion rather than a coincidence. `axis` titles an axis the subtitle cannot carry the unit for, `valueLabels` writes each bar's value at its end, and `referenceLines` draws a rule across the measure. A constant baseline belongs on the rule rather than in a third series: it costs a palette color, a legend entry and a third of the bars to draw a line. Value labels are dropped as a set when the bands are too small to hold them, so a chart that shows them at one height stops showing them at another rather than overprinting. ### Three across `ChartGroup` gives the charts equal columns, so three drawn at the same `width` and `height` line up across the row and read as one figure. Draw them at a width near the column, not at the page width: the SVG scales into its column and takes its type with it. ## Rows and panels Three parts for an index rather than a grid of cards: the tile that marks an entry, the row that is one entry, and the panel that sets a short piece of writing beside the code it describes. ### Icon tiles The box comes off the control-height scale and the frame is one of three. `--accent` is per instance, so a list can give every entry a color of its own without the part learning what the list holds. ### Icon rows The anchor is the row itself, so the tile, the title and the line are one hit area and one accessible name. Hover tints the row where it sits; nothing lifts. Two to a desktop column and one to a phone is `CardGrid columns={2}`. - [Cards](https://ambiqai.github.io/helia-ui/cards/): Every part of the card family, and the modifiers that move them. - [Code](https://ambiqai.github.io/helia-ui/code/): Fences, language tabs and the terminal transcript. - [Layout](https://ambiqai.github.io/helia-ui/layout/): Bands, grids and the two mosaics. - [Foundations](https://ambiqai.github.io/helia-ui/foundations/): The tokens every recipe on this page is built from. ### Split panel The `code` slot is what the panel exists for: the block is the answer to the sentence beside it rather than a fence further down the page. `ratio` gives the two columns their share of the width, and below 62rem the text leads and the code follows. Quickstart Profile a model on the board The command reads the model, runs it on the attached board and writes the layer timings beside it. ## Hero The top of a landing page. The headline is the default slot rather than a prop, because the word that takes the product accent has to be marked in the markup: wrap it in `` and the hero draws it in `--helia-product-accent` with the slant taken off. The side column renders only when `aside` or `media` has something in it, and below 62rem it stacks under the lede. In MDX the headline goes in a `` on one line, with a blank line between it and every slotted child. Bare text on its own line is flow content, so MDX wraps it in a paragraph inside the heading and pulls the line after it into the same paragraph, which costs the first action its slot. `data-helia-accent` is set on the example itself to show one product's color on a page that carries none. A product site sets it once, through the Starlight plugin's `accent` option, and writes no CSS. The copy here is placeholder, not an approved product claim. The code frame in the side column holds the dark treatment on either page theme, the way one inside a contrast `Band` does, down to the frame's title and buttons. Kernel acceleration for the edge. [Getting started](https://ambiqai.github.io/helia-ui/) [Why](https://ambiqai.github.io/helia-ui/gallery/) [API](https://ambiqai.github.io/helia-ui/reference/) 200+ 53 40+ 4 With no side column and no ground, the same part is the lede on its own measure: a section opener rather than a front door. The lede here is the `summary` slot rather than the prop, which is what a claim carrying bold or inline code needs; the slot wins wherever both are set. Parts, not pages. Every part on this page is composed from the same tokens, so a site adopts **the theme** rather than a stylesheet: the recipes live in `recipes.css` and the site writes none of them. [Foundations](https://ambiqai.github.io/helia-ui/foundations/) [Cards](https://ambiqai.github.io/helia-ui/cards/) ## Reference An API reference is generated, not written, and it is generated for four languages. The extractors differ, the model they produce does not, and these parts render the model: the same header, the same table, the same columns for a Python function, a C function and a TypeScript function. Everything below comes from one hand-written model in `src/lib/reference-gallery-model.ts`. A generated module page carries more symbols than a table of contents will show, so it indexes itself; a site that builds its own sidebar takes the same tree as nested links. ## Other parts The rest of the Astro parts, one example each. They are documented in depth on their own pages; they are here so that one page answers what the package can draw. ```text $ npm run build Resolving configuration… ENTRY src/index.ts TARGET es2022 ! no accent color set x missing tsconfig path alias ✓ Build complete ``` ```text $ npm run docs:build Reading what the parts stated ROUTES 26 renditions written ``` The converter writes it beside the artifact, so the next run starts from the same numbers. A part that names its own step opts out of the hook and keeps it. - [Everything the package draws](https://ambiqai.github.io/helia-ui/reference/astro-parts/): One row above a section, with the link that leaves it. Section label Inline label Neutral Accent Static Linked Medium Medium static [Primary](https://ambiqai.github.io/helia-ui/gallery/#other-parts) [Secondary](https://ambiqai.github.io/helia-ui/gallery/#other-parts) [Ghost](https://ambiqai.github.io/helia-ui/gallery/#other-parts) [Primary, small](https://ambiqai.github.io/helia-ui/gallery/#other-parts) [Secondary, small](https://ambiqai.github.io/helia-ui/gallery/#other-parts) [Ghost, small](https://ambiqai.github.io/helia-ui/gallery/#other-parts) Neutral Info Success Warning Danger Accent Neutral, medium Info, medium With a dot ## Charts after tabular data Standalone plots keep the same separation as other prose blocks. A chart group owns the spacing between its plots. | Build | Size | | ------- | ---- | | Example | 24 | ## Features without navigation ### Planned before deployment A feature row can explain a capability without linking its whole surface.