# Colors

A strict, utilitarian monochromatic palette.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).



Colors in the **Monolith Design System** are ruthlessly monochromatic. The system relies on absolute contrast (black and white) and subtle gray mid-tones for all structural elements.

Color is reserved strictly for persistent semantics (Danger, Success) and must never be used for decoration.

## Surfaces [#surfaces]

Surfaces form the structural hierarchy of the interface. We use a 4-tier model:

| Token                 | Light Mode | Dark Mode | Usage                                            |
| --------------------- | ---------- | --------- | ------------------------------------------------ |
| `--bg-canvas`         | `#fcfcfc`  | `#09090b` | The base document background.                    |
| `--bg-subtle`         | `#f4f4f5`  | `#121215` | Secondary regions (sidebars, secondary panels).  |
| `--bg-surface`        | `#ffffff`  | `#18181b` | Primary content cards, modals, dropdowns.        |
| `--bg-surface-raised` | `#e4e4e7`  | `#27272a` | Code blocks, inline highlights, raised elements. |

## Foregrounds [#foregrounds]

Text and icons must maintain strict WCAG AA/AAA compliance.

| Token                    | Light Mode | Dark Mode | Usage                                              |
| ------------------------ | ---------- | --------- | -------------------------------------------------- |
| `--foreground-primary`   | `#18181b`  | `#f4f4f5` | Standard body text, active icons, primary content. |
| `--foreground-secondary` | `#52525b`  | `#a1a1aa` | Supporting text, metadata, deactivated elements.   |
| `--foreground-muted`     | `#71717a`  | `#71717a` | Disabled states, line numbers, subtle hints.       |

## Interactions [#interactions]

Interactive states follow the same monochromatic rules.

* **Button Primary (`--btn-primary-bg`)**: The primary execution action. Always a solid block (`#18181b` in Light, `#f4f4f5` in Dark).
* **Transient Accents (`--accent-interactive`)**: Used only during hover/active states. We do not use permanent colored accents for interactivity.
* **Focus Rings (`--focus-ring`)**: Rigid 1px rings (`focus-visible:ring-1`) using the absolute contrast color.

## Semantics [#semantics]

Color is weaponized for meaning. It is only introduced when the user must be alerted to a state change.

* **Danger (`--semantic-danger`)**: `#dc2626` (Light) / `#ef4444` (Dark). Destructive actions, errors.
* **Success (`--semantic-success`)**: `#16a34a` (Light) / `#16a34a` (Dark). Confirmations, success states.

### The "One Voice" Rule [#the-one-voice-rule]

Do not mix semantic colors. A single screen should never have both a solid Red and solid Green button competing for attention.

## Tailwind Mapping [#tailwind-mapping]

We expose standard Tailwind utility classes mapping to these tokens. For legacy compatibility, they are mapped as follows:

* `bg-background` -> `--bg-canvas`
* `bg-surface` -> `--bg-surface`
* `text-foreground` -> `--foreground-primary`
* `border-border` -> `--border-subtle`
* `bg-primary` -> `--btn-primary-bg`