<!-- source: openspec/current/design-system.md -->

---
title: Design System
status: stable
owner: pavel
audience: [pavel, ai, engineer]
tldr: Umbrella visual-intent spec for the studio design system — philosophy, voice, surface mapping, hard constraints, and the studio-wide WCAG 2.2 AA accessibility contract.
canonical_at: openspec/brands/studio/design-system.md
---
# Design System — capability spec

> The umbrella visual-intent spec for the studio design system. It owns *what the design system is* at the brand level — philosophy, voice, surface mapping, hard constraints — and the corpus-wide accessibility contract. It does **not** own token values, motion curves, component anatomy, or implementation paths; those live in the sister files below.
>
> **Sister files:** [`design-tokens.md`](design-tokens.md) (token registry) · [`design-motion.md`](design-motion.md) (motion) · [`design-components.md`](design-components.md) (component intent) · [`ui.md`](ui.md) (implementation references).
>
> Authority: rules R1, R3, R5, R9, R13 from [`_methodology/design-system-convention.md`](../_methodology/design-system-convention.md). When this file and an implementation reference (`ui.md`) disagree, this file wins.

---

## 1. Philosophy

The studio's visual language is **editorial, tactical, and flat**. It reads like a well-set book overlaid with a blueprint — never like a cockpit, a dashboard template, or a SaaS marketing page.

- **Editorial serif as the reading anchor.** Long-form content is set in a serif (Lora). The serif carries body copy and editorial display headings. It signals that the studio's work is read and considered, not skimmed.
- **Mono for meta.** Anything that is *about* the content rather than the content itself — status labels, captions, micro-labels, code, route markers — is set in monospace (JetBrains Mono). Mono is the studio's "machine voice": precise, secondary, never the headline.
- **Sans for UI.** Interface chrome — UI headings, inputs, dense workspace tables — uses a neutral sans (Inter).
- **Tactical / blueprint visual language.** Structure is expressed through corner brackets, blueprint rules (2px accent lines), technical dividers with ticks, and sharp corners. Elevation is contrast and brackets, not shadow. This is the "tactical frame" grammar — it makes a surface read as engineered.
- **No cockpit clichés.** The studio does not use the visual shorthand of telemetry dashboards: no gauge dials, no neon-on-black "command center" styling, no decorative data-viz, no glow. Tactical grammar is structural, not theatrical.

The implementation layer of this philosophy — the package that turns it into React + Tailwind — is documented in [`ui.md § Architecture`](ui.md).

## 2. Voice & casing

Casing is a typographic contract, applied consistently across every surface. The token-level *definitions* of each ramp step live in [`design-tokens.md § Typography`](design-tokens.md); this section owns the *application* rules.

- **Micro labels** (`STATUS`, `STACK`, `LANGUAGES`, `STAGE`, `ROUTE`): `UPPERCASE`, `letter-spacing: 0.2em`, monospace, 10–12px, terracotta accent. The studio's signature eyebrow.
- **Caption labels** (category tags like `/build`, `/signal`): lowercase, with a leading `/`, monospace, muted. The slash marks them as routes/categories.
- **Headings**: sentence case. Inter 600 for UI headings; Lora 500 for editorial display headings. Never title-case running headings.
- **Body**: sentence case, serif (Lora).
- **Code / meta**: lowercase, monospace.

### Tone

Copy is plain, direct, and unhedged. The studio states what a thing is and what it does. It does not use exclamation, marketing superlatives, or emoji.

- **Error copy** names what went wrong and what the reader can do next — never a bare code or a cheerful euphemism.
- **Empty states** describe what would be here and how to create the first one — they are an instruction, not an apology.
- **Loading states** are quiet: a skeleton or a low-key indicator, never a spinner-with-personality.

## 3. Surface mapping

