Skip to content

cotel Design Tokens ​

Source of truth for all visual values. Implementors use these names verbatim in CSS Modules. Every token is a CSS custom property set on :root.

Status: v1 — sufficient for FLO-34 dashboard implementation. Related: components.md, pages.md


Color — Light mode ​

TokenValueUsage
--color-bg#f8fafcPage background
--color-surface#ffffffCard, panel, popover background
--color-surface-2#f1f5f9Table header, hover state, nested surface
--color-border#e2e8f0Dividers, card outlines, input borders
--color-border-2#cbd5e1Stronger dividers, focused/active borders
--color-text-1#0f172aPrimary text, headings, values
--color-text-2#475569Secondary text, labels, sub-labels
--color-text-3#94a3b8Placeholder, disabled, empty-state text
--color-accent#2563ebActive nav, links, primary button, chart bars
--color-accent-bg#eff6ffActive nav background, selected row highlight
--color-success#15803dPositive delta, success badge text
--color-success-bg#dcfce7Success badge background
--color-warning#d97706Warning badge text, caution indicators
--color-warning-bg#fef9c3Warning badge background
--color-danger#dc2626Error text, error badge, error row indicator
--color-danger-bg#fef2f2Error row background, error badge background
--color-neutral-bg#f1f5f9Neutral badge background
--color-neutral#475569Neutral badge text

Color — Dark mode ​

Applied via @media (prefers-color-scheme: dark) override on :root. All token names are identical; only values change.

TokenDark valueUsage
--color-bg#020617Page background
--color-surface#0f172aCard, panel background
--color-surface-2#1e293bTable header, hover
--color-border#334155Dividers
--color-border-2#475569Stronger dividers
--color-text-1#f8fafcPrimary text
--color-text-2#94a3b8Secondary text
--color-text-3#475569Muted / placeholder
--color-accent#60a5faLinks, active state, chart bars
--color-accent-bg#172554Active nav background
--color-success#4ade80Success text
--color-success-bg#14532dSuccess badge background
--color-warning#fbbf24Warning text
--color-warning-bg#422006Warning badge background
--color-danger#f87171Error text
--color-danger-bg#450a0aError row background
--color-neutral-bg#1e293bNeutral badge background
--color-neutral#94a3b8Neutral badge text

Contrast compliance (WCAG AA / 4.5:1 for normal text) ​

PairLight ratioDark ratioPass
--color-text-1 on --color-bg19.4:119.4:1✓ AAA
--color-text-2 on --color-surface7.1:14.6:1✓ AA
--color-accent on --color-bg5.9:15.7:1✓ AA
--color-danger on --color-danger-bg5.1:14.8:1✓ AA
--color-text-3 on --color-surface3.5:1—✗ Use only for non-essential UI (placeholders, timestamps)

--color-text-3 intentionally falls below AA — it marks genuinely secondary, non-interactive content. Never use it for actionable labels or data values.


Chart palette ​

Ordered list used for multi-series charts (tool breakdowns, model comparisons). Every pair separates under colour-vision deficiency, and the series keep the same loudness order in both schemes. The two rules below say what that means, on what ruler, and what the palette measures today.

TokenLight valueDark valueUsage
--color-chart-1#2563eb#60a5faPrimary series (matches accent)
--color-chart-2#8373bc#8b6edaSecond series
--color-chart-3#046642#01d699Third series
--color-chart-4#b36519#c89716Fourth series
--color-chart-5#e4307e#e965abFifth series

Use --color-chart-1 → --color-chart-5 in order; do not skip. When more than 5 series exist, group the tail as "Other" (use --color-text-3).

The dark values are not the light values lightened. Rule 1 makes the dark scheme's lightness order the reverse of the light scheme's, because the surface flips underneath: against white a token is loud by being dark, against #0f172a it is loud by being light. A token that reads quiet in one scheme is therefore a lighter colour in light mode and a darker one in dark mode.

The ruler ​

