Audit Uiux Design System

UI Design System Audit Skill

Visual design system coherency audit: tokens, components, visual consistency, dark mode, animations, and WCAG visual compliance.

Before ANY browser interaction, read the browser-anti-stall skill and apply its rules to every step. That skill lives at ~/.cursor/skills/protocol-browser-anti-stall/SKILL.md.

CRITICAL: Anti-Template, Anti-AI-Generated Design

Every UI recommendation MUST result in output that looks hand-crafted by a senior designer, not generated by a template or AI. Before implementing or recommending ANY visual change:

1. Research real products — Search Firecrawl for award-winning sites in the product's

domain (Awwwards, Muzli, SiteInspire). Study what makes them feel human and curated.

1. Break the grid intentionally — Uniform spacing, identical card sizes, and perfectly

symmetric layouts are AI tells. Introduce deliberate visual rhythm: vary section padding, use asymmetric hero layouts, offset elements with purpose.

1. Microinteraction budget — Every interactive element needs a response. Not the same

response. Buttons get press feedback (scale, shadow shift). Links get underline animations. Cards get subtle lift. Hover, focus, active, and disabled MUST all feel distinct.

1. Personality tokens — The design system must define personality, not just colors.

What's the brand's visual "voice"? Sharp corners = precision. Rounded = friendly. Monospace accents = technical. Serif headings = editorial. This must be intentional.

1. Forbid these AI tells:

• Identical padding on every section
• Generic gradient backgrounds with no brand logic
• Icon-title-description cards in a 3-column grid as the default layout for everything
• "Lorem ipsum" placeholder patterns in empty states
• Perfectly uniform border-radius on all elements
• Stock illustration style (undraw, absurd-design) without brand adaptation

---

Step 0: Auto-Detect Design System

0a. Detect CSS Framework

Read package.json and config files:

| Signal | Technology | |--------|-----------| | tailwindcss v3 + tailwind.config.* | Tailwind CSS v3 | | tailwindcss v4 + @theme in CSS | Tailwind CSS v4 | | *.module.css files | CSS Modules | | styled-components or @emotion/styled | CSS-in-JS | | @chakra-ui/react | Chakra UI | | @mui/material | Material UI | | @mantine/core | Mantine |

0b. Detect Component Library

Glob: **/components/ui/*.tsx → shadcn/ui
Glob: **/components/ui/*.vue → Vue component lib
Glob: **/components/ui/*.svelte → Svelte component lib
Grep: "from '@radix-ui" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'lucide-react" glob "*.{ts,tsx}" output_mode "count"
Grep: "from '@heroicons" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'react-icons" glob "*.{ts,tsx}" output_mode "count"

0c. Find Design Tokens

Glob: **/tailwind.config.*
Glob: **/app/globals.css
Glob: **/styles/tokens.*
Glob: **/theme.*
Grep: "--primary|--secondary|--accent|--muted" glob "*.css"

Read token source to extract: colors, spacing, typography, radii, shadows.

0d. Discover Forbidden Patterns

Grep: "NEVER|FORBIDDEN|DO NOT" glob "**/*README*" -i

0e. Record Discovery

DESIGN SYSTEM DISCOVERY:
- CSS framework: [Tailwind v3/v4 / CSS Modules / Styled Components / etc.]
- Component library: [shadcn/ui / Radix / MUI / Chakra / custom]
- Icon library: [Lucide / Heroicons / react-icons / mixed]
- Token source: [file path]
- Colors defined: [count]
- Typography scale: [list]
- Spacing base: [4px / 8px / etc.]
- Border radius: [list]
- Shadow levels: [list]
- Dark mode: [YES — class/media / NO]
- Forbidden patterns: [list from README]

---

Step 1: Research Design System Best Practices

1a. Context7 — Component Library Docs

CallMcpTool(server: "context7", toolName: "resolve-library-id", arguments: {
 "libraryName": "",
 "query": "component variants accessibility patterns"
})

Then fetch docs with the resolved ID. Also fetch CSS framework docs.

1b. Firecrawl — Design System Standards

CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: {
 "query": " design system audit token compliance best practices [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
})

Additional queries:

| Topic | Query | |-------|-------| | Token compliance | design token audit consistency | | Component patterns | component modularity composition patterns | | Dark mode | dark mode implementation best practices |

