@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/skills/ux-ui-design/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: flux:ux-ui-design
+description: Expert UX/UI design guidance for creating simple, user-focused experiences with clean, cohesive interfaces. Use when designing or reviewing UI components, layouts, navigation, forms, or any user-facing interface. Applies human-centered design principles and explicitly avoids AI slop patterns (generic, over-designed, feature-bloated interfaces). Triggers on UI implementation, design decisions, component creation, or layout work.
+user-invocable: false
+---
+
+# UX/UI Design Skill
+
+Design guidance for creating interfaces that are simple for users and visually clean—not generic AI slop.
+
+## Core Philosophy
+
+**UX**: Remove friction. Every interaction should feel effortless.
+**UI**: Less is more. Every element earns its place.
+
+---
+
+## UX Principles
+
+### 1. Reduce Cognitive Load
+
+Users form opinions in 50ms. Simplify ruthlessly.
+
+- **One primary action per screen** — Secondary actions stay subtle
+- **Progressive disclosure** — Show basics upfront, reveal complexity on demand
+- **Predictable patterns** — Consistency reduces learning curve
+
+```
+❌ Dashboard with 12 cards, 5 CTAs, sidebar, and floating action button
+✅ Dashboard with 3 key metrics, one primary action, minimal navigation
+```
+
+### 2. Design for Intent, Not Features
+
+Start with user goals, not feature lists.
+
+| User Intent | Good Design | Bad Design |
+|-------------|-------------|------------|
+| "Find a product" | Search bar prominent, filters accessible | Feature tour modal on load |
+| "Complete checkout" | Linear flow, minimal fields | Upsells interrupting every step |
+| "Check status" | Status visible immediately | Requires 3 clicks to find |
+
+### 3. Respect User Time
+
+- **Minimize steps** — Combine related actions
+- **Smart defaults** — Pre-fill what you can infer
+- **Instant feedback** — Show loading states, confirm actions immediately
+- **Remember state** — Don't make users repeat themselves
+
+### 4. Error Prevention Over Error Messages
+
+Design to prevent errors, not just handle them.
+
+```
+❌ "Invalid email format" after submit
+✅ Real-time validation as user types
+
+❌ Delete button with no confirmation
+✅ Undo within 5 seconds, or confirmation for destructive actions
+```
+
+---
+
+## UI Principles
+
+### 1. Visual Hierarchy
+
+Guide attention through deliberate contrast.
+
+**Size**: Larger = more important
+**Color**: Accent colors for actions, muted for secondary
+**Space**: Whitespace groups related elements, separates sections
+**Position**: Top-left starts the reading flow (LTR languages)
+
+```
+Primary action:   Bold, accent color, prominent size
+Secondary action: Outlined or text-only, subdued
+Tertiary action:  Text link, smallest
+```
+
+### 2. Limited Color Palette
+
+95% of minimalist interfaces use a restricted palette.
+
+**Core palette structure:**
+- 1 neutral background (white, off-white, or dark mode equivalent)
+- 1-2 accent colors (one primary, one optional secondary)
+- Semantic colors: success (green), warning (amber), error (red), info (blue)
+- Text: 2-3 shades (primary, secondary, disabled)
+
+```css
+/* Example minimal palette */
+--bg-primary: #FFFFFF;
+--bg-secondary: #F8F9FA;
+--text-primary: #1A1A1A;
+--text-secondary: #6B7280;
+--accent: #2563EB;
+--accent-hover: #1D4ED8;
+```
+
+### 3. Typography
+
+One typeface, multiple weights. Never more than two font families.
+
+**Hierarchy through weight and size, not different fonts:**
+- Headings: Semibold or bold, larger size
+- Body: Regular weight, comfortable reading size (16px minimum)
+- Captions: Regular or medium, smaller size, secondary color
+
+**Line height**: 1.4-1.6 for body text, 1.2-1.3 for headings
+
+### 4. Spacing System
+
+Use consistent spacing tokens—never arbitrary values.
+
+```
+4px  (xs)  — Tight spacing within components
+8px  (sm)  — Related elements
+16px (md)  — Standard spacing
+24px (lg)  — Section separation
+32px (xl)  — Major sections
+48px (2xl) — Page-level spacing
+```
+
+**Rule**: Space between elements = relationship strength. Closer = more related.
+
+### 5. Whitespace as Design Element
+
+Empty space is not wasted space. It:
+- Reduces cognitive load
+- Creates visual breathing room
+- Emphasizes important elements
+- Communicates hierarchy
+
+```
+❌ Cramped form with no padding
+✅ Generous padding, grouped fields with clear sections
+```
+
+---
+
+## Avoiding AI Slop
+
+AI slop = generic, over-engineered, feature-bloated design that looks "designed" but lacks soul.
+
+### Red Flags (Don't Do This)
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Gradient everything | Looks like a template | Flat colors, subtle shadows only |
+| Rounded corners on everything | Generic "modern" look | Consistent radius, not excessive |
+| Unnecessary animations | Distracting, slow | Purposeful micro-interactions only |
+| Stock illustrations everywhere | Feels corporate/hollow | Use sparingly or not at all |
+| Feature overload | "Look how much it does!" | Ship less, ship focused |
+| Symmetric grids always | Predictable, boring | Intentional asymmetry when appropriate |
+| Drop shadows on everything | Cluttered, dated | Minimal elevation, purposeful depth |
+| Glassmorphism/neumorphism by default | Trendy but often inaccessible | Use sparingly, ensure contrast |
+
+### AI Slop Content Patterns to Avoid
+
+- Generic hero sections with vague taglines ("Empower your workflow")
+- Cookie-cutter landing page layouts
+- Feature grids with icons that could apply to anything
+- Excessive use of buzzwords in UI copy
+- Decorative elements that add no meaning
+
+### What Makes Design Feel Human
+
+- **Personality in copywriting** — Real voice, not corporate speak
+- **Intentional imperfection** — Hand-drawn elements, custom illustrations
+- **Constraint** — Knowing what NOT to include
+- **Context-awareness** — Design serves the specific use case, not generic patterns
+- **Consistency over novelty** — Boring is often better
+
+---
+
+## Component Guidelines
+
+### Buttons
+
+```
+Primary:   Solid background, high contrast text, clear CTA
+Secondary: Outlined or ghost, lower visual weight
+Tertiary:  Text-only, for less important actions
+Disabled:  50% opacity, no pointer events
+
+Sizing:
+- Small: 32px height, compact UI
+- Medium: 40px height, default
+- Large: 48px height, touch targets, primary CTAs
+```
+
+### Forms
+
+- Labels above inputs (not placeholder-as-label)
+- Clear focus states (visible ring, color change)
+- Inline validation, not just on submit
+- Logical tab order
+- Required field indicators (asterisk or text)
+- Helpful hint text for complex fields
+
+```
+❌ Placeholder text as the only label
+❌ Error messages appearing somewhere else on screen
+❌ Submit button disabled with no explanation why
+
+✅ Clear labels, visible focus, inline errors, enabled submit with validation
+```
+
+### Cards
+
+- Consistent padding (16-24px)
+- Clear content hierarchy
+- Single primary action if any
+- Subtle shadow or border, not both
+- Avoid nesting cards within cards
+
+### Navigation
+
+- Primary nav: 5-7 items maximum
+- Mobile: Hamburger menu or bottom nav (not both)
+- Current state clearly indicated
+- Breadcrumbs for deep hierarchies
+- Search accessible on complex sites
+
+### Tables
+
+- Left-align text, right-align numbers
+- Zebra striping OR grid lines, not both
+- Sticky headers for long tables
+- Sort indicators when sortable
+- Row actions: hover reveal or action column
+- Pagination or infinite scroll, clear indication of more data
+
+### Modals/Dialogs
+
+- Clear title describing the action
+- Single primary action, cancel always available
+- Focus trapped within modal
+- Escape key closes (unless destructive action)
+- Background overlay with click-to-close
+- Don't nest modals
+
+---
+
+## Responsive Design
+
+### Breakpoints (Standard)
+
+```
+sm:  640px  — Small tablets, large phones landscape
+md:  768px  — Tablets portrait
+lg:  1024px — Tablets landscape, small laptops
+xl:  1280px — Desktops
+2xl: 1536px — Large desktops
+```
+
+### Mobile-First Patterns
+
+- Stack columns on mobile, expand on desktop
+- Touch targets: minimum 44x44px
+- Thumb-friendly zones for critical actions
+- Simplify navigation for mobile
+- Reduce content density, not just shrink
+
+### What Changes on Mobile
+
+| Desktop | Mobile |
+|---------|--------|
+| Horizontal nav | Hamburger or bottom nav |
+| Multi-column grid | Single column or 2-col max |
+| Hover states | Tap states (no hover on touch) |
+| Side panels | Full-screen overlays |
+| Data tables | Cards or simplified tables |
+
+---
+
+## Accessibility Checklist
+
+Not optional. Design for everyone.
+
+- [ ] Color contrast: 4.5:1 minimum for text
+- [ ] Don't rely on color alone (add icons, text, patterns)
+- [ ] Focus states visible and clear
+- [ ] Keyboard navigation works
+- [ ] Alt text on meaningful images
+- [ ] Form labels associated with inputs
+- [ ] Error messages clear and specific
+- [ ] Touch targets 44x44px minimum
+- [ ] Motion can be reduced (respects prefers-reduced-motion)
+- [ ] Text resizable without breaking layout
+
+---
+
+## Implementation Checklist
+
+Before shipping any interface:
+
+### UX Verification
+- [ ] Primary action is immediately obvious
+- [ ] User can accomplish goal in minimum steps
+- [ ] Error states are helpful, not just red
+- [ ] Loading states exist for async operations
+- [ ] Empty states guide users to next action
+
+### UI Verification
+- [ ] Spacing follows consistent scale
+- [ ] Typography hierarchy is clear
+- [ ] Color palette is limited and intentional
+- [ ] Components are consistent throughout
+- [ ] No orphan elements (everything aligned to grid)
+
+### Anti-Slop Check
+- [ ] Could remove any element without losing function?
+- [ ] Does every gradient/shadow/animation serve a purpose?
+- [ ] Would a non-designer find it cluttered?
+- [ ] Is the copywriting specific to this product?
+- [ ] Does it look distinct from a template?
+
+---
+
+## Quick Reference
+
+### When Designing
+
+1. **Start with user intent** — What are they trying to do?
+2. **Minimize choices** — Each decision = cognitive load
+3. **Establish hierarchy** — What's most important?
+4. **Apply constraints** — Limited colors, spacing scale, one typeface
+5. **Remove until it breaks** — Then add back only what's needed
+
+### When Reviewing
+
+Ask these questions:
+- Can I remove anything?
+- Is the primary action obvious?
+- Does the spacing feel consistent?
+- Is there unnecessary decoration?
+- Would this work on mobile?
+
+---
+
+## References
+
+For detailed design token specifications and component patterns, see:
+- `references/design-tokens.md` — Spacing, color, typography scales

