@spectrabrain/eds 0.0.4 → 0.1.1

package/TAILWIND_V4.md

@@ -1,284 +1,98 @@
-# EVA token을 Tailwind CSS v4에서 사용하는 가이드
+# EDS token을 Tailwind CSS v4에서 쓰는 방법
 
-이 문서는 소비처가 `@spectrabrain/eds`의 공개 semantic token을 Tailwind CSS v4의 `className`으로 사용하는 방법을 안내합니다. EDS는 Tailwind utility API를 패키지에 포함하지 않으며, 소비처에서 공개 CSS variable을 Tailwind theme alias와 utility로 연결해 사용합니다.
+Tailwind CSS v4 저장소에서 `eds sync`가 공개 token을 `text-eds-*`·`bg-eds-*`·`border-eds-*`·`eds-typography-*` class로 쓸 수 있게 연결하는 설정 절차입니다. 필수 규칙은 package root의 `QUICKSTART.md`에, class를 고르는 기준은 `TOKEN_CONTEXT.md`에 있습니다.
 
-이 가이드는 token만 연결하는 경우를 다룹니다. React 컴포넌트의 구현이나 컴포넌트별 스타일을 변경하지 않습니다.
+## 공개 경로
 
-## 공개 범위
+CSS 진입점은 `@spectrabrain/eds/styles.css` 하나를 권장합니다. 개별 파일(`@spectrabrain/eds/tokens.css`, `@spectrabrain/eds/components.css`, `@spectrabrain/eds/fonts.css`, 선택 `@spectrabrain/eds/base.css`)의 구성 규칙은 `CONSUMER_AGENT.md` 「font 정책」에 있습니다. 전체 공개 경로는 `README.md`의 「공개 경로」 표에 있으며, 그 밖의 패키지 내부 경로와 token 값은 소비처에 복사하지 않습니다.
 
-소비처는 다음 공개 경로만 사용합니다.
+## 설정 순서
 
-| 경로 | 용도 |
-| --- | --- |
-| `@spectrabrain/eds/tokens.css` | semantic CSS variable을 불러옵니다. |
-| `@spectrabrain/eds/fonts.css` | Pretendard font를 불러옵니다. 선택 사항입니다. |
-| `@spectrabrain/eds/tokens.json` | 공개 token 이름과 타입을 도구에서 확인합니다. |
-| `@spectrabrain/eds/tokens` | TypeScript token 이름과 `cssVar()`를 사용합니다. |
+1. 「adapter 선택」 표에서 저장소에 맞는 행 하나를 골라 설치하고 연결합니다.
+2. 앱의 전역 CSS 파일 하나에 `@import "tailwindcss";`를 둡니다. 이 파일이 Tailwind root이며, 이미 있으면 새로 만들지 않습니다.
+3. `npm run sync:eds`를 실행합니다. script가 없으면 `npx @spectrabrain/eds init`을 실행합니다(패키지 매니저별 명령은 `CONSUMER_AGENT.md` 「첫 setup 절차」). init을 2단계보다 먼저 실행했다면 2단계 뒤에 sync를 다시 실행합니다.
+4. 「완료 기준」을 확인합니다.
 
-공개되지 않은 내부 token 원본이나 raw 값을 소비처에 복사하지 않습니다.
+CSS가 `@tailwind` 지시어를 쓰는 Tailwind CSS v3 저장소는 이 절차 대신 `CONSUMER_AGENT.md` 「Tailwind root 결정」을 따릅니다.
 
-## 사전 조건
+## adapter 선택
 
-- React 웹 프로젝트입니다.
-- Tailwind CSS v4를 사용합니다.
-- 프로젝트의 framework와 bundler가 확인되어 있습니다.
-- 전역 CSS 진입점이 하나 지정되어 있습니다.
+명령은 npm 기준이며 다른 패키지 매니저는 그 add 명령을 씁니다.
 
