Design Tokens

Overview

Design tokens are the centralized style values — colors, spacing, typography — that keep the system visually consistent. In this theme they are CSS custom properties defined once in css/base.css (:root), and every component reaches them indirectly through the semantic utility classes (see Design Tokens and Utility Classes).

This page explains the token architecture. For the actual values, see Color and Spacing; for type, see Typography.

A two-layer system

1. Layer 1 — Primitives. Raw values: the Maryland color palette and gray ramp, and the --space-* scale. Defined in :root.
2. Layer 2 — Semantic utilities. Classes (c-*, t-*, s-*, ani-*) that map a role to a primitive via var(). This is the surface developers write.

Components never use a primitive directly in markup — they apply the semantic utility, which references the primitive. Because of this indirection, changing a single token value in base.css updates the whole system, and dark mode comes for free (see below). Developers building components should read Building a Component.

How dark mode works

The .dark-theme class re-maps the same token names to inverted values, rather than introducing new tokens:

.dark-theme {
  --maryland-red: #ffd200;   /* red ↔ yellow swap */
  --maryland-yellow: #e21833;
  --white: #000000;          /* white ↔ black swap */
  --black: #ffffff;
  --lightest-gray: #242424;  /* gray ramp reversed */
  --lighter-gray: #454545;
  --light-gray: #757575;
  --medium-gray: #e6e6e6;
  --dark-gray: #f1f1f1;
  --darker-gray: #fafafa;
}

Because every utility and component references var(--token), nothing downstream needs dark-mode-specific code — flipping .dark-theme on an ancestor recolors the entire subtree.

Two things are intentionally theme-independent and are not re-mapped: the spacing scale (sizes don't change between themes) and --green (a status-only color — see Color).

Adapting the system to another brand

Because all appearance flows from these tokens, this design system can be re-pointed at a different brand by editing the token values in base.css — not by touching individual components. Update the palette and the whole system follows.