CLAUDE.md Assembly

compiling the definitive CLAUDE.md design system reference file.

Category	Development › Technical writing
Tags	DraftingReformattingDeveloperTable

Prompt

You are compiling the definitive CLAUDE.md design system reference file.
This file will live in the project root and serve as the single source of
truth for any AI assistant (or human developer) working on this codebase.

## Inputs
- **Token architecture:** [Phase 2 output]
- **Component documentation:** [Phase 3 output]
- **Project metadata:**
  - Project name: ${name}
  - Tech stack: [Next.js 14+ / React 18+ / Tailwind 3.x / etc.]
  - Node version: ${version}
  - Package manager: [npm / pnpm / yarn]

## CLAUDE.md Structure

Compile the final file with these sections IN THIS ORDER:

### 1. Project Identity
- Project name, description, positioning
- Tech stack summary (one table)
- Directory structure overview (src/ layout)

### 2. Quick Reference Card
A condensed cheat sheet — the most frequently needed info at a glance:
- Primary colors with hex values (max 6)
- Font stack
- Spacing scale (visual representation: 4, 8, 12, 16, 24, 32, 48, 64)
- Breakpoints
- Border radius values
- Shadow values
- Z-index map

### 3. Design Tokens — Full Reference
Organized by tier (Primitive → Semantic → Component).
Each token entry: name, value, CSS variable, Tailwind class equivalent.
Use tables for scannability.

### 4. Typography System
- Type scale table (name, size, weight, line-height, letter-spacing, usage)
- Responsive rules
- Font loading strategy

### 5. Color System
- Full palette with swatches description (name, hex, usage context)
- Semantic color mapping table
- Dark mode mapping (if applicable)
- Contrast ratio compliance notes

### 6. Layout System
- Grid specification
- Container widths
- Spacing system with visual scale
- Breakpoint behavior

### 7. Component Library
[Insert Phase 3 output for each component]

### 8. Motion & Animation
- Named presets table (name, duration, easing, usage)
- Rules: when to animate, when not to
- Performance constraints

### 9. Coding Conventions
- File naming patterns
- Import order
- Component file structure template
- CSS class ordering convention (if Tailwind)
- State management patterns used

### 10. Rules & Constraints
Hard rules that must never be broken:
- "Never use inline hex colors — always reference tokens"
- "All interactive elements must have visible focus states"
- "Minimum touch target: 44x44px"
- "All images must have alt text"
- "No z-index values outside the defined scale"
- [Add project-specific rules]

## Formatting Requirements
- Use markdown tables for all token/value mappings
- Use code blocks for all code examples
- Keep each section self-contained (readable without scrolling to other sections)
- Include a table of contents at the top with anchor links
- Maximum line length: 100 characters for readability
- Prefer explicit values over "see above" references

