whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-11-conceptual-specifications/lesson-04-spacing-objects.md

@@ -0,0 +1,192 @@
+# Module 11: Conceptual Specifications
+
+## Lesson 4: Spacing as First-Class Objects
+
+**The invisible layer that holds everything together**
+
+---
+
+## The Gap Is Not Empty
+
+Look at a well-designed page. Between the header and the hero. Between the cards in a grid. Between a heading and the paragraph below it.
+
+That space is not "nothing." It's a design decision.
+
+In WDS, **spacing is a first-class object** — it has an ID, a type, and a value, just like a button or a card.
+
+---
+
+## Why Spacing Gets an ID
+
+Without IDs, spacing conversations sound like this:
+
+> "Add more space between the trust section and the seasons section"
+
+With IDs, they sound like this:
+
+> "Change `hem-v-space-3xl` to `space-4xl`"
+
+The second version is precise, traceable, and can be found in the design system. The first version requires the developer to figure out which space you mean.
+
+---
+
+## The Naming Convention
+
+```
+{page}-{v|h}-{type}-{size}
+```
+
+| Part | Meaning | Examples |
+|------|---------|---------|
+| `{page}` | Which page | `hem`, `nyheter`, `om-oss` |
+| `{v\|h}` | Direction | `v` = vertical, `h` = horizontal |
+| `{type}` | What kind | `space`, `separator`, `line` |
+| `{size}` | Token value | `zero`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `flex` |
+
+**The ID describes WHAT the spacing IS, not what it sits between.**
+
+### Examples
+
+```markdown
+#### ↕ `hem-v-space-zero` — header and service menu form one continuous nav unit
+#### ↕ `hem-v-separator-2xl` — gray line, space-2xl above and below
+#### ↕ `hem-v-space-3xl` — major section boundary between seasons and footer
+```
+
+---
+
+## Zero Spacing Is a Decision
+
+When two objects touch with no gap, that's a deliberate design choice:
+
+```markdown
+#### ↕ `hem-v-space-zero` — hero sits flush below navigation, background color shift provides visual separation
+```
+
+If you don't document this, a future developer might "fix" it by adding spacing. Zero spacing says: "This is intentional. Don't add a gap."
+
+---
+
+## How Spacing Appears in Page Specs
+
+Between each section, an explicit spacing object:
+
+```
+┌──────────────────────────┐
+│  Site Header             │
+├──────────────────────────┤
+│ ↕ hem-v-space-zero       │  ← spacing object
+├──────────────────────────┤
+│  Service Menu            │
+├──────────────────────────┤
+│ ↕ hem-v-space-zero       │  ← spacing object
+├──────────────────────────┤
+│  Hero Section            │
+├──────────────────────────┤
+│ ↕ hem-v-space-zero       │  ← spacing object (bg color shift)
+├──────────────────────────┤
+│  About Section           │
+├──────────────────────────┤
+│ ↕ hem-v-separator-2xl    │  ← gray line with equal spacing
+├──────────────────────────┤
+│  Trust Cards             │
+├──────────────────────────┤
+│ ↕ hem-v-space-3xl        │  ← major boundary
+├──────────────────────────┤
+│  Season Cards            │
+└──────────────────────────┘
+```
+
+---
+
+## Group-Level vs. Individual Spacing
+
+When all items in a grid share the same spacing, define it **on the container**:
+
+```markdown
+| Grid gap | h-space-lg / v-space-lg (24px) |
+```
+
+Don't create separate spacing objects between card 1 and card 2, card 2 and card 3. The grid gap handles it.
+
+Individual spacing objects are for **between sections** and **non-uniform gaps**.
+
+---
+
+## Internal Spacing
+
+Spacing inside a component (image-to-heading, heading-to-teaser inside a card) is NOT specified upfront. It's added only when the designer explicitly requests it during visual review.
+
+```markdown
+<!-- Internal spacing (image->heading, heading->teaser, content padding)
+     is NOT specified yet. Add here only when the designer requests it. -->
+```
+
+This follows the emergent principle: don't design what hasn't been needed yet.
+
+---
+
+## Spacing in the Design System
+
+Spacing objects go to the design system **immediately on first use** — unlike regular objects which extract on second use.
+
+Why? Because spacing is relational. When you decide that a heading needs `space-xl` above a card grid, that's a universal design principle, not a page-specific detail.
+
+The design system organizes patterns by spacing value:
+
+```markdown
+### v-space-3xl
+| Above | Below | Why |
+|-------|-------|-----|
+| `trust-section` | `seasons-section` | Major section boundary |
+| `seasons-section` | `site-footer` | Major section boundary |
+
+### v-space-zero
+| Above | Below | Why |
+|-------|-------|-----|
+| `site-header` | `service-menu` | One continuous nav unit |
+| `service-menu` | `hero` | Flush below navigation |
+```
+
+As more pages are designed, each spacing value accumulates more situations. The pattern table grows from real decisions.
+
+---
+
+## How Many Spacing Objects Per Page?
+
+On a typical homepage with 8 sections:
+
+- **6 spacing objects** between sections
+- **4 sections** with internal spacing properties (padding, grid gap)
+- **10 total** spacing declarations
+
+That's lean. One or two per section boundary. Not dozens.
+
+---
+
+## The Communication Pattern
+
+Always use token names when discussing spacing:
+
+```
+BAD:  "Add 48 pixels above the footer"
+GOOD: "Change hem-v-space-3xl to space-4xl above the footer"
+```
+
+This builds a shared vocabulary. Over time, the designer and developer both think in tokens.
+
+---
+
+## What's Next
+
+In the next module, you'll learn how patterns emerge across pages and when to extract them into reusable components.
+
+---
+
+**[Continue to Lesson 5: Typography Tokens →](lesson-05-typography-tokens.md)**
+
+---
+
+[← Back to Lesson 3](lesson-03-element-state-specifications.md) | [Back to Module Overview](module-11-conceptual-specifications-overview.md)
+
+*Part of Module 11: Conceptual Specifications*

