5.9 KiB

Raw Blame History

HTML Tags vs. Visual Text Styles

Critical Best Practice for WDS Specifications

The Two-Layer System

Layer 1: HTML Semantic Structure (h1-h6, p, etc.)

Purpose: SEO, accessibility, document outline, screen readers

Rules:

Each page must have exactly ONE h1 (main page title)
Heading hierarchy must be logical (h1 → h2 → h3, no skipping)
Same across all pages for semantic consistency
Not about visual appearance

Layer 2: Visual Text Styles (Design System)

Purpose: Visual hierarchy, branding, design consistency

Rules:

Named by visual purpose (Display-Large, Headline-Primary, Body-Regular, etc.)
Can be applied to any HTML tag
Different pages can use different visual styles for the same HTML tag
About appearance, not semantics

Why Separate?

Problem: Mixing HTML and Visual Styles

❌ BAD:

- **Style**: H1 heading

What does this mean?

- Is it an h1 tag?
- Is it a visual style that looks like an h1?
- What if another page needs h1 but different visual style?

Solution: Specify Both Independently

✅ GOOD:

- **HTML Tag**: h1 (semantic structure)
- **Visual Style**: Display-Large (from Design System)

Now we know:

HTML: This is the main page heading (h1 for SEO)
Visual: It uses the "Display-Large" design system style
Another page could have: h1 + Headline-Medium (different visual, same semantic)

Real-World Examples

Example 1: Landing Page vs. Article Page

Landing Page - Hero Headline:

- **HTML Tag**: h1
- **Visual Style**: Hero headline
- **Font**: Bold, 56px, line-height 1.1

Article Page - Article Title:

- **HTML Tag**: h1
- **Visual Style**: Main header
- **Font**: Bold, 32px, line-height 1.3

Both are h1 (semantic), but different visual styles!

Example 2: Same Visual Style, Different Semantics

Section Heading:

- **HTML Tag**: h2
- **Visual Style**: Sub header
- **Font**: Bold, 28px, line-height 1.2

Testimonial Quote:

- **HTML Tag**: p
- **Visual Style**: Sub header
- **Font**: Bold, 28px, line-height 1.2

Same visual style (Sub header), but different HTML tags for proper semantics!

Design System Visual Style Naming

Good Visual Style Names (Descriptive & Purpose-Based)

For Headers: ✅ Main header - Primary page header ✅ Sub header - Section headers ✅ Sub header light - Lighter variant of section header ✅ Card header - Headers within cards ✅ Small header - Minor headers, labels

For Body Text: ✅ Body text - Standard paragraph text ✅ Body text large - Larger body text for emphasis ✅ Body text small - Smaller body text, secondary info ✅ Intro text - Opening paragraph, lead text

For Special Purposes: ✅ Hero headline - Large display text for hero sections ✅ Caption text - Image captions, metadata ✅ Label text - Form labels, UI labels ✅ Error text - Error messages ✅ Success text - Success messages ✅ Link text - Link styling ✅ Button text - Text within buttons

Bad Visual Style Names

❌ H1-Style / Heading-1 - Confuses with HTML tags ❌ Text-Size-42 - Just a number, not semantic ❌ Big-Text - Too vague ❌ Display-Large - Too abstract (unless using design system tokens)

WDS Specification Format

Complete Example

#### Primary Headline

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

**HTML Structure:**

- **Tag**: h1
- **Purpose**: Main page heading (SEO/accessibility)

**Visual Style:**

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

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

**Behavior**: Updates with language toggle

**Content**:

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

Benefits of This Approach

✅ Flexibility - Different pages can have different visual styles for same semantic tags ✅ Consistency - Design system ensures visual consistency across visual styles ✅ SEO/Accessibility - Proper HTML structure maintained ✅ Scalability - Easy to add new visual styles without breaking semantic structure ✅ Clarity - Designers and developers both understand the specification ✅ Reusability - Visual styles can be reused across different HTML tags

Common Patterns

Pattern 1: Landing Page

h1 → Hero headline (big hero text, 56px)
h2 → Sub header (section headings, 32px)
h3 → Small header (subsection headings, 24px)
p → Body text (regular paragraphs, 16px)

Pattern 2: Blog Post

h1 → Main header (article title, 36px)
h2 → Sub header (section headings, 28px)
h3 → Sub header light (subsection headings, 22px)
p → Body text large (article body, 18px)

Pattern 3: Dashboard

h1 → Main header (page title, 28px)
h2 → Card header (widget titles, 20px)
h3 → Small header (section labels, 16px)
p → Body text small (compact info, 14px)

Same HTML structure (h1, h2, h3, p) but different visual styles for each context!

Implementation Note

When generating HTML prototypes or handing off to developers:

<!-- The HTML tag is semantic, the class references the visual style -->
<h1 class="hero-headline">Every walk. on time. Every time.</h1>

<!-- Another page might have -->
<h1 class="main-header">Welcome to Your Profile</h1>

<!-- NOT this (mixing concerns) -->
<h1 class="h1">Every walk. on time. Every time.</h1>

The CSS class references the visual style name (hero-headline, main-header), not the HTML tag.

Remember: HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯

5.9 KiB Raw Blame History