The studio runs **two themes** (per R13: a *theme* is a complete token set scoped to one surface; a *mode* is a light/dark variant of a single token's value — the two terms are used strictly).

| Surface | Theme | Used for |
|---|---|---|
| Public surfaces | **Light** | Marketing site (`rapoport.studio`), Muse, public snapshots — warm-ivory canvas, the reading-first editorial presentation. |
| Internal workspace | **Dark** | The studio workspace (`app.rapoport.studio`) — near-black canvas, the dense operating surface. |
| Future client surface | (new theme) | Any future engagement skin is a new `[data-theme]` token set, declared per R13; themes never overlap, each owns its tokens. |

The variant a primitive renders in is chosen by *surface intent*, applied via `.dark` / `[data-theme="dark"]` on the root element — never branched per-component. Token values for both modes are registered in [`design-tokens.md`](design-tokens.md); the path to add a new theme is in [`ui.md § Adding a new theme`](ui.md).

## 4. Hard constraints

Brand-level constraints. These hold on every surface; a primitive that violates one is a regression.

1. **Radius `0` everywhere.** Sharp corners are the brand. Sole exception: a `3px` radius on inline code pills and small tags.
2. **No shadows.** No `box-shadow` except `none`. Elevation is expressed through surface contrast (canvas vs. subtle) and corner brackets.
3. **No gradients.** Decorative colour washes and soft-elevation gradients are forbidden. The single exception (`D-DS-8`): structural, single-tone, geometric pattern utilities (drafting grids, hatching) built on `linear`/`radial-gradient` are permitted **only as decorative fill on text-free zones**. No gradient or pattern ever sits behind text. The full pattern system — catalog, API, host requirements, density budget, do/don't, anti-patterns — lives at [`design-components.md § Background patterns`](design-components.md).
4. **Flat background behind content.** The canvas is flat warm ivory (light) or flat near-black (dark) behind all content. Always. Only decorative text-free zones may carry a `D-DS-8` pattern fill.
5. **No emoji.** Emoji are not part of the studio's typographic system. Glyphs and bracketed-letter identifiers carry the same role.
6. **Favicon = RS glyph + tactical corner-bracket frame** (D-FAV-2, D-FAV-10; applied 2026-05-25 from change `add-studio-favicon`). The default Next.js `favicon.ico` is never re-introduced; the file-based icon convention (`apps/web/src/app/icon.tsx`, `apple-icon.tsx`, `icon.svg`) ships a two-layer mark — JetBrains Mono SemiBold "RS" letterforms (53 % cap-height, `0em` tracking) inside four corner L-brackets (18 % length, 4.5 % stroke, 7 % inset of viewBox). See `web.md § Icon contract`.

The token-level statement of these rules lives in [`design-tokens.md § Hard rules at the colour level`](design-tokens.md) and [`design-tokens.md § Borders & radius`](design-tokens.md); this section is the brand-level summary.

## 5. Accessibility contract

This section names the corpus-wide accessibility contract. The per-component a11y baseline lives in [`design-components.md`](design-components.md); the token-level baseline (contrast, focus ring) lives in [`design-tokens.md § A11y baseline`](design-tokens.md). This section names the *contract* both of them conform to.

### 5.1 Conformance target (`D-DS-10`)

Every studio surface — marketing site, studio workspace, and any future client surface — conforms to **WCAG 2.2 Level AA**. AA is the floor, not a goal; AAA criteria are elective and named explicitly where a surface adopts one.

**Why AA and not AAA.** AA is the recognised legal and industry conformance bar (EN 301 549, ADA, the studio's EU exposure). AAA is not achievable corpus-wide — e.g. SC 1.4.6 (contrast 7:1) conflicts with the brand's warm-ivory palette. Naming AA as the floor, and AAA as elective where a surface chooses to meet it, is the honest contract. This is `D-DS-10`.

### 5.2 Touch-target floor (`D-DS-9`)

The corpus carried two conflicting touch-target figures — `home/spec.md` mandates `44×44` CSS px, `_methodology/research/chat-redesign-a11y.md` cites `24×24`. `D-DS-9` reconciles them:

- **Canonical floor:** every interactive target is at least **24×24 CSS px**, per WCAG 2.2 SC 2.5.8 Target Size (Minimum, **AA**). This is the corpus-wide requirement and follows directly from the AA contract in `§ 5.1`.
- **Elective goal:** **44×44 CSS px**, per WCAG 2.2 SC 2.5.5 Target Size (Enhanced, **AAA**). Surface specs MAY raise their own targets to `44×44` — the marketing home does, for its primary and secondary CTAs (`home/spec.md`) — but the corpus never *requires* it.

This makes both pre-existing specs correct: `home/spec.md`'s `44×44` reads as a surface electively meeting the SC 2.5.5 AAA goal; `chat-redesign-a11y.md`'s `24×24` reads as the SC 2.5.8 AA corpus floor. Neither is contradicted.

**Why `24×24` as the floor.** SC 2.5.8 is the AA-level criterion; `D-DS-10` makes AA the corpus contract, so the floor that follows from the contract is `24×24`. Mandating `44×44` corpus-wide would claim an AAA conformance the studio has not committed to — and dense workspace surfaces (`DataTable` rows, inline chips) cannot meet it without breaking density.

The token-level statement of the floor lives in [`design-tokens.md § A11y baseline`](design-tokens.md), which cites this section so the registry and the umbrella agree.

## 6. Anti-patterns

Brand-level anti-patterns. Token-, motion-, and component-specific anti-patterns live in the respective sister files.

- **No gradients** as decorative colour washes or soft elevation (the `D-DS-8` text-free-zone pattern exception aside).
- **No emoji** anywhere in the typographic system.
- **No cockpit clichés** — gauge dials, neon-on-black command-center styling, decorative telemetry, glow.
- **No decorative imagery behind text.** No images and no patterns under text content; the canvas behind content is always flat.
- **No shadows** for elevation. Use contrast and brackets.

## Cross-references

- [`design-tokens.md`](design-tokens.md) — token registry; W3C DTCG `$type`; mode parity; the type ramp.
- [`design-motion.md`](design-motion.md) — duration scale, easing curves, motion modes, reduced motion.
- [`design-components.md`](design-components.md) — component anatomy, variants, per-component a11y baseline.
- [`ui.md`](ui.md) — implementation references; `path:line` anchors into `packages/ui`.
- [`_methodology/design-system-convention.md`](../_methodology/design-system-convention.md) — the five-file structure and rules R1–R13 that govern this file.
- [`platform.md`](platform.md) — overall platform context; the capability map.
