design-reference

design-reference — 템플릿이 아닌 레퍼런스가 되는 인터페이스

인터페이스는 해당 분야를 아는 사람이 이 제품을 위해 그리고 최고 수준의 전문가가 만들었다고 인정할 때 레퍼런스가 됩니다. 적은 기본값(default)입니다: 어떤 모델이 비슷한 브리핑에 대해 생성할 법한 결과물.

0. 프로젝트 규칙

렌더링된 모든 조각의 첫 단계 — 화면, 컴포넌트, HTML 문서, Artifact, PDF, 슬라이드, 다이어그램(cloud-diagram), 배너 — 는 프로젝트 디자인 시스템의 스윕(sweep)입니다. 세션당 프로젝트당 한 번:

python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root>         # 요약
python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root> --css   # --ds-*가 포함된 :root

작성된 명세(DESIGN.md, docs/design*), 토큰(tailwind.config.*, :root/@theme가 있는 CSS, *.tokens.json), 컴포넌트 테마, package.json, components.json, Storybook 및 Figma 링크를 읽고 다음 판정을 내립니다: project (조각이 자체 토큰을 사용) 또는 neutral (스쿼드의 중립 팔레트 사용). --css는 --ds-bg --ds-surface --ds-fg --ds-fg-2 --ds-accent --ds-border --ds-font-display --ds-font-body --ds-font-mono 및 다크 블록을 출력하며, 스쿼드의 템플릿은 이 변수들을 읽습니다. --json은 전체 결과를 반환합니다. 충돌 시 우선 순위: 명세 > 토큰 > 컴포넌트. 페이지당 하나의 시스템. 조각이 어떤 시스템을 사용하고 어디서 찾았는지 한 줄로 명시하세요. 클라이언트나 타사의 브랜드: 먼저 물어보세요. 자세한 내용은 references/design-system-sweep.md 참조.

그런 다음 새 화면이 사용할 공유 컴포넌트를 읽습니다. 브리핑과 이미 채택된 시각 세계는 여러분의 취향과 여기의 모든 규칙보다 우선합니다. 리파이닝(Refining)은 정체성, 카피, 동작을 보존합니다. 리디자인(Redesigning)은 전체 시각 세계를 교체합니다. 버려진 모습을 절대 다듬지 마세요. 프로젝트 자체의 디자인 스킬(.claude/skills/)은 이 스킬보다 우선합니다.

DESIGN.md가 없다고 해서 프로젝트가 반드시 그린필드인 것은 아닙니다: 증거는 파일 이름이 아니라 코드와 기존 화면입니다.

1. 표면 모드 (이후 모든 것을 결정)

요청된 표면에 따라 선택하며, 제품에 따라 선택하지 않습니다:

모드	방문자의 성공	예시	규칙
설득(Persuade)	결정하고 행동	랜딩 페이지, 가격, 캠페인	주의, 증거, 행동 촉구 — 디자인 곧 제품
조작(Operate)	작업 완료	앱, 대시보드, 관리자, 편집기, 설정	스캔 가능성, 일관성, 네이티브 기대; 브랜드는 디테일에 존재
읽기(Read)	무언가 이해	문서, 글, 변경 로그, 도움말	이해를 위한 구조, 그 다음 읽기 편안함
경험(Experience)	작품 속에 있음	포트폴리오, 갤러리, 박물관, 쇼케이스	첫 폴드부터 작품이 주도; 인터페이스는 뒤로 물러남

도구의 랜딩 페이지는 설득(Persuade); 패션 브랜드의 문서는 읽기(Read); 박물관의 투어는 경험(Experience)입니다.

2. 코드보다 먼저 방향성 (두 번의 패스, 필수)

패스 1 — 간결한 계획, 코드 파일을 열기 전에:

• 주제: 한 문장: 누구를 위한 것인지, 이 화면의 단일 작업은 무엇인지, 그리고 이 주제의 세계(재료, 도구, 어휘, 인공물) 중 무엇이 시각적 선택이 될 수 있는지.
• 색상: 4–6개의 명명된 값(hex 또는 oklch), 각각의 의미적 역할 포함.
• 타이포그래피: 2개 이상의 역할 — 절제된 사용이 필요한 개성 있는 디스플레이 서체, 보조 본문 서체, 필요 시 데이터용 유틸리티 서체. 다른 프로젝트에서 사용할 법한 짝은 절대 사용하지 마세요.
• 레이아웃: 한 문장 개념 + ASCII 와이어프레임. 두 가지 대안을 비교하세요.
• 시그니처: 화면이 기억될 단일 요소. 모든 대담함은 거기에 쏟고, 나머지는 조용하고 규율 있게 유지하세요.
• 모션: 하나의 조율된 순간, 또는 없음. 어떤 것인지 명시하세요.

