@nexus-cross/design-system 1.0.6-beta.1 → 1.0.6

package/DESIGN.md

@@ -0,0 +1,185 @@
+# NEXUS Design System
+
+## Overview
+
+This document defines the visual identity and design principles for projects using `@nexus-cross/design-system`. AI agents should read this file to generate consistent, on-brand UI across the entire project.
+
+## Visual Theme & Atmosphere
+
+The interface prioritizes **clarity, density, and efficiency**. It targets professional data-driven applications — trading platforms, dashboards, and enterprise tools — where information density matters but readability must not be sacrificed.
+
+Design philosophy:
+- **Functional minimalism**: Every visual element serves a purpose. No decorative flourishes.
+- **High contrast hierarchy**: Clear distinction between primary, secondary, and tertiary information.
+- **Calm neutrals with intentional accent**: The UI stays quiet until interaction or status demands attention.
+- **Dark-mode first**: Designed for prolonged screen use. Light mode is equally supported but dark mode is the primary context.
+
+## Color Palette & Roles
+
+### Background layers (depth ordering)
+
+| Token | Role | Light | Dark |
+|---|---|---|---|
+| `bg-default` | Page-level background | `#FFFFFF` | `#1E232E` |
+| `bg-subtle` | Recessed areas, sidebar backgrounds | `#F3F6F8` | `#161A21` |
+| `bg-strong` | Maximum depth contrast | `#ECF0F2` | `#000000` |
+
+### Surface layers (interactive containers)
+
+| Token | Role | Light | Dark |
+|---|---|---|---|
+| `surface-default` | Cards, panels, modals | `#FFFFFF` | `#1E232E` |
+| `surface-subtle` | Secondary panels, nested containers | `#F3F6F8` | `#252B39` |
+| `surface-strong` | Emphasized containers, active sections | `#ECF0F2` | `#363B4C` |
+| `surface-inverted` | High-contrast banners, tooltips | `#161A21` | `#F3F6F8` |
+
+**Rule**: Always layer surfaces in order: `bg` → `surface-default` → `surface-subtle`. Never place `surface-subtle` directly on `bg-default` — use `surface-default` as an intermediate layer.
+
+### Text hierarchy
+
+| Token | Role | When to use |
+|---|---|---|
+| `text-highlight` | Maximum emphasis | Titles, critical numbers, hero stats |
+| `text-primary` | Default readable text | Body text, labels, headings |
+| `text-secondary` | Supporting information | Descriptions, helper text, timestamps |
+| `text-tertiary` | De-emphasized content | Placeholders, disabled labels |
+| `text-muted` | Lowest priority | Watermarks, footnotes |
+
+**Rule**: Never use `text-muted` for any content the user needs to read. It exists only for decorative or supplementary text.
+
+### Accent colors
+
+| Token | Role |
+|---|---|
+| `accent-primary` (teal/green) | Primary CTA, links, active states, brand identity |
+| `accent-secondary` (purple) | Secondary actions, premium features, alternate highlights |
+
+**Rule**: Use `accent-primary` for the single most important action on screen. If there are multiple CTAs, only ONE gets `accent-primary` — the rest use `outline` or `ghost` variants.
+
+### Status colors
+
+| Token | Role | Usage context |
+|---|---|---|
+| `status-success` | Positive outcomes | Completed actions, profit, online status |
+| `status-warning` | Caution needed | Expiring items, approaching limits |
+| `status-danger` | Errors or destructive | Failed actions, losses, delete confirmations |
+| `status-info` | Neutral information | Tips, update notices, general alerts |
+
+**Rule**: Status colors should only appear in context — on alerts, badges, inline messages, or status indicators. Never use status colors for decorative purposes or general theming.
+
+## Typography Rules
+
+- **Font**: System font stack (inherits from the consuming project).
+- **Scale**: 8 levels from `text-xs` (0.75rem) to `text-xl` (1.25rem) for body, plus heading scale `h7`–`h1` and display `sm`–`lg`.
+- **Weight system**: Regular (400) for body, Medium (500) for labels, Semi-bold (600) for headings, Bold (700) for display and h1–h2.
+- **Letter spacing**: `-0.01em` for body text (tighter for readability at small sizes), `0` for headings and labels.
+- **Line height**: Built into each typography token — do not override.
+
+**Rule**: Use typography tokens (`text-text-sm`, `text-heading-h4`, etc.) instead of raw Tailwind sizes. The tokens include coordinated font-size, font-weight, line-height, and letter-spacing.
+
+## Spacing & Layout
+
+### Spacing scale
+
+- **Padding**: `none` (0), `2xs` (4px), `xs` (8px), `sm` (12px), `md` (16px), `lg` (24px), `xl` (32px), `2xl` (40px)
+- **Gap**: `none` (0), `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px)
+
+### Control sizes
+
+| Size | Height | Use case |
+|---|---|---|
+| `xs` | 24px | Compact tables, inline actions |
+| `sm` | 32px | Secondary actions, filters |
+| `md` | 40px | Default inputs, buttons |
+| `lg` | 48px | Primary CTAs, prominent inputs |
+
+### Border radius
+
+| Token | Value | Use case |
+|---|---|---|
+| `corner-none` | 0px | Tables, full-width elements |
+| `corner-sm` | 4px | Chips, badges, small elements |
+| `corner-md` | 8px | Buttons, inputs, cards (default) |
+| `corner-lg` | 12px | Modals, large cards |
+| `corner-xl` | 16px | Hero sections, featured cards |
+| `corner-full` | 9999px | Avatars, pills, circular buttons |
+
+**Rule**: Be consistent within a feature. If a card uses `corner-md`, its internal buttons should also use `corner-md` or smaller — never larger than their container.
+
+### Breakpoints
+
+| Token | Value | Context |
+|---|---|---|
+| `screen-xs` | 320px | Small mobile |
+| `screen-sm` | 640px | Mobile |
+| `screen-md` | 768px | Tablet |
+| `screen-lg` | 1024px | Desktop |
+| `screen-xl` | 1280px | Wide desktop |
+| `screen-2xl` | 1440px | Ultra-wide |
+
+## Component Styling Principles
+
+- **Buttons**: `corner-md` (8px) radius by default. Primary actions use `accent-primary` fill with white text. Ghost and outline variants for secondary actions.
+- **Inputs**: `corner-md` radius, `border-default` border, `surface-default` background. Focus state uses `accent-primary` ring.
+- **Cards/Panels**: `surface-default` background, `border-default` border (1px), `corner-md` or `corner-lg` radius. No drop shadows by default — use `shadow-sm` only on hover or elevated contexts.
+- **Modals/Drawers**: `surface-default` background, `corner-lg` radius on visible corners. Overlay uses `opacity-overlay-dim` (0.5).
+- **Chips/Tags**: `corner-sm` (4px) radius, compact padding. Use semantic variants (`accent`, `success`, `danger`) to convey meaning.
+- **Tables**: No border-radius on the table itself. Use `surface-subtle` for alternating rows or header background. `border-default` for cell dividers.
+
+## Elevation & Shadows
+
+| Token | Value | Use case |
+|---|---|---|
+| `shadow-none` | `none` | Default state for most elements |
+| `shadow-sm` | `0 1px 2px 0 rgb(0 0 0 / 0.12)` | Hover states, subtle lift |
+| `shadow-md` | `0 1px 3px 0 rgb(0 0 0 / 0.12)` | Dropdown menus, popovers |
+| `shadow-lg` | `0 2px 8px -1px rgb(0 0 0 / 0.12)` | Modals, drawers |
+| `shadow-xl` | `0 4px 15px -3px rgb(0 0 0 / 0.12)` | Toast notifications |
+
+**Rule**: Prefer borders over shadows for static elements. Shadows should imply interactivity or overlay behavior. A card sitting on a page uses a border, not a shadow.
+
+## Animation & Motion
+
+- **Transitions**: 150ms (fast), 200ms (normal), 300ms (slow). Use `cubic-bezier(0, 0, 0.2, 1)` (ease-out) for most transitions.
+- **Enter animations**: 200ms with ease-out. Elements enter from the direction they were triggered (dropdown from top, drawer from side).
+- **Exit animations**: 150ms with `cubic-bezier(0.4, 0, 1, 1)` (ease-in). Exits are faster than enters.
+
+**Rule**: Only animate properties that benefit the user's understanding of state change (opacity, transform). Never animate color or background-color on large surfaces — it feels sluggish.
+
+## Do's and Don'ts
+
+### Colors
+
+- **Do** use semantic token names (`bg-surface-default`, `text-text-primary`), not raw hex values.
+- **Do** use `accent-primary` sparingly — one primary CTA per visible area.
+- **Don't** use `status-danger` red for non-error purposes (e.g., decorative highlights).
+- **Don't** mix `text-muted` with `bg-subtle` — the contrast ratio is too low for accessibility.
+- **Don't** override dark mode colors manually. The token system handles light/dark switching automatically.
+
+### Typography
+
+- **Do** use the typography token scale. Every text element should map to a token.
+- **Don't** use more than 3 different text sizes in a single card or section.
+- **Don't** use `font-bold` (700) for body text. Bold is reserved for headings and display text.
+
+### Layout
+
+- **Do** use the spacing scale tokens for all padding, margin, and gap values.
+- **Do** maintain consistent spacing within a component: if padding-x is `md`, padding-y should be `sm` or `md`, not `2xs`.
+- **Don't** use arbitrary pixel values (e.g., `p-[13px]`). Snap to the nearest spacing token.
+- **Don't** nest more than 3 surface layers deep. If you need more depth, reconsider the information architecture.
+
+### Components
+
+- **Do** use `@nexus-cross/design-system` components for any matching UI element. Never re-implement buttons, inputs, modals, etc.
+- **Do** use `className` prop for style overrides. The `cn()` utility resolves prefix conflicts automatically.
+- **Don't** use `!important` in className overrides — it's unnecessary and breaks the override system.
+- **Don't** wrap design system components in extra `<div>` elements for styling. Use `className` directly.
+- **Don't** import Radix UI, Headless UI, or similar libraries to build components that already exist in the design system.
+
+### Interaction States
+
+- **Do** provide visual feedback for all interactive elements: hover, focus, active, disabled.
+- **Do** use `focus-visible` outlines (not `focus`) to avoid showing focus rings on click.
+- **Don't** remove focus indicators entirely — they are required for keyboard accessibility.
+- **Don't** use `opacity` below `0.4` for disabled states — it becomes invisible in some contexts.

package/cursor-rules/nexus-project-setup.mdc

@@ -1,108 +1,130 @@
 ---
-description: "NEXUS Design System 프로젝트 설정 — 이 프로젝트의 기술 스택과 필수 규칙"
+description: "NEXUS Design System project setup — tech stack and mandatory rules for this project"
 alwaysApply: true
 ---
 
-# NEXUS Design System 프로젝트 설정
+# NEXUS Design System Project Setup
 
-이 프로젝트는 NEXUS Design System을 사용한다. 코드를 생성할 때 반드시 아래를 따른다.
+This project uses NEXUS Design System. All generated code MUST follow the rules below.
 
-## 기술 스택
+## Tech Stack
 
-- **디자인 토큰**: `@nexus-cross/tokens` (CSS 변수 기반)
-- **UI 컴포넌트**: `@nexus-cross/design-system` (React, CVA + Tailwind)
-- **스타일링**: Tailwind CSS v4 + NEXUS 시맨틱 토큰
+- **Design Tokens**: `@nexus-cross/tokens` (CSS variable based)
+- **UI Components**: `@nexus-cross/design-system` (React, CVA + Plain CSS)
+- **Styling**: Tailwind CSS v4 + NEXUS semantic tokens
 
-## 절대 규칙
+## Design System CSS Setup
 
-1. **색상은 반드시 NEXUS 토큰을 사용한다.** 하드코딩 금지.
-   - `bg-bg-default`, `text-text-primary`, `border-border-default` 등
-   - `#ffffff`, `#000000`, `rgb()` 등 직접 색상값 사용 금지
-   - 참고: `.cursor/rules/nexus-tokens.mdc`
+Choose one of two CSS entry points depending on the project environment:
 
