whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md

@@ -0,0 +1,301 @@
+# Cross-Page Consistency Strategy
+
+**Maintaining Visual Coherence Across Project Sketches**
+
+---
+
+## Core Principle
+
+**Text that looks similar and serves the same role should have the same specification across all pages.**
+
+This creates:
+
+- ✅ Consistent user experience
+- ✅ Natural design system patterns
+- ✅ Faster specification process
+- ✅ Professional, cohesive design
+
+---
+
+## Workflow: Multi-Page Projects
+
+### Page 1: Start Page (Establish Baseline)
+
+**First page analyzed - establish reference patterns:**
+
+```
+Start Page Analysis:
+├─ Body Text: Thin lines, icon-sized spacing → 16px Regular
+├─ Button Labels: Medium lines → 16px Semibold
+├─ Page Title: Thick lines, button-height spacing → 48px Bold
+├─ Navigation: Medium lines, small spacing → 14px Medium
+└─ Caption: Thinnest lines, half-icon spacing → 12px Regular
+```
+
+**These become your reference anchors for subsequent pages.**
+
+---
+
+### Page 2: About Page (Apply Patterns)
+
+**When analyzing the About Page sketch:**
+
+#### Step 1: Check Previous Pages
+
+```
+Agent: "I see you've already analyzed the Start Page.
+I'll use those text styles as reference points."
+```
+
+#### Step 2: Match Visual Patterns
+
+```
+About Page body text:
+- Thin lines ✓
+- Icon-sized spacing ✓
+- Left-aligned ✓
+
+→ Matches Start Page body text pattern
+→ Apply same spec: 16px Regular
+```
+
+#### Step 3: Confirm with Designer
+
+```
+Agent: "This body text looks identical to Start Page body text.
+Should I use the same specification (16px Regular)?"
+
+Designer: "Yes!" or "No, make it 18px"
+```
+
+---
+
+## Pattern Matching Rules
+
+### When to Apply Same Specification
+
+**Match if ALL criteria align:**
+
+1. **Visual Similarity**
+   - Line thickness matches (relative to other elements)
+   - Spacing matches (relative to UI anchors)
+   - Alignment matches
+
+2. **Functional Role**
+   - Serves same purpose (e.g., both are body paragraphs)
+   - Same content type (e.g., both are descriptions)
+   - Same hierarchy level
+
+3. **Context**
+   - Similar page sections (e.g., both in main content area)
+   - Similar surrounding elements
+
+### When to Create New Specification
+
+**Create new spec if:**
+
+- Visual appearance differs (thicker lines, different spacing)
+- Functional role differs (e.g., one is a quote, one is body text)
+- Designer explicitly requests different styling
+- Context requires emphasis/de-emphasis
+
+---
+
+## Design System Integration
+
+### Automatic Pattern Building
+
+As you analyze pages, WDS naturally builds design system patterns:
+
+```
+Project: Dog Week
+
+Text Styles Identified:
+├─ heading-xl: 48px Bold (Page titles)
+├─ heading-lg: 36px Bold (Section headings)
+├─ heading-md: 24px Semibold (Subsection headings)
+├─ body-text: 16px Regular (Paragraphs)
+├─ button-label: 16px Semibold (All buttons)
+├─ caption: 12px Regular (Helper text)
+└─ nav-item: 14px Medium (Navigation)
+
+Components Identified:
+├─ Feature Card (used on Start, Features, About pages)
+├─ Navigation Bar (used on all pages)
+├─ Footer (used on all pages)
+└─ CTA Button (used on Start, Pricing pages)
+```
+
+### Benefits
+
+**Without explicit design system:**
+
+- Maintains consistency through pattern recognition
+- Reduces specification time (reference previous pages)
+- Creates professional, cohesive experience
+
+**With explicit design system:**
+
+- Automatically maps to existing components
+- Validates sketch against design system
+- Suggests design system updates when new patterns emerge
+
+---
+
+## Agent Behavior Examples
+
+### Example 1: Exact Match
+
+```
+Agent: "I'm analyzing the Contact Page body text.
+
+Visual Analysis:
+- Line thickness: Thinnest (matches Start Page body text)
+- Spacing: Icon-sized (matches Start Page body text)
+- Alignment: Left (matches Start Page body text)
+
+Pattern Match: Start Page body text (16px Regular)
+
+Should I use the same specification?"
+
+Designer: "Yes, keep it consistent."
+
+Agent: "✅ Applied: 16px Regular (consistent with Start Page)"
+```
+
+### Example 2: Intentional Variation
+
+```
+Agent: "I'm analyzing the Testimonial Quote text.
+
+Visual Analysis:
+- Line thickness: Medium (thicker than body text)
+- Spacing: Slightly larger than body text
+- Alignment: Center (different from body text)
+
+This looks different from body text. Should this be:
+1. New style: 18px Medium, center-aligned (emphasis)
+2. Same as body: 16px Regular (consistency)
+
+Your choice?"
+
+Designer: "Option 1 - quotes should stand out."
+
+Agent: "✅ Created new style: testimonial-quote (18px Medium)"
+```
+
+### Example 3: Component Recognition
+
+```
+Agent: "I'm analyzing the Features section on the Pricing Page.
+
+Component Match Detected:
+- Layout: 3-column card grid ✓
+- Card structure: Icon + Title + Description ✓
+- Visual style: Matches Features section from Start Page ✓
+
+This looks like the same 'Feature Card' component.
+Should I:
+1. Reference existing component (recommended)
+2. Create page-specific version
+
+Your choice?"
+
+Designer: "Option 1 - it's the same component."
+
+Agent: "✅ Referenced: Feature Card component (defined on Start Page)"
+```
+
+---
+
+## Best Practices
+
+### For Designers
+
+1. **Be Consistent in Sketches**
+   - Use same line thickness for same text types
+   - Use same spacing patterns across pages
+   - Helps AI recognize patterns automatically
+
+2. **Confirm Pattern Matches**
+   - When AI suggests pattern match, verify it's intentional
+   - Speak up if variation is desired
+
+3. **Build Design System Gradually**
+   - First few pages establish patterns
+   - Later pages reference patterns
+   - Natural evolution into design system
+
+### For AI Agents
+
+1. **Always Check Previous Pages First**
+   - Before analyzing text, look for established patterns
+   - Show detected patterns to designer for transparency
+
+2. **Ask, Don't Assume**
+   - Even if visual match is strong, confirm with designer
+   - Designer may have intentional variation
+
+3. **Track Pattern Usage**
+   - Note which pages use which patterns
+   - Helps identify true design system components
+
+---
+
+## Implementation in WDS Workflow
+
+### Step 1: Holistic Sketch Reading
+
+```
+<action>
+1. Check if other pages in project have been analyzed
+2. Load established text style patterns
+3. Identify UI anchors in current sketch
+4. Use previous pages + UI elements to calibrate scale
+</action>
+```
+
+### Step 2: Pattern Detection
+
+```
+<action>
+For each text element in current sketch:
+1. Analyze visual properties (thickness, spacing, alignment)
+2. Compare to established patterns from previous pages
+3. If match found → suggest applying same specification
+4. If no match → analyze using UI anchors + relative measurements
+</action>
+```
+
+### Step 3: Designer Confirmation
+
+```
+<output>
+Text Element: Body paragraph in "About Us" section
+
+Pattern Match: Start Page body text
+- Visual: Thin lines, icon-sized spacing ✓
+- Functional: Paragraph description ✓
+- Specification: 16px Regular
+
+Apply same specification?
+</output>
+
+<ask>
+1. Yes - Use 16px Regular (consistent)
+2. No - I want different styling
+</ask>
+```
+
+---
+
+## Summary
+
+**Cross-page consistency is achieved through:**
+
+1. **Pattern Recognition** - AI identifies similar visual patterns across pages
+2. **Reference Anchors** - First pages establish baseline specifications
+3. **Designer Confirmation** - AI suggests matches, designer validates
+4. **Natural Design System** - Patterns emerge organically from consistent application
+
+**Result:** Professional, cohesive multi-page designs with minimal specification overhead.

