4.7 KiB

Raw Blame History

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.

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

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)

Design individual components
Try to arrange them into sections
Hope the page makes sense
Realize it doesn't flow logically
Start over

Right Approach (Top-Down)

Identify page sections - What major areas exist?
Define section purposes - Why does each section exist?
Confirm flow logic - Does the story make sense?
Detail each section - Now design components
Specify components - With clear purpose and context

Result: Logical flow, no gaps, confident specifications

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":

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"?
Developer-Ready - Could someone build this confidently?

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"

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

File Naming: ../../workflows/00-system/FILE-NAMING-CONVENTIONS.md
Language Config: ../../workflows/00-system/language-configuration-guide.md
Page Spec Template: ../../workflows/4-ux-design/templates/page-specification.template.md

Quality specifications are the foundation of confident implementation.

4.7 KiB Raw Blame History