dsforge

A verified design → design-system → code harness for Claude Code. / Claude Code용 검증형 디자인 → 디자인시스템 → 코드 하네스.

목차 / Table of Contents

• 한국어
  • 개요
  • 설치 / 사용
  • 무엇을 입력받나
  • 구조
  • 한계
  • 포크 / 리브랜딩 메모
• English
  • Overview
  • Install / use
  • What it asks for
  • Structure
  • Limits
  • Notes for forking / rebranding

한국어

개요

기능 명세와 Figma 디자인시스템(DS)을 주면 전체 파이프라인을 굴립니다 — Figma 시안, 토큰 바인딩 디자인시스템, 토큰 충실 프론트엔드 코드 — 자동 검사 게이트(DS 감사 · 시안-명세 대조 · 코드-DS 대조)와 사람 리뷰 게이트 2곳과 함께. 원칙은 추정하지 말고 측정하라: 모든 단계를 빌드 보고서가 아니라 Figma 노드와 코드를 직접 읽어 검증합니다. 두 화면(리스트·폼) × 두 도메인에서 단계별로 검증됐고, DS가 없을 때 토큰 바인딩 DS를 처음부터 도출하는 Branch B 도 검증됐습니다.

엔진은 Claude입니다(시안·코드는 Claude가 만들고, 리뷰어가 검증). 번들 스크립트는 검사만 자동화합니다 — dsforge는 화면을 혼자 찍어내는 정적 생성기가 아닙니다.

설치 / 사용

동작 모델: dsforge 설치(npx dsforge-harness init 또는 아래 플러그인 경로)는 셸에서 실행하는 유일한 단계 입니다. skill과 CLAUDE.md 진입점만 깔아줍니다. 이후는 전부 Claude Code 세션 안에서 일어납니다: Claude가 Figma 시안과 코드를 만들고, Figma-MCP 검사(Check 1/2)와 Node 검사(Check 3 / verify)를 돌리고, 사람 게이트 2곳 에서 멈춰 승인을 기다립니다. dsforge는 터미널에서 호출하는 단독 생성기가 아니라 Claude Code가 따르는 하네스 입니다. npx dsforge-harness verify/check3는 Node 쪽 검사만 다시 돌릴 뿐 화면을 만들지 않습니다.

A — npm으로 프로젝트별 설치 (공개 기본):

npx dsforge-harness init

skill을 .claude/skills/dsforge/에 설치하고 현재 프로젝트에 CLAUDE.md 진입점을 씁니다. 그 폴더에서 Claude Code를 열면 읽고 시작합니다. "하네스를 한 리포에 떨궈서 바로 쓰는" 경로이며 누구나 됩니다(npm 패키지는 공개). (npx dsforge-harness verify <project> <screen>로 검증기도 돌릴 수 있습니다.)

npm 패키지명은 dsforge-harness, 설치되는 CLI 명령은 dsforge 입니다 — 전역 설치 (npm i -g dsforge-harness) 후엔 dsforge init / dsforge verify …로 실행합니다.

B — Claude Code 플러그인으로 (모든 프로젝트에서 사용):

/plugin marketplace add jsiksn/dsforge      # 이 GitHub 리포
/plugin install dsforge@dsforge

설치 후 아무 프로젝트나 열고, dsforge skill이 깔려 있으므로 명세로 화면을 만들어 달라고 하면 하네스가 트리거됩니다. 나중에 /plugin marketplace update로 갱신.

주의 — GitHub 리포는 현재 비공개입니다. 마켓플레이스 경로(B)는 리포 소유자(또는 접근 허가된 계정)만 됩니다. 공개 전까지는 위 npm 경로(A) 를 쓰세요(공개 기본).

C — 수동: plugins/dsforge/skills/dsforge/를 ~/.claude/skills/(모든 프로젝트) 또는 리포의 .claude/skills/(해당 프로젝트)로 복사.

설치 후 Claude Code에 붙여넣어 하네스를 시작하는 프롬프트:

Run the dsforge harness for this project. Inputs:
- Design-system Figma file key: <DS_FILE_KEY>   (or: "no DS yet — propose mockups first, then derive the DS")
- Functional spec: <paste the spec, or a path/link>
- Working Figma file key (for mockups): <WORK_FILE_KEY>
- Screens to build: <e.g. dataset list; model create/edit>
- Mockup options per screen: <default 2-3>

Follow the dsforge skill's pipeline exactly. First confirm whether a real DS exists
and how many mockup options per screen, then take the branch:
- Branch A (DS exists): audit the DS -> if it has gaps, ASK me augment-vs-mark-"(proposed)"
  -> extract tokens -> per screen [ build 2-3 mockup OPTIONS -> run checks ->
  STOP for my pick (GATE 1) -> build code -> run checks -> STOP for final review (GATE 2) ].
- Branch B (no DS): per screen build 2-3 mockup OPTIONS first -> STOP for my pick (GATE 1)
  -> author a new token-bound DS in a new Figma file (variables, focus/disabled variants,
  elevation) until check1 PASSes -> extract tokens -> build code -> run checks ->
  STOP for final review (GATE 2).
