whiteport-design-studio 0.1.0

package/src/workflows/5-design-system/assessment/06-present-decision.md

@@ -0,0 +1,435 @@
+# Assessment Step 6: Present Decision
+
+**Purpose:** Present complete analysis to designer for informed decision.
+
+**Input:** Comparison, opportunities, and risks
+
+**Output:** Clear decision options with trade-offs
+
+---
+
+## Presentation Structure
+
+### 1. Context Summary
+
+What we're deciding and why
+
+### 2. The Options
+
+Clear description of each choice
+
+### 3. Comparison Table
+
+Side-by-side trade-offs
+
+### 4. Recommendation
+
+AI's suggestion based on analysis
+
+### 5. Designer Choice
+
+Let designer decide
+
+---
+
+## Step 1: Present Context
+
+<output>
+```
+🔍 Design System Decision Needed
+
+**Current Component:** Navigation Button
+**Similar Component Found:** Button [btn-001]
+**Similarity:** 72% (High)
+
+**Key Similarities:**
+✓ Visual appearance (size, shape, color)
+✓ Primary action purpose
+✓ Standard states
+
+**Key Differences:**
+✗ Navigation vs submission purpose
+✗ Has icon and loading state
+✗ Different usage context
+
+**Decision:** How should we handle this in the design system?
+
+```
+</output>
+
+---
+
+## Step 2: Present Options
+
+<output>
+```
+
+📋 Your Options:
+
+**Option 1: Reuse Existing Component**
+Use Button [btn-001], just change the label to "Continue"
+
+**Option 2: Add Variant**
+Add "navigation" variant to Button [btn-001]
+
+- Button.primary (submit)
+- Button.navigation (continue)
+
+**Option 3: Create New Component**
+Create separate "Navigation Button" component [btn-002]
+
+```
+</output>
+
+---
+
+## Step 3: Present Trade-Offs Table
+
+<output>
+```
+
+📊 Trade-Offs Comparison:
+
+┌─────────────┬──────────────────┬──────────────────┬──────────────────┐
+│ │ Reuse [btn-001] │ Add Variant │ Create New │
+├─────────────┼──────────────────┼──────────────────┼──────────────────┤
+│ Consistency │ ✅ Highest │ ✅ High │ ⚠️ Medium │
+│ Maintenance │ ✅ Easiest │ ⚠️ Moderate │ ❌ More work │
+│ Clarity │ ❌ Confusing │ ⚠️ Moderate │ ✅ Clearest │
+│ Flexibility │ ❌ Constrained │ ✅ Flexible │ ✅ Independent │
+│ Complexity │ ✅ Simple │ ⚠️ More complex │ ✅ Simple │
+│ Semantics │ ❌ Lost │ ⚠️ Preserved │ ✅ Clear │
+├─────────────┼──────────────────┼──────────────────┼──────────────────┤
+│ Best For │ Identical use │ Related purposes │ Different roles │
+└─────────────┴──────────────────┴──────────────────┴──────────────────┘
+
+Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue
+
+```
+</output>
+
+---
+
+## Step 4: Present Detailed Analysis
+
+<output>
+```
+
+🔍 Detailed Analysis:
+
+**Option 1: Reuse Button [btn-001]**
+
+Opportunities:
+✅ Perfect visual consistency
+✅ Single source of truth
+✅ Easiest to maintain
+✅ Simplest design system
+
+Risks:
+❌ HIGH: Semantic confusion (navigation looks like submission)
+❌ HIGH: Accessibility issues (same component, different actions)
+❌ MEDIUM: Developer confusion
+❌ MEDIUM: Future constraint
+
+Verdict: ⚠️ Not recommended due to semantic/accessibility risks
+
+---
+
+**Option 2: Add "Navigation" Variant to Button [btn-001]**
+
+Opportunities:
+✅ Maintains button family
+✅ Flexible for different use cases
+✅ Easy to add more variants
+✅ All buttons documented together
+
+Risks:
+❌ HIGH: Variant explosion (could lead to 10+ variants)
+⚠️ MEDIUM: Component complexity increases
+⚠️ MEDIUM: Maintenance burden grows
+⚠️ LOW: Documentation overhead
+
+Mitigation: Strict variant guidelines can manage explosion risk
+
+Verdict: ✅ Viable option if you expect more button types
+
+---
+
+**Option 3: Create New "Navigation Button" [btn-002]**
+
+Opportunities:
+✅ Clear semantic distinction
+✅ Optimized for navigation use case
+✅ Independent evolution
+✅ Simple component definition
+
+Risks:
+⚠️ MEDIUM: Visual inconsistency over time
+⚠️ MEDIUM: More components to manage
+⚠️ LOW: Some code duplication
+⚠️ LOW: Developer choice overhead
+
+Mitigation: Shared design tokens ensure visual consistency
+
+Verdict: ✅ Safest option, especially for semantically different purposes
+
+```
+</output>
+
+---
+
+## Step 5: Present AI Recommendation
+
+<action>
+Based on analysis, provide recommendation with reasoning
+</action>
+
+<output>
+```
+
+🤖 AI Recommendation: Create New Component (Option 3)
+
+**Reasoning:**
+
+1. **Semantic Distinction Matters**
+   - Navigation and submission are fundamentally different actions
+   - Users and developers benefit from clear distinction
+   - Accessibility is better with separate components
+
+2. **Manageable Risks**
+   - Visual inconsistency can be prevented with shared tokens
+   - Duplication is minimal and acceptable
+   - Proliferation can be monitored
+
+3. **Future Flexibility**
+   - Each component can evolve independently
+   - No risk of variant explosion
+   - Clear component boundaries
+
+4. **Your Project Context**
+   - Design system is new (only 3 components)
+   - Better to establish clear patterns now
+   - Easier to merge later than split
+
+**However:** If you expect many button types (delete, cancel, save, etc.),
+Option 2 (variant) might be better for organization.
+
+```
+</output>
+
+---
+
+## Step 6: Ask for Designer Decision
+
+<ask>
+```
+
+💭 Your Decision:
+
+Based on this analysis, which approach fits your design intent?
+
+[1] Reuse Button [btn-001]
+→ Choose if: Visual consistency is paramount, purposes are actually the same
+
+[2] Add "navigation" variant to Button [btn-001]
+→ Choose if: You want button family, expect more button types
+
+[3] Create new "Navigation Button" [btn-002]
+→ Choose if: Semantic distinction matters, want independence
+
+[4] I need more information
+→ I can clarify any aspect of the analysis
+
+Your choice (1/2/3/4):
+
+```
+</ask>
+
+---
+
+## Step 7: Handle Designer Response
+
+<action>
+Based on designer's choice, route to appropriate operation
+</action>
+
+**If Choice 1 (Reuse):**
+```
+
+✅ Got it - reusing Button [btn-001]
+
+I'll update the page spec to reference the existing component.
+
+```
+**Route to:** `07-execute-decision.md` with action: `reuse`
+
+**If Choice 2 (Variant):**
+```
+
+✅ Got it - adding "navigation" variant to Button [btn-001]
+
+I'll update the component definition and create the reference.
+
+```
+**Route to:** `07-execute-decision.md` with action: `add_variant`
+
+**If Choice 3 (New):**
+```
+
+✅ Got it - creating new Navigation Button [btn-002]
+
+I'll create the new component and set up the reference.
+
+```
+**Route to:** `07-execute-decision.md` with action: `create_new`
+
+**If Choice 4 (More Info):**
+```
+
+📚 What would you like to know more about?
+
+- Similarity calculation details
+- Specific opportunities or risks
+- How variants work
+- Component boundaries
+- Something else
+
+Your question:
+
+```
+**Provide clarification, then re-present decision**
+
+---
+
+## Presentation Variations
+
+### For High Similarity (80%+)
+
+<output>
+```
+
+✨ These components are very similar!
+
+Similarity: 87%
+
+The main question is: Are they the same thing with different content,
+or different things that happen to look similar?
+
+If same thing → Reuse
+If different things → Variant or New
+
+```
+</output>
+
+### For Low Similarity (40%-)
+
+<output>
+```
+
+⚠️ These components are quite different.
+
+Similarity: 38%
+
+They share a type (Button) but serve different purposes.
+Creating a new component is likely the best choice.
+
+Would you like to proceed with creating a new component,
+or would you like to see the full analysis?
+
+```
+</output>
+
+### For Borderline Cases
+
+<output>
+```
+
+🤔 This is a borderline case.
+
+Similarity: 64% (right between "High" and "Medium")
+
+This could go either way. I'll present both perspectives:
+
+**Perspective 1: Similar Enough**
+[Present variant option]
+
+**Perspective 2: Different Enough**
+[Present new component option]
+
+Your design philosophy will guide this decision.
+
+```
+</output>
+
+---
+
+## Edge Cases
+
+**Designer asks for recommendation:**
+```
+
+Based on the analysis, I recommend Option 3 (Create New).
+
+But this is your design system - you know your project best.
+
+What's most important to you?
+
+- Consistency? → Reuse or Variant
+- Clarity? → New
+- Flexibility? → Variant
+- Simplicity? → Reuse or New
+
+```
+
+**Designer is unsure:**
+```
+
+That's okay! This is a judgment call.
+
+Here's a simple heuristic:
+
+If a developer saw both buttons, would they think:
+A) "Same button, different label" → Reuse
+B) "Related buttons, different purposes" → Variant
+C) "Different buttons entirely" → New
+
+What's your gut feeling?
+
+```
+
+**Designer wants to defer decision:**
+```
+
+✅ No problem!
+
+I'll create it as a new component for now.
+
+You can always:
+
+- Merge it later if you decide they're the same
+- Convert it to a variant if you see a pattern
+- Keep it separate if the distinction is valuable
+
+Design systems evolve - this isn't permanent.
+
+````
+
+---
+
+## Output Format
+
+**For next step:**
+```json
+{
+  "decision": {
+    "choice": "create_new",
+    "component_id": "btn-002",
+    "reasoning": "Semantic distinction matters",
+    "designer_notes": "Navigation and submission are different actions"
+  }
+}
+````
+
+---
+
+**This step presents and captures the decision. Execution happens in the next step.**