Communitygithub.com

디자인 시스템

디자인 시스템, 스타일 가이드 또는 토큰 세트를 시작하거나, 컴포넌트나 토큰을 추가/변경하거나, 일관되지 않은 화면을 표준화하거나, 가이드에서 느슨한 색상, 일회성 요소, 누락된 상태 또는 일치하지 않는 화면을 감사할 때 사용합니다.

디자인 시스템란 무엇인가요?

이 스킬은 디자인 시스템, 스타일 가이드 또는 토큰 세트를 체계적으로 구축하고 유지 관리하는 AI 에이전트를 위한 완전한 워크플로우를 제공합니다. 핵심 원칙은 '한 번 결정한 것을 모든 곳에서 재사용'하는 것으로, 모든 색상은 토큰화되고, 모든 상호작용 요소는 모든 상태를 가지며, 모든 변경 사항은 영향을 받는 모든 화면에 일관되게 전파됩니다. 이 스킬은 생성, 추가/변경, 감사의 세 가지 주요 모드를 지원하며, 각 모드마다 명확한 단계별 지침을 제공합니다. 특히 '승인 후 진행' 방식을 강조하여, 기초와 상호작용 규칙을 먼저 승인받은 후에 컴포넌트를 구축하거나, 감사 보고서를 제출하고 승인된 수정만 진행하도록 합니다. 또한, 느슨한 색상 값 방지, 단일 아이콘 세트 사용, 설계와 코드 동시 변경, 상태 매트릭스 필수 적용 등 엄격한 규칙을 포함하여 프로젝트 전반의 일관성과 유지보수성을 보장합니다. 주요 스킬 파일(SKILL.md)을 기반으로 하여, Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/design-skills/tree/HEAD/skills/design-system

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

디자인 시스템은(는) 무엇을 하나요?

개요

디자인 시스템은 한 번 결정된 사항이 모든 곳에서 재사용되는 곳입니다. 모든 색상은 토큰이며, 모든 상호작용 요소는 모든 상태를 보여주고, 모든 변경 사항은 해당 요소를 사용하는 모든 화면에 적용됩니다. 계층별로, 기초부터 구축하고 각 계층에서 승인을 위해 멈추십시오. 감사는 보고만 하고 자체적으로 수정하지 않습니다.

사용 시기

  • "...에 대한 스타일 가이드 / 디자인 시스템 / 토큰 시작"
  • 컴포넌트, 변형 또는 토큰 추가, 또는 기존 항목 변경
  • "이 화면들을 일관되게 만들기", "표준화", "가이드 감사", 또는 화면의 느슨한 16진수 값과 일회성 요소들

사용하지 말아야 할 시기

  • 하나의 값에 대한 질문(예: "우리의 주요 색상은 무엇인가요?") -> 답변하세요.
  • 사용자가 정확히 설명한 작은 편집(하나의 값, 하나의 라벨, 하나의 크기)이며, 공유 요소에 대한 경우에도 -> 한 번 정의된 곳에서 변경하고 영향을 받는 화면을 알려주세요. 상태 매트릭스나 중단 단계는 필요하지 않습니다.

시작하기 전에

  1. 프로젝트 루트에 DESIGN.md가 있으면 읽으십시오: 이는 프로젝트의 디자인 개요입니다.
  2. 존재하는 항목(토큰, 가이드, 컴포넌트, 화면 및 코드)을 찾으십시오. 기존 가이드가 외관에 우선합니다. 아래 기본값과 다른 경우에도 해당 규칙을 따르고, 차이점을 한 번 언급하십시오.
  3. references/adapters/에서 도구에 맞는 어댑터를 선택하십시오(paper.md, figma.md, html.md). 일치하는 어댑터가 없으면 도구에서 동일한 동사를 수행하고 수동으로 매핑했음을 명시하십시오. 디자인 도구가 전혀 없으면 HTML(html.md)로 구축하십시오. 이미지만 있는 경우, 이미지에서 읽은 값은 추정치임을 명시하십시오.
  4. 모드를 결정하십시오: 생성, 추가 또는 변경, 또는 감사.

단계 · 생성

  1. 기초 초안:

    • 색상 역할 (토큰 역할);
    • 타이포그래피 스케일;
    • 간격;
    • 둥글기;
    • 그림자 (최대 두 개);
    • 레이아웃 너비;
    • 모션 지속 시간;
    • 간단한 "작성 방법" 섹션.

    토큰은 역할별로 이름을 지정하십시오(text-muted, border-hover, danger-bg). 값으로만 이름을 지정하지 마십시오(gray-500).

  2. 상호작용 규칙, 한 번만: 테두리가 있는 요소, 테두리가 없는 요소 및 기본 작업에 대해 호버, 눌림, 포커스(키보드 전용), 비활성화, 로딩 및 선택됨 상태의 모양을 작성하십시오. 컴포넌트는 각자 자체 규칙을 만드는 대신 이 규칙을 따릅니다.

  3. 기초와 상호작용 규칙을 사용자에게 보여주고 승인을 받으십시오. 아직 컴포넌트를 구축하지 마십시오.

  4. 첫 번째 화면이 필요한 순서대로 컴포넌트를 하나씩 구축하십시오. 각 컴포넌트는 컴포넌트 구조에 따라 가이드 섹션을 갖습니다: 규칙과 그 이유를 설명하는 범례, 예제, 그리고 변형 × 상태의 상태 매트릭스가 포함됩니다. 각 컴포넌트를 컴포넌트 인덱스에 추가하십시오.

