Skip to content
sdlc

The Determined design language

Status: open/accepted

Summary

Section titled “Summary”
  • The suite-wide design language is the one packages/ts/ui (@determined/ui) already implements — the --d-* token system, the dSemantics intent contract, and the D* component kit. It is named Determined. No new system is built; this one is promoted, governed, and extended outward by descent.
  • Six laws (below) bind every consumer; S-0010-design-language-consumption is their enforcement standard.
  • The survey that grounds this, the full proposal, and the phased execution plan live in docs/planning/design-language/.

Context

Section titled “Context”

Every live desktop app shares one stack (Tauri 2 + Nuxt 4 + Vue 3 + Tailwind 4 + Nuxt UI) but diverged below it: four palettes, three icon sets, three incompatible dark-mode stances, fonts undecided everywhere. Meanwhile a real design system exists — 94 --d-* tokens in a seed/derived two-tier layer, five themes × light/dark, orthogonal appearance axes, 35 intent-driven components, a written spec — with deep adoption inside determined’s experiences and the SDF desktop, and none outside. Nothing at repo level governed tokens, theming, typography, or components. The full inventory: docs/planning/design-language/SURVEY.md.

Decision

Section titled “Decision”

Identity. The language is Determined. The --d-* prefix, @determined/ui package name, and D* component prefix stay (D-0001-project-structure: names never change). It originates in the determined suite; every other surface inherits by descent — the way solutions/ontological/desktop already registers its sdf theme.

Architecture — four planes.

  1. Grammar: the 25-token app-frame contract + the appearance vocabulary, dSemantics intents, the D* kit.
  2. Themes: base themes (platinum, graphite, contrast, flat, mono) → solution themes (registered presets) → product tint (vault-hue generalized to product-hue), × orthogonal user axes (mode, density, radius, shadow, contrast, os). A theme is data, never a component fork.
  3. Chrome: @sksizer/app-frame consumes only the grammar; any host supplying the contract gets the whole workbench.
  4. Projections: derived skins of the same seed tokens for non-Nuxt surfaces — docs sites, report templates, data-viz palettes, static pages.

Six laws.

  1. Spec-first, spec-true. packages/ts/ui/docs/design-system.md is the vocabulary’s canonical spec and is edited in the same change as any token addition or change.
  2. One dark-mode mechanism. .dark on the root, owned by color-mode, read through useDTheme; primitives taking a theme prop are fed from it, never from matchMedia. prefers-color-scheme only in standalone static surfaces with no shell.
  3. One icon language. Lucide via Iconify.
  4. Semantic-first, everywhere. Intents and tokens, not palette classes or color/variant literals, in experiences and products.
  5. Fonts are tokens. System stacks are the default (right for a native pro tool and offline Tauri builds); identity faces enter only as token overrides in themes or projections.
  6. Themes are data; the registry is the door. Presets registered through registerTheme() + a data-theme CSS block. A theme the vocabulary cannot express means the vocabulary is extended (law 1), never a component forked.

Owner calls (2026-08-26).

  • Ring 3 adoption: the live apps adopt — zoo, then agentpants, then pumice; solutions/augmented/apps/augmented_web adopts after them. Frozen/legacy apps stay untouched.
  • Fonts stay pure-system for now; type identity is revisited during the redesign theme.
  • Every PR that changes pixels carries before/after screenshot pairs (light + dark) in its description.

Consequences

Section titled “Consequences”
  • S-0010-design-language-consumption governs all UI surfaces, with named escape hatches (frozen apps, the Obsidian plugin, shell-less static surfaces).
  • The execution order is fixed by the plan (docs/planning/design-language/PLAN.md): wiring gaps close before the redesign; the redesign lands as a candidate theme preset and flips the default only when it wins; adoption follows the redesign so surfaces migrate once.
  • The design-system spec was rewritten in place to match the shipped tokens as part of this decision’s Phase 0.
  • dataVizPalette and the per-theme data-viz projection, the Starlight docs skin, and the report-template palette become derivations of the seed tokens (plane 4) as the plan reaches them.

← Back to Decisions