npm - atomic-css-cli - Versions diffs - 1.0.1 → 1.0.3 - Mend

atomic-css-cli 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -6,144 +6,218 @@ HTML 클래스명을 기반으로 CSS 규칙을 자동 생성하는 CLI 도구
 > **VSCode 확장도 있습니다**: [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Drangon-Knight.atomicss)에서 설치하면 파일 저장 시 자동으로 CSS가 생성됩니다.
-## 왜 Atomic CSS인가?
+## 어떤 프로젝트에든 바로 적용
-- **제로 CSS 작성**: 별도 CSS 파일 작성이 불필요합니다. HTML 클래스명만으로 모든 시각적 스타일을 처리합니다.
-- **무제한 자유도**: 다른 유틸리티 프레임워크와 달리 미리 정해진 값에 제한받지 않습니다. `gap37px`, `w847px`, `fs1-3rem` 등 어떤 수치와 단위든 자유롭게 조합할 수 있습니다.
-- **직관적 네이밍**: CSS 속성과 값의 앞글자를 조합하는 규칙 하나만 알면, 문서 없이도 대부분의 클래스명을 추론할 수 있습니다.
-- **14단계 반응형**: QHD(2560px)부터 Ultra Small(420px)까지 14개 브레이크포인트를 지원하여 세밀한 반응형 대응이 가능합니다.
-- **32개 의사 클래스**: hover, focus, disabled, valid 등 32개 의사 클래스를 프리픽스 방식으로 간편하게 적용합니다.
-- **협업 효율**: HTML에서 바로 디자인 변경 및 조정이 가능하여, CSS 파일을 오가며 작업하는 시간이 대폭 줄어듭니다.
-- **제로 의존성**: 외부 CSS 라이브러리 없이 사용 가능합니다.
-- **스타일 일관성**: 전체 프로젝트에 걸쳐 동일한 유틸리티 클래스를 사용하므로 스타일의 일관성이 자연스럽게 유지됩니다.
+Atomic 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
-```
+**핵심 원리: `atomic.min.css`를 항상 가장 마지막에 로드합니다.**
-이 규칙만 알면 문서에 없는 속성도 추론할 수 있습니다.
+CSS는 동일 선택자 우선순위일 때 나중에 선언된 스타일이 이기므로, Atomic CSS를 맨 마지막에 불러오면 기존 스타일을 자연스럽게 덮어씁니다. 기존 코드를 수정하거나 삭제할 필요 없이, HTML에 Atomic 클래스만 추가하면 됩니다.
 ```html
-<div class="df jcc aic gap2rem p2rem bgFFFFFF br8px">Hello Atomic CSS!</div>
+<!-- 기존에 사용하던 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" />
 ```
-생성되는 CSS:
+React, Vue 등 import 방식도 동일합니다. **항상 가장 마지막에 import**하면 됩니다:
-```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;
-}
+```tsx
+// 기존에 사용하던 스타일
+import "./styles/framework.css";
+import "./styles/global.css";
+// Atomic CSS를 항상 가장 마지막에 import → 최우선 적용
+import "./assets/css/atomic.min.css";
 ```
+> 기존 프로젝트에 점진적으로 도입하거나, 새 프로젝트에서 처음부터 사용하거나, 자유롭게 선택할 수 있습니다. 도입 비용은 제로입니다.
 ---
 ## 설치
 ```bash
+# 글로벌 설치 (어디서든 atomic-css 명령 사용)
 npm install -g atomic-css-cli
+# 또는 프로젝트 로컬 설치
+npm install --save-dev atomic-css-cli
 ```
-## 사용법
+로컬 설치 시에는 `npx`를 붙여 실행합니다:
-### 명령어
+```bash
+npx atomic-css build
+npx atomic-css watch
+```
-| 명령어 | 설명 |
-| --- | --- |
-| `atomic-css build [dir]` | 파일을 스캔하고 CSS를 일괄 생성 (1회) |
-| `atomic-css watch [dir]` | 파일 변경을 감지하여 CSS 자동 생성 |
-| `atomic-css init` | `.atomic.json` 설정 파일 생성 |
+설치 확인:
-### 옵션
+```bash
+atomic-css --version
+```
-| 옵션 | 설명 |
-| --- | --- |
-| `-o, --output <path>` | CSS 출력 디렉토리 |
-| `-d, --debug` | 미니파이되지 않은 `atomic.css`도 함께 생성 |
-| `-e, --extensions <exts>` | 스캔할 파일 확장자 (쉼표 구분) |
-| `-c, --config <path>` | `.atomic.json`이 위치한 프로젝트 루트 경로 |
+---
+## 빠른 시작
-### 빠른 시작
+### 1단계: 프로젝트에서 설정 파일 생성
 ```bash
-# 1. 설정 파일 생성
+cd my-project
 atomic-css init
+```
+프로젝트 루트에 `.atomic.json` 파일이 생성됩니다:
+```json
+{
+    "selectedLanguages": ["html"],
+    "cssDirectoryPath": "/assets/css/common/",
+    "extensions": [".html"],
+    "projects": []
+}
+```
-# 2. 일괄 빌드
+### 2단계: HTML에 Atomic CSS 클래스 작성
+```html
+<!-- 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 빌드
+```bash
+# 일괄 빌드 (1회)
 atomic-css build
