initial commit
This commit is contained in:
@@ -0,0 +1,436 @@
|
||||
# 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
|
||||
|
||||
```markdown
|
||||
### 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
|
||||
|
||||
```markdown
|
||||
#### 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:**
|
||||
|
||||
```markdown
|
||||
`start-hero-headline` ← Purpose clear
|
||||
`signin-form-email-label` ← Function clear
|
||||
`profile-success-message` ← Role clear
|
||||
```
|
||||
|
||||
### 2. Separated Concerns
|
||||
|
||||
**Structure/Style** (rarely changes):
|
||||
|
||||
```markdown
|
||||
- **Component**: H1 heading
|
||||
- **Position**: Center of hero
|
||||
- **Style**: Bold, 42px
|
||||
```
|
||||
|
||||
**Content** (often changes):
|
||||
|
||||
```markdown
|
||||
- **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:**
|
||||
|
||||
```markdown
|
||||
### 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:**
|
||||
|
||||
```markdown
|
||||
#### {{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:**
|
||||
|
||||
```markdown
|
||||
#### 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):**
|
||||
|
||||
```markdown
|
||||
#### 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!** 🎨🌍✨
|
||||
Reference in New Issue
Block a user