@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/audit-uiux-design-system/SKILL.md

@@ -0,0 +1,475 @@
+---
+name: audit-uiux-design-system
+description: >
+  Audit visual-system coherence: tokens, component variants, color, type,
+  spacing, dark mode. Use for "design drift", inconsistent UI, or duplicate
+  primitives. Per-page usability → audit-ux. Plan-only unification →
+  plan-uiux-unification.
+license: MIT
+effort: high
+---
+
+# UI Design System Audit Skill
+
+**Degree of freedom: MIXED** — Steps 0–3, 5–6 `[HIGH freedom]`; Step 4
+playwright captures `[LOW freedom — run exactly]`. Read
+`protocol-browser-anti-stall` before any browser step. Breakpoints-only →
+`audit-responsive`.
+
+## How to reason
+
+1. **Observe** — quote the token file, raw hex, or screenshot
+2. **Interpret** — is this the system token, a one-off, or an AI-tell?
+3. **Classify** — token leak / duplicate component / missing state / template / correct
+4. **Severity** — raw color on a core primitive = P0; missing hover = P1; radius nit = P2
+
+## Worked example
+
+> **Observe:** `Button.tsx` uses `bg-[#3B82F6]`; `--primary` exists in `globals.css`.
+> **Interpret:** the primitive bypasses the token SSOT; dark mode cannot switch it.
+> **Classify:** token leak on a core primitive.
+> **Severity:** P0 — every button is a hardcoded hex.
+> **Finding:** `Button.tsx` | color token | P0 | replace with `bg-primary`.
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Tokens first** — do not invent a second scale
+2. **Evidenced** — screenshot under `.playwright-mcp/` or quoted class
+3. **Severity justified** — P0 = core primitive off-token or unusable contrast
+4. **Right owner** — linearized desktop → `audit-responsive`; WCAG keyboard → `audit-accessibility`
+5. **Hand-crafted** — no recommendation that increases template sameness
+
+## Anti-template
+
+Recommendations must name what to avoid, not ask for taste. Research
+award-winning sites in the domain; vary rhythm (not identical `py-16`);
+give each control a distinct hover/focus/active/disabled; define
+personality tokens (radius, type voice). Defaults to call out — extend
+this list from whatever the first draft reached for: identical section
+padding, generic or purple gradients, three equal cards / 3-col
+icon-title-desc as the default, cream or off-white page backgrounds,
+italic accent words in headlines, "01/02/03" numbered section labels,
+monospace labels, pill-shaped buttons everywhere, Inter/Roboto as the
+only type voice, lorem empty states, uniform radius, unadapted stock art.
+
+---
+
+## Step 0: Auto-Detect Design System
+
+### 0a. Detect CSS Framework
+
+| 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
+context7:resolve-library-id
+{
+ "libraryName": "<DETECTED_COMPONENT_LIBRARY>",
+ "query": "component variants accessibility patterns"
+}
+```
+
+Then fetch docs with the resolved ID. Also fetch CSS framework docs.
+
+### 1b. Firecrawl — Design System Standards
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<COMPONENT_LIBRARY> design system audit token compliance best practices [current year]",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+Additional queries:
+
+| Topic | Query |
+|-------|-------|
+| Token compliance | `design token audit <CSS_FRAMEWORK> consistency` |
+| Component patterns | `<FRAMEWORK> component modularity composition patterns` |
+| Dark mode | `<CSS_FRAMEWORK> dark mode implementation best practices` |
+
+### 1c. Firecrawl — Award-Winning Reference Sites
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<PRODUCT_TYPE> website design award Awwwards Muzli [current year]",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<PRODUCT_TYPE> SaaS UI design inspiration unique not generic [current year]",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+Scrape 2–3 standout sites for grid breaks, signature motion, type voice, and accent logic.
+
+---
+
+## 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: "<button " glob "*.tsx" — raw buttons outside ui/ (should use Button)
+Grep: "<input " glob "*.tsx" — raw inputs (should use Input)
+Grep: "<select " glob "*.tsx" — raw selects
+Grep: "<a " glob "*.tsx" — raw anchors (should use Link)
+```
+
+Exclude `components/ui/*` — those are legitimate primitives.
+
+### 3c. Check Component Consistency
+
+```
+Grep: "function (Button|Input|Modal|Dialog|Card)" glob "*.tsx" output_mode "files_with_matches"
+```
+
+### 3d. Mixed Icon Libraries
+
+```
+Grep: "from .lucide-react" glob "*.tsx" output_mode "count"
+Grep: "from .@heroicons" glob "*.tsx" output_mode "count"
+Grep: "from .react-icons" glob "*.tsx" output_mode "count"
+```
+
+---
+
+## Step 4: Live Visual Verification (playwright-cli)
+
+### 4a. Navigate and Capture
+
+```bash
+PW="npx --yes @playwright/cli@latest"
+$PW -s=ds-audit open --headed "http://localhost:<PORT>/<ROUTE>"
+sleep 2
+$PW -s=ds-audit snapshot                                              # verify content rendered
+$PW -s=ds-audit screenshot --filename ".playwright-mcp/ds-<route>.png"  # visual evidence
+$PW -s=ds-audit console                                               # check for errors
+```
+
+### 4b. Per-Page Checks
+
+| Check | How |
+|-------|-----|
+| Token compliance | Screenshot — inconsistent colors, spacing |
+| Component reuse | Snapshot — shared primitives used? |
+| Console errors | `console` — 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** (1440px)
+- **Tablet** (768px)
+- **Mobile** (375px)
+
+### 4d. Visual Accessibility
+
+| Check | How |
+|-------|-----|
+| Color contrast | 4.5:1 text, 3:1 large text/UI — compute from the token pair values (one-line script or the DevTools accessibility pane); the screenshot confirms which pair is in use, it does not measure the ratio |
+| Focus rings | Tab through elements, verify visible focus indicator |
+| Semantic HTML | `Grep: "<nav>|<main>|<section>|<article>|<aside>" glob "*.tsx"` |
+| Alt text | `Grep: "<(img|Image)" glob "*.tsx"` then check for `alt=` |
+
+---
+
+## Step 5: Microinteractions and User Feedback
+
+### 5a. Microinteraction Coverage Audit
+
+Check each interactive:
+
+| Element | Expected Feedback | AI-Tell if Missing |
+|---------|------------------|--------------------|
+| Buttons | Hover: color shift + subtle shadow change. Active: scale(0.98) press. Loading: spinner replaces label or inline indicator | Flat, no state change — feels dead |
+| Links | Hover: underline animation or color transition, not instant swap | Instant color jump with no transition |
+| Cards (clickable) | Hover: lift (translateY + shadow increase). Not just color change | Color change only, or no hover at all |
+| Inputs | Focus: ring animation or border color transition. Not just outline swap | Browser default outline, no custom focus |
+| Toggles/switches | State transition animated, not instant. Haptic feel via easing | Instant snap between states |
+| Dropdowns/menus | Open/close with slide or fade, not instant appear/disappear | Instant pop, no transition |
+| Toasts/notifications | Enter with slide + fade, exit with fade. Auto-dismiss with progress | Instant appear/disappear |
+| Modals/dialogs | Backdrop fade + content scale/slide. Exit reverses. Not instant | Instant appear, jarring |
+| Tabs | Active indicator slides to new tab, not instant jump | Instant color swap |
+| Tooltips | Slight delay (200-300ms), fade in. Don't flicker on mouse movement | Instant, flickers, no delay |
+
+**Find in code:**
+
+```
+Grep: "transition-all|transition-colors|transition-opacity|transition-transform" glob "*.tsx" output_mode "count"
+Grep: "hover:|group-hover:|focus-visible:" glob "*.tsx" output_mode "count"
+Grep: "animate-|animation-|@keyframes|framer-motion|motion\." glob "*.tsx" output_mode "count"
+Grep: "scale-|translate-|rotate-" glob "*.tsx" output_mode "count"
+```
+
+### 5b. Interaction State Completeness
+
+Verify ALL states exist per interactive:
+
+```
+States checklist per component:
+□ Default (resting)
+□ Hover (mouse over)
+□ Focus-visible (keyboard navigation)
+□ Active/pressed (during click)
+□ Disabled (grayed, not clickable, cursor-not-allowed)
+□ Loading (async action in progress)
+□ Error (validation failed, destructive context)
+□ Success (completed action)
+```
+
+**Find missing states:**
+
+```
+Grep: "focus-visible:|focus:" glob "*.tsx" output_mode "count"
+Grep: "active:|pressed" glob "*.tsx" output_mode "count"
+Grep: "disabled:|cursor-not-allowed|opacity-50" glob "*.tsx" output_mode "count"
+```
+
+### 5c. Visual Rhythm and Personality Audit
+
+Intentional variety vs uniform repetition:
+
+| Pattern | Curated Feel | Template Feel |
+|---------|-------------|---------------|
+| Section spacing | Varies by content type (hero: generous, form: tight, CTA: spacious) | Same `py-16` on every section |
+| Typography contrast | Large jumps between heading and body (e.g., 48px → 16px). Mix weights | Incremental scale, same weight everywhere |
+| Color accent usage | Accent used sparingly for emphasis, not on every element | Primary color on every button, link, icon |
+| Layout variation | Different layouts per section (text-left/image-right, full-width, sidebar) | Same 3-column card grid repeated |
+| Border radius | Intentional variation (pills for tags, rounded for cards, sharp for data tables) | Same `rounded-lg` on everything |
+| Shadow depth | Multiple shadow levels for elevation hierarchy | Same shadow on everything, or no shadows |
+| Whitespace | Asymmetric margins create visual flow and reading rhythm | Perfectly symmetric, mechanical spacing |
+
+---
+
+## Step 6: Animation and Dark Mode
+
+### Animations
+
+| Rule | Standard |
+|------|----------|
+| Duration scale | `150ms` (micro), `200ms` (hover), `300ms` (enter), `500ms` (complex) — NOT all the same |
+| Easing | `ease-out` for enter, `ease-in` for exit, `ease-in-out` for state changes — NOT all `ease-in-out` |
+| Reduced motion | `motion-safe:` prefix or `prefers-reduced-motion` |
+| No layout shift | Transitions don't cause CLS |
+| Stagger effect | List items, card grids animate in with stagger delay, not all at once |
+
+```
+Grep: "duration-[0-9]+" glob "*.tsx" output_mode "count"
+Grep: "transition-" glob "*.tsx" output_mode "count"
+Grep: "prefers-reduced-motion|motion-safe|motion-reduce" glob "*.tsx"
+Grep: "stagger|delay-\[|animation-delay" glob "*.tsx" output_mode "count"
+```
+
+### Dark Mode
+
+| Rule | Standard |
+|------|----------|
+| All tokens switch | CSS variables change in dark mode |
+| No hardcoded colors | No `bg-white`, `text-black` — use semantic tokens |
+| Borders visible | In both modes |
+| Contrast | WCAG in BOTH light and dark |
+| Not an afterthought | Dark mode should feel designed, not inverted. Shadows become glows, borders become subtle |
+
+```
+Grep: "(bg-white|bg-black|text-white|text-black)" glob "*.tsx" output_mode "count"
+```
+
+---
+
+## Output Template
+
+```markdown
+## UI Design System Audit Report
+
+**Date:** [date]
+**Framework:** [detected]
+**CSS:** [Tailwind v3/v4 / CSS Modules / etc.]
+**Component library:** [shadcn / Radix / MUI / custom]
+**Pages Audited:** [count]
+**Issues Found:** [count]
+
+---
+
+### Design Token Compliance
+
+| Token Category | Defined | Violations | Status |
+|----------------|---------|------------|--------|
+| Colors | [count] | [count] raw hex/rgb | [pass/warn/fail] |
+| Typography | [count] | [count] arbitrary sizes | [pass/warn/fail] |
+| Spacing | [count] | [count] arbitrary values | [pass/warn/fail] |
+| Radii | [count] | [count] arbitrary radii | [pass/warn/fail] |
+| Shadows | [count] | [count] inconsistent | [pass/warn/fail] |
+
+---
+
+### Component Health
+
+| Component | Used In | Variants | Issues |
+|-----------|---------|----------|--------|
+| Button | [N] files | [N] | [notes] |
+| Input | [N] files | [N] | [notes] |
+| Card | [N] files | [N] | [notes] |
+
+---
+
+### Duplicate / Redundant Components
+
+| Pattern | Locations | Recommendation |
+|---------|-----------|----------------|
+| Raw `<button>` | [files] | Use `<Button>` from `components/ui` |
+| Custom modal | [file] | Use `<Dialog>` 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)

package/skills/audit-uiux-design-system/references/details.md

@@ -0,0 +1,71 @@
+```markdown
+### Microinteraction Coverage
+
+| Element | Hover | Focus | Active | Loading | Disabled | Status |
+|---------|-------|-------|--------|---------|----------|--------|
+| Buttons | [y/n] | [y/n] | [y/n] | [y/n] | [y/n] | [pass/warn/fail] |
+| Links | [y/n] | [y/n] | [y/n] | — | — | [pass/warn/fail] |
+| Cards | [y/n] | [y/n] | [y/n] | — | — | [pass/warn/fail] |
+| Inputs | — | [y/n] | — | — | [y/n] | [pass/warn/fail] |
+| Modals | enter | exit | — | — | — | [pass/warn/fail] |
+| Toasts | enter | — | dismiss | auto | — | [pass/warn/fail] |
+
+---
+
+### Visual Personality Assessment
+
+| Trait | Score (1-5) | Evidence |
+|-------|-------------|----------|
+| Typography personality | [1-5] | [serif/sans contrast, weight variety, scale jumps] |
+| Layout variety | [1-5] | [different section layouts vs repeated grids] |
+| Color restraint | [1-5] | [accent used sparingly vs painted everywhere] |
+| Spacing rhythm | [1-5] | [intentional variation vs mechanical uniformity] |
+| Border radius intention | [1-5] | [varied by context vs same everywhere] |
+| Shadow depth hierarchy | [1-5] | [multiple levels vs flat/uniform] |
+| **AI-Generated Feel?** | [YES/NO] | [specific tells found] |
+
+---
+
+### Dark Mode & Animation
+
+| Category | Status | Issues |
+|----------|--------|--------|
+| Token switching | [pass/warn/fail] | [details] |
+| Hardcoded colors | [pass/warn/fail] | [count] violations |
+| Reduced motion | [pass/warn/fail] | [details] |
+| Easing variety | [pass/warn/fail] | [all same vs appropriate per context] |
+| Duration variety | [pass/warn/fail] | [appropriate per interaction type] |
+| Stagger animations | [pass/warn/fail] | [lists/grids animate with stagger?] |
+
+---
+
+### Page-by-Page Summary
+
+| Page | Tokens | Components | Visual A11y | Dark Mode | Overall |
+|------|--------|------------|-------------|-----------|---------|
+| / | pass | pass | warn | pass | Good |
+| /dashboard | warn | fail | fail | warn | Needs Work |
+
+---
+
+### Research Findings Applied
+- [Pattern from research]: [how it applies]
+
+---
+
+### Critical Issues (Must Fix)
+
+#### 1. [Component/Page] — [Issue]
+- **Problem:** [description]
+- **Impact:** [visual consistency / a11y / dark mode]
+- **Fix:** [specific code change]
+
+---
+
+### Next Steps
+
+1. [ ] Replace raw HTML with shared components: [list]
+2. [ ] Remove arbitrary token values: [list]
+3. [ ] Fix dark mode violations: [list]
+4. [ ] Add reduced motion support: [list]
+```