git:20261024.3715fee to git:20261025.ead452c

# LangAlpha Web Design System — "Quiet Workspace"

The visual language of the web app (`web/`): a quiet, charcoal-and-paper research

workspace where **content is the interface** and color is reserved for meaning.

Tokens are the single source of truth — every value below lives in

`web/src/styles/tokens.css`, and every `var(--color-*)` referenced anywhere must

be declared there (enforced by `web/src/styles/__tests__/tokenRefs.test.ts`).

## Identity

- **Temperature**: dark charcoal layers / light warm paper. No decorative

gradients anywhere (`--color-accent-gradient` is intentionally flat).

- **Accent**: burnished amber — `#E9954A` (dark) / `#D07D33` (light). It is an

**annotation color, not a brand fill** (see Accent discipline).

- **Radius**: soft, growing with the element. Pick from the scale, never a new value:

4px inline code · 6px thumbnails · 8px (`--radius`) the default for rows, tables

and most surfaces · 12px transcript file cards and the composer's send button ·

pills (half the height) for chips, tags and avatars.

- **One exception, the chat composer at 22px**: concentric with its 12px send

button, which sits 10px from the bottom edge (12 + 10). The todo tab tucked

behind it takes 16px, about 0.7× the composer. Change the composer's radius

and the send button's radius or inset together, or the corner pinches.

- **Depth**: borders first, shadows second (`--shadow-card` is the only card

shadow); never glows.

## Palette (both themes live in tokens.css)

| Role | Dark | Light |

|---|---|---|

| Page ground | `hsl(var(--background))` charcoal ~#191919 | white |

| Canvas under card grids | = page | `#F5F4F1` warm paper |

| Cards | `hsl(var(--card))` ~#202020 | white + `#E8E8E6` hairline |

| Elevated (menus, tooltips) | `#2A2B2E` | `#F7F7F6` |

| Primary text | `#E6E6E4` | `#1F1F1E` |

| Focus ring | = primary text | = primary text |

| Accent (annotation) | `#E9954A` | `#D07D33` |

| Primary button | `#ECECEA` bg / `#1A1B1D` text | `#1F1D1A` bg / `#FAF9F7` text |

| Profit / loss | `#3FB950` / `#F85149` | `#1A7F37` / `#CF222E` |

| Warning | `#D8B04C` | `#B45309` |

Background roles (`bg-page` → `bg-canvas` → `bg-card`/`bg-tool-card` →

`bg-elevated`, `bg-input`, `bg-popover`) are documented in the comment block

above the background group in `tokens.css` — pick by surface role, never by

matching a hex. Floating surfaces deliberately do not share one fill yet; don't

converge one of them in isolation.

## Typography

| Role | Face | How |

|---|---|---|

| Display / headings | **Sora** | `.title-font` (`--font-ui`, tracking −0.01em) |

| UI + body | **Geist** (+ Noto Sans SC for CJK) | `--font-ui` / `--font-content` |

| Data, numbers, kickers | **JetBrains Mono** | literal stack at call sites (`'JetBrains Mono', 'Menlo', monospace`) |

Tabular numerals (`font-variant-numeric: tabular-nums`) wherever digits align.

## Accent discipline (the rule that makes the system)

Amber is **annotation-only**: small icons, dots, chips, thin indicators, the

ascii liveness glyph. Never:

- a button or CTA fill, wash, ring, or glow;

- a **one-sided accent bar** on a card, panel, or blockquote — liveness and

state are carried by glyphs + text, and borders stay uniform neutral. The

only sanctioned edge markers are **nav selection** (sidebar rail edge,

bottom-bar underline, watchlist active row).

The rule governs the product's own surfaces. Illustrations that *depict* the

product are not one of them: the onboarding intro panels draw a miniature of the

app rather than being part of it, and they carry the accent structurally, in

washes, glows and fills. A picture of a branded thing reads as brand, not as

state. The alternative is a picture whose color has to be kept in step with the

brand by hand, which is how that panel spent a rebrand still showing the old one.

**The sign-in page is the one product surface that is exempt**, and the reason

is that the rule has nothing to bite on there. It carries no chrome, no

navigation and no data, so there is nothing for the accent to annotate. Amber

is its whole interaction vocabulary instead: the submit button has always taken the

fill on hover, and keyboard focus takes the same fill rather than inventing a

second language for the same "about to act" state. Focus is not left to hue

alone, since hue is what a color deficiency flattens: an underline by default, a

doubled edge on the boxed controls, an outline under forced colors. The exemption

is the `.login-page` surface itself, not the route it mounts on: the same build

serves the app from that route once someone is signed in.

Semantic color (profit/loss/warning/danger) is separate from the accent and

never substitutes for it.

## Status & liveness vocabulary

- **Live work** renders an amber liveness glyph beside text that says what is

running, never a spinning lucide icon. The ascii `Loader`

(`web/src/components/ui/loader.tsx`) marks running rows, chips and cards; the

`FigureEightLoading` orbit sits under a reply while its text is still, the

agent at work with nothing yet to type. Reduced motion slows both rather than

stopping them: a glyph that changes is not movement across the screen.

- **A running label shimmers**, and it is the one looping text treatment:

`TextShimmer` sweeps the title of a running tool call, the reasoning row's

label while it streams, the reader's own message while it is still being

delivered (pending, steering or queued), and a chart's loading label. It

ends with the work, it stops under reduced motion, and nothing else loops on

text.

- **Completed** on dense surfaces (nav subagent rows) renders **no glyph**:

absence of the liveness glyph is the done state. Roomier surfaces (status

bar) may keep a celebratory check.

- Exceptional terminal states keep informative glyphs (error = alert,

cancelled = stop, spawned-idle = hollow circle).

- A running turn lists its tool calls a row per call. The status line, opt-in