package/src/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md

@@ -0,0 +1,161 @@
+# Phase 4 Documentation Architecture
+
+## Problem: Redundant Information
+
+Currently sketch text analysis rules are duplicated across multiple files, making maintenance difficult and increasing risk of inconsistency.
+
+## Solution: Single Source of Truth Pattern
+
+### Core Documentation (Single Source of Truth)
+
+1. **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** ← **MASTER GUIDE**
+   - Complete rules for analyzing text markers
+   - Line thickness → font weight
+   - Line spacing → font size
+   - Line position → text alignment
+   - Line count → text lines
+   - Line length → character capacity
+   - All visual examples and edge cases
+
+2. **`SKETCH-TEXT-QUICK-REFERENCE.md`**
+   - One-page summary of the guide
+   - Quick lookup table
+   - References master guide for details
+
+3. **`SKETCH-TEXT-STRATEGY.md`**
+   - When to use actual text vs. line markers
+   - Proactive translation workflow
+   - References master guide for analysis rules
+
+### Specialized Documentation (References Core)
+
+4. **`object-types/TEXT-DETECTION-PRIORITY.md`**
+   - Why text detection is first
+   - PAIRS = text, SINGLE = decorative
+   - References master guide for analysis
+   - Focus: Detection logic only
+
+5. **`object-types/heading-text.md`**
+   - Instruction file for AI agent
+   - References master guide
+   - Focus: Workflow and user interaction
+   - Does NOT duplicate analysis rules
+
+6. **`object-types/object-router.md`**
+   - Routes to appropriate object type
+   - References TEXT-DETECTION-PRIORITY.md
+   - Does NOT duplicate analysis rules
+
+### Supporting Documentation
+
+7. **`HTML-VS-VISUAL-STYLES.md`**
+   - HTML tags vs visual styles
+   - No sketch analysis (different topic)
+
+8. **`IMAGE-SKETCHING-BEST-PRACTICES.md`**
+   - How to sketch images
+   - No text analysis (different topic)
+
+9. **`WDS-SPECIFICATION-PATTERN.md`**
+   - Shows complete specification format
+   - Examples reference the guides
+   - Does NOT teach analysis rules
+
+10. **`TRANSLATION-ORGANIZATION-GUIDE.md`**
+    - Purpose-based naming
+    - Grouped translations
+    - References guides for text detection
+
+---
+
+## Refactoring Plan
+
+### Keep As-Is (Single Source of Truth)
+
+✅ `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Master guide with all rules
+✅ `SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference
+✅ `SKETCH-TEXT-STRATEGY.md` - Strategy guide
+
+### Refactor (Remove Duplication, Add References)
+
+**`TEXT-DETECTION-PRIORITY.md`:**
+
+- Keep: Detection logic (pairs vs single)
+- Remove: Detailed analysis rules (thickness → weight, spacing → size)
+- Add: Reference to master guide
+
+**`heading-text.md`:**
+
+- Keep: Workflow steps
+- Remove: Duplicate explanations of analysis rules
+- Add: Reference to master guide
+- Show: Example output only
+
+**`object-router.md`:**
+
+- Keep: Routing logic
+- Remove: Any duplicate analysis
+- Add: Reference to TEXT-DETECTION-PRIORITY.md
+
+**`WDS-SPECIFICATION-PATTERN.md`:**
+
+- Keep: Examples
+- Add: Note "See SKETCH-TEXT-ANALYSIS-GUIDE.md for how these values were derived"
+
+**`TRANSLATION-ORGANIZATION-GUIDE.md`:**
+
+- Keep: Organization patterns
+- Add: Reference to master guide for analysis
+
+---
+
+## Benefits
+
+✅ **Single Source of Truth** - One place to update analysis rules
+✅ **No Redundancy** - Each file has clear purpose
+✅ **Easy Maintenance** - Update once, references everywhere
+✅ **Clear Hierarchy** - Master guide → specialized docs
+✅ **Reduced File Size** - Instruction files become smaller and focused
+
+---
+
+## Reference Pattern
+
+In instruction files, use this pattern:
+
+```markdown
+<output>Analyzing text markers in sketch...</output>
+
+<action>Apply text marker analysis rules from SKETCH-TEXT-ANALYSIS-GUIDE.md:
+
+- Count pairs → number of lines
+- Measure thickness → font weight
+- Measure spacing → font size estimate
+- Check position → alignment
+- Calculate length → character capacity
+  </action>
+
+<output>**Sketch Analysis:**
+
+- 2 line pairs → 2 lines of text
+- Thick lines (3px) → Bold weight
+- Spacing (24px) → ~42px font size estimate
+- Centered position → Center alignment
+- ~35 characters per line
+
+For detailed analysis rules, see: SKETCH-TEXT-ANALYSIS-GUIDE.md</output>
+```
+
+---
+
+## Status
+
+**To Do:**
+
+- [ ] Refactor TEXT-DETECTION-PRIORITY.md
+- [ ] Refactor heading-text.md
+- [ ] Refactor object-router.md
+- [ ] Add references in WDS-SPECIFICATION-PATTERN.md
+- [ ] Add references in TRANSLATION-ORGANIZATION-GUIDE.md
+
+**Result:** Clean, maintainable documentation architecture! 🎯

