kwon-ui 0.0.0-stage → 0.2.0

package/check/index.mjs

@@ -0,0 +1,233 @@
+// kwon-ui 검사기. 앱 코드가 디자인 시스템을 벗어난 곳을 찾는다.
+// - CSS: 색·글자 크기·굵기·모서리 값을 직접 쓴 곳, 시스템 조각과 토큰을 앱에서 다시 정의한 곳
+// - TSX: style 과 Tailwind 유틸리티로 색·글자를 직접 정한 곳
+// 이미 있는 위반은 기준선(baseline)에 적어 두고, 파일별로 그 수가 늘어날 때만 실패한다.
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import postcss from "postcss";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export const RULES = {
+  "raw-color": "색 값을 직접 썼습니다. var(--n-…) 토큰을 쓰거나, 앱 고유의 색이면 앱 토큰 파일에서 변수로 정의합니다.",
+  "raw-font-size": "글자 크기를 직접 썼습니다. var(--n-fs-title), var(--n-fs-body), var(--n-fs-small) 가운데 하나를 씁니다.",
+  "font-weight": "굵기는 400과 500 두 가지입니다.",
+  "raw-radius": "모서리 값을 직접 썼습니다. var(--n-radius), var(--n-radius-md), var(--n-radius-pill) 가운데 하나를 씁니다.",
+  "system-redefine": "kwon-ui 의 조각을 앱에서 다시 정의했습니다. 고칠 것이 있으면 kwon-ui 에 제안합니다.",
+  "reserved-prefix": "n- 으로 시작하는 이름은 kwon-ui 에서만 만듭니다. 앱의 조각은 앱 접두어로 짓습니다.",
+  "token-redefine": "--n- 토큰은 kwon-ui 에서만 정합니다.",
+  "inline-style": "style 에 색·글자 값을 직접 썼습니다. kwon-ui 조각과 토큰을 씁니다.",
+  "tw-arbitrary": "Tailwind 임의 값으로 색·글자·모서리를 정했습니다. kwon-ui 조각과 토큰을 씁니다.",
+  "tw-type": "Tailwind 글자 크기·굵기 유틸리티 대신 Title, Body, Small 을 씁니다.",
+  "tw-color": "Tailwind 색 유틸리티 대신 kwon-ui 조각과 토큰을 씁니다.",
+};
+// 실패로 치지 않고 수만 알려 주는 것
+export const WARNINGS = {
+  "system-override": "kwon-ui 조각을 페이지 문맥에서 덮어썼습니다. 자주 되풀이되면 kwon-ui 에 변형을 제안합니다.",
+};
+
+export const DEFAULT_CONFIG = {
+  roots: ["src"],
+  extensions: [".css", ".tsx"],
+  exclude: [],
+  tokenFiles: [],
+  scopes: ["night", "paper"],
+  baseline: "kwon-ui.baseline.json",
+};
+
+export function loadSystem() {
+  const p = join(here, "..", "dist", "classes.json");
+  if (!existsSync(p)) throw new Error("dist/classes.json 이 없습니다. kwon-ui 를 먼저 빌드합니다(npm run build).");
+  const j = JSON.parse(readFileSync(p, "utf8"));
+  return { version: j.version, classes: new Set(j.classes), modifiers: new Set(j.modifiers), tokens: new Set(j.tokens) };
+}
+
+export function loadConfig(cwd) {
+  const p = join(cwd, "kwon-ui.config.json");
+  const user = existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : {};
+  return { ...DEFAULT_CONFIG, ...user, found: existsSync(p) };
+}
+
+const posix = (p) => p.split(sep).join("/");
+const strip = (v) => v.replace(/url\([^)]*\)/gi, "").replace(/(["'])(?:\\.|(?!\1).)*\1/g, "");
+const COLOR = /#[0-9a-fA-F]{3,8}(?![\w-])|(?<![\w-])(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(|(?<![\w-])(?:white|black)(?![\w-])/i;
+const RADIUS_OK = /^(?:0|50%|100%|999px|9999px|inherit|initial|unset|var\(--[\w-]+(?:,[^)]*)?\))$/;
+const WEIGHT_OK = /^(?:400|500|normal|inherit|initial|unset|var\(--[\w-]+(?:,[^)]*)?\))$/;
+const SIZE_KEYWORD = /^(?:inherit|initial|unset|1em|100%|0)$/;
+
+/** CSS 한 파일을 검사한다. */
+export function checkCss(source, { file = "", system, config = DEFAULT_CONFIG } = {}) {
+  const out = [];
+  const add = (rule, node, text) => out.push({ rule, line: node.source?.start?.line ?? 0, text: text.replace(/\s+/g, " ").slice(0, 120) });
+  const isTokenFile = config.tokenFiles.map(posix).includes(posix(file));
+  const scopes = new Set(config.scopes);
+  let root;
+  try {
+    root = postcss.parse(source, { from: file || undefined });
+  } catch (e) {
+    return [{ rule: "parse-error", line: e.line ?? 0, text: String(e.reason ?? e.message) }];
+  }
+  const inTheme = (node) => {
+    for (let p = node.parent; p; p = p.parent) if (p.type === "atrule" && p.name === "theme") return true;
+    return false;
+  };
+
+  root.walkDecls((d) => {
+    const prop = d.prop.toLowerCase();
+    const value = strip(d.value);
+    const shown = `${d.prop}: ${d.value}`;
+    if (prop.startsWith("--")) {
+      if (prop.startsWith("--n-")) add("token-redefine", d, shown);
+      // 변수 정의는 앱 토큰 파일과 @theme 안에서만 값을 직접 쓸 수 있다
+      if (!isTokenFile && !inTheme(d) && COLOR.test(value)) add("raw-color", d, shown);
+      return;
+    }
+    if (COLOR.test(value) && prop !== "content" && prop !== "font-family") add("raw-color", d, shown);
+    if (prop === "font-size" || prop === "font") {
+      const rest = value.replace(/var\((?:[^()]|\([^()]*\))*\)/g, "");
+      const literal = /\d/.test(rest) && !SIZE_KEYWORD.test(value.trim());
+      if (prop === "font" || literal || (!/var\(--/.test(value) && !SIZE_KEYWORD.test(value.trim()))) add("raw-font-size", d, shown);
+    }
+    if (prop === "font-weight" && !WEIGHT_OK.test(value.trim())) add("font-weight", d, shown);
+    if (/^border(?:-(?:top|bottom|start|end)-(?:left|right|start|end))?-radius$/.test(prop)) {
+      const parts = value.replace(/var\((?:[^()]|\([^()]*\))*\)/g, "var(--x)").split(/[\s/]+/).filter(Boolean);
+      if (parts.some((p) => !RADIUS_OK.test(p))) add("raw-radius", d, shown);
+    }
+  });
+
+  if (system) {
+    root.walkRules((rule) => {
+      if (rule.parent?.type === "atrule" && /keyframes$/i.test(rule.parent.name)) return;
+      for (const sel of rule.selectors ?? []) {
+        const classes = (sel.match(/\.(-?[a-zA-Z_][\w-]*)/g) ?? []).map((c) => c.slice(1));
+        const reserved = classes.filter((c) => c.startsWith("n-"));
+        if (!reserved.length) continue;
+        if (reserved.some((c) => !system.classes.has(c))) {
+          add("reserved-prefix", rule, sel);
+        } else if (classes.every((c) => c.startsWith("n-") || scopes.has(c) || system.modifiers.has(c))) {
+          add("system-redefine", rule, sel);
+        } else {
+          add("system-override", rule, sel);
+        }
+      }
+    });
+  }
+  return out;
+}
+
+const TW_VARIANT = String.raw`(?<![\w-])(?:[a-z0-9-]+:)*`;
+const TW_TYPE = new RegExp(TW_VARIANT + String.raw`(?:text-(?:xs|sm|base|lg|xl|[2-9]xl)|font-(?:thin|extralight|light|semibold|bold|extrabold|black))(?![\w-])`);
+const TW_COLOR = new RegExp(
+  TW_VARIANT +
+    String.raw`(?:text|bg|border|ring|fill|stroke|from|to|via|decoration|divide|outline|placeholder|caret|accent)-(?:white|black|(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3})(?:\/\d{1,3})?(?![\w-])`,
+);
+const TW_ARBITRARY = new RegExp(TW_VARIANT + String.raw`(text|bg|border|ring|fill|stroke|from|to|via|shadow|outline|decoration|divide|rounded(?:-[a-z]{1,2})?|leading|tracking|font)-\[([^\]]+)\]`, "g");
+const STYLE_KEYS = /(?<![\w-])(color|background|backgroundColor|borderColor|fontSize|fontWeight|borderRadius|letterSpacing|lineHeight|fontFamily)\s*:\s*([^,}\n]+)/g;
+
+/** TSX 한 파일을 검사한다(문자열과 style 속성을 정규식으로 훑는다). */
+export function checkTsx(source) {
+  const out = [];
+  const lines = source.split("\n");
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(/(["'`])((?:\\.|(?!\1).)*)\1/g)) {
+      const s = m[2];
+      if (!s || s.length > 600) continue;
+      const type = s.match(TW_TYPE);
+      if (type) out.push({ rule: "tw-type", line: i + 1, text: type[0] });
+      const color = s.match(TW_COLOR);
+      if (color) out.push({ rule: "tw-color", line: i + 1, text: color[0] });
+      for (const a of s.matchAll(TW_ARBITRARY)) {
+        const [whole, prop, val] = a;
+        if (/var\(--/.test(val)) continue; // 토큰을 가리키는 임의 값은 허용
+        const colorish = COLOR.test(val);
+        const sizeish = /^\d*\.?\d+(?:px|rem|em|%)$/.test(val);
+        const isTypeProp = /^(?:rounded|leading|tracking|font)/.test(prop);
+        if (isTypeProp || colorish || (prop === "text" && sizeish)) out.push({ rule: "tw-arbitrary", line: i + 1, text: whole });
+      }
+    }
+  });
+  for (const m of source.matchAll(/style=\{\{([\s\S]*?)\}\}/g)) {
+    const base = source.slice(0, m.index).split("\n").length;
+    for (const k of m[1].matchAll(STYLE_KEYS)) {
+      const v = k[2].trim();
+      const literal = /^["'`\d]/.test(v) && !/var\(--/.test(v);
+      if (literal) out.push({ rule: "inline-style", line: base + m[1].slice(0, k.index).split("\n").length - 1, text: `${k[1]}: ${v}`.slice(0, 120) });
+    }
+  }
+  return out;
+}
+
+export function checkFile(abs, { cwd, system, config }) {
+  const rel = posix(relative(cwd, abs));
+  const source = readFileSync(abs, "utf8");
+  const found = abs.endsWith(".css") ? checkCss(source, { file: rel, system, config }) : checkTsx(source);
+  return found.map((v) => ({ ...v, file: rel }));
+}
+
+/** 설정의 roots 아래에서 검사할 파일을 모은다. */
+export function collect(cwd, config) {
+  const files = [];
+  const skip = config.exclude.map(posix);
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      if (name === "node_modules" || name.startsWith(".")) continue;
+      const abs = join(dir, name);
+      const rel = posix(relative(cwd, abs));
+      if (skip.some((x) => rel === x || rel.startsWith(x.endsWith("/") ? x : x + "/"))) continue;
+      if (statSync(abs).isDirectory()) walk(abs);
+      else if (config.extensions.some((e) => name.endsWith(e))) files.push(abs);
+    }
+  };
+  for (const r of config.roots) if (existsSync(join(cwd, r))) walk(join(cwd, r));
+  return files.sort();
+}
+
+/** 위반을 파일과 규칙별 수로 줄인다(경고와 파싱 오류는 빼고 센다). */
+export function summarize(violations) {
+  const files = {};
+  for (const v of violations) {
+    if (!(v.rule in RULES)) continue;
+    files[v.file] ??= {};
+    files[v.file][v.rule] = (files[v.file][v.rule] ?? 0) + 1;
+  }
+  return files;
+}
+
+/** 기준선보다 늘어난 (파일, 규칙)만 고른다. */
+export function overBaseline(counts, baseline) {
+  const over = [];
+  for (const [file, rules] of Object.entries(counts)) {
+    for (const [rule, n] of Object.entries(rules)) {
+      const base = baseline?.files?.[file]?.[rule] ?? 0;
+      if (n > base) over.push({ file, rule, count: n, base });
+    }
+  }
+  return over;
+}
+
+/**
+ * 검사를 돌린다. files 를 주면 그 파일만, 없으면 설정의 roots 전체를 본다.
+ * 돌려주는 값: violations(전부), over(기준선보다 늘어난 것), counts, baseline
+ */
+export function run({ cwd = process.cwd(), files, useBaseline = true } = {}) {
+  cwd = resolve(cwd);
+  const config = loadConfig(cwd);
+  const system = loadSystem();
+  const targets = (files?.length ? files.map((f) => resolve(cwd, f)) : collect(cwd, config)).filter(
+    (f) => existsSync(f) && config.extensions.some((e) => f.endsWith(e)),
+  );
+  const violations = targets.flatMap((f) => checkFile(f, { cwd, system, config }));
+  const counts = summarize(violations);
+  const basePath = join(cwd, config.baseline);
+  const baseline = useBaseline && existsSync(basePath) ? JSON.parse(readFileSync(basePath, "utf8")) : null;
+  return { config, system, targets, violations, counts, baseline, over: overBaseline(counts, baseline) };
+}
+
+export function writeBaseline(cwd = process.cwd()) {
+  cwd = resolve(cwd);
+  const r = run({ cwd, useBaseline: false });
+  const body = { kwonUi: r.system.version, files: Object.fromEntries(Object.entries(r.counts).sort(([a], [b]) => a.localeCompare(b))) };
+  writeFileSync(join(cwd, r.config.baseline), JSON.stringify(body, null, 2) + "\n");
+  return { path: r.config.baseline, total: Object.values(r.counts).reduce((s, x) => s + Object.values(x).reduce((a, b) => a + b, 0), 0), files: Object.keys(r.counts).length };
+}

package/claude/ADOPTING.md

@@ -0,0 +1,107 @@
+# 앱에 넣는 순서
+
+앱 하나에 kwon-ui를 넣을 때 따르는 순서입니다. 한 번에 한 앱씩, 넣기 전과 후의 화면을 같은 크기로 찍어 대조합니다.
+
+## 1. 설치
+
+```bash
+npm install kwon-ui@0.2.0 --save-exact
+```
+
+정확한 버전을 고정합니다. 올릴 때는 `CHANGELOG.md`를 읽고 한 앱씩 올립니다.
+
+## 2. CSS 불러오기
+
+레이아웃에서 앱의 CSS보다 먼저 불러옵니다.
+
+```tsx
+import "kwon-ui/kwon-ui.css";
+import "./globals.css";
+```
+
+- 앱의 CSS가 `@layer`로 묶여 있고 kwon-ui도 같은 층에 넣어야 하면 CSS에서 `@import "kwon-ui/kwon-ui.css" layer(components);`로 부릅니다.
+- 층 없이 부르면 kwon-ui의 규칙이 Tailwind 유틸리티보다 우선합니다. 그래서 조각에는 margin과 폭이 없습니다.
+- 페이지 맨 바깥에 `.night`가 있어야 합니다.
+- Next.js 16과 Tailwind 4에서 `@import "kwon-ui/kwon-ui.css" layer(components);`가 개발 서버(webpack)와 운영 빌드(Turbopack) 모두에서 되는 것을 확인했습니다(스킬캠퍼스, 2026-11-16). 컴포넌트와 `tone()`도 서버 컴포넌트에서 그대로 불러와 씁니다.
+- 같은 층에 넣으면 특이도와 순서가 그대로 적용됩니다. kwon-ui의 규칙은 `.night .n-…`(클래스 둘)이라, 같은 요소에 붙은 앱의 한 클래스짜리 규칙(`.cp-offer { padding-top: … }`)은 집니다. 앱 쪽을 `.n-sect.cp-offer`처럼 클래스 둘로 씁니다.
+- `.night`는 글자색을 흰색으로 둡니다. 앱의 기본 글자색이 다르면 바깥 요소에서 한 번 정합니다(`.cp.night { color: var(--n-soft); }`).
+- 개발 서버가 떠 있는 채로 브랜치를 바꿔 CSS 파일이 사라졌다 생기면 옛 CSS가 남습니다. 불러오는 CSS 파일을 한 번 저장(touch)하면 다시 만들어집니다.
+
+## 3. 앱에 있던 같은 정의 지우기
+
+```bash
+npx kwon-ui check --report
+```
+
+`system-redefine`과 `token-redefine`으로 나오는 규칙이 앱에 남아 있는 같은 이름의 정의입니다. 지우고 화면을 대조합니다. 앱의 값이 kwon-ui와 달랐다면 그 차이가 화면에 나타납니다. 의도한 변형이었는지 보고, 필요하면 kwon-ui에 변형을 제안합니다.
+
+`reserved-prefix`로 나오는 것은 앱에만 있는 `n-` 이름입니다. 한 번에 바꾸지 않아도 됩니다. 기준선에 두고, 그 파일을 고칠 때 앱 접두어로 바꿉니다.
+
+## 4. 설정과 기준선
+
+앱 루트에 `kwon-ui.config.json`을 둡니다.
+
+```json
+{
+  "roots": ["src"],
+  "exclude": [],
+  "tokenFiles": ["src/app/tokens.css"]
+}
+```
+
+- `roots`: 검사할 폴더. 화면과 상관없는 폴더는 `exclude`에 넣습니다.
+- `tokenFiles`: 앱 고유의 색(강조색 등)을 변수로 정의하는 파일. 색 값을 직접 쓸 수 있는 곳은 여기뿐입니다.
+
+```bash
+npx kwon-ui baseline
+```
+
+지금의 위반 수가 `kwon-ui.baseline.json`에 적힙니다. 커밋합니다. 이 수는 줄어들기만 해야 합니다. 위반을 고쳤으면 다시 `baseline`을 돌려 수를 낮춥니다.
+
+## 5. 빌드에 걸기
+
+```json
+{
+  "scripts": {
+    "check:design": "kwon-ui check",
+    "prebuild": "npm run check:design"
+  }
+}
+```
+
+위반이 기준선보다 늘면 빌드가 실패합니다. 어떤 도구로 작업해도 똑같이 걸립니다.
+
+## 6. Claude Code 훅
+
+파일을 저장할 때마다 그 파일만 검사해서, 위반이 늘었으면 내용을 모델에게 바로 돌려줍니다. 작업 공간의 Claude Code 설정(`.claude/settings.json`)에 한 번 겁니다. 아래 모양으로 걸어 실제로 되돌아오는 것을 확인했습니다(2026-11-16).
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{ "type": "command", "command": "command -v node >/dev/null 2>&1 || exit 0; node /경로/kwon-ui/claude/hook.mjs", "timeout": 20 }]
+      }
+    ]
+  }
+}
+```
+
+훅은 `kwon-ui.config.json`이 있는 앱 안의 `.css`, `.tsx` 파일만 봅니다. 그 밖의 파일과 오류는 조용히 지나갑니다.
+
+## 7. 앱의 CLAUDE.md
+
+[APP-CLAUDE.md](APP-CLAUDE.md)의 문구를 앱의 CLAUDE.md에 넣습니다.
+
+## 넣기 전과 후를 대조하는 법
+
+넣기 전의 화면에서 모든 요소의 자리(x, y, 폭, 높이)와 계산된 스타일을 기록해 두고, 넣은 뒤 같은 방법으로 기록해 요소 순서대로 맞춰 봅니다. 화면 폭은 390, 768, 1024, 1440 네 가지로 잽니다. 같은 화면을 두 번 재서 차이가 0인지 먼저 확인합니다(움직이는 조각은 빼고 잽니다). 남는 차이가 kwon-ui의 값을 받아들인 것뿐이면 끝입니다. 스킬캠퍼스는 이 방법으로 네 페이지를 대조했고, 페이지 길이 차이는 16,000px 가운데 4px 안팎이었습니다.
+
+## 넣을 때 알아 둘 차이
+
+값의 기준은 kwonandcompany.com입니다. 0.1.0은 계산된 스타일이 홈페이지와 같고, 0.2.0에서 아래 두 가지가 달라졌습니다. 다른 두 제품은 손으로 옮기면서 생긴 작은 차이가 있어, 넣으면 그만큼 바뀝니다.
+
+- kwonandcompany.com: 줄 목록의 라벨이 본문 첫 줄의 밑선에 맞춰져 넓은 화면에서 4px 내려갑니다(`items-baseline`을 이미 준 줄은 그대로입니다). 교육 문의의 사진 판(`n-closing`)을 `n-photo`로 바꾸면 1024px 미만에서 최소 높이가 560px → 480px, 제목과 문단 사이가 20px → 16px, 제목의 회색 글자가 50% → 62%가 됩니다. 문단과 버튼 줄 사이는 버튼 줄을 `n-actions`로 두면 40px 그대로입니다. 사진 판 안의 `mt-5`, `mt-10`은 뺍니다.
+- Projects 랜딩: 제목 줄 간격 1.25 → 1.2, 본문 1.55 → 1.5, 알약 버튼 글자 사이 0.01em과 간격 10px, 글자 링크 간격 8px, 구간 머리의 세로 정렬(위 → 가운데). 구간 사이의 선(`n-sect n-rule`)을 `n-sect ruled`로 바꾸면 선이 바깥 여백만큼 짧아져 내용 폭과 같아집니다.
+- 스킬캠퍼스(2026-11-16 공개 네 페이지에 넣음): 변수 이름을 바꿨습니다(`--hi`, `--mid`, `--line` 등 → `--n-hi`, `--n-mid`, `--n-line`). 바뀐 값은 작은 글 줄 간격 1.5 → 1.45, 글자 링크의 줄 높이 1.4 → 1.6, 줄 목록 라벨의 글자 사이 0, 검은 판의 z-index 1입니다. 0.2.0으로 올리면서 앱이 덧붙여 쓰던 규칙(구간 선, 짧은 구간, 줄 목록의 첫 줄 맞춤, 진한 낱말, 사진 판)을 지웠습니다.

package/claude/APP-CLAUDE.md

@@ -0,0 +1,15 @@
+# 앱의 CLAUDE.md에 넣는 문구
+
+kwon-ui를 넣은 앱의 CLAUDE.md에 아래를 그대로 넣습니다. 짧게 둡니다. 지켜지게 하는 것은 이 문구가 아니라 검사(`kwon-ui check`)와 훅입니다.
+
+```
+디자인 시스템: kwon-ui
+
+'디자인 시스템', '공통 컴포넌트'는 모두 kwon-ui(패키지 kwon-ui)를 뜻한다. 이 앱의 화면은 kwon-ui로만 만든다.
+
+- 화면 작업 전에 node_modules/kwon-ui/CATALOG.md 를 읽고, 거기 있는 조각으로 짠다.
+- 색, 글자 크기, 굵기, 모서리 값을 앱 코드에 직접 쓰지 않는다. kwon-ui 의 토큰(var(--n-…))과 조각만 쓴다. 앱 고유의 색은 kwon-ui.config.json 의 tokenFiles 에 적힌 파일에서만 변수로 정의한다.
+- n- 으로 시작하는 이름과 --n- 토큰을 앱에서 만들거나 다시 정의하지 않는다. 앱의 조각은 앱 접두어로 짓는다.
+- 필요한 조각이 없으면 페이지에서 비슷한 것을 새로 만들지 않는다. 멈추고 "kwon-ui 에 추가할 것"을 제안한다. 한 페이지에서만 쓸 조각이면 앱 접두어로 만들고 토큰만 쓴다.
+- 끝내기 전에 npm run check:design 을 통과시킨다. 검사를 끄거나, 기준선을 올리거나, 예외로 넘기지 않는다.
+```

package/claude/hook.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Claude Code 훅(PostToolUse, Edit·Write)용. 방금 고친 파일 하나를 kwon-ui 검사기로 본다.
+// 표준 입력으로 훅 JSON 을 받는다. 그 파일이 kwon-ui 를 쓰는 앱(kwon-ui.config.json 이 있는 폴더) 안에 있고
+// 위반이 기준선보다 늘었으면 내용을 표준 오류로 내고 종료 코드 2로 끝낸다(모델에게 그대로 돌아간다).
+// 그 밖의 경우(다른 폴더, 다른 종류의 파일, 검사기 오류)는 조용히 0으로 끝낸다. 훅 때문에 작업이 막히면 안 된다.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+
+function read() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+const input = read();
+const file = input?.tool_input?.file_path;
+if (!file || !/\.(css|tsx)$/.test(file) || !existsSync(file)) process.exit(0);
+
+// 가장 가까운 kwon-ui.config.json 을 찾는다
+let app = dirname(file);
+while (!existsSync(join(app, "kwon-ui.config.json"))) {
+  const up = dirname(app);
+  if (up === app) process.exit(0);
+  app = up;
+}
+
+try {
+  // 앱에 설치된 판의 검사기를 쓴다(앱마다 kwon-ui 버전이 다를 수 있다)
+  const installed = join(app, "node_modules", "kwon-ui", "check", "index.mjs");
+  const { run, RULES } = await import(pathToFileURL(existsSync(installed) ? installed : new URL("../check/index.mjs", import.meta.url).pathname).href);
+  const r = run({ cwd: app, files: [relative(app, file)] });
+  if (!r.over.length) process.exit(0);
+  const lines = [`kwon-ui: ${relative(app, file)} 이 디자인 시스템을 벗어났습니다.`];
+  for (const o of r.over) {
+    lines.push(`[${o.rule}] ${RULES[o.rule]}`);
+    for (const v of r.violations.filter((x) => x.rule === o.rule).slice(0, 6)) lines.push(`  ${v.line}: ${v.text}`);
+  }
+  lines.push("조각과 토큰 목록: node_modules/kwon-ui/CATALOG.md. 필요한 조각이 없으면 페이지에서 만들지 말고 kwon-ui 에 추가를 제안합니다.");
+  console.error(lines.join("\n"));
+  process.exit(2);
+} catch {
+  process.exit(0);
+}

package/dist/classes.json

@@ -0,0 +1,76 @@
+{
+  "version": "0.2.0",
+  "scope": "night",
+  "classes": [
+    "n-actions",
+    "n-body",
+    "n-card-title",
+    "n-cta-band",
+    "n-display",
+    "n-head",
+    "n-link",
+    "n-media",
+    "n-num",
+    "n-page",
+    "n-page-head",
+    "n-panel",
+    "n-photo",
+    "n-photo-in",
+    "n-pill",
+    "n-row",
+    "n-row-label",
+    "n-rows",
+    "n-rule",
+    "n-sect",
+    "n-small",
+    "n-sr",
+    "n-timeline",
+    "n-title",
+    "n-tl-more",
+    "n-tl-year",
+    "n-wrap"
+  ],
+  "modifiers": [
+    "chev",
+    "ghost",
+    "hi",
+    "lo",
+    "lo-inline",
+    "ruled",
+    "slim",
+    "wide",
+    "wide-label"
+  ],
+  "tokens": [
+    "--n-bg",
+    "--n-panel",
+    "--n-card",
+    "--n-card-2",
+    "--n-line",
+    "--n-hi",
+    "--n-soft",
+    "--n-mid",
+    "--n-dim",
+    "--n-btn",
+    "--n-btn-ink",
+    "--n-btn-hover",
+    "--n-ghost",
+    "--n-ghost-hover",
+    "--n-focus",
+    "--n-shade",
+    "--n-shade-soft",
+    "--n-on-photo",
+    "--n-fs-display",
+    "--n-fs-title",
+    "--n-fs-body",
+    "--n-fs-small",
+    "--n-fs-control",
+    "--n-radius",
+    "--n-radius-md",
+    "--n-radius-pill",
+    "--n-wrap",
+    "--n-gutter",
+    "--n-edge",
+    "--n-font"
+  ]
+}