imhcode 1.0.0

package/skills/design-auditor/references/states.md

@@ -0,0 +1,254 @@
+# UI States Reference
+
+Most beginner UIs only design the "happy path" — data loads perfectly and the user does everything right. In reality, users spend a surprising amount of time in other states. Each needs its own design.
+
+## The 9 States Every UI Component Can Be In
+
+| State | When | Design Priority |
+|---|---|---|
+| **Default** | Nothing has happened yet | ✅ Always designed |
+| **Hover** | Cursor over an interactive element | 🟡 Sometimes missing |
+| **Focus** | Element selected via keyboard | ⚠️ Often forgotten |
+| **Active** | Element being pressed/clicked | 🟡 Sometimes missing |
+| **Loading** | Waiting for data or an action to complete | ⚠️ Often forgotten |
+| **Error** | Something went wrong | ⚠️ Often forgotten |
+| **Empty** | No data exists yet | ⚠️ Often forgotten |
+| **Disabled** | Action not available | 🟡 Sometimes missing |
+| **Success** | Action completed | ⚠️ Often forgotten |
+
+Not every state applies to every component — a Button has no Empty state; a data table has no Active state. Use judgment. The States Coverage Map widget tracks all 9 and lets you mark cells N/A where a state genuinely can't apply.
+
+---
+
+## Loading States
+
+### When to use what
+
+| Pattern | Best For |
+|---|---|
+| **Skeleton screen** | Content-heavy layouts (feeds, cards, tables) |
+| **Spinner** | Short, action-triggered waits (button click, form submit) |
+| **Progress bar** | Long operations where progress can be measured (upload, export) |
+| **Shimmer / pulse** | Image placeholders and text blocks |
+
+### Rules
+- **Never show a blank screen.** Even a spinner is better than nothing.
+- **Skeleton screens beat spinners** for perceived performance — the layout already exists, so content "appears" rather than "loading."
+- **Show loading state immediately** — don't wait 500ms before showing anything. Users click again if nothing happens.
+- **Skeleton shapes should match real content shapes.** A skeleton for a card should have lines where the title, description, and image will be — not generic rectangles.
+- **Don't show too many spinners at once.** If five components all have their own spinner, the page feels broken. Consolidate into a page-level or section-level loading state.
+
+### Loading State Checklist
+- [ ] Every data fetch has a visual loading indicator
+- [ ] Skeleton shapes match actual content layout
+- [ ] Loading state matches the overall visual style (not plain gray boxes in an otherwise polished UI)
+- [ ] Buttons show a loading state when clicked (spinner inside, disabled)
+- [ ] Long operations have a progress indicator
+
+---
+
+## Empty States
+
+Empty states are one of the most underdesigned parts of any product. They're the first thing a brand new user sees — and often the thing that determines whether they come back.
+
+### Anatomy of a Good Empty State
+
+```
+[Illustration or icon]
+
+[Friendly headline]
+"You haven't added any tasks yet"
+
+[Helpful context — optional]
+"Tasks help you track work and stay on schedule."
+
+[Clear call to action]
+[+ Create your first task]
+```
+
+### Rules
+- **Always include a CTA.** An empty state without an action leaves the user stranded.
+- **Be specific.** "Nothing here yet" is useless. "You haven't connected any integrations — connect Slack to get started" is actionable.
+- **Match the tone of the product.** A playful product can have a fun illustration. An enterprise tool should stay professional.
+- **Don't use sad/broken imagery** (broken robots, crying faces) — it implies the product failed, not that the user just needs to add something.
+- **Search empty states are different** — "No results for 'purple elephant'" needs different copy and a different CTA (clear search, refine filters) than a true empty state.
+
+### Types of Empty States
+
+| Type | Example | CTA |
+|---|---|---|
+| **First-use** | New user, no data created yet | Create first item |
+| **Cleared** | User deleted everything | Undo or create new |
+| **Search/filter** | No results match the query | Clear filters |
+| **Error-caused** | Data failed to load | Retry |
+| **Permission** | User can't see data | Request access |
+
+### Empty State Checklist
+- [ ] Every list, table, feed, or grid has a designed empty state
+- [ ] Empty states include an illustration/icon, headline, and CTA
+- [ ] Search/filter empty state is distinct from first-use empty state
+- [ ] Copy is specific and helpful, not generic
+
+---
+
+## Error States
+
+### Levels of Error
+
+| Level | Examples | How to Handle |
+|---|---|---|
+| **Field validation** | Invalid email, password too short | Inline message below the field |
+| **Form-level** | Missing required fields on submit | Summary at top + highlight fields |
+| **Action failure** | "Save failed — try again" | Toast or inline error near the action |
+| **Page-level** | 404, server error, network offline | Full error page with recovery action |
+| **Partial failure** | 3 of 5 items loaded | Inline error on failed items, rest still usable |
+
+### Rules
+- **Say what went wrong AND what to do.** "Something went wrong" with no next step is a dead end.
+- **Don't blame the user.** "You entered an invalid email" vs "The email address doesn't look right — check for typos." The second is kinder.
+- **Error messages should be specific.** "Error 500" means nothing to a user. "We couldn't save your changes — check your connection and try again" is helpful.
+- **Position errors close to the cause.** Field errors below the field. Form errors near the submit button. Don't show errors at the top of the page for a field at the bottom.
+- **Preserve user input.** If a form fails, never clear the fields. Force the user to retype everything = guaranteed frustration.
+- **Retry should be one click.** If something fails, a "Try again" button should be immediately available.
+
+### Error State Checklist
+- [ ] Field validation errors appear inline, below the field
+- [ ] Error messages say what's wrong and how to fix it
+- [ ] Failed actions have a retry option
+- [ ] Page-level errors (404, 500) have a designed state, not a browser default
+- [ ] Error messages never clear user's input
+- [ ] Errors use both color AND text/icon (not color alone)
+
+---
+
+## Success States
+
+Success states close the loop — they tell the user "yes, it worked." Without them, users click submit buttons twice, refresh pages, or simply don't know if their action completed.
+
+### Patterns
+
+| Pattern | Best For | Duration |
+|---|---|---|
+| **Toast / snackbar** | Non-critical confirmations ("Saved", "Copied") | 3–5 seconds, then auto-dismiss |
+| **Inline confirmation** | Form submission, settings saved | Until next user action |
+| **State change** | Button changes to "Saved ✓", item marked complete | Persistent until state changes |
+| **Full screen** | Payment completed, account created | One-time, then redirect |
+| **Email confirmation** | Account verification, order placed | The page becomes a holding state |
+
+### Rules
+- **Be specific.** "Saved" is fine. "Project 'Q4 Launch' saved" is better.
+- **Auto-dismiss toasts after 3–5 seconds.** Persistent toasts that require manual dismissal block the UI.
+- **Don't use green for everything.** Reserve green for genuine success. Confirmations that aren't "good news" (e.g., "Your account has been deleted") shouldn't be green.
+- **Success states need to be accessible.** Toasts that appear and disappear must be announced to screen readers (`role="status"` or `aria-live="polite"`).
+
+### Success State Checklist
+- [ ] Every form submission has a visible success confirmation
+- [ ] Toasts auto-dismiss and are screen-reader accessible
+- [ ] Destructive actions (delete, cancel) confirm completion without using green
+
+---
+
+## Disabled States
+
+### Rules
+- **Look clearly different from enabled.** Reduced opacity (50–60%) is the standard pattern.
+- **Never remove disabled elements entirely** — this is confusing. Show them, just make them unclickable.
+- **Explain why when possible.** A tooltip on hover: "You need admin access to do this" is vastly better than a greyed-out button with no context.
+- **Don't use color alone** to signal disabled — combine reduced opacity with `cursor: not-allowed` and `aria-disabled="true"`.
+- **Disabled inputs** should still be readable (contrast ≥ 3:1 even in disabled state).
+
+### Disabled State Checklist
+- [ ] Disabled elements are visually distinct (opacity + cursor)
+- [ ] Disabled state doesn't remove elements from the layout
+- [ ] Where possible, a tooltip explains why the element is disabled
+- [ ] `aria-disabled="true"` set for screen readers
+
+---
+
+## Code-Specific State Checks
+
+When auditing HTML/CSS/React/Vue, the following state implementations can be verified directly from code — do not guess from visual inspection alone.
+
+### Loading state
+```
+aria-busy attribute:
+  → <section aria-busy="true"> during loading → ✅
+  → Loading state with no aria-busy → 🟢 Tip
+
+Skeleton screen HTML pattern:
+  → <div class="skeleton" aria-hidden="true"> → ✅ (hidden from AT, decorative)
+  → Skeleton without aria-hidden → 🟢 Tip
+
+Button loading pattern:
+  → <button disabled aria-disabled="true"><Spinner /> Saving...</button> → ✅
+  → <button> still interactive during async action → 🔴 Critical (double-submit risk)
+```
+
+### Error state
+```
+aria-invalid:
+  → <input aria-invalid="true"> on a field with a validation error → ✅
+  → Error visible but aria-invalid missing → 🟡 Warning
+
+aria-describedby linking error message:
+  → <input aria-describedby="field-error"> ... <span id="field-error">...</span> → ✅
+  → Error message not linked via aria-describedby → 🟡 Warning
+
+role="alert" on dynamic errors:
+  → <div role="alert"> for errors injected after page load → ✅ (announced immediately)
+  → Errors injected into DOM without role="alert" or aria-live → 🟡 Warning
+```
+
+### Success state (toasts and confirmations)
+```
+aria-live on toast containers:
+  → <div aria-live="polite" aria-atomic="true"> wrapping toast area → ✅
+  → Toast visible in DOM but no aria-live → 🟡 Warning (screen readers miss it)
+  → role="status" is equivalent to aria-live="polite" → ✅
+
+Auto-dismiss timing:
+  → Toast dismissed < 2 seconds → 🟡 (too fast for screen readers to announce)
+  → Toast dismissed at 3–5 seconds → ✅
+  → Toast never auto-dismissed → 🟢 Tip (blocks UI permanently)
+```
+
+### Disabled state
+```
+aria-disabled vs disabled attribute:
+  → <button disabled> removes from tab order (correct for forms) → ✅
+  → <button aria-disabled="true"> keeps in tab order (better for explaining why) → ✅
+  → Interactive element visually greyed out with neither disabled nor aria-disabled → 🔴
+
+cursor: not-allowed:
+  → disabled elements missing cursor: not-allowed → 🟢 Tip
+  → pointer-events: none alone (without aria-disabled) → 🟡 (keyboard still activatable)
+
+Opacity for disabled visual:
+  → opacity: 0.5 or 0.4 on disabled elements → ✅
+  → opacity: 0.15 or lower → 🟡 (contrast too low, violates WCAG disabled contrast guideline)
+```
+
+### Empty state
+```
+Empty state detection in code:
+  → Conditional render: {items.length === 0 && <EmptyState />} → ✅
+  → Array renders with no empty state fallback → 🟡 Warning
+  → Search/filter result with no "no results" state → 🟡 Warning
+
+Empty state accessibility:
+  → Empty state illustration should have aria-hidden="true" (decorative)
+  → Heading inside empty state should be a proper <h> level, not <p> or <div>
+```
+
+### Focus state
+```
+outline: none / outline: 0 detection:
+  → Any global *:focus { outline: none } → 🔴 Critical
+  → :focus-visible { outline: none } → 🔴 Critical (still removes focus for keyboard users)
+  → :focus { outline: none } with :focus-visible alternative → ✅ (progressive enhancement)
+
+Focus ring visibility:
+  → :focus-visible with visible outline (2px solid, not just color change) → ✅
+  → Focus managed only via box-shadow (no outline) → 🟡 (Windows High Contrast Mode loses it)
+  → Recommended: outline: 2px solid var(--color-focus); outline-offset: 2px → ✅
+```

