Communitygithub.com

비주얼 디자인

디자인 시스템(디자인 토큰, 색상 팔레트, 대비, 서체, 서체 스케일, 간격 스케일, 다크 모드, 모션 토큰, 컴포넌트 상태 명세)을 구축하거나 변경할 때 사용합니다. 특정 페이지 배치나 리디자인에는 사용하지 마세요. 이미지 제작에도 사용하지 마세요.

비주얼 디자인란 무엇인가요?

비주얼 디자인 스킬은 화면 아래에 깔린 시스템을 구축합니다. 색상, 서체, 간격, 형태, 깊이, 모션을 위한 토큰과 이로부터 만들어지는 컴포넌트 명세가 핵심입니다. 이 스킬은 디자인 방향을 먼저 글로 정의한 후 모든 토큰 결정을 그 방향에 맞추도록 강제합니다. 또한 컴포넌트는 원시 값 대신 의미론적 토큰을 참조하여 다크 모드, 테마 변경, 리브랜딩 시 재작성 없이 매핑만 변경하면 되도록 합니다. 대비는 모든 실제 쌍에 대해 두 테마 모두에서 WCAG 2.2 기준을 충족하는지 검증하며, 모든 컴포넌트 명세는 모든 상태(기본, 호버, 포커스, 활성, 비활성, 로딩, 오류, 선택)를 포함해야 합니다. 더 적은 값을 일관되게 사용하는 원칙을 따릅니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 도구에서 사용 가능하며, 개발자가 디자인 시스템을 체계적으로 구축하고 유지보수할 수 있도록 도와줍니다.

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

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

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

문서

비주얼 디자인은(는) 무엇을 하나요?

모든 화면 아래에 깔린 시스템: 색상, 서체, 공간, 형태, 깊이, 모션을 위한 토큰과 이로부터 구축된 컴포넌트 명세. designer 스킬은 이 시스템을 실제 페이지에 적용합니다. 시스템을 한 번 구축하면 페이지는 그것을 활용하기만 하면 됩니다.

가장 중요한 규칙

  1. 토큰보다 먼저 디자인 방향을 글로 작성하세요. 세 문장: 누구를 위한 것인지, 어떤 느낌이어야 하는지, 절대 느껴서는 안 되는 느낌, 그리고 주제에서 가져온 한 가지. 모든 토큰 결정은 이 문단에 비추어 확인됩니다.
  2. 컴포넌트는 의미론적 토큰을 참조하고, 절대 프리미티브를 참조하지 않습니다. --color-text-primary이지 --grey-900이 아닙니다. 다크 모드, 테마 변경, 리브랜딩은 재작성 대신 재매핑이 됩니다.
  3. 모든 실제 쌍에 대해 두 테마 모두에서 대비를 확인하고 아래 표를 따르세요. 흰색에서 통과하는 팔레트가 자체 색상 표면에서는 실패할 수 있습니다.
  4. 기본값은 결정이 아닙니다. 프레임워크 회색, 모든 곳의 Inter, 모든 상자의 4px 반경: 각각은 괜찮아 보이지만 함께 사용하면 다른 모든 제품과 똑같아 보입니다. 각 값을 결정하거나 인지하고 수용하세요.
  5. 모든 컴포넌트 명세는 모든 상태를 나열합니다: 기본, 호버, 포커스, 활성, 비활성, 로딩, 오류, 그리고 해당하는 경우 선택. 누락된 상태는 빌드 과정에서 일관성 없이 생성됩니다.
  6. 더 적은 값을 일관되게 사용하세요. 6단계 스케일이 모든 곳에서 사용되면 14단계 스케일이 무작위로 사용되는 것보다 낫습니다.

사용하지 말아야 할 경우

  • 특정 페이지 배치, 접힌 부분 위에 무엇을 넣을지 결정, 화면 비평 또는 리디자인 실행: designer.
  • 일러스트레이션, 아이콘, 히어로 이미지 또는 브랜드 마크 생성: artist.
  • 차트 및 데이터 시각화 팔레트: frontend 스킬의 references/charts.md. 범주형 차트 색상은 브랜드 팔레트와 다른 제약 조건이 있습니다.
  • 프레임워크에서 토큰 구현: frontend.