Both rules below are measured, not argued, so a proposed value can be checked before it ships. Simulate colour-vision deficiency with Machado 2009 at severity 1.0 applied to linearised sRGB, then take Euclidean distance in OKLab × 100 — that is what "ΔE" means on this page. The simulated colour is not clamped back into the sRGB gamut on the way: clamping is a display concession, and it understates separation the reader still perceives. A tool that clamped measured 1–2 light at 8.8 where this ruler reads 11.4. Lightness is OKLab L. Salience is WCAG contrast against --color-surface (#ffffff light, #0f172a dark).

The ruler is a pinned contract, not a recipe to reimplement: ADR-0017 makes its matrices and constants normative in internal/design/palette.go, and the Go test beside them fails CI when either rule breaks. Both tables below are generated output — regenerate them with go test ./internal/design/... -update instead of editing rows by hand.

There is no lightness ceiling. A bare L cap was proposed and rejected: it reads a symptom of rule 1 off a single token while leaving the same fault in the neighbouring ones.

Rule 1 — salience order is the same in both schemes ​

A token's rank by contrast against the surface is a promise about how loud that series is. The ranks must agree across schemes, or the same chart puts a different series on top depending on the reader's theme.

TokenLight contrastRankDark contrastRank
--color-chart-15.17:127.02:12
--color-chart-24.08:154.54:15
--color-chart-37.04:119.42:11
--color-chart-44.38:136.71:13
--color-chart-54.18:145.88:14

The ranks agree. Where two of these share one plot — spans in chart-1 against cost in chart-4 on the Overview — the primary series is the louder one in both schemes; before this palette the dark scheme promoted cost over spans and the light scheme did not.

The floor is 4:1, a third above the 3:1 WCAG 1.4.11 asks of a 2 px stroke. chart-1 cannot be the loudest token: it is pinned to --color-accent, and rule 2 needs the other four spread far enough in lightness that two of them must land outside it on either side. Rank 2 of 5 is the loudest position available to it.

Rule 2 — any two tokens that can share a plot stay ΔE ≥ 8 apart ​

Because the palette is used in order, "can share a plot" means every pair. The bar of 8 is this project's own, set in ADR-0015. Worst case over protanopia, deuteranopia and tritanopia, with the simulation that produced it:

PairLightDark
1–211.4 (protan)9.7 (deutan)
1–312.9 (tritan)8.4 (tritan)
1–431.6 (protan)24.2 (tritan)
1–518.3 (protan)13.0 (deutan)
2–317.4 (tritan)23.2 (tritan)
2–416.0 (tritan)16.0 (tritan)
2–510.7 (protan)9.2 (protan)
3–48.6 (protan)12.2 (deutan)
3–59.4 (protan)9.5 (deutan)
4–510.0 (deutan)9.3 (tritan)

The worst pair in the product is 8.4 — 1–3 under tritanopia in dark, with 3–4 under protanopia in light next at 8.6. Treat both as "passing, with no room". The previous palette put chart-1 and chart-2 at 0.4 and 0.3 — the same colour to a deuteranope — and since the palette is handed out in order, that was the pair every two-series chart drew.

ΔE 8 is "tellable apart", not "comfortable". It does not license colour as the only channel: a chart whose series must be identified at a glance still earns a direct label or a different mark per series. It licenses the legend swatch to work for a reader who has one.

How the values were derived ​

Re-deriving the palette means solving both rules at once; nudging one token cannot do it. The constraints a replacement value must satisfy:

  • chart-1 is pinned — it is --color-accent, and it is the one chart token with product meaning.
  • Hue family per index is kept: blue, violet, green, amber, pink. Every value here is within 3° of the hue it replaces; only lightness and chroma moved.
  • ≥ 4:1 against the surface, and chroma ≥ 0.10 in OKLab. The chroma floor is what keeps a quiet token a colour rather than a tint — a pale near-neutral reads as "no series assigned", which is how an earlier candidate palette failed by eye while passing both rules on paper.
  • chart-4 must no longer be byte-identical to --color-warning, which it was in both schemes.

The Tailwind ramps the rest of this file is built from cannot satisfy this: at a 4:1 floor no assignment of their shades meets both rules, because a ramp steps lightness for one surface and rule 1 needs the two schemes ordered oppositely. These ten values are therefore off-ramp, and are the only colour tokens in the file that are.


Typography ​

Font stack: system-ui, -apple-system, 'Segoe UI', sans-serif
Monospace stack: ui-monospace, 'JetBrains Mono', 'Fira Code', monospace

TokenSizeWeightLine-heightUsage
--text-xs11px5001.4Table headers, card labels, badges (ALL CAPS + letter-spacing)
--text-sm13px4001.5Table cells, body copy, nav items, filter labels
--text-base14px4001.5Default body, form inputs
--text-lg16px6001.4Section headings, modal titles
--text-xl20px7001.3Page titles
--text-2xl24px7001.2KPI Card values
--text-mono-sm12px4001.5Session IDs, span names, JSON viewer
--text-mono-base13px4001.5Code blocks, inline monospace

Letter-spacing for uppercase labels: 0.06em (applies to .card-label, th, .section-title, .badge).


Spacing ​

Base unit = 4px. Tokens are multiples.

TokenValueCommon use
--space-14pxTight inline gap, badge padding vertical
--space-28pxRow padding vertical, icon-to-text gap
--space-312pxCard gap in row, section-title margin-bottom
--space-416pxCard padding, nav item padding horizontal, chart padding
--space-520px— (available; use sparingly)
--space-624pxSection margin-bottom, card row margin-bottom
--space-832pxPage content padding, large section gap
--space-1040px—
--space-1248pxNav height, top-bar height

Do not use raw pixel values in CSS Modules. Reference var(--space-*).


Border radius ​

TokenValueUsage
--radius-sm4pxButtons, pagination buttons, badges
--radius-base6pxCards, table wrappers, chart wrappers, inputs
--radius-lg8pxModals, date pickers, tooltips
--radius-full9999pxPill badges, pulse dot

Shadows ​

TokenValueUsage
--shadow-10 1px 2px rgba(0,0,0,.06)Cards, table wrappers, chart wrappers
--shadow-20 2px 8px rgba(0,0,0,.10)Popovers, tooltips, date picker dropdown
--shadow-30 4px 16px rgba(0,0,0,.14)Modals

In dark mode, shadows are less visible due to dark surface; keep the same values but the UI relies more on border contrast. Do not disable shadows in dark mode.


Z-index ladder ​

TokenValueLayer
--z-base0Normal stacking
--z-sticky100Sticky top nav bar
--z-dropdown200Date range picker, filter dropdowns
--z-tooltip300Tooltips
--z-modal-backdrop400Modal scrim
--z-modal500Modal content
--z-toast600Toast notifications

Motion ​

TokenValueUsage
--duration-fast100msHover state, opacity
--duration-base200msExpand/collapse, dropdown open
--duration-slow300msSkeleton shimmer
--easing-defaulteaseStandard transitions
--easing-in-outcubic-bezier(0.4,0,0.2,1)Panel open/close

Respect prefers-reduced-motion: when set, all durations collapse to 0ms. Implement via:

css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after { transition-duration: 0ms !important; animation-duration: 0ms !important; }
}