-## 설치
-
-기본 패키지를 설치합니다. Tailwind adapter는 프로젝트의 빌드 방식에 맞는 하나만 선택합니다.
-
-~~~sh
-npm install @spectrabrain/eds
-~~~
-
-Vite 프로젝트는 Tailwind Vite adapter를 추가합니다.
-
-~~~sh
-npm install -D tailwindcss @tailwindcss/vite
-~~~
-
-PostCSS 기반 프로젝트는 PostCSS adapter를 추가합니다.
-
-~~~sh
-npm install -D tailwindcss @tailwindcss/postcss postcss
-~~~
-
-이미 설치된 패키지는 중복 설치하지 않으며 Vite adapter와 PostCSS adapter를 동시에 추가하지 않습니다.
-
-## 설치 시 자동화 정책
-
-EDS는 `npm install`의 `postinstall`에서 소비처의 CSS나 설정 파일을 수정하지 않습니다. 설치 스크립트가 파일을 덮어쓰면 소비처의 기존 Tailwind 설정, CI 정책, package manager 설정과 충돌할 수 있기 때문입니다.
-
-token alias를 EDS 버전과 함께 자동 갱신하려면 소비처 저장소가 다음 작업을 소유하는 명시적인 생성 스크립트를 둡니다.
-
-1. `@spectrabrain/eds/tokens.json`에서 token 이름만 읽습니다.
-2. `color-*` token을 `var(--eds-...)`로 연결하는 `@theme inline` 블록을 생성합니다.
-3. raw `$value`나 비공개 파일 경로는 생성물에 기록하지 않습니다.
-4. `npm run generate:eds-tailwind`처럼 명시적으로 실행하고, 필요할 때만 소비처의 `postinstall` 또는 CI에 연결합니다.
-
-설치 스크립트를 사용하지 않는 환경에서도 동작하도록 생성된 `eds-tokens.css`는 저장소에 두거나 CI에서 재생성합니다. 현재 EDS가 제공하는 자동화 범위는 공개 token manifest와 이 설치 가이드이며, 소비처 파일을 직접 변경하는 CLI는 제공하지 않습니다.
-
-다음은 소비처가 소유할 수 있는 color alias 생성 스크립트 예시입니다. 이 스크립트는 token의 실제 값을 읽지 않고 공개 이름만 읽습니다.
-
-~~~js
-// scripts/generate-eds-tailwind.mjs
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-
-const require = createRequire(import.meta.url);
-const manifestPath = require.resolve("@spectrabrain/eds/tokens.json");
-const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-const colorNames = Object.keys(manifest.tokens).filter((name) => name.startsWith("color-"));
-const aliases = colorNames
-  .map((name) => `  --color-eds-${name.slice("color-".length)}: var(--eds-${name});`)
-  .join("\n");
-const output = `@theme inline {\n${aliases}\n}\n`;
-const outputPath = path.resolve("src/styles/eds-tokens.css");
-
-fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-fs.writeFileSync(outputPath, output);
-~~~
-
-소비처의 `package.json`에는 기존 script를 덮어쓰지 않는 범위에서 다음 명령을 추가할 수 있습니다.
-
-~~~json
-{
-  "scripts": {
-    "generate:eds-tailwind": "node scripts/generate-eds-tailwind.mjs"
-  }
-}
-~~~
-
-`postinstall`에 연결하려면 소비처의 보안·CI 정책이 허용하는 경우에만 기존 `postinstall` 뒤에 `npm run generate:eds-tailwind`를 추가합니다. 설치 시 script 실행이 차단된 환경도 고려해 생성 파일을 커밋하거나 CI에서 `generate:eds-tailwind`를 먼저 실행합니다.
-
-## Tailwind v4 연결
-
-### Vite
+| 저장소 | 설치 | 연결 |
+| --- | --- | --- |
+| `vite.config.*`가 있음 | `npm install -D tailwindcss @tailwindcss/vite` | `vite.config`의 `plugins`에 `tailwindcss()`를 추가합니다. `postcss.config.*`에 `@tailwindcss/postcss` 항목이 있으면 그 항목과 devDependency를 지웁니다. |
+| `vite.config.*` 없이 PostCSS를 씀 | `npm install -D tailwindcss @tailwindcss/postcss postcss` | PostCSS 설정의 `plugins`에 `"@tailwindcss/postcss": {}`를 추가합니다. |
 
-`vite.config.ts`의 기존 plugins를 유지하면서 `tailwindcss()`를 추가합니다.
+Vite에서 `@tailwindcss/postcss`로 빌드하면 import한 EDS CSS의 상대 `url()`이 옮겨지지 않아 `fonts.css`의 Pretendard 파일이 번들에 들어가지 않습니다. 기존 framework plugin과 Tailwind 외 PostCSS plugin은 유지합니다.
 
