AAtomic CSS

설치 및 사용 가이드

Atomic CSS는 두 가지 방법으로 사용할 수 있습니다. VS Code 확장은 에디터 안에서 자동완성과 실시간 CSS 생성을 제공하고, NPM CLI는 에디터와 무관하게 터미널에서 CSS를 생성합니다.

VS Code 확장

에디터에서 바로 사용. 자동완성, 호버 프리뷰, 실시간 CSS 파일 생성까지 한 번에.

  • ✓ 클래스명 자동완성 + CSS 프리뷰
  • ✓ 호버 시 CSS 출력 확인
  • ✓ 파일 저장 시 자동 CSS 생성
  • ✓ 유효하지 않은 클래스 경고

NPM CLI

터미널에서 실행. VS Code 없이도 CSS 생성 가능. CI/CD 파이프라인 연동에 적합.

  • ✓ 에디터 독립적 — 어디서든 실행
  • ✓ build / watch 모드 지원
  • ✓ CI/CD 빌드 파이프라인 연동
  • ✓ 설정 파일(.atomic.json)로 관리

VS Code 확장

Visual Studio Code 마켓플레이스에서 설치하면 바로 사용할 수 있습니다. 빌드 과정이나 추가 설정이 필요 없습니다.

Marketplace: https://marketplace.visualstudio.com/items?itemName=Drangon-Knight.atomicss

1. 설치

마켓플레이스에서 설치

  1. VS Code를 엽니다
  2. 확장(Ctrl+Shift+X)으로 이동합니다
  3. "Atomic CSS"를 검색합니다 (게시자: Drangon-Knight)
  4. Install을 클릭합니다

터미널에서 설치

code --install-extension Drangon-Knight.atomicss

설치 확인

설치 후, 아무 HTML 파일을 열고 class="" 속성 안에 입력해보세요. 자동완성 목록과 CSS 프리뷰가 나타나면 정상입니다.

2. 주요 기능

자동완성

class="" 속성에 입력하면 CSS 출력과 함께 실시간 클래스 제안을 받습니다.

호버 프리뷰

클래스명 위에 마우스를 올리면 생성되는 CSS를 툴팁으로 확인합니다.

실시간 CSS 생성

파일을 저장하거나 편집하면 atomic.css와 atomic.min.css가 자동으로 생성/업데이트됩니다.

유효성 검사

잘못된 클래스명은 Output 패널에 경고가 표시되며, 상태바에서 업데이트 결과를 확인할 수 있습니다.

지원 파일 형식

HTML, Vue (.vue), React/JSX (.jsx / .tsx), Svelte (.svelte), PHP, JSP, Twig 등 class 속성을 사용하는 모든 파일.

3. 동작 방식

VS Code 확장은 파일을 저장하거나 편집할 때마다 HTML 내의 class 속성을 스캔하여 CSS 파일을 자동으로 생성합니다.

1HTML 파일에서 class="df jcc aic" 작성
2확장이 클래스명을 파싱하여 CSS 규칙 생성
3지정된 경로에 atomic.css + atomic.min.css 자동 저장
✓HTML에서 <link rel="stylesheet" href="atomic.min.css">로 연결

4. 설정

VS Code 설정 (Settings)

Ctrl+,를 눌러 Settings를 열고 "atomic"을 검색하면 두 가지 설정이 나타납니다:

설정기본값설명
atomic.cssDirectoryPath/assets/css/commonCSS 파일이 저장될 디렉토리 경로
atomic.selectedLanguages["html"]CSS 생성을 트리거할 파일 언어 목록
settings.json (VS Code)
{
    "atomic.cssDirectoryPath": "/assets/css/common",
    "atomic.selectedLanguages": ["html", "vue", "php", "jsp"]
}

프로젝트 설정 파일 (.atomic.json)

프로젝트 루트에 .atomic.json을 생성하면 VS Code 설정보다 우선 적용됩니다. 팀 프로젝트에서 설정을 공유할 때 유용합니다.

.atomic.json
{
    "selectedLanguages": ["html"],
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html"],
    "projects": []
}
속성타입설명
selectedLanguagesstring[]CSS 생성을 트리거할 파일 언어 (예: html, vue, php)
cssDirectoryPathstringCSS 파일이 저장될 디렉토리 경로 (프로젝트 루트 기준)
extensionsstring[]스캔할 파일 확장자 (예: .html, .vue, .jsx)
projectsobject[]멀티 프로젝트 설정 (폴더별 다른 출력 경로)

