@spectrabrain/eds 0.0.4 → 0.1.0

package/TOKEN_CONTEXT.md

@@ -0,0 +1,71 @@
+# EVA semantic token 사용 맥락
+
+이 문서는 `@spectrabrain/eds`의 공개 semantic token을 소비처의 화면 맥락에 맞춰 선택하기 위한 보조 안내입니다. 필수 읽기는 package root의 `QUICKSTART.md`이며, 이 문서는 token을 직접 고를 때 읽습니다. 정확한 이름과 값은 설치된 버전의 `dist/tokens.json`(`@spectrabrain/eds/tokens.json`)과 `@spectrabrain/eds/tokens`를 기준으로 합니다.
+
+## 색상 역할
+
+| 역할 | 적용 대상 | Tailwind class 패턴 | 선택 기준 |
+| --- | --- | --- | --- |
+| `fg` | 제목, 본문, placeholder, 아이콘, inverted content | `text-eds-fg-*` | 콘텐츠가 전달하는 의미와 대비를 먼저 결정합니다. |
+| `bg` | 페이지, 카드, 입력, 버튼, 상태 surface | `bg-eds-bg-*` | surface의 위계와 interaction state를 결정합니다. |
+| `stroke` | border, divider, focus ring | `border-eds-stroke-*` | 경계의 중요도와 keyboard focus 여부를 결정합니다. |
+
+역할을 고른 뒤 `brand`, `neutral`, `critical`, `informative`, `positive`, `warning`의 의미와 `primary`, `weak`, `disabled`, `hover`, `focus` 상태를 맞춥니다. 색상 취향만으로 역할을 고르지 않습니다.
+
+### 행동 맥락 예시
+
+| 화면 맥락 | 우선 검토할 표현 | 이유 |
+| --- | --- | --- |
+| 생성·저장·관리·확인 같은 화면의 핵심 행동 | `brand`의 primary 표현 | 사용자가 완료해야 할 대표 행동을 분명히 합니다. |
+| 검색·조회·일반적인 주요 실행 | `neutral`의 primary 표현 | 핵심 행동보다 낮은 브랜드 주목도로 일반 행동을 표현합니다. |
+| 취소·닫기·수정 같은 보조 작업 | `neutral`의 outline 표현 | 주 행동과 시각적 위계를 분리합니다. |
+| 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동 | `neutral`의 weak 표현 | 주 행동을 보조하는 반복 가능한 행동을 낮은 위계로 표현합니다. |
+| 되돌리기 어려운 삭제·초기화 | `critical`의 weak 표현 | 위험을 분명히 하고 확인 절차와 함께 사용합니다. |
+| 비동기 처리 중 | 컴포넌트의 `loading` contract | 라벨 공간과 접근성 이름을 유지하면서 중복 실행을 막습니다. |
+
+기존 화면에서 다른 역할이 사용되고 있더라도 새 코드에서는 행동 의미에 맞는 공개 역할을 먼저 검토합니다. exact token이 없으면 `fg/bg/stroke` 역할, 상태, 행동 의미, `neutral` 순서로 가까운 공개 token을 선택합니다.
+
+## Typography
+
+text style은 다섯 속성을 함께 적용하는 preset입니다. `fontFamily`, `fontWeight`, `fontSize`, `lineHeight`, `letterSpacing`을 각각 임의로 조합하지 않습니다.
+
+Tailwind utility는 `eds-typography-*` 패턴으로 사용하며, 설치된 manifest에 있는 preset 이름만 선택합니다. `npm run sync:eds`가 생성하는 `@theme inline`에는 `--font-sans: var(--eds-typography-body1-fontFamily);`가 포함되므로 Tailwind의 `font-sans`와 기본 sans font도 Pretendard가 됩니다. 이 font family는 `@spectrabrain/eds/fonts.css`가 선언합니다.
+
+| 순서 | class 패턴 | 권장 맥락 |
+| --- | --- | --- |
+| Display | `eds-typography-display1`, `eds-typography-display2` | 제품의 큰 메시지와 페이지 진입점입니다. |
+| Heading | `eds-typography-heading1` … `eds-typography-heading4` | 페이지·섹션·그룹의 구조를 나타냅니다. |
+| Title | `eds-typography-title1` … `eds-typography-title4` | 카드·행·대화상자의 핵심 제목과 control label입니다. |
+| Body | `eds-typography-body1` … `eds-typography-body4` | 설명, 입력 안내, 일반 본문입니다. |
+| Caption | `eds-typography-caption1` … `eds-typography-caption3` | 보조 설명, 메타데이터, 짧은 상태 안내입니다. |
+
+한글과 영문이 함께 있는 화면에서도 실제 Pretendard preset을 그대로 사용합니다. 문장의 중요도와 정보 구조를 먼저 판단하고 글자 크기만 임의로 조정하지 않습니다.
+
+## Tailwind className 예시
+
+```tsx
+<section className="bg-eds-bg-neutral-primary text-eds-fg-neutral">
+  <h2 className="eds-typography-heading2 text-eds-fg-neutral">
+    카메라 그룹
+  </h2>
+  <p className="eds-typography-body2 text-eds-fg-neutral-secondary">
+    등록된 장치를 관리합니다.
+  </p>
+  <div className="border border-eds-stroke-neutral-secondary" />
+</section>
+```
+
+새 UI는 위처럼 `className`으로 조합합니다. 컴포넌트별 규칙을 `index.css`에 추가하거나 공개 token의 값을 복사하지 않습니다.
+
+## Spacing과 radius
+
+현재 공개 semantic token에는 소비처용 spacing·radius alias가 없습니다. 소비처 Tailwind의 기본 scale을 사용하고, 기존 scale로 표현할 수 없는 요구가 있을 때만 디자인 시스템 담당자에게 목적과 대체 가능성을 요청합니다.
+
+## 확인 목록
+
+- `@spectrabrain/eds/styles.css`가 Tailwind root CSS에서 한 번만 import되어 있습니다. 개별 파일로 구성했다면 `@spectrabrain/eds/tokens.css`, `@spectrabrain/eds/components.css`, `@spectrabrain/eds/fonts.css`가 함께 import되어 있고 `@spectrabrain/eds/base.css`는 선택입니다. EDS text style이 참조하는 font family는 EDS `fonts.css`가 선언하므로 다른 출처의 Pretendard로 대신하지 않습니다.
+- 생성된 `eds-tokens.css`가 설치된 `dist/tokens.json`의 공개 이름만 참조합니다.
+- 색상은 `fg/bg/stroke` 역할과 상태를 설명할 수 있습니다.
+- typography preset은 다섯 속성을 함께 적용합니다.
+- 새 컴포넌트가 EDS component를 대체 구현하고 있지 않습니다.
+- raw 색상·typography·임의 CSS variable이 새 코드에 없습니다.

