체계적인 디자인 시스템 구축
brand 스킬은 정체성을 결정하고, frontend-design 스킬은 표면의 모양을 결정합니다.
이 팩은 디자인이 확장 가능하도록 구조화하는 방법을 결정합니다: 단일 진실 공급원을 가진 3계층 토큰 아키텍처, 모든 상태를 포함하는 컴포넌트 사양, 그리고 원시 값이 다시 스며드는 것을 방지하는 검사를 포함합니다. 깊이가 필요할 때는 참고 자료를 불러오세요:
| 주제 | 참고 자료 |
|---|---|
| 계층, 명명 규칙, 다크 모드, DTCG JSON, 플랫 토큰에서 마이그레이션 | references/token-architecture.md |
| 버튼/입력/카드/뱃지/알림/대화상자/테이블의 변형, 크기 및 상태 매트릭스 | references/component-specs.md |
| 상태 우선순위, 포커스 링, 오류/로딩 패턴, 상태별 ARIA | references/states-and-variants.md |
한눈에 보는 아키텍처
/* 원시 — 원시 값, 의미 없음. 거의 변경되지 않음. */
--blue-600: oklch(55% 0.2 264);
/* 의미 — 목적. 테마 경계: 밝음/어두움/브랜드 재정의는 이 계층에서만 발생. */
--color-primary: var(--blue-600);
/* 컴포넌트 — 컴포넌트별 설정값, 의미 토큰 참조. */
--button-bg: var(--color-primary);
컴포넌트는 컴포넌트 또는 의미 토큰을 소비합니다 — 절대 원시 토큰이나 리터럴 값을 직접 사용하지 않습니다. 테마(다크, 고대비, 두 번째 브랜드)는 의미 토큰만 다시 가리키며 그 외에는 변경하지 않습니다.
단일 진실 공급원. 저장소가 토큰을 W3C Design Tokens Community Group
(DTCG) JSON으로 유지하는 경우 — 이 형식은 2025년 10월에 첫 번째 안정 버전 2025.10에 도달했습니다 —
해당 파일이 진실 공급원입니다: 토큰은 $value와 $type을 가지며, 별칭은
{color.blue.600} 형식으로 작성되고, 빌드 도구(Style Dictionary 또는 저장소의 동등한 도구)는
CSS 변수, Tailwind 테마 및 네이티브 값을 생성합니다. JSON을 편집하고 다시 생성하세요.
생성된 출력물을 직접 수동 편집하지 마십시오. 저장소에 CSS 사용자 정의 속성만 있는 경우, 그것이
진실 공급원입니다. 두 번째 공급원을 도입하지 마십시오.
단계
- 기존 항목을 읽습니다.
search_lore로 디자인 시스템 ADR을 검색하고, 토큰 파일 (*.tokens.json,tokens/,theme.ts,:root블록, Tailwind 설정), 출력물을 생성하는 빌드 명령어, 그리고 두 개의 관련 컴포넌트를 찾습니다. 기존 시스템의 관용구를 확장하세요. 절대 경쟁 시스템을 추가하지 마십시오. - 추가하기 전에 감사합니다. 컴포넌트 스타일의 리터럴 수를 셉니다(아래 명령어 참조). 발견한 모든 누수는 기존 토큰으로 대체하거나 새 토큰의 필요성을 정당화합니다.
- 각 새 토큰을 해당 계층에 배치합니다. 진정으로 새로운 원시 값에 대해서만 원시 계층을 사용하고,
새로운 목적(
--color-surface-raised,--space-section)에 대해서는 의미 계층을 사용하며, 하나의 컴포넌트가 달라져야 할 때만 컴포넌트 계층을 사용합니다. 이름은 모양이 아닌 목적을 설명합니다 (--color-red가 아닌--color-danger). 색상 원시 값은oklch(팀 관용구)를 사용하고, 타입은clamp()유동적 스케일을 사용하며, 간격은 하나의 기본 단위(4px 또는 8px)를 사용합니다. - 의미 계층에서 테마를 적용합니다. 다크 모드 및 기타 테마는 하나의 블록에서 의미 토큰을 재정의하고
(
[data-theme="dark"],.dark또는@media (prefers-color-scheme: dark), 저장소 규칙에 따라),color-scheme을 설정하여 네이티브 컨트롤과 스크롤바도 따라가도록 합니다. 원시 또는 컴포넌트 토큰을 재정의하는 테마는 경계가 잘못된 위치에 있음을 의미합니다. - 테마별 대비를 확인합니다. 실제로 사용되는 모든 전경/배경 의미 쌍(표면 위의 텍스트, primary 위의
텍스트, 표면 위의 테두리, 표면 위의 포커스 표시기)에 대해 각 테마에서 WCAG 대비 비율을 계산합니다:
본문 텍스트는 4.5:1, 큰 텍스트, UI 경계 및 포커스 표시기는 3:1입니다.
oklch밝기는 WCAG 비율이 아닙니다 — 직접 계산하십시오(스크립트, 저장소의 검사기 또는 테스트 사용). 표를 기록합니다. - 컴포넌트를 완전히 지정합니다. 변형, 크기(명시적 높이, 패딩, 폰트 토큰) 및 상태 매트릭스
— 기본, 호버, focus-visible, 활성, 비활성, 로딩, 오류, 그리고 해당되는 경우 선택/체크 — 각 상태가
노출하는 ARIA를 포함합니다. 여러 상태가 동시에 적용될 때의 우선순위: 비활성 > 로딩 > 오류 > 활성 >
포커스 > 호버 > 기본. 포커스는 항상 가시적이어야 합니다(
--color-ring의:focus-visible링, 절대outline: none단독으로 사용하지 마십시오). 자세한 내용은 참고 자료를 참조하세요. - 새 제품을 위한 시스템 추천: 키트가 아닌 제품에서 추론하십시오 —
(a) 패턴과 밀도(마케팅, 데이터 밀집 대시보드, 트랜잭션 흐름),
(b) 방향성(
brand에 위임), (c) 팔레트 태세(성공/경고/위험/정보를 포함한 의미 역할; 사용자에게 필요한 경우에만 다크 모드), (d) 접근성 및 성능 목표를 사전에 명시합니다. 간단한 근거와 토큰 및 컴포넌트 스캐폴드를 출력하고, 시각적 실행은frontend-design에 넘깁니다. - 검증하고 증거를 남깁니다. 저장소가 빌드하는 경우 토큰 출력물을 다시 생성하고 차이가 의도한 대로만
발생했는지 확인합니다. 린트, 타입 검사 및 테스트를 실행하고, 누수 검사를 실행하며, 저장소의 컴포넌트
또는 스크린샷 테스트가 있는 경우 모든 테마에서 변경된 컴포넌트를 렌더링합니다.
record-evidence스킬로 AC별 증거를 기록하고(누수 수 전후, 대비 표), 중지합니다.
누수 검사
변경된 컴포넌트 및 스타일 파일(토큰 파일 자체는 제외)에서 실행:
- 원시 색상:
grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components - 원시 타입 크기:
grep -rEn 'font-size:\s*[0-9.]+px' src/components - 컴포넌트에서 참조된 원시 토큰:
grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components - 토큰이 존재하는 Tailwind 임의 값:
grep -rEn '\[(#|[0-9]+px)' src/components
경로와 원시 이름을 저장소에 맞게 조정하십시오. 변경 사항의 새로운 일치는 빌더가 수정해야 할 결함이며,
해당 줄이 토큰 정의 자체가 아닌 경우 리뷰어는 이를 (선택사항)으로 나열합니다. 단, AC를 위반하거나
테마 대비를 깨뜨리는 경우는 예외입니다.
완료 조건
컴포넌트에 새로운 리터럴 또는 원시 참조가 없음; 모든 테마가 의미 토큰만 재정의함; 대비 표가 모든 테마에서 통과함; 수정된 각 컴포넌트의 상태 매트릭스가 가시적 포커스로 구현됨; 생성된 출력물이 소스와 일치함.
학습 사항 기록
저장소의 토큰 아키텍처 — 계층 분할, 명명 규칙, 다크 모드 경계 또는 "컴포넌트에서 원시 참조 금지" 규칙 —
은 다음 에이전트가 작업을 시작하기 전에 정확히 알아야 하는 사실입니다. 그러한 사실은 lore입니다.
브리프의 lore-capture 프로토콜을 통해 기록하십시오(CLAUDE.factory.md, 11단계 "Memory contribution"):
작업 마무리 시 Memory MCP suggest_lore를 한 번 호출하십시오 — 재사용 가능한 규칙, 문제점, 결정 및
경계만 포함하고, 티켓별 사소한 정보는 포함하지 마십시오.