구축 순서

각 레이어는 이전 레이어에 의존합니다:

  1. 방향 문단.
  2. 색상: 프리미티브, 그다음 의미론적 토큰.
  3. 서체: 서체, 그다음 스케일과 역할.
  4. 간격 스케일과 그리드.
  5. 반경, 테두리 및 입체감.
  6. 모션 토큰.
  7. 컴포넌트 토큰과 컴포넌트 명세.

색상

구조:

프리미티브 (원시 값, 색상당 하나의 램프, 예: 50, 100 ... 900, 950):
  --blue-600: oklch(0.55 0.17 255)

의미론적 토큰 (프리미티브를 참조, 역할별로 명명):
  --color-bg, --color-surface, --color-surface-raised
  --color-text, --color-text-muted, --color-text-on-accent
  --color-accent, --color-accent-hover
  --color-border, --color-focus-ring
  --color-danger, --color-success, --color-warning (각각 텍스트 안전 변형 포함)

고려된 팔레트와 기본 팔레트를 구분하는 규칙:

  • OKLCH로 램프를 구축하세요. 명도는 색상 전반에 걸쳐 지각적으로 균일하므로 600 파랑과 600 초록은 동일한 시각적 무게를 가집니다. HSL 명도는 거짓말을 합니다.
  • 중성색에 색조를 추가하세요. 순수한 회색과 순수한 검정 또는 흰색은 소유되지 않은 느낌을 줍니다. 브랜드 색조 방향으로 약간의 채도(약 0.005~0.015)를 추가하세요.
  • 색상이 있는 표면의 텍스트는 중성 회색이 아닌 해당 표면 색상의 어두운 음영을 사용하세요. 색상 위의 회색은 바랜 느낌을 줍니다.
  • 약속 수준을 선택하고 유지하세요: 절제됨(중성 바탕, 하나의 강조), 전념(브랜드 색상이 전체에 걸쳐 있음), 전체 팔레트, 또는 흠뻑 젖음(브랜드 색상이 바탕). 반쯤 약속은 우유부단함으로 읽힙니다.
  • 색상에만 의미를 부여하지 마세요. 아이콘, 레이블 또는 패턴과 함께 사용하세요.
  • 현재의 반사 신경을 주의하세요. 따뜻한 크림색 페이지에 세리프 디스플레이와 테라코타 강조, 또는 거의 검은색에 하나의 산성 강조는 아무것도 결정되지 않았을 때 생성된 디자인이 손이 닿는 곳입니다. 방향 문단이 요청할 때만 사용하세요.

대비 (WCAG 2.2)

쌍AAAAA
본문 텍스트 (큰 크기 미만)4.5:17:1
큰 텍스트: 24px 일반 또는 약 18.7px 굵기 이상3:14.5:1
UI 컴포넌트 경계, 아이콘, 포커스 표시기, 의미를 전달하는 차트 표시3:1없음
  • 사용자에게 정보를 알리는 플레이스홀더 텍스트는 텍스트입니다: 4.5:1.
  • 비활성화된 컨트롤은 면제되지만, 사용자는 여전히 컨트롤이 존재하는 것을 볼 수 있어야 합니다.
  • 불투명도와 오버레이를 포함한 계산된 색상을 측정하세요. 색상이 있는 카드 위의 60% 불투명도 레이블은 새로운 색상입니다.