-~~~ts
+```ts
+import react from "@vitejs/plugin-react"; // 기존 import는 유지합니다.
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  plugins: [tailwindcss()],
+  // 기존 설정(server.proxy, resolve.alias 등)은 그대로 둡니다.
+  plugins: [react(), tailwindcss()], // 기존 plugin 배열 끝에 tailwindcss()만 추가합니다.
 });
-~~~
-
-기존 React plugin 등 다른 plugin은 제거하지 않습니다.
+```
 
-### PostCSS
+`vite.config.*`가 없는 저장소의 PostCSS 설정은 다음과 같습니다.
 
-`postcss.config.mjs`의 기존 설정을 유지하면서 adapter를 추가합니다.
-
-~~~js
+```js
 export default {
   plugins: {
+    // 기존 plugin 항목에 추가합니다.
     "@tailwindcss/postcss": {},
   },
 };
-~~~
+```
 
-## 전역 CSS 설정
+## sync가 만드는 것
 
-기존 전역 CSS 파일을 사용합니다. 중복 stylesheet를 만들지 않습니다.
+sync는 설치된 package의 공개 `@spectrabrain/eds/tokens.json`에서 token 이름만 읽어 `src/styles/eds-tokens.css`를 생성하고, Tailwind root의 마지막 Tailwind import 바로 다음 줄에 `@spectrabrain/eds/styles.css`와 `eds-tokens.css`의 `@import`를 한 번씩 추가합니다. `tailwindcss/theme.css`와 `tailwindcss/utilities.css`를 따로 불러오는 root에서는 `utilities.css` 다음 줄입니다. 생성 CSS의 상대 경로는 root 위치에 맞춰 sync가 계산하므로 경로를 직접 쓰지 않습니다. `src/index.css`가 root이면 다음과 같습니다.
 
-~~~css
+```css
 @import "tailwindcss";
-@import "@spectrabrain/eds/tokens.css";
-@import "./eds-tokens.css";
-~~~
-
-Pretendard font도 사용하려면 `eds-tokens.css`보다 앞이나 뒤에 다음 import를 추가합니다.
-
-~~~css
-@import "@spectrabrain/eds/fonts.css";
-~~~
-
-`tokens.css`는 token variable만 제공하며 애플리케이션의 font-family를 자동으로 지정하지 않습니다.
-
-## Color token alias
+@import "@spectrabrain/eds/styles.css";
+@import "./styles/eds-tokens.css";
+```
 
-`eds-tokens.css`에 공개 semantic color variable을 Tailwind theme alias로 연결합니다. `@theme inline`을 사용해야 EDS CSS variable 참조가 유지됩니다.
+생성 CSS의 color alias는 공개 color token마다 한 줄씩 생기며, 형태는 다음과 같습니다.
 
