UI Audit

Precondition. Tool of dept-ux-ui (supporting: dept-qa, which runs it in the Definition of Done of significant UI changes). If that department skill is not loaded in this conversation, load it first and use its brief (what, why, where, how) as the input of this skill. Skip only for L0 edits.

Approach

An audit produces evidence, not opinions. Every finding names a rule, a location and a fix; a concern that maps to no rule is a note for ui-refine, not a finding.

• Local, versioned rules. The rule set lives in rules/ (no network fetch) and grows from real audits.
• Report before touching. audit never edits. Only findings the user approved are fixed.
• Severity decides order. Critical and serious first; twenty minor findings must not hide one blocker.
• A search hit is a candidate, not a finding. Confirm each hit in context: component libraries often supply roles, labels and focus handling that a pattern cannot see.
• Name the limits. Static review cannot prove computed contrast, focus order or screen-reader output; list what was not verified.
• Questions before acting: which files or diff? Which template and styling syntax? Which component library and what does it handle? Which themes? Which UI language?

Inputs

Severity

Each rule has a default severity. Raise it one level when the issue sits on a primary flow (sign-in, checkout, send, save); lower it only with a stated reason.

Growing the rule set

• A confirmed finding that matches no rule → novelty check: grep rules/ for the concept, its keywords and its WCAG criterion. Covered → reuse that id and, if its pattern missed the case, refine the Check. Not covered → append a rule to the right category file with the next free id and Added: <YYYY-MM-DD> · source: <project>; update the count in rules/README.md.
• A recurring false positive → tighten that rule's Check and note why.
• Never renumber. Retire a rule with Retired: <date> — <reason> so old reports stay readable.
• A category file beyond ~15 rules → split it and update the index.

Output contract

Always return: scope (file count), categories applied, findings table with totals by severity, the not-verified list, files changed (fix mode only), check re-run results, audit log updated (yes/no), rules added or refined, and hand-offs: ui-system for system-level token or contrast fixes, ui-refine for non-rule UX critique, dept-frontend for structural changes, dept-qa for automated accessibility tests.

Pattern library (grows with use)

• Before building, list patterns/ and read the matching file, if any. In this skill the reusable knowledge is the rule set in rules/; widget patterns (dialog, combobox, tabs) live in ui-build and are the reference for what a correct widget looks like.
• After building something reusable that has no pattern yet (a modal, a data table, a stepper…), write patterns/<pattern>.md from ../waymark/templates/pattern.template.md: stack-agnostic intent, anatomy, states, a11y, pitfalls, and one short adapter per stack it was built in. Project-specific details go to project memory, not here.
• Update an existing pattern only with new, verified information (novelty check, waymark references/learning.md).

Modes

Read only the mode the task needs (one file); never load all modes.

• audit — "audita la UI", "revisa la accesibilidad", "cumple WCAG", "revisa el formulario", before a PR with UI changes, dept-qa Definition of Done. → modes/audit.md
• fix — the user approved findings by number, rule id or severity. → modes/fix.md
• regression — after a fix round, before a release, "verifica que sigan corregidos". → modes/regression.md

Stack adapters

Stack-specific notes → references/stack-adapters.md (read only the project's stack row).

Learned notes

Grows with use (waymark references/learning.md). Dated, non-obvious notes about using this tool. When there are more than ~10, fold them into the body above and clear this list.