package/skills/ux-ui-design/references/design-tokens.md

@@ -0,0 +1,359 @@
+# Design Tokens Reference
+
+Standardized design values for consistent, scalable interfaces.
+
+## Spacing Scale
+
+Use multiples of 4px for all spacing.
+
+| Token | Value | Use Case |
+|-------|-------|----------|
+| `--space-0` | 0 | Reset spacing |
+| `--space-1` | 4px | Tight: icon-text gap, inline elements |
+| `--space-2` | 8px | Compact: related elements within a component |
+| `--space-3` | 12px | Default: form field gaps, list item padding |
+| `--space-4` | 16px | Standard: card padding, section gaps |
+| `--space-5` | 20px | Comfortable: grouped content spacing |
+| `--space-6` | 24px | Relaxed: between sections |
+| `--space-8` | 32px | Large: major section separation |
+| `--space-10` | 40px | Generous: page section margins |
+| `--space-12` | 48px | Extra: hero sections, major landmarks |
+| `--space-16` | 64px | Maximum: page-level vertical rhythm |
+
+### CSS Variables
+
+```css
+:root {
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  --space-5: 1.25rem;  /* 20px */
+  --space-6: 1.5rem;   /* 24px */
+  --space-8: 2rem;     /* 32px */
+  --space-10: 2.5rem;  /* 40px */
+  --space-12: 3rem;    /* 48px */
+  --space-16: 4rem;    /* 64px */
+}
+```
+
+---
+
+## Typography Scale
+
+Based on a 1.25 ratio (major third) from 16px base.
+
+| Token | Size | Line Height | Use Case |
+|-------|------|-------------|----------|
+| `--text-xs` | 12px | 1.5 | Labels, captions, fine print |
+| `--text-sm` | 14px | 1.5 | Secondary text, table cells |
+| `--text-base` | 16px | 1.5 | Body text, inputs |
+| `--text-lg` | 18px | 1.5 | Lead paragraphs |
+| `--text-xl` | 20px | 1.4 | H4, card titles |
+| `--text-2xl` | 24px | 1.3 | H3 |
+| `--text-3xl` | 30px | 1.3 | H2 |
+| `--text-4xl` | 36px | 1.2 | H1, page titles |
+| `--text-5xl` | 48px | 1.1 | Hero headings |
+
+### Font Weights
+
+| Token | Weight | Use Case |
+|-------|--------|----------|
+| `--font-normal` | 400 | Body text |
+| `--font-medium` | 500 | Emphasis, labels |
+| `--font-semibold` | 600 | Subheadings, buttons |
+| `--font-bold` | 700 | Headings, strong emphasis |
+
+### CSS Variables
+
+```css
+:root {
+  /* Sizes */
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+  --text-4xl: 2.25rem;
+  --text-5xl: 3rem;
+
+  /* Line heights */
+  --leading-tight: 1.2;
+  --leading-snug: 1.3;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.625;
+
+  /* Weights */
+  --font-normal: 400;
+  --font-medium: 500;
+  --font-semibold: 600;
+  --font-bold: 700;
+}
+```
+
+---
+
+## Color Tokens
+
+### Neutral Colors (Light Mode)
+
+| Token | Value | Use Case |
+|-------|-------|----------|
+| `--neutral-50` | #FAFAFA | Page background |
+| `--neutral-100` | #F5F5F5 | Card backgrounds, subtle fills |
+| `--neutral-200` | #E5E5E5 | Borders, dividers |
+| `--neutral-300` | #D4D4D4 | Disabled borders |
+| `--neutral-400` | #A3A3A3 | Placeholder text |
+| `--neutral-500` | #737373 | Secondary text |
+| `--neutral-600` | #525252 | Body text (secondary) |
+| `--neutral-700` | #404040 | Body text |
+| `--neutral-800` | #262626 | Headings |
+| `--neutral-900` | #171717 | High contrast text |
+
+### Semantic Colors
+
+```css
+:root {
+  /* Primary */
+  --primary-50: #EFF6FF;
+  --primary-100: #DBEAFE;
+  --primary-500: #3B82F6;
+  --primary-600: #2563EB;
+  --primary-700: #1D4ED8;
+
+  /* Success */
+  --success-50: #F0FDF4;
+  --success-500: #22C55E;
+  --success-700: #15803D;
+
+  /* Warning */
+  --warning-50: #FFFBEB;
+  --warning-500: #F59E0B;
+  --warning-700: #B45309;
+
+  /* Error */
+  --error-50: #FEF2F2;
+  --error-500: #EF4444;
+  --error-700: #B91C1C;
+
+  /* Info */
+  --info-50: #EFF6FF;
+  --info-500: #3B82F6;
+  --info-700: #1D4ED8;
+}
+```
+
+### Dark Mode Mapping
+
+| Light Token | Dark Equivalent |
+|-------------|-----------------|
+| `--neutral-50` (bg) | `--neutral-900` |
+| `--neutral-100` (surface) | `--neutral-800` |
+| `--neutral-200` (border) | `--neutral-700` |
+| `--neutral-700` (text) | `--neutral-200` |
+| `--neutral-900` (heading) | `--neutral-50` |
+
+---
+
+## Border Radius
+
+| Token | Value | Use Case |
+|-------|-------|----------|
+| `--radius-none` | 0 | No rounding |
+| `--radius-sm` | 4px | Subtle rounding (inputs, buttons) |
+| `--radius-md` | 6px | Default (cards, modals) |
+| `--radius-lg` | 8px | Prominent elements |
+| `--radius-xl` | 12px | Larger containers |
+| `--radius-2xl` | 16px | Pills, avatars |
+| `--radius-full` | 9999px | Circles, full pills |
+
+### Consistency Rule
+
+Pick ONE radius for each component category and stick to it:
+- Buttons: `--radius-sm` or `--radius-md`
+- Cards: `--radius-md` or `--radius-lg`
+- Inputs: Same as buttons
+- Avatars: `--radius-full`
+
+---
+
+## Shadows
+
+| Token | Use Case |
+|-------|----------|
+| `--shadow-sm` | Subtle elevation (dropdowns, popovers) |
+| `--shadow-md` | Default cards |
+| `--shadow-lg` | Modals, dialogs |
+| `--shadow-xl` | High emphasis elements |
+
+```css
+:root {
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);
+}
+```
+
+### Shadow Guidelines
+
+- Use sparingly—most elements need no shadow
+- Shadows indicate elevation/layering
+- Cards on white backgrounds often need only subtle border OR shadow, not both
+- Dark mode: reduce shadow opacity or use lighter shadows
+
+---
+
+## Z-Index Scale
+
+| Token | Value | Use Case |
+|-------|-------|----------|
+| `--z-dropdown` | 50 | Dropdowns, popovers |
+| `--z-sticky` | 100 | Sticky headers |
+| `--z-modal` | 200 | Modal dialogs |
+| `--z-toast` | 300 | Toast notifications |
+| `--z-tooltip` | 400 | Tooltips |
+
+---
+
+## Transitions
+
+| Token | Duration | Easing | Use Case |
+|-------|----------|--------|----------|
+| `--duration-fast` | 100ms | ease-out | Hover states |
+| `--duration-normal` | 200ms | ease-in-out | Default transitions |
+| `--duration-slow` | 300ms | ease-in-out | Modals, overlays |
+
+```css
+:root {
+  --duration-fast: 100ms;
+  --duration-normal: 200ms;
+  --duration-slow: 300ms;
+  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+}
+```
+
+### Motion Guidelines
+
+- Respect `prefers-reduced-motion`
+- Keep transitions under 300ms
+- Use `transform` and `opacity` for performance
+- Avoid animating `width`, `height`, `top`, `left`
+
+---
+
+## Breakpoints
+
+| Token | Value | Description |
+|-------|-------|-------------|
+| `--screen-sm` | 640px | Small tablets |
+| `--screen-md` | 768px | Tablets |
+| `--screen-lg` | 1024px | Small laptops |
+| `--screen-xl` | 1280px | Desktops |
+| `--screen-2xl` | 1536px | Large screens |
+
+### Media Query Pattern
+
+```css
+/* Mobile first */
+.component { /* mobile styles */ }
+
+@media (min-width: 768px) {
+  .component { /* tablet+ styles */ }
+}
+
+@media (min-width: 1024px) {
+  .component { /* desktop styles */ }
+}
+```
+
+---
+
+## Component Size Tokens
+
+### Button Sizes
+
+| Size | Height | Padding X | Font Size |
+|------|--------|-----------|-----------|
+| `sm` | 32px | 12px | 14px |
+| `md` | 40px | 16px | 14px |
+| `lg` | 48px | 24px | 16px |
+
+### Input Sizes
+
+| Size | Height | Padding X | Font Size |
+|------|--------|-----------|-----------|
+| `sm` | 32px | 12px | 14px |
+| `md` | 40px | 14px | 16px |
+| `lg` | 48px | 16px | 16px |
+
+### Icon Sizes
+
+| Token | Size | Use Case |
+|-------|------|----------|
+| `--icon-xs` | 12px | Inline with small text |
+| `--icon-sm` | 16px | Inline with body text |
+| `--icon-md` | 20px | Buttons, inputs |
+| `--icon-lg` | 24px | Standalone icons |
+| `--icon-xl` | 32px | Feature icons |
+
+---
+
+## Using Tokens in Practice
+
+### Example: Card Component
+
+```css
+.card {
+  background: var(--neutral-50);
+  border: 1px solid var(--neutral-200);
+  border-radius: var(--radius-lg);
+  padding: var(--space-6);
+  box-shadow: var(--shadow-sm);
+}
+
+.card-title {
+  font-size: var(--text-xl);
+  font-weight: var(--font-semibold);
+  color: var(--neutral-900);
+  margin-bottom: var(--space-2);
+}
+
+.card-body {
+  font-size: var(--text-base);
+  color: var(--neutral-700);
+  line-height: var(--leading-relaxed);
+}
+```
+
+### Example: Button Component
+
+```css
+.btn {
+  height: 40px;
+  padding: 0 var(--space-4);
+  font-size: var(--text-sm);
+  font-weight: var(--font-semibold);
+  border-radius: var(--radius-md);
+  transition: all var(--duration-fast) var(--ease-default);
+}
+
+.btn-primary {
+  background: var(--primary-600);
+  color: white;
+}
+
+.btn-primary:hover {
+  background: var(--primary-700);
+}
+
+.btn-secondary {
+  background: transparent;
+  border: 1px solid var(--neutral-300);
+  color: var(--neutral-700);
+}
+```