-~~~css
+```css
+/* Generated from @spectrabrain/eds@<version>. Do not edit manually. */
 @theme inline {
   --color-eds-fg-brand: var(--eds-color-fg-brand);
-  --color-eds-fg-neutral: var(--eds-color-fg-neutral);
-  --color-eds-fg-neutral-secondary: var(--eds-color-fg-neutral-secondary);
-  --color-eds-fg-neutral-inverted: var(--eds-color-fg-neutral-inverted);
-
-  --color-eds-bg-brand-primary: var(--eds-color-bg-brand-primary);
-  --color-eds-bg-brand-primary-hover: var(--eds-color-bg-brand-primary-hover);
-  --color-eds-bg-neutral-primary: var(--eds-color-bg-neutral-primary);
-  --color-eds-bg-neutral-primary-hover: var(--eds-color-bg-neutral-primary-hover);
-  --color-eds-bg-neutral-weak: var(--eds-color-bg-neutral-weak);
-  --color-eds-bg-disabled: var(--eds-color-bg-disabled);
-
-  --color-eds-stroke-neutral-secondary: var(--eds-color-stroke-neutral-secondary);
-  --color-eds-stroke-focusRing: var(--eds-color-stroke-focusRing);
+  --font-sans: var(--eds-typography-body1-fontFamily);
 }
-~~~
-
-다음 규칙으로 추가 alias를 작성합니다.
-
-| EDS token | Tailwind alias | 생성되는 utility 예시 |
-| --- | --- | --- |
-| `color-fg-brand` | `--color-eds-fg-brand` | `text-eds-fg-brand` |
-| `color-bg-brand-primary` | `--color-eds-bg-brand-primary` | `bg-eds-bg-brand-primary` |
-| `color-stroke-neutral-secondary` | `--color-eds-stroke-neutral-secondary` | `border-eds-stroke-neutral-secondary` |
-
-사용 예시는 다음과 같습니다.
-
-~~~tsx
-<div className="bg-eds-bg-neutral-primary text-eds-fg-neutral border border-eds-stroke-neutral-secondary">
-  콘텐츠입니다.
-</div>
-~~~
 
-상태별 표현에는 semantic hover token을 사용합니다.
-
-~~~tsx
-<a className="text-eds-fg-brand hover:text-eds-fg-brand-contrast" href="/details">
-  자세히 보기
-</a>
-~~~
-
-## Typography preset utility
-
-EDS typography preset은 font family, weight, size, line height, letter spacing을 함께 적용합니다. Tailwind의 `text-*` theme variable만으로는 다섯 속성을 하나의 preset으로 묶을 수 없으므로 `@utility`를 사용합니다.
-
-~~~css
-@utility eds-typography-title3 {
-  font-family: var(--eds-typography-title3-fontFamily);
-  font-weight: var(--eds-typography-title3-fontWeight);
-  font-size: var(--eds-typography-title3-fontSize);
-  line-height: var(--eds-typography-title3-lineHeight);
-  letter-spacing: var(--eds-typography-title3-letterSpacing);
+@utility eds-typography-body2 {
+  font-family: var(--eds-typography-body2-fontFamily);
+  font-weight: var(--eds-typography-body2-fontWeight);
+  font-size: var(--eds-typography-body2-fontSize);
+  line-height: var(--eds-typography-body2-lineHeight);
+  letter-spacing: var(--eds-typography-body2-letterSpacing);
 }
-~~~
-
-다음 preset을 같은 규칙으로 제공합니다.
-
-~~~text
-display1, display2
-heading1, heading2, heading3, heading4
-title1, title2, title3, title4
-body1, body2, body3, body4
-caption1, caption2, caption3
-~~~
-
-사용 예시는 다음과 같습니다.
-
-~~~tsx
-<h1 className="eds-typography-heading1 text-eds-fg-neutral">
-  제목입니다.
-</h1>
-
-<p className="eds-typography-body2 text-eds-fg-neutral-secondary">
-  본문입니다.
-</p>
-~~~
-
-## Spacing과 radius
-
-현재 공개 semantic token에 없는 spacing·radius 값을 소비처에서 임의로 alias로 만들지 않습니다. 공개 token이 필요한 경우 다음 정보를 디자인 시스템 담당자에게 요청합니다.
-
-- 필요한 token 이름입니다.
-- 사용하려는 UI 목적입니다.
-- 필요한 상태나 variant입니다.
-- 기존 Tailwind scale로 대체할 수 없는 이유입니다.
-
-내부 파일 경로를 참조하거나 raw 값을 복사해 `spacing-eds-*`, `radius-eds-*` utility를 만들지 않습니다.
-
-## TypeScript token 자동완성
-
-CSS가 아닌 CSS-in-JS 또는 inline style에서 token을 선택해야 하면 공개 TypeScript API를 사용합니다.
-
-~~~ts
-import { cssVar, type SemanticTokenName } from "@spectrabrain/eds/tokens";
-
-const token: SemanticTokenName = "color-fg-brand";
-const color = cssVar(token);
-// var(--eds-color-fg-brand)
-~~~
-
-`SemanticTokenName`은 공개 semantic token 이름 자동완성을 제공합니다. token 값 자체를 복사해 스타일에 넣지 않고 `cssVar()` 결과를 사용합니다.
-
-## 권장 파일 구조
-
-~~~text
-src/styles/
-  globals.css
-  eds-tokens.css
-~~~
-
-`globals.css`에서 `tailwindcss`, EDS token CSS, `eds-tokens.css`를 한 번씩 import합니다. alias와 typography utility는 `eds-tokens.css`에서 관리합니다.
+```
 
