ui-ux-design-audit

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# UI/UX Design Audit

## Core Boundaries

Default to `audit-only`:

- Inspect, observe, score, verify, and report findings.
- Do not edit runtime/product code unless the user explicitly asks to fix the
  verified findings.
- Create or update a durable audit artifact only when the user asks for one;
  otherwise report in chat.
- Do not commit or archive artifacts without separate explicit authorization.

Use this skill for cross-surface design quality. Route a current diff/PR review
to `personal-assistant-review`, even when the diff is UI-heavy.

Read:

1. `AGENTS.md`
2. `docs/product/pa-product-north-star.md`
3. `docs/product/pa-low-burden-review-product-principles.md`
4. `docs/development/workflows/pa-ui-ux-review-framework.md`
5. The source files and tests for the audited surfaces

Reuse the current PA framework before inventing a new instrument. Treat its
four Layer A dimensions—Design Coherence, Visual Polish, Interaction Quality,
and Content Clarity—as a **PA adaptation**, not a verbatim external framework.
Research external frameworks only when the current instrument needs revision;
use authoritative sources and preserve citations for adapted claims.

## Evidence Standard

Separate evidence into three lanes:

| Lane | Can prove | Cannot prove alone |
| --- | --- | --- |
| Source and tests | State, lifecycle, copy, accessibility markup, CSS intent, product contract | Rendered visual quality or interaction feel |
| Runtime/DOM | Mounting, state transitions, computed structure, fresh console behavior | Visual polish or real user interaction by itself |
| Visible UI | Layout, hierarchy, contrast, clipping, focus, keyboard/touch flow, perceived burden | Hidden code paths not exercised |

Require `obsidian-test-vault-smoke` at `full-ui` tier before assigning visual or
interaction scores. Capture the visible path, interaction, observed state, and
screenshot evidence. If the app cannot be observed, mark those dimensions
`UNSCORED` or `BLOCKED`; do not infer a score from source code.

Use `obsidian-ios-real-device-smoke` for claims about real iOS touch behavior.
Do not generalize desktop evidence to mobile.

## Workflow

### 1. Bound the Audit

1. Confirm the requested surfaces, platforms, themes, and key user journeys.
2. Inventory views, panels, modals, overlays, commands, settings, and navigation
   transitions in scope.
3. Select only the framework dimensions relevant to the request.
4. Define the evidence needed for every score before auditing.

### 2. Observe and Score

1. Deploy and observe the real test-vault UI through
   `obsidian-test-vault-smoke` when visual or interaction scoring is requested.
2. Trace each visible issue to source, CSS, state, or product-contract evidence.
3. Score with the current PA framework. Use short evidence-backed rationales;
   do not manufacture numerical precision.
4. Check the North Star explicitly:
   - capture friction
   - right-time return
   - quietness and ignorable states
   - source-backed trust
   - reversible maintenance and earned action
   - net review burden

For layered surfaces, use Mermaid for topology or flow diagrams. Use a Markdown
table for the score heatmap.

### 3. Fan Out Broad Audits

If multi-agent tools are available and the audit is broad or the user asks for
an agent team, partition surfaces across independent agents. Give every agent
the same framework and different surfaces. If subagents are unavailable, run
the same partitions locally.

Require this schema from each lane:

```markdown
## Surface: <name>

### Evidence
- visible path and screenshot
- source/test anchors

### Scores
| Dimension | Score or UNSCORED | Evidence |
| --- | --- | --- |

### Findings
| Finding | Severity | Trigger | Suggested direction |
| --- | --- | --- | --- |
```

Add one cross-surface pass for terminology, design tokens, navigation,
progressive disclosure, accessibility, and desktop/mobile consistency.

### 4. Verify Findings

Verify every P0/P1/P2 finding against the actual source and the relevant visible
flow before presenting it as confirmed.

Classify each finding:

- `CONFIRMED`: the trigger and impact match the evidence
- `PARTIALLY CONFIRMED`: the issue exists but scope or severity changes
- `FALSE POSITIVE`: current source or observed behavior contradicts it
- `BLOCKED`: required runtime/device evidence is unavailable

Recalibrate severity after verification. Do not force findings per surface or
dimension.

From edonyzpc/personal-assistant, AGPL-3.0.

More from edonyzpc/personal-assistant