39/ 50
＋ 요구된 10개 절과 목차를 빠짐없이 구성했다.
－ 입력에 없는 구조·규칙·수치를 다수 추정했다.
CLAUDE.md 조립 프롬프트
토큰 아키텍처, 컴포넌트 문서, 프로젝트 메타데이터를 넣으면 프로젝트 루트용 CLAUDE.md 디자인 시스템 참조 파일을 구성합니다.
| 분류 | 개발 › 기술 문서 |
|---|---|
| 태그 | 초안작성형식변환개발자표 |
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).어떤 프롬프트인가
AI와 개발자가 함께 참조할 디자인 시스템 문서를 완성할 때 쓰인다. 섹션 순서, 표 형식, 토큰·타이포·색·레이아웃·규칙 구성을 엄격히 지정한다.
모델 비교
ChatGPT는 가장 완결적이나 추정 내용이 많다. Gemini는 더 많은 정보를 지어내고 중단됐으며, [C]는 제출되지 않았다.
23/ 50
＋ 토큰 계층과 표 구성이 상세하고 탐색하기 쉽다.
－ 미제공 사양을 대량 창작했고 답변도 중간에 끊겼다.
| 기준 | ChatGPT | Gemini | 앞선 모델 |
|---|---|---|---|
| 지시 준수 | 9 | 3 | ChatGPT +200% |
| 정확성 | 6 | 3 | ChatGPT +100% |
| 구체성 | 8 | 7 | ChatGPT +14% |
| 구성·가독성 | 9 | 7 | ChatGPT +29% |
| 분량 적정성 | 7 | 3 | ChatGPT +133% |
gpt-5.6-sol가 모델 이름을 가린 채 1~10점으로 채점했습니다 (2026-09-24). 측정값이 아니라 AI 심사 결과입니다.
답 전문 보기
같은 입력을 세 모델에 넣어 받은 답을 그대로 옮겼습니다. 각 CLI(에이전트 하네스)에서 실행했습니다. ChatGPT·Claude 앱이나 웹에서는 답이 다를 수 있습니다.
[붙여 넣은 자료] 프로젝트명: 무드로그 (개인 감정 다이어리 웹앱) 기술 스택: 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, 최대 글자수 표시 지원)
현재 환경은 읽기 전용이라 루트에 직접 저장할 수 없습니다. 아래 내용을 그대로 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 토큰을 사용합니다.
색상만으로 상태, 오류 또는 성공 여부를 전달하지 않습니다.
모바일 화면에서 가로 스크롤이 발생하지 않아야 합니다.
사용자 감정 기록은 오류나 네트워크 실패로 유실되지 않도록 처리합니다.
로딩, 오류, 빈 상태를 누락하지 않습니다.
사용자 입력은 적절히 검증하고 최대 길이를 적용합니다.
감정 기록과 개인정보를 로그에 평문으로 남기지 않습니다.
접근 가능한 이름이 없는 아이콘 전용 버튼을 만들지 않습니다.
디자인 토큰에 없는 임의의 색상, 간격, 반경을 추가하지 않습니다.
실제 구현과 이 문서가 다르면 실제 구현을 기준으로 이 문서를 먼저 갱신합니다. 이 문서는 미래 계획이 아니라 현재 시스템의 기록입니다.
같은 분류의 프롬프트
| FTTH 통신 전문가 역할을 맡기는 프롬프트 | |
| 개발자 아키텍처 안내 프롬프트 | |
| LLM 입문서 작성 프롬프트 | |
| 프로그래밍 팀 구성 프롬프트 | |
| CLAUDE.md 생성 프롬프트 |