asharyu-design-token 2.0.4 → 2.1.0

package/README.md

@@ -1,135 +1,222 @@
-# Asharyu-design-token
-
-> 디자인 토큰
-
-## Install
-
-1.npm
-
-```
-npm i asharyu-design-token
-```
-
-2.yarn
-
-```
-yarn add asharyu-design-token
-```
-
-## Usage
-
-1. css
-
-```js
-import 'normalize.css';
-import 'asharyu-design-token/index.css';
-```
-
-2.js(ts)
-
-```js
-import Token from 'asharyu-design-token';
-```
-
-## Concept
-
-**asharyu**는 동양 철학인 음양오행설을 현대적인 인터페이스 가이드라인에 투영한 디자인 시스템입니다. 디자인 감각에만 의존하지 않고, 요소 간의 상생(相生)과 상극(相剋) 관계를 통해 논리적이고 의미론적인(Semantic) UI 구성을 지향합니다.
-
-- **음양 (Yin-Yang):** 명암의 대비를 통해 라이트/다크 테마의 질서와 반전을 정의합니다.
-- **오행 (Five Elements):** 목(Action), 화(Danger), 토(Surface), 금(Border), 수(Info)의 기운으로 기능적 위계를 구분합니다.
-- **필치와 검의 예리함:** 수묵의 번짐(Bleed)과 날카로운 필압(Stroke Weight)을 인터랙션과 스타일의 핵심 요소로 삼습니다.
-
-### 오행의 기능적 역할 (Functional Roles)
-
-| 오행 (Element) | 시맨틱 역할 | 주요 용도 | 기운의 성질 |
-| :--- | :--- | :--- | :--- |
-| **목 (Wood)** | `Action` | 주 버튼(Primary), 시작, 긍정 상태 | 솟구치는 시작 |
-| **화 (Fire)** | `Danger` | 경고, 오류, 삭제, 중요 알림 | 확산되는 경고 |
-| **토 (Earth)** | `Surface` | 카드, 컨테이너 배경, 머무르는 공간 | 머무르는 안정 |
-| **금 (Metal)** | `Border` | 보조 버튼(Confirm), 경계선, 결단 | 응축된 결단 |
-| **수 (Water)** | `Info` | 정보 전달, 네비게이션, 탐색 | 흐르는 정보 |
-
-이러한 시맨틱 정의를 통해 개발자와 디자이너는 색상 선택 시 주관적인 감각 대신 시스템의 논리(상생/상극)에 따라 의사결정을 내릴 수 있습니다.
-
-### 상생과 상극의 인터랙션 (Interaction Guide)
-
-디자인 시스템의 동적인 기운(Motion)은 오행의 순환 논리인 상생과 상극에 기반합니다.
-
-| 분류 (Category) | 기운 (Ki-Un) | 인터랙션 성격 | 권장 사용 사례 |
-| :--- | :--- | :--- | :--- |
-| **상생 (Sangsaeng)** | `Gentle` | 부드럽고 유연한 연결 | 긍정적인 여정, 일반적인 상태 변화, 페이지 전환 |
-| **상극 (Sanggeuk)** | `Sharp / Spread` | 예리한 대비와 제어 | 경고, 오류, 중요 알림, 삭제 시의 긴장감 표현 |
-
-- **상생 Flow (`flow.sangSaeng`):** 물이 나무를 자라게 하듯 자연스러운 흐름을 표현할 때 사용하며, 사용자 경험의 연속성을 확보합니다.
-- **상극 Feedback (`feedback.sangGeuk...`):** 화기가 금속을 녹이듯 강한 시각적 제어가 필요할 때 사용합니다. 예리한 필압의 결단(`decisive`) 혹은 충돌하여 널리 퍼지는 경고(`spread`)로 구분됩니다.
-
-이러한 인터랙션 원칙은 단순한 애니메이션을 넘어, 인터페이스 내의 기운의 흐름과 긴장을 조절하는 핵심 장치입니다.
-
-### 인터랙션 토큰 사용 예제 (Usage Examples)
-
-**1. 순수 CSS에서 사용**
-
-```css
-/* 예: 버튼 호버 시 상생 흐름 애니메이션 적용 */
-.my-button {
-  transition: var(--asharyu-interaction-flow-sang-saeng);
-  /* 다른 스타일 */
-}
-
-/* 예: 경고 메시지 등장 시 상극 확산 애니메이션 적용 */
-.alert-message {
-  animation: fade-in-spread 0.8s var(--asharyu-interaction-feedback-sang-geuk-spread);
-  /* 다른 스타일 */
-}
-
-@keyframes fade-in-spread {
-  from { opacity: 0; transform: scale(0.9); }
-  to { opacity: 1; transform: scale(1); }
-}
-```
-
-**2. Emotion (React)에서 사용**
-
-```tsx
-import styled from '@emotion/styled';
-import { tokens } from 'asharyu-design-token'; // JS 브릿지 토큰 임포트
-
-const AnimatedButton = styled.button`
-  transition: ${tokens.interaction.flow.sangSaeng};
-  background-color: ${tokens.color.semantic.action.primary};
-  color: ${tokens.color.semantic.background};
-  /* 다른 스타일 */
-`;
-```
-## Token Structure
-
-모든 토큰은 `--asharyu-` 접두사를 가지며, **Raw(원형)**와 **Semantic(의미)** 계층으로 나뉩니다.
-
-### 1. Naming Convention (Sword's Edge)
-모든 키값은 CamelCase에서 Kebab-case로 자동 변환되어 생성됩니다.
-예: `yinText` (JS) -> `--asharyu-color-semantic-yin-text` (CSS)
-
-### 2. Semantic Layers
-테마 전환 시 시맨틱 토큰의 값은 자동으로 상응하는 음/양의 값으로 교체됩니다.
-
-```css
-:root {
-  /* 🎨 Color: Raw & Semantic */
-  --asharyu-color-raw-wood-2: #7BA2BE;
-  --asharyu-color-semantic-action-primary: var(--asharyu-color-raw-wood-2);
-  --asharyu-color-semantic-background: #fdfaf4;
-  --asharyu-color-semantic-text: #0c0c0c;
-
-  /* ✍️ Typography */
-  --asharyu-font-semantic-h1: 4.25rem;
-  --asharyu-font-semantic-body1: 1rem;
-
-  /* 🌬️ Motion & Stroke */
-  --asharyu-motion-duration-bleed: 0.8s;
-  --asharyu-stroke-weight-heavy: 3px;
-}
-```
-
-## License
-
-This project is licensed under the [Apache 2.0 License](/LICENSE).
+# asharyu-design-token
+
+<div align="center">
+
+**A Design Token System Inspired by Yin-Yang, Wu Xing, and Korean Traditional Ink & Wash Aesthetics.**  
+*음양오행(陰陽五行)과 수묵·담채화의 미학을 담은 디자인 토큰 시스템*
+
+[English](README.md) | [한국어](README.ko.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md)
+
+[![npm version](https://img.shields.io/npm/v/asharyu-design-token.svg?style=flat-square&color=7BA2BE)](https://www.npmjs.com/package/asharyu-design-token)
+[![license](https://img.shields.io/npm/l/asharyu-design-token.svg?style=flat-square&color=3E6586)](https://github.com/yoonjonglyu/asharyu-design/blob/main/LICENSE)
+[![WCAG 2.1 AAA](https://img.shields.io/badge/WCAG%202.1-AAA%20(18.5:1)-success?style=flat-square&color=ACC4A6)](https://www.w3.org/WAI/WCAG21/quickref/)
+[![Figma DTCG](https://img.shields.io/badge/Figma-W3C%20DTCG%20%2F%20Tokens%20Studio-blue?style=flat-square&color=8AA1B2)](https://tokens.studio/)
+
+</div>
+
+---
+
+## 📖 Table of Contents
+1. [Installation](#1-installation)
+2. [Quick Start](#2-quick-start)
+3. [Design Philosophy](#3-design-philosophy)
+4. [Token Specifications & CSS Variables](#4-token-specifications--css-variables)
+5. [🎨 Figma Integration](#5--figma-integration)
+6. [🤖 AI Agent Integration](#6--ai-agent-integration)
+7. [Accessibility & Testing](#7-accessibility--testing)
+8. [License](#8-license)
+
+---
+
+## 1. Installation
+
+```bash
+# npm
+npm install asharyu-design-token
+
+# pnpm
+pnpm add asharyu-design-token
+
+# yarn
+yarn add asharyu-design-token
+```
+
+---
+
+## 2. Quick Start
+
+### 1) Load Global CSS Variables
+Import the compiled stylesheet at your application's entry point (`index.tsx`, `App.tsx`, or main CSS):
+
+```tsx
+import 'asharyu-design-token/index.css';
+```
+
+### 2) Use with CSS-in-JS (Emotion / Styled-Components)
+Import the typed `tokens` bridge object for full TypeScript autocompletion and CSS variable references:
+
+```tsx
+import styled from '@emotion/styled';
+import { tokens } from 'asharyu-design-token';
+
+const AsharyuCard = 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);
+  }
+`;
+```
+
+### 3) Yin-Yang (Light / Dark) Theme Switching
+Switch themes instantaneously via the `data-theme` attribute:
+
+```html
+<!-- Light Mode (Yang 陽) : Default -->
+<html data-theme="light"> ... </html>
+
+<!-- Dark Mode (Yin 陰) -->
+<html data-theme="dark"> ... </html>
+```
+
+---
+
+## 3. Design Philosophy
+
+**asharyu** translates Eastern cosmological principles—**Yin-Yang (陰陽)**, **Wu Xing (五行, Five Elements)**, and the ink gradation of **Sumuk-damchae (수묵·담채화)**—into a rigorous, logic-driven digital design system.
+
+1. **Sharpness (예리함 / 묵선)**: Precise, razor-sharp 0.5px ink strokes (`--asharyu-stroke-weight-sharp`) define clear information boundaries.
+2. **Void (여백 / 한지의 숨구멍)**: Breathing room (`--asharyu-spacing-void`) reflects the aesthetic of Hanji paper, avoiding cramped layouts.
+3. **Nong-dam Elevation (농담의 깊이)**: Replaces artificial shadows with the natural depth of ink diffusion (Dam-muk, Jung-muk, Nong-muk).
+4. **Ki-un Motion (기운생동)**: Animations are choreographed according to Sang-saeng (相生, harmonic flow) and Sang-geuk (相剋, decisive feedback).
+
+---
+
+## 4. Token Specifications & CSS Variables
+
+### ① Color Tokens
+
+#### Wu Xing (五行) — Primary Action & Surface
+| Element | Semantic Role | Usage | CSS Variable |
+|---|---|---|---|
+| **Yang / Yin (Theme)** | Background & Text | Hanji white / Deep abyssal ink | `--asharyu-color-semantic-background`, `-text` |
+| **Wood (木, 목)** | `Action` | Primary action, buttons, links | `--asharyu-color-semantic-action-primary` |
+| **Fire (火, 화)** | `Danger` | Danger, alert, destructive actions | `--asharyu-color-semantic-danger-primary` |
+| **Earth (土, 토)** | `Surface` | Cards, container surfaces, resting areas | `--asharyu-color-semantic-surface-primary` |
+| **Metal (金, 금)** | `Border` | Borders, dividers, structured edges | `--asharyu-color-semantic-border-primary` |
+| **Water (水, 수)** | `Info` | Navigation, auxiliary information, flow | `--asharyu-color-semantic-info-primary` |
+
+#### Five Intermediate Colors (五間色, 오간색) — Secondary Status & Feedback
+| Color | Semantic Role | Formulation | CSS Variable |
+|---|---|---|---|
+| **Nok (綠, 녹)** | `Success` | Wood + Earth | `--asharyu-color-semantic-status-success-primary` |
+| **Hong (紅, 홍)** | `Alert-Hover` | Fire + Metal | `--asharyu-color-semantic-status-alert-hover-primary` |
+| **Byeok (碧, 벽)** | `Focus` | Wood + Metal | `--asharyu-color-semantic-status-action-focus-primary` |
+| **Yu (硫黃, 유황)** | `Warning / Sub-Surface` | Earth + Water | `--asharyu-color-semantic-status-sub-surface-primary` |
+| **Ja (紫, 자)** | `Special / Active` | Fire + Water | `--asharyu-color-semantic-status-info-active-primary` |
+
+---
+
+### ② Spacing & Void
+
+| Key | CSS Variable | Rem | Px | Concept & Usage |
+|---|---|---|---|---|
+| `compact` | `--asharyu-spacing-compact` | `0.25rem` | 4px | Instant: icon spacing, tag padding |
+| `fine` | `--asharyu-spacing-fine` | `0.5rem` | 8px | Fine: inline element spacing |
+| `moderate` | `--asharyu-spacing-moderate` | `0.75rem` | 12px | Near: form controls & list items |
+| `base` | `--asharyu-spacing-base` | `1rem` | 16px | Regular: standard card padding |
+| `void` | `--asharyu-spacing-void` | `1.5rem` | 24px | **Void: breathing space (standard component margin)** |
+| `wide` | `--asharyu-spacing-wide` | `2rem` | 32px | Distant: section inner grouping |
+| `spacious` | `--asharyu-spacing-spacious` | `3rem` | 48px | Spacious: inter-section gap |
+| `vast` | `--asharyu-spacing-vast` | `4rem` | 64px | Vast: page-level margins |
+
+---
+
+### ③ Radius (Curvature)
+
+- `--asharyu-radius-sharp`: `0px` (Sword's edge, crisp orthogonal corners)
+- `--asharyu-radius-delicate`: `0.25rem` (4px, understated curves for tags)
+- `--asharyu-radius-gentle`: `0.5rem` (8px, warm organic curvature for cards)
+- `--asharyu-radius-smooth`: `0.75rem` (12px, flowing curves for dialogs)
+- `--asharyu-radius-prominent`: `1rem` (16px, large surface rounding)
+- `--asharyu-radius-full`: `9999px` (Taegeuk, circular avatars & pills)
+
+---
+
+### ④ Nong-dam Elevation & Shadows
+
+Depth tokens that dynamically respond to Yin-Yang (Light/Dark) themes via ink diffusion:
+- `--asharyu-elevation-none`: Flat surface
+- `--asharyu-elevation-dam-muk`: **Dam-muk (淡墨, Light Ink)** — card hover, dropdowns
+- `--asharyu-elevation-jung-muk`: **Jung-muk (中墨, Medium Ink)** — popovers, floating boards
+- `--asharyu-elevation-nong-muk`: **Nong-muk (濃墨, Dark Ink)** — modal dialogs
+- `--asharyu-elevation-guk-muk`: **Guk-muk (極墨, Deepest Ink)** — floating toasts & critical alerts
+
+---
+
+### ⑤ Typography
+
+- **Families**:
+  - `--asharyu-font-family-serif`: Lyrical Hanji 바탕/명조 (`Gowun Batang`, `Noto Serif KR`)
+  - `--asharyu-font-family-sans`: Modern readable sans-serif (`Pretendard`, system-ui)
+  - `--asharyu-font-family-mono`: Monospace for code & numbers (`JetBrains Mono`, monospace)
+- **Weights**:
+  - `--asharyu-font-weight-light` (300 / Dam), `--asharyu-font-weight-regular` (400 / Sang), `--asharyu-font-weight-semibold` (600 / Nong), `--asharyu-font-weight-bold` (700 / Pil)
+- **Line Heights**:
+  - `--asharyu-font-line-height-tight` (1.25), `--asharyu-font-line-height-normal` (1.5), `--asharyu-font-line-height-relaxed` (1.75)
+
+---
+
+## 5. 🎨 Figma Integration
+
+`asharyu-design-token` automatically generates and exports design token files ready for Figma:
+
+### Method A: Tokens Studio for Figma (Recommended)
+1. Open the **Tokens Studio for Figma** plugin in Figma.
+2. Under `Settings` > `Sync Providers`, select **GitHub** or choose **Load from local file**.
+3. Select **`node_modules/asharyu-design-token/dist/tokens.json`**.
+4. The `global`, `light`, and `dark` token sets will be loaded with colors, spacing, radius, typography, and shadows fully synchronized.
+
+### Method B: Native Figma Variables
+1. Use **`node_modules/asharyu-design-token/dist/figma-variables.json`**.
+2. Import via Figma Variables REST API or a variable import plugin to create `Color (Raw)`, `Color (Semantic)` (with Light/Dark modes), and `Spacing & Radius` collections.
+
+---
+
+## 6. 🤖 AI Agent Integration
+
+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
+```
+
+---
+
+## 7. Accessibility & Testing
+
+- **WCAG 2.1 AAA Compliant**:
+  - Light mode text-on-background contrast: **18.52 : 1** (far exceeds the 7.0:1 AAA standard)
+  - Dark mode text-on-background contrast: **18.52 : 1** (far exceeds the 7.0:1 AAA standard)
+- **Interactive Boundaries & Focus**:
+  - State lines (`action.sharp`, `danger.sharp`) meet WCAG 2.1 AA (≥ 4.5:1).
+- **Automated Validation Suite**:
+  - `pnpm test` verifies token integrity, CSS variable parity, and WCAG contrast ratios with 100% test coverage.
+
+---
+
+## 8. License
+
+This project is licensed under the [Apache 2.0 License](https://github.com/yoonjonglyu/asharyu-design/blob/main/LICENSE).

package/README.zh-TW.md

@@ -0,0 +1,222 @@
+# asharyu-design-token
+
+<div align="center">
+
+**融合陰陽五行與水墨·淡彩畫美學的設計權杖（Design Token）系統**  
+*A Design Token System Inspired by Yin-Yang, Wu Xing, and Korean Traditional Ink & Wash Aesthetics.*
+
+[English](README.md) | [한국어](README.ko.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md)
+
+[![npm version](https://img.shields.io/npm/v/asharyu-design-token.svg?style=flat-square&color=7BA2BE)](https://www.npmjs.com/package/asharyu-design-token)
+[![license](https://img.shields.io/npm/l/asharyu-design-token.svg?style=flat-square&color=3E6586)](https://github.com/yoonjonglyu/asharyu-design/blob/main/LICENSE)
+[![WCAG 2.1 AAA](https://img.shields.io/badge/WCAG%202.1-AAA%20(18.5:1)-success?style=flat-square&color=ACC4A6)](https://www.w3.org/WAI/WCAG21/quickref/)
+[![Figma DTCG](https://img.shields.io/badge/Figma-W3C%20DTCG%20%2F%20Tokens%20Studio-blue?style=flat-square&color=8AA1B2)](https://tokens.studio/)
+
+</div>
+
+---
+
+## 📖 目錄
+1. [安裝 (Installation)](#1-安裝-installation)
+2. [快速入門 (Quick Start)](#2-快速入門-quick-start)
+3. [核心美學與設計哲學 (Design Philosophy)](#3-核心美學與設計哲學-design-philosophy)
+4. [Token 規範與 CSS 變數 (Token Specifications)](#4-token-規範與-css-變數-token-specifications)
+5. [🎨 Figma 設計權杖整合 (Figma Integration)](#5--figma-設計權杖整合-figma-integration)
+6. [🤖 AI Agent 整合 (Agent & Skill Integration)](#6--ai-agent-整合-agent--skill-integration)
+7. [無障礙與品質驗證 (Accessibility)](#7-無障礙與品質驗證-accessibility)
+8. [授權條款 (License)](#8-授權條款-license)
+
+---
+
+## 1. 安裝 (Installation)
+
+```bash
+# npm
+npm install asharyu-design-token
+
+# pnpm
+pnpm add asharyu-design-token
+
+# yarn
+yarn add asharyu-design-token
+```
+
+---
+
+## 2. 快速入門 (Quick Start)
+
+### 1) 載入全域 CSS 變數
+在專案的入口檔案（如 `index.tsx`, `App.tsx` 或全域 CSS）中引入樣式表：
+
+```tsx
+import 'asharyu-design-token/index.css';
+```
+
+### 2) 在 CSS-in-JS (Emotion / Styled-Components) 中使用
+匯入具備完整 TypeScript 型別提示的 `tokens` 物件，安全引用 CSS 變數：
+
+```tsx
+import styled from '@emotion/styled';
+import { tokens } from 'asharyu-design-token';
+
+const AsharyuCard = 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);
+  }
+`;
+```
+
+### 3) 陰陽（深色 / 淺色）主題切換
+透過 `data-theme` 屬性即可瞬間切換全域主題：
+
+```html
+<!-- 陽（淺色模式）: 預設值 -->
+<html data-theme="light"> ... </html>
+
+<!-- 陰（深色模式） -->
+<html data-theme="dark"> ... </html>
+```
+
+---
+
+## 3. 核心美學與設計哲學 (Design Philosophy)
+
+**asharyu** 並非單憑主觀感官，而是將東方傳統的**陰陽（Yin-Yang）**、**五行（Wu Xing）**以及水墨淡彩畫的**筆觸與濃淡（Nong-dam）**轉化為嚴謹、邏輯化的數位介面規範。
+
+1. **銳利之墨線 (Sharpness)**：以如刀裁般鮮明的 0.5px 墨線（`--asharyu-stroke-weight-sharp`）定義清晰的資訊界線。
+2. **宣紙之留白 (Void)**：注重呼吸空間（`--asharyu-spacing-void`），展現傳統紙張的留白意境，避免擁擠堆砌。
+3. **濃淡層次 (Nong-dam Elevation)**：捨棄生硬的人工投影，以水墨暈染的濃淡（淡墨、中墨、濃墨、極墨）呈現溫潤而深邃的空間感。
+4. **氣韻生動動效 (Ki-un Motion)**：動畫遵循五行之相生（順暢柔和之流動）與相剋（銳利決斷之回饋）邏輯。
+
+---
+
+## 4. Token 規範與 CSS 變數 (Token Specifications)
+
+### ① 色彩 (Color Tokens)
+
+#### 五行 (五行) — 主要操作與容器表面 (Primary Semantic)
+| 元素 | 語意功能 | 主要用途 | 代表 CSS 變數 |
+|---|---|---|---|
+| **陽 / 陰 (Theme)** | 背景與正文文字 | 宣紙米白、深淵墨黑 | `--asharyu-color-semantic-background`, `-text` |
+| **木 (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)
+| 間色 | 語意功能 | 配方關係 | 代表 CSS 變數 |
+|---|---|---|---|
+| **綠 (Nok)** | `Success` | 木 + 土 | `--asharyu-color-semantic-status-success-primary` |
+| **紅 (Hong)** | `Alert-Hover` | 火 + 金 | `--asharyu-color-semantic-status-alert-hover-primary` |
+| **碧 (Byeok)** | `Focus` | 木 + 金 | `--asharyu-color-semantic-status-action-focus-primary` |
+| **硫黃 (Yu)** | `Warning / Sub-Surface` | 土 + 水 | `--asharyu-color-semantic-status-sub-surface-primary` |
+| **紫 (Ja)** | `Special / Active` | 火 + 水 | `--asharyu-color-semantic-status-info-active-primary` |
+
+---
+
+### ② 留白與間距 (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 | 廣漠：頁面層級留白 |
+
+---
+
+### ③ 圓角曲率 (Radius)
+
+- `--asharyu-radius-sharp`: `0px`（劍鋒銳角，俐落直角）
+- `--asharyu-radius-delicate`: `0.25rem`（4px，微斂圓角）
+- `--asharyu-radius-gentle`: `0.5rem`（8px，溫和自然曲率）
+- `--asharyu-radius-smooth`: `0.75rem`（12px，流暢圓弧）
+- `--asharyu-radius-prominent`: `1rem`（16px，大容器圓角）
+- `--asharyu-radius-full`: `9999px`（太極，圓形頭像與膠囊按鈕）
+
+---
+
+### ④ 濃淡陰影 (Elevation & Depth)
+
+依據水墨暈染濃淡，在深淺模式中自動感應的立體深淺 Token：
+- `--asharyu-elevation-none`: 平面無陰影
+- `--asharyu-elevation-dam-muk`: **淡墨 (Dam-muk)** — 卡片懸停、下拉選單
+- `--asharyu-elevation-jung-muk`: **中墨 (Jung-muk)** — 浮動面板、氣泡提示
+- `--asharyu-elevation-nong-muk`: **濃墨 (Nong-muk)** — 對話方塊（Modal）
+- `--asharyu-elevation-guk-muk`: **極墨 (Guk-muk)** — 最上層浮動通知（Toast）
+
+---
+
+### ⑤ 字體排印 (Typography)
+
+- **字系 (Font Family)**：
+  - `--asharyu-font-family-serif`: 展現宣紙纖維感的明體 / 楷體 (`Gowun Batang`, `Noto Serif KR`)
+  - `--asharyu-font-family-sans`: 現代清晰之無襯線黑體 (`Pretendard`, system-ui)
+  - `--asharyu-font-family-mono`: 程式碼等寬字型 (`JetBrains Mono`, monospace)
+- **筆壓字重 (Font Weight)**：
+  - `--asharyu-font-weight-light`（300/淡）、`regular`（400/常）、`semibold`（600/濃）、`bold`（700/筆）
+- **行高 (Line Height)**：
+  - `--asharyu-font-line-height-tight`（1.25）、`normal`（1.5）、`relaxed`（1.75）
+
+---
+
+## 5. 🎨 Figma 設計權杖整合 (Figma Integration)
+
+`asharyu-design-token` 在建置時會自動生成可直接匯入 Figma 的權杖檔案：
+
+### 方法 A：使用 Tokens Studio for Figma 外掛（推薦）
+1. 在 Figma 中開啟 **Tokens Studio for Figma** 外掛。
+2. 於 `Settings` > `Sync Providers` 選擇 **GitHub** 或選擇 **Load from local file**。
+3. 選取 **`node_modules/asharyu-design-token/dist/tokens.json`**。
+4. 即可載入 `global`, `light`, `dark` 權杖集，將色彩、留白、圓角、陰影完整套用至 Figma 設計稿。
+
+### 方法 B：原生 Figma Variables
+1. 使用 **`node_modules/asharyu-design-token/dist/figma-variables.json`**。
+2. 透過 Figma Variables REST API 或匯入外掛，一鍵生成 `Color (Raw)`, `Color (Semantic)`（含 Light/Dark 模式）及 `Spacing & Radius` 變數集合。
+
+---
+
+## 6. 🤖 AI Agent 整合 (Agent & Skill Integration)
+
+與 **Antigravity**, **Cursor**, **Claude Code**, **GitHub Copilot** 等 AI 助手結伴程式設計時，可自動載入 Asharyu 設計系統規範：
+
+### 1) Antigravity 工作區支援
+本套件內建 `.agents/skills/asharyu-design-system/` 技能與 `.agents/rules/asharyu-design-system.md` 規則，確保 AI 生成程式碼時不發生樣式偏移。
+
+### 2) 直接引用提示詞指南
+可直接將隨附的提示指南注入 AI 系統提示中：
+```
+node_modules/asharyu-design-token/SKILL.md
+```
+
+---
+
+## 7. 無障礙與品質驗證 (Accessibility)
+
+- **符合 WCAG 2.1 AAA 級規範**：
+  - 淺色模式文字對比度：**18.52 : 1**（遠高於 7.0:1 之 AAA 標準）
+  - 深色模式文字對比度：**18.52 : 1**（遠高於 7.0:1 之 AAA 標準）
+- **UI 邊界線與焦點圈**：
+  - 狀態線條均達到 WCAG 2.1 AA 規範（≥ 4.5:1）。
+- **自動化測試覆蓋**：
+  - 每次建置皆執行自動化測試，確保 Token 結構、CSS 變數一致性與對比度達成率達 100%。
+
+---
+
+## 8. 授權條款 (License)
+
+本專案採用 [Apache 2.0 授權條款](https://github.com/yoonjonglyu/asharyu-design/blob/main/LICENSE)。