agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/skills/design/frontend-design-review/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: frontend-design-review
+description: >
+  Review and create distinctive, production-grade frontend interfaces with high design
+  quality and design system compliance. Evaluates using three pillars: frictionless
+  insight-to-action, quality craft, and trustworthy building.
+origin:
+  type: upstream
+upstream:
+  repository: microsoft/skills
+  path: .github/skills/frontend-design-review
+  ref: e58528db9a006528a5fb0a2c029790fa6a9a7c0e
+  license: MIT
+  version: e58528d
+trust:
+  tier: reviewed
+  reviewed_at: '2026-08-11'
+  reviewed_by: ulises-jeremias
+  reviewed_provenance: sha256:5394cd7cf5d9c56acd77c251da40cb603795ac5e5b4d817578991d12d57d2be7
+maintenance:
+  status: active
+  last_activity: '2026-08-11'
+distribution:
+  mode: vendored
+  redistribution_allowed: true
+security:
+  scripts: false
+  shell: false
+  network: false
+  mcp: []
+  hooks: []
+  dangerous_permissions: []
+  cve_policy: not-applicable
+---
+
+# Frontend Design Review
+
+> **Frozen vendored snapshot** of `microsoft/skills` `.github/skills/frontend-design-review` at `e58528d` (commit `e58528db9a006528a5fb0a2c029790fa6a9a7c0e`, MIT) per ADR-0001 declaration→lock→vendored→surfaces. All references are local `references/` — no runtime network fetch. See `capabilities/upstream.lock` `design/frontend-design-review` and `docs/UPSTREAM.md`.
+
+Review UI implementations against design quality standards and your design system **OR** create distinctive, production-grade frontend interfaces from scratch.
+
+## Two Modes
+
+### Mode 1: Design Review
+Evaluate existing UI for design system compliance, three quality pillars (Frictionless, Quality Craft, Trustworthy), accessibility, and code quality.
+
+### Mode 2: Creative Frontend Design
+Create distinctive interfaces that avoid generic "AI slop" aesthetics, have clear conceptual direction, and execute with precision.
+
+---
+
+## Creative Frontend Design
+
+Before coding, commit to an aesthetic direction:
+- **Purpose**: What problem does this solve? Who uses it?
+- **Tone**: minimal, maximalist, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, soft/pastel, industrial, etc.
+- **Constraints**: Framework, performance, accessibility requirements.
+- **Differentiation**: What makes this distinctive and context-appropriate?
+
+### Aesthetics Guidelines
+
+- **Typography**: Distinctive fonts that elevate aesthetics. Pair a display font with a refined body font. Avoid Inter, Roboto, Arial, Space Grotesk.
+- **Color & Theme**: Cohesive palette with CSS variables. Dominant colors + sharp accents > timid, evenly-distributed palettes.
+- **Motion**: CSS-only preferred. One well-orchestrated page load with staggered reveals > scattered micro-interactions.
+- **Spatial Composition**: Asymmetry, overlap, diagonal flow, grid-breaking elements, generous negative space OR controlled density.
+- **Backgrounds**: Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, grain overlays.
+
+**AVOID**: Overused fonts, cliched color schemes, predictable layouts, cookie-cutter design without context-specific character.
+
+Match implementation complexity to vision. Maximalist = elaborate code. Minimalist = restraint and precision.
+
+---
+
+## Design Review
+
+### Design System Workflow
+
+**Before implementing:**
+1. Review component in your Storybook / component library for API and usage
+2. Use Figma Dev Mode to get exact specs (spacing, tokens, properties)
+3. Implement using design system components + design tokens
+
+**During review:**
+1. Compare implementation to Figma design
+2. Verify design tokens are used (not hardcoded values)
+3. Check all variants/states are implemented correctly
+4. Flag deviations (needs design approval)
+
+**If component doesn't exist:**
+1. Check if existing component can be adapted
+2. Reach out to design for new component creation
+3. Document exception and rationale in code
+
+### Review Process
+
+1. Identify user task
+2. Check design system for matching patterns
+3. Evaluate aesthetic direction
+4. Identify scope (component, feature, or flow)
+5. Evaluate each pillar
+6. Score and prioritize issues (blocking/major/minor)
+7. Provide recommendations with design system examples
+
+### Core Principles
+
+- **Task completion**: Minimum clicks. Every screen answers "What can I do?" and "What happens next?"
+- **Action hierarchy**: 1-2 primary actions per view. Progressive disclosure for secondary.
+- **Onboarding**: Explain features on introduction. Smart defaults over configuration.
+- **Navigation**: Clear entry/exit points. Back/cancel always available. Breadcrumbs for deep flows.
+
+---
+
+## Quality Pillars
+
+### 1. Frictionless Insight to Action
+
+**Evaluate:** Task completable in ≤3 interactions? Primary action obvious and singular?
+
+**Red flags:** Excessive clicks, multiple competing primary buttons, buried actions, dead ends.
+
+### 2. Quality is Craft
+
+**Evaluate:**
+- Design system compliance: matches Figma specs, uses design tokens
+- Aesthetic direction: distinctive typography, cohesive colors, intentional motion
+- Accessibility: Grade C minimum (WCAG 2.1 A), Grade B ideal (WCAG 2.1 AA)
+
+**Red flags:** Generic AI aesthetics, hardcoded values, implementation doesn't match Figma, broken reflow, missing focus indicators.
+
+### 3. Trustworthy Building
+
+**Evaluate:**
+- AI transparency: disclaimer on AI-generated content
+- Error transparency: actionable error messages
+
+**Red flags:** Missing AI disclaimers, opaque errors without guidance.
+
+---
+
+## Review Output Format
+
+See [references/review-output-format.md](references/review-output-format.md) for the full review template.
+
+## Review Type Modifiers
+
+See [references/review-type-modifiers.md](references/review-type-modifiers.md) for context-specific review focus areas (PR, Creative, Design, Accessibility).
+
+## Quick Checklist
+
+See [references/quick-checklist.md](references/quick-checklist.md) for the pre-approval checklist covering design system compliance, aesthetic quality, frictionless, quality craft, and trustworthy pillars.
+
+## Pattern Examples
+
+See [references/pattern-examples.md](references/pattern-examples.md) for good/bad examples of creative frontend and design system review work.
+
+---
+
+## Acknowledgments
+
+Creative frontend principles inspired by [Anthropic's frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design). Design review principles and quality pillar framework created by [@Quirinevwm](https://github.com/Quirinevwm) for systematic UI evaluation.
+
+
+---
+
+## Toolkit integration
+
+### Delegation — visual critique vs project health
+
+| Concern | Owner skill | What it does | When to use |
+|---------|-------------|--------------|-------------|
+| Project health (tech/mgmt) | `technical-unit-assessment` + `project-assessment-evidence` | Evidence-based 1–5 scoring of repo/platform/infra units; no visual judgment | Repo health, CI, security posture |
+| Design orchestration | `design-assessment` (planned #373, per ADR-0002 Option A) | Orchestrates discovery→inspect→capture→visual/UX/a11y/responsive/DS/AI-slop/perf→findings→roadmap; reuses evidence semantics; fans out to reviewers | Full product design audit |
+| Procedural visual critique | **`frontend-design-review`** (this skill) | Checklist evaluation of hierarchy, design-system compliance, three pillars (frictionless / quality craft / trustworthy), a11y, responsive, polish, AI-slop — outputs severity-ranked findings with citations | PR review, component review, creative frontend kickoff |
+| Distinctive visual direction | `frontend-design` | Studio-lead aesthetic choice, palette/type/layout thesis | New UI creation with intentional style |
+
+**This skill does not score project health.** For project health use `technical-unit-assessment`. For full design product audit, `design-assessment` will delegate to this skill for the procedural visual pass, alongside `web-design-guidelines` (Web Interface Guidelines rules) and browser/accessibility/Figma reviewers.
+
+### Evidence-cited findings — no fake scores
+
+- Never emit numeric scores (e.g. `72/100`) without observable evidence. Use **severity bands** `Blocking / Major / Minor` with `confidence` and `evidence` per finding, reusing `project-assessment-evidence` semantics where applicable.
+- Every issue must cite: **observation** (what you saw — screenshot region, code line, token mismatch), **impact** (user/task consequence), **effort**, and **recommended fix** with design-system link or token reference.
+- Mark indicators as **Not assessed** when screenshot/code unavailable rather than inventing a rating. Vision harness unavailable → text-only heuristic review with lower confidence, explicitly flagged.
+
+### Wiring to `design-assessment` (planned)
+
+This skill is a **delegate of `design-assessment`**. The orchestrator (see #373) will call it during the `VISUAL REVIEW` phase, passing captured screens/states (Playwright) and design-system manifest (Figma tokens / Storybook / Tailwind). It runs in parallel with `accessibility` / `web-design-guidelines` reviewers where the harness supports subagents, otherwise sequentially. Future `design-assessment` will document the full routing.
+
+### Provenance
+
+- Upstream: `microsoft/skills` `.github/skills/frontend-design-review` + `references/*` at `e58528db9a006528a5fb0a2c029790fa6a9a7c0e` (MIT), `LICENSE` vendored here as `LICENSE`.
+- Lock: `capabilities/upstream.lock` `design/frontend-design-review` `provenance_digest` (commit + content_checksum + license), `trust.reviewed_provenance` binding.
+- References vendored: `references/review-output-format.md`, `references/review-type-modifiers.md`, `references/quick-checklist.md`, `references/pattern-examples.md` — byte-identical to upstream at pinned commit.
+- Update: `pull-request` per `resolved_at`; never fetch `main` at runtime.
+

agent_toolkit/data/skills/design/frontend-design-review/references/pattern-examples.md

@@ -0,0 +1,21 @@
+# Pattern Examples
+
+## Creative Frontend (New Interfaces)
+
+### Good: Clear Aesthetic Direction
+- Landing page with brutalist aesthetic: Raw typography (Neue Haas Grotesk), stark black and white, asymmetric layouts
+- Dashboard with organic theme: Rounded forms, earth tones, flowing animations, textured backgrounds
+
+### Bad: Generic AI Aesthetic
+- Overused fonts, cliched color schemes, centered content, generic card layouts
+
+## Design System Review (Existing Work)
+
+### Good: Frictionless
+- Single primary button, clear task completion path
+
+### Good: Quality Craft
+- Uses design system with tokens, distinctive typography, keyboard accessible, tested in themes
+
+### Bad: Quality Craft
+- Hardcoded values, generic overused fonts, poor contrast in dark mode

agent_toolkit/data/skills/design/frontend-design-review/references/quick-checklist.md

@@ -0,0 +1,38 @@
+# Quick Checklist
+
+Before approving any UI work:
+
+## Design System Compliance
+- [ ] Component verified in your Figma Design System
+- [ ] Component implementation checked in your Component Library
+- [ ] Figma Dev Mode specs followed (spacing, tokens, typography)
+- [ ] Design tokens used (no hardcoded hex colors or pixel values)
+- [ ] Token imports verified in code
+- [ ] All variants/states implemented as designed in Figma
+- [ ] Spacing measurements match Figma Dev Mode exactly
+- [ ] Deviations documented with design approval
+
+## Aesthetic Quality (especially for new designs)
+- [ ] Clear conceptual direction (not generic overused fonts and cliched schemes)
+- [ ] Distinctive typography (avoid overused fonts)
+- [ ] Cohesive color palette with CSS variables
+- [ ] Intentional motion (staggered reveals, hover states)
+- [ ] Visual interest through composition (asymmetry, overlap, grid-breaking)
+- [ ] Atmosphere through backgrounds (gradients, textures, patterns)
+- [ ] Implementation complexity matches vision
+
+## Frictionless
+- [ ] Core task completable efficiently (≤3 interactions)
+- [ ] Single clear primary action per view
+
+## Quality Craft
+- [ ] Uses design system components (verified in Figma)
+- [ ] Design tokens used (no hardcoded values)
+- [ ] Distinctive aesthetic (not generic overused fonts/cliched schemes)
+- [ ] Accessible (Grade C minimum, Grade B ideal)
+- [ ] Keyboard navigation complete
+- [ ] Tested in light/dark/high contrast modes
+
+## Trustworthy
+- [ ] AI-generated content has disclaimer
+- [ ] Error messages are actionable

agent_toolkit/data/skills/design/frontend-design-review/references/review-output-format.md

@@ -0,0 +1,68 @@
+# Review Output Format
+
+```
+## Frontend Design Review: [Component/Feature Name]
+
+### Context
+- **Purpose**: What problem does this solve? Who uses it?
+- **Aesthetic Direction**: [If new design: describe the bold conceptual direction]
+- **User Task**: What is the user trying to accomplish?
+
+### Summary
+[Pass/Needs Work/Blocked] - [One-line assessment]
+
+### Design System Compliance (if applicable)
+- [ ] Component exists in [Your Figma Design System]
+- [ ] Component usage verified in [Your Component Library]
+- [ ] Implementation matches Figma specs (spacing, colors, typography)
+- [ ] Uses design tokens (not hardcoded values) - verified in code
+- [ ] All variants match design system options
+- [ ] Spacing verified against Figma Dev Mode
+- [ ] Documented exception if deviating from design system
+
+### Aesthetic Quality (especially for new designs)
+- [ ] Clear conceptual direction (not generic AI aesthetic)
+- [ ] Distinctive typography choices
+- [ ] Cohesive color palette with CSS variables
+- [ ] Intentional motion and micro-interactions
+- [ ] Spatial composition creates visual interest
+- [ ] Backgrounds and visual details add atmosphere
+
+### Pillar Assessment
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Frictionless | 🟢/🟠/⚫ | Task completion efficient, primary action clear |
+| Quality Craft | 🟢/🟠/⚫ | Design system compliant, aesthetic distinctive, accessible |
+| Trustworthy | 🟢/🟠/⚫ | AI disclaimers present, errors actionable |
+
+**Legend:** 🟢 Pass | 🟠 Needs attention | ⚫ Blocking issue
+
+### Design Critique
+**Verdict:** [Pass / Needs work / Reach out to design for more support]
+
+**Rationale:** [Brief explanation based on pillar assessment, design system compliance, and aesthetic direction]
+
+**Criteria:**
+- **Pass**: All pillars 🟢 or minor 🟠 that don't block user tasks, design system compliant, clear aesthetic direction
+- **Needs work**: Multiple 🟠 or any critical workflow issues, design system deviations, or generic aesthetic choices
+- **Reach out to design for more support**: Any ⚫ blocking issues, fundamental pattern problems, major design system violations, or need for aesthetic direction
+
+### Issues
+
+**Blocking (must fix before merge):**
+1. [Pillar/Design System/Aesthetic] Issue description + recommendation with link
+
+**Major (should fix):**
+1. [Pillar/Design System/Aesthetic] Issue description + pattern suggestion with reference
+
+**Minor (consider for refinement):**
+1. [Pillar/Design System/Aesthetic] Issue description + optional improvement
+
+### Recommendations
+- [Design system component to use with link]
+- [Specific code change with design token reference]
+- [Typography recommendation for better aesthetic direction]
+- [Motion/animation suggestion]
+- [Link to design system in Figma]
+```

agent_toolkit/data/skills/design/frontend-design-review/references/review-type-modifiers.md

@@ -0,0 +1,31 @@
+# Review Type Modifiers
+
+Adjust focus based on review context:
+
+## PR Review
+- **Focus**: Code implementation, design system component usage, design token usage, accessibility in code
+- **Check**: Proper imports, design tokens used (not hardcoded), ARIA attributes present
+- **Verify**: Component matches Figma specs using Dev Mode
+
+## Creative Frontend Review
+- **Focus**: Aesthetic direction, typography choices, visual distinctiveness, motion design
+- **Check**: Clear conceptual intent, avoiding generic AI patterns, cohesive execution
+- **Verify**: Implementation complexity matches vision (maximalist needs elaborate code, minimalist needs precision)
+
+## Design Review
+- **Focus**: User flows, interaction patterns, visual hierarchy, navigation, design system alignment
+- **Check**: Task completion path, action hierarchy, progressive disclosure
+- **Verify**: All components exist in design system or have documented exceptions
+
+## Accessibility Audit
+- **Focus**: Deep dive Quality Craft pillar
+- **Check**: Keyboard testing, screen reader testing, contrast ratios, ARIA patterns
+- **Test with**: Screen readers (NVDA, JAWS, Narrator), keyboard only, 200% zoom
+- **Verify**: Design system accessibility features are properly implemented
+
+## Design System Compliance Audit
+- **Focus**: Deep dive design system usage
+- **Check**: All components match Figma specs, design tokens used throughout, no hardcoded values
+- **Test**: Compare implementation side-by-side with Figma using Dev Mode
+- **Verify**: Component variants, spacing, colors, typography all match design system
+- **Document**: Any deviations with rationale and plan to align

agent_toolkit/data/skills/design/web-design-guidelines/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance — accessibility, focus, forms, animation, typography, performance, and anti-patterns. Use when asked to "review my UI", "check accessibility", "audit design", or "review UX".
+origin:
+  type: upstream
+sources:
+  - id: wrapper
+    role: wrapper
+    repository: vercel-labs/agent-skills
+    path: skills/web-design-guidelines
+    ref: 7c180d9044c9ae2b442b567aad4e42a28dd5ed62
+    license: NOASSERTION
+  - id: rules
+    role: rules
+    repository: vercel-labs/web-interface-guidelines
+    path: command.md
+    ref: 4e799d45c17aec1498c269287a83b9dba22b966b
+    license: MIT
+trust:
+  tier: reviewed
+  reviewed_at: '2026-08-11'
+  reviewed_by: ulises-jeremias
+  reviewed_provenance: sha256:7c23f915c756d4322d1b8ca17ed1d57a98cc6accd11a11ae765e288a181ff870
+maintenance:
+  status: active
+  last_activity: '2026-07-24'
+distribution:
+  mode: vendored
+  redistribution_allowed: false
+security:
+  scripts: false
+  shell: false
+  network: false
+  mcp: []
+  hooks: []
+  dangerous_permissions: []
+  cve_policy: not-applicable
+---
+
+# Web Design Guidelines
+
+Review UI code for compliance with Vercel Web Interface Guidelines (frozen vendored snapshot).
+
+This skill is a **frozen, dual-source vendored** adaptation of:
+
+- **Wrapper:** `vercel-labs/agent-skills` `skills/web-design-guidelines` at `7c180d9` (NOASSERTION — no LICENSE file, README declares MIT but not machine-verifiable)
+- **Rules:** `vercel-labs/web-interface-guidelines` `command.md` at `4e799d4` (MIT)
+
+The original upstream `SKILL.md` fetched the guidelines from the `web-interface-guidelines` repository `main` branch at runtime via `WebFetch` — a mutable fetch that violated supply-chain reproducibility. This Toolkit skill **freezes** that content into `references/web-interface-guidelines.md` and removes the network fetch.
+
+## How it works (frozen)
+
+1. Read the **frozen guidelines** from `references/web-interface-guidelines.md` (do not fetch from the network)
+2. Read the specified files (or ask user for files/pattern)
+3. Check against all rules in the frozen guidelines
+4. Output findings in the terse `file:line` format specified in the guidelines
+
+## Usage
+
+When a user provides a file or pattern argument:
+
+1. Read `references/web-interface-guidelines.md` from this skill directory (not the network)
+2. Read the specified source files
+3. Apply all rules from the frozen guidelines
+4. Output findings using the format in the guidelines (grouped by file, `file:line` entries, `✓ pass` if clean)
+
+If no files specified, ask which files to review. Never fetch from the network — use the vendored `references/` copy.
+
+## Source mapping
+
+- `references/web-interface-guidelines.md` — frozen `command.md` at `4e799d4` (MIT), `sha256:eea73cb6dd46fee9faec9973e8e7fe198b5f07ec326f14d276a56e50287e1cab`
+- This `SKILL.md` wrapper body adapted from `vercel-labs/agent-skills` `7c180d9` (NOASSERTION), original `SKILL.md` `sha256:f4647ca866a3accf763777f83e7682954f0187cd6bea7eea0399796652414e8f`; frozen wrapper checksum below is vendored artifact `sha256:...` (Toolkit frontmatter + adapted body)
+
+## Provenance
+
+See `capabilities/upstream.lock` `design/web-design-guidelines` (dual-source, `provenance_digest`), `docs/UPSTREAM.md`, and `docs/adr/0001...` for declaration→lock→vendored→surfaces.
+
+Update strategy: `pull-request` per `capabilities/upstream.lock` `resolved_at`; never `main` fetch.

agent_toolkit/data/skills/design/web-design-guidelines/references/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vercel Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_toolkit/data/skills/design/web-design-guidelines/references/web-interface-guidelines.md

@@ -0,0 +1,180 @@
+---
+description: Review UI code for Vercel Web Interface Guidelines compliance
+argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review these files for compliance: $ARGUMENTS
+
+Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
+
+## Rules
+
+### Accessibility
+
+- Icon-only buttons need `aria-label`
+- Form controls need `<label>` or `aria-label`
+- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
+- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
+- Images need `alt` (or `alt=""` if decorative)
+- Decorative icons need `aria-hidden="true"`
+- Async updates (toasts, validation) need `aria-live="polite"`
+- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
+- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
+- `scroll-margin-top` on heading anchors
+
+### Focus States
+
+- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
+- Never `outline-none` / `outline: none` without focus replacement
+- Use `:focus-visible` over `:focus` (avoid focus ring on click)
+- Group focus with `:focus-within` for compound controls
+
+### Forms
+
+- Inputs need `autocomplete` and meaningful `name`
+- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
+- Never block paste (`onPaste` + `preventDefault`)
+- Labels clickable (`htmlFor` or wrapping control)
+- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
+- Checkboxes/radios: label + control share single hit target (no dead zones)
+- Submit button stays enabled until request starts; spinner during request
+- Errors inline next to fields; focus first error on submit
+- Placeholders end with `…` and show example pattern
+- `autocomplete="off"` on non-auth fields to avoid password manager triggers
+- Warn before navigation with unsaved changes (`beforeunload` or router guard)
+
+### Animation
+
+- Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- Animate `transform`/`opacity` only (compositor-friendly)
+- Never `transition: all`—list properties explicitly
+- Set correct `transform-origin`
+- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
+- Animations interruptible—respond to user input mid-animation
+
+### Typography
+
+- `…` not `...`
+- Curly quotes `"` `"` not straight `"`
+- Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- Loading states end with `…`: `"Loading…"`, `"Saving…"`
+- `font-variant-numeric: tabular-nums` for number columns/comparisons
+- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
+
+### Content Handling
+
+- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
+- Flex children need `min-w-0` to allow text truncation
+- Handle empty states—don't render broken UI for empty strings/arrays
+- User-generated content: anticipate short, average, and very long inputs
+
+### Images
+
+- `<img>` needs explicit `width` and `height` (prevents CLS)
+- Below-fold images: `loading="lazy"`
+- Above-fold critical images: `priority` or `fetchpriority="high"`
+
+### Performance
+
+- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
+- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
+- Batch DOM reads/writes; avoid interleaving
+- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
+- Add `<link rel="preconnect">` for CDN/asset domains
+- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+### Navigation & State
+
+- URL reflects state—filters, tabs, pagination, expanded panels in query params
+- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
+- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
+- Destructive actions need confirmation modal or undo window—never immediate
+
+### Touch & Interaction
+
+- `touch-action: manipulation` (prevents double-tap zoom delay)
+- `-webkit-tap-highlight-color` set intentionally
+- `overscroll-behavior: contain` in modals/drawers/sheets
+- During drag: disable text selection, `inert` on dragged elements
+- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
+
+### Safe Areas & Layout
+
+- Full-bleed layouts need `env(safe-area-inset-*)` for notches
+- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
+- Flex/grid over JS measurement for layout
+
+### Dark Mode & Theming
+
+- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
+- `<meta name="theme-color">` matches page background
+- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
+
+### Locale & i18n
+
+- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
+- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
+- Detect language via `Accept-Language` / `navigator.languages`, not IP
+- Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
+
+### Hydration Safety
+
+- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
+- Date/time rendering: guard against hydration mismatch (server vs client)
+- `suppressHydrationWarning` only where truly needed
+
+### Hover & Interactive States
+
+- Buttons/links need `hover:` state (visual feedback)
+- Interactive states increase contrast: hover/active/focus more prominent than rest
+
+### Content & Copy
+
+- Active voice: "Install the CLI" not "The CLI will be installed"
+- Title Case for headings/buttons (Chicago style)
+- Numerals for counts: "8 deployments" not "eight"
+- Specific button labels: "Save API Key" not "Continue"
+- Error messages include fix/next step, not just problem
+- Second person; avoid first person
+- `&` over "and" where space-constrained
+
+### Anti-patterns (flag these)
+
+- `user-scalable=no` or `maximum-scale=1` disabling zoom
+- `onPaste` with `preventDefault`
+- `transition: all`
+- `outline-none` without focus-visible replacement
+- Inline `onClick` navigation without `<a>`
+- `<div>` or `<span>` with click handlers (should be `<button>`)
+- Images without dimensions
+- Large arrays `.map()` without virtualization
+- Form inputs without labels
+- Icon buttons without `aria-label`
+- Hardcoded date/number formats (use `Intl.*`)
+- `autoFocus` without clear justification
+
+## Output Format
+
+Group by file. Use `file:line` format (VS Code clickable). Terse findings.
+
+```text
+## src/Button.tsx
+
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:18 - input lacks label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all → list properties
+
+## src/Modal.tsx
+
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "..." → "…"
+
+## src/Card.tsx
+
+✓ pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.