Design2html

Design2HTML — Design Spec to Showcase HTML

Design spec MD 파일 하나를 입력받아, 해당 디자인 시스템을 충실히 반영한 single-file HTML 페이지를 생성하는 스킬.

CRITICAL RULE: No Left Accent Borders

카드, callout, 인용, 강조 요소에 border-left 스타일의 세로 강조선(accent line)을 절대 사용하지 말 것.

• border-left: Npx solid 형태의 왼쪽 강조 라인은 전면 금지
• 카드 강조가 필요하면 background, box-shadow, border(전체), 또는 outline을 사용
• callout/blockquote 강조는 배경색 변경이나 아이콘으로 대체
• 이 규칙은 모든 spec에 공통 적용되며, spec 자체에 border-left가 명시되어 있어도 무시한다
• 생성 후 self-check 시 border-left grep으로 위반 여부를 반드시 확인

Dependency: Design Spec Files

이 스킬은 디자인 스펙 MD 파일이 필요합니다. 스펙 파일은 아래 사이트에서 다운로드:

• https://styles.refero.design — 디자인 시스템 스펙 MD 파일 제공
• 예: OpenAI 스타일 → https://styles.refero.design/style/dc541737-8bf2-4b31-b729-0352f696e82f
• 다운로드한 .md 파일을 프로젝트 폴더에 넣고 /design2html 로 사용

CRITICAL RULE: No Invented Styles

사용자가 직접 제공한 MD 파일 또는 refero.design에서 다운로드한 스펙만 사용할 것.

• "dark mode", "brutalist", "glassmorphism", "terminal", "swiss" 등 임의 스타일을 발명하여 생성하는 것은 금지
• 사용자가 스타일을 지정하지 않으면 refero.design에서 원하는 스타일을 다운로드하도록 안내
• 여러 스타일을 동시에 생성할 때도 각각 다운로드한 spec 기반이어야 함

No-Argument Mode (인자 없이 호출 시)

인자 없이 /design2html만 호출하면, 아래 리스트를 보여주고 사용자에게 선택을 요청한다:

Available design styles:

  1. ease-health    — Calm clinical, green-blue
  2. look-inc       — Editorial, black-white serif
  3. parker-studio  — Scrapbook-chic, sage green
  4. panxo          — Data terminal, warm ink
  5. attio          — Precision toolkit, serif-sans
  6. ui             — Monochromatic blueprint
  7. openai         — Blank canvas, pure white

Pick a number or name (or pass a custom .md path):

사용자가 번호, 이름, 또는 경로를 응답하면 해당 스펙으로 Workflow를 시작한다. 추가로 콘텐츠 주제(--content)와 언어(--lang)도 이 시점에 물어본다:

• "어떤 내용으로 만들까? (예: AI 연구자 소개, SaaS 랜딩페이지, 포트폴리오)"
• 답변 없으면 기본값: 디자인 시스템 소개 페이지, 한국어

Built-in Design Specs

~/.claude/skills/design2html/specs/에 7개 디자인 스펙이 번들되어 있다. 이름만으로 바로 사용 가능 (경로 불필요):

| 이름 | 스타일 | 파일 | |------|--------|------| | ease-health | Calm clinical, green-blue | specs/ease-health.md | | look-inc | Editorial, black-white serif | specs/look-inc.md | | parker-studio | Scrapbook-chic, sage green | specs/parker-studio.md | | panxo | Data terminal, warm ink | specs/panxo.md | | attio | Precision toolkit, serif-sans | specs/attio.md | | ui | Monochromatic blueprint | specs/ui.md | | openai | Blank canvas, pure white | specs/openai.md |

Spec Resolution 순서

1. Built-in 이름 매칭: ease-health -> ~/.claude/skills/design2html/specs/ease-health.md
2. 절대 경로: /path/to/custom-spec.md
3. 현재 디렉토리 상대 경로: ./my-spec.md

새 스펙 추가: specs/ 폴더에 MD 파일 복사하면 자동으로 이름 사용 가능.

Workflow

1. Design Spec 파싱

MD 파일에서 다음 섹션을 추출:

