---
name: bigstack-david-design-review
version: 0.1.0
description: |
  Live site visual design audit. Opens the site in a headless browser,
  evaluates against design targets/mockups, and runs a fix loop for
  identified issues (max 30 fixes).
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - Edit
  - Write
  - AskUserQuestion
---
<!-- Auto-generated from SKILL.md.tmpl by bigstack. DO NOT EDIT. -->
<!-- Regenerate: npm run gen:skill-docs -->

<!-- bigstack v0.1.0 | skill: bigstack-david-design-review -->

> **bigstack v0.1.0** — skills for Bigscreen development.

Before starting, run this setup block silently:

```bash
# Session context
BIGSTACK_VERSION="0.1.0"
BIGSTACK_DIR="C:/Users/GGPC/Documents/Github/bigstack"
REPO_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "bigstack v$BIGSTACK_VERSION | repo: $REPO_NAME | branch: $BRANCH"
```

**Guidelines:**
- When asking the user a question, use AskUserQuestion (not inline text questions)
- When uncertain about a change, state your confidence level before proceeding
- Prefer modifying existing code over creating new files
- This is an existing codebase — understand before changing

# /bigstack-david-design-review — Visual Design Audit

Perform a visual design review of a live site or local dev server.

## Browser Setup

Before browsing, detect an available headless browser:

```bash
# Check for Playwright (preferred)
if npx playwright --version &>/dev/null; then
  BROWSE_ENGINE="playwright"
  echo "Using Playwright"
# Check for gstack's browse binary
elif [ -x "$HOME/.claude/skills/gstack/browse/dist/browse" ]; then
  BROWSE_ENGINE="gstack"
  echo "Using gstack browse binary"
else
  BROWSE_ENGINE="none"
  echo "WARNING: No headless browser found."
  echo "Install with: npx playwright install chromium"
fi
```

If `BROWSE_ENGINE` is `none`, inform the user and offer to install Playwright:
`npx playwright install chromium`

## Test Framework Detection

Detect the existing test setup silently:

```bash
TEST_CMD=""
TEST_FRAMEWORK=""

# Node.js / JavaScript / TypeScript
if [ -f "vitest.config.ts" ] || [ -f "vitest.config.js" ]; then
  TEST_FRAMEWORK="vitest"
  TEST_CMD="npx vitest run"
elif [ -f "jest.config.ts" ] || [ -f "jest.config.js" ] || [ -f "jest.config.mjs" ]; then
  TEST_FRAMEWORK="jest"
  TEST_CMD="npx jest"
elif grep -q '"test"' package.json 2>/dev/null; then
  TEST_FRAMEWORK="npm-script"
  TEST_CMD="npm test"
fi

# Python
if [ -f "pytest.ini" ] || [ -f "pyproject.toml" ] && grep -q "pytest" pyproject.toml 2>/dev/null; then
  TEST_FRAMEWORK="pytest"
  TEST_CMD="pytest"
elif [ -f "setup.cfg" ] && grep -q "tool:pytest" setup.cfg 2>/dev/null; then
  TEST_FRAMEWORK="pytest"
  TEST_CMD="pytest"
fi

# Go
if [ -f "go.mod" ]; then
  TEST_FRAMEWORK="go-test"
  TEST_CMD="go test ./..."
fi

# Rust
if [ -f "Cargo.toml" ]; then
  TEST_FRAMEWORK="cargo-test"
  TEST_CMD="cargo test"
fi

# .NET
if ls *.csproj &>/dev/null || ls *.sln &>/dev/null; then
  TEST_FRAMEWORK="dotnet-test"
  TEST_CMD="dotnet test"
fi

if [ -n "$TEST_FRAMEWORK" ]; then
  echo "Detected test framework: $TEST_FRAMEWORK"
  echo "Test command: $TEST_CMD"
else
  echo "WARNING: No test framework detected. Ask the user how to run tests."
fi
```

## Workflow

### Step 1: Target Identification

Ask the user:
1. What URL to review (production URL or local dev server)
2. Whether there's a design mockup/target to compare against
3. Which pages or flows to focus on

### Step 2: Capture Current State

Using the browser engine:
1. Navigate to the target URL
2. Capture screenshots at 3 breakpoints:
   - Mobile: 375px
   - Tablet: 768px
   - Desktop: 1280px
3. Capture any console errors or warnings

### Step 3: Design Assessment

Evaluate each dimension (rate 0-10):

| Dimension | What to Check |
|-----------|---------------|
| **Layout** | Alignment, spacing, grid consistency |
| **Typography** | Hierarchy, readability, font consistency |
| **Color** | Palette consistency, contrast, accessibility |
| **Interaction** | Hover states, transitions, feedback |
| **Responsiveness** | Breakpoint behavior, touch targets |
| **Visual polish** | Shadows, borders, micro-interactions |
| **Content** | Placeholder text, missing images, truncation |

### Step 4: Risk Heuristics

Flag high-risk issues:
- Anything that looks broken (not just suboptimal)
- Accessibility violations (contrast, focus, screen reader)
- Content that appears unintentionally truncated or hidden
- Layout shifts or flashing

### Step 5: Fix Loop (max 30 iterations)

For each identified issue, ordered by severity:
1. Identify the source file and CSS/component responsible
2. Propose a fix
3. Apply the fix
4. Re-capture the screenshot to verify
5. Move to the next issue

Stop after 30 fixes or when the user is satisfied.

### Step 6: Before/After Report

Present a summary:

| Issue | File | Severity | Status |
|-------|------|----------|--------|
| ... | ... | ... | Fixed / Flagged |

Include before/after screenshots where available.

## Confidence Calibration

Before completing a major action, state your confidence:

| Level | Meaning | Action |
|-------|---------|--------|
| **High** | Well-understood change, clear test coverage, matches existing patterns | Proceed |
| **Medium** | Reasonable approach but some uncertainty — unfamiliar area, partial test coverage | Proceed but flag risks |
| **Low** | Significant unknowns, could break existing behavior, no test coverage | Stop and ask the user |

Format: **Confidence: [High/Medium/Low]** — [one-line rationale]