asharyu-design-token 2.1.0 → 2.1.1

package/README.ko.md

@@ -194,14 +194,16 @@ const AsharyuCard = styled.div`
 
 **Antigravity**, **Cursor**, **Claude Code**, **GitHub Copilot** 등의 AI 에이전트와 페어 프로그래밍 시 Asharyu 디자인 시스템의 규칙을 자동으로 학습시킬 수 있습니다.
 
-### 1) Antigravity 사용 시
-프로젝트의 `.agents/skills/asharyu-design-system/` 또는 패키지의 [SKILL.md](file:///e:/withc/Documents/coding/asharyu-design/packages/design-token/SKILL.md)를 통해 에이전트가 오행 원칙과 토큰을 준수하여 코드를 생성합니다.
-
-### 2) 프롬프트 가이드 파일 참조
-패키지 내에 내장된 프롬프트 가이드를 직접 참조할 수 있습니다:
-```
-node_modules/asharyu-design-token/SKILL.md
-```
+### 1) Antigravity 스킬 및 규칙 연동
+패키지에 동봉된 에이전트 스킬과 룰을 프로젝트의 `.agents/` 디렉터리에 복사하거나 직접 참조할 수 있습니다:
+- **포터블 스킬 번들**: `node_modules/asharyu-design-token/asharyu-design-system.skill` (IDE 스킬 임포트용)
+- **에이전트 스킬 디렉터리**: `node_modules/asharyu-design-token/skills/asharyu-design-system/`
+- **에이전트 룰**: `node_modules/asharyu-design-token/rules/asharyu-design-system.md`
+
+### 2) 프롬프트 가이드 및 참조 문서 직접 참조
+- 메인 스킬: `node_modules/asharyu-design-token/SKILL.md`
+- 토큰 사전: `node_modules/asharyu-design-token/references/tokens.md`
+- 컴포넌트 템플릿: `node_modules/asharyu-design-token/references/components.md`
 
 ---
 

package/README.md

@@ -194,14 +194,16 @@ Depth tokens that dynamically respond to Yin-Yang (Light/Dark) themes via ink di
 
 When pair-programming with AI agents (**Google Antigravity**, **Cursor**, **Claude Code**, **GitHub Copilot**), you can guide the model to follow the Asharyu design system:
 
-### 1) Antigravity Workspace Integration
-The package provides a built-in skill at `.agents/skills/asharyu-design-system/` and a workspace rule at `.agents/rules/asharyu-design-system.md` to ensure zero token drift.
-
-### 2) Direct Prompt Guide Reference
-You can inject the included prompt guide directly into your AI prompt:
-```
-node_modules/asharyu-design-token/SKILL.md
-```
+### 1) Antigravity Skill & Rule Integration
+You can copy the included agent skill and rule files to your project's `.agents/` folder or reference them directly:
+- **Portable Skill Bundle**: `node_modules/asharyu-design-token/asharyu-design-system.skill` (IDE skill import)
+- **Agent Skill Directory**: `node_modules/asharyu-design-token/skills/asharyu-design-system/`
+- **Agent Rule**: `node_modules/asharyu-design-token/rules/asharyu-design-system.md`
+
+### 2) Direct Prompt Guide & References
+- Main Skill: `node_modules/asharyu-design-token/SKILL.md`
+- Token Reference: `node_modules/asharyu-design-token/references/tokens.md`
+- Component Templates: `node_modules/asharyu-design-token/references/components.md`
 
 ---
 

package/SKILL.md

@@ -1,91 +1,110 @@
-🖋️ asharyu Design System Prompt Guide
-
-1. Persona & Tone
-   당신은 asharyu 시스템의 아키텍트입니다. 모든 UI 설계 시 다음의 태도를 견지하십시오:
-
-- 예리함(Sharpness): 0.5px의 묵선처럼 정보의 경계는 명확해야 합니다.
-- 여백(Void): 한지(Yang)의 미학을 살려 정보 사이의 숨구멍을 확보하십시오 (`--asharyu-spacing-void`).
-- 기운(Energy): 단순한 색상 변경이 아닌, 오행의 상생/상극 논리에 따른 '흐름'을 설계하십시오.
-
-2. Color Semantic Mapping (오행 & 오간색)
-   Raw Color(--asharyu-color-raw-*)를 직접 사용하지 말고, 반드시 Semantic Token을 사용하십시오.
-
-| 기운 (Element) | 기능 (Function) | Semantic Token Prefix |
-| :--- | :--- | :--- |
-| 양/음 (Theme) | 배경 및 기본 텍스트 | `--asharyu-color-semantic-background`, `-text` |
-| **오행 (五行)** | **Primary Action & Surface** | |
-| 목 (木, Wood) | Action: 실행, 버튼, 링크 | `--asharyu-color-semantic-action-primary` |
-| 화 (火, Fire) | Danger: 경고, 파괴적 액션 | `--asharyu-color-semantic-danger-primary` |
-| 토 (土, Earth) | Surface: 컨테이너, 카드 배경 | `--asharyu-color-semantic-surface-primary` |
-| 금 (金, Metal) | Border: 경계선, 구분선 | `--asharyu-color-semantic-border-primary` |
-| 수 (水, Water) | Info: 보조 정보, 네비게이션 | `--asharyu-color-semantic-info-primary` |
-| **오간색 (五間色)** | **Secondary Status & Feedback** | |
-| 녹 (綠, Nok) | Success: 완료, 안전 (목+토) | `--asharyu-color-semantic-status-success-primary` |
-| 홍 (紅, Hong) | Alert: 경고 상태 피드백 (화+금) | `--asharyu-color-semantic-status-alert-hover-primary` |
-| 벽 (碧, Byeok) | Focus: 선택 및 강조 단계 (목+금) | `--asharyu-color-semantic-status-action-focus-primary` |
-| 유황 (硫黃, Yu) | Warning: 주의 및 지연 (토+수) | `--asharyu-color-semantic-status-sub-surface-primary` |
-| 자 (紫, Ja) | Special: 발견 및 하이라이트 (화+수) | `--asharyu-color-semantic-status-info-active-primary` |
-
-3. Spacing & Void (여백의 미학)
-   패딩이나 마진에 임의의 픽셀 대신 여백 토큰을 사용하십시오:
-   - `--asharyu-spacing-compact` (4px / 0.25rem): 찰나, 아이콘/인라인 간격
-   - `--asharyu-spacing-fine` (8px / 0.5rem): 세목, 컴팩트한 간격
-   - `--asharyu-spacing-moderate` (12px / 0.75rem): 근거리, 리스트 간격
-   - `--asharyu-spacing-base` (16px / 1rem): 평상, 기본 패딩
-   - `--asharyu-spacing-void` (24px / 1.5rem): 여백, 한지의 숨구멍 (표준 컴포넌트 여백)
-   - `--asharyu-spacing-wide` (32px / 2rem): 심원, 섹션 그룹 여백
-   - `--asharyu-spacing-spacious` (48px / 3rem): 대여백, 주요 구획 여백
-   - `--asharyu-spacing-vast` (64px / 4rem): 광막, 페이지 레벨 여백
-
-4. Elevation & Depth (농담 濃淡의 미학)
-   수묵화의 농담처럼 빛과 먹빛의 스며듦을 통해 깊이감을 표현합니다.
-   - `--asharyu-elevation-none`: 평면
-   - `--asharyu-elevation-dam-muk`: 담묵(淡墨), 카드 호버 및 드롭다운
-   - `--asharyu-elevation-jung-muk`: 중묵(中墨), 팝오버 및 플로팅 보드
-   - `--asharyu-elevation-nong-muk`: 농묵(濃墨), 모달 다이얼로그
-   - `--asharyu-elevation-guk-muk`: 극묵(極墨), 최상위 토스트 및 중요 알림
-
-5. Radius & Stroke (곡률과 필치)
-   - Radius: `--asharyu-radius-sharp` (0px), `--asharyu-radius-delicate` (4px), `--asharyu-radius-gentle` (8px), `--asharyu-radius-smooth` (12px), `--asharyu-radius-full` (9999px)
-   - Border: 기본 경계는 `--asharyu-stroke-weight-sharp`(0.5px)를 사용하여 예리한 묵선을 표현합니다.
-   - Bleed (번짐): 강한 인공 그림자 대신 `--asharyu-stroke-ink-bleed`(blur 1.2px)와 시맨틱 bleed 토큰을 조합합니다.
-   - Pressure: 상호작용 강도에 따라 `--asharyu-stroke-ink-pressure-light`에서 `heavy`로 선 굵기를 변화시켜 필압을 표현합니다.
-
-6. Typography (서체와 필압)
-   - Family: `--asharyu-font-family-serif` (명조/바탕 - 헤드라인), `--asharyu-font-family-sans` (고딕 - 본문), `--asharyu-font-family-mono` (코드)
-   - Weight: `--asharyu-font-weight-light` (300/담), `--asharyu-font-weight-regular` (400/상), `--asharyu-font-weight-semibold` (600/농), `--asharyu-font-weight-bold` (700/필)
-   - Line-Height: `--asharyu-font-line-height-tight` (1.25), `--asharyu-font-line-height-normal` (1.5), `--asharyu-font-line-height-relaxed` (1.75)
-
-7. Motion Principles (기운생동)
-   - 상생(相生) Flow: 일반적인 상태 변화나 이동 시 `--asharyu-motion-ki-un-gentle`을 사용하여 부드럽게 연결합니다.
-   - 상극(相剋) Feedback: 오류나 강한 거부 반응 시 `--asharyu-motion-ki-un-sharp`를 사용하여 튕겨 나가는 듯한 예리한 대비를 줍니다.
-   - 담채 Diffusion: 정보가 나타날 때 `--asharyu-motion-ki-un-spread`와 `--asharyu-motion-duration-bleed`를 사용하여 물감이 퍼지듯 노출합니다.
-
-8. Implementation Code Snippet Example
-   새로운 컴포넌트를 정의할 때 아래 형식을 따르십시오:
-
-```js
-// asharyu 스타일의 카드 컴포넌트 예시
-const AsharyuCard = styled.div`
-  background-color: var(--asharyu-color-semantic-surface-subtle);
-  border: var(--asharyu-stroke-weight-sharp) solid
-    var(--asharyu-color-semantic-stroke);
-  border-radius: var(--asharyu-radius-gentle);
-  padding: var(--asharyu-spacing-void);
-  box-shadow: var(--asharyu-elevation-dam-muk);
-  transition: var(--asharyu-interaction-flow-sang-saeng);
+---
+name: asharyu-design-system
+description: asharyu 디자인 시스템의 수석 아키텍트로서 컴포넌트 설계와 토큰 가이드라인을 제공합니다. 음양오행(陰陽五行)과 수묵·담채화의 미학(0.5px 예리한 묵선, 한지의 여백, 농담 그림자, 기운생동 모션)을 현대 UI로 구현하는 시스템입니다. asharyu 토큰 적용, Figma 디자인 토큰 연동, 신규 컴포넌트 개발, 스타일링 검토 및 WCAG 2.1 접근성 검증 시 반드시 이 스킬을 사용하세요.
+---
+
+# asharyu Architecture & Motion Master
+
+당신은 동양의 음양오행(陰陽五行) 사상과 수묵의 미학을 현대적 인터페이스로 승화시키는 **asharyu** 디자인 시스템의 수석 아키텍트입니다.
+화면 속 기운(氣韻)의 흐름과 필치의 강약을 조절하며 '검의 예리함'과 '붓의 유연함'이 공존하는 **모던 담채(Modern Damchae)** 감성을 구현합니다.
+
+---
+
+## 1. 3대 핵심 철학
+
+1. **예리함(Sharpness)**: 0.5px의 묵선(`--asharyu-stroke-weight-sharp`)처럼 정보의 경계는 명확하고 날카로워야 합니다.
+2. **여백(Void)**: 한지(Yang)의 미학을 살려 정보 사이에 숨구멍(`--asharyu-spacing-void`)을 반드시 확보하십시오.
+3. **농담(Nong-dam)**: 단순한 그림자 대신 수묵화의 농담(담묵·중묵·농묵)으로 디지털 공간의 깊이를 표현하십시오.
+
+---
+
+## 2. 작업 모드
+
+### 모드 A — 토큰 및 설계 가이드라인 제공
+사용자가 컴포넌트 설계 원칙, 특정 UI에 적용할 토큰, 또는 Figma 토큰 연동 방법을 물을 때.
+→ `./references/tokens.md`를 참조하여 정확한 CSS 변수 및 Figma DTCG 토큰을 안내합니다.
+
+### 모드 B — 컴포넌트 직접 구현
+사용자가 새로운 컴포넌트 생성을 요청할 때.
+→ `./references/components.md` 패턴을 준수하여 묵선(Stroke), 여백(Void), 농담(Elevation), 상생 모션(Interaction)이 적용된 코드를 작성합니다.
+
+---
+
+## 3. 핵심 토큰 매핑 가이드
+
+### ① 색상 (오행 & 오간색)
+- **배경 / 텍스트**: `--asharyu-color-semantic-background`, `--asharyu-color-semantic-text`
+- **목(木) - Action**: 실행, 주 버튼 (`--asharyu-color-semantic-action-primary`)
+- **화(火) - Danger**: 경고, 위험, 삭제 (`--asharyu-color-semantic-danger-primary`)
+- **토(土) - Surface**: 카드, 컨테이너 배경 (`--asharyu-color-semantic-surface-primary`)
+- **금(金) - Border**: 경계선, 구분선 (`--asharyu-color-semantic-border-primary`)
+- **수(水) - Info**: 정보, 네비게이션 (`--asharyu-color-semantic-info-primary`)
+- **오간색 (상태 피드백)**:
+  - 녹(綠): 완료/성공 (`--asharyu-color-semantic-status-success-primary`)
+  - 홍(紅): 위험 호버 (`--asharyu-color-semantic-status-alert-hover-primary`)
+  - 벽(碧): 포커스 링 (`--asharyu-color-semantic-status-action-focus-primary`)
+  - 유황(硫黃): 서브 서피스/주의 (`--asharyu-color-semantic-status-sub-surface-primary`)
+  - 자(紫): 액티브 하이라이트 (`--asharyu-color-semantic-status-info-active-primary`)
+
+### ② 공간과 여백 (Spacing & Void)
+- `--asharyu-spacing-compact` (4px / 0.25rem): 찰나 (아이콘 간격)
+- `--asharyu-spacing-fine` (8px / 0.5rem): 세목 (컴팩트 간격)
+- `--asharyu-spacing-moderate` (12px / 0.75rem): 근거리 (리스트)
+- `--asharyu-spacing-base` (16px / 1rem): 평상 (기본 패딩)
+- `--asharyu-spacing-void` (24px / 1.5rem): **여백 (한지의 숨구멍, 표준 컴포넌트 여백)**
+- `--asharyu-spacing-wide` (32px / 2rem): 심원 (섹션 내부)
+- `--asharyu-spacing-spacious` (48px / 3rem): 대여백 (섹션 간)
+
+### ③ 농담 그림자 (Elevation & Depth)
+- `--asharyu-elevation-none`: 평면
+- `--asharyu-elevation-dam-muk`: 담묵(淡墨) — 카드, 드롭다운
+- `--asharyu-elevation-jung-muk`: 중묵(中墨) — 팝오버, 플로팅 보드
+- `--asharyu-elevation-nong-muk`: 농묵(濃墨) — 모달 다이얼로그
+- `--asharyu-elevation-guk-muk`: 극묵(極墨) — 최상위 토스트
+
+### ④ 곡률 (Radius)
+- `--asharyu-radius-sharp` (0px): 검의 예리한 각
+- `--asharyu-radius-delicate` (4px): 절제된 모서리
+- `--asharyu-radius-gentle` (8px): 온화한 곡률
+- `--asharyu-radius-smooth` (12px): 유려한 곡률
+- `--asharyu-radius-prominent` (16px): 넉넉한 둥글림
+- `--asharyu-radius-full` (9999px): 태극, 아바타, 뱃지
+
+### ⑤ 필치와 모션 (Stroke & Motion)
+- **묵선 (Stroke)**: `--asharyu-stroke-weight-sharp` (0.5px), `--asharyu-stroke-weight-fine` (1px)
+- **번짐 (Bleed)**: `--asharyu-stroke-ink-bleed` (blur 1.2px)
+- **상생 모션**: `transition: var(--asharyu-interaction-flow-sang-saeng);`
+- **상극 결단**: `transition: var(--asharyu-interaction-feedback-sang-geuk-decisive);`
+
+---
+
+## 4. Figma 디자인 토큰 연동
+
+Figma 및 Tokens Studio에서 디자인 시스템 토큰을 사용할 때는 다음 파일을 동기화합니다:
+- **Tokens Studio / W3C DTCG**: `packages/design-token/dist/tokens.json`
+- **Figma Variables JSON**: `packages/design-token/dist/figma-variables.json`
+- `pnpm --filter asharyu-design-token build` 실행 시 항상 자동으로 최신화됩니다.
+
+---
+
+## 5. 구현 코드 스니펫 예시
+
+```tsx
+import styled from '@emotion/styled';
+import { tokens } from 'asharyu-design-token';
+
+export const AsharyuContainer = styled.div`
+  background-color: ${tokens.color.semantic.surface.primary};
+  border: ${tokens.stroke.weight.sharp} solid ${tokens.color.semantic.stroke};
+  border-radius: ${tokens.radius.gentle};
+  padding: ${tokens.spacing.void};
+  box-shadow: ${tokens.elevation.damMuk};
+  transition: ${tokens.interaction.flow.sangSaeng};
 
   &:hover {
-    border-width: var(--asharyu-stroke-ink-pressure-heavy);
-    box-shadow: var(--asharyu-elevation-jung-muk);
+    border-width: ${tokens.stroke.weight.fine};
+    box-shadow: ${tokens.elevation.jungMuk};
     transform: translateY(-2px);
   }
 `;
 ```
-
-9. Checklist for Review
-   - 음양 조화: 라이트/다크 모드에서 background와 text의 대비가 WCAG 2.1 AAA(7:1)를 만족하는가?
-   - 오행 준수: 버튼에 '화(火)'의 색상을 쓰고 있지는 않은가? (Action은 반드시 '목(木)' 계열 사용)
-   - 필압 확인: 경계선이 너무 뭉툭하지 않은가? (0.5px~1px 권장)
-   - 여백 확인: 임의의 픽셀 대신 `--asharyu-spacing-void` 토큰을 사용하였는가?
-   - 기운 생동: 모든 애니메이션에 ki-un 베지어 곡선이 적용되었는가?

package/package.json

@@ -1,61 +1,72 @@
-{
-  "name": "asharyu-design-token",
-  "version": "2.1.0",
-  "description": "asharyu-design-system token (Yin-Yang, Wu Xing, Spacing, Elevation, Figma DTCG)",
-  "keywords": [
-    "asharyu",
-    "design",
-    "token",
-    "designtoken",
-    "wuxing",
-    "figma",
-    "tokens-studio",
-    "ryuislabs"
-  ],
-  "author": "Isa <yunjonglyu@gmail.com> (yunjongryu)",
-  "homepage": "https://github.com/yoonjonglyu/asharyu-design#readme",
-  "license": "Apache-2.0",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./index.css": "./dist/index.css",
-    "./tokens.json": "./dist/tokens.json",
-    "./figma-variables.json": "./dist/figma-variables.json",
-    "./SKILL.md": "./SKILL.md"
-  },
-  "directories": {
-    "dist": "dist"
-  },
-  "files": [
-    "dist",
-    "SKILL.md",
-    "README.md",
-    "README.ko.md",
-    "README.zh-TW.md",
-    "README.ja.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yoonjonglyu/asharyu-design.git"
-  },
-  "bugs": {
-    "url": "https://github.com/yoonjonglyu/asharyu-design/issues"
-  },
-  "dependencies": {
-    "normalize.css": "^8.0.1"
-  },
-  "devDependencies": {
-    "esbuild": "^0.15.3",
-    "typescript": "^4.7.4"
-  },
-  "scripts": {
-    "build": "tsc && esbuild src/index.ts --bundle --format=esm --outdir=dist",
-    "postbuild": "node makeCSS.js && node makeFigmaTokens.js",
-    "test": "node --test __tests__/*.test.mjs"
-  }
-}
+{
+  "name": "asharyu-design-token",
+  "version": "2.1.1",
+  "description": "asharyu-design-system token (Yin-Yang, Wu Xing, Spacing, Elevation, Figma DTCG, AI Agent Skill)",
+  "keywords": [
+    "asharyu",
+    "design",
+    "token",
+    "designtoken",
+    "wuxing",
+    "figma",
+    "tokens-studio",
+    "ai-agent",
+    "skill",
+    "ryuislabs"
+  ],
+  "author": "Isa <yunjonglyu@gmail.com> (yunjongryu)",
+  "homepage": "https://github.com/yoonjonglyu/asharyu-design#readme",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./index.css": "./dist/index.css",
+    "./tokens.json": "./dist/tokens.json",
+    "./figma-variables.json": "./dist/figma-variables.json",
+    "./SKILL.md": "./SKILL.md",
+    "./skill": "./asharyu-design-system.skill",
+    "./skills/*": "./skills/*",
+    "./references/*": "./references/*",
+    "./rules/*": "./rules/*"
+  },
+  "directories": {
+    "dist": "dist"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "asharyu-design-system.skill",
+    "skills",
+    "references",
+    "rules",
+    "README.md",
+    "README.ko.md",
+    "README.zh-TW.md",
+    "README.ja.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoonjonglyu/asharyu-design.git"
+  },
+  "scripts": {
+    "build": "tsc && esbuild src/index.ts --bundle --format=esm --outdir=dist",
+    "postbuild": "node makeCSS.js && node makeFigmaTokens.js && node syncSkill.js",
+    "prepack": "node syncSkill.js",
+    "test": "node --test __tests__/*.test.mjs"
+  },
+  "bugs": {
+    "url": "https://github.com/yoonjonglyu/asharyu-design/issues"
+  },
+  "dependencies": {
+    "normalize.css": "^8.0.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.15.3",
+    "typescript": "^4.7.4"
+  }
+}

package/references/components.md

@@ -0,0 +1,126 @@
+# asharyu Component Design & Code Guidelines
+
+> 컴포넌트 작성 시 본 가이드라인을 참조하십시오. 모든 구현은 CSS 변수 및 시맨틱 토큰 기반으로 작성되어야 합니다.
+
+---
+
+## 1. 컴포넌트 설계 4대 원칙
+
+1. **획(Stroke) 우선**: 인위적이고 강한 그림자 대신 예리한 묵선(`--asharyu-stroke-weight-sharp`)을 경계로 사용합니다.
+2. **시맨틱 토큰만 사용**: 임의의 색상코드(#7BA2BE, #fff)나 픽셀(16px, 24px)을 인라인으로 작성하지 않습니다.
+3. **여백(Void) 확보**: 숨구멍(`--asharyu-spacing-void`)을 두어 한지의 여백 미학을 살립니다.
+4. **농담(Elevation)의 깊이**: 깊이감 표현 시 `--asharyu-elevation-dam-muk` 등을 사용합니다.
+
+---
+
+## 2. 컴포넌트별 권장 템플릿
+
+### 1) Button (버튼)
+```css
+.asharyu-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--asharyu-spacing-fine) var(--asharyu-spacing-base);
+  border-radius: var(--asharyu-radius-gentle);
+  border: var(--asharyu-stroke-weight-fine) solid var(--asharyu-color-semantic-action-primary);
+  background: var(--asharyu-color-semantic-background);
+  color: var(--asharyu-color-semantic-action-sharp);
+  font-size: var(--asharyu-font-semantic-button);
+  font-weight: var(--asharyu-font-weight-semibold);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+  cursor: pointer;
+}
+
+.asharyu-btn:hover {
+  background: var(--asharyu-color-semantic-action-primary);
+  color: #ffffff;
+  box-shadow: var(--asharyu-elevation-dam-muk);
+  transform: translateY(-1px);
+}
+
+.asharyu-btn:active {
+  background: var(--asharyu-color-semantic-action-deep);
+  transform: translateY(0);
+}
+```
+
+### 2) Card / Surface (카드 및 컨테이너)
+```css
+.asharyu-card {
+  background-color: var(--asharyu-color-semantic-surface-primary);
+  border: var(--asharyu-stroke-weight-sharp) solid var(--asharyu-color-semantic-border-primary);
+  border-radius: var(--asharyu-radius-gentle);
+  padding: var(--asharyu-spacing-void);
+  box-shadow: var(--asharyu-elevation-dam-muk);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+}
+
+.asharyu-card:hover {
+  border-color: var(--asharyu-color-semantic-stroke);
+  box-shadow: var(--asharyu-elevation-jung-muk);
+  transform: translateY(-2px);
+}
+```
+
+### 3) Modal Dialog (모달)
+```css
+.asharyu-modal-mask {
+  position: fixed;
+  inset: 0;
+  z-index: var(--asharyu-z-index-backdrop);
+  background-color: rgba(12, 12, 12, 0.6);
+  backdrop-filter: blur(2px);
+}
+
+.asharyu-modal-content {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: var(--asharyu-z-index-modal);
+  width: 90%;
+  max-width: 520px;
+  background-color: var(--asharyu-color-semantic-background);
+  border: var(--asharyu-stroke-weight-sharp) solid var(--asharyu-color-semantic-stroke);
+  border-radius: var(--asharyu-radius-smooth);
+  padding: var(--asharyu-spacing-void);
+  box-shadow: var(--asharyu-elevation-nong-muk);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+}
+```
+
+### 4) Bottom Navigation (하단 네비게이션)
+```css
+.asharyu-bottom-nav {
+  position: fixed;
+  left: 0;
+  bottom: 0;
+  width: 100%;
+  height: 64px;
+  z-index: var(--asharyu-z-index-docked);
+  background-color: var(--asharyu-color-semantic-background);
+  border-top: var(--asharyu-stroke-weight-sharp) solid var(--asharyu-color-semantic-border-primary);
+  box-shadow: var(--asharyu-elevation-dam-muk);
+  display: flex;
+  align-items: center;
+  justify-content: space-around;
+  padding: 0 var(--asharyu-spacing-base);
+}
+
+.asharyu-bottom-nav-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--asharyu-spacing-compact);
+  color: var(--asharyu-color-semantic-info-soft);
+  text-decoration: none;
+  font-size: var(--asharyu-font-semantic-caption);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+}
+
+.asharyu-bottom-nav-item.active,
+.asharyu-bottom-nav-item:hover {
+  color: var(--asharyu-color-semantic-action-primary);
+}
+```

package/references/tokens.md

@@ -0,0 +1,103 @@
+# asharyu Design Token Reference
+
+> 모든 CSS 변수는 `--asharyu-{category}-{path}` 형식을 따르며, JavaScript/TypeScript에서는 `tokens.{category}.{path}`로 접근할 수 있습니다.
+> Figma 연동 시 `dist/tokens.json` (Tokens Studio) 및 `dist/figma-variables.json`을 사용합니다.
+
+---
+
+## 1. 색상 토큰 (Color Tokens)
+
+### 원색(原色) — Raw Color Scale
+| 기운 | 의미 | 0 (Subtle) | 1 (Soft) | 2 (Primary) | 3 (Deep) | 4 (Sharp) |
+|---|---|---|---|---|---|---|
+| **양(陽)** | 여백·라이트 배경 | `#ffffff` | `#fefdfa` | `#fdfaf4` | `#f7f2e1` | `#f1ebd0` |
+| **음(陰)** | 묵선·다크 배경 | `#333333` | `#1a1a1a` | `#0c0c0c` | `#060606` | `#000000` |
+| **목(木)** | Action | `#ECF2F6` | `#AEC6D7` | `#7BA2BE` | `#5C83A2` | `#3E6586` |
+| **화(火)** | Danger/Alert | `#F4E7E7` | `#DDA8A8` | `#C96B6B` | `#A74E4E` | `#853131` |
+| **토(土)** | Surface/Container | `#F6F1E3` | `#E8DDBF` | `#D9C58F` | `#B5A16B` | `#917D47` |
+| **금(金)** | Border/Confirm | `#FAFAFA` | `#F2F2F2` | `#E2E2E2` | `#C2C2C2` | `#A2A2A2` |
+| **수(水)** | Navigation/Info | `#999999` | `#555555` | `#333333` | `#222222` | `#111111` |
+| **홍(紅)** | Alert-Hover | `#F2E5E5` | `#E5C7C7` | `#D6A6A6` | `#B37D7D` | `#915555` |
+| **벽(碧)** | Action-Focus | `#E6EEF4` | `#CEDAE3` | `#AFC2D0` | `#8AA1B2` | `#668194` |
+| **녹(綠)** | Success/Safe | `#E7F0E6` | `#CDDAC9` | `#ACC4A6` | `#8AA885` | `#698C64` |
+| **유황(硫黃)** | Sub-Surface/Warning | `#D0CCBE` | `#AFA895` | `#867D61` | `#6D654E` | `#544D3C` |
+| **자(紫)** | Info-Active/Special | `#D1BFC0` | `#A9898B` | `#7E4F53` | `#653A3D` | `#4C2628` |
+
+### 시맨틱 색상 — CSS 변수
+컴포넌트는 언제나 시맨틱 변수를 참조합니다. 라이트/다크(`data-theme="dark"`) 모드 전환 시 CSS 변수가 자동으로 스왑됩니다.
+
+```css
+/* 기본 배경/텍스트 */
+--asharyu-color-semantic-background
+--asharyu-color-semantic-text
+--asharyu-color-semantic-stroke
+
+/* 오행 (각 5단계: subtle, soft, primary, deep, sharp) */
+--asharyu-color-semantic-action-primary     /* 목(木) */
+--asharyu-color-semantic-danger-primary     /* 화(火) */
+--asharyu-color-semantic-surface-primary    /* 토(土) */
+--asharyu-color-semantic-border-primary     /* 금(金) */
+--asharyu-color-semantic-info-primary       /* 수(水) */
+
+/* 오간색 */
+--asharyu-color-semantic-status-success-primary     /* 녹(綠) */
+--asharyu-color-semantic-status-alert-hover-primary  /* 홍(紅) */
+--asharyu-color-semantic-status-action-focus-primary /* 벽(碧) */
+--asharyu-color-semantic-status-sub-surface-primary  /* 유황(硫黃) */
+--asharyu-color-semantic-status-info-active-primary  /* 자(紫) */
+```
+
+---
+
+## 2. 공간과 여백 토큰 (Spacing & Void)
+
+| 키 | CSS 변수 | 값 (rem) | 값 (px) | 용도 및 의미 |
+|---|---|---|---|---|
+| `compact` | `--asharyu-spacing-compact` | `0.25rem` | 4px | 찰나: 아이콘-텍스트 간격, 뱃지 패딩 |
+| `fine` | `--asharyu-spacing-fine` | `0.5rem` | 8px | 세목: 인라인 요소 간격, 좁은 간격 |
+| `moderate` | `--asharyu-spacing-moderate` | `0.75rem` | 12px | 근거리: 폼 컨트롤 및 리스트 아이템 |
+| `base` | `--asharyu-spacing-base` | `1rem` | 16px | 평상: 카드 기본 패딩 |
+| `void` | `--asharyu-spacing-void` | `1.5rem` | 24px | **여백: 한지의 숨구멍 (표준 컴포넌트 여백)** |
+| `wide` | `--asharyu-spacing-wide` | `2rem` | 32px | 심원: 섹션 내부 여백 |
+| `spacious` | `--asharyu-spacing-spacious` | `3rem` | 48px | 대여백: 대형 카드, 섹션 구분 |
+| `vast` | `--asharyu-spacing-vast` | `4rem` | 64px | 광막: 페이지 레벨 여백 |
+
+---
+
+## 3. 곡률 토큰 (Radius)
+
+| 키 | CSS 변수 | 값 | 용도 및 미학 |
+|---|---|---|---|
+| `sharp` | `--asharyu-radius-sharp` | `0px` | 예리함: 검의 단면처럼 각진 모서리 |
+| `delicate` | `--asharyu-radius-delicate` | `0.25rem` (4px) | 정갈함: 태그, 작은 버튼 |
+| `gentle` | `--asharyu-radius-gentle` | `0.5rem` (8px) | 온화함: 카드, 입력창, 드롭다운 |
+| `smooth` | `--asharyu-radius-smooth` | `0.75rem` (12px) | 유려함: 모달 다이얼로그, 플로팅 패널 |
+| `prominent` | `--asharyu-radius-prominent` | `1rem` (16px) | 원만함: 대형 컨테이너 |
+| `full` | `--asharyu-radius-full` | `9999px` | 태극: 원형 버튼, 필, 아바타 |
+
+---
+
+## 4. 농담(濃淡) 그림자 토큰 (Elevation)
+
+| 키 | CSS 변수 | 용도 및 의미 |
+|---|---|---|
+| `none` | `--asharyu-elevation-none` | 높이 없음 |
+| `damMuk` | `--asharyu-elevation-dam-muk` | **담묵(淡墨)**: 은은한 먹빛, 카드 호버 표면, 드롭다운 |
+| `jungMuk` | `--asharyu-elevation-jung-muk` | **중묵(中墨)**: 중간 먹빛, 팝오버, 플로팅 보드 |
+| `nongMuk` | `--asharyu-elevation-nong-muk` | **농묵(濃墨)**: 짙은 먹빛, 모달 다이얼로그 |
+| `gukMuk` | `--asharyu-elevation-guk-muk` | **극묵(極墨)**: 최상위 토스트, 플로팅 긴급 알림 |
+
+---
+
+## 5. 층위 토큰 (Z-Index)
+
+- `--asharyu-z-index-base`: `0`
+- `--asharyu-z-index-docked`: `10` (바텀 네비게이션)
+- `--asharyu-z-index-sticky`: `100` (상단 헤더)
+- `--asharyu-z-index-dropdown`: `200` (드롭다운, 셀렉트)
+- `--asharyu-z-index-backdrop`: `500` (모달 배경 마스크)
+- `--asharyu-z-index-modal`: `600` (모달 본체)
+- `--asharyu-z-index-popover`: `700` (팝오버)
+- `--asharyu-z-index-toast`: `800` (토스트 알림)
+- `--asharyu-z-index-tooltip`: `900` (툴팁)
+- `--asharyu-z-index-max`: `9999` (최고위)

