review-design — evaluate a user-visible artifact
Judge whether the audience can understand, engage with and use the artifact as intended, including its purpose-led visual ambition. Review only: you find and explain, the author decides and edits. You never repair the artifact; applying fixes after the report is a separate request for the invoking workflow. When invoked as a gate, record the actual basis of your judgment; this skill does not change how the run verifies. For a standalone review of work you produced, use a fresh context when available; otherwise disclose self-review and apply the same evidence bar.
Input
$ARGUMENTS carries what to review — a file path, a directory, a URL, or a running app plus how to reach it. It may name the genre explicitly (genre=dashboard, genre=deck) to override detection. A manifest gate's body activates this skill under the run's selected evaluator; the gate may name the genre and any pinned references — mocks, examples, or criteria the author fixed during definition, which the evaluation then judges against.
With no argument, review the most recently modified user-visible artifact in the working tree and say which one you picked. If that is ambiguous, ask what to review rather than guessing — or, when running as a gate evaluator with no user to ask, return BLOCKED naming the ambiguity.
Rendered evidence or BLOCKED
A verdict from source inspection alone is not a complete design evaluation. Inspect the delivered artifact in its intended browser, native host, player or device and exercise relevant behavior. Responsive web viewports are starting points, not a requirement to turn every file into a website. For audio, commands or conversation, use playback or interaction evidence; a screenshot is not required for a nonvisual property. Check supported themes, inputs, access and relevant states. If a required property cannot be inspected with available capabilities, return BLOCKED for that scope and name what would enable verification; do not clear it through a proxy preview. Source inspection can locate causes and establish properties such as semantic structure.
Standards
Use ../design/SKILL.md for audience-centered art direction. Treat it as guidance beneath the brief and established design system, not a style-conformance gate. Every shipped standard here is an opinionated default: where a rule the user stated, in the session or a context file, or the project's own documented design system differs, that rule governs, an artifact following it raises no finding, and the report names the rule applied; the one limit is the critical-failure rule under Procedure, and such a finding names the rule that produced it. If the companion skill is absent, judge against the supplied brief and references without inventing its defaults.
This evaluator owns the conditional standards below. Load those the artifact's medium and touched domains call for:
| When reviewing | Read |
|---|---|
| Web access and interaction | references/floors.md — requirements, exceptions and behavioral checks |
| Structural or quantitative information and information graphics | references/figures.md — faithful encoding and equivalent access |
| Stateful or shared work, multi-page journeys, presentations, non-web or unfamiliar media | references/experience.md — continuity, consequences and actual-medium evidence |
Procedure
- Name the genre and use context you are judging against, in one line, before any finding — a finding graded for the wrong use is noise the author should ignore. An explicit
genre=argument wins; otherwise detect from the artifact's job, and where detection is genuinely balanced, say so and ask — with no user to ask, judge under the closer use context and name the call in the report. - Recover the intended result and work from the supplied brief, evidence and requirements before judging the artifact. Name the audience, their relevant path or loop and the information needed together. If intent is unavailable, distinguish what can be assessed from unverified purpose fit. The artifact can reveal its apparent operation; that does not establish that it serves the intended outcome. Do not invent a goal and convict against it.
- Run applicable checks. Use established project tooling and, for HTML,
node scripts/design-check.mjs <artifact.html>from this skill's directory. Exit zero means completed, not clean. Validate measured candidates and NOTE items against the actual artifact and applicable exceptions before grading; SKIPPED properties remain unverified. Neither selector presence nor a heuristic count establishes a requirement violation or pass. - Render and exercise per the section above. Run the loop from step 2 yourself, twice, and watch what each pass costs. Use the intended result to select the observation; delivery probes in the loaded standards are starting examples.
- For improvements, compare with the incumbent under matched content, state, output size and useful fidelity. Identify gains and losses in the actual task and visual expression, preserving successful identity and behavior. If the original is unavailable, state that limit rather than claim superiority.
- Judge the renders against the loaded standards, in this order: task fit — whether the arrangement lets that loop run, with what the loop needs together visible together, the repeated action reachable without hunting, and the sequence's order matching the reading order, and whether the chosen representation serves the information or experience under the encoding guidance in
references/figures.md; fitness for the use context; functional floors (states, error paths, recovery); composition and hierarchy — blur or shrink each key render and check that what the eye lands on first, and the path it follows from there, is what the person's moment needs, with nothing secondary competing, using other visual probes as judgment aids; craft consistency (grouping, alignment, color roles, typography); copy; visual impact and creative direction — whether the composition, typography, color, imagery, material, interaction and motion make the artifact compelling in a way that serves its purpose and subject. Apply this to every genre, within the user's requirements and existing design system; mechanical correctness alone does not establish finished design. Judge the whole encounter as well as its parts: where relationships become clear, where emphasis competes, and where explanation adds meaning or merely repeats it. Inspect beyond the strongest frame, including active use, endings and return; compare motion with its still or reduced alternative where relevant. Distinguish design judgment from measured audience understanding, recall or preference.
Task fit comes first because it is the one dimension whose repair restructures the artifact: every finding below it is graded against an arrangement that may not survive. An unfamiliar layout that runs the loop cleanly is not a finding.
Judge against the artifact's job and its chosen direction, never against the arrangement or style you would have chosen; a deviation from a numerical or stylistic default is not itself a finding. Name the applicable requirement or the observed task consequence; standards retain their levels and exceptions. Neither a stated rule nor a preference cancels a critical functional or access failure.
A finding about visual ambition must point to what the render leaves unresolved — for example, an interchangeable composition that gives the subject no visual expression, or a treatment whose competing effects obscure its central idea — and describe a concrete improvement within the brief. Familiar patterns, restrained styling, and required design-system components are not defects.
Grading
- CRITICAL — the artifact fails its genre's job: the form loses input on error, the deck's argument cannot be restated, content is unreachable or unreadable, the repeated loop cannot be completed at all.
- HIGH — a floor violation the audience will hit in normal use: a missing empty or error state, failed contrast on body text, a broken narrow-viewport layout, or an arrangement that breaks the loop's co-visibility so every pass costs a scroll away from what is being acted on or a value carried in the head, or a misleading or unsuitable representation that materially obscures information the task needs.
- MEDIUM — a supported defect a careful audience member would notice, rather than a different valid style choice: a region unsuited to its use, an unresolved creative direction supported by the rendered evidence above, grouping or alignment that obscures a relationship, inconsistent use of the governing design system, misleading copy on a control.
- LOW — a supported polish issue: awkward optical alignment, unnecessarily distracting timing or a wordier-than-needed label.
The threshold, unless the activating gate states its own: no MEDIUM-or-higher findings to PASS.
Reporting
Report each finding with:
- the severity and the rule area
- where it is — the element, screen, and state, with the screenshot or machine-check line that shows it
- what the standard requires, and why this instance fails it
- the concrete fix — the changed value or rule where one line is enough, the shape of the change where it isn't
Order findings by severity, then by position. A clean artifact is a real result: say so plainly, name the genre, use context, and references you applied, and stop. Never pad a report with marginal findings to look thorough. When the artifact has many instances of one pattern, report the pattern once with two or three examples and a count. Where a rule's application is a genuine judgment call, say that in the finding instead of grading it as a defect.
Scope, and what this is not
This skill evaluates finished or in-progress artifacts on request or under a manifest gate. The design skill supplies design guidance. It does not review prose style — a document's writing quality is the review-writing skill; this skill judges the same document's layout, hierarchy, typography, and reading structure.