타이포그래피

  • 콘텐츠의 레지스터에 맞는 서체를 선택하고, 습관적으로 선택하지 마세요. 세 가지 역할: 개성이 있는 디스플레이 서체(드물게 사용); 편안한 본문 서체; 레이블, 캡션 및 데이터를 위한 유틸리티 서체(표의 숫자에는 표 그림체 사용).
  • 명확한 대비로 짝을 이루세요 (세리프와 산세리프, 기하학적과 휴머니스트) 또는 한 패밀리를 무게별로 사용하세요. 비슷하지만 같지 않은 두 서체는 실수로 읽힙니다.
  • 모듈러 스케일. 하나의 비율을 선택하세요: 조밀한 제품 UI의 경우 1.2, 콘텐츠 및 마케팅의 경우 1.251.333. 크기가 아닌 역할로 이름을 지정하세요: display, h1h4, body-lg, body, body-sm, label, caption.
  • 줄 길이 본문 텍스트의 경우 60~75자 (max-width: 70ch).
  • 디스플레이 유형은 더 좁은 자간(약 -0.02em~-0.04em)과 크기 상한선(약 clamp()를 사용한 6rem)을 가집니다. 더 크다고 의도적으로 보이지는 않습니다.
  • 제목에는 text-wrap: balance, 본문 산문에는 text-wrap: pretty.
  • 줄 높이: 본문은 약 1.5, 디스플레이는 1.1~1.25.

공간, 형태, 깊이

  • 간격 스케일은 4 또는 8 기준: 예: 4, 8, 12, 16, 24, 32, 48, 64. 컴포넌트는 토큰을 사용하고, 절대 원시 픽셀 값을 사용하지 않습니다.
  • 반경: 두세 개의 값과 어디에 적용되는지에 대한 규칙. 중첩된 반경: 내부 반경은 외부 반경에서 그 사이의 패딩을 뺀 값과 같습니다.
  • 입체감: 세 또는 네 단계, 각각 작업(휴식 카드, 드롭다운, 모달)에 연결됩니다. 어두운 테마에서는 더 무거운 그림자가 아닌 더 밝은 표면으로 입체감을 높이세요.

모션

  • 토큰: 지속 시간(예: 120ms, 200ms, 320ms)과 두세 개의 이징 곡선(하나는 진입용, 더 날카로운 하나는 종료용). 요소는 이를 재사용합니다. 아무도 요소별 값을 선택하지 않습니다.
  • 모션은 변화를 설명합니다: 무언가가 어디서 왔는지, 무엇이 반응했는지. 장식만 하는 모션은 생성된 것처럼 보입니다.
  • 하나의 안무된 순간이 모든 것이 한 번에 페이드 인하는 것보다 낫습니다.
  • prefers-reduced-motion: reduce를 존중하세요: 움직임과 긴 전환을 제거하고, 불투명도 변경은 유지하세요.
  • 호버 시 사진 크기를 조정하지 마세요. 컨테이너(그림자, 테두리, 배경)에 애니메이션을 적용하세요.

다크 모드

  • 어두운 테마는 의미론적 토큰의 재매핑이지, 절대 반전이 아닙니다. 바탕에는 순수한 검정이 아닌 어두운 회색을 사용하고, 빛나는 강조의 채도를 낮추세요.
  • 어두운 테마에서 모든 대비 쌍을 다시 확인하세요.
  • 잘못된 테마의 섬광을 방지하세요: 첫 번째 페인트 전에 문서 헤드의 작은 인라인 스크립트에서 테마를 결정하세요.

다크 모드에서 테마 전환, 지속성 또는 이미지를 구현할 때는 references/dark-mode.md를 읽으세요.

컴포넌트 명세

컴포넌트 명세를 작성하기 전에 references/component-spec.md를 읽으세요. 템플릿과 상태 체크리스트가 들어 있습니다.