## Critical Rule
This file must be AUTHORITATIVE. If there's ambiguity between the
CLAUDE.md and the actual code, the CLAUDE.md should be updated to
match reality — never the other way around. This documents what IS,
not what SHOULD BE (that's a separate roadmap).

What this prompt does

This prompt assembles a design-system reference document for both AI assistants and developers. It strictly specifies section order, table formatting, and coverage of tokens, typography, color, layout, and rules.

Model comparison

ChatGPT is the most complete but relies on assumptions. Gemini invents more details and is truncated, while [C] is missing.

ChatGPTTop overall

39/ 50

＋ Covers all ten required sections with a clear TOC.

－ Invents several structures, rules, and values absent from input.

Gemini

23/ 50

＋ Detailed token tiers and tables are easy to scan.

－ Fabricates many specs and ends abruptly before completion.

Criterion	ChatGPT	Gemini	Leader
Instruction following	9	3	ChatGPT +200%
Accuracy	6	3	ChatGPT +100%
Specificity	8	7	ChatGPT +14%
Structure	9	7	ChatGPT +29%
Right length	7	3	ChatGPT +133%

Scored 1–10 by gpt-5.6-sol with model names hidden (2026-09-24). This is an AI review, not a measurement.

Read full answers

We gave three models the same input and copied their answers unedited. Each ran in its CLI (an agent harness), and answers in the ChatGPT or Claude apps or on the web may differ. Outputs are in Korean.

Input used

[Pasted material]
프로젝트명: 무드로그 (개인 감정 다이어리 웹앱)
기술 스택: Next.js 14.2 / React 18.3 / TypeScript 5 / Tailwind CSS 3.4
Node 버전: 20.11.0
패키지 매니저: pnpm

[Phase 2 출력 - 토큰 아키텍처]
Primitive: --color-blue-500: #3B82F6, --space-4: 16px, --radius-md: 8px
Semantic: --color-primary → --color-blue-500, --color-surface: #FFFFFF, --color-danger: #EF4444
Component: --button-primary-bg → --color-primary, --card-padding → --space-4

[Phase 3 출력 - 컴포넌트 문서]
Button(variants: primary/secondary/ghost, sizes: sm/md/lg, props: loading/disabled/icon)
Card(props: title/footer/elevation, 기본 padding 16px, radius 8px)
Input(states: default/focus/error, helper text, 최대 글자수 표시 지원)

gpt-5.6-luna (codex CLI · 에이전트 하네스) · Run on 2026-09-24

현재 환경은 읽기 전용이라 루트에 직접 저장할 수 없습니다. 아래 내용을 그대로 CLAUDE.md로 저장하면 됩니다.

# 무드로그 디자인 시스템

개인 감정 기록을 돕는 차분하고 접근성 높은 감정 다이어리 웹앱의
디자인 시스템 기준 문서입니다.

이 문서는 현재 확인된 토큰과 컴포넌트 문서를 기준으로 작성되었습니다.
코드와 문서가 다를 경우 실제 구현을 기준으로 이 문서를 먼저 갱신합니다.

## 목차

- [1. 프로젝트 정체성](#1-프로젝트-정체성)
- [2. 빠른 참조 카드](#2-빠른-참조-카드)
- [3. 디자인 토큰 전체 참조](#3-디자인-토큰-전체-참조)
- [4. 타이포그래피 시스템](#4-타이포그래피-시스템)
- [5. 색상 시스템](#5-색상-시스템)
- [6. 레이아웃 시스템](#6-레이아웃-시스템)
- [7. 컴포넌트 라이브러리](#7-컴포넌트-라이브러리)
- [8. 모션 및 애니메이션](#8-모션-및-애니메이션)
- [9. 코딩 규칙](#9-코딩-규칙)
- [10. 규칙 및 제약](#10-규칙-및-제약)

## 1. 프로젝트 정체성

### 프로젝트 정보

| 항목 | 내용 |
| --- | --- |
| 프로젝트명 | 무드로그 |
| 설명 | 사용자가 자신의 감정과 일상을 기록하는 개인 감정 다이어리 |
| 포지셔닝 | 차분하고 사적인 감정 기록 경험을 제공하는 웹앱 |
| 런타임 | Node.js 20.11.0 |
| 패키지 매니저 | pnpm |

### 기술 스택

| 영역 | 기술 |
| --- | --- |
| 프레임워크 | Next.js 14.2 이상 |
| UI 라이브러리 | React 18.3 이상 |
| 언어 | TypeScript 5 |
| 스타일링 | Tailwind CSS 3.4 |
| 렌더링 | Next.js App Router 기준 |
| 패키지 관리 | pnpm |

### 디렉터리 구조

```text
src/
├── app/          # 라우트, 레이아웃, 페이지, 전역 스타일
├── components/   # 재사용 가능한 UI 컴포넌트
├── lib/          # 유틸리티, 도메인 로직, 데이터 접근
├── types/        # 공통 TypeScript 타입
└── styles/       # 추가 스타일과 디자인 토큰

실제 저장소의 구조가 위와 다르면 실제 구조를 기준으로 이 문서를 갱신합니다.

2. 빠른 참조 카드

주요 색상

이름	값	용도
Blue 500	`#3B82F6`	기본 브랜드 색상
Surface	`#FFFFFF`	기본 표면 및 카드 배경
Danger	`#EF4444`	오류, 삭제, 위험 상태

폰트

시스템 UI 폰트:
-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif

간격 스케일

4px  ─  8px  ─  12px  ─  16px  ─  24px  ─  32px  ─  48px  ─  64px

값	Tailwind
4px	`space-1`
8px	`space-2`
12px	`space-3`
16px	`space-4`
24px	`space-6`
32px	`space-8`
48px	`space-12`
64px	`space-16`

브레이크포인트

이름	최소 너비	Tailwind
기본	0px	기본 스타일
Small	640px	`sm`
Medium	768px	`md`
Large	1024px	`lg`
Extra Large	1280px	`xl`
2XL	1536px	`2xl`

모서리 반경

이름	값	Tailwind
Medium	8px	`rounded-md`

그림자

현재 정의된 프로젝트 전용 그림자는 없습니다. 기본 Tailwind 그림자를 사용할 경우 실제 사용 패턴을 확인한 뒤 이 표를 갱신합니다.

Z-index

이름	값	용도
base	0	일반 콘텐츠
dropdown	10	드롭다운 및 팝오버
sticky	20	고정 헤더 및 컨트롤
overlay	30	오버레이
modal	40	모달
toast	50	토스트 및 전역 알림

3. 디자인 토큰 전체 참조

Primitive 토큰

토큰 이름	값	CSS 변수	Tailwind 클래스
Blue 500	`#3B82F6`	`var(--color-blue-500)`	`bg-blue-500`
Space 4	`16px`	`var(--space-4)`	`p-4`, `m-4`, `gap-4`
Radius Medium	`8px`	`var(--radius-md)`	`rounded-md`

Semantic 토큰

토큰 이름	값	CSS 변수	Tailwind 클래스
Primary	Blue 500 참조	`var(--color-primary)`	`bg-primary`
Surface	`#FFFFFF`	`var(--color-surface)`	`bg-white`
Danger	`#EF4444`	`var(--color-danger)`	`text-red-500`

Component 토큰

토큰 이름	참조 값	CSS 변수	Tailwind 클래스
Button Primary Background	Primary	`var(--button-primary-bg)`	`bg-primary`
Card Padding	Space 4	`var(--card-padding)`	`p-4`

CSS 변수 예시

:root {
  --color-blue-500: #3b82f6;
  --space-4: 16px;
  --radius-md: 8px;

  --color-primary: var(--color-blue-500);
  --color-surface: #ffffff;
  --color-danger: #ef4444;

  --button-primary-bg: var(--color-primary);
  --card-padding: var(--space-4);
}

4. 타이포그래피 시스템

기본 폰트

구분	값
기본 폰트	시스템 UI 폰트
폴백	`sans-serif`
기본 방향	가독성과 감정 기록의 편안함 우선

font-family:
  -apple-system,
  BlinkMacSystemFont,
  "Segoe UI",
  sans-serif;

타입 스케일

이름	크기	굵기	줄 높이	자간	용도
Body	16px	400	1.5	0	본문, 감정 기록
Label	14px	500	1.4	0	입력 레이블, 보조 정보
Heading 3	20px	600	1.3	0	카드 및 섹션 제목
Heading 2	24px	600	1.25	0	페이지 제목
Heading 1	32px	700	1.2	-0.01em	주요 화면 제목

반응형 규칙

모바일에서는 본문 최소 크기를 16px로 유지합니다.
제목은 작은 화면에서 한 단계 낮은 크기를 사용할 수 있습니다.
긴 감정 기록은 줄 높이 1.5 이상을 유지합니다.
텍스트가 컨테이너를 벗어나지 않도록 줄바꿈을 허용합니다.

폰트 로딩 전략

시스템 폰트를 우선 사용합니다.
외부 웹폰트를 추가할 경우 next/font를 사용합니다.
폰트 로딩으로 인한 레이아웃 이동을 방지합니다.
로컬 폰트 파일을 추가할 경우 사용 이유와 폴백을 함께 기록합니다.

5. 색상 시스템

전체 팔레트

이름	HEX	사용 맥락
Blue 500	`#3B82F6`	기본 브랜드 및 주요 액션
White	`#FFFFFF`	표면, 카드, 입력 배경
Red 500	`#EF4444`	오류, 위험, 삭제 액션

Semantic 색상 매핑

의미	토큰	실제 값	사용 예
Primary	`--color-primary`	`#3B82F6`	주요 버튼, 활성 상태
Surface	`--color-surface`	`#FFFFFF`	카드, 입력 영역
Danger	`--color-danger`	`#EF4444`	오류 메시지, 삭제 경고

다크 모드

현재 다크 모드 매핑은 정의되어 있지 않습니다. 다크 모드를 구현할 경우 모든 시맨틱 색상에 대응하는 다크 값을 추가하고, 컴포넌트에서 Primitive 색상을 직접 사용하지 않습니다.

대비 및 접근성

본문과 배경의 대비는 WCAG AA 기준을 만족해야 합니다.
일반 텍스트는 최소 4.5:1 대비를 유지합니다.
큰 텍스트는 최소 3:1 대비를 유지합니다.
색상만으로 오류나 상태를 전달하지 않습니다.
포커스 상태에는 색상 외에도 테두리, 외곽선 또는 형태 변화를 사용합니다.

6. 레이아웃 시스템

그리드

기본 레이아웃은 반응형 단일 컬럼을 우선합니다.
넓은 화면에서 콘텐츠 영역을 중앙 정렬합니다.
카드 사이 간격은 정의된 간격 스케일을 사용합니다.
임의의 픽셀 간격을 추가하지 않습니다.

컨테이너 너비

화면	권장 동작
모바일	화면 너비에 맞추고 좌우 여백을 둡니다
`md` 이상	읽기 편한 최대 너비를 사용합니다
`lg` 이상	주요 콘텐츠를 중앙 정렬합니다

프로젝트에서 실제 컨테이너 최대 너비가 확인되면 이 표에 명시적으로 기록합니다.

간격 시스템

이름	값	대표 용도
`space-1`	4px	아이콘과 텍스트 사이
`space-2`	8px	작은 요소 사이
`space-3`	12px	레이블과 입력 사이
`space-4`	16px	카드 기본 패딩
`space-6`	24px	섹션 내부 간격
`space-8`	32px	주요 섹션 간격
`space-12`	48px	페이지 영역 간격
`space-16`	64px	큰 화면의 여백

브레이크포인트 동작

모바일 기본 스타일을 먼저 작성합니다.
sm, md, lg, xl, 2xl 순서로 확장합니다.
모바일에서 가로 스크롤이 발생하지 않아야 합니다.
버튼과 입력은 작은 화면에서도 충분한 터치 영역을 유지합니다.

7. 컴포넌트 라이브러리

Button

버튼은 사용자의 주요 행동을 실행하는 인터랙티브 요소입니다.

항목	지원 값
Variants	`primary`, `secondary`, `ghost`
Sizes	`sm`, `md`, `lg`
Props	`loading`, `disabled`, `icon`
주요 토큰	`--button-primary-bg`

동작 규칙:

primary는 화면에서 가장 중요한 행동에 사용합니다.
secondary는 보조 행동에 사용합니다.
ghost는 낮은 강조도의 행동에 사용합니다.
loading 상태에서는 중복 실행을 방지합니다.
disabled 상태는 시각적으로 구분하되 충분한 대비를 유지합니다.
아이콘만 사용하는 버튼에는 접근 가능한 이름을 제공합니다.

사용 예:

<Button variant="primary" size="md">
  감정 기록하기
</Button>

<Button variant="ghost" loading>
  저장 중
</Button>

Card

카드는 감정 기록, 요약 정보, 관련 콘텐츠를 그룹화합니다.

항목	값
Props	`title`, `footer`, `elevation`
기본 패딩	16px
패딩 토큰	`--card-padding`
기본 반경	8px
반경 토큰	`--radius-md`

동작 규칙:

title은 카드 콘텐츠의 맥락을 설명해야 합니다.
footer는 보조 액션이나 메타데이터에 사용합니다.
elevation은 계층 구조가 필요한 경우에만 사용합니다.
카드 내부 요소 사이에는 정의된 간격 스케일을 사용합니다.

사용 예:

<Card title="오늘의 기분" elevation="low">
  오늘은 차분한 하루였다.
</Card>

Input

Input은 감정 기록과 사용자 정보를 입력받습니다.

항목	지원 값
States	`default`, `focus`, `error`
기능	helper text
기능	최대 글자 수 표시

동작 규칙:

모든 입력에는 연결된 레이블이 있어야 합니다.
focus 상태는 시각적으로 명확해야 합니다.
error 상태는 오류 원인을 텍스트로 설명합니다.
helper text는 입력 목적이나 형식을 설명합니다.
최대 글자 수를 지원하는 경우 현재 길이와 최대 길이를 함께 표시합니다.
오류 메시지는 입력 요소와 programmatically 연결합니다.

사용 예:

<Input
  label="오늘의 감정"
  helperText="오늘 느낀 감정을 자유롭게 적어보세요."
  maxLength={500}
/>

8. 모션 및 애니메이션

현재 프로젝트 전용 모션 프리셋은 정의되어 있지 않습니다.

권장 프리셋

이름	지속 시간	easing	사용
Fast	100ms	`ease-out`	버튼 상태 변화
Standard	200ms	`ease-out`	입력, 카드 상태 변화
Emphasized	300ms	`ease-in-out`	모달, 주요 전환

규칙

상태 변화와 피드백을 명확하게 하는 경우에만 애니메이션을 사용합니다.
사용자의 입력이나 저장 완료 피드백은 짧게 반응해야 합니다.
장식 목적의 지속적인 움직임은 사용하지 않습니다.
prefers-reduced-motion을 존중합니다.
페이지 핵심 콘텐츠의 표시를 애니메이션으로 지연하지 않습니다.

성능 제약

transform과 opacity 기반 애니메이션을 우선합니다.
레이아웃을 반복적으로 변경하는 애니메이션은 피합니다.
스크롤 이벤트 기반 애니메이션은 최소화합니다.
무거운 애니메이션은 저사양 모바일 환경에서 비활성화할 수 있어야 합니다.

9. 코딩 규칙

파일 이름

React 컴포넌트 파일은 PascalCase를 사용합니다.
유틸리티 파일은 camelCase를 사용합니다.
타입 전용 파일은 도메인 이름을 사용합니다.
라우트 디렉터리는 Next.js 규칙을 따릅니다.

예시:

src/components/Button.tsx
src/components/MoodCard.tsx
src/lib/formatDate.ts
src/types/mood.ts

Import 순서

React 및 Next.js
외부 패키지
프로젝트 내부 절대 경로
상대 경로
스타일 및 타입

import type { ReactNode } from "react";
import Link from "next/link";

import { cn } from "@/lib/cn";

import type { Mood } from "@/types/mood";

컴포넌트 파일 구조

import type { ReactNode } from "react";

type ExampleProps = {
  children: ReactNode;
};

export function Example({ children }: ExampleProps) {
  return <div>{children}</div>;
}

Tailwind 클래스 순서

다음 순서를 유지합니다.

레이아웃
크기
간격
타이포그래피
색상
테두리 및 반경
상태 및 반응형 변형

<div className="flex w-full gap-4 p-4 text-base text-gray-900
  rounded-md bg-white focus-visible:outline-none md:p-6">
  콘텐츠
</div>

긴 클래스 문자열은 cn 같은 프로젝트 유틸리티로 조건부 조합합니다.

상태 관리

컴포넌트 내부에서만 필요한 상태는 React state를 사용합니다.
여러 컴포넌트가 공유하는 상태는 기존 프로젝트 패턴을 우선합니다.
서버 데이터와 클라이언트 UI 상태를 분리합니다.
로딩, 오류, 빈 상태를 명시적으로 처리합니다.
낙관적 업데이트는 실패 시 복구 전략이 있을 때만 사용합니다.

10. 규칙 및 제약

다음 규칙은 반드시 지킵니다.

인라인 HEX 색상을 사용하지 않습니다. 정의된 디자인 토큰이나 Tailwind 토큰을 사용합니다.
모든 인터랙티브 요소에는 눈에 보이는 포커스 상태가 있어야 합니다.
인터랙티브 요소의 최소 터치 영역은 44x44px입니다.
모든 이미지에는 의미에 맞는 alt 텍스트를 제공합니다. 장식용 이미지는 빈 alt를 사용합니다.
정의된 Z-index 스케일 밖의 값을 사용하지 않습니다.
컴포넌트에서 Primitive 토큰을 직접 남용하지 않습니다. 가능한 경우 Semantic 또는 Component 토큰을 사용합니다.
색상만으로 상태, 오류 또는 성공 여부를 전달하지 않습니다.
모바일 화면에서 가로 스크롤이 발생하지 않아야 합니다.
사용자 감정 기록은 오류나 네트워크 실패로 유실되지 않도록 처리합니다.
로딩, 오류, 빈 상태를 누락하지 않습니다.
사용자 입력은 적절히 검증하고 최대 길이를 적용합니다.
감정 기록과 개인정보를 로그에 평문으로 남기지 않습니다.
접근 가능한 이름이 없는 아이콘 전용 버튼을 만들지 않습니다.
디자인 토큰에 없는 임의의 색상, 간격, 반경을 추가하지 않습니다.
실제 구현과 이 문서가 다르면 실제 구현을 기준으로 이 문서를 먼저 갱신합니다. 이 문서는 미래 계획이 아니라 현재 시스템의 기록입니다.

More in this category

Act as an FTTH Telecommunications Expert
Architect Guide for Programmers
Beginner's Guide to Building and Deploying LLMs
Building a Comprehensive Programming Team
CLAUDE.md Generator for AI Coding Agents

Categories

CLAUDE.md Assembly

What this prompt does

Model comparison

2. 빠른 참조 카드

주요 색상

폰트

간격 스케일

브레이크포인트

모서리 반경

그림자

Z-index

3. 디자인 토큰 전체 참조

Primitive 토큰

Semantic 토큰

Component 토큰

CSS 변수 예시

4. 타이포그래피 시스템

기본 폰트

타입 스케일

반응형 규칙

폰트 로딩 전략

5. 색상 시스템

전체 팔레트

Semantic 색상 매핑

다크 모드

대비 및 접근성

6. 레이아웃 시스템

그리드

컨테이너 너비

간격 시스템

브레이크포인트 동작

7. 컴포넌트 라이브러리

Button

Card

Input

8. 모션 및 애니메이션

권장 프리셋

규칙

성능 제약

9. 코딩 규칙

파일 이름

Import 순서

컴포넌트 파일 구조

Tailwind 클래스 순서

상태 관리

10. 규칙 및 제약

More in this category