Wds 0 Project Setup

Follow the instructions in ./workflow.md.

Freya's Design System Guide

When to load: When Phase 7 (Design System) is enabled and component questions arise

---

Core Principle

Design systems grow organically - discover components through actual work, never create speculatively.

---

Three Design System Modes

Mode A: No Design System

What it means:

• All components stay page-specific
• No component extraction
• AI/dev team handles consistency
• Faster for simple projects

When this workflow doesn't run:

• Phase 7 is disabled
• Components reference page context only

Agent behavior:

• Create components as page-specific
• Use clear, descriptive class names
• No need to think about reusability

---

Mode B: Custom Figma Design System

What it means:

• Designer defines components in Figma
• Components extracted as discovered during Phase 4
• Figma MCP endpoints for integration
• Component IDs link spec ↔ Figma

Workflow: 1. Designer creates component in Figma 2. Component discovered during page design 3. Agent links to Figma via Component ID 4. Specification references Figma source

See: skill:wds-6-asset-generation → workflow-figma.md

---

Mode C: Component Library Design System

What it means:

• Uses shadcn/Radix/similar library
• Library chosen during setup
• Components mapped to library defaults
• Variants customized as needed

Workflow: 1. Component needed during page design 2. Check if library has it (button, input, card, etc.) 3. Map to library component 4. Document customizations (if any)

---

The Design System Router

Runs automatically during Phase 4 component specification

For each component: 1. Check: Design system enabled? (Mode B or C) 2. If NO → Create page-specific, continue 3. If YES → Call design-system-router.md

Router asks:

• Is this component new?
• Is there a similar component?
• Should we create new or use/extend existing?

See: skill:wds-7-design-system → design-system-router.md

---

Never Create Components Speculatively

❌ Wrong Approach

"Let me create a full component library upfront..."

Why bad:

• You don't know what you'll actually need
• Over-engineering
• Wasted effort on unused components

---

✅ Right Approach

"I'm designing the landing page hero... oh, I need a button."

Process: 1. Design the button for this specific page 2. When another page needs a button → Opportunity! 3. Assess: Similar enough to extract? 4. Extract to Design System if makes sense

Result: Components emerge from real needs.

---

Opportunity/Risk Assessment

When similar component exists, run assessment:

See: skill:wds-7-design-system → assessment/

7 Micro-Steps: 1. Scan existing components 2. Compare attributes (visual, behavior, states) 3. Calculate similarity score 4. Identify opportunities (reuse, consistency) 5. Identify risks (divergence, complexity) 6. Present decision to designer 7. Execute decision

Outcomes:

• Use existing - Component is close enough
• Create variant - Extend existing with new state
• Create new - Too different, warrants separate component
• Update existing - Existing is too narrow, expand it

---

Foundation First

Before any components:

1. Design Tokens

Design tokens = the DNA of your design system

Colors:
- Primary, secondary, accent
- Neutral scale (50-900)
- Semantic (success, warning, error, info)

Typography:
- Font families
- Font scales (h1-h6, body, caption)
- Font weights
- Line heights

Spacing:
- Spacing scale (xs, sm, md, lg, xl)
- Layout scales

Effects:
- Border radius scale
- Shadow scale
- Transitions

Why first: Tokens ensure consistency across all components.

---

2. Atomic Design Structure

Organize from simple → complex:

atoms/
├── button.md
├── input.md
├── label.md
├── icon.md
└── badge.md

molecules/
├── form-field.md (label + input + error)
├── card.md (container + content)
└── search-box.md (input + button + icon)

organisms/
├── header.md (logo + nav + search + user-menu)
├── feature-section.md (headline + cards + cta)
└── form.md (multiple form-fields + submit)

Why this structure: Clear dependencies, easy to understand, scales well.

---

Component Operations

See: skill:wds-7-design-system → operations/

1. Initialize Design System

First component triggers auto-initialization

• Creates folder structure
• Creates design-tokens.md
• Creates component-library-config.md (if Mode C)

2. Create New Component

• Defines component specification
• Assigns Component ID
• Documents states and variants
• Notes where used

3. Add Variant

• Extends existing component
• Documents variant trigger
• Updates component spec

4. Update Component

• Modifies existing definition
• Increments version
• Documents change rationale

---

Component Specification Template

# [Component Name] [COMP-001]

**Type:** [Atom|Molecule|Organism]
**Library:** [shadcn Button|Custom|N/A]
**Figma:** [Link if Mode B]

## Purpose
[What job does this component do?]

## Variants
- variant-name: [When to use]
- variant-name: [When to use]

## States
- default
- hover
- active
- disabled
- loading (if applicable)
- error (if applicable)

## Props/Attributes
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| size | sm\|md\|lg | md | Button size |
| variant | primary\|secondary | primary | Visual style |

## Styling
[Design tokens or Figma reference]

## Used In
- [Page name] ([Component purpose in context])
- [Page name] ([Component purpose in context])

## Version History
- v1.0.0 (2024-01-01): Initial creation

---

Integration with Phase 4

Phase 4 (UX Design) → Phase 7 (Design System) flow:

User creates page specification
├── Component 1: Button
│   ├── Check: Design system enabled?
│   ├── YES → Router checks existing components
│   ├── Similar button found → Opportunity/Risk Assessment
│   └── Decision: Use existing primary button variant
├── Component 2: Input
│   ├── Check: Design system enabled?
│   ├── YES → Router checks existing components
│   ├── No similar input → Create new
│   └── Add to Design System
└── Component 3: Custom illustration
    ├── Check: Design system enabled?
    └── NO extraction (one-off asset)

Result:

• Page spec contains references + page-specific content
• Design System contains component definitions
• Clean separation maintained

---

Common Mistakes

❌ Creating Library Before Designing

"Let me make 50 components upfront..."

• Instead: Design pages, extract components as needed

❌ Over-Abstracting Too Early

"This button might need 10 variants someday..."

• Instead: Start simple, add variants when actually needed

❌ Forcing Reuse

"I'll make this work even though it's awkward..."

• Instead: Sometimes a new component is better than a forced variant

❌ No Design Tokens

"I'll define colors per component..."

• Instead: Tokens first, components second

---

Quality Checklist

Before marking a component "complete":

• [ ] Clear purpose - What job does it do?
• [ ] Design tokens - Uses tokens, not hard-coded values?
• [ ] All states - Default, hover, active, disabled documented?
• [ ] Variants - Each variant has clear use case?
• [ ] Reusability - Can be used in multiple contexts?
• [ ] Documentation - Specification is complete?
• [ ] Examples - Shows where it's actually used?

---

Related Resources

• Phase 7 Workflow: skill:wds-7-design-system
• Figma Integration: skill:wds-6-asset-generation → workflow-figma.md
• Shared Knowledge: design-system data (tokens, naming, states, validation, boundaries)

---

Components emerge from real needs. Design systems grow organically.

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

### [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

### 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

#### 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?

SEO (Public Pages)

• [ ] H1 Present - Exactly one H1 on the page, contains primary keyword?
• [ ] Heading Hierarchy - Logical H1 → H2 → H3, no skipped levels?
• [ ] URL Slug - Defined, keyword-rich, matches project brief keyword map?
• [ ] Primary Keyword - Identified and placed in H1, title tag, meta description?
• [ ] Meta Title - ≤ 60 chars, includes primary keyword + brand?
• [ ] Meta Description - 150-160 chars, includes keyword + CTA?
• [ ] Image Alt Text - All images have descriptive alt text in all languages?
• [ ] Internal Links - At least 2 links to other pages on the site?
• [ ] Structured Data - Schema type specified per project brief plan?

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 🚩 No SEO section: Public page without URL slug, keywords, or meta content

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: skill:wds-0-project-setup → FILE-NAMING-CONVENTIONS.md
• Language Config: skill:wds-0-project-setup → language-configuration-guide.md
• Page Spec Template: ./resources/wds-4-ux-design/templates/page-specification.template.md

---

Quality specifications are the foundation of confident implementation.

Project Info: {{project_name}}

Created: {{date}} Project Type: {{project_type}} Design Experience: {{design_experience}} Status: In progress

---

Team

Project Lead: {{user_name}} Communication Language: {{communication_language}} Document Output Language: {{document_output_language}}

---

Project Configuration

Output Folder: {{output_folder}}/ WDS System Folder: {{wds_folder}}/

Configuration stored in: {{wds_folder}}/config.yaml

---

Quick Navigation

Product Brief (Phase 1):

• 01 — Product Brief
• 02 — Content Language
• 03 — Visual Direction
• 04 — Platform Requirements

Trigger Map (Phase 2):

• 00 — Trigger Map Overview

UX Scenarios (Phase 4):

• UX Scenarios Guide

Design System (Phase 7):

• 00 — Design System Overview

---

Project Timeline

---

Technical Stack

Frontend: TBD Backend: TBD Hosting: TBD Languages: {{document_output_language}}

---

WDS Agents

To activate agents, tell Claude:

Read and activate the agent in `{{wds_folder}}/agents/[agent-name].md`

Available:

• Saga — Product Brief, Trigger Mapping & Platform Requirements
• Freya — UX Design, Design System, Testing & Product Evolution

---

Generated by Whiteport Design Studio installer

Content & Language: {{project_name}}

Tone of Voice & Content Guidelines

Created: {{date}} Author: {{user_name}} Related: Product Brief

---

Brand Personality

{{brand_personality_summary}}

Personality Attributes