-2. **UI 컴포넌트는 반드시 `@nexus-cross/design-system`에서 import한다.** 직접 구현 금지.
-   - `<Button>`, `<TextInput>`, `<Modal>`, `<Toast>` 등
-   - Radix UI, Headless UI 등을 직접 import하여 동일 기능 컴포넌트를 만들지 않는다
-   - 참고: `.cursor/rules/nexus-ui-components.mdc`, `.cursor/rules/nexus-ui-api.mdc`
+| Environment | import | Description |
+|---|---|---|
+| Tailwind v3 / Plain CSS / CSS Modules | `@nexus-cross/design-system/styles` | unlayered CSS |
+| Tailwind v4 | `@nexus-cross/design-system/styles/layer` | wrapped in `@layer nexus` |
 
-3. **Figma 디자인 구현 시:**
-   - NEXUS 토큰과 공용 UI를 적극 활용하되, **Figma 디자인에 충실하게** 구현한다
-   - Figma의 색상값을 보고 가장 가까운 NEXUS 토큰으로 매핑한다
-   - Figma의 UI 요소(버튼, 입력필드 등)는 `@nexus-cross/design-system` 컴포넌트로 구현한다
-   - Figma 디자인과 공용 UI의 스타일이 다를 경우, `className`으로 Figma에 맞게 오버라이드한다
-   - Figma에 없는 커스텀 스타일만 Tailwind 유틸리티로 작성한다
+```tsx
+// Tailwind v3, Plain CSS, CSS Modules
+import '@nexus-cross/design-system/styles'
+
+// Tailwind v4
+import '@nexus-cross/design-system/styles/layer'
+```
+
+For Tailwind v4 projects, also declare layer order in `globals.css`:
+```css
+@layer base, nexus, components, utilities;
+```
+
+## Absolute Rules
+
+1. **Always use NEXUS tokens for colors.** Hardcoding is prohibited.
+   - `bg-bg-default`, `text-text-primary`, `border-border-default`, etc.
+   - Direct color values like `#ffffff`, `#000000`, `rgb()` are prohibited
+   - Reference: `.cursor/rules/nexus-tokens.mdc`
+
+2. **Always import UI components from `@nexus-cross/design-system`.** Direct implementation is prohibited.
+   - `<Button>`, `<TextInput>`, `<Modal>`, `<Toast>`, etc.
+   - Do NOT import Radix UI, Headless UI, etc. to build equivalent components
+   - Reference: `.cursor/rules/nexus-ui-components.mdc`, `.cursor/rules/nexus-ui-api.mdc`
+
+3. **When implementing Figma designs:**
+   - Actively use NEXUS tokens and shared UI, while **faithfully** implementing the Figma design
+   - Map Figma color values to the closest NEXUS token
+   - Implement Figma UI elements (buttons, inputs, etc.) using `@nexus-cross/design-system` components
+   - If shared UI style differs from Figma, override with `className` to match Figma
+   - Only use Tailwind utilities for custom styles not present in Figma
 
