diff --git a/product-team/ui-design-system/SKILL.md b/product-team/ui-design-system/SKILL.md
index 35be86b..2f08dc4 100644
--- a/product-team/ui-design-system/SKILL.md
+++ b/product-team/ui-design-system/SKILL.md
@@ -5,28 +5,375 @@ description: UI design system toolkit for Senior UI Designer including design to
# UI Design System
-Professional toolkit for creating and maintaining scalable design systems.
+Generate design tokens, create color palettes, calculate typography scales, build component systems, and prepare developer handoff documentation.
-## Core Capabilities
-- Design token generation (colors, typography, spacing)
-- Component system architecture
-- Responsive design calculations
-- Accessibility compliance
-- Developer handoff documentation
+---
-## Key Scripts
+## Table of Contents
+
+- [Trigger Terms](#trigger-terms)
+- [Workflows](#workflows)
+ - [Workflow 1: Generate Design Tokens](#workflow-1-generate-design-tokens)
+ - [Workflow 2: Create Component System](#workflow-2-create-component-system)
+ - [Workflow 3: Responsive Design](#workflow-3-responsive-design)
+ - [Workflow 4: Developer Handoff](#workflow-4-developer-handoff)
+- [Tool Reference](#tool-reference)
+- [Quick Reference Tables](#quick-reference-tables)
+- [Knowledge Base](#knowledge-base)
+
+---
+
+## Trigger Terms
+
+Use this skill when you need to:
+
+- "generate design tokens"
+- "create color palette"
+- "build typography scale"
+- "calculate spacing system"
+- "create design system"
+- "generate CSS variables"
+- "export SCSS tokens"
+- "set up component architecture"
+- "document component library"
+- "calculate responsive breakpoints"
+- "prepare developer handoff"
+- "convert brand color to palette"
+- "check WCAG contrast"
+- "build 8pt grid system"
+
+---
+
+## Workflows
+
+### Workflow 1: Generate Design Tokens
+
+**Situation:** You have a brand color and need a complete design token system.
+
+**Steps:**
+
+1. **Identify brand color and style**
+ - Brand primary color (hex format)
+ - Style preference: `modern` | `classic` | `playful`
+
+2. **Generate tokens using script**
+ ```bash
+ python scripts/design_token_generator.py "#0066CC" modern json
+ ```
+
+3. **Review generated categories**
+ - Colors: primary, secondary, neutral, semantic, surface
+ - Typography: fontFamily, fontSize, fontWeight, lineHeight
+ - Spacing: 8pt grid-based scale (0-64)
+ - Borders: radius, width
+ - Shadows: none through 2xl
+ - Animation: duration, easing
+ - Breakpoints: xs through 2xl
+
+4. **Export in target format**
+ ```bash
+ # CSS custom properties
+ python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css
+
+ # SCSS variables
+ python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss
+
+ # JSON for Figma/tooling
+ python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json
+ ```
+
+5. **Validate accessibility**
+ - Check color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)
+ - Verify semantic colors have contrast colors defined
+
+---
+
+### Workflow 2: Create Component System
+
+**Situation:** You need to structure a component library using design tokens.
+
+**Steps:**
+
+1. **Define component hierarchy**
+ - Atoms: Button, Input, Icon, Label, Badge
+ - Molecules: FormField, SearchBar, Card, ListItem
+ - Organisms: Header, Footer, DataTable, Modal
+ - Templates: DashboardLayout, AuthLayout
+
+2. **Map tokens to components**
+
+ | Component | Tokens Used |
+ |-----------|-------------|
+ | Button | colors, sizing, borders, shadows, typography |
+ | Input | colors, sizing, borders, spacing |
+ | Card | colors, borders, shadows, spacing |
+ | Modal | colors, shadows, spacing, z-index, animation |
+
+3. **Define variant patterns**
+
+ Size variants:
+ ```
+ sm: height 32px, paddingX 12px, fontSize 14px
+ md: height 40px, paddingX 16px, fontSize 16px
+ lg: height 48px, paddingX 20px, fontSize 18px
+ ```
+
+ Color variants:
+ ```
+ primary: background primary-500, text white
+ secondary: background neutral-100, text neutral-900
+ ghost: background transparent, text neutral-700
+ ```
+
+4. **Document component API**
+ - Props interface with types
+ - Variant options
+ - State handling (hover, active, focus, disabled)
+ - Accessibility requirements
+
+5. **Reference:** See `references/component-architecture.md`
+
+---
+
+### Workflow 3: Responsive Design
+
+**Situation:** You need breakpoints, fluid typography, or responsive spacing.
+
+**Steps:**
+
+1. **Define breakpoints**
+
+ | Name | Width | Target |
+ |------|-------|--------|
+ | xs | 0 | Small phones |
+ | sm | 480px | Large phones |
+ | md | 640px | Tablets |
+ | lg | 768px | Small laptops |
+ | xl | 1024px | Desktops |
+ | 2xl | 1280px | Large screens |
+
+2. **Calculate fluid typography**
+
+ Formula: `clamp(min, preferred, max)`
+
+ ```css
+ /* 16px to 24px between 320px and 1200px viewport */
+ font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
+ ```
+
+ Pre-calculated scales:
+ ```css
+ --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
+ --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
+ --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
+ --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
+ ```
+
+3. **Set up responsive spacing**
+
+ | Token | Mobile | Tablet | Desktop |
+ |-------|--------|--------|---------|
+ | --space-md | 12px | 16px | 16px |
+ | --space-lg | 16px | 24px | 32px |
+ | --space-xl | 24px | 32px | 48px |
+ | --space-section | 48px | 80px | 120px |
+
+4. **Reference:** See `references/responsive-calculations.md`
+
+---
+
+### Workflow 4: Developer Handoff
+
+**Situation:** You need to hand off design tokens to development team.
+
+**Steps:**
+
+1. **Export tokens in required formats**
+ ```bash
+ # For CSS projects
+ python scripts/design_token_generator.py "#0066CC" modern css
+
+ # For SCSS projects
+ python scripts/design_token_generator.py "#0066CC" modern scss
+
+ # For JavaScript/TypeScript
+ python scripts/design_token_generator.py "#0066CC" modern json
+ ```
+
+2. **Prepare framework integration**
+
+ **React + CSS Variables:**
+ ```tsx
+ import './design-tokens.css';
+
+
+ ```
+
+ **Tailwind Config:**
+ ```javascript
+ const tokens = require('./design-tokens.json');
+
+ module.exports = {
+ theme: {
+ colors: tokens.colors,
+ fontFamily: tokens.typography.fontFamily
+ }
+ };
+ ```
+
+ **styled-components:**
+ ```typescript
+ import tokens from './design-tokens.json';
+
+ const Button = styled.button`
+ background: ${tokens.colors.primary['500']};
+ padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
+ `;
+ ```
+
+3. **Sync with Figma**
+ - Install Tokens Studio plugin
+ - Import design-tokens.json
+ - Tokens sync automatically with Figma styles
+
+4. **Handoff checklist**
+ - [ ] Token files added to project
+ - [ ] Build pipeline configured
+ - [ ] Theme/CSS variables imported
+ - [ ] Component library aligned
+ - [ ] Documentation generated
+
+5. **Reference:** See `references/developer-handoff.md`
+
+---
+
+## Tool Reference
### design_token_generator.py
-Generates complete design system tokens from brand colors.
-**Usage**: `python scripts/design_token_generator.py [brand_color] [style] [format]`
-- Styles: modern, classic, playful
-- Formats: json, css, scss
+Generates complete design token system from brand color.
-**Features**:
-- Complete color palette generation
-- Modular typography scale
-- 8pt spacing grid system
-- Shadow and animation tokens
-- Responsive breakpoints
-- Multiple export formats
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| brand_color | Hex color | #0066CC | Primary brand color |
+| style | modern, classic, playful | modern | Design style preset |
+| format | json, css, scss, summary | json | Output format |
+
+**Examples:**
+
+```bash
+# Generate JSON tokens (default)
+python scripts/design_token_generator.py "#0066CC"
+
+# Classic style with CSS output
+python scripts/design_token_generator.py "#8B4513" classic css
+
+# Playful style summary view
+python scripts/design_token_generator.py "#FF6B6B" playful summary
+```
+
+**Output Categories:**
+
+| Category | Description | Key Values |
+|----------|-------------|------------|
+| colors | Color palettes | primary, secondary, neutral, semantic, surface |
+| typography | Font system | fontFamily, fontSize, fontWeight, lineHeight |
+| spacing | 8pt grid | 0-64 scale, semantic (xs-3xl) |
+| sizing | Component sizes | container, button, input, icon |
+| borders | Border values | radius (per style), width |
+| shadows | Shadow styles | none through 2xl, inner |
+| animation | Motion tokens | duration, easing, keyframes |
+| breakpoints | Responsive | xs, sm, md, lg, xl, 2xl |
+| z-index | Layer system | base through notification |
+
+---
+
+## Quick Reference Tables
+
+### Color Scale Generation
+
+| Step | Brightness | Saturation | Use Case |
+|------|------------|------------|----------|
+| 50 | 95% fixed | 30% | Subtle backgrounds |
+| 100 | 95% fixed | 38% | Light backgrounds |
+| 200 | 95% fixed | 46% | Hover states |
+| 300 | 95% fixed | 54% | Borders |
+| 400 | 95% fixed | 62% | Disabled states |
+| 500 | Original | 70% | Base/default color |
+| 600 | Original × 0.8 | 78% | Hover (dark) |
+| 700 | Original × 0.6 | 86% | Active states |
+| 800 | Original × 0.4 | 94% | Text |
+| 900 | Original × 0.2 | 100% | Headings |
+
+### Typography Scale (1.25x Ratio)
+
+| Size | Value | Calculation |
+|------|-------|-------------|
+| xs | 10px | 16 ÷ 1.25² |
+| sm | 13px | 16 ÷ 1.25¹ |
+| base | 16px | Base |
+| lg | 20px | 16 × 1.25¹ |
+| xl | 25px | 16 × 1.25² |
+| 2xl | 31px | 16 × 1.25³ |
+| 3xl | 39px | 16 × 1.25⁴ |
+| 4xl | 49px | 16 × 1.25⁵ |
+| 5xl | 61px | 16 × 1.25⁶ |
+
+### WCAG Contrast Requirements
+
+| Level | Normal Text | Large Text |
+|-------|-------------|------------|
+| AA | 4.5:1 | 3:1 |
+| AAA | 7:1 | 4.5:1 |
+
+Large text: ≥18pt regular or ≥14pt bold
+
+### Style Presets
+
+| Aspect | Modern | Classic | Playful |
+|--------|--------|---------|---------|
+| Font Sans | Inter | Helvetica | Poppins |
+| Font Mono | Fira Code | Courier | Source Code Pro |
+| Radius Default | 8px | 4px | 16px |
+| Shadows | Layered, subtle | Single layer | Soft, pronounced |
+
+---
+
+## Knowledge Base
+
+Detailed reference guides in `references/`:
+
+| File | Content |
+|------|---------|
+| `token-generation.md` | Color algorithms, HSV space, WCAG contrast, type scales |
+| `component-architecture.md` | Atomic design, naming conventions, props patterns |
+| `responsive-calculations.md` | Breakpoints, fluid typography, grid systems |
+| `developer-handoff.md` | Export formats, framework setup, Figma sync |
+
+---
+
+## Validation Checklist
+
+### Token Generation
+- [ ] Brand color provided in hex format
+- [ ] Style matches project requirements
+- [ ] All token categories generated
+- [ ] Semantic colors include contrast values
+
+### Component System
+- [ ] All sizes implemented (sm, md, lg)
+- [ ] All variants implemented (primary, secondary, ghost)
+- [ ] All states working (hover, active, focus, disabled)
+- [ ] Uses only design tokens (no hardcoded values)
+
+### Accessibility
+- [ ] Color contrast meets WCAG AA
+- [ ] Focus indicators visible
+- [ ] Touch targets ≥ 44×44px
+- [ ] Semantic HTML elements used
+
+### Developer Handoff
+- [ ] Tokens exported in required format
+- [ ] Framework integration documented
+- [ ] Design tool synced
+- [ ] Component documentation complete
diff --git a/product-team/ui-design-system/references/component-architecture.md b/product-team/ui-design-system/references/component-architecture.md
new file mode 100644
index 0000000..a50a1e2
--- /dev/null
+++ b/product-team/ui-design-system/references/component-architecture.md
@@ -0,0 +1,396 @@
+# Component Architecture Guide
+
+Reference for design system component organization, naming conventions, and documentation patterns.
+
+---
+
+## Table of Contents
+
+- [Component Hierarchy](#component-hierarchy)
+- [Naming Conventions](#naming-conventions)
+- [Component Documentation](#component-documentation)
+- [Variant Patterns](#variant-patterns)
+- [Token Integration](#token-integration)
+
+---
+
+## Component Hierarchy
+
+### Atomic Design Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ COMPONENT HIERARCHY │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ TOKENS (Foundation) │
+│ └── Colors, Typography, Spacing, Shadows │
+│ │
+│ ATOMS (Basic Elements) │
+│ └── Button, Input, Icon, Label, Badge │
+│ │
+│ MOLECULES (Simple Combinations) │
+│ └── FormField, SearchBar, Card, ListItem │
+│ │
+│ ORGANISMS (Complex Components) │
+│ └── Header, Footer, DataTable, Modal │
+│ │
+│ TEMPLATES (Page Layouts) │
+│ └── DashboardLayout, AuthLayout, SettingsLayout │
+│ │
+│ PAGES (Specific Instances) │
+│ └── HomePage, LoginPage, UserProfile │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Component Categories
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| **Primitives** | Base HTML wrapper | Box, Text, Flex, Grid |
+| **Inputs** | User interaction | Button, Input, Select, Checkbox |
+| **Display** | Content presentation | Card, Badge, Avatar, Icon |
+| **Feedback** | User feedback | Alert, Toast, Progress, Skeleton |
+| **Navigation** | Route management | Link, Menu, Tabs, Breadcrumb |
+| **Overlay** | Layer above content | Modal, Drawer, Popover, Tooltip |
+| **Layout** | Structure | Stack, Container, Divider |
+
+---
+
+## Naming Conventions
+
+### Token Naming
+
+```
+{category}-{property}-{variant}-{state}
+
+Examples:
+ color-primary-500
+ color-primary-500-hover
+ spacing-md
+ fontSize-lg
+ shadow-md
+ radius-lg
+```
+
+### Component Naming
+
+```
+{ComponentName} # PascalCase for components
+{componentName}{Variant} # Variant suffix
+
+Examples:
+ Button
+ ButtonPrimary
+ ButtonOutline
+ ButtonGhost
+```
+
+### CSS Class Naming (BEM)
+
+```
+.block__element--modifier
+
+Examples:
+ .button
+ .button__icon
+ .button--primary
+ .button--lg
+ .button__icon--loading
+```
+
+### File Structure
+
+```
+components/
+├── Button/
+│ ├── Button.tsx # Main component
+│ ├── Button.styles.ts # Styles/tokens
+│ ├── Button.test.tsx # Tests
+│ ├── Button.stories.tsx # Storybook
+│ ├── Button.types.ts # TypeScript types
+│ └── index.ts # Export
+├── Input/
+│ └── ...
+└── index.ts # Barrel export
+```
+
+---
+
+## Component Documentation
+
+### Documentation Template
+
+```markdown
+# ComponentName
+
+Brief description of what this component does.
+
+## Usage
+
+\`\`\`tsx
+import { Button } from '@design-system/components'
+
+
+\`\`\`
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Component size |
+| disabled | boolean | false | Disabled state |
+| onClick | () => void | - | Click handler |
+
+## Variants
+
+### Primary
+Use for main actions.
+
+### Secondary
+Use for secondary actions.
+
+### Ghost
+Use for tertiary or inline actions.
+
+## Accessibility
+
+- Uses `button` role by default
+- Supports `aria-disabled` for disabled state
+- Focus ring visible for keyboard navigation
+
+## Design Tokens Used
+
+- `color-primary-*` for primary variant
+- `spacing-*` for padding
+- `radius-md` for border radius
+- `shadow-sm` for elevation
+```
+
+### Props Interface Pattern
+
+```typescript
+interface ButtonProps {
+ /** Visual variant of the button */
+ variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+
+ /** Size of the button */
+ size?: 'sm' | 'md' | 'lg';
+
+ /** Whether button is disabled */
+ disabled?: boolean;
+
+ /** Whether button shows loading state */
+ loading?: boolean;
+
+ /** Left icon element */
+ leftIcon?: React.ReactNode;
+
+ /** Right icon element */
+ rightIcon?: React.ReactNode;
+
+ /** Click handler */
+ onClick?: () => void;
+
+ /** Button content */
+ children: React.ReactNode;
+}
+```
+
+---
+
+## Variant Patterns
+
+### Size Variants
+
+```typescript
+const sizeTokens = {
+ sm: {
+ height: 'sizing-button-sm-height', // 32px
+ paddingX: 'sizing-button-sm-paddingX', // 12px
+ fontSize: 'fontSize-sm', // 14px
+ iconSize: 'sizing-icon-sm' // 16px
+ },
+ md: {
+ height: 'sizing-button-md-height', // 40px
+ paddingX: 'sizing-button-md-paddingX', // 16px
+ fontSize: 'fontSize-base', // 16px
+ iconSize: 'sizing-icon-md' // 20px
+ },
+ lg: {
+ height: 'sizing-button-lg-height', // 48px
+ paddingX: 'sizing-button-lg-paddingX', // 20px
+ fontSize: 'fontSize-lg', // 18px
+ iconSize: 'sizing-icon-lg' // 24px
+ }
+};
+```
+
+### Color Variants
+
+```typescript
+const variantTokens = {
+ primary: {
+ background: 'color-primary-500',
+ backgroundHover: 'color-primary-600',
+ backgroundActive: 'color-primary-700',
+ text: 'color-white',
+ border: 'transparent'
+ },
+ secondary: {
+ background: 'color-neutral-100',
+ backgroundHover: 'color-neutral-200',
+ backgroundActive: 'color-neutral-300',
+ text: 'color-neutral-900',
+ border: 'transparent'
+ },
+ outline: {
+ background: 'transparent',
+ backgroundHover: 'color-primary-50',
+ backgroundActive: 'color-primary-100',
+ text: 'color-primary-500',
+ border: 'color-primary-500'
+ },
+ ghost: {
+ background: 'transparent',
+ backgroundHover: 'color-neutral-100',
+ backgroundActive: 'color-neutral-200',
+ text: 'color-neutral-700',
+ border: 'transparent'
+ }
+};
+```
+
+### State Variants
+
+```typescript
+const stateStyles = {
+ default: {
+ cursor: 'pointer',
+ opacity: 1
+ },
+ hover: {
+ // Uses variantTokens backgroundHover
+ },
+ active: {
+ // Uses variantTokens backgroundActive
+ transform: 'scale(0.98)'
+ },
+ focus: {
+ outline: 'none',
+ boxShadow: '0 0 0 2px color-primary-200'
+ },
+ disabled: {
+ cursor: 'not-allowed',
+ opacity: 0.5,
+ pointerEvents: 'none'
+ },
+ loading: {
+ cursor: 'wait',
+ pointerEvents: 'none'
+ }
+};
+```
+
+---
+
+## Token Integration
+
+### Consuming Tokens in Components
+
+**CSS Custom Properties:**
+
+```css
+.button {
+ height: var(--sizing-button-md-height);
+ padding-left: var(--sizing-button-md-paddingX);
+ padding-right: var(--sizing-button-md-paddingX);
+ font-size: var(--typography-fontSize-base);
+ border-radius: var(--borders-radius-md);
+}
+
+.button--primary {
+ background-color: var(--colors-primary-500);
+ color: var(--colors-surface-background);
+}
+
+.button--primary:hover {
+ background-color: var(--colors-primary-600);
+}
+```
+
+**JavaScript/TypeScript:**
+
+```typescript
+import tokens from './design-tokens.json';
+
+const buttonStyles = {
+ height: tokens.sizing.components.button.md.height,
+ paddingLeft: tokens.sizing.components.button.md.paddingX,
+ backgroundColor: tokens.colors.primary['500'],
+ borderRadius: tokens.borders.radius.md
+};
+```
+
+**Styled Components:**
+
+```typescript
+import styled from 'styled-components';
+
+const Button = styled.button`
+ height: ${({ theme }) => theme.sizing.components.button.md.height};
+ padding: 0 ${({ theme }) => theme.sizing.components.button.md.paddingX};
+ background: ${({ theme }) => theme.colors.primary['500']};
+ border-radius: ${({ theme }) => theme.borders.radius.md};
+
+ &:hover {
+ background: ${({ theme }) => theme.colors.primary['600']};
+ }
+`;
+```
+
+### Token-to-Component Mapping
+
+| Component | Token Categories Used |
+|-----------|----------------------|
+| Button | colors, sizing, borders, shadows, typography |
+| Input | colors, sizing, borders, spacing |
+| Card | colors, borders, shadows, spacing |
+| Typography | typography (all), colors |
+| Icon | sizing, colors |
+| Modal | colors, shadows, spacing, z-index, animation |
+
+---
+
+## Component Checklist
+
+### Before Release
+
+- [ ] All sizes implemented (sm, md, lg)
+- [ ] All variants implemented (primary, secondary, etc.)
+- [ ] All states working (hover, active, focus, disabled)
+- [ ] Keyboard accessible
+- [ ] Screen reader tested
+- [ ] Uses only design tokens (no hardcoded values)
+- [ ] TypeScript types complete
+- [ ] Storybook stories for all variants
+- [ ] Unit tests passing
+- [ ] Documentation complete
+
+### Accessibility Checklist
+
+- [ ] Correct semantic HTML element
+- [ ] ARIA attributes where needed
+- [ ] Visible focus indicator
+- [ ] Color contrast meets AA
+- [ ] Works with keyboard only
+- [ ] Screen reader announces correctly
+- [ ] Touch target ≥ 44×44px
+
+---
+
+*See also: `token-generation.md` for token creation*
diff --git a/product-team/ui-design-system/references/developer-handoff.md b/product-team/ui-design-system/references/developer-handoff.md
new file mode 100644
index 0000000..ee0d60a
--- /dev/null
+++ b/product-team/ui-design-system/references/developer-handoff.md
@@ -0,0 +1,509 @@
+# Developer Handoff Guide
+
+Reference for integrating design tokens into development workflows and design tool collaboration.
+
+---
+
+## Table of Contents
+
+- [Export Formats](#export-formats)
+- [Integration Patterns](#integration-patterns)
+- [Framework Setup](#framework-setup)
+- [Design Tool Integration](#design-tool-integration)
+- [Handoff Checklist](#handoff-checklist)
+
+---
+
+## Export Formats
+
+### JSON (Recommended for Most Projects)
+
+**File:** `design-tokens.json`
+
+```json
+{
+ "meta": {
+ "version": "1.0.0",
+ "style": "modern",
+ "generated": "2024-01-15"
+ },
+ "colors": {
+ "primary": {
+ "50": "#E6F2FF",
+ "100": "#CCE5FF",
+ "500": "#0066CC",
+ "900": "#002855"
+ }
+ },
+ "typography": {
+ "fontFamily": {
+ "sans": "Inter, system-ui, sans-serif",
+ "mono": "Fira Code, monospace"
+ },
+ "fontSize": {
+ "xs": "10px",
+ "sm": "13px",
+ "base": "16px",
+ "lg": "20px"
+ }
+ },
+ "spacing": {
+ "0": "0px",
+ "1": "4px",
+ "2": "8px",
+ "4": "16px"
+ }
+}
+```
+
+**Use Case:** JavaScript/TypeScript projects, build tools, Figma plugins
+
+### CSS Custom Properties
+
+**File:** `design-tokens.css`
+
+```css
+:root {
+ /* Colors */
+ --color-primary-50: #E6F2FF;
+ --color-primary-100: #CCE5FF;
+ --color-primary-500: #0066CC;
+ --color-primary-900: #002855;
+
+ /* Typography */
+ --font-family-sans: Inter, system-ui, sans-serif;
+ --font-family-mono: Fira Code, monospace;
+ --font-size-xs: 10px;
+ --font-size-sm: 13px;
+ --font-size-base: 16px;
+ --font-size-lg: 20px;
+
+ /* Spacing */
+ --spacing-0: 0px;
+ --spacing-1: 4px;
+ --spacing-2: 8px;
+ --spacing-4: 16px;
+}
+```
+
+**Use Case:** Plain CSS, CSS-in-JS, any web project
+
+### SCSS Variables
+
+**File:** `_design-tokens.scss`
+
+```scss
+// Colors
+$color-primary-50: #E6F2FF;
+$color-primary-100: #CCE5FF;
+$color-primary-500: #0066CC;
+$color-primary-900: #002855;
+
+// Typography
+$font-family-sans: Inter, system-ui, sans-serif;
+$font-family-mono: Fira Code, monospace;
+$font-size-xs: 10px;
+$font-size-sm: 13px;
+$font-size-base: 16px;
+$font-size-lg: 20px;
+
+// Spacing
+$spacing-0: 0px;
+$spacing-1: 4px;
+$spacing-2: 8px;
+$spacing-4: 16px;
+
+// Maps for programmatic access
+$colors-primary: (
+ '50': $color-primary-50,
+ '100': $color-primary-100,
+ '500': $color-primary-500,
+ '900': $color-primary-900
+);
+```
+
+**Use Case:** SASS/SCSS pipelines, component libraries
+
+---
+
+## Integration Patterns
+
+### Pattern 1: CSS Variables (Universal)
+
+Works with any framework or vanilla CSS.
+
+```css
+/* Import tokens */
+@import 'design-tokens.css';
+
+/* Use in styles */
+.button {
+ background-color: var(--color-primary-500);
+ padding: var(--spacing-2) var(--spacing-4);
+ font-size: var(--font-size-base);
+ border-radius: var(--radius-md);
+}
+
+.button:hover {
+ background-color: var(--color-primary-600);
+}
+```
+
+### Pattern 2: JavaScript Theme Object
+
+For CSS-in-JS libraries (styled-components, Emotion, etc.)
+
+```typescript
+// theme.ts
+import tokens from './design-tokens.json';
+
+export const theme = {
+ colors: {
+ primary: tokens.colors.primary,
+ secondary: tokens.colors.secondary,
+ neutral: tokens.colors.neutral,
+ semantic: tokens.colors.semantic
+ },
+ typography: {
+ fontFamily: tokens.typography.fontFamily,
+ fontSize: tokens.typography.fontSize,
+ fontWeight: tokens.typography.fontWeight
+ },
+ spacing: tokens.spacing,
+ shadows: tokens.shadows,
+ radii: tokens.borders.radius
+};
+
+export type Theme = typeof theme;
+```
+
+```typescript
+// styled-components usage
+import styled from 'styled-components';
+
+const Button = styled.button`
+ background: ${({ theme }) => theme.colors.primary['500']};
+ padding: ${({ theme }) => theme.spacing['2']} ${({ theme }) => theme.spacing['4']};
+ font-size: ${({ theme }) => theme.typography.fontSize.base};
+`;
+```
+
+### Pattern 3: Tailwind Config
+
+```javascript
+// tailwind.config.js
+const tokens = require('./design-tokens.json');
+
+module.exports = {
+ theme: {
+ colors: {
+ primary: tokens.colors.primary,
+ secondary: tokens.colors.secondary,
+ neutral: tokens.colors.neutral,
+ success: tokens.colors.semantic.success,
+ warning: tokens.colors.semantic.warning,
+ error: tokens.colors.semantic.error
+ },
+ fontFamily: {
+ sans: [tokens.typography.fontFamily.sans],
+ serif: [tokens.typography.fontFamily.serif],
+ mono: [tokens.typography.fontFamily.mono]
+ },
+ spacing: {
+ 0: tokens.spacing['0'],
+ 1: tokens.spacing['1'],
+ 2: tokens.spacing['2'],
+ // ... etc
+ },
+ borderRadius: tokens.borders.radius,
+ boxShadow: tokens.shadows
+ }
+};
+```
+
+---
+
+## Framework Setup
+
+### React + CSS Variables
+
+```tsx
+// App.tsx
+import './design-tokens.css';
+import './styles.css';
+
+function App() {
+ return (
+
+ );
+}
+```
+
+```css
+/* styles.css */
+.btn {
+ padding: var(--spacing-2) var(--spacing-4);
+ font-size: var(--font-size-base);
+ font-weight: var(--font-weight-medium);
+ border-radius: var(--radius-md);
+ transition: background-color var(--animation-duration-fast);
+}
+
+.btn-primary {
+ background: var(--color-primary-500);
+ color: var(--color-surface-background);
+}
+
+.btn-primary:hover {
+ background: var(--color-primary-600);
+}
+```
+
+### React + styled-components
+
+```tsx
+// ThemeProvider.tsx
+import { ThemeProvider } from 'styled-components';
+import { theme } from './theme';
+
+export function AppThemeProvider({ children }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+```tsx
+// Button.tsx
+import styled from 'styled-components';
+
+export const Button = styled.button<{ variant?: 'primary' | 'secondary' }>`
+ padding: ${({ theme }) => `${theme.spacing['2']} ${theme.spacing['4']}`};
+ font-size: ${({ theme }) => theme.typography.fontSize.base};
+ border-radius: ${({ theme }) => theme.radii.md};
+
+ ${({ variant = 'primary', theme }) => variant === 'primary' && `
+ background: ${theme.colors.primary['500']};
+ color: ${theme.colors.surface.background};
+
+ &:hover {
+ background: ${theme.colors.primary['600']};
+ }
+ `}
+`;
+```
+
+### Vue + CSS Variables
+
+```vue
+
+
+
+
+
+
+```
+
+### Next.js + Tailwind
+
+```javascript
+// tailwind.config.js
+const tokens = require('./design-tokens.json');
+
+module.exports = {
+ content: ['./app/**/*.{js,ts,jsx,tsx}'],
+ theme: {
+ extend: {
+ colors: tokens.colors,
+ fontFamily: {
+ sans: tokens.typography.fontFamily.sans.split(', ')
+ }
+ }
+ }
+};
+```
+
+```tsx
+// page.tsx
+export default function Page() {
+ return (
+
+ );
+}
+```
+
+---
+
+## Design Tool Integration
+
+### Figma
+
+**Option 1: Tokens Studio Plugin**
+1. Install "Tokens Studio for Figma" plugin
+2. Import `design-tokens.json`
+3. Tokens sync automatically with Figma styles
+
+**Option 2: Figma Variables (Native)**
+1. Open Variables panel
+2. Create collections matching token structure
+3. Import JSON via plugin or API
+
+**Sync Workflow:**
+```
+design_token_generator.py
+ ↓
+design-tokens.json
+ ↓
+Tokens Studio Plugin
+ ↓
+Figma Styles & Variables
+```
+
+### Storybook
+
+```javascript
+// .storybook/preview.js
+import '../design-tokens.css';
+
+export const parameters = {
+ backgrounds: {
+ default: 'light',
+ values: [
+ { name: 'light', value: '#FFFFFF' },
+ { name: 'dark', value: '#111827' }
+ ]
+ }
+};
+```
+
+```javascript
+// Button.stories.tsx
+import { Button } from './Button';
+
+export default {
+ title: 'Components/Button',
+ component: Button,
+ argTypes: {
+ variant: {
+ control: 'select',
+ options: ['primary', 'secondary', 'ghost']
+ },
+ size: {
+ control: 'select',
+ options: ['sm', 'md', 'lg']
+ }
+ }
+};
+
+export const Primary = {
+ args: {
+ variant: 'primary',
+ children: 'Button'
+ }
+};
+```
+
+### Design Tool Comparison
+
+| Tool | Token Format | Sync Method |
+|------|--------------|-------------|
+| Figma | JSON | Tokens Studio plugin / Variables |
+| Sketch | JSON | Craft / Shared Styles |
+| Adobe XD | JSON | Design Tokens plugin |
+| InVision DSM | JSON | Native import |
+| Zeroheight | JSON/CSS | Direct import |
+
+---
+
+## Handoff Checklist
+
+### Token Generation
+
+- [ ] Brand color defined
+- [ ] Style selected (modern/classic/playful)
+- [ ] Tokens generated: `python scripts/design_token_generator.py "#0066CC" modern`
+- [ ] All formats exported (JSON, CSS, SCSS)
+
+### Developer Setup
+
+- [ ] Token files added to project
+- [ ] Build pipeline configured
+- [ ] Theme/CSS variables imported
+- [ ] Hot reload working for token changes
+
+### Design Sync
+
+- [ ] Figma/design tool updated with tokens
+- [ ] Component library aligned
+- [ ] Documentation generated
+- [ ] Storybook stories created
+
+### Validation
+
+- [ ] Colors render correctly
+- [ ] Typography scales properly
+- [ ] Spacing matches design
+- [ ] Responsive breakpoints work
+- [ ] Dark mode tokens (if applicable)
+
+### Documentation Deliverables
+
+| Document | Contents |
+|----------|----------|
+| `design-tokens.json` | All tokens in JSON |
+| `design-tokens.css` | CSS custom properties |
+| `_design-tokens.scss` | SCSS variables |
+| `README.md` | Usage instructions |
+| `CHANGELOG.md` | Token version history |
+
+---
+
+## Version Control
+
+### Token Versioning
+
+```json
+{
+ "meta": {
+ "version": "1.2.0",
+ "style": "modern",
+ "generated": "2024-01-15",
+ "changelog": [
+ "1.2.0 - Added animation tokens",
+ "1.1.0 - Updated primary color",
+ "1.0.0 - Initial release"
+ ]
+ }
+}
+```
+
+### Breaking Change Policy
+
+| Change Type | Version Bump | Migration |
+|-------------|--------------|-----------|
+| Add new token | Patch (1.0.x) | None |
+| Change token value | Minor (1.x.0) | Optional |
+| Rename/remove token | Major (x.0.0) | Required |
+
+---
+
+*See also: `token-generation.md` for generation options*
diff --git a/product-team/ui-design-system/references/responsive-calculations.md b/product-team/ui-design-system/references/responsive-calculations.md
new file mode 100644
index 0000000..f6468e3
--- /dev/null
+++ b/product-team/ui-design-system/references/responsive-calculations.md
@@ -0,0 +1,390 @@
+# Responsive Design Calculations
+
+Reference for breakpoint math, fluid typography, and responsive layout patterns.
+
+---
+
+## Table of Contents
+
+- [Breakpoint System](#breakpoint-system)
+- [Fluid Typography](#fluid-typography)
+- [Responsive Spacing](#responsive-spacing)
+- [Container Queries](#container-queries)
+- [Grid Systems](#grid-systems)
+
+---
+
+## Breakpoint System
+
+### Standard Breakpoints
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ BREAKPOINT RANGES │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ xs sm md lg xl 2xl │
+│ │─────────│──────────│──────────│──────────│─────────│ │
+│ 0 480px 640px 768px 1024px 1280px │
+│ 1536px │
+│ │
+│ Mobile Mobile+ Tablet Laptop Desktop Large │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Breakpoint Values
+
+| Name | Min Width | Target Devices |
+|------|-----------|----------------|
+| xs | 0 | Small phones |
+| sm | 480px | Large phones |
+| md | 640px | Small tablets |
+| lg | 768px | Tablets, small laptops |
+| xl | 1024px | Laptops, desktops |
+| 2xl | 1280px | Large desktops |
+| 3xl | 1536px | Extra large displays |
+
+### Mobile-First Media Queries
+
+```css
+/* Base styles (mobile) */
+.component {
+ padding: var(--spacing-sm);
+ font-size: var(--fontSize-sm);
+}
+
+/* Small devices and up */
+@media (min-width: 480px) {
+ .component {
+ padding: var(--spacing-md);
+ }
+}
+
+/* Medium devices and up */
+@media (min-width: 768px) {
+ .component {
+ padding: var(--spacing-lg);
+ font-size: var(--fontSize-base);
+ }
+}
+
+/* Large devices and up */
+@media (min-width: 1024px) {
+ .component {
+ padding: var(--spacing-xl);
+ }
+}
+```
+
+### Breakpoint Utility Function
+
+```javascript
+const breakpoints = {
+ xs: 480,
+ sm: 640,
+ md: 768,
+ lg: 1024,
+ xl: 1280,
+ '2xl': 1536
+};
+
+function mediaQuery(breakpoint, type = 'min') {
+ const value = breakpoints[breakpoint];
+ if (type === 'min') {
+ return `@media (min-width: ${value}px)`;
+ }
+ return `@media (max-width: ${value - 1}px)`;
+}
+
+// Usage
+const styles = `
+ ${mediaQuery('md')} {
+ display: flex;
+ }
+`;
+```
+
+---
+
+## Fluid Typography
+
+### Clamp Formula
+
+```css
+font-size: clamp(min, preferred, max);
+
+/* Example: 16px to 24px between 320px and 1200px viewport */
+font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
+```
+
+### Fluid Scale Calculation
+
+```
+preferred = min + (max - min) * ((100vw - minVW) / (maxVW - minVW))
+
+Simplified:
+preferred = base + (scaling-factor * vw)
+
+Where:
+ scaling-factor = (max - min) / (maxVW - minVW) * 100
+```
+
+### Fluid Typography Scale
+
+| Style | Mobile (320px) | Desktop (1200px) | Clamp Value |
+|-------|----------------|------------------|-------------|
+| h1 | 32px | 64px | `clamp(2rem, 1rem + 3.6vw, 4rem)` |
+| h2 | 28px | 48px | `clamp(1.75rem, 1rem + 2.3vw, 3rem)` |
+| h3 | 24px | 36px | `clamp(1.5rem, 1rem + 1.4vw, 2.25rem)` |
+| h4 | 20px | 28px | `clamp(1.25rem, 1rem + 0.9vw, 1.75rem)` |
+| body | 16px | 18px | `clamp(1rem, 0.95rem + 0.2vw, 1.125rem)` |
+| small | 14px | 14px | `0.875rem` (fixed) |
+
+### Implementation
+
+```css
+:root {
+ /* Fluid type scale */
+ --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
+ --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
+ --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
+ --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
+}
+
+h1 { font-size: var(--fluid-h1); }
+h2 { font-size: var(--fluid-h2); }
+h3 { font-size: var(--fluid-h3); }
+body { font-size: var(--fluid-body); }
+```
+
+---
+
+## Responsive Spacing
+
+### Fluid Spacing Formula
+
+```css
+/* Spacing that scales with viewport */
+spacing: clamp(minSpace, preferredSpace, maxSpace);
+
+/* Example: 16px to 48px */
+--spacing-responsive: clamp(1rem, 0.5rem + 2vw, 3rem);
+```
+
+### Responsive Spacing Scale
+
+| Token | Mobile | Tablet | Desktop |
+|-------|--------|--------|---------|
+| --space-xs | 4px | 4px | 4px |
+| --space-sm | 8px | 8px | 8px |
+| --space-md | 12px | 16px | 16px |
+| --space-lg | 16px | 24px | 32px |
+| --space-xl | 24px | 32px | 48px |
+| --space-2xl | 32px | 48px | 64px |
+| --space-section | 48px | 80px | 120px |
+
+### Implementation
+
+```css
+:root {
+ --space-section: clamp(3rem, 2rem + 4vw, 7.5rem);
+ --space-component: clamp(1rem, 0.5rem + 1vw, 2rem);
+ --space-content: clamp(1.5rem, 1rem + 2vw, 3rem);
+}
+
+.section {
+ padding-top: var(--space-section);
+ padding-bottom: var(--space-section);
+}
+
+.card {
+ padding: var(--space-component);
+ gap: var(--space-content);
+}
+```
+
+---
+
+## Container Queries
+
+### Container Width Tokens
+
+| Container | Max Width | Use Case |
+|-----------|-----------|----------|
+| sm | 640px | Narrow content |
+| md | 768px | Blog posts |
+| lg | 1024px | Standard pages |
+| xl | 1280px | Wide layouts |
+| 2xl | 1536px | Full-width dashboards |
+
+### Container CSS
+
+```css
+.container {
+ width: 100%;
+ margin-left: auto;
+ margin-right: auto;
+ padding-left: var(--spacing-md);
+ padding-right: var(--spacing-md);
+}
+
+.container--sm { max-width: 640px; }
+.container--md { max-width: 768px; }
+.container--lg { max-width: 1024px; }
+.container--xl { max-width: 1280px; }
+.container--2xl { max-width: 1536px; }
+```
+
+### CSS Container Queries
+
+```css
+/* Define container */
+.card-container {
+ container-type: inline-size;
+ container-name: card;
+}
+
+/* Query container width */
+@container card (min-width: 400px) {
+ .card {
+ display: flex;
+ flex-direction: row;
+ }
+}
+
+@container card (min-width: 600px) {
+ .card {
+ gap: var(--spacing-lg);
+ }
+}
+```
+
+---
+
+## Grid Systems
+
+### 12-Column Grid
+
+```css
+.grid {
+ display: grid;
+ grid-template-columns: repeat(12, 1fr);
+ gap: var(--spacing-md);
+}
+
+/* Column spans */
+.col-1 { grid-column: span 1; }
+.col-2 { grid-column: span 2; }
+.col-3 { grid-column: span 3; }
+.col-4 { grid-column: span 4; }
+.col-6 { grid-column: span 6; }
+.col-12 { grid-column: span 12; }
+
+/* Responsive columns */
+@media (min-width: 768px) {
+ .col-md-4 { grid-column: span 4; }
+ .col-md-6 { grid-column: span 6; }
+ .col-md-8 { grid-column: span 8; }
+}
+```
+
+### Auto-Fit Grid
+
+```css
+/* Cards that automatically wrap */
+.auto-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+ gap: var(--spacing-lg);
+}
+
+/* With explicit min/max columns */
+.auto-grid--constrained {
+ grid-template-columns: repeat(
+ auto-fit,
+ minmax(min(100%, 280px), 1fr)
+ );
+}
+```
+
+### Common Layout Patterns
+
+**Sidebar + Content:**
+```css
+.layout-sidebar {
+ display: grid;
+ grid-template-columns: 1fr;
+ gap: var(--spacing-lg);
+}
+
+@media (min-width: 768px) {
+ .layout-sidebar {
+ grid-template-columns: 280px 1fr;
+ }
+}
+```
+
+**Holy Grail:**
+```css
+.layout-holy-grail {
+ display: grid;
+ grid-template-columns: 1fr;
+ grid-template-rows: auto 1fr auto;
+ min-height: 100vh;
+}
+
+@media (min-width: 1024px) {
+ .layout-holy-grail {
+ grid-template-columns: 200px 1fr 200px;
+ grid-template-rows: auto 1fr auto;
+ }
+
+ .layout-holy-grail header,
+ .layout-holy-grail footer {
+ grid-column: 1 / -1;
+ }
+}
+```
+
+---
+
+## Quick Reference
+
+### Viewport Units
+
+| Unit | Description |
+|------|-------------|
+| vw | 1% of viewport width |
+| vh | 1% of viewport height |
+| vmin | 1% of smaller dimension |
+| vmax | 1% of larger dimension |
+| dvh | Dynamic viewport height (accounts for mobile chrome) |
+| svh | Small viewport height |
+| lvh | Large viewport height |
+
+### Responsive Testing Checklist
+
+- [ ] 320px (small mobile)
+- [ ] 375px (iPhone SE/8)
+- [ ] 414px (iPhone Plus/Max)
+- [ ] 768px (iPad portrait)
+- [ ] 1024px (iPad landscape/laptop)
+- [ ] 1280px (desktop)
+- [ ] 1920px (large desktop)
+
+### Common Device Widths
+
+| Device | Width | Breakpoint |
+|--------|-------|------------|
+| iPhone SE | 375px | xs-sm |
+| iPhone 14 | 390px | sm |
+| iPhone 14 Pro Max | 430px | sm |
+| iPad Mini | 768px | lg |
+| iPad Pro 11" | 834px | lg |
+| MacBook Air 13" | 1280px | xl |
+| iMac 24" | 1920px | 2xl+ |
+
+---
+
+*See also: `token-generation.md` for breakpoint token details*
diff --git a/product-team/ui-design-system/references/token-generation.md b/product-team/ui-design-system/references/token-generation.md
new file mode 100644
index 0000000..0d50ac5
--- /dev/null
+++ b/product-team/ui-design-system/references/token-generation.md
@@ -0,0 +1,324 @@
+# Design Token Generation Guide
+
+Reference for color palette algorithms, typography scales, and WCAG accessibility checking.
+
+---
+
+## Table of Contents
+
+- [Color Palette Generation](#color-palette-generation)
+- [Typography Scale System](#typography-scale-system)
+- [Spacing Grid System](#spacing-grid-system)
+- [Accessibility Contrast](#accessibility-contrast)
+- [Export Formats](#export-formats)
+
+---
+
+## Color Palette Generation
+
+### HSV Color Space Algorithm
+
+The token generator uses HSV (Hue, Saturation, Value) color space for precise control.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ COLOR SCALE GENERATION │
+├─────────────────────────────────────────────────────────────┤
+│ Input: Brand Color (#0066CC) │
+│ ↓ │
+│ Convert: Hex → RGB → HSV │
+│ ↓ │
+│ For each step (50, 100, 200... 900): │
+│ • Adjust Value (brightness) │
+│ • Adjust Saturation │
+│ • Keep Hue constant │
+│ ↓ │
+│ Output: 10-step color scale │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Brightness Algorithm
+
+```python
+# For light shades (50-400): High fixed brightness
+if step < 500:
+ new_value = 0.95 # 95% brightness
+
+# For dark shades (500-900): Exponential decrease
+else:
+ new_value = base_value * (1 - (step - 500) / 500)
+ # At step 900: brightness ≈ base_value * 0.2
+```
+
+### Saturation Scaling
+
+```python
+# Saturation increases with step number
+# 50 = 30% of base saturation
+# 900 = 100% of base saturation
+new_saturation = base_saturation * (0.3 + 0.7 * (step / 900))
+```
+
+### Complementary Color Generation
+
+```
+Brand Color: #0066CC (H=210°, S=100%, V=80%)
+ ↓
+ Add 180° to Hue
+ ↓
+Secondary: #CC6600 (H=30°, S=100%, V=80%)
+```
+
+### Color Scale Output
+
+| Step | Use Case | Brightness | Saturation |
+|------|----------|------------|------------|
+| 50 | Subtle backgrounds | 95% (fixed) | 30% |
+| 100 | Light backgrounds | 95% (fixed) | 38% |
+| 200 | Hover states | 95% (fixed) | 46% |
+| 300 | Borders | 95% (fixed) | 54% |
+| 400 | Disabled states | 95% (fixed) | 62% |
+| 500 | Base color | Original | 70% |
+| 600 | Hover (dark) | Original × 0.8 | 78% |
+| 700 | Active states | Original × 0.6 | 86% |
+| 800 | Text | Original × 0.4 | 94% |
+| 900 | Headings | Original × 0.2 | 100% |
+
+---
+
+## Typography Scale System
+
+### Modular Scale (Major Third)
+
+The generator uses a **1.25x ratio** (major third) to create harmonious font sizes.
+
+```
+Base: 16px
+
+Scale calculation:
+ Smaller sizes: 16px ÷ 1.25^n
+ Larger sizes: 16px × 1.25^n
+
+Result:
+ xs: 10px (16 ÷ 1.25²)
+ sm: 13px (16 ÷ 1.25¹)
+ base: 16px
+ lg: 20px (16 × 1.25¹)
+ xl: 25px (16 × 1.25²)
+ 2xl: 31px (16 × 1.25³)
+ 3xl: 39px (16 × 1.25⁴)
+ 4xl: 49px (16 × 1.25⁵)
+ 5xl: 61px (16 × 1.25⁶)
+```
+
+### Type Scale Ratios
+
+| Ratio | Name | Multiplier | Character |
+|-------|------|------------|-----------|
+| 1.067 | Minor Second | Tight | Compact UIs |
+| 1.125 | Major Second | Subtle | App interfaces |
+| 1.200 | Minor Third | Moderate | General use |
+| **1.250** | **Major Third** | **Balanced** | **Default** |
+| 1.333 | Perfect Fourth | Pronounced | Marketing |
+| 1.414 | Augmented Fourth | Bold | Editorial |
+| 1.618 | Golden Ratio | Dramatic | Headlines |
+
+### Pre-composed Text Styles
+
+| Style | Size | Weight | Line Height | Letter Spacing |
+|-------|------|--------|-------------|----------------|
+| h1 | 48px | 700 | 1.2 | -0.02em |
+| h2 | 36px | 700 | 1.3 | -0.01em |
+| h3 | 28px | 600 | 1.4 | 0 |
+| h4 | 24px | 600 | 1.4 | 0 |
+| h5 | 20px | 600 | 1.5 | 0 |
+| h6 | 16px | 600 | 1.5 | 0.01em |
+| body | 16px | 400 | 1.5 | 0 |
+| small | 14px | 400 | 1.5 | 0 |
+| caption | 12px | 400 | 1.5 | 0.01em |
+
+---
+
+## Spacing Grid System
+
+### 8pt Grid Foundation
+
+All spacing values are multiples of 8px for visual consistency.
+
+```
+Base Unit: 8px
+
+Multipliers: 0, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8...
+
+Results:
+ 0: 0px
+ 1: 4px (0.5 × 8)
+ 2: 8px (1 × 8)
+ 3: 12px (1.5 × 8)
+ 4: 16px (2 × 8)
+ 5: 20px (2.5 × 8)
+ 6: 24px (3 × 8)
+ ...
+```
+
+### Semantic Spacing Mapping
+
+| Token | Numeric | Value | Use Case |
+|-------|---------|-------|----------|
+| xs | 1 | 4px | Inline icon margins |
+| sm | 2 | 8px | Button padding |
+| md | 4 | 16px | Card padding |
+| lg | 6 | 24px | Section spacing |
+| xl | 8 | 32px | Component gaps |
+| 2xl | 12 | 48px | Section margins |
+| 3xl | 16 | 64px | Page sections |
+
+### Why 8pt Grid?
+
+1. **Divisibility**: 8 divides evenly into common screen widths
+2. **Consistency**: Creates predictable vertical rhythm
+3. **Accessibility**: Touch targets naturally align to 48px (8 × 6)
+4. **Integration**: Most design tools default to 8px grids
+
+---
+
+## Accessibility Contrast
+
+### WCAG Contrast Requirements
+
+| Level | Normal Text | Large Text | Definition |
+|-------|-------------|------------|------------|
+| AA | 4.5:1 | 3:1 | Minimum requirement |
+| AAA | 7:1 | 4.5:1 | Enhanced accessibility |
+
+**Large text**: ≥18pt regular or ≥14pt bold
+
+### Contrast Ratio Formula
+
+```
+Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
+
+Where:
+ L1 = Relative luminance of lighter color
+ L2 = Relative luminance of darker color
+
+Relative Luminance:
+ L = 0.2126 × R + 0.7152 × G + 0.0722 × B
+ (Values linearized from sRGB)
+```
+
+### Color Step Contrast Guide
+
+| Background | Minimum Text Step | For AA |
+|------------|-------------------|--------|
+| 50 | 700+ | Large text at 600 |
+| 100 | 700+ | Large text at 600 |
+| 200 | 800+ | Large text at 700 |
+| 300 | 900 | - |
+| 500 (base) | White or 50 | - |
+| 700+ | White or 50-100 | - |
+
+### Semantic Colors Accessibility
+
+Generated semantic colors include contrast colors:
+
+```json
+{
+ "success": {
+ "base": "#10B981",
+ "light": "#34D399",
+ "dark": "#059669",
+ "contrast": "#FFFFFF" // For text on base
+ }
+}
+```
+
+---
+
+## Export Formats
+
+### JSON Format
+
+Best for: Design tool plugins, JavaScript/TypeScript projects, APIs
+
+```json
+{
+ "colors": {
+ "primary": {
+ "50": "#E6F2FF",
+ "500": "#0066CC",
+ "900": "#002855"
+ }
+ },
+ "typography": {
+ "fontSize": {
+ "base": "16px",
+ "lg": "20px"
+ }
+ }
+}
+```
+
+### CSS Custom Properties
+
+Best for: Web applications, CSS frameworks
+
+```css
+:root {
+ --colors-primary-50: #E6F2FF;
+ --colors-primary-500: #0066CC;
+ --colors-primary-900: #002855;
+ --typography-fontSize-base: 16px;
+ --typography-fontSize-lg: 20px;
+}
+```
+
+### SCSS Variables
+
+Best for: SCSS/SASS projects, component libraries
+
+```scss
+$colors-primary-50: #E6F2FF;
+$colors-primary-500: #0066CC;
+$colors-primary-900: #002855;
+$typography-fontSize-base: 16px;
+$typography-fontSize-lg: 20px;
+```
+
+### Format Selection Guide
+
+| Format | When to Use |
+|--------|-------------|
+| JSON | Figma plugins, Storybook, JS/TS, design tool APIs |
+| CSS | Plain CSS projects, CSS-in-JS (some), web apps |
+| SCSS | SASS pipelines, component libraries, theming |
+| Summary | Quick verification, debugging |
+
+---
+
+## Quick Reference
+
+### Generation Command
+
+```bash
+# Default (modern style, JSON output)
+python scripts/design_token_generator.py "#0066CC"
+
+# Classic style, CSS output
+python scripts/design_token_generator.py "#8B4513" classic css
+
+# Playful style, summary view
+python scripts/design_token_generator.py "#FF6B6B" playful summary
+```
+
+### Style Differences
+
+| Aspect | Modern | Classic | Playful |
+|--------|--------|---------|---------|
+| Fonts | Inter, Fira Code | Helvetica, Courier | Poppins, Source Code Pro |
+| Border Radius | 8px default | 4px default | 16px default |
+| Shadows | Layered, subtle | Single layer | Soft, pronounced |
+
+---
+
+*See also: `component-architecture.md` for component design patterns*
diff --git a/product-team/ui-design-system/scripts/design_token_generator.py b/product-team/ui-design-system/scripts/design_token_generator.py
index b671e86..119508c 100644
--- a/product-team/ui-design-system/scripts/design_token_generator.py
+++ b/product-team/ui-design-system/scripts/design_token_generator.py
@@ -1,7 +1,59 @@
#!/usr/bin/env python3
"""
Design Token Generator
-Creates consistent design system tokens for colors, typography, spacing, and more
+Creates consistent design system tokens for colors, typography, spacing, and more.
+
+Usage:
+ python design_token_generator.py [brand_color] [style] [format]
+
+ brand_color: Hex color (default: #0066CC)
+ style: modern | classic | playful (default: modern)
+ format: json | css | scss | summary (default: json)
+
+Examples:
+ python design_token_generator.py "#0066CC" modern json
+ python design_token_generator.py "#8B4513" classic css
+ python design_token_generator.py "#FF6B6B" playful summary
+
+Table of Contents:
+==================
+
+CLASS: DesignTokenGenerator
+ __init__() - Initialize base unit (8pt), type scale (1.25x)
+ generate_complete_system() - Main entry: generates all token categories
+ generate_color_palette() - Primary, secondary, neutral, semantic colors
+ generate_typography_system() - Font families, sizes, weights, line heights
+ generate_spacing_system() - 8pt grid-based spacing scale
+ generate_sizing_tokens() - Container and component sizing
+ generate_border_tokens() - Border radius and width values
+ generate_shadow_tokens() - Shadow definitions per style
+ generate_animation_tokens() - Durations, easing, keyframes
+ generate_breakpoints() - Responsive breakpoints (xs-2xl)
+ generate_z_index_scale() - Z-index layering system
+ export_tokens() - Export to JSON/CSS/SCSS
+
+PRIVATE METHODS:
+ _generate_color_scale() - Generate 10-step color scale (50-900)
+ _generate_neutral_scale() - Fixed neutral gray palette
+ _generate_type_scale() - Modular type scale using ratio
+ _generate_text_styles() - Pre-composed h1-h6, body, caption
+ _export_as_css() - CSS custom properties exporter
+ _hex_to_rgb() - Hex to RGB conversion
+ _rgb_to_hex() - RGB to Hex conversion
+ _adjust_hue() - HSV hue rotation utility
+
+FUNCTION: main() - CLI entry point with argument parsing
+
+Token Categories Generated:
+ - colors: primary, secondary, neutral, semantic, surface
+ - typography: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing
+ - spacing: 0-64 scale based on 8pt grid
+ - sizing: containers, buttons, inputs, icons
+ - borders: radius (per style), width
+ - shadows: none through 2xl, inner
+ - animation: duration, easing, keyframes
+ - breakpoints: xs, sm, md, lg, xl, 2xl
+ - z-index: hide through notification
"""
import json
@@ -61,9 +113,7 @@ class DesignTokenGenerator:
},
'warning': {
'base': '#F59E0B',
- 'light': '#FBB
-
-D24',
+ 'light': '#FBBD24',
'dark': '#D97706',
'contrast': '#FFFFFF'
},
diff --git a/product-team/ux-researcher-designer/SKILL.md b/product-team/ux-researcher-designer/SKILL.md
index 946f95c..fd4e237 100644
--- a/product-team/ux-researcher-designer/SKILL.md
+++ b/product-team/ux-researcher-designer/SKILL.md
@@ -5,26 +5,410 @@ description: UX research and design toolkit for Senior UX Designer/Researcher in
# UX Researcher & Designer
-Comprehensive toolkit for user-centered research and experience design.
+Generate user personas from research data, create journey maps, plan usability tests, and synthesize research findings into actionable design recommendations.
-## Core Capabilities
-- Data-driven persona generation
-- Customer journey mapping
-- Usability testing frameworks
-- Research synthesis and insights
-- Design validation methods
+---
-## Key Scripts
+## Table of Contents
+
+- [Trigger Terms](#trigger-terms)
+- [Workflows](#workflows)
+ - [Workflow 1: Generate User Persona](#workflow-1-generate-user-persona)
+ - [Workflow 2: Create Journey Map](#workflow-2-create-journey-map)
+ - [Workflow 3: Plan Usability Test](#workflow-3-plan-usability-test)
+ - [Workflow 4: Synthesize Research](#workflow-4-synthesize-research)
+- [Tool Reference](#tool-reference)
+- [Quick Reference Tables](#quick-reference-tables)
+- [Knowledge Base](#knowledge-base)
+
+---
+
+## Trigger Terms
+
+Use this skill when you need to:
+
+- "create user persona"
+- "generate persona from data"
+- "build customer journey map"
+- "map user journey"
+- "plan usability test"
+- "design usability study"
+- "analyze user research"
+- "synthesize interview findings"
+- "identify user pain points"
+- "define user archetypes"
+- "calculate research sample size"
+- "create empathy map"
+- "identify user needs"
+
+---
+
+## Workflows
+
+### Workflow 1: Generate User Persona
+
+**Situation:** You have user data (analytics, surveys, interviews) and need to create a research-backed persona.
+
+**Steps:**
+
+1. **Prepare user data**
+
+ Required format (JSON):
+ ```json
+ [
+ {
+ "user_id": "user_1",
+ "age": 32,
+ "usage_frequency": "daily",
+ "features_used": ["dashboard", "reports", "export"],
+ "primary_device": "desktop",
+ "usage_context": "work",
+ "tech_proficiency": 7,
+ "pain_points": ["slow loading", "confusing UI"]
+ }
+ ]
+ ```
+
+2. **Run persona generator**
+ ```bash
+ # Human-readable output
+ python scripts/persona_generator.py
+
+ # JSON output for integration
+ python scripts/persona_generator.py json
+ ```
+
+3. **Review generated components**
+
+ | Component | What to Check |
+ |-----------|---------------|
+ | Archetype | Does it match the data patterns? |
+ | Demographics | Are they derived from actual data? |
+ | Goals | Are they specific and actionable? |
+ | Frustrations | Do they include frequency counts? |
+ | Design implications | Can designers act on these? |
+
+4. **Validate persona**
+
+ - Show to 3-5 real users: "Does this sound like you?"
+ - Cross-check with support tickets
+ - Verify against analytics data
+
+5. **Reference:** See `references/persona-methodology.md` for validity criteria
+
+---
+
+### Workflow 2: Create Journey Map
+
+**Situation:** You need to visualize the end-to-end user experience for a specific goal.
+
+**Steps:**
+
+1. **Define scope**
+
+ | Element | Description |
+ |---------|-------------|
+ | Persona | Which user type |
+ | Goal | What they're trying to achieve |
+ | Start | Trigger that begins journey |
+ | End | Success criteria |
+ | Timeframe | Hours/days/weeks |
+
+2. **Gather journey data**
+
+ Sources:
+ - User interviews (ask "walk me through...")
+ - Session recordings
+ - Analytics (funnel, drop-offs)
+ - Support tickets
+
+3. **Map the stages**
+
+ Typical B2B SaaS stages:
+ ```
+ Awareness → Evaluation → Onboarding → Adoption → Advocacy
+ ```
+
+4. **Fill in layers for each stage**
+
+ ```
+ Stage: [Name]
+ ├── Actions: What does user do?
+ ├── Touchpoints: Where do they interact?
+ ├── Emotions: How do they feel? (1-5)
+ ├── Pain Points: What frustrates them?
+ └── Opportunities: Where can we improve?
+ ```
+
+5. **Identify opportunities**
+
+ Priority Score = Frequency × Severity × Solvability
+
+6. **Reference:** See `references/journey-mapping-guide.md` for templates
+
+---
+
+### Workflow 3: Plan Usability Test
+
+**Situation:** You need to validate a design with real users.
+
+**Steps:**
+
+1. **Define research questions**
+
+ Transform vague goals into testable questions:
+
+ | Vague | Testable |
+ |-------|----------|
+ | "Is it easy to use?" | "Can users complete checkout in <3 min?" |
+ | "Do users like it?" | "Will users choose Design A or B?" |
+ | "Does it make sense?" | "Can users find settings without hints?" |
+
+2. **Select method**
+
+ | Method | Participants | Duration | Best For |
+ |--------|--------------|----------|----------|
+ | Moderated remote | 5-8 | 45-60 min | Deep insights |
+ | Unmoderated remote | 10-20 | 15-20 min | Quick validation |
+ | Guerrilla | 3-5 | 5-10 min | Rapid feedback |
+
+3. **Design tasks**
+
+ Good task format:
+ ```
+ SCENARIO: "Imagine you're planning a trip to Paris..."
+ GOAL: "Book a hotel for 3 nights in your budget."
+ SUCCESS: "You see the confirmation page."
+ ```
+
+ Task progression: Warm-up → Core → Secondary → Edge case → Free exploration
+
+4. **Define success metrics**
+
+ | Metric | Target |
+ |--------|--------|
+ | Completion rate | >80% |
+ | Time on task | <2× expected |
+ | Error rate | <15% |
+ | Satisfaction | >4/5 |
+
+5. **Prepare moderator guide**
+
+ - Think-aloud instructions
+ - Non-leading prompts
+ - Post-task questions
+
+6. **Reference:** See `references/usability-testing-frameworks.md` for full guide
+
+---
+
+### Workflow 4: Synthesize Research
+
+**Situation:** You have raw research data (interviews, surveys, observations) and need actionable insights.
+
+**Steps:**
+
+1. **Code the data**
+
+ Tag each data point:
+ - `[GOAL]` - What they want to achieve
+ - `[PAIN]` - What frustrates them
+ - `[BEHAVIOR]` - What they actually do
+ - `[CONTEXT]` - When/where they use product
+ - `[QUOTE]` - Direct user words
+
+2. **Cluster similar patterns**
+
+ ```
+ User A: Uses daily, advanced features, shortcuts
+ User B: Uses daily, complex workflows, automation
+ User C: Uses weekly, basic needs, occasional
+
+ Cluster 1: A, B (Power Users)
+ Cluster 2: C (Casual User)
+ ```
+
+3. **Calculate segment sizes**
+
+ | Cluster | Users | % | Viability |
+ |---------|-------|---|-----------|
+ | Power Users | 18 | 36% | Primary persona |
+ | Business Users | 15 | 30% | Primary persona |
+ | Casual Users | 12 | 24% | Secondary persona |
+
+4. **Extract key findings**
+
+ For each theme:
+ - Finding statement
+ - Supporting evidence (quotes, data)
+ - Frequency (X/Y participants)
+ - Business impact
+ - Recommendation
+
+5. **Prioritize opportunities**
+
+ | Factor | Score 1-5 |
+ |--------|-----------|
+ | Frequency | How often does this occur? |
+ | Severity | How much does it hurt? |
+ | Breadth | How many users affected? |
+ | Solvability | Can we fix this? |
+
+6. **Reference:** See `references/persona-methodology.md` for analysis framework
+
+---
+
+## Tool Reference
### persona_generator.py
-Creates research-backed personas from user data and interviews.
-**Usage**: `python scripts/persona_generator.py [json]`
+Generates data-driven personas from user research data.
-**Features**:
-- Analyzes user behavior patterns
-- Identifies persona archetypes
-- Extracts psychographics
-- Generates scenarios
-- Provides design implications
-- Confidence scoring based on sample size
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| format | (none), json | (none) | Output format |
+
+**Sample Output:**
+
+```
+============================================================
+PERSONA: Alex the Power User
+============================================================
+
+📝 A daily user who primarily uses the product for work purposes
+
+Archetype: Power User
+Quote: "I need tools that can keep up with my workflow"
+
+👤 Demographics:
+ • Age Range: 25-34
+ • Location Type: Urban
+ • Tech Proficiency: Advanced
+
+🎯 Goals & Needs:
+ • Complete tasks efficiently
+ • Automate workflows
+ • Access advanced features
+
+😤 Frustrations:
+ • Slow loading times (14/20 users)
+ • No keyboard shortcuts
+ • Limited API access
+
+💡 Design Implications:
+ → Optimize for speed and efficiency
+ → Provide keyboard shortcuts and power features
+ → Expose API and automation capabilities
+
+📈 Data: Based on 45 users
+ Confidence: High
+```
+
+**Archetypes Generated:**
+
+| Archetype | Signals | Design Focus |
+|-----------|---------|--------------|
+| power_user | Daily use, 10+ features | Efficiency, customization |
+| casual_user | Weekly use, 3-5 features | Simplicity, guidance |
+| business_user | Work context, team use | Collaboration, reporting |
+| mobile_first | Mobile primary | Touch, offline, speed |
+
+**Output Components:**
+
+| Component | Description |
+|-----------|-------------|
+| demographics | Age range, location, occupation, tech level |
+| psychographics | Motivations, values, attitudes, lifestyle |
+| behaviors | Usage patterns, feature preferences |
+| needs_and_goals | Primary, secondary, functional, emotional |
+| frustrations | Pain points with evidence |
+| scenarios | Contextual usage stories |
+| design_implications | Actionable recommendations |
+| data_points | Sample size, confidence level |
+
+---
+
+## Quick Reference Tables
+
+### Research Method Selection
+
+| Question Type | Best Method | Sample Size |
+|---------------|-------------|-------------|
+| "What do users do?" | Analytics, observation | 100+ events |
+| "Why do they do it?" | Interviews | 8-15 users |
+| "How well can they do it?" | Usability test | 5-8 users |
+| "What do they prefer?" | Survey, A/B test | 50+ users |
+| "What do they feel?" | Diary study, interviews | 10-15 users |
+
+### Persona Confidence Levels
+
+| Sample Size | Confidence | Use Case |
+|-------------|------------|----------|
+| 5-10 users | Low | Exploratory |
+| 11-30 users | Medium | Directional |
+| 31+ users | High | Production |
+
+### Usability Issue Severity
+
+| Severity | Definition | Action |
+|----------|------------|--------|
+| 4 - Critical | Prevents task completion | Fix immediately |
+| 3 - Major | Significant difficulty | Fix before release |
+| 2 - Minor | Causes hesitation | Fix when possible |
+| 1 - Cosmetic | Noticed but not problematic | Low priority |
+
+### Interview Question Types
+
+| Type | Example | Use For |
+|------|---------|---------|
+| Context | "Walk me through your typical day" | Understanding environment |
+| Behavior | "Show me how you do X" | Observing actual actions |
+| Goals | "What are you trying to achieve?" | Uncovering motivations |
+| Pain | "What's the hardest part?" | Identifying frustrations |
+| Reflection | "What would you change?" | Generating ideas |
+
+---
+
+## Knowledge Base
+
+Detailed reference guides in `references/`:
+
+| File | Content |
+|------|---------|
+| `persona-methodology.md` | Validity criteria, data collection, analysis framework |
+| `journey-mapping-guide.md` | Mapping process, templates, opportunity identification |
+| `example-personas.md` | 3 complete persona examples with data |
+| `usability-testing-frameworks.md` | Test planning, task design, analysis |
+
+---
+
+## Validation Checklist
+
+### Persona Quality
+- [ ] Based on 20+ users (minimum)
+- [ ] At least 2 data sources (quant + qual)
+- [ ] Specific, actionable goals
+- [ ] Frustrations include frequency counts
+- [ ] Design implications are specific
+- [ ] Confidence level stated
+
+### Journey Map Quality
+- [ ] Scope clearly defined (persona, goal, timeframe)
+- [ ] Based on real user data, not assumptions
+- [ ] All layers filled (actions, touchpoints, emotions)
+- [ ] Pain points identified per stage
+- [ ] Opportunities prioritized
+
+### Usability Test Quality
+- [ ] Research questions are testable
+- [ ] Tasks are realistic scenarios, not instructions
+- [ ] 5+ participants per design
+- [ ] Success metrics defined
+- [ ] Findings include severity ratings
+
+### Research Synthesis Quality
+- [ ] Data coded consistently
+- [ ] Patterns based on 3+ data points
+- [ ] Findings include evidence
+- [ ] Recommendations are actionable
+- [ ] Priorities justified
diff --git a/product-team/ux-researcher-designer/references/example-personas.md b/product-team/ux-researcher-designer/references/example-personas.md
new file mode 100644
index 0000000..594c939
--- /dev/null
+++ b/product-team/ux-researcher-designer/references/example-personas.md
@@ -0,0 +1,411 @@
+# Example Personas
+
+Real output examples showing what good personas look like.
+
+---
+
+## Table of Contents
+
+- [Example 1: Power User Persona](#example-1-power-user-persona)
+- [Example 2: Business User Persona](#example-2-business-user-persona)
+- [Example 3: Casual User Persona](#example-3-casual-user-persona)
+- [JSON Output Format](#json-output-format)
+- [Quality Checklist](#quality-checklist)
+
+---
+
+## Example 1: Power User Persona
+
+### Script Output
+
+```
+============================================================
+PERSONA: Alex the Power User
+============================================================
+
+📝 A daily user who primarily uses the product for work purposes
+
+Archetype: Power User
+Quote: "I need tools that can keep up with my workflow"
+
+👤 Demographics:
+ • Age Range: 25-34
+ • Location Type: Urban
+ • Occupation Category: Software Engineer
+ • Education Level: Bachelor's degree
+ • Tech Proficiency: Advanced
+
+🧠 Psychographics:
+ Motivations: Efficiency, Control, Mastery
+ Values: Time-saving, Flexibility, Reliability
+ Lifestyle: Fast-paced, optimization-focused
+
+🎯 Goals & Needs:
+ • Complete tasks efficiently without repetitive work
+ • Automate recurring workflows
+ • Access advanced features and shortcuts
+
+😤 Frustrations:
+ • Slow loading times (mentioned by 14/20 users)
+ • No keyboard shortcuts for common actions
+ • Limited API access for automation
+
+📊 Behaviors:
+ • Frequently uses: Dashboard, Reports, Export, API
+ • Usage pattern: 5+ sessions per day
+ • Interaction style: Exploratory - uses many features
+
+💡 Design Implications:
+ → Optimize for speed and efficiency
+ → Provide keyboard shortcuts and power features
+ → Expose API and automation capabilities
+ → Allow UI customization
+
+📈 Data: Based on 45 users
+ Confidence: High
+ Method: Quantitative analysis + 12 qualitative interviews
+```
+
+### Data Behind This Persona
+
+**Quantitative Data (n=45):**
+- 78% use product daily
+- Average session: 23 minutes
+- Average features used: 12
+- 84% access via desktop
+- Support tickets: 0.2 per month (low)
+
+**Qualitative Insights (12 interviews):**
+
+| Theme | Frequency | Sample Quote |
+|-------|-----------|--------------|
+| Speed matters | 10/12 | "Every second counts when I'm in flow" |
+| Shortcuts wanted | 8/12 | "Why can't I Cmd+K to search?" |
+| Automation need | 9/12 | "I wrote a script to work around..." |
+| Customization | 7/12 | "Let me hide features I don't use" |
+
+---
+
+## Example 2: Business User Persona
+
+### Script Output
+
+```
+============================================================
+PERSONA: Taylor the Business Professional
+============================================================
+
+📝 A weekly user who primarily uses the product for team collaboration
+
+Archetype: Business User
+Quote: "I need to show clear value to my stakeholders"
+
+👤 Demographics:
+ • Age Range: 35-44
+ • Location Type: Urban/Suburban
+ • Occupation Category: Product Manager
+ • Education Level: MBA
+ • Tech Proficiency: Intermediate
+
+🧠 Psychographics:
+ Motivations: Team success, Visibility, Recognition
+ Values: Collaboration, Measurable outcomes, Professional growth
+ Lifestyle: Meeting-heavy, cross-functional work
+
+🎯 Goals & Needs:
+ • Improve team efficiency and coordination
+ • Generate reports for stakeholders
+ • Integrate with existing work tools (Slack, Jira)
+
+😤 Frustrations:
+ • No way to share views with team (11/18 users)
+ • Can't generate executive summaries
+ • No SSO - team has to manage passwords
+
+📊 Behaviors:
+ • Frequently uses: Sharing, Reports, Team Dashboard
+ • Usage pattern: 3-4 sessions per week
+ • Interaction style: Goal-oriented, feature-specific
+
+💡 Design Implications:
+ → Add collaboration and sharing features
+ → Build executive reporting and dashboards
+ → Integrate with enterprise tools (SSO, Slack)
+ → Provide permission and access controls
+
+📈 Data: Based on 38 users
+ Confidence: High
+ Method: Survey (n=200) + 18 interviews
+```
+
+### Data Behind This Persona
+
+**Survey Data (n=200):**
+- 19% of total user base fits this profile
+- Average company size: 50-500 employees
+- 72% need to share outputs with non-users
+- Top request: Team collaboration features
+
+**Interview Insights (18 interviews):**
+
+| Need | Frequency | Business Impact |
+|------|-----------|-----------------|
+| Reporting | 16/18 | "I spend 2hrs/week making slides" |
+| Team access | 14/18 | "Can't show my team what I see" |
+| Integration | 12/18 | "Copy-paste into Confluence..." |
+| SSO | 11/18 | "IT won't approve without SSO" |
+
+### Scenario: Quarterly Review Prep
+
+```
+Context: End of quarter, needs to present metrics to leadership
+Goal: Create compelling data story in 30 minutes
+Current Journey:
+ 1. Export raw data (works)
+ 2. Open Excel, make charts (manual)
+ 3. Copy to PowerPoint (manual)
+ 4. Share with team for feedback (via email)
+
+Pain Points:
+ • No built-in presentation view
+ • Charts don't match brand guidelines
+ • Can't collaborate on narrative
+
+Opportunity:
+ • One-click executive summary
+ • Brand-compliant templates
+ • In-app commenting on reports
+```
+
+---
+
+## Example 3: Casual User Persona
+
+### Script Output
+
+```
+============================================================
+PERSONA: Casey the Casual User
+============================================================
+
+📝 A monthly user who uses the product for occasional personal tasks
+
+Archetype: Casual User
+Quote: "I just want it to work without having to think about it"
+
+👤 Demographics:
+ • Age Range: 25-44
+ • Location Type: Mixed
+ • Occupation Category: Various
+ • Education Level: Bachelor's degree
+ • Tech Proficiency: Beginner-Intermediate
+
+🧠 Psychographics:
+ Motivations: Task completion, Simplicity
+ Values: Ease of use, Quick results
+ Lifestyle: Busy, product is means to end
+
+🎯 Goals & Needs:
+ • Complete specific task quickly
+ • Minimal learning curve
+ • Don't have to remember how it works between uses
+
+😤 Frustrations:
+ • Too many options, don't know where to start (18/25)
+ • Forgot how to do X since last time (15/25)
+ • Feels like it's designed for experts (12/25)
+
+📊 Behaviors:
+ • Frequently uses: 2-3 core features only
+ • Usage pattern: 1-2 sessions per month
+ • Interaction style: Focused - uses minimal features
+
+💡 Design Implications:
+ → Simplify onboarding and main navigation
+ → Provide contextual help and reminders
+ → Don't require memorization between sessions
+ → Progressive disclosure - hide advanced features
+
+📈 Data: Based on 52 users
+ Confidence: High
+ Method: Analytics analysis + 25 intercept interviews
+```
+
+### Data Behind This Persona
+
+**Analytics Data (n=1,200 casual segment):**
+- 65% of users are casual (< 1 session/week)
+- Average features used: 2.3
+- Return rate after 30 days: 34%
+- Session duration: 4.2 minutes
+
+**Intercept Interview Insights (25 quick interviews):**
+
+| Quote | Count | Implication |
+|-------|-------|-------------|
+| "Where's the thing I used last time?" | 18 | Need breadcrumbs/history |
+| "There's so much here" | 15 | Simplify main view |
+| "I only need to do X" | 22 | Surface common tasks |
+| "Is there a tutorial?" | 11 | Better help system |
+
+### Journey: Infrequent Task Completion
+
+```
+Stage 1: Return After Absence
+ Action: Opens app, doesn't recognize interface
+ Emotion: 😕 Confused
+ Thought: "This looks different, where do I start?"
+
+Stage 2: Feature Hunt
+ Action: Clicks around looking for needed feature
+ Emotion: 😕 Frustrated
+ Thought: "I know I did this before..."
+
+Stage 3: Discovery
+ Action: Finds feature (or gives up)
+ Emotion: 😐 Relief or 😠 Abandonment
+ Thought: "Finally!" or "I'll try something else"
+
+Stage 4: Task Completion
+ Action: Uses feature, accomplishes goal
+ Emotion: 🙂 Satisfied
+ Thought: "That worked, hope I remember next time"
+```
+
+---
+
+## JSON Output Format
+
+### persona_generator.py JSON Output
+
+```json
+{
+ "name": "Alex the Power User",
+ "archetype": "power_user",
+ "tagline": "A daily user who primarily uses the product for work purposes",
+ "demographics": {
+ "age_range": "25-34",
+ "location_type": "urban",
+ "occupation_category": "Software Engineer",
+ "education_level": "Bachelor's degree",
+ "tech_proficiency": "Advanced"
+ },
+ "psychographics": {
+ "motivations": ["Efficiency", "Control", "Mastery"],
+ "values": ["Time-saving", "Flexibility", "Reliability"],
+ "attitudes": ["Early adopter", "Optimization-focused"],
+ "lifestyle": "Fast-paced, tech-forward"
+ },
+ "behaviors": {
+ "usage_patterns": ["daily: 45 users", "weekly: 8 users"],
+ "feature_preferences": ["dashboard", "reports", "export", "api"],
+ "interaction_style": "Exploratory - uses many features",
+ "learning_preference": "Self-directed, documentation"
+ },
+ "needs_and_goals": {
+ "primary_goals": [
+ "Complete tasks efficiently",
+ "Automate workflows"
+ ],
+ "secondary_goals": [
+ "Customize workspace",
+ "Integrate with other tools"
+ ],
+ "functional_needs": [
+ "Speed and performance",
+ "Keyboard shortcuts",
+ "API access"
+ ],
+ "emotional_needs": [
+ "Feel in control",
+ "Feel productive",
+ "Feel like an expert"
+ ]
+ },
+ "frustrations": [
+ "Slow loading times",
+ "No keyboard shortcuts",
+ "Limited API access",
+ "Can't customize dashboard",
+ "No batch operations"
+ ],
+ "scenarios": [
+ {
+ "title": "Bulk Processing",
+ "context": "Monday morning, needs to process week's data",
+ "goal": "Complete batch operations quickly",
+ "steps": ["Import data", "Apply bulk actions", "Export results"],
+ "pain_points": ["No keyboard shortcuts", "Slow processing"]
+ }
+ ],
+ "quote": "I need tools that can keep up with my workflow",
+ "data_points": {
+ "sample_size": 45,
+ "confidence_level": "High",
+ "last_updated": "2024-01-15",
+ "validation_method": "Quantitative analysis + Qualitative interviews"
+ },
+ "design_implications": [
+ "Optimize for speed and efficiency",
+ "Provide keyboard shortcuts and power features",
+ "Expose API and automation capabilities",
+ "Allow UI customization",
+ "Support bulk operations"
+ ]
+}
+```
+
+### Using JSON Output
+
+```bash
+# Generate JSON for integration
+python scripts/persona_generator.py json > persona_power_user.json
+
+# Use with other tools
+cat persona_power_user.json | jq '.design_implications'
+```
+
+---
+
+## Quality Checklist
+
+### What Makes a Good Persona
+
+| Criterion | Bad Example | Good Example |
+|-----------|-------------|--------------|
+| **Specificity** | "Wants to be productive" | "Needs to process 50+ items daily" |
+| **Evidence** | "Users want simplicity" | "18/25 users said 'too many options'" |
+| **Actionable** | "Likes easy things" | "Hide advanced features by default" |
+| **Memorable** | Generic descriptions | Distinctive quote and archetype |
+| **Validated** | Team assumptions | User interviews + analytics |
+
+### Persona Quality Rubric
+
+| Element | Points | Criteria |
+|---------|--------|----------|
+| Data-backed demographics | /5 | From real user data |
+| Specific goals | /5 | Actionable, measurable |
+| Evidenced frustrations | /5 | With frequency counts |
+| Design implications | /5 | Directly usable by designers |
+| Authentic quote | /5 | From actual user |
+| Confidence stated | /5 | Sample size and method |
+
+**Score:**
+- 25-30: Production-ready persona
+- 18-24: Needs refinement
+- Below 18: Requires more research
+
+### Red Flags in Persona Output
+
+| Red Flag | What It Means |
+|----------|---------------|
+| No sample size | Ungrounded assumptions |
+| Generic frustrations | Didn't do user research |
+| All positive | Missing real pain points |
+| No quotes | No qualitative research |
+| Contradicting behaviors | Forced archetype |
+| "Everyone" language | Too broad to be useful |
+
+---
+
+*See also: `persona-methodology.md` for creation process*
diff --git a/product-team/ux-researcher-designer/references/journey-mapping-guide.md b/product-team/ux-researcher-designer/references/journey-mapping-guide.md
new file mode 100644
index 0000000..d415156
--- /dev/null
+++ b/product-team/ux-researcher-designer/references/journey-mapping-guide.md
@@ -0,0 +1,497 @@
+# Journey Mapping Guide
+
+Step-by-step reference for creating user journey maps that drive design decisions.
+
+---
+
+## Table of Contents
+
+- [Journey Map Fundamentals](#journey-map-fundamentals)
+- [Mapping Process](#mapping-process)
+- [Journey Stages](#journey-stages)
+- [Touchpoint Analysis](#touchpoint-analysis)
+- [Emotion Mapping](#emotion-mapping)
+- [Opportunity Identification](#opportunity-identification)
+- [Templates](#templates)
+
+---
+
+## Journey Map Fundamentals
+
+### What Is a Journey Map?
+
+A journey map visualizes the end-to-end experience a user has while trying to accomplish a goal with your product or service.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ JOURNEY MAP STRUCTURE │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ STAGES: Awareness → Consideration → Acquisition → │
+│ Onboarding → Regular Use → Advocacy │
+│ │
+│ LAYERS: ┌─────────────────────────────────────────┐ │
+│ │ Actions: What user does │ │
+│ ├─────────────────────────────────────────┤ │
+│ │ Touchpoints: Where interaction happens │ │
+│ ├─────────────────────────────────────────┤ │
+│ │ Emotions: How user feels │ │
+│ ├─────────────────────────────────────────┤ │
+│ │ Pain Points: What frustrates │ │
+│ ├─────────────────────────────────────────┤ │
+│ │ Opportunities: Where to improve │ │
+│ └─────────────────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Journey Map Types
+
+| Type | Focus | Best For |
+|------|-------|----------|
+| Current State | How things are today | Identifying pain points |
+| Future State | Ideal experience | Design vision |
+| Day-in-the-Life | Beyond your product | Context understanding |
+| Service Blueprint | Backend processes | Operations alignment |
+
+### When to Create Journey Maps
+
+| Scenario | Map Type | Outcome |
+|----------|----------|---------|
+| New product | Future state | Design direction |
+| Redesign | Current + Future | Gap analysis |
+| Churn investigation | Current state | Pain point diagnosis |
+| Cross-team alignment | Service blueprint | Process optimization |
+
+---
+
+## Mapping Process
+
+### Step 1: Define Scope
+
+**Questions to Answer:**
+- Which persona is this journey for?
+- What goal are they trying to achieve?
+- Where does the journey start and end?
+- What timeframe does it cover?
+
+**Scope Template:**
+```
+Persona: [Name from persona library]
+Goal: [Specific outcome they want]
+Start: [Trigger that begins journey]
+End: [Success criteria or exit point]
+Timeframe: [Hours/Days/Weeks]
+```
+
+**Example:**
+```
+Persona: Alex the Power User
+Goal: Set up automated weekly reports
+Start: Realizes manual reporting is unsustainable
+End: First automated report runs successfully
+Timeframe: 1-2 days
+```
+
+### Step 2: Gather Data
+
+**Data Sources for Journey Mapping:**
+
+| Source | Insights Gained |
+|--------|-----------------|
+| User interviews | Actions, emotions, quotes |
+| Session recordings | Actual behavior patterns |
+| Support tickets | Common pain points |
+| Analytics | Drop-off points, time spent |
+| Surveys | Satisfaction at stages |
+
+**Interview Questions for Journey Mapping:**
+
+1. "Walk me through how you first discovered [product]"
+2. "What made you decide to try it?"
+3. "Describe your first day using it"
+4. "What was the hardest part?"
+5. "When did you feel confident using it?"
+6. "What would you change about that experience?"
+
+### Step 3: Map the Stages
+
+**Identify Natural Breakpoints:**
+
+Look for moments where:
+- User's mindset changes
+- Channels shift (web → app → email)
+- Time passes (hours, days)
+- Goals evolve
+
+**Stage Validation:**
+
+Each stage should have:
+- Clear entry criteria
+- Distinct user actions
+- Measurable outcomes
+- Exit to next stage
+
+### Step 4: Fill in Layers
+
+For each stage, document:
+
+1. **Actions**: What does the user do?
+2. **Touchpoints**: Where do they interact?
+3. **Thoughts**: What are they thinking?
+4. **Emotions**: How do they feel?
+5. **Pain Points**: What's frustrating?
+6. **Opportunities**: Where can we improve?
+
+### Step 5: Validate and Iterate
+
+**Validation Methods:**
+
+| Method | Effort | Confidence |
+|--------|--------|------------|
+| Team review | Low | Medium |
+| User walkthrough | Medium | High |
+| Data correlation | Medium | High |
+| A/B test interventions | High | Very High |
+
+---
+
+## Journey Stages
+
+### Common B2B SaaS Stages
+
+```
+┌────────────┬────────────┬────────────┬────────────┬────────────┐
+│ AWARENESS │ EVALUATION │ ONBOARDING │ ADOPTION │ ADVOCACY │
+├────────────┼────────────┼────────────┼────────────┼────────────┤
+│ Discovers │ Compares │ Signs up │ Regular │ Recommends │
+│ problem │ solutions │ Sets up │ usage │ to others │
+│ exists │ │ First win │ Integrates │ │
+└────────────┴────────────┴────────────┴────────────┴────────────┘
+```
+
+### Stage Detail Template
+
+**Stage: Onboarding**
+
+| Element | Description |
+|---------|-------------|
+| Goal | Complete setup, achieve first success |
+| Duration | 1-7 days |
+| Entry | User creates account |
+| Exit | First meaningful action completed |
+| Success Metric | Activation rate |
+
+**Substages:**
+1. Account creation
+2. Profile setup
+3. First feature use
+4. Integration (if applicable)
+5. First value moment
+
+### B2C vs. B2B Stages
+
+| B2C Stages | B2B Stages |
+|------------|------------|
+| Discover | Awareness |
+| Browse | Evaluation |
+| Purchase | Procurement |
+| Use | Implementation |
+| Return/Loyalty | Renewal |
+
+---
+
+## Touchpoint Analysis
+
+### Touchpoint Categories
+
+| Category | Examples | Owner |
+|----------|----------|-------|
+| Marketing | Ads, content, social | Marketing |
+| Sales | Demos, calls, proposals | Sales |
+| Product | App, features, UI | Product |
+| Support | Help center, chat, tickets | Support |
+| Transactional | Emails, notifications | Varies |
+
+### Touchpoint Mapping Template
+
+```
+Stage: [Name]
+Touchpoint: [Where interaction happens]
+Channel: [Web/Mobile/Email/Phone/In-person]
+Action: [What user does]
+Owner: [Team responsible]
+Current Experience: [1-5 rating]
+Improvement Priority: [High/Medium/Low]
+```
+
+### Cross-Channel Consistency
+
+**Check for:**
+- Information consistency across channels
+- Seamless handoffs (web → mobile)
+- Context preservation (user doesn't repeat info)
+- Brand voice alignment
+
+**Red Flags:**
+- User has to re-enter information
+- Different answers from different channels
+- Can't continue task on different device
+- Inconsistent terminology
+
+---
+
+## Emotion Mapping
+
+### Emotion Scale
+
+```
+ POSITIVE
+ │
+ Delighted ────┤──── 😄 5
+ Pleased ────┤──── 🙂 4
+ Neutral ────┤──── 😐 3
+ Frustrated ────┤──── 😕 2
+ Angry ────┤──── 😠 1
+ │
+ NEGATIVE
+```
+
+### Emotional Triggers
+
+| Trigger | Positive Emotion | Negative Emotion |
+|---------|------------------|------------------|
+| Speed | Delight | Frustration |
+| Clarity | Confidence | Confusion |
+| Control | Empowerment | Helplessness |
+| Progress | Satisfaction | Anxiety |
+| Recognition | Validation | Neglect |
+
+### Emotion Data Sources
+
+**Direct Signals:**
+- Interview quotes: "I felt so relieved when..."
+- Survey scores: NPS, CSAT, CES
+- Support sentiment: Angry vs. grateful tickets
+
+**Inferred Signals:**
+- Rage clicks (frustration)
+- Quick completion (satisfaction)
+- Abandonment (frustration or confusion)
+- Return visits (interest or necessity)
+
+### Emotion Curve Patterns
+
+**The Valley of Death:**
+```
+😄 ─┐
+ │ ╱
+ │ ╱
+😐 ─│───╱────────
+ │╲ ╱
+ │ ╳ ← Critical drop-off point
+😠 ─│╱ ╲─────────
+ │
+ Onboarding First Use Regular
+```
+
+**The Aha Moment:**
+```
+😄 ─┐ ╱──
+ │ ╱
+ │ ╱
+😐 ─│──────╱────── ← Before: neutral
+ │ ↑
+😠 ─│ Aha!
+ │
+ Stage 1 Stage 2 Stage 3
+```
+
+---
+
+## Opportunity Identification
+
+### Pain Point Prioritization
+
+| Factor | Score (1-5) |
+|--------|-------------|
+| Frequency | How often does this occur? |
+| Severity | How much does it hurt? |
+| Breadth | How many users affected? |
+| Solvability | Can we fix this? |
+
+**Priority Score = (Frequency + Severity + Breadth) × Solvability**
+
+### Opportunity Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| Friction Reduction | Remove obstacles | Fewer form fields |
+| Moment of Delight | Exceed expectations | Personalized welcome |
+| Channel Addition | New touchpoint | Mobile app for on-the-go |
+| Proactive Support | Anticipate needs | Tutorial at right moment |
+| Personalization | Tailored experience | Role-based onboarding |
+
+### Opportunity Canvas
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ OPPORTUNITY: [Name] │
+├─────────────────────────────────────────────────────────────┤
+│ Stage: [Where in journey] │
+│ Current Pain: [What's broken] │
+│ Desired Outcome: [What should happen] │
+│ Proposed Solution: [How to fix] │
+│ Success Metric: [How to measure] │
+│ Effort: [High/Medium/Low] │
+│ Impact: [High/Medium/Low] │
+│ Priority: [Calculated] │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Quick Wins vs. Strategic Bets
+
+| Criteria | Quick Win | Strategic Bet |
+|----------|-----------|---------------|
+| Effort | Low | High |
+| Impact | Medium | High |
+| Timeline | Weeks | Quarters |
+| Risk | Low | Medium-High |
+| Requires | Small team | Cross-functional |
+
+---
+
+## Templates
+
+### Basic Journey Map Template
+
+```
+PERSONA: _______________
+GOAL: _______________
+
+┌──────────┬──────────┬──────────┬──────────┬──────────┐
+│ STAGE 1 │ STAGE 2 │ STAGE 3 │ STAGE 4 │ STAGE 5 │
+├──────────┼──────────┼──────────┼──────────┼──────────┤
+│ Actions │ │ │ │ │
+│ │ │ │ │ │
+├──────────┼──────────┼──────────┼──────────┼──────────┤
+│ Touch- │ │ │ │ │
+│ points │ │ │ │ │
+├──────────┼──────────┼──────────┼──────────┼──────────┤
+│ Emotions │ │ │ │ │
+│ (1-5) │ │ │ │ │
+├──────────┼──────────┼──────────┼──────────┼──────────┤
+│ Pain │ │ │ │ │
+│ Points │ │ │ │ │
+├──────────┼──────────┼──────────┼──────────┼──────────┤
+│ Opport- │ │ │ │ │
+│ unities │ │ │ │ │
+└──────────┴──────────┴──────────┴──────────┴──────────┘
+```
+
+### Detailed Stage Template
+
+```
+STAGE: _______________
+DURATION: _______________
+ENTRY CRITERIA: _______________
+EXIT CRITERIA: _______________
+
+USER ACTIONS:
+1. _______________
+2. _______________
+3. _______________
+
+TOUCHPOINTS:
+• Channel: _____ | Owner: _____
+• Channel: _____ | Owner: _____
+
+THOUGHTS:
+"_______________"
+"_______________"
+
+EMOTIONAL STATE: [1-5] ___
+
+PAIN POINTS:
+• _______________
+• _______________
+
+OPPORTUNITIES:
+• _______________
+• _______________
+
+METRICS:
+• Completion rate: ___%
+• Time spent: ___
+• Drop-off: ___%
+```
+
+### Service Blueprint Extension
+
+Add backstage layers:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ FRONTSTAGE (User sees) │
+├─────────────────────────────────────────────────────────────┤
+│ User actions, touchpoints, emotions │
+├─────────────────────────────────────────────────────────────┤
+│ LINE OF VISIBILITY │
+├─────────────────────────────────────────────────────────────┤
+│ BACKSTAGE (User doesn't see) │
+├─────────────────────────────────────────────────────────────┤
+│ • Employee actions │
+│ • Systems/tools used │
+│ • Data flows │
+├─────────────────────────────────────────────────────────────┤
+│ SUPPORT PROCESSES │
+├─────────────────────────────────────────────────────────────┤
+│ • Backend systems │
+│ • Third-party integrations │
+│ • Policies/procedures │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Reference
+
+### Journey Mapping Checklist
+
+**Preparation:**
+- [ ] Persona selected
+- [ ] Goal defined
+- [ ] Scope bounded
+- [ ] Data gathered (interviews, analytics)
+
+**Mapping:**
+- [ ] Stages identified
+- [ ] Actions documented
+- [ ] Touchpoints mapped
+- [ ] Emotions captured
+- [ ] Pain points identified
+
+**Analysis:**
+- [ ] Opportunities prioritized
+- [ ] Quick wins identified
+- [ ] Strategic bets proposed
+- [ ] Metrics defined
+
+**Validation:**
+- [ ] Team reviewed
+- [ ] User validated
+- [ ] Data correlated
+
+### Common Mistakes
+
+| Mistake | Impact | Fix |
+|---------|--------|-----|
+| Too many stages | Overwhelming | Limit to 5-7 |
+| No data | Assumptions | Interview users |
+| Single session | Bias | Multiple sources |
+| No emotions | Misses human element | Add feeling layer |
+| No follow-through | Wasted effort | Create action plan |
+
+---
+
+*See also: `persona-methodology.md` for persona creation*
diff --git a/product-team/ux-researcher-designer/references/persona-methodology.md b/product-team/ux-researcher-designer/references/persona-methodology.md
new file mode 100644
index 0000000..7befd2a
--- /dev/null
+++ b/product-team/ux-researcher-designer/references/persona-methodology.md
@@ -0,0 +1,387 @@
+# Persona Methodology Guide
+
+Reference for creating research-backed, data-driven user personas.
+
+---
+
+## Table of Contents
+
+- [What Makes a Valid Persona](#what-makes-a-valid-persona)
+- [Data Collection Methods](#data-collection-methods)
+- [Analysis Framework](#analysis-framework)
+- [Persona Components](#persona-components)
+- [Validation Criteria](#validation-criteria)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## What Makes a Valid Persona
+
+### Research-Backed vs. Assumption-Based
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ PERSONA VALIDITY SPECTRUM │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ ASSUMPTION-BASED HYBRID RESEARCH-BACKED │
+│ │───────────────────────────────────────────────────────│ │
+│ ❌ Invalid ⚠️ Limited ✅ Valid │
+│ │
+│ • "Our users are..." • Some interviews • 20+ users │
+│ • No data • 5-10 data points • Quant + Qual │
+│ • Team opinions • Partial patterns • Validated │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Minimum Viability Requirements
+
+| Requirement | Threshold | Confidence Level |
+|-------------|-----------|------------------|
+| Sample size | 5 users | Low (exploratory) |
+| Sample size | 20 users | Medium (directional) |
+| Sample size | 50+ users | High (reliable) |
+| Data types | 2+ sources | Required |
+| Interview depth | 30+ min | Recommended |
+| Behavioral data | 1 week+ | Recommended |
+
+### The Persona Validity Test
+
+A valid persona must pass these checks:
+
+1. **Grounded in Data**
+ - Can you point to specific user quotes?
+ - Can you show behavioral data supporting claims?
+ - Are demographics from actual user profiles?
+
+2. **Represents a Segment**
+ - Does this persona represent 15%+ of your user base?
+ - Are there other users who fit this pattern?
+ - Is it a real cluster, not an outlier?
+
+3. **Actionable for Design**
+ - Can designers make decisions from this persona?
+ - Does it reveal unmet needs?
+ - Does it clarify feature priorities?
+
+---
+
+## Data Collection Methods
+
+### Quantitative Sources
+
+| Source | Data Type | Use For |
+|--------|-----------|---------|
+| Analytics | Behavior | Usage patterns, feature adoption |
+| Surveys | Demographics, preferences | Segmentation, satisfaction |
+| Support tickets | Pain points | Frustration patterns |
+| Product logs | Actions | Feature usage, workflows |
+| CRM data | Profile | Job roles, company size |
+
+### Qualitative Sources
+
+| Source | Data Type | Use For |
+|--------|-----------|---------|
+| User interviews | Motivations, goals | Deep understanding |
+| Contextual inquiry | Environment | Real-world context |
+| Diary studies | Longitudinal | Behavior over time |
+| Usability tests | Pain points | Specific frustrations |
+| Customer calls | Quotes | Authentic voice |
+
+### Data Collection Matrix
+
+```
+ QUICK DEEP
+ (1-2 weeks) (4+ weeks)
+ │ │
+ ┌─────────┼──────────────────┼─────────┐
+ QUANT │ Survey │ │ Product │
+ │ + CRM │ │ Logs + │
+ │ │ │ A/B │
+ ├─────────┼──────────────────┼─────────┤
+ QUAL │ 5 │ │ 15+ │
+ │ Quick │ │ Deep │
+ │ Calls │ │ Inter- │
+ │ │ │ views │
+ └─────────┴──────────────────┴─────────┘
+```
+
+### Interview Protocol
+
+**Pre-Interview:**
+- Review user's analytics data
+- Note usage patterns to explore
+- Prepare open-ended questions
+
+**Interview Structure (45-60 min):**
+
+1. **Context (10 min)**
+ - "Walk me through your typical day"
+ - "When do you use [product]?"
+ - "What were you doing before you found us?"
+
+2. **Behaviors (15 min)**
+ - "Show me how you use [feature]"
+ - "What do you do when [scenario]?"
+ - "What's your workaround for [pain point]?"
+
+3. **Goals & Frustrations (15 min)**
+ - "What are you ultimately trying to achieve?"
+ - "What's the hardest part about [task]?"
+ - "If you had a magic wand, what would you change?"
+
+4. **Reflection (10 min)**
+ - "What would make you recommend us?"
+ - "What almost made you quit?"
+ - "What's missing that you need?"
+
+---
+
+## Analysis Framework
+
+### Pattern Identification
+
+**Step 1: Code Data Points**
+
+Tag each insight with:
+- `[GOAL]` - What they want to achieve
+- `[PAIN]` - What frustrates them
+- `[BEHAVIOR]` - What they actually do
+- `[CONTEXT]` - When/where they use product
+- `[QUOTE]` - Direct user words
+
+**Step 2: Cluster Similar Patterns**
+
+```
+User A: Uses daily, advanced features, keyboard shortcuts
+User B: Uses daily, complex workflows, automation
+User C: Uses weekly, basic needs, occasional
+User D: Uses daily, power features, API access
+
+Cluster 1: A, B, D (Power Users - daily, advanced)
+Cluster 2: C (Casual User - weekly, basic)
+```
+
+**Step 3: Calculate Cluster Size**
+
+| Cluster | Users | % of Sample | Viability |
+|---------|-------|-------------|-----------|
+| Power Users | 18 | 36% | Primary persona |
+| Business Users | 15 | 30% | Primary persona |
+| Casual Users | 12 | 24% | Secondary persona |
+| Mobile-First | 5 | 10% | Consider merging |
+
+### Archetype Classification
+
+| Archetype | Identifying Signals | Design Focus |
+|-----------|--------------------| -------------|
+| Power User | Daily use, 10+ features, shortcuts | Efficiency, customization |
+| Casual User | Weekly use, 3-5 features, simple | Simplicity, guidance |
+| Business User | Work context, team features, ROI | Collaboration, reporting |
+| Mobile-First | Mobile primary, quick actions | Touch, offline, speed |
+
+### Confidence Scoring
+
+Calculate confidence based on data quality:
+
+```
+Confidence = (Sample Size Score + Data Quality Score + Consistency Score) / 3
+
+Sample Size Score:
+ 5-10 users = 1 (Low)
+ 11-30 users = 2 (Medium)
+ 31+ users = 3 (High)
+
+Data Quality Score:
+ Survey only = 1 (Low)
+ Survey + Analytics = 2 (Medium)
+ Quant + Qual + Logs = 3 (High)
+
+Consistency Score:
+ Contradicting data = 1 (Low)
+ Some alignment = 2 (Medium)
+ Strong alignment = 3 (High)
+```
+
+---
+
+## Persona Components
+
+### Required Elements
+
+| Component | Description | Source |
+|-----------|-------------|--------|
+| Name & Photo | Memorable identifier | Stock photo, AI-generated |
+| Tagline | One-line summary | Synthesized from data |
+| Quote | Authentic voice | Direct from interviews |
+| Demographics | Age, role, location | CRM, surveys |
+| Goals | What they want | Interviews |
+| Frustrations | Pain points | Interviews, support |
+| Behaviors | How they act | Analytics, observation |
+| Scenarios | Usage contexts | Interviews, logs |
+
+### Optional Enhancements
+
+| Component | When to Include |
+|-----------|-----------------|
+| Day-in-the-life | Complex workflows |
+| Empathy map | Design workshops |
+| Technology stack | B2B products |
+| Influences | Consumer products |
+| Brands they love | Marketing-heavy |
+
+### Component Depth Guide
+
+**Demographics (Keep Brief):**
+```
+❌ Too detailed:
+ Age: 34, Lives: Seattle, Education: MBA from Stanford
+
+✅ Right level:
+ Age: 30-40, Urban professional, Graduate degree
+```
+
+**Goals (Be Specific):**
+```
+❌ Too vague:
+ "Wants to be productive"
+
+✅ Actionable:
+ "Needs to process 50+ items daily without repetitive tasks"
+```
+
+**Frustrations (Include Evidence):**
+```
+❌ Generic:
+ "Finds the interface confusing"
+
+✅ With evidence:
+ "Can't find export function (mentioned by 8/12 users)"
+```
+
+---
+
+## Validation Criteria
+
+### Internal Validation
+
+**Team Check:**
+- [ ] Does sales recognize this user type?
+- [ ] Does support see these pain points?
+- [ ] Does product know these workflows?
+
+**Data Check:**
+- [ ] Can we quantify this segment's size?
+- [ ] Do behaviors match analytics?
+- [ ] Are quotes from real users?
+
+### External Validation
+
+**User Validation (recommended):**
+- Show persona to 3-5 users from segment
+- Ask: "Does this sound like you?"
+- Iterate based on feedback
+
+**A/B Design Test:**
+- Design for persona A vs. persona B
+- Test with actual users
+- Measure if persona-driven design wins
+
+### Red Flags
+
+Watch for these persona validity problems:
+
+| Red Flag | What It Means | Fix |
+|----------|---------------|-----|
+| "Everyone" persona | Too broad to be useful | Split into segments |
+| Contradicting data | Forcing a narrative | Re-analyze clusters |
+| No frustrations | Sanitized or incomplete | Dig deeper in interviews |
+| Assumptions labeled as data | No real research | Conduct actual research |
+| Single data source | Fragile foundation | Add another data type |
+
+---
+
+## Anti-Patterns
+
+### 1. The Elastic Persona
+
+**Problem:** Persona stretches to include everyone
+
+```
+❌ "Sarah is 25-55, uses mobile and desktop, wants simplicity
+ but also advanced features, works alone and in teams..."
+```
+
+**Fix:** Create separate personas for distinct segments
+
+### 2. The Demographic Persona
+
+**Problem:** All demographics, no psychographics
+
+```
+❌ "John is 35, male, $80k income, urban, MBA..."
+ (Nothing about goals, frustrations, behaviors)
+```
+
+**Fix:** Lead with goals and frustrations, add minimal demographics
+
+### 3. The Ideal User Persona
+
+**Problem:** Describes who you want, not who you have
+
+```
+❌ "Emma is a passionate advocate who tells everyone
+ about our product and uses every feature daily..."
+```
+
+**Fix:** Base on real user data, include realistic limitations
+
+### 4. The Committee Persona
+
+**Problem:** Each stakeholder added their opinions
+
+```
+❌ CEO added "enterprise-focused"
+ Sales added "loves demos"
+ Support added "never calls support"
+```
+
+**Fix:** Single owner, data-driven only
+
+### 5. The Stale Persona
+
+**Problem:** Created once, never updated
+
+```
+❌ "Last updated: 2019"
+ Product has changed completely since then
+```
+
+**Fix:** Review quarterly, update with new data
+
+---
+
+## Quick Reference
+
+### Persona Creation Checklist
+
+- [ ] Minimum 20 users in data set
+- [ ] At least 2 data sources (quant + qual)
+- [ ] Clear segment boundaries
+- [ ] Actionable for design decisions
+- [ ] Validated with team and users
+- [ ] Documented data sources
+- [ ] Confidence level stated
+
+### Time Investment Guide
+
+| Persona Type | Time | Team | Output |
+|--------------|------|------|--------|
+| Quick & Dirty | 1 week | 1 | Directional |
+| Standard | 2-4 weeks | 2 | Production |
+| Comprehensive | 6-8 weeks | 3+ | Strategic |
+
+---
+
+*See also: `example-personas.md` for output examples*
diff --git a/product-team/ux-researcher-designer/references/usability-testing-frameworks.md b/product-team/ux-researcher-designer/references/usability-testing-frameworks.md
new file mode 100644
index 0000000..8b469fa
--- /dev/null
+++ b/product-team/ux-researcher-designer/references/usability-testing-frameworks.md
@@ -0,0 +1,412 @@
+# Usability Testing Frameworks
+
+Reference for planning and conducting usability tests that produce actionable insights.
+
+---
+
+## Table of Contents
+
+- [Testing Methods Overview](#testing-methods-overview)
+- [Test Planning](#test-planning)
+- [Task Design](#task-design)
+- [Moderation Techniques](#moderation-techniques)
+- [Analysis Framework](#analysis-framework)
+- [Reporting Template](#reporting-template)
+
+---
+
+## Testing Methods Overview
+
+### Method Selection Matrix
+
+| Method | When to Use | Participants | Time | Output |
+|--------|-------------|--------------|------|--------|
+| Moderated remote | Deep insights, complex flows | 5-8 | 45-60 min | Rich qualitative |
+| Unmoderated remote | Quick validation, simple tasks | 10-20 | 15-20 min | Quantitative + video |
+| In-person | Physical products, context matters | 5-10 | 60-90 min | Very rich qualitative |
+| Guerrilla | Quick feedback, public spaces | 3-5 | 5-10 min | Rapid insights |
+| A/B testing | Comparing two designs | 100+ | Varies | Statistical data |
+
+### Participant Count Guidelines
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ FINDING USABILITY ISSUES │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ % Issues Found │
+│ 100% ┤ ●────●────● │
+│ 90% ┤ ●───── │
+│ 80% ┤ ●───── │
+│ 75% ┤ ●──── ← 5 users: 75-80% │
+│ 50% ┤ ●──── │
+│ 25% ┤ ●── │
+│ 0% ┼────┬────┬────┬────┬────┬──── │
+│ 1 2 3 4 5 6+ Users │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Nielsen's Rule:** 5 users find ~75-80% of usability issues
+
+| Goal | Participants | Reasoning |
+|------|--------------|-----------|
+| Find major issues | 5 | 80% coverage, diminishing returns |
+| Validate fix | 3 | Confirm specific issue resolved |
+| Compare designs | 8-10 per design | Need comparison data |
+| Quantitative metrics | 20+ | Statistical significance |
+
+---
+
+## Test Planning
+
+### Research Questions
+
+Transform vague goals into testable questions:
+
+| Vague Goal | Testable Question |
+|------------|-------------------|
+| "Is it easy to use?" | "Can users complete checkout in under 3 minutes?" |
+| "Do users like it?" | "Will users choose Design A or B for this task?" |
+| "Does it make sense?" | "Can users find the settings without hints?" |
+
+### Test Plan Template
+
+```
+PROJECT: _______________
+DATE: _______________
+RESEARCHER: _______________
+
+RESEARCH QUESTIONS:
+1. _______________
+2. _______________
+3. _______________
+
+PARTICIPANTS:
+• Target: [Persona or user type]
+• Count: [Number]
+• Recruitment: [Source]
+• Incentive: [Amount/type]
+
+METHOD:
+• Type: [Moderated/Unmoderated/Remote/In-person]
+• Duration: [Minutes per session]
+• Environment: [Tool/Location]
+
+TASKS:
+1. [Task description + success criteria]
+2. [Task description + success criteria]
+3. [Task description + success criteria]
+
+METRICS:
+• Completion rate (target: __%)
+• Time on task (target: __ min)
+• Error rate (target: __%)
+• Satisfaction (target: __/5)
+
+SCHEDULE:
+• Pilot: [Date]
+• Sessions: [Date range]
+• Analysis: [Date]
+• Report: [Date]
+```
+
+### Pilot Testing
+
+**Always pilot before real sessions:**
+
+- Run 1-2 test sessions with team members
+- Check task clarity and timing
+- Test recording/screen sharing
+- Adjust based on pilot feedback
+
+**Pilot Checklist:**
+- [ ] Tasks understood without clarification
+- [ ] Session fits in time slot
+- [ ] Recording captures screen + audio
+- [ ] Post-test questions make sense
+
+---
+
+## Task Design
+
+### Good vs. Bad Tasks
+
+| Bad Task | Why Bad | Good Task |
+|----------|---------|-----------|
+| "Find the settings" | Leading | "Change your notification preferences" |
+| "Use the dashboard" | Vague | "Find how many sales you made last month" |
+| "Click the blue button" | Prescriptive | "Submit your order" |
+| "Do you like this?" | Opinion-based | "Rate how easy it was (1-5)" |
+
+### Task Construction Formula
+
+```
+SCENARIO + GOAL + SUCCESS CRITERIA
+
+Scenario: Context that makes task realistic
+Goal: What user needs to accomplish
+Success: How we know they succeeded
+
+Example:
+"Imagine you're planning a trip to Paris next month. [SCENARIO]
+Book a hotel for 3 nights in your budget. [GOAL]
+You've succeeded when you see the confirmation page. [SUCCESS]"
+```
+
+### Task Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| Exploration | First impressions | "Look around and tell me what you think this does" |
+| Specific | Core functionality | "Add item to cart and checkout" |
+| Comparison | Design validation | "Which of these two menus would you use to..." |
+| Stress | Edge cases | "What would you do if your payment failed?" |
+
+### Task Difficulty Progression
+
+Start easy, increase difficulty:
+
+```
+Task 1: Warm-up (easy, builds confidence)
+Task 2: Core flow (main functionality)
+Task 3: Secondary flow (important but less common)
+Task 4: Edge case (stress test)
+Task 5: Free exploration (open-ended)
+```
+
+---
+
+## Moderation Techniques
+
+### The Think-Aloud Protocol
+
+**Instruction Script:**
+"As you work through the tasks, please think out loud. Tell me what you're looking at, what you're thinking, and what you're trying to do. There are no wrong answers - we're testing the design, not you."
+
+**Prompts When Silent:**
+- "What are you thinking right now?"
+- "What do you expect to happen?"
+- "What are you looking for?"
+- "Tell me more about that"
+
+### Handling Common Situations
+
+| Situation | What to Say |
+|-----------|-------------|
+| User asks for help | "What would you do if I weren't here?" |
+| User is stuck | "What are your options?" (wait 30 sec before hint) |
+| User apologizes | "You're doing great. We're testing the design." |
+| User goes off-task | "That's interesting. Let's come back to [task]." |
+| User criticizes | "Tell me more about that." (neutral, don't defend) |
+
+### Non-Leading Question Techniques
+
+| Leading (Don't) | Neutral (Do) |
+|-----------------|--------------|
+| "Did you find that confusing?" | "How was that experience?" |
+| "The search is over here" | "What do you think you should do?" |
+| "Don't you think X is easier?" | "Which do you prefer and why?" |
+| "Did you notice the tooltip?" | "What happened there?" |
+
+### Post-Task Questions
+
+After each task:
+1. "How difficult was that?" (1-5 scale)
+2. "What, if anything, was confusing?"
+3. "What would you improve?"
+
+After all tasks:
+1. "What stood out to you?"
+2. "What was the best/worst part?"
+3. "Would you use this? Why/why not?"
+
+---
+
+## Analysis Framework
+
+### Severity Rating Scale
+
+| Severity | Definition | Criteria |
+|----------|------------|----------|
+| 4 - Critical | Prevents task completion | User cannot proceed |
+| 3 - Major | Significant difficulty | User struggles, considers giving up |
+| 2 - Minor | Causes hesitation | User recovers independently |
+| 1 - Cosmetic | Noticed but not problematic | User comments but unaffected |
+
+### Issue Documentation Template
+
+```
+ISSUE ID: ___
+SEVERITY: [1-4]
+FREQUENCY: [X/Y participants]
+
+TASK: [Which task]
+TIMESTAMP: [When in session]
+
+OBSERVATION:
+[What happened - factual description]
+
+USER QUOTE:
+"[Direct quote if available]"
+
+HYPOTHESIS:
+[Why this might be happening]
+
+RECOMMENDATION:
+[Proposed solution]
+
+AFFECTED PERSONA:
+[Which user types]
+```
+
+### Pattern Recognition
+
+**Quantitative Signals:**
+- Task completion rate < 80%
+- Time on task > 2x expected
+- Error rate > 20%
+- Satisfaction < 3/5
+
+**Qualitative Signals:**
+- Same confusion point across 3+ users
+- Repeated verbal frustration
+- Workaround attempts
+- Feature requests during task
+
+### Analysis Matrix
+
+```
+┌─────────────────┬───────────┬───────────┬───────────┐
+│ Issue │ Frequency │ Severity │ Priority │
+├─────────────────┼───────────┼───────────┼───────────┤
+│ Can't find X │ 4/5 │ Critical │ HIGH │
+│ Confusing label │ 3/5 │ Major │ HIGH │
+│ Slow loading │ 2/5 │ Minor │ MEDIUM │
+│ Typo in text │ 1/5 │ Cosmetic │ LOW │
+└─────────────────┴───────────┴───────────┴───────────┘
+
+Priority = Frequency × Severity
+```
+
+---
+
+## Reporting Template
+
+### Executive Summary
+
+```
+USABILITY TEST REPORT
+[Project Name] | [Date]
+
+OVERVIEW
+• Participants: [N] users matching [persona]
+• Method: [Type of test]
+• Tasks: [N] tasks covering [scope]
+
+KEY FINDINGS
+1. [Most critical issue + impact]
+2. [Second issue]
+3. [Third issue]
+
+SUCCESS METRICS
+• Completion rate: [X]% (target: Y%)
+• Avg. time on task: [X] min (target: Y min)
+• Satisfaction: [X]/5 (target: Y/5)
+
+TOP RECOMMENDATIONS
+1. [Highest priority fix]
+2. [Second priority]
+3. [Third priority]
+```
+
+### Detailed Findings Section
+
+```
+FINDING 1: [Title]
+
+Severity: [Critical/Major/Minor/Cosmetic]
+Frequency: [X/Y participants]
+Affected Tasks: [List]
+
+What Happened:
+[Description of the problem]
+
+Evidence:
+• P1: "[Quote]"
+• P3: "[Quote]"
+• [Video timestamp if available]
+
+Impact:
+[How this affects users and business]
+
+Recommendation:
+[Proposed solution with rationale]
+
+Design Mockup:
+[Optional: before/after if applicable]
+```
+
+### Metrics Dashboard
+
+```
+TASK PERFORMANCE SUMMARY
+
+Task 1: [Name]
+├─ Completion: ████████░░ 80%
+├─ Avg. Time: 2:15 (target: 2:00)
+├─ Errors: 1.2 avg
+└─ Satisfaction: ★★★★☆ 4.2/5
+
+Task 2: [Name]
+├─ Completion: ██████░░░░ 60% ⚠️
+├─ Avg. Time: 4:30 (target: 3:00) ⚠️
+├─ Errors: 3.1 avg ⚠️
+└─ Satisfaction: ★★★☆☆ 3.1/5
+
+[Continue for all tasks]
+```
+
+---
+
+## Quick Reference
+
+### Session Checklist
+
+**Before Session:**
+- [ ] Test plan finalized
+- [ ] Tasks written and piloted
+- [ ] Recording set up and tested
+- [ ] Consent form ready
+- [ ] Prototype/product accessible
+- [ ] Note-taking template ready
+
+**During Session:**
+- [ ] Consent obtained
+- [ ] Think-aloud explained
+- [ ] Recording started
+- [ ] Tasks presented one at a time
+- [ ] Post-task ratings collected
+- [ ] Debrief questions asked
+- [ ] Thanks and incentive
+
+**After Session:**
+- [ ] Notes organized
+- [ ] Recording saved
+- [ ] Initial impressions captured
+- [ ] Issues logged
+
+### Common Metrics
+
+| Metric | Formula | Target |
+|--------|---------|--------|
+| Completion rate | Successful / Total × 100 | >80% |
+| Time on task | Average seconds | <2x expected |
+| Error rate | Errors / Attempts × 100 | <15% |
+| Task-level satisfaction | Average rating | >4/5 |
+| SUS score | Standard formula | >68 |
+| NPS | Promoters - Detractors | >0 |
+
+---
+
+*See also: `journey-mapping-guide.md` for contextual research*
diff --git a/product-team/ux-researcher-designer/scripts/persona_generator.py b/product-team/ux-researcher-designer/scripts/persona_generator.py
index dd5f281..a26ff59 100644
--- a/product-team/ux-researcher-designer/scripts/persona_generator.py
+++ b/product-team/ux-researcher-designer/scripts/persona_generator.py
@@ -1,7 +1,69 @@
#!/usr/bin/env python3
"""
Data-Driven Persona Generator
-Creates research-backed user personas from user data and interviews
+Creates research-backed user personas from user data and interviews.
+
+Usage:
+ python persona_generator.py [json]
+
+ Without arguments: Human-readable formatted output
+ With 'json': JSON output for integration with other tools
+
+Examples:
+ python persona_generator.py # Formatted persona output
+ python persona_generator.py json # JSON for programmatic use
+
+Table of Contents:
+==================
+
+CLASS: PersonaGenerator
+ __init__() - Initialize archetype templates and persona components
+ generate_persona_from_data() - Main entry: generate persona from user data + interviews
+ format_persona_output() - Format persona dict as human-readable text
+
+PATTERN ANALYSIS:
+ _analyze_user_patterns() - Extract usage, device, context patterns from data
+ _identify_archetype() - Classify user into power/casual/business/mobile archetype
+ _analyze_behaviors() - Analyze usage patterns and feature preferences
+
+DEMOGRAPHIC EXTRACTION:
+ _aggregate_demographics() - Calculate age range, location, tech proficiency
+ _extract_psychographics() - Extract motivations, values, attitudes, lifestyle
+
+NEEDS & FRUSTRATIONS:
+ _identify_needs() - Identify primary/secondary goals, functional/emotional needs
+ _extract_frustrations() - Extract pain points from patterns and interviews
+
+CONTENT GENERATION:
+ _generate_name() - Generate persona name from archetype
+ _generate_tagline() - Generate one-line persona summary
+ _generate_scenarios() - Create usage scenarios based on archetype
+ _select_quote() - Select representative quote from interviews
+
+DATA VALIDATION:
+ _calculate_data_points() - Calculate sample size and confidence level
+ _derive_design_implications() - Generate actionable design recommendations
+
+FUNCTIONS:
+ create_sample_user_data() - Generate sample data for testing/demo
+ main() - CLI entry point
+
+Archetypes Supported:
+ - power_user: Daily users, 10+ features, efficiency-focused
+ - casual_user: Weekly users, basic needs, simplicity-focused
+ - business_user: Work context, team collaboration, ROI-focused
+ - mobile_first: Mobile primary, on-the-go, quick interactions
+
+Output Components:
+ - name, archetype, tagline, quote
+ - demographics: age, location, occupation, education, tech_proficiency
+ - psychographics: motivations, values, attitudes, lifestyle
+ - behaviors: usage_patterns, feature_preferences, interaction_style
+ - needs_and_goals: primary, secondary, functional, emotional
+ - frustrations: pain points with frequency
+ - scenarios: contextual usage stories
+ - data_points: sample_size, confidence_level, validation_method
+ - design_implications: actionable recommendations
"""
import json