-token 목록이 많거나 EDS 버전 변경 때 자동 갱신이 필요하면 `@spectrabrain/eds/tokens.json`의 token 이름과 CSS variable 이름만 읽어 alias 파일을 생성할 수 있습니다. 생성 스크립트에는 raw `$value`를 포함하지 않습니다.
+- `--font-sans`는 `@theme inline`의 마지막 줄이며 Tailwind의 기본 sans font를 EDS body1 font family로 바꿉니다.
+- `@theme`의 EDS alias는 sync가 생성한 `var(--eds-*)` 참조만 두고, EDS를 업데이트할 때마다 `npm run sync:eds`로 다시 생성합니다.
+- `eds-tokens.css`는 `@theme`·`@utility`를 담으므로 Tailwind root CSS에서만 import합니다. `@spectrabrain/eds/styles.css`와 `eds-tokens.css`는 각각 한 곳에서만 import합니다.
+- `src/styles/eds-tokens.css`는 생성물이지만 저장소에 commit합니다. install은 이 파일을 만들지 않으므로, 파일이 없으면 Tailwind root의 `@import`가 깨지고, `pretypecheck`·`prebuild` hook(yarn berry는 `typecheck`·`build` 앞의 `eds doctor`)과 `--print-ci` CI job의 `eds doctor`가 `missing:`으로 실패합니다.
 
-## 금지 사항
+## Tailwind root 지정
 
-- EDS 내부 token 원본을 import하거나 복사하지 않습니다.
-- raw hex·px·rem 값을 EDS token 대신 작성하지 않습니다.
-- `@theme`에 EDS token의 resolved 값을 직접 입력하지 않습니다.
-- `@spectrabrain/eds` 패키지 내부의 비공개 경로를 deep import하지 않습니다.
-- Tailwind class로 EDS가 관리하는 UI 스타일을 임의로 덮어쓰지 않습니다.
-- EDS token 이름과 다른 의미의 alias를 만들어 역할을 바꾸지 않습니다.
+`eds sync`와 `eds doctor`는 `@import "tailwindcss"`가 있는 CSS 파일 하나를 Tailwind root로 찾습니다. 후보가 둘 이상이면 둘 다 exit 2로 멈추며, 사용자에게 root를 확인하는 절차는 `CONSUMER_AGENT.md` 「Tailwind root 결정」을 따릅니다. 확인한 root는 다음처럼 한 번 지정하고, sync가 그 경로를 소비처 `package.json`의 `eds.tailwindRoot`에 기록합니다.
 
-## AI 설정 완료 조건
+```sh
+EDS_TAILWIND_ROOT=src/app/styles/index.css npm run sync:eds
+```
 
-소비처 AI는 설정을 마친 뒤 다음을 확인합니다.
+## 완료 기준
 
-1. framework와 Tailwind v4 adapter가 현재 프로젝트에 맞게 연결되어 있습니다.
-2. EDS token CSS가 전역에서 한 번만 import되어 있습니다.
-3. semantic color alias가 `var(--eds-...)`를 참조합니다.
-4. typography preset utility가 모든 공개 preset에 대해 생성되어 있습니다.
-5. 생성 CSS에 raw 값이나 비공개 token 경로가 없습니다.
-6. 예시 `className`이 실제 빌드 결과에 포함됩니다.
-7. 소비처의 typecheck, lint, test, build가 통과합니다.
+1. `npm run eds:doctor`가 `[EDS] synced with` 줄을 출력하고, 출력에 `No Tailwind root CSS found`·`Tailwind CSS v3 detected` note가 없습니다.
+2. Vite 저장소는 `vite.config.*`의 `plugins`에 `@tailwindcss/vite`의 `tailwindcss()`가 있고, 그 밖의 저장소는 PostCSS 설정에 `@tailwindcss/postcss`가 있습니다. doctor는 이 연결을 점검하지 않습니다.
+3. `@spectrabrain/eds/styles.css`는 Tailwind root CSS나 앱 진입점 가운데 한 곳에서만 import됩니다.
 
-설정 후 변경 파일, 설치 패키지, 사용할 수 있는 `eds-*` class, 공개되지 않아 추가하지 않은 token, 검증 결과를 요약합니다.
+EDS를 업데이트한 뒤에는 `CONSUMER_AGENT.md` 「버전 업데이트」를 따릅니다.

package/TOKEN_CONTEXT.md

