Principles / 03

Reading surface vs cockpit

Two visual modes, one design system. Why forcing dashboards and long-form prose to share a layout fails both.

Section: Foundations

Two contexts, two jobs

When a reader lands on a 4,000-word article about EU AI Act risk classification, they need exactly one thing: to be able to read it. The visual job is to disappear — to put the words on the page in a way that sustains attention for fifteen minutes without taxing the eyes.

When the same reader lands on the LLMOps dashboard, they need the opposite: everything at once. Six panels of evals, a latency chart, an error log, the cost ticker, and the deploy button — all visible, all glanceable, all capable of getting attention when their state changes.

These are not two flavors of the same problem. They are two different problems, and the design moves that solve one actively sabotage the other. A reading surface that uses cockpit-style multi-column layouts is unreadable; a cockpit that uses reading-style generous whitespace shows three panels where it should show twelve.

What a reading surface looks like

The reading surface in this system has six rules:

  1. Single column, capped at ~70ch. Anything wider breaks the eye's return-sweep across lines.
  2. Dark background, soft-white text. --ds-color-bg-base (#0a0a0e) under --ds-color-text-primary (rgba 0.95). Pure white on pure black is too harsh; we sit one notch off each.
  3. Generous vertical rhythm. Paragraph spacing is --ds-space-4; H2 spacing is --ds-space-10. The page wants to breathe.
  4. Reading-optimized type. Body copy at 17–18px (clamped), line-height 1.6–1.7. No condensed faces.
  5. Inline elements pull weight. Footnotes pop up in hover-tooltips; internal links surface their preview via Pagefind. The reader rarely has to leave the paragraph.
  6. Motion is muted. Reveal animations only on first scroll into view. No constant attention pulls.

Every one of those rules is wrong for a cockpit.

What a cockpit looks like

A cockpit operates on different principles:

  1. Multi-region layout. Three to twelve panels visible simultaneously. Information density per square inch is the metric.
  2. Density-aware components. Every primitive obeys data-density="compact" by multiplying padding tokens. The compact mode is 75% of comfortable, applied uniformly.
  3. Status earns color. Status-success, status-warn, status-danger are loud on purpose. A reading surface has no status states; a cockpit lives by them.
  4. Hub-tinted accents. The cockpit knows which workspace it serves and tints accordingly. The reader uses color to find their way.
  5. Motion conveys state change. A row pulses when its data refreshes. A toast slides in when an action completes. Motion is the feedback channel.
  6. Keyboard density. Roving tabindex, ↑↓ for lists, ⌘K for the command palette. The cockpit assumes a power user.

A reader who is in cockpit mode trying to read a 4,000-word article will bail after a minute. A power user trying to operate a dashboard styled as a reading surface will rage at every click.

The system supports both at no cost

The temptation, when faced with two modes, is to fork the design system: one "marketing" theme and one "product" theme, each with its own tokens. This always becomes unmaintainable within six months: every new component has to be re-implemented twice, and the two themes drift.

Our move is different. We have one token system. The modes live in how components compose tokens — not in which tokens exist. The same --ds-space-4 means 16px everywhere; what changes is how often the layout reaches for --ds-space-4 versus --ds-space-2. The reading surface uses the big steps; the cockpit uses the small ones.

Density is the formalisation. When the cockpit declares data-density="compact" on its root, every density-aware component multiplies its padding tokens by 0.75. Control heights drop from 40px to 34px. Gaps tighten. The same components, the same tokens, render densely. Switch back to comfortable on a marketing page and the same components breathe.

Color works the same way. --ds-color-accent resolves through --hub-accent when a hub is set, and through brand violet otherwise. A cockpit dashboard tinted by LLMOps amber and an article page in the same hub share the same tint — the tokens did the work.

What this commits us to

Every page declares its mode at the top. Reading surfaces wrap in <article class="reading-surface">; cockpits wrap in a container with data-density="compact". We do not invent a third mode without a written argument.

More importantly, we resist the urge to make reading surfaces fancier. Designers reflexively want to add multi-column layouts, sidebar widgets, floating CTAs, and parallax heroes to article pages because article pages feel empty. They are supposed to feel empty. The empty space is the product.

And we resist the urge to make cockpits prettier. Dashboards do not need rounded-corner gradients and motion-rich page transitions. They need information per pixel and visible state changes. The pretty version costs the user a click. We do not pay that cost.

The system supports both modes because both modes are real, both modes are earned, and a design system that pretends one of them does not exist is only solving half the problem.