-## Figma MCP → NEXUS 변환 워크플로우
+## Figma MCP → NEXUS Conversion Workflow
 
-**Figma MCP 도구(get_design_context, get_code 등)의 출력을 절대 그대로 사용하지 않는다.**
-Figma MCP는 바닐라 HTML + Tailwind를 출력하지만, 이 프로젝트는 `@nexus-cross/design-system`을 사용한다.
-**MCP 출력은 "디자인 의도를 파악하는 참고 자료"일 뿐, 최종 코드가 아니다.**
+**NEVER use Figma MCP tool output (get_design_context, get_code, etc.) as-is.**
+Figma MCP outputs vanilla HTML + Tailwind, but this project uses `@nexus-cross/design-system`.
+**MCP output is only a "reference for understanding design intent", not final code.**
 
-### 필수 3단계 워크플로우
+### Mandatory 3-Step Workflow
 
-**1단계: 디자인 분석 (MCP 호출)**
-- `get_design_context`로 구조와 레이아웃 파악
-- `get_screenshot`으로 시각적 참조 확인
-- 이 단계에서 MCP가 출력하는 코드는 **읽기만 하고 사용하지 않는다**
+**Step 1: Design Analysis (MCP call)**
+- Use `get_design_context` to understand structure and layout
+- Use `get_screenshot` for visual reference
+- Code output from MCP at this stage is **read-only — do not use it**
 
