atomsystem 0.4.3 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atomsystem",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "type": "module",
   "homepage": "https://system.atomground.com",
   "repository": {
@@ -58,6 +58,7 @@
     "start": "next start",
     "lint": "next lint",
     "lint:design": "impeccable detect app components css presets",
+    "audit:recursive": "tsx scripts/audit-recursive.ts",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:report": "playwright show-report"

package/presets/agents.guide.md

@@ -0,0 +1,49 @@
+# 🏛️ AtomSystem Universal AI Coding Guidelines
+
+> 이 프로젝트는 **AtomSystem (Universal Design Token & Agentic UI System)**을 공식 디자인 시스템으로 채택하고 있습니다.  
+> 모든 AI 어시스턴트(Cursor, Claude, Copilot, Antigravity, Windsurf 등)는 새로운 UI를 구현하거나 기존 코드를 리팩토링할 때 아래 원칙을 **절대적으로 준수**해야 합니다.
+
+---
+
+## 🚀 1. 핵심 아키텍처: 4단계 레고 조립 파이프라인
+
+```
+[1. W3C DTCG Tokens] ──> [2. UI Components] ──> [3. Content Blocks] ──> [4. UX Patterns / Templates]
+ (CSS 변수: 색상/간격)     (Button, Card, Badge)   (RealtimeChart, Chat)     (Dashboard, Checkout)
+```
+
+1. **Tokens (`atom.design.md`, `tokens/token.json`)**:
+   - 모든 색상, 간격, 보더, 폰트 크기는 반드시 CSS 변수(`var(--text-primary)`, `var(--bg-primary)`, `var(--border-subtle)` 등)를 사용합니다.
+   - **하드코딩 절대 금지**: `text-blue-500`, `bg-[#123456]`, `p-[13px]`, `border-gray-200` 등 임의의 인라인 값 사용을 엄격히 금지합니다.
+2. **Components (`atom.components.md`, `components/ui/`)**:
+   - 화면을 구성하는 기초 원자입니다 (`Button`, `Card`, `Badge`, `Input`, `Table`, `Tabs`, `Switch`, `Modal` 등).
+   - 날림 원시 태그(`<button>`, `<div class="rounded-lg ...">`)를 작성하지 않고, 검증된 `components/ui/` 컴포넌트를 import하여 사용합니다.
+3. **Blocks (`atom.blocks.md`, `components/blocks/`)**:
+   - 컴포넌트들을 조립하여 완성한 독립 기능형 콘텐츠 블록입니다 (`realtime-chart`, `interactive-chat`, `pricing-table`, `card-list`, `file-explorer` 등).
+   - 블록에 필요한 새 컴포넌트가 없다면, 컴포넌트를 먼저 `components/ui/`에 신설하고 블록을 조립합니다 (**Component-First 원칙**).
+4. **UX Patterns & Templates (`atom.uxPattern.md`)**:
+   - 완성된 블록과 레이아웃을 조립하여 완성형 사용자 경험(대시보드, 폼 유효성, 결제 플로우 등)을 구축합니다.
+
+---
+
+## 🎨 2. 표준 시맨틱 CSS 변수 규격
+
+| 용도 | 라이트 모드 | 다크 모드 | CSS 변수 표기 |
+|---|---|---|---|
+| 기본 배경 | `#ffffff` | `#0a0a0a` | `var(--bg-primary)` 또는 `bg-(--bg-primary)` |
+| 보조 표면 | `#f9f9fb` | `#141414` | `var(--bg-secondary)` 또는 `bg-(--bg-secondary)` |
+| 본문 텍스트 | `#111111` | `#ededed` | `var(--text-primary)` 또는 `text-(--text-primary)` |
+| 보조 텍스트 | `#666666` | `#a0a0a0` | `var(--text-secondary)` 또는 `text-(--text-secondary)` |
+| 옅은 보더 | `#eaeaea` | `#222222` | `var(--border-subtle)` 또는 `border-(--border-subtle)` |
+| 강조 보더 | `#d4d4d8` | `#333333` | `var(--border-strong)` 또는 `border-(--border-strong)` |
+| 기본 곡률 | `6px` | `6px` | `var(--radius)` 또는 `rounded-(--radius)` |
+| 작은 곡률 | `4px` | `4px` | `var(--radius-sm)` 또는 `rounded-(--radius-sm)` |
+
+---
+
+## 💡 3. AI 작업 시 필수 체크리스트
+- [ ] Tailwind 임의의 컬러(`blue-500`, `gray-100`)를 하드코딩하지 않고 시맨틱 토큰 변수를 사용했는가?
+- [ ] 버튼, 카드, 뱃지 등 UI를 날림 태그 대신 `components/ui/`에서 import하여 조립했는가?
+- [ ] 복잡한 화면을 만들 때 `atom.blocks.md` 및 `atom.uxPattern.md`의 검증된 패턴을 따랐는가?
+- [ ] 빈 데이터 상태(Empty State), 로딩 상태(Loading/Skeleton), 키보드 포커스링(A11y)을 보장했는가?
+- [ ] 10px 극소 폰트나 과도한 그라디언트, 형광색 등 AI 슬롭(Visual Noise)을 배제했는가?

package/presets/blocks.md

@@ -0,0 +1,101 @@
+# 🧱 AtomSystem Design Blocks Guide (atom.blocks.md)
+
+> 페이지 전체가 아닌, 페이지 내부에 결합(Composition)되는 실무 완성형 독립 콘텐츠 블록 명세서입니다.  
+> **Component-First 원칙**: 블록은 날림 HTML 태그가 아니라, 반드시 검증된 원자 컴포넌트(`Button`, `Card`, `Badge`, `Input`, `Table` 등)를 레고 조각 삼아 조립합니다.
+
+---
+
+## 🧱 4대 레고 조립 파이프라인 (Lego Assembly Pipeline)
+
+```
+[1. W3C DTCG Tokens] ──> [2. UI Components] ──> [3. Content Blocks] ──> [4. Templates / Screens]
+ (CSS 변수: 색상/간격)     (Button, Card, Badge)   (RealtimeChart, Chat)     (Dashboard, Checkout)
+```
+
+1. **Tokens**: 블록의 모든 곡률, 간격, 보더, 컬러는 CSS 변수(`var(--atom-*)`, `var(--bg-primary)` 등)로 주입됩니다.
+2. **Components**: 블록은 반드시 `components/ui/`의 순수 아톰 컴포넌트를 임포트하여 조립합니다.
+3. **Blocks**: 특정 기능/콘텐츠(차트, 챗, 요금제 등)를 완결성 있게 수행하는 독립 모듈입니다.
+4. **Templates**: 1개 이상의 블록과 레이아웃이 결합되어 최종 화면(대시보드, 랜딩 등)을 구성합니다.
+
+---
+
+## 📦 7대 핵심 디자인 블록 카탈로그
+
+### 1. 실시간 차트 & 틱 시계열 블록 (`realtime-chart`)
+- **분류**: `chart` (Analytics & FinTech)
+- **조립 컴포넌트**: `Card`, `Button`, `Badge`
+- **주입 토큰**: `--text-primary`, `--bg-primary`, `--border-subtle`, `--radius`
+- **핵심 기능**:
+  - 1초 단위 실시간 틱 데이터 스트리밍 시뮬레이션 (재생/일시정지 토글)
+  - 0KB 순수 SVG 기반 라인 차트 및 캔들스틱(Candle) 모드 전환
+  - 시간 범위 필터 (1m, 5m, 1h, 1d) 및 24h High/Low/Volume 요약 스탯
+- **결합 템플릿**: SaaS 성과 분석 대시보드 메인 캔버스, 금융 자산 모니터링 화면
+
+### 2. 인터랙티브 AI 챗 & 메신저 블록 (`interactive-chat`)
+- **분류**: `chat` (AI Assistant & Messenger)
+- **조립 컴포넌트**: `Card`, `Input`, `Button`, `Badge`
+- **주입 토큰**: `--text-primary`, `--bg-primary`, `--border-subtle`, `--radius`
+- **핵심 기능**:
+  - 발신/수신 말풍선 정렬 (송신자: 우측 고대비, 수신자: 좌측 서피스)
+  - 자주 묻는 질문(FAQ) 원클릭 빠른 전송 제안 칩 (가로 스크롤)
+  - 타이핑 중 애니메이션 인디케이터 및 자동 스크롤(Auto-scroll)
+- **결합 템플릿**: 온디맨드 AI 코파일럿 드로어, 1:1 고객 상담 센터 화면
+
+### 3. 플랜 비교 & 가격 정책 블록 (`pricing-table`)
+- **분류**: `pricing` (Conversion & Subscriptions)
+- **조립 컴포넌트**: `Card`, `Button`, `Badge`
+- **주입 토큰**: `--text-primary`, `--bg-primary`, `--border-subtle`, `--border-strong`
+- **핵심 기능**:
+  - 월간 / 연간(20% 할인) 결제 주기 원클릭 토글 스위치 및 금액 실시간 재계산
+  - 3단계 티어(Starter, Pro, Enterprise) 비교 구조
+  - 추천 플랜(Pro) 1px 볼드 보더 하이라이트 및 원클릭 CTA
+  - 티어별 포함/미포함 기능 체크리스트
+- **결합 템플릿**: SaaS 구독 랜딩 페이지 요금표, 업그레이드 모달
+
+### 4. 반응형 필터 카드 컬렉션 블록 (`card-list`)
+- **분류**: `card` (Showcase & Directory)
+- **조립 컴포넌트**: `Card`, `Button`, `Badge`, `Input`
+- **주입 토큰**: `--text-primary`, `--bg-primary`, `--border-subtle`
+- **핵심 기능**:
+  - 실시간 검색 인풋 및 카테고리 필터 탭
+  - 그리드(3열) ↔ 리스트(1열) 뷰포트 원클릭 토글
+  - 북마크 토글 및 호버 피드백
+- **결합 템플릿**: 리소스 라이브러리, 컴포넌트 카탈로그, 앱스토어 탐색기
+
+### 5. 비용 시뮬레이터 & 캐러셀 슬라이더 블록 (`interactive-slider`)
+- **분류**: `slider` (Simulation & Control)
+- **조립 컴포넌트**: `Card`, `Slider`, `Button`, `Badge`
+- **주입 토큰**: `--text-primary`, `--bg-primary`, `--border-subtle`
+- **핵심 기능**:
+  - 사용자 수/스토리지 용량 슬라이더 조절에 따른 실시간 견적 동적 계산기
+  - 스와이프 가능한 슬라이드 캐러셀 쇼케이스 탭
+- **결합 템플릿**: 클라우드 인프라 견적 계산기, 온보딩 인터랙티브 가이드
+
+### 6. 비즈니스 메트릭 & 4대 KPI 스탯 블록 (`metric-stats`)
+- **분류**: `stats` (Executive Dashboard)
+- **조립 컴포넌트**: `Card`, `Badge`
+- **주입 토큰**: `--text-primary`, `--bg-primary`, `--border-subtle`
+- **핵심 기능**:
+  - 매출, 활성 유저, 가동률, 전환율 4대 핵심 지표 요약
+  - 전주 대비 증감 배지 (+14.8%) 및 미니 인라인 스파크라인 트렌드
+- **결합 템플릿**: 관리자 대시보드 상단 서머리, 프로젝트 오버뷰
+
+### 7. 프로덕션 파일 탐색기 & 계층 트리 블록 (`file-explorer`)
+- **분류**: `files` (Developer Tools)
+- **조립 컴포넌트**: `Card`, `Button`, `Badge`
+- **주입 토큰**: `--text-primary`, `--bg-primary`, `--border-subtle`
+- **핵심 기능**:
+  - 폴더 계층 트리 사이드바 (확장/축소 아코디언)
+  - 디렉토리 경로 브레드크럼 및 그리드/리스트 토글
+  - 파일 확장자별 아이콘 매핑 및 실시간 파일 미리보기 패널
+- **결합 템플릿**: 웹 IDE 코드 편집기, 클라우드 스토리지 매니저
+
+---
+
+## 🛠 AI Agent를 위한 블록 생성 지침
+1. **임의의 Tailwind 색상 하드코딩 엄격 금지**:
+   - `text-blue-500`, `bg-gray-100` 대신 시맨틱 토큰 `text-(--text-primary)`, `bg-(--bg-primary)`, `border-(--border-subtle)`을 사용합니다.
+2. **원시 `<button>` 날림 태그 금지**:
+   - 블록 내부의 모든 액션 버튼은 `components/ui/Button.tsx`의 `<Button variant="primary|secondary|outline|ghost">` 컴포넌트로 조립합니다.
+3. **상태 피드백 보장**:
+   - 로딩, 빈 데이터(Empty State), 활성/비활성 상태를 반드시 명시합니다.

package/presets/components.md

@@ -0,0 +1,142 @@
+# 🧱 AtomSystem UI Components Guide (atom.components.md)
+
+> W3C DTCG 표준 토큰과 결합된 고접근성 0KB 런타임 UI 원자/분자 컴포넌트 규격서입니다.  
+> 모든 컴포넌트는 `components/ui/`에서 import하여 사용합니다.
+
+---
+
+## 📦 컴포넌트 목록 및 사용법
+
+### 1. Button (`components/ui/Button.tsx`)
+```tsx
+import { Button } from '@/components/ui';
+
+<Button variant="primary" size="md">확인</Button>
+<Button variant="secondary">보조 액션</Button>
+<Button variant="outline">테두리 버튼</Button>
+<Button variant="ghost">고스트 버튼</Button>
+<Button variant="destructive">삭제</Button>
+<Button loading>처리 중...</Button>
+```
+- **Variants**: `primary`, `secondary`, `outline`, `ghost`, `destructive`
+- **Sizes**: `sm`, `md`, `lg`
+- **A11y**: `aria-disabled`, 키보드 엔터/스페이스 포커스 링 보장
+
+### 2. Card (`components/ui/Card.tsx`)
+```tsx
+import { Card } from '@/components/ui';
+
+<Card className="p-5 border border-(--border-subtle) bg-(--bg-primary)">
+  <h3>카드 제목</h3>
+  <p>카드 본문</p>
+</Card>
+```
+- 1px 시맨틱 보더와 토큰 기반 곡률(`--radius`) 적용
+
+### 3. Badge (`components/ui/Badge.tsx`)
+```tsx
+import { Badge } from '@/components/ui';
+
+<Badge variant="primary">추천</Badge>
+<Badge variant="secondary">일반</Badge>
+<Badge variant="success">+14.8%</Badge>
+<Badge variant="warning">점검 예정</Badge>
+<Badge variant="destructive">실패</Badge>
+```
+
+### 4. Input (`components/ui/Input.tsx`)
+```tsx
+import { Input } from '@/components/ui';
+
+<Input
+  placeholder="이메일 주소 입력"
+  status="default" // "error" | "success"
+  errorMessage="올바른 이메일 형식이 아닙니다."
+/>
+```
+
+### 5. Table (`components/ui/Table.tsx`)
+```tsx
+import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@/components/ui';
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>사용자</TableHead>
+      <TableHead>플랜</TableHead>
+      <TableHead>상태</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>홍길동</TableCell>
+      <TableCell>Pro</TableCell>
+      <TableCell><Badge variant="success">활성</Badge></TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### 6. Tabs (`components/ui/Tabs.tsx`)
+```tsx
+import { TabsList, TabsTrigger } from '@/components/ui';
+
+<TabsList>
+  <TabsTrigger active={tab === '1'} onClick={() => setTab('1')}>월간</TabsTrigger>
+  <TabsTrigger active={tab === '2'} onClick={() => setTab('2')}>연간</TabsTrigger>
+</TabsList>
+```
+
+### 7. Switch (`components/ui/Switch.tsx`)
+```tsx
+import { Switch } from '@/components/ui';
+
+<Switch checked={enabled} onChange={setEnabled} label="알림 받기" />
+```
+
+### 8. Modal (`components/ui/Modal.tsx`)
+```tsx
+import { Modal } from '@/components/ui';
+
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} title="확인">
+  <p>정말 삭제하시겠습니까?</p>
+</Modal>
+```
+- **A11y**: `role="dialog"`, `aria-modal="true"`, ESC 키 누름 시 자동 닫기
+
+### 9. Container (`components/ui/Container.tsx`)
+```tsx
+import { Container } from '@/components/ui';
+
+<Container size="xl" gutters center>
+  <h1>대시보드</h1>
+</Container>
+```
+- **연동 토큰**: `--atom-container-sm` (640px), `--atom-container-md` (768px), `--atom-container-lg` (1024px), `--atom-container-xl` (1280px), `--atom-container-2xl` (1536px), `--atom-layout-gutter` (16px/24px)
+- **용도**: 모든 페이지의 표준 가로폭 및 안전 여백 통일 (하드코딩 금지)
+
+### 10. Layout (`components/ui/Layout.tsx`)
+```tsx
+import { Layout, Container, Stack, Grid, Section } from '@/components/ui';
+
+<Layout>
+  <Layout.Header sticky>헤더 네비바</Layout.Header>
+  <Layout.Content>
+    <Container size="xl">
+      <Section spacing="md">
+        <Stack gap="6">
+          <Grid cols={3} gap="4">
+            <Card>1</Card>
+            <Card>2</Card>
+            <Card>3</Card>
+          </Grid>
+        </Stack>
+      </Section>
+    </Container>
+  </Layout.Content>
+  <Layout.Footer>푸터</Layout.Footer>
+</Layout>
+```
+- **연동 토큰**: `--atom-space-*` (4px, 8px, 12px, 16px, 24px, 32px), `Section` spacing 토큰
+- **용도**: 전역 페이지 쉘 구조화 및 스택/그리드 기반의 제로 하드코딩 여백 배치
+

package/tokens/token.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://design-tokens.github.io/community-group/format/",
   "name": "AtomDesignToken System",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "color": {
     "brand": {
       "color-primary": {
@@ -290,6 +290,68 @@
       "variable": "--atom-shadow-xl"
     }
   },
+  "layout": {
+    "container": {
+      "sm": {
+        "$value": "640px",
+        "$type": "dimension",
+        "$description": "인증 폼, 결제 모달, 단일 컬럼 콘텐츠",
+        "variable": "--atom-container-sm"
+      },
+      "md": {
+        "$value": "768px",
+        "$type": "dimension",
+        "$description": "블로그 아티클, 프로필 뷰어, 설정 폼",
+        "variable": "--atom-container-md"
+      },
+      "lg": {
+        "$value": "1024px",
+        "$type": "dimension",
+        "$description": "표준 랩탑 뷰, 카탈로그 카드 그리드",
+        "variable": "--atom-container-lg"
+      },
+      "xl": {
+        "$value": "1280px",
+        "$type": "dimension",
+        "$description": "기본 데스크톱 와이드 레이아웃 및 대시보드 허브",
+        "variable": "--atom-container-xl"
+      },
+      "2xl": {
+        "$value": "1536px",
+        "$type": "dimension",
+        "$description": "초광폭 고밀도 데이터 그리드, 핀테크 차트 워크스페이스",
+        "variable": "--atom-container-2xl"
+      },
+      "full": {
+        "$value": "100%",
+        "$type": "dimension",
+        "$description": "전체 화면 플루이드 유연 뷰어",
+        "variable": "--atom-container-full"
+      }
+    },
+    "gutter": {
+      "gutter": {
+        "$value": "16px",
+        "$type": "dimension",
+        "$description": "화면 좌우 기본 안전 여백 (Safe Padding)",
+        "variable": "--atom-layout-gutter"
+      },
+      "gutter-lg": {
+        "$value": "24px",
+        "$type": "dimension",
+        "$description": "데스크톱 화면 좌우 안전 여백",
+        "variable": "--atom-layout-gutter-lg"
+      }
+    },
+    "gap": {
+      "gap": {
+        "$value": "32px",
+        "$type": "dimension",
+        "$description": "섹션과 섹션 간의 기본 레이아웃 간격",
+        "variable": "--atom-layout-gap"
+      }
+    }
+  },
   "presets": {
     "toss": {
       "name": "토스 스타일 (Toss)",

package/tokens/tokens.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://design-tokens.github.io/community-group/format/",
   "name": "AtomDesignToken System",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "color": {
     "brand": {
       "color-primary": {
@@ -290,6 +290,68 @@
       "variable": "--atom-shadow-xl"
     }
   },
+  "layout": {
+    "container": {
+      "sm": {
+        "$value": "640px",
+        "$type": "dimension",
+        "$description": "인증 폼, 결제 모달, 단일 컬럼 콘텐츠",
+        "variable": "--atom-container-sm"
+      },
+      "md": {
+        "$value": "768px",
+        "$type": "dimension",
+        "$description": "블로그 아티클, 프로필 뷰어, 설정 폼",
+        "variable": "--atom-container-md"
+      },
+      "lg": {
+        "$value": "1024px",
+        "$type": "dimension",
+        "$description": "표준 랩탑 뷰, 카탈로그 카드 그리드",
+        "variable": "--atom-container-lg"
+      },
+      "xl": {
+        "$value": "1280px",
+        "$type": "dimension",
+        "$description": "기본 데스크톱 와이드 레이아웃 및 대시보드 허브",
+        "variable": "--atom-container-xl"
+      },
+      "2xl": {
+        "$value": "1536px",
+        "$type": "dimension",
+        "$description": "초광폭 고밀도 데이터 그리드, 핀테크 차트 워크스페이스",
+        "variable": "--atom-container-2xl"
+      },
+      "full": {
+        "$value": "100%",
+        "$type": "dimension",
+        "$description": "전체 화면 플루이드 유연 뷰어",
+        "variable": "--atom-container-full"
+      }
+    },
+    "gutter": {
+      "gutter": {
+        "$value": "16px",
+        "$type": "dimension",
+        "$description": "화면 좌우 기본 안전 여백 (Safe Padding)",
+        "variable": "--atom-layout-gutter"
+      },
+      "gutter-lg": {
+        "$value": "24px",
+        "$type": "dimension",
+        "$description": "데스크톱 화면 좌우 안전 여백",
+        "variable": "--atom-layout-gutter-lg"
+      }
+    },
+    "gap": {
+      "gap": {
+        "$value": "32px",
+        "$type": "dimension",
+        "$description": "섹션과 섹션 간의 기본 레이아웃 간격",
+        "variable": "--atom-layout-gap"
+      }
+    }
+  },
   "presets": {
     "toss": {
       "name": "토스 스타일 (Toss)",