picasso-skill 1.0.0

package/references/color-and-contrast.md

@@ -0,0 +1,174 @@
+# Color and Contrast Reference
+
+## Table of Contents
+1. Color Space and Manipulation
+2. Palette Construction
+3. Tinted Neutrals
+4. Dark Mode
+5. Accessibility
+6. CSS Variables Pattern
+7. Common Mistakes
+
+---
+
+## 1. Color Space and Manipulation
+
+Use OKLCH for perceptually uniform color. Unlike HSL, OKLCH ensures that colors at the same lightness value actually appear equally bright to the human eye.
+
+```css
+/* OKLCH: lightness (0-1), chroma (0-0.4), hue (0-360) */
+--accent: oklch(0.65 0.25 25);        /* vibrant red-orange */
+--accent-hover: oklch(0.60 0.28 25);  /* darker, more saturated */
+--accent-muted: oklch(0.75 0.08 25);  /* same hue, much less chroma */
+```
+
+For programmatic palette generation, adjust lightness for tints/shades, chroma for saturation, and hue for variation. OKLCH makes this predictable.
+
+---
+
+## 2. Palette Construction
+
+### The 60-30-10 Rule
+- 60% dominant (surface/background)
+- 30% secondary (cards, sections, supporting elements)
+- 10% accent (CTAs, active states, highlights)
+
+### Building a Palette
+1. Start with the accent color (the brand or action color)
+2. Derive a surface color: very low chroma version of the accent hue
+3. Build neutral scale: tinted toward the accent hue (never pure gray)
+4. Add a semantic layer: success (green family), warning (amber), error (red), info (blue)
+5. Generate dark mode variants by inverting the lightness scale, not the colors
+
+### Token Structure
+```css
+:root {
+  /* Surfaces */
+  --surface-0: oklch(0.99 0.005 80);    /* page background */
+  --surface-1: oklch(0.97 0.008 80);    /* card background */
+  --surface-2: oklch(0.94 0.01 80);     /* elevated/hover surface */
+  --surface-3: oklch(0.90 0.012 80);    /* active/selected surface */
+
+  /* Text */
+  --text-primary: oklch(0.15 0.02 80);
+  --text-secondary: oklch(0.40 0.02 80);
+  --text-tertiary: oklch(0.55 0.015 80);
+
+  /* Accent */
+  --accent: oklch(0.55 0.25 30);
+  --accent-hover: oklch(0.50 0.28 30);
+  --accent-subtle: oklch(0.92 0.04 30);
+
+  /* Borders */
+  --border: oklch(0.88 0.01 80);
+  --border-strong: oklch(0.78 0.015 80);
+
+  /* Semantic */
+  --success: oklch(0.55 0.18 145);
+  --warning: oklch(0.65 0.18 70);
+  --error: oklch(0.55 0.22 25);
+}
+```
+
+---
+
+## 3. Tinted Neutrals
+
+Never use pure gray (#808080, rgb(128,128,128), etc.). Always tint neutrals toward the dominant hue of the palette. This creates warmth and cohesion.
+
+**Warm neutrals** (tinted toward amber/brown): suited for editorial, luxury, organic brands
+**Cool neutrals** (tinted toward blue/slate): suited for tech, data, professional tools
+**Neutral neutrals** (tinted toward the accent hue at very low chroma): the most versatile approach
+
+```css
+/* Instead of #333333 */
+--text-primary: oklch(0.25 0.015 260);  /* cool-tinted dark */
+
+/* Instead of #f5f5f5 */
+--surface-bg: oklch(0.97 0.005 260);    /* cool-tinted light */
+```
+
+---
+
+## 4. Dark Mode
+
+Dark mode is not "invert everything." Follow these rules:
+
+1. Surface colors get darker but retain their hue tint
+2. Text colors flip but never become pure white (use oklch lightness 0.93-0.97)
+3. Accent colors often need a lightness bump (+0.05 to +0.10) to maintain contrast
+4. Shadows become less visible on dark surfaces; use subtle inner glows or border effects instead
+5. Elevation in dark mode goes lighter (higher surfaces are lighter), opposite of light mode
+6. Images and illustrations may need reduced brightness/contrast (`filter: brightness(0.9)`)
+
+```css
+[data-theme="dark"] {
+  --surface-0: oklch(0.13 0.01 260);
+  --surface-1: oklch(0.17 0.012 260);
+  --surface-2: oklch(0.21 0.015 260);
+  --text-primary: oklch(0.93 0.01 260);
+  --text-secondary: oklch(0.70 0.01 260);
+  --border: oklch(0.25 0.01 260);
+}
+```
+
+---
+
+## 5. Accessibility
+
+### Contrast Requirements (WCAG 2.2)
+- Normal text (<24px or <18.66px bold): 4.5:1 minimum
+- Large text (>=24px or >=18.66px bold): 3:1 minimum
+- UI components and graphical objects: 3:1 minimum
+- Focus indicators: 3:1 against adjacent colors
+
+### Testing
+Use OKLCH lightness difference as a quick heuristic: a difference of 0.40+ between text and background lightness values usually passes AA. For precise checking, use the APCA (Advanced Perceptual Contrast Algorithm) when possible, as it better represents human perception than WCAG 2.x contrast ratios.
+
+### Color Blindness
+Never use color as the only way to convey information. Pair color with icons, patterns, or text labels. Test palettes with a deuteranopia/protanopia simulator.
+
+---
+
+## 6. CSS Variables Pattern
+
+Define all colors as CSS custom properties. Group by function, not by color name.
+
+```css
+/* Good: semantic naming */
+--color-surface: ...;
+--color-text: ...;
+--color-accent: ...;
+--color-border: ...;
+
+/* Bad: literal naming */
+--blue: ...;
+--dark-gray: ...;
+--light-blue: ...;
+```
+
+For component-level overrides:
+```css
+.card {
+  --card-bg: var(--surface-1);
+  --card-border: var(--border);
+  background: var(--card-bg);
+  border: 1px solid var(--card-border);
+}
+.card.highlighted {
+  --card-bg: var(--accent-subtle);
+  --card-border: var(--accent);
+}
+```
+
+---
+
+## 7. Common Mistakes
+
+- Using pure black (#000) for text (use tinted near-black instead)
+- Using gray text on colored backgrounds (low contrast, hard to read)
+- Applying opacity to achieve lighter colors (makes elements look washed out; use chroma reduction instead)
+- Using too many accent colors (one primary accent, one secondary maximum)
+- Forgetting to test dark mode after building light mode
+- Using brand colors at full saturation for large surfaces (they vibrate and cause eye strain; reserve full chroma for small accents)
+- Not providing hover/focus states with visible color change

package/references/component-patterns.md

@@ -0,0 +1,113 @@
+# Component Patterns Reference
+
+Standard component taxonomy, naming conventions, and state patterns drawn from 90+ real-world design systems and 2,500+ implementations (sourced from component.gallery).
+
+## Standard Component Names
+
+Use these names consistently. When building a component, check this list first. Do not invent new names for solved patterns.
+
+### Navigation
+- **Navbar / Navigation Bar**: Top-level site navigation. Contains logo, links, actions.
+- **Sidebar / Side Navigation**: Vertical navigation panel, typically on the left.
+- **Breadcrumb**: Shows the user's location in a hierarchy. e.g., Home > Products > Shoes.
+- **Tabs**: Horizontal set of toggles for switching between views within a section.
+- **Pagination**: Controls for navigating between pages of content.
+- **Bottom Navigation / Tab Bar**: Mobile-only bottom navigation with 3-5 icon+label items.
+- **Menu / Dropdown Menu**: A list of options revealed on click, typically from a button.
+- **Command Palette / Command Menu**: Keyboard-driven search-and-action overlay (Cmd+K pattern).
+
+### Content
+- **Card**: A bounded container for a unit of content (image, title, description, action).
+- **Accordion / Disclosure**: Expandable/collapsible sections in a vertical stack.
+- **Carousel / Slider**: Multiple slides navigated via swipe, scroll, or buttons.
+- **Table / Data Table**: Structured rows and columns for tabular data.
+- **List / List Item**: Ordered or unordered vertical sequence of items.
+- **Tree View**: Nested hierarchical content (file explorer, category browser).
+- **Timeline**: Chronological sequence of events.
+- **Empty State**: Placeholder shown when a section has no content yet.
+
+### Input
+- **Text Input / Text Field**: Single-line text entry.
+- **Textarea**: Multi-line text entry.
+- **Select / Dropdown**: Choose one option from a list.
+- **Combobox / Autocomplete**: Text input with filtered dropdown suggestions.
+- **Checkbox**: Binary on/off selection (multiple selections allowed).
+- **Radio / Radio Group**: Select exactly one option from a set.
+- **Toggle / Switch**: Binary on/off with immediate effect (no form submission needed).
+- **Slider / Range**: Select a value within a numeric range by dragging.
+- **Date Picker**: Calendar-based date selection.
+- **File Upload**: Interface for selecting and uploading files.
+- **Search Input**: Text input with search semantics (clear button, submit on enter).
+
+### Feedback
+- **Alert / Banner**: Non-interactive message at the top of a page or section.
+- **Toast / Snackbar**: Temporary notification that auto-dismisses. Bottom of screen.
+- **Modal / Dialog**: Overlay requiring user attention before returning to the page.
+- **Popover**: Small overlay anchored to a trigger element, often for contextual info.
+- **Tooltip**: Brief label shown on hover/focus, never interactive.
+- **Progress Bar**: Linear indicator of completion (determinate or indeterminate).
+- **Spinner / Loading Indicator**: Circular animation indicating a pending operation.
+- **Skeleton / Placeholder**: Gray shapes matching expected content layout during load.
+- **Badge / Tag / Chip**: Small label for status, category, or count.
+
+### Actions
+- **Button**: Primary interactive element for triggering actions.
+- **Icon Button**: Button with only an icon (must have aria-label).
+- **Button Group**: Set of related buttons displayed together.
+- **Floating Action Button (FAB)**: Prominent circular button for the primary action (mobile).
+- **Link / Anchor**: Navigation to another page or resource.
+
+### Layout
+- **Container**: Max-width wrapper centering content on the page.
+- **Divider / Separator**: Visual line separating content sections.
+- **Grid**: Multi-column layout system.
+- **Stack**: Vertical or horizontal arrangement with consistent spacing.
+- **Aspect Ratio**: Container maintaining a fixed width:height ratio.
+
+## Component State Matrix
+
+Every interactive component needs these states defined:
+
+| State | Visual Treatment |
+|---|---|
+| Default | Base appearance |
+| Hover | Subtle change: background lightens/darkens, cursor changes |
+| Focus | High-contrast outline (2px accent, 2px offset) |
+| Active / Pressed | Slight scale-down (0.97-0.98), darkened background |
+| Disabled | 50% opacity, cursor: not-allowed, no hover/focus effects |
+| Loading | Spinner or skeleton replacing content, pointer-events: none |
+| Error | Error-colored border, inline error message |
+| Selected / Active | Accent background or border, checkmark indicator |
+| Dragging | Elevated shadow, slight rotation, reduced opacity on source |
+
+## Compound Component Pattern
+
+For components with multiple sub-parts, use the dot notation compound pattern:
+
+```tsx
+<Dialog>
+  <Dialog.Trigger>Open</Dialog.Trigger>
+  <Dialog.Content>
+    <Dialog.Title>Confirm</Dialog.Title>
+    <Dialog.Description>Are you sure?</Dialog.Description>
+    <Dialog.Footer>
+      <Dialog.Close>Cancel</Dialog.Close>
+      <Button>Confirm</Button>
+    </Dialog.Footer>
+  </Dialog.Content>
+</Dialog>
+```
+
+This pattern appears in: Radix UI, shadcn/ui, Headless UI, Reach UI, Ark UI.
+
+## Component Sizing Convention
+
+Use a consistent sizing scale across all components:
+
+| Size | Height | Font Size | Padding | Use Case |
+|---|---|---|---|---|
+| xs | 28px | 12px | 4px 8px | Dense UIs, inline tags |
+| sm | 32px | 13px | 6px 12px | Secondary actions, compact forms |
+| md | 40px | 14px | 8px 16px | Default for most components |
+| lg | 48px | 16px | 12px 24px | Primary actions, hero sections |
+| xl | 56px | 18px | 16px 32px | Landing page CTAs |

package/references/design-system.md

@@ -0,0 +1,176 @@
+# Design System Reference
+
+## Table of Contents
+1. DESIGN.md Format
+2. Theme Generation
+3. Token Structure
+4. Pre-Built Themes
+
+---
+
+## 1. DESIGN.md Format
+
+When generating a design system document, follow this structure (derived from the Google Stitch DESIGN.md format, extended by VoltAgent):
+
+```markdown
+# DESIGN.md
+
+## 1. Visual Theme & Atmosphere
+Describe the mood, density, and design philosophy. Is this minimal or dense?
+Warm or cold? Playful or serious? What existing products or aesthetics does it
+reference?
+
+## 2. Color Palette & Roles
+| Token | Hex | Role |
+|---|---|---|
+| surface-primary | #fafaf9 | Page background |
+| surface-secondary | #f5f5f4 | Card/section background |
+| text-primary | #1c1917 | Headings and body text |
+| text-secondary | #57534e | Supporting text, labels |
+| accent | #dc2626 | CTAs, active states, links |
+| accent-hover | #b91c1c | Hover state for accent |
+| accent-subtle | #fef2f2 | Accent-tinted background |
+| border | #e7e5e4 | Default borders |
+| success | #16a34a | Success states |
+| warning | #d97706 | Warning states |
+| error | #dc2626 | Error states |
+
+## 3. Typography Rules
+| Level | Font | Size | Weight | Line Height | Letter Spacing |
+|---|---|---|---|---|---|
+| Display | [Display Font] | 3rem | 700 | 1.1 | -0.02em |
+| H1 | [Display Font] | 2.25rem | 700 | 1.15 | -0.01em |
+| H2 | [Display Font] | 1.875rem | 600 | 1.2 | -0.01em |
+| H3 | [Body Font] | 1.5rem | 600 | 1.25 | 0 |
+| Body | [Body Font] | 1rem | 400 | 1.6 | 0 |
+| Small | [Body Font] | 0.875rem | 400 | 1.5 | 0 |
+| Caption | [Body Font] | 0.75rem | 500 | 1.4 | 0.02em |
+| Code | [Mono Font] | 0.875rem | 400 | 1.6 | 0 |
+
+## 4. Component Styling
+### Buttons
+| Variant | Background | Text | Border | Radius | Padding |
+|---|---|---|---|---|---|
+| Primary | accent | white | none | 8px | 12px 24px |
+| Secondary | transparent | text-primary | 1px border | 8px | 12px 24px |
+| Ghost | transparent | text-secondary | none | 8px | 12px 24px |
+| Destructive | error | white | none | 8px | 12px 24px |
+
+States: hover (darken bg 5%), active (darken 10%, scale 0.98), disabled (opacity 0.5), focus (2px accent outline, 2px offset).
+
+### Cards
+Background: surface-secondary. Border: 1px border. Radius: 12px.
+Padding: 24px. Shadow: 0 1px 3px rgba(0,0,0,0.05).
+Hover: shadow increases to 0 4px 12px rgba(0,0,0,0.08).
+
+### Inputs
+Height: 44px. Border: 1px border. Radius: 8px. Padding: 0 12px.
+Focus: 2px accent border, subtle accent glow.
+Error: error border, error message below.
+Disabled: opacity 0.5, cursor not-allowed.
+
+### Navigation
+Describe the navigation pattern (sidebar, top bar, tabs) with specific dimensions,
+colors, and active/hover states.
+
+## 5. Layout Principles
+Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96.
+Max content width: [value]px.
+Grid: [columns] columns with [gap]px gaps.
+Page margins: [value]px on desktop, [value]px on mobile.
+
+## 6. Depth & Elevation
+| Level | Shadow | Use |
+|---|---|---|
+| 0 | none | Flat elements, inline content |
+| 1 | 0 1px 2px rgba(0,0,0,0.05) | Cards, dropdowns |
+| 2 | 0 4px 12px rgba(0,0,0,0.08) | Floating elements, hover cards |
+| 3 | 0 8px 24px rgba(0,0,0,0.12) | Modals, dialogs |
+| 4 | 0 16px 48px rgba(0,0,0,0.16) | Popovers, overlays |
+
+## 7. Do's and Don'ts
+### Do
+- [specific guidance for this design system]
+
+### Don't
+- [specific anti-patterns to avoid]
+
+## 8. Responsive Behavior
+Breakpoints: [values].
+Mobile navigation: [pattern].
+Column collapse strategy: [how grids simplify].
+Touch target minimum: 48px.
+
+## 9. Agent Prompt Guide
+Quick reference for AI agents building with this system:
+- Primary color: [hex]
+- Background: [hex]
+- Font family: [name]
+- Border radius: [value]
+- Spacing unit: [value]
+```
+
+---
+
+## 2. Theme Generation
+
+When creating a custom theme, follow this process:
+
+1. **Start with the accent color.** This is usually the brand color or the primary action color.
+2. **Derive surfaces.** Take the accent hue, reduce chroma to near-zero, and create a lightness scale.
+3. **Build the text scale.** Tint near-black toward the accent hue for warmth.
+4. **Choose fonts.** Match the emotional register (serif for editorial/luxury, sans for tech/modern, mono for developer/terminal).
+5. **Set border radius.** 0px for brutalist, 4-8px for professional, 12-16px for friendly, 999px for pill-shaped.
+6. **Define shadows.** Match the overall aesthetic (no shadows for flat designs, layered shadows for elevated designs).
+
+---
+
+## 3. Token Structure
+
+Organize tokens by function, not by value:
+
+```
+--color-surface-{0-3}     Backgrounds, from page to elevated
+--color-text-{primary,secondary,tertiary}  Text hierarchy
+--color-accent             Primary action color
+--color-accent-{hover,subtle}  Accent variants
+--color-border             Default borders
+--color-{success,warning,error,info}  Semantic states
+--space-{1-24}             Spacing scale
+--radius-{sm,md,lg,full}   Border radius
+--shadow-{sm,md,lg,xl}     Elevation
+--font-{display,body,mono} Font families
+--text-{xs,sm,base,lg,xl,2xl,3xl,4xl}  Type scale
+```
+
+---
+
+## 4. Pre-Built Themes
+
+### Midnight Terminal
+Dark background, green accent, monospace-forward. Suited for developer tools.
+- Surface: oklch(0.12 0.01 150) to oklch(0.20 0.015 150)
+- Accent: oklch(0.70 0.20 150) (terminal green)
+- Font: JetBrains Mono + IBM Plex Sans
+- Radius: 4px
+
+### Warm Editorial
+Cream background, serif headings, generous whitespace. Suited for content-heavy sites.
+- Surface: oklch(0.97 0.01 60) to oklch(0.93 0.015 60)
+- Accent: oklch(0.45 0.15 25) (warm red)
+- Font: Instrument Serif + Source Sans 3
+- Radius: 2px
+
+### Swiss Precision
+White background, strict grid, no decoration. Suited for professional tools.
+- Surface: oklch(0.99 0.002 0) to oklch(0.95 0.005 0)
+- Accent: oklch(0.50 0.25 250) (blue)
+- Font: Helvetica Neue / Outfit + DM Sans
+- Radius: 0px
+
+### Soft Pastel
+Light pastel background, rounded elements, friendly. Suited for consumer apps.
+- Surface: oklch(0.97 0.02 280) to oklch(0.93 0.03 280)
+- Accent: oklch(0.60 0.20 280) (soft purple)
+- Font: Nunito + Nunito Sans
+- Radius: 16px

package/references/generative-art.md

@@ -0,0 +1,54 @@
+# Generative Art Reference
+
+## Process
+
+### Step 1: Algorithmic Philosophy
+Before writing code, write a manifesto (4-6 paragraphs) that describes the computational aesthetic. Name the movement (1-2 words). Describe how the philosophy manifests through computational processes, noise functions, particle behaviors, temporal evolution, and parametric variation.
+
+### Step 2: Implementation
+Express the philosophy through p5.js with seeded randomness. The algorithm should be 90% generative, 10% parameters.
+
+### Core Technical Requirements
+
+**Seeded Randomness:**
+```javascript
+let seed = 12345;
+randomSeed(seed);
+noiseSeed(seed);
+```
+Same seed always produces the same output. Different seeds reveal different facets.
+
+**Parameter Structure:**
+```javascript
+let params = {
+  seed: 12345,
+  particleCount: 1000,
+  noiseScale: 0.005,
+  speed: 1.5,
+  // Add parameters specific to the algorithm
+};
+```
+
+**Single-File HTML:**
+Everything inline, no external files except p5.js CDN:
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.7.0/p5.min.js"></script>
+```
+
+### Required UI Features
+1. **Seed navigation**: prev/next/random buttons, seed display, jump-to-seed input
+2. **Parameter controls**: sliders for numeric values, color pickers for palette
+3. **Actions**: regenerate, reset defaults, download PNG
+
+### Philosophy Examples
+
+**Flow Fields**: Layered Perlin noise driving particle trails. Thousands of particles follow vector forces, accumulating into organic density maps.
+
+**Quantum Harmonics**: Particles on a grid with phase values evolving through sine waves. Constructive/destructive interference creates emergent patterns.
+
+**Stochastic Crystallization**: Randomized circle packing or Voronoi tessellation. Random points evolve through relaxation algorithms until equilibrium.
+
+**Recursive Whispers**: Branching structures that subdivide recursively, constrained by golden ratios with noise perturbations.
+
+### Quality Bar
+The output should look like it was refined by a computational artist over hundreds of iterations. Every parameter should feel carefully tuned. The result should reward sustained viewing.

package/references/interaction-design.md

@@ -0,0 +1,162 @@
+# Interaction Design Reference
+
+## Table of Contents
+1. Form Design
+2. Focus Management
+3. Loading Patterns
+4. Empty States
+5. Error Handling
+6. UX Writing
+7. Common Mistakes
+
+---
+
+## 1. Form Design
+
+### Input Fields
+- Use visible labels above inputs, not placeholder-only labels (placeholders disappear on focus)
+- Input height: 40-48px for desktop, 48px minimum for touch
+- Group related fields visually (name + email, street + city + zip)
+- Show validation inline, not in an alert after submission
+- Use `inputmode` attribute for mobile keyboards: `inputmode="email"`, `inputmode="numeric"`, `inputmode="tel"`
+- Auto-focus the first field on page load when the form is the primary task
+
+### Field States
+Every input needs four visible states:
+1. **Default**: subtle border, neutral background
+2. **Focus**: accent border (2px), subtle glow or shadow
+3. **Error**: error-colored border, inline error message below the field
+4. **Disabled**: reduced opacity (0.5), `cursor: not-allowed`
+
+### Buttons
+- Primary action: filled, high contrast (accent color)
+- Secondary action: outlined or ghost (border only)
+- Destructive action: red/error color, requires confirmation for irreversible actions
+- Button text: verb-first ("Save changes", "Create project"), never "Submit" or "Click here"
+- Loading state: replace text with spinner or use `aria-busy="true"`, disable the button to prevent double-submission
+
+---
+
+## 2. Focus Management
+
+### Focus Indicators
+Never remove focus outlines without replacement. Use a visible, high-contrast focus ring:
+```css
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+```
+
+Use `:focus-visible` (not `:focus`) to show focus rings only for keyboard navigation, not mouse clicks.
+
+### Focus Trapping
+Modal dialogs must trap focus within them. When a modal opens:
+1. Move focus to the first focusable element inside
+2. Tab cycles within the modal
+3. Escape closes the modal
+4. Focus returns to the trigger element on close
+
+### Skip Links
+Add a skip-to-content link as the first focusable element:
+```html
+<a href="#main-content" class="skip-link">Skip to content</a>
+```
+```css
+.skip-link {
+  position: absolute;
+  top: -100%;
+  left: 0;
+}
+.skip-link:focus {
+  top: 0;
+  z-index: 1000;
+}
+```
+
+---
+
+## 3. Loading Patterns
+
+### Skeleton Screens
+Replace content with gray shapes that match the expected layout. This feels faster than a spinner because the user can see the structure forming.
+
+### Progressive Loading
+Show content as it arrives. Do not wait for everything to load before showing anything. Use `Suspense` boundaries in React to show parts of the page while others load.
+
+### Optimistic Updates
+For user-initiated actions (like, save, delete), update the UI immediately and reconcile with the server response. Show a subtle undo option if the server rejects the action.
+
+### Spinner vs. Skeleton
+- **Spinner**: Use for actions that take 1-3 seconds (button submissions, API calls). Place inside the triggering element.
+- **Skeleton**: Use for content areas that take 0.5-5 seconds to load. Match the shape of the expected content.
+- **Progress bar**: Use for operations that take 5+ seconds with measurable progress (file uploads, multi-step processes).
+
+---
+
+## 4. Empty States
+
+Empty states are an opportunity, not a placeholder. They should:
+1. Explain what this area will contain once populated
+2. Provide a clear action to get started
+3. Optionally include an illustration or icon for warmth
+
+```
+No projects yet.
+Create your first project to get started.
+[+ Create Project]
+```
+
+Never show a blank page, an error message, or raw "null" / "undefined" in place of empty content.
+
+---
+
+## 5. Error Handling
+
+### Inline Errors
+Show errors next to the element that caused them, not in a modal or toast. Use the error color for the field border and display the message directly below.
+
+### Error Messages
+- Be specific: "Email address must include an @ symbol" not "Invalid input"
+- Be helpful: suggest the fix, not just the problem
+- Be human: "We couldn't find that page" not "404 Not Found"
+
+### Network Errors
+Show a non-blocking banner or inline message with a retry action. Never show a raw error object or stack trace.
+
+### Form Validation
+Validate on blur (when the user leaves a field), not on every keystroke. Show success indicators for valid fields (subtle checkmark or green border).
+
+---
+
+## 6. UX Writing
+
+### Buttons
+- Use action verbs: "Save", "Send", "Create", "Delete"
+- Be specific: "Save changes" > "Save", "Send message" > "Send"
+- Match the action to the context: "Place order" not "Submit"
+
+### Labels
+- Clear and concise: "Full name" not "Please enter your full name"
+- Avoid jargon: "Phone number" not "Primary contact number"
+
+### Confirmations
+- State what happened: "Project created successfully"
+- Provide next step if relevant: "Project created. Add your first task?"
+
+### Destructive Actions
+- State what will happen: "This will permanently delete 3 files"
+- Require explicit confirmation: "Type DELETE to confirm"
+- Provide an out: "Cancel" should be more prominent than "Delete"
+
+---
+
+## 7. Common Mistakes
+
+- Placeholder text as the only label (disappears on focus, inaccessible)
+- Disabling the submit button before all fields are filled (users do not know which field is missing)
+- Using toast notifications for errors (the user may not see them, they disappear)
+- No loading feedback after clicking a button (user clicks again, causing duplicate submissions)
+- Custom scrollbars that break native scroll behavior
+- Hover-only interactions with no keyboard or touch equivalent
+- Alert/confirm dialogs that block the entire page for minor confirmations