# Understudy design language

Version 2.0. Updated July 2026.

This is the canonical visual and content reference for Understudy. It evolves
the warm paper, ink, and stamp system used by understudylabs.com with the
model language developed for the native app and the marketing mood board.

The rendered reference lives at `https://design.understudylabs.com/`. Its
source lives in `app/page.tsx`, `app/globals.css`, and `components/`.
Machine-readable tokens live in `tokens/`. The same spec is served as Markdown
at `https://design.understudylabs.com/design.md` for agents and LLMs.

## The idea

Understudy observes the work. Understudy finds what wins. Understudy builds
the better performer.

The interface should feel observant, exact, and alive. Every visible choice
should help someone understand identity, activity, evidence, or progress.

## Principles

### Evidence earns attention

Show the result, trace, comparison, or system state. Do not ask decoration to
carry a claim that the evidence can prove.

### Color has a job

Foundation colors establish the surface. The stamp identifies Understudy.
Model colors identify actors. State colors report outcomes. Do not use the
model palette as confetti.

### Motion explains work

Breath means activity. Orbit means delegation. Transfer means data or work
moving between actors. Promotion means a candidate passed a gate. Motion is
part of the model, not a flourish.

### Structure stays quiet

Use hairline borders, restrained radii, and almost no elevation. Let the
actors and evidence carry the emphasis.

### Complexity remains inspectable

Rich diagrams are welcome. Keep their labels, states, and relationships
legible. A person should be able to say what moved, why it moved, and what the
result means.

## Visual grammar

The visual language maps system concepts to stable shapes.

| Concept | Shape | Meaning |
| --- | --- | --- |
| Understudy house assistant | White halo | The observing system |
| Open model | Circle with a visible core | Internals can be inspected |
| Closed model | Regular tile or regular hexagon | Internals are not exposed |
| Anthropic profile | Upright rounded-square tile colony | Anthropic closed-model reference |
| OpenAI profile | Upright point-top hexagon lattice | OpenAI closed-model reference |
| Delegated worker | Small orbiting body | Work handed to another actor |
| Request or trace | Packet, trail, or moving point | Work or evidence in transit |
| Model state | Ring color and breath | Identity plus current activity |
| Promotion | Mint-green ring and gate | Candidate beat the incumbent |
| Lineage | Connected nodes | Parentage and search history |
| Micro-ID | Compact outlined capsule | Exact system reference |

Shape identifies the actor. Color identifies the family or state. Motion
identifies what is happening.

Vendor profiles are reference glyphs for explicit vendor comparisons. Keep
every tile and hexagon regular. Rotate the colony or lattice as a group; never
skew its individual cells. Use the generic closed-model shape when the vendor
is unknown or user-defined.

Vendor identity is separate from model state. Anthropic uses clay. OpenAI uses
an adaptive neutral: `#0A0A0A` on light surfaces and `#E7E8EA` on dark
surfaces. OpenAI is identified primarily by its regular point-top hexagon
lattice. Shade every cell uniformly with a faint neutral fill so the lattice
reads as sealed. Do not use mint or promoted green as an OpenAI identity color.

## Color

### Foundation

The warm website palette remains the brand foundation. The black field is a
special surface for model theater, simulation, and high-density evidence.

| Token | Light | Dark | Use |
| --- | --- | --- | --- |
| `--color-paper` | `#F5F2ED` | `#141311` | Page background |
| `--color-window` | `#EFECE6` | `#0B0C0E` | Native shell and outer frame |
| `--color-content` | `#F5F2ED` | `#0E0F12` | Primary content plane |
| `--color-card` | `#FFFFFF` | `#141519` | Raised or grouped content |
| `--color-hover` | `#ECEAE4` | `#1C1E25` | Hover and selected neutral |
| `--color-ink` | `#0A0A0A` | `#E7E8EA` | Primary text and marks |
| `--color-ink-bright` | `#0A0A0A` | `#F2F2F0` | Model theater and key data |
| `--color-ink-muted` | `#6B6862` | `#9B9DA3` | Secondary text |
| `--color-rule` | `rgba(0,0,0,.10)` | `rgba(255,255,255,.08)` | Hairline border |
| `--color-rule-strong` | `rgba(0,0,0,.16)` | `rgba(255,255,255,.14)` | Control and active border |
| `--color-field` | `#000000` | `#000000` | Model theater only |

