10 KiB

Raw Blame History

WDS Specification Pattern

Complete specification format for Whiteport Design Studio projects

Overview

This document defines the WDS Specification Pattern used in Phase 4 (UX Design) for all WDS projects.

Dog Week Start Page is used as the example implementation to demonstrate the pattern in action.

Related Documentation:

SKETCH-TEXT-ANALYSIS-GUIDE.md - How sketch analysis values are derived
HTML-VS-VISUAL-STYLES.md - HTML tags vs visual text styles
TRANSLATION-ORGANIZATION-GUIDE.md - Purpose-based text organization

Key Principles

1. Purpose-Based Naming

Text objects are named by function, not content:

✅ hero-headline (describes purpose)
❌ welcome-message (describes content)

2. Grouped Translations

All product languages grouped together per object for coherent review.

3. Estimated Values from Sketch Analysis

When text properties are estimated from sketch markers:

Spell out the values explicitly (e.g., 42px (est. from 24px spacing))
Mark with analysis note to show reasoning
Designer confirms or adjusts during specification dialog
Update with final values once confirmed

Analysis methodology: See SKETCH-TEXT-ANALYSIS-GUIDE.md for complete rules on deriving font weight, font size, line-height, and alignment from sketch markers.

This ensures transparency about which values came from AI interpretation vs. designer specification.

The Pattern in Action

Hero Section Example

### Hero Object

**Purpose**: Primary value proposition and main conversion action

#### Primary Headline

**OBJECT ID**: `start-hero-headline`

**HTML Structure:**

- **Tag**: h1
- **Semantic Purpose**: Main page heading for SEO and accessibility

**Visual Style:**

- **Style Name**: Hero headline
- **Font weight**: Bold (from 3px thick line markers in sketch)
- **Font size**: 56px (est. from 32px vertical spacing between line pairs)
- **Line-height**: 1.1 (est. calculated as font-size × 1.1)
- **Color**: #1a1a1a
- **Letter spacing**: -0.02em

**Position**: Center of hero section, above supporting text
**Alignment**: center

**Behavior**: Updates with language toggle

**Content**:

- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."

> **Sketch Analysis:** Line thickness (3px) → Bold weight. Line spacing (32px) → ~56px font size estimate. Designer should confirm these values.

#### Supporting Text

**OBJECT ID**: `start-hero-supporting`

**HTML Structure:**

- **Tag**: p
- **Semantic Purpose**: Paragraph text providing additional context

**Visual Style:**

- **Style Name**: Body text large
- **Font weight**: Regular (from 1px thin line markers in sketch)
- **Font size**: 18px (est. from 14px vertical spacing between line pairs)
- **Line-height**: 1.5 (est. calculated as font-size × 1.5)
- **Color**: #4a4a4a

**Position**: Below headline, above CTA, center-aligned
**Alignment**: center

**Behavior**: Updates with language toggle

**Content**:

- EN: "Organize your family around dog care. Never miss a walk again."
- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."

> **Sketch Analysis:** Line thickness (1px) → Regular weight. Line spacing (14px) → ~18px font size estimate. Designer should confirm these values.

#### Primary CTA Button

**OBJECT ID**: `start-hero-cta`

- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
- **Position**: Center, below supporting text, 24px margin-top
- **Behavior**: Navigate to /auth/signup
- **States**: default, hover, active, loading
- **Content**:
  - EN: "start planning - free forever"
  - SE: "börja planera - gratis för alltid"

Reading in English:

Every walk. on time. Every time. Organize your family around dog care. Never miss a walk again. [start planning - free forever]

Reading in Swedish:

Varje promenad. i tid. Varje gång. Organisera din familj kring hundvård. Missa aldrig en promenad igen. [börja planera - gratis för alltid]

The Complete Process

Step 1: Sketch Analysis (4B)

Agent sees sketch with horizontal lines:

═══════════════════════════════  ← Line 1 (thick, 3px)
═══════════════════════════      ← Line 2 (thick, 3px)

─────────────────────────────────────────  ← Line 3 (thin, 1px)
─────────────────────────────────────────  ← Line 4 (thin, 1px)

┌─────────────────────────────┐
│  start planning             │  ← Button
└─────────────────────────────┘

Agent identifies:
1. TEXT GROUP (2 thick lines) - Hero headline
2. TEXT GROUP (2 thin lines) - Supporting text
3. BUTTON - CTA

Step 2: Object Detection (4C-03 + object-router)

For Object 1:
  → Detects horizontal lines
  → TEXT DETECTED
  → Routes to heading-text.md

heading-text.md:
  → Asks: "What's the PURPOSE?" → "Primary Headline"
  → Object ID: `start-hero-headline`
  → Sketch analysis: 2 lines, 3px thick, ~50-60 chars
  → Content guidance: Brief heading, 2 short lines
  → Requests content with length validation

