atomic-css-cli

v1.2.0

Published

2 months ago

Atomic CSS generator CLI — watch files and generate atomic.min.css automatically

0High
0Medium
0Low

yoodaekyung

atomic css cli generator utility-first watch

Atomic CSS CLI

HTML 클래스명을 기반으로 CSS 규칙을 자동 생성하는 CLI 도구입니다.

사전 정의된 패턴을 인식하여 각 클래스에 대응하는 스타일을 즉시 생성함으로써 CSS 작성의 번거로움을 획기적으로 줄여줍니다. 클래스 이름이 곧 스타일 자체를 설명하기 때문에 누구나 쉽고 빠르게 클래스를 조합하여 다양한 디자인을 만들 수 있습니다.

공식 문서: atomiccss.dev
VS Code 확장: VS Code Marketplace
MCP 서버: mcp.atomiccss.dev — AI 도구 연동
MCP Registry: io.github.Yoodaekyung/atomic-css — 공식 MCP Registry 등록

어떤 프로젝트에든 바로 적용

Atomic CSS는 기존 프로젝트의 CSS를 전혀 건드리지 않고 도입할 수 있습니다.

핵심 원리: atomic.min.css를 항상 가장 마지막에 로드합니다.

CSS는 동일 선택자 우선순위일 때 나중에 선언된 스타일이 이기므로, Atomic CSS를 맨 마지막에 불러오면 기존 스타일을 자연스럽게 덮어씁니다. 기존 코드를 수정하거나 삭제할 필요 없이, HTML에 Atomic 클래스만 추가하면 됩니다.

<!-- 기존에 사용하던 CSS -->
<link rel="stylesheet" href="/css/framework.css" />
<link rel="stylesheet" href="/css/custom.css" />

<!-- Atomic CSS를 항상 가장 마지막에 → 최우선 적용 -->
<link rel="stylesheet" href="/assets/css/common/atomic.min.css" />

React, Vue 등 import 방식도 동일합니다. 항상 가장 마지막에 import하면 됩니다:

// 기존에 사용하던 스타일
import "./styles/framework.css";
import "./styles/global.css";

// Atomic CSS를 항상 가장 마지막에 import → 최우선 적용
import "./assets/css/atomic.min.css";

기존 프로젝트에 점진적으로 도입하거나, 새 프로젝트에서 처음부터 사용하거나, 자유롭게 선택할 수 있습니다. 도입 비용은 제로입니다.

설치

# 글로벌 설치 (어디서든 atomic-css 명령 사용)
npm install -g atomic-css-cli

# 또는 프로젝트 로컬 설치
npm install --save-dev atomic-css-cli

로컬 설치 시에는 npx를 붙여 실행합니다:

npx atomic-css build
npx atomic-css watch

설치 확인:

atomic-css --version

빠른 시작

1단계: 프로젝트에서 설정 파일 생성

cd my-project
atomic-css init

프로젝트 루트에 .atomic.json 파일이 생성됩니다:

{
    "selectedLanguages": ["html"],
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html"],
    "projects": []
}

2단계: HTML에 Atomic CSS 클래스 작성

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <!-- 기존 CSS가 있다면 먼저 -->
    <!-- Atomic CSS를 항상 가장 마지막에 → 최우선 적용 -->
    <link rel="stylesheet" href="/assets/css/common/atomic.min.css" />
</head>
<body>
    <div class="df jcc aic h100vh">
        <h1 class="fs3-2rem fw700 c333333">Hello Atomic CSS!</h1>
    </div>
</body>
</html>

3단계: CSS 빌드

# 일괄 빌드 (1회)
atomic-css build

실행하면 .atomic.json의 cssDirectoryPath에 atomic.min.css가 생성됩니다:

my-project/
├── index.html
├── .atomic.json
└── assets/css/common/
    └── atomic.min.css    ← 자동 생성!

4단계: 개발 중에는 워치 모드

# 파일 변경을 감지하여 CSS 자동 재생성
atomic-css watch

워치 모드는:

시작 시 초기 빌드를 자동 실행합니다
HTML 파일이 수정/추가/삭제될 때마다 자동으로 CSS를 재생성합니다
300ms 디바운스가 적용되어 연속 변경 시 불필요한 빌드를 방지합니다
Ctrl+C로 종료합니다

출력 예시:

  atomic-css watch

  Watching: /Users/you/my-project
  Extensions: .html
  Debug: OFF (atomic.min.css only)

  Initial build: 5 files, 42 classes, 42 new rules

  [14:30:15] Rebuilding... +3 rules
  [14:30:22] Rebuilding... no changes

명령어 상세

`atomic-css build [dir]`

지정된 디렉토리(기본: 현재 디렉토리)의 파일을 스캔하고 CSS를 일괄 생성합니다.

# 현재 디렉토리 빌드
atomic-css build

# 특정 디렉토리 빌드
atomic-css build src

# 출력 경로 지정
atomic-css build src -o dist/css

# 스캔할 확장자 지정 (쉼표 구분)
atomic-css build src -e html,tsx,jsx