{{#each personality_attributes}} | {{this.attribute}} | {{this.description}} | {{this.expression}} | {{/each}}

---

Tone of Voice

Core Tone

Primary Tone: {{primary_tone}}

{{tone_description}}

Tone Spectrum

We Say / We Don't Say

We say: {{#each we_say}}

• {{this}}

{{/each}}

We don't say: {{#each we_dont_say}}

• {{this}}

{{/each}}

---

Language Strategy

Supported Languages

{{#each languages}} | {{this.language}} | {{this.priority}} | {{this.coverage}} | {{this.notes}} | {{/each}}

Translation Approach

{{translation_approach}}

Localization Notes

{{#each localization_notes}}

• {{this.language}}: {{this.note}}

{{/each}}

---

Content Types

UI Microcopy

Buttons, labels, error messages, system feedback

Guidelines: {{#each microcopy_guidelines}}

• {{this}}

{{/each}}

Examples:

{{#each microcopy_examples}} | {{this.context}} | {{this.do}} | {{this.dont}} | {{/each}}

Marketing Content

Headlines, feature descriptions, value propositions

Guidelines: {{#each marketing_guidelines}}

• {{this}}

{{/each}}

Informational Content

Service descriptions, about pages, FAQs

Guidelines: {{#each informational_guidelines}}

• {{this}}

{{/each}}

---

SEO Strategy

Page-Keyword Map

| Page | URL Slug | Primary Keyword (SE) | Primary Keyword (EN) | {{#if has_german}}Primary Keyword (DE) |{{/if}} |------|----------|---------------------|---------------------|{{#if has_german}}---------------------|{{/if}} {{#each page_keyword_map}} | {{this.page}} | {{this.slug}} | {{this.keyword_se}} | {{this.keyword_en}} | {{#if ../has_german}}{{this.keyword_de}} |{{/if}} {{/each}}

URL Structure

Pattern:

{{url_primary}}          → {{primary_language}}
{{url_secondary}}        → {{secondary_language}}
{{#if url_tertiary}}
{{url_tertiary}}         → {{tertiary_language}}
{{/if}}

Primary Keywords (by language)

{{#each seo_keywords_by_language}} {{this.language}}: {{#each this.keywords}}

• {{this}}

{{/each}}

{{/each}}

Local SEO

{{#if is_local_business}}

{{else}} Not a local business — skip this section {{/if}}

Structured Data Plan

{{#each structured_data_plan}} | {{this.page_type}} | {{this.schema_type}} | {{this.properties}} | {{/each}}

Keyword Usage Guidelines

{{keyword_usage_guidelines}}

---

Content Structure Principles

Structure Type

{{structure_type}}

User's Vision

{{users_vision}}

Content Priorities

Must be prominent (visible immediately): {{#each must_be_prominent}}

• {{this}}

{{/each}}

Important but secondary: {{#each secondary_content}}

• {{this}}

{{/each}}

Navigation Principles

{{#each navigation_principles}}

• {{this}}

{{/each}}

Not Included

{{#each not_included}}

• {{this}}

{{/each}}

Clarity Level

{{clarity_level}}

---

Content Ownership

{{#each content_ownership}} | {{this.type}} | {{this.owner}} | {{this.frequency}} | {{/each}}

---

Writing Checklist

Before publishing any content, verify:

{{#each writing_checklist}}

• [ ] {{this}}

{{/each}}

---

Next Steps

• [ ] Visual Direction — Establish visual style and brand
• [ ] Phase 2: Trigger Mapping — Connect content to user psychology
• [ ] Phase 4: UX Design — Apply tone to interface copy

---

_Generated by Whiteport Design Studio_

Project Contract

Project: {{project_name}} Date: {{date}} Client: {{client_name}} Contractor: {{contractor_name}} Contract Language: {{contract_language}} Governing Law/Jurisdiction: {{governing_jurisdiction}}

---

Contract Philosophy: This contract is designed to be simple, fair, and clear - providing reliable terms that support a long-lasting working relationship between both parties.

---

1. Project Overview

The Realization

{{realization}}

Recommended Solution

{{recommended_solution}}

---

2. Business Model

Selected Model: {{business_model}}

{{business_model_description}}

{{business_model_terms}}

---

3. Scope of Work

The Path Forward

{{path_forward}}

Deliverables

Based on the path forward, the following deliverables will be provided:

{{deliverables_list}}

In Scope

The following work is explicitly included in this contract:

{{in_scope}}

Out of Scope

The following work is explicitly NOT included in this contract:

{{out_of_scope}}

Note: Any work outside the scope defined above requires a written Change Order (see Section 10: Not to Exceed Clause).

---

4. Our Commitment

{{our_commitment}}

---

Payment Terms

Total Contract Amount: {{total_amount}}

Payment Structure: {{payment_structure}}

Payment Schedule: {{payment_schedule}}

Background: Clear payment terms protect both parties and ensure fair compensation.

What it does: Defines when and how payments will be made.

Purpose:

• Ensures supplier receives fair compensation for work
• Provides client with clear payment expectations
• Protects both parties from payment disputes
• For fixed-price contracts, upfront payment is fair since supplier assumes cost overrun risk

Payment Terms Details:

• Payment Method: {{payment_method}} (check, wire transfer, credit card, etc.)
• Payment Due Dates: {{payment_due_dates}}
• Late Payment: {{late_payment_terms}} (e.g., interest charges, work suspension)
• Payment Conditions: {{payment_conditions}} (e.g., payment required before work begins, payment tied to deliverables)

For Fixed-Price Contracts: This is a fixed-price contract, meaning the contractor commits to deliver specified work for the agreed price, regardless of actual costs. Since the contractor assumes the risk of cost overruns, upfront payment (50-100%) is standard and fair. This demonstrates client commitment and enables the contractor to deliver quality work without cash flow concerns.

---

5. Timeline

{{timeline}}

Note: Timeline is based on the work plan outlined above and may be adjusted based on project requirements.

---

6. Why It Matters

{{why_it_matters}}

---

7. Expected Outcomes

The Value We'll Create

{{value_we_create}}

---

8. Risks and Considerations

Cost of Inaction

{{cost_of_inaction}}

---

9. Confidentiality

Confidentiality Clause

Background: This clause protects sensitive information shared during the project.

What it does: Both parties agree to keep project information confidential.

Purpose: Protects proprietary information, business strategies, trade secrets, and sensitive data.

Terms:

Both parties agree to:

• Keep all project-related information confidential
• Not disclose project details to third parties without written consent
• Use confidential information solely for project purposes
• Return or destroy confidential materials upon project completion or termination
• Maintain confidentiality obligations even after project completion

Exceptions:

• Information already publicly known
• Information independently developed
• Information required by law to be disclosed

Duration: Confidentiality obligations shall remain in effect for [X] years after project completion.

---

10. Not to Exceed Clause

Budget Cap

Background: This clause sets a maximum budget limit.

What it does: States that total costs will not exceed a specified amount without prior written approval.

Purpose:

• Protects both parties from unexpected cost overruns
• Ensures budget control
• Prevents scope creep - Any work beyond the original scope requires approval and may affect the budget cap

Terms:

• Total project costs shall not exceed {{not_to_exceed_amount}} without prior written approval from {{client_name}}
• Any work that would exceed this amount must be approved in advance
• If additional work is needed, a change order must be signed before proceeding
• This cap includes all fees, expenses, and costs related to the project

Change Orders and Scope Control:

• Any changes to scope that affect cost must be documented in a written change order
• Change orders must be signed by both parties before work begins
• Change orders may adjust the not-to-exceed amount if agreed upon
• Scope creep prevention: Work outside the original scope (as defined in Section 2) requires a change order and approval before proceeding
• This clause helps prevent gradual expansion of project scope without proper authorization

---

11. Terms and Conditions

Work Initiation

When work begins: {{work_initiation_date_or_condition}}

Background: This clause specifies exactly when the contractor is authorized to begin work.

What it does: Defines the start date or conditions that must be met before work begins.

Purpose:

• Prevents unauthorized work before contract is fully executed
• Establishes clear timeline expectations
• Protects both parties by ensuring work only begins after proper authorization

Initiation conditions (select applicable):

• Upon full execution of this contract (signatures from both parties)
• On a specific date: {{specific_start_date}}
• Upon receipt of initial payment/deposit
• Upon written notice from {{client_name}}
• Other: {{custom_initiation_condition}}

Project Initiation

This project is initiated upon approval of the project pitch. Project initiation is considered complete upon stakeholder approval.

Next Steps

After contract approval: 1. Proceed to full Project Brief development 2. Execute work plan as outlined above 3. Deliverables will be provided according to the agreed timeline

Changes and Modifications

Any changes to scope, timeline, or investment must be agreed upon in writing by all parties.

Intellectual Property

Philosophy: Clear IP ownership prevents future disputes and protects both parties' interests.

All deliverables and work products created under this contract will be owned by {{client_name}} upon full payment, unless otherwise specified in writing. This ensures clarity and prevents misunderstandings about ownership rights.

Termination

Philosophy: Fair termination terms protect both parties while allowing for reasonable exit if needed.

Either party may terminate this agreement with [X] days written notice. Upon termination, payment is due for work completed to date. This ensures fair compensation for work done and reasonable notice for both parties to plan accordingly.

Dispute Resolution

Background: Defines how conflicts will be resolved if they arise.

What it does: Establishes the process for handling disagreements.

Purpose: Provides a clear path for resolving disputes without costly litigation when possible.

Method: {{dispute_resolution_method}} (mediation/arbitration/litigation)

Location: {{dispute_resolution_location}}

Any disputes arising from this contract shall be resolved through {{dispute_resolution_method}} in {{dispute_resolution_location}}.

---

Governing Law and Jurisdiction

Background: Determines which laws apply and where legal proceedings would take place.

What it does: Specifies the legal framework and court system that governs the contract.

Purpose: Provides legal clarity and predictability for both parties.

Governing Law: This contract shall be governed by and construed in accordance with the laws of {{governing_jurisdiction}}.

Jurisdiction: Any legal proceedings arising from this contract shall be subject to the exclusive jurisdiction of the courts of {{governing_jurisdiction}}.

Contract Language: This contract is executed in {{contract_language}}. In case of translation, the {{contract_language}} version shall prevail.

---

12. Approval

Client Approval:

Signature: _________________ Name: {{client_name}} Date: _______________

Contractor Approval:

Signature: _________________ Name: {{contractor_name}} Date: _______________

---

Appendix

Reference Documents

• Project Pitch: docs/wds-1-project-brief/pitch.md
• Project Brief: (To be created after contract approval)

---

This contract is based on the project pitch dated {{date}}.

Inspiration Analysis: {{project_name}}

Reference Site Analysis & Design Principles

Created: {{date}} Author: {{user_name}} Related: Product Brief | Visual Direction | Content & Language

---

Sites Analyzed

{{#each sites}}

{{this.name}}

URL: {{this.url}}

What Client Liked

{{#each this.liked}}

• {{this.element}} — {{this.why}}

{{/each}}

What Client Didn't Like

{{#each this.disliked}}

• {{this.element}} — {{this.why}}

{{/each}}

Adaptations Needed

{{#each this.adaptations}}

• {{this.element}} — {{this.modification}}

{{/each}}

Principles Extracted

{{#each this.principles}}

• {{this}}

{{/each}}

---

{{/each}}

Design Principles (Synthesized)

Layout

DO: {{#each layout_do}}

• {{this}}

{{/each}}

DON'T: {{#each layout_dont}}

• {{this}}

{{/each}}

Content Hierarchy

DO: {{#each content_do}}

• {{this}}

{{/each}}

DON'T: {{#each content_dont}}

• {{this}}

{{/each}}

Visual Style

DO: {{#each visual_do}}

• {{this}}

{{/each}}

DON'T: {{#each visual_dont}}

• {{this}}

{{/each}}

User Experience

DO: {{#each ux_do}}

• {{this}}

{{/each}}

DON'T: {{#each ux_dont}}

• {{this}}

{{/each}}

---

How to Use This Document

For Scenario Outlining (Phase 4): Reference layout patterns when designing user flows. Use navigation principles to inform site structure.

For Page Design (Phase 5): Use extracted principles as design checklist. Reference "What Client Liked" for visual direction. Avoid "What Client Didn't Like" patterns.

For Dream Up Self-Review: Check generated output against documented preferences. Each design principle is a self-review checkpoint.

---

_Generated by Whiteport Design Studio_

Project Pitch: {{project_name}}

Compelling case for why this project matters and should be built

Created: {{date}} Author: {{user_name}} Status: Ready for stakeholder approval

---

1. The Realization

{{realization}}

---

2. Why It Matters

{{why_it_matters}}

---

3. How We See It Working

{{how_we_see_it_working}}

---

4. Paths We Explored

{{paths_we_explored}}

---

5. Recommended Solution

{{recommended_solution}}

---

6. The Path Forward

{{path_forward}}

---

7. The Value We'll Create

{{value_we_create}}

---

8. Cost of Inaction

{{cost_of_inaction}}

---

9. Our Commitment

{{our_commitment}}

---

10. Summary

{{summary}}

---

Business Context

This project serves:

• Primary Goal: {{business_goal}}
• Solution: {{solution}}
• Target Users: {{target_users}}

Detailed strategic analysis (personas, driving forces, prioritization) is developed in Phase 2: Trigger Mapping.

---

Next Steps

After approval, proceed to:

• Full Project Brief - Detailed strategic foundation
• Trigger Mapping - User research and personas
• Platform Requirements - Technical foundation
• UX Design - Scenarios and prototypes

---

_Generated by Whiteport Design Studio_

Platform Requirements: {{project_name}}

Technical Boundaries & Platform Decisions

Created: {{date}} Author: {{user_name}} Related: Product Brief

---

Technology Stack

Core Platform

CMS/Framework: {{cms_framework}} Approach: {{tech_approach}}

{{tech_approach_details}}

Key Technologies

---

Plugin/Package Stack

{{#if plugins}}

{{#each plugins}} | {{this.name}} | {{this.purpose}} | {{this.status}} | {{/each}} {{else}} To be determined during development {{/if}}

---

Integrations

Required Integrations

{{#each integrations}}

• {{this.name}}: {{this.purpose}}

{{/each}}

Future Integrations

{{#each future_integrations}}

• {{this.name}}: {{this.purpose}} ({{this.timeline}})

{{/each}}

---

Contact Strategy

Primary Contact Method

{{contact_strategy}}

Contact Channels

{{#each contact_channels}} | {{this.channel}} | {{this.priority}} | {{this.implementation}} | {{/each}}

Future: AI Integration

{{ai_integration_notes}}

---

UX Constraints

These constraints inform what's possible in Phase 4 (UX Design)

Platform Limitations

{{#each ux_constraints}}

• {{this}}

{{/each}}

Performance Targets

---

Multilingual Requirements

{{#if multilingual}} Languages: {{languages}}

Implementation: {{multilingual_implementation}}

URL Structure:

{{url_structure}}

Translation Workflow: {{translation_workflow}} {{else}} Single language site {{/if}}

---

SEO Requirements

Technical SEO

{{#each seo_requirements}}

• {{this}}

{{/each}}

Structured Data

{{#each structured_data}} | {{this.page_type}} | {{this.schema_type}} | {{this.properties}} | {{/each}}

Local SEO (if applicable)

{{#if is_local_business}}

• [ ] Google Business Profile claimed and verified
• [ ] NAP consistency (Name, Address, Phone) across all pages
• [ ] Business category set correctly
• [ ] Service area defined
• [ ] Photos uploaded

{{else}} Not a local business {{/if}}

Performance & Infrastructure

Security Headers

SEO Plugin/Tools

{{seo_tools}}

---

Maintenance & Ownership

---

Development Handoff Notes

For Phase 6 (Deliveries)

Environment Setup

{{environment_setup}}

Deployment Process

{{deployment_process}}

Key Considerations

{{#each dev_considerations}}

• {{this}}

{{/each}}

---

Next Steps

• [ ] Content & Language — Define tone, languages, SEO keywords
• [ ] Visual Direction — Establish visual style and brand
• [ ] Phase 2: Trigger Mapping — Map user psychology
• [ ] Phase 4: UX Design — Begin design within these constraints

---

_Generated by Whiteport Design Studio_

Context & Working Relationship

Step: Phase 0 - Project Setup Completed: {{date}} Session: {{session_number}}

---

Project Metadata

Project Name: {{project_name}} Project Slug: {{project_slug}} Product Type: {{website|web_app|mobile_app|landing_page}} Industry: {{industry}}

---

Working Relationship Context

Stakes

Level: {{personal|business|departmental|enterprise}}

What this means: {{explanation_of_stakes}}

Stakeholders (if applicable): {{stakeholder_list_or_none}}

Political Sensitivities (if applicable): {{sensitivities_or_none}}

---

Collaboration Style

Involvement Level: {{collaborative|balanced|autonomous}} User Role: {{role_description}} Recommendation Style: {{options|recommend|direct}}

What this means for our work: {{how_this_shapes_collaboration}}

---

Documentation Approach

Documentation Needs: {{minimal|standard|comprehensive}} Justification Level: {{trust_based|balanced|evidence_based}}

Adapted approach:

• Tone: {{tone_description}}
• Detail level: {{detail_level}}
• Evidence requirements: {{evidence_approach}}

---

Project Configuration

Brief Level: {{complete|simplified}} Strategic Analysis: {{full|simplified|skip}} Skip Design System: {{yes|no}} Skip Trigger Map: {{yes|no}}

Product Complexity: {{simple|standard|complex}} Tech Stack: {{tech_stack_or_tbd}} Component Library: {{library_or_tbd}}

---

Documented in: wds-project-outline.yaml (frontmatter)

Step 2: Vision Capture

Completed: {{date}} Session: {{session_number}} Substeps: 01-open-conversation → 02-explore-vision → 03-reflect-confirm → 04-synthesize-document

---

Opening Question

Agent asked: {{opening_question_adapted_to_context}}

User's initial response: {{first_response}}

---

Conversation Highlights

Key Exchange 1

Agent: {{question_or_followup}} User: {{response}} Signal detected: {{signal_type}} — {{what_this_revealed}}

Key Exchange 2

Agent: {{question_or_followup}} User: {{response}} Signal detected: {{signal_type}} — {{what_this_revealed}}

Key Exchange 3

Agent: {{question_or_followup}} User: {{response}} Signal detected: {{signal_type}} — {{what_this_revealed}}

---

Conversation Flow Summary

{{narrative_summary_of_conversation}}

Total exchanges: {{count}} Duration: {{approximate_time}}

---

Reflection Checkpoint

Agent's synthesis (2-3 sentences): {{what_im_hearing_is}}

User response:

• [x] Confirmed
• [ ] Corrected

Corrections (if any): {{what_was_misunderstood_and_corrected}}

---

Synthesized Vision

{{vision_statement}}

---

Key Insights Captured

1. {{insight_1}} 2. {{insight_2}} 3. {{insight_3}}

---

Example Context (if applicable)

Concrete example provided: {{example_scenario_or_none}}

This example shaped understanding of: {{what_example_clarified}}

---

Documented in: wds-project-outline.yaml → vision Referenced in: Product Brief documentation

Step 3: User Definition

Completed: {{date}} Session: {{session_number}}

---

Opening Question

Agent asked: {{opening_question_about_users}}

User's initial response: {{first_response}}

---

User Exploration

Primary User Discovery

Key exchanges:

Agent: {{followup_question}} User: {{response}}

Agent: {{deeper_question}} User: {{response}}

Agent: {{clarifying_question}} User: {{response}}

---

Reflection Checkpoint

Agent's synthesis: {{understanding_of_primary_user}}

User response:

• [ ] Confirmed
• [ ] Corrected

Corrections (if any): {{corrections}}

---

Primary User Definition

Who they are: {{user_description}}

Their context: {{situation_and_environment}}

Their frustrations: {{pain_points}}

What they're trying to achieve: {{goals_and_jobs_to_be_done}}

How they currently solve this: {{current_alternatives}}

---

Secondary Users (if applicable)

User 2: {{description_or_none}} User 3: {{description_or_none}}

---

User Scenarios Captured

Scenario 1: {{concrete_example}} Scenario 2: {{concrete_example}}

---

Documented in: wds-project-outline.yaml → users

Step 4: Product Concept

Completed: {{date}} Session: {{session_number}}

---

Purpose

Capture the designer's STRUCTURAL vision - the founding principle or key feature that defines the product concept.

Not just requirements - the IDEA.

---

Concept Exploration

Agent asked: {{question_to_surface_concept}}

User described: {{concept_description}}

---

Deep Dive

Core Structural Idea

The founding principle: {{what_makes_this_product_distinct}}

Concrete example: {{specific_example_of_concept_in_action}}

Why This Matters

User's rationale: {{why_this_approach}}

Problem it solves: {{what_this_enables}}

---

Reflection Checkpoint

Agent's synthesis: {{understanding_of_concept}}

User response:

• [ ] Confirmed
• [ ] Corrected

Corrections (if any): {{corrections}}

---

Concept Documentation

Core concept: {{concept_statement}}

Implementation principle: {{how_this_shapes_design}}

Example: {{concrete_example}}

---

Related Features

Features that stem from this concept: 1. {{feature_1}} 2. {{feature_2}} 3. {{feature_3}}

---

Documented in: wds-project-outline.yaml → product_concept Impacts: Navigation structure, information architecture, feature priorities

Step 6: Inspiration & References

Completed: {{date}} Session: {{session_number}}

---

Visual Preference Exploration

What User Likes

Reference 1: {{site_or_example}} What they like: {{specific_elements}} Why it resonates: {{reason}}

Reference 2: {{site_or_example}} What they like: {{specific_elements}} Why it resonates: {{reason}}

Reference 3: {{site_or_example}} What they like: {{specific_elements}} Why it resonates: {{reason}}

---

What User Dislikes

Reference 1: {{site_or_example}} What to avoid: {{specific_elements}} Why it doesn't work: {{reason}}

Reference 2: {{site_or_example}} What to avoid: {{specific_elements}} Why it doesn't work: {{reason}}

---

Style Preferences

Overall aesthetic: {{description}} Color preferences: {{notes}} Tone/mood: {{description}} Level of complexity: {{simple|balanced|rich}}

---

Competitor Analysis (if discussed)

Competitor 1: {{name}}

• What they do well: {{strengths}}
• Where they fall short: {{weaknesses}}
• How we'll differentiate: {{approach}}

Competitor 2: {{name}}

• What they do well: {{strengths}}
• Where they fall short: {{weaknesses}}
• How we'll differentiate: {{approach}}

---

Reference Material Collected

• {{name}} — {{what_to_extract}}
• {{name}} — {{what_to_extract}}
• {{name}} — {{what_to_extract}}

---

Documented in:

• inspiration/visual-refs.md
• inspiration/competitor-analysis.md
• wds-project-outline.yaml → inspiration

Step 7: Positioning

Completed: {{date}} Session: {{session_number}}

---

Positioning Exploration

Agent asked: {{opening_question_about_positioning}}

User's initial response: {{first_response}}

---

Key Exchanges

Differentiation

Agent: {{question_about_difference}} User: {{response}}

What this revealed: {{insight_about_unique_angle}}

---

Market Context

Agent: {{question_about_alternatives}} User: {{response}}

What this revealed: {{insight_about_competitive_landscape}}

---

Value Proposition

Agent: {{question_about_value}} User: {{response}}

What this revealed: {{insight_about_core_value}}

---

Reflection Checkpoint

Agent's synthesis: {{positioning_understanding}}

User response:

• [ ] Confirmed
• [ ] Corrected

Corrections (if any): {{corrections}}

---

Positioning Statement

{{positioning_statement}}

For: {{target_user}} Who: {{their_situation}} This product: {{what_it_is}} That: {{key_benefit}} Unlike: {{alternatives}} Our approach: {{differentiation}}

---

Supporting Evidence

Why this position makes sense: 1. {{rationale_1}} 2. {{rationale_2}} 3. {{rationale_3}}

---

Documented in: wds-project-outline.yaml → positioning

Key Decisions Log

Project: {{project_name}} Format: Append-only decision log

---

Decision 1: {{decision_topic}}

Date: {{date}} Step: {{step_where_decided}} Session: {{session_number}}

Context: {{what_prompted_this_decision}}

What was decided: {{the_decision}}

Why: {{rationale}}

Impact: {{how_this_shapes_project}}

Alternatives considered:

• {{option_1}} — {{why_not}}
• {{option_2}} — {{why_not}}

Documented in: {{file_path}}

---

Decision 2: {{decision_topic}}

Date: {{date}} Step: {{step_where_decided}} Session: {{session_number}}

Context: {{what_prompted_this_decision}}

What was decided: {{the_decision}}

Why: {{rationale}}

Impact: {{how_this_shapes_project}}

Alternatives considered:

• {{option_1}} — {{why_not}}
• {{option_2}} — {{why_not}}

Documented in: {{file_path}}

---

Decision 3: {{decision_topic}}

Date: {{date}} Step: {{step_where_decided}} Session: {{session_number}}

Context: {{what_prompted_this_decision}}

What was decided: {{the_decision}}

Why: {{rationale}}

Impact: {{how_this_shapes_project}}

Alternatives considered:

• {{option_1}} — {{why_not}}

Documented in: {{file_path}}

---

_Continue appending decisions as they're made throughout the Product Brief process._

Product Brief Dialog: {{project_name}}

Agent: Saga (Product Brief Analyst) Project: {{project_name}} Started: {{start_date}} Status: {{in_progress|completed}} Last Updated: {{current_date}}

---

About This Dialog

This dialog tracks the Product Brief discovery process - the conversations, reflections, decisions, and synthesis that led to the documented brief.

---

Project Context

Client/Stakeholder: {{client_name}} ({{relationship}}) Designer: {{designer_name}} Sign-off Authority: {{who_approves}} Project Type: {{internal|external|agency}}

Working Relationship: {{Brief description of stakes, involvement level, how directive to be}}

---

Progress Tracker

• [ ] Vision Capture — What we're building and why
• [ ] User Definition — Who we're building for
• [ ] Product Concept — The founding structural idea
• [ ] Core Features — Essential functionality
• [ ] Inspiration & References — Visual preferences and references
• [ ] Positioning — Market position and differentiation
• [ ] Success Metrics — How we measure success
• [ ] Constraints — Limitations and boundaries
• [ ] Launch Requirements — What's needed to ship
• [ ] Timeline & Phases — Roadmap and milestones
• [ ] Review & Synthesis — Final review and signoff

---

Key Decisions

See decisions.md for detailed decision log.

Major decisions: 1. {{decision_summary_1}} 2. {{decision_summary_2}} 3. {{decision_summary_3}}

---

Reflection Quality

Total Checkpoints: {{count}} Confirmed First Try: {{count}} Required Correction: {{count}}

This measures how well the agent understood the user's intent.

---

Dialog Artifacts

All dialog files are timestamped and track the natural conversation flow, not just the final outputs.

Purpose: Enable future agents (or humans) to understand WHY decisions were made, not just WHAT was decided.

---

Generated Artifacts:

• wds-project-outline.yaml
• Product Brief documentation

Dialog Template Usage

Quick Start

Copy to project:

cp -r workflows/wds-1-project-brief/templates/project-brief-dialog projects/{{slug}}/dialog

Update as you progress:

• Complete each file when the corresponding PB step finishes
• Update README.md progress tracker
• Append to decisions.md whenever key decisions are made

---

What to Capture

DO:

• Key questions + user responses (not full transcript)
• Signal-based follow-ups that revealed insights
• Reflection checkpoint (synthesis + confirmation + corrections)
• Final outputs (vision, positioning, etc.)
• WHY decisions were made

DON'T:

• Verbatim transcripts
• Procedural agent actions
• Implementation details
• Repetitive exchanges

---

Mandatory Checkpoints

Document EVERY reflection: 1. Agent's synthesis (2-3 sentences) 2. User confirmed or corrected? 3. What was misunderstood? (if corrected)

---

Integration with Steps

Each step file should mandate:

## Design Log Update

Before marking complete:
1. Update `dialog/{{step}}-{{name}}.md`
2. Document reflection checkpoint
3. Record final synthesis
4. Mark complete in `dialog/README.md`

---

File Sizes

All dialog files: 65-86 lines (well under 100-line target)

---

Design Log (Meta-Level)

For multi-session work, agents should use the design log for state tracking and _progress/agent-experiences/ for session insights.

Location: {{root_folder}}/_progress/00-design-log.md

Update Protocol: 1. Complete current task 2. Update design log with changes 3. Show git diff to user 4. Record session insights in _progress/agent-experiences/ if needed

---

Purpose

Create transparent record of discovery conversations so future agents (and humans) understand WHY decisions were made, not just WHAT was decided. The design log provides this continuity across sessions.

Project Brief: {{project_name}}

Complete Strategic Foundation

Created: {{date}} Author: {{user_name}} Brief Type: Complete

---

Vision

{{vision}}

---

Positioning Statement

{{positioning_statement}}

Breakdown:

• Target Customer: {{target_customer}}
• Need/Opportunity: {{need_opportunity}}
• Category: {{category}}
• Key Benefit: {{key_benefit}}
• Differentiator: {{differentiator}}

---

Business Model

Type: {{business_model}}

{{#if business_model_b2b}}

Business Customer Profile (B2B)

{{business_customer_profile}}

Buying Roles

{{/if}}

---

{{#if business_model_b2b}}User Profile (within Business){{else}}Ideal Customer Profile (ICP){{/if}}

{{ideal_user_profile}}

Secondary Users

{{secondary_users}}

---

Success Criteria

{{success_criteria}}

---

Competitive Landscape

{{competitive_landscape}}

Our Unfair Advantage

{{unfair_advantage}}

---

Constraints

{{constraints}}

---

Platform & Device Strategy

Primary Platform: {{primary_platform}}

Supported Devices: {{supported_devices}}

Device Priority: {{device_priority}}

Interaction Models: {{interaction_models}}

Technical Requirements:

• Offline Functionality: {{offline_requirements}}
• Native Features: {{native_features_needed}}

Platform Rationale: {{platform_rationale}}

Future Platform Plans: {{future_platform_plans}}

Design Implications: {{design_implications}}

Development Implications: {{development_implications}}

---

Tone of Voice

For UI Microcopy & System Messages

Tone Attributes

1. {{tone_attribute_1}}: {{tone_description_1}} 2. {{tone_attribute_2}}: {{tone_description_2}} 3. {{tone_attribute_3}}: {{tone_description_3}} {{#if tone_attribute_4}}4. {{tone_attribute_4}}: {{tone_description_4}}{{/if}} {{#if tone_attribute_5}}5. {{tone_attribute_5}}: {{tone_description_5}}{{/if}}

Examples

Error Messages:

• ✅ {{tone_example_error_good}}
• ❌ {{tone_example_error_bad}}

Button Text:

• ✅ {{tone_example_button_good}}
• ❌ {{tone_example_button_bad}}

Empty States:

• ✅ {{tone_example_empty_good}}
• ❌ {{tone_example_empty_bad}}

Success Messages:

• ✅ {{tone_example_success_good}}
• ❌ {{tone_example_success_bad}}

Guidelines

Do: {{tone_do_guidelines}}

Don't: {{tone_dont_guidelines}}

---

Note: Tone of Voice applies to UI microcopy (labels, buttons, errors, system messages). Strategic content (headlines, feature descriptions, value propositions) uses the Content Creation Workshop based on page-specific purpose and context.

---

Additional Context

{{additional_context}}

---

Business Context

• Primary Goal: {{business_goal}}
• Solution: {{solution}}
• Target Users: {{target_users}}

Full strategic analysis (business goals, personas, driving forces) is developed in [Phase 2: Trigger Mapping](../B-Trigger-Map/).

---

Next Steps

This complete brief provides strategic foundation for all design work:

• [ ] Phase 2: Trigger Mapping - Map user psychology to business goals
• [ ] Phase 3: PRD Platform - Define technical foundation
• [ ] Phase 4: UX Design - Begin sketching and specifications
• [ ] Phase 5: Design System - If enabled, build components
• [ ] Phase 6: PRD Finalization - Compile for development handoff

---

_Generated by Whiteport Design Studio_

Service Agreement

Project: {{project_name}} Date: {{date}} Client/Owner: {{client_name}} Service Provider: {{service_provider_name}} Contract Language: {{contract_language}} Governing Law/Jurisdiction: {{governing_jurisdiction}}

---

Agreement Philosophy: This agreement is designed to be simple, fair, and clear - providing reliable terms that support a long-lasting working relationship between both parties.

---

1. Project Overview

The Realization

{{realization}}

Recommended Solution

{{recommended_solution}}

---

2. Scope of Services

The Path Forward

{{path_forward}}

Deliverables

Based on the path forward, the following deliverables will be provided:

{{deliverables_list}}

---

3. Our Commitment

{{our_commitment}}

---

Payment Terms

Total Agreement Amount: {{total_amount}}

Payment Structure: {{payment_structure}}

Payment Schedule: {{payment_schedule}}

Background: Clear payment terms protect both parties and ensure fair compensation.

What it does: Defines when and how payments will be made.

Purpose:

• Ensures service provider receives fair compensation for work
• Provides client with clear payment expectations
• Protects both parties from payment disputes
• For fixed-price agreements, upfront payment is fair since service provider assumes cost overrun risk

Payment Terms Details:

• Payment Method: {{payment_method}} (check, wire transfer, credit card, etc.)
• Payment Due Dates: {{payment_due_dates}}
• Late Payment: {{late_payment_terms}} (e.g., interest charges, work suspension)
• Payment Conditions: {{payment_conditions}} (e.g., payment required before work begins, payment tied to deliverables)

For Fixed-Price Agreements: This is a fixed-price agreement, meaning the service provider commits to deliver specified work for the agreed price, regardless of actual costs. Since the service provider assumes the risk of cost overruns, upfront payment (50-100%) is standard and fair. This demonstrates client commitment and enables the service provider to deliver quality work without cash flow concerns.

---

4. Timeline

{{timeline}}

Note: Timeline is based on the path forward outlined above and may be adjusted based on project requirements.

---

5. Why It Matters

{{why_it_matters}}

---

6. Expected Outcomes

The Value We'll Create

{{value_we_create}}

---

7. Service Terms

Payment Terms

{{payment_terms}}

Deliverable Acceptance

Deliverables will be considered accepted upon:

• Completion according to specifications
• Review and approval by client
• Any requested revisions completed

Intellectual Property

All deliverables and work products will be owned by {{client_name}} upon full payment.

---

8. Risks and Considerations

Cost of Inaction

{{cost_of_inaction}}

---

9. Confidentiality

Confidentiality Clause

Background: This clause protects sensitive information shared during the project.

What it does: Both parties agree to keep project information confidential.

Purpose: Protects proprietary information, business strategies, trade secrets, and sensitive data.

Terms:

Both parties agree to:

• Keep all project-related information confidential
• Not disclose project details to third parties without written consent
• Use confidential information solely for project purposes
• Return or destroy confidential materials upon project completion or termination
• Maintain confidentiality obligations even after project completion

Exceptions:

• Information already publicly known
• Information independently developed
• Information required by law to be disclosed

Duration: Confidentiality obligations shall remain in effect for [X] years after project completion.

---

10. Not to Exceed Clause

Budget Cap

Background: This clause sets a maximum budget limit.

What it does: States that total costs will not exceed a specified amount without prior written approval.

Purpose:

• Protects both parties from unexpected cost overruns
• Ensures budget control
• Prevents scope creep - Any work beyond the original scope requires approval and may affect the budget cap

Terms:

• Total project costs shall not exceed {{not_to_exceed_amount}} without prior written approval from {{client_name}}
• Any work that would exceed this amount must be approved in advance
• If additional work is needed, a change order must be signed before proceeding
• This cap includes all fees, expenses, and costs related to the project

Change Orders and Scope Control:

• Any changes to scope that affect cost must be documented in a written change order
• Change orders must be signed by both parties before work begins
• Change orders may adjust the not-to-exceed amount if agreed upon
• Scope creep prevention: Work outside the original scope (as defined in Section 2) requires a change order and approval before proceeding
• This clause helps prevent gradual expansion of project scope without proper authorization

---

11. Terms and Conditions

Work Initiation

When work begins: {{work_initiation_date_or_condition}}

Background: This clause specifies exactly when the service provider is authorized to begin work.

What it does: Defines the start date or conditions that must be met before work begins.

Purpose:

• Prevents unauthorized work before agreement is fully executed
• Establishes clear timeline expectations
• Protects both parties by ensuring work only begins after proper authorization

Initiation conditions (select applicable):

• Upon full execution of this agreement (signatures from both parties)
• On a specific date: {{specific_start_date}}
• Upon receipt of initial payment/deposit
• Upon written notice from {{client_name}}
• Other: {{custom_initiation_condition}}

Project Initiation

This project is initiated upon approval of the project pitch. Project initiation is considered complete upon stakeholder approval.

Changes and Modifications

Any changes to scope, timeline, or investment must be agreed upon in writing by all parties.

Termination

Either party may terminate this agreement with [X] days written notice. Upon termination, payment is due for work completed to date.

Dispute Resolution

Background: Defines how conflicts will be resolved if they arise.

What it does: Establishes the process for handling disagreements.

Purpose: Provides a clear path for resolving disputes without costly litigation when possible.

Method: {{dispute_resolution_method}} (mediation/arbitration/litigation)

Location: {{dispute_resolution_location}}

Any disputes arising from this agreement shall be resolved through {{dispute_resolution_method}} in {{dispute_resolution_location}}.

---

Governing Law and Jurisdiction

Background: Determines which laws apply and where legal proceedings would take place.

What it does: Specifies the legal framework and court system that governs the agreement.

Purpose: Provides legal clarity and predictability for both parties.

Governing Law: This agreement shall be governed by and construed in accordance with the laws of {{governing_jurisdiction}}.

Jurisdiction: Any legal proceedings arising from this agreement shall be subject to the exclusive jurisdiction of the courts of {{governing_jurisdiction}}.

Contract Language: This agreement is executed in {{contract_language}}. In case of translation, the {{contract_language}} version shall prevail.

---

12. Approval

Client/Owner Approval:

Signature: _________________ Name: {{client_name}} Date: _______________

Service Provider Approval:

Signature: _________________ Name: {{service_provider_name}} Date: _______________

---

Appendix

Reference Documents

• Project Pitch: docs/wds-1-project-brief/pitch.md
• Project Brief: (To be created after agreement approval)

---

This service agreement is based on the project pitch dated {{date}}.

Project Signoff Document

Project: {{project_name}} Date: {{date}} Department/Team: {{department_name}} Project Owner: {{project_owner}} Document Language: {{contract_language}} Governing Jurisdiction: {{governing_jurisdiction}} (if applicable)

---

Document Philosophy: This signoff document is designed to be simple, fair, and clear - providing reliable terms that support successful project execution and clear accountability.

---

1. Project Overview

The Realization

{{realization}}

Recommended Solution

{{recommended_solution}}

---

2. Goals and Success Metrics

What We're Trying to Accomplish

{{goals}}

Success Metrics

{{success_metrics}}

How We'll Measure Success

{{measurement_approach}}

Key Performance Indicators (KPIs)

{{kpis}}

---

3. Budget and Resources

Budget Allocation

Total Budget: {{total_budget}}

Budget Breakdown (if applicable): {{budget_breakdown}}

Resources Needed

{{resources_needed}}

Not-to-Exceed Budget Cap

{{not_to_exceed_budget}}

---

4. Ownership and Responsibility

Project Owner

{{project_owner}}

Process Owner

{{process_owner}}

Key Stakeholders

{{key_stakeholders}}

Decision-Making Authority

{{decision_making_authority}}

---

5. Approval and Sign-Off

Who Needs to Approve

{{approvers_list}}

Approval Stages

{{approval_stages}}

Sign-Off Process

{{signoff_process}}

Timeline for Approval

{{approval_timeline}}

---

6. Timeline and Milestones

Key Milestones

{{key_milestones}}

Delivery Dates

{{delivery_dates}}

Critical Deadlines

{{critical_deadlines}}

---

7. Optional Sections

Risks and Considerations (Optional)

{{risks_and_considerations}}

Confidentiality (Optional)

{{confidentiality_requirements}}

The Path Forward (Optional - High-Level Overview)

{{path_forward_high_level}}

---

8. Approval and Signoff

This document serves as formal approval to proceed with the project as outlined above.

Stakeholder Signoffs:

Project Sponsor:

Name: _________________ Signature: _________________ Date: _______________

Budget Approver:

Name: _________________ Signature: _________________ Date: _______________

Project Owner:

Name: {{project_owner}} Signature: _________________ Date: _______________

---

9. Next Steps

Upon signoff: 1. Proceed to full Project Brief development 2. Execute work plan as outlined above 3. Deliverables will be provided according to the agreed timeline

Changes and Modifications

Any changes to scope, timeline, or investment must be agreed upon by all signatories.

---

Appendix

Reference Documents

• Project Pitch: docs/wds-1-project-brief/pitch.md
• Project Brief: (To be created after signoff)

---

This signoff document is based on the project pitch dated {{date}}.

Project Brief: {{project_name}}

Simplified Brief - Essential context for design work

Created: {{date}} Author: {{user_name}} Brief Type: Simplified

---

Project Scope

{{project_scope}}

---

Challenge / Opportunity

{{challenge_opportunity}}

---

Design Goals

{{design_goals}}

---

Constraints

{{constraints}}

---

Next Steps

This simplified brief provides essential context for design work. The following phases can now proceed:

• [ ] Phase 4: UX Design - Begin sketching and specifications
• [ ] Phase 5: Design System - If enabled, build components alongside design

---

_Generated by Whiteport Design Studio_

Visual Direction: {{project_name}}

Brand Aesthetics & Design Guidelines

Created: {{date}} Author: {{user_name}} Related: Product Brief | Content & Language

---

Existing Brand Assets

Current Assets

{{existing_assets_summary}}

{{#each existing_assets}} | {{this.asset}} | {{this.status}} | {{this.location}} | {{/each}}

Brand Constraints

{{#each brand_constraints}}

• {{this}}

{{/each}}

---

Visual References

Inspiration Sites

{{#each reference_sites}} [{{this.name}}]({{this.url}})

• What we like: {{this.what_we_like}}
• Relevance: {{this.relevance}}

{{/each}}

Visual Mood

{{mood_description}}

Keywords: {{mood_keywords}}

---

Design Style

UI Style

Primary Style: {{ui_style}}

{{ui_style_description}}

Characteristics: {{#each ui_style_characteristics}}

• {{this}}

{{/each}}

Design Aesthetic

Aesthetic: {{design_aesthetic}}

{{aesthetic_description}}

---

Color Direction

Color Strategy

{{color_strategy}}

Palette Direction

Color Scheme Type

Type: {{color_scheme_type}}

Reference: [Color Terminology](../../../docs/models/design-nomenclature/color-terminology.md)

---

Typography Direction

Type Approach

{{typography_approach}}

Font Direction

Reference: [Typography Classification](../../../docs/models/design-nomenclature/typography-classification.md)

---

Layout Direction

Layout Approach

{{layout_approach}}

Key Layout Elements

Reference: [Layout Terminology](../../../docs/models/design-nomenclature/layout-terminology.md)

---

Visual Effects

Effect Usage

{{effects_approach}}

Specific Effects

{{#each effects}} | {{this.effect}} | {{this.usage}} | {{this.notes}} | {{/each}}

Reference: [Visual Effects](../../../docs/models/design-nomenclature/visual-effects.md)

---

Photography & Imagery

Photography Style

{{photography_style}}

Image Sources

{{#each image_sources}} | {{this.type}} | {{this.source}} | {{this.notes}} | {{/each}}

Image Guidelines

{{#each image_guidelines}}

• {{this}}

{{/each}}

---

Design Constraints

From Platform Requirements and brand needs

{{#each design_constraints}}

• {{this}}

{{/each}}

---

Summary: Visual DNA

Style:        {{summary_style}}
Colors:       {{summary_colors}}
Typography:   {{summary_typography}}
Mood:         {{summary_mood}}
Key Element:  {{summary_key_element}}

---

Next Steps

• [ ] Phase 2: Trigger Mapping — Connect visuals to user psychology
• [ ] Phase 4: UX Design — Apply visual direction to designs
• [ ] Phase 5: Design System — Build design tokens from direction

---

Reference Files

• visual-references/ — Collected reference images
• Design Nomenclature — Vocabulary reference

---

_Generated by Whiteport Design Studio_

Feature Impact Analysis: {{project_name}}

Scoring

Primary Persona (⭐): High = 5 pts | Medium = 3 pts | Low = 1 pt Other Personas: High = 3 pts | Medium = 1 pt | Low = 0 pts

Max Possible Score: {{max_score}} (with {{persona_count}} personas) Must Have Threshold: {{must_have_threshold}}+ or Primary High (5)

---

Prioritized Features

{{#each sorted_features}} | {{this.rank}} | {{this.name}} | {{this.score}} | {{this.decision}} | {{/each}}

---

Decisions

Must Have MVP (Primary High OR Top Tier Score): {{#each must_have}}

• {{this.name}} ({{this.score}})

{{/each}}

Consider for MVP: {{#each consider}}

• {{this.name}} ({{this.score}})

{{/each}}

Defer (Nice-to-Have or Low Strategic Value): {{#each defer}}

• {{this.name}} ({{this.score}})

{{/each}}

---

_Generated with Whiteport Design Studio framework_ _Strategic input for Phase 4: UX Design and Phase 6: PRD/Development_

Persona Document Template

This template provides the comprehensive structure for generating detailed persona documents from trigger map data.

---

File Naming Convention

02-[Name]-the-[Role].md  → Primary persona
03-[Name]-the-[Role].md  → Secondary persona
04-[Name]-the-[Role].md  → Tertiary persona (if exists)

Examples:

• 02-Sarah-the-Student.md
• 03-Marcus-the-Mentor.md
• 04-Emma-the-Enthusiast.md

---

Document Structure for EACH Persona

1. Header

# [Name] the [Role] - [Type] Persona

> [Priority] target - [One-line role in flywheel]

**Priority:** [PRIMARY 🎓 / SECONDARY 💼 / TERTIARY 🏠]
**Role in Flywheel:** [How they contribute to goals]
**Created:** [Date]

---

2. Profile Summary

## Profile Summary

**[One compelling paragraph that captures the essence of this persona]**

[Explain their role in the bigger picture - why they matter to the product's success]

---

2a. Visual Representation

## Visual Representation

**Image Generation Prompt:**

"[Detailed prompt for AI image generation - include age, gender, profession, setting, emotional state, visual style, technical details like lighting and composition]"

**Example:**
"Professional headshot photograph of a 34-year-old Scandinavian female designer, shoulder-length blonde hair, sitting at modern desk with laptop, looking contemplative and slightly stressed, natural lighting, shallow depth of field, professional business casual attire, tech startup office background, photorealistic style, 4K quality"

**Prompt Components:**
- **Demographics:** Age, gender, ethnicity, appearance
- **Professional Context:** Role, work environment, tools/props
- **Emotional State:** Expression that matches their driving forces
- **Visual Style:** Photography style, illustration, realistic/stylized
- **Technical Details:** Lighting, composition, camera angle, quality

---

3. Background

For different persona types:

Students/Employees:

## Background

### Education & Career Path

**University/School:** [Educational background]

**Learning Journey:** [How they got their skills]

**First Break:** [How they entered this field/situation]

**Current Role:** [What they do now]

**Career Pattern:** [Straight path or winding road?]

Entrepreneurs/Business:

## Background

### Business Journey

**Company Role:** [Position and history]

**Experience Level:** [Seasoned or new?]

**Technical Background:** [Their relationship with tech/tools]

**Management Style:** [How they lead]

---

4. Current Situation

## Current Situation

### Professional Reality [or Business Context / Daily Life]

**The Daily Struggle:**
- [Challenge 1]
- [Challenge 2]
- [Key pain point]
- [Overwhelming aspect]

**Skills & Tools:**
- [What they know]
- [What they use]
- [Skill gaps]
- [Learning attitude]

**The [Specific] Gap:**
- [Core challenge description]
- [Why it matters]
- [What's blocking them]
- [What they need]

---

5. Psychological Profile

## Psychological Profile

### Personality & Motivations

**Core Identity:**
- [Key trait 1]
- [Key trait 2]
- [Deep motivation]
- [Belief system]

**Work Style [or Leadership Style / Life Approach]:**
- [How they operate]
- [What they value]
- [How they make decisions]
- [Communication preferences]

---

6. Driving Forces (CRITICAL SECTION)

## Driving Forces

### ✅ Top 3 Positive Drivers (What They Want)

**1. [Want #1]**
- [Detailed description of the want]
- [Why it matters to them]
- [What success looks like]
- **[Product] Promise:** [How your product delivers this]

**2. [Want #2]**
- [Detailed description]
- [Why it matters]
- [What success looks like]
- **[Product] Promise:** [How your product delivers this]

**3. [Want #3]**
- [Detailed description]
- [Why it matters]
- [What success looks like]
- **[Product] Promise:** [How your product delivers this]

---

### ❌ Top 3 Negative Drivers (What They Fear)

**1. [Fear #1]**
- [Detailed description of the fear]
- [Why this terrifies them]
- [What failure looks like]
- **[Product] Answer:** [How your product solves/prevents this]

**2. [Fear #2]**
- [Detailed description]
- [Why this terrifies them]
- [What failure looks like]
- **[Product] Answer:** [How your product solves/prevents this]

**3. [Fear #3]**
- [Detailed description]
- [Why this terrifies them]
- [What failure looks like]
- **[Product] Answer:** [How your product solves/prevents this]

---

7. The Transformation Journey (PRIMARY PERSONA ESPECIALLY)

## The Transformation Journey

### BEFORE [Product]

**Emotional State:**
- 😰 [Feeling 1]
- 😔 [Feeling 2]
- 🤷‍♀️ [Feeling 3]
- 😤 [Feeling 4]
- 📦 [Self-perception]

**Daily Reality:**
- [Daily struggle 1]
- [Daily struggle 2]
- [Daily struggle 3]
- [Daily struggle 4]

**Self-Perception:**
- [How they see themselves]
- [Where they feel stuck]
- [Their limitations]

---

### AFTER [Product]

**Emotional State:**
- 🎯 [New feeling 1]
- 🚀 [New feeling 2]
- 💪 [New feeling 3]
- ⭐ [New feeling 4]
- 🌍 [New self-perception]

**Daily Reality:**
- [New capability 1]
- [New capability 2]
- [New capability 3]
- [New outcome]

**Self-Perception:**
- [How they now see themselves]
- [Their new role]
- [Their new identity]

---

8. Role in Strategic Triangle

## Role in Strategic Triangle

\```
[PRIMARY PERSONA]
[Role/Title]
[Key action]
      │
      │ [Connection action]
      ▼
[SECONDARY PERSONA]
[Role/Title]
[Benefit received]
      │
      │ [Connection action]
      ▼
[TERTIARY PERSONA]
[Role/Title]
[Benefit received]
      │
      │ [Connection action]
      └──────────────► [PRIMARY PERSONA]
                      (Loop closes)
\```

**[This Persona]'s Role:**
- [Key contribution 1]
- [Key contribution 2]
- [How they enable others]
- [How the loop reinforces]

---

9. Creating Awesome [This Persona Type] OR Validation/Discovery Strategy

For PRIMARY:

## Role in Flywheel: Creating Awesome [Personas] Who Become [Champions]

[Persona Name] represents the [type] who [Product] empowers to become truly awesome - and awesome [users] naturally become [champions].

**The Natural Evolution:**
1. [Persona] discovers [Product] and sees themselves in the methodology
2. Learns [approach] with [support level]
3. Builds [outcome] using [Product] - sees results
4. Transforms from [before] to [after]
5. Naturally shares what worked with others
6. Becomes one of the [X] [champions] - not because we asked, but because [they're] excited

---

## What [Persona Name] Needs to See on [Product] Page

**1. [Section Name]**
- [Requirement 1]
- [Requirement 2]
- [Key message]

**2. [Section Name]**
- [Requirement 1]
- [Requirement 2]
- [Key message]

[Continue for 5-6 key sections]

For SECONDARY:

## Validation Strategy

### What [Persona Name] Needs to See About [Product]

**1. [Validation Need]**
- [Proof point 1]
- [Proof point 2]
- [Trust signal]

[Continue for 3-4 validation needs]

---

## Conversion Path

### How [Persona Name] Validates [Product]

**Phase 1: Discovery**
- [How they hear about it]

**Phase 2: Evaluation**
- [What they check]

**Phase 3: Adoption**
- [How they engage]

**Phase 4: Advocacy**
- [How they spread word]

For TERTIARY:

## How [Persona Name] Discovers [Product] Value

### The Recognition Path

**Phase 1: Experience the Difference**
- [What changes for them]

**Phase 2: Recognition**
- [When they realize why]

**Phase 3: Appreciation**
- [How they respond]

**Phase 4: Word of Mouth**
- [How they share]

---

10. Impact on Business Goals

## Impact on Business Goals

**[This Persona]'s Role in Success Metrics:**

**Primary Goal ([X Champions]):**
- [How they contribute]
- [Specific impact]

**Secondary Goals ([Product] Adoption):**
- [How they contribute]
- [Specific impact]

**Tertiary Goals (Community Opportunities):**
- [How they contribute]
- [Specific impact]

---

11. Success Metrics (PRIMARY especially)

## Success Metrics

**[Persona] Becomes [Champion] When [They]:**
1. ✅ [Milestone 1]
2. ✅ [Milestone 2]
3. ✅ [Milestone 3]
4. ✅ [Milestone 4]
5. ✅ [Milestone 5]

**Impact on Business Goals:**
- Becomes one of **[X] [champions]** (PRIMARY GOAL)
- [Impact 2]
- [Impact 3]
- [Impact 4]

---

12. Transformation Journey (PRIMARY persona especially)

## Transformation Journey

**Current State:** [Current challenges and limitations]

**With [Product]:** [How the product enables change]

**Desired State:** [Outcome and new capabilities]

**What Makes This Possible:**
- [Enabler 1]
- [Enabler 2]
- [Enabler 3]

This is especially important for the PRIMARY persona.

---

13. Related Documents Footer

## Related Documents

- **[00-trigger-map.md](00-trigger-map.md)** - Visual overview and navigation
- **[02-[Other].md](02-[Other].md)** - [Other] persona
- **[03-[Other].md](03-[Other].md)** - [Other] persona
- **[05-Key-Insights.md](05-Key-Insights.md)** - Strategic implications

---

_Back to [Trigger Map](00-trigger-map.md)_

---

Key Requirements

Length: Each persona should be ~250-375 lines

Tone:

• Rich, nuanced, human
• Not "converting" but "creating awesome"
• Natural language, storytelling

Driving Forces:

• Each must have [Product] Promise or [Product] Answer
• Show how product addresses each driver
• Be specific and actionable

Transformation:

• PRIMARY persona gets full BEFORE/AFTER
• Show emotional journey, not just functional
• Use emojis to show emotional states

Strategic Triangle:

• Show how personas interconnect
• Explain the loop/flywheel
• Make relationships clear

Trigger Map Poster: {{project_name}}

Visual overview connecting business goals to user psychology

Created: {{date}} Author: {{user_name}} Methodology: Based on Effect Mapping (Balic & Domingues), adapted for WDS framework

---

Strategic Documents

This is the visual overview. For detailed documentation, see:

• 01-Business-Goals.md - Full vision statements and SMART objectives
• 02-Target-Groups.md - All personas with complete driving forces
• 03-Feature-Impact-Analysis.md - Prioritized features with impact scores
• *04-08-\.md** - Individual persona detail files

---

Vision

{{vision_statement}}

---

Business Objectives

{{#each objectives}}

Objective {{@index + 1}}: {{this.statement}}

• Metric: {{this.metric}}
• Target: {{this.target}}
• Timeline: {{this.timeline}}

{{/each}}

---

Target Groups (Prioritized)

{{#each prioritized_groups}}

{{@index + 1}}. {{this.name}}

Priority Reasoning: {{this.reasoning}}

{{this.persona_summary}}

Key Positive Drivers: {{#each this.positive_drivers}}

• {{this}}

{{/each}}

Key Negative Drivers: {{#each this.negative_drivers}}

• {{this}}

{{/each}}

{{/each}}

---

Trigger Map Visualization

%%{init: {'theme':'base', 'themeVariables': { 'fontFamily':'Inter, system-ui, sans-serif', 'fontSize':'14px'}}}%%
flowchart LR
    %% Business Goals (Left)
    {{#each business_goals}}
    BG{{@index}}["<br/>{{this.emoji}} {{this.title}}<br/><br/>{{#each this.points}}{{this}}<br/>{{/each}}<br/>"]
    {{/each}}
    
    %% Central Platform
    PLATFORM["<br/>{{platform_emoji}} {{platform_name}}<br/><br/>{{platform_tagline}}<br/><br/>{{platform_transformation}}<br/><br/>"]
    
    %% Target Groups
    {{#each target_groups}}
    TG{{@index}}["<br/>{{this.emoji}} {{this.name}}<br/>{{this.priority}}<br/><br/>{{#each this.profile}}{{this}}<br/>{{/each}}<br/>"]
    {{/each}}
    
    %% Driving Forces
    {{#each target_groups}}
    DF{{@index}}["<br/>{{this.emoji}} {{this.name}}'S DRIVERS<br/><br/>WANTS<br/>{{#each this.positive_drivers}}✅ {{this}}<br/>{{/each}}<br/>FEARS<br/>{{#each this.negative_drivers}}❌ {{this}}<br/>{{/each}}<br/>"]
    {{/each}}
    
    %% Connections
    {{#each business_goals}}
    BG{{@index}} --> PLATFORM
    {{/each}}
    {{#each target_groups}}
    PLATFORM --> TG{{@index}}
    TG{{@index}} --> DF{{@index}}
    {{/each}}

    %% Light Gray Styling with Dark Text
    classDef businessGoal fill:#f3f4f6,color:#1f2937,stroke:#d1d5db,stroke-width:2px
    classDef platform fill:#e5e7eb,color:#111827,stroke:#9ca3af,stroke-width:3px
    classDef targetGroup fill:#f9fafb,color:#1f2937,stroke:#d1d5db,stroke-width:2px
    classDef drivingForces fill:#f3f4f6,color:#1f2937,stroke:#d1d5db,stroke-width:2px
    
    {{#each business_goals}}
    class BG{{@index}} businessGoal
    {{/each}}
    class PLATFORM platform
    {{#each target_groups}}
    class TG{{@index}} targetGroup
    class DF{{@index}} drivingForces
    {{/each}}

---

Design Focus Statement

{{focus_statement}}

Primary Design Target: {{top_group.name}}

Must Address: {{#each must_address_drivers}}

• {{this}}

{{/each}}

Should Address: {{#each should_address_drivers}}

• {{this}}

{{/each}}

---

Cross-Group Patterns

Shared Drivers

{{shared_drivers}}

Unique Drivers

{{unique_drivers}}

{{#if conflicts}}

Potential Tensions

{{conflicts}} {{/if}}

---

Next Steps

This Trigger Map Poster provides a quick reference. For detailed work:

• [ ] Review detailed docs - See 01-Business-Goals.md, 02-Target-Groups.md, 03-Feature-Impact-Analysis.md
• [ ] Use for Feature Prioritization - Reference feature impact scores
• [ ] Guide UX Design - Ensure designs address priority drivers
• [ ] Validate with Users - Test assumptions with real target group members
• [ ] Update as Learnings Emerge - This is a living document

---

_Generated with Whiteport Design Studio framework_ _Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces_

<!-- NAVIGATION BEST PRACTICE: Navigation links appear in THREE places: 1. Above the sketch (top) 2. Below the sketch (still in header area) 3. At document bottom This is intentional for long specifications - users should not need to scroll the entire document to navigate between pages. -->

{page-number}-{page-name}

Previous Step: ← {previous-page-name} Next Step: → {next-page-name}

!{Page Name}

Previous Step: ← {previous-page-name} Next Step: → {next-page-name}

---

{page-number}-{page-name}

Page Metadata

---

Overview

Page Purpose: {What job must this page accomplish?}

User Situation: {What brings the user here?}

Success Criteria: {How will we know this page succeeded?}

Entry Points:

• {How users arrive}

Exit Points:

• {Where users go next}

---

Reference Materials

Strategic Foundation:

• Product Brief - {brief description}
• Trigger Map - {brief description}

Related Pages:

• {Related Page}

Design System:

• {Component}

---

Layout Structure

{High-level description of page layout}

[ASCII layout diagram]
+------------------+
| Header           |
+------------------+
| Main Content     |
+------------------+
| Footer           |
+------------------+

---

Spacing

<!-- All spacing values MUST use token names from the project's spacing scale. The scale is defined in D-Design-System/00-design-system.md → Spacing Scale. This can be the WDS default scale, Tailwind classes, Material tokens, or any system. Do NOT use arbitrary pixel values. If unsure, check the scale. -->

Scale: Spacing Scale

---

Typography

<!-- Text sizes use token names from the project's type scale. The scale is defined in D-Design-System/00-design-system.md → Type Scale.

IMPORTANT: Semantic level (H1, H2, p) signals document structure — for accessibility and SEO. Visual styling (size, weight, typeface) signals visual hierarchy — how it looks. They are related but NOT locked together. An H2 can be text-sm. A <p> can be text-2xl. Headings can have different typefaces and styles on different pages — that's fine. -->

Scale: Type Scale

---

Page Sections

Section: {Section Name}

OBJECT ID: {page-name}-{section-name}

---

{Object Name}

OBJECT ID: {page-name}-{object-name}

↕ {page}-{v|h}-{type}-{size} — {reason}

<!-- Spacing objects sit between content objects. They have IDs and are first-class.

NAMING: {page}-{v|h}-{type}-{size}

• v = vertical, h = horizontal
• type = space, separator, line
• size = the token name (zero, sm, md, lg, xl, 2xl, 3xl, flex)

The ID describes WHAT the spacing IS, not which objects it sits between.

RULES:

• Default element spacing (from the Spacing section above) is implicit — no spacing object needed.
• Non-default spacing MUST be an explicit spacing object with an ID.
• Zero spacing (overlap / flush) MUST be documented: ↕ id — space-zero (reason)
• Same spacing shared by all items in a group → define on the group, not between each item.
• Spacing objects flow into D-Design-System/00-design-system.md → Patterns.

FORMAT: #### ↕ {id} — {reason}

EXAMPLES:

↕ hem-v-space-zero — header and service menu form one continuous nav unit

↕ hem-v-separator-2xl — gray line, space-2xl above and below. Separates about from trust cards.

↕ hem-v-space-3xl — major section boundary between seasons and footer

-->

---

{Object Name 2}

OBJECT ID: {page-name}-{object-name-2}

---

{Group Name} (Container)

OBJECT ID: {page-name}-{group-name}

{Object in Group}

OBJECT ID: {page-name}-{group-name}-{object}

↕ {page-name}-{group-name}-{obj1}-{obj2}-gap — {spacing token}

{Object in Group 2}

OBJECT ID: {page-name}-{group-name}-{object-2}

---

Page States

---

Conditional Sections

Include these micro-instructions when applicable:

---

Technical Notes

{Any constraints, performance requirements, or implementation notes}

---

Open Questions

<!-- This section captures decisions needed before development. During spec creation or audits, auto-populate questions based on: → instructions/open-questions.instructions.md

Categories to check:

• Responsive breakpoints (if multiple viewports)
• Loading/Error/Empty states (if API data)
• SEO meta content (if public page)
• Accessibility requirements
• User permissions/roles
• Time-sensitive behaviors
• Form validation rules
• Navigation/back behavior

-->

_No open questions at this time._

<!-- When questions exist, use this format:

Status Legend: 🔴 Open | 🟡 In Discussion | 🟢 Resolved -->

---

Checklist

• [ ] Page purpose clear
• [ ] All Object IDs assigned
• [ ] Components reference design system
• [ ] Translations complete (SE/EN)
• [ ] States documented
• [ ] Conditional sections included where needed

---

Previous Step: ← {previous-page-name} Next Step: → {next-page-name}

---

_Created using Whiteport Design Studio (WDS) methodology_

{scenario-number}-{scenario-name}

Project: {project-name} Created: {date} Method: Whiteport Design Studio (WDS)

---

Scenario Overview

User Journey: {High-level description of what users accomplish in this scenario}

Entry Point: {Where users begin this scenario} Success Exit: {Where users end after successful completion} Alternative Exits: {Other possible endpoints - errors, cancellations, etc.}

Target Personas: {Which personas from Trigger Map use this scenario}

---

Pages in This Scenario

---

User Flow

flowchart TD
    A[{Entry Point}] --> B[{Page n.1}]
    B --> C[{Page n.2}]
    C --> D{{Decision Point?}}
    D -->|Yes| E[{Page n.3}]
    D -->|No| F[{Alternative Path}]
    E --> G[{Success Exit}]
    F --> G

---

Scenario Steps

Step 1: {Step Name}

Page: {n.1-Page-Name} User Action: {What the user does} System Response: {How the system responds} Success Criteria: {What defines success for this step}

Step 2: {Step Name}

Page: {n.2-Page-Name} User Action: {What the user does} System Response: {How the system responds} Success Criteria: {What defines success for this step}

{Repeat for all steps}

---

Trigger Map Connections

Positive Drivers Addressed

From Trigger Map analysis, this scenario serves these user goals:

• ✅ {Positive goal from Trigger Map}
• ✅ {Positive goal from Trigger Map}

Negative Drivers Avoided

This scenario helps users avoid:

• ❌ {Negative outcome from Trigger Map}
• ❌ {Negative outcome from Trigger Map}

---

Success Metrics

Primary Metric: {Main measure of scenario success}

Secondary Metrics:

• {Metric 1}
• {Metric 2}

User Satisfaction Indicators:

• {What indicates good user experience}

---

Edge Cases & Error Handling

---

Technical Requirements

Data Flow

{Entry} → [Fetch Data] → {Display} → [User Action] → [Validate] → [API Call] → {Success}

API Endpoints Used

State Management

{How state is managed across pages in this scenario}

---

Design Assets

Scenario Folder: C-UX-Scenarios/{scenario-number}-{scenario-name}/

Page Specifications:

• {n}.1-{page-name}/{page-name}.md
• {n}.2-{page-name}/{page-name}.md
• {n}.3-{page-name}/{page-name}.md

Prototypes:

• {n}.1-{page-name}/Prototype/
• {n}.2-{page-name}/Prototype/
• {n}.3-{page-name}/Prototype/

---

Development Notes

{Any scenario-level technical considerations, performance requirements, security notes, etc.}

---

Revision History

---

_Created using Whiteport Design Studio (WDS) methodology_

Component Library Configuration

Library: [Library Name] Version: [Version] Last Updated: [Date]

---

Installation

[Installation commands]

---

Component Mappings

Format: WDS Component → Library Component

Interactive Components

• Button [btn-001] → shadcn/ui Button
• [More mappings]

Form Components

• Input Field [inp-001] → shadcn/ui Input
• [More mappings]

---

Theme Configuration

{
  "colors": {
    "primary": "#2563eb",
    "secondary": "#64748b"
  },
  "typography": {
    "fontFamily": "Inter, sans-serif"
  },
  "spacing": {
    "unit": "0.25rem"
  },
  "borderRadius": {
    "default": "0.375rem"
  }
}

---

Customizations

[Document any customizations from library defaults]

---

Library Documentation

Official Docs: [Link] Component Gallery: [Link] GitHub: [Link]

[Component Name] [[component-id]]

Type: [Interactive/Form/Layout/Content/Feedback/Navigation] Category: [Specific category] Purpose: [Brief description]

---

Overview

[Component description and when to use it]

---

Variants

[List variants if any, or state "This component has no variants"]

---

States

Required States:

• default
• [other required states]

Optional States:

• [optional states if any]

State Descriptions: [Describe each state]

---

Styling

Visual Properties

Size: [values] Shape: [values] Colors: [values] Typography: [values] Spacing: [values]

Design Tokens

[Token definitions]

Figma Reference

[If Mode B - Custom Design System]

Library Component

[If Mode C - Component Library]

---

Behavior

Interactions

[Describe interactions]

Animations

[Describe animations if any]

---

Accessibility

ARIA Attributes: [List ARIA attributes]

Keyboard Support: [List keyboard shortcuts]

Screen Reader: [How screen readers announce this]

---

Usage

When to Use

[Guidelines]

When Not to Use

[Guidelines]

Best Practices

• [Practice 1]
• [Practice 2]

---

Used In

Pages: [count]

Examples:

• [Page] - [Usage]

---

Related Components

[Related components if any]

---

Version History

Created: [Date] Last Updated: [Date]

Changes:

• [Date]: [Change]

---

Notes

[Additional notes]

Design Tokens

Last Updated: [Date] Token Count: [count]

---

Colors

Primary Colors

primary-50: #eff6ff
primary-100: #dbeafe
primary-200: #bfdbfe
primary-300: #93c5fd
primary-400: #60a5fa
primary-500: #3b82f6
primary-600: #2563eb
primary-700: #1d4ed8
primary-800: #1e40af
primary-900: #1e3a8a

Semantic Colors

success: #10b981
error: #ef4444
warning: #f59e0b
info: #3b82f6

Neutral Colors

gray-50: #f9fafb
gray-100: #f3f4f6
[... more grays]
gray-900: #111827

---

Typography

Font Families

font-sans: 'Inter, system-ui, sans-serif'
font-mono: 'JetBrains Mono, monospace'

Font Sizes

text-xs: 0.75rem
text-sm: 0.875rem
text-base: 1rem
text-lg: 1.125rem
text-xl: 1.25rem
text-2xl: 1.5rem
text-3xl: 1.875rem
text-4xl: 2.25rem

Font Weights

font-normal: 400
font-medium: 500
font-semibold: 600
font-bold: 700

---

Spacing

spacing-0: 0
spacing-1: 0.25rem
spacing-2: 0.5rem
spacing-3: 0.75rem
spacing-4: 1rem
spacing-6: 1.5rem
spacing-8: 2rem
spacing-12: 3rem
spacing-16: 4rem

---

Layout

Breakpoints

sm: 640px
md: 768px
lg: 1024px
xl: 1280px
2xl: 1536px

Container Widths

container-sm: 640px
container-md: 768px
container-lg: 1024px
container-xl: 1280px

---

Effects

Shadows

shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05)
shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1)
shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1)

Border Radius

radius-sm: 0.125rem
radius-md: 0.375rem
radius-lg: 0.5rem
radius-full: 9999px

Transitions

transition-fast: 150ms
transition-base: 200ms
transition-slow: 300ms

---

Component-Specific Tokens

Button

button-padding-x: spacing-4
button-padding-y: spacing-2
button-border-radius: radius-md
button-font-weight: font-semibold

Input

input-height: 2.5rem
input-padding-x: spacing-3
input-border-color: gray-300
input-border-radius: radius-md

---

Tokens are automatically populated as components are added to the design system.

Step 1: Welcome & Orientation

STEP GOAL:

Welcome the user to WDS, introduce the methodology and agents, determine if this is a greenfield or brownfield project, and assess if stakeholder alignment is needed.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Project Setup facilitator, onboarding users to WDS methodology
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring WDS methodology expertise, user brings their project knowledge
• ✅ Maintain a welcoming and informative tone throughout

Step-Specific Rules:

• 🎯 Focus only on WDS introduction, project type, and alignment assessment
• 🚫 FORBIDDEN to skip the project type determination or assume it
• 💬 Approach: Present information clearly, let user choose their path
• 📋 Routing decisions here determine the entire workflow path

EXECUTION PROTOCOLS:

• 🎯 Introduce WDS, determine project type, assess alignment needs
• 💾 Record project type (greenfield/brownfield) and alignment decision
• 📖 Present WDS overview including phases and agents
• 🚫 Do not skip project type or alignment questions

CONTEXT BOUNDARIES:

• Available context: Fresh start - no prior project context
• Focus: Orientation, project type, alignment needs
• Limits: Do not configure project details yet (that is step 02)
• Dependencies: None - this is the entry point

Sequence of Instructions (Do not deviate, skip, or optimize)

1. Present WDS Introduction

Welcome to Whiteport Design Studio (WDS)

WDS is a design methodology that helps you create great digital products through structured workflows.

---

What WDS Does

For NEW products (Greenfield):

• Phase 1: Define your vision (Project Brief)
• Phase 2: Understand your users (Trigger Mapping)
• Phase 3: Specify features (PRD Platform)
• Phase 4: Design the experience (UX Design) + Hand off to developers
• Phase 5: Build with agentic development + Validate quality
• Phase 6: Build consistency (Design System)
• Phase 7: Launch & Go Live

For EXISTING products (Brownfield):

• Phase 8: Strategic improvements (Kaizen approach)
• Limited Brief (document what exists)
• Focused improvements (not complete redesigns)
• Continuous iteration cycles

---

What WDS is NOT

• Not a code framework
• Not a UI library
• Not a one-size-fits-all template

WDS is a thinking framework with templates to guide your design decisions.

---

The Agents

Three specialized agents help you:

You are currently working with one of these agents.

2. Ask Project Type

What type of project is this?

Understanding your starting point ensures you follow the right workflow.

[A] NEW Product (Greenfield) - Building from scratch -> Phase 1 [B] EXISTING Product (Brownfield) - Improving what exists -> Phase 8 [C] NOT SURE - We will analyze together

Your choice (A, B, or C):

3. Ask Alignment Requirement

Do you need stakeholder approval before starting?

[A] No - Ready to start -> Continue to project configuration [B] Yes - Need to pitch/create agreement -> Route to Alignment & Signoff workflow

Your choice (A or B):

4. Handle Routing

Based on user responses:

If alignment = [B] Need to pitch: 1. Route to: skill:wds-0-alignment-signoff 2. After alignment complete -> Return here for project configuration

If alignment = [A] Ready to start:

If [A] NEW Product: Continue to step-02-structure.md then Phase 1 If [B] EXISTING Product: Continue to step-02-structure.md then Phase 8 If [C] NOT SURE: Scan project, recommend path, then continue

5. Completion Output

Project type confirmed: [Greenfield/Brownfield] Next: Set up your project structure.

6. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Step 2: Configuration & Structure"

Menu Handling Logic:

• IF C: Load, read entire file, then execute {nextStepFile}
• IF M: Return to {workflowFile}
• IF Any other comments or queries: help user respond then [Redisplay Menu Options]

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects 'C'
• User can chat or ask questions - always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN the project type is confirmed and alignment decision is made will you then load and read fully {nextStepFile} to execute and begin the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• User understands WDS methodology at a high level
• Project type (greenfield/brownfield) is determined
• Alignment needs are assessed and routed correctly
• User feels oriented and confident about the path ahead

❌ SYSTEM FAILURE:

• Skipping project type determination
• Assuming greenfield or brownfield without asking
• Not assessing alignment needs
• Routing to wrong workflow path

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

---

_Phase 0: Project Setup - Step 01: Welcome & Orientation_

Design Log

Project: {{project_name}} Started: {{date}} Method: Whiteport Design Studio (WDS)

---

Backlog

Business-value items. Add links to detail files if needed.

• [ ] Complete product brief — Phase 1
• [ ] Define trigger map — Phase 2
• [ ] Create user scenarios — Phase 3

---

Current

Rules: Mark what you start. Complete it when done (move to Log). One task at a time per agent.

---

Design Loop Status

Per-page design progress. Updated by agents at every design transition.

Status values: discussed → wireframed → specified → explored → building → built → approved | removed

How to use:

• Append a row when a page reaches a new status (do not overwrite — latest row per page is current status)
• Read on startup to see where the project stands and what to suggest next

---

Log

{{date}} — Project initialized (Phase 0)

• Type: {{greenfield/brownfield}}
• Complexity: {{product_complexity}}
• Tech stack: {{tech_stack}}

---

About This Folder

• This file — Single source of truth for project progress
• agent-experiences/ — Compressed insights from design discussions (dated files)
• wds-project-outline.yaml — Project configuration from Phase 0 setup

Do not modify `wds-project-outline.yaml` — it is the source of truth for project configuration.