Step 3: Content with Grouped Translations

Agent asks:

"What's the content for Primary Headline?

Based on sketch: 2 lines, ~50-60 characters total

I found text in your sketch: 'Every walk. on time. Every time.'

Let me suggest translations...

EN: Every walk. on time. Every time.
SE: Varje promenad. i tid. Varje gång.

Do these work? [1] Use these [2] Adjust [3] Manual"

User provides:
1  ← Accepts suggestions!

Agent validates:
✅ EN: 37 chars (fits 60 capacity)
✅ SE: 36 chars (fits 60 capacity)

Step 4: Generate Specification

#### Primary Headline

**OBJECT ID**: `start-hero-headline`

- **Component**: H1 heading
- **Position**: Center of hero
- **Style**: Bold, 42px, line-height 1.2
- **Content**:
  - EN: "Every walk. on time. Every time."
  - SE: "Varje promenad. i tid. Varje gång."

Key Advantages

1. Purpose-Based Object IDs

Stable Naming:

Content changes don't affect Object IDs
IDs remain semantic and meaningful
Easy to find by function

Examples:

`start-hero-headline` ← Purpose clear
`signin-form-email-label` ← Function clear
`profile-success-message` ← Role clear

2. Separated Concerns

Structure/Style (rarely changes):

- **Component**: H1 heading
- **Position**: Center of hero
- **Style**: Bold, 42px

Content (often changes):

- **Content**:
  - EN: "..."
  - SE: "..."

3. Grouped Translations

Benefits:

Each language reads as complete message
Translator sees full context
Natural language flow
Easy to verify coherence

Format:

### Text Group

#### Element 1

- EN: "..."
- SE: "..."

#### Element 2

- EN: "..."
- SE: "..."

#### Element 3

- EN: "..."
- SE: "..."

4. Character Capacity Validation

From Sketch Analysis:

Agent: "Sketch shows 2 lines, ~50-60 chars capacity"

User provides: "Every walk. on time. Every time." (37 chars)

Agent: "✅ Content fits within sketch capacity!"

If too long:

Agent: "⚠️ Your content (85 chars) exceeds capacity (60 chars).
Consider shortening or adjusting font size."

Complete Workflow Integration

4B: Sketch Analysis
    ↓
    Identifies text groups, estimates capacity
    ↓
4C-03: Components & Objects
    ↓
    object-router.md
        ↓
        STEP 1: TEXT DETECTION (checks horizontal lines)
        ↓
        If text → heading-text.md
            ↓
            1. Ask PURPOSE (not content)
            2. Generate Object ID from purpose
            3. Specify position/style
            4. Request content with grouped translations
            5. Validate against sketch capacity
            6. Generate specification (Dog Week format)
            ↓
        Return to 4C-03
    ↓
4C-04: Content & Languages
    (Already captured in heading-text.md)
    ↓
4C-08: Generate Final Spec

Template Structure

Every text element follows this format:

#### {{Purpose_Title}}

**OBJECT ID**: `{{page-section-purpose}}`

- **Component**: {{type}} ({{class_or_ref}})
- **Position**: {{position_description}}
  {{#if has_behavior}}
- **Behavior**: {{behavior_description}}
  {{/if}}
  {{#if has_style_details}}
- **Style**: {{style_specifications}}
  {{/if}}
  {{#if links_to_input}}
- **For**: {{input_object_id}}
  {{/if}}
- **Content**:
  - EN: "{{english_text}}"
  - SE: "{{swedish_text}}"
    {{#each additional_language}}
  - {{code}}: "{{text}}"
    {{/each}}

Real Dog Week Specifications

These follow the exact pattern we're implementing:

From 1.1-Start-Page.md:

#### Primary Headline

**OBJECT ID**: `start-hero-headline`

- **Component**: H1 heading (`.text-heading-1`)
- **Content**:
  - EN: "Every walk. on time. Every time."
  - SE: "Varje promenad. i tid. Varje gång."

#### Primary CTA Button

**OBJECT ID**: `start-hero-cta`

- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
- **Content**:
  - EN: "start planning - free forever"
  - SE: "börja planera - gratis för alltid"

From 1.2-Sign-In.md (Header example):

#### Sign In Button

**OBJECT ID**: `start-header-signin`

- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md)
- **Content**:
  - EN: "Sign in"
  - SE: "Logga in"
- **Behavior**: Navigate to sign-in page

Specification Checklist

For each text element:

Purpose-based name (not content-based)
Object ID from purpose: {page}-{section}-{purpose}
Component reference specified
Position clearly described
Style separated from content
Behavior specified if applicable
Content with grouped translations:
- EN: "..."
- SE: "..."
- Additional languages if needed
Character length validated against sketch
Part of text group if applicable

This is the WDS standard for text specifications, proven by Dog Week! 🎨🌍✨

10 KiB Raw Blame History Unescape Escape