jaspr-web:audit

Walk a Jaspr site, inventory CoUI Web selectors, capture a11y + console-error reports per route.

항목	내용
Invoke	/jaspr-web:audit
Category	cocode-web
Complexity	moderate
MCP Servers	playwright

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

한마디로#

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

누가·언제 쓰나요#

우리 웹사이트(예: 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: 부품을 알아보는 기준 목록을 직접 바꿔 끼우고 싶을 때
--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 overriding default CoUI selectors	bundled defaults
`--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).
Apply the selector catalogue → counts per primitive.
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.

Selector Catalogue (defaults)#

Primitive	Selector
Button	`[data-co="button"]`
Button.primary	`[data-co="button"][data-variant="primary"]`
Input	`[data-co="input"]`
Dialog	`[data-co="dialog"]`
NavigationBar	`[data-co="navigation-bar"]`
FlutterCanvas	`flt-glass-pane, flutter-view`

Override with --selector-catalogue=.claude/docs/jaspr-web/selectors.yaml if CoUI Web ships different attribute names.

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  (primary 612, secondary 488, outline 320, ghost 244, link 256, destructive 184)
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