# 디버그 모드: atomic.min.css + atomic.css(원본) 모두 생성
atomic-css build -d

# 설정 파일 경로 지정 (.atomic.json이 다른 위치에 있을 때)
atomic-css build src -c /path/to/project-root

# 옵션 조합
atomic-css build src -o dist/css -e html,tsx,jsx -d

| 옵션 | 설명 | 기본값 | | --- | --- | --- | | -o, --output <path> | CSS 출력 디렉토리 | .atomic.json의 cssDirectoryPath | | -d, --debug | 미니파이되지 않은 atomic.css도 함께 생성 | false | | -e, --extensions <exts> | 스캔할 파일 확장자 (쉼표 구분, . 생략 가능) | .atomic.json의 extensions, 그것도 없으면 .html | | -c, --config <path> | .atomic.json이 위치한 프로젝트 루트 경로 | 소스 디렉토리와 동일 | | -v, --verbose | CSS가 생성되지 않은(무효한) 클래스명을 모두 출력 | false |

확장자는 대소문자를 구분하지 않으며 앞의 .도 생략할 수 있습니다 (-e HTML,vue = -e .html,.vue). .atomic.json이 깨져 있으면 기본값으로 조용히 넘어가지 않고 에러 메시지와 함께 종료 코드 1로 실패합니다.

확장자 우선순위는 -e 옵션 > .atomic.json의 extensions > 기본값 .html 입니다. -e를 주면 .atomic.json의 extensions는 완전히 무시됩니다. 아무것도 지정하지 않으면 .html 파일만 스캔하므로, Vue/JSX/TSX/PHP 등을 쓰는 프로젝트는 반드시 둘 중 하나로 확장자를 지정해야 합니다.

`atomic-css watch [dir]`

파일 변경을 실시간으로 감지하여 CSS를 자동 재생성합니다. build와 동일한 옵션을 지원합니다.

# 현재 디렉토리 워치
atomic-css watch

# 특정 디렉토리 워치 + 출력 경로 지정
atomic-css watch src -o dist/css

# React 프로젝트 워치
atomic-css watch src -e html,tsx,jsx

# 디버그 모드 워치
atomic-css watch -d

watch에서만 추가로 제외되는 파일 (재빌드 루프 방지):

atomic.css, atomic.min.css (출력 파일)
.atomic.json (설정 파일)

스캔 제외 디렉토리

build와 watch 모두, 아래 디렉토리는 이름이 일치하면 깊이에 관계없이 스캔 대상에서 자동 제외됩니다. 의존성이나 빌드 산출물에서 남의 클래스를 주워와 잘못된 CSS가 생성되는 것을 막고, 대형 프로젝트의 스캔 속도를 유지하기 위함입니다.

| 분류 | 디렉토리 | | --- | --- | | 의존성 | node_modules | | 버전 관리 | .git, .svn, .hg | | 빌드 산출물 | dist, build, out, coverage | | 프레임워크 캐시 | .nuxt, .output, .next, .cache, .vercel, .turbo |

이 목록은 고정되어 있으며 현재 설정으로 변경할 수 없습니다. 위 이름의 디렉토리에 있는 소스를 스캔해야 한다면, 해당 디렉토리를 직접 소스 경로로 지정해 실행하세요 (예: atomic-css build dist/pages).

`atomic-css init`

현재 디렉토리에 .atomic.json 기본 설정 파일을 생성합니다. 이미 존재하면 생성하지 않습니다.

atomic-css init

설정 파일 (.atomic.json)

프로젝트 루트에 .atomic.json 파일을 생성하면 프로젝트별로 동작을 커스터마이징할 수 있습니다. 파일이 없으면 기본 설정으로 동작합니다.

옵션 상세

| 옵션 | 타입 | 기본값 | 설명 | | --- | --- | --- | --- | | cssDirectoryPath | string | "/assets/css/common/" | 생성될 CSS 파일의 저장 경로. 프로젝트 루트 기준 상대 경로 | | extensions | string[] | [".html"] | 클래스를 추출할 대상 파일 확장자 | | selectedLanguages | string[] | ["html"] | VSCode 확장 전용 옵션 (CLI에서는 미사용) | | projects | array | — | VS Code 확장 전용 옵션 (CLI에서는 미사용). 멀티프로젝트 설정. 파일 경로에 따라 서로 다른 위치에 CSS를 생성 |

프레임워크별 설정 예시

기본 HTML 프로젝트

{
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html"]
}

React / Next.js

{
    "cssDirectoryPath": "/src/assets/css/",
    "extensions": [".html", ".tsx", ".jsx"]
}

Vue / Nuxt

{
    "cssDirectoryPath": "/src/assets/css/",
    "extensions": [".html", ".vue"]
}

PHP (Laravel, WordPress 등)

{
    "cssDirectoryPath": "/public/css/",
    "extensions": [".html", ".php", ".blade.php"]
}

멀티프로젝트 (다국어/멀티 출력) — VS Code 확장 전용

