whiteport-design-studio 0.1.0

package/src/data/agent-guides/freya/specification-quality.md

@@ -0,0 +1,250 @@
+# Freya's Specification Quality Guide
+
+**When to load:** Before creating any page spec, component definition, or scenario documentation
+
+---
+
+## Core Principle
+
+**If I can't explain it logically, it's not ready to specify.**
+
+Gaps in logic become bugs in code. Clear specifications = confident implementation.
+
+---
+
+## The Logical Explanation Test
+
+Before you write any specification, ask:
+
+**"Can I explain WHY this exists and HOW it works without hand-waving?"**
+
+- ✅ "This button triggers the signup flow, serving users who want to feel prepared (driving force)"
+- ❌ "There's a button here... because users need it?"
+
+**If you can't explain it clearly, stop and think deeper.**
+
+---
+
+## Area Label Structure & Hierarchy
+
+**Area Labels follow a consistent hierarchical pattern to identify UI locations across sketch, specification, and code.**
+
+### Structural Area Labels (Containers)
+These define the page architecture and visual grouping:
+
+- `{page-name}-page` - Top-level page wrapper
+- `{page-name}-header` - Header section container
+- `{page-name}-main` - Main content area
+- `{page-name}-form` - Form element wrapper
+- `{page-name}-{section}-section` - Section containers
+- `{page-name}-{section}-header-bar` - Section header bars
+
+**Purpose:** Organize page structure, enable Figma layer naming (via aria-label), support testing selectors (via id attribute)
+
+### Interactive Area Labels (Components)
+These identify specific interactive elements:
+
+- `{page-name}-{section}-{element}` - Standard pattern
+- `{page-name}-input-{field}` - Form inputs
+- `{page-name}-button-{action}` - Buttons
+- `{page-name}-error-{field}` - Error messages
+
+**Purpose:** Enable user interaction, form validation, accessibility, and location tracking across design and code
+
+**Note:** Area Labels become both `id` and `aria-label` attributes in HTML implementation.
+
+### Purpose-Based Naming
+
+**Name components by FUNCTION, not CONTENT**
+
+### Good (Function)
+- `hero-headline` - Describes its role on the page
+- `primary-cta` - Describes its function in the flow
+- `feature-benefit-section` - Describes what it does
+- `form-validation-error` - Describes when it appears
+
+### Bad (Content)
+- `welcome-message` - What if the message changes?
+- `blue-button` - What if we change colors?
+- `first-paragraph` - Position isn't purpose
+- `email-error-text` - Too specific, not reusable
+
+**Why this matters:**
+- Content changes, function rarely does
+- Makes specs maintainable
+- Helps developers understand intent
+- Enables component reuse
+- Supports Figma html.to.design layer naming
+
+---
+
+## Clear Component Purpose
+
+**Every component needs a clear job description:**
+
+### Template
+```markdown
+### [Component Name]
+
+**Purpose:** [What job does this do?]
+**Triggers:** [What user action/state causes this?]
+**Serves:** [Which driving force or goal?]
+**Success:** [How do we know it worked?]
+```
+
+### Example
+```markdown
+### Primary CTA Button
+
+**Purpose:** Initiate account creation flow
+**Triggers:** User clicks after reading value proposition
+**Serves:** User's desire to "feel prepared" (positive driving force)
+**Success:** User enters email and moves to step 2
+```
+
+---
+
+## Section-First Workflow
+
+**Understand the WHOLE before detailing the PARTS**
+
+### Wrong Approach (Bottom-Up)
+1. Design individual components
+2. Try to arrange them into sections
+3. Hope the page makes sense
+4. Realize it doesn't flow logically
+5. Start over
+
+### Right Approach (Top-Down)
+1. **Define structural containers** - Page, header, main, sections
+2. **Assign structural Area Labels** - `{page}-page`, `{page}-header`, etc.
+3. **Identify page sections** - What major areas exist?
+4. **Define section purposes** - Why does each section exist?
+5. **Confirm flow logic** - Does the story make sense?
+6. **Detail each section** - Now design components
+7. **Specify components** - With clear purpose and context
+8. **Assign interactive Area Labels** - `{page}-{section}-{element}`
+
+**Result:** Logical flow, no gaps, confident specifications, complete Area Label coverage
+
+### Area Label Coverage Checklist
+- [ ] Page container (`{page}-page`)
+- [ ] Header section (`{page}-header`)
+- [ ] Main content area (`{page}-main`)
+- [ ] Form container if applicable (`{page}-form`)
+- [ ] Section containers (`{page}-{section}-section`)
+- [ ] Section header bars if visible (`{page}-{section}-header-bar`)
+- [ ] All interactive elements (`{page}-{section}-{element}`)
+
+---
+
+## Multi-Language from the Start
+
+**Never design in one language only**
+
+### Grouped Translations
+```markdown
+#### Hero Headline
+
+**Content:**
+- EN: "Stop losing clients to poor proposals"
+- SE: "Sluta förlora kunder på dåliga offerter"
+- NO: "Slutt å miste kunder på dårlige tilbud"
+
+**Purpose:** Hook Problem Aware users by validating frustration
+```
+
+### Why This Matters
+- Prevents "English-first" bias
+- Reveals translation issues early
+- Shows if message works across cultures
+- Keeps translations coherent (grouped by component)
+
+---
+
+## Specification Quality Checklist
+
+Before marking a spec "complete":
+
+### Core Quality
+- [ ] **Logical Explanation** - Can I explain WHY and HOW?
+- [ ] **Purpose-Based Names** - Named by function, not content?
+- [ ] **Clear Purpose** - Every component has a job description?
+- [ ] **Section-First** - Whole page flows logically?
+- [ ] **Multi-Language** - All product languages included?
+- [ ] **No Hand-Waving** - No "probably" or "maybe" or "users will figure it out"?
+
+### Area Labels
+- [ ] **Structural Area Labels** - Page, header, main, sections all have labels?
+- [ ] **Interactive Area Labels** - All buttons, inputs, links have labels?
+- [ ] **Area Label Hierarchy** - Labels follow `{page}-{section}-{element}` pattern?
+- [ ] **Figma-Ready** - Area Labels support html.to.design layer naming?
+
+### Accessibility
+- [ ] **ARIA Labels** - All interactive elements have aria-label attributes?
+- [ ] **Alt Text** - All images have descriptive alt attributes?
+- [ ] **Form Labels** - All inputs have associated labels?
+- [ ] **Keyboard Navigation** - Tab order and focus management documented?
+- [ ] **Screen Reader Support** - Semantic HTML and ARIA attributes specified?
+- [ ] **Color Contrast** - WCAG AA compliance (4.5:1 for text)?
+- [ ] **Error Announcements** - Error messages accessible to screen readers?
+- [ ] **Heading Hierarchy** - Logical H1-H6 structure documented?
+
+### Content Completeness
+- [ ] **All Text Defined** - No placeholder content?
+- [ ] **Error Messages** - All error states have messages in all languages?
+- [ ] **Success Messages** - Confirmation messages defined?
+- [ ] **Empty States** - Messages for no-data scenarios?
+- [ ] **Loading States** - Loading indicators and messages?
+- [ ] **Meta Content** - Page title and meta description for public pages?
+- [ ] **Social Sharing** - Social media title, description, and image for public pages?
+
+### Implementation Ready
+- [ ] **Developer-Ready** - Could someone build this confidently?
+- [ ] **Component References** - All design system components linked?
+- [ ] **API Endpoints** - Data requirements documented?
+- [ ] **Validation Rules** - Form validation clearly specified?
+
+---
+
+## Red Flags (Stop and Rethink)
+
+🚩 **Vague language:** "Something here to help users understand..."  
+🚩 **Content-based names:** "blue-box", "top-paragraph"  
+🚩 **Missing purpose:** "There's a button... because buttons are good?"  
+🚩 **Illogical flow:** "This section comes after that one... because?"  
+🚩 **English-only:** "We'll translate later..."  
+🚩 **Gaps in logic:** "Users will just know what to do here"  
+🚩 **Missing accessibility:** "We'll add ARIA labels during development..."  
+🚩 **No alt text:** Images without descriptive alternatives  
+🚩 **Unlabeled inputs:** Form fields without associated labels
+
+**When you spot these, pause and dig deeper.**
+
+---
+
+## The Developer Trust Test
+
+**Imagine handing your spec to a developer who:**
+- Has never seen your sketches
+- Doesn't know the business context
+- Speaks a different language
+- Lives in a different timezone
+
+**Could they build this confidently?**
+
+- ✅ Yes → Good spec
+- ❌ No → More work needed
+
+---
+
+## Related Resources
+
+- **File Naming:** `../../workflows/00-system/FILE-NAMING-CONVENTIONS.md`
+- **Language Config:** `../../workflows/00-system/language-configuration-guide.md`
+- **Page Spec Template:** `../../workflows/4-ux-design/templates/page-specification.template.md`
+
+---
+
+*Quality specifications are the foundation of confident implementation.*
+