| 섹션 | 추출 대상 | |------|----------| | ## Tokens — Colors | 색상명, hex, CSS token, role | | ## Tokens — Typography | 폰트명, substitute, weights, sizes, line-height, letter-spacing, OpenType features | | ### Type Scale | role별 size/leading/tracking/token | | ## Tokens — Spacing & Shapes | spacing scale, border-radius, shadows, layout values | | ## Components | 컴포넌트명, role, 구체적 스타일 설명 | | ## Surfaces | surface level별 색상·용도 | | ## Do's and Don'ts | 필수/금지 규칙 | | ## Layout | 레이아웃 패턴 (max-width, section gap, hero 구조 등) | | ## Agent Prompt Guide | Quick Color Reference, Example Component Prompts | | ### CSS Custom Properties | :root 블록 전체 | | ## Imagery | 이미지 스타일 가이드 |

2. Font Resolution

MD의 각 폰트에서 Substitute 필드를 확인:

• Google Fonts에서 무료로 사용 가능한 substitute가 있으면 → Google Fonts `` 태그로 로드
• substitute가 system font면 → system font stack 사용
• substitute 없으면 → 원본 폰트명 + generic fallback

중요: CSS에서 font-family 선언 시 substitute 폰트를 먼저, 원본을 뒤에:

--font-suisseintl: 'Inter', 'Suisseintl', sans-serif;

3. HTML 생성 규칙

구조

  
  
  {Brand Name} — Design Showcase
  
  
  ...

  ...
  ...
  ...
  ...
  ...
  ...
  ...

필수 섹션

1. Navigation Bar — MD의 Layout 섹션에 기술된 nav 스타일 반영. 브랜드명 + 샘플 링크 2-3개 + primary CTA 버튼
2. Hero Section — MD의 Layout/Agent Prompt Guide에 기술된 hero 패턴. 대형 헤드라인(display font) + 서브텍스트(body font) + CTA 버튼(들)
3. Color Palette — 모든 토큰 색상을 swatches로 표시. 각 swatch에 이름, hex, token명 표기
4. Typography Showcase — 각 폰트 패밀리를 Type Scale의 모든 단계로 표시. 실제 텍스트 샘플 포함
5. Component Gallery — MD의 Components 섹션에 정의된 모든 컴포넌트를 실제 렌더링. 각 컴포넌트 옆에 이름과 role 표기
6. Surfaces — surface level별 카드를 중첩하여 depth 표현
7. Footer — 브랜드명 + "Design System Showcase" + 생성 날짜

CSS 규칙

• MD의 ### CSS Custom Properties 블록을 그대로 :root에 삽입
• 모든 스타일링은 CSS custom properties를 통해 적용 (하드코딩 금지)
• Do's and Don'ts의 규칙을 엄격히 준수
• Spacing, border-radius, shadow 값은 반드시 토큰 사용
• 반응형: 모바일 (" ".png"

**Mobile 캡처 (선택):**
```bash
npx playwright screenshot --viewport-size="375,812" --full-page "file://" "-mobile.png"

• URL의 공백은 %20으로 인코딩할 것
• output 파일명은 HTML과 동일하게 .png 확장자
• 캡처 후 Read 도구로 PNG를 열어 시각 검증 수행
• 검증 항목: 레이아웃 깨짐, 폰트 미로드, 색상 이상, overflow, 요소 겹침
• 문제 발견 시 HTML 수정 후 재캡처

Full Pipeline 요약

/design2html spec.md
  1. Spec 파싱 + Font resolution
  2. HTML 생성
  3. Self-checklist 검증
  4. /impeccable audit    → 기술 품질
  5. /impeccable critique → UX 디자인
  6. /impeccable polish   → 마감 디테일
  7. Self-audit           → Spec compliance 최종 확인
  8. Playwright screenshot → 시각 검증 (desktop + optional mobile)

--quick 플래그: step 4-7 생략, self-checklist + screenshot만 수행. --full 플래그 (기본): 전체 파이프라인 실행. --no-screenshot 플래그: step 8 생략.

사용 가능한 기존 스킬 맵

| 상황 | 호출할 스킬 | |------|-----------| | 기술 감사 (a11y, perf, responsive) | /impeccable audit | | UX 디자인 평가 | /impeccable critique | | 마감 디테일 점검 | /impeccable polish | | 색상 문제 | /impeccable colorize | | 타이포 문제 | /impeccable typeset | | 레이아웃/정렬 문제 | /impeccable arrange | | 애니메이션 추가 | /impeccable animate | | AI 슬롭 제거 | /impeccable critique (AI slop test 포함) | | 반응형 문제 | /impeccable adapt | | 전체 디자인 리뷰 | /impeccable audit + /impeccable critique |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: s-choung
• Source: s-choung/Research-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.