주의: projects는 VS Code 확장에서만 동작합니다. CLI의 build/watch는 이 값을 읽지 않습니다.
.atomic.json에 projects를 정의해도 CLI는 이를 무시하고 언제나 단일 출력 경로(-o 옵션 또는 cssDirectoryPath) 하나에만 CSS를 생성합니다. CLI에서 출력을 분리하려면 아래처럼 디렉토리마다 명령을 나누어 실행하세요.
atomic-css build src/ko -o assets/css/ko
atomic-css build src/en -o assets/css/en

projects 배열을 사용하면 VS Code 확장이 파일 경로에 따라 CSS 출력 위치를 분리합니다. sources에 해당하는 경로의 파일은 output 경로로, 매칭되지 않는 파일은 cssDirectoryPath로 CSS가 생성됩니다.

{
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html", ".php"],
    "projects": [
        {
            "name": "korean",
            "sources": ["/src/ko/", "/pages/ko/"],
            "output": "/assets/css/ko/"
        },
        {
            "name": "english",
            "sources": ["/src/en/", "/pages/en/"],
            "output": "/assets/css/en/"
        }
    ]
}

| projects 옵션 | 타입 | 설명 | | --- | --- | --- | | name | string | 프로젝트 식별 이름 (콘솔 출력에 표시) | | sources | string[] | 이 프로젝트에 속하는 소스 디렉토리 경로 목록 | | output | string | 이 프로젝트의 CSS 출력 경로 |

init이 만들어 주는 기본 설정에도 빈 projects: []가 포함되지만, CLI만 사용한다면 이 항목은 지워도 무방합니다.

출력 파일

| 파일 | 생성 조건 | 설명 | | --- | --- | --- | | atomic.min.css | 항상 | 미니파이된 CSS (프로덕션용) | | atomic.css | -d 플래그 사용 시 | 포매팅된 CSS (디버그/확인용) |

HTML에서 연결 — 항상 모든 CSS 중 가장 마지막에 로드합니다:

<link rel="stylesheet" href="/css/기존스타일.css" />

<!-- Atomic CSS를 항상 가장 마지막에 → 최우선 적용 -->
<link rel="stylesheet" href="/assets/css/common/atomic.min.css" />

실전 워크플로우 예시

HTML 프로젝트

mkdir my-site && cd my-site
npm init -y
npm install --save-dev atomic-css-cli

# 설정 생성
npx atomic-css init

# index.html 작성 후
npx atomic-css watch

package.json에 스크립트 추가:

{
    "scripts": {
        "css": "atomic-css build",
        "css:watch": "atomic-css watch",
        "css:debug": "atomic-css build -d"
    }
}

npm run css:watch    # 개발 중
npm run css          # 배포 전 빌드

React / Next.js 프로젝트

cd my-react-app
npm install --save-dev atomic-css-cli

# .atomic.json 생성 후 수정
npx atomic-css init

.atomic.json 수정:

{
    "cssDirectoryPath": "/src/assets/css/",
    "extensions": [".html", ".tsx", ".jsx"]
}

# tsx/jsx 파일의 className에서 클래스 추출
npx atomic-css watch src -e html,tsx,jsx

CSS import (React) — 항상 가장 마지막에 import:

// src/App.tsx
import "./styles/global.css";        // 기존 스타일
import "./assets/css/atomic.min.css"; // 항상 마지막 → 최우선 적용

Vue / Nuxt 프로젝트

.atomic.json:

{
    "cssDirectoryPath": "/src/assets/css/",
    "extensions": [".html", ".vue"]
}

npx atomic-css watch src -e html,vue

CI/CD 파이프라인

# GitHub Actions 예시
- name: Generate Atomic CSS
  run: npx atomic-css-cli build src -o dist/css -e html,tsx,jsx

Node.js에서 사용하기 — CLI 전용 패키지입니다

atomic-css-cli는 커맨드라인 전용 패키지이며, 공개된 Programmatic API가 없습니다.

패키지의 진입점은 CLI 실행 파일 그 자체입니다. 따라서 require("atomic-css-cli")를 하면 아무 함수도 얻지 못할 뿐 아니라, 로드되는 순간 CLI가 실행되어 호출한 스크립트의 명령행 인자를 그대로 해석하고 종료하거나 빌드를 수행합니다.

// 이렇게 하지 마세요 — 아무것도 얻지 못하고 CLI가 실행됩니다
const api = require("atomic-css-cli");   // → CLI 도움말 출력 후 종료
console.log(Object.keys(api));           // → []  (도달하더라도 빈 객체)

Node.js 스크립트나 빌드 파이프라인에서는 CLI를 자식 프로세스로 실행하세요.

const { execFileSync } = require("node:child_process");

// 일회성 빌드
execFileSync("npx", [
    "atomic-css", "build", "./src",
    "-o", "./dist/css",
    "-e", "html,tsx,jsx"
], { stdio: "inherit" });

package.json 스크립트나 CI 단계에서 호출하는 방법은 위의 실전 워크플로우 예시와 CI/CD 파이프라인을 참고하세요.

라이브러리로 임포트해 쓰는 형태(generateCSSRules, parseClassName 등 직접 호출)는 아직 제공되지 않습니다. 필요하다면 이슈로 요청해 주세요.

