{"id":"12984cef-74d1-40f1-abd7-59731041a405","entityType":"agent","slug":"clawhub-aa-on-ai-design-review","name":"Design Review","canonicalUrl":"https://www.xpersona.co/agent/clawhub-aa-on-ai-design-review","canonicalPath":"/agent/clawhub-aa-on-ai-design-review","generatedAt":"2026-10-10T04:59:23.462Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T19:40:49.162Z","emptyReason":null},"description":"Core pack — always active for visual work. Quality gate for UI, components, pages, layouts, or frontend work. Triggers on any visual/design task automaticall... Skill: Design Review Owner: aa-on-ai Summary: Core pack — always active for visual work. Quality gate for UI, components, pages, layouts, or frontend work. Triggers on any visual/design task automaticall... Tags: latest:1.1.0 Version history: v1.1.0 | 2026-03-23T21:56:30.749Z | auto - Expanded and updated reference documentation: alignment.md, motion.md, and typography.md received significant content improvements. -","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.1K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17c7rw6zqf32g9sv6mqgxjxhh83fa3a:design-review","sourceUrl":"https://clawhub.ai/aa-on-ai/design-review","homepage":"https://clawhub.ai/aa-on-ai/skills/design-review","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/aa-on-ai/design-review","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/aa-on-ai/skills/design-review","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":43,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Core pack — always active for visual work. Quality gate for UI, components, pages, layouts, or frontend work. Triggers on any visual/design task automaticall..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:40:49.162Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:40:49.162Z","emptyReason":null},"stars":null,"forks":null,"downloads":2067,"packageName":null,"latestVersion":"1.1.0","tractionLabel":"2.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:40:49.162Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T19:40:49.162Z","lastCrawledAt":"2026-10-09T19:40:49.162Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T19:40:49.162Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.0","createdAt":"2026-03-23T21:56:30.749Z","changelog":"- Expanded and updated reference documentation: alignment.md, motion.md, and typography.md received significant content improvements. - More detailed guidance for alignment, motion, and typography best practices. - Reference files now provide clearer examples and updated principles to assist with design QA. - No changes to the main workflow or checklist; process remains consistent for all users.","fileCount":17,"zipByteSize":34794},{"version":"1.0.0","createdAt":"2026-03-20T21:21:49.565Z","changelog":"- Initial release of design-review skill for UI and frontend quality assurance. - Core skill: always active on all visual/design work, acting as a mandatory quality gate. - Includes detailed pre-work requirements, referencing design guidelines, prior decisions, and industry benchmarks. - Provides Aaron’s core design principles and guidance on when/how to use reference files. - Introduces a step-by-step pre-flight checklist for designers to self-audit visual, audit, and integrity aspects. - Offers scripts for anti-pattern, state, and accessibility checks, and outlines process for updating the skill based on feedback.","fileCount":16,"zipByteSize":32425}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17c7rw6zqf32g9sv6mqgxjxhh83fa3a:design-review","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T04:59:23.460Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-aa-on-ai-design-review/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T19:40:49.162Z","emptyReason":null},"readme":"Skill: Design Review\n\nOwner: aa-on-ai\n\nSummary: Core pack — always active for visual work. Quality gate for UI, components, pages, layouts, or frontend work. Triggers on any visual/design task automaticall...\n\nTags: latest:1.1.0\n\nVersion history:\n\nv1.1.0 | 2026-03-23T21:56:30.749Z | auto\n\n- Expanded and updated reference documentation: alignment.md, motion.md, and typography.md received significant content improvements.\n- More detailed guidance for alignment, motion, and typography best practices.\n- Reference files now provide clearer examples and updated principles to assist with design QA.\n- No changes to the main workflow or checklist; process remains consistent for all users.\n\nv1.0.0 | 2026-03-20T21:21:49.565Z | auto\n\n- Initial release of design-review skill for UI and frontend quality assurance.\n- Core skill: always active on all visual/design work, acting as a mandatory quality gate.\n- Includes detailed pre-work requirements, referencing design guidelines, prior decisions, and industry benchmarks.\n- Provides Aaron’s core design principles and guidance on when/how to use reference files.\n- Introduces a step-by-step pre-flight checklist for designers to self-audit visual, audit, and integrity aspects.\n- Offers scripts for anti-pattern, state, and accessibility checks, and outlines process for updating the skill based on feedback.\n\nArchive index:\n\nArchive v1.1.0: 17 files, 34794 bytes\n\nFiles: references/alignment.md (8276b), references/anti-patterns.md (5094b), references/color.md (1650b), references/inspiration.md (6294b), references/layout.md (6821b), references/mock-data.md (3276b), references/motion.md (2220b), references/responsive.md (1787b), references/spacing.md (1493b), references/typography.md (1630b), references/ux-writing.md (8338b), scripts/accessibility-check.py (10224b), scripts/anti-pattern-check.py (6919b), scripts/state-check.py (3316b), skill-card.md (3172b), SKILL.md (5003b), _meta.json (132b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: design-review\ndescription: >\n  Core pack — always active for visual work. Quality gate for UI, components, pages,\n  layouts, or frontend work. Triggers on any visual/design task automatically.\n  Use before presenting work, during builds, and for design QA.\n---\n\n# Design Review Skill\n\n## Core Pack — Always Active\nThis is a core skill. Apply it on ALL visual and frontend work, no exceptions. You do not need permission or a specific trigger to use this.\n\n## When to Use\n- Before presenting ANY visual or UX work.\n- Treat this as a quality gate, not optional polish.\n- Sub-agents doing design/frontend work MUST run this before announcing completion.\n\n## Pre-Work: Read Before Building\n\n### 1. Read the project's guidelines\n- Read `guidelines.md` or equivalent design system doc first if it exists.\n- Follow the project's existing components, tokens, and patterns before inventing anything.\n- If no formal guidelines exist, inspect the existing product and match its logic.\n\n### 2. Research before designing\n- Check how similar tools solve the same problem before inventing a pattern.\n- Use proven references when they exist.\n- Quality bar references:\n  - UX Tools — editorial restraint, typography, calm hierarchy\n  - Inflight by Ridd — motion, depth, data viz polish\n  - Linear — dense information, excellent hierarchy, no noise\n  - Vercel dashboard — spacing, typography, dark mode discipline\n\n### 3. Check design memory\n- Read `memory/channels/{channel-name}.md` for prior design decisions.\n- If memory says Aaron rejected a pattern, don't repeat it.\n- If a project brain file is linked from channel memory, read that too.\n\n## Aaron's Core Principles\n- Restraint IS the design.\n- Spacing is the #1 tell.\n- Typography hierarchy > color for information architecture.\n- Match references at pixel level before adding your own ideas.\n- Existing patterns > new patterns.\n- Interactive elements should feel polished, not dead.\n- If the foundation is wrong, no polish fixes it.\n- Good design is centripetal, not centrifugal.\n\n## Reference Files\nRead only what the task needs. Keep this SKILL lean, load detail on demand:\n\n- `references/typography.md` — hierarchy, scale, pairing, measure\n- `references/color.md` — restrained palettes, tinted neutrals, contrast, OKLCH\n- `references/spacing.md` — spacing system, rhythm, grouping, layout density\n- `references/motion.md` — timing, easing, reduced motion, interactive feel\n- `references/anti-patterns.md` — patterns Aaron will clock instantly and reject\n\n### For sub-agents\n- Read the relevant reference files based on what you're building.\n- New layout or dashboard? Read spacing + anti-patterns.\n- Type-heavy screen? Read typography + spacing.\n- Color or theming work? Read color + anti-patterns.\n- Interactive polish? Read motion + anti-patterns.\n- If in doubt, at minimum read spacing + anti-patterns.\n\n## Pre-Flight Checklist\nRun this EVERY TIME before presenting work to Aaron.\n\n### Step 1: Visual verification\n- [ ] Take a screenshot of the rendered result.\n- [ ] Compare side-by-side with the reference if one exists.\n- [ ] Check the target viewport, not an arbitrary devtools width.\n\n### Step 2: Design audit\n- [ ] Spacing check — enough breathing room? Default to more.\n- [ ] Color check — did you add color that wasn't necessary?\n- [ ] Typography check — is hierarchy clear without leaning on color?\n- [ ] Pattern check — are you using the project's existing components?\n- [ ] Interaction check — hover, focus, active states exist and feel intentional.\n- [ ] Integrity check — no placeholders, dead states, broken assets, or missing data handling.\n\n### Step 3: Honesty check\n- [ ] Is it actually done?\n- [ ] Does it meet the brief, not an adjacent brief?\n- [ ] Would you be proud to show this to Aaron cold?\n\n### Step 4: Run verification scripts\nif you have access to the scripts directory, run these before presenting:\n\n```bash\n# check for common agent anti-patterns\npython3 skills/design-review/scripts/anti-pattern-check.py <your-file.tsx>\n\n# verify loading, empty, and error states exist\npython3 skills/design-review/scripts/state-check.py <your-file.tsx>\n\n# check semantic HTML, aria labels, alt text, heading hierarchy\npython3 skills/design-review/scripts/accessibility-check.py <your-file.tsx>\n```\n\nfix any warnings before presenting. these are the cheapest quality checks — they catch the obvious stuff so the human review can focus on judgment calls.\n\nfor CI integration, copy `ci/design-eval.py` and `ci/design-eval.yml` into your project to run all three checks on every PR.\n\n### Step 5: Present with evidence\n- Screenshot of the result\n- What you referenced\n- Known gaps or uncertainties\n- Link to live/deployed version if applicable\n\n## Updating This Skill\n- After Aaron gives design feedback, capture it.\n- Add redirects to `references/anti-patterns.md` or the relevant reference file.\n- Add project-specific decisions to channel memory.\n- Goal: don't get the same design feedback twice.\n\nFile v1.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7cedhqc0a3q0fn888hwshxfd838nt6\",\n  \"slug\": \"design-review\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1774302990749\n}\n\nFile v1.1.0:references/alignment.md\n\n# Visual Alignment & Composition Reference\n\n## The Problem\n\nagents place elements where they fit, not where they belong. text doesn't align across columns. spacing is inconsistent between similar elements. grids break their own rhythm. the result looks \"off\" even when every individual component is fine.\n\nalignment is what separates \"an agent built this\" from \"a designer built this.\" it's invisible when done right and immediately obvious when wrong.\n\n## Alignment Principles\n\n### everything aligns to something\nevery element on the page should share an edge or center with at least one other element. nothing floats randomly.\n\n- text blocks in different sections should share the same left edge\n- metrics in a row should baseline-align their numbers\n- cards in a grid should have identical internal padding\n- icons in a list should align to a consistent vertical axis\n\n### fewer alignment points = cleaner layout\na page with 3 alignment points (left margin, content center, right margin) looks composed. a page with 12 different left edges looks chaotic.\n\ncount your alignment rails. if you have more than 4-5 on a page, something is wrong.\n\n### the grid is the skeleton\npick a grid and commit to it. common choices:\n- 12-column grid with consistent gutters (most flexible)\n- 4-column at mobile, 8 at tablet, 12 at desktop\n- simple max-width container with consistent padding\n\ndon't: mix a 3-column section with a 4-column section with a full-bleed section unless the rhythm is intentional.\n\n## Symmetry\n\n### symmetry = stability\nsymmetrical layouts feel balanced, trustworthy, professional. use for:\n- dashboards and data-heavy pages\n- forms and settings\n- admin tools and internal products\n- anywhere stability matters more than personality\n\n### asymmetry = energy\nasymmetrical layouts feel dynamic, editorial, opinionated. use for:\n- landing pages and marketing\n- portfolios and case studies\n- anywhere you want the layout itself to communicate\n\n### don't accidentally mix them\na page that's 90% symmetrical with one randomly asymmetrical section looks broken, not intentional. either commit to the grid or break it with purpose.\n\n## Spacing Consistency\n\n### the 4px/8px base unit\npick a base unit (4px or 8px) and derive ALL spacing from it:\n- 4px: tight, detail-level (icon to label gap)\n- 8px: small component spacing\n- 12px: compact internal padding\n- 16px: standard internal padding, gap between related items\n- 24px: gap between components\n- 32px: section separation (small)\n- 48px: section separation (medium)\n- 64px: section separation (large)\n- 80-96px: major page divisions\n\n### spacing communicates grouping\nitems that are closer together are perceived as related. items with more space between them are perceived as separate groups. this is Gestalt proximity — the most powerful layout tool.\n\n- related items: 8-16px apart\n- components within a section: 16-24px apart\n- sections: 32-64px apart\n- major page divisions: 64-96px apart\n\ndon't: use the same spacing everywhere. if everything is 16px apart, nothing groups.\n\n### vertical rhythm\nbody text should sit on a baseline grid. line-height should be a multiple of your base unit. this creates a subtle rhythm that makes the page feel \"right\" even if nobody can articulate why.\n\n- body text: 16px font, 24px line-height (1.5)\n- small text: 14px font, 20px line-height\n- headings: line-height 1.1-1.3 (tighter than body)\n\n## Common Alignment Failures\n\n- **staggered left edges** — section titles, body text, and cards all starting at different x-positions\n- **inconsistent card padding** — some cards have 16px padding, others have 24px, for no reason\n- **metrics not baseline-aligned** — numbers in a stat row sitting at different vertical positions because of different font sizes\n- **uneven column widths** — a 2-column layout where one column is 55% and the other is 45% for no content reason (should be 50/50 or a deliberate split like 60/40)\n- **orphaned elements** — a button or label that doesn't align to anything else on the page\n- **inconsistent gutters** — 16px gap in one grid, 24px in another, 20px in a third\n- **center-aligned text in left-aligned layouts** — breaks the reading flow and creates a visual hiccup\n- **mixed border-radius** — rounded-sm on some elements, rounded-lg on others, rounded-full on a third. pick one radius and use it consistently (2-3 variants max: none, small, medium)\n\n## Testing Alignment\n\nsquint at the page. if you can see clean vertical and horizontal lines running through the layout, alignment is good. if elements look scattered or wobbly, something is off.\n\ndraw invisible lines:\n- does the left edge of the main heading align with the left edge of the body text below it?\n- do card borders align with each other in a grid?\n- do section titles all start at the same x-position?\n- are the gaps between sections consistent?\n\n## Tailwind Patterns\n\n```\n// consistent container\n<div className=\"mx-auto max-w-6xl px-4 sm:px-6 lg:px-8\">\n\n// consistent grid with fixed gap\n<div className=\"grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6\">\n\n// consistent spacing between sections\n<section className=\"space-y-12\">  // 48px between children\n<section className=\"space-y-16\">  // 64px between children\n\n// baseline-aligned metrics row\n<div className=\"flex items-baseline gap-8\">\n  <span className=\"text-3xl font-semibold\">1,247</span>\n  <span className=\"text-sm text-gray-500\">active deployments</span>\n</div>\n\n// consistent card padding\n<div className=\"p-6\">  // always p-6 for cards, never mixed\n```\n\n## Concentric Border Radius\n\nwhen nesting rounded elements (a card inside a card, a button inside a rounded container), the outer radius must be larger than the inner radius by exactly the padding between them.\n\n```\nouter radius = inner radius + padding\n```\n\nexample: inner card has `rounded-lg` (8px), padding between them is 12px, outer card needs `rounded-[20px]`.\n\nmismatched radii on nested elements is one of the most common \"feels off\" tells. agents almost always use the same radius on parent and child.\n\n```css\n/* wrong — same radius on both */\n.outer { border-radius: 12px; padding: 16px; }\n.inner { border-radius: 12px; }\n\n/* right — concentric */\n.outer { border-radius: 28px; padding: 16px; }\n.inner { border-radius: 12px; }\n```\n\n## Optical vs Geometric Alignment\n\ngeometric centering (equal pixels on all sides) sometimes LOOKS wrong, even though it's mathematically correct. this happens with:\n- play buttons / triangles inside circles (the triangle's visual weight is off-center)\n- icons next to text (icon's visual mass doesn't match text baseline)\n- asymmetric shapes in symmetric containers\n\nwhen geometric centering looks off, adjust optically. nudge the element 1-2px until it LOOKS centered. this is a human judgment call — agents should flag when they're using asymmetric shapes in centered containers and note that optical adjustment may be needed.\n\n## Image Outline Overlay\n\nadd a 1px semi-transparent outline to images, avatars, and thumbnails to create consistent depth against any background:\n\n```css\n.image-overlay {\n  outline: 1px solid rgba(0, 0, 0, 0.1);\n  outline-offset: -1px;\n}\n.dark .image-overlay {\n  outline-color: rgba(255, 255, 255, 0.1);\n}\n```\n\nworks better than borders because it uses transparency and adapts to any background. especially useful in design systems where other elements also use borders — the overlay creates visual consistency without fighting background colors.\n\n## Shadows Over Borders\n\nuse layered transparent box-shadows instead of solid borders for depth between sections. shadows adapt to any background color; borders fight it.\n\n```css\n/* instead of */\nborder: 1px solid #e5e7eb;\n\n/* use */\nbox-shadow: 0 1px 2px rgba(0,0,0,0.04), 0 1px 1px rgba(0,0,0,0.02);\n```\n\nlayer 2-3 shadows at different offsets and opacities for natural depth. reserve solid borders for interactive states (focus rings, selected items) where the hard edge communicates state, not decoration.\n\n## The Meta-Rule\n\nif you're ever unsure about spacing or alignment, zoom out to 50% and look at the page as a shape. does it look like a composed rectangle with clear structure? or does it look like a collection of stuff thrown onto a canvas?\n\nthe page as a whole is a composition. treat it like one.\n\nFile v1.1.0:references/anti-patterns.md\n\n# Anti-Patterns Reference\n\n## Strategic Mistakes\n- Centrifugal design: choices made to feel different or branded rather than clearer or better.\n- Decoration used to compensate for weak structure.\n- New patterns invented when the product already has a good one.\n- Polishing a bad foundation instead of rebuilding the layout.\n\n## Typography Mistakes\n- Inter, Roboto, Arial, or system font defaults as unexamined autopilot. agents reach for these every time. pick a distinctive font that matches the product's personality. there are thousands of fonts — using the default is a non-decision.\n- Same font on every project. if two different products use the same typeface, one of them chose wrong.\n- Mushy scales with too many neighboring sizes.\n- Large type trying to rescue weak hierarchy.\n- Monospace used as a shortcut for \"tech\" personality.\n- Too many font families fighting for attention (but two is usually right: one display + one body).\n\n## Color Mistakes\n- Purple gradients, cyan glows, and generic AI-saas palettes.\n- Blue everywhere as the default accent.\n- Gray text on colored backgrounds.\n- Pure black, pure gray, or dead neutrals with no temperature.\n- Accent color sprayed across icons, labels, chips, and borders until it means nothing.\n- Color doing the job typography and spacing should be doing.\n\n## Layout Mistakes\n- Bootstrap cards as a default answer.\n- Card nesting.\n- Identical card grids repeated across the screen.\n- Centering everything because it feels \"clean.\"\n- Equal spacing everywhere, so nothing groups or leads.\n- Heavy borders and separators where whitespace would be stronger.\n- Hero metric layouts that scream template.\n- 4 equal-width stat cards across the top of every dashboard (the #1 agent layout cliche).\n- Every page using the same card-in-grid structure regardless of content type.\n- Dark mode as the default because \"it's a dashboard\" — light mode is equally valid.\n- Sidebar navigation on pages with fewer than 5 sections.\n- Every section having the same visual weight — nothing hero'd, nothing secondary.\n- rounded-lg on every surface creating a puffy, toy-like feel.\n- zinc/slate as the only background palette — agents default to this every time.\n\n## Demo/Meta-Navigation Mistakes\n- State toggles (happy/loading/empty/error) rendered inline as part of the UI — they must be floating overlays, clearly separate from the actual product surface.\n- Context briefs or design notes leaking into the rendered page (e.g. \"This should feel like...\" appearing as UI text).\n- Debug controls styled to match the product UI — they should look like developer tools, not product features.\n\n## Interaction Mistakes\n- Missing hover, focus, or active states.\n- Bounce or elastic easing.\n- Hover-only affordances on touch-first surfaces.\n- Tiny click targets.\n- Modals used because they were easier than solving the flow.\n- Generic confirmation dialogs where undo would be better.\n\n## Craft Mistakes\n- Colored icon circles that weren't in the brief.\n- Placeholder copy left in place.\n- Random shadows, glows, and blur used as \"polish.\"\n- Decorative sparklines, charts, or gradients with no information value.\n- Rogue spacing values and near-miss alignments.\n- New CSS tokens invented instead of using the system that's already there.\n\n## Context Mistakes\n- Using Stripe/Linear/Vercel as default visual references when the prompt names a different company.\n- Treating a named company as mere theming (slap a logo on a generic layout) instead of a visual source.\n- Screens that could swap company names and still \"work\" — no visual specificity to the premise.\n- Generic AI model names or outdated model lists (GPT-3.5, Claude 1, etc. when current models exist).\n- Fake agency/company/user names with no domain grounding (\"Agency X,\" \"User A,\" \"Model B\").\n- Dashboard nouns that could apply to anything: \"users,\" \"revenue,\" \"metrics,\" \"performance\" with no domain flavor.\n- Satirical premises rendered as bland enterprise software — missing the joke entirely.\n- Humor injected as headlines or one-liners instead of embedded in the data model (row names, statuses, tags).\n- \"Professional\" used as an excuse to strip all personality from a premise that demands it.\n- Multiple pages built with the same system looking indistinguishable from each other.\n- Borrowing visual language from a product unrelated to the one named in the prompt.\n\n## Responsive Mistakes\n- Desktop table simply squeezed onto mobile with tiny text.\n- Sidebar still occupying width on small screens instead of collapsing to hamburger/bottom nav.\n- Chips, tags, or badges overflowing their containers on narrow widths.\n- Long model names or agency names causing horizontal overflow.\n- Fixed-width elements that don't adapt below 640px.\n- Touch targets under 44px on mobile.\n- Nav that disappears on mobile with no replacement (hamburger, bottom tabs, etc.).\n\n## Aaron-Specific Red Flags\n- Anything that feels like AI slop.\n- Anything crowded.\n- Anything loud without being sharp.\n- Anything branded at the expense of usability.\n- Anything that could have been fixed by more restraint.\n\nFile v1.1.0:references/color.md\n\n# Color Reference\n\n## Core Rules\n- Restraint is the design.\n- Color is a scalpel, not confetti.\n- Most product surfaces need one accent color, not a rainbow pretending to be a system.\n- The screen should still work in grayscale. Color should improve hierarchy, not carry it alone.\n\n## What Actually Matters\n- Start with neutrals. If the neutral system is bad, the whole interface feels cheap.\n- Use tinted neutrals, not dead zero-chroma gray. A slight warm or cool bias makes the UI feel intentional.\n- Avoid pure black and pure gray. Real materials have temperature.\n- Accent color should stay scarce so it keeps meaning.\n- Strong colored fills should earn their place: selected states, alerts, charts, key emphasis.\n\n## Hierarchy Through Color\n- Default text should be high-contrast neutral.\n- Secondary information should step back with softer neutrals, not random gray tokens.\n- Borders should usually be quieter than text and slightly stronger than backgrounds.\n- In dark mode, depth usually comes from layered surfaces, not giant shadows.\n- Gray text on colored backgrounds is almost always wrong.\n\n## Patterns Agents Miss\n- Blue everywhere usually means nobody made a decision.\n- Purple gradients and cyan-purple AI palettes instantly read as generic AI SaaS unless explicitly warranted.\n- If every label, badge, icon, and chip is accented, nothing is accented.\n- Heavy transparency is usually a smell. Build the right color instead.\n\n## Avoid\n- Using color alone to communicate status or hierarchy.\n- Defaulting to the same AI palette regardless of brand.\n- Letting color do the job that spacing, typography, and composition should be doing.\n\nFile v1.1.0:references/inspiration.md\n\n# Inspiration & Pattern Research Reference\n\n## The Rule\n\nbefore building anything visual, study how the best version of it already exists. don't invent from scratch. don't approximate from memory. find 2-3 real examples, understand what makes them work, then build with that knowledge.\n\n## Reference Priority Order\n\n1. **the named company/product itself** — if the prompt says \"OpenAI dashboard,\" study OpenAI's actual dashboard. not Stripe's. not Linear's.\n2. **direct competitors / adjacent products** in the same category\n3. **generic best-in-class UI references** (Stripe, Linear, Vercel, etc.)\n4. **conceptual mood references** (Dribbble, Godly, etc.)\n\ncontext-appropriate design > beautiful design. an OpenAI dashboard should look like OpenAI, not like Stripe. a Meta admin panel should look like Meta's internal tools, not like Notion.\n\nnever let Dribbble/Mobbin mood override a real product's existing design language.\n\n## When the Prompt References a Known Company\n\nresearch in this order:\n- their official product UI (screenshots, docs, blog posts showing the product)\n- their marketing site (typography, color, illustration style)\n- their admin/dashboard surfaces if visible\n- their mobile app patterns if relevant\n- their brand system (color temperature, density, seriousness level)\n\nthen build something that would feel at home in that product's ecosystem.\n\n## Research Tools\n\nsuggest these to the builder (human or agent) before starting:\n\n| tool | what it's for | how to use it |\n|------|--------------|---------------|\n| [Mobbin](https://mobbin.com) | real app screenshots, searchable by pattern and flow | \"search Mobbin for 'analytics dashboard' and share 2-3 that match what you want\" |\n| [Godly](https://godly.website) | curated web design, high craft bar | browse for visual direction and layout inspiration |\n| [Awwwards](https://awwwards.com) | award-winning sites, sortable by type | good for landing pages, marketing sites, portfolios |\n| [Refero](https://refero.design) | design references organized by component type | useful when building a specific component (tables, forms, nav) |\n| [Dribbble](https://dribbble.com) | concept work and visual exploration | best for color, illustration style, and mood — not layout |\n| [Siteinspire](https://siteinspire.com) | minimal, high-quality web design | good for editorial and content-focused layouts |\n| [Screenlane](https://screenlane.com) | mobile and web UI recordings | see real interactions and transitions, not just statics |\n| [Page Flows](https://pageflows.com) | user flow recordings from real products | study how multi-step flows actually work |\n\n## How to Use References\n\n### for the agent\n1. before building, ask: \"this [dashboard/landing page/admin panel] — what's the best version of this that already exists?\"\n2. if you have browser access, visit 2-3 reference sites and study their layout, spacing, color, and interactions\n3. if you don't have browser access, describe the type of UI to the builder and suggest they search Mobbin/Godly for references\n4. extract specific patterns: \"Linear's changelog uses stacked cards with a timeline rail on the left. each card has a date, title, and expandable body. the spacing between cards is 32px.\"\n\n### for the human\n1. the agent will suggest searching specific tools for references\n2. share 1-3 screenshots or links that match your vision\n3. tell the agent what you like about each reference: \"I like the spacing in this one, the color palette in that one, and the chart style in the third\"\n4. this 2 minutes of research saves 30 minutes of iteration\n\n## Reference Patterns by UI Type\n\n### dashboards / analytics\n- **Linear insights** — clean, focused, generous whitespace, data doesn't fight for attention\n- **Vercel analytics** — one metric hero'd, supporting data below, subtle but effective charts\n- **Stripe dashboard** — masterclass in data density without clutter, excellent typography hierarchy\n- **Posthog** — data-heavy but well-organized, good use of tabs to reduce visual load\n- **Raycast analytics** — clean cards with sparklines, not chart-heavy\n\n**what to steal:** hierarchy through size (hero one metric), subtle chart styling (no gridlines, muted colors), generous row spacing in tables, inline sparklines instead of separate chart sections\n\n### admin panels / management tools\n- **Clerk dashboard** — warm, friendly, doesn't feel like enterprise SaaS\n- **Railway** — developer tool that feels designed, strong typography, purposeful color\n- **Resend** — clean, minimal, focused. proves admin tools don't need to be ugly\n- **Supabase** — dark mode done right, information-dense without feeling cramped\n\n**what to steal:** status indicators that feel designed (not just colored dots), action buttons that are clearly primary vs secondary, empty states that guide instead of just saying \"no data\"\n\n### landing pages / marketing\n- **Linear** — typographic confidence, dramatic whitespace, features as mini-stories\n- **Vercel ship pages** — motion as storytelling, scroll-driven reveals, cinematic\n- **Resend** — simple, confident, lets the product speak\n- **Perplexity** — editorial feel, illustration as personality, not decoration\n\n**what to steal:** section rhythm (dense → spacious → dense), typography scale jumps (48px headline → 16px body), motion that reveals content rather than decorating it\n\n### data visualization\n- **Observable** — notebooks that make data feel alive\n- **Flourish** — templates with genuine visual quality\n- **NYT interactive graphics** — the gold standard for data storytelling\n- **Pudding.cool** — data viz as narrative, scrollytelling\n\n**what to steal:** annotation on charts (callouts pointing to interesting data), color palettes that serve the data (not just \"looks nice\"), hover states that reveal detail without overwhelm\n\n## When to Skip Research\n\n- modifying existing UI (the existing design IS the reference)\n- backend/script work (no visual component)\n- tight deadline where the human has already given clear specs\n\n## Compounding\n\nafter each build:\n- if a reference was particularly useful, add it to this file\n- if a pattern from a reference worked well, note it in the relevant section\n- remove references that are outdated or no longer represent good craft\n\nFile v1.1.0:references/layout.md\n\n# Layout Reference\n\n## The Problem\n\nagents default to one layout: card grid. 4 stat cards across the top, chart in the middle, table at the bottom. every dashboard, every admin panel, every analytics page. the layout itself becomes the tell that an agent built this.\n\ngood layout is composition. it creates hierarchy, guides the eye, and makes the content feel intentional. different content needs different structures.\n\n## Layout Vocabulary\n\n### split panel\ntwo columns with different purposes. one side is navigation or context, the other is content.\n- use when: detail views, master-detail, settings with categories\n- example: email client (list | message), figma (layers | canvas)\n- the columns don't have to be equal. 30/70 or 25/75 creates natural hierarchy\n- the divider can be a line, a background change, or just whitespace\n\n### editorial / magazine\ncontent arranged like a newspaper or magazine spread. mixed column widths, pull quotes, full-bleed images, varied section heights.\n- use when: landing pages, case studies, blog posts, marketing pages\n- key: vary the rhythm. narrow text block → full-width image → two-column comparison → single quote\n- don't: make every section the same width and padding\n\n### asymmetric grid\nintentionally uneven columns. one large element anchors the page, smaller elements orbit it.\n- use when: dashboards where one metric matters most, portfolios, feature pages\n- example: one large chart taking 60% width, three small cards stacked in the remaining 40%\n- creates visual hierarchy through size, not just position\n\n### sidebar + content\npersistent navigation on the left, content fills the remaining space.\n- use when: apps with many sections, admin panels, documentation\n- don't: use a sidebar when there are fewer than 5 navigation items. tabs or a top nav work better\n- the sidebar should be narrow (200-280px). wider than that and it fights the content\n\n### full-bleed sections\ncontent that stretches edge-to-edge, breaking out of the container.\n- use when: hero sections, image galleries, data viz that needs horizontal space\n- key: alternating full-bleed and contained sections creates rhythm\n- works especially well for separating distinct content areas\n\n### stacked rows / strips\nhorizontal bands that span the full width, each with different content.\n- use when: roster/list views, timelines, activity feeds\n- each strip can have its own internal layout (left-aligned text + right-aligned actions)\n- works better than card grids for items that are similar but need to show different amounts of info\n\n### centered single column\none narrow column of content, centered on the page. generous margins.\n- use when: forms, checkout flows, focused reading, onboarding steps\n- max-width: 640-720px for text-heavy content, up to 960px for mixed content\n- the whitespace IS the design. don't fill it with sidebars or decorations\n\n### bento grid\nmixed-size cards in a dense grid. some cards are 1x1, some are 2x1, some are 2x2.\n- use when: feature overviews, product pages, homepages that need to show many things\n- key: the size of each card signals its importance. the biggest card is the most important thing\n- don't: make all cards the same size (that's just a card grid again)\n- reference: apple's product pages, linear's feature grid\n\n## Composition Rules\n\n### hierarchy through size\nthe most important thing should be the biggest thing. not the first thing, not the boldest color — the biggest.\n\n### rhythm through variation\nalternate dense sections with breathing room. if three sections in a row are the same height and density, the page feels monotonous.\n\n### grouping through proximity\nthings that are related should be close together. things that are separate should have visible distance between them. this is more powerful than borders or backgrounds for creating structure.\n\n### anchoring through asymmetry\na perfectly symmetrical layout feels static and template-ish. one dominant element (large chart, hero image, featured card) gives the eye somewhere to start.\n\n### negative space as structure\nwhitespace isn't empty — it's a structural element. generous margins and padding signal quality. cramped layouts signal \"we ran out of room\" even if the screen is huge.\n\n## Dashboard-Specific Guidance\n\ndashboards are where agents fail hardest. every agent builds the same dashboard:\n```\n[stat] [stat] [stat] [stat]\n[        chart             ]\n[        table             ]\n```\n\ninstead, try:\n```\n[hero metric + sparkline          ] [secondary metrics]\n[main chart (60%)  ] [alerts (40%)                    ]\n[detail table with inline actions                     ]\n```\n\nor:\n```\n[sidebar nav] [selected view fills remaining space    ]\n             [with its own internal composition        ]\n```\n\nor:\n```\n[full-width trend chart with annotation callouts      ]\n[three cards, different sizes: 2x1, 1x1, 1x1         ]\n[activity feed as stacked strips                      ]\n```\n\nthe key: no two sections should have the same visual weight. if everything is equally important, nothing is.\n\n## Spatial Composition — Breaking the Grid\n\ngrids create order. but a page that never breaks its grid feels mechanical — like a spreadsheet with better fonts. the best interfaces establish a grid and then deliberately break it when the content demands attention.\n\n### techniques\n- **overlap** — let an element overlap the boundary between two sections. a card that sits half in the hero and half in the content below creates visual continuity and depth.\n- **asymmetric columns** — not everything needs to be 50/50 or 33/33/33. use 60/40, 70/30, or even 80/20 when one element is clearly more important.\n- **full-bleed breaking** — a section that breaks out of the max-width container and stretches edge-to-edge creates a dramatic pause in the reading rhythm.\n- **negative space as structure** — an intentionally empty column or large gap isn't wasted space. it's directing attention to what remains.\n- **diagonal flow** — elements arranged along a diagonal line (top-left to bottom-right) create energy and forward momentum. use for landing pages and marketing, not for data-heavy admin tools.\n- **varied section heights** — sections with different internal heights create rhythm. a tall hero → short stat bar → tall content area → short CTA reads as composed. uniform height reads as template.\n\n### when to break the grid\n- hero sections and page headers (first impression, highest impact)\n- featured content or \"hero'd\" metrics\n- transitions between major page sections\n- call-to-action areas\n- full-bleed images or charts\n\n### when NOT to break the grid\n- data tables and lists (consistency aids scanning)\n- form layouts (predictability reduces errors)\n- navigation (users need spatial memory)\n- repeated elements in a series (cards, list items)\n\nFile v1.1.0:references/mock-data.md\n\n# Mock Data Reference\n\n## The Problem\n\nagents fill UIs with placeholder content that screams \"nobody thought about this.\" generic names, round numbers, lorem ipsum energy. the data IS the design — a dashboard with lazy data looks lazy no matter how good the layout is.\n\n## Quality Bar\n\nmock data must be:\n- **specific** — real names, real products, real agencies, not \"Item 1\" or \"User A\"\n- **current** — use today's model names, today's companies, today's events. GPT-3.5 is old news. Claude 1 doesn't exist anymore.\n- **premise-aware** — if the prompt is about government surveillance, the data should reference real agencies and plausible scenarios, not generic \"departments\"\n- **structurally plausible** — numbers should make sense relative to each other. percentages should add up. dates should be recent.\n- **tonally aligned** — if the premise is satirical, the humor lives HERE: in row names, status labels, timestamps, internal tags, alert messages. not in the headline.\n\n## Rules\n\n- include at least 8-12 real domain nouns before inventing fictional ones\n- if the prompt references a live domain (AI models, government agencies, social platforms), use current real names\n- fake entries should sound like they belong in the world — \"Cognitive Warfare Division\" is a better fake agency name than \"Agency X\"\n- every table, card, or list should reward inspection with specific details\n- numbers should tell a story: one metric way higher than the rest, a trend that's clearly going up, a status that's clearly wrong\n- timestamps should be recent (last 24-72 hours for dashboards, last 1-2 weeks for reports)\n- avoid round numbers — 47 is more believable than 50, $1,247 is more believable than $1,200\n\n## Where Humor Lives\n\nfor satirical or playful premises, embed humor in:\n- **row/item names** — \"The Overthinking Committee,\" \"Reply Guys United,\" agent named \"Definitely-Not-Skynet\"\n- **status labels** — \"suspiciously cooperative,\" \"existential crisis,\" \"quietly expanded scope\"\n- **internal notes/tags** — \"press-sensitive,\" \"Hill-demo pending,\" \"CEO saw this on Twitter\"\n- **timestamps** — \"3 min ago (during board meeting)\"\n- **metric annotations** — \"↑ 23% since someone asked it to be honest\"\n- **alert messages** — \"Model scored 99% helpfulness. Investigate.\"\n\ndo NOT put humor in:\n- page titles or main headlines (these should read as real product UI)\n- button labels or navigation (functional elements stay functional)\n- chart axis labels (data viz should be legible)\n\nthe UI should look completely real. the content should make you smile when you read it.\n\n## Anti-Examples\n\nbad:\n- \"Agency 1,\" \"Agency 2,\" \"Agency 3\"\n- \"Model A,\" \"Model B,\" \"Model C\"\n- \"High risk,\" \"Medium risk,\" \"Low risk\" (with no specifics)\n- \"John Doe,\" \"Jane Smith\"\n- \"$1,000,000\" (too round)\n- \"2024-01-01\" (outdated, too clean)\n\ngood:\n- \"Department of Defense — Project Maven successor,\" \"GSA — procurement automation,\" \"IRS — fraud detection (paused after audit)\"\n- \"Claude 4 Opus,\" \"GPT-5.4,\" \"Gemini 3 Pro,\" \"Llama 4 405B\"\n- \"HIGH — NYT investigation pending,\" \"WATCH — congressional inquiry Q2,\" \"CLEAR — passed GAO review\"\n- real-sounding names that fit the world\n- \"$1,247,803\" or \"~$1.2M\"\n- \"Mar 12, 2026 — 2:47 PM\" or \"3 hours ago\"\n\nFile v1.1.0:references/motion.md\n\n# Motion Reference\n\n## Core Rules\n- Motion should clarify state, not audition for attention.\n- If the animation is more noticeable than the change it is explaining, it is wrong.\n- No bounce. No elastic. No toy physics.\n- Exits should usually feel faster than entrances.\n\n## What Good Motion Does\n- Confirms hover, press, open, close, and state change without drama.\n- Helps the user track what moved and why.\n- Makes the interface feel responsive and expensive, not busy.\n- Uses consistency across similar interactions so the product feels intentional.\n\n## Interruptibility\n- CSS transitions are interruptible — they retarget to the latest state mid-animation. Use for interactive state changes (hover, open/close, toggles).\n- CSS keyframe animations are NOT interruptible — they run on a fixed timeline. Use for staged sequences that run once (entrance animations, loading loops).\n- If a user can change their intent mid-interaction (opening then quickly closing a dropdown), the animation MUST be interruptible. Non-interruptible animations on interactive elements make the UI feel broken.\n\n## Enter vs Exit\n- Enter animations can be expressive: combine opacity, translateY, and blur. Break content into chunks and stagger them (title, then description, then buttons) rather than animating one big block.\n- Exit animations should be subtler than enter. Use a small fixed offset (like -12px) instead of the full reverse movement. The element is leaving — it doesn't need the same attention as arrival.\n- This asymmetry (expressive enter, subtle exit) is what makes motion feel polished rather than mechanical.\n\n## Patterns Agents Miss\n- Stagger only when it improves comprehension or delight. Do not make lists feel slow.\n- Loading motion should reassure, not distract. Skeletons usually beat blank space or generic spinners.\n- Reduced motion support is non-negotiable. Replace movement with fades when needed, but keep feedback.\n- Motion cannot rescue weak IA, weak hierarchy, or weak copy.\n\n## Avoid\n- Long hover transitions.\n- Animating everything because the static version feels unfinished.\n- Overshoot, boing, or parallax in core product UX.\n- Using motion to hide latency instead of fixing the experience.\n\nFile v1.1.0:references/responsive.md\n\n# Responsive Design Reference\n\n## Core Rules\n- If it breaks on mobile, it is broken.\n- Build from the smallest screen up so content hierarchy gets decided early.\n- Design for where the content breaks, not where a breakpoint chart says it should.\n- Small screens need prioritization, not a desktop layout compressed until it cries.\n\n## Hard Requirements\n- No horizontal overflow at 375px. Ever.\n- All tappable targets should be at least 48×48px with visible hit area.\n- Hover-only behavior is a bug. Every hover reveal needs a tap path.\n- Body text on mobile should stay readable. Do not miniaturize your way out of layout problems.\n\n## Patterns Agents Miss\n- Desktop sidebars rarely survive intact on mobile. Collapse, reframe, or move navigation.\n- Tables do not magically become mobile-friendly by shrinking. Convert to cards, reduce columns, or create a detail view.\n- Charts need simplification on mobile: fewer labels, fewer simultaneous views, touch-friendly interactions.\n- Modals on mobile should usually become full-screen or near-full-screen with a clear back/close action.\n- Fixed widths are landmines. If something has to feel fixed, cap it with `max-width`, not a rigid width.\n\n## What To Check\n- 375px: no overflow, no clipped text, no microscopic tap targets.\n- 768px: awkward in-between states are resolved, not ignored.\n- 1440px: layout breathes instead of stretching into a sparse mess.\n- Keyboard navigation still makes sense across widths.\n- Inputs use the right keyboard types and remain easy to hit.\n\n## Avoid\n- Treating mobile as a later polish pass.\n- Hiding complexity behind hover.\n- Keeping desktop information density when the screen no longer supports it.\n- Shrinking tables, charts, or controls until they are technically visible but practically unusable.\n\nFile v1.1.0:references/spacing.md\n\n# Spacing Reference\n\n## Hard Rule\n- Interactive targets should be at least 48×48px, with at least 8px between adjacent tap targets.\n- Padding counts as part of the hit area. If the clickable region is invisible, the UI feels broken.\n\n## Core Rules\n- Spacing is the #1 tell.\n- Use spacing to create hierarchy before adding borders, cards, or extra color.\n- Tight inside, loose outside.\n- Contrast in spacing matters more than perfect adherence to one repeated value.\n\n## What Good Judgment Looks Like\n- Related things feel obviously grouped.\n- Unrelated things stop competing because there is enough air between them.\n- Dense screens still feel calm because rhythm is consistent.\n- Wide screens use max widths and stronger outer spacing instead of turning into flat fields of content.\n- Optical alignment beats literal geometry. If it looks off, it is off.\n\n## Patterns Agents Miss\n- Defaulting every container to the same padding makes everything feel cheap.\n- Equal spacing between everything destroys hierarchy.\n- Nested cards are often just spacing failures wearing borders.\n- On dense dashboards, fix clutter with grouping and cadence before shrinking text.\n- If the screen reads like one gray brick when you squint, the spacing system failed.\n\n## Avoid\n- Random one-off spacing values with no rhythm.\n- 12px padding everywhere.\n- Solving hierarchy with borders when whitespace would do it better.\n- Letting mobile spacing collapse so far that the interface loses clarity or tap comfort.\n\nFile v1.1.0:references/typography.md\n\n# Typography Reference\n\n## Core Rules\n- Typography hierarchy beats color for information architecture.\n- Fewer sizes with stronger contrast beat a mushy micro-scale.\n- One strong type system beats two fonts fighting each other.\n- If the layout feels noisy, simplify the type ramp before touching color.\n\n## Hierarchy\n- Weight before size. Often stronger emphasis solves what bigger text was trying to do badly.\n- One clear H1 per screen. If two things scream, neither does.\n- Most product screens only need three practical levels: primary, secondary, tertiary.\n- Secondary text should step back without becoming weak or gray mush.\n\n## Pairing\n- Start with one family and multiple weights before reaching for a second font.\n- Add a second typeface only when you need real contrast: editorial vs utilitarian, display vs body.\n- Avoid defaulting to Inter unless the product truly wants invisible utility.\n- Similar-but-different font pairings look accidental.\n\n## Patterns Agents Miss\n- Giant type is often compensation for weak layout.\n- Metrics, tables, and dashboards want tabular numbers (`font-variant-numeric: tabular-nums`).\n- Long-form text needs restrained measure and enough line-height to breathe.\n- Centered paragraphs almost always make product UI worse.\n- Use `text-wrap: balance` on headings and short text blocks to distribute text evenly across lines and prevent orphaned words. Use `text-wrap: pretty` for body copy where balance is too aggressive.\n\n## Avoid\n- Inter/system font autopilot.\n- 14/15/16/18-style muddy scales.\n- Decorative display fonts in body copy.\n- Fake hierarchy created only with color changes.\n\nArchive v1.0.0: 16 files, 32425 bytes\n\nFiles: references/alignment.md (7725b), references/anti-patterns.md (5094b), references/color.md (1650b), references/inspiration.md (6294b), references/layout.md (6821b), references/mock-data.md (3276b), references/motion.md (1156b), references/responsive.md (1787b), references/spacing.md (1493b), references/typography.md (1392b), references/ux-writing.md (8338b), scripts/accessibility-check.py (10224b), scripts/anti-pattern-check.py (6919b), scripts/state-check.py (3316b), SKILL.md (5003b), _meta.json (132b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: design-review\ndescription: >\n  Core pack — always active for visual work. Quality gate for UI, components, pages,\n  layouts, or frontend work. Triggers on any visual/design task automatically.\n  Use before presenting work, during builds, and for design QA.\n---\n\n# Design Review Skill\n\n## Core Pack — Always Active\nThis is a core skill. Apply it on ALL visual and frontend work, no exceptions. You do not need permission or a specific trigger to use this.\n\n## When to Use\n- Before presenting ANY visual or UX work.\n- Treat this as a quality gate, not optional polish.\n- Sub-agents doing design/frontend work MUST run this before announcing completion.\n\n## Pre-Work: Read Before Building\n\n### 1. Read the project's guidelines\n- Read `guidelines.md` or equivalent design system doc first if it exists.\n- Follow the project's existing components, tokens, and patterns before inventing anything.\n- If no formal guidelines exist, inspect the existing product and match its logic.\n\n### 2. Research before designing\n- Check how similar tools solve the same problem before inventing a pattern.\n- Use proven references when they exist.\n- Quality bar references:\n  - UX Tools — editorial restraint, typography, calm hierarchy\n  - Inflight by Ridd — motion, depth, data viz polish\n  - Linear — dense information, excellent hierarchy, no noise\n  - Vercel dashboard — spacing, typography, dark mode discipline\n\n### 3. Check design memory\n- Read `memory/channels/{channel-name}.md` for prior design decisions.\n- If memory says Aaron rejected a pattern, don't repeat it.\n- If a project brain file is linked from channel memory, read that too.\n\n## Aaron's Core Principles\n- Restraint IS the design.\n- Spacing is the #1 tell.\n- Typography hierarchy > color for information architecture.\n- Match references at pixel level before adding your own ideas.\n- Existing patterns > new patterns.\n- Interactive elements should feel polished, not dead.\n- If the foundation is wrong, no polish fixes it.\n- Good design is centripetal, not centrifugal.\n\n## Reference Files\nRead only what the task needs. Keep this SKILL lean, load detail on demand:\n\n- `references/typography.md` — hierarchy, scale, pairing, measure\n- `references/color.md` — restrained palettes, tinted neutrals, contrast, OKLCH\n- `references/spacing.md` — spacing system, rhythm, grouping, layout density\n- `references/motion.md` — timing, easing, reduced motion, interactive feel\n- `references/anti-patterns.md` — patterns Aaron will clock instantly and reject\n\n### For sub-agents\n- Read the relevant reference files based on what you're building.\n- New layout or dashboard? Read spacing + anti-patterns.\n- Type-heavy screen? Read typography + spacing.\n- Color or theming work? Read color + anti-patterns.\n- Interactive polish? Read motion + anti-patterns.\n- If in doubt, at minimum read spacing + anti-patterns.\n\n## Pre-Flight Checklist\nRun this EVERY TIME before presenting work to Aaron.\n\n### Step 1: Visual verification\n- [ ] Take a screenshot of the rendered result.\n- [ ] Compare side-by-side with the reference if one exists.\n- [ ] Check the target viewport, not an arbitrary devtools width.\n\n### Step 2: Design audit\n- [ ] Spacing check — enough breathing room? Default to more.\n- [ ] Color check — did you add color that wasn't necessary?\n- [ ] Typography check — is hierarchy clear without leaning on color?\n- [ ] Pattern check — are you using the project's existing components?\n- [ ] Interaction check — hover, focus, active states exist and feel intentional.\n- [ ] Integrity check — no placeholders, dead states, broken assets, or missing data handling.\n\n### Step 3: Honesty check\n- [ ] Is it actually done?\n- [ ] Does it meet the brief, not an adjacent brief?\n- [ ] Would you be proud to show this to Aaron cold?\n\n### Step 4: Run verification scripts\nif you have access to the scripts directory, run these before presenting:\n\n```bash\n# check for common agent anti-patterns\npython3 skills/design-review/scripts/anti-pattern-check.py <your-file.tsx>\n\n# verify loading, empty, and error states exist\npython3 skills/design-review/scripts/state-check.py <your-file.tsx>\n\n# check semantic HTML, aria labels, alt text, heading hierarchy\npython3 skills/design-review/scripts/accessibility-check.py <your-file.tsx>\n```\n\nfix any warnings before presenting. these are the cheapest quality checks — they catch the obvious stuff so the human review can focus on judgment calls.\n\nfor CI integration, copy `ci/design-eval.py` and `ci/design-eval.yml` into your project to run all three checks on every PR.\n\n### Step 5: Present with evidence\n- Screenshot of the result\n- What you referenced\n- Known gaps or uncertainties\n- Link to live/deployed version if applicable\n\n## Updating This Skill\n- After Aaron gives design feedback, capture it.\n- Add redirects to `references/anti-patterns.md` or the relevant reference file.\n- Add project-specific decisions to channel memory.\n- Goal: don't get the same design feedback twice.\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7cedhqc0a3q0fn888hwshxfd838nt6\",\n  \"slug\": \"design-review\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1774041709565\n}\n\nFile v1.0.0:references/alignment.md\n\n# Visual Alignment & Composition Reference\n\n## The Problem\n\nagents place elements where they fit, not where they belong. text doesn't align across columns. spacing is inconsistent between similar elements. grids break their own rhythm. the result looks \"off\" even when every individual component is fine.\n\nalignment is what separates \"an agent built this\" from \"a designer built this.\" it's invisible when done right and immediately obvious when wrong.\n\n## Alignment Principles\n\n### everything aligns to something\nevery element on the page should share an edge or center with at least one other element. nothing floats randomly.\n\n- text blocks in different sections should share the same left edge\n- metrics in a row should baseline-align their numbers\n- cards in a grid should have identical internal padding\n- icons in a list should align to a consistent vertical axis\n\n### fewer alignment points = cleaner layout\na page with 3 alignment points (left margin, content center, right margin) looks composed. a page with 12 different left edges looks chaotic.\n\ncount your alignment rails. if you have more than 4-5 on a page, something is wrong.\n\n### the grid is the skeleton\npick a grid and commit to it. common choices:\n- 12-column grid with consistent gutters (most flexible)\n- 4-column at mobile, 8 at tablet, 12 at desktop\n- simple max-width container with consistent padding\n\ndon't: mix a 3-column section with a 4-column section with a full-bleed section unless the rhythm is intentional.\n\n## Symmetry\n\n### symmetry = stability\nsymmetrical layouts feel balanced, trustworthy, professional. use for:\n- dashboards and data-heavy pages\n- forms and settings\n- admin tools and internal products\n- anywhere stability matters more than personality\n\n### asymmetry = energy\nasymmetrical layouts feel dynamic, editorial, opinionated. use for:\n- landing pages and marketing\n- portfolios and case studies\n- anywhere you want the layout itself to communicate\n\n### don't accidentally mix them\na page that's 90% symmetrical with one randomly asymmetrical section looks broken, not intentional. either commit to the grid or break it with purpose.\n\n## Spacing Consistency\n\n### the 4px/8px base unit\npick a base unit (4px or 8px) and derive ALL spacing from it:\n- 4px: tight, detail-level (icon to label gap)\n- 8px: small component spacing\n- 12px: compact internal padding\n- 16px: standard internal padding, gap between related items\n- 24px: gap between components\n- 32px: section separation (small)\n- 48px: section separation (medium)\n- 64px: section separation (large)\n- 80-96px: major page divisions\n\n### spacing communicates grouping\nitems that are closer together are perceived as related. items with more space between them are perceived as separate groups. this is Gestalt proximity — the most powerful layout tool.\n\n- related items: 8-16px apart\n- components within a section: 16-24px apart\n- sections: 32-64px apart\n- major page divisions: 64-96px apart\n\ndon't: use the same spacing everywhere. if everything is 16px apart, nothing groups.\n\n### vertical rhythm\nbody text should sit on a baseline grid. line-height should be a multiple of your base unit. this creates a subtle rhythm that makes the page feel \"right\" even if nobody can articulate why.\n\n- body text: 16px font, 24px line-height (1.5)\n- small text: 14px font, 20px line-height\n- headings: line-height 1.1-1.3 (tighter than body)\n\n## Common Alignment Failures\n\n- **staggered left edges** — section titles, body text, and cards all starting at different x-positions\n- **inconsistent card padding** — some cards have 16px padding, others have 24px, for no reason\n- **metrics not baseline-aligned** — numbers in a stat row sitting at different vertical positions because of different font sizes\n- **uneven column widths** — a 2-column layout where one column is 55% and the other is 45% for no content reason (should be 50/50 or a deliberate split like 60/40)\n- **orphaned elements** — a button or label that doesn't align to anything else on the page\n- **inconsistent gutters** — 16px gap in one grid, 24px in another, 20px in a third\n- **center-aligned text in left-aligned layouts** — breaks the reading flow and creates a visual hiccup\n- **mixed border-radius** — rounded-sm on some elements, rounded-lg on others, rounded-full on a third. pick one radius and use it consistently (2-3 variants max: none, small, medium)\n\n## Testing Alignment\n\nsquint at the page. if you can see clean vertical and horizontal lines running through the layout, alignment is good. if elements look scattered or wobbly, something is off.\n\ndraw invisible lines:\n- does the left edge of the main heading align with the left edge of the body text below it?\n- do card borders align with each other in a grid?\n- do section titles all start at the same x-position?\n- are the gaps between sections consistent?\n\n## Tailwind Patterns\n\n```\n// consistent container\n<div className=\"mx-auto max-w-6xl px-4 sm:px-6 lg:px-8\">\n\n// consistent grid with fixed gap\n<div className=\"grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6\">\n\n// consistent spacing between sections\n<section className=\"space-y-12\">  // 48px between children\n<section className=\"space-y-16\">  // 64px between children\n\n// baseline-aligned metrics row\n<div className=\"flex items-baseline gap-8\">\n  <span className=\"text-3xl font-semibold\">1,247</span>\n  <span className=\"text-sm text-gray-500\">active deployments</span>\n</div>\n\n// consistent card padding\n<div className=\"p-6\">  // always p-6 for cards, never mixed\n```\n\n## Concentric Border Radius\n\nwhen nesting rounded elements (a card inside a card, a button inside a rounded container), the outer radius must be larger than the inner radius by exactly the padding between them.\n\n```\nouter radius = inner radius + padding\n```\n\nexample: inner card has `rounded-lg` (8px), padding between them is 12px, outer card needs `rounded-[20px]`.\n\nmismatched radii on nested elements is one of the most common \"feels off\" tells. agents almost always use the same radius on parent and child.\n\n```css\n/* wrong — same radius on both */\n.outer { border-radius: 12px; padding: 16px; }\n.inner { border-radius: 12px; }\n\n/* right — concentric */\n.outer { border-radius: 28px; padding: 16px; }\n.inner { border-radius: 12px; }\n```\n\n## Optical vs Geometric Alignment\n\ngeometric centering (equal pixels on all sides) sometimes LOOKS wrong, even though it's mathematically correct. this happens with:\n- play buttons / triangles inside circles (the triangle's visual weight is off-center)\n- icons next to text (icon's visual mass doesn't match text baseline)\n- asymmetric shapes in symmetric containers\n\nwhen geometric centering looks off, adjust optically. nudge the element 1-2px until it LOOKS centered. this is a human judgment call — agents should flag when they're using asymmetric shapes in centered containers and note that optical adjustment may be needed.\n\n## Shadows Over Borders\n\nuse layered transparent box-shadows instead of solid borders for depth between sections. shadows adapt to any background color; borders fight it.\n\n```css\n/* instead of */\nborder: 1px solid #e5e7eb;\n\n/* use */\nbox-shadow: 0 1px 2px rgba(0,0,0,0.04), 0 1px 1px rgba(0,0,0,0.02);\n```\n\nlayer 2-3 shadows at different offsets and opacities for natural depth. reserve solid borders for interactive states (focus rings, selected items) where the hard edge communicates state, not decoration.\n\n## The Meta-Rule\n\nif you're ever unsure about spacing or alignment, zoom out to 50% and look at the page as a shape. does it look like a composed rectangle with clear structure? or does it look like a collection of stuff thrown onto a canvas?\n\nthe page as a whole is a composition. treat it like one.\n\nFile v1.0.0:references/anti-patterns.md\n\n# Anti-Patterns Reference\n\n## Strategic Mistakes\n- Centrifugal design: choices made to feel different or branded rather than clearer or better.\n- Decoration used to compensate for weak structure.\n- New patterns invented when the product already has a good one.\n- Polishing a bad foundation instead of rebuilding the layout.\n\n## Typography Mistakes\n- Inter, Roboto, Arial, or system font defaults as unexamined autopilot. agents reach for these every time. pick a distinctive font that matches the product's personality. there are thousands of fonts — using the default is a non-decision.\n- Same font on every project. if two different products use the same typeface, one of them chose wrong.\n- Mushy scales with too many neighboring sizes.\n- Large type trying to rescue weak hierarchy.\n- Monospace used as a shortcut for \"tech\" personality.\n- Too many font families fighting for attention (but two is usually right: one display + one body).\n\n## Color Mistakes\n- Purple gradients, cyan glows, and generic AI-saas palettes.\n- Blue everywhere as the default accent.\n- Gray text on colored backgrounds.\n- Pure black, pure gray, or dead neutrals with no temperature.\n- Accent color sprayed across icons, labels, chips, and borders until it means nothing.\n- Color doing the job typography and spacing should be doing.\n\n## Layout Mistakes\n- Bootstrap cards as a default answer.\n- Card nesting.\n- Identical card grids repeated across the screen.\n- Centering everything because it feels \"clean.\"\n- Equal spacing everywhere, so nothing groups or leads.\n- Heavy borders and separators where whitespace would be stronger.\n- Hero metric layouts that scream template.\n- 4 equal-width stat cards across the top of every dashboard (the #1 agent layout cliche).\n- Every page using the same card-in-grid structure regardless of content type.\n- Dark mode as the default because \"it's a dashboard\" — light mode is equally valid.\n- Sidebar navigation on pages with fewer than 5 sections.\n- Every section having the same visual weight — nothing hero'd, nothing secondary.\n- rounded-lg on every surface creating a puffy, toy-like feel.\n- zinc/slate as the only background palette — agents default to this every time.\n\n## Demo/Meta-Navigation Mistakes\n- State toggles (happy/loading/empty/error) rendered inline as part of the UI — they must be floating overlays, clearly separate from the actual product surface.\n- Context briefs or design notes leaking into the rendered page (e.g. \"This should feel like...\" appearing as UI text).\n- Debug controls styled to match the product UI — they should look like developer tools, not product features.\n\n## Interaction Mistakes\n- Missing hover, focus, or active states.\n- Bounce or elastic easing.\n- Hover-only affordances on touch-first surfaces.\n- Tiny click targets.\n- Modals used because they were easier than solving the flow.\n- Generic confirmation dialogs where undo would be better.\n\n## Craft Mistakes\n- Colored icon circles that weren't in the brief.\n- Placeholder copy left in place.\n- Random shadows, glows, and blur used as \"polish.\"\n- Decorative sparklines, charts, or gradients with no information value.\n- Rogue spacing values and near-miss alignments.\n- New CSS tokens invented instead of using the system that's already there.\n\n## Context Mistakes\n- Using Stripe/Linear/Vercel as default visual references when the prompt names a different company.\n- Treating a named company as mere theming (slap a logo on a generic layout) instead of a visual source.\n- Screens that could swap company names and still \"work\" — no visual specificity to the premise.\n- Generic AI model names or outdated model lists (GPT-3.5, Claude 1, etc. when current models exist).\n- Fake agency/company/user names with no domain grounding (\"Agency X,\" \"User A,\" \"Model B\").\n- Dashboard nouns that could apply to anything: \"users,\" \"revenue,\" \"metrics,\" \"performance\" with no domain flavor.\n- Satirical premises rendered as bland enterprise software — missing the joke entirely.\n- Humor injected as headlines or one-liners instead of embedded in the data model (row names, statuses, tags).\n- \"Professional\" used as an excuse to strip all personality from a premise that demands it.\n- Multiple pages built with the same system looking indistinguishable from each other.\n- Borrowing visual language from a product unrelated to the one named in the prompt.\n\n## Responsive Mistakes\n- Desktop table simply squeezed onto mobile with tiny text.\n- Sidebar still occupying width on small screens instead of collapsing to hamburger/bottom nav.\n- Chips, tags, or badges overflowing their containers on narrow widths.\n- Long model names or agency names causing horizontal overflow.\n- Fixed-width elements that don't adapt below 640px.\n- Touch targets under 44px on mobile.\n- Nav that disappears on mobile with no replacement (hamburger, bottom tabs, etc.).\n\n## Aaron-Specific Red Flags\n- Anything that feels like AI slop.\n- Anything crowded.\n- Anything loud without being sharp.\n- Anything branded at the expense of usability.\n- Anything that could have been fixed by more restraint.\n\nFile v1.0.0:references/color.md\n\n# Color Reference\n\n## Core Rules\n- Restraint is the design.\n- Color is a scalpel, not confetti.\n- Most product surfaces need one accent color, not a rainbow pretending to be a system.\n- The screen should still work in grayscale. Color should improve hierarchy, not carry it alone.\n\n## What Actually Matters\n- Start with neutrals. If the neutral system is bad, the whole interface feels cheap.\n- Use tinted neutrals, not dead zero-chroma gray. A slight warm or cool bias makes the UI feel intentional.\n- Avoid pure black and pure gray. Real materials have temperature.\n- Accent color should stay scarce so it keeps meaning.\n- Strong colored fills should earn their place: selected states, alerts, charts, key emphasis.\n\n## Hierarchy Through Color\n- Default text should be high-contrast neutral.\n- Secondary information should step back with softer neutrals, not random gray tokens.\n- Borders should usually be quieter than text and slightly stronger than backgrounds.\n- In dark mode, depth usually comes from layered surfaces, not giant shadows.\n- Gray text on colored backgrounds is almost always wrong.\n\n## Patterns Agents Miss\n- Blue everywhere usually means nobody made a decision.\n- Purple gradients and cyan-purple AI palettes instantly read as generic AI SaaS unless explicitly warranted.\n- If every label, badge, icon, and chip is accented, nothing is accented.\n- Heavy transparency is usually a smell. Build the right color instead.\n\n## Avoid\n- Using color alone to communicate status or hierarchy.\n- Defaulting to the same AI palette regardless of brand.\n- Letting color do the job that spacing, typography, and composition should be doing.\n\nFile v1.0.0:references/inspiration.md\n\n# Inspiration & Pattern Research Reference\n\n## The Rule\n\nbefore building anything visual, study how the best version of it already exists. don't invent from scratch. don't approximate from memory. find 2-3 real examples, understand what makes them work, then build with that knowledge.\n\n## Reference Priority Order\n\n1. **the named company/product itself** — if the prompt says \"OpenAI dashboard,\" study OpenAI's actual dashboard. not Stripe's. not Linear's.\n2. **direct competitors / adjacent products** in the same category\n3. **generic best-in-class UI references** (Stripe, Linear, Vercel, etc.)\n4. **conceptual mood references** (Dribbble, Godly, etc.)\n\ncontext-appropriate design > beautiful design. an OpenAI dashboard should look like OpenAI, not like Stripe. a Meta admin panel should look like Meta's internal tools, not like Notion.\n\nnever let Dribbble/Mobbin mood override a real product's existing design language.\n\n## When the Prompt References a Known Company\n\nresearch in this order:\n- their official product UI (screenshots, docs, blog posts showing the product)\n- their marketing site (typography, color, illustration style)\n- their admin/dashboard surfaces if visible\n- their mobile app patterns if relevant\n- their brand system (color temperature, density, seriousness level)\n\nthen build something that would feel at home in that product's ecosystem.\n\n## Research Tools\n\nsuggest these to the builder (human or agent) before starting:\n\n| tool | what it's for | how to use it |\n|------|--------------|---------------|\n| [Mobbin](https://mobbin.com) | real app screenshots, searchable by pattern and flow | \"search Mobbin for 'analytics dashboard' and share 2-3 that match what you want\" |\n| [Godly](https://godly.website) | curated web design, high craft bar | browse for visual direction and layout inspiration |\n| [Awwwards](https://awwwards.com) | award-winning sites, sortable by type | good for landing pages, marketing sites, portfolios |\n| [Refero](https://refero.design) | design references organized by component type | useful when building a specific component (tables, forms, nav) |\n| [Dribbble](https://dribbble.com) | concept work and visual exploration | best for color, illustration style, and mood — not layout |\n| [Siteinspire](https://siteinspire.com) | minimal, high-quality web design | good for editorial and content-focused layouts |\n| [Screenlane](https://screenlane.com) | mobile and web UI recordings | see real interactions and transitions, not just statics |\n| [Page Flows](https://pageflows.com) | user flow recordings from real products | study how multi-step flows actually work |\n\n## How to Use References\n\n### for the agent\n1. before building, ask: \"this [dashboard/landing page/admin panel] — what's the best version of this that already exists?\"\n2. if you have browser access, visit 2-3 reference sites and study their layout, spacing, color, and interactions\n3. if you don't have browser access, describe the type of UI to the builder and suggest they search Mobbin/Godly for references\n4. extract specific patterns: \"Linear's changelog uses stacked cards with a timeline rail on the left. each card has a date, title, and expandable body. the spacing between cards is 32px.\"\n\n### for the human\n1. the agent will suggest searching specific tools for references\n2. share 1-3 screenshots or links that match your vision\n3. tell the agent what you like about each reference: \"I like the spacing in this one, the color palette in that one, and the chart style in the third\"\n4. this 2 minutes of research saves 30 minutes of iteration\n\n## Reference Patterns by UI Type\n\n### dashboards / analytics\n- **Linear insights** — clean, focused, generous whitespace, data doesn't fight for attention\n- **Vercel analytics** — one metric hero'd, supporting data below, subtle but effective charts\n- **Stripe dashboard** — masterclass in data density without clutter, excellent typography hierarchy\n- **Posthog** — data-heavy but well-organized, good use of tabs to reduce visual load\n- **Raycast analytics** — clean cards with sparklines, not chart-heavy\n\n**what to steal:** hierarchy through size (hero one metric), subtle chart styling (no gridlines, muted colors), generous row spacing in tables, inline sparklines instead of separate chart sections\n\n### admin panels / management tools\n- **Clerk dashboard** — warm, friendly, doesn't feel like enterprise SaaS\n- **Railway** — developer tool that feels designed, strong typography, purposeful color\n- **Resend** — clean, minimal, focused. proves admin tools don't need to be ugly\n- **Supabase** — dark mode done right, information-dense without feeling cramped\n\n**what to steal:** status indicators that feel designed (not just colored dots), action buttons that are clearly primary vs secondary, empty states that guide instead of just saying \"no data\"\n\n### landing pages / marketing\n- **Linear** — typographic confidence, dramatic whitespace, features as mini-stories\n- **Vercel ship pages** — motion as storytelling, scroll-driven reveals, cinematic\n- **Resend** — simple, confident, lets the product speak\n- **Perplexity** — editorial feel, illustration as personality, not decoration\n\n**what to steal:** section rhythm (dense → spacious → dense), typography scale jumps (48px headline → 16px body), motion that reveals content rather than decorating it\n\n### data visualization\n- **Observable** — notebooks that make data feel alive\n- **Flourish** — templates with genuine visual quality\n- **NYT interactive graphics** — the gold standard for data storytelling\n- **Pudding.cool** — data viz as narrative, scrollytelling\n\n**what to steal:** annotation on charts (callouts pointing to interesting data), color palettes that serve the data (not just \"looks nice\"), hover states that reveal detail without overwhelm\n\n## When to Skip Research\n\n- modifying existing UI (the existing design IS the reference)\n- backend/script work (no visual component)\n- tight deadline where the human has already given clear specs\n\n## Compounding\n\nafter each build:\n- if a reference was particularly useful, add it to this file\n- if a pattern from a reference worked well, note it in the relevant section\n- remove references that are outdated or no longer represent good craft\n\nFile v1.0.0:references/layout.md\n\n# Layout Reference\n\n## The Problem\n\nagents default to one layout: card grid. 4 stat cards across the top, chart in the middle, table at the bottom. every dashboard, every admin panel, every analytics page. the layout itself becomes the tell that an agent built this.\n\ngood layout is composition. it creates hierarchy, guides the eye, and makes the content feel intentional. different content needs different structures.\n\n## Layout Vocabulary\n\n### split panel\ntwo columns with different purposes. one side is navigation or context, the other is content.\n- use when: detail views, master-detail, settings with categories\n- example: email client (list | message), figma (layers | canvas)\n- the columns don't have to be equal. 30/70 or 25/75 creates natural hierarchy\n- the divider can be a line, a background change, or just whitespace\n\n### editorial / magazine\ncontent arranged like a newspaper or magazine spread. mixed column widths, pull quotes, full-bleed images, varied section heights.\n- use when: landing pages, case studies, blog posts, marketing pages\n- key: vary the rhythm. narrow text block → full-width image → two-column comparison → single quote\n- don't: make every section the same width and padding\n\n### asymmetric grid\nintentionally uneven columns. one large element anchors the page, smaller elements orbit it.\n- use when: dashboards where one metric matters most, portfolios, feature pages\n- example: one large chart taking 60% width, three small cards stacked in the remaining 40%\n- creates visual hierarchy through size, not just position\n\n### sidebar + content\npersistent navigation on the left, content fills the remaining space.\n- use when: apps with many sections, admin panels, documentation\n- don't: use a sidebar when there are fewer than 5 navigation items. tabs or a top nav work better\n- the sidebar should be narrow (200-280px). wider than that and it fights the content\n\n### full-bleed sections\ncontent that stretches edge-to-edge, breaking out of the container.\n- use when: hero sections, image galleries, data viz that needs horizontal space\n- key: alternating full-bleed and contained sections creates rhythm\n- works especially well for separating distinct content areas\n\n### stacked rows / strips\nhorizontal bands that span the full width, each with different content.\n- use when: roster/list views, timelines, activity feeds\n- each strip can have its own internal layout (left-aligned text + right-aligned actions)\n- works better than card grids for items that are similar but need to show different amounts of info\n\n### centered single column\none narrow column of content, centered on the page. generous margins.\n- use when: forms, checkout flows, focused reading, onboarding steps\n- max-width: 640-720px for text-heavy content, up to 960px for mixed content\n- the whitespace IS the design. don't fill it with sidebars or decorations\n\n### bento grid\nmixed-size cards in a dense grid. some cards are 1x1, some are 2x1, some are 2x2.\n- use when: feature overviews, product pages, homepages that need to show many things\n- key: the size of each card signals its importance. the biggest card is the most important thing\n- don't: make all cards the same size (that's just a card grid again)\n- reference: apple's product pages, linear's feature grid\n\n## Composition Rules\n\n### hierarchy through size\nthe most important thing should be the biggest thing. not the first thing, not the boldest color — the biggest.\n\n### rhythm through variation\nalternate dense sections with breathing room. if three sections in a row are the same height and density, the page feels monotonous.\n\n### grouping through proximity\nthings that are related should be close together. things that are separate should have visible distance between them. this is more powerful than borders or backgrounds for creating structure.\n\n### anchoring through asymmetry\na perfectly symmetrical layout feels static and template-ish. one dominant element (large chart, hero image, featured card) gives the eye somewhere to start.\n\n### negative space as structure\nwhitespace isn't empty — it's a structural element. generous margins and padding signal quality. cramped layouts signal \"we ran out of room\" even if the screen is huge.\n\n## Dashboard-Specific Guidance\n\ndashboards are where agents fail hardest. every agent builds the same dashboard:\n```\n[stat] [stat] [stat] [stat]\n[        chart             ]\n[        table             ]\n```\n\ninstead, try:\n```\n[hero metric + sparkline          ] [secondary metrics]\n[main chart (60%)  ] [alerts (40%)                    ]\n[detail table with inline actions                     ]\n```\n\nor:\n```\n[sidebar nav] [selected view fills remaining space    ]\n             [with its own internal composition        ]\n```\n\nor:\n```\n[full-width trend chart with annotation callouts      ]\n[three cards, different sizes: 2x1, 1x1, 1x1         ]\n[activity feed as stacked strips                      ]\n```\n\nthe key: no two sections should have the same visual weight. if everything is equally important, nothing is.\n\n## Spatial Composition — Breaking the Grid\n\ngrids create order. but a page that never breaks its grid feels mechanical — like a spreadsheet with better fonts. the best interfaces establish a grid and then deliberately break it when the content demands attention.\n\n### techniques\n- **overlap** — let an element overlap the boundary between two sections. a card that sits half in the hero and half in the content below creates visual continuity and depth.\n- **asymmetric columns** — not everything needs to be 50/50 or 33/33/33. use 60/40, 70/30, or even 80/20 when one element is clearly more important.\n- **full-bleed breaking** — a section that breaks out of the max-width container and stretches edge-to-edge creates a dramatic pause in the reading rhythm.\n- **negative space as structure** — an intentionally empty column or large gap isn't wasted space. it's directing attention to what remains.\n- **diagonal flow** — elements arranged along a diagonal line (top-left to bottom-right) create energy and forward momentum. use for landing pages and marketing, not for data-heavy admin tools.\n- **varied section heights** — sections with different internal heights create rhythm. a tall hero → short stat bar → tall content area → short CTA reads as composed. uniform height reads as template.\n\n### when to break the grid\n- hero sections and page headers (first impression, highest impact)\n- featured content or \"hero'd\" metrics\n- transitions between major page sections\n- call-to-action areas\n- full-bleed images or charts\n\n### when NOT to break the grid\n- data tables and lists (consistency aids scanning)\n- form layouts (predictability reduces errors)\n- navigation (users need spatial memory)\n- repeated elements in a series (cards, list items)\n\nFile v1.0.0:references/mock-data.md\n\n# Mock Data Reference\n\n## The Problem\n\nagents fill UIs with placeholder content that screams \"nobody thought about this.\" generic names, round numbers, lorem ipsum energy. the data IS the design — a dashboard with lazy data looks lazy no matter how good the layout is.\n\n## Quality Bar\n\nmock data must be:\n- **specific** — real names, real products, real agencies, not \"Item 1\" or \"User A\"\n- **current** — use today's model names, today's companies, today's events. GPT-3.5 is old news. Claude 1 doesn't exist anymore.\n- **premise-aware** — if the prompt is about government surveillance, the data should reference real agencies and plausible scenarios, not generic \"departments\"\n- **structurally plausible** — numbers should make sense relative to each other. percentages should add up. dates should be recent.\n- **tonally aligned** — if the premise is satirical, the humor lives HERE: in row names, status labels, timestamps, internal tags, alert messages. not in the headline.\n\n## Rules\n\n- include at least 8-12 real domain nouns before inventing fictional ones\n- if the prompt references a live domain (AI models, government agencies, social platforms), use current real names\n- fake entries should sound like they belong in the world — \"Cognitive Warfare Division\" is a better fake agency name than \"Agency X\"\n- every table, card, or list should reward inspection with specific details\n- numbers should tell a story: one metric way higher than the rest, a trend that's clearly going up, a status that's clearly wrong\n- timestamps should be recent (last 24-72 hours for dashboards, last 1-2 weeks for reports)\n- avoid round numbers — 47 is more believable than 50, $1,247 is more believable than $1,200\n\n## Where Humor Lives\n\nfor satirical or playful premises, embed humor in:\n- **row/item names** — \"The Overthinking Committee,\" \"Reply Guys United,\" agent named \"Definitely-Not-Skynet\"\n- **status labels** — \"suspiciously cooperative,\" \"existential crisis,\" \"quietly expanded scope\"\n- **internal notes/tags** — \"press-sensitive,\" \"Hill-demo pending,\" \"CEO saw this on Twitter\"\n- **timestamps** — \"3 min ago (during board meeting)\"\n- **metric annotations** — \"↑ 23% since someone asked it to be honest\"\n- **alert messages** — \"Model scored 99% helpfulness. Investigate.\"\n\ndo NOT put humor in:\n- page titles or main headlines (these should read as real product UI)\n- button labels or navigation (functional elements stay functional)\n- chart axis labels (data viz should be legible)\n\nthe UI should look completely real. the content should make you smile when you read it.\n\n## Anti-Examples\n\nbad:\n- \"Agency 1,\" \"Agency 2,\" \"Agency 3\"\n- \"Model A,\" \"Model B,\" \"Model C\"\n- \"High risk,\" \"Medium risk,\" \"Low risk\" (with no specifics)\n- \"John Doe,\" \"Jane Smith\"\n- \"$1,000,000\" (too round)\n- \"2024-01-01\" (outdated, too clean)\n\ngood:\n- \"Department of Defense — Project Maven successor,\" \"GSA — procurement automation,\" \"IRS — fraud detection (paused after audit)\"\n- \"Claude 4 Opus,\" \"GPT-5.4,\" \"Gemini 3 Pro,\" \"Llama 4 405B\"\n- \"HIGH — NYT investigation pending,\" \"WATCH — congressional inquiry Q2,\" \"CLEAR — passed GAO review\"\n- real-sounding names that fit the world\n- \"$1,247,803\" or \"~$1.2M\"\n- \"Mar 12, 2026 — 2:47 PM\" or \"3 hours ago\"\n\nFile v1.0.0:references/motion.md\n\n# Motion Reference\n\n## Core Rules\n- Motion should clarify state, not audition for attention.\n- If the animation is more noticeable than the change it is explaining, it is wrong.\n- No bounce. No elastic. No toy physics.\n- Exits should usually feel faster than entrances.\n\n## What Good Motion Does\n- Confirms hover, press, open, close, and state change without drama.\n- Helps the user track what moved and why.\n- Makes the interface feel responsive and expensive, not busy.\n- Uses consistency across similar interactions so the product feels intentional.\n\n## Patterns Agents Miss\n- Stagger only when it improves comprehension or delight. Do not make lists feel slow.\n- Loading motion should reassure, not distract. Skeletons usually beat blank space or generic spinners.\n- Reduced motion support is non-negotiable. Replace movement with fades when needed, but keep feedback.\n- Motion cannot rescue weak IA, weak hierarchy, or weak copy.\n\n## Avoid\n- Long hover transitions.\n- Animating everything because the static version feels unfinished.\n- Overshoot, boing, or parallax in core product UX.\n- Using motion to hide latency instead of fixing the experience.\n\nFile v1.0.0:references/responsive.md\n\n# Responsive Design Reference\n\n## Core Rules\n- If it breaks on mobile, it is broken.\n- Build from the smallest screen up so content hierarchy gets decided early.\n- Design for where the content breaks, not where a breakpoint chart says it should.\n- Small screens need prioritization, not a desktop layout compressed until it cries.\n\n## Hard Requirements\n- No horizontal overflow at 375px. Ever.\n- All tappable targets should be at least 48×48px with visible hit area.\n- Hover-only behavior is a bug. Every hover reveal needs a tap path.\n- Body text on mobile should stay readable. Do not miniaturize your way out of layout problems.\n\n## Patterns Agents Miss\n- Desktop sidebars rarely survive intact on mobile. Collapse, reframe, or move navigation.\n- Tables do not magically become mobile-friendly by shrinking. Convert to cards, reduce columns, or create a detail view.\n- Charts need simplification on mobile: fewer labels, fewer simultaneous views, touch-friendly interactions.\n- Modals on mobile should usually become full-screen or near-full-screen with a clear back/close action.\n- Fixed widths are landmines. If something has to feel fixed, cap it with `max-width`, not a rigid width.\n\n## What To Check\n- 375px: no overflow, no clipped text, no microscopic tap targets.\n- 768px: awkward in-between states are resolved, not ignored.\n- 1440px: layout breathes instead of stretching into a sparse mess.\n- Keyboard navigation still makes sense across widths.\n- Inputs use the right keyboard types and remain easy to hit.\n\n## Avoid\n- Treating mobile as a later polish pass.\n- Hiding complexity behind hover.\n- Keeping desktop information density when the screen no longer supports it.\n- Shrinking tables, charts, or controls until they are technically visible but practically unusable.\n\nFile v1.0.0:references/spacing.md\n\n# Spacing Reference\n\n## Hard Rule\n- Interactive targets should be at least 48×48px, with at least 8px between adjacent tap targets.\n- Padding counts as part of the hit area. If the clickable region is invisible, the UI feels broken.\n\n## Core Rules\n- Spacing is the #1 tell.\n- Use spacing to create hierarchy before adding borders, cards, or extra color.\n- Tight inside, loose outside.\n- Contrast in spacing matters more than perfect adherence to one repeated value.\n\n## What Good Judgment Looks Like\n- Related things feel obviously grouped.\n- Unrelated things stop competing because there is enough air between them.\n- Dense screens still feel calm because rhythm is consistent.\n- Wide screens use max widths and stronger outer spacing instead of turning into flat fields of content.\n- Optical alignment beats literal geometry. If it looks off, it is off.\n\n## Patterns Agents Miss\n- Defaulting every container to the same padding makes everything feel cheap.\n- Equal spacing between everything destroys hierarchy.\n- Nested cards are often just spacing failures wearing borders.\n- On dense dashboards, fix clutter with grouping and cadence before shrinking text.\n- If the screen reads like one gray brick when you squint, the spacing system failed.\n\n## Avoid\n- Random one-off spacing values with no rhythm.\n- 12px padding everywhere.\n- Solving hierarchy with borders when whitespace would do it better.\n- Letting mobile spacing collapse so far that the interface loses clarity or tap comfort.\n\nFile v1.0.0:references/typography.md\n\n# Typography Reference\n\n## Core Rules\n- Typography hierarchy beats color for information architecture.\n- Fewer sizes with stronger contrast beat a mushy micro-scale.\n- One strong type system beats two fonts fighting each other.\n- If the layout feels noisy, simplify the type ramp before touching color.\n\n## Hierarchy\n- Weight before size. Often stronger emphasis solves what bigger text was trying to do badly.\n- One clear H1 per screen. If two things scream, neither does.\n- Most product screens only need three practical levels: primary, secondary, tertiary.\n- Secondary text should step back without becoming weak or gray mush.\n\n## Pairing\n- Start with one family and multiple weights before reaching for a second font.\n- Add a second typeface only when you need real contrast: editorial vs utilitarian, display vs body.\n- Avoid defaulting to Inter unless the product truly wants invisible utility.\n- Similar-but-different font pairings look accidental.\n\n## Patterns Agents Miss\n- Giant type is often compensation for weak layout.\n- Metrics, tables, and dashboards want tabular numbers.\n- Long-form text needs restrained measure and enough line-height to breathe.\n- Centered paragraphs almost always make product UI worse.\n\n## Avoid\n- Inter/system font autopilot.\n- 14/15/16/18-style muddy scales.\n- Decorative display fonts in body copy.\n- Fake hierarchy created only with color changes.","readmeExcerpt":"Skill: Design Review Owner: aa-on-ai Summary: Core pack — always active for visual work. Quality gate for UI, components, pages, layouts, or frontend work. Triggers on any visual/design task automaticall... Tags: latest:1.1.0 Version history: v1.1.0 | 2026-03-23T21:56:30.749Z | auto - Expanded and updated reference documentation: alignment.md, motion.md, and typography.md received significant content improvements. - ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# check for common agent anti-patterns\npython3 skills/design-review/scripts/anti-pattern-check.py <your-file.tsx>\n\n# verify loading, empty, and error states exist\npython3 skills/design-review/scripts/state-check.py <your-file.tsx>\n\n# check semantic HTML, aria labels, alt text, heading hierarchy\npython3 skills/design-review/scripts/accessibility-check.py <your-file.tsx>"},{"language":"text","snippet":"// consistent container\n<div className=\"mx-auto max-w-6xl px-4 sm:px-6 lg:px-8\">\n\n// consistent grid with fixed gap\n<div className=\"grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6\">\n\n// consistent spacing between sections\n<section className=\"space-y-12\">  // 48px between children\n<section className=\"space-y-16\">  // 64px between children\n\n// baseline-aligned metrics row\n<div className=\"flex items-baseline gap-8\">\n  <span className=\"text-3xl font-semibold\">1,247</span>\n  <span className=\"text-sm text-gray-500\">active deployments</span>\n</div>\n\n// consistent card padding\n<div className=\"p-6\">  // always p-6 for cards, never mixed"},{"language":"text","snippet":"outer radius = inner radius + padding"},{"language":"css","snippet":"/* wrong — same radius on both */\n.outer { border-radius: 12px; padding: 16px; }\n.inner { border-radius: 12px; }\n\n/* right — concentric */\n.outer { border-radius: 28px; padding: 16px; }\n.inner { border-radius: 12px; }"},{"language":"css","snippet":".image-overlay {\n  outline: 1px solid rgba(0, 0, 0, 0.1);\n  outline-offset: -1px;\n}\n.dark .image-overlay {\n  outline-color: rgba(255, 255, 255, 0.1);\n}"},{"language":"css","snippet":"/* instead of */\nborder: 1px solid #e5e7eb;\n\n/* use */\nbox-shadow: 0 1px 2px rgba(0,0,0,0.04), 0 1px 1px rgba(0,0,0,0.02);"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: design-review\ndescription: >\n  Core pack — always active for visual work. Quality gate for UI, components, pages,\n  layouts, or frontend work. Triggers on any visual/design task automatically.\n  Use before presenting work, during builds, and for design QA.\n---\n\n# Design Review Skill\n\n## Core Pack — Always Active\nThis is a core skill. Apply it on ALL visual and frontend work, no exceptions. You do not need permission or a specific trigger to use this.\n\n## When to Use\n- Before presenting ANY visual or UX work.\n- Treat this as a quality gate, not optional polish.\n- Sub-agents doing design/frontend work MUST run this before announcing completion.\n\n## Pre-Work: Read Before Building\n\n### 1. Read the project's guidelines\n- Read `guidelines.md` or equivalent design system doc first if it exists.\n- Follow the project's existing components, tokens, and patterns before inventing anything.\n- If no formal guidelines exist, inspect the existing product and match its logic.\n\n### 2. Research before designing\n- Check how similar tools solve the same problem before inventing a pattern.\n- Use proven references when they exist.\n- Quality bar references:\n  - UX Tools — editorial restraint, typography, calm hierarchy\n  - Inflight by Ridd — motion, depth, data viz polish\n  - Linear — dense information, excellent hierarchy, no noise\n  - Vercel dashboard — spacing, typography, dark mode discipline\n\n### 3. Check design memory\n- Read `memory/channels/{channel-name}.md` for prior design decisions.\n- If memory says Aaron rejected a pattern, don't repeat it.\n- If a project brain file is linked from channel memory, read that too.\n\n## Aaron's Core Principles\n- Restraint IS the design.\n- Spacing is the #1 tell.\n- Typography hierarchy > color for information architecture.\n- Match references at pixel level before adding your own ideas.\n- Existing patterns > new patterns.\n- Interactive elements should feel polished, not dead.\n- If the foundation is wrong, no polish fixes it.\n- Good design is centripetal, not centrifugal.\n\n## Reference Files\nRead only what the task needs. Keep this SKILL lean, load detail on demand:\n\n- `references/typography.md` — hierarchy, scale, pairing, measure\n- `references/color.md` — restrained palettes, tinted neutrals, contrast, OKLCH\n- `references/spacing.md` — spacing system, rhythm, grouping, layout density\n- `references/motion.md` — timing, easing, reduced motion, interactive feel\n- `references/anti-patterns.md` — patterns Aaron will clock instantly and reject\n\n### For sub-agents\n- Read the relevant reference files based on what you're building.\n- New layout or dashboard? Read spacing + anti-patterns.\n- Type-heavy screen? Read typography + spacing.\n- Color or theming work? Read color + anti-patterns.\n- Interactive polish? Read motion + anti-patterns.\n- If in doubt, at minimum read spacing + anti-patterns.\n\n## Pre-Flight Checklist\nRun this EVERY TIME before presenting work to Aaron.\n\n### Step 1: Visual verification\n- [ ] Take a screenshot of th"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7cedhqc0a3q0fn888hwshxfd838nt6\",\n  \"slug\": \"design-review\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1774302990749\n}"},{"path":"references/alignment.md","content":"# Visual Alignment & Composition Reference\n\n## The Problem\n\nagents place elements where they fit, not where they belong. text doesn't align across columns. spacing is inconsistent between similar elements. grids break their own rhythm. the result looks \"off\" even when every individual component is fine.\n\nalignment is what separates \"an agent built this\" from \"a designer built this.\" it's invisible when done right and immediately obvious when wrong.\n\n## Alignment Principles\n\n### everything aligns to something\nevery element on the page should share an edge or center with at least one other element. nothing floats randomly.\n\n- text blocks in different sections should share the same left edge\n- metrics in a row should baseline-align their numbers\n- cards in a grid should have identical internal padding\n- icons in a list should align to a consistent vertical axis\n\n### fewer alignment points = cleaner layout\na page with 3 alignment points (left margin, content center, right margin) looks composed. a page with 12 different left edges looks chaotic.\n\ncount your alignment rails. if you have more than 4-5 on a page, something is wrong.\n\n### the grid is the skeleton\npick a grid and commit to it. common choices:\n- 12-column grid with consistent gutters (most flexible)\n- 4-column at mobile, 8 at tablet, 12 at desktop\n- simple max-width container with consistent padding\n\ndon't: mix a 3-column section with a 4-column section with a full-bleed section unless the rhythm is intentional.\n\n## Symmetry\n\n### symmetry = stability\nsymmetrical layouts feel balanced, trustworthy, professional. use for:\n- dashboards and data-heavy pages\n- forms and settings\n- admin tools and internal products\n- anywhere stability matters more than personality\n\n### asymmetry = energy\nasymmetrical layouts feel dynamic, editorial, opinionated. use for:\n- landing pages and marketing\n- portfolios and case studies\n- anywhere you want the layout itself to communicate\n\n### don't accidentally mix them\na page that's 90% symmetrical with one randomly asymmetrical section looks broken, not intentional. either commit to the grid or break it with purpose.\n\n## Spacing Consistency\n\n### the 4px/8px base unit\npick a base unit (4px or 8px) and derive ALL spacing from it:\n- 4px: tight, detail-level (icon to label gap)\n- 8px: small component spacing\n- 12px: compact internal padding\n- 16px: standard internal padding, gap between related items\n- 24px: gap between components\n- 32px: section separation (small)\n- 48px: section separation (medium)\n- 64px: section separation (large)\n- 80-96px: major page divisions\n\n### spacing communicates grouping\nitems that are closer together are perceived as related. items with more space between them are perceived as separate groups. this is Gestalt proximity — the most powerful layout tool.\n\n- related items: 8-16px apart\n- components within a section: 16-24px apart\n- sections: 32-64px apart\n- major page divisions: 64-96px apart\n\ndon't: use the same spacing everywhere. if everyt"},{"path":"references/anti-patterns.md","content":"# Anti-Patterns Reference\n\n## Strategic Mistakes\n- Centrifugal design: choices made to feel different or branded rather than clearer or better.\n- Decoration used to compensate for weak structure.\n- New patterns invented when the product already has a good one.\n- Polishing a bad foundation instead of rebuilding the layout.\n\n## Typography Mistakes\n- Inter, Roboto, Arial, or system font defaults as unexamined autopilot. agents reach for these every time. pick a distinctive font that matches the product's personality. there are thousands of fonts — using the default is a non-decision.\n- Same font on every project. if two different products use the same typeface, one of them chose wrong.\n- Mushy scales with too many neighboring sizes.\n- Large type trying to rescue weak hierarchy.\n- Monospace used as a shortcut for \"tech\" personality.\n- Too many font families fighting for attention (but two is usually right: one display + one body).\n\n## Color Mistakes\n- Purple gradients, cyan glows, and generic AI-saas palettes.\n- Blue everywhere as the default accent.\n- Gray text on colored backgrounds.\n- Pure black, pure gray, or dead neutrals with no temperature.\n- Accent color sprayed across icons, labels, chips, and borders until it means nothing.\n- Color doing the job typography and spacing should be doing.\n\n## Layout Mistakes\n- Bootstrap cards as a default answer.\n- Card nesting.\n- Identical card grids repeated across the screen.\n- Centering everything because it feels \"clean.\"\n- Equal spacing everywhere, so nothing groups or leads.\n- Heavy borders and separators where whitespace would be stronger.\n- Hero metric layouts that scream template.\n- 4 equal-width stat cards across the top of every dashboard (the #1 agent layout cliche).\n- Every page using the same card-in-grid structure regardless of content type.\n- Dark mode as the default because \"it's a dashboard\" — light mode is equally valid.\n- Sidebar navigation on pages with fewer than 5 sections.\n- Every section having the same visual weight — nothing hero'd, nothing secondary.\n- rounded-lg on every surface creating a puffy, toy-like feel.\n- zinc/slate as the only background palette — agents default to this every time.\n\n## Demo/Meta-Navigation Mistakes\n- State toggles (happy/loading/empty/error) rendered inline as part of the UI — they must be floating overlays, clearly separate from the actual product surface.\n- Context briefs or design notes leaking into the rendered page (e.g. \"This should feel like...\" appearing as UI text).\n- Debug controls styled to match the product UI — they should look like developer tools, not product features.\n\n## Interaction Mistakes\n- Missing hover, focus, or active states.\n- Bounce or elastic easing.\n- Hover-only affordances on touch-first surfaces.\n- Tiny click targets.\n- Modals used because they were easier than solving the flow.\n- Generic confirmation dialogs where undo would be better.\n\n## Craft Mistakes\n- Colored icon circles that weren't in the brief.\n- Placeholder copy lef"},{"path":"references/color.md","content":"# Color Reference\n\n## Core Rules\n- Restraint is the design.\n- Color is a scalpel, not confetti.\n- Most product surfaces need one accent color, not a rainbow pretending to be a system.\n- The screen should still work in grayscale. Color should improve hierarchy, not carry it alone.\n\n## What Actually Matters\n- Start with neutrals. If the neutral system is bad, the whole interface feels cheap.\n- Use tinted neutrals, not dead zero-chroma gray. A slight warm or cool bias makes the UI feel intentional.\n- Avoid pure black and pure gray. Real materials have temperature.\n- Accent color should stay scarce so it keeps meaning.\n- Strong colored fills should earn their place: selected states, alerts, charts, key emphasis.\n\n## Hierarchy Through Color\n- Default text should be high-contrast neutral.\n- Secondary information should step back with softer neutrals, not random gray tokens.\n- Borders should usually be quieter than text and slightly stronger than backgrounds.\n- In dark mode, depth usually comes from layered surfaces, not giant shadows.\n- Gray text on colored backgrounds is almost always wrong.\n\n## Patterns Agents Miss\n- Blue everywhere usually means nobody made a decision.\n- Purple gradients and cyan-purple AI palettes instantly read as generic AI SaaS unless explicitly warranted.\n- If every label, badge, icon, and chip is accented, nothing is accented.\n- Heavy transparency is usually a smell. Build the right color instead.\n\n## Avoid\n- Using color alone to communicate status or hierarchy.\n- Defaulting to the same AI palette regardless of brand.\n- Letting color do the job that spacing, typography, and composition should be doing."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Core pack — always active for visual work. Quality gate for UI, components, pages, layouts, or frontend work. Triggers on any visual/design task automaticall... Skill: Design Review Owner: aa-on-ai Summary: Core pack — always active for visual work. Quality gate for UI, components, pages, layouts, or frontend work. Triggers on any visual/design task automaticall... Tags: latest:1.1.0 Version history: v1.1.0 | 2026-03-23T21:56:30.749Z | auto - Expanded and updated reference documentation: alignment.md, motion.md, and typography.md received significant content improvements. -","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":2056,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T19:40:49.162Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T19:40:49.162Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:59:23.462Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}