패스 2 — 자기 비판. 각 항목에 대해 묻습니다: "다른 제품의 비슷한 브리핑에 대해 이것을 생성할 것인가?" 만약 그렇다면, 그것은 선택이 아닌 기본값입니다 — 다시 작성하고 무엇이 바뀌었는지 말하세요. 그 후에야 코딩을 시작하고, 모든 색상과 서체를 계획에서 도출하세요.

AI가 오늘날 기본적으로 생성하는 세 가지 모습: (1) 크림 #F4F1EA + 고대비 세리프 + 테라코타; (2) 거의 검정 + 하나의 강렬한 악센트(라임 그린 또는 버밀리온); (3) 얇은 규칙의 전면 시트, 제로 반경, 빽빽한 열. 모두 브리핑이 요구한다면 적법합니다. 축이 자유로운 곳에서는 그 자유를 이것들에 낭비하지 마세요.

스타일, 팔레트 및 타이포그래피 짝의 카탈로그를 로컬 검색으로 보려면 ui-ux-pro-max (python3 scripts/search.py "<도메인> <제품>")를 사용하세요; 이것은 레퍼런스 엔진이지 아트 디렉터가 아닙니다 — 결정은 여전히 여러분의 몫입니다.

3. 토큰이 진실의 근원

• 세 계층: 원시 → 의미 → 컴포넌트. 컴포넌트는 절대 원시 값이나 원시 hex를 읽지 않습니다. --color-surface-raised를 읽지 --gray-100을 읽지 않습니다.
• 형식: 프로젝트에 파이프라인이 있을 때는 W3C DTCG 2025.10 (tokens.json); 그렇지 않으면 :root의 CSS 사용자 정의 속성과 함께 @media (prefers-color-scheme: dark) 및 [data-theme]의 다크 모드.
• 가능하면 oklch 색상; 대비 측정(APCA 또는 WCAG), 추정하지 않음.
• 다크 테마는 휘도 매핑이지 반전이 아닙니다.
• 완료 시, 프로젝트에 DESIGN.md가 없으면 생성을 제안하세요 (YAML 토큰 + 각 값의 이유를 산문으로) — 다음 세션이 이번 세션과 일관성을 유지하도록 하는 것입니다.

스케일, 컴포넌트 명세(변형, 크기, 우선순위가 있는 상태, 구조) 및 shadcn/Tailwind/다크 모드에 대한 참고: references/tokens-and-components.md. DTCG + CSS/Tailwind로 전체 시스템을 생성하려면: sumi:tokens.

4. 구축

• 스택 및 컴포넌트: 프로젝트의 것. shadcn/Tailwind → references/tokens-and-components.md 및 context7을 통한 라이브 문서; Figma에서 디자인이 오는 경우 → figma:figma-design-to-code (MCP) 또는 프로젝트 자체 로컬 스킬 (예: implement-from-figma, refactor-frontend-component); Figma에 쓰기 → figma:figma-use.
• 네이티브 모바일: 브랜드보다 플랫폼(HIG / Material)을 존중하세요.
• 클라우드 또는 인프라 아키텍처 다이어그램(AWS, OCI, GCP, Azure, Cloudflare): cloud-diagram, 항상. 이 작업을 위한 디자인 스킬입니다; 그 키트(해당 스킬의 references에 있는 template.html)를 복사하고 render.sh로 측정하세요. Mermaid, 일반 박스 또는 외부 이미지 아이콘은 사용하지 마세요.
• 처음부터 실제 콘텐츠: 짧은, 중간, 매우 긴 카피 테스트; 빈 상태; 로딩; 오류; 권한 없음. Lorem 플레이스홀더는 결함입니다.
• 카피는 디자인 재료입니다: 컨트롤은 발생할 일을 말합니다 ("제출"이 아닌 "변경 사항 저장"); 버튼에서 토스트까지 동일한 동사; 오류는 무슨 일이 일어났는지와 어떻게 벗어날지 말합니다; 빈 상태는 행동 초대입니다; 능동태, 문장 케이스.
• CSS: 자신을 무효화하는 특이성 조심 (.section × .cta), transition: all 절대 사용 금지, 기본적으로 transform/opacity만 애니메이션.
• 브라우저 표면도 디자인입니다: 텍스트 선택, 캐럿, 스크롤바, 포커스, 밑줄 오프셋, 표 형 숫자. 팔레트에서 테마를 지정하세요 — 페이지가 구축되었음을 보여주는 가장 저렴한 신호입니다.