### Brand

| Token | Light | Dark | Use |
| --- | --- | --- | --- |
| `--color-stamp` | `#B24A2E` | `#D7623E` | Understudy identity, provenance, sparse emphasis |

Terracotta belongs to Understudy. It is not the default button color and it
is no longer the only permitted accent.

### Model identity

| Token | Value | Default meaning |
| --- | --- | --- |
| `--model-house` | `#FFFFFF` | Understudy house assistant |
| `--model-clay` | `#D97757` | Closed model family A |
| `--model-mint` | `#9EDBD3` | Closed model family B and primary operational accent |
| `--model-amber` | `#F2B34C` | Data-taking and supervised training |
| `--model-violet` | `#A78BFA` | Search, lineage, and critic systems |
| `--model-cyan` | `#67E8F9` | Parallel work, RLM workers, and trace flow |

Keep model-family mappings stable inside a surface. Do not imply a permanent
vendor mapping when the UI is showing arbitrary user models.

### Vendor identity

| Token | Light | Dark | Use |
| --- | --- | --- | --- |
| `--vendor-anthropic` | `#D97757` | `#D97757` | Anthropic in explicit vendor comparisons |
| `--vendor-openai` | `#0A0A0A` | `#E7E8EA` | OpenAI in explicit vendor comparisons |

Vendor color names the vendor only. It never means active, promoted, healthy,
or failed. Keep the vendor label visible and show state with a separate label,
ring, or position.

In palette references, present Anthropic and OpenAI together as one “Closed
models” competitor card with two labeled circles. Clay identifies Anthropic.
Adaptive neutral identifies OpenAI. Their actor geometry remains distinct in
the visual grammar.

### State

| Token | Value | Use |
| --- | --- | --- |
| `--state-promoted` | `#6EE7A0` | Passed gate, promoted candidate, verified improvement |
| `--state-ok` | `#3FB950` | Healthy system state |
| `--state-warn` | `#D29922` | Needs attention |
| `--state-bad` | `#F85149` | Failure or destructive action |

Mint and cyan carry the operational voice of the new system. Use mint for
the main candidate, route, or comparison emphasis. Use cyan for fanned-out
work and information in motion. Green is reserved for an earned result.

Do not rely on hue alone to separate mint, cyan, and promoted green. Render
mint as a filled candidate core, cyan as an outlined route or moving trace,
and promoted green as a filled result with an outer gate ring. Keep the role
label visible.

### Contrast

Body copy must meet WCAG AA. Small uppercase labels must not rely on opacity
below 55 percent on the field. Color cannot be the only state signal. Pair it
with a label, shape, or position.

## Typography

### Structural type

IBM Plex Mono carries identity, controls, navigation, diagrams, IDs, data,
and short declarative headlines.

Weights: 300, 400, 500, 600.

### Reading type

IBM Plex Sans carries instructions, explanations, documentation, and dense
product prose. Native macOS surfaces may use SF Pro Text for the same role.

Weights: 400, 500, 600.

### Roles

| Role | Family | Size | Treatment |
| --- | --- | --- | --- |
| Display | Plex Mono | `clamp(2.5rem, 6vw, 5.8rem)` | 400, tight leading |
| Page title | Plex Mono | `clamp(1.8rem, 4vw, 3.4rem)` | 400, tight leading |
| Section title | Plex Mono | `1.35rem` to `2rem` | 400 to 500 |
| Body | Plex Sans | `0.95rem` to `1.05rem` | 400, 1.6 leading |
| UI body | Plex Sans or native sans | `0.82rem` to `0.9rem` | 400 to 500 |
| Label | Plex Mono | `0.62rem` to `0.72rem` | 500, uppercase, `0.14em` to `0.2em` tracking |
| ID and metric | Plex Mono | `0.68rem` to `0.9rem` | 400 to 500, tabular numbers |

