Communitygithub.com

halo-design

Halo 디자인 스킬. 웹 앱, 대시보드, 도구, 랜딩 페이지 또는 벡터 PDF를 위한 차분하고 광택 있는 숫자 우선 디자인 시스템입니다. 영어 + 쿠르드어(소라니) 또는 모든 RTL 스크립트를 지원하는 이중 언어 설계입니다. 사용자가 Halo 스타일을 요청하거나, 정교한 다크/라이트 인터페이스(가장자리 조명 카드, 조용한 모션, 선택적 사운드)를 원하거나, 쿠르드어/아랍어/페르시아어를 영어와 함께 사용하거나, 인쇄용 벡터 PDF가 필요할 때 사용하세요.

halo-design란 무엇인가요?

Halo 디자인 스킬은 AI 에이전트가 일관된 디자인 시스템을 기반으로 고품질의 사용자 인터페이스와 인쇄물을 제작할 수 있게 해주는 Claude Code 및 유사 도구 전용 스킬입니다. 이 시스템은 단순한 테마 복사가 아니라, 토큰, 타이포그래피, 모션, 접근성, 이중 언어 레이아웃, QA를 포함하는 '디자인 문법'을 제공하며, 각 제품의 고유한 특성(시그니처 비주얼, 강조 색상 의미, 일러스트레이션, 카피, 사운드)은 사용자가 자유롭게 정의할 수 있습니다. 핵심 원칙으로는 철저한 숫자 우선 접근법, 가벼운 모션(한 번만 나타남, 반복 없음), 두 가지 테마(다크/라이트)와 모든 방향(LTR/RTL) 및 모든 중단점에서의 설계, 그리고 검증된 라이브러리 사용을 강조합니다. 주요 워크플로는 디자인 브리프 작성, 기초 파일(토큰, CSS, JS) 연결, 섹션 구성, 전화/노트북 균형 맞춤, 이중 언어 사전 설정, 모션 및 사운드 적용, 그리고 자동화된 QA 테스트(9가지 너비 × 2가지 테마 × 2가지 언어)로 마무리됩니다. 또한 인쇄용 벡터 PDF 생성, React/Next/Vue/Tailwind 등 다양한 프레임워크 지원, Figma 디자인 토큰 연동 등의 고급 기능을 제공합니다.

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

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

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

문서

Halo 디자인 스킬

Halo는 디자인하는 방법이지, 복사할 테마가 아닙니다. 문법(토큰, 타이포그래피, 모션, 접근성, 이중 언어 레이아웃, QA)을 고정하고, 제품의 특성(시그니처 비주얼, 강조 색상 의미, 일러스트레이션, 카피, 사운드)은 사용자에게 맡깁니다. examples/의 워크아웃 플랜과 두 템플릿은 메커니즘을 보여주는 데모일 뿐, 재사용할 콘텐츠가 아닙니다.

기본 규칙

  1. 제품별로 디자인하세요. 먼저 브리프(templates/brief.md)를 작성하고 이 제품에 맞는 시그니처 비주얼을 선택하세요(docs/00-creative-direction.md). 링, 운동 픽토그램, 워크아웃 카피는 제품이 일일 목표 달성에 관한 것이 아니라면 잘못된 것입니다.
  2. 플랫폼 → Halo → 검증된 라이브러리. 메커니즘을 절대 발명하지 마세요. (docs/16-libraries.md).
  3. 토큰이 색상, 곡선, 반경의 유일한 출처입니다. tokens/tokens.css 외부에 색상 리터럴은 없어야 합니다. scripts/check_skill.py가 Halo CSS에 대해 이를 강제합니다.
  4. 두 테마, 두 방향, 모든 중단점을 설계하고 테스트합니다.
  5. 숫자 우선: 회색 레이블 → 큰 강조 값 → 평이한 문장. 시각 자료는 숫자를 반복하며, 절대 대체하지 않습니다.
  6. 모션은 가볍게: 하나의 곡선, 한 번만 나타남, 반복 없음, reduced-motion 안전. 실시간 데이터 업데이트는 제자리에서 이루어지며, 절대 다시 애니메이션되지 않습니다.
  7. 로고 없음. 브랜드 슬롯은 제품 이름을 텍스트로 표시합니다. 사용자가 제공하는 경우에만 마크를 사용하세요.
  8. 완료는 QA 통과를 의미합니다. (docs/13-qa.md).

작업에 필요한 것만 읽으세요

문서는 짧습니다(각각 1,500 토큰 미만). 모든 것을 읽지 말고 작업별로 경로를 지정하세요:

