design-prim

Skill: design-prim

design (lock in one design system throughout) + prim (polished, impeccable standard, no misalignment).

Compress once: orca-onboard (drop — too heavy, hallmark scans tokens itself at Step 0) + playwright-verify + impeccable (bundle doyourmagic/impeccable) + hallmark (design floor + slop-test) + qc-uiux (senior 4-section verdict, using deterministic engine visual-qa). Do not rewrite the logic of these skills — just call them in the right order, at the right target.

Traps already paid for — read before running: /impeccable document generates DESIGN.md by re-capturing exactly the token/color/font CURRENTLY in the code (it describes the current state, does not propose anything new). If you call this command first and then give hallmark redesign to read, Hallmark Step 0 Pre-flight treats DESIGN.md as a locked system, overriding everything else — meaning it hard-locks the very slop token set that needs cleaning, then only tweaks a few small things on top. This is why the previous version of this skill "ran but the page did not get prettier": it thought it was locking in a new system, but actually locked in the old one. Do not call /impeccable document in the slop-cleanup flow.

WHAT

Purpose and context

Purpose: clean up UI/UX slop when onboarding any project — capture before, let hallmark redesign generate its own new design system, then measure + patch per slop-test, /impeccable audit/critique, /qc-uiux until clean or out of 2 rounds.
Trigger (when to use):
- Just received an unfamiliar project (onboard) and need to bring UI to a consistent standard, without exposing AI-slop traces.
- There are already many scattered views/screens, each one a different style, need to lock in one system.
- User says "clean up slop", "tidy the project UI", "standardize UI throughout", "onboard then clean up UI", "design prim", "/design-prim".
Non-goals: DO NOT use when only fixing 1 small component (use hallmark component-scope directly) or when deep understanding of architecture/business logic beyond UI is needed (that is the full orca-onboard , not this skill). Do not rewrite the logic of the skills being called.

Mental model

impeccable đã cài? → view/route → ảnh before → PRODUCT.md (bối cảnh, KHÔNG token cũ) → hallmark redesign (design.md mới, bước DUY NHẤT sinh code) → 3 lớp đo (slop-test · impeccable audit/critique · qc-uiux) + ảnh after → vá theo bảng finding, tối đa 2 vòng → known limitation.

Input and output contract

	Field	Required?	Meaning
In	target project (root + router/pages)	yes	where all chat commands run
In	app running at `<base-url>`	yes for `/qc-uiux` and images	like `playwright-verify`
In	`design.md`/`DESIGN.md` valid wants to KEEP	no	only when the user wants to keep the old system, stated clearly in the brief
Out	`PRODUCT.md` + `design.md` new + redesigned code	has	due to `/impeccable init` and `hallmark` generated
Out	before/after images for each view + results of 3 measurement layers	has	evidence of "prettier", not just bare scores
Out	final report	has	remaining findings after round 2 recorded as known limitation

Rules and capabilities

RULE-01 (MUST): Order 0→6 is not reversed: step 4 is the ONLY step that generates/modifies code; step 3 is only context, steps 5–6 only measure and patch — if you stop at step 3 or only run step 5 without reaching step 4/6, the "beautifying" job is considered NOT done, even with a score report.
RULE-02 (MUST): Steps 3–6 are commands chat (/impeccable ..., hallmark is a skill), not shell — don't type them into the terminal.
RULE-03 (MUST): Don't add orca-onboard again unless the user needs to understand architecture/business logic beyond the UI scope.
RULE-04 (MUST): Already installed impeccable globally (not per project) → remove/reinstall with the correct scope before running step 3, to avoid mixing with artifacts from other projects (see trap 2 in dym-impeccable-install-into-your-project).
Capabilities: read the target project's route structure; call other UI skills via chat (not shell); run a headless browser to capture/measure; write the target project's UI code (only at the redesign/patch step).

Failure boundaries

Stopping at step 3 or only running step 5 without reaching step 4/6 → NOT done the "beautifying" job, even with a score (RULE-01).
App cannot run at <base-url> → cannot capture/cannot /qc-uiux it: blocked, notify the user.
Findings remain after round 2 → partial, record known limitation, don't loop infinitely.
Accidentally ran /impeccable document before redesign → the old slop system is locked in: failed, discard DESIGN.md that and redesign again.

HOW

Main workflow

W01–W07 correspond to steps 0–6 below.

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	target project root	Check `.claude/skills/impeccable/`; if missing, install via hub	impeccable ready	already present → skip; install global → B01
W02	deterministic	router/pages	List views/routes	view list	—
W03	effect	view + `<base-url>`	Capture before with `playwright-verify`	before screenshots	app doesn't run → blocked
W04	judgment	target project chat	`/impeccable init` → `PRODUCT.md` (DO NOT `document`)	product context	—
W05	effect	root + summary `PRODUCT.md`	`hallmark` verb `redesign` on project root	`design.md` + new code	want to keep old system → B02
W06	deterministic	view redesigned	3 measurement layers + after capture	finding + after screenshots	still P0/P1 / gate fail / NEEDS FIX → W07
W07	effect	finding	Patch according to the finding type table, then repeat W06	clean	after round 2 → known limitation