Use all-mono pages when the surface is brief and diagrammatic. Move sustained
reading into Plex Sans. This is a role distinction, not a decorative font
pairing.

## Spacing and layout

Use a 4px base unit. The preferred spacing sequence is 4, 8, 12, 16, 24, 32,
48, 64, 96, and 128px.

| Container | Maximum width |
| --- | --- |
| Reading | 720px |
| Product form | 880px |
| Marketing content | 1120px |
| Wide evidence | 1280px |

Use 1px rules to create structure before adding filled panels. Split dense
regions with aligned borders. Let sections breathe before adding cards.
Surface-profile cards use a 2px boundary because the register itself is the
subject. Cedar-style voice cards use separated 12px shells rather than a
single flat grid.

## Radius and elevation

| Token | Value | Use |
| --- | --- | --- |
| `--radius-id` | 4px | Micro-IDs and square chips |
| `--radius-control` | 8px | Inputs and segmented controls |
| `--radius-card` | 12px | Model and evidence cards |
| `--radius-panel` | 16px | Rare large contained region |
| `--radius-pill` | 999px | Status, compact filters, model chips |

Do not put every section in a rounded container. Do not use large soft
shadows as hierarchy. On the field, a low-opacity radial light may reveal a
working actor. On paper, prefer borders and spacing.

## Motion

All motion uses `--motion-ease: cubic-bezier(0.2, 0.7, 0.2, 1)` unless the
movement represents a constant orbit.

| Motion | Duration | Meaning |
| --- | --- | --- |
| Control | 120 to 160ms | Hover, focus, selection |
| Settle | 600ms | Page or section arrival |
| Transfer | 2.4 to 2.8s | Request, trace, or data movement |
| Breath | 5.2s | Active actor or promoted state |
| Training cycle | 7 to 12s | Multi-step operation |
| Orbit idle | 26s linear | Delegation present |
| Orbit active | 16s linear | Delegated work active |

Motion must state what changed. Pause decorative or looping motion when the
page is not visible. Honor `prefers-reduced-motion` by freezing the final,
most informative state.

## Components

### Buttons

Use a filled ink button once per local task. Secondary actions use a hairline
border. Stamp buttons are rare and brand-specific. Destructive buttons use
the bad state token and always include a precise label.

On operational field surfaces, mint identifies the active action and cyan
identifies trace or parallel-work actions. Put dark ink on cyan and mint fills;
white text does not meet the intended contrast on these colors.

### Segmented controls

Use for small state sets. Keep the container quiet and the selected segment
one contrast step brighter. Do not use segmented controls as navigation for
unrelated pages.

### Cards

Cards group one actor, one comparison, or one decision. Model cards may carry
a 12px radius on the black field. Marketing and documentation sections can
remain square when a border grid communicates the structure better.

Operation exploration cards use the shipped Cedar phase-card shell: a 12px
outer radius, 16px padding, a 96px black thumbnail field, one mono name, one
plain-language sentence, and a source reference. Use them to compare related
operational ideas without expanding every diagram at once. Selection reveals
the full pattern below the cards.

- `04F · rubric calibration` evolves `08 · swipe`: reject left or accept right
  so the scoring rule learns from human correction. The decided card exits in
  the chosen direction and reveals the next candidate in the stack.
- `04G · optimization record` combines `06A` and `06B`: the step-line shows
  the hill climb; lineage shows how the frontier compounded.

Do not use the phase-card shell as a generic dashboard container. It names an
operation and leads to evidence or an interaction.

### IDs and labels

Use micro-ID capsules for exact references such as `04B`, `RUN-21`, or
`V5`. Pair the ID with a plain label. IDs are not decoration.

### Evidence panels

Name the metric, baseline, evaluation set, and result. Put the threshold in
the same view as the outcome. A chart without a comparison or decision does
not belong.

### Forms

Labels remain visible after input. Help text uses reading type. Errors say
what happened and what the user can do. Do not use placeholder text as the
only label.

## Surface profiles

### Field