+```
-# 3. 워치 모드 (개발 중)
+실행하면 `.atomic.json`의 `cssDirectoryPath`에 `atomic.min.css`가 생성됩니다:
+```
+my-project/
+├── index.html
+├── .atomic.json
+└── assets/css/common/
+    └── atomic.min.css    ← 자동 생성!
+```
+### 4단계: 개발 중에는 워치 모드
+```bash
+# 파일 변경을 감지하여 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를 일괄 생성합니다.
 ```bash
-# 현재 디렉토리의 HTML 파일을 스캔하여 CSS 생성
+# 현재 디렉토리 빌드
 atomic-css build
-# src 디렉토리를 스캔하고 dist/css에 출력
+# 특정 디렉토리 빌드
+atomic-css build src
+# 출력 경로 지정
 atomic-css build src -o dist/css
-# tsx, jsx 파일도 포함하여 스캔
-atomic-css build src -e tsx,jsx,html
+# 스캔할 확장자 지정 (쉼표 구분)
+atomic-css build src -e html,tsx,jsx
-# 디버그 모드 (미니파이 + 원본 CSS 모두 생성)
+# 디버그 모드: atomic.min.css + atomic.css(원본) 모두 생성
 atomic-css build -d
-# 워치 모드로 개발
-atomic-css watch src -o dist/css -e html,tsx
+# 설정 파일 경로 지정 (.atomic.json이 다른 위치에 있을 때)
+atomic-css build src -c /path/to/project-root
+# 옵션 조합
+atomic-css build src -o dist/css -e html,tsx,jsx -d
 ```