Detailed steps (source of truth for W01–W07):

Check conditions — has impeccable been installed in the target project yet? Check existence .claude/skills/impeccable/ at the target project root (artifact from the previous install run). If it already exists → skip this step, don't reinstall. If not present → call /dym-impeccable install-into-your-project (via the hub, let it find the correct version in 1 of 3 places — sibling npx skills add, bundle project, or .claude/skills/ — do not hardcode the bundle path of the framework repo, because the target project may not have it). Pitfall to remember when following that file: always npx impeccable install -y --scope=project --providers=claude, don't type --help.
List views/routes — Explore agent or grep directly the router/pages config of the target project. No need for a separate skill, no need for orca-onboard.
Capture current state (before) each view with playwright-verify — keep it for comparison in step 5.
Product context (not the old token) — type in the target project chat: /impeccable init → generate PRODUCT.md (users, purpose, constraints, tone). This is the input compensating for hallmark redesign (verb) being silent and not asking about audience/use-case/tone — paste the summary PRODUCT.md into the brief when calling step 4. DO NOT run /impeccable document (see the pitfall above).
Actual redesign — this is the only step that generates new code. Call skill hallmark with verb redesign on the PROJECT ROOT (route folder path, not individual files) → falls into the multi-page flow of hallmark: it automatically scans existing tokens/brand, automatically chooses genre/macrostructure/theme, writes its own design.md of its own at the root, then rebuilds each page according to that system. If the project already has design.md/DESIGN.md valid (not the copy document was just banned at step 3) and the user wants to KEEP that system instead of writing a new one, state that clearly in the brief.
Re-scan + compare — on each redesigned view, THREE layers (no layer can replace another): a. hallmark self-score the slop-test (six-axes pre-emit + 58 gate, already run in Build of step 4). b. /impeccable audit <view> (P0–P3: a11y, perf, theming, responsive, anti-pattern) and /impeccable critique <view> (hierarchy, IA, cognitive load). c. /qc-uiux <view> (the app must be running — <base-url> such as playwright-verify) — senior verdict 4 items (accessibility · visual-hierarchy · consistency · antipattern), the MEASURABLE part (WCAG contrast, tap-target, geometric overlap/misalign) runs deterministically via the visual-qa engine (measures real rects, does not read static CSS) → PASS or NEEDS FIXING conclusion. Re-capture (after) with playwright-verify, placed next to the before image from step 2 — this is the evidence of "better", not a mere score.

Fix loop — if there are still P0/P1 findings, the slop-test gate fails, or /qc-uiux concludes NEEDS FIXING → fix with the right command, do not go back to redesigning from scratch:

Finding type	Fix with
a11y (contrast, tap-target, missing label)	`/impeccable harden <view>`
performance (load, render, animation)	`/impeccable optimize <view>`
theming (token drift between views)	`/impeccable polish <view>` — or go back to `hallmark audit <view>` if the whole system drifts
responsive (breakpoint, touch area)	`/impeccable adapt <view> <context>`
anti-pattern / cognitive load / messy IA	`/impeccable distill <view>` or `clarify <view>` (copy)
a specific slop-test gate fails	fix directly according to that gate in `hallmark/references/slop-test.md`, no need for `/impeccable`
`qc-uiux` visual-hierarchy/consistency (LLM's eye, not measurable)	`/impeccable distill`/`polish <view>` according to the right item — `qc-uiux` only for the MOST SEVERE error + how to fix, does not fix by itself
`qc-uiux` MEASURABLE a11y/antipattern (engine `visual-qa`: contrast/tap-target/overlap/misalign)	duplicates the a11y/anti-pattern row above — the same error, two tools both catch it

Re-run step 5 after each fix loop. Maximum 2 loops. If findings remain after loop 2 → state clearly in the final report as known limitation, do not repeat infinitely.

Branches

ID	Kind	Guard	Behavior	Skip / failure	Rejoin
B01	recovery	`impeccable` already installed globally (not project)	uninstall/reinstall the correct scope before step 3 (RULE-04)	—	W04
B02	user_optional	project has `design.md`/`DESIGN.md` valid (not a version `document`) and the user wants to KEEP	state clearly in the redesign brief to keep that system	—	W06
B03	recovery	still has P0/P1 findings, the slop-test gate fails, or `/qc-uiux` NEEDS FIXING	patch according to the table in step 6, re-run step 5	more than 2 rounds → known limitation	W06

Validation and stopping

Three independent measurement layers (slop-test 58 gate, /impeccable audit+critique, /qc-uiux with the part measured via engine visual-qa); no layer replaces another. The final evidence is the before/after image pair. Stop when clean or after 2 patch rounds.

Examples

Positive: "/design-prim" on a 6-route admin project → impeccable already exists (skip step 0) → before images of 6 views → PRODUCT.md → hallmark redesign produces design.md new → round 1 /qc-uiux reports contrast fail in 1 view → /impeccable harden <view> → round 2 PASS, report with before/after images.
Boundary/failure: agent calls /impeccable document at step 3 and only then redesigns → design.md locks in exactly the old slop tokens, the page "runs to completion without looking better" → violates a recorded trap, discard DESIGN.md that and re-run from step 3 using /impeccable init.