# 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

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

## Bare snippet

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

## Terminal

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

## Language tabs

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

## Diff

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

```text
$ 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.

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

```text
$ 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.

```text
$ 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.

```text
$ 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.

```text
$ 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

- 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

- 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

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.

```bash title="Terminal"
npm install example-package
```

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

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

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