CSS Variables (Custom Properties)

Atomic CSS can directly reference CSS custom properties (variables) as classes. Use variables defined in :root with HTML classes alone — no additional CSS needed.

Core Rule: prefix--variable-name → property: var(--variable-name)

How It Works

Define variables in :root, reference them with Atomic classes, and CSS is auto-generated.

/* :root definition */
:root {
  --primary: #6366f1;
  --spacing: 16px;
  --radius: 8px;
}

/* Use with Atomic CSS classes */
<div class="bg--primary gap--spacing br--radius">
  ...
</div>

/* Generated CSS */
.bg--primary { background-color: var(--primary); }
.gap--spacing { gap: var(--spacing); }
.br--radius { border-radius: var(--radius); }

Syntax

Class names connect a CSS property prefix and variable name with a double hyphen (--).

prefix--variable-name

Part	Description	Example
`prefix`	CSS property abbreviation prefix (same as standard Atomic rules)	`bg`, `w`, `gap`
`--`	Double hyphen — separator indicating a variable reference	—
`variable-name`	CSS custom property name (the part after `--`)	`primary`, `spacing-md`

Colors

Manage text, background, and border colors with variables.

Class	CSS	Description
`c--text`	color: var(--text)	Text color
`bg--primary`	background-color: var(--primary)	Background color
`bc--border`	border-color: var(--border)	Border color
`btc--accent`	border-top-color: var(--accent)	Top border color
`fill--icon`	fill: var(--icon)	SVG fill color
`stroke--line`	stroke: var(--line)	SVG stroke color

<!-- Define variables in :root -->
<style>
:root {
  --primary: #6366f1;
  --surface: #18181b;
  --text: #fafafa;
  --muted: #71717a;
  --border: #27272a;
}
</style>

<!-- Use with Atomic CSS -->
<div class="bg--surface c--text b1pxsolid--border br8px p2rem">
  <h2 class="c--primary fs2rem fw700">Heading</h2>
  <p class="c--muted fs14px">Description text</p>
</div>

Spacing

Unify margin, padding, gap, and position values with variables.

Class	CSS	Description
`m--spacing`	margin: var(--spacing)	All margins
`mt--header-h`	margin-top: var(--header-h)	Top margin
`p--card-pad`	padding: var(--card-pad)	All padding
`gap--grid-gap`	gap: var(--grid-gap)	Grid/flex gap
`rg--row-gap`	row-gap: var(--row-gap)	Row gap
`cg--col-gap`	column-gap: var(--col-gap)	Column gap
`t--nav-h`	top: var(--nav-h)	Top offset

<style>
:root {
  --page-pad: 2.4rem;
  --card-gap: 16px;
  --section-gap: 4rem;
}
</style>

<!-- Consistent spacing with variables -->
<main class="p--page-pad">
  <section class="mb--section-gap">
    <div class="dg gtcr3-1fr gap--card-gap">
      <div class="p--page-pad bg18181B br8px">Card</div>
      <div class="p--page-pad bg18181B br8px">Card</div>
      <div class="p--page-pad bg18181B br8px">Card</div>
    </div>
  </section>
</main>

Sizing

Class	CSS	Description
`w--sidebar-w`	width: var(--sidebar-w)	Width
`h--hero-h`	height: var(--hero-h)	Height
`maxw--container`	max-width: var(--container)	Max width
`minh--screen`	min-height: var(--screen)	Min height

Typography

Class	CSS
`fs--body`	font-size: var(--body)
`fw--heading`	font-weight: var(--heading)
`lh--body`	line-height: var(--body)
`ff--mono`	font-family: var(--mono)
`ls--wide`	letter-spacing: var(--wide)

Border & Radius

Class	CSS
`br--radius`	border-radius: var(--radius)
`bw--border-w`	border-width: var(--border-w)
`btw--divider`	border-top-width: var(--divider)

Grid & Flex

Class	CSS
`gtc--cols`	grid-template-columns: var(--cols)
`gtr--rows`	grid-template-rows: var(--rows)
`gac--auto-col`	grid-auto-columns: var(--auto-col)
`fb--basis`	flex-basis: var(--basis)
`fg--grow`	flex-grow: var(--grow)