-**2단계: 컴포넌트 매핑 (코드 작성 전에 반드시 수행)**
-MCP 출력의 각 요소를 NEXUS 컴포넌트로 매핑한다. **코드를 한 줄이라도 쓰기 전에** 이 매핑을 먼저 완료한다.
+**Step 2: Component Mapping (MUST be done before writing code)**
+Map each element from MCP output to a NEXUS component. **Complete this mapping before writing a single line of code.**
 
 ```
-MCP 출력 분석:
-- <button> 2개 발견 → Button (primary, ghost)
-- <input type="text"> 1개 → TextInput
-- <select> 1개 → Select + SelectItem
-- 색상 #09B498 → bg-accent-primary (NEXUS 토큰)
-- 색상 #1E232E → text-text-primary (NEXUS 토큰)
-- 간격 16px → var(--spacing-padding-md)
+MCP Output Analysis:
+- 2 <button> found → Button (primary, ghost)
+- 1 <input type="text"> → TextInput
+- 1 <select> → Select + SelectItem
+- Color #09B498 → bg-accent-primary (NEXUS token)
+- Color #1E232E → text-text-primary (NEXUS token)
+- Spacing 16px → var(--spacing-padding-md)
 ```
 
-**3단계: NEXUS 코드 생성**
-매핑을 기반으로 코드를 작성한다. 이 단계에서는 MCP 출력 코드를 참조하지 않는다.
+**Step 3: NEXUS Code Generation**
+Write code based on the mapping. Do NOT reference MCP output code at this stage.
 