Full token CSS block ​

Copy into src/styles/tokens.css as the canonical token file. All CSS Modules import this.

css
:root {
  /* Color */
  --color-bg:          #f8fafc;
  --color-surface:     #ffffff;
  --color-surface-2:   #f1f5f9;
  --color-border:      #e2e8f0;
  --color-border-2:    #cbd5e1;
  --color-text-1:      #0f172a;
  --color-text-2:      #475569;
  --color-text-3:      #94a3b8;
  --color-accent:      #2563eb;
  --color-accent-bg:   #eff6ff;
  --color-success:     #15803d;
  --color-success-bg:  #dcfce7;
  --color-warning:     #d97706;
  --color-warning-bg:  #fef9c3;
  --color-danger:      #dc2626;
  --color-danger-bg:   #fef2f2;
  --color-neutral-bg:  #f1f5f9;
  --color-neutral:     #475569;

  /* Chart palette */
  --color-chart-1: #2563eb;
  --color-chart-2: #8373bc;
  --color-chart-3: #046642;
  --color-chart-4: #b36519;
  --color-chart-5: #e4307e;

  /* Typography */
  --font-sans:  system-ui, -apple-system, 'Segoe UI', sans-serif;
  --font-mono:  ui-monospace, 'JetBrains Mono', 'Fira Code', monospace;
  --text-xs:    11px;
  --text-sm:    13px;
  --text-base:  14px;
  --text-lg:    16px;
  --text-xl:    20px;
  --text-2xl:   24px;
  --text-mono-sm:   12px;
  --text-mono-base: 13px;

  /* Spacing */
  --space-1:  4px;
  --space-2:  8px;
  --space-3:  12px;
  --space-4:  16px;
  --space-5:  20px;
  --space-6:  24px;
  --space-8:  32px;
  --space-10: 40px;
  --space-12: 48px;

  /* Radii */
  --radius-sm:   4px;
  --radius-base: 6px;
  --radius-lg:   8px;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-1: 0 1px 2px rgba(0,0,0,.06);
  --shadow-2: 0 2px 8px rgba(0,0,0,.10);
  --shadow-3: 0 4px 16px rgba(0,0,0,.14);

  /* Z-index */
  --z-base:           0;
  --z-sticky:         100;
  --z-dropdown:       200;
  --z-tooltip:        300;
  --z-modal-backdrop: 400;
  --z-modal:          500;
  --z-toast:          600;

  /* Motion */
  --duration-fast: 100ms;
  --duration-base: 200ms;
  --duration-slow: 300ms;
  --easing-default: ease;
  --easing-in-out: cubic-bezier(0.4,0,0.2,1);
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg:          #020617;
    --color-surface:     #0f172a;
    --color-surface-2:   #1e293b;
    --color-border:      #334155;
    --color-border-2:    #475569;
    --color-text-1:      #f8fafc;
    --color-text-2:      #94a3b8;
    --color-text-3:      #475569;
    --color-accent:      #60a5fa;
    --color-accent-bg:   #172554;
    --color-success:     #4ade80;
    --color-success-bg:  #14532d;
    --color-warning:     #fbbf24;
    --color-warning-bg:  #422006;
    --color-danger:      #f87171;
    --color-danger-bg:   #450a0a;
    --color-neutral-bg:  #1e293b;
    --color-neutral:     #94a3b8;

    --color-chart-1: #60a5fa;
    --color-chart-2: #8b6eda;
    --color-chart-3: #01d699;
    --color-chart-4: #c89716;
    --color-chart-5: #e965ab;
  }
}

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    transition-duration: 0ms !important;
    animation-duration:  0ms !important;
  }
}

Released under the MIT License.