CSS 변수 (Custom Properties)

Atomic CSS는 CSS 커스텀 속성(변수)을 클래스로 직접 참조할 수 있습니다. :root에 정의한 변수를 별도의 CSS 작성 없이 HTML 클래스만으로 사용합니다.

핵심 규칙: 접두사--변수명 → 속성: var(--변수명)

작동 방식

:root에 변수를 정의하고, Atomic 클래스로 참조하면 CSS가 자동 생성됩니다.

/* :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); }

문법

클래스명은 CSS 속성 접두사와 변수명을 이중 하이픈(--)으로 연결합니다.

prefix--variable-name

구성	설명	예시
`prefix`	CSS 속성의 약어 접두사 (기존 Atomic 규칙과 동일)	`bg`, `w`, `gap`
`--`	이중 하이픈 — 변수 참조를 나타내는 구분자	—
`variable-name`	CSS 커스텀 속성명 (`--` 이후 부분)	`primary`, `spacing-md`

색상 (Color)

텍스트, 배경, 테두리 색상을 변수로 관리합니다.

클래스	CSS	설명
`c--text`	color: var(--text)	텍스트 색상
`bg--primary`	background-color: var(--primary)	배경색
`bc--border`	border-color: var(--border)	테두리 색상
`btc--accent`	border-top-color: var(--accent)	상단 테두리 색상
`fill--icon`	fill: var(--icon)	SVG fill 색상
`stroke--line`	stroke: var(--line)	SVG stroke 색상

<!-- 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)

마진, 패딩, 갭, 위치값을 변수로 통일합니다.

클래스	CSS	설명
`m--spacing`	margin: var(--spacing)	전체 마진
`mt--header-h`	margin-top: var(--header-h)	상단 마진
`p--card-pad`	padding: var(--card-pad)	전체 패딩
`gap--grid-gap`	gap: var(--grid-gap)	그리드/플렉스 간격
`rg--row-gap`	row-gap: var(--row-gap)	행 간격
`cg--col-gap`	column-gap: var(--col-gap)	열 간격
`t--nav-h`	top: var(--nav-h)	상단 위치값

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

클래스	CSS	설명
`w--sidebar-w`	width: var(--sidebar-w)	너비
`h--hero-h`	height: var(--hero-h)	높이
`maxw--container`	max-width: var(--container)	최대 너비
`minh--screen`	min-height: var(--screen)	최소 높이

타이포그래피 (Typography)

클래스	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)

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

그리드 & 플렉스 (Grid & Flex)

클래스	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)

클래스	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 변수 클래스는 미디어 쿼리, 의사 클래스, !important와 자유롭게 조합됩니다.

미디어 쿼리 + 변수

<!-- 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>

의사 클래스 + 변수

<!-- 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 + 변수

<!-- !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 분해

p, m, gap, bw는 shorthand로 각 방향으로 분해됩니다.

클래스	생성되는 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)

실전 예시 — 디자인 시스템

변수를 활용하면 디자인 토큰 기반의 일관된 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>

다크 모드 전환

:root 변수만 바꾸면 같은 Atomic 클래스로 라이트/다크 모드를 전환할 수 있습니다.

/* 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"> */

팁 & 주의사항

지원하는 접두사

아래 전체 레퍼런스에 나열된 접두사만 CSS 변수를 지원합니다. 지원하지 않는 접두사는 무시됩니다.

neg- 사용 불가

CSS 변수 클래스에는 neg- 접두사를 사용할 수 없습니다. 음수값이 필요하면 변수 자체에 음수를 정의하세요.

:root 정의 필수

Atomic CSS는 변수를 참조만 합니다. 변수의 실제 값은 :root 또는 별도 CSS에서 정의해야 합니다.

전체 접두사 레퍼런스

CSS 변수를 지원하는 모든 접두사 목록입니다.

Color

Prefix	CSS Property	예시
`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`

Spacing

Prefix	CSS Property	예시
`m`	margin (shorthand)	`m--space`
`mt`	margin-top	`mt--gap`
`mr`	margin-right	`mr--gap`
`mb`	margin-bottom	`mb--gap`
`ml`	margin-left	`ml--gap`
`p`	padding (shorthand)	`p--pad`
`pt`	padding-top	`pt--pad`
`pr`	padding-right	`pr--pad`
`pb`	padding-bottom	`pb--pad`
`pl`	padding-left	`pl--pad`
`gap`	gap (shorthand)	`gap--grid`
`rg`	row-gap	`rg--row`
`cg`	column-gap	`cg--col`
`t`	top	`t--offset`
`r`	right	`r--offset`
`b`	bottom	`b--offset`
`l`	left	`l--offset`

Sizing

Prefix	CSS Property	예시
`w`	width	`w--sidebar`
`h`	height	`h--hero`
`maxw`	max-width	`maxw--container`
`maxh`	max-height	`maxh--modal`
`minw`	min-width	`minw--btn`
`minh`	min-height	`minh--page`

Typography

Prefix	CSS Property	예시
`fs`	font-size	`fs--body`
`fw`	font-weight	`fw--bold`
`lh`	line-height	`lh--body`
`ff`	font-family	`ff--mono`
`ls`	letter-spacing	`ls--wide`
`ws`	word-spacing	`ws--loose`
`ti`	text-indent	`ti--indent`

Border & Radius

Prefix	CSS Property	예시
`br`	border-radius	`br--radius`
`bw`	border-width (shorthand)	`bw--line`
`btw`	border-top-width	`btw--divider`
`brw`	border-right-width	`brw--line`
`bbw`	border-bottom-width	`bbw--line`
`blw`	border-left-width	`blw--line`

Grid & Flex

Prefix	CSS Property	예시
`gtc`	grid-template-columns	`gtc--layout`
`gtr`	grid-template-rows	`gtr--rows`
`gta`	grid-template-areas	`gta--areas`
`gac`	grid-auto-columns	`gac--auto`
`gar`	grid-auto-rows	`gar--auto`
`gcs`	grid-column-start	`gcs--start`
`gce`	grid-column-end	`gce--end`
`grs`	grid-row-start	`grs--start`
`gre`	grid-row-end	`gre--end`
`fg`	flex-grow	`fg--grow`
`fb`	flex-basis	`fb--basis`

Effects & Others

Prefix	CSS Property	예시
`zi`	z-index	`zi--modal`
`o`	opacity	`o--fade`
`bxs`	box-shadow	`bxs--card`
`ts`	text-shadow	`ts--glow`
`fltr`	filter	`fltr--blur`
`bdfltr`	backdrop-filter	`bdfltr--glass`
`trf`	transform	`trf--move`
`trn`	transition	`trn--smooth`
`anim`	animation	`anim--fade`
`ar`	aspect-ratio	`ar--video`