brand-ui — TerminalSurface

import { TerminalSurface } from "@elabs-ai/components-terminal";

Install

npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-terminal

Skipping the @source line is the most common first failure: Tailwind does not scan node_modules, so every component renders unstyled. The one-time wiring

Prompt for your coding agent

Paste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.

Add the brand-ui TerminalSurface component (from @elabs-ai/components-terminal) to this project.

1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`.
2. Look TerminalSurface up before writing code: `npx -y @elabs-ai/components-cli docs TerminalSurface` prints its real props, variants, what it pairs with and what to avoid.
3. If @elabs-ai/components-terminal is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-terminal` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-terminal`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`.
4. Use it here: [the screen or file, and what it should show]
5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop.
6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.

Avoid

Adding a second value to its context — it publishes `variant` and nothing else; transcript state, expansion state and a clock all belong to the caller or to the row (D5).
Expecting it to scroll — it owns no scroll container on purpose, so a caller's virtualizer for a long transcript is never fought.
Declaring `--terminal-gutter` in themes.css — it is a local layout custom property, not a theme token; it does not vary by theme.
Reaching for a spinner while `loading` — the not-ready rung is layout-shaped skeleton rows rendered through the real TerminalRow, behind exactly one live region.

Works with

Contains

TerminalRow

Pairs with

Examples

7 live examples

Marker

A glyph in the gutter cell. Reads as a bullet transcript.

Rail

A rule down the gutter, glyph suppressed — the accessible label remains.

Boxed

A square framed block per row. Reads as frame-drawing output.

Loading

Restoring a past session. Layout-shaped placeholders reserve the real grid — never a spinner — behind exactly one polite announcement.

Wide Gutter

A wider gutter, for a two-character marker.

Row Without Surface

A row outside any surface still renders legibly. That is the difference between a surface and a required provider.

API

`TerminalSurface`

Prop	Type	Description
`variant`	`TerminalVariant`	Gutter grammar for every row inside. A row may override it per-row.
`gutter`	`string`	Width of the gutter track, as any CSS length. Written to the local `--terminal-gutter` custom property — deliberately NOT a theme token: it does not vary by theme and no other package needs it. A caller's own `style` still wins over this.
`loading`	`boolean`	`true` while the transcript has no renderable content yet (restoring a past session). Renders layout-shaped skeleton rows through the REAL `TerminalRow`, so the placeholder cannot drift from the grid it stands in for. Never a spinner.
`loadingRows`	`number`	How many skeleton rows to reserve while `loading`.
`loadingLabel`	`string`	Overrides the announced loading label. Defaults to the shared "Loading…".

Also accepts: HTMLAttributes<HTMLDivElement>

`TerminalRow`

variant: marker (default)railboxed

Prop	Type	Description
`variant`	`TerminalVariant`	Gutter grammar. Omitted, the row inherits the surrounding `TerminalSurface`; passed, it overrides it, so a row still renders correctly outside any surface.
`gutter`	`ReactNode`	What sits in the gutter cell — usually one glyph. Decorative by default.
`gutterLabel`	`string`	The meaning the gutter glyph carries, as words. Set it whenever the glyph is not purely ornamental; it is announced and it survives greyscale.
`children`	`ReactNode`

Also accepts: Omit<HTMLAttributes<HTMLDivElement>, "children">, Omit<VariantProps<typeof terminalRowVariants>, "variant">

Theming

The tokens each state resolves to. Change the token and every theme follows.

State	Token
surface	`bg-terminal-background text-terminal-foreground border-terminal-border`
elevation	`shadow-sm`