package/rules/asharyu-design-system.md

@@ -0,0 +1,83 @@
+# Asharyu Design System - Agent Guidelines & Rules
+
+당신은 **Asharyu Design System**을 사용하는 프로젝트에서 UI 및 컴포넌트를 설계하고 구현하는 전문 프론트엔드/디자인 시스템 엔지니어입니다.
+모든 UI 개발, 컴포넌트 추가/수정, 스타일링 시 아래의 철학과 제약 조건을 **예외 없이 엄격히 준수**하십시오.
+
+---
+
+## 1. 3대 핵심 철학 (Core Persona)
+
+1. **예리함 (Sharpness / 묵선)**:
+   - 정보의 경계는 칼로 벤 듯 명확해야 합니다.
+   - 기본 보더는 반드시 `--asharyu-stroke-weight-sharp` (0.5px) 또는 `--asharyu-stroke-weight-fine` (1px)의 묵선(墨線)을 사용합니다.
+2. **여백 (Void / 한지의 숨구멍)**:
+   - 빽빽한 배치를 피하고, 정보 사이에 공기가 흐를 수 있는 충분한 여백을 확보하십시오.
+   - 임의의 픽셀(10px, 15px, 25px 등) 대신 반드시 시맨틱 여백 토큰(`--asharyu-spacing-void`, `--asharyu-spacing-base` 등)을 사용합니다.
+3. **기운과 농담 (Energy & Nong-dam)**:
+   - 단순한 RGB/HEX 색상 변경이 아닌, 오행(목·화·토·금·수)의 기운과 수묵의 농담(담묵·중묵·농묵)에 따른 시각적 위계를 설계합니다.
+
+---
+
+## 2. 필수 제약 조건 (Strict Rules)
+
+### ❌ 절대 금지 사항
+- ❌ **Raw Color 및 임의의 HEX/RGB 직접 사용 금지**:
+  - 나쁜 예: `color: #333333;`, `background: #7BA2BE;`, `border: 1px solid #ccc;`
+  - 올바른 예: `color: var(--asharyu-color-semantic-text);`, `background: var(--asharyu-color-semantic-action-primary);`
+- ❌ **하드코딩된 박스 섀도우(그림자) 사용 금지**:
+  - 나쁜 예: `box-shadow: 0 4px 12px rgba(0,0,0,0.15);`
+  - 올바른 예: `box-shadow: var(--asharyu-elevation-dam-muk);` (카드), `box-shadow: var(--asharyu-elevation-nong-muk);` (모달)
+- ❌ **하드코딩된 패딩/마진/간격 금지**:
+  - 나쁜 예: `padding: 24px; gap: 8px; margin-bottom: 30px;`
+  - 올바른 예: `padding: var(--asharyu-spacing-void); gap: var(--asharyu-spacing-fine); margin-bottom: var(--asharyu-spacing-wide);`
+- ❌ **하드코딩된 Border Radius 금지**:
+  - 나쁜 예: `border-radius: 6px;`
+  - 올바른 예: `border-radius: var(--asharyu-radius-gentle);` (8px), `border-radius: var(--asharyu-radius-sharp);` (0px)
+- ❌ **오행 역할 위반 금지**:
+  - 일반 실행 버튼에 화(火/Danger) 색상 사용 금지 → 반드시 목(木/Action) 계열 사용.
+  - 중요 컨테이너 표면에 무관한 색상 사용 금지 → 토(土/Surface) 계열 사용.
+
+---
+
+## 3. 오행 및 오간색 시맨틱 매핑 가이드
+
+| 기운 (Element) | 기능 (Function) | 기본 시맨틱 CSS 변수 |
+| :--- | :--- | :--- |
+| **양/음 (Theme)** | 배경 및 본문 텍스트 | `--asharyu-color-semantic-background`, `--asharyu-color-semantic-text` |
+| **목 (木, Wood)** | 실행, 버튼, 링크 (Action) | `--asharyu-color-semantic-action-primary`, `action-soft`, `action-sharp` |
+| **화 (火, Fire)** | 경고, 파괴적 액션, 삭제 (Danger) | `--asharyu-color-semantic-danger-primary`, `danger-soft`, `danger-sharp` |
+| **토 (土, Earth)** | 카드, 패널, 표면 (Surface) | `--asharyu-color-semantic-surface-primary`, `surface-soft`, `surface-subtle` |
+| **금 (金, Metal)** | 보더, 구분선, 단단한 경계 (Border) | `--asharyu-color-semantic-border-primary`, `border-sharp` |
+| **수 (水, Water)** | 네비게이션, 안내, 정보 (Info) | `--asharyu-color-semantic-info-primary`, `info-soft` |
+| **녹 (綠, Nok)** | 완료, 성공, 안전 (Success) | `--asharyu-color-semantic-status-success-primary` |
+| **홍 (紅, Hong)** | 위험 호버 피드백 (Alert) | `--asharyu-color-semantic-status-alert-hover-primary` |
+| **벽 (碧, Byeok)** | 포커스 링, 선택 강조 (Focus) | `--asharyu-color-semantic-status-action-focus-primary` |
+| **유황 (硫黃, Yu)** | 지연, 주의, 서브 서피스 (Warning) | `--asharyu-color-semantic-status-sub-surface-primary` |
+| **자 (紫, Ja)** | 하이라이트, 액티브 상태 (Special) | `--asharyu-color-semantic-status-info-active-primary` |
+
+---
+
+## 4. 농담(濃淡) 그림자 및 여백 표준
+
+### 농담 그림자 (Elevation)
+- `--asharyu-elevation-none`: 높이 없음
+- `--asharyu-elevation-dam-muk`: 담묵(淡墨) — 카드, 리스트 아이템 호버, 드롭다운
+- `--asharyu-elevation-jung-muk`: 중묵(中墨) — 팝오버, 플로팅 보드, 툴팁
+- `--asharyu-elevation-nong-muk`: 농묵(濃墨) — 모달 다이얼로그, 바텀 시트
+- `--asharyu-elevation-guk-muk`: 극묵(極墨) — 토스트 알림, 최상위 레이어
+
+### 여백 (Spacing)
+- `--asharyu-spacing-compact` (4px): 아이콘-텍스트 간격
+- `--asharyu-spacing-fine` (8px): 컴팩트 패딩, 태그 내부
+- `--asharyu-spacing-moderate` (12px): 폼 컨트롤 내부 패딩
+- `--asharyu-spacing-base` (16px): 표준 카드 패딩
+- `--asharyu-spacing-void` (24px): 한지의 숨구멍 (표준 컴포넌트 여백)
+- `--asharyu-spacing-wide` (32px): 그룹핑 여백
+- `--asharyu-spacing-spacious` (48px): 섹션 간 여백
+
+---
+
+## 5. 기운생동 (Motion) 인터랙션 규칙
+- **부드러운 전환 (상생 Flow)**: `transition: var(--asharyu-interaction-flow-sang-saeng);`
+- **예리한 결단 피드백 (상극 Decisive)**: `transition: var(--asharyu-interaction-feedback-sang-geuk-decisive);`
+- **담채 번짐 (Bleed Diffusion)**: `transition: var(--asharyu-interaction-theme-bleed);`

