Proposal — the design language

State: open/active · Genre: proposal

1. Verdict first

Do not start a new design system. Promote the one that exists. @determined/ui already encodes the target aesthetic — a native-feeling, technical, quiet, compact pro tool — and already has the theming machinery a suite needs. The revamp is: make it true, make it law, and extend it outward through descent.

2. Stance

The OmniGraffle reference decomposed into commitments the system can enforce:

Quality	Commitment (mostly already in the spec)
Technical, dense, legible	Compact density: 28px controls, 13px base text, 28px status bar. Whitespace spent on grouping, not padding
Quiet, native	Hairline borders and background steps, not shadows. Restrained single accent. System font stacks. OS-decorated windows
Inspector-grade UX	Panes with disciplined collapse states; one headline surface per screen; settings and palette as system surfaces
Keyboard-first	mod+k palette, chord registry, visible DKbd hints
Modern update	color-mix()/OKLCH-tuned tokens, honest AA contrast axis, density/radius/shadow as user choices, per-vault hue tinting

These live in packages/ts/ui/docs/design-system.md §1. The proposal keeps them and makes them binding beyond the package.

3. Identity and descent

The language is Determined. It originates in the determined suite; every other surface inherits by descent, the way solutions/ontological/desktop already does. Concretely:

• The --d-* prefix, the @determined/ui package name, and the D* component prefix stay. Renames buy nothing (D-0001: names never change).
• “Hierarchy of descent and commonality” is the four-plane model below plus the theme tree. Commonality = the grammar; descent = who supplies which values.

The four planes

1 GRAMMAR      the 25-token contract + appearance vocabulary,
               dSemantics intents, D* component kit
2 THEMES       base themes (platinum, graphite, contrast, flat, mono)
               → solution themes (sdf; future: per-solution presets)
               → product tint (generalize vault-hue → product-hue)
               × orthogonal axes: mode, density, radius, shadow, contrast, os
3 CHROME       app-frame consumes only the grammar; any host that supplies
               the contract gets the whole workbench
4 PROJECTIONS  derived skins for non-Nuxt surfaces: Starlight docs CSS,
               data-viz palette, report templates, terminal/static pages

Plane 2 is the theming answer: a theme is data (a seed-token block registered via registerTheme()), never a component fork. A solution descends by registering a preset; a product descends by setting a hue; a user composes axes. This already works — SDF proves it — so the work is codifying and generalizing, not building.

Plane 4 is what makes the language suite-wide rather than Nuxt-wide. Every non-Vue surface gets a generated or hand-derived projection of the same seed tokens, so a docs site, an HTML report, and a desktop app read as one family.

4. Decisions to make law

Mint one repo-level decision (D-xxxx, “the Determined design language”) and one standard (S-xxxx, “UI surfaces consume the design language”). Contents:

1. Spec-first, spec-true. design-system.md is rewritten in place to match shipped tokens.css (all 94 tokens, both tiers, five themes, axes, the bridge direction --ui-* ← --d-*). After that, token changes edit the spec in the same PR. The spec’s own rule, now honored.
2. One dark-mode mechanism. .dark on <html> (via color-mode) is the single source of truth. Primitives that take a theme prop are fed from useDTheme, never from matchMedia. prefers-color-scheme allowed only in standalone/static surfaces with no shell.
3. One icon language. Lucide, via Iconify. @determined/ui declares the collection it uses. Heroicons retired from shipped code.
4. Semantic-first, everywhere. No raw palette classes or color/variant literals in experiences and products; intents and tokens only. The narrow UButton soft/ghost allowance gets an explicit written boundary (or a DButton intent that covers it).
5. Fonts are tokens. --d-font-sans/--d-font-mono actually style the app (fix the shell.css hard-coding). Default stays system stacks — correct for a native pro tool and for offline Tauri builds. Optional identity fonts (e.g. a bundled mono for terminals/editors, a display face for marketing/docs) enter only as token overrides in themes or projections, never as component styling.
6. Themes are data; the registry is the door. Third-party and solution themes use the same registerTheme() + CSS block seam as sdf. A theme that cannot be expressed in tokens is proof the vocabulary is incomplete — extend the vocabulary, don’t fork a component.

5. What deliberately does not change

• No package renames, no new prefix, no component-framework change.
• Frozen/legacy apps stay untouched: apps/legacy-polish (D-0011 §6), apps/ontological-legacy (parts donor), archived precursors.
• The Obsidian plugin keeps inheriting the host vault theme — that is the correct design for that surface. The mockups’ Obsidian-variable mapping can later become a documented projection.
• No webfont dependency in the desktop default path.

6. Owner calls (answered 2026-08-26)

• The language is named Determined.
• Ring 3 adoption: yes — zoo, agentpants, pumice, in that order.
• solutions/augmented/apps/augmented_web: adopts in Phase 3, after the three apps (owner overrode the leave-bespoke default).
• Fonts: pure system stacks for now. Type identity is revisited during the redesign theme and enters only as token overrides (law 5).

These are recorded in D-DLNG-design-language; the consumption rule is S-0010-design-language-consumption.

---

← Back to Notes