Effects & Others

Class	CSS
`zi--modal`	z-index: var(--modal)
`o--fade`	opacity: var(--fade)
`bxs--card`	box-shadow: var(--card)
`ts--glow`	text-shadow: var(--glow)
`fltr--blur`	filter: var(--blur)
`trf--move`	transform: var(--move)
`trn--smooth`	transition: var(--smooth)
`ar--video`	aspect-ratio: var(--video)

Combinations

CSS variable classes can be freely combined with media queries, pseudo-classes, and !important.

Media Query + Variable

<!-- Responsive: different variable per breakpoint -->
<div class="bg--primary md-bg--primary-md sm-bg--primary-sm">
  Responsive color
</div>

<!-- Variable-based responsive spacing -->
<section class="p--desktop-pad md-p--tablet-pad sm-p--mobile-pad">
  Content
</section>

Pseudo-class + Variable

<!-- Hover: change to accent color -->
<button class="bg--primary hover-bg--accent c--text cp py8px px16px br8px bn">
  Hover me
</button>

<!-- Focus: outline with variable color -->
<input class="focus-olc--ring focus-visible-olc--ring" />

<!-- Pseudo-element -->
<div class="before-bg--accent">Decorated</div>

!important + Variable

<!-- !important suffix: add 'i' at the end -->
<div class="bg--surfacei c--texti">
  Styles with !important
</div>

<!-- Generated CSS -->
<!-- .bg--surfacei { background-color: var(--surface) !important; } -->
<!-- .c--texti { color: var(--text) !important; } -->

Shorthand Decomposition

p, m, gap, bw are shorthands that decompose into individual directions.

Class	Generated CSS
`p--space`	padding-top/right/bottom/left: var(--space)
`m--space`	margin-top/right/bottom/left: var(--space)
`gap--space`	row-gap: var(--space); column-gap: var(--space)
`bw--line`	border-top/right/bottom/left-width: var(--line)

Practical Example — Design System

Using variables enables consistent, design-token-based UI.

<style>
:root {
  --primary: #6366f1;
  --surface: #111113;
  --surface-hover: #18181b;
  --text: #fafafa;
  --muted: #71717a;
  --border: #27272a;
  --radius: 12px;
  --gap: 16px;
  --pad: 2rem;
}
</style>

<!-- Design system powered by variables -->
<div class="dg gtcr3-1fr gap--gap sm-gtc1fr">
  <article class="bg--surface b1pxsolid--border br--radius p--pad hover-bg--surface-hover tall200msease">
    <h3 class="c--text fs16px fw700 mb8px">Card Title</h3>
    <p class="c--muted fs14px m0 lh1-6">Card description text</p>
  </article>
</div>

Dark Mode Toggle

Just swap :root variables and the same Atomic classes switch between light and dark mode.

/* Light mode */
:root {
  --bg: #ffffff;
  --text: #1a1a2e;
  --border: #e4e4e7;
  --primary: #6366f1;
}

/* Dark mode */
:root.dark {
  --bg: #09090b;
  --text: #fafafa;
  --border: #27272a;
  --primary: #818cf8;
}

/* Same Atomic classes work in both modes */
/* <div class="bg--bg c--text b1pxsolid--border"> */

Tips & Cautions

Supported Prefixes

Only prefixes listed in the full reference below support CSS variables. Unsupported prefixes are ignored.

neg- Not Allowed

The neg- prefix cannot be used with CSS variable classes. Define negative values in the variable itself if needed.

:root Definition Required

Atomic CSS only references variables. The actual values must be defined in :root or a separate CSS file.

Full Prefix Reference

Complete list of all prefixes that support CSS variables.

Color

Prefix	CSS Property	Example
`c`	color	`c--text`
`bg`	background-color	`bg--primary`
`bc`	border-color	`bc--border`
`btc`	border-top-color	`btc--accent`
`brc`	border-right-color	`brc--accent`
`bbc`	border-bottom-color	`bbc--accent`
`blc`	border-left-color	`blc--accent`
`fill`	fill	`fill--icon`
`stroke`	stroke	`stroke--line`