디자인 시스템 애드온

사용자 대면 인터페이스 표면을 가진 리포지토리에 DESIGN.md를 부여합니다 — 어떤 코딩 에이전트든 읽어서, 안내가 없을 때 에이전트가 기대는 스타일 없는 통계적 기본값 대신 리포지토리 고유의 관례에 일관된 인터페이스 출력을 생성하게 하는 Markdown 디자인 시스템 파일입니다. 네 번째 선택형 Deep Work Plan 애드온입니다.

“인터페이스 표면”은 하나가 아닙니다. 렌더링되는 비주얼 UI, 스타일이 입혀진 CLI 출력, 그리고 대화형 표면(제품이 채팅이나 이메일로 말함)이 각각 해당합니다. 애드온은 각각을 프로필로서 독립적으로 감지하며, 채택된 프로필들은 동일한 단일 DESIGN.md에 쌓입니다.

무엇을 추가하는가

docs/DESIGN.md에 위치하는 DESIGN.md(리포지토리의 다른 스펙들과 나란히 두며, docs/ 트리가 없을 때만 리포지토리 루트에 둠). 에이전트가 나머지 문서처럼 발견할 수 있도록 AGENTS.md에서 참조됩니다. 하나의 리포지토리, 하나의 파일 — 표면별 형제 파일은 결코 만들지 않습니다.
visual-ui 프로필 — 정규 비주얼 섹션들: 개요/분위기, 색상 팔레트 & 역할(라이트 + 다크), 타이포그래피, 레이아웃 & 간격, 입체감 & 깊이, 형태, 컴포넌트, 반응형 동작, 권장 사항 & 금지 사항(리포지토리의 접근성 규칙 포함).
cli-output 프로필 — 스타일이 입혀진 터미널 인터페이스: 출력 어조, 의미론적 색상 & 스타일(success/error/warning/info/dim을 실제 테마에 매핑), 출력 컴포넌트(패널, 테이블, 스피너, 인터랙티브 프롬프트 — 리포지토리의 실제 헬퍼 이름을 따름), 레이아웃 관례, 그리고 강등 규칙(TTY 대 파이프, NO_COLOR, stdout/stderr 규율, 종료 코드).
conversational 프로필 — 제품의 메시징 표면: 어조 & 격식(톤, 간결성, 브랜드 명명 규칙), 메시지 구조(DM, 채널 게시물, 스레드 답글, 제자리 편집), 그리고 플랫폼별 렌더링(Slack mrkdwn, Discord 마크다운, Teams 어댑티브 카드, 이메일)과 일반 텍스트 대체.
공유 에이전트 프롬프트 가이드, 그리고 각 프로필의 무결성을 확인하는 검증 단계: 문서화된 텍스트 대비가 WCAG AA를 충족하는지(비주얼), 색상이 의미의 유일한 전달자가 아닌지(CLI), 리치 렌더링이 일반 텍스트 대체를 명시하는지(대화형), 토큰 참조가 해석되는지.

동작

추론하라, 복사하지 마라. 모든 값은 리포지토리의 실제 디자인 소스 — 스타일시트, CSS 커스텀 속성, Tailwind 설정, 토큰 파일, 컴포넌트 스타일, CLI 표시/테마 모듈, 또는 메시지 구성 헬퍼 — 에서 도출됩니다. 제3자 브랜드의 DESIGN.md를 결코 붙여 넣지 않으며 다른 제품의 관례를 통째로 들여오지도 않습니다. 참조 카탈로그는 구조를 위한 영감일 뿐 결코 내용을 위한 것이 아닙니다.
조정하라, 덮어쓰지 마라. 기존 DESIGN.md나 토큰 소스는 덮어쓰지 않고 가산적으로 조정됩니다. 새로 채택된 프로필을 추가하면 나머지를 다시 쓰지 않고 그 섹션만 덧붙입니다. 파괴적 변경에는 승인이 필요합니다.
참조에 의한 발견. DESIGN.md가 어디에 있든 AGENTS.md(그리고 CLAUDE.md)가 그것을 참조합니다 — 에이전트가 그것을 로드하도록 보장하는 것은 물리적 위치가 아니라 그 포인터입니다.
실용적이며, 경직되게 묶이지 않음. 떠오르는 DESIGN.md 관례를 따를 형태로 참조하고, 이를 비주얼이 아닌 표면으로 확장하며, Markdown 우선을 유지하고 어떤 단일 토큰 스키마에도 묶이지 않습니다.

인터페이스 범위, 프로필별 권장 강도

이 애드온은 실제 인터페이스 표면을 적어도 하나 가진 리포지토리를 위한 것입니다. 인터페이스 표면이 전혀 없는 리포지토리(순수 라이브러리, 헤드리스 서비스, 인프라 전용 리포지토리)에는 결코 제안되지 않습니다. 각 프로필은 고유한 권장 강도를 가집니다:

visual-ui는 감지 시 기본 활성 — CSS 커스텀 속성이 있는 스타일시트, Tailwind 설정이나 @theme 블록, UI 컴포넌트, 또는 브랜드/스타일 가이드. 온보딩은 신뢰 모드에서 이를 적용하고 가이드 모드에서 강력히 권장합니다.
cli-output과 conversational은 감지 시 권장되며 — 언제나 먼저 물어보고, 결코 자동 적용되지 않습니다. 신뢰 모드에서도 마찬가지입니다. CLI 렌더링 라이브러리와 의도적인 표시 레이어가 전자의 신호이고, 채팅 플랫폼 SDK나 메시지 구성 레이어가 후자의 신호입니다. 날것의 출력만 하는 단순 인자 파서는 해당하지 않습니다.

결코 필수는 아닙니다 — 애드온이 하나도 없는 리포지토리도 완전히 적합하며, 어떤 프로필이든 애드온 전체든 언제든 거절할 수 있습니다. 프로필이 존재하기 전에 만들어진 DESIGN.md는 유효한 단일 프로필 비주얼 파일입니다: 마이그레이션은 없습니다.

선택적 명령

채택되면, 애드온은 나중에 DESIGN.md를 재생성하거나 갱신할 수 있도록 리포지토리의 .agents/commands/에 /design-system 위임자를 설치할 수 있습니다. 명령 설치는 선택적이며, 거절된 애드온은 아무것도 설치하지 않습니다.

기능별 디자인 문서와의 관계

이것은 리포지토리 수준의 영속적인 디자인 시스템 파일입니다 — 도구에 묶인 스펙 주도 워크플로의 기능별 기술 디자인 문서(“요구사항 → 디자인 → 작업”의 design.md)와는 구별됩니다. Deep Work Plan은 의도적으로 별도의 기능별 디자인 문서 아키타입을 제공하지 않습니다. 계획의 README, 각 작업의 인수 기준, 그리고 검증 게이트가 이미 그 역할을 담당합니다. 이 애드온은 그 역할이 채우지 못하는 한 가지 공백을 메웁니다: 지속적이고 리포지토리 고유의 인터페이스 디자인 컨텍스트.