Skip to content

docs(design-system): v2.2.0 동기화 — content fundamentals, animations, dual palette #589

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thxforall merged 7 commits into from
May 28, 2026
Merged

docs(design-system): v2.2.0 동기화 — content fundamentals, animations, dual palette #589

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
65beacb
docs(design-system): bump README to v2.2.0 with content fundamentals …
thxforall May 28, 2026
4a14cdc
docs(design-system): add content-fundamentals.md
thxforall May 28, 2026
19b0801
docs(design-system): add animations.md catalog
thxforall May 28, 2026
4a90093
docs(design-system): patterns.md add 5.4 dual palette usage
thxforall May 28, 2026
8bc84c2
docs(design-system): tokens.md add magazine palette sub-table
thxforall May 28, 2026
db3988e
docs(agent): rewrite design-system-llm.md as v2.2.0 1-pager SSOT
thxforall May 28, 2026
d7ee5ce
docs(agent): design-system-summary.md add v2.2.0 entry
thxforall May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 101 additions & 75 deletions docs/agent/design-system-llm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,82 @@
title: Design System — LLM Reference
owner: human
status: approved
updated: 2026-04-17
updated: 2026-05-28
tags: [agent, design-system]
---

# Design System — LLM Reference
# Design System — LLM Reference (v2.2.0)

Implementation: `packages/web/lib/design-system/`. Human-facing 토큰·패턴 상세는 [docs/design-system/](../design-system/)를 SSOT로 둡니다.
<!-- keep in sync with design-system@2.2.0 -->

## Import path
decoded Design System v2.2 1-pager SSOT. Human-facing 토큰·패턴 상세는 [docs/design-system/](../design-system/)를 SSOT로 둡니다.
구현체: `packages/web/lib/design-system/` + `packages/web/app/globals.css`.

## Visual Foundations

### Dual palette (surface-scoped)

