whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md

@@ -0,0 +1,275 @@
+# Object Router Flow Diagram
+
+**Updated with Text-First Detection**
+
+---
+
+## Complete Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  4C-03: Components & Objects                            │
+│  (For each object, top-left to bottom-right)            │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────┐
+│  OBJECT-ROUTER.MD                                       │
+│  Step 1: TEXT DETECTION FIRST                           │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+                      ▼
+         ┌────────────────────────┐
+         │ Horizontal lines       │
+         │ detected in sketch?    │
+         └────────┬───────┬───────┘
+                  │       │
+        YES ◄─────┘       └─────► NO
+         │                        │
+         ▼                        ▼
+┌──────────────────────┐  ┌──────────────────────────┐
+│ ✓ TEXT DETECTED      │  │ Step 2: ANALYZE          │
+│                      │  │ OTHER OBJECT TYPE        │
+│ Quick Analysis:      │  │                          │
+│ - Line count         │  │ Check for:               │
+│ - Thickness          │  │ - Button shapes          │
+│ - Spacing            │  │ - Input boxes            │
+│ - Alignment          │  │ - Image placeholders     │
+│                      │  │ - Containers             │
+│ Appears to be:       │  │ - Interactive elements   │
+│ {{text_type}}        │  └────────┬─────────────────┘
+└──────┬───────────────┘           │
+       │                           ▼
+       │              ┌────────────────────────────┐
+       │              │ Agent suggests             │
+       │              │ interpretation with        │
+       │              │ reasoning                  │
+       │              └────────┬───────────────────┘
+       │                       │
+       │                       ▼
+       │              ┌────────────────────────────┐
+       │              │ User confirms:             │
+       │              │ 1. Yes                     │
+       │              │ 2. Close - clarify         │
+       │              │ 3. No - different          │
+       │              └────────┬───────────────────┘
+       │                       │
+       │                       ▼
+       │              ┌────────────────────────────┐
+       │              │ Confirmed object type      │
+       │              └────────┬───────────────────┘
+       │                       │
+       ▼                       ▼
+┌─────────────────────────────────────────────────────────┐
+│  ROUTE TO OBJECT-SPECIFIC INSTRUCTION FILE              │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+        ┌─────────────┴─────────────────────┐
+        │                                   │
+        ▼                                   ▼
+┌──────────────────┐            ┌──────────────────────┐
+│ heading-text.md  │            │ Other object files:  │
+│                  │            │                      │
+│ Complete text    │            │ • button.md          │
+│ analysis:        │            │ • text-input.md      │
+│                  │            │ • link.md            │
+│ 1. Object ID     │            │ • image.md           │
+│ 2. Text type     │            │ • card.md            │
+│ 3. Sketch        │            │ • modal-dialog.md    │
+│    analysis:     │            │ • table.md           │
+│    - Lines       │            │ • list.md            │
+│    - Thickness   │            │ • navigation.md      │
+│    - Spacing     │            │ • badge.md           │
+│    - Capacity    │            │ • alert-toast.md     │
+│ 4. Content       │            │ • progress.md        │
+│    guidance      │            │ • video.md           │
+│ 5. Styling       │            │ • custom.md          │
+│ 6. Responsive    │            │                      │
+│ 7. Generate      │            │ Each with:           │
+│    spec          │            │ - Object ID          │
+└────────┬─────────┘            │ - Type-specific      │
+         │                      │   analysis           │
+         │                      │ - Complete examples  │
+         │                      │ - Generate spec      │
+         │                      └──────────┬───────────┘
+         │                                 │
+         └─────────────┬───────────────────┘
+                       │
+                       ▼
+         ┌─────────────────────────────┐
+         │ Specification Complete      │
+         │                             │
+         │ Object documented with:     │
+         │ - Object ID assigned        │
+         │ - Complete specification    │
+         │ - Examples included         │
+         │ - Consistent format         │
+         └─────────────┬───────────────┘
+                       │
+                       ▼
+         ┌─────────────────────────────┐
+         │ Return to 4C-03             │
+         │                             │
+         │ Next object? [Y/N]          │
+         │ - YES: Loop back to router  │
+         │ - NO: Section complete      │
+         └─────────────────────────────┘
+```
+
+---
+
+## Key Changes
+
+### OLD: Generic Object Detection
+
+```
+1. Ask user "What type is this?" [list of 20 options]
+2. User selects from list
+3. Route to file
+```
+
+### NEW: Text-First with Intelligence
+
+```
+1. Check for horizontal lines FIRST
+   ├─ YES → Text detected → Route to heading-text.md
+   └─ NO → Continue analysis
+2. Agent analyzes and suggests with reasoning
+3. User confirms quickly
+4. Route to appropriate file
+```
+
+---
+
+## Text Detection Flow (Detailed)
+
+```
+Object Router detects horizontal lines:
+
+═══════════════════════════════
+═══════════════════════════
+
+         ↓
+
+Agent says:
+"✓ TEXT ELEMENT DETECTED
+
+I see 2 thick horizontal lines - text content.
+
+Quick Analysis:
+- 2 lines (text placeholders)
+- Thickness: 3px
+- Spacing: 3px
+- Alignment: Center
+
+This appears to be HEADING (H2).
+
+→ Loading text-specific instructions..."
+
+         ↓
+
+Routes to heading-text.md
+
+         ↓
+
+heading-text.md executes:
+1. Confirms text type
+2. Analyzes sketch in detail:
+   - Estimates font size (28-32px)
+   - Estimates line-height (1.3)
+   - Calculates capacity (50-60 chars)
+3. Requests content with guidance
+4. Validates content length
+5. Specifies styling
+6. Generates complete spec
+
+         ↓
+
+Returns to 4c-03 with completed specification
+```
+
+---
+
+## Benefits
+
+### 1. Efficiency
+
+- Text detected immediately (no menu selection)
+- Most common object type caught first
+- Reduces decision points
+
+### 2. Accuracy
+
+- Text has unique signature (horizontal lines)
+- Clear visual indicator
+- Hard to misidentify
+
+### 3. Completeness
+
+- Routes to specialized text analysis
+- Character capacity automatic
+- Content guidance immediate
+
+### 4. Intelligence
+
+- Agent demonstrates understanding
+- Natural interpretation flow
+- Trust-the-agent philosophy
+
+---
+
+## Example Scenarios
+
+### Scenario 1: Page with Heading + Paragraph + Button
+
+```
+Sketch shows (top to bottom):
+
+═══════════════════════════════  ← 1. Text: pair of THICK lines (1 line of text)
+═══════════════════════════════     = Heading (bold font weight)
+
+─────────────────────────────────  ← 2. Text: 2 pairs of THIN lines (2 lines of text)
+─────────────────────────────────     = Body paragraph (regular font weight)
+
+─────────────────────────────────     Large spacing between pairs = larger font
+─────────────────────────────────
+
+┌──────────────────┐
+│  Get Started     │  ← 3. Button
+└──────────────────┘
+
+Router processes:
+1. Object 1: Detects 1 pair of thick lines → heading-text.md → H2 heading (bold, ~1 line)
+2. Object 2: Detects 2 pairs of thin lines → heading-text.md → Body paragraph (~2 lines)
+3. Object 3: Detects button shape → button.md → Primary button
+```
+
+### Scenario 2: Form with Labels + Inputs
+
+```
+Sketch shows:
+
+══════════                         ← 1. Text: pair of thin lines (1 line = label)
+══════════                            Small spacing = smaller font
+
+┌───────────────────────────────┐
+│                               │  ← 2. Input box
+└───────────────────────────────┘
+
+──────────                         ← 3. Text: pair of thin lines (1 line = label)
+──────────                            Small spacing = smaller font
+
+┌───────────────────────────────┐
+│                               │  ← 4. Input box
+└───────────────────────────────┘
+
+Router processes:
+1. Object 1: Detects pair of lines → heading-text.md → Label text (~20-30 chars)
+2. Object 2: Detects input box → text-input.md → Email input
+3. Object 3: Detects pair of lines → heading-text.md → Label text (~20-30 chars)
+4. Object 4: Detects input box → text-input.md → Password input
+```
+
+---
+
+**Text-first detection ensures accurate routing and complete text analysis!** 📝✨

package/src/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md

@@ -0,0 +1,391 @@
+# Text Detection Priority Rules
+
+**For Object Router - Always Check for Text FIRST**
+
+---
+
+## Critical Rule: Text Markers = PAIRS of Lines
+
+**✅ Text = Two horizontal lines together** (representing one line of text)
+
+```
+═══════════════════════════  ← Line 1 of pair
+═══════════════════════════  ← Line 2 of pair = ONE line of text
+```
+
+**❌ Single line alone = NOT text** (it's a decorative element)
+
+```
+═══════════════════════════  ← SINGLE LINE = divider, border, underline (NOT text)
+```
+
+**Important Exception:** Very schematic sketches or miniatures (rare cases) might use single lines for text, but the default assumption should be: **single line = decorative element**.
+
+---
+
+## Why Text Detection is First
+
+Text elements are the most common objects in sketches, and they have a distinctive visual signature (horizontal line pairs). Detecting them first:
+
+- ✅ Reduces confusion
+- ✅ Routes to text-specific analysis immediately
+- ✅ Ensures character capacity is calculated
+- ✅ Prevents misidentification as other elements
+
+---
+
+## Text Detection Signatures
+
+### Text Markers (Paired Lines)
+
+**1 line of heading text (ONE PAIR = ONE TEXT LINE):**
+
+```
+═══════════════════════════  ← Thick pair line 1
+═══════════════════════════  ← Thick pair line 2 = ONE text line
+```
+
+**2 lines of heading text (TWO PAIRS = TWO TEXT LINES):**
+
+```
+═══════════════════════════  ← Pair 1 line 1
+═══════════════════════════  ← Pair 1 line 2 = Text line 1
+                                Small gap
+═══════════════════════════  ← Pair 2 line 1
+═══════════════════════════  ← Pair 2 line 2 = Text line 2
+```
+
+**4 lines of body text (FOUR PAIRS = FOUR TEXT LINES):**
+
+```
+─────────────────────────────  ← Pair 1
+─────────────────────────────
+
+─────────────────────────────  ← Pair 2
+─────────────────────────────
+
+─────────────────────────────  ← Pair 3
+─────────────────────────────
+
+─────────────────────────────  ← Pair 4
+─────────────────────────────
+```
+
+**Label (short text, ONE PAIR = ONE TEXT LINE):**
+
+```
+══════════  ← Short pair line 1
+══════════  ← Short pair line 2 = ONE short text line
+```
+
+### NOT Text Markers (Single Lines = Decorative Elements)
+
+**❌ Horizontal divider (`<hr>`):**
+
+```
+═══════════════════════════  ← SINGLE LINE = section divider
+```
+
+**❌ Underline (decorative):**
+
+```
+Main Heading
+─────────────────────────────  ← SINGLE LINE = decorative underline
+```
+
+**❌ Border line:**
+
+```
+___________________________  ← SINGLE LINE = top/bottom border
+```
+
+**❌ Separator:**
+
+```
+Section 1 content...
+
+───────────────────────────── ← SINGLE LINE = visual separator
+
+Section 2 content...
+```
+
+---
+
+## Detection Logic
+
+### Step 1: Look for Paired Horizontal Lines
+
+```
+IF horizontal lines come in pairs (2 lines close together):
+  → TEXT MARKER
+  → Count pairs to get number of text lines
+  → Route to heading-text.md
+
+ELSE IF single horizontal line:
+  → DECORATIVE ELEMENT (divider, border, underline)
+  → Document as visual element, not text
+
+ELSE IF sees button shape (box with text):
+  → BUTTON
+  → Route to button.md
+
+ELSE IF sees input box (rectangular border):
+  → INPUT FIELD
+  → Route to text-input.md
+
+... etc
+```
+
+### Step 2: Analyze Text Marker Pairs
+
+**Once text markers are detected, route to `heading-text.md` for complete analysis.**
+
+The detailed analysis rules are documented in **`SKETCH-TEXT-ANALYSIS-GUIDE.md`**, which covers:
+
+- Line thickness → font weight
+- Line spacing between pairs → font size
+- Line position in container → text alignment
+- Line count → number of text lines
+- Line length → character capacity
+
+**This file focuses on DETECTION only. For ANALYSIS, see `SKETCH-TEXT-ANALYSIS-GUIDE.md`.**
+
+---
+
+## Text vs. Other Elements
+
+### ✅ Text Element (Horizontal Line PAIRS)
+
+```
+═══════════════════════════  ← Pair indicating text
+═══════════════════════════
+
+─────────────────────────────  ← Another pair
+─────────────────────────────
+```
+
+**Detection:** Lines come in pairs, parallel, evenly spaced
+**Route to:** `heading-text.md`
+
+### ❌ NOT Text - Decorative Line (SINGLE)
+
+```
+═══════════════════════════  ← Single line alone
+```
+
+**Detection:** Single horizontal line, no pair
+**Type:** Divider, border, separator, underline
+**Action:** Document as decorative visual element
+
+### ❌ NOT Text - Button
+
+```
+┌─────────────────┐
+│  Button Label   │  ← Box with centered text inside
+└─────────────────┘
+```
+
+**Detection:** Rectangle with text inside, clickable appearance
+**Route to:** `button.md`
+
+### ❌ NOT Text - Input Field
+
+```
+┌───────────────────────────┐
+│ Placeholder text...       │  ← Box with light text inside
+└───────────────────────────┘
+```
+
+**Detection:** Rectangle with subtle border, input appearance
+**Route to:** `text-input.md`
+
+### ❌ NOT Text - Image
+
+**WDS Best Practice: Sketch the actual image content**
+
+```
+┌─────────────────┐
+│   ~  ~  ~       │  ← Sketch of clouds (hero image background)
+│  ~     ~    ~   │
+└─────────────────┘
+
+┌─────────────────┐
+│   ◠  ◠          │  ← Sketch of face/person (profile photo)
+│     ᵕ           │
+└─────────────────┘
+
+┌─────────────────┐
+│    /\  /\       │  ← Sketch of mountains/landscape
+│   /  \/  \      │
+└─────────────────┘
+```
+
+**WDS Recommends:**
+
+- ✅ **Draw what the image shows** - Sketch the actual content (person, landscape, product)
+- ✅ **Use soft shapes** - Clouds, waves, organic shapes for abstract images
+- ❌ **Avoid "X" markers** - Too intrusive and provides no content guidance
+
+**Why?** Sketching actual image content:
+
+- Provides visual direction and context
+- Helps with AI interpretation of image purpose
+- Guides content selection and art direction
+- More inspiring and communicative than placeholder X
+
+**Detection:** Rectangle containing sketch/drawing, not text markers
+**Route to:** `image.md`
+
+### ❌ NOT Text - Link (Often With Text)
+
+```
+══════════  ← Text pair (the link text)
+══════════
+    ↑ underline indicator or different color
+```
+
+**Detection:** Text with underline or special formatting indicating clickability
+**Route to:** `link.md` (which handles the text content)
+
+---
+
+## Detection Algorithm (Pseudo-code)
+
+```python
+def detect_object_type(sketch_element):
+    """
+    Always check for text FIRST before other object types
+    """
+
+    # Step 1: Check for horizontal line pairs (TEXT)
+    if has_horizontal_lines(sketch_element):
+        lines = get_horizontal_lines(sketch_element)
+        pairs = group_lines_into_pairs(lines, max_distance=4px)
+
+        if len(pairs) > 0:
+            # This is text! Count pairs = text lines
+            text_line_count = len(pairs)
+
+            # Analyze each pair
+            for pair in pairs:
+                thickness = measure_line_thickness(pair)
+                spacing = measure_spacing_between_pairs(pairs)
+
+                font_weight = thickness_to_weight(thickness)
+                font_size = spacing_to_size(spacing)
+
+            return route_to("heading-text.md", {
+                "line_count": text_line_count,
+                "font_weight": font_weight,
+                "font_size_estimate": font_size
+            })
+
+        elif len(lines) == 1:
+            # Single line = decorative element
+            return {
+                "type": "decorative_line",
+                "purpose": "divider or border"
+            }
+
+    # Step 2: Check for other object types
+    if has_button_shape(sketch_element):
+        return route_to("button.md")
+
+    if has_input_box_shape(sketch_element):
+        return route_to("text-input.md")
+
+    if has_image_placeholder(sketch_element):
+        return route_to("image.md")
+
+    # ... etc
+```
+
+---
+
+## Examples from Dog Week
+
+### Example 1: Hero Headline
+
+**Sketch:**
+
+```
+═══════════════════════════════  ← Thick pair detected
+═══════════════════════════════
+```
+
+**Detection:**
+
+- ✅ **Pair detected** → This is TEXT
+- **Route to:** `heading-text.md` for detailed analysis
+
+**For complete analysis of thickness, spacing, size, see:** `SKETCH-TEXT-ANALYSIS-GUIDE.md`
+
+---
+
+### Example 2: Supporting Paragraph
+
+**Sketch:**
+
+```
+─────────────────────────────────────────  ← Thin pairs detected
+─────────────────────────────────────────
+
+─────────────────────────────────────────
+─────────────────────────────────────────
+```
+
+**Detection:**
+
+- ✅ **2 pairs detected** → This is TEXT (2 lines)
+- **Route to:** `heading-text.md` for detailed analysis
+
+**For complete analysis of thickness, spacing, size, see:** `SKETCH-TEXT-ANALYSIS-GUIDE.md`
+
+---
+
+### Example 3: Divider Line (NOT TEXT)
+
+**Sketch:**
+
+```
+Section 1 content...
+
+───────────────────────────────────────── ← Single line
+
+Section 2 content...
+```
+
+**Detection:**
+
+- ❌ **Single line detected** (no pair) → NOT text
+- **Type:** Decorative `<hr>` element
+
+---
+
+## Key Takeaways
+
+### Detection Rules (This File)
+
+1. **Text markers ALWAYS come in pairs** (two lines = one text line)
+2. **Single lines are decorative** (dividers, borders, underlines)
+3. **Detect text FIRST** before checking for other object types
+4. **Count pairs to get text line count** (3 pairs = 3 lines of text)
+
+### Analysis Rules (See SKETCH-TEXT-ANALYSIS-GUIDE.md)
+
+5. **Line thickness → font weight**
+6. **Spacing between pairs → font size**
+7. **Line position → text alignment**
+8. **Line length → character capacity**
+
+---
+
+## Related Documentation
+
+- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** ← Complete analysis rules (MASTER GUIDE)
+- **`heading-text.md`** ← Text object instruction file (uses analysis rules)
+- **`SKETCH-TEXT-QUICK-REFERENCE.md`** ← Quick lookup table
+
+---
+
+**This file: DETECTION logic. For detailed ANALYSIS rules, see SKETCH-TEXT-ANALYSIS-GUIDE.md** 🎯