in Settings while it is being tried out (`other_preference.tool_call_layout:

'status'`), shows one line naming the current step under the counts of the

finished ones, in the same glyphs and shimmer. A turn shows one line, on its

newest activity. Between steps the line holds the step that last finished,

settled, until the next one takes its place, and it stays while the reply

types under it; it goes when the turn ends and folds its work away. The step

a turn opens on, a thought or a call, runs where the counts will be, at their

height, so nothing is held empty above the line: a reply finds it where it

ran, and the next step turns it into the count in place, with the line coming

in under it. The line's steps are drawn at that height too.

- Status/icon mappings live in one table per vocabulary

(`web/src/pages/ChatAgent/components/taskStatusUi.tsx`); surfaces declare

overrides there instead of restating ladders.

## Motion

Motion says something changed: it arrived, left, opened, closed or was pressed.

Nothing moves for decoration. A loop says something is live: the vocabulary

above, a loading skeleton, a live-data dot, a microphone listening.

**One vocabulary**, `web/src/lib/motion.ts`, mirrored for CSS in `tokens.css`:

| Token | Value | For |

|---|---|---|

| `DURATION.press` · `--motion-press` | 100ms | the press scale |

| `DURATION.quick` · `--motion-quick` | 160ms | color and hover, a menu, tooltip or chip appearing |

| `DURATION.fold` · `--motion-fold` | 240ms | a section folding, a panel growing to fit |

| `DURATION.enter` · `--motion-enter` | 280ms | a dialog, sheet or card entering |

| `DURATION.exit` · `--motion-exit` | 140ms | anything leaving |

| `DURATION.reveal` · `--motion-reveal` | 360ms | streamed text fading in as it is typed |

| `STAGGER` · `--motion-stagger` | 40ms | between the items of a batch |

Curves: `EASE_OUT` (`--ease-out`), fast out with a long settle, for nearly

everything; `EASE_REVEAL` (`--ease-reveal`) for a fade that must not pop, such

as streamed text, which `EASE_OUT` has at half opacity a tenth of the way in;

`EASE_COLLAPSE` (`--ease-collapse`) for a tall box closing, so the content

under it does not leap. Springs: `SPRING_FOLD` (disclosures, chevrons),

`SPRING_SNAPPY` (live rows), `SPRING_INDICATOR` (knobs, sliding markers) and

`SPRING_DRAG` (whatever a finger lets go of), each damped to at least 0.85 of

critical, so nothing overshoots. Tailwind's bare `transition` and

`transition-colors` already run `quick` on `EASE_OUT`, and `duration-*` and

`ease-*` take the token names.

- **Enter and settle; leave faster.** A small surface pops in at its anchor

(`.pop-in`: menus, popovers, hover cards, tooltips), a dialog uses

`.pop-in-center` and a sheet `.sheet-in`. One state replacing another in

place crossfades rather than cutting, through `SwapCell`

(`web/src/components/ui/crossfade.tsx`), which keeps the leaving state from

screen readers and clicks.

- **Folds are measured.** A box changes height by tweening measured px, through

the one fold, `Disclosure` (`web/src/components/ui/Disclosure.tsx`). Inside

the chat scroller nothing hands framer `auto` or a `layout` prop: resolving

one forces a layout that clamps the scroll offset.

- **Live rows open, then rise in.** A row of a running turn opens its space

first, and its content rises a few px into it as it fades in once the space

is nearly open; leaving, the content fades and lifts first and the space

closes after (`LiveRow`). A step that replaces another on the status line

rises in as the old one lifts out (`SwapCell`'s `riseKey`). A box opening

over content already showing drew every glyph top first, cut off at the

bottom. A row opening from rest is launched at its spring's own rate, so the

space is nearly open in 160ms and the content comes in that much sooner.

- **Press, not hover.** A committing button scales to 0.97 (`PRESS_SCALE`,

`--press-scale`) over `press`, through the shared `Button` or the `press`

class, which carries its own transition list and so never sits beside a

`transition-*` class. Hover changes color, background or border and never

size. What moves on hover moves 2px at most: an arrow nudging toward where it

leads, a chip or the sign-in buttons lifting 1px.

- **Stagger only a batch the reader asked for**, and only its first few items.

- **Reduced motion** is one block in `styles/animations.css` for every CSS

transition and keyframe, plus framer's `MotionConfig` for transforms. What

neither reaches (a framer opacity loop, an imperative `animate()`, a smooth

scroll) asks `useMotionSafe()` or `scrollMotion()` in

`web/src/lib/reducedMotion.ts`.

- **No literals.** A duration, curve or spring written outside `motion.ts`,

`tokens.css` and `animations.css` fails lint for scripts and

`styles/__tests__/motionTokens.test.ts` for CSS. A value no token names on

purpose, such as a loop's period, takes an exemption with its reason.

**Pin your message, then follow.** On send the reader's message holds near the

top of the transcript and the reply fills the room under it; once the reply

outgrows that room the view glides after its tail

(`web/src/pages/ChatAgent/components/chatView/useChatScroll.ts`).

## Empty states

Dot-grid texture is reserved for empty states only — never behind content.

## Working rules

1. New colors enter through `tokens.css` (both themes, plus the role comment)

— never a hex literal in a component. Canvas painters that can't read CSS

variables go through `web/src/lib/themeTokens.ts`.

2. Style both themes in the same change; the light theme is a first-class

surface, not an inversion.

3. Buttons are quiet: `--color-btn-primary-*` for primary, neutral borders for

secondary. `--color-text-on-accent` exists solely for text sitting on an

amber accent fill (rare, annotation-scale).

4. Liveness = glyph + text, per the vocabulary above; motion = the tokens in

§ Motion.

5. When in doubt, remove decoration rather than add it.