Skip to main content
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.
TokenClass PrefixBase 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:
SuffixDirection
-l-5Lightest
-l-4Lighter
-l-3Light
-l-2Slightly light
-l-1Just above base
(none)Base
-d-1Just below base
-d-2Slightly dark
-d-3Dark
-d-4Darker
-d-5Darkest
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. 
<!-- 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>

<!-- Darker success shade for a hover state or emphasis badge -->
<span class="background-success-d-1 text-white">Verified</span>
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.

​
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)
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.

​
Accessibility

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.

​
Color Utility Categories

Text Colors

Set color on headings, body copy, links, and status labels using .text-* classes.

Background Colors

Fill sections, cards, and panels with .background-* classes across the full palette.

Border Colors

Apply .border-* color classes alongside width and style utilities for complete borders.