주의 사항

  • 100에서 900으로 명명된 11개의 음영. 9단계입니다. 개수와 이름이 일치하도록 램프 이름을 지정하세요(50, 100 ... 900, 950은 11개).
  • "큰 텍스트"는 18포인트를 의미하며 18픽셀이 아닙니다. 18px 일반 본문 텍스트는 3:1이 아닌 4.5:1이 필요합니다. 큰 텍스트 임계값은 24px 일반 또는 약 18.7px 굵기입니다.
  • 컴포넌트의 프리미티브 토큰. 첫 번째 테마까지는 작동합니다. 그런 다음 모든 컴포넌트에 편집이 필요합니다.
  • 목업에서 대비 확인, 빌드가 아닌. 불투명도, 오버레이 및 앤티앨리어싱은 실제 색상을 변경합니다. 렌더링된 픽셀 또는 계산된 스타일을 측정하세요.
  • 지역 문제를 해결하기 위한 하나의 전역 조정. 하나의 실패하는 쌍을 구하기 위해 전체 팔레트를 어둡게 하면 다른 모든 쌍이 이동합니다. 쌍의 토큰을 수정하세요.
  • 아무도 사용하지 않는 토큰 또는 아무도 토큰화하지 않은 원시 값. 둘 다 시스템과 빌드가 분기되었음을 의미합니다. 빌드에서 원시 16진수 및 픽셀 값을 grep하세요.
  • 하나의 제목을 위해 로드된 새 글꼴. 각 서체는 로드 시간이 듭니다. 시스템이 이미 로드하는 서체를 사용하세요.

검증

  • 방향 문단이 작성되었고, 각 토큰 패밀리가 이에 연결될 수 있습니다.
  • 모든 텍스트 및 UI 쌍이 밝은 테마와 어두운 테마에서 AA를 통과하며, 빌드된 페이지에서 측정되었습니다.
  • 컴포넌트는 의미론적 토큰만 사용합니다: grep 결과 컴포넌트 코드에 원시 색상 또는 간격 값이 없습니다.
  • 모든 컴포넌트 명세는 모든 상태를 나열합니다.
  • 축소된 모션 설정이 테스트되었습니다: 움직임이 남아 있지 않습니다.
  • 테마 전환 시 반대 시스템 설정으로 하드 새로고침했을 때 섬광이 나타나지 않습니다.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

api-design

Use when designing or changing an HTTP API contract, adding or editing a route, endpoint or webhook, writing an OpenAPI spec, choosing error, pagination or versioning shapes. Also when asking "is this a breaking change". Not for server internals such as jobs, retries or rate-limit storage; use `backend-patterns`.

artist

Use when making or directing visual assets such as illustrations, hero images, icons, logos, brand marks, textures or diagrams, or writing prompts for an image-generation model. Covers art direction, reference boards and critique against a brief. Not for page layout; use `designer`. Not for palettes and tokens; use `visual-design`.

copywriter

Use when writing, rewriting or reviewing words a customer reads, such as landing or marketing pages, headlines, taglines, calls to action, pricing pages, product descriptions, onboarding text, button labels, error messages and empty states. Not for long-form docs or articles; use `docs`. Not for positioning strategy; use `marketing`.

designer

Use when asked to critique, redesign or review the layout and hierarchy of a page, screen, landing page or dashboard (hero, CTAs, card grids, testimonials), or when a design \"looks off\", \"looks generic\" or \"looks AI-made\". Use it for any layout feedback, even if the word design is not used. Not for tokens, palettes or type scales; use `visual-design`. Not for images; use `artist`.

frontend

Use when building, reviewing or fixing browser UI, such as pages, components, forms, client state, charts, print or PDF views, accessibility or web performance (Core Web Vitals, bundle size, slow renders). Not for visual direction, layout critique or brand (use `designer` or `visual-design`). Not for native or React Native apps (use `mobile`).

game-design

Use when designing or reviewing how a game plays: core loop, mechanics, game feel and juice, difficulty curve, progression, economy and balance, tutorials, HUD and menus or a game design document (GDD) and playtest plan. Not for engine code or rendering (use `frontend`) or for non-game product UX (use `ux-research`).

ux-research

Use when planning or synthesising user research (interviews, usability tests, surveys), mapping a journey or job to be done, specifying an interaction's states, or running a heuristic review of a flow. Not for menus, labels, taxonomy or site structure; use `information-architecture`. Not for visual polish; use `designer`.

관련 스킬