단계 · 요소 추가 또는 변경

  1. 기존 컴포넌트에 변형을 추가하여 처리할 수 있는지 확인하십시오. 일회성 요소보다 재사용을 선호하십시오.
  2. 전체 상태 매트릭스를 포함하여 구조와 함께 그리십시오. 새로운 색상, 크기 또는 아이콘은 지금(나중이 아닌) 토큰 또는 아이콘 세트 항목이 됩니다.
  3. 해당 요소를 사용하는 모든 화면과 코드 위치를 나열하십시오.
  4. 변경 사항과 해당 목록을 사용자에게 보여주고 승인을 받으십시오.
  5. 승인 후, 전파하십시오:
    • 목록에 있는 모든 화면 업데이트;
    • 코드(있는 경우) 업데이트;
    • 컴포넌트 인덱스 업데이트;
    • 변경된 내용과 위치를 보고하십시오.

단계 · 감사

  1. 감사 체크리스트를 가이드, 화면 및 코드(있는 경우)에 대해 실행하십시오.
  2. 보고서를 작성하십시오: 심각도별로 정렬된 발견 사항, 각각의 위치, 중요성 및 제안된 수정 사항을 포함하십시오.
  3. 보고서를 사용자에게 보여주고 승인을 받으십시오. 사용자가 어떤 수정을 할지 말하기 전까지 어떤 파일도 변경하지 마십시오. 원본을 복사해 두었다고 해서 편집이 허용되는 것은 아닙니다.

규칙

확고한 규칙 (모든 프로젝트):

규칙이유
모든 색상은 토큰이며, 화면이나 코드에 느슨한 16진수 값이 없어야 함느슨한 값은 근사 중복으로 변질되어 한 번에 변경할 수 없음
하나의 아이콘 세트혼합 세트는 혼합 제품처럼 보임
디자인과 코드가 함께 변경되며, 디자인이 먼저임그렇지 않으면 가이드가 일주일 안에 진실이 아닌 것이 됨
모든 상호작용 요소는 상태 매트릭스가 있어야 함화면에서 임시로 그린 상태는 결코 일치하지 않음
공유 요소의 변경은 전파되기 전에 영향을 받는 화면과 함께 나열되어야 함그렇지 않으면 하나의 "작은" 변경이 조용히 20개의 화면을 재설계함

기본값 (기존 가이드가 이를 재정의함):

기본값이유
호버 시, 테두리 있는 요소만 테두리를 어둡게 함카드와 필드의 배경이 변경되면 무거워 보임
호버는 선택됨보다 미묘해야 함호버가 선택됨처럼 보이면 두 가지가 선택된 것으로 착각함
선택은 글꼴 두께를 변경하지 않음두께 변경은 텍스트 너비를 이동시킴
플레이스홀더는 흐린 텍스트보다 연해야 함그렇지 않으면 플레이스홀더가 입력된 텍스트처럼 읽힘
누적 목록과 메뉴의 항목은 약간의 간격을 가지며, 절대 닿지 않음닿는 하이라이트는 하나의 블록으로 합쳐짐
포커스 링은 키보드에서만 나타남마우스 클릭 후의 링은 버그처럼 보임
로딩은 요소의 정확한 크기를 유지함레이아웃 이동 방지
그림자는 떠 있는 요소(메뉴, 팝오버, 대화상자, 토스트)에만, 두 가지 강도로 사용모든 곳의 그림자는 만들려고 했던 계층 구조를 평평하게 만듦
화면당 최대 하나의 기본 작업두 개의 기본 작업은 화면이 결정하지 못했음을 의미함

완료 조건

  • 생성: 기초와 상호작용 규칙이 승인됨; 각 컴포넌트는 구조, 상태 매트릭스 및 인덱스 행을 가짐.
  • 변경: 나열된 모든 화면과 코드 위치가 업데이트되고 인덱스가 업데이트됨.
  • 감사: 순위가 매겨진 보고서가 전달되었으며 어떤 파일도 변경되지 않음.

일반적인 실수

생각현실
"전체 가이드를 한 번에 구축할 거야: 토큰과 10개의 컴포넌트"승인되지 않은 기초 위에 10개의 컴포넌트는 10번의 재작업을 의미함. 기초, 중단, 그 다음 컴포넌트.
"감사에서 문제를 찾았으니 그냥 고치면 되지"사용자는 수정 사항의 절반에 동의하지 않을 수 있음. 보고, 중단, 사용자가 선택한 것만 수정.
"원본을 백업 폴더에 보관했으니 수정해도 안전해"백업이 사용자가 수정에 동의하게 만들지는 않음. 먼저 보고.
"버튼에 호버와 비활성화가 있으면 충분해"상태 매트릭스는 모든 상태 × 모든 변형을 가짐: 일반, 호버, 눌림, 포커스, 비활성화, 로딩, 선택됨.
"--teal-600은 토큰이야"값입니다. 컴포넌트는 역할(--color-primary)이 필요하므로 값이 한 곳에서 변경될 수 있음.
"이 화면에는 약간 다른 카드가 필요해"카드의 변형으로 만들거나 카드를 사용하십시오. 일회성 요소는 표류의 시작입니다.

관련 스킬