Skip to content
helia-ui
Sections
HELIA HUB

Code

Code samples should be easy to scan, copy, and compare. Keep labels useful, highlight only the lines that require attention, and avoid decorative editor chrome.

File example

Section titled “File example”

Use a filename when the sample belongs in a specific project location. Line numbers and highlights are optional.

src/measurements.ts
const samples = [5.2, 4.8, 5.0, 4.9];


export function averageLatency(values: number[]) {
const total = values.reduce((sum, value) => sum + value, 0);
return total / values.length;
}

Bare snippet

Section titled “Bare snippet”

Use the bare variant for short, self-contained examples that do not need a filename, terminal context, or language switcher.

const measurements = {
latencyMs: 4.8,
peakMemoryKb: 184,
};


console.log(measurements);

Terminal

Section titled “Terminal”

Terminal blocks keep commands and representative output together without imitating a complete terminal application.

Terminal window
$ npm run check


Result (48 files):


- 0 errors
- 0 warnings

Language tabs

Section titled “Language tabs”

Use tabs for equivalent implementations. Do not hide unrelated steps or materially different workflows behind language selection.

const average = values.reduce((sum, value) => sum + value, 0) / values.length;

Diff

Section titled “Diff”
Configuration change
 engine: tflm
 engine: heliaRT
measurements:
  - latency
  - peak_memory

ASCII terminal

Section titled “ASCII terminal”

AsciiTerminal renders a command-and-output transcript as markup. Give it lines; a command line gets a prompt, every other kind is output. The default form ships no JavaScript at all, which makes it the right choice for reference transcripts and for ASCII diagrams that need a monospace grid.

Expected output
$ npm run build Resolving configuration… ENTRY src/index.ts TARGET es2022 ✓ Build complete

Spaces are preserved and the viewport scrolls horizontally rather than wrapping, so the component also holds a diagram that has to keep its columns.

Build path
source │ ▼ compiler ──▶ bundle ──▶ artifact

Add animated when watching a short sequence unfold is part of the explanation. Commands then type character by character and output arrives a line at a time, with replay as an explicit control. copy adds a clipboard action for the whole transcript. Either option makes the component emit its behavior script, so ask for them deliberately.

First run
$ npx create-thing my-app Fetching template… CREATED my-app/ ! remember to set an accent color ✓ Ready

A transcript that shows commands and their output can still hand the reader just the commands. copy="commands" copies the command lines alone, without prompts, so what lands in the shell is what the page told them to run.

Install the CLI
$ npm install --global @ambiqai/helia-cli added 42 packages in 3s $ helia --version 1.4.0

A page can carry as many animated transcripts as the explanation needs. The second and later frames replay and autoplay like the first, each one following its own autoplay setting.

Doctor
$ npx thing doctor Checking toolchain… NODE 24.4.1 x missing board support package ! 1 check failed

Set autoplay={false} when the reader should decide. The transcript then sits complete and still until the replay control is used.

Manual start
$ npx thing deploy --dry-run Planning… UPLOAD 2 artifacts ✓ Nothing to change

tone decides which way round the transcript reads. adaptive, the default, follows the page theme. light is dark ink on a fixed pale backdrop and dark is pale ink on a fixed dark one; both keep their palette when the reader switches themes, which is what you want for a screenshot-like transcript sitting in a light page.

Under prefers-reduced-motion: reduce the complete transcript is shown at once and the caret does not blink, whether or not the reader had already started an animation. The <pre> is hidden from assistive technology and a visually hidden copy of the transcript carries the reading order, so a partially typed line is never announced.

Authoring guidance

Section titled “Authoring guidance”
  • Animate one short sequence, not a long live log.
  • Use command lines for what the reader types and output lines for responses.
  • Keep measured performance claims out of illustrative transcripts.
  • Prefer the static form for output a reader needs to scan quickly.

What the parts cover

Section titled “What the parts cover”
  • Copyable code and terminal blocks
  • Bare snippets with a floating copy action
  • Filename and language context
  • Optional line numbers and highlights
  • Keyboard-accessible language tabs
  • Diff presentation
  • Static and animated terminal transcripts

CodeBlock renders through Expressive Code, which is what the Starlight plugin themes, so it and a fenced block on the same page are the same object. CodeTabs renders through Shiki directly. Both highlight at build time, so a page pays no JavaScript for highlighting and the copy button is the only script either one ships. AsciiTerminal is not highlighted at all and ships nothing unless asked.

Terminals inside tabs

Section titled “Terminals inside tabs”

The tab labels the terminal, so its nested frame omits the title bar and keeps the copy control. Standalone terminals and file examples retain their framing.

Terminal
npm install example-package

Muted backgrounds

Section titled “Muted backgrounds”

Use tone="muted" for a neutral gray surface that follows the page theme. The frame, syntax highlighting and copy control work the same way. Omit tone to inherit the site setting, or use tone="default" to select the ordinary card surface.

import numpy as np
frame = np.zeros(320, dtype=np.float32)
Terminal window
python --version
value = 42

Set the site default for Markdown fences and component blocks in the Starlight plugin:

heliaStarlight({ code: { tone: 'muted' } });

The existing code: true and code: false options keep their behavior. A site’s explicit Expressive Code frame backgrounds still take precedence over the plugin default.

print("ordinary surface")