- **Editorial surfaces** (`/`, `/magazine/*`, spot detail) → magazine palette, **fixed dark**, `.dark` 토글 무관.
- Tokens: `magPrimary` (`--mag-primary` `#050505`), `magAccent` (`--mag-accent` `#eafd67`), `magBg` (`--mag-bg` `#050505`), `magText` (`--mag-text` `#f5f5f5`)
- Source: `packages/web/lib/design-system/tokens.ts:176-179`, `packages/web/app/globals.css:109-112` (#573)
- ThemeToggle 숨김
- **Product UI** (`/explore`, `/profile`, `/rankings`, `/admin`, `/auth`, `/upload`, `/settings`) → semantic OKLCH, `next-themes` `.dark` 토글 활성.
- Tokens: `primary`, `secondary`, `muted`, `accent`, `destructive`, `background`, `foreground`, `card`, `border`, `ring`
- **No-mix rule**: 두 팔레트를 한 페이지에서 섞지 말 것. 섞여야 한다면 surface 경계가 잘못 그어진 것.

### Typography

- Playfair Display (serif) — 제목/브랜드/Hero
- Inter (sans) — 본문/UI/버튼
- JetBrains Mono (mono) — 코드
- **IBM Plex Mono** — DecodedLogo / HeroCover inline 사용 (현재 `next/font` 미적용, 점진 마이그레이션 대상)

크기 스케일: `hero(64px) / h1(48) / h2(36) / h3(28) / h4(24) / body(16) / small(14) / caption(12)`.

### Spacing / Radius / Shadow

4px 기반 spacing (`0` ~ `32`), `--radius` 기준 borderRadius (`sm` ~ `2xl`, `full`), CSS-var 기반 shadow (`2xs` ~ `2xl`).

### Z-index layers

`base(0) / floating(10) / dropdown(20) / header(30) / sidebar(40) / modalBackdrop(50) / modal(60) / toast(70) / tooltip(100)`.

### Navigation facts

| Surface | Height | Source |
| ---------------- | ------------------------ | ------------------------------------------------ |
| Desktop Header | 72px | `lib/design-system/desktop-header.tsx` |
| Mobile Header | 56px | `lib/design-system/mobile-header.tsx` |
| 본문 top padding | `pt-[56px] md:pt-[72px]` | [patterns.md §1.4](../design-system/patterns.md) |

### Home page sequence

`packages/web/app/page.tsx:568` 기준:
`HeroItemSync` (md+) → `EditorialMagazine` → `EditorialCarousel` → `StyleMoods` → `EditorPicks` (data 있을 때) → `TrendingListSection` → `DomeGallerySection` (data 있을 때).
루트 컨테이너: `<div className="min-h-screen bg-[#050505] overflow-x-hidden">` — magazine palette 고정.

### 3D / Shader

`DecodedLogo` → three.js + `@chenglou/pretext` shader, `packages/web/lib/components/DecodedLogo.tsx`.

All design system components are exported from a single barrel import:
## Content Fundamentals

decoded 콘텐츠 규칙 (v2.2 신규, 정본 [content-fundamentals.md](../design-system/content-fundamentals.md)):

- **Voice**: 큐레이터 톤 — 단정적·간결·과한 마케팅 언어 회피
- **Casing**: 영문 헤더는 Title Case, 본문은 Sentence case
- **Person**: 사용자 1인칭("나의 ...") vs 시스템 3인칭 명확히 구분
- **Language**: 한국어 우선, 영문 브랜드/기술 용어는 원형 보존
- **Pricing**: 통화 기호 + 천 단위 콤마, 통화 코드는 후위 (예: `₩48,000 KRW`)
- **Numbers**: 천 단위 콤마, 0.xxx 단축 금지
- **Emoji**: UI 안에 emoji 사용 금지 (decorative 포함). 본문/에디토리얼만 허용.

## Iconography

Lucide Icons SSOT. 도메인 특화 아이콘은 `lib/design-system/` 내 컴포넌트로 캡슐화.
크기 규칙: inline body 16px, button leading icon 16-20px, hero/feature 24-32px. Animation 카탈로그는 [animations.md](../design-system/animations.md) 참조 (`spin`, `pulse`, `fade-in-up`, `marquee` 등 15+ keyframes + `prefers-reduced-motion` 정책).

## Import path

```typescript
import {
Expand All @@ -32,7 +97,7 @@ import {
GridCard,
FeedCardBase,
ProfileHeaderCard,
// Headers & Footer
// Navigation
DesktopHeader,
MobileHeader,
DesktopFooter,
Expand All @@ -46,75 +111,36 @@ import {
} from "@/lib/design-system";
```

## Component usage guide

| Component | Use Case | Example |
| --------------- | ------------------- | ---------------------------------------------------- |
| **Heading** | Page/section titles | `<Heading variant="h2">Title</Heading>` |
| **Text** | Body text, captions | `<Text variant="small">Description</Text>` |
| **Card** | Generic container | `<Card variant="elevated" size="md">...</Card>` |
| **ProductCard** | Product display | `<ProductCard image={url} title="..." price="$99"/>` |
| **Input** | Form inputs | `<Input variant="search" leftIcon={<Search/>}/>` |

## Design token reference

Access design tokens directly for custom styling:

```typescript
import { typography, spacing, colors } from "@/lib/design-system/tokens";

// Typography
typography.sizes.h1; // Font size for h1
responsiveTypography.pageTitle; // Responsive title sizing

// Spacing (4px base unit)
spacing[4]; // 16px
spacing[8]; // 32px

// Colors (CSS variable references)
colors.primary;
colors.muted;
```

## Further documentation

- **[docs/design-system/](../design-system/)** — Design token documentation
- **[.planning/codebase/](../../.planning/codebase/)** — Architecture and conventions
`colors.magPrimary` / `colors.magAccent` / `colors.magBg` / `colors.magText`도 동일 barrel에서 export.

## Component inventory

Located in `lib/design-system/`:

| Component | Purpose |
| ------------------------------------ | ---------------------------------------------------- |
| **tokens.ts** | Design tokens (colors, spacing, typography, shadows) |
| **Heading, Text** | Typography components with size variants |
| **Input, SearchInput** | Form inputs with variants |
| **Card Family** | Base card + Header/Content/Footer + Skeleton |
| **ProductCard** | Product card with image & description |
| **GridCard** | Grid layout card variant |
| **FeedCardBase** | Social feed card variant |
| **ProfileHeaderCard** | Profile header card |
| **DesktopHeader** | Desktop navigation header |
| **MobileHeader** | Mobile navigation with bottom sheet |
| **DesktopFooter** | Desktop footer with links |
| **ActionButton** | Interactive action button |
| **ArtistCard** | Artist/celebrity display card |
| **Badge** | Badge/tag display |
| **BottomSheet** | Mobile bottom sheet |
| **Divider** | Section divider |
| **GuestButton** | Guest action button |
| **Hotspot** | Interactive hotspot marker |
| **LeaderItem** | Leaderboard/ranking item |
| **LoadingSpinner** | Loading state indicator |
| **LoginCard** | Login prompt card |
| **NavBar, NavItem** | Navigation components |
| **OAuthButton** | OAuth provider button |
| **RankingItem** | Ranking display item |
| **SectionHeader** | Section title header |
| **ShopCarouselCard** | Shop item carousel card |
| **SpotCard, SpotDetail, SpotMarker** | Spot interaction components |
| **StatCard** | Statistics display card |
| **StepIndicator** | Multi-step progress indicator |
| **Tabs** | Tab navigation |
| **Tag** | Categorization tag |
Located in `packages/web/lib/design-system/`:

| Component | Purpose |
| ---------------------------------------------------------------------- | ---------------------------------------------------- |
| **tokens.ts** | Design tokens (colors, spacing, typography, shadows) |
| **Heading, Text** | Typography components with size variants |
| **Input, SearchInput** | Form inputs with variants |
| **Card Family** | Base card + Header/Content/Footer + Skeleton |
| **ProductCard / GridCard** | Product / grid layout cards |
| **FeedCardBase** | Social feed card |
| **ProfileHeaderCard** | Profile header card |
| **DesktopHeader / MobileHeader** | Top navigation (72px / 56px) |
| **DesktopFooter** | Desktop footer with links |
| **ActionButton / OAuthButton / GuestButton** | Interactive buttons |
| **ArtistCard / SpotCard / SpotDetail / SpotMarker** | Domain cards |
| **Badge / Tag / Divider / Tabs** | Feedback / structure |
| **BottomSheet / Hotspot / LoadingSpinner / LoginCard / StepIndicator** | Misc UI |
| **NavBar / NavItem / SectionHeader** | Navigation primitives |
| **RankingItem / LeaderItem / StatCard / ShopCarouselCard** | Ranking & shop |
| **DecodedLogo** | WebGL brand mark (`lib/components/DecodedLogo.tsx`) |

## Cross-links

- [docs/design-system/README.md](../design-system/README.md) — v2.2.0 진입점
- [docs/design-system/content-fundamentals.md](../design-system/content-fundamentals.md) — voice / casing / pricing
- [docs/design-system/animations.md](../design-system/animations.md) — keyframes 카탈로그
- [docs/design-system/patterns.md](../design-system/patterns.md) — layout / animation / theme patterns (§5.4 dual palette)
- [docs/design-system/tokens.md](../design-system/tokens.md) — 통합 토큰 레퍼런스 (Magazine palette 포함)
- [docs/design-system/decoded.pen](../design-system/decoded.pen) — 시각적 레퍼런스
3 changes: 2 additions & 1 deletion docs/agent/design-system-summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Design System — Agent Summary
owner: llm
status: draft
updated: 2026-04-17
updated: 2026-05-28
tags: [design-system, ui, agent]
related:
- docs/design-system/README.md
Expand Down Expand Up @@ -34,4 +34,5 @@ decoded DS v2.0 진입점. 컴포넌트·토큰·사용 규칙을 에이전트

## Recent changes

- 2026-05-28 v2.2.0: content-fundamentals / animations / dual palette (editorial fixed dark + product `.dark` 토글) / magazine palette tokens (#573) / design-system-llm.md 1-pager SSOT rewrite
- 2026-04-17: 초기 작성 (Phase 1)
Loading
Loading