Use for model theater, simulation, training choreography, and high-density
evidence. Black background, bright ink, 9 percent card borders, model colors,
and defined motion.

### Website

Use the warm dark paper, ink, rule, and stamp system. Mint can identify the
candidate, route, or product cycle. Green appears only after an earned win.
Keep the current website's editorial spacing and square evidence grids.

### Product

Use dark surface tiers, Plex Sans for product reading, Plex Mono for system
structure, and the semantic model palette inside comparisons and operational
views.

### Native

Use the same semantic tokens with native window, content, card, hover, and
overlay tiers. SF Pro Text may replace Plex Sans. Keep Plex Mono for labels,
IDs, traces, and model operations.

### Paper

Use for LMAB, reports, documents, and long evidence. Warm off-white paper,
black ink, light rules, restrained stamp, and model color only where it
identifies a subject or result.

## Content design

### Voice

Understudy says what it means. The voice is direct, confident, specific, and
plain. Confidence comes from work that can be shown.

Use one operating rule:

> Say the claim. Show the evidence. Name the action.

### Attributes

| Attribute | Do | Do not |
| --- | --- | --- |
| Direct | Make one clear point per statement. | Repeat the point in clauses. |
| Earned confidence | Use examples and results that can be inspected. | Pad the claim with sales language. |
| Unapologetic | Take a position and defend it with work. | Hedge to avoid disagreement. |
| Data-first | Name the metric, baseline, and result. | Generalize without specifics. |
| Non-pretentious | Use common words when they are precise. | Use jargon to sound technical. |
| Legacy-aware | Name predecessors with respect and distance. | Insult teams, vendors, or prior work. |

Challenge the default, not the people who chose it.

### Sentence rules

- Put one point in each sentence.
- Prefer active verbs.
- Name the model, workload, metric, or result.
- Keep the proof close to the claim.
- Remove adjectives that the evidence already proves.
- Expand into a longer sentence only after the reader has the premise.
- Use technical terms when ordinary words would be less precise.

### Claim order

Lead with evidence when credibility is the question. Lead with the claim when
the reader needs orientation, then show proof in the same view. Never leave a
strong claim unsupported below the fold.

### Product language

Master operating line:

> Test. Learn. Deploy. Repeat.

Customer promise:

> Use the data you have. Build the model you need.

Platform description:

> Understudy turns production traces into smaller models, tests them
> head-to-head, and deploys them when they win.

Design-guide orientation line:

> Understudy Optimizes the Complete LLM Production Route

Use “helps you deploy” when the product does not perform the promotion itself.

Campaign language can be sharper:

- Don't use their model. Use yours.
- Fire their models.
- Move beyond the frontier.
- Build a better performer.

Do not use campaign lines as product descriptions.

### Evidence standard

Every public result should name the metric, baseline, evaluation set, and
date or run. Label estimates. Separate customer results from internal tests.
Do not publish a percentage without saying what changed.

### UI copy

Buttons name the next action: “Compare models,” “Inspect traces,” “Run an
evaluation.” Loading states name the work. Errors name the failure and the
next recovery step.

Weak: “Something went wrong.”

Understudy: “The evaluation stopped. The verifier returned no score.”

Weak: “Unlock powerful optimization capabilities.”

Understudy: “Compare every model on your workload. Deploy the one that wins.”

## Assets

Use `svgs/usl-stamp.svg` for the Understudy stamp. Preserve `currentColor` and
the paper knockout. Use source Rive personas for halo, command, and glint when
the product needs animated model identity. Do not redraw supplied brand
assets.

## Governance

`understudy-design` owns the reference. Shipped product code can move first
when speed requires it, but the reference must be updated in the same work
stream. Product repos should record the design token version they copied.

Change a foundation token only when the change improves more than one
surface. Add semantic colors only when they have a named job. Document new
motion before using it twice.

## Files

```text
.
├── design.md
├── globals.css
├── tokens/
│   ├── primitives.json
│   ├── semantic.json
│   └── motion.json
├── examples/
│   └── mood-board.html
├── svgs/
│   └── usl-stamp.svg
└── assets/
```