-### Programmatic API
+| 옵션 | 설명 | 기본값 |
+| --- | --- | --- |
+| `-o, --output <path>` | CSS 출력 디렉토리 | `.atomic.json`의 `cssDirectoryPath` |
+| `-d, --debug` | 미니파이되지 않은 `atomic.css`도 함께 생성 | `false` |
+| `-e, --extensions <exts>` | 스캔할 파일 확장자 (쉼표 구분, `.` 생략 가능) | `.atomic.json`의 `extensions` |
+| `-c, --config <path>` | `.atomic.json`이 위치한 프로젝트 루트 경로 | 소스 디렉토리와 동일 |
-```js
-const {
-    generateCSSRules,
-    parseClassName,
-    build,
-    watch,
-    extractClassesFromText,
-    loadConfig
-} = require("atomic-css-cli");
+### `atomic-css watch [dir]`
-// 텍스트에서 클래스 추출
-const classes = extractClassesFromText('<div class="df jcc aic">');
+파일 변경을 실시간으로 감지하여 CSS를 자동 재생성합니다. `build`와 동일한 옵션을 지원합니다.
-// 클래스명 → CSS 규칙 생성
-const rules = generateCSSRules(["df", "jcc", "aic"]);
+```bash
+# 현재 디렉토리 워치
+atomic-css watch
-// 프로그래밍 방식으로 빌드
-await build("./src", { output: "./dist/css" });
+# 특정 디렉토리 워치 + 출력 경로 지정
+atomic-css watch src -o dist/css
+# React 프로젝트 워치
+atomic-css watch src -e html,tsx,jsx
+# 디버그 모드 워치
+atomic-css watch -d
+```
+감시 대상에서 자동 제외되는 파일:
+- `atomic.css`, `atomic.min.css` (출력 파일)
+- `.atomic.json` (설정 파일)
+- `node_modules/` 하위 전체
+### `atomic-css init`
+현재 디렉토리에 `.atomic.json` 기본 설정 파일을 생성합니다. 이미 존재하면 생성하지 않습니다.
+```bash
+atomic-css init
 ```
+---
 ## 설정 파일 (.atomic.json)
 프로젝트 루트에 `.atomic.json` 파일을 생성하면 프로젝트별로 동작을 커스터마이징할 수 있습니다. 파일이 없으면 기본 설정으로 동작합니다.
@@ -152,12 +226,14 @@ await build("./src", { output: "./dist/css" });
 | 옵션 | 타입 | 기본값 | 설명 |
 | --- | --- | --- | --- |
-| `cssDirectoryPath` | `string` | `"/assets/css/common/"` | 생성될 CSS 파일의 저장 경로. 워크스페이스 루트 기준 상대 경로 |
+| `cssDirectoryPath` | `string` | `"/assets/css/common/"` | 생성될 CSS 파일의 저장 경로. 프로젝트 루트 기준 상대 경로 |
 | `extensions` | `string[]` | `[".html"]` | 클래스를 추출할 대상 파일 확장자 |
 | `selectedLanguages` | `string[]` | `["html"]` | VSCode 확장 전용 옵션 (CLI에서는 미사용) |
 | `projects` | `array` | — | 멀티프로젝트 설정. 파일 경로에 따라 서로 다른 위치에 CSS를 생성 |
-### 기본 설정 (HTML 프로젝트)
+### 프레임워크별 설정 예시
+#### 기본 HTML 프로젝트
 ```json
 {
@@ -166,7 +242,7 @@ await build("./src", { output: "./dist/css" });
 }
 ```
-### React / Next.js
+#### React / Next.js
 ```json
 {
@@ -175,7 +251,7 @@ await build("./src", { output: "./dist/css" });
 }
 ```
-### Vue / Nuxt
+#### Vue / Nuxt
 ```json
 {
@@ -184,7 +260,7 @@ await build("./src", { output: "./dist/css" });
 }
 ```
-### PHP (Laravel, WordPress 등)
+#### PHP (Laravel, WordPress 등)
 ```json
 {
@@ -193,9 +269,9 @@ await build("./src", { output: "./dist/css" });
 }
 ```
-### 멀티프로젝트 (다국어/멀티 출력)
+#### 멀티프로젝트 (다국어/멀티 출력)
-`projects` 배열을 사용하면 파일 경로에 따라 CSS 출력 위치를 분리할 수 있습니다.
+`projects` 배열을 사용하면 파일 경로에 따라 CSS 출력 위치를 분리할 수 있습니다. `sources`에 해당하는 경로의 파일은 `output` 경로로, 매칭되지 않는 파일은 `cssDirectoryPath`로 CSS가 생성됩니다.
 ```json
 {
@@ -218,18 +294,221 @@ await build("./src", { output: "./dist/css" });
 | projects 옵션 | 타입 | 설명 |
 | --- | --- | --- |
-| `name` | `string` | 프로젝트 식별 이름 (CSS 파일 상단에 표시) |
+| `name` | `string` | 프로젝트 식별 이름 (콘솔 출력에 표시) |
 | `sources` | `string[]` | 이 프로젝트에 속하는 소스 디렉토리 경로 목록 |
 | `output` | `string` | 이 프로젝트의 CSS 출력 경로 |
-### HTML에 연결
+---
+## 출력 파일
+| 파일 | 생성 조건 | 설명 |
+| --- | --- | --- |
+| `atomic.min.css` | 항상 | 미니파이된 CSS (프로덕션용) |
+| `atomic.css` | `-d` 플래그 사용 시 | 포매팅된 CSS (디버그/확인용) |
+HTML에서 연결 — **항상 모든 CSS 중 가장 마지막에** 로드합니다:
 ```html
+<link rel="stylesheet" href="/css/기존스타일.css" />
+<!-- Atomic CSS를 항상 가장 마지막에 → 최우선 적용 -->
 <link rel="stylesheet" href="/assets/css/common/atomic.min.css" />
 ```
 ---
+## 실전 워크플로우 예시
+### HTML 프로젝트
+```bash
+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`에 스크립트 추가:
+```json
+{
+    "scripts": {
+        "css": "atomic-css build",
+        "css:watch": "atomic-css watch",
+        "css:debug": "atomic-css build -d"
+    }
+}
+```
+```bash
+npm run css:watch    # 개발 중
+npm run css          # 배포 전 빌드
+```
+### React / Next.js 프로젝트
+```bash
+cd my-react-app
+npm install --save-dev atomic-css-cli
+# .atomic.json 생성 후 수정
+npx atomic-css init
+```
+`.atomic.json` 수정:
+```json
+{
+    "cssDirectoryPath": "/src/assets/css/",
+    "extensions": [".html", ".tsx", ".jsx"]
+}
+```
+```bash
+# tsx/jsx 파일의 className에서 클래스 추출
+npx atomic-css watch src -e html,tsx,jsx
+```
+CSS import (React) — **항상 가장 마지막에 import**:
+```tsx
+// src/App.tsx
+import "./styles/global.css";        // 기존 스타일
+import "./assets/css/atomic.min.css"; // 항상 마지막 → 최우선 적용
+```
+### Vue / Nuxt 프로젝트
+`.atomic.json`:
+```json
+{
+    "cssDirectoryPath": "/src/assets/css/",
+    "extensions": [".html", ".vue"]
+}
+```
+```bash
+npx atomic-css watch src -e html,vue
+```
+### CI/CD 파이프라인
+```yaml
+# GitHub Actions 예시
+- name: Generate Atomic CSS
+  run: npx atomic-css-cli build src -o dist/css -e html,tsx,jsx
+```
+---
+## Programmatic API
+Node.js에서 직접 import하여 사용할 수 있습니다.
+```js
+const {
+    generateCSSRules,
+    parseClassName,
+    build,
+    watch,
+    extractClassesFromText,
+    loadConfig,
+    minifyCss
+} = require("atomic-css-cli");
+// 텍스트에서 클래스 추출
+const classes = extractClassesFromText('<div class="df jcc aic gap2rem">');
+// → ["df", "jcc", "aic", "gap2rem"]
+// 클래스명 → CSS 규칙 생성
+const rules = generateCSSRules(["df", "jcc", "aic"]);
+// CSS 미니파이
+const minified = minifyCss(rules);
+// 프로그래밍 방식으로 빌드
+await build("./src", {
+    output: "./dist/css",
+    debug: false,
+    extensions: [".html", ".tsx"]
+});
+// 프로그래밍 방식으로 워치
+const watcher = watch("./src", {
+    output: "./dist/css",
+    extensions: [".html", ".tsx"]
+});
+```
+---
+## 왜 Atomic CSS인가?
+- **제로 CSS 작성**: 별도 CSS 파일 작성이 불필요합니다. HTML 클래스명만으로 모든 시각적 스타일을 처리합니다.
+- **무제한 자유도**: 다른 유틸리티 프레임워크와 달리 미리 정해진 값에 제한받지 않습니다. `gap37px`, `w847px`, `fs1-3rem` 등 어떤 수치와 단위든 자유롭게 조합할 수 있습니다.
+- **직관적 네이밍**: CSS 속성과 값의 앞글자를 조합하는 규칙 하나만 알면, 문서 없이도 대부분의 클래스명을 추론할 수 있습니다.
+- **14단계 반응형**: QHD(2560px)부터 Ultra Small(420px)까지 14개 브레이크포인트를 지원하여 세밀한 반응형 대응이 가능합니다.
+- **32개 의사 클래스**: hover, focus, disabled, valid 등 32개 의사 클래스를 프리픽스 방식으로 간편하게 적용합니다.
+- **협업 효율**: 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
+```
+이 규칙만 알면 문서에 없는 속성도 추론할 수 있습니다.
+```html
+<div class="df jcc aic gap2rem p2rem bgFFFFFF br8px">Hello Atomic CSS!</div>
+```
+생성되는 CSS:
+```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;
+}
+```
+---
 ## 네이밍 규칙
 ### 단위
@@ -543,21 +822,7 @@ await build("./src", { output: "./dist/css" });
 > **AI가 Atomic CSS를 완벽하게 이해합니다.**
-Atomic CSS는 AI 코딩 도구를 위한 전용 **MCP(Model Context Protocol) 서버**를 제공합니다. 이것은 단순한 문서 참조가 아닙니다. AI가 Atomic CSS의 모든 클래스 체계를 **실시간으로 조회하고, 검색하고, 생성**할 수 있도록 설계된 AI 전용 인터페이스입니다.
-### 왜 MCP인가?
-일반적인 CSS 프레임워크를 AI와 사용할 때의 문제:
-- AI가 클래스명을 **추측**하거나 **잘못된 클래스**를 생성
-- 문서를 매번 컨텍스트에 넣어야 하는 **토큰 낭비**
-- 프레임워크 업데이트 시 AI가 **구버전 정보**를 사용
-**Atomic CSS + MCP는 이 문제를 완전히 해결합니다:**
-- AI가 클래스명을 추측하지 않고 MCP 서버에 **직접 질의**
-- 항상 **최신 데이터** 기반으로 정확한 클래스 반환
-- 컨텍스트 오염 없이 **필요한 순간에만** 정보를 가져옴
+Atomic CSS는 AI 코딩 도구를 위한 전용 **MCP(Model Context Protocol) 서버**를 제공합니다. AI가 Atomic CSS의 모든 클래스 체계를 **실시간으로 조회하고, 검색하고, 생성**할 수 있도록 설계된 AI 전용 인터페이스입니다.
 ### 제공 도구 (Tools)
@@ -582,10 +847,6 @@ Atomic CSS는 AI 코딩 도구를 위한 전용 **MCP(Model Context Protocol)
 }
 ```
-> `https://mcp.atomiccss.dev`는 Atomic CSS 전용 원격 MCP 서버입니다. 로컬 설치가 필요 없으며, 인터넷 연결만으로 모든 AI 도구에서 사용할 수 있습니다.
-### 지원 도구
 | AI 도구 | 설정 파일 | 비고 |
 | --- | --- | --- |
 | **Claude Code** | `.mcp.json` | 프로젝트 루트에 배치 |