package/skills/design-auditor/references/tokens.md

@@ -0,0 +1,286 @@
+# Design Tokens & Variables Health Reference
+
+Design tokens are the single source of truth for visual decisions — colors, spacing, typography, shadows, radii. A healthy token system means changing one value updates the entire product. A broken system means hunting through hundreds of files to change a brand color.
+
+---
+
+## What Are Design Tokens?
+
+Design tokens are named variables that store visual values:
+
+```
+color.primary.500 = #7c3aed
+spacing.4 = 16px
+font.size.body = 16px
+radius.md = 8px
+shadow.card = 0 4px 8px rgba(0,0,0,0.08)
+```
+
+Instead of using `#7c3aed` directly in a component, you reference `color.primary.500`. When the brand color changes, you update one token — everything updates automatically.
+
+---
+
+## Token Naming Systems
+
+### Anti-Pattern: Descriptive Names
+Naming tokens after their appearance breaks when values change:
+
+```
+❌ color.purple = #7c3aed   → What if purple becomes blue? The name is now wrong.
+❌ color.red-500 = #ef4444  → Is this always used for danger? Or sometimes for decoration?
+```
+
+### Best Practice: Semantic Names
+Name tokens by their **purpose**, not their **value**:
+
+```
+✅ color.brand.primary = #7c3aed     → The main brand color, whatever it is
+✅ color.feedback.danger = #ef4444   → Used for error states everywhere
+✅ color.text.secondary = #6b7280    → Secondary text color
+✅ color.background.surface = #f9fafb → Card/panel backgrounds
+```
+
+### Two-Tier Token System (Industry Best Practice)
+
+**Tier 1 — Primitive tokens** (raw values):
+```
+color.purple.500 = #7c3aed
+color.red.500 = #ef4444
+spacing.4 = 16px
+```
+
+**Tier 2 — Semantic tokens** (reference primitives):
+```
+color.brand.primary = color.purple.500
+color.feedback.danger = color.red.500
+color.interactive.default = color.purple.500
+```
+
+Components reference **semantic tokens only**. Primitives are never used directly in components. This allows you to remap semantic meaning without touching components (e.g. changing brand color from purple to blue: update one primitive reference).
+
+---
+
+## Token Categories
+
+### Color Tokens
+
+```
+color.brand.primary       — Primary brand color (buttons, links, highlights)
+color.brand.secondary     — Secondary brand color
+color.brand.accent        — Accent/pop color
+
+color.text.primary        — Main body text
+color.text.secondary      — Supporting text, captions
+color.text.disabled       — Disabled state text
+color.text.inverse        — Text on dark/colored backgrounds
+color.text.link           — Hyperlink color
+
+color.background.page     — Base page/app background
+color.background.surface  — Cards, panels, containers
+color.background.elevated — Dropdowns, modals, tooltips
+color.background.overlay  — Modal backdrop scrim
+
+color.border.default      — Standard borders
+color.border.subtle       — Dividers, faint borders
+color.border.focus        — Focus ring color
+color.border.danger       — Error state border
+
+color.feedback.success    — Success states
+color.feedback.warning    — Warning states
+color.feedback.danger     — Error states
+color.feedback.info       — Informational states
+```
+
+### Spacing Tokens
+```
+spacing.1  = 4px
+spacing.2  = 8px
+spacing.3  = 12px
+spacing.4  = 16px
+spacing.6  = 24px
+spacing.8  = 32px
+spacing.10 = 40px
+spacing.12 = 48px
+spacing.16 = 64px
+```
+
+### Typography Tokens
+```
+font.family.sans    = 'Figtree', sans-serif
+font.family.mono    = 'JetBrains Mono', monospace
+
+font.size.xs   = 11px
+font.size.sm   = 13px
+font.size.md   = 15px
+font.size.base = 16px
+font.size.lg   = 18px
+font.size.xl   = 20px
+font.size.2xl  = 24px
+font.size.3xl  = 30px
+font.size.4xl  = 36px
+
+font.weight.regular    = 400
+font.weight.medium     = 500
+font.weight.semibold   = 600
+font.weight.bold       = 700
+
+line.height.tight   = 1.2
+line.height.snug    = 1.35
+line.height.normal  = 1.5
+line.height.relaxed = 1.6
+```
+
+---
+
+## Dark Mode Token Architecture
+
+The most important benefit of a semantic token system is clean dark mode support.
+
+### How It Works
+Instead of creating separate dark mode components, you remap semantic token values:
+
+```css
+/* Light mode */
+:root {
+  --color-background-page: #ffffff;
+  --color-text-primary: #111827;
+  --color-background-surface: #f9fafb;
+  --color-border-default: #e5e7eb;
+}
+
+/* Dark mode — same tokens, different values */
+[data-theme="dark"] {
+  --color-background-page: #0f172a;
+  --color-text-primary: #f1f5f9;
+  --color-background-surface: #1e293b;
+  --color-border-default: #334155;
+}
+```
+
+Components use `var(--color-background-page)` — they don't need to know which mode they're in. The theme switch happens at one level.
+
+### Signs the Token System is Broken for Dark Mode
+- Components have hardcoded hex values that don't change in dark mode
+- Dark mode overrides are scattered across individual component files
+- Dark mode colors are new hardcoded values, not remapped tokens
+- Some components adapt to dark mode but others don't
+
+---
+
+## Auditing Token Health in a Codebase
+
+### Signs of a Healthy Token System
+- All colors in components reference CSS variables or JS tokens
+- No hardcoded hex values (`#abc123`) in component styles
+- Spacing values are multiples of the base unit (4 or 8)
+- Typography uses a defined text style system
+- Dark mode works by swapping a theme class, not editing components
+
+### Signs of a Broken Token System
+
+**Red flags in CSS/code:**
+```css
+/* ❌ Hardcoded values — no token */
+color: #7c3aed;
+margin: 13px;
+font-size: 15px;
+border-radius: 7px;
+box-shadow: 0 3px 7px rgba(0,0,0,0.11);
+```
+
+```css
+/* ✅ Tokenized */
+color: var(--color-brand-primary);
+margin: var(--spacing-3);
+font-size: var(--font-size-md);
+border-radius: var(--radius-md);
+box-shadow: var(--shadow-sm);
+```
+
+**Red flags in Figma:**
+- Components use local styles instead of shared library styles
+- Colors show as hex values in the inspector, not style names
+- "Detached" text styles (no linked text style)
+- Different teams using different color values for the same UI element
+
+### Token Coverage Audit
+
+Run a search for hardcoded values in your codebase:
+```bash
+# Find hardcoded hex colors (not in token definition files)
+grep -r "#[0-9a-fA-F]\{3,6\}" src/components/
+
+# Find hardcoded pixel spacing
+grep -rE "margin|padding|gap" src/components/ | grep -v "var(--"
+
+# Find hardcoded font sizes
+grep -rE "font-size:\s*[0-9]" src/components/ | grep -v "var(--"
+```
+
+Any hits in component files (not token definition files) are candidates for tokenization.
+
+---
+
+## Token System Maturity Levels
+
+| Level | Description | Signs |
+|---|---|---|
+| **0 — No system** | All values hardcoded | Hex values everywhere, no variables |
+| **1 — Basic variables** | CSS variables exist but naming is inconsistent | Mix of `--purple`, `--color-primary`, `#7c3aed` |
+| **2 — Consistent naming** | Variables follow a naming convention | All components use tokens, names are meaningful |
+| **3 — Semantic + primitive** | Two-tier system in place | Components only use semantic tokens |
+| **4 — Multi-theme** | Token system supports light/dark/brand themes | Theme switching works by swapping one class |
+| **5 — Cross-platform** | Tokens shared between web, iOS, Android | Single source of truth across platforms |
+
+---
+
+## Common Token Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Naming tokens by value (`--red`, `--purple-500`) | Name by purpose (`--color-danger`, `--color-brand-primary`) |
+| Using primitive tokens directly in components | Create semantic tokens; components reference semantic only |
+| Hardcoding hex values in components | Replace with token references |
+| Different tokens for same concept in different parts of codebase | Audit and consolidate — one token per concept |
+| Dark mode via per-component overrides | Remap semantic tokens at theme level |
+| Tokens defined but not used consistently | Enforce via linting (stylelint, custom ESLint rules) |
+| Spacing that doesn't follow the token scale | Replace with scale tokens, remove magic numbers |
+
+---
+
+## Token Health Score
+
+Use this formula to quickly assess the health of a token system during an audit:
+
+### How to Score
+
+Check 5 areas, each worth 20 points:
+
+| Area | 20pts (Full) | 10pts (Partial) | 0pts (Missing) |
+|---|---|---|---|
+| **Color** | All colors are tokens, semantic naming | Mix of tokens + hardcoded | Mostly hardcoded hex |
+| **Spacing** | All spacing uses scale tokens | Some tokens, some arbitrary | Mostly arbitrary px values |
+| **Typography** | Font size/weight/line-height tokenized | Partial tokenization | All hardcoded |
+| **Dark Mode** | Single theme swap, no new hex values | Some components adapt | Per-component overrides or no dark mode |
+| **Naming** | Semantic (purpose-based) naming throughout | Mix of semantic + descriptive | Descriptive or no naming convention |
+
+### Token Health Score Bands
+
+| Score | Health Level | What It Means |
+|---|---|---|
+| **90–100** | ✅ Excellent | System is production-grade, scalable, and maintainable |
+| **70–89** | 🟡 Good | Minor gaps, easy to clean up |
+| **50–69** | 🟠 Needs Work | Significant hardcoding, inconsistent adoption |
+| **< 50** | 🔴 Broken | Tokens exist in name only — no real system |
+
+### Quick Audit Command
+Run this to get a rough hardcoded value count in a codebase:
+```bash
+# Count hardcoded hex colors in component files
+grep -rE "#[0-9a-fA-F]{3,6}" src/components/ | grep -v "token\|variable\|\.tokens\." | wc -l
+
+# Count hardcoded px spacing (not in token files)
+grep -rE "(margin|padding|gap):\s*[0-9]+px" src/components/ | grep -v "var(--" | wc -l
+```
+
+A healthy codebase returns **0** for both. Every non-zero hit is a token debt item.