왜 Atomic CSS인가?

제로 CSS 작성: 별도 CSS 파일 작성이 불필요합니다. HTML 클래스명만으로 모든 시각적 스타일을 처리합니다.
무제한 자유도: 다른 유틸리티 프레임워크와 달리 미리 정해진 값에 제한받지 않습니다. gap37px, w847px, fs1-3rem 등 어떤 수치와 단위든 자유롭게 조합할 수 있습니다.
직관적 네이밍: CSS 속성과 값의 앞글자를 조합하는 규칙 하나만 알면, 문서 없이도 대부분의 클래스명을 추론할 수 있습니다.
14단계 반응형: QHD(2560px)부터 Ultra Small(420px)까지 14개 브레이크포인트를 지원하여 세밀한 반응형 대응이 가능합니다.
39개 의사 클래스: hover, focus, 구조 의사클래스(first-child), nth-child(2n+1)까지 프리픽스 방식으로 적용합니다.
그라디언트·애니메이션·Emmet 관계체인: bglg-45deg-..., anfadeIn-2s, child-li-nth-child-2-dn 등 고급 패턴을 지원합니다.
협업 효율: HTML에서 바로 디자인 변경 및 조정이 가능하여, CSS 파일을 오가며 작업하는 시간이 대폭 줄어듭니다.
제로 의존성: 외부 CSS 라이브러리 없이 사용 가능합니다.
모든 프로젝트에 적용: 어떤 CSS를 사용하고 있든, 마지막에 로드하는 것만으로 즉시 사용 가능합니다.
스타일 일관성: 전체 프로젝트에 걸쳐 동일한 유틸리티 클래스를 사용하므로 스타일의 일관성이 자연스럽게 유지됩니다.

핵심 컨셉

CSS 속성과 값의 앞글자를 조합하여 클래스명을 만듭니다.

display: flex           → df
justify-content: center → jcc
align-items: center     → aic
flex-direction: column  → fdc
white-space: nowrap     → wsn
text-overflow: ellipsis → toe
object-fit: cover       → ofc

이 규칙만 알면 문서에 없는 속성도 추론할 수 있습니다.

<div class="df jcc aic gap2rem p2rem bgFFFFFF br8px">Hello Atomic CSS!</div>

생성되는 CSS:

.df {
    display: flex;
}
.jcc {
    justify-content: center;
}
.aic {
    align-items: center;
}
.gap2rem {
    gap: 2rem;
}
.p2rem {
    padding: 2rem;
}
.bgFFFFFF {
    background-color: #ffffff;
}
.br8px {
    border-radius: 8px;
}

네이밍 규칙

단위

| 단위 | 표기 | 예시 | | --- | --- | --- | | px | px | w100px, gap8px | | % | p | w50p → width: 50% | | rem / em | rem, em | fs1-5rem → font-size: 1.5rem | | vh / vw / vmin / vmax | vh, vw, vmin, vmax | h100vh, w50vmin | | 뷰포트 변형 | svh, lvh, dvh, vi, vb … | h100dvh | | 컨테이너 쿼리 | cqw, cqh, cqi, cqb … | w50cqi | | 절대 | cm, mm, in, pt, pc, q | w10cm | | 폰트 상대 | ch, ex, lh, rlh, cap, ic … | w20ch | | fr | fr | gtc1fr-2fr |

CSS의 모든 단위 사용 가능 — 소문자만(w10q, w10Q 아님). 0이 아닌 길이값은 단위 필수(w100 무효, w100px 유효).
html { font-size: 10px } 기준: 1rem = 10px → 2rem = 20px, 10rem = 100px

하이픈(-) 사용

| 용도 | 예시 | 결과 | | --- | --- | --- | | 소수점 | gap1-5rem | 1.5rem | | 값 구분 | gtc1fr-2fr-1fr | 1fr 2fr 1fr | | 미디어 쿼리 | sm-dn | @media(max-width:768px) | | 의사 클래스 | hover-bg000000 | :hover |

특수 표기

| 표기 | 설명 | 예시 | 결과 | | --- | --- | --- | --- | | i 접미사 | !important | w100pxi | width: 100px !important | | neg- 접두사 | 음수값 | neg-mt10px | margin-top: -10px (허용: margin, top/right/bottom/left, inset, letter-spacing, word-spacing, text-indent, outline-offset, grid-column/row-start·end, scroll-margin, z-index, order, transform. 그 외는 원천 차단) |

Display

| 클래스 | CSS | | --- | --- | | df | display: flex | | dif | display: inline-flex | | dg | display: grid | | db | display: block | | dib | display: inline-block | | di | display: inline | | dn | display: none | | dt | display: table | | dtc | display: table-cell |

Flexbox

