# Qa

> Visual + a11y QA — screenshot-first critique, contrast, touch targets, mockup-vs-impl diff. For adversarial logic checks use `/verify`. Triggers "visual QA", "QA check", "does this look right", "a11y check", "contrast check", post-component changes.

- **Type:** Skill
- **Install:** `agentstack add skill-darkroomengineering-cc-settings-qa`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [darkroomengineering](https://agentstack.voostack.com/s/darkroomengineering)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [darkroomengineering](https://github.com/darkroomengineering)
- **Source:** https://github.com/darkroomengineering/cc-settings/tree/main/skills/qa

## Install

```sh
agentstack add skill-darkroomengineering-cc-settings-qa
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Visual QA Validation

## Core Philosophy

- **Screenshot first, then critique.** Always look at the actual rendered output, not just the code.
- **Be specific.** "The spacing looks off" is useless. "The gap between the heading and paragraph is 32px but should be 16px based on the surrounding spacing rhythm" is useful.
- **Prioritize impact.** Not every pixel matters. Focus on what users will actually notice.
- **Reference the intent.** Compare against design tokens, mockups, or stated design goals.

## Quick Start

The Chrome DevTools MCP exposes browser automation as tool calls. Typical sequence:

1. `mcp__chrome-devtools__navigate_page` (type: "url", url: "http://localhost:3000") — load the page
2. `mcp__chrome-devtools__take_snapshot` — text-based a11y tree with element `uid`s (cheap, preferred first step)
3. `mcp__chrome-devtools__take_screenshot` — visual capture for review
4. Interact via `click` / `fill` / `hover` / `press_key` using the `uid`s from the snapshot

---

## Review Categories (Priority Order)

### 1. Layout & Spacing

**Check for:**
- Consistent spacing rhythm (is everything on the spacing grid?)
- Alignment -- are elements that should be aligned actually aligned?
- Padding consistency within similar components
- Container widths and max-widths
- No horizontal overflow
- Responsive behavior (if multiple viewport screenshots available)

**Common issues:**
- Inconsistent padding in cards (e.g., 24px top, 16px sides)
- Elements slightly off-grid (15px instead of 16px)
- Text not aligned with adjacent elements
- Sections with wildly different vertical spacing

### 2. Typography

**Check for:**
- Hierarchy -- is it clear what's a heading vs body vs caption?
- Line length -- body text should be 45-75 characters per line
- Line height -- too tight or too loose for the font size?
- Font weight usage -- are weights used consistently for the same role?
- Heading hierarchy is correct (h1 > h2 > h3)
- Orphans/widows -- single words on their own line in headings

**Common issues:**
- Heading that doesn't look like a heading (weight/size too close to body)
- Body text line length > 80 characters (hard to read)
- Inconsistent heading sizes across sections
- All-caps text without letter-spacing adjustment

### 3. Color & Contrast

**Check for:**
- Text meets 4.5:1 contrast ratio
- UI elements meet 3:1 contrast ratio
- Consistent use of brand colors
- Color meaning consistency (is the same blue used for links AND errors?)
- Dark mode issues (if applicable)
- Hover/active state visibility
- UI elements are distinguishable

**Common issues:**
- Light gray text on white background (contrast fail)
- Primary color used for too many different purposes
- Borders that are nearly invisible
- Status colors that conflict (green for danger, red for success)

### 4. Visual Hierarchy

**Check for:**
- Eye flow -- where does the eye go first? Is that correct?
- CTA prominence -- is the primary action the most visible element?
- Information density -- too sparse or too crowded?
- Grouping -- are related items visually grouped?
- White space -- is it used intentionally or just leftover?

**Common issues:**
- Two equally prominent CTAs competing for attention
- Important information buried below less important elements
- Sections that feel disconnected from each other
- Dense walls of text without visual breaks

### 5. Component Quality

**Check for:**
- Button sizing and padding consistency
- Input field styling consistency
- Card styling consistency (shadows, borders, radius)
- Icon sizing and alignment with text
- Image aspect ratios and cropping

**Common issues:**
- Buttons with inconsistent padding or height
- Mixed border-radius values (some 8px, some 12px, some 4px)
- Icons misaligned with adjacent text baselines
- Images stretched or poorly cropped

### 6. Accessibility

- [ ] All images have `alt` text
- [ ] Icon-only buttons have `aria-label`
- [ ] Form inputs have labels
- [ ] Heading hierarchy is correct
- [ ] Focus order is logical
- [ ] Interactive elements >= 44x44px
- [ ] Adequate spacing between touch targets
- [ ] Focus indicators present (no `outline: none` without replacement)

### 7. Polish & Micro-details

**Check for:**
- Hover states exist and are visible
- Focus states for keyboard navigation
- Loading states (skeleton screens, spinners)
- Empty states (what shows when there's no data?)
- Transitions between states (abrupt vs smooth)
- Error states are clear

**Common issues:**
- No hover state on interactive elements
- Focus ring removed with no replacement
- Abrupt content shifts when data loads
- No empty state -- just a blank area

### 8. Responsive Issues

**Check for:**
- Content readable on mobile (not too small)
- Touch targets >= 44px on mobile
- Navigation accessible on small screens
- Images not overflowing containers
- Horizontal scroll (almost always a bug)

Use `mcp__chrome-devtools__resize_page` to switch between desktop (1440×900), tablet (768×1024), and mobile (375×667) viewports.

---

## Workflow

1. **Navigate** to target URL
2. **Snapshot** the a11y tree (text-based, returns `uid`s for interactive elements)
3. **Screenshot** the current state
4. **Analyze** against the review categories above
5. **Score** using the output format below
6. **Report** issues with actionable fixes

### After Building a Component

1. Render the component in the browser
2. Take a screenshot
3. Run visual QA review
4. Fix issues
5. Re-screenshot and verify

### After Building a Full Page

1. Screenshot at desktop (1440px), tablet (768px), and mobile (375px) — use `resize_page` between captures
2. Run responsive review across all three
3. Run full review on the desktop version
4. Fix issues, prioritizing critical ones

### Comparing to a Mockup

1. Get the mockup image:
   - **From Figma (preferred):** Use the Figma MCP directly — `mcp__figma__get_design_context` returns structured design specs (tokens, dimensions, component props) instead of pixel-pushing screenshots. The MCP server's own instructions cover URL parsing and the design-to-code workflow.
   - **Manual:** Figma export, screenshot, or user-provided image
2. Screenshot the implementation at the same viewport size
3. Run comparison review
4. Fix deviations by priority

---

## Tool Cheat-Sheet

| Action | Tool |
|---|---|
| Load a URL | `mcp__chrome-devtools__navigate_page` `{ type: "url", url }` |
| Text a11y tree with `uid`s (cheap) | `mcp__chrome-devtools__take_snapshot` |
| Screenshot | `mcp__chrome-devtools__take_screenshot` |
| Click an element | `mcp__chrome-devtools__click` `{ uid }` |
| Fill input / select option | `mcp__chrome-devtools__fill` `{ uid, value }` |
| Hover an element | `mcp__chrome-devtools__hover` `{ uid }` |
| Press key (Enter, Tab, Escape, …) | `mcp__chrome-devtools__press_key` `{ key }` |
| Resize viewport | `mcp__chrome-devtools__resize_page` `{ width, height }` |
| Run JS in page | `mcp__chrome-devtools__evaluate_script` |

---

## Output Formats

### Full Review

```
## QA Report: [Page/Component]

**Overall impression:** [One sentence -- first gut reaction]
**Quality score:** [1-10] / 10

### Critical Issues (fix before shipping)
1. **[Category]:** [Specific issue with exact details]
   -> **Fix:** [Actionable recommendation]

### Improvements (should fix)
1. **[Category]:** [Specific issue]
   -> **Fix:** [Recommendation]

### Minor Polish (nice to fix)
1. **[Category]:** [Specific issue]
   -> **Fix:** [Recommendation]

### What's Working Well
- [Specific praise -- what's well-executed]
- [Another positive]

### Passed Checks
- [x] Touch targets adequate
- [x] Heading hierarchy correct

### Issues Found
- [ ] Missing alt text on hero image
  -> Add alt="..." to components/hero/index.tsx:15

- [ ] Contrast too low on muted text
  -> Change text-gray-400 to text-gray-500

### Recommendations
- Consider adding loading skeleton for async content
```

### Quick Review

```
## Quick QA: [Page/Component Name]

Score: [X]/10

Top 3 fixes:
1. [Most impactful issue + fix]
2. [Second issue + fix]
3. [Third issue + fix]

Looks good: [What's working]
```

### Comparison Review (Implementation vs Mockup)

```
## Design vs Implementation Review

**Fidelity score:** [1-10] / 10

### Deviations Found
1. **[Element]:** Mockup shows [X], implementation has [Y]
   Impact: [High/Medium/Low]
   -> **Fix:** [How to match the mockup]

### Matching Well
- [Elements that accurately match the design]
```

---

## Prerequisites

Requires the `chrome-devtools` MCP server (shipped in `mcp-configs/recommended.json` and installed by `setup.sh`).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [darkroomengineering](https://github.com/darkroomengineering)
- **Source:** [darkroomengineering/cc-settings](https://github.com/darkroomengineering/cc-settings)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-darkroomengineering-cc-settings-qa
- Seller: https://agentstack.voostack.com/s/darkroomengineering
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.