멀티 프로젝트 설정

하나의 워크스페이스에서 여러 프로젝트를 관리할 때, projects 배열로 폴더별 다른 CSS 출력 경로를 지정할 수 있습니다.

.atomic.json
{
    "selectedLanguages": ["html", "vue", "jsp"],
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html", ".vue", ".jsp"],
    "projects": [
        {
            "name": "admin",
            "sources": ["/admin/"],
            "output": "/admin/assets/css/"
        },
        {
            "name": "front",
            "sources": ["/front/"],
            "output": "/front/assets/css/"
        }
    ]
}

동작: /admin/pages/login.html을 수정하면 /admin/assets/css/에 CSS가 생성되고, /front/ 하위 파일은 /front/assets/css/에 각각 독립적으로 생성됩니다.

5. 명령어 & 단축키

Ctrl+Shift+P를 눌러 명령어 팔레트에서 실행하거나, 단축키로 바로 사용할 수 있습니다:

명령어단축키설명
Atomic CSS: Search ClassCtrl+Shift+A
Mac: Cmd+Shift+A		CSS 속성명으로 Atomic CSS 클래스를 검색합니다. 예: "justify-content"를 검색하면 jcc, jcsb 등 관련 클래스 목록이 나타납니다.
Atomic CSS: Update AllCtrl+Alt+A
Mac: Cmd+Alt+A		프로젝트 전체 파일을 스캔하여 CSS를 일괄 생성합니다. 초기 설정이나 대량 파일 처리 시 유용합니다.

참고: 일반적으로 명령어를 직접 실행할 필요는 없습니다. 파일을 저장하면 자동으로 CSS가 업데이트됩니다. Ctrl+Shift+A는 클래스명이 기억나지 않을 때 빠르게 검색할 수 있어 자주 사용합니다.

NPM CLI (atomic-css-cli)

VS Code 없이도 터미널에서 Atomic CSS를 생성할 수 있는 CLI 도구입니다. 빌드 서버, CI/CD 파이프라인, 또는 VS Code 외의 에디터(WebStorm, Vim 등)에서 작업할 때 사용합니다.

NPM: https://www.npmjs.com/package/atomic-css-cli

1. 설치

글로벌 설치 (권장)

어디서든 atomic-css 명령어를 사용할 수 있습니다:

npm install -g atomic-css-cli

프로젝트 로컬 설치

프로젝트 의존성으로 설치하여 package.json 스크립트에서 사용:

npm install --save-dev atomic-css-cli

설치 확인

atomic-css --version

2. build — 일회성 CSS 생성

지정한 디렉토리를 재귀적으로 스캔하여 모든 HTML/Vue/JSX 파일에서 Atomic CSS 클래스를 추출하고, CSS 파일을 한 번 생성합니다.

# 현재 디렉토리를 스캔하여 CSS 생성
atomic-css build .

옵션

옵션축약설명
--output <path>-oCSS 출력 디렉토리 경로. 미지정 시 .atomic.json의 cssDirectoryPath 사용
--extensions <exts>-e스캔할 파일 확장자를 쉼표로 구분 (예: html,vue,jsx)
--debug-datomic.css(포맷된 버전)도 함께 생성
--config <path>-c.atomic.json 파일이 있는 프로젝트 루트 경로

사용 예시

# 기본: 현재 디렉토리 스캔, 기본 경로에 CSS 생성
atomic-css build .

# src 폴더를 스캔하여 ./css 폴더에 출력
atomic-css build ./src -o ./css

# html, vue, jsx 파일만 스캔
atomic-css build . -e html,vue,jsx

# 디버그 모드: atomic.css도 함께 생성 (포맷된 버전)
atomic-css build . --debug

# 프로젝트 루트의 .atomic.json 설정을 사용하여 빌드
atomic-css build ./src -c ./

# 모든 옵션 조합
atomic-css build ./src -o ./assets/css -e html,vue,jsx -d -c ./

출력 결과

build 완료 시 두 파일이 생성됩니다:

파일설명
atomic.css포맷된 CSS (디버깅용, --debug 옵션 시에만 생성)
atomic.min.css압축된 CSS (배포용, 항상 생성)

3. watch — 실시간 감시 모드