-### 컴포넌트 변환 테이블
+### Component Conversion Table
 
-| MCP 출력 (네이티브 HTML) | → NEXUS 컴포넌트 |
+| MCP Output (Native HTML) | → NEXUS Component |
 |---|---|
-| `<button>`, `<a>` 버튼 스타일 | `<Button>` (variant, size 지정) |
-| `<input type="text">` | `<TextInput>` (prefixIcon, suffixIcon 지원) |
-| `<textarea>` | `<TextArea>` (showCount, maxLength 지원) |
+| `<button>`, `<a>` button style | `<Button>` (specify variant, size) |
+| `<input type="text">` | `<TextInput>` (prefixIcon, suffixIcon supported) |
+| `<textarea>` | `<TextArea>` (showCount, maxLength supported) |
 | `<input type="number">` | `<NumberInput>` |
 | `<select>` | `<Select>` + `<SelectItem>` |
 | `<input type="checkbox">` | `<CheckBox>` |
 | `<input type="radio">` | `<RadioGroup>` + `<RadioItem>` |
-| 토글/스위치 UI | `<Switch>` |
-| 탭 UI | `<Tab>` (items 배열로 구성) |
-| 칩/태그/필터/뱃지 | `<Chip>` (variant, onClose 지원) |
-| 아바타/프로필 이미지 | `<Avatar>` (fallback, shape 지원) |
-| 구분선/`<hr>` | `<Divider>` (orientation, variant 지정) |
-| 드롭다운 메뉴 | `<Select>` 또는 `<Popover>` |
-| 툴팁 | `<Tooltip>` |
-| 아코디언/접기 | `<Accordion>` |
-| 캐러셀/슬라이더 | `<Carousel>` + `<CarouselSlide>` |
-| 페이지네이션 | `<Pagination>` |
-| 모달/다이얼로그 | `modal()` + `<ModalTemplate>` |
-| 토스트/알림 | `toast()` |
-| 드로어/바텀시트 | `<Drawer>` |
-| 로딩 스피너 | `<Spinner>` |
-| 스켈레톤 로딩 | `<Skeleton>` |
-| 데이터 리스트 | `<DataList>` |
-| 테이블 | `<Table>` + `<TableRow>` + `<TdColumn>` |
-| 숫자 카운트 애니메이션 | `<Counter>` |
-| 카운트다운 타이머 | `<Countdown>` |
-| 텍스트 말줄임 | `<Ellipsis>` |
-| 흐르는 텍스트 | `<Marquee>` |
-| 무한 스크롤 리스트 | `<InfiniteScroll>` |
-| 대량 리스트 (가상 스크롤) | `<VirtualList>` / `<VirtualGrid>` |
-
-**위 교체를 하지 않고 네이티브 HTML을 사용하면 규칙 위반이다.**
-
-### 색상 변환 테이블
-
-MCP가 출력하는 색상값을 NEXUS 토큰으로 변환한다:
-
-| MCP 출력 색상 | → NEXUS 토큰 |
+| Toggle/Switch UI | `<Switch>` |
+| Tab UI | `<Tab>` (configured via items array) |
+| Chip/Tag/Filter/Badge | `<Chip>` (variant, onClose supported) |
+| Avatar/Profile image | `<Avatar>` (fallback, shape supported) |
+| Divider/`<hr>` | `<Divider>` (specify orientation, variant) |
+| Dropdown menu | `<Select>` or `<Popover>` |
+| Tooltip | `<Tooltip>` |
+| Accordion/Collapsible | `<Accordion>` |
+| Carousel/Slider | `<Carousel>` + `<CarouselSlide>` |
+| Pagination | `<Pagination>` |
+| Modal/Dialog | `modal()` + `<ModalTemplate>` |
+| Toast/Notification | `toast()` |
+| Drawer/Bottom sheet | `<Drawer>` |
+| Loading spinner | `<Spinner>` |
+| Skeleton loader | `<Skeleton>` |
+| Data list | `<DataList>` |
+| Table | `<Table>` + `<TableRow>` + `<TdColumn>` |
+| Number count animation | `<Counter>` |
+| Countdown timer | `<Countdown>` |
+| Text ellipsis | `<Ellipsis>` |
+| Scrolling text | `<Marquee>` |
+| Infinite scroll list | `<InfiniteScroll>` |
+| Large list (virtual scroll) | `<VirtualList>` / `<VirtualGrid>` |
+
+**Using native HTML instead of the replacements above is a rule violation.**
+
+### Color Conversion Table
+
+Convert MCP output colors to NEXUS tokens:
+
+| MCP Output Color | → NEXUS Token |
 |---|---|
 | `#FFFFFF`, `bg-white` | `bg-bg-default` |
 | `#F3F6F8`, `bg-gray-50` | `bg-bg-subtle` |