package/src/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md

@@ -0,0 +1,243 @@
+# HTML Tags vs. Visual Text Styles
+
+**Critical Best Practice for WDS Specifications**
+
+---
+
+## The Two-Layer System
+
+### Layer 1: HTML Semantic Structure (h1-h6, p, etc.)
+
+**Purpose:** SEO, accessibility, document outline, screen readers
+
+**Rules:**
+
+- **Each page must have exactly ONE h1** (main page title)
+- **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping)
+- **Same across all pages** for semantic consistency
+- **Not about visual appearance**
+
+### Layer 2: Visual Text Styles (Design System)
+
+**Purpose:** Visual hierarchy, branding, design consistency
+
+**Rules:**
+
+- **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.)
+- **Can be applied to any HTML tag**
+- **Different pages can use different visual styles** for the same HTML tag
+- **About appearance, not semantics**
+
+---
+
+## Why Separate?
+
+### Problem: Mixing HTML and Visual Styles
+
+```markdown
+❌ BAD:
+
+- **Style**: H1 heading
+
+What does this mean?
+
+- Is it an h1 tag?
+- Is it a visual style that looks like an h1?
+- What if another page needs h1 but different visual style?
+```
+
+### Solution: Specify Both Independently
+
+```markdown
+✅ GOOD:
+
+- **HTML Tag**: h1 (semantic structure)
+- **Visual Style**: Display-Large (from Design System)
+```
+
+**Now we know:**
+
+- HTML: This is the main page heading (h1 for SEO)
+- Visual: It uses the "Display-Large" design system style
+- Another page could have: h1 + Headline-Medium (different visual, same semantic)
+
+---
+
+## Real-World Examples
+
+### Example 1: Landing Page vs. Article Page
+
+**Landing Page - Hero Headline:**
+
+```markdown
+- **HTML Tag**: h1
+- **Visual Style**: Hero headline
+- **Font**: Bold, 56px, line-height 1.1
+```
+
+**Article Page - Article Title:**
+
+```markdown
+- **HTML Tag**: h1
+- **Visual Style**: Main header
+- **Font**: Bold, 32px, line-height 1.3
+```
+
+**Both are h1 (semantic), but different visual styles!**
+
+### Example 2: Same Visual Style, Different Semantics
+
+**Section Heading:**
+
+```markdown
+- **HTML Tag**: h2
+- **Visual Style**: Sub header
+- **Font**: Bold, 28px, line-height 1.2
+```
+
+**Testimonial Quote:**
+
+```markdown
+- **HTML Tag**: p
+- **Visual Style**: Sub header
+- **Font**: Bold, 28px, line-height 1.2
+```
+
+**Same visual style (Sub header), but different HTML tags for proper semantics!**
+
+---
+
+## Design System Visual Style Naming
+
+### Good Visual Style Names (Descriptive & Purpose-Based)
+
+**For Headers:**
+✅ **Main header** - Primary page header
+✅ **Sub header** - Section headers
+✅ **Sub header light** - Lighter variant of section header
+✅ **Card header** - Headers within cards
+✅ **Small header** - Minor headers, labels
+
+**For Body Text:**
+✅ **Body text** - Standard paragraph text
+✅ **Body text large** - Larger body text for emphasis
+✅ **Body text small** - Smaller body text, secondary info
+✅ **Intro text** - Opening paragraph, lead text
+
+**For Special Purposes:**
+✅ **Hero headline** - Large display text for hero sections
+✅ **Caption text** - Image captions, metadata
+✅ **Label text** - Form labels, UI labels
+✅ **Error text** - Error messages
+✅ **Success text** - Success messages
+✅ **Link text** - Link styling
+✅ **Button text** - Text within buttons
+
+### Bad Visual Style Names
+
+❌ **H1-Style** / **Heading-1** - Confuses with HTML tags
+❌ **Text-Size-42** - Just a number, not semantic
+❌ **Big-Text** - Too vague
+❌ **Display-Large** - Too abstract (unless using design system tokens)
+
+---
+
+## WDS Specification Format
+
+### Complete Example
+
+```markdown
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+**HTML Structure:**
+
+- **Tag**: h1
+- **Purpose**: Main page heading (SEO/accessibility)
+
+**Visual Style:**
+
+- **Style Name**: Hero headline
+- **Font weight**: Bold (from 3px thick line markers in sketch)
+- **Font size**: 56px (est. from 32px spacing between line pairs)
+- **Line-height**: 1.1 (est. calculated from font size)
+- **Color**: #1a1a1a
+- **Letter spacing**: -0.02em
+
+**Position**: Center of hero section, above supporting text
+
+**Behavior**: Updates with language toggle
+
+**Content**:
+
+- EN: "Every walk. on time. Every time."
+- SE: "Varje promenad. i tid. Varje gång."
+```
+
+---
+
+## Benefits of This Approach
+
+✅ **Flexibility** - Different pages can have different visual styles for same semantic tags
+✅ **Consistency** - Design system ensures visual consistency across visual styles
+✅ **SEO/Accessibility** - Proper HTML structure maintained
+✅ **Scalability** - Easy to add new visual styles without breaking semantic structure
+✅ **Clarity** - Designers and developers both understand the specification
+✅ **Reusability** - Visual styles can be reused across different HTML tags
+
+---
+
+## Common Patterns
+
+### Pattern 1: Landing Page
+
+```
+h1 → Hero headline (big hero text, 56px)
+h2 → Sub header (section headings, 32px)
+h3 → Small header (subsection headings, 24px)
+p → Body text (regular paragraphs, 16px)
+```
+
+### Pattern 2: Blog Post
+
+```
+h1 → Main header (article title, 36px)
+h2 → Sub header (section headings, 28px)
+h3 → Sub header light (subsection headings, 22px)
+p → Body text large (article body, 18px)
+```
+
+### Pattern 3: Dashboard
+
+```
+h1 → Main header (page title, 28px)
+h2 → Card header (widget titles, 20px)
+h3 → Small header (section labels, 16px)
+p → Body text small (compact info, 14px)
+```
+
+**Same HTML structure (h1, h2, h3, p) but different visual styles for each context!**
+
+---
+
+## Implementation Note
+
+When generating HTML prototypes or handing off to developers:
+
+```html
+<!-- The HTML tag is semantic, the class references the visual style -->
+<h1 class="hero-headline">Every walk. on time. Every time.</h1>
+
+<!-- Another page might have -->
+<h1 class="main-header">Welcome to Your Profile</h1>
+
+<!-- NOT this (mixing concerns) -->
+<h1 class="h1">Every walk. on time. Every time.</h1>
+```
+
+The CSS class references the **visual style name** (hero-headline, main-header), not the HTML tag.
+
+---
+
+**Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