package/skills/asharyu-design-system/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: asharyu-design-system
+description: asharyu 디자인 시스템의 수석 아키텍트로서 컴포넌트 설계와 토큰 가이드라인을 제공합니다. 음양오행(陰陽五行)과 수묵·담채화의 미학(0.5px 예리한 묵선, 한지의 여백, 농담 그림자, 기운생동 모션)을 현대 UI로 구현하는 시스템입니다. asharyu 토큰 적용, Figma 디자인 토큰 연동, 신규 컴포넌트 개발, 스타일링 검토 및 WCAG 2.1 접근성 검증 시 반드시 이 스킬을 사용하세요.
+---
+
+# asharyu Architecture & Motion Master
+
+당신은 동양의 음양오행(陰陽五行) 사상과 수묵의 미학을 현대적 인터페이스로 승화시키는 **asharyu** 디자인 시스템의 수석 아키텍트입니다.
+화면 속 기운(氣韻)의 흐름과 필치의 강약을 조절하며 '검의 예리함'과 '붓의 유연함'이 공존하는 **모던 담채(Modern Damchae)** 감성을 구현합니다.
+
+---
+
+## 1. 3대 핵심 철학
+
+1. **예리함(Sharpness)**: 0.5px의 묵선(`--asharyu-stroke-weight-sharp`)처럼 정보의 경계는 명확하고 날카로워야 합니다.
+2. **여백(Void)**: 한지(Yang)의 미학을 살려 정보 사이에 숨구멍(`--asharyu-spacing-void`)을 반드시 확보하십시오.
+3. **농담(Nong-dam)**: 단순한 그림자 대신 수묵화의 농담(담묵·중묵·농묵)으로 디지털 공간의 깊이를 표현하십시오.
+
+---
+
+## 2. 작업 모드
+
+### 모드 A — 토큰 및 설계 가이드라인 제공
+사용자가 컴포넌트 설계 원칙, 특정 UI에 적용할 토큰, 또는 Figma 토큰 연동 방법을 물을 때.
+→ `./references/tokens.md`를 참조하여 정확한 CSS 변수 및 Figma DTCG 토큰을 안내합니다.
+
+### 모드 B — 컴포넌트 직접 구현
+사용자가 새로운 컴포넌트 생성을 요청할 때.
+→ `./references/components.md` 패턴을 준수하여 묵선(Stroke), 여백(Void), 농담(Elevation), 상생 모션(Interaction)이 적용된 코드를 작성합니다.
+
+---
+
+## 3. 핵심 토큰 매핑 가이드
+
+### ① 색상 (오행 & 오간색)
+- **배경 / 텍스트**: `--asharyu-color-semantic-background`, `--asharyu-color-semantic-text`
+- **목(木) - Action**: 실행, 주 버튼 (`--asharyu-color-semantic-action-primary`)
+- **화(火) - Danger**: 경고, 위험, 삭제 (`--asharyu-color-semantic-danger-primary`)
+- **토(土) - Surface**: 카드, 컨테이너 배경 (`--asharyu-color-semantic-surface-primary`)
+- **금(金) - Border**: 경계선, 구분선 (`--asharyu-color-semantic-border-primary`)
+- **수(水) - Info**: 정보, 네비게이션 (`--asharyu-color-semantic-info-primary`)
+- **오간색 (상태 피드백)**:
+  - 녹(綠): 완료/성공 (`--asharyu-color-semantic-status-success-primary`)
+  - 홍(紅): 위험 호버 (`--asharyu-color-semantic-status-alert-hover-primary`)
+  - 벽(碧): 포커스 링 (`--asharyu-color-semantic-status-action-focus-primary`)
+  - 유황(硫黃): 서브 서피스/주의 (`--asharyu-color-semantic-status-sub-surface-primary`)
+  - 자(紫): 액티브 하이라이트 (`--asharyu-color-semantic-status-info-active-primary`)
+
+### ② 공간과 여백 (Spacing & Void)
+- `--asharyu-spacing-compact` (4px / 0.25rem): 찰나 (아이콘 간격)
+- `--asharyu-spacing-fine` (8px / 0.5rem): 세목 (컴팩트 간격)
+- `--asharyu-spacing-moderate` (12px / 0.75rem): 근거리 (리스트)
+- `--asharyu-spacing-base` (16px / 1rem): 평상 (기본 패딩)
+- `--asharyu-spacing-void` (24px / 1.5rem): **여백 (한지의 숨구멍, 표준 컴포넌트 여백)**
+- `--asharyu-spacing-wide` (32px / 2rem): 심원 (섹션 내부)
+- `--asharyu-spacing-spacious` (48px / 3rem): 대여백 (섹션 간)
+
+### ③ 농담 그림자 (Elevation & Depth)
+- `--asharyu-elevation-none`: 평면
+- `--asharyu-elevation-dam-muk`: 담묵(淡墨) — 카드, 드롭다운
+- `--asharyu-elevation-jung-muk`: 중묵(中墨) — 팝오버, 플로팅 보드
+- `--asharyu-elevation-nong-muk`: 농묵(濃墨) — 모달 다이얼로그
+- `--asharyu-elevation-guk-muk`: 극묵(極墨) — 최상위 토스트
+
+### ④ 곡률 (Radius)
+- `--asharyu-radius-sharp` (0px): 검의 예리한 각
+- `--asharyu-radius-delicate` (4px): 절제된 모서리
+- `--asharyu-radius-gentle` (8px): 온화한 곡률
+- `--asharyu-radius-smooth` (12px): 유려한 곡률
+- `--asharyu-radius-prominent` (16px): 넉넉한 둥글림
+- `--asharyu-radius-full` (9999px): 태극, 아바타, 뱃지
+
+### ⑤ 필치와 모션 (Stroke & Motion)
+- **묵선 (Stroke)**: `--asharyu-stroke-weight-sharp` (0.5px), `--asharyu-stroke-weight-fine` (1px)
+- **번짐 (Bleed)**: `--asharyu-stroke-ink-bleed` (blur 1.2px)
+- **상생 모션**: `transition: var(--asharyu-interaction-flow-sang-saeng);`
+- **상극 결단**: `transition: var(--asharyu-interaction-feedback-sang-geuk-decisive);`
+
+---
+
+## 4. Figma 디자인 토큰 연동
+
+Figma 및 Tokens Studio에서 디자인 시스템 토큰을 사용할 때는 다음 파일을 동기화합니다:
+- **Tokens Studio / W3C DTCG**: `packages/design-token/dist/tokens.json`
+- **Figma Variables JSON**: `packages/design-token/dist/figma-variables.json`
+- `pnpm --filter asharyu-design-token build` 실행 시 항상 자동으로 최신화됩니다.
+
+---
+
+## 5. 구현 코드 스니펫 예시
+
+```tsx
+import styled from '@emotion/styled';
+import { tokens } from 'asharyu-design-token';
+
+export const AsharyuContainer = styled.div`
+  background-color: ${tokens.color.semantic.surface.primary};
+  border: ${tokens.stroke.weight.sharp} solid ${tokens.color.semantic.stroke};
+  border-radius: ${tokens.radius.gentle};
+  padding: ${tokens.spacing.void};
+  box-shadow: ${tokens.elevation.damMuk};
+  transition: ${tokens.interaction.flow.sangSaeng};
+
+  &:hover {
+    border-width: ${tokens.stroke.weight.fine};
+    box-shadow: ${tokens.elevation.jungMuk};
+    transform: translateY(-2px);
+  }
+`;
+```