package/consumer/cli.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { runDoctor } from "./doctor.mjs";
+import { runInit } from "./init.mjs";
+import { runSync } from "./sync.mjs";
+
+const usage = [
+  "Usage: eds <command> [options]",
+  "",
+  "Commands:",
+  "  init      Register sync:eds, eds:doctor and doctor hooks in package.json, approve the postinstall",
+  "            for the detected package manager (npm 12+ writes allowScripts; others print steps), then run sync",
+  "  sync      Generate src/styles/eds-tokens.css, wire the Tailwind root CSS and update AGENTS.md",
+  "            and the @AGENTS.md import in CLAUDE.md and GEMINI.md when they exist (without a Tailwind root only those change)",
+  "  doctor    Check whether sync is up to date, the EDS font is imported and every eds-* class in the sources",
+  "            is a public token (exit 1 when something is off)",
+  "",
+  "Options:",
+  "  --only tailwind|agents     sync: apply only that part",
+  "  --dry-run                  Print the files sync or init would write without writing them",
+  "  --no-sync                  init: register scripts only",
+  "  --no-allow-scripts         init: do not write allowScripts to package.json on npm 12+",
+  "  --print-ci github|gitlab   init: print a CI job that runs npx eds doctor, then exit",
+  "  --warn                     doctor: report findings but exit 0 (same as EDS_DOCTOR=warn)",
+  "  --scan                     doctor: also list Tailwind palette and arbitrary color classes that bypass the EDS tokens",
+  "  --help                     Show this message",
+  "",
+  "Environment:",
+  "  EDS_TAILWIND_ROOT=src/index.css   Tailwind root CSS when it cannot be detected (needed once: sync records",
+  "                                    it in package.json \"eds\": { \"tailwindRoot\" }, which doctor and the hooks reuse)",
+  "  EDS_DOCTOR=warn|off               Downgrade or silence doctor failures",
+].join("\n");
+
+function parseArguments(argv) {
+  const [command, ...rest] = argv;
+  const options = { only: null, dryRun: false, noSync: false, allowScripts: true, printCi: null, warn: false, scan: false, help: false };
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index];
+    if (argument === "--dry-run") {
+      options.dryRun = true;
+    } else if (argument === "--no-sync") {
+      options.noSync = true;
+    } else if (argument === "--no-allow-scripts") {
+      options.allowScripts = false;
+    } else if (argument === "--warn") {
+      options.warn = true;
+    } else if (argument === "--scan") {
+      options.scan = true;
+    } else if (argument === "--help" || argument === "-h") {
+      options.help = true;
+    } else if (argument === "--only") {
+      index += 1;
+      options.only = rest[index] ?? "";
+    } else if (argument.startsWith("--only=")) {
+      options.only = argument.slice("--only=".length);
+    } else if (argument === "--print-ci") {
+      index += 1;
+      options.printCi = rest[index] ?? "";
+    } else if (argument.startsWith("--print-ci=")) {
+      options.printCi = argument.slice("--print-ci=".length);
+    } else {
+      throw new Error("Unknown option: " + argument);
+    }
+  }
+  return { command, options };
+}
+
+async function main() {
+  const consumerRoot = process.cwd();
+  let parsed;
+  try {
+    parsed = parseArguments(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message + "\n\n" + usage);
+    return 2;
+  }
+  const { command, options } = parsed;
+
+  if (command === "--help" || command === "-h" || options.help) {
+    console.log(usage);
+    return 0;
+  }
+  if (command === "sync") {
+    return runSync({ consumerRoot, only: options.only, dryRun: options.dryRun });
+  }
+  if (command === "doctor") {
+    return runDoctor({ consumerRoot, warn: options.warn, scan: options.scan });
+  }
+  if (command === "init") {
+    return runInit({
+      consumerRoot,
+      noSync: options.noSync,
+      dryRun: options.dryRun,
+      allowScripts: options.allowScripts,
+      printCi: options.printCi,
+    });
+  }
+
+  console.error((command ? "Unknown command: " + command + "\n\n" : "") + usage);
+  return 2;
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  console.error("[EDS] " + (error instanceof Error ? error.message : String(error)));
+  process.exitCode = typeof error?.exitCode === "number" ? error.exitCode : 1;
+}