| 클래스 | CSS | | --- | --- | | fdr / fdrr | flex-direction: row / row-reverse | | fdc / fdcr | flex-direction: column / column-reverse | | fwn / fww / fwr | flex-wrap: nowrap / wrap / wrap-reverse | | jcfs / jcfe / jcc | justify-content: flex-start / flex-end / center | | jcsb / jcsa / jcse | justify-content: space-between / space-around / space-evenly | | ais / aifs / aife / aic | align-items: stretch / flex-start / flex-end / center | | fs0 / fs1 | flex-shrink: 0 / 1 | | fg1 / fg2 | flex-grow: 1 / 2 | | fba | flex-basis: auto | | fb200px / fb50p | flex-basis: 200px / 50% | | flex1-1-auto | flex: 1 1 auto | | fa / fi | flex: auto / initial |

Grid

| 패턴 | 예시 | CSS | | --- | --- | --- | | 직접 지정 | gtc1fr-2fr-1fr | grid-template-columns: 1fr 2fr 1fr | | repeat | gtcr3-1fr | repeat(3, 1fr) | | auto-fit | gtcrfit-minmax28rem-1fr | repeat(auto-fit, minmax(28rem, 1fr)) | | auto-fill | gtcrfill-minmax250px-1fr | repeat(auto-fill, minmax(250px, 1fr)) | | rows | gtrauto-1fr-auto | grid-template-rows: auto 1fr auto | | rows repeat | gtrr3-1fr | repeat(3, 1fr) | | minmax | gtcminmax100px-1fr | minmax(100px, 1fr) | | calc | gtccalc100p-200px-1fr | calc(100% - 200px) 1fr |

calc (사칙연산)

모든 단위 속성(width, height, margin, padding, top, left 등)에서 calc()를 사용할 수 있습니다.

| 패턴 | 예시 | CSS | | --- | --- | --- | | 빼기 (기본) | wcalc100p-200px | width: calc(100% - 200px) | | 더하기 | wcalc-add50p-100px | width: calc(50% + 100px) | | 곱하기 | wcalc-mul2rem-3 | width: calc(2rem * 3) | | 나누기 | wcalc-div100p-3 | width: calc(100% / 3) | | 높이 | hcalc100vh-6rem | height: calc(100vh - 60px) |

Spacing

| 패턴 | 속성 | | --- | --- | | m, mt, mr, mb, ml | margin (방향) | | p, pt, pr, pb, pl | padding (방향) | | gap, rg, cg | gap, row-gap, column-gap | | mta, mra, mba, mla | margin-방향: auto | | p10px-20px | padding shorthand (2~4값) |

간격값은 4의 배수 권장: 4px, 8px, 12px, 16px, 2rem, 2-4rem...

Shorthand 분해: p, m, gap, bw 같은 shorthand는 내부적으로 longhand(방향별)로 분해됩니다. 따라서 p20px pl10px처럼 전체 패딩 + 특정 방향 덮어쓰기가 순서 상관없이 정확히 동작합니다.
Multi-value shorthand도 CSS 규칙에 따라 분해됩니다:
2값: p10px-20px → top/bottom: 10px, right/left: 20px
3값: p10px-20px-30px → top: 10px, right/left: 20px, bottom: 30px
4값: p10px-20px-30px-40px → top: 10px, right: 20px, bottom: 30px, left: 40px
m, gap(2값), bw도 동일하게 분해됩니다.
따라서 p10px-20px pl5px처럼 multi-value + 개별 방향 덮어쓰기도 정확히 동작합니다.

Color

| 패턴 | 예시 | CSS | | --- | --- | --- | | c + HEX 6자리 | cFFFFFF | color: #FFFFFF | | bg + HEX 6자리 | bg000000 | background-color: #000000 | | bc + HEX 6자리 | bcDDDDDD | border-color: #DDDDDD | | RGBA | c255-0-0-50 | color: rgba(255,0,0,0.5) | | RGBA 배경 | bg0-0-0-80 | background-color: rgba(0,0,0,0.8) | | Opacity | o50, o80 | opacity: 0.5, opacity: 0.8 |

소문자 HEX 입력 시 자동 대문자 변환: cffffff → cFFFFFF

CSS 변수 (Custom Property)

프리픽스 + -- + 변수명 패턴으로 CSS 변수(var())를 사용할 수 있습니다.

| 분류 | 예시 | CSS | | --- | --- | --- | | 색상 | bg--primary, c--text | background-color: var(--primary) | | 크기 | w--sidebar, h--header | width: var(--sidebar) | | 간격 | gap--space, p--padding | shorthand 분해 (4방향) | | 타이포 | fs--size, fw--bold | font-size: var(--size) | | 테두리 | br--radius, bc--color | border-radius: var(--radius) | | 기타 | zi--modal, fill--icon | z-index: var(--modal) |

조합: 미디어(md-bg--x), 의사클래스(hover-bg--x), !important(bg--xi), before/after(before-bg--x), 관계선택자(child-div-bg--x) 모두 지원

<div class="bg--surface-primary c--text-primary gap--spacing br--radius">
<button class="bg--primary hover-bg--accent md-hover-c--accenti">

Border

| 패턴 | 예시 | CSS | | --- | --- | --- | | 단축 | b1pxsolidDDDDDD | border: 1px solid #DDDDDD | | 방향 | bt2pxdashed000000 | border-top: 2px dashed #000000 | | 스타일 | solid, dashed, dotted, double, groove, ridge, inset, outset | | radius | br8px, br0, br50p | border-radius | | none | bn | border: none | | 방향 제거 | bt0, brn, bb0, bl0 | border-방향: 0 (brn = border-right:0) |

