# Color Tokens

## Overview

The repo currently defines two color themes:

- `light`: the default color theme
- `dark`: a dark mode theme using the BYU navy background, softened blue accents, and brighter status colors

Color themes are defined in [color.css](/Users/stuft2/Projects/design-system/src/css/color.css) and are applied with the `data-color-theme` attribute when needed.

Both themes define semantic utility color families for `info`, `success`, `warning`, `error`, and `unavailable`.

Each color family has one authored default token. Strong and subtle variants are calculated from that default so theme authors do not need to provide a separate value for every step in the scale.

## Usage

Apply a color theme when needed:

```html
<html data-color-theme="light">
```

```html
<html data-color-theme="dark">
```

Display token values with native color inputs when documenting or configuring a color scale:

```html
<label for="color-primary">
  Primary
  <input id="color-primary" name="primary" type="color" value="#0047ba" />
  <small>--color-primary</small>
</label>
```

For exact shared color values and computed token definitions, use [color.css](/Users/stuft2/Projects/design-system/src/css/color.css) as the source of truth.

Reference color tokens directly from component styles. The shared color stylesheet defines semantic tokens, not public text or background helper classes.

## Authoring Rules

- Use shared color tokens before creating a new component-level color token.
- Prefer semantic names that describe role or state instead of raw hue names.
- Derive supportive utility shades from the base semantic token when that preserves the intended family relationship.
- Do not use semantic color tokens as generic replacements for unrelated primary, accent, text, or border roles.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--color-accent` | `<color>` | Default accent background color. Use for: page backgrounds, control backgrounds, and neutral component accents Avoid for: borders or text |
| `--color-accent-disabled` | `<color>` | Muted accent color for disabled controls. Use for: disabled buttons and inactive accents Avoid for: default interactive controls |
| `--color-accent-strong` | `<color>` | Strong accent fill color. Derived from: `--color-accent` Use for: filled secondary UI accents that need contrast with white content Avoid for: borders or text |
| `--color-accent-subtle` | `<color>` | Quiet accent background color. Derived from: `--color-accent` by increasing each RGB channel Use for: low-emphasis panels, code blocks, and grouped preview regions Avoid for: primary page backgrounds |
| `--color-border` | `<color>` | Default border color source. Use for: the authored border color that derived border variants are calculated from Avoid for: component borders when a subtle or strong role better describes the treatment |
| `--color-border-inverse` | `<color>` | Default border color for inverse accents. Use for: dividers and outlines on inverted accents Avoid for: component borders on default light accents |
| `--color-border-strong` | `<color>` | Strong border color. Derived from: `--color-border` Use for: emphasized outlines and low-emphasis badges or chips that need visible separation Avoid for: primary text |
| `--color-border-strong-inverse` | `<color>` | Strong border color for inverse accents. Derived from: `--color-border-inverse` Use for: high-emphasis dividers and outlines on inverted accents Avoid for: component borders on default light accents |
| `--color-border-subtle` | `<color>` | Subtle border color. Derived from: `--color-border` Use for: default control borders and quiet separators Avoid for: primary actions or text |
| `--color-border-subtle-inverse` | `<color>` | Subtle border color for inverse accents. Derived from: `--color-border-inverse` Use for: quiet dividers and outlines on inverted accents Avoid for: essential focus indicators |
| `--color-error` | `<color>` | Default error utility color. Use for: the standard error tone in components and the source color for the error scale Avoid for: non-semantic decorative emphasis |
| `--color-error-strong` | `<color>` | Derived darker error utility color. Use for: destructive and high-emphasis error states Avoid for: default body text |
| `--color-error-subtle` | `<color>` | Derived lighter error utility color. Use for: low-emphasis error backgrounds and inline validation regions Avoid for: high-contrast borders or dense copy |
| `--color-focus-ring` | `<color>` | Focus ring color paired with the primary color. Derived from: `--color-primary-subtle` Use for: accessible focus indication around interactive elements Avoid for: static fills or borders |
| `--color-info` | `<color>` | Default informational utility color. Use for: the standard info tone in components and the source color for the info scale Avoid for: direct replacement of all primary accents |
| `--color-info-strong` | `<color>` | Derived darker informational utility color. Use for: higher-emphasis info surfaces, badges, and banners Avoid for: default body text |
| `--color-info-subtle` | `<color>` | Derived lighter informational utility color. Use for: low-emphasis info backgrounds and supporting UI Avoid for: high-contrast borders or dense text |
| `--color-primary` | `<color>` | Primary action color. Use for: primary action fills, primary borders, control accents, and derived primary accents Avoid for: foreground accent text when `--color-text-accent` better describes the role |
| `--color-primary-strong` | `<color>` | Stronger primary color for pressed or deeper emphasis states. Derived from: `--color-primary` Use for: pressed primary actions and higher-emphasis primary accents Avoid for: default accent text on page accents |
| `--color-primary-subtle` | `<color>` | Subtle primary accent color. Derived from: `--color-primary` Use for: selected tab backgrounds, quiet primary hover accents, and low-emphasis primary fills Avoid for: foreground text or primary action fills |
| `--color-success` | `<color>` | Default success utility color. Use for: the standard success tone in components and the source color for the success scale Avoid for: generic primary styling |
| `--color-success-strong` | `<color>` | Derived darker success utility color. Use for: high-emphasis success states and confirmation surfaces Avoid for: default body text |
| `--color-success-subtle` | `<color>` | Derived lighter success utility color. Use for: quiet success backgrounds and supportive emphasis Avoid for: strong dividers or compact text |
| `--color-text` | `<color>` | Default foreground text color. Use for: primary text and form values Avoid for: placeholder text or subtle dividers |
| `--color-text-accent` | `<color>` | Accent foreground text color. Derived from: `--color-primary` Use for: accent-colored links, labels, headings, and foreground accents on default accents Avoid for: primary fills, borders, and native control accents |
| `--color-text-accent-inverse` | `<color>` | Accent foreground text color for inverse accents. Copies the same value as `--color-text-inverse` without aliasing it Use for: accent-colored foreground accents on dark, inverse, or primary-heavy accents Avoid for: primary fills, borders, and foreground text on default light accents |
| `--color-text-accent-strong` | `<color>` | Strong accent foreground text color. Derived from: `--color-text-accent` Use for: higher-emphasis accent foreground accents on default accents Avoid for: primary fills or non-accent text emphasis |
| `--color-text-accent-strong-inverse` | `<color>` | Strong accent foreground text color for inverse accents. Uses the same derivation as `--color-text-strong-inverse` without aliasing it Use for: higher-emphasis accent foreground accents on dark, inverse, or primary-heavy accents Avoid for: primary fills or foreground text on default light accents |
| `--color-text-accent-subtle` | `<color>` | Subtle accent foreground text color. Derived from: `--color-text-accent` Use for: lower-emphasis accent foreground accents on default accents Avoid for: long-form body text or disabled text |
| `--color-text-accent-subtle-inverse` | `<color>` | Subtle accent foreground text color for inverse accents. Uses the same derivation as `--color-text-subtle-inverse` without aliasing it Use for: lower-emphasis accent foreground accents on dark, inverse, or primary-heavy accents Avoid for: primary text on inverse accents |
| `--color-text-inverse` | `<color>` | Default foreground text color for inverse accents. Sits between `--color-text-strong-inverse` and `--color-text-subtle-inverse` Use for: primary text on inverted accents Avoid for: primary text on default light accents |
| `--color-text-strong` | `<color>` | Strong foreground text color. Derived from: `--color-text` Use for: high-emphasis foreground content Avoid for: subtle helper text |
| `--color-text-strong-inverse` | `<color>` | Strong foreground text color for inverse accents. Derived from: `--color-text-inverse` by mixing darker Use for: darker foreground content on inverted accents Avoid for: subtle helper text or current navigation items that need maximum inverse contrast |
| `--color-text-subtle` | `<color>` | Subtle foreground text color. Derived from: `--color-text` Use for: secondary copy, quiet labels, and low-emphasis foregrounds Avoid for: long-form primary reading text |
| `--color-text-subtle-inverse` | `<color>` | Subtle foreground text color for inverse accents. Derived from: `--color-text-inverse` by mixing lighter Use for: lighter foreground accents on inverted accents Avoid for: muted or low-emphasis text on inverse accents |
| `--color-unavailable` | `<color>` | Default unavailable utility color. Use for: unavailable states, unavailable item markers, and the source color for the unavailable scale Avoid for: disabled control styling when `--color-accent-disabled` better describes the role |
| `--color-unavailable-strong` | `<color>` | Derived darker unavailable utility color. Use for: higher-emphasis unavailable markers and unavailable state accents Avoid for: default body text |
| `--color-unavailable-subtle` | `<color>` | Derived lighter unavailable utility color. Use for: low-emphasis unavailable backgrounds and supporting UI Avoid for: essential borders or dense copy without contrast testing |
| `--color-warning` | `<color>` | Default warning utility color. Use for: the standard warning tone in components and the source color for the warning scale Avoid for: body text or default low-emphasis highlighting |
| `--color-warning-strong` | `<color>` | Derived darker warning utility color. Use for: high-emphasis warning states and warning banners Avoid for: low-contrast content |
| `--color-warning-subtle` | `<color>` | Derived lighter warning utility color. Use for: low-emphasis warning backgrounds Avoid for: text-heavy UI without stronger foreground contrast |