package/consumer/css-root.mjs

@@ -0,0 +1,239 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  createExitError,
+  detectEol,
+  detectPackageManager,
+  generatedCssRelativePath,
+  listCssFiles,
+  listHtmlFiles,
+  listScriptFiles,
+  readPackageJson,
+  relativeImportPath,
+  relativeTo,
+  runnerCommand,
+  toPosix,
+} from "./paths.mjs";
+
+export const tailwindRootEnvironmentVariable = "EDS_TAILWIND_ROOT";
+// Consumer package.json: "eds": { "tailwindRoot": "src/index.css" }. Written by sync when the override is used.
+export const consumerConfigField = "eds";
+export const tailwindRootConfigKey = "tailwindRoot";
+export const stylesImportLine = '@import "@spectrabrain/eds/styles.css";';
+export const fontsImportLine = '@import "@spectrabrain/eds/fonts.css";';
+
+// Accepts the canonical `@import "tailwindcss";`, the granular `tailwindcss/theme.css` and
+// `tailwindcss/utilities.css` entries (Preflight opt-out) and the `@import url("tailwindcss")` form.
+const tailwindSpecifier = "tailwindcss(?:\\/(?:theme|utilities)(?:\\.css)?)?";
+const tailwindImportSource = "^[ \\t]*@import\\s+(?:url\\(\\s*)?[\"']" + tailwindSpecifier + "[\"']\\s*\\)?[^;]*;[^\\r\\n]*";
+const tailwindImportPattern = new RegExp(tailwindImportSource, "m");
+const tailwindImportPatternGlobal = new RegExp(tailwindImportSource, "gm");
+const cssImportPattern = /^[ \t]*@import\s+(?:url\()?["']([^"']+)["']/gm;
+const scriptImportPattern = /^[ \t]*import\s+["']([^"']+)["']/gm;
+const legacyGeneratedImportPattern = /^[ \t]*import\s+["'][^"']*eds-tokens\.css["'];?[ \t]*(?:\r?\n|$)/gm;
+const cssCommentPattern = /\/\*[\s\S]*?\*\//g;
+const pretendardPattern = /pretendard/i;
+const packageReferencePattern = /@spectrabrain\/eds\//;
+
+// Blanks `/* ... */` comments while keeping every index and line break, so a commented-out import is
+// neither a Tailwind root nor a satisfied EDS import, and match positions still apply to the original.
+export function stripCssComments(contents) {
+  return contents.replace(cssCommentPattern, (comment) => comment.replace(/[^\r\n]/g, " "));
+}
+
+function collectImports(contents, pattern) {
+  return [...contents.matchAll(pattern)].map((match) => match[1]);
+}
+
+function hasTailwindImport(contents) {
+  return tailwindImportPattern.test(stripCssComments(contents));
+}
+
+function readSources(consumerRoot) {
+  const generatedPath = path.join(consumerRoot, generatedCssRelativePath);
+  const css = listCssFiles(consumerRoot)
+    .filter((filePath) => filePath !== generatedPath)
+    .map((filePath) => ({ path: filePath, contents: fs.readFileSync(filePath, "utf8") }));
+  const scripts = listScriptFiles(consumerRoot)
+    .map((filePath) => ({ path: filePath, contents: fs.readFileSync(filePath, "utf8") }));
+  const html = listHtmlFiles(consumerRoot)
+    .map((filePath) => ({ path: filePath, contents: fs.readFileSync(filePath, "utf8") }));
+  return { generatedPath, css, scripts, html };
+}
+
+export function readConfiguredTailwindRoot(consumerRoot) {
+  const configured = readPackageJson(consumerRoot)?.[consumerConfigField]?.[tailwindRootConfigKey];
+  if (configured === undefined || configured === null) {
+    return null;
+  }
+  if (typeof configured !== "string" || configured.trim() === "") {
+    throw createExitError("package.json " + consumerConfigField + "." + tailwindRootConfigKey + " must be a relative path string, for example \"src/index.css\".", 2);
+  }
+  return configured;
+}
+
+function resolveExplicitRoot(consumerRoot, relative, { source, label, remedy }) {
+  const rootPath = path.resolve(consumerRoot, relative);
+  if (!fs.existsSync(rootPath) || !fs.statSync(rootPath).isFile()) {
+    throw createExitError(label + " does not point to an existing file: " + relative + ". " + remedy, 2);
+  }
+  const contents = fs.readFileSync(rootPath, "utf8");
+  const relativePath = relativeTo(consumerRoot, rootPath);
+  return {
+    path: rootPath,
+    relativePath,
+    contents,
+    source,
+    warning: hasTailwindImport(contents)
+      ? null
+      : relativePath + ' does not import "tailwindcss"; EDS imports will be inserted at the top of the file.',
+  };
+}
+
+// Resolution order: EDS_TAILWIND_ROOT, then package.json eds.tailwindRoot, then auto-detection.
+// Returns null when the consumer has no Tailwind root at all: sync then skips the Tailwind wiring.
+// Two or more candidates and an explicit path that does not exist still exit 2.
+export function findTailwindRoot(
+  consumerRoot,
+  env = process.env,
+  sources = readSources(consumerRoot),
+  packageManager = detectPackageManager(consumerRoot, env),
+) {
+  const override = env[tailwindRootEnvironmentVariable];
+  if (override) {
+    return resolveExplicitRoot(consumerRoot, override, {
+      source: "env",
+      label: tailwindRootEnvironmentVariable,
+      remedy: "Point it at the CSS file that imports tailwindcss.",
+    });
+  }
+
+  const configured = readConfiguredTailwindRoot(consumerRoot);
+  if (configured !== null) {
+    return resolveExplicitRoot(consumerRoot, toPosix(configured), {
+      source: "config",
+      label: "package.json " + consumerConfigField + "." + tailwindRootConfigKey,
+      remedy: "Update or remove that key, or run " + tailwindRootEnvironmentVariable + "=<file> " +
+        runnerCommand(packageManager, "sync:eds") + " once to record the new path.",
+    });
+  }
+
+  const candidates = sources.css.filter((file) => hasTailwindImport(file.contents));
+  if (candidates.length === 0) {
+    return null;
+  }
+  if (candidates.length > 1) {
+    const found = candidates.map((file) => relativeTo(consumerRoot, file.path));
+    throw createExitError(
+      "Could not identify one Tailwind root CSS file (found " + found.length + ": " + found.join(", ") + "). " +
+        "Set " + tailwindRootEnvironmentVariable + ", for example " +
+        tailwindRootEnvironmentVariable + "=src/index.css " + runnerCommand(packageManager, "sync:eds") + ". " +
+        "sync records the choice in package.json as \"" + consumerConfigField + "\": { \"" + tailwindRootConfigKey +
+        "\": \"src/index.css\" } so doctor and the hooks reuse it.",
+      2,
+    );
+  }
+
+  const [root] = candidates;
+  return { path: root.path, relativePath: relativeTo(consumerRoot, root.path), contents: root.contents, source: "detected", warning: null };
+}
+
+export function importsPackageFile(sources, fileName) {
+  const pattern = new RegExp("^@spectrabrain/eds/" + fileName.replace(".", "\\.") + "$");
+  const cssHit = sources.css.some((file) => collectImports(stripCssComments(file.contents), cssImportPattern).some((entry) => pattern.test(entry)));
+  const scriptHit = sources.scripts.some((file) => collectImports(file.contents, scriptImportPattern).some((entry) => pattern.test(entry)));
+  return cssHit || scriptHit;
+}
+
+// EDS text styles reference the font family "Pretendard" from fonts.css, so a consumer that opts out of
+// styles.css must import tokens.css, components.css and fonts.css. Returns the import lines still missing.
+export function planPackageImports(sources) {
+  const hasStyles = importsPackageFile(sources, "styles.css");
+  const hasTokensAndComponents = importsPackageFile(sources, "tokens.css") && importsPackageFile(sources, "components.css");
+  const hasFonts = importsPackageFile(sources, "fonts.css");
+  if (!hasStyles && !hasTokensAndComponents) {
+    return [stylesImportLine];
+  }
+  if (!hasStyles && !hasFonts) {
+    return [fontsImportLine];
+  }
+  return [];
+}
+
+// Files (other than the EDS imports themselves) that mention Pretendard: a CDN link, a second @font-face
+// or a font-family declaration. Reported by doctor as a note only.
+export function findPretendardReferences(consumerRoot, sources) {
+  return [...sources.html, ...sources.css]
+    .filter((file) => file.contents.split(/\r?\n/).some((line) => pretendardPattern.test(line) && !packageReferencePattern.test(line)))
+    .map((file) => relativeTo(consumerRoot, file.path));
+}
+
+function importsGeneratedFile(root, generatedPath) {
+  return collectImports(stripCssComments(root.contents), cssImportPattern).some((specifier) => {
+    if (!specifier.startsWith(".")) {
+      return false;
+    }
+    return path.resolve(path.dirname(root.path), specifier) === generatedPath;
+  });
+}
+
+// End index of the last Tailwind import line (comments ignored), or null. With granular imports the EDS
+// lines go after the last one so they follow both theme.css and utilities.css.
+function lastTailwindImportEnd(contents) {
+  let end = null;
+  for (const match of stripCssComments(contents).matchAll(tailwindImportPatternGlobal)) {
+    end = match.index + match[0].length;
+  }
+  return end;
+}
+
+export function planCssRootImports({ consumerRoot, root, sources }) {
+  const generatedPath = sources.generatedPath;
+  const generatedImportLine = '@import "' + relativeImportPath(root.path, generatedPath) + '";';
+  const missing = planPackageImports(sources);
+  if (!importsGeneratedFile(root, generatedPath)) {
+    missing.push(generatedImportLine);
+  }
+
+  const eol = detectEol(root.contents);
+  let after = root.contents;
+  if (missing.length > 0) {
+    const lineEnd = lastTailwindImportEnd(root.contents);
+    if (lineEnd !== null) {
+      const lineBreak = root.contents.slice(lineEnd, lineEnd + eol.length) === eol ? eol : "";
+      const inserted = missing.join(eol);
+      after = root.contents.slice(0, lineEnd) + eol + inserted + (lineBreak ? "" : eol) + root.contents.slice(lineEnd);
+    } else {
+      after = missing.join(eol) + eol + root.contents;
+    }
+  }
+
+  return {
+    label: "css-root",
+    path: root.path,
+    relativePath: relativeTo(consumerRoot, root.path),
+    before: root.contents,
+    after,
+    missing,
+  };
+}
+
+export function planLegacyJsImportCleanup({ consumerRoot }) {
+  const sourceDirectory = path.join(consumerRoot, "src");
+  return listScriptFiles(sourceDirectory).flatMap((filePath) => {
+    const before = fs.readFileSync(filePath, "utf8");
+    const after = before.replace(legacyGeneratedImportPattern, "");
+    if (after === before) {
+      return [];
+    }
+    return [{
+      label: "legacy-js-import",
+      path: filePath,
+      relativePath: relativeTo(consumerRoot, filePath),
+      before,
+      after,
+    }];
+  });
+}
+
+export { readSources };

package/consumer/doctor.mjs

@@ -0,0 +1,178 @@
+import { findPretendardReferences, planPackageImports, stylesImportLine, fontsImportLine } from "./css-root.mjs";
+import { readGeneratedVersion } from "./generate-tailwind.mjs";
+import { legacyVersionLabel } from "./managed-block.mjs";
+import { generatedCssRelativePath, normalizeEol, readJson, readPackageJson, runnerCommand, toPosix } from "./paths.mjs";
+import { doctorCommand, doctorScriptName, isCompatibleCommand, syncCommand, syncScriptName } from "./register-scripts.mjs";
+import { scanClassNames } from "./scan-classes.mjs";
+import { collectPlans, noTailwindNote } from "./sync.mjs";
+
+export const doctorEnvironmentVariable = "EDS_DOCTOR";
+
+const fontGuidance = {
+  [stylesImportLine]: "missing: @spectrabrain/eds/styles.css import in CSS or JS (or tokens.css + components.css + fonts.css); EDS text styles need the bundled Pretendard font",
+  [fontsImportLine]: "missing: @spectrabrain/eds/fonts.css import next to tokens.css and components.css; EDS text styles reference the font family \"Pretendard\" from fonts.css",
+};
+
+export function collectFindings({ consumerRoot, env = process.env }) {
+  const plans = collectPlans({ consumerRoot, env });
+  const installed = plans.pkg.version;
+  const generatedRelativePath = toPosix(generatedCssRelativePath);
+  const findings = [];
+  const notes = [];
+  let rawColors = null;
+
+  const scripts = readPackageJson(consumerRoot)?.scripts ?? {};
+  for (const [name, command] of [[syncScriptName, syncCommand], [doctorScriptName, doctorCommand]]) {
+    if (isCompatibleCommand(scripts[name], command)) {
+      continue;
+    }
+    findings.push(
+      scripts[name] === undefined
+        ? "scripts: " + name + " is not registered; run npx @spectrabrain/eds init"
+        : "scripts: " + name + " runs " + JSON.stringify(scripts[name]) + " instead of \"" + command +
+          "\"; rename that script and run npx @spectrabrain/eds init, or make it run \"" + command + "\"",
+    );
+  }
+  // The fix line may only point at sync:eds when that script really runs eds sync.
+  const syncRegistered = isCompatibleCommand(scripts[syncScriptName], syncCommand);
+
+  if (plans.root === null) {
+    notes.push(noTailwindNote);
+    // Without a Tailwind root, sync cannot insert the imports, so doctor states the requirement directly.
+    for (const line of planPackageImports(plans.sources)) {
+      findings.push(fontGuidance[line]);
+    }
+  } else {
+    if (plans.tailwind.before === null) {
+      findings.push("missing: " + generatedRelativePath);
+    } else if (normalizeEol(plans.tailwind.before) !== normalizeEol(plans.tailwind.after)) {
+      // Line endings are ignored: an autocrlf checkout of the LF generated file is not stale.
+      const generatedBy = readGeneratedVersion(plans.tailwind.before);
+      findings.push(
+        generatedBy === null
+          ? "stale: " + generatedRelativePath + " has no @spectrabrain/eds version header (installed " + installed + ")"
+          : generatedBy === installed
+            ? "stale: " + generatedRelativePath + " differs from the output of @spectrabrain/eds@" + installed
+            : "stale: " + generatedRelativePath + " was generated by @spectrabrain/eds@" + generatedBy + " (installed " + installed + ")",
+      );
+    }
+
+    for (const line of plans.cssRoot.missing) {
+      findings.push("missing: " + line + " in " + plans.cssRoot.relativePath);
+    }
+
+    for (const write of plans.legacyImports) {
+      findings.push("legacy: " + write.relativePath + " imports eds-tokens.css from JavaScript (Tailwind cannot compile it)");
+    }
+
+    // Tailwind drops a class no token backs without a word, so an unknown eds-* name is always a finding.
+    const classScan = scanClassNames({
+      consumerRoot,
+      manifest: readJson(plans.pkg.resolve("tokens.json")),
+      files: [...plans.sources.scripts, ...plans.sources.css, ...plans.sources.html],
+    });
+    for (const hit of classScan.unknown) {
+      findings.push("unknown: " + hit.location + " " + hit.className + " is not a public EDS class; check tokens.json or " + generatedRelativePath);
+    }
+    rawColors = classScan.raw;
+  }
+
+  for (const filePath of findPretendardReferences(consumerRoot, plans.sources)) {
+    notes.push(filePath + " references Pretendard outside @spectrabrain/eds; EDS text styles use the bundled font, so the extra font source can be removed.");
+  }
+
+  for (const error of plans.errors) {
+    findings.push("invalid: " + error.message);
+  }
+  if (plans.agents) {
+    if (plans.agents.existingBlock === null) {
+      findings.push("missing: AGENTS.md managed block");
+    } else if (normalizeEol(plans.agents.existingBlock) !== normalizeEol(plans.agents.block)) {
+      const blockVersion = plans.agents.existingVersion ?? legacyVersionLabel;
+      findings.push(
+        blockVersion === installed
+          ? "stale: AGENTS.md managed block differs from @spectrabrain/eds@" + installed
+          : "stale: AGENTS.md managed block is for " + blockVersion + " (installed " + installed + ")",
+      );
+    }
+  }
+
+  if (plans.claude && normalizeEol(plans.claude.before) !== normalizeEol(plans.claude.after)) {
+    findings.push("missing: @AGENTS.md import in CLAUDE.md");
+  }
+  if (plans.gemini && normalizeEol(plans.gemini.before) !== normalizeEol(plans.gemini.after)) {
+    findings.push("missing: @./AGENTS.md import in GEMINI.md");
+  }
+
+  return { plans, findings, notes, installed, generatedRelativePath, syncRegistered, rawColors };
+}
+
+const rawColorLineLimit = 40;
+
+// --scan lists the classes that bypass the EDS tokens. It never changes the exit code: legacy code may keep them.
+function logRawColors(rawColors, log) {
+  if (rawColors === null) {
+    log("[EDS] scan: skipped (no Tailwind root)");
+    return;
+  }
+  if (rawColors.length === 0) {
+    log("[EDS] scan: no raw color classes found");
+    return;
+  }
+  const files = new Set(rawColors.map((hit) => hit.location.split(":")[0]));
+  log(
+    "[EDS] scan: " + rawColors.length + " raw color class" + (rawColors.length === 1 ? "" : "es") + " in " + files.size +
+      " file" + (files.size === 1 ? "" : "s") + " bypass the EDS tokens (informational; prefer text-eds-fg-*, bg-eds-bg-*, border-eds-stroke-*)",
+  );
+  for (const hit of rawColors.slice(0, rawColorLineLimit)) {
+    log("[EDS] raw: " + hit.location + " " + hit.className);
+  }
+  if (rawColors.length > rawColorLineLimit) {
+    log("[EDS] raw: … " + (rawColors.length - rawColorLineLimit) + " more");
+  }
+}
+
+export function runDoctor({ consumerRoot, env = process.env, warn = false, scan = false, log = console.log }) {
+  const mode = env[doctorEnvironmentVariable];
+  if (mode === "off") {
+    return 0;
+  }
+  const downgrade = warn || mode === "warn";
+
+  let result;
+  try {
+    result = collectFindings({ consumerRoot, env });
+  } catch (error) {
+    log("[EDS] " + error.message);
+    if (error.exitCode === 2) {
+      return downgrade ? 0 : 2;
+    }
+    throw error;
+  }
+
+  for (const note of result.notes) {
+    log("[EDS] note: " + note);
+  }
+  if (scan) {
+    logRawColors(result.rawColors, log);
+  }
+
+  if (result.findings.length === 0) {
+    const syncedPaths = result.plans.root === null
+      ? ["AGENTS.md"]
+      : [result.plans.root.relativePath, result.generatedRelativePath, "AGENTS.md"];
+    log("[EDS] synced with @spectrabrain/eds@" + result.installed + ": " + syncedPaths.join(", "));
+    return 0;
+  }
+
+  for (const finding of result.findings) {
+    log("[EDS] " + finding);
+  }
+  const fixCommand = result.syncRegistered ? runnerCommand(result.plans.packageManager, syncScriptName) : "npx eds sync";
+  log(
+    "[EDS] Run " + fixCommand + " to fix. (" +
+      doctorEnvironmentVariable + "=warn or eds doctor --warn downgrades this to a warning.)",
+  );
+  log("[EDS] Then read the AGENTS.md managed block and QUICKSTART.md in the package root before UI work.");
+  return downgrade ? 0 : 1;
+}

package/consumer/generate-tailwind.mjs

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { generatedCssRelativePath, readJson, readTextIfExists, relativeTo } from "./paths.mjs";
+
+const propertyNames = [
+  "fontFamily",
+  "fontWeight",
+  "fontSize",
+  "lineHeight",
+  "letterSpacing",
+];
+
+export const fontSansStyleName = "body1";
+export function renderTailwindCss(manifest, version) {
+  const tokens = Object.keys(manifest.tokens ?? {});
+  const colorNames = tokens.filter((name) => name.startsWith("color-"));
+  const typography = new Map();
+
+  for (const name of tokens.filter((entry) => entry.startsWith("typography-"))) {
+    const match = name.match(/^typography-(.+)-(fontFamily|fontWeight|fontSize|lineHeight|letterSpacing)$/);
+    if (!match) {
+      throw new Error(`Unsupported typography token name: ${name}`);
+    }
+
+    const [, styleName, propertyName] = match;
+    const properties = typography.get(styleName) ?? new Set();
+    properties.add(propertyName);
+    typography.set(styleName, properties);
+  }
+
+  for (const [styleName, properties] of typography) {
+    for (const propertyName of propertyNames) {
+      if (!properties.has(propertyName)) {
+        throw new Error(`Typography preset ${styleName} is missing ${propertyName}.`);
+      }
+    }
+  }
+
+  if (!typography.has(fontSansStyleName)) {
+    throw new Error(`Typography preset ${fontSansStyleName} is required for --font-sans.`);
+  }
+
+  const colorAliases = colorNames
+    .map((name) => `  --color-eds-${name.slice("color-".length)}: var(--eds-${name});`)
+    .join("\n");
+  // Last line of the @theme block: Tailwind's default font family becomes the EDS body font.
+  const fontSans = `  --font-sans: var(--eds-typography-${fontSansStyleName}-fontFamily);`;
+  const typographyUtilities = [...typography.keys()].sort().map((styleName) => [
+    `@utility eds-typography-${styleName} {`,
+    `  font-family: var(--eds-typography-${styleName}-fontFamily);`,
+    `  font-weight: var(--eds-typography-${styleName}-fontWeight);`,
+    `  font-size: var(--eds-typography-${styleName}-fontSize);`,
+    `  line-height: var(--eds-typography-${styleName}-lineHeight);`,
+    `  letter-spacing: var(--eds-typography-${styleName}-letterSpacing);`,
+    `}`,
+  ].join("\n")).join("\n\n");
+
+  return [
+    `/* Generated from @spectrabrain/eds@${version}. Do not edit manually. */`,
+    "@theme inline {",
+    colorAliases,
+    fontSans,
+    "}",
+    "",
+    typographyUtilities,
+    "",
+  ].join("\n");
+}
+
+export function readGeneratedVersion(contents) {
+  return contents.match(/^\/\* Generated from @spectrabrain\/eds@(\S+)\. Do not edit manually\. \*\//m)?.[1] ?? null;
+}
+
+export function planTailwind({ consumerRoot, pkg }) {
+  const manifest = readJson(pkg.resolve("tokens.json"));
+  const filePath = path.join(consumerRoot, generatedCssRelativePath);
+  return {
+    label: "tailwind",
+    path: filePath,
+    relativePath: relativeTo(consumerRoot, filePath),
+    before: readTextIfExists(filePath),
+    after: renderTailwindCss(manifest, pkg.version),
+  };
+}