package/docs/learn/module-11-conceptual-specifications/lesson-05-typography-tokens.md

@@ -0,0 +1,157 @@
+# Module 11: Conceptual Specifications
+
+## Lesson 5: Typography Tokens — Size Is Not Structure
+
+**Decoupling visual size from semantic meaning**
+
+---
+
+## The Problem
+
+Most design systems conflate two things:
+
+- **Visual size** — how big text looks
+- **Semantic level** — what the text means (H1, H2, H3, p)
+
+This creates rigid rules like "H1 is always 48px" or "H2 is always 32px." But reality doesn't work that way.
+
+A landing page H1 might be a serif display font at 56px italic.
+An admin page H1 might be clean sans-serif at 20px medium.
+A sidebar H2 might be 14px.
+
+The semantic level is for accessibility and SEO. The visual token is for hierarchy.
+
+---
+
+## The WDS Approach
+
+Two independent systems:
+
+### Heading Scale (Visual Size)
+
+| Token | Size | Weight | Example Use |
+|-------|------|--------|-------------|
+| `heading-xxs` | 14px | 700 | Smallest sub-headers |
+| `heading-xs` | 16px | 700 | Minor headings, labels |
+| `heading-sm` | 18px | 700 | Card sub-headings |
+| `heading-md` | 20px | 800 | Card headings |
+| `heading-lg` | 24px | 800 | Section sub-headers |
+| `heading-xl` | 30px | 900 | Section headers |
+| `heading-2xl` | 36px | 900 | Major section headers |
+| `heading-3xl` | 44px | 900 | Hero headings (tablet) |
+| `heading-4xl` | 56px | 900 | Hero headings (desktop) |
+
+### Semantic Level (Document Structure)
+
+`<h1>`, `<h2>`, `<h3>`, `<p>` — these define the document outline for accessibility and SEO.
+
+### How They Combine
+
+```html
+<h2 class="text-heading-lg md:text-heading-xl lg:text-heading-2xl">
+  Our Services
+</h2>
+```
+
+This `<h2>` is `heading-lg` on mobile, `heading-xl` on tablet, `heading-2xl` on desktop. The semantic level stays H2 on all devices. The visual size adapts.
+
+---
+
+## The Responsive Scaling Rule
+
+Step up one token size per breakpoint:
+
+```
+Mobile:  heading-lg   (24px)
+Tablet:  heading-xl   (30px)
+Desktop: heading-2xl  (36px)
+```
+
+In code:
+```html
+<h2 class="text-heading-lg md:text-heading-xl lg:text-heading-2xl">
+```
+
+In specifications:
+```markdown
+| Visual size | heading-lg / heading-xl / heading-2xl |
+```
+
+Always use token names — never arbitrary pixel values per breakpoint.
+
+---
+
+## Body Type Scale
+
+The same principle applies to body text:
+
+| Token | Size | Weight | Usage |
+|-------|------|--------|-------|
+| `text-body` | 16px | 400 | Body text |
+| `text-body-small` | 14px | 400 | Captions, metadata |
+| `text-body-large` | 18px | 400 | Lead paragraphs |
+| `text-label` | 14px | 600 | Labels, badges |
+| `text-phone` | 24px | 700 | Phone number CTA |
+
+---
+
+## Why Tokens Beat Pixel Values
+
+### 1. Single Point of Change
+
+Bump `heading-xl` from 30px to 32px and every section header on the site adjusts. No hunting through files.
+
+### 2. Shared Vocabulary
+
+"Change the heading from `heading-lg` to `heading-xl`" is precise. "Make it bigger" is not.
+
+### 3. Consistent Hierarchy
+
+Tokens enforce a scale. You can't accidentally use 31px when the scale goes 30, 36, 44.
+
+### 4. Responsive by Default
+
+Each token has responsive variants built in. No reinventing breakpoint behavior per element.
+
+---
+
+## When Tokens Emerge
+
+Don't create the full type scale before building any pages.
+
+Build pages first. Notice that you keep using the same sizes. Extract the scale from real usage.
+
+On the Kalla project, the heading scale emerged after the homepage was built and refined through browser review. The same heading sizes appeared 3+ times in different sections — that's when they became tokens.
+
+---
+
+## Specifying Typography in Page Specs
+
+```markdown
+### Section Heading
+
+**OBJECT ID:** `hem-trust-heading`
+**DS TYPE:** `section-heading`
+
+| Property | Value |
+|----------|-------|
+| Tag | h2 |
+| Visual size | heading-xl / heading-xl / heading-2xl |
+| Font family | font-headline (Inter) |
+| Font weight | 900 |
+| Color | text-primary (#141414) |
+```
+
+Notice: the semantic tag (`h2`) and the visual size (`heading-xl`) are independent. The same component template can be used for an H2 on one page and an H3 on another.
+
+---
+
+## What's Next
+
+You now understand the three invisible specification layers: spacing objects (Lesson 4), typography tokens (this lesson), and the dual-ID system that connects them to the design system (Module 12).
+
+---
+
+[← Back to Lesson 4](lesson-04-spacing-objects.md) | [Back to Module Overview](module-11-conceptual-specifications-overview.md)
+
+*Part of Module 11: Conceptual Specifications*