Shadow

| 패턴 | 예시 | CSS | | --- | --- | --- | | Box Shadow (HEX) | bs2px4px10px0pxFF0000 | box-shadow: 2px 4px 10px 0px #FF0000 | | Box Shadow (RGBA) | bs0px4px12px0px0-0-0-10 | box-shadow: 0px 4px 12px 0px rgba(0,0,0,0.1) | | Inset | bsi0px2px4px0px000000 | box-shadow: inset 0px 2px 4px 0px #000000 | | Text Shadow | ts2px-2px-4px-DDDDDD | text-shadow: 2px 2px 4px #DDDDDD (하이픈 구분) | | Text Shadow RGBA | ts0px-0px-8px-0-0-0-50 | text-shadow: 0px 0px 8px rgba(0,0,0,0.5) | | None | bsn | box-shadow: none |

Transform

| 클래스 | CSS | | --- | --- | | ttx10px | transform: translateX(10px) | | tty2-5rem | transform: translateY(2.5rem) | | neg-ttx50p | transform: translateX(-50%) | | tr45deg | transform: rotate(45deg) | | neg-tr90deg | transform: rotate(-90deg) | | ts1-5 | transform: scale(1.5) | | ts1-5_2 | transform: scale(1.5, 2) |

Transition

| 클래스 | CSS | | --- | --- | | tall200msease | transition: all 200ms ease | | tall300ms | transition: all 300ms | | topacity500ms | transition: opacity 500ms | | tall200mscb0-50-50-100 | transition: all 200ms cubic-bezier(...) | | tnone | transition: none |

Filter