제품 UI 실행 동반자

네이티브 또는 반응형 제품 UI의 경우, 사용 가능한 mobile-design-studio 스킬을 하나의 선택적 디자인 동반자로 사용하세요: 작은 구현 단위, 모바일 인체공학(터치 대상, 안전 영역, 키보드, 텍스트 스케일링, 뒤로 가기), 상태/복구 검사 및 플랫폼 증거. design-reference는 단일 디자인 방향 소스로 남습니다: 승인된 브리핑, 토큰 및 컴포넌트를 재사용하고; 두 번째 브랜딩/방향 프로세스를 실행하거나 중복 토큰 파일을 생성하지 마세요. 현재 단위에 필요한 동반자 참조만 읽으세요. 슬라이드, 아트, 포스터 또는 클라우드 다이어그램의 경로가 아닙니다; 그들은 전용 스킬을 유지합니다.

동반자의 디렉토리는 선택한 스킬의 원래 인벤토리 경로에서 확인하고, 생성된 프롬프트 캐시나 가정된 ~/.claude 설치에서 확인하지 마세요. 동반자가 없거나 수동 전용인 경우, 광고하거나 자동 로드하지 말고; 프로젝트 방법으로 계속하세요. 프로젝트 스킬 및 필수 플랫폼/Figma 전제 조건(예: Expo 개요, React Native 및 Figma design-to-code/use)은 여전히 적용됩니다; 경쟁하는 선택적 디자인 방향이 아닙니다. 두 디자인 스킬 상한선 유지: 이 방법 + 하나의 동반자, 절대 추가 Sumi/UI 스타일 스택 없음.

5. 품질 기준 (의도가 아닌 결과에서 검증됨)

UI 편집 직전에 references/quality-floor.md를 읽으세요. 양보할 수 없는 사항:

• 대비 ≥ 4.5:1 (텍스트), ≥ 3:1 (큰 텍스트); 색상 표면의 보조 텍스트는 해당 표면의 자체 색조에서 착색, 절대 회색 사용 금지.
• 모든 상호작용 요소에 가시적 포커스; 대체 수단 없이 아웃라인 제거 금지.
• 터치 대상 ≥ 44×44(네이티브) / 24×24 CSS px(웹), 대상 간 8px.
• prefers-reduced-motion 존중; 애니메이션 중단 가능; 키보드로 시작된 어떤 것도 애니메이션 금지.
• 320px까지 반응형, 가로 스크롤 없음; 전체 너비 레이아웃에 안전 영역 적용.
• 선언된 치수의 이미지; font-display가 있는 폰트; 긴 리스트 가상화.
• 상태: hover, active, focus, disabled, loading, error, empty — 모두.
• 아이콘으로 이모지 사용 금지; 하나의 라이브러리, 하나의 스트로크, 하나의 두께의 아이콘.

루프가 아닌 제한된 라운드로 검사: 전체를 구축하고, 데스크톱과 모바일을 함께 캡처하고(브라우저가 있으면 스크린샷), 모든 것을 한 번에 수정하고, 최대 한 라운드 더 확인하고 중단하세요. 무제한 QA는 sumi:audit이 더 잘하는 일을 하면서 소유자의 돈을 태웁니다.

6. 규칙이 있는 모션 (Emil Kowalski)

