/jaspr-web audit — 웹사이트 건강검진

Jaspr 사이트를 순회하며 CoUI Web 셀렉터 현황을 조사하고, 화면별 접근성(a11y) + 콘솔 에러 리포트를 캡처합니다.

항목	내용
실행 명령	`/cc-jaspr-web:audit`
분류	웹
난이도	●●○ 보통
MCP 서버	`playwright`

한마디로#

웹사이트의 모든 페이지를 자동으로 한 바퀴 돌면서 "어떤 부품(버튼·입력창 등)이 몇 개나 쓰였는지" 세어보고, "글씨가 너무 흐려서 안 보이거나, 화면 뒤에서 오류가 나는 곳은 없는지" 점검해 주는 웹사이트 건강검진입니다. 건물을 한 층씩 돌며 문·창문 개수를 세고 누수·균열을 기록하는 시설 점검과 비슷합니다.

누가·언제 쓰나요#

우리 웹사이트(예: CoUI 사이트)가 얼마나 크고, 어떤 구성요소로 이루어져 있는지 전체 현황을 한눈에 파악하고 싶을 때
화면에 보이지 않는 접근성 문제(흐린 글씨, 대체 텍스트 누락 등)나 숨은 오류를 한꺼번에 찾아내고 싶을 때
배포 전후로 사이트 상태를 객관적인 숫자로 기록해 두고 싶을 때

무엇을 해주나요#

검진이 끝나면 .claude/docs/jaspr-web/audit-<시각>/ 폴더 아래에 결과물이 정리되어 남습니다.

summary.md — 전체 요약 보고서 (몇 개 페이지를 돌았고, 부품이 총 몇 개이며, 발견된 문제는 몇 건인지)
inventory/ — 페이지별 부품 개수 명세 (JSON)
screens/ — 페이지별 전체 화면 캡처 이미지 (PNG)
a11y/ — 페이지별 접근성 점검 결과 (텍스트)
network/, console/ — 페이지별 네트워크·오류 기록

이 명령은 세어보고 점검만 합니다. 화면을 클릭하거나 조작하지 않고, 디자인이 픽셀 단위로 똑같은지까지는 보지 않습니다(그건 /jaspr-web match, /jaspr-web regression 같은 다른 명령의 몫입니다).

어떻게 쓰나요#

/jaspr-web audit \
  --url=https://coui.cocode.im \
  --depth=2 \
  --exclude=/contributing,/changelog

--url (필수): 검진을 시작할 사이트 주소
--depth: 시작 페이지에서 몇 단계까지 따라 들어갈지 (기본 1단계)
--include / --exclude: 점검에 포함하거나 건너뛸 경로 지정
--selector-catalogue: 역할 기반 기본 목록에 프로젝트만의 표식(예: data-testid)을 더하거나, 일부 항목을 덮어쓰고 싶을 때
--mcp: 사용할 브라우저 자동화 엔진 (기본 playwright)
--output: 결과물을 저장할 폴더

위 예시는 CoUI 사이트를 2단계 깊이까지 돌되, /contributing과 /changelog 페이지는 건너뛰며 점검합니다.

안에서 무슨 일이 벌어지나요#

발견한 모든 페이지마다 아래 과정을 차례로 반복합니다.

페이지로 이동해 화면이 완전히 멈출(로딩이 끝날) 때까지 기다립니다.
화면 구조를 통째로 떠서, 기준 목록에 따라 버튼·입력창·대화창 등 부품을 종류별로 셉니다.
페이지 전체를 이미지로 캡처합니다.
화면 뒤에서 난 오류·네트워크 실패를 모아 담습니다.
흐린 글씨·대체 텍스트 누락 같은 접근성 문제를 자동으로 점검합니다.
페이지별 결과물을 파일로 저장하고, 마지막에 전체 요약 보고서를 만듭니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Parameters#

Parameter	Required	Description	Default
`--url`	✅	Root URL to crawl (e.g. `https://coui.cocode.im`)	—
`--depth`	❌	Crawl depth from root	`1`
`--include`	❌	Glob list of paths to include	all
`--exclude`	❌	Glob list of paths to skip	none
`--selector-catalogue`	❌	Path to YAML adding or overriding the role-based defaults (e.g. project `data-testid` hooks)	role table below
`--mcp`	❌	`playwright` (default) or `chrome-devtools`	`playwright`
`--output`	❌	Output dir	`.claude/docs/jaspr-web/audit-<ts>/`

Loop#

For every page discovered:

Navigate (browser_navigate).
Wait for networkidle.
Snapshot the DOM + ARIA tree (browser_snapshot + aria-snapshot).
Count primitives by ARIA role from the snapshot (table below), plus any --selector-catalogue entries.
Capture full-page screenshot.
Drain console messages, network errors (4xx/5xx), and uncaught exceptions.
Run accessibility heuristics (axe-style: missing alt, low-contrast text, role mismatches).
Write per-route artifacts.

Role-based defaults#

CoUI Web ships no selector catalogue — no data-co="<component>" / data-variant attributes and no per-component class catalogue — so primitives are counted by role (full table and caveats: jaspr-web-guide skill).

Primitive	ARIA role	CSS fallback
Button	`button`	`button:not([role])`
Text field	`textbox`	`input:not([type=checkbox]):not([type=radio]):not([type=hidden]):not([type=file]), textarea`
Checkbox / Radio / Switch	`checkbox` / `radio` / `switch`	`[role="checkbox"]` / `[role="radio"]` / `[role="switch"]`
Dialog / Drawer	`dialog`	`[role="dialog"][aria-modal="true"]`
Tabs	`tab`	`[role="tab"]`
Navigation bar	`navigation`	`nav`
FlutterCanvas	—	`flt-glass-pane, flutter-view`

Variants (primary, outline, …) are styles, not attributes, so they are not counted. Add project hooks (e.g. [data-testid="price-card"]) with --selector-catalogue=.claude/docs/jaspr-web/selectors.yaml.

Example#

/jaspr-web audit \
  --url=https://coui.cocode.im \
  --depth=2 \
  --exclude=/contributing,/changelog

Output (excerpt of summary.md):

Crawled: 142 routes
Components inventoried: 7,318 instances
Buttons:        2,104
Inputs:           512
Dialogs:           37
Flutter embeds:   142  (one per live-preview card)
A11y findings:     12  (1 missing alt, 11 low-contrast text)
Console errors:     0
Network 4xx:        3  (favicon-related, ignorable)

What this command does not do#

It does not interact with Flutter Web embeds (just counts the canvas containers). Use /jaspr-web match or /jaspr-web widgetbook-web for that.
It does not assert pixel parity. Use /jaspr-web regression for that.

Artifacts#

.claude/docs/jaspr-web/audit-<ts>/
├── inventory/
│   └── <route-slug>.json
├── screens/<route-slug>.png
├── a11y/<route-slug>.txt
├── network/<route-slug>.har
├── console/<route-slug>.log
└── summary.md