Rules: tokens only (no hardcoded hex/px) once a DS exists; never fabricate spec content
(mark proposals "(제안)"/"(proposed)"); measure by reading Figma nodes and code, don't
trust build reports; hold at both human gates (exactly two) until I approve.
Craft: author every component with auto-layout (no clipped labels, no floating/detached
nodes, correctly-sized badges); keep the DS and the screens on SEPARATE pages
("Design System" / "Screens"); and render + self-critique each screen to a clean image
BEFORE running the mechanical checks — GATE 1 is the visual judgment point, and a green
check is a floor, not the quality bar.

무엇을 입력받나

트리거되면 Claude Code가 먼저 진짜 DS가 이미 있는지(Branch A) 없는지(Branch B)와 화면당 시안 옵션 수 (기본 2–3)를 확인한 뒤, ① 대상 디자인시스템 Figma 파일 키(Branch A) ② 기능 명세 ③ 시안용 작업 Figma 파일 키 를 받습니다. 그다음 둘 중 하나를 굴립니다:

• Branch A (DS 있음): DS 감사(빈틈 있으면 보강 vs "(제안)" 표시 를 물음) → 토큰 추출 → 화면마다 [시안 2–3안 → 검사 → 하나 선택 → 코드 → 검사 → 최종 리뷰].
• Branch B (DS 없음): 화면마다 [시안 2–3안 → 하나 선택] → 새 Figma 파일에 토큰 바인딩 DS 작성(변수, focus/disabled variant, elevation)해서 DS 감사 통과까지 → 토큰 추출 → 코드 → 검사 → 최종 리뷰.

어느 쪽이든 사람 게이트는 정확히 둘입니다.

구조

dsforge/
├── .claude-plugin/marketplace.json        # 이 리포는 CC 플러그인 마켓플레이스
├── plugins/dsforge/
│   ├── .claude-plugin/plugin.json
│   └── skills/dsforge/
│       ├── SKILL.md                        # 하네스 skill (트리거 + 워크플로)
│       ├── validators/                     # 검증기 + 토큰 추출기 (+ projects/_TEMPLATE.json, ezp.json)
│       ├── references/                     # 방법론, 런북, 실제 실행 예시
│       └── assets/code-scaffold-reference-ezp/   # 참조 React 구현 (드롭인 아님, 패턴)
├── templates/CLAUDE.md                     # `dsforge init`가 프로젝트에 써줌
├── bin/dsforge.js                          # npm CLI (init / verify / check3)
└── package.json

제네릭·재사용: validators/(DS를 입력으로) 와 references/(방법). 프로젝트별 예시: code-scaffold-reference-ezp/ 와 validators/projects/ezp.json — ezp는 dsforge가 검증된 디자인시스템일 뿐, 하네스의 일부가 아닙니다.

한계

DS 조합형 화면(리스트 / 폼 / 상세)에서 증명됨. 캔버스 / 그래프 에디터형 화면은 미검증. 검사는 기계적 토큰/콘텐츠/구조 충실도만 검증하며, 시각적 판단과 디자인 의도는 사람 게이트의 몫입니다. 전제: Claude Code + Figma MCP(당신 Figma에 인증), Node.js ≥ 18, 리뷰어.

포크 / 리브랜딩 메모

• 이름 dsforge가 전반(package, plugin, skill, marketplace)에 쓰입니다. 리브랜딩하려면 package.json, .claude-plugin/marketplace.json, plugins/dsforge/.claude-plugin/plugin.json에서 바꾸고 plugins/dsforge/ + plugins/dsforge/skills/dsforge/를 리네임하세요.
• npm publish 전에 npm 이름 가용성 확인 — 선점됐으면 스코프(@<you>/dsforge).

라이선스: MIT.

English

Overview

Give it a functional spec and a Figma design system, and it drives the whole pipeline — Figma mockups, token-bound design system, token-faithful front-end code — with automated check gates (DS audit, mockup-vs-spec, code-vs-DS) and two human review gates. Its rule is measure, don't estimate: every step is verified by reading Figma nodes and code, not by trusting a build report. Validated end-to-end on two screens (a list and a form) across two domains — and on Branch B, where it derives a brand-new token-bound design system from scratch when no DS exists.

The engine is Claude (it builds the mockups and code; a reviewer verifies). The bundled scripts automate only the checking — dsforge is not a static generator that emits screens on its own.

Install / use

How it runs (operating model): installing dsforge — npx dsforge-harness init or the plugin path below — is the only step you run at a shell. It just places the skill and a CLAUDE.md entry point. Everything after that happens inside a Claude Code session: Claude builds the Figma mockups and the code, runs the Figma-MCP checks (Check 1/2) and the Node checks (Check 3 / verify), and stops at the two human gates for your sign-off. dsforge is not a standalone generator you invoke from the terminal — it is a harness that Claude Code follows. The npx dsforge-harness verify/check3 commands only re-run the Node-side checks; they do not build screens.

A — Per project via npm (public default):

npx dsforge-harness init