파일 변경을 실시간으로 감지하여 자동으로 CSS를 재생성합니다. 개발 중에 터미널 하나를 띄워놓으면 VS Code 확장과 동일한 경험을 제공합니다.

# 현재 디렉토리를 감시하여 변경 시 자동 CSS 생성
atomic-css watch .

종료: Ctrl+C를 누르면 watch 모드가 종료됩니다.

사용 예시

# 기본: 현재 디렉토리 감시
atomic-css watch .

# src 폴더를 감시하여 ./css 폴더에 출력
atomic-css watch ./src -o ./css

# 특정 확장자만 감시
atomic-css watch . -e html,vue,jsx

# 디버그 모드 + 커스텀 출력 경로
atomic-css watch . -o ./assets/css --debug

build vs watch: build는 한 번 실행 후 종료, watch는 파일 변경을 계속 감시합니다. 개발 중에는 watch, 빌드 파이프라인에서는 build를 사용하세요.

4. init — 설정 파일 생성

프로젝트 루트에 기본 .atomic.json 설정 파일을 생성합니다.

# 프로젝트 루트에서 실행
atomic-css init

# → .atomic.json 파일 생성

생성되는 기본 설정:

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

5. package.json 스크립트 연동

프로젝트에 로컬 설치한 경우, package.json의 scripts에 등록하면 편리합니다:

package.json
{
    "scripts": {
        "css": "atomic-css watch ./src -o ./assets/css",
        "css:build": "atomic-css build ./src -o ./assets/css",
        "dev": "npm run css & your-dev-server",
        "build": "npm run css:build && your-build-command"
    }
}

이후 다음과 같이 실행합니다:

# 개발 중: watch 모드 실행
npm run css

# 빌드 시: 일회성 CSS 생성
npm run css:build

6. CI/CD 파이프라인 연동

빌드 서버에서 CSS를 자동 생성하려면 빌드 단계에 atomic-css build를 추가합니다:

GitHub Actions 예시
# .github/workflows/build.yml
name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - run: npm install
      - run: npx atomic-css build ./src -o ./assets/css
      - run: npm run build  # 이후 프로젝트 빌드

기본 HTML 설정

어떤 방법을 선택하든, HTML에서 정확한 rem 계산을 위해 루트 폰트 크기를 10px로 설정합니다:

index.html
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Project</title>
    <style>html { font-size: 10px; }</style>
    <link rel="stylesheet" href="./assets/css/common/atomic.min.css">
</head>
<body>
    <div class="df jcc aic h100vh">
        <h1 class="fs4-8rem fw900 c333333">Hello Atomic CSS</h1>
    </div>
</body>
</html>

위 클래스들이 생성하는 CSS:

클래스생성 CSS
dfdisplay: flex
jccjustify-content: center
aicalign-items: center
h100vhheight: 100vh
fs4-8remfont-size: 4.8rem
fw900font-weight: 900
c333333color: #333333

rem 규칙: html { font-size: 10px } 설정 시, 1rem = 10px. 따라서 4.8rem = 48px, 2rem = 20px.

프레임워크 연동

Atomic CSS는 어떤 프레임워크에서든 사용 가능합니다 — CSS 클래스명일 뿐입니다.

Vue / Nuxt

<template>
    <div class="df fdc gap2rem p2-4rem maxw80rem mxa">
        <h1 class="fs3-2rem fw800">{{ title }}</h1>
        <p class="fs16px c71717A">{{ description }}</p>
    </div>
</template>

React / Next.js

export default function App() {
    return (
        <div className="df fdc gap2rem p2-4rem maxw80rem mxa">
            <h1 className="fs3-2rem fw800">{title}</h1>
            <p className="fs16px c71717A">{description}</p>
        </div>
    );
}

Svelte

<div class="df fdc gap2rem p2-4rem maxw80rem mxa">
    <h1 class="fs3-2rem fw800">{title}</h1>
    <p class="fs16px c71717A">{description}</p>
</div>

PHP / JSP

<div class="df fdc gap2rem p2-4rem maxw80rem mxa">
    <h1 class="fs3-2rem fw800">{title}</h1>
    <p class="fs16px c71717A">{description}</p>
</div>

다음 단계

설치가 완료되었습니다. 더 자세한 사용법은 아래 문서를 참고하세요.

빠른 시작네이밍 규칙단위 시스템반응형 디자인DisplayFlexbox