twltr/design-system

디자인 시스템

리프 스킬 — 디자인 영역에 속하며, 해당 도메인이나 이름으로 접근할 수 있습니다.

디자인 시스템은 팀이 신뢰하는 동안에만 결정을 절약해 줍니다. 드리프트(Drift)는 조용히 그 신뢰를 무너뜨립니다: 하나의 컴포넌트에 세 가지 이름, 토큰 옆에 복제된 원시 hex 값, 아무도 문서화하지 않은 상태. 일단 사람들이 시스템을 신뢰하지 않게 되면, 시스템을 우회하여 구축합니다. 이 방법은 세 가지 모드로 작동합니다 — 감사(audit) 시스템을 있는 그대로, 문서화(document) 컴포넌트를 올바르게 사용할 수 있도록, 확장(extend) 시스템에 맞는 패턴으로 — 각각 실제 소스(토큰 파일, 컴포넌트 코드, 디자인 파일)에 기반하며, 디자인 시스템에 대한 일반적인 개념이 아닙니다.

감사 결과 예시

상황(가상): 토큰 파일이 있는 React 라이브러리; 요청은 "버튼과 카드 감사".

명명     Button, IconBtn 및 .btn-link가 하나의 개념을 세 가지 방식으로 이름 짓습니다.
          → `icon` 및 `link` 변형이 있는 Button을 채택하고, 이전 이름은 한 릴리스 동안 별칭을 유지합니다.
토큰     Card와 Modal에서 23개의 하드코딩된 색상. 18개는 기존 토큰과 일치합니다(기계적으로 교체).
          5개는 일치하는 토큰이 없습니다.
          → 5개는 결정이 필요합니다: 누락된 토큰 또는 수정해야 할 디자인 오류.
상태     Card는 클릭 가능함에도 불구하고 포커스 상태가 없습니다.

재사용 가능한 선택은 토큰을 복제하는 값(기계적 수정)과 일치하는 토큰이 없는 값(추측 대신 사람에게 제시해야 할 디자인 질문)의 구분입니다.

시스템 수집

판단하기 전에 존재하는 것을 읽으십시오: 토큰 소스, 컴포넌트 코드 또는 라이브러리, 문서. rg -n '#[0-9a-fA-F]{3,8}\b|[0-9]+px' src/components와 같은 검색으로 코드에서 하드코딩된 값을 찾을 수 있습니다. 패턴을 스택에 맞게 조정하세요.

~~로 표시된 섹션은 제품이 아닌 도구 범주를 나타냅니다: ~~디자인 도구(예: Figma) 또는 ~~지식 베이스(예: Notion). 호스트가 제공하는 해당 범주의 연결된 도구를 사용하고, 제공되지 않으면 단계를 건너뜁니다.

~~디자인 도구를 사용하는 경우, 디자인 파일에서 컴포넌트 이름, 변형, 레이어 구조 및 토큰 사용을 검사하고 코드와 비교합니다. ~~지식 베이스를 사용하는 경우, 기존 컴포넌트 페이지와 사용 가이드라인을 찾고, 요청자가 요청한 경우에만 업데이트된 문서를 게시합니다.

시스템은 세 가지 계층으로 구성됩니다. 감사와 문서화는 각각을 다룹니다:

계층	내용
토큰	색상(브랜드, 의미, 중립), 타이포그래피, 간격, 반경 및 테두리, 고도, 모션 지속 시간 및 이징
컴포넌트	변형, 상태(기본, 호버, 포커스, 활성, 비활성, 로딩, 오류), 크기, 동작, 접근성
패턴	양식, 내비게이션, 데이터 표시, 피드백 — 반복되는 문제를 해결하기 위해 결합된 컴포넌트

토큰이 도구 간에 이동할 때, Design Tokens Community Group 형식(첫 번째 안정 버전 2025.10, 2025년 10월)이 공통 교환 형식입니다. 프로젝트가 이미 사용하는 형식을 따르세요.

원칙

1. 일관성이 새로운 것보다 우선합니다. 시스템은 팀이 동일한 사항을 재결정하지 않도록 존재합니다. 일회성 변형에는 시스템이 부족한 이유가 필요합니다.
2. 제약 내에서 구성 가능합니다. 새 컴포넌트보다 기존 컴포넌트의 변형 또는 구성을 선호합니다.
3. 문서화되지 않은 것은 사용할 수 없음을 의미합니다. 아무도 찾을 수 없는 상태나 변형은 다시 구축됩니다.
4. 버전 관리 및 마이그레이션. 이름 변경이나 제거 시에는 마이그레이션 경로(예: 한 릴리스 동안 별칭 및 codemod 또는 사용처를 찾는 검색)가 필요합니다.

감사

점수가 아닌 개수와 증거를 보고하세요: 기준 없는 숫자는 어떤 문제가 중요한지 숨깁니다.

## 디자인 시스템 감사: [범위]

**검토:** [컴포넌트, 토큰 파일] | **발견 사항:** [범주별 개수]

### 명명
| 문제 | 위치 | 권장 사항 |
|---|---|---|

### 토큰 범위
| 범주 | 정의된 토큰 | 하드코딩된 값 | 기존 토큰과 일치 |
|---|---|---|---|

### 컴포넌트 완전성
| 컴포넌트 | 상태 | 변형 | 문서 | 접근성 |
|---|---|---|---|---|
| 버튼 | 완료 | 부분: 아이콘 전용 크기 없음 | 누락 | 포커스 링 존재 |

### 우선 작업
1. [사용자 또는 팀 영향이 가장 큰 순서, 필요 노력과 함께]

문서화

컴포넌트를 사용하는 모든 사람을 위해 재사용 가능한 컴포넌트를 문서화하세요. props와 코드 예제는 실제 컴포넌트에서 가져오고, 발명된 API가 아닙니다.

## 컴포넌트: [이름]

[무엇이며 언제 사용하는지 — 그리고 언제 다른 것을 사용해야 하는지]

### 변형
| 변형 | 사용 시점 |
|---|---|

### Props
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|

### 상태
| 상태 | 시각적 | 동작 |
|---|---|---|

### 접근성
- **역할:** [역할 또는 네이티브 요소]
- **키보드:** [Tab, Enter, Space, Escape, 화살표]
- **스크린 리더:** [다음으로 알림 …]

### 권장 및 금지
| 권장 | 금지 |
|---|---|

### 예제
[프로젝트 프레임워크의 짧은 스니펫]

확장

새로운 것을 제안하기 전에, 유사한 기존 컴포넌트를 나열하고 각각이 충분하지 않은 이유를 설명하세요. 대부분의 요청은 새로운 변형으로 끝납니다. 새 컴포넌트는 기존 토큰을 재사용하고, 이유와 함께 새 토큰만 제안합니다.

## 제안 컴포넌트: [이름]

### 문제
[사용자 요구 또는 격차]

### 기존 옵션
| 컴포넌트 | 공유하는 부분 | 충분하지 않은 이유 |
|---|---|---|

### 디자인
문서 템플릿과 동일한 props, 변형 및 상태; 사용된 토큰.

### 접근성
역할, 키보드 및 스크린 리더 동작.

### 열린 질문
[디자인 검토가 필요한 결정 사항]

시스템의 컴포넌트와 토큰은 이 방법의 주제입니다. 하나의 기능이나 화면에 대한 사양 시트와 새로운 제품의 시각적 방향은 별도의 디자인 작업입니다. 시스템 감사가 WCAG 감사를 대체하지도 않습니다.