Skill: zacko2o/ui-design-tips (version 1.1.0)

--- name: ui-design-tips description: "Apply practical UI/UX design principles to improve user interfaces, landing pages, web apps, and components. Use when asked to review, critique, or improve UI design; suggest design improvements for buttons, forms, headers, cards, menus, color usage, visual hierarchy, pricing pages, or any UI element; apply UX laws (Fitts's Law, Gutenberg Principle, Hick's Law, Jakob's Law, etc.); fix accessibility issues; design better onboarding, error messages, empty states, navigation, micro-interactions, or UX copy; or answer questions about UI/UX best practices. Covers visual hierarchy, CTA optimization, color usage, typography, whitespace, alignment, form design, mobile UX, dangerous actions, empty states, onboarding, UX writing, error handling, trust signals, conversion optimization, and more." --- # UI Design Tips Practical UI/UX knowledge distilled from real-world product testing (Jim Raptis / uidesign.tips) plus extended UX principles. Apply these when reviewing or improving any interface. ## Core Philosophy - **Never leave things to user imagination** — make actions explicit and obvious - **Use multiple attributes** to distinguish elements (color + icon + size, never color alone) - **Prioritize the primary action** — dangerous/secondary actions must never compete visually - **Users hate surprises** — copy and microcopy must eliminate all ambiguity - **UX > Conversions** — 10 annoyed users outweigh 1 accidental conversion --- ## 1. Visual Hierarchy The #1 design lever. Everything else builds on this. **Hacks:** - Reduce opacity of secondary info (50–70%) - Bold font-weight for primary content emphasis - Type scale ×1.25: 40px title → 32px subtitle → 25px H3 → 16px body - Left-align for LTR readability (not centered) - Group related elements (proximity = relationship) - Use size contrast: make primary elements noticeably bigger **Perfect Header formula:** 1. Strong font-weight on title 2. ×1.25 type scale 3. Lower contrast (opacity ~70%) for subtitle 4. Line-height 1.5–1.7 for body text 5. Left-aligned --- ## 2. CTA & Conversion Optimization - **Always have a CTA above the fold** — many users never scroll - **One primary CTA per screen** — multiple competing styles cause decision paralysis - **Button copy = action verb** — "Start Creating Free" beats "Submit" - **Eliminate pre-click anxiety** — add "No credit card required" / "Free forever" near the CTA - **Gutenberg Principle:** Eyes travel Z-path (top-left → top-right → bottom-left → bottom-right). Place CTA at the terminal point (bottom-right) - **Prompt scrolling** — show a glimpse of the next section to signal there's more - **Direct attention with media** — people follow lines of sight; point characters toward CTA --- ## 3. Color Usage - **Brand color = accent only** — highlight 1–2 elements maximum; everything else uses tints/shades - **Never rely on color alone** — always pair with shape/icon/label (8% of men are color-blind) - When highlighting pricing plans: use **color + size + elevation (shadow)** — minimum 2 attributes --- ## 4. Pricing Pages - **Highlight the recommended plan** with ≥2 design attributes: color + shadow + scale - Example: `transform: scale(1.04)` + distinct border color + box-shadow glow - This guides users to the popular plan and reduces decision fatigue (Hick's Law) --- ## 5. Layout & Alignment **Aligning uneven elements:** Set same width for all items using the widest element's width. **Avoid full-width paragraphs:** Limit to 500–700px. CSS: `max-width: 65ch` **Padding on rounded cards:** Use double padding on the non-rounded edges (text/icon side) **Border radius consistency:** Outer radius = 2× Inner radius --- ## 6. Cards & Clickability - **Make cards obviously clickable** — add explicit CTA button; hover effects alone aren't enough - Never rely on user experience to infer clickability — state it explicitly --- ## 7. Navigation & Menus - **Add icons next to every menu item** — visual identification without reading - **Highlight the active tab** clearly (background change, not just color) - **Whitespace over dividers** between menu sections — cleaner, less cognitive load - Only use dividers between major sections - **Keyboard shortcuts:** Display them next to action buttons (Fitts's Law reduces memory load) - **Dropdown menus:** Add icons to items for faster visual scanning --- ## 8. Forms & Inputs - **Placeholder text = guidance**, not label repetition — show format examples - **Choose correct input type** — number picker for integers, not text field - **Predefined values** reduce errors (country selectors, date pickers) - For small integer ranges (cart qty 1–10): use −/+ buttons - **Social login above email/password** for higher conversion; always provide email fallback - **Inline validation** — show errors as user types, not only on submit - **Group related fields** — billing info together, personal info together - **Progress indicators** for multi-step forms — show "Step 2 of 4" --- ## 9. Dangerous Actions - **De-emphasize destructive actions** with multiple attributes: ghost style + small font + low opacity + placement at end - **Always validate deletions** — inline or popup confirmation; never silent deletes - **Button copy = specific action**: "Delete 'Project Alpha'" beats "Delete" beats "Yes" - Consider **undo** as an alternative to confirmation dialogs (less friction, same safety) - Never style a destructive action as a primary button --- ## 10. Empty States - **Never show a blank screen** — empty states are onboarding opportunities - Offer **pre-made templates** to let users experience value immediately - Include: illustration/icon + headline + short description + primary CTA + secondary "learn more" link - Show **sample content** when possible so users understand what they're working toward --- ## 11. Onboarding & UX Copy - **Inform users of the next step** — never make them guess - Eliminate anxiety-triggering words — "Reserve" → "Try Free"; add "Cancel anytime" - **Microcopy near CTAs** is as important as the button label itself - **Progress indicators** help users commit to multi-step flows (they've already started) - Pre-fill forms with smart defaults to reduce friction --- ## 12. Error Messages - **Specific, not generic** — "Email is already in use" not "Invalid input" - **Actionable** — tell the user what to do next: "Try a different email or log in instead" - **Friendly tone** — never blame the user ("You entered..." → "We couldn't find...") - **Inline, not modal** — show errors near the field that caused them - **Preserve user input** — never clear the form on error --- ## 13. Avatars & Media - **Transparent PNG avatars:** Add background color + subtle border matching app background - **Use media to direct attention** — faces/characters should look toward the CTA - **Avatar consistency:** Apply the same border/background treatment to all avatars --- ## 14. Mobile UX - **Hover tooltips don't work on mobile** — add a tappable ❓ icon that shows tooltip on tap - **Thumb Zone:** Place primary CTAs within easy thumb reach (bottom center / lower areas) - **Touch targets ≥ 44×44px** — small targets cause misclicks and frustration - Don't rely on hover states for critical functionality - **Swipe gestures:** Always provide a visible alternative (swipe to delete = also show a delete button) --- ## 15. Accessibility - **Never use color as the only differentiator** — add icon, shape, or label - **Contrast ratio ≥ 4.5:1** for normal text, ≥ 3:1 for large text (WCAG AA) - **Icon labels** are mandatory on mobile (no hover to discover meaning) - **Focus states** must be visible — don't remove browser outlines without replacing them - **Alt text** for all meaningful images --- ## 16. Charts & Data - **Bar chart** for limited/discrete categories (monthly data, categories) - **Line chart** for continuous time-series data — don't use for discrete values (introduces false intermediate data) - Label axes clearly; don't make users guess units --- ## 17. Selected & Interactive States - **Background color change** is the strongest signal for selected items — more accessible than border alone - Show selected state at a glance — don't make users search for what they chose - **Hover states** must be meaningful, not decorative --- ## 18. Trust & Social Proof - Place trust signals **near the CTA** (not buried in footer) - Trust signals: "No credit card required" / testimonials / user counts / security badges - **Social proof proximity** — testimonials directly under the offer they're validating - Show real numbers ("12,847 users") over vague claims ("thousands of users") --- ## 19. UX Writing Checklist | ❌ Avoid | ✅ Use instead | |---------|--------------| | "Submit" | "Start Free Trial" / "Create My Account" | | "Yes" / "No" | "Delete Project" / "Keep It" | | "Error occurred" | "We couldn't save your work. Try again?" | | "Invalid input" | "Email must include @" | | "Are you sure?" | "This will permanently delete 'Project Name'" | --- --- ## 20. Micro-Interactions & Button States (from uiverse.io) Every interactive element needs **3 states minimum:** 1. **Default** — resting appearance 2. **Hover** — `translateY(-2px)` + glow/shadow increase 3. **Active/Press** — `translate(2px, 2px)` reverses lift (feels physical) **Missing active state = cheap, broken feel.** **Navigation button pattern:** - Each item gets its own accent color (icon + text change on hover) - Icons always visible, label always present (no icon-only nav) **Button animation timing rules:** - Under 300ms = fast and responsive - `ease-out` for entrances, `ease-in` for exits, never `linear` (except spinners) - Always add `@media (prefers-reduced-motion: reduce)` wrapper **Loading states:** - Skeleton screens (shimmer) > spinners for content areas - Button loading state: inline spinner after label text, `pointer-events: none` **Neon/glow effects (dark UI):** ```css /* Focus ring */ .input:focus { box-shadow: 0 0 0 3px rgba(177,79,255,0.2); } /* Hover intensify */ .btn:hover { box-shadow: 0 0 30px rgba(177,79,255,0.5); } ``` **CSS custom properties for consistent theming:** ```css :root { --accent: #b14fff; --accent-rgb: 177, 79, 255; --radius: 12px; /* card outer */ --radius-sm: 6px; /* card inner → outer = 2× inner rule */ } ``` For full CSS patterns and component code → `references/micro-interactions.md` --- --- ## 21. Color System by Product Type Choose palette based on industry psychology — not personal preference: | Category | Primary | CTA | Background | |---|---|---|---| | SaaS / Tech | Blue #2563EB | Orange #F97316 | Light #F8FAFC | | Gaming / Cyberpunk | Purple #7C3AED | Rose #F43F5E | Dark #0F0F23 | | AI Products | Purple #7C3AED | Cyan #06B6D4 | Soft #FAF5FF | | Fintech / Crypto | Gold #F59E0B | Purple #8B5CF6 | Dark #0F172A | | Healthcare | Cyan #0891B2 | Green #059669 | Light #ECFEFF | | Creative Agency | Pink #EC4899 | Cyan #06B6D4 | Soft #FDF2F8 | | E-commerce Luxury | Black #1C1917 | Gold #CA8A04 | Off-white #FAFAF9 | | Video Streaming | Black #0F0F23 | Red #E11D48 | Pure #000000 | | Food / Restaurant | Red #DC2626 | Gold #CA8A04 | Warm #FEF2F2 | **Industry rules:** - Healthcare/Medical: NEVER neon colors; ALWAYS calm + WCAG AAA - Finance/Banking: NEVER playful; ALWAYS security badges + dark navy - Gaming: NEVER minimal; ALWAYS dark mode + neon/3D effects - Kids: NEVER dark; ALWAYS rounded + bright pastels + large touch targets Full database (96 product types) → `references/design-systems-pro.md` --- ## 22. UI Style Systems (Choose by Context) **Glassmorphism** — Modern SaaS, financial, lifestyle ```css backdrop-filter: blur(15px); background: rgba(255,255,255,0.15); border: 1px solid rgba(255,255,255,0.2); ``` **Neubrutalism** — Gen Z brands, creative, startups ```css border: 3px solid #000; box-shadow: 5px 5px 0 #000; /* hard offset, no blur */ /* Hover: translate(-4px, -4px) + box-shadow: 9px 9px 0 #000 */ ``` **Bento Grid** (Apple-style) — Dashboards, product features ```css display: grid; grid-template-columns: repeat(4, 1fr); grid-auto-rows: 200px; gap: 16px; /* Cards: border-radius: 24px; hover: scale(1.02) */ ``` **Cyberpunk** — Gaming, crypto, entertainment ```css background: #0D0D0D; color: #00FF00; /* or #FF00FF / #00FFFF */ text-shadow: 0 0 10px currentColor; font-family: monospace; /* Add scanlines via ::before repeating-linear-gradient */ ``` **Claymorphism** — Kids, education, SaaS onboarding ```css border-radius: 16-24px; border: 3-4px solid rgba(0,0,0,0.1); box-shadow: inset -2px -2px 8px rgba(255,255,255,0.5), 4px 4px 8px rgba(0,0,0,0.2); /* Bounce: cubic-bezier(0.34, 1.56, 0.64, 1) */ ``` For all 60+ styles → `references/design-systems-pro.md` --- ## 23. Typography Selection Guide | Vibe | Heading | Body | |---|---|---| | Tech Startup | Space Grotesk | DM Sans | | Gaming / Esports | Russo One | Chakra Petch | | Cyberpunk / HUD | Share Tech Mono | Fira Code | | Luxury / Fashion | Cormorant | Montserrat | | Minimal SaaS | Inter | Inter | | AI / Modern | Plus Jakarta Sans | Plus Jakarta Sans | | Wellness | Lora (serif) | Raleway | | Kids / Education | Baloo 2 | Comic Neue | | News / Editorial | Newsreader | Roboto | | Gen Z Bold | Anton | Epilogue | | Crypto / Web3 | Orbitron | Exo 2 | Chinese: `Noto Sans SC` Japanese: `Noto Serif JP` + `Noto Sans JP` --- ## 24. Landing Page Pattern Selection | Goal | Pattern | Key CTA Rule | |---|---|---| | SaaS free trial | Hero + Features + CTA | Video demo + sticky CTA | | Lead generation | Lead Magnet + Form | ≤3 fields, preview lead magnet | | Pricing page | 3-tier Pricing | Middle tier = "Most Popular", annual discount 20-30% | | Brand / storytelling | Scroll Narrative | 5-7 chapters, emotional hooks | | Event / Webinar | Event Landing | Countdown + limited seats | | Waitlist | Waitlist Pattern | Countdown + email + social proof count | **CTA placement rules:** - Primary CTA: **above fold always** - Secondary: after testimonials/social proof - Sticky CTA: in navbar when hero scrolls out of view - Never > 2 CTA variants visible at once --- ## 25. Design Tokens Template ```css :root { /* Spacing (8px base) */ --space-4: 16px; --space-8: 32px; --space-12: 48px; --space-16: 64px; /* Type Scale (1.25×) */ --text-base: 16px; /* body minimum */ --text-2xl: 24px; --text-4xl: 36px; --text-6xl: 60px; /* Radius */ --radius: 12px; --radius-lg: 16px; --radius-xl: 24px; /* Elevation */ --shadow-sm: 0 1px 3px rgba(0,0,0,0.1); --shadow-md: 0 10px 20px rgba(0,0,0,0.1); --shadow-lg: 0 20px 40px rgba(0,0,0,0.15); --shadow-glow: 0 0 30px rgba(var(--accent-rgb), 0.4); /* Z-Index */ --z-1: 10; --z-2: 20; --z-modal: 50; --z-toast: 100; /* Animation */ --duration-fast: 150ms; --duration-normal: 200ms; --duration-slow: 300ms; --ease-out: cubic-bezier(0.22, 1, 0.36, 1); --spring: cubic-bezier(0.34, 1.56, 0.64, 1); /* bouncy press */ } ``` --- ## Reference Files - **UX Laws deep-dive:** `references/ux-laws.md` - **UX Writing patterns:** `references/ux-writing.md` - **Conversion checklist (40 items):** `references/conversion-checklist.md` - **CSS micro-interactions & uiverse.io patterns:** `references/micro-interactions.md` - **Design Systems Pro (color/typography/styles/99 UX issues):** `references/design-systems-pro.md`

