aiskillstore DESIGN-LINT — 결정론적 디자인 안티패턴 린터
요구사항: detector 스크립트는 Node.js 18+ 로 실행한다(ESM
.mjs,realpathSync/fileURLToPath사용). 외부 npm 의존은 0개. 라이브 URL 검사 경로는 동봉된 playwright MCP(.mcp.json)를 사용한다.
RESOLVE INPUT → RUN DETECTORS(script) → REPORT → [GATE VERDICT]
존재 이유: "내 디자인 리뷰해줘"는 LLM이 매번 다르게 답해 게이트로 쓸 수 없다. 같은 안티패턴 목록을 순수 함수로 강제하면 동일 입력→동일 판정·0토큰·CI 실행 가능한 진짜 게이트가 된다. 이건 impeccable "anti-pattern ban list"의 고레버 절반(목록을 프롬프트가 아니라 탐지기로). LLM 판단 critic의 결정론 버전이라 보면 된다 — 코드/디자인 수정은 하지 않고 판정만 한다.
경계
| LLM 디자인 리뷰 | design-lint | |
|---|---|---|
| 재현성 | 매번 다름 | 동일 입력→동일 출력 |
| 비용 | 토큰 소모 | 0토큰(스크립트) |
| 게이트 적합 | 부적합 | exit code로 CI 게이트 |
| 잡는 것 | 주관적 미감 | 객관적 안티패턴·토큰 위생 |
design-lint는 객관적으로 검증 가능한 것만 잡는다. "이 레이아웃이 우아한가" 같은 주관 판단은 범위 밖 — 그건 사람/디자인 리뷰 몫이다. 둘은 상보적이다. (
frontend-design스킬이 함께 설치돼 있으면 주관적 미감 방향은 그쪽에 맡기고 이 스킬은 객관 게이트만 담당한다.)
Phase 0: PARSE
| 인자 | 기본값 | 설명 |
|---|---|---|
| 입력 (첫 비플래그) | docs/design/prototype/*.html |
검사할 HTML 글롭, 또는 http(s):// URL |
--tokens {경로} |
docs/design/DESIGN-TOKENS.md 자동탐색 |
토큰 위생 검사 기준. 없으면 hygiene 스킵(false positive 방지) |
--gate |
OFF | error 발견 시 비-제로 종료로 호출 파이프라인을 막는다 |
--max-colors N 등 |
references 참조 | 임계값 오버라이드 |
Phase 1: RESOLVE INPUT
- 입력이
http(s)://이면 → Playwright로 렌더 후 정규화한다. (라이브 사이트·배포본 검사 경로)- 뷰포트 고정 필수 — box 측정(w/h/maxWidth)은 뷰포트 의존이라 고정 안 하면 결정론이 깨진다.
browser_resize로 1280×800을 먼저 박는다(반응형 판정이 필요하면 데스크탑+모바일 2개 고정 뷰포트로). browser_navigate→ 임시 HTML:browser_evaluate로document.documentElement.outerHTML덤프를<style>인라인 형태로 저장(정규식 detector 입력).- computed-style 관측(Group A: 대비비·box-model·구조):
node scripts/design-lint.mjs --observe-snippet로 수집 스니펫 문자열을 얻어 그대로browser_evaluate에 주입 → 반환된 관측 배열(JSON)을obs.json으로 저장 → 본 실행에--observed obs.json으로 전달한다. (playwright npm 의존 0 — computed-style COLLECT_SNIPPET 패턴) --observed없이 실행하면 Group A detector는 skip(reportobserved: skipped)되고 정규식 detector만 돈다. 라이브URL 경로에서만 대비비/box-model이 활성된다.
- 뷰포트 고정 필수 — box 측정(w/h/maxWidth)은 뷰포트 의존이라 고정 안 하면 결정론이 깨진다.
- 입력이 글롭이면 → Glob으로 파일 목록 확정. 0개면 사용자에게 경로 확인.
--tokens미지정 시docs/design/DESIGN-TOKENS.md를 Glob으로 자동탐색. 있으면 토큰 위생 ON, 없으면 OFF(경고만).
왜 standalone HTML이 1차 입력인가: framework-neutral standalone HTML(예: 프로토타입 산출물)을 Ground Truth로 삼으면 프레임워크 빌드 없이 즉시 검사 가능하다. 인라인
<style>기반 프로토타입이면 정규식 detector가 바로 돈다.
Phase 2: RUN DETECTORS
번들 스크립트를 실행한다 (LLM 호출 없음):
node ${SKILL_DIR}/scripts/design-lint.mjs <파일들> [--tokens <경로>] [--md]
스크립트는 각 detector를 (harvest, ctx) => Finding[] 순수 함수로 돌려 {id, severity, msg, evidence, file}를 모은다. severity=error는 게이트를 막고, warn은 보고만 한다. 현재 47개 전부 구현, 전체 분류는 references/detectors.md 참조. 정규식 detector는 standalone HTML에서 바로 돌고, Group A(대비비 D-COLOR-05/06·box-model D-A11Y-02/D-SPACE-03·구조 D-LAYOUT-03/04·런타임 오버플로우 D-LAYOUT-08~11)는 --observed(라이브 URL computed-style 수집, Phase 1 참조) 있을 때만 활성·없으면 skip. 색만으로 상태 구분(구 D-A11Y-03)은 DOM 자식 콘텐츠가 필요해 폐기했다(재구현 금지 — detectors.md).
스크립트 출력(JSON)을 받아 그대로 신뢰한다. 임의로 detector를 추가 판단하지 말 것 — 결정론성이 이 스킬의 전부다. 새 규칙이 필요하면 detectors.md에 정의하고 스크립트에 함수로 추가한 뒤 정량 케이스(양성/음성 HTML)로 precision/recall을 검증한다(프롬프트로 때우지 않는다).
Phase 3: REPORT
🔎 design-lint — {PASS|FAIL}
─────────────────────────────
검사 파일: {N}개
토큰 위생: {checked|skipped}
detector: 47종 구현 ({run} 함수 실행)
판정: error {E} · warn {W}
─────────────────────────────
[error] D-COLOR-02 토큰 외 하드코딩 색 7종 — prototype/02.html
#d94f3a #2ecc71 ...
[warn] D-AIDEFAULT-01 beige 배경 — prototype/01.html
...
- error 0 → PASS. error ≥1 → FAIL.
- error는 "토큰 위생 위반"처럼 객관적 계약 위반만. 클리셰(beige·gradient text 등)는 warn(맥락상 의도일 수 있음).
Phase 4: GATE (호출 파이프라인용)
exit code 계약 — --gate가 있을 때만 error 발견 시 비-제로(1) 종료한다. --gate 없이 실행하면 error가 있어도 항상 exit 0(순수 리포터) — 판정은 JSON verdict/summary.error에 담긴다. 그래서 standalone /design-lint는 보고만 하고, 파이프라인만 게이팅된다.
| 호출처 | 호출 형태 | 삽입 지점 | FAIL 판정 시 |
|---|---|---|---|
| CI / verify 스텝 | --gate |
빌드/검증 스크립트 내(시각 산출물 존재 시) | 비-제로 종료로 파이프라인 차단 |
| 리팩토링·리디자인 등 후속 워크플로우 | --gate |
시각 검증 단계(스크린샷 회귀와 병행 가능) | JSON summary.error ≥ 1 → 재수정 이슈로 환류 |
| standalone | 플래그 없음 | /design-lint 직접 |
보고만 (exit 0) |
호출 측은 exit code뿐 아니라 JSON
verdict/summary.error를 읽어 판정할 수 있다(모델 오케스트레이션 파이프라인은 셸&&가 아니라 출력을 읽는 구조가 자연스럽다).--gate의 비-제로 종료는 CI/셸 게이트 신호다.
warn은 게이트를 막지 않는다 — 안티패턴이 의도적 디자인 결정일 수 있으므로 사람이 본다. error(객관적 계약 위반)만 자동 차단한다. 이 분리가 false-positive로 파이프라인을 막지 않게 하는 핵심이다.
검증
이 스킬의 가치는 "detector가 실제 안티패턴을 잡고 깨끗한 디자인은 통과시키는가"로 판정한다. 안티패턴을 심은 HTML / 깨끗한 HTML / 토큰 위생 위반 fixture로 **precision(거짓양성 없음)·recall(놓침 없음)**을 정량 확인한 뒤 detector를 확장한다. 확장 절차는 references/detectors.md의 "확장 원칙" 참조.
주의사항
- 결정론 유지가 최우선 — detector는 전부 순수 함수. LLM 추론을 섞으면 게이트 가치가 사라진다.
- 토큰 없으면 hygiene 스킵 — DESIGN-TOKENS.md 없는 프로젝트에서 모든 색을 error로 잡으면 노이즈. 명시적으로 끈다.
- standalone HTML 범위 — 정규식 파싱은 인라인
<style>프로토타입에 충분. 복잡한 외부 CSS·빌드 산출물은 Playwright computed-style 경로로 정규화 후 검사.