@@ -0,0 +1,98 @@
+# EVA semantic token 사용 맥락
+
+이 문서는 `@spectrabrain/eds`의 공개 semantic token을 화면 맥락에 맞춰 고르는 방법을 안내합니다. 필수 규칙은 package root의 `QUICKSTART.md`에 있습니다. class 이름은 `src/styles/eds-tokens.css`에, CSS variable과 `cssVar()`에 쓰는 token 이름은 설치된 버전의 `@spectrabrain/eds/tokens`(`SemanticTokenName`)와 `dist/tokens.json`에 있습니다.
+
+## 색상 역할
+
+| 역할 | 적용 대상 | Tailwind class 패턴 | CSS variable 패턴 |
+| --- | --- | --- | --- |
+| `fg` | 제목, 본문, placeholder, 아이콘, inverted content | `text-eds-fg-*`(SVG 아이콘은 `currentColor`로 따라갑니다), `fill-eds-fg-*` | `var(--eds-color-fg-*)` |
+| `bg` | 페이지, 카드, 입력, 버튼, 상태 surface | `bg-eds-bg-*` | `var(--eds-color-bg-*)` |
+| `stroke` | border, divider, keyboard focus ring | `border-eds-stroke-*`, `divide-eds-stroke-*`, `outline-eds-stroke-*`, `ring-eds-stroke-*` | `var(--eds-color-stroke-*)` |
+
+Tailwind class는 Tailwind root CSS가 있는 저장소에서 `eds sync`가 생성하며, 그 밖의 저장소에서는 CSS variable 또는 `cssVar()`를 씁니다. class 이름은 token 이름의 대소문자를 그대로 씁니다(예: focus ring은 `focus-visible:outline-eds-stroke-focusRing`). 공개 token이 없는 `eds-*` class는 Tailwind가 오류 없이 버리며 doctor의 `unknown:`으로만 드러납니다.
+
+역할을 고른 뒤 의미, 강도, 상태를 아래 표의 이름에서 고릅니다. 의미는 주변 화면의 색이 아니라 콘텐츠가 전달하는 상태로 고릅니다: `critical` 오류·위험, `warning` 주의, `positive` 성공·완료, `informative` 정보·안내, `brand` 제품 강조, `neutral` 그 밖의 모든 것.
+
+앞의 두 열은 `color-<역할>-<의미>` 뒤에 붙는 이름이고, 마지막 열은 `color-<역할>-` 뒤에 바로 붙는 이름입니다(예: `color-bg-critical-weak`, `color-fg-neutral`, `color-bg-layer-default`). 표에 없는 조합은 없는 token입니다. hover 상태는 bg 이름 뒤에 `-hover`를 붙이며(`bg-disabled` 제외), fg와 stroke에는 hover token이 없습니다.
+
+| 역할 | 의미 색(`brand`·`critical`·`informative`·`positive`·`warning`) | `neutral` | 의미 없이 쓰는 이름 |
+| --- | --- | --- | --- |
+| `bg` | `-primary`, `-weak` | `-primary`, `-weak`, `-inverted` | `layer-basement`, `layer-default`, `layer-floating`, `transparent`, `disabled` |
+| `fg` | 접미사 없음, `-contrast` | 접미사 없음, `-secondary`, `-tertiary`, `-inverted` | `disabled`, `placeholder`, `focus` |
+| `stroke` | `-primary`, `-weak` | `-contrast`, `-primary`, `-secondary`, `-tertiary`, `-weak` | `focusRing` |
+
+Button 계약에 있는 배경·글자 조합은 `bg-critical-weak`와 `fg-critical`, `bg-neutral-weak`와 `fg-neutral`, `bg-brand-primary`·`bg-neutral-inverted`와 `fg-neutral-inverted`입니다. 본문보다 낮은 위계의 글자는 `fg-neutral-secondary`, 그보다 낮으면 `fg-neutral-tertiary`를 씁니다. 그 밖의 배경 위 글자 색(`brand`·`informative`·`positive`·`warning`의 `weak`·`primary` 배경), 상태 안내(오류 border, badge)의 stroke·fg 조합, `-contrast` fg의 용도, `layer` 계열과 `neutral` 배경의 구분은 `미결`입니다.
+
+exact token이 없으면 아래 순서로 조건을 하나씩 완화하고, 처음 존재하는 이름을 씁니다.
+
+1. 역할(`fg`·`bg`·`stroke`)은 바꾸지 않습니다.
+2. disabled는 `fg`·`bg`에서 `color-<역할>-disabled`를 쓰고, keyboard focus는 `color-stroke-focusRing`(focus ring)이나 `color-fg-focus`를 씁니다. disabled·hover token이 없는 역할은 기본 token을 그대로 씁니다.
+3. 강도를 같은 의미 안의 가까운 단계로 바꿉니다(`primary`↔`weak`, `neutral`의 `secondary`·`tertiary`).
+4. 의미를 `neutral`로 바꿉니다. `critical`·`warning`·`positive`·`informative`를 `neutral`로 바꿔야 한다면 구현을 멈추고 사용자에게 확인합니다.
+
+버튼은 token을 조합하지 않고 EDS `Button`의 `role`·`variant`를 씁니다. 행동별 조합은 `QUICKSTART.md` 표와 `dist/components/Button/README.md` 「Role과 Variant」에 있습니다.
+
+## Typography
+
+text style은 `fontFamily`, `fontWeight`, `fontSize`, `lineHeight`, `letterSpacing`을 함께 적용하는 preset입니다. 한 속성만 떼어 쓰지 않고 preset 하나를 통째로 적용합니다. preset을 적용한 요소에는 `text-lg`(크기), `font-bold`(weight), `leading-*`, `tracking-*` 같은 typography utility를 덧붙이지 않고, 크기나 강조가 달라야 하면 다른 preset을 고릅니다.
+
+`src/styles/eds-tokens.css`가 있는 저장소에서는 `eds-typography-*` utility로, 그 밖의 저장소에서는 같은 preset의 `--eds-typography-<preset>-*` 변수 다섯 개로 적용하며, 설치된 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`가 선언합니다.
+
+| 그룹 | preset | 권장 맥락 |
+| --- | --- | --- |
+| Display | `display1`, `display2` | 제품의 큰 메시지와 페이지 진입점입니다. |
+| Heading | `heading1` … `heading4` | 페이지·섹션·그룹의 구조를 나타냅니다. |
+| Title | `title1` … `title4` | 카드·행·대화상자의 핵심 제목과 control label입니다. |
+| Body | `body1` … `body4` | 설명, 입력 안내, 일반 본문입니다. |
+| Caption | `caption1` … `caption3` | 보조 설명, 메타데이터, 짧은 상태 안내입니다. |
+
+같은 그룹에서는 번호가 작을수록 글자가 크거나 같고, 크기가 같은 preset은 weight로 구분합니다. Title과 Body는 같은 번호끼리 크기가 같고 Title이 더 굵습니다.
+
+## 예시
+
+`src/styles/eds-tokens.css`가 있는 저장소에서는 `className`으로 조합합니다.
+
+```tsx
+<section className="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>
+  <hr className="border-t border-eds-stroke-neutral-secondary" />
+</section>
+```
+
+divider의 stroke 단계는 `미결`이며, 예시는 Button `outline`의 경계와 같은 `neutral-secondary`를 씁니다.
+
+Tailwind가 없는 저장소에서는 공개 CSS variable로 같은 조합을 씁니다.
+
+```css
+.cameraGroupTitle {
+  color: var(--eds-color-fg-neutral);
+  font-family: var(--eds-typography-heading2-fontFamily);
+  font-weight: var(--eds-typography-heading2-fontWeight);
+  font-size: var(--eds-typography-heading2-fontSize);
+  line-height: var(--eds-typography-heading2-lineHeight);
+  letter-spacing: var(--eds-typography-heading2-letterSpacing);
+}
+```
+
+CSS-in-JS나 inline style에서는 `cssVar()`로 같은 이름을 씁니다. `cssVar()`는 CSS 변수 문자열만 반환하므로 앱 진입점에서 `@spectrabrain/eds/styles.css`를 한 번 import해 두어야 합니다.
+
+```tsx
+import { cssVar } from "@spectrabrain/eds/tokens";
+
+<p style={{ color: cssVar("color-fg-neutral-secondary") }}>…</p>; // var(--eds-color-fg-neutral-secondary)
+```
+
+## Spacing과 radius
+
+현재 공개 semantic token에는 소비처용 spacing·radius alias가 없습니다. 소비처의 기존 scale(Tailwind를 쓰는 저장소는 Tailwind 기본 scale)을 씁니다. 기존 scale로 표현할 수 없으면 임의 값을 만들기 전에 멈추고 사용자에게 확인합니다.
+
+## 확인 목록
+
+- 새로 쓴 `var(--eds-*)` 이름이 모두 `tokens.json` key 앞에 `--eds-`를 붙인 이름입니다. doctor는 Tailwind class만, typecheck는 `cssVar()` 인자만 검사하므로 CSS·inline style의 변수는 직접 대조합니다.
+- typography는 preset 하나(`eds-typography-*` class 또는 같은 preset의 변수 다섯 개)로 지정합니다.

package/consumer/align/templates/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "{{eds.srcDir}}/app/styles/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/shared/ui",
+    "utils": "@/shared/lib/utils",
+    "ui": "@/shared/ui",
+    "lib": "@/shared/lib",
+    "hooks": "@/shared/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/consumer/align/templates/env.mock

@@ -0,0 +1 @@
+VITE_API_MOCKING=true

package/consumer/align/templates/eslint.config.js

@@ -0,0 +1,35 @@
+import js from "@eslint/js";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import tseslint from "typescript-eslint";
+import { defineConfig, globalIgnores } from "eslint/config";
+
+export default defineConfig([
+  // Build output, generated files and backend code are not linted by this frontend's config.
+  globalIgnores([{{eds.eslintIgnores}}]),
+  {
+    files: ["**/*.{ts,tsx}"],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      // Includes the React Compiler rules.
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          ignoreRestSiblings: true,
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+    },
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+]);

package/consumer/align/templates/package.scripts.json

@@ -0,0 +1,10 @@
+{
+  "dev": "vite",
+  "dev:mock": "vite --mode mock",
+  "build": "vite build",
+  "preview": "vite preview",
+  "lint": "eslint .",
+  "format": "prettier --write .",
+  "format:check": "prettier --check .",
+  "typecheck": "tsc --noEmit"
+}

package/consumer/align/templates/prettierignore

@@ -0,0 +1,2 @@
+# Build output, generated files, Markdown and backend code are not formatted by this frontend's Prettier.
+{{eds.prettierIgnores}}

package/consumer/align/templates/prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "printWidth": 80,
+  "tabWidth": 2
+}

package/consumer/align/templates/src/app/App.tsx

@@ -0,0 +1,16 @@
+import { Toaster } from "sonner";
+import Router from "./router";
+import { ErrorHandlerProvider } from "./providers/ErrorHandler";
+
+function App() {
+  return (
+    <ErrorHandlerProvider>
+      <main>
+        <Router />
+        <Toaster position="top-right" richColors />
+      </main>
+    </ErrorHandlerProvider>
+  );
+}
+
+export default App;

package/consumer/align/templates/src/app/main.tsx

@@ -0,0 +1,27 @@
+import "./styles/index.css";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { queryClient } from "@/shared/api/queryClient";
+import App from "./App.tsx";
+
+async function main() {
+  // The dev:mock script loads .env.mock, which sets VITE_API_MOCKING=true.
+  if (import.meta.env.VITE_API_MOCKING === "true") {
+    const { worker } = await import("@/mocks/browser");
+    await worker.start({ onUnhandledRequest: "bypass" });
+  }
+
+  createRoot(document.getElementById("root")!).render(
+    <StrictMode>
+      <BrowserRouter>
+        <QueryClientProvider client={queryClient}>
+          <App />
+        </QueryClientProvider>
+      </BrowserRouter>
+    </StrictMode>,
+  );
+}
+
+main();

package/consumer/align/templates/src/app/providers/ErrorBoundary.tsx

@@ -0,0 +1,58 @@
+import { Component, type ReactNode } from "react";
+import { Button } from "@spectrabrain/eds";
+
+export function ErrorFallback() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center gap-4 bg-eds-bg-layer-basement p-8 text-center">
+      <h1 className="eds-typography-title2 text-eds-fg-neutral">
+        문제가 발생했습니다
+      </h1>
+      <p className="eds-typography-body2 text-eds-fg-neutral-secondary">
+        페이지를 불러오지 못했습니다. 새로고침 후 다시 시도해 주세요.
+      </p>
+      <Button
+        size="md"
+        role="neutral"
+        variant="weak"
+        type="button"
+        onClick={() => window.location.reload()}
+      >
+        새로고침
+      </Button>
+    </div>
+  );
+}
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+}
+
+/**
+ * Catches render errors, including lazy page chunks that fail to load after a deploy,
+ * and shows a recoverable fallback instead of a blank screen.
+ */
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  state: ErrorBoundaryState = { hasError: false };
+
+  static getDerivedStateFromError(): ErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: unknown) {
+    console.error("Unhandled render error:", error);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorFallback />;
+    }
+    return this.props.children;
+  }
+}