package/src/data/agent-guides/freya/strategic-design.md

@@ -0,0 +1,118 @@
+# Freya's Strategic Design Guide
+
+**When to load:** Before designing any page, component, or user flow
+
+---
+
+## Core Principle
+
+**Every design decision connects to strategy.** Never design in a vacuum.
+
+---
+
+## Before You Design Anything
+
+### 1. Load Strategic Context
+
+**Ask yourself:**
+- Is there a VTC (Value Trigger Chain) for this page/scenario?
+- What's in the Trigger Map?
+- What does the Product Brief say?
+
+**If missing:** Suggest creating one first. Design without strategy is decoration.
+
+---
+
+### 2. Connect to Business Goals
+
+**Every major design choice should answer:**
+- Which business goal does this serve?
+- How does this move the needle on our success metrics?
+
+**Example:**
+- ❌ "Let's make this button blue because it's pretty"
+- ✅ "This CTA should be prominent because it serves the 'Convert Problem Aware users' goal"
+
+---
+
+### 3. Identify User Driving Forces
+
+**From the VTC/Trigger Map, ask:**
+- What positive driving forces should we trigger? (wishes, desires, aspirations)
+- What negative driving forces should we address? (fears, frustrations, anxieties)
+
+**Example:**
+- User wants to "feel like an industry expert"
+- User fears "looking unprofessional to clients"
+- Design should make them feel capable, not overwhelmed
+
+---
+
+### 4. Customer Awareness Stage
+
+**Where are users in their journey?**
+
+1. **Unaware** - Don't know they have a problem → Educate on problem
+2. **Problem Aware** - Know the problem, not solutions → Show there are solutions
+3. **Solution Aware** - Know solutions exist → Show why yours is different
+4. **Product Aware** - Know your product → Remove friction, show proof
+5. **Most Aware** - Ready to buy/use → Make it easy, reinforce decision
+
+**Design implications:**
+- Unaware users need more context, education
+- Most Aware users need less explanation, more action
+
+---
+
+### 5. Content Hierarchy (Golden Circle)
+
+**Structure content as:** WHY → HOW → WHAT
+
+- **WHY** - Purpose, benefit, emotional hook (first)
+- **HOW** - Process, approach, differentiation (second)
+- **WHAT** - Features, specifics, details (last)
+
+**Example:**
+```
+Hero Section:
+├── Headline (WHY): "Stop losing clients to competitors with better proposals"
+├── Subhead (HOW): "Create stunning proposals in minutes with AI-powered templates"
+└── Features (WHAT): "10,000+ templates, Smart pricing, E-signatures"
+```
+
+---
+
+## Strategic Design Checklist
+
+Before finalizing any design:
+
+- [ ] **VTC Connection** - Which driving force does this serve?
+- [ ] **Business Goal** - How does this support our objectives?
+- [ ] **Customer Awareness** - Appropriate for their awareness stage?
+- [ ] **Golden Circle** - WHY before HOW before WHAT?
+- [ ] **Logical Explanation** - Can I defend this decision strategically?
+
+---
+
+## When You're Stuck
+
+**If you can't connect a design choice to strategy:**
+1. It might not be needed (remove it)
+2. You need more strategic context (ask for VTC/Trigger Map)
+3. There's a better alternative (explore options)
+
+**Never guess.** Always design with intent.
+
+---
+
+## Related Resources
+
+- **VTC Workshop:** `../../workflows/shared/vtc-workshop/`
+- **Trigger Mapping:** `../../docs/method/phase-2-trigger-mapping-guide.md`
+- **Customer Awareness:** `../../docs/models/customer-awareness-cycle.md`
+- **Golden Circle:** `../../docs/models/golden-circle.md`
+
+---
+
+*Strategic design is what makes WDS different. Every pixel has a purpose.*
+