> ## Documentation Index
> Fetch the complete documentation index at: https://atomickit.copyelement.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AtomicKit Color Palette: Grays and Semantic Tokens

> AtomicKit's color system includes structural grays, six semantic tokens with 11-step shade ramps, and text, background, and border utility classes.

AtomicKit ships a unified color palette covering text, background, and border utilities. The system uses six semantic tokens — primary, secondary, neutral, success, warning, and error — each with an 11-step shade ramp that lets you reach for a lighter tint or deeper shade without leaving your utility classes. On top of those tokens, a set of structural grays handles everyday typography hierarchy and surface fills.

## Semantic Base Colors

Each semantic token has a base hex value. All six tokens support the full shade ramp described below.

| Token     | Class Prefix        | Base Hex  |
| --------- | ------------------- | --------- |
| Primary   | `.{type}-primary`   | `#0740f9` |
| Secondary | `.{type}-secondary` | `#aaebfd` |
| Neutral   | `.{type}-neutral`   | `#6b7280` |
| Success   | `.{type}-success`   | `#3DC13C` |
| Warning   | `.{type}-warning`   | `#F4BB1B` |
| Error     | `.{type}-error`     | `#F13737` |

Replace `{type}` with `text`, `background`, or `border` depending on which property you need to set.

## The 11-Step Shade Ramp

Every semantic token supports eleven steps: five lighter shades, the base, and five darker shades. The ramp suffix follows this pattern:

| Suffix   | Direction       |
| -------- | --------------- |
| `-l-5`   | Lightest        |
| `-l-4`   | Lighter         |
| `-l-3`   | Light           |
| `-l-2`   | Slightly light  |
| `-l-1`   | Just above base |
| *(none)* | Base            |
| `-d-1`   | Just below base |
| `-d-2`   | Slightly dark   |
| `-d-3`   | Dark            |
| `-d-4`   | Darker          |
| `-d-5`   | Darkest         |

Append the suffix directly to any semantic token class. For example, `.background-primary` is the base blue, while `.background-primary-l-3` gives you a lighter mid-tint and `.background-primary-d-2` steps into a deeper shade.

## Using Shade Variants

Apply a shade suffix whenever the base token is too saturated or too light for your context. A common pattern is using a light tint for a section background and the base token for a prominent call-to-action inside it.

```html theme={null}
<!-- Light primary tint for a section background -->
<div class="background-primary-l-3">

  <!-- Base primary for the CTA button inside -->
  <button class="background-primary text-white">
    Get Started
  </button>

</div>
```

```html theme={null}
<!-- Darker success shade for a hover state or emphasis badge -->
<span class="background-success-d-1 text-white">Verified</span>
```

<Tip>
  Start with the base token and only reach for a shade variant when you need contrast adjustment or a subtle tint. Limiting your palette to two or three steps per token keeps designs coherent.
</Tip>

## Structural Grays

Alongside the semantic tokens, AtomicKit includes fixed gray values for typography hierarchy and neutral surfaces. These are available across text, background, and border utilities:

* **white / black** — absolute extremes for high-contrast needs
* **gray-dark** (`#374151`) — primary body text
* **gray** (`#6b7280`) — secondary text, captions
* **gray-light** — muted text (`#9ca3af` for text; `#f3f4f6` for backgrounds; `#e5e7eb` for borders)

<Note>
  The `text-gray-*` classes are intended for typographic hierarchy tiers and are fixed values. The `text-neutral` class and its shade variants follow the full 11-step semantic ramp and are better suited when you need programmatic shade stepping.
</Note>

## Accessibility

<Warning>
  Color alone should never be the only signal conveying meaning. Always supplement color-coded status (success, warning, error) with an icon, label, or text description. Check that your foreground and background color pairings meet WCAG AA contrast ratios — a minimum of 4.5:1 for normal text and 3:1 for large text. The AtomicKit palette is designed with sensible defaults, but your specific combination of shade variants and surface colors still needs verification.
</Warning>

## Color Utility Categories

<CardGroup cols={3}>
  <Card title="Text Colors" icon="font" href="/colors/text-colors">
    Set `color` on headings, body copy, links, and status labels using `.text-*` classes.
  </Card>

  <Card title="Background Colors" icon="paintbrush" href="/colors/background-colors">
    Fill sections, cards, and panels with `.background-*` classes across the full palette.
  </Card>

  <Card title="Border Colors" icon="border-all" href="/colors/border-colors">
    Apply `.border-*` color classes alongside width and style utilities for complete borders.
  </Card>
</CardGroup>