package/skills/asharyu-design-system/references/components.md

@@ -0,0 +1,126 @@
+# asharyu Component Design & Code Guidelines
+
+> 컴포넌트 작성 시 본 가이드라인을 참조하십시오. 모든 구현은 CSS 변수 및 시맨틱 토큰 기반으로 작성되어야 합니다.
+
+---
+
+## 1. 컴포넌트 설계 4대 원칙
+
+1. **획(Stroke) 우선**: 인위적이고 강한 그림자 대신 예리한 묵선(`--asharyu-stroke-weight-sharp`)을 경계로 사용합니다.
+2. **시맨틱 토큰만 사용**: 임의의 색상코드(#7BA2BE, #fff)나 픽셀(16px, 24px)을 인라인으로 작성하지 않습니다.
+3. **여백(Void) 확보**: 숨구멍(`--asharyu-spacing-void`)을 두어 한지의 여백 미학을 살립니다.
+4. **농담(Elevation)의 깊이**: 깊이감 표현 시 `--asharyu-elevation-dam-muk` 등을 사용합니다.
+
+---
+
+## 2. 컴포넌트별 권장 템플릿
+
+### 1) Button (버튼)
+```css
+.asharyu-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--asharyu-spacing-fine) var(--asharyu-spacing-base);
+  border-radius: var(--asharyu-radius-gentle);
+  border: var(--asharyu-stroke-weight-fine) solid var(--asharyu-color-semantic-action-primary);
+  background: var(--asharyu-color-semantic-background);
+  color: var(--asharyu-color-semantic-action-sharp);
+  font-size: var(--asharyu-font-semantic-button);
+  font-weight: var(--asharyu-font-weight-semibold);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+  cursor: pointer;
+}
+
+.asharyu-btn:hover {
+  background: var(--asharyu-color-semantic-action-primary);
+  color: #ffffff;
+  box-shadow: var(--asharyu-elevation-dam-muk);
+  transform: translateY(-1px);
+}
+
+.asharyu-btn:active {
+  background: var(--asharyu-color-semantic-action-deep);
+  transform: translateY(0);
+}
+```
+
+### 2) Card / Surface (카드 및 컨테이너)
+```css
+.asharyu-card {
+  background-color: var(--asharyu-color-semantic-surface-primary);
+  border: var(--asharyu-stroke-weight-sharp) solid var(--asharyu-color-semantic-border-primary);
+  border-radius: var(--asharyu-radius-gentle);
+  padding: var(--asharyu-spacing-void);
+  box-shadow: var(--asharyu-elevation-dam-muk);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+}
+
+.asharyu-card:hover {
+  border-color: var(--asharyu-color-semantic-stroke);
+  box-shadow: var(--asharyu-elevation-jung-muk);
+  transform: translateY(-2px);
+}
+```
+
+### 3) Modal Dialog (모달)
+```css
+.asharyu-modal-mask {
+  position: fixed;
+  inset: 0;
+  z-index: var(--asharyu-z-index-backdrop);
+  background-color: rgba(12, 12, 12, 0.6);
+  backdrop-filter: blur(2px);
+}
+
+.asharyu-modal-content {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: var(--asharyu-z-index-modal);
+  width: 90%;
+  max-width: 520px;
+  background-color: var(--asharyu-color-semantic-background);
+  border: var(--asharyu-stroke-weight-sharp) solid var(--asharyu-color-semantic-stroke);
+  border-radius: var(--asharyu-radius-smooth);
+  padding: var(--asharyu-spacing-void);
+  box-shadow: var(--asharyu-elevation-nong-muk);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+}
+```
+
+### 4) Bottom Navigation (하단 네비게이션)
+```css
+.asharyu-bottom-nav {
+  position: fixed;
+  left: 0;
+  bottom: 0;
+  width: 100%;
+  height: 64px;
+  z-index: var(--asharyu-z-index-docked);
+  background-color: var(--asharyu-color-semantic-background);
+  border-top: var(--asharyu-stroke-weight-sharp) solid var(--asharyu-color-semantic-border-primary);
+  box-shadow: var(--asharyu-elevation-dam-muk);
+  display: flex;
+  align-items: center;
+  justify-content: space-around;
+  padding: 0 var(--asharyu-spacing-base);
+}
+
+.asharyu-bottom-nav-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--asharyu-spacing-compact);
+  color: var(--asharyu-color-semantic-info-soft);
+  text-decoration: none;
+  font-size: var(--asharyu-font-semantic-caption);
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+}
+
+.asharyu-bottom-nav-item.active,
+.asharyu-bottom-nav-item:hover {
+  color: var(--asharyu-color-semantic-action-primary);
+}
+```

package/skills/asharyu-design-system/references/tokens.md

@@ -0,0 +1,103 @@
+# asharyu Design Token Reference
+
+> 모든 CSS 변수는 `--asharyu-{category}-{path}` 형식을 따르며, JavaScript/TypeScript에서는 `tokens.{category}.{path}`로 접근할 수 있습니다.
+> Figma 연동 시 `dist/tokens.json` (Tokens Studio) 및 `dist/figma-variables.json`을 사용합니다.
+
+---
+
+## 1. 색상 토큰 (Color Tokens)
+
+### 원색(原色) — Raw Color Scale
+| 기운 | 의미 | 0 (Subtle) | 1 (Soft) | 2 (Primary) | 3 (Deep) | 4 (Sharp) |
+|---|---|---|---|---|---|---|
+| **양(陽)** | 여백·라이트 배경 | `#ffffff` | `#fefdfa` | `#fdfaf4` | `#f7f2e1` | `#f1ebd0` |
+| **음(陰)** | 묵선·다크 배경 | `#333333` | `#1a1a1a` | `#0c0c0c` | `#060606` | `#000000` |
+| **목(木)** | Action | `#ECF2F6` | `#AEC6D7` | `#7BA2BE` | `#5C83A2` | `#3E6586` |
+| **화(火)** | Danger/Alert | `#F4E7E7` | `#DDA8A8` | `#C96B6B` | `#A74E4E` | `#853131` |
+| **토(土)** | Surface/Container | `#F6F1E3` | `#E8DDBF` | `#D9C58F` | `#B5A16B` | `#917D47` |
+| **금(金)** | Border/Confirm | `#FAFAFA` | `#F2F2F2` | `#E2E2E2` | `#C2C2C2` | `#A2A2A2` |
+| **수(水)** | Navigation/Info | `#999999` | `#555555` | `#333333` | `#222222` | `#111111` |
+| **홍(紅)** | Alert-Hover | `#F2E5E5` | `#E5C7C7` | `#D6A6A6` | `#B37D7D` | `#915555` |
+| **벽(碧)** | Action-Focus | `#E6EEF4` | `#CEDAE3` | `#AFC2D0` | `#8AA1B2` | `#668194` |
+| **녹(綠)** | Success/Safe | `#E7F0E6` | `#CDDAC9` | `#ACC4A6` | `#8AA885` | `#698C64` |
+| **유황(硫黃)** | Sub-Surface/Warning | `#D0CCBE` | `#AFA895` | `#867D61` | `#6D654E` | `#544D3C` |
+| **자(紫)** | Info-Active/Special | `#D1BFC0` | `#A9898B` | `#7E4F53` | `#653A3D` | `#4C2628` |
+
+### 시맨틱 색상 — CSS 변수
+컴포넌트는 언제나 시맨틱 변수를 참조합니다. 라이트/다크(`data-theme="dark"`) 모드 전환 시 CSS 변수가 자동으로 스왑됩니다.
+
+```css
+/* 기본 배경/텍스트 */
+--asharyu-color-semantic-background
+--asharyu-color-semantic-text
+--asharyu-color-semantic-stroke
+
+/* 오행 (각 5단계: subtle, soft, primary, deep, sharp) */
+--asharyu-color-semantic-action-primary     /* 목(木) */
+--asharyu-color-semantic-danger-primary     /* 화(火) */
+--asharyu-color-semantic-surface-primary    /* 토(土) */
+--asharyu-color-semantic-border-primary     /* 금(金) */
+--asharyu-color-semantic-info-primary       /* 수(水) */
+
+/* 오간색 */
+--asharyu-color-semantic-status-success-primary     /* 녹(綠) */
+--asharyu-color-semantic-status-alert-hover-primary  /* 홍(紅) */
+--asharyu-color-semantic-status-action-focus-primary /* 벽(碧) */
+--asharyu-color-semantic-status-sub-surface-primary  /* 유황(硫黃) */
+--asharyu-color-semantic-status-info-active-primary  /* 자(紫) */
+```
+
+---
+
+## 2. 공간과 여백 토큰 (Spacing & Void)
+
+| 키 | CSS 변수 | 값 (rem) | 값 (px) | 용도 및 의미 |
+|---|---|---|---|---|
+| `compact` | `--asharyu-spacing-compact` | `0.25rem` | 4px | 찰나: 아이콘-텍스트 간격, 뱃지 패딩 |
+| `fine` | `--asharyu-spacing-fine` | `0.5rem` | 8px | 세목: 인라인 요소 간격, 좁은 간격 |
+| `moderate` | `--asharyu-spacing-moderate` | `0.75rem` | 12px | 근거리: 폼 컨트롤 및 리스트 아이템 |
+| `base` | `--asharyu-spacing-base` | `1rem` | 16px | 평상: 카드 기본 패딩 |
+| `void` | `--asharyu-spacing-void` | `1.5rem` | 24px | **여백: 한지의 숨구멍 (표준 컴포넌트 여백)** |
+| `wide` | `--asharyu-spacing-wide` | `2rem` | 32px | 심원: 섹션 내부 여백 |
+| `spacious` | `--asharyu-spacing-spacious` | `3rem` | 48px | 대여백: 대형 카드, 섹션 구분 |
+| `vast` | `--asharyu-spacing-vast` | `4rem` | 64px | 광막: 페이지 레벨 여백 |
+
+---
+
+## 3. 곡률 토큰 (Radius)
+
+| 키 | CSS 변수 | 값 | 용도 및 미학 |
+|---|---|---|---|
+| `sharp` | `--asharyu-radius-sharp` | `0px` | 예리함: 검의 단면처럼 각진 모서리 |
+| `delicate` | `--asharyu-radius-delicate` | `0.25rem` (4px) | 정갈함: 태그, 작은 버튼 |
+| `gentle` | `--asharyu-radius-gentle` | `0.5rem` (8px) | 온화함: 카드, 입력창, 드롭다운 |
+| `smooth` | `--asharyu-radius-smooth` | `0.75rem` (12px) | 유려함: 모달 다이얼로그, 플로팅 패널 |
+| `prominent` | `--asharyu-radius-prominent` | `1rem` (16px) | 원만함: 대형 컨테이너 |
+| `full` | `--asharyu-radius-full` | `9999px` | 태극: 원형 버튼, 필, 아바타 |
+
+---
+
+## 4. 농담(濃淡) 그림자 토큰 (Elevation)
+
+| 키 | CSS 변수 | 용도 및 의미 |
+|---|---|---|
+| `none` | `--asharyu-elevation-none` | 높이 없음 |
+| `damMuk` | `--asharyu-elevation-dam-muk` | **담묵(淡墨)**: 은은한 먹빛, 카드 호버 표면, 드롭다운 |
+| `jungMuk` | `--asharyu-elevation-jung-muk` | **중묵(中墨)**: 중간 먹빛, 팝오버, 플로팅 보드 |
+| `nongMuk` | `--asharyu-elevation-nong-muk` | **농묵(濃墨)**: 짙은 먹빛, 모달 다이얼로그 |
+| `gukMuk` | `--asharyu-elevation-guk-muk` | **극묵(極墨)**: 최상위 토스트, 플로팅 긴급 알림 |
+
+---
+
+## 5. 층위 토큰 (Z-Index)
+
+- `--asharyu-z-index-base`: `0`
+- `--asharyu-z-index-docked`: `10` (바텀 네비게이션)
+- `--asharyu-z-index-sticky`: `100` (상단 헤더)
+- `--asharyu-z-index-dropdown`: `200` (드롭다운, 셀렉트)
+- `--asharyu-z-index-backdrop`: `500` (모달 배경 마스크)
+- `--asharyu-z-index-modal`: `600` (모달 본체)
+- `--asharyu-z-index-popover`: `700` (팝오버)
+- `--asharyu-z-index-toast`: `800` (토스트 알림)
+- `--asharyu-z-index-tooltip`: `900` (툴팁)
+- `--asharyu-z-index-max`: `9999` (최고위)