Tokens

Named design decisions that travel from a designer's file to a compiled binary without anyone retyping a hex code — and, in a regulated product, without anyone being able to change a safety-critical value by accident.

Overview

A token is a name bound to a value. The name expresses intent — --muted-foreground, --alarm-critical — and the value can change per theme without any component knowing. That indirection is what makes a dark theme a configuration change rather than a redesign.

In a SaMD the indirection buys something else as well: a single auditable place where safety-relevant visual decisions live. When a notified body asks how you guarantee that a high-priority alarm is red in every screen of every product, the answer is one token definition and the lint rule that protects it — not a review of four hundred components.

The three layers

A value travels through exactly three stops. Skipping one is what makes design systems drift.

The shadcn contract

The semantic layer uses shadcn/ui's variable names verbatim. This is deliberate and it is the main reason to build on shadcn at all: any block, example or third-party component from the wider ecosystem drops into this system and is instantly on-brand, because it is already reaching for --primary and --muted.

/* app/globals.css */
:root {
  --background: #FDFCF8;   --foreground: #16231F;
  --card: #FFFFFF;         --card-foreground: #16231F;
  --popover: #FFFFFF;      --popover-foreground: #16231F;
  --primary: #0F3B35;      --primary-foreground: #F6F1E7;
  --secondary: #EFEDE4;    --secondary-foreground: #16504A;
  --muted: #EFEDE4;        --muted-foreground: #54635E;
  --accent: #E4EEE9;       --accent-foreground: #0F3B35;
  --destructive: #CE0E2D;  --destructive-foreground: #FFFFFF;
  --border: #DEE4DF;       --input: #DEE4DF;
  --ring: #2A8B7C;         --radius: 0.625rem;
}

.dark {
  --background: #0B2A26;   --foreground: #F6F1E7;
  --card: #0F3B35;         --primary: #3BC4AF;
  --muted: #16504A;        --muted-foreground: #A8BDB6;
  --border: #1E4A43;       --ring: #3BC4AF;
  --destructive: #D93650;
}

The alarm extension

Stock shadcn has no concept of alarm priority. It has --destructive, which means "this control destroys data" — a completely different job from "this patient may be having a STEMI." Conflating them is the single most likely way for a team new to medical software to build something unsafe.

/* Medical extension — IEC 60601-1-8 alarm priorities.
   GOVERNED: not re-themable by product, customer skin, or user preference.
   Identical in light and dark. Changing a value here requires re-validation. */
:root, .dark {
  --alarm-critical: #CE0E2D; --alarm-critical-foreground: #FFFFFF;
  --alarm-urgent:   #F2C200; --alarm-urgent-foreground:   #000000;
  --alarm-advisory: #4FB3D9; --alarm-advisory-foreground: #000000;
  --alarm-info:     #B3BEB9; --alarm-info-foreground:     #000000;
  --alarm-ok:       #1D6E62; --alarm-ok-foreground:       #FFFFFF;
}

Wiring into Tailwind

// tailwind.config.ts
theme: {
  extend: {
    colors: {
      // …stock shadcn keys…
      alarm: {
        critical: "var(--alarm-critical)",
        "critical-foreground": "var(--alarm-critical-foreground)",
        urgent:   "var(--alarm-urgent)",
        "urgent-foreground":   "var(--alarm-urgent-foreground)",
        advisory: "var(--alarm-advisory)",
        "advisory-foreground": "var(--alarm-advisory-foreground)",
        info:     "var(--alarm-info)",
        "info-foreground":     "var(--alarm-info-foreground)",
        ok:       "var(--alarm-ok)",
        "ok-foreground":       "var(--alarm-ok-foreground)",
      },
    },
  },
}

Governance

Tokens split into two governance classes. The distinction is the whole point of this page.

Enforcement

A rule that lives only in documentation is not a control. The governed set is enforced by a dependency-free gate that runs on every pull request and fails the build on violation.

Running it

$ npm run check:tokens

  Token governance gate — NotJustAnyMed.Tech Design System
  ──────────────────────────────────────────────────────────────
  PASS  parity        10 governed alarm tokens identical across both themes
  PASS  contrast      34 colour pairs meet their documented minimum
  PASS  sync          assets/njt-ds.css matches tokens.json
  PASS  redefinition  8 files scanned, no governed token redefined or hard-coded
  ──────────────────────────────────────────────────────────────
  note  ΔE(alarm-critical #CE0E2D, #D8593A) = 22.6
  note    ↳ below the 25 separation threshold — this is why coral is
          banned from product UI.
  ──────────────────────────────────────────────────────────────
  All governance contracts hold.

What a violation looks like

  FAIL  parity        --alarm-critical differs between themes
                      light #CE0E2D vs dark #E24359. IEC 60601-1-8 hues are
                      absolute; a theme may not change what a signal means.

  FAIL  redefinition  --alarm-urgent is declared outside the blessed blocks
                      assets/njt-ds.css:405 → #FF9900. Governed tokens have
                      exactly one definition point; a skin may not override them.

  FAIL  redefinition  Literal #CE0E2D appears in src/Widget.tsx
                      That is the value of --alarm-critical. Use the token:
                      a literal is invisible to this gate.

$ echo $?
1

Files

Non-colour scales

Spacing — 4 px base

Every gap is a multiple of four. Tailwind's default scale already is, so no override is needed; the constraint is on usage, not configuration.

Radius

One base token, two derived. Matches the brand's 6 / 10 / 16 geometry.

Motion

Do's and don'ts

<div className="bg-alarm-critical
     text-alarm-critical-foreground">

<div className="bg-[#CE0E2D]
     text-white">

--primary: #0F3B35;   /* open  */
--alarm-urgent: #F2C200;  /* governed */

.customer-acme {
  --alarm-urgent: #FF9900; /* on-brand! */
}

More do's and don'ts

"alarm-urgent": {
  "class": "governed",
  "light": "#F2C200",
  "dark":  "#F2C200",
  "rationale": "IEC 60601-1-8 medium priority."
}

/* hotfix: customer said the
   yellow looked harsh */
--alarm-urgent: #FFE066;

.alert { background: var(--alarm-urgent); }

.alert { background: var(--njt-warm-400); }

Clinical safety notes

• Single definition point for alarm appearance. Mitigates: divergent alarm presentation across products, and the audit burden of proving consistency component by component.
• Governed set is machine-enforced. A lint rule and a CI contrast test, not a paragraph of guidance. Mitigates: well-intentioned local overrides.
• Themes cannot alter meaning. Dark mode changes surfaces, never signals. Mitigates: a clinician misreading priority after a theme switch.
• No hard-coded values in components. Mitigates: silent drift that survives a validated palette change.

Related

• Colour — the ramps and the alarm hues in full.
• Typography — the type tokens and the scale they build.
• Alert Banner — the alarm tokens applied.