Installs the skill to .claude/skills/dsforge/ and writes a CLAUDE.md entry point into the current project. Open Claude Code in that folder → it reads them and starts. This is the "drop the harness into one repo and go" path, and it works for anyone — the npm package is public. (You can also npx dsforge-harness verify <project> <screen> to run the verifier.)

The npm package is dsforge-harness, but the CLI command it installs is dsforge — so after a global install (npm i -g dsforge-harness) you run dsforge init / dsforge verify ….

B — As a Claude Code plugin (available in every project):

/plugin marketplace add jsiksn/dsforge      # this GitHub repo
/plugin install dsforge@dsforge

Then start any project: open Claude Code, and because the dsforge skill is installed, asking it to build screens from a spec triggers the harness. Update later with /plugin marketplace update.

Note — the GitHub repo is currently private. The marketplace path (B) works only for the repo owner (or accounts granted access). Until the repo is made public, use the npm path (A) above — it's the public default.

C — Manual: copy plugins/dsforge/skills/dsforge/ into your ~/.claude/skills/ (all projects) or a repo's .claude/skills/ (that project).

After installing, paste this into Claude Code to kick off the harness:

Run the dsforge harness for this project. Inputs:
- Design-system Figma file key: <DS_FILE_KEY>   (or: "no DS yet — propose mockups first, then derive the DS")
- Functional spec: <paste the spec, or a path/link>
- Working Figma file key (for mockups): <WORK_FILE_KEY>
- Screens to build: <e.g. dataset list; model create/edit>
- Mockup options per screen: <default 2-3>

Follow the dsforge skill's pipeline exactly. First confirm whether a real DS exists
and how many mockup options per screen, then take the branch:
- Branch A (DS exists): audit the DS -> if it has gaps, ASK me augment-vs-mark-"(proposed)"
  -> extract tokens -> per screen [ build 2-3 mockup OPTIONS -> run checks ->
  STOP for my pick (GATE 1) -> build code -> run checks -> STOP for final review (GATE 2) ].
- Branch B (no DS): per screen build 2-3 mockup OPTIONS first -> STOP for my pick (GATE 1)
  -> author a new token-bound DS in a new Figma file (variables, focus/disabled variants,
  elevation) until check1 PASSes -> extract tokens -> build code -> run checks ->
  STOP for final review (GATE 2).
Rules: tokens only (no hardcoded hex/px) once a DS exists; never fabricate spec content
(mark proposals "(제안)"/"(proposed)"); measure by reading Figma nodes and code, don't
trust build reports; hold at both human gates (exactly two) until I approve.
Craft: author every component with auto-layout (no clipped labels, no floating/detached
nodes, correctly-sized badges); keep the DS and the screens on SEPARATE pages
("Design System" / "Screens"); and render + self-critique each screen to a clean image
BEFORE running the mechanical checks — GATE 1 is the visual judgment point, and a green
check is a floor, not the quality bar.

What it asks for

Once triggered, Claude Code first confirms whether a real DS already exists (Branch A) or not (Branch B) and how many mockup options per screen (default 2–3), then collects ① the target design-system Figma file key (Branch A) ② the functional spec ③ a working Figma file key for mockups. Then it runs one of:

• Branch A (DS exists): DS audit (if it has gaps, it asks you augment vs. mark "(proposed)") → token extract → per screen [2–3 mockup options → check → you pick one → code → check → final review].
• Branch B (no DS): per screen [2–3 mockup options → you pick one] → author a token-bound DS in a new Figma file (variables, focus/disabled variants, elevation) until the DS audit passes → token extract → code → check → final review.

Either way there are exactly two human gates.

Structure

dsforge/
├── .claude-plugin/marketplace.json        # this repo is a CC plugin marketplace
├── plugins/dsforge/
│   ├── .claude-plugin/plugin.json
│   └── skills/dsforge/
│       ├── SKILL.md                        # the harness skill (triggers + workflow)
│       ├── validators/                     # verifier + token extractor (+ projects/_TEMPLATE.json, ezp.json)
│       ├── references/                     # methodology, runbook, real-run examples
│       └── assets/code-scaffold-reference-ezp/   # reference React impl (a pattern, not drop-in)
├── templates/CLAUDE.md                     # written into a project by `dsforge init`
├── bin/dsforge.js                          # the npm CLI (init / verify / check3)
└── package.json

Generic & reusable: validators/ (DS-as-input) and references/ (method). Project-specific examples: code-scaffold-reference-ezp/ and validators/projects/ezp.json — ezp is just the design system dsforge was validated on, not part of the harness.

Limits

Proven for DS-composition screens (list / form / detail). Canvas / graph-editor screens are unproven. The checks verify mechanical token/content/structure fidelity; visual judgment and design intent are what the human gates are for. Prerequisites: Claude Code + Figma MCP (authed to your Figma), Node.js ≥ 18, and a reviewer.

Notes for forking / rebranding

• The name dsforge is used throughout (package, plugin, skill, marketplace). To rebrand, change it in package.json, .claude-plugin/marketplace.json, plugins/dsforge/.claude-plugin/plugin.json, and rename plugins/dsforge/ + plugins/dsforge/skills/dsforge/.
• Check npm name availability before npm publish — if taken, scope it (@<you>/dsforge).

License: MIT.