작업읽을 내용시작 파일
새 제품 또는 페이지docs/00, docs/02, docs/03, docs/05templates/starter.html(개인 앱) 또는 templates/dashboard.html(데이터/운영)
데이터가 많은 화면docs/10, docs/04templates/dashboard.html
쿠르드어 / 아랍어 / 페르시아어docs/08, docs/03lang=ckb를 사용한 템플릿
휴대폰 다듬기docs/07—
모션, 가장자리 조명, 스크롤docs/06—
사운드docs/14js/halo-sound.js
아이콘 또는 일러스트레이션icons/README.md, docs/09icons/
인쇄 문서 또는 PDFdocs/11templates/print-a4.html
React / Next / Tailwind / Vuedocs/17—
라이브러리 선택docs/16—
Figma 또는 기타 도구용 디자인 토큰docs/15, tokens/*.tokens.json—
접근성docs/12—
테스트docs/13qa/

examples/workout-plan/index.html 전체를 읽지 마세요(약 42k 토큰). 대신 특정 패턴을 검색하세요(grep -n "restTimer" …).

워크플로우

  1. 브리프. templates/brief.md를 작성하세요: 대상 사용자, 확인하러 돌아오는 이유, 1~3개의 히어로 숫자, 시그니처 비주얼, 강조 색상 의미, 일러스트레이션 언어, 모션 및 사운드 강도, 표면, 언어, 섹션. 요청이 모호하면 브리프를 보여주고 한 가지 질문을 하세요. 그렇지 않으면 짧은 단락으로 설명하고 빌드하세요.
  2. 기초. tokens/tokens.css, css/halo.css, js/halo.js(브리프에 사운드가 있는 경우 js/halo-sound.js 추가)를 연결하고 Halo.init({dict})를 호출하세요. 폰트: Google Sans + IBM Plex Sans Arabic (docs/03).
  3. 섹션 구성 docs/05의 컴포넌트를 사용하세요:
    • 기존 조각으로 시그니처 비주얼을 빌드하세요: Halo.rings, Halo.spark, .target 마커가 있는 .meter, .bars, .timeline, 상태 그리드, 또는 타이포그래피 히어로. 또는 docs/00의 규칙을 따르는 새 것을 발명하세요.
    • 모든 템플릿 콘텐츠를 교체하세요. 페이지에 "링 닫기" 또는 "GPU 정상"이라고 표시되면서 제품이 그것에 관한 것이 아니라면 복사한 것입니다.
  4. 휴대폰과 노트북을 별도로 균형 잡으세요(docs/04, docs/07).
  5. 이중 언어: 모든 문자열은 사전에 포함되며, docs/08의 RTL 규칙을 따릅니다. 직접 쿠르드어를 작성하는 경우 사용자에게 알리고 원어민 검토를 권장하세요.
  6. 모션 및 사운드는 브리프가 선택한 강도로 적용하세요(docs/06, docs/14).
  7. QA, http를 통해 제공:
    python3 qa/qa_layout.py http://localhost:8000/page.html    # 9가지 너비 × 2가지 테마 × 2가지 언어
    python3 qa/qa_touch.py  http://localhost:8000/page.html    # 휴대폰 터치 제품군
    
    자체 상호작용 검사와 axe-core를 추가하세요. 두 테마에서 390 및 1440 너비의 스크린샷을 검토하세요.
  8. 인쇄 필요한 경우: HTML → scripts/print_pdf.py → qpdf 병합 → scripts/verify_pdf.sh(이미지 0개). .ttf 폰트를 포함하세요.

전달 전 체크리스트

  • 브리프가 존재하며, 시그니처 비주얼이 제품에 적합합니다(기본적으로 링이 아니고, 복사된 콘텐츠가 아님).
  • 최대 세 가지 강조 색상 의미가 일관되게 사용됨; 텍스트 강조는 --XT를 사용합니다.
  • 토큰 외부에 색상 리터럴이 없음; 사용자가 제공하지 않은 로고가 없음.
  • 노트북: 균형 잡힌 열, 정렬된 바닥글, 차트가 카드를 채움. 휴대폰: ≤ 4개의 탐색 컨트롤, 44px 터치 대상, 320px에서 가로 스크롤 없음.
  • RTL: dir/lang, 뒤집힌 갈매기 모양, 미러링된 차트, 라틴어 용어 및 라틴어 단위 주위에 <bdi>.
  • reduced motion 준수; 사운드(있는 경우)는 토글이 있으며 절대 유일한 신호가 아님.
  • 사실적 주장에 대한 출처 링크; 파괴적 작업에 대한 실행 취소.
  • qa_layout.py 및 qa_touch.py 통과; 콘솔 오류 없음; PDF가 벡터로 확인됨.

재현성

  • make setup은 고정된 종속성(requirements.txt)과 Chromium을 설치합니다.
  • make check는 스킬 자체를 검증합니다: 링크, 토큰 동기화, 잘못된 색상, 로고, JS 구문, frontmatter.
  • make qa는 모든 템플릿과 예제를 테스트합니다. make assets는 README 이미지를 다시 렌더링합니다. make tokens는 DTCG JSON을 다시 빌드합니다.
  • CI는 .github/workflows/qa.yml에서 동일하게 실행됩니다.

파일 맵

경로설명
docs/00-creative-direction.md먼저 읽으세요. 브리프, 시그니처 비주얼 카탈로그, 강조 색상 의미, 일러스트레이션 언어, 안티패턴
templates/brief.md작성할 브리프
templates/starter.html개인 앱 메커니즘: 분할 히어로, 링, 작업, 타이머, 시트, 사운드
templates/dashboard.html데이터/운영 메커니즘: 상태 그리드, 스파크라인, 대상 마커가 있는 미터, 실시간 업데이트, 정적 모션
templates/print-a4.html벡터 인쇄 페이지
tokens/tokens.css(진실의 원천) + DTCG 2025.10 JSON
css/halo.css · js/halo.js · js/halo-sound.js컴포넌트 · 런타임 · 차분한 사운드
icons/UI 아이콘(Lucide 그리드), 글리프, 픽토그램 문법 + 갤러리
docs/01–17원칙, 색상, 타이포그래피, 레이아웃, 컴포넌트, 모션, 휴대폰, RTL, 아이콘, 데이터 시각화, 인쇄, 접근성, QA, 사운드, Figma, 라이브러리, 프레임워크
qa/ · scripts/테스트 제품군 · 인쇄, 검증, 토큰, 에셋, 자가 점검
fonts/IBM Plex Sans Arabic + Inter (TTF, OFL) for 오프라인, CI 및 인쇄
examples/workout-plan/Halo로 만든 하나의 완성된 제품 (사이트 + 4개의 벡터 PDF). 참고용으로만 사용하세요.

관련 스킬