Scrape the best result for detailed guidance.

1c. Firecrawl — Award-Winning Reference Sites

Research real products in the same domain to establish a visual benchmark:

CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: {
 "query": " website design award Awwwards Muzli [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
})

CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: {
 "query": " SaaS UI design inspiration unique not generic [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
})

Scrape 2-3 standout sites. Extract:

• How they break typical grid patterns
• Signature microinteractions (hover, scroll, transition)
• Typography personality (serif/sans mix, weight contrast, size jumps)
• Color usage patterns (accent frequency, gradient logic, muted vs saturated)
• What makes them NOT look like a template

---

Step 2: Token Compliance Audit

2a. Color Tokens

| Rule | Standard | How to Check | |------|----------|-------------| | Semantic naming | primary, secondary, destructive, muted, accent | No raw hex/rgb in components | | CSS variables | hsl(var(--primary)) or oklch() | All colors reference variables | | Foreground pairs | Every bg color has *-foreground | Text contrast maintained | | Dark mode | All tokens have dark variant | .dark class or @media | | Status colors | success, warning, error, info defined | Consistent across alerts, badges, toasts |

Find violations:

Grep: "(#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\([^v])" glob "*.tsx"
Grep: "\[(#|rgb|hsl)" glob "*.tsx"

2b. Typography Tokens

| Rule | Standard | |------|----------| | Font families | Max 2-3 families in theme | | Size scale | Consistent (text-sm, text-base, text-lg) | | Weight scale | Limited set (font-normal, font-medium, font-semibold, font-bold) | | Heading hierarchy | h1 > h2 > h3 in visual weight AND DOM order | | No arbitrary sizes | No text-[14px] when text-sm exists |

Grep: "text-\[" glob "*.tsx"
Grep: "font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)" glob "*.tsx" output_mode "count"

2c. Spacing Tokens

| Rule | Standard | |------|----------| | Base unit | 4px grid (Tailwind default) | | Consistent gaps | Same spacing for same contexts | | No arbitrary values | No p-[13px] when p-3 exists |

Grep: "(p|m|gap|space)-\[" glob "*.tsx"

2d. Borders, Radii, Shadows

Grep: "rounded-\[" glob "*.tsx"
Grep: "shadow-" glob "*.tsx" output_mode "count"

---

Step 3: Component Modularity Audit

3a. Component Health

| Rule | Standard | |------|----------| | Single responsibility | One component = one purpose | | Composable | Small pieces compose into larger ones | | Reusable | Same UI = same component everywhere | | Consistent props | variant, size, disabled, className across all | | Variants pattern | cva() or similar for style variants |

3b. Find Duplicate Components

Grep: "/
browser_wait_for → { time: 2 }
browser_snapshot → verify content rendered
browser_take_screenshot → visual evidence
browser_console_messages → check for errors

4b. Per-Page Checks

| Check | How | |-------|-----| | Token compliance | Screenshot — inconsistent colors, spacing | | Component reuse | Snapshot — shared primitives used? | | Console errors | browser_console_messages — hydration, missing CSS vars | | Layout shift | Snapshot before/after interaction | | Dark mode | Toggle dark mode, re-screenshot, compare |

4c. Responsive Check

Test at three viewports:

• Desktop (1280px)
• Tablet (768px)
• Mobile (375px)

Capture screenshots at each.

4d. Visual Accessibility

| Check | How | |-------|-----| | Color contrast | 4.5:1 text, 3:1 large text/UI — inspect via screenshot | | Focus rings | Tab through elements, verify visible focus indicator | | Semantic HTML | Grep: "||||" glob "*.tsx" | | Alt text | Grep: " | [files] | Use ` from components/ui | | Custom modal | [file] | Use from components/ui` |

---

Visual Accessibility

| Criteria | Status | Issues | |----------|--------|--------| | Color contrast | [pass/warn/fail] | [details] | | Focus indicators | [pass/warn/fail] | [details] | | Alt text | [pass/warn/fail] | [details] | | Semantic HTML | [pass/warn/fail] | [details] |

---

Further reading

• [Microinteraction Coverage and more](references/details.md)

Source & license

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

• Author: kensaurus
• Source: kensaurus/cursor-kenji
• License: MIT
• Homepage: https://github.com/kensaurus/cursor-kenji

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