Spacing naming convention and extraction rules for design system

- Page spec template: rename -gap to -space, use {page}-{v|h}-{type}-{size} naming
- Design system template: objects extract on 2nd use, spacing extracts immediately
- Pattern examples updated with Above/Below/Why table format

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/workflows/0-project-setup/templates/folder-guides/00-design-system.template.md

@@ -198,9 +198,10 @@ _Additional design tokens (colors, shadows, borders) will be documented here as
   The agent does NOT ask "why?" — it observes and reflects:
   "Got it — large image above a card row needs extra room. I'll remember that."
 
-  First occurrence: one-off fix in the page spec.
+  EXTRACTION RULES — objects vs spacing:
-  Second occurrence: agent applies the same pattern.
+  - Objects: first use stays in the page spec. Second use → extract here.
-  Third time: extract it here.
+  - Spacing: first use → immediately extract here. No waiting.
+  Spacing is relational — a decision about two object types is universal from day one.
 
   CONTEXT RULE: Entries are context-free by default (universal).
   Add context only when the same object pair needs DIFFERENT spacing
@@ -208,7 +209,7 @@ _Additional design tokens (colors, shadows, borders) will be documented here as
   so you can tell them apart. Before the first violation, keep it clean.
 -->
 
-Spacing objects are first-class — they have IDs in page specs (e.g., `hem-heading-subtitle-gap`) and live here organized by value. Each spacing value accumulates the situations where it's used. The list grows from real design decisions.
+Spacing objects are first-class — they have IDs in page specs (e.g., `hem-v-space-xl`) and live here organized by value. Each spacing value accumulates the situations where it's used. The list grows from real design decisions.
 
 _Patterns will be documented here as spacing objects recur across pages._
 
@@ -216,29 +217,27 @@ _Patterns will be documented here as spacing objects recur across pages._
   Example format (delete when real patterns emerge):
 
   ### space-sm
-  - Between heading and subheading
+  | Above | Below | Why |
-  - Between icon and label inside buttons
+  |-------|-------|-----|
-  - Between badge dot and badge text
+  | Heading | Subheading | Tight pair — always read together |
+  | Icon | Label (inside button) | Compact inline group |
 
   ### space-lg
-  - Card grid gap
+  | Above | Below | Why |
-  - Between image and caption
+  |-------|-------|-----|
-  - Between form field groups
+  | Card | Card (grid gap) | Comfortable breathing room |
-
+  | Image | Caption | Standard image-to-text |
-  ### space-md
-  - Between image and caption (article page, inline photo — smaller image needs less room)
-  Note: space-lg also has "Between image and caption" — context added to both
-  because article pages are an exception to the universal rule.
 
   ### space-zero
-  - Vehicle icon bar flush against section below (homepage hero)
+  | Above | Below | Why |
-  - Nav items touching divider lines (service menu)
+  |-------|-------|-----|
+  | Header | Service menu | One continuous nav unit |
+  | Icon bar | Section below | Flush — belongs to the section above |
 
-  ### space-2xl / line / space-2xl
+  ### v-separator-2xl
-  - Between content groups within a section when a visual break is needed
+  | Above | Below | Why |
-
+  |-------|-------|-----|
-  ### space-xl + space-xs
+  | About preview | Trust cards | Gray line, equal space above/below |
-  - Below busy content blocks before card rows
 -->
 
 ---

src/workflows/4-ux-design/templates/page-specification.template.md

@@ -152,23 +152,30 @@
 | EN | "{English text}" |
 | Behavior | {onClick / onChange / etc.} |
 
-#### ↕ `{page-name}-{above}-{below}-gap` — {spacing token}
+#### ↕ `{page}-{v|h}-{type}-{size}` — {reason}
 
 <!--
   Spacing objects sit between content objects. They have IDs and are first-class.
 
+  NAMING: {page}-{v|h}-{type}-{size}
+  - v = vertical, h = horizontal
+  - type = space, separator, line
+  - size = the token name (zero, sm, md, lg, xl, 2xl, 3xl, flex)
+  The ID describes WHAT the spacing IS, not which objects it sits between.
+
   RULES:
-  - Default element gap (from the Spacing section above) is implicit — no spacing object needed.
+  - Default element spacing (from the Spacing section above) is implicit — no spacing object needed.
   - Non-default spacing MUST be an explicit spacing object with an ID.
   - Zero spacing (overlap / flush) MUST be documented: ↕ `id` — space-zero (reason)
+  - Same spacing shared by all items in a group → define on the group, not between each item.
   - Spacing objects flow into D-Design-System/00-design-system.md → Patterns.
 
-  FORMAT: #### ↕ `{id}` — {token} [{optional reason}]
+  FORMAT: #### ↕ `{id}` — {reason}
 
   EXAMPLES:
-  #### ↕ `hem-heading-subtitle-gap` — space-sm
+  #### ↕ `hem-v-space-zero` — header and service menu form one continuous nav unit
-  #### ↕ `hem-icons-about-gap` — space-zero (icon bar sits flush against section below)
+  #### ↕ `hem-v-separator-2xl` — gray line, space-2xl above and below. Separates about from trust cards.
-  #### ↕ `hem-about-trust-gap` — space-xl + space-xs (busy content needs breathing room)
+  #### ↕ `hem-v-space-3xl` — major section boundary between seasons and footer
 -->
 
 ---