path: references/conversion-checklist.md
content: # Conversion & UX Checklist

Use this checklist to audit any landing page, app screen, or flow for quick wins.

## Above the Fold (Hero Section)

- [ ] Clear value proposition visible without scrolling
- [ ] Primary CTA present and prominent above the fold
- [ ] Only ONE primary CTA (no competing actions)
- [ ] Trust signals near the CTA ("No credit card" / "Free forever" / user count)
- [ ] Hero describes the outcome/benefit, not just features
- [ ] Subtitle has lower contrast than headline (not competing)
- [ ] Scroll prompt visible (chevron, partial next section, or animation)
- [ ] Hero image/video directs attention toward the CTA (Gutenberg + gaze direction)

## Visual Hierarchy

- [ ] Title is clearly the largest element
- [ ] Type scale is consistent (×1.25 ratio)
- [ ] Secondary text has reduced opacity (≤70%)
- [ ] Primary action is visually dominant over secondary
- [ ] Related elements are grouped with consistent spacing
- [ ] Left-aligned text blocks (not centered paragraphs)
- [ ] Line width capped at 65ch / 500–700px

## Navigation

- [ ] Active state is obvious (background change, not just color)
- [ ] All nav items have icons + labels (not icons alone)
- [ ] Maximum 7 nav items (Miller's Law)
- [ ] Mobile nav accessible in thumb zone
- [ ] Sections separated by whitespace, not excessive dividers

## CTA Buttons

- [ ] Copy is a specific action verb (not "Submit" / "OK")
- [ ] Primary CTA is visually dominant (size + color + shadow)
- [ ] Dangerous/secondary actions are de-emphasized (ghost/text style)
- [ ] Consistent button styles throughout (same shape, same primary color)
- [ ] CTA placement at Z-pattern terminal point (bottom-right of flow)

## Forms

- [ ] Placeholder shows format example, not just repeating label
- [ ] Correct input types used (number picker for integers, etc.)
- [ ] Social login above email/password
- [ ] Progress bar shown for multi-step forms
- [ ] Inline validation (errors shown per field, not only on submit)
- [ ] Form preserves user input on error
- [ ] Error messages are specific and tell user what to do

## Pricing

- [ ] Recommended plan highlighted with ≥2 attributes (color + size + shadow)
- [ ] "Most popular" / "Best value" badge on recommended plan
- [ ] Price anchoring visible (crossed-out higher price or comparison)
- [ ] Feature comparison clearly differentiates tiers
- [ ] CTA on each plan is specific ("Start Pro Trial" not "Choose Plan")

## Dangerous Actions

- [ ] Delete / destructive actions use ghost/text style (not primary button)
- [ ] Confirmation dialog with specific copy ("Delete 'Project Name'")
- [ ] Undo option offered where technically possible
- [ ] Warning color (red/orange) used sparingly and only for actual danger

## Empty States

- [ ] Empty states have: icon + headline + description + CTA
- [ ] Templates offered instead of blank canvas
- [ ] Empty state CTA leads directly to the creation flow

## Accessibility

- [ ] Color is never the only differentiator
- [ ] All icons have text labels (especially on mobile)
- [ ] Touch targets ≥ 44×44px
- [ ] Focus states visible on all interactive elements
- [ ] Contrast ratio ≥ 4.5:1 for body text
- [ ] Alt text on all meaningful images

## Mobile

- [ ] Primary CTAs in thumb zone (lower half of screen)
- [ ] Hover-only tooltips replaced with tap-reveal ❓ icons
- [ ] No content requiring horizontal scroll (except deliberate carousels)
- [ ] Swipe gestures have visible button fallback

## Trust & Social Proof

- [ ] Trust signals placed adjacent to CTA (not buried)
- [ ] Testimonials specific (name, company, real outcome)
- [ ] Social proof uses real numbers ("12,847 users", not "thousands")
- [ ] Security/privacy indicators near data-sensitive inputs

## UX Copy

- [ ] No generic error messages ("Error occurred")
- [ ] Button copies describe specific actions
- [ ] No double negatives
- [ ] Loading states show estimated time or progress
- [ ] Success states are celebratory and confirm what happened
- [ ] Onboarding copy is encouraging, not clinical

## Scroll & Attention Flow

- [ ] Page prompts scrolling (partial next section visible)
- [ ] Whitespace used to create breathing room and guide eye
- [ ] Visual weight leads user from hero → value props → social proof → CTA
- [ ] Charts use appropriate type (bar for discrete, line for continuous)

---

## Quick Wins (High Impact, Low Effort)

1. Add "No credit card required" under your CTA button
2. Make recommended pricing plan `scale(1.05)` with glow shadow
3. Replace "Submit" with a specific action verb
4. Add icons to all navigation items
5. Cap paragraph width at `max-width: 65ch`
6. Change selected item state to background-color fill (not just border)
7. Make delete buttons ghost style with 70% opacity
8. Add skeleton loading states instead of spinners
9. Show the next section peeking at the bottom of the hero
10. Put trust signals (user count, "free forever") directly below the CTA

---

## Score Your UI (1 point each)

**0–15:** Major issues. Start with hierarchy + CTA copy.
**16–25:** Solid foundation. Focus on conversion details + copy.
**26–35:** Well-designed. Polish accessibility + mobile.
**36–40:** Excellent. Ship it.


path: references/design-systems-pro.md
content: # Design Systems Pro — Advanced UI/UX Reference
> Learned from ui-ux-pro-max (xobi667) on ClawHub + distilled into actionable guidance

---

## 1. Color Palette by Product Type (96 product categories)

### Most Common Archetypes

| Product Type | Primary | CTA | Background | Notes |
|---|---|---|---|---|
| SaaS (General) | #2563EB (blue) | #F97316 (orange) | #F8FAFC | Trust blue + orange CTA contrast |
| Gaming / Cyberpunk | #7C3AED (purple) | #F43F5E (rose) | #0F0F23 | Neon purple + rose action |
| AI / Chatbot | #7C3AED (purple) | #06B6D4 (cyan) | #FAF5FF | AI purple + cyan interactions |
| Fintech / Crypto | #F59E0B (gold) | #8B5CF6 (purple) | #0F172A | Gold trust + purple tech |
| E-commerce Luxury | #1C1917 | #CA8A04 (gold) | #FAFAF9 | Premium black + gold accent |
| Healthcare | #0891B2 (cyan) | #059669 (green) | #ECFEFF | Calm cyan + health green |
| Creative Agency | #EC4899 (pink) | #06B6D4 (cyan) | #FDF2F8 | Bold pink + cyan accent |
| Video Streaming | #0F0F23 (black) | #E11D48 (red) | #000000 | Cinema dark + play red |
| Restaurant / Food | #DC2626 (red) | #CA8A04 (gold) | #FEF2F2 | Appetiting red + warm gold |
| Fitness / Gym | #F97316 (orange) | #22C55E (green) | #1F2937 | Energy orange + success green |

**Rule:** Primary color sets trust, CTA color creates urgency/action. They must have ≥7:1 contrast.

### Dark Background Products
Products that MUST use dark backgrounds: Gaming, Cyberpunk, Fintech, Video Streaming, Music Streaming, Developer Tools, Space Tech, Coding.

Products that MUST use light backgrounds: Healthcare, Education (kids), Restaurant, Wellness, Wedding.

---

## 2. Typography Pairings (50+ curated combinations)

### By Aesthetic

| Style | Heading | Body | Google Fonts Import |
|---|---|---|---|
| Tech Startup | Space Grotesk | DM Sans | `Space+Grotesk:wght@400;500;600;700&DM+Sans:wght@400;500;700` |
| Gaming / Esports | Russo One | Chakra Petch | `Russo+One&Chakra+Petch:wght@300;400;500;600;700` |
| Cyberpunk / HUD | Share Tech Mono | Fira Code | Monospace only — both mono |
| Pixel / Retro | Press Start 2P | VT323 | `Press+Start+2P&VT323` |
| Luxury / Fashion | Cormorant | Montserrat | `Cormorant:wght@400;500;600;700&Montserrat:wght@300;400;500` |
| Minimal Swiss | Inter | Inter | Single font — weight variations only |
| AI / Modern SaaS | Plus Jakarta Sans | Plus Jakarta Sans | Single font — versatile |
| Wellness / Calm | Lora | Raleway | Serif heading + elegant sans body |
| Developer Tool | JetBrains Mono | IBM Plex Sans | Mono heading + clean sans body |
| Editorial / News | Newsreader | Roboto | Serif editorial + readable body |
| Gen Z / Bold | Anton | Epilogue | Impact display + clean body |
| Crypto / Web3 | Orbitron | Exo 2 | Futuristic both |
| Kids / Education | Baloo 2 | Comic Neue | Fun, rounded |

**Chinese (Simplified):** `Noto Sans SC`
**Japanese:** `Noto Serif JP` (heading) + `Noto Sans JP` (body)

---

## 3. UI Style Systems (60+ documented styles)

### Most Relevant for Dark/Tech UI

#### Cyberpunk UI
- Background: `#0D0D0D`
- Colors: `#00FF00`, `#FF00FF`, `#00FFFF`
- Effects: Neon glow (`text-shadow: 0 0 10px`), glitch animation, CRT scanlines
- Font: monospace only
- CSS: `animation: glitch 0.3s`, `::before` scanlines with `repeating-linear-gradient`

#### Retro-Futurism (Synthwave)
- Background: `#1A1A2E`
- Colors: Neon Blue, Hot Pink #FF006E, Cyan #00FFFF
- Effects: CRT scanlines, neon glow, glitch on hover
- Era: 1980s inspired

#### Glassmorphism
- Background: `rgba(255,255,255,0.15)` over vibrant bg
- CSS: `backdrop-filter: blur(15px); border: 1px solid rgba(255,255,255,0.2);`
- Text must maintain 4.5:1 contrast over glass

#### Neubrutalism (2024 Trend)
- Borders: `3-4px solid #000`
- Shadows: `5px 5px 0 #000` (hard offset, no blur)
- Colors: High saturation primary colors
- No gradients, no border-radius (or minimal)
- Hover: `transform: translate(-4px, -4px)` + `box-shadow: 9px 9px 0 #000`

#### Bento Grid (Apple-style)
- Layout: `display: grid; grid-template-columns: repeat(4, 1fr); grid-auto-rows: 200px; gap: 16px;`
- Cards: `border-radius: 24px; background: #FFFFFF; box-shadow: 0 4px 6px rgba(0,0,0,0.05);`
- Hover: `transform: scale(1.02)`
- Background: `#F5F5F7`

#### Aurora / Gradient Mesh
- CSS: `background: conic-gradient(...)` or `radial-gradient` with multiple stops
- Animation: `background-position` shift `8-12s infinite`
- Text must have sufficient contrast — often needs dark overlay

---

## 4. UX Anti-Patterns — 99 Issues to Avoid

The following are HIGH SEVERITY issues (from 99-item database):

### Navigation
- No smooth scroll on anchor links → add `html { scroll-behavior: smooth; }`
- Fixed nav covering content → add `padding-top` equal to nav height
- No active state indicator → highlight current page/section
- No back button on mobile → preserve browser history

### Animation
- Animate more than 1-2 elements per view → animation overload, distraction
- Animations > 500ms → feels sluggish (use 150-300ms)
- No `prefers-reduced-motion` check → accessibility failure (HIGH SEVERITY)
- Continuous decorative animations → distracting
- Using `top/left/width/height` in animations → triggers expensive repaints, use `transform` instead

### Layout
- Z-index above 50 (arbitrary) → use scale: 10, 20, 30, 50
- `100vh` on mobile → use `min-h-dvh` instead (browser chrome issue)
- No space reserved for async content → layout shift (CLS)
- Multiple overlapping `position: fixed` elements → chaos

### Touch / Mobile
- Touch targets < 44×44px → HIGH SEVERITY
- Hover-only interactions → doesn't work on touch
- `tap delay` → add `touch-action: manipulation`
- Horizontal swipe conflicts with system gestures → avoid on main content

### Accessibility (ALL HIGH SEVERITY)
- Missing focus ring → `focus:ring-2 focus:ring-blue-500`
- Color as only indicator → add icons/text
- Missing alt text
- No form labels (placeholder only)
- No skip link for keyboard nav

### Forms
- Placeholder as label → use floating label or separate label
- No inline validation → validate on blur
- Wrong input type (text for email/phone) → use `type="email"`, `type="tel"`
- No password show/hide toggle
- No submission feedback

### Responsive
- Mobile body text < 16px → HIGH SEVERITY
- Missing viewport meta tag → HIGH SEVERITY
- No horizontal scroll prevention → `max-w-full overflow-x-hidden`
- Same small button sizes on mobile → increase touch targets

---

## 5. Pre-Delivery Checklist (40 items)

### Visual Quality
- [ ] No emojis as UI icons — use SVG (Heroicons/Lucide)
- [ ] All icons from consistent set (24×24 viewBox)
- [ ] Hover states don't shift layout (use `opacity`/`color`, not `margin`/`padding`)
- [ ] Use theme colors directly, not `var()` wrapper on Tailwind
- [ ] Brand logos verified from Simple Icons

### Interaction
- [ ] All clickable elements have `cursor-pointer`
- [ ] Hover: visual feedback (`150-300ms`)
- [ ] Active/press state present (`transform: scale(0.95)` or `translate`)
- [ ] Focus states visible (`focus:ring-2`)
- [ ] Loading buttons: disabled + spinner

### Light/Dark Mode
- [ ] Light mode text ≥ 4.5:1 contrast (body text)
- [ ] Glass/transparent elements visible in light mode (`bg-white/80`, not `/10`)
- [ ] Borders visible in both modes
- [ ] No `text-gray-400` for body text in light mode (use `#475569` minimum)

### Layout
- [ ] Floating elements have edge spacing (`top-4 left-4 right-4`)
- [ ] Content not hidden behind fixed navbar (add `padding-top`)
- [ ] Responsive at 375px / 768px / 1024px / 1440px
- [ ] No horizontal scroll on mobile

### Accessibility
- [ ] All images have alt text
- [ ] Form inputs have labels (not just placeholder)
- [ ] Color is not the only indicator
- [ ] `prefers-reduced-motion` respected
- [ ] Touch targets ≥ 44×44px

---

## 6. Landing Page Patterns (30 documented)

### By Conversion Goal

| Goal | Pattern | Key Elements |
|---|---|---|
| SaaS free trial | Hero + Features + CTA | Video demo center, sticky CTA, trust badges |
| E-commerce | Product Demo | Before/after slider, reviews, urgency |
| Lead generation | Lead Magnet + Form | ≤3 form fields, preview of lead magnet, instant value |
| Pricing page | Pricing + CTA | 3 tiers, popular badge, annual discount 20-30%, FAQ |
| Brand awareness | Storytelling-Driven | Scroll narrative, 5-7 chapters, emotional hooks |
| Event/Webinar | Event Landing | Countdown timer, speaker bio, limited seats |
| Launch/Waitlist | Waitlist Pattern | Countdown, email capture, social proof count |
| Community | Community/Forum | Member count, activity feed preview, low friction join |

### CTA Placement Rules
- Primary CTA: above fold always
- Secondary CTA: after testimonials/social proof
- Sticky CTA: in navbar on scroll past hero
- Never more than 2 CTA variants visible at once

---

## 7. Design System Tokens Template

```css
:root {
  /* Spacing (8px base unit) */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;
  --space-8: 32px;
  --space-12: 48px;
  --space-16: 64px;

  /* Typography Scale (1.25 ratio) */
  --text-xs: 12px;
  --text-sm: 14px;
  --text-base: 16px;    /* minimum for body */
  --text-lg: 18px;
  --text-xl: 20px;
  --text-2xl: 24px;
  --text-3xl: 30px;
  --text-4xl: 36px;
  --text-5xl: 48px;
  --text-6xl: 60px;

  /* Border Radius */
  --radius-sm: 6px;
  --radius: 12px;
  --radius-lg: 16px;
  --radius-xl: 24px;    /* Bento/large cards */
  --radius-full: 9999px;

  /* Shadows / Elevation */
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.1);
  --shadow: 0 4px 6px rgba(0,0,0,0.1);
  --shadow-md: 0 10px 20px rgba(0,0,0,0.1);
  --shadow-lg: 0 20px 40px rgba(0,0,0,0.15);
  --shadow-glow: 0 0 30px rgba(var(--accent-rgb), 0.4);

  /* Z-Index Scale */
  --z-1: 10;
  --z-2: 20;
  --z-3: 30;
  --z-modal: 50;
  --z-toast: 100;

  /* Animation */
  --duration-fast: 150ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;
  --ease-out: cubic-bezier(0.22, 1, 0.36, 1);
  --ease-in: cubic-bezier(0.64, 0, 0.78, 0);
  --spring: cubic-bezier(0.34, 1.56, 0.64, 1);  /* bouncy */
}
```

---

## 8. Design Decision Framework

When choosing a UI style, ask 3 questions:

1. **Who is the user?** Age, tech savvy, context (mobile/desktop/TV)
2. **What is the industry?** Healthcare = accessible + calm. Gaming = immersive + dark. Finance = trust + professional.
3. **What is the goal?** Conversion = minimal distractions. Showcase = rich visual. Dashboard = information density.

### Quick Decision Table

| Industry | NEVER use | ALWAYS include |
|---|---|---|
| Healthcare / Medical | Neon colors, heavy animation | WCAG AAA, calm palette, 18px+ body text |
| Finance / Banking | Playful design, bright colors | Security badges, dark navy, trust signals |
| Gaming | Flat/minimal design | Dark mode, neon, 3D or glitch effects |
| Kids / Education | Dark mode, complex UX | Rounded shapes, bright pastels, large touch targets |
| SaaS B2B | Emoji icons, cluttered layout | Feature comparison, trust logos, demo CTA |
| E-commerce Luxury | Bright/vibrant palette | Premium black/gold, white space, elegance |

---

## Source
Learned from: `ui-ux-pro-max` by @xobi667 on ClawHub (MIT-0 license)
Data files: colors.csv (96 rows), typography.csv (57 rows), styles.csv (68 rows), ux-guidelines.csv (99 rows), landing.csv (30 rows), ui-reasoning.csv


path: references/micro-interactions.md
content: # Micro-Interactions & CSS Component Patterns
> Learned from uiverse.io/elements (3000+ community CSS components, MIT License)

## What is uiverse.io?
The largest open-source UI component library — 3000+ CSS/Tailwind components (Buttons, Cards, Inputs, Loaders, Toggles, Checkboxes, etc.) all MIT-licensed and copy-pasteable. Source: https://github.com/uiverse-io/galaxy

---

## Button Design Patterns

### 1. Icon + Label Pattern (Navigation Buttons)
Most effective nav buttons show colored icon + text label side by side.
```css
/* Pattern: icon in brand color, text inherits on hover */
.nav-btn { display: flex; align-items: center; gap: 8px; }
.nav-btn:hover { color: var(--accent-color); }
/* Icon stays its color, text changes to match */
```
Key insight: Each nav item gets its own accent color (dashboard=cyan, articles=blue, notes=yellow, reviews=orange). Color differentiation + icon = zero ambiguity.

### 2. Reveal-on-Hover (Progressive Disclosure Button)
Show label text only on hover — great for icon-only toolbars:
```css
.label { 
  transform: scaleX(0); 
  transform-origin: left;
  transition: transform 0.2s;
}
.btn:hover .label { transform: scaleX(1); }
```
Use for: compact toolbars where space is limited but discoverability matters.

### 3. Brutalist Button (High-Attention CTA)
Technique: hard offset shadow + glare sweep animation:
```css
.brutalist-btn {
  border: 3px solid #fff;
  outline: 3px solid #000;
  box-shadow: 6px 6px 0 var(--accent);
}
.brutalist-btn:hover {
  transform: translate(-4px, -4px);
  box-shadow: 10px 10px 0 #000;
}
.brutalist-btn:active {
  transform: translate(4px, 4px);
  box-shadow: none;
}
/* Glare sweep on hover */
.brutalist-btn::before {
  content: '';
  position: absolute;
  left: -100%;
  background: linear-gradient(90deg, transparent, rgba(255,255,255,0.8), transparent);
  animation: slide 2s infinite on-hover;
}
```
Use for: primary CTAs that need maximum attention. Neobrutalism trend.

### 4. Active/Press State (Required for all clickable elements)
Every button MUST have 3 states:
- **Default** — resting state
- **Hover** — `transform: translateY(-2px)` + glow
- **Active/Press** — `transform: translate(4px, 4px)` reverses the hover lift

Missing active state = feels broken and cheap.

---

## Card Design Patterns

### 5. Glitch Effect Card (Dark/Cyberpunk aesthetic)
For dark-mode, high-impact cards:
```css
/* CRT scan line overlay */
.card::before {
  content: '';
  background: repeating-linear-gradient(
    0deg,
    rgba(255,255,255,0.05),
    rgba(255,255,255,0.05) 1px,
    transparent 1px, transparent 2px
  );
  animation: tv-static 0.2s infinite alternate;
}
/* RGB channel split */
.card::after {
  background: linear-gradient(rgba(0,0,0,0) 50%, rgba(0,0,0,0.25) 50%),
    linear-gradient(90deg, rgba(255,0,0,0.06), rgba(0,255,0,0.02), rgba(0,0,255,0.06));
}
/* Glitch text */
.title::before { left: 2px; text-shadow: -1px 0 red; }
.title::after  { left: -2px; text-shadow: -1px 0 blue; }
```
Use for: gaming, cyberpunk, creative tech products. NOT for: B2B SaaS, medical, finance.

### 6. Card Hover Lift (Universal Pattern)
```css
.card {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}
.card:hover {
  transform: translateY(-8px);
  box-shadow: 0 20px 40px rgba(0,0,0,0.3);
}
```
The translateY + shadow increase = sense of elevation, signals interactivity.

### 7. Spotlight/Scan Line Animation
Moving scan line across a card = attention directing:
```css
.scan-line {
  position: absolute;
  height: 6px;
  background: rgba(255,255,255,0.15);
  animation: scan 2.5s linear infinite;
}
@keyframes scan { 0% { top: 0; } 100% { top: 100%; } }
```

---

## Input Design Patterns

### 8. Floating Label Input (Best UX Pattern)
Label starts inside the field as placeholder, floats up when focused:
```css
.input-wrap { position: relative; }
.label {
  position: absolute;
  top: 16px; left: 12px;
  transition: all 0.2s;
  pointer-events: none;
  color: #888;
}
.input:focus ~ .label,
.input:not(:placeholder-shown) ~ .label {
  top: 4px;
  font-size: 11px;
  color: var(--accent);
}
```
Why: Shows context even after user has typed. Better than disappearing placeholder.

### 9. Focus Ring (Neon Glow for Dark UI)
```css
.input:focus {
  outline: none;
  border-color: var(--accent);
  box-shadow: 0 0 0 3px rgba(var(--accent-rgb), 0.2),
              0 0 12px rgba(var(--accent-rgb), 0.1);
}
```
Replace standard browser outline with theme-consistent glow.

---

## Loading State Patterns

### 10. Skeleton Screen (Best Practice)
```css
.skeleton {
  background: linear-gradient(
    90deg,
    rgba(255,255,255,0.05) 25%,
    rgba(255,255,255,0.1) 50%,
    rgba(255,255,255,0.05) 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}
@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}
```
Always prefer skeleton screens over spinners for content-heavy areas.

### 11. Loading Button State
```css
.btn.loading {
  pointer-events: none;
  opacity: 0.8;
}
.btn.loading::after {
  content: '';
  width: 16px; height: 16px;
  border: 2px solid transparent;
  border-top-color: currentColor;
  border-radius: 50%;
  animation: spin 0.8s linear infinite;
  display: inline-block;
  margin-left: 8px;
}
```

---

## Toggle / Checkbox Patterns

### 12. Custom Toggle (Avoid Native Checkboxes for Primary Settings)
```css
.toggle {
  width: 44px; height: 24px;
  background: #333;
  border-radius: 12px;
  transition: background 0.2s;
}
.toggle.on { background: var(--accent); }
.toggle-thumb {
  width: 20px; height: 20px;
  border-radius: 50%;
  background: white;
  transition: transform 0.2s;
  box-shadow: 0 2px 4px rgba(0,0,0,0.3);
}
.toggle.on .toggle-thumb { transform: translateX(20px); }
```
Minimum size: 44×24px (touch target compliance).

---

## Animation Principles from uiverse.io

### 13. The 5 Micro-interaction Rules
1. **Keep it under 300ms** — interactions above 300ms feel sluggish
2. **Use ease-out for entrances** — `cubic-bezier(0.22, 1, 0.36, 1)` feels snappy
3. **Use ease-in for exits** — things leaving the screen accelerate away
4. **Avoid linear** — only for loading spinners; everywhere else feels robotic
5. **Respect `prefers-reduced-motion`** — always add:
```css
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; }
}
```

### 14. CSS Custom Properties for Theming
Design all components with CSS variables:
```css
:root {
  --accent: #b14fff;
  --accent-rgb: 177, 79, 255;
  --surface: rgba(255,255,255,0.04);
  --border: rgba(255,255,255,0.08);
  --radius: 12px;
  --radius-sm: 6px;
}
/* Outer = 2× inner */
.card { border-radius: calc(var(--radius) * 2); }
.card-inner { border-radius: var(--radius); }
```

### 15. Glow Effect (Neon/Cyberpunk)
```css
/* Text glow */
.neon-text { text-shadow: 0 0 10px var(--accent), 0 0 30px var(--accent); }

/* Border glow */
.neon-border { box-shadow: 0 0 0 1px var(--accent), 0 0 20px rgba(var(--accent-rgb), 0.3); }

/* Hover intensify */
.neon-btn:hover { box-shadow: 0 0 30px rgba(var(--accent-rgb), 0.6); }
```

---

## Component Categories on uiverse.io

| Category | Count | Best Use |
|----------|-------|----------|
| Buttons | 500+ | CTAs, nav, actions |
| Cards | 400+ | Content display, pricing |
| Inputs | 300+ | Forms, search |
| Checkboxes | 200+ | Settings, filters |
| Toggles | 150+ | On/off settings |
| Loaders | 200+ | Loading states |
| Notifications | 100+ | Alerts, toasts |
| Patterns | 100+ | Backgrounds, textures |
| Radio buttons | 100+ | Single-choice forms |

All MIT licensed → copy-paste freely, attribution appreciated.
Source: https://github.com/uiverse-io/galaxy

---

## Patterns to Avoid (Anti-patterns seen in poor implementations)

- ❌ **No hover state** — every interactive element needs hover feedback
- ❌ **No active/press state** — hover without press feels broken  
- ❌ **Infinite animation on static cards** — distracting; use hover-triggered animations
- ❌ **Animation without `prefers-reduced-motion`** — accessibility failure
- ❌ **Native checkbox/radio for important settings** — always custom style or use a library
- ❌ **Spinner for page-level loading** — use skeleton screens
- ❌ **CSS only for complex interactions** — some things need JavaScript for proper UX


path: references/ux-laws.md
content: # UX Laws & Principles Reference

## Jakob's Law
> Users spend most of their time on other sites. They expect your site to work like sites they already know.

**Apply:**
- Follow established UI conventions (hamburger menu, logo top-left, search top-right)
- Don't reinvent interaction patterns without a compelling reason
- Social login at top matches user expectations from other platforms
- Navigation patterns: consistent with platform norms (iOS vs Android vs Web)

---

# Original Laws

## Fitts's Law
> The time to acquire a target is a function of the distance to and size of the target.

**Practical applications:**
- Place keyboard shortcuts next to the action they trigger (reduces memory load + distance)
- Make primary CTAs large and centrally positioned
- Place frequently used actions in thumb zones on mobile
- Navigation items placed at corners and edges are easiest to hit

## The Gutenberg Principle (Z-Pattern Layout)
Users' eyes naturally travel in a Z-shape:
1. Top-left (start)
2. Top-right
3. Bottom-left
4. Bottom-right (terminal area = best CTA placement)

**Apply:** Place the primary CTA at the terminal area (bottom-right of the Z-path). Don't fight natural eye movement.

## Hick's Law
> The time it takes to make a decision increases with the number and complexity of choices.

**Apply:**
- Limit menu items
- Highlight the recommended pricing plan to reduce decision paralysis
- Use one primary CTA per screen — multiple competing CTAs slow conversion

## Jakob's Law
> Users spend most of their time on other sites. They expect your site to work like sites they already know.

**Apply:**
- Don't reinvent navigation patterns without strong reason
- Social login at top matches user expectations from other platforms
- Follow platform conventions (back buttons, form layouts, etc.)

## Von Restorff Effect (Isolation Effect)
> Items that stand out are more likely to be remembered and noticed.

**Apply:**
- Highlight the best pricing plan with color + shadow + size (multiple attributes)
- Use brand color sparingly so highlighted elements truly pop
- Make selected states clearly distinct

## Miller's Law
> The average person can hold 7 (±2) items in working memory.

**Apply:**
- Keep navigation menus under 7 items
- Break long forms into steps
- Group related elements to reduce cognitive load

## Tesler's Law (Conservation of Complexity)
> Every application has an inherent amount of complexity that cannot be removed — only shifted.

**Apply:**
- Better to absorb complexity in the system than push it to users
- Pre-made templates in empty states absorb the complexity of starting from scratch
- Smart defaults reduce decisions users must make

## Color Accessibility (8-3-0 Rule)
- ~8% of men have color vision deficiency
- ~0.5% of women have color vision deficiency
- **Never use color as the only differentiator** — always pair with icon, shape, or label

## Type Scale System
Standard scale multiplier: **×1.25**

| Element | Example Size |
|---------|-------------|
| H1 Title | 40px |
| H2 Subtitle | 32px |
| H3 | 25.6px |
| Body | 16px |
| Small/Label | 12.8px |

Consistent scale creates automatic hierarchy without manual tuning.

## Line Width for Readability
- Optimal: **50–75 characters per line** (approximately 500–700px)
- CSS shortcut: `max-width: 65ch` (ch = width of "0" character)
- Too wide → eyes lose track when returning to next line
- Too narrow → choppy reading rhythm

## Padding Rules for Rounded Elements
- When inner element is round and outer container is rounded:
  `Outer Border Radius = 2 × Inner Border Radius`
- When edge element is NOT round (text, icon):
  Use **double padding** on that edge vs. the rounded side

## Social Login Best Practices
- Place social login **above** email/password (higher conversion)
- Always provide email/password fallback (privacy-conscious users avoid social login)
- Display social options prominently with recognizable brand colors + logos

## Deletion Validation Checklist
- [ ] Confirmation dialog or inline confirmation required
- [ ] Button copy describes specific action ("Delete 'Project Alpha'", not "Delete")
- [ ] Dangerous action visually de-emphasized (ghost button, warning color)
- [ ] Consider undo functionality as alternative to confirmation
- [ ] Never style delete button as primary action

---

## Peak-End Rule
> People judge an experience by its most intense point (peak) and how it ends — not the average.

**Apply:**
- Make the success moment (after completing a task) celebratory — "🎉 Your video is ready!"
- Fix the worst friction points in your flow (peak pain = peak memory)
- End onboarding with a win, not a form
- The last interaction before churn matters most — make it positive

## Doherty Threshold
> Productivity soars when a computer and user interact at a pace < 400ms.

**Apply:**
- Show loading states immediately (skeleton screens, not spinners)
- Give instant visual feedback on button clicks (pressed state, loading state)
- Optimistic UI updates (assume success, rollback on failure)
- Progress bars reduce perceived wait time even if they don't speed anything up

## Parkinson's Law
> Work expands to fill the time available.

**Apply:**
- Set deadlines in copy: "Your free trial ends in 3 days"
- Time-limited offers (real ones, not fake countdown timers)
- Break tasks into smaller pieces with their own deadlines

## Aesthetic-Usability Effect
> Users perceive aesthetically pleasing designs as easier to use.

**Apply:**
- Good visual design buys tolerance for usability issues
- Polish matters — rough-looking UIs get less patience from users
- Consistent spacing, typography, and color = perceived quality

## Serial Position Effect
> Users best remember the first and last items in a list.

**Apply:**
- Put your most important navigation items first or last
- Feature your strongest testimonial first AND last
- Key pricing benefits at the top and bottom of feature lists

## Goal-Gradient Effect
> People accelerate effort as they get closer to a goal.

**Apply:**
- Show progress bars even for simple tasks ("Profile 60% complete")
- Pre-fill some progress: "You've already done step 1!" for new users
- Break long forms into labeled steps with visible completion status

## Law of Proximity
> Objects near each other are perceived as related.

**Apply:**
- Group form fields by category (personal info, billing info)
- Labels must be closer to their input than to other inputs
- Action buttons near the content they affect (not in a distant footer)

## Law of Similarity
> Similar items are perceived as belonging together.

**Apply:**
- Same visual style for same-level navigation items
- Tags should look different from primary buttons
- Distinguish interactive from non-interactive elements visually


path: references/ux-writing.md
content: # UX Writing Reference

## Core Principles

### 1. Be Specific, Not Generic
Every UI text should answer: "What exactly will happen?"

| Context | ❌ Bad | ✅ Good |
|---------|--------|--------|
| Delete confirm | "Are you sure?" | "Delete 'Marketing Campaign 2024'? This can't be undone." |
| Button | "Submit" | "Send My Application" |
| Error | "Error occurred" | "Payment declined. Check your card details or try a different card." |
| Success | "Done!" | "Your video is being processed. We'll email you in ~3 minutes." |
| Loading | "Loading..." | "Generating your script... (usually takes 30 seconds)" |
| Empty state | "No data" | "No campaigns yet. Create your first campaign to start tracking results." |

### 2. Reduce Anxiety at Decision Points
Users pause before irreversible actions. Microcopy near CTAs resolves the hesitation.

**Patterns:**
- Near "Subscribe" → "Cancel anytime. No questions asked."
- Near "Delete" → make it a ghost button + specific copy
- Near "Connect Account" → "We only read your data. We never post."
- Near payment → "Secured by Stripe. Your card info never touches our servers."
- Near "Start Trial" → "No credit card required"

### 3. Active Voice, User-Centered
Frame copy from the user's perspective:

| ❌ System-centric | ✅ User-centric |
|------------------|----------------|
| "Your account has been created" | "You're in! Let's set up your workspace." |
| "Payment was processed" | "You're all set. Your credits are ready to use." |
| "An error has occurred" | "Something went wrong. Here's what you can try:" |

### 4. Microcopy Placement
Put the most important clarifying text **immediately adjacent** to the element it describes:
- Inline under an input (not in a separate help section)
- Directly below a CTA button (not in the footer)
- Inside the tooltip (not in a separate FAQ page)

### 5. Button Copy Formula
`[Verb] + [Object] + [Benefit/Timeframe]`

Examples:
- "Start Free Trial" (verb + free modifier)
- "Download Report" (verb + object)
- "Book Demo — 15 min" (verb + object + timeframe)
- "Create My First Video" (possessive makes it personal)

### 6. Error Message Formula
`[What happened] + [Why] + [What to do next]`

Examples:
- "Couldn't upload your file. Files must be under 10MB. [Choose a smaller file]"
- "We couldn't find that email. Double-check the spelling or [create a new account]."
- "Your session expired after 30 minutes of inactivity. [Log in again to continue]"

### 7. Empty State Formula
`[Illustration/Icon] + [What's missing] + [Value of filling it] + [Primary CTA] + [Secondary help link]`

Example:
```
🎬 (icon)
No videos yet
Your AI-generated videos will appear here.
[Create Your First Video]  [See how it works →]
```

## Tone & Voice Guidelines

### Match Tone to Context
- **Success states:** Celebratory, warm — "🎉 Your video is ready!"
- **Error states:** Calm, helpful — never apologize excessively
- **Warnings:** Direct, clear — "This will permanently delete your data"
- **Onboarding:** Encouraging, confident — "You're 2 steps away from your first video"
- **Empty states:** Inviting, not clinical — "Start something amazing →"

### Avoid These Patterns
- **Jargon:** "Authenticate your OAuth token" → "Connect your account"
- **Double negatives:** "Don't not enable notifications" → "Enable notifications"
- **Vague time:** "Soon" / "Shortly" → "In about 3 minutes" / "Within 24 hours"
- **Over-apologizing:** "We're so sorry..." → "Something went wrong. Let's fix it:"
- **All caps for emphasis:** Use bold or color instead

## Notification & Alert Copy

### Hierarchy of Alerts
1. **Error (red):** Something failed. User must act. → "Payment failed. Update your card."
2. **Warning (orange):** Something might go wrong. → "Your storage is 90% full."
3. **Info (blue):** Useful but not urgent. → "New AI model available for video generation."
4. **Success (green):** Positive confirmation. → "Changes saved."

### Alert Copy Rules
- One sentence max for inline alerts
- Include a link/action when the user can fix it
- Auto-dismiss success messages after 3–5 seconds
- Don't auto-dismiss errors — user needs to acknowledge

## Placeholder Text Best Practices

### Do
- Show the **format**: "[REDACTED_SECRET]"
- Give an **example**: "e.g., A robot falls in love in 2087 Tokyo"
- Indicate **constraints**: "Max 280 characters"

### Don't
- Repeat the label: Label "Email" → Placeholder "Email" (redundant)
- Use placeholder as the only instruction (it disappears on type)
- Use placeholder for required format info — put that below the field permanently


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)