agentleFS
igovetigovet/cortex-orch-acp/skills/design-visual-qa/SKILL.md

design-visual-qa

Skill1 starsChanged 59 days agoMITView on GitHub

Visual QA of a rendered interface at desktop and mobile widths. Judges composition, typography, spacing, wrapping, clipping, states and journeys from opened screenshots and exercised interactions, with an evidence-level completion gate. Use after a UI is rendered; audit-only unless a fix is explicitly requested.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to judge an interface that is already rendered: what a person would actually see at the sizes they use, in the states they …

    line 8
  2. Very specific:

    Read the packaged references/defect-checklist.md through Cortex read_skill with the registered id design-defect-checklist, and the banned …

    line 17
  3. Distinctive:

    Before judging, write down:

    line 36
  4. Distinctive:

    Use the weakest level that answers the question, and say which level each finding rests on:

    line 47
  5. Distinctive:

    Call the current render verified only when all of these hold:

    line 84
  6. Distinctive:

    every screenshot cited in the report was opened and inspected.

    line 87
  7. Distinctive:

    no unresolved blocker or major finding contradicts the pass.

    line 90
  8. Very specific:

    every explicit requirement in the brief or DESIGN.md was checked, including information necessity when density or layout is in scope.

    line 91
  9. Distinctive:

    If no capture tool is available in this session, the result is blocked for any claim about the rendered result.

    line 98
  10. Distinctive:

    Do not produce a score such as "9/10" as proof of visual quality.

    line 103

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Visual QA

Use this skill to judge an interface that is already rendered: what a person would actually see at the sizes they use, in the states they reach. Build success, a passing unit test and the presence of DOM nodes are supporting signals only.

Adapted for Cortex from the MIT-licensed frontend-visual-qa skill (see LICENSE, references/defect-checklist.md and CORTEX-SOURCE.md). Tool-bound steps of the upstream skill are replaced by the Cortex roles below.

Read the packaged references/defect-checklist.md through Cortex read_skill with the registered id design-defect-checklist, and the banned AI-tell patterns with the id design-banned-patterns, not as target-project files.

Roles in the review

  • Capture (write role, such as frontend_dev or qa_engineer): produces the screenshots and state captures inside the project, at least at desktop and a phone width, and reports their paths and the state each one shows.
  • Review (read-only role, such as ux_designer or accessibility_auditor): opens each cited screenshot with the image-capable read tool and writes the findings. A read-only role does not create or edit files.

Audit-only is the default. Do not edit implementation, add tests, change snapshots or rebuild a target unless the assignment explicitly asks for a fix. A fix is then rechecked against the same target, state and viewport.

Audit contract

Before judging, write down:

  • the artifact and the actor, and the job the actor is trying to do;
  • the target and its state (route, data, logged-in or not, theme);
  • the viewports: at least desktop and a phone width;
  • the journeys and states in scope (loading, empty, error, success, long content);
  • the reference the design should match, if one exists (DESIGN.md, a brief or a named screenshot), and what is out of scope.

Evidence levels

Use the weakest level that answers the question, and say which level each finding rests on:

  1. Static observation: an opened screenshot. It supports visual observations only, such as composition, clipping and wrapping that is visible.
  2. Measured observation: a geometry or DOM measurement tied to the element in the screenshot. Use it to confirm a specific claim such as overflow, overlap or a target size.
  3. Exercised behavior: the interaction was performed and the resulting state was captured. Use it for focus order, menus, forms, transitions and outputs.

A screenshot that was never opened has no evidence value. A visible control is not proof that it works. A claim about data, copy correctness or domain facts needs the matching subject-matter review; a rendering pass cannot certify it.

Procedure

  1. Establish the audit contract above.
  2. Choose the evidence level for each question.
  3. Prove the target, state and viewport: the captured file and the state it shows.
  4. Capture and open the macro view (whole page or window) first, then the local regions with disputed details, then the responsive widths.
  5. Exercise affected journeys and their outputs (downloads, dialogs, copies), including keyboard-only traversal.
  6. Report findings, the checks that ran, and what remains unverified. Re-run the affected states after any authorized fix.

For each finding, record: the observable symptom, the region, the viewport, the state, the impact on the actor, and how to reproduce it. Use the defect catalog in design-defect-checklist for the usual defect families, including banned one-sided accent stripes and decorative leading-dot/meta-chip patterns (clipping, orphan lines, dense-item collisions, broken images, focus obstruction, repeated-card density) and its triage table for the evidence each one needs.

Completion gate

Call the current render verified only when all of these hold:

  • the target, data and actor state are established;
  • every screenshot cited in the report was opened and inspected;
  • the relevant viewports and the lower sections of the page were covered;
  • the affected interactions and outputs were exercised at the required level;
  • no unresolved blocker or major finding contradicts the pass;
  • every explicit requirement in the brief or DESIGN.md was checked, including information necessity when density or layout is in scope;
  • remaining limitations are stated.

Otherwise report partial or blocked. A fix is verified only after it is rechecked against the same target, state and viewport.

If no capture tool is available in this session, the result is blocked for any claim about the rendered result. Say so; do not infer the look from source.

No self-scoring as evidence

Do not produce a score such as "9/10" as proof of visual quality. Findings, opened screenshots and re-checks are the evidence. A finding labeled as taste or minor does not override a requirement the user stated.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.