diff --git a/plugins/pixel-perfect/.factory-plugin/plugin.json b/plugins/pixel-perfect/.factory-plugin/plugin.json new file mode 100644 index 0000000..5540bd1 --- /dev/null +++ b/plugins/pixel-perfect/.factory-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "pixel-perfect", + "description": "Browser-native visual QA, design skills, and anti-pattern detection for frontend interfaces. Leverages real screenshots, Lighthouse audits, and multi-viewport testing to catch what code review can't.", + "version": "1.0.0", + "author": { + "name": "Factory", + "email": "support@factory.ai" + }, + "license": "Apache-2.0" +} diff --git a/plugins/pixel-perfect/LICENSE b/plugins/pixel-perfect/LICENSE new file mode 100644 index 0000000..3410f3a --- /dev/null +++ b/plugins/pixel-perfect/LICENSE @@ -0,0 +1,17 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + Copyright 2026 Factory AI + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/plugins/pixel-perfect/NOTICE.md b/plugins/pixel-perfect/NOTICE.md new file mode 100644 index 0000000..b5f4e7d --- /dev/null +++ b/plugins/pixel-perfect/NOTICE.md @@ -0,0 +1,26 @@ +# Notice + +Pixel Perfect +Copyright 2026 Factory AI + +## Derived Works + +The design reference files (typography, color-and-contrast, spatial-design, motion-design, +interaction-design, responsive-design, ux-writing) and critique heuristics references +are derived from: + +### Impeccable by Paul Bakaus +- **Source:** https://github.com/pbakaus/impeccable +- **License:** Apache License 2.0 +- **Copyright:** 2025 Paul Bakaus + +### Anthropic frontend-design Skill +- **Source:** https://github.com/anthropics/skills/tree/main/skills/frontend-design +- **License:** Apache License 2.0 +- **Copyright:** 2025 Anthropic, PBC + +## What's New in Pixel Perfect + +The skill definitions, browser-native commands (/visual-qa, /screenshot-diff), +and browser verification workflows are original work by Factory AI. The reference +documents above were retained as foundational design knowledge. diff --git a/plugins/pixel-perfect/README.md b/plugins/pixel-perfect/README.md new file mode 100644 index 0000000..7656612 --- /dev/null +++ b/plugins/pixel-perfect/README.md @@ -0,0 +1,150 @@ +# Pixel Perfect + +Browser-native visual QA, design skills, and anti-pattern detection for frontend interfaces. Uses real screenshots, live rendering, and multi-viewport testing to catch what code review can't. + +> Built for [Factory Droid](https://factory.ai) with `agent-browser` integration. Code review finds bugs in logic. Pixel Perfect finds bugs in pixels. + +## What Makes This Different + +Most design linting happens in code. Pixel Perfect opens a real browser, takes real screenshots, and tests what users actually see. A button can pass every linter and still have 2.1:1 contrast, a 28x18px touch target, and no focus ring -- invisible in code, obvious in a screenshot. + +## Commands + +### Browser-Native (New) + +#### `/visual-qa` - Real Rendered Inspection + +Opens the page in a real browser, screenshots at mobile/tablet/desktop, checks contrast ratios on rendered elements, measures touch targets, detects overflow, and tests focus indicators. Produces an annotated visual report. + +![/visual-qa](images/visual-qa.png) + +--- + +#### `/screenshot-diff` - Visual Regression Detection + +Takes before/after screenshots and produces a pixel diff. Catches unintended regressions at every viewport. Compare two URLs side-by-side or track changes across edits. + +![/screenshot-diff](images/screenshot-diff.png) + +--- + +### Design Skills + +#### `/audit` - Technical Quality Checks + +Scores accessibility, performance, theming, responsive design, and anti-patterns (0-20). Now includes browser verification: multi-viewport screenshots, rendered contrast checks, and ARIA scanning. + +![/audit](images/audit.png) + +--- + +#### `/critique` - UX Design Review + +Nielsen's 10 heuristics scoring (0-40) with screenshot-first analysis. Tests actual user flows via browser interaction, not hypothetical walkthroughs. + +![/critique](images/critique.png) + +--- + +#### `/polish` - Final Pass Before Shipping + +Pixel-perfect alignment, spacing rhythm, interaction state testing. Uses before/after screenshots and actually hovers, focuses, and clicks elements to verify every state. + +![/polish](images/polish.png) + +--- + +#### `/normalize` - Design System Alignment + +Scans for inconsistent tokens, screenshots components side-by-side, applies systematic fixes. Verifies visually that normalized components still look intentional. + +![/normalize](images/normalize.png) + +--- + +#### `/distill` - Strip to Essence + +Removes clutter, redundant elements, and noise. Verifies with before/after screenshots that nothing essential was lost. + +![/distill](images/distill.png) + +--- + +#### `/clarify` - Improve UX Copy + +Fixes vague errors, confusing labels, and wordy instructions. Reads actual rendered text in browser context. + +![/clarify](images/clarify.png) + +--- + +#### `/optimize` - Performance + +Measures real Core Web Vitals (LCP, FID, CLS), profiles runtime performance, checks image sizes and lazy loading. Before/after measurements. + +![/optimize](images/optimize.png) + +--- + +#### `/harden` - Error Handling & Edge Cases + +Tests with extreme inputs (long text, emoji, RTL), offline mode, slow networks, and bad form data -- all via real browser interaction. + +![/harden](images/harden.png) + +--- + +#### `/animate` - Motion Design + +Choreographed animations, micro-interactions, and celebration moments. Previews in browser, records demos, tests `prefers-reduced-motion`, verifies 60fps. + +![/animate](images/animate.png) + +--- + +#### `/colorize` - Strategic Color + +Transforms monochrome UIs with purposeful color. Checks contrast ratios on rendered elements and simulates colorblind vision. + +![/colorize](images/colorize.png) + +--- + +#### `/typeset` - Typography + +Fixes flat hierarchy, poor readability, and bad font choices. Verifies font rendering (no FOUT/FOIT) and line lengths in screenshots. + +![/typeset](images/typeset.png) + +--- + +#### `/adapt` - Responsive Design + +Screenshots at every breakpoint, tests touch targets, detects horizontal overflow, and verifies orientation changes -- all in a real browser. + +![/adapt](images/adapt.png) + +--- + +### The Skill: frontend-design + +The foundational skill loaded by all commands. Includes: +- Typography, color, layout, motion, interaction, responsive, and UX writing guidelines +- 7 domain-specific reference documents +- Curated anti-patterns (the "AI Slop Test") +- DO/DON'T patterns for every design dimension + +### Cut from Impeccable + +These commands were removed as redundant: +- `/delight` -- merged into `/animate` (celebration moments) +- `/bolder` + `/quieter` -- subjective taste toggles, covered by `/polish` +- `/arrange` -- spacing/rhythm work merged into `/polish` +- `/extract` -- design system extraction is a dev task +- `/teach-impeccable` -- replaced by `.pixel-perfect.md` config file +- `/overdrive` -- too niche +- `/onboard` -- too narrow + +## Attribution + +Apache 2.0. Design reference files derived from [Impeccable](https://github.com/pbakaus/impeccable) by Paul Bakaus and [Anthropic's frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design). Browser-native commands and skill rewrites are original work by Factory AI. See [NOTICE.md](NOTICE.md). diff --git a/plugins/pixel-perfect/images/adapt.png b/plugins/pixel-perfect/images/adapt.png new file mode 100644 index 0000000..4cf30d9 Binary files /dev/null and b/plugins/pixel-perfect/images/adapt.png differ diff --git a/plugins/pixel-perfect/images/animate.png b/plugins/pixel-perfect/images/animate.png new file mode 100644 index 0000000..c78ffb3 Binary files /dev/null and b/plugins/pixel-perfect/images/animate.png differ diff --git a/plugins/pixel-perfect/images/audit.png b/plugins/pixel-perfect/images/audit.png new file mode 100644 index 0000000..1732413 Binary files /dev/null and b/plugins/pixel-perfect/images/audit.png differ diff --git a/plugins/pixel-perfect/images/clarify.png b/plugins/pixel-perfect/images/clarify.png new file mode 100644 index 0000000..d8029da Binary files /dev/null and b/plugins/pixel-perfect/images/clarify.png differ diff --git a/plugins/pixel-perfect/images/colorize.png b/plugins/pixel-perfect/images/colorize.png new file mode 100644 index 0000000..f209931 Binary files /dev/null and b/plugins/pixel-perfect/images/colorize.png differ diff --git a/plugins/pixel-perfect/images/critique.png b/plugins/pixel-perfect/images/critique.png new file mode 100644 index 0000000..e4d7b0c Binary files /dev/null and b/plugins/pixel-perfect/images/critique.png differ diff --git a/plugins/pixel-perfect/images/distill.png b/plugins/pixel-perfect/images/distill.png new file mode 100644 index 0000000..938bb78 Binary files /dev/null and b/plugins/pixel-perfect/images/distill.png differ diff --git a/plugins/pixel-perfect/images/harden.png b/plugins/pixel-perfect/images/harden.png new file mode 100644 index 0000000..4c585fa Binary files /dev/null and b/plugins/pixel-perfect/images/harden.png differ diff --git a/plugins/pixel-perfect/images/normalize.png b/plugins/pixel-perfect/images/normalize.png new file mode 100644 index 0000000..b1193a7 Binary files /dev/null and b/plugins/pixel-perfect/images/normalize.png differ diff --git a/plugins/pixel-perfect/images/optimize.png b/plugins/pixel-perfect/images/optimize.png new file mode 100644 index 0000000..ca8584e Binary files /dev/null and b/plugins/pixel-perfect/images/optimize.png differ diff --git a/plugins/pixel-perfect/images/polish.png b/plugins/pixel-perfect/images/polish.png new file mode 100644 index 0000000..6953565 Binary files /dev/null and b/plugins/pixel-perfect/images/polish.png differ diff --git a/plugins/pixel-perfect/images/screenshot-diff.png b/plugins/pixel-perfect/images/screenshot-diff.png new file mode 100644 index 0000000..79b2d7e Binary files /dev/null and b/plugins/pixel-perfect/images/screenshot-diff.png differ diff --git a/plugins/pixel-perfect/images/typeset.png b/plugins/pixel-perfect/images/typeset.png new file mode 100644 index 0000000..3bc1fe3 Binary files /dev/null and b/plugins/pixel-perfect/images/typeset.png differ diff --git a/plugins/pixel-perfect/images/visual-qa.png b/plugins/pixel-perfect/images/visual-qa.png new file mode 100644 index 0000000..f3ae2e5 Binary files /dev/null and b/plugins/pixel-perfect/images/visual-qa.png differ diff --git a/plugins/pixel-perfect/skills/adapt/SKILL.md b/plugins/pixel-perfect/skills/adapt/SKILL.md new file mode 100644 index 0000000..7b99f75 --- /dev/null +++ b/plugins/pixel-perfect/skills/adapt/SKILL.md @@ -0,0 +1,139 @@ +--- +name: adapt +description: "Adapt designs for responsive layouts using real browser screenshots at each breakpoint. Tests touch targets, overflow, and orientation with actual rendered output. Use when the user mentions responsive design, mobile layout, breakpoints, viewport adaptation, or cross-device compatibility." +argument-hint: " [target-viewport]" +user-invocable: true +--- + +# Adapt — Browser-Verified Responsive Design + +Adapt designs across screen sizes using real rendered screenshots. Document what's broken at each breakpoint visually, then verify fixes in the browser. + +## Step 1: Document Current State at Every Breakpoint + +```bash +agent-browser open +agent-browser wait --load networkidle + +agent-browser set viewport 375 812 +agent-browser screenshot --full current-mobile.png + +agent-browser set viewport 768 1024 +agent-browser screenshot --full current-tablet.png + +agent-browser set viewport 1024 768 +agent-browser screenshot --full current-tablet-landscape.png + +agent-browser set viewport 1280 800 +agent-browser screenshot --full current-desktop.png +``` + +Review each screenshot. List every issue per viewport before writing any code. + +## Step 2: Test Touch Targets + +At mobile viewport, check all interactive elements are ≥ 44×44px: + +```bash +agent-browser set viewport 375 812 +agent-browser eval " + const violations = []; + document.querySelectorAll('a,button,input,select,textarea,[role=button]').forEach(el => { + const r = el.getBoundingClientRect(); + if (r.width > 0 && (r.width < 44 || r.height < 44)) { + violations.push({ tag: el.tagName, text: el.textContent.slice(0,25), w: Math.round(r.width), h: Math.round(r.height) }); + } + }); + JSON.stringify(violations); +" +``` + +Check spacing between adjacent targets (≥ 8px): + +```bash +agent-browser eval " + const els = [...document.querySelectorAll('a,button,[role=button]')]; + const crowded = []; + for (let i = 0; i < els.length; i++) { + const a = els[i].getBoundingClientRect(); + for (let j = i+1; j < Math.min(i+5, els.length); j++) { + const b = els[j].getBoundingClientRect(); + const gap = Math.min(Math.abs(a.right-b.left), Math.abs(b.right-a.left), Math.abs(a.bottom-b.top), Math.abs(b.bottom-a.top)); + if (gap >= 0 && gap < 8) crowded.push({ el1: els[i].textContent.slice(0,15), el2: els[j].textContent.slice(0,15), gap: Math.round(gap) }); + } + } + JSON.stringify(crowded.slice(0,15)); +" +``` + +## Step 3: Check Horizontal Overflow + +At each viewport, verify no content overflows: + +```bash +agent-browser eval " + const sw = document.documentElement.scrollWidth; + const cw = document.documentElement.clientWidth; + sw > cw ? 'OVERFLOW: ' + sw + ' > ' + cw : 'OK' +" +``` + +Find offending elements: + +```bash +agent-browser eval " + const cw = document.documentElement.clientWidth; + const wide = []; + document.querySelectorAll('*').forEach(el => { + const r = el.getBoundingClientRect(); + if (r.right > cw + 2) wide.push({ tag: el.tagName, class: el.className.toString().slice(0,30), overflow: Math.round(r.right - cw) }); + }); + JSON.stringify(wide.slice(0,10)); +" +``` + +## Step 4: Test Orientation Changes + +```bash +agent-browser set viewport 768 1024 +agent-browser screenshot --full portrait.png + +agent-browser set viewport 1024 768 +agent-browser screenshot --full landscape.png + +agent-browser set viewport 375 812 +agent-browser screenshot --full phone-portrait.png + +agent-browser set viewport 812 375 +agent-browser screenshot --full phone-landscape.png +``` + +Check: Does nav collapse correctly? Do images scale? Does content reflow? + +## Step 5: Make Changes and Verify + +After implementing responsive fixes, re-screenshot and re-run all checks: + +```bash +agent-browser reload +agent-browser wait --load networkidle + +agent-browser set viewport 375 812 +agent-browser screenshot --full fixed-mobile.png + +agent-browser set viewport 768 1024 +agent-browser screenshot --full fixed-tablet.png + +agent-browser set viewport 1280 800 +agent-browser screenshot --full fixed-desktop.png +``` + +Re-run touch target and overflow checks to confirm zero violations. + +## Key Principles + +- **Screenshot before coding** — document the broken state visually +- **Test orientation** — portrait ≠ landscape, both must work +- **Verify touch targets in the browser** — bounding box math doesn't lie +- **Fix overflow at every width** — horizontal scroll on mobile is unacceptable +- **Re-screenshot after every fix** — confirm changes visually, not just in code diff --git a/plugins/pixel-perfect/skills/animate/SKILL.md b/plugins/pixel-perfect/skills/animate/SKILL.md new file mode 100644 index 0000000..3ea8bc3 --- /dev/null +++ b/plugins/pixel-perfect/skills/animate/SKILL.md @@ -0,0 +1,135 @@ +--- +name: animate +description: "Add purposeful animations, micro-interactions, and celebration moments to a UI — then preview them in a real browser, record demos, and verify performance. Use when the user wants to add motion, transitions, micro-interactions, celebration effects, or make the interface feel alive." +argument-hint: "" +user-invocable: true +--- + +# Animate — Motion Design with Live Preview + +Add purposeful animations and celebration moments, then verify in a real browser. Record demos, test reduced motion, and confirm 60fps. + +## Step 1: Identify Animation Opportunities + +```bash +agent-browser open +agent-browser wait --load networkidle +agent-browser snapshot -i +``` + +Look for: +- **Missing feedback** — buttons with no press response, forms with no validation animation +- **Jarring transitions** — instant show/hide, abrupt page changes +- **Celebration gaps** — success states that feel flat (task completed, milestone hit) +- **Static empty states** — illustrations that could subtly breathe + +## Step 2: Implement Animations + +### Timing & Easing Reference + +| Purpose | Duration | Example | +|---------|----------|---------| +| Instant feedback | 100–150ms | Button press, toggle | +| State change | 200–300ms | Hover, menu open | +| Layout shift | 300–500ms | Accordion, modal | +| Entrance | 500–800ms | Page load, hero | + +**Easing — use these, not CSS defaults:** +```css +--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */ +--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */ +``` +Avoid bounce/elastic easing — feels dated. Exit animations run at ~75% of entrance duration. + +### Celebration & Milestone Moments + +- **Task completion** — animated checkmark, confetti burst, gentle scale pulse +- **Streaks** — "5 days in a row!" with particle effects +- **First-time actions** — special entrance animation for first use +- **Progress at 100%** — progress bar celebrates when full + +Keep celebrations under 1 second, skippable, and varied. + +### GPU Rules + +Only animate `transform` and `opacity` — never `width`, `height`, `top`, `left`. + +## Step 3: Preview in Browser + +```bash +agent-browser reload +agent-browser wait --load networkidle +agent-browser snapshot -i + +agent-browser hover @e1 +agent-browser screenshot hover-state.png +agent-browser click @e2 +agent-browser wait 500 +agent-browser screenshot click-feedback.png +``` + +## Step 4: Record a Demo + +```bash +agent-browser record start ./animation-demo.webm +agent-browser click @e1 +agent-browser wait 800 +agent-browser hover @e3 +agent-browser wait 500 +agent-browser click @e5 +agent-browser wait 1000 +agent-browser record stop +``` + +## Step 5: Test Reduced Motion + +```bash +agent-browser set media reduced-motion +agent-browser reload +agent-browser wait --load networkidle +agent-browser screenshot reduced-motion.png +``` + +Verify: decorative animations disabled, essential transitions instant, content fully accessible. + +```bash +agent-browser eval " + const has = [...document.styleSheets].some(s => { + try { return [...s.cssRules].some(r => r.conditionText?.includes('reduced-motion')); } catch(e) { return false; } + }); + has ? 'HAS prefers-reduced-motion support' : 'MISSING — add @media (prefers-reduced-motion: reduce)' +" +``` + +## Step 6: Verify 60fps + +```bash +agent-browser eval " + let frames=0, last=performance.now(), drops=[]; + function check(now) { frames++; if(now-last>20) drops.push(Math.round(now-last)); last=now; if(frames<120) requestAnimationFrame(check); } + requestAnimationFrame(check); + setTimeout(() => document.title='drops:'+JSON.stringify(drops), 2500); +" +agent-browser wait 3000 +agent-browser get title +``` + +Trigger animations while the counter runs. Any frame >20ms is potential jank. + +## Quality Checklist + +- [ ] Animations use `transform`/`opacity` only +- [ ] Easing is `ease-out-quart` or `ease-out-expo` +- [ ] Durations match the timing table +- [ ] `prefers-reduced-motion` disables decorative motion +- [ ] Celebrations are under 1s and skippable +- [ ] Demo recorded showing smooth motion +- [ ] No frame drops >20ms + +## Key Principles + +- **Every animation needs a reason** — feedback, transition, or delight +- **One hero moment beats scattered animations** — focus on impact +- **Preview in the browser** — code review can't judge motion +- **Record demos** — stakeholders need to see motion, not read about it +- **Respect reduced motion** — accessibility requirement, not optional diff --git a/plugins/pixel-perfect/skills/audit/SKILL.md b/plugins/pixel-perfect/skills/audit/SKILL.md new file mode 100644 index 0000000..8f1bebf --- /dev/null +++ b/plugins/pixel-perfect/skills/audit/SKILL.md @@ -0,0 +1,137 @@ +--- +name: audit +description: "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Uses browser automation for real-device verification. Generates a scored report with P0-P3 severity ratings." +user-invocable: true +--- + +Run systematic **technical** quality checks with **real browser verification** and generate a comprehensive report. Don't fix issues — document them for other skills to address. + +## Preparation + +1. Invoke the `frontend-design` skill to load design principles and anti-patterns. +2. Check for `.pixel-perfect.md` in the project root for project-specific design context. + +--- + +## Browser Verification Phase + +Before scoring anything in code, **open the actual page** with `agent-browser` and perform real visual checks: + +### Multi-Viewport Screenshots +Take screenshots at three breakpoints to assess responsive behavior: +``` +agent-browser screenshot at viewport 375x812 → mobile.png +agent-browser screenshot at viewport 768x1024 → tablet.png +agent-browser screenshot at viewport 1280x800 → desktop.png +``` + +### Contrast Verification +Use `agent-browser eval` to check actual rendered contrast ratios on key text elements: +```js +// Get computed styles on rendered elements +const el = document.querySelector('.hero-heading'); +const styles = getComputedStyle(el); +// Log color and background-color for manual contrast check +console.log('color:', styles.color, 'bg:', styles.backgroundColor); +``` +Check at least: primary headings, body text, secondary/muted text, text on colored backgrounds, and button labels. + +### Accessibility Scan +Use `agent-browser eval` to check for common a11y gaps: +```js +// Missing alt text +document.querySelectorAll('img:not([alt])').length; +// Buttons/links without accessible names +document.querySelectorAll('button:not([aria-label]):empty').length; +// Inputs without labels +document.querySelectorAll('input:not([aria-label]):not([id])').length; +// Missing landmarks +document.querySelectorAll('main, nav, header, footer').length; +``` + +### Screenshot Problem Areas +When you find a visual issue, screenshot the specific region and annotate what's wrong. This creates a visual paper trail. + +--- + +## Diagnostic Scan + +Score each dimension 0–4 using the criteria below. + +### 1. Accessibility (A11y) +**Check for**: Contrast ratios < 4.5:1, missing ARIA, keyboard navigation gaps, improper heading hierarchy, missing alt text, unlabeled form inputs. + +**Score**: 0=Inaccessible (fails WCAG A), 1=Major gaps, 2=Partial effort with significant gaps, 3=WCAG AA mostly met, 4=WCAG AA fully met. + +### 2. Performance +**Check for**: Layout thrashing, expensive animations (animating width/height/top/left), missing lazy loading, unnecessary imports, unnecessary re-renders. + +**Score**: 0=Severe issues, 1=Major problems, 2=Partial optimization, 3=Mostly optimized, 4=Fast and lean. + +### 3. Theming +**Check for**: Hard-coded colors, broken dark mode, inconsistent token usage, values that don't update on theme change. + +**Score**: 0=No theming, 1=Mostly hard-coded, 2=Tokens exist but inconsistent, 3=Tokens used with minor gaps, 4=Full token system, dark mode works. + +### 4. Responsive Design +**Check for**: Fixed widths that break on mobile, touch targets < 44x44px, horizontal scroll, text scaling failures, missing breakpoints. **Use the multi-viewport screenshots** from the browser verification phase to validate. + +**Score**: 0=Desktop-only, 1=Some breakpoints with many failures, 2=Works on mobile with rough edges, 3=Responsive with minor issues, 4=Fluid across all viewports. + +### 5. Anti-Patterns (CRITICAL) +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells: AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts. **Use the desktop screenshot** — AI slop is obvious visually before it's obvious in code. + +**Score**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4), 2=Some tells (1-2), 3=Mostly clean, 4=Distinctive and intentional. + +--- + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical issue] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent, 14-17 Good, 10-13 Acceptable, 6-9 Poor, 0-5 Critical. + +### Anti-Patterns Verdict +Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. Reference the screenshots. + +### Executive Summary +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues with screenshot evidence +- Recommended next steps + +### Detailed Findings by Severity + +Tag every issue **P0-P3**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix — address if time permits + +For each issue: **[P?] Issue name**, Location, Category, Impact, Standard violated, Recommendation, and screenshot reference if applicable. + +### Patterns & Systemic Issues +Identify recurring problems that indicate systemic gaps rather than one-off mistakes. + +### Positive Findings +Note what's working well — good practices to maintain and replicate. + +## Recommended Actions + +List recommended skills in priority order (P0 first): + +1. **[P?] `skill-name`** — Brief description with specific context from findings +2. **[P?] `skill-name`** — Brief description + +> Re-run `audit` after fixes to see your score improve. + +**NEVER**: Report issues without explaining impact. Provide generic recommendations. Skip positive findings. Report false positives without browser verification. diff --git a/plugins/pixel-perfect/skills/clarify/SKILL.md b/plugins/pixel-perfect/skills/clarify/SKILL.md new file mode 100644 index 0000000..ceed4f8 --- /dev/null +++ b/plugins/pixel-perfect/skills/clarify/SKILL.md @@ -0,0 +1,87 @@ +--- +name: clarify +description: "Improve unclear UX copy, error messages, labels, and instructions by reading the actual rendered text in the browser. Use when the user mentions confusing text, unclear labels, bad error messages, or wants better UX writing." +user-invocable: true +--- + +Find and fix unclear interface text by reading what users actually see in the browser. + +## 1. Read Rendered Text via agent-browser + +Don't just grep source code—use agent-browser to see what users see: + +- Navigate to each screen in the target area +- Read the actual rendered text: headings, labels, buttons, tooltips, error states +- Trigger error states to see real error messages +- Check empty states, loading states, and confirmation dialogs +- Note text that's truncated, overlapping, or visually confusing in context + +This catches issues that code review misses: dynamic text, interpolated strings, text that only appears in specific states. + +## 2. Identify Copy Problems + +Flag text that fails these checks: + +### Vague Error Messages +- ❌ "Something went wrong" / "Error" / "Invalid input" +- ✅ "We couldn't save your changes. Check your connection and try again." +- ✅ "Email address needs an @ symbol. Example: name@company.com" + +### Confusing Labels +- ❌ Generic: "Value", "Type", "Status", "Items" +- ❌ Jargon: "Webhook payload", "OAuth scope", "Idempotency key" +- ✅ Specific: "Monthly revenue", "Account type", "Delivery status" + +### Wordy Instructions +- ❌ "In order to proceed with the creation of your account, please fill in the required fields below" +- ✅ "Create your account" + +### Weak CTAs +- ❌ "Submit" / "OK" / "Click here" / "Yes" +- ✅ "Save changes" / "Create project" / "Delete account" + +### Passive Voice +- ❌ "Your file has been uploaded" +- ✅ "File uploaded" or "We uploaded your file" + +### Missing Context +- ❌ Empty state: "No items" +- ✅ Empty state: "No projects yet. Create one to get started." + +## 3. Apply Fixes + +For each identified issue: + +- **Replace jargon** with plain language the target audience understands +- **Make CTAs action-oriented**: verb + noun ("Save draft", "Send invite") +- **Error messages**: explain what happened + how to fix it +- **Be specific**: "Your email" not "Enter value", "3 team members" not "Items" +- **Be concise**: cut unnecessary words but keep clarity +- **Be consistent**: same term everywhere (don't alternate "delete"/"remove"/"discard") + +### Priority Order +1. Error messages (highest user frustration) +2. Primary CTAs (directly affect task completion) +3. Form labels and help text +4. Empty states and loading messages +5. Navigation labels +6. Success messages and confirmations + +## 4. Verify in Context + +Use agent-browser to confirm fixes work in the actual UI: + +- Read the updated text as rendered in the browser +- Check that improved copy fits the layout (no overflow, no truncation) +- Trigger error states again to verify error messages are helpful +- Walk through complete user flows to ensure copy is consistent +- Verify placeholder text disappears correctly and labels remain visible + +## Rules + +- Never use humor in error messages—be empathetic and helpful +- Don't blame the user ("You entered an invalid email" → "This email format isn't recognized") +- Match the audience's vocabulary (technical docs can use technical terms; consumer UI cannot) +- Maintain consistent terminology throughout the entire application +- Don't change microcopy that has legal or compliance implications without flagging it +- Run lint, type-check, and tests after changes diff --git a/plugins/pixel-perfect/skills/colorize/SKILL.md b/plugins/pixel-perfect/skills/colorize/SKILL.md new file mode 100644 index 0000000..6b307c8 --- /dev/null +++ b/plugins/pixel-perfect/skills/colorize/SKILL.md @@ -0,0 +1,111 @@ +--- +name: colorize +description: "Add strategic color to monochromatic UIs with browser-verified contrast and accessibility. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant palette." +user-invocable: true +--- + +Transform monochrome or gray interfaces with purposeful color, verified in the actual browser. + +## 1. Assess the Current Palette + +Scan the codebase for the existing color usage: + +- Grep for all color values: hex, rgb, hsl, oklch, CSS custom properties +- Map which colors are used where (backgrounds, text, borders, icons, states) +- Identify the dominant palette: pure grayscale? One timid accent? All neutrals? +- Check for existing brand colors or design tokens + +Use agent-browser to screenshot the current state—see how monochromatic it actually looks rendered. + +## 2. Plan Color Introduction + +Define a purposeful palette (2-4 colors max beyond neutrals): + +- **Primary color**: The dominant accent (60% of colored elements)—brand identity, primary CTAs +- **Semantic colors**: Success (green), error (red), warning (amber), info (blue) +- **Supporting accent**: A secondary color for variety (30%) +- **Highlight color**: Sparingly used for key moments (10%) + +Map where each color will appear: +- Primary CTAs and interactive elements +- Status indicators and badges +- Section backgrounds and card accents +- Icons and data visualization +- Hover/focus/active states + +## 3. Verify Contrast via agent-browser + +Before applying colors, check contrast ratios on rendered elements: + +```javascript +// Use eval in agent-browser to check computed styles +const el = document.querySelector('.button-primary'); +const styles = getComputedStyle(el); +const bgColor = styles.backgroundColor; +const textColor = styles.color; +// Calculate contrast ratio +``` + +- Check every text-on-background combination meets WCAG AA (4.5:1 for text, 3:1 for large text and UI components) +- Verify interactive elements have sufficient contrast against their backgrounds +- Test focus ring visibility on colored backgrounds + +## 4. Apply Color Strategically + +### State Communication +- **Success states**: Green tones for completed, saved, active +- **Error states**: Red/rose for failures, validation errors, destructive actions +- **Warning states**: Amber/orange for caution, approaching limits +- **Info states**: Blue for informational messages, tips +- Don't rely on color alone—pair with icons or text labels + +### Surfaces and Backgrounds +- Replace pure gray backgrounds (`#f5f5f5`) with warm-tinted neutrals +- Add subtle colored section backgrounds to create visual rhythm +- Use colored left-borders on cards for categorization +- Tint empty states with soft brand color + +### Interactive Elements +- Color primary buttons with the brand/primary color +- Add hover state color shifts (darken or lighten by one step) +- Color links distinctly from body text +- Ensure focus states use visible, colored rings + +### Data and Status +- Color-code badges, tags, and status indicators +- Use color meaningfully in charts and graphs +- Apply consistent color mapping (green = good, red = bad) across all features + +## 5. Check Colorblind Accessibility + +Use agent-browser eval to simulate color vision deficiency: + +```javascript +// Apply CSS filter to simulate color blindness +document.documentElement.style.filter = 'url(#protanopia-filter)'; +// Or use SVG filters for deuteranopia, tritanopia +``` + +- Verify the UI is still usable under protanopia (red-blind) simulation +- Check deuteranopia (green-blind) simulation +- Confirm that color is never the **only** indicator—icons, patterns, or text must accompany it +- Screenshot each simulation for the record + +## 6. Visual Verification + +Use agent-browser to confirm the final result: + +- Screenshot the colorized UI and compare against the monochrome original +- Verify color communicates meaning (users can tell success from error at a glance) +- Check that the palette feels cohesive, not chaotic +- Test at multiple viewport sizes—color should work on mobile too +- Confirm dark mode compatibility if applicable + +## Rules + +- Max 2-4 colors beyond neutrals—strategic beats saturated +- Never use color as the only indicator (accessibility requirement) +- Don't put gray text on colored backgrounds—use darker shades of the background color +- Avoid pure black (`#000`) and pure white (`#fff`) for large surfaces +- Every color must have a purpose: hierarchy, meaning, or brand identity +- Run lint, type-check, and tests after changes diff --git a/plugins/pixel-perfect/skills/critique/SKILL.md b/plugins/pixel-perfect/skills/critique/SKILL.md new file mode 100644 index 0000000..3b7cf1b --- /dev/null +++ b/plugins/pixel-perfect/skills/critique/SKILL.md @@ -0,0 +1,149 @@ +--- +name: critique +description: "Evaluate design from a UX perspective using browser automation. Assesses visual hierarchy, information architecture, emotional resonance, and cognitive load with quantitative scoring and real interaction testing." +user-invocable: true +--- + +Conduct a holistic design critique by **actually looking at and interacting with the interface** in a real browser. Think like a design director who opens the product, uses it, and gives feedback based on what they see — not what they imagine from reading code. + +## Preparation + +1. Invoke the `frontend-design` skill to load design principles and anti-patterns. +2. Check for `.pixel-perfect.md` in the project root for project-specific design context. +3. Identify the URL or file path to open the interface. + +--- + +## Phase 1: Visual Capture & Flow Testing + +Before writing a single word of critique, **use the interface**: + +### Screenshot the Current State +Open the page with `agent-browser` and take a full-page screenshot. This is your primary input — study the visual hierarchy, composition, and overall impression before reading any code. + +### Test the Primary User Flow +Use `agent-browser` to walk through the main user journey: +1. Identify the primary action the interface is designed for. +2. Click through it step by step — every button, every form field, every transition. +3. Screenshot each major state change. +4. Note where you hesitate, get confused, or feel friction. Those are your findings. + +### Test Interaction States +Use `agent-browser` to verify hover, focus, and active states on key interactive elements: +- Hover over buttons and links — is there feedback? +- Tab through the page — are focus indicators visible and logical? +- Click interactive elements — does the active state feel responsive? + +--- + +## Phase 2: Design Critique + +Evaluate the interface across these dimensions, using your screenshots and interaction experience as primary evidence: + +### 1. AI Slop Detection (CRITICAL) +Look at the screenshot. Does this look like every other AI-generated interface? Check against ALL the **DON'T** guidelines in the frontend-design skill. The test: would someone immediately believe "AI made this"? + +### 2. Visual Hierarchy +Does the eye flow to the most important element first? Is there a clear primary action visible in 2 seconds? Do size, color, and position communicate importance correctly? + +### 3. Information Architecture & Cognitive Load +Is the structure intuitive? Are there too many choices at once (>4 visible options at a decision point)? Is complexity revealed progressively or dumped upfront? + +### 4. Emotional Journey +What emotion does this interface evoke? Does it match the brand personality? Does the experience end well (confirmation, celebration, clear next step)? + +### 5. Discoverability & Affordance +Are interactive elements obviously interactive? Would a user know what to do without instructions? Do hover/focus states provide useful feedback? (You tested these in Phase 1.) + +### 6. Composition & Balance +Does the layout feel balanced? Is whitespace intentional? Is there visual rhythm? Does asymmetry feel designed or accidental? + +### 7. Typography as Communication +Does the type hierarchy signal what to read first, second, third? Is body text comfortable (45-75 char line length)? Do font choices reinforce the tone? + +### 8. Color with Purpose +Is color used to communicate, not just decorate? Does the palette feel cohesive? Do accent colors draw attention to the right things? + +### 9. States & Edge Cases +Empty states: do they guide users? Loading states: do they reduce perceived wait? Error states: are they helpful and non-blaming? + +### 10. Microcopy & Voice +Is the writing clear and concise? Does it sound human? Are labels unambiguous? + +--- + +## Phase 3: Persona Testing via Browser + +Select 2-3 personas most relevant to this interface type and **simulate their experience** using `agent-browser`: + +### First-Timer Test +Navigate the interface as if seeing it for the first time: +- Can you complete the primary action without prior knowledge? +- Is there visible help or onboarding? +- Screenshot the exact point where a newcomer would get stuck. + +### Power User Test +Try to accomplish tasks efficiently: +- Are there keyboard shortcuts? Try common ones (Cmd+K, /, Escape). +- How many clicks for the primary action? Count them. +- Is there a way to skip steps or use advanced features? + +### Accessibility User Test +Navigate with keyboard only (use agent-browser tab/enter/escape): +- Can you reach all interactive elements? +- Is the focus order logical? +- Are focus indicators visible? + +For each persona, list **specific elements and interactions that fail** — not generic descriptions. + +--- + +## Phase 4: Present Findings + +### Design Health Score + +Score each of Nielsen's 10 heuristics 0–4: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—"] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest. A 4 means genuinely excellent. Most real interfaces score 20-32. + +### Anti-Patterns Verdict +Pass/fail with screenshot evidence. List specific AI slop tells found. + +### Overall Impression +Gut reaction — what works, what doesn't, the single biggest opportunity. + +### What's Working +2-3 things done well, with specific reasons why. + +### Priority Issues +3-5 most impactful problems, ordered by importance. For each: +- **[P0-P3] What**: Name it clearly +- **Why it matters**: How this hurts users +- **Fix**: Concrete recommendation +- **Screenshot**: Reference the specific screenshot showing the problem + +### Persona Red Flags +Specific failures per persona from Phase 3, with screenshots. + +### Recommended Actions + +List recommended skills in priority order: +1. **`skill-name`** — Brief description with specific context from findings + +> Re-run `critique` after fixes to see your score improve. + +**NEVER**: Give vague feedback. Say "consider exploring" instead of giving a concrete fix. Soften criticism. Skip the browser testing phases — code review alone misses visual and interaction problems. diff --git a/plugins/pixel-perfect/skills/critique/reference/cognitive-load.md b/plugins/pixel-perfect/skills/critique/reference/cognitive-load.md new file mode 100644 index 0000000..313df16 --- /dev/null +++ b/plugins/pixel-perfect/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/plugins/pixel-perfect/skills/critique/reference/heuristics-scoring.md b/plugins/pixel-perfect/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 0000000..fd5b1b0 --- /dev/null +++ b/plugins/pixel-perfect/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/plugins/pixel-perfect/skills/critique/reference/personas.md b/plugins/pixel-perfect/skills/critique/reference/personas.md new file mode 100644 index 0000000..4b426e4 --- /dev/null +++ b/plugins/pixel-perfect/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `.impeccable.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/plugins/pixel-perfect/skills/distill/SKILL.md b/plugins/pixel-perfect/skills/distill/SKILL.md new file mode 100644 index 0000000..0ff799a --- /dev/null +++ b/plugins/pixel-perfect/skills/distill/SKILL.md @@ -0,0 +1,88 @@ +--- +name: distill +description: "Strip designs to their essence by removing clutter, redundancy, and unnecessary complexity. Use when the user asks to simplify, declutter, reduce noise, or make a UI cleaner and more focused." +user-invocable: true +--- + +Remove unnecessary complexity from the UI, reducing cognitive load while preserving everything essential. + +## 1. Identify Clutter + +Analyze the target for these common sources of visual and cognitive noise: + +- **Redundant headers**: Titles restating what the page already says, breadcrumbs duplicating tabs +- **Too many CTAs**: Multiple competing buttons fighting for attention +- **Nested cards**: Cards inside cards inside cards—unnecessary visual containers +- **Unnecessary chrome**: Borders, dividers, backgrounds, and decorations that don't aid comprehension +- **Information overload**: Everything visible at once with no progressive disclosure +- **Repeated content**: Same information stated multiple ways +- **Dead weight**: Elements that exist "just in case" but no one uses + +Use agent-browser to screenshot the current state and annotate what's clutter vs. essential. + +## 2. Find the Essence + +For each screen or component, answer: + +- What is the **one primary goal** the user has here? +- What's the minimum needed to accomplish that goal? +- What can be removed entirely? +- What can be hidden behind progressive disclosure (accordion, "Show more", modal)? +- What can be combined into a single element? + +## 3. Apply Progressive Disclosure + +Move secondary complexity out of the default view: + +- **Collapse advanced options** into expandable sections +- **Move edge-case actions** into overflow menus +- **Defer details** behind "Learn more" or expandable rows +- **Simplify forms** by hiding optional fields until requested +- **Reduce visible choices** to the 2-3 most common options + +## 4. Simplify Systematically + +### Layout +- Flatten nesting: remove wrapper elements that only add indirection +- Eliminate unnecessary cards—use spacing and alignment instead +- Replace complex multi-column layouts with linear flow where possible +- Use whitespace to create grouping instead of borders and backgrounds + +### Visual +- Reduce to 1-2 accent colors plus neutrals +- Remove decorative borders, shadows, and backgrounds that don't serve hierarchy +- Limit to 3-4 type sizes maximum +- Strip gratuitous icons that duplicate adjacent text + +### Content +- Cut copy in half. Then cut it in half again +- Remove redundant headings and labels +- One CTA per context—make the next step obvious +- Eliminate marketing fluff from functional UI + +### Interaction +- Reduce confirmation dialogs to only destructive actions +- Replace multi-step flows with single-step where possible +- Smart defaults over explicit choices +- Inline editing over modal forms + +## 5. Verify with Before/After Screenshots + +Use agent-browser to capture before and after: + +- Screenshot the original cluttered state +- Screenshot the simplified version +- Compare side-by-side to confirm: + - All essential functionality is still accessible + - The primary action is more obvious, not less + - Users can still accomplish their goals + - Nothing critical was hidden too aggressively + +Test interactive flows to make sure progressive disclosure works correctly—hidden content should be easy to find when needed. + +## Rules + +- Simplification ≠ removal of features. Everything essential stays, just better organized +- Never sacrifice accessibility (labels, ARIA, contrast must remain) +- If you're unsure whether something is essential, keep it and ask +- Run lint, type-check, and tests after changes diff --git a/plugins/pixel-perfect/skills/frontend-design/SKILL.md b/plugins/pixel-perfect/skills/frontend-design/SKILL.md new file mode 100644 index 0000000..a5b5d42 --- /dev/null +++ b/plugins/pixel-perfect/skills/frontend-design/SKILL.md @@ -0,0 +1,112 @@ +--- +name: frontend-design +description: "Create distinctive, production-grade frontend interfaces with high design quality. Uses browser automation for visual verification. Generates creative, polished code that avoids generic AI aesthetics." +user-invocable: true +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details — then **verify it visually** with browser screenshots. + +## Project Configuration + +Before starting any design work, check for a `.pixel-perfect.md` file in the project root. This file contains project-specific design context: + +1. **Read `.pixel-perfect.md`** from the project root. If it exists, load the design context (target audience, brand personality, tone, palette constraints, typography choices, component library). +2. **If no config exists**, examine the existing codebase for design patterns, then proceed with the design direction below. Note the absence — suggest the user create one after the session. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme — brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? + +Then implement working code that is production-grade, visually striking, cohesive, and meticulously refined. + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +**DO**: Use a modular type scale with fluid sizing (clamp). Vary weights and sizes for clear hierarchy. +**DON'T**: Use overused fonts — Inter, Roboto, Arial, Open Sans, system defaults. +**DON'T**: Use monospace as lazy shorthand for "technical/developer" vibes. +**DON'T**: Put large icons with rounded corners above every heading. + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark). Tint neutrals toward your brand hue. +**DON'T**: Use gray text on colored backgrounds — use a shade of the background color instead. +**DON'T**: Use pure black (#000) or pure white (#fff) — always tint. +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark. +**DON'T**: Use gradient text for "impact." Default to dark mode with glowing accents. + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +**DO**: Create visual rhythm through varied spacing. Use fluid spacing with clamp(). Use asymmetry intentionally. +**DON'T**: Wrap everything in cards. Nest cards inside cards. Use identical card grids endlessly. +**DON'T**: Use the hero metric layout template. Center everything. Use the same spacing everywhere. + +### Visual Details +**DON'T**: Use glassmorphism everywhere. Use rounded elements with thick colored border on one side. +**DON'T**: Use sparklines as decoration. Use rounded rectangles with generic drop shadows. +**DON'T**: Use modals unless there's truly no better alternative. + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +**DO**: Use motion to convey state changes. Use exponential easing (ease-out-quart/quint/expo). +**DO**: For height animations, use grid-template-rows transitions. +**DON'T**: Animate layout properties (width, height, padding, margin) — use transform and opacity. +**DON'T**: Use bounce or elastic easing — they feel dated. + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +**DO**: Use progressive disclosure. Design empty states that teach. Make every interactive surface responsive. +**DON'T**: Repeat the same information. Make every button primary. + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container). Adapt the interface for different contexts. +**DON'T**: Hide critical functionality on mobile. + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place. **DON'T**: Repeat information users can already see. + +--- + +## The AI Slop Test + +If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. Review the DON'T guidelines above — they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Browser Verification + +After implementing any design work, **visually verify your output** using `agent-browser`: + +1. **Open the page** in agent-browser and take a full-page screenshot. +2. **Check visual hierarchy**: Does the eye flow to the most important element? Is the layout balanced? +3. **Verify typography**: Are fonts loading correctly? Is the type scale working? Check for FOUT/FOIT. +4. **Verify color**: Do the colors render as intended? Check dark mode if applicable. +5. **Test responsiveness**: Resize to mobile (375px), tablet (768px), and desktop (1280px). Screenshot each. +6. **Test interactions**: Hover, focus, and click interactive elements. Verify state transitions are smooth. +7. **Compare against intent**: Does the rendered result match the aesthetic direction you chose? + +If anything looks wrong in the screenshots, fix it before moving on. Code that looks right in your head but wrong in the browser is wrong. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Interpret creatively — make unexpected choices that feel genuinely designed for the context. No two designs should look the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +The AI model is capable of extraordinary creative work. Don't hold back — commit fully to a distinctive vision, then verify it renders correctly in the browser. diff --git a/plugins/pixel-perfect/skills/frontend-design/reference/color-and-contrast.md b/plugins/pixel-perfect/skills/frontend-design/reference/color-and-contrast.md new file mode 100644 index 0000000..77aaf03 --- /dev/null +++ b/plugins/pixel-perfect/skills/frontend-design/reference/color-and-contrast.md @@ -0,0 +1,132 @@ +# Color & Contrast + +## Color Spaces: Use OKLCH + +**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark. + +```css +/* OKLCH: lightness (0-100%), chroma (0-0.4+), hue (0-360) */ +--color-primary: oklch(60% 0.15 250); /* Blue */ +--color-primary-light: oklch(85% 0.08 250); /* Same hue, lighter */ +--color-primary-dark: oklch(35% 0.12 250); /* Same hue, darker */ +``` + +**Key insight**: As you move toward white or black, reduce chroma (saturation). High chroma at extreme lightness looks garish. A light blue at 85% lightness needs ~0.08 chroma, not the 0.15 of your base color. + +## Building Functional Palettes + +### The Tinted Neutral Trap + +**Pure gray is dead.** Add a subtle hint of your brand hue to all neutrals: + +```css +/* Dead grays */ +--gray-100: oklch(95% 0 0); /* No personality */ +--gray-900: oklch(15% 0 0); + +/* Warm-tinted grays (add brand warmth) */ +--gray-100: oklch(95% 0.01 60); /* Hint of warmth */ +--gray-900: oklch(15% 0.01 60); + +/* Cool-tinted grays (tech, professional) */ +--gray-100: oklch(95% 0.01 250); /* Hint of blue */ +--gray-900: oklch(15% 0.01 250); +``` + +The chroma is tiny (0.01) but perceptible. It creates subconscious cohesion between your brand color and your UI. + +### Palette Structure + +A complete system needs: + +| Role | Purpose | Example | +|------|---------|---------| +| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades | +| **Neutral** | Text, backgrounds, borders | 9-11 shade scale | +| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each | +| **Surface** | Cards, modals, overlays | 2-3 elevation levels | + +**Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise. + +### The 60-30-10 Rule (Applied Correctly) + +This rule is about **visual weight**, not pixel count: + +- **60%**: Neutral backgrounds, white space, base surfaces +- **30%**: Secondary colors—text, borders, inactive states +- **10%**: Accent—CTAs, highlights, focus states + +The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power. + +## Contrast & Accessibility + +### WCAG Requirements + +| Content Type | AA Minimum | AAA Target | +|--------------|------------|------------| +| Body text | 4.5:1 | 7:1 | +| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 | +| UI components, icons | 3:1 | 4.5:1 | +| Non-essential decorations | None | None | + +**The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG. + +### Dangerous Color Combinations + +These commonly fail contrast or cause readability issues: + +- Light gray text on white (the #1 accessibility fail) +- **Gray text on any colored background**—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency +- Red text on green background (or vice versa)—8% of men can't distinguish these +- Blue text on red background (vibrates visually) +- Yellow text on white (almost always fails) +- Thin light text on images (unpredictable contrast) + +### Never Use Pure Gray or Pure Black + +Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.) + +### Testing + +Don't trust your eyes. Use tools: + +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) +- Browser DevTools → Rendering → Emulate vision deficiencies +- [Polypane](https://polypane.app/) for real-time testing + +## Theming: Light & Dark Mode + +### Dark Mode Is Not Inverted Light Mode + +You can't just swap colors. Dark mode requires different design decisions: + +| Light Mode | Dark Mode | +|------------|-----------| +| Shadows for depth | Lighter surfaces for depth (no shadows) | +| Dark text on light | Light text on dark (reduce font weight) | +| Vibrant accents | Desaturate accents slightly | +| White backgrounds | Never pure black—use dark gray (oklch 12-18%) | + +```css +/* Dark mode depth via surface color, not shadow */ +:root[data-theme="dark"] { + --surface-1: oklch(15% 0.01 250); + --surface-2: oklch(20% 0.01 250); /* "Higher" = lighter */ + --surface-3: oklch(25% 0.01 250); + + /* Reduce text weight slightly */ + --body-weight: 350; /* Instead of 400 */ +} +``` + +### Token Hierarchy + +Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer—primitives stay the same. + +## Alpha Is A Design Smell + +Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed. + +--- + +**Avoid**: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected). diff --git a/plugins/pixel-perfect/skills/frontend-design/reference/interaction-design.md b/plugins/pixel-perfect/skills/frontend-design/reference/interaction-design.md new file mode 100644 index 0000000..19d6809 --- /dev/null +++ b/plugins/pixel-perfect/skills/frontend-design/reference/interaction-design.md @@ -0,0 +1,195 @@ +# Interaction Design + +## The Eight Interactive States + +Every interactive element needs these states designed: + +| State | When | Visual Treatment | +|-------|------|------------------| +| **Default** | At rest | Base styling | +| **Hover** | Pointer over (not touch) | Subtle lift, color shift | +| **Focus** | Keyboard/programmatic focus | Visible ring (see below) | +| **Active** | Being pressed | Pressed in, darker | +| **Disabled** | Not interactive | Reduced opacity, no pointer | +| **Loading** | Processing | Spinner, skeleton | +| **Error** | Invalid state | Red border, icon, message | +| **Success** | Completed | Green check, confirmation | + +**The common miss**: Designing hover without focus, or vice versa. They're different. Keyboard users never see hover states. + +## Focus Rings: Do Them Right + +**Never `outline: none` without replacement.** It's an accessibility violation. Instead, use `:focus-visible` to show focus only for keyboard users: + +```css +/* Hide focus ring for mouse/touch */ +button:focus { + outline: none; +} + +/* Show focus ring for keyboard */ +button:focus-visible { + outline: 2px solid var(--color-accent); + outline-offset: 2px; +} +``` + +**Focus ring design**: +- High contrast (3:1 minimum against adjacent colors) +- 2-3px thick +- Offset from element (not inside it) +- Consistent across all interactive elements + +## Form Design: The Non-Obvious + +**Placeholders aren't labels**—they disappear on input. Always use visible `