dvy1987/agent-loom / .agents/skills/design-review
design-review
VerifiedReview a built frontend against its chosen direction, catch drift back to generic AI defaults, enforce state coverage, ethical patterns, UX heuristics, and polish, and check contrast with APCA (not the legacy WCAG ratio). Produces specific, prioritized fixes — never vibes-based feedback. Works with pasted screenshots or Playwright MCP automated capture. Load when the user asks to review a UI, audit a design, check if a frontend looks generic or vibecoded, evaluate visual quality or polish, says "review this UI", "is this design good", "audit my frontend", "does this feel like [product]", "design QA", or when frontend-design routes here. Sub-skill of frontend-design.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| references/apca-contrast.md | markdown | 2.0 KB |
| references/ethical-patterns.md | markdown | 1.7 KB |
| references/examples.md | markdown | 1.8 KB |
| references/playwright-flow.md | markdown | 3.1 KB |
| references/review-rubric.md | markdown | 5.8 KB |
| references/ux-heuristics.md | markdown | 1.8 KB |
| scripts/apca.mjs | script | 2.5 KB |
references/apca-contrast.md
View on GitHub# APCA Contrast — Measure, Don't Eyeball
Use APCA (perceptual) instead of the legacy WCAG 2.x ratio. WCAG misjudges dark themes and
thin type; APCA models real readability. This is a HARD GATE in review.
## Targets (`Lc`, absolute value)
| Content | Min Lc |
|---|---|
| Body text (normal weight, ≤18px) | 75 |
| Large or bold text (≥24px or ≥18px bold) | 45 |
| Non-text UI (icons, borders, focus rings, disabled affordances) | 30 |
Polarity: dark-on-light gives positive Lc, light-on-dark gives negative — compare the
absolute value to the target.
## How to run
The script lives at `scripts/apca.mjs` (Node, no deps).
Single pair:
```bash
node .agents/skills/design-review/scripts/apca.mjs "#1A1A1A" "#FAFAF7"
# -> Lc 101.1 (text on bg)
```
Batch — build a `pairs.json` from the DESIGN.md token table and check all at once:
```json
[
{ "name": "body", "text": "#1A1A1A", "bg": "#FAFAF7", "min": 75 },
{ "name": "secondary text", "text": "#5A5A5A", "bg": "#FAFAF7", "min": 75 },
{ "name": "text-on-accent", "text": "#FFFFFF", "bg": "#4338CA", "min": 75 },
{ "name": "border", "text": "#D8D6CF", "bg": "#FAFAF7", "min": 30 },
{ "name": "body (dark mode)","text": "#ECECEC", "bg": "#141414", "min": 75 }
]
```
```bash
node .agents/skills/design-review/scripts/apca.mjs --check pairs.json
# PASS/FAIL per pair; non-zero exit if any fail
```
## What to check (every review)
- Every text/background pair from the DESIGN.md color table — BOTH light and dark mode.
- `text-on-accent` against the accent (the most-missed failure).
- Secondary/tertiary text (often fails at Lc 75).
- Non-text: borders, focus ring, disabled text, icon-only buttons (Lc ≥ 30).
## Fixing failures
- Shift the text or surface lightness until the pair clears the target.
- Text over images/gradients: add a semi-transparent overlay so the worst-case pair clears.
- Do NOT lower the target. If a brand accent can't carry white text at Lc 75, darken the
accent or use dark text on it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |