# Audit Uiux Design System

> >

- **Type:** Skill
- **Install:** `agentstack add skill-kensaurus-cursor-kenji-audit-uiux-design-system`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kensaurus](https://agentstack.voostack.com/s/kensaurus)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kensaurus](https://github.com/kensaurus)
- **Source:** https://github.com/kensaurus/cursor-kenji/tree/main/skills/audit-uiux-design-system
- **Website:** https://github.com/kensaurus/cursor-kenji

## Install

```sh
agentstack add skill-kensaurus-cursor-kenji-audit-uiux-design-system
```

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

## About

# 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.
2. **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.
3. **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.
4. **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.
5. **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

```json
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

```json
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:

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

```json
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](https://github.com/kensaurus)
- **Source:** [kensaurus/cursor-kenji](https://github.com/kensaurus/cursor-kenji)
- **License:** MIT
- **Homepage:** https://github.com/kensaurus/cursor-kenji

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

## Pricing

- **Free** — Free

## Security capabilities

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

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

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


## Versions

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

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kensaurus-cursor-kenji-audit-uiux-design-system
- Seller: https://agentstack.voostack.com/s/kensaurus
- Browse the marketplace: https://agentstack.voostack.com/browse

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