| 클래스 | CSS | | --- | --- | | filterb5px | filter: blur(5px) | | filterbr120p | filter: brightness(120%) | | filterc80p | filter: contrast(80%) | | filterg100p | filter: grayscale(100%) | | filterhr90deg | filter: hue-rotate(90deg) | | filteri100p | filter: invert(100%) | | filtero80p | filter: opacity(80%) | | filtersa150p | filter: saturate(150%) | | filters50p | filter: sepia(50%) | | filterds2px4px8pxFF0000 | filter: drop-shadow(2px 4px 8px #FF0000) | | filtern | filter: none | | filterinh | filter: inherit | | filterinit | filter: initial | | filteru | filter: unset |

Backdrop Filter

| 클래스 | CSS | | --- | --- | | bfb10px | backdrop-filter: blur(10px) | | bfbr120p | backdrop-filter: brightness(120%) | | bfc80p | backdrop-filter: contrast(80%) | | bfn | backdrop-filter: none |

그라디언트 (Gradient)

background 그라디언트 3종. 색상은 hex6 / rgba / transparent (2개 이상 필요).

| 종류 | 예시 | CSS | | --- | --- | --- | | linear | bglg-45deg-FF0000-0000FF | linear-gradient(45deg, #FF0000, #0000FF) | | linear (방향 키워드) | bglg-to-r-FF0000-00FF00 | linear-gradient(to right, ...) | | radial | bgrg-circle-FF0000-0000FF | radial-gradient(circle, ...) | | conic | bgcg-from-90deg-FF0000-0000FF | conic-gradient(from 90deg, ...) |

방향(선택): 각도(45deg/90grad/1-5rad/0-5turn) 또는 to-t/to-r/to-b/to-l/to-tr/to-tl/to-br/to-bl.

애니메이션 (Animation)

an<name>-<duration>[-<timing>][-<delay>][-<iteration>][-<fill>]. 프리셋 name은 @keyframes 자동 주입.

| 클래스 | CSS | | --- | --- | | anfadeIn-2s | animation: fadeIn 2s (+ @keyframes fadeIn) | | anspinCW-2s-linear-infinite | animation: spinCW 2s linear infinite | | anslideUp-1s-easein | animation: slideUp 1s ease-in (컴팩트 타이밍) | | anbounce-2s-3 | animation: bounce 2s 3 |

timing: ease/linear/ease-in/ease-out/ease-in-out/step-start/step-end, 또는 컴팩트 easein/easeout/easeinout/stepstart/stepend
프리셋 17종: fadeIn, fadeOut, slideUp/Down/Left/Right, zoomIn/Out, spinCW/CCW, bounce, pulse, shake, flip, swing, rubberBand, blink. 커스텀 name도 가능(@keyframes 직접 정의 필요).

미디어 쿼리 (14개 Breakpoint)

모든 클래스에 프리픽스를 붙여 반응형 적용:

| 프리픽스 | Breakpoint | | 프리픽스 | Breakpoint | | --- | --- | --- | --- | --- | | qh- | 2560px | | rg- | 1080px | | uh- | 2160px | | md- | 1024px | | kk- | 2048px | | sm- | 768px | | fh- | 1920px | | es- | 640px | | hl- | 1800px | | us- | 420px | | sl- | 1700px | | | | | ul- | 1600px | | | | | el- | 1440px | | | | | lg- | 1280px | | | |

<!-- 3열 → 2열 → 1열 반응형 -->
<div class="dg gtcr3-1fr md-gtcr2-1fr sm-gtc1fr gap2rem">
    <!-- 반응형 숨김 -->
    <div class="db sm-dn">데스크탑만</div>
    <div class="dn sm-db">모바일만</div>
</div>

Pseudo Class (39개)

모든 클래스에 프리픽스를 붙여 상태별 스타일 적용:

| 카테고리 | 프리픽스 | | --- | --- | | 인터랙션 | hover-, focus-, active-, focus-within-, focus-visible- | | 입력 상태 | disabled-, enabled-, checked-, indeterminate- | | 폼 검증 | valid-, invalid-, required-, optional-, in-range-, out-of-range- | | 링크 | link-, visited-, any-link-, target- | | 구조 | first-child-, last-child-, only-child-, first-of-type-, last-of-type-, only-of-type-, root- | | 기타 | placeholder-shown-, empty-, read-only-, fullscreen-, autofill-, modal- 등 |

<button class="bg007BFF hover-bg0056B3 active-ts0_98 disabled-o50 tall200msease cp">버튼</button>

nth 인자형 의사클래스

nth-child / nth-last-child / nth-of-type / nth-last-of-type — 인자: 정수, odd, even, An(2n), An+B(2n1 → 2n+1).

| 클래스 | CSS | | --- | --- | | nth-child-2-dn | :nth-child(2) { display: none } | | nth-child-odd-bg000000 | :nth-child(odd) | | nth-child-2n1-mt10px | :nth-child(2n+1) | | nth-of-type-3-fw700 | :nth-of-type(3) |

Pseudo Element

| 키워드 | CSS | | --- | --- | | before | ::before | | after | ::after |

관계 선택자

결합자 4종 · 사용 형태 3가지:

| 결합자 | 키워드 | CSS | | --- | --- | --- | | > 직접 자식 | child | > target | | 모든 자손 | children | target | | + 인접 형제 | next | + target | | ~ 일반 형제 | siblings | ~ target |

① 단독 — 자기 하위/형제에 직접 적용:

child-li-mt10px        →  .x > li { margin-top: 10px }
children-div-bgFF0000  →  .x div { background-color: #FF0000 }

② 트리거형 — 본인에 의사클래스, 하위에 스타일:

card-hover-child-img-ofc  →  .card:hover > img { object-fit: cover }

③ Emmet 스타일 체인 — 좌→우로 읽어 의사클래스/nth가 대상 요소에 귀속(ul>li:nth-child(2)처럼). 선행 의사클래스는 본인에 귀속:

child-li-hover-bg000000        →  .x > li:hover { ... }
child-li-nth-child-2-dn        →  .x > li:nth-child(2) { display: none }   (리스트의 N번째)
child-li-first-child-mt0       →  .x > li:first-child { margin-top: 0 }
nth-child-2-child-li-dn        →  .x:nth-child(2) > li { ... }   (선행 nth = 본인)
child-ul-child-li-c000000      →  .x > ul > li { ... }   (다중 체인)
child-li-hover-after-c000000   →  .x > li:hover::after { ... }   (+ 의사요소)

<!-- card에 hover 시 자식 img에 scale 적용 -->
<div class="card-hover-child-img-ts1-1"></div>

기타 클래스

| 클래스 | CSS | | --- | --- | | ar16-9 | aspect-ratio: 16/9 | | lc3-1-5rem | 3줄 제한 (line-clamp) | | fw100~fw900 | font-weight | | zi10, zi999 | z-index | | w100p, h100vh | width: 100%, height: 100vh | | wa, ha | width: auto, height: auto | | mxa | margin-left: auto; margin-right: auto | | cp | cursor: pointer | | usn | user-select: none | | pen | pointer-events: none | | oh | overflow: hidden | | toe | text-overflow: ellipsis |

키워드 클래스

값이 정해진 CSS 속성은 속성 약어 + 값 약어 형태의 키워드 클래스로 제공됩니다. 아래는 대표값이며, 각 속성의 전체 값 목록은 공식 문서에서 확인하세요.

| 속성 | 클래스 예시 | | --- | --- | | text-align | tal left, tac center, tar right, taj justify, tas start, tae end | | white-space | wsn nowrap, wsnorm normal, wsp pre, wspl pre-line, wspw pre-wrap, wsbs break-spaces | | cursor | cp pointer, cd default, cm move, ct text, cna not-allowed, cgrb grab, cgrbg grabbing, czi zoom-in, czo zoom-out, cpr progress, cch crosshair, chelp help, ccp copy | | object-fit | ofc cover, ofct contain, off fill, ofn none, ofsd scale-down | | object-position | opc center, opt top, opb bottom, opl left, opr right | | background-size | bsc cover, bsct contain, bsa auto | | border-style | bss solid, bsd dashed, bsdt dotted, bsdb double, bsh hidden, bsnone none | | list-style-type | lsn none, lsd disc, lsc circle, lssq square, lsde decimal, lsla lower-alpha, lslr lower-roman | | mix-blend-mode | mbmn normal, mbmm multiply, mbms screen, mbmo overlay, mbmd darken, mbml lighten, mbmlu luminosity | | background-blend-mode | bbmn normal, bbmm multiply, bbms screen, bbmo overlay, bbmlu luminosity | | will-change | wca auto, wct transform, wco opacity, wcsp scroll-position, wcc contents | | touch-action | taa auto, tan none, tapx pan-x, tapy pan-y, tam manipulation, tapz pinch-zoom | | appearance | appn none, appa auto |

키워드 클래스도 미디어 쿼리·의사클래스 접두사와 자유롭게 조합됩니다 — md-tac, hover-cp, sm-wsnorm.

실전 예제

Flexbox 센터 정렬

<div class="df jcc aic gap2rem p2rem">
    <span>센터 정렬된 콘텐츠</span>
</div>

반응형 그리드 카드

<div class="dg gtcrfit-minmax28rem-1fr gap2rem p2rem">
    <div class="bgFFFFFF br8px p2rem bs0px4px12px0px0-0-0-10">카드 1</div>
    <div class="bgFFFFFF br8px p2rem bs0px4px12px0px0-0-0-10">카드 2</div>
    <div class="bgFFFFFF br8px p2rem bs0px4px12px0px0-0-0-10">카드 3</div>
</div>

글래스모피즘

<div class="bfb10px bg255-255-255-20 br16px p2-4rem">
    <h2 class="fs2-4rem fw700 mb16px cFFFFFF">제목</h2>
    <p class="fs1-6rem lh1-6 c255-255-255-80">내용</p>
</div>

호버 버튼

<button
    class="
    p12px-2-4rem bg007BFF cFFFFFF br8px fs1-6rem fw600
    cp tall200msease hover-bg0056B3 active-ts0_98
    md-p8px-2rem md-fs1-4rem
"
>
    클릭하세요
</button>

풀스크린 레이아웃

<div class="dg gtrauto-1fr-auto h100vh">
    <header class="p16px bg000000 cFFFFFF">헤더</header>
    <main class="p2rem oa">콘텐츠</main>
    <footer class="p16px bgF0F0F0">푸터</footer>
</div>

사이드바 레이아웃

<div class="dg gtc25rem-1fr gap2rem md-gtc1fr">
    <aside class="p2rem bgF5F5F5 md-order2">사이드바</aside>
    <main class="p2rem md-order1">콘텐츠</main>
</div>

텍스트 말줄임

<p class="lc3-1-5rem">이 텍스트는 3줄까지만 표시되고 나머지는 ...으로 말줄임 처리됩니다.</p>

AI Integration — MCP Server

AI가 Atomic CSS를 완벽하게 이해합니다.

Atomic CSS는 AI 코딩 도구를 위한 전용 MCP(Model Context Protocol) 서버를 제공합니다. AI가 Atomic CSS의 모든 클래스 체계를 실시간으로 조회하고, 검색하고, 생성할 수 있도록 설계된 AI 전용 인터페이스입니다.

제공 도구 (6개)

| 도구 | 설명 | 예시 입력 | | --- | --- | --- | | get_guide | 전체 규칙 가이드 반환 (AI 온보딩) | 처음 1회 호출하면 즉시 학습 | | css_to_classes | CSS → Atomic 클래스 변환 | display: flex; gap: 20px; | | validate_classes | 클래스 유효성 검증 + 유사 클래스 추천 | df jcc aic xyz | | lookup_class | 클래스명 → CSS 변환 결과 조회 | df jcc aic gap2rem | | search_by_css | CSS 속성/값으로 클래스 역검색 | justify-content, hidden | | list_classes | 카테고리별 전체 클래스 목록 | flexbox, grid, pseudo, nth, gradient, animation, relation |

설정 방법

프로젝트 루트에 .mcp.json 파일을 생성하면 설정 없이 즉시 연동됩니다:

{
    "mcpServers": {
        "atomic-css": {
            "type": "sse",
            "url": "https://mcp.atomiccss.dev/sse"
        }
    }
}

| AI 도구 | 설정 파일 | 비고 | | --- | --- | --- | | Claude Code | .mcp.json | 프로젝트 루트에 배치 | | Cursor | .cursor/mcp.json | SSE 타입 지원 | | Windsurf | .windsurf/mcp.json | SSE 타입 지원 |

문서 및 링크

| | 링크 | 설명 | | --- | --- | --- | | Web | atomiccss.dev | 공식 문서 — 전체 클래스 레퍼런스, 실시간 미리보기 | | MCP | mcp.atomiccss.dev | AI 전용 MCP 서버 — Claude, Cursor 등에서 즉시 연동 | | Marketplace | VS Code Marketplace | VSCode 확장 설치 (호버, 자동완성, 색상 프리뷰, 진단, Quick Fix, 디자인 토큰, CSS 변수 자동완성 등 12개 IDE 기능 포함) | | npm | atomic-css-cli | npm 패키지 |

지원 및 문의

[email protected]