1. 애니메이션해야 하는가? 하루 100회 이상 (단축키, 팔레트) → 절대 안 함. 하루 수십 회 (hover, 목록 탐색) → 대폭 줄임. 가끔 (모달, 드로어, 토스트) → 표준. 드물게 (온보딩, 축하) → 즐거움을 줄 수 있음.
2. 선언된 목적: 공간 연속성, 상태 표시, 설명, 피드백, 급격한 전환 방지. "예뻐 보인다"는 자주 보이는 것의 목적이 아닙니다.
3. 이징: 등장/퇴장 → 강한 ease-out cubic-bezier(0.23, 1, 0.32, 1); 화면 내 이동/변형 → ease-in-out cubic-bezier(0.77, 0, 0.175, 1); hover/색상 → ease; 지속적인 움직임 → linear; iOS 드로어 → cubic-bezier(0.32, 0.72, 0, 1). UI에서 절대 ease-in 사용 금지.
4. 지속 시간: 버튼 100–160ms; 툴팁 125–200ms; 드롭다운 150–250ms; 모달/드로어 200–500ms; 마케팅 외 UI는 항상 < 300ms.
5. 아무것도 갑자기 나타나지 않음: scale(0.95) + opacity 0, scale(0) 아님. 팝오버는 트리거에서 스케일링(transform-origin); 모달은 중앙 유지. :active에서 scale(0.97). 모든 섹션에 동일한 등장은 안티패턴; 하나의 저작된 순간은 안티패턴이 아닙니다.

7. 아트, 캔버스 및 창의적인 작업

요청이 포스터, 표지, 그래픽 조각, 생성 예술, 3D 시각 또는 "UI 브리핑 없는 아름다운 무언가"일 때 방법이 변경됩니다: 먼저 시각적 철학(1–2단어로 명명된 운동 + 공간, 색상, 재료, 규모, 리듬, 구성에 대한 4–6단락), 그 다음 실행. 테마에 대한 참조는 미묘합니다 — 아는 사람은 느끼고, 다른 사람은 숙달된 구성을 봅니다. 90% 시각, 10% 텍스트. 여백을 벗어나는 것 없음, 겹치는 것 없음.

표면	도구
정적 PNG/PDF (포스터, 아트, 표지)	vendor/canvas-design (Anthropic)
2D 생성 예술, 흐름 장, 입자	vendor/algorithmic-art (p5.js, 재현 가능한 시드, 슬라이더)
3D / 셰이더 / 인터랙티브 장면	three.js (r160+), GLSL ShaderMaterial; 항상 dispose() 및 이벤트 리스너 제거 포함
소셜 미디어 / 광고 / 배너 / 인쇄용 조각	references/identity-and-pieces.md (크기, 안전 영역, 행동 촉구) + 정확한 크기로 캡처된 HTML
슬라이드	slides
클라우드 아키텍처 다이어그램	cloud-diagram
브랜드 가이드, 팔레트, 로고 규칙	references/identity-and-pieces.md; 브랜드 음성 및 카피 → writing
AI 생성 로고, 아이콘, 아이덴티티 목업	design (claudekit: API를 사용한 생성 스크립트, 키 필요)
무한 캔버스의 나란히 변형	superdesign 플러그인 (유료; 로그인 필요 — 소유자 결정)
생성된 이미지/비디오	sumi:generate 또는 설정된 이미지 MCP

식별 가능한 예술가의 작품을 절대 복사하지 마세요; 영향력을 인용하고, 자신의 것을 만드세요. 폰트: 올바른 문자 집합을 가진 폰트를 다운로드하여 자체 호스팅; "가장 가까운" 시스템 폰트는 실패이지 폴백이 아닙니다.

8. 기존 항목 감사 및 수정

• 상위 수정 사항이 포함된 빠른 점수: sumi:roast. 전체 감사 (휴리스틱, 인지, 흐름): sumi:audit. WCAG 2.2 AA 접근성: sumi:a11y. 웹 체크리스트 (a11y, 폼, 모션, 타이포그래피, 성능, i18n): references/quality-floor.md §B, file:line 형식으로 출력.
• 생성된 UI 코드 수정: sumi:fix. 모션 리뷰: | Before | After | Why | 테이블, 발견당 한 행.
• 동일 세션에서 두 개 이상의 디자인 스킬을 절대 로드하지 마세요: 설명이 경쟁하고 컨텍스트가 답변 개선 없이 부풀어 오릅니다.

9. 전달

모드             [설득 | 조작 | 읽기 | 경험]
방향성           [주제 · 명명된 팔레트 · 타이포그래피 짝 · 시그니처 · 모션]
기본값이었던 것   [자기 비판에서 다시 쓴 내용과 이유]
토큰             [파일 및 계층; DESIGN.md 생성/업데이트?]
기준             [§5의 각 확인 사항, 측정된 값 포함, "ok" 아님]
상태             [구현된 상태 목록]
캡처            [데스크톱 + 모바일, 환경이 허용하는 경우]
보류             [소유자만 제공할 수 있는 자산; 그들의 결정인 사항]