@@ -117,59 +139,59 @@ MCP가 출력하는 색상값을 NEXUS 토큰으로 변환한다:
 | `#FF9D00`, `bg-amber-*` | `bg-status-warning` |
 | `#0095FF`, `bg-blue-*` | `bg-status-info` |
 
-위에 정확히 매칭되지 않는 색상은 가장 가까운 NEXUS 토큰을 선택한다.
-**어떤 경우에도 hex 값이나 Tailwind 기본 색상(bg-blue-500 등)을 사용하지 않는다.**
+For colors not exactly matching above, choose the closest NEXUS token.
+**Under no circumstances use hex values or default Tailwind colors (bg-blue-500, etc.).**
 
-### Button variant 판단 기준
+### Button Variant Decision Criteria
 
-Figma에서 버튼의 시각적 스타일을 보고 variant를 결정한다:
+Determine the variant based on visual style in Figma:
 
-| Figma 시각적 특징 | → variant |
+| Figma Visual Characteristic | → variant |
 |---|---|
-| 채워진 accent 색상 배경 (초록/틸) | `variant="primary"` |
-| 채워진 회색/중립 배경 | `variant="secondary"` |
-| 테두리만 있고 배경 투명 | `variant="outline"` |
-| 배경/테두리 없이 텍스트만 | `variant="ghost"` |
-| 빨간색/위험 표시 | `variant="danger"` |
+| Filled accent color background (green/teal) | `variant="primary"` |
+| Filled gray/neutral background | `variant="secondary"` |
+| Border only, transparent background | `variant="outline"` |
+| No background/border, text only | `variant="ghost"` |
+| Red/danger indicator | `variant="danger"` |
 
-### 자기 검증 체크리스트
+### Self-Verification Checklist
 
