# Color Tokens

## Contrast-Based Naming

Theme colors use a **subtle → strong** scale that works across light and dark modes:

| Token | Light Mode | Dark Mode | Use Case |
| - | - | - | - |
| `subtlest` | Lightest tint | Darkest shade | Subtle backgrounds |
| `subtle` | Light tint | Dark shade | Muted backgrounds |
| `soft` | Medium-light | Medium-dark | Soft accents |
| `base` | Core color | Adjusted core | Primary brand use |
| `strong` | Medium-dark | Medium-light | Text on backgrounds |
| `stronger` | Dark | Light | High-contrast text |
| `strongest` | Darkest | Lightest | Maximum contrast |

The key insight: **"stronger" always means more contrast** against the contextual background, regardless of light/dark mode.

## Default Color Palettes

Tangible Design System ships with the following color defaults. When extending the system with new components these are the only allowed color tokens, and colors must *never* be hardcoded.

For deterministic identity colors (avatar initials, tags, category accents) see [Generative Colors](https://storybook-tangible-ui.pages.dev/docs/tokens-generative-colors.md) — those are intentionally outside the theme ladders.

### Brand Colors

---

Visual swatches: [see the interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/tokens-colors--docs). Token values are in [the primitive token reference](https://storybook-tangible-ui.pages.dev/docs/reference-primitive-tokens.md).

### Semantic Colors

---

### Neutral Colors

---

Neutrals use **role names**, not the contrast ladder. The background roles, from the canvas up:

| Token | Role |
| - | - |
| `bg-surface` | The page canvas *behind* components — a light gray by design, so white component faces read as raised against it. Also the fill for bordered panels sitting on a white face. |
| `bg` | Component faces (cards, inputs, menus) — white in light mode. |
| `bg-muted` | Muted wells *within* a component face: readouts, submitted-text panels, disabled fills. |
| `bg-elevated` | Overlaid faces (popovers, modals) — white, lifted by shadow rather than color. |
| `bg-inverted` | Inverted panels (tooltips, dark callouts). |
| `bg-overlay` | The translucent backdrop behind modals. |

Foregrounds follow the same pattern: `fg` for body text, `fg-secondary` for supporting text, `fg-muted` for meta/hints, `fg-on-accent` for text on `base`-color fills, `fg-inverted` for text on inverted panels.

## Customization

Color customization is fairly straightforward, since all colors consumed by components are attached to global CSS custom properties.

The default palettes can be overridden by re-defining the CSS custom properties. In most cases, this change will be scoped to `tui-interface` in order to impact all components within the defined Tangible frontend scope.

```css
/* Re-map Primary colors to a calming sage green */
.tui-interface {
  --tui-theme-primary-strongest:  #242424;
  --tui-theme-primary-stronger:   #535249;
  --tui-theme-primary-strong:     #797762;
  --tui-theme-primary-base:       #a9ad7f;
  --tui-theme-primary-soft:       #b6c48b;
  --tui-theme-primary-subtle:     #c2dc9c;
  --tui-theme-primary-subtlest:   #d7f2c5;
}

```

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/tokens-colors--docs