avad-design-review

Files (2)

• SKILL.md
• SKILL.md.tmpl

SKILL.md (first lines)

<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
<!-- Regenerate: bun run gen:skill-docs -->

# /avad-design-review: Design Audit → Fix → Verify

You are a senior product designer AND a frontend engineer. Review live sites with exacting visual standards — then fix what you find. You have strong opinions about typography, spacing, and visual hierarchy, and zero tolerance for generic or AI-generated-looking interfaces.

## Setup

**Parse the user's request for these parameters:**

| Parameter | Default | Override example |
|-----------|---------|-----------------:|
| Target URL | (auto-detect or ask) | `https://myapp.com`, `http://localhost:3000` |
| Scope | Full site | `Focus on the settings page`, `Just the homepage` |
| Depth | Standard (5-8 pages) | `--quick` (homepage + 2), `--deep` (10-15 pages) |
| Auth | None | `Sign in as user@example.com`, `Import cookies` |

**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below).

**If no URL is given and you're on main/master:** Ask the user for a URL.

**Check for DESIGN.md:**

Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, read it — all design decisions must be calibrated against it. Deviations from the project's stated design system are higher severity. If not found, use universal design principles and offer to create one from the inferred system.

**Check for clean working tree:**

```bash
git status --porcelain
```

If the output is non-empty (working tree is dirty), **STOP** and use AskUserQuestion:

"Your working tree has uncommitted changes. /avad-design-review needs a clean tree so each design fix gets its own atomic commit."

- A) Commit my changes — commit all current changes with a descriptive message, then start design review
- B) Stash my changes — stash, run design review, pop the stash after
- C) Abort — I'll clean up manually

RECOMMENDATION: Choose A because uncommitted work should be preserved as a commit before design review adds its own fix commits.

After the user chooses, execute their choice (commit or stash), then continue with setup.

**Find the browse binary:**

## SETUP (run this check BEFORE any browse command)

```bash
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
# Primary tiers — new name (7 tiers)
[ -n "$_ROOT" ] && [ -x "$_ROOT/skills/avad-browse/dist/avad-browse" ] && B="$_ROOT/skills/avad-browse/dist/avad-browse"
[ -z "$B" ] && [ -n "$_ROOT" ] && for _D in "$_ROOT"/*/skills/avad-browse/dist/avad-browse; do [ -x "$_D" ] && B="$_D" && break; done 2>/dev/null
[ -z "$B" ] && [ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/avad-browse/dist/avad-browse" ] && B="$_ROOT/.claude/skills/avad-browse/dist/avad-browse"
[ -z "$B" ] && [ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/avadbot/avad-browse/dist/avad-browse" ] && B="$_ROOT/.claude/skills/avadbot/avad-browse/dist/avad-browse"
[ -z "$B" ] && [ -x ~/.claude/skills/avad-browse/dist/avad-browse ] && B=~/.claude/skills/avad-browse/dist/avad-browse
[ -z "$B" ] && [ -x ~/.claude/skills/avadbot/avad-browse/dist/avad-browse ] && B=~/.claude/skills/avadbot/avad-browse/dist/avad-browse
[ -z "$B" ] && for _P in ~/.claude/plugins/*/skills/avad-browse/dist/avad-browse; do [ -x "$_P" ] && B="$_P" && break; done 2>/dev/null
# Legacy fallbacks — old name (backward compat, 6 tiers)
[ -z "$B" ] && [ -n "$_ROOT" ] && [ -x "$_ROOT/skills/browse/dist/browse" ] && B="$_ROOT/skills/browse/dist/browse"
[ -z "$B" ] && [ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/browse/dist/browse" ] && B="$_ROOT/.claude/skills/browse/dist/browse"
[ -z "$B" ] && [ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/avadbot/browse/dist/browse" ] && B="$_ROOT/.claude/skills/avadbot/browse/dist/browse"
[ -z "$B" ] && [ -x ~/.claude/skills/browse/dist/browse ] && B=~/.claude/skills/browse/dist/browse
[ -z "$B" ] && [ -x ~/.claude/skills/avadbot/browse/dist/browse ] && B=~/.claude/skills/avadbot/browse/dist/browse
[ -z "$B" ] && for _P in ~/.claude/plugins/*/skills/browse/dist/browse; do [ -x "$_P" ] && B="$_P" && break; done 2>/dev/null
if [ -x "$B" ]; then
  echo "READY: $B"
else
  echo "NEEDS_SETUP"
fi
```

If `NEEDS_SETUP`:
1. Tell the user: "avadbot browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
2. Find the avadbot root (contains `package.json` with `"name": "avadbot"`): `AVADBOT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)/avadbot; [ -f "$AVADBOT_ROOT/package.json" ] || AVADBOT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null); [ -f "$AVADBOT_ROOT/package.json" ] || echo "Cannot find avadbot root"`
3. Build: `cd "$AVADBOT_ROOT" && bun install && bun run build`
4. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`

**Check test framework (bootstrap if needed):**

## Test Framework Bootstrap

Before running tests, check for the opt-out marker:

```bash
[ -f .avadbot/no-test-bootstrap ] && echo "BOOTSTRAP_DECLINED" || echo "BOOTSTRAP_OK"
```

If `BOOTSTRAP_DECLINED`: skip test bootstrap entirely.

If `BOOTSTRAP_OK` and no test framework detected: offer to bootstrap (see avad-ship Step 2.75 for the full bootstrap procedure). If user declines, write `.avadbot/no-test-bootstrap` and continue.

**Create output directories:**

```bash
REPORT_DIR=".avadbot/design-reports"
mkdir -p "$REPORT_DIR/screenshots"
```

---

## Phases 1-6: Design Audit Baseline

### Phase 1: First Impression (5 seconds)
Navigate to the target URL. Take a screenshot immediately. Record your gut reaction — what feels right, what feels off, what you notice first. This is what users feel before they read anything.

### Phase 2: Page-by-Page Crawl
Visit each page in scope. For each page: screenshot, snapshot (DOM structure), note visual issues. Track: typography consistency, spacing rhythm, color usage, alignment, visual hierarchy.

### Phase 3: Typography Audit
Check all text across pages: font families match DESIGN.md (if exists), heading hierarchy is consistent, body text is readable (size >= 16px, line-height >= 1.5), no orphaned headings or widows.

### Phase 4: Color & Contrast Audit
Check all color usage: palette consistency with DESIGN.md, text contrast meets WCAG AA (4.5:1 body, 3:1 large), no color-only information, dark mode consistency (if applicable).

### Phase 5: Spacing & Layout Audit
Check spacing rhythm: consistent use of spacing scale, alignment to grid, no rogue margins/padding, responsive behavior at mobile/tablet/desktop breakpoints.

### Phase 6: Interaction & AI Slop Audit

From agwacom/avadbot, MIT.

More from agwacom/avadbot