-코드를 출력하기 전에 아래를 확인한다:
+Verify the following before outputting code:
 
-- [ ] `<button>`, `<input>`, `<select>`, `<textarea>` 등 네이티브 HTML 폼 요소가 없는가?
-- [ ] hex 색상값(`#...`)이 없는가?
-- [ ] Tailwind 기본 색상(`bg-blue-500`, `text-gray-900` 등)이 없는가?
-- [ ] 모든 import가 `@nexus-cross/design-system`에서 오는가?
-- [ ] 모달은 `ModalTemplate`으로 감쌌는가?
-- [ ] 간격/크기에 하드코딩 px이 없는가?
+- [ ] No native HTML form elements (`<button>`, `<input>`, `<select>`, `<textarea>`, etc.)?
+- [ ] No hex color values (`#...`)?
+- [ ] No default Tailwind colors (`bg-blue-500`, `text-gray-900`, etc.)?
+- [ ] All imports from `@nexus-cross/design-system`?
+- [ ] Modals wrapped with `ModalTemplate`?
+- [ ] No hardcoded px values for spacing/sizing?
 
-**하나라도 실패하면 코드를 수정한 후 출력한다.**
+**If any check fails, fix the code before outputting.**
 
 ```tsx
-// ❌ Figma MCP 코드 그대로 사용 (금지)
-<button className="bg-[#09B498] text-white px-4 py-2 rounded-lg">확인</button>
-<input className="border border-[#C6D0DA] px-3 py-2 rounded" placeholder="검색" />
-<div className="w-8 h-8 rounded-full bg-gray-200" /> {/* 아바타 */}
-<hr className="border-[#ECF0F2]" /> {/* 구분선 */}
-
-// ✅ NEXUS 컴포넌트로 교체 (필수)
-<Button variant="primary">확인</Button>
-<TextInput placeholder="검색" prefixIcon={<SearchIcon />} />
+// WRONG — Using Figma MCP code as-is (prohibited)
+<button className="bg-[#09B498] text-white px-4 py-2 rounded-lg">Confirm</button>
+<input className="border border-[#C6D0DA] px-3 py-2 rounded" placeholder="Search" />
+<div className="w-8 h-8 rounded-full bg-gray-200" /> {/* avatar */}
+<hr className="border-[#ECF0F2]" /> {/* divider */}
+
+// CORRECT — Replace with NEXUS components (required)
+<Button variant="primary">Confirm</Button>
+<TextInput placeholder="Search" prefixIcon={<SearchIcon />} />
 <Avatar fallback="JD" size="sm" />
 <Divider />
 ```
 
-## 전역 설정 (앱 루트에 필수)
+## Global Setup (Required at App Root)
 
-아래 컴포넌트를 앱 루트(layout.tsx 또는 App.tsx)에 **반드시** 배치한다.
+The following components MUST be placed at the app root (layout.tsx or App.tsx).
 
-| 컴포넌트 | import | 필수 조건 | 설명 |
-|----------|--------|----------|------|
-| `<ModalContainer />` | `@nexus-cross/design-system/modal` | `modal()` 또는 `useModal()` 사용 시 | 모달 렌더링 컨테이너 |
-| `<Toaster />` | `@nexus-cross/design-system` | `toast()` 사용 시 | 토스트 알림 렌더링 |
+| Component | import | Required When | Description |
+|---|---|---|---|
+| `<ModalContainer />` | `@nexus-cross/design-system/modal` | Using `modal()` or `useModal()` | Modal rendering container |
+| `<Toaster />` | `@nexus-cross/design-system` | Using `toast()` | Toast notification renderer |
 
 ```tsx
-// layout.tsx 또는 App.tsx
+// layout.tsx or App.tsx
 import { ModalContainer } from '@nexus-cross/design-system/modal';
 import { Toaster } from '@nexus-cross/design-system';
 
@@ -184,87 +206,87 @@ export default function RootLayout({ children }) {
 }
 ```
 
-**전역 설정이 필요 없는 컴포넌트** (별도 Provider 없이 바로 사용 가능):
-- Tooltip (내부에 Provider 내장)
-- Popover, Drawer, Select, Accordion 등 모든 나머지 컴포넌트
+**Components that do NOT need global setup** (usable directly without Provider):
+- Tooltip (Provider built-in)
+- Popover, Drawer, Select, Accordion, and all other components
 
-## Import 패턴
+## Import Patterns
 
 ```tsx
-// 일반 컴포넌트
+// General components
 import { Button, TextInput, TextArea, Select, Switch, Chip, Spinner, Divider } from '@nexus-cross/design-system';
 
-// 오버레이 컴포넌트
+// Overlay components
 import { Tooltip, Popover, Drawer, Accordion } from '@nexus-cross/design-system';
 
-// 토스트
+// Toast
 import { toast, Toaster } from '@nexus-cross/design-system';
 
-// 모달 시스템 (별도 서브패스)
+// Modal system (separate subpath)
 import { modal, useModal, ModalTemplate, ModalContainer } from '@nexus-cross/design-system/modal';
 
-// 토큰 (JS API가 필요한 경우만)
+// Tokens (only when JS API is needed)
 import { getTheme } from '@nexus-cross/tokens';
 ```
 
-## 모달 작성 규칙
+## Modal Writing Rules
 
-모달 컴포넌트는 **반드시 `ModalTemplate`으로 감싸야 한다.** `<div>`만으로 모달을 만들지 않는다.
+Modal components **MUST be wrapped with `ModalTemplate`.** Do NOT create modals with plain `<div>`.
 
 ```tsx
-// ✅ 올바른 모달
+// CORRECT modal
 import { ModalTemplate } from '@nexus-cross/design-system/modal';
 
 function MyModal({ close, resolve }: { close: () => void; resolve: (value: any) => void }) {
   return (
-    <ModalTemplate title="제목" close={close}>
-      <p className="text-text-secondary">내용</p>
-      <Button onClick={() => resolve({ confirmed: true })}>확인</Button>
+    <ModalTemplate title="Title" close={close}>
+      <p className="text-text-secondary">Content</p>
+      <Button onClick={() => resolve({ confirmed: true })}>Confirm</Button>
     </ModalTemplate>
   );
 }
 
-// 호출
+// Call
 const result = await modal({ component: MyModal });
 ```
 
 ```tsx
-// ❌ 잘못된 모달 — ModalTemplate 없이 div만 사용
+// WRONG modal — using div without ModalTemplate
 function MyModal({ close }: { close: () => void }) {
   return (
     <div className="p-6 bg-white rounded-lg">
-      <h2>제목</h2>
-      <p>내용</p>
+      <h2>Title</h2>
+      <p>Content</p>
     </div>
   );
 }
 ```
 
-## 토스트 사용 규칙
+## Toast Usage Rules
 
 ```tsx
 import { toast } from '@nexus-cross/design-system';
 
-toast('기본 메시지');
-toast.success('성공!');
-toast.error('오류가 발생했습니다');
-toast.loading('처리 중...');
+toast('Default message');
+toast.success('Success!');
+toast.error('An error occurred');
+toast.loading('Processing...');
 ```
 
-루트에 `<Toaster />` 없이 `toast()`를 호출하면 아무것도 표시되지 않는다.
+Calling `toast()` without `<Toaster />` at the root will display nothing.
 
-## 토큰 사용 예시
+## Token Usage Examples
 
 ```tsx
-// ✅ 올바른 사용
+// CORRECT usage
 <div className="bg-bg-default text-text-primary border border-border-default">
-  <Button variant="primary">확인</Button>
-  <TextInput placeholder="검색..." />
+  <Button variant="primary">Confirm</Button>
+  <TextInput placeholder="Search..." />
 </div>
 
-// ❌ 잘못된 사용
+// WRONG usage
 <div className="bg-white text-gray-900 border border-gray-200">
-  <button className="bg-green-500 text-white px-4 py-2 rounded">확인</button>
-  <input className="border border-gray-300 px-3 py-2" placeholder="검색..." />
+  <button className="bg-green-500 text-white px-4 py-2 rounded">Confirm</button>
+  <input className="border border-gray-300 px-3 py-2" placeholder="Search..." />
 </div>
 ```