@hotelfriendag/design-tokens 0.3.0

package/RFC-0002-semantic-tier-naming.md

@@ -0,0 +1,296 @@
+# RFC-0002 — Semantic tier naming (Phase 1B)
+
+> **Status:** ✅ Accepted (2026-05-21) — implementation in progress
+> **Author:** Frontend platform
+> **Created:** 2026-05-21
+> **Implements:** RFC-0001 §4.1 (three-tier token architecture)
+> **Blocks:** Phase 1B implementation; Phase 2 component generator
+> **Scope:** naming convention only — does NOT define new color values
+
+## Resolutions (decided 2026-05-21)
+
+- **Q1, Q3, Q4, Q5, Q6, Q8**: defaults accepted as-is (see §6).
+- **Q2 — override**: keep **only 4 generic fg levels** (`default`, `muted`, `subtle`, `faint`). The portal-specific `fg-steel` (`#485B78`) and `fg-emphasis` (`#252F4A`) **do NOT promote to semantic tier**. They become **component-tier tokens in Phase 2** (used exclusively by `.hf-tab`/`.hf-pagination__item` inactive/active states). Until Phase 2 lands, these stay as bare hex in `components.css` with explicit TODO comments.
+- **Q7 — default + refinement**: drop `badge.*` from tokens (Option B), BUT the domain→semantic mapping (e.g. `booking.confirmed` → `info`) must NOT be hardcoded in `components.css` — that would re-introduce the drift RFC-0001 §5b warned about. Instead: create a new **`status-map.json`** file that the generator reads to emit `.status-{domain}-{state}` CSS classes. For Phase 1B implementation the map MAY temporarily live as a hardcoded block in `components.css`, but only with an explicit `TODO: extract to status-map.json` annotation and a separate Phase 2 task to externalize.
+
+## 1. Goal
+
+Restructure `tokens.figma.json` into three explicit tiers so:
+
+- **App code references roles, not raw values** (`bg-hf-bg-section` instead of `bg-hf-neutral-very-light`).
+- **Themes are swappable** at the semantic layer without touching primitives.
+- **AI agents have a stable, predictable token-set** to lean on when generating new products from the Blueprint.
+- **`pre-built/components.css` can be generated** from a single token source (Phase 2), instead of hand-mirrored from `components.html`.
+
+## 2. Conceptual model
+
+Three tiers, per W3C DTCG + Tokens Studio conventions:
+
+| Tier | Example | Purpose | Used by app code? |
+|------|---------|---------|-------------------|
+| **1. Primitive** | `hf-blue-500: #24AFE8` | Raw values, palette ramps | ❌ No |
+| **2. Semantic** | `hf-color-accent: {hf-blue-500}` | Role tokens — what app code references | ✅ Yes |
+| **3. Component** *(deferred → Phase 2)* | `hf-button-bg: {hf-color-accent}` | Component-specific overrides | ✅ Yes, if defined |
+
+> **Why three tiers, not two:** primitives are the only place colors actually live. Semantic aliases them by role. Components MAY alias semantics for cases where one component needs to drift (e.g. dark-mode-only overrides). Without primitives there's no source-of-truth; without semantics there's no theming.
+
+## 3. Naming conventions
+
+### 3.1 Primitive tier
+
+**Pattern:** `{type}-{family}-{step}`
+
+```
+hf-blue-500       — color, family=blue, step=500
+hf-gray-300       — color, family=gray, step=300
+hf-radius-md      — radius, family=md (single step)
+```
+
+- **Type:** `color`, `radius`, `space`, `shadow`, `font-size`, `font-weight`, `line-height`, `z`
+- **Family:** color-family-name OR direct value name (for non-color types)
+- **Step:** Tailwind-style numeric `50 / 100 / 200 / 300 / 400 / 500 / 600 / 700 / 800 / 900 / 950`. Lower = lighter (for light-on-dark families like gray, blue) or sparser (for accents).
+
+**Color families we need:**
+
+| Family | Anchor | Used by | Likely steps |
+|--------|--------|---------|--------------|
+| `blue` | `#24AFE8` @ 500 | primary brand | 50, 100, 500, 600 (anchored to portal) |
+| `gray` | `#2B2B2B` @ 900 | neutrals, text, borders | 25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950 (most populated ramp) |
+| `green` | `#59B59D` @ 500 | success, due-in, clean | 500 (single — phase 2 extend) |
+| `amber` | `#FFBD5A` @ 400 | warning, waiting, new | 400, 600 (#FFC900 frontdesk-OOO) |
+| `red` | `#EA6565` @ 400 | error, no-show, dirty | 400, 500 (#FB5A56), 700 (#D9534F) |
+| `orange` | `#F87921` @ 500 | coral, check-out, in-progress | 500, 700 (#A55505 due-out) |
+| `violet` | `#5761D8` @ 500 | offer, inspected | 500 |
+| `slate` | `#7F8FA4` @ 500 | canceled, deleted, OOS | 500 |
+| `olive` | `#5B7A02` @ 700 | check-in (lime) | 700 |
+
+**Why this granularity:** the portal palette is *already* sparse. Forcing full 50–950 ramps everywhere would mean inventing colors that don't exist in production. Phase 1B defines only what we actually use; Phase 2+ extends ramps if/when designer needs them (e.g. for dark mode).
+
+### 3.2 Semantic tier
+
+**Pattern:** `{type}-{slot}-{variant?}`
+
+```
+hf-color-fg-default         — type=color, slot=fg, variant=default (implicit)
+hf-color-fg-muted           — type=color, slot=fg, variant=muted
+hf-color-bg-surface         — slot=bg, variant=surface
+hf-color-accent-hover       — slot=accent, variant=hover
+hf-color-status-success     — slot=status, variant=success
+hf-color-status-success-bg  — slot=status, variant=success, sub-variant=bg
+```
+
+- **Slot** answers *"what role does this color play"*: `accent`, `bg`, `fg`, `border`, `status-*`
+- **Variant** answers *"what flavor of that role"*: `default` (implicit, dropped from emitted name), `muted`, `subtle`, `emphasis`, `hover`, `disabled`
+
+**Industry inspiration:**
+
+- GitHub Primer: `fgColor-default`, `fgColor-muted`, `bgColor-emphasis`
+- Atlassian: `ds-text-subtle`, `ds-background-input`
+- Radix / shadcn: `--primary` + `--primary-foreground` pair convention
+
+We borrow **slot.variant nesting** from Primer + the **`-foreground` pair** idea from Radix where it helps (e.g. `accent` + `on-accent` for text on top of accent backgrounds).
+
+### 3.3 Component tier (deferred)
+
+Component tokens come ONLY when a component diverges from the semantic layer. For Phase 1B we deliberately ship ZERO component tokens — everything binds to semantic. Phase 2 will introduce component tokens for cases like:
+
+- Button — if we want a primary button bg ≠ accent (e.g. dark variant)
+- Modal — if modal shadow ≠ generic floating-UI shadow
+- Pagination active — currently uses a unique `#252F4A` not represented by any other slot
+
+## 4. Proposed semantic tier — complete list
+
+### 4.1 Accent / brand (5 tokens)
+
+| Token | Aliases primitive | Replaces (Phase 1A name) |
+|-------|-------------------|-------------------------|
+| `hf-color-accent` | `hf-blue-500` | `--color-hf-primary` |
+| `hf-color-accent-hover` | `hf-blue-600` | `--color-hf-primary-hover` |
+| `hf-color-accent-subtle` | `hf-blue-100` | `--color-hf-primary-light-tint` (#E9F6FC) |
+| `hf-color-accent-subtler` | `hf-blue-50` | `--color-hf-primary-tint-bg` (#EFF6FF) |
+| `hf-color-on-accent` | `white` | implicit — for text on accent bg |
+
+### 4.2 Background slots (5 tokens)
+
+| Token | Aliases | Replaces |
+|-------|---------|----------|
+| `hf-color-bg-page` | `hf-gray-25` | `color-hf-neutral-light-grey` (#FBFBFC) |
+| `hf-color-bg-section` | `hf-gray-50` | `color-hf-neutral-bg-accent` (#F6F7FB) |
+| `hf-color-bg-muted` | `hf-gray-100` | `color-hf-neutral-very-light` (#F1F3F6) — used for hover, inputs |
+| `hf-color-bg-surface` | `white` | the "card" background |
+| `hf-color-bg-hover` | `#F5F5F5` | currently bare hex in `components.css` (dropdown hover) |
+
+> **Decision needed (Q1):** is `hf-color-bg-hover` (`#F5F5F5`) really distinct from `hf-color-bg-muted` (`#F1F3F6`)? Or fold them into one?
+
+### 4.3 Foreground (text) slots (6 tokens)
+
+| Token | Aliases | Replaces |
+|-------|---------|----------|
+| `hf-color-fg` *(no -default — see §6 Q4)* | `hf-gray-900` | `color-hf-text-primary` (#2B2B2B) |
+| `hf-color-fg-muted` | `hf-gray-700` | `color-hf-text-secondary` (#4B5675) |
+| `hf-color-fg-subtle` | `hf-gray-600` | `color-hf-text-useful` (#7E8EA6) — for hints |
+| `hf-color-fg-faint` | `hf-gray-400` | `color-hf-text-placeholder` (#AEBCCF) — placeholder, disabled |
+| `hf-color-fg-steel` | `hf-gray-800` | `color-hf-text-steel-blue` (#485B78) — tab/nav inactive |
+| `hf-color-fg-emphasis` | `hf-gray-950` | currently bare hex `#252F4A` in pagination active |
+
+> **Decision needed (Q2):** four levels of fg (default/muted/subtle/faint) plus two specific roles (steel, emphasis) — is that the right axis-count? Primer uses 4. Radix uses 2 (`fg` + `fg-muted`). Our portal currently uses 6+.
+
+### 4.4 Border slots (3 tokens)
+
+| Token | Aliases | Replaces |
+|-------|---------|----------|
+| `hf-color-border` | `hf-gray-300` | `color-hf-neutral-border` (#D1D6DD) — default |
+| `hf-color-border-subtle` | `hf-gray-200` | `color-hf-neutral-light-blue-gray` (#E4E8EF) — dividers |
+| `hf-color-border-strong` | `hf-gray-400` | `color-hf-neutral-border-hover` (#B2BAC4) — hover/focus |
+
+Plus implicitly: `hf-color-border-accent` = `hf-color-accent` for primary-bordered things.
+
+### 4.5 Status slots (semantic feedback)
+
+We need both `color` (text+border) and `bg` (15% alpha tint) per status. Two naming options:
+
+**Option A — flat slot suffix:**
+```
+hf-color-status-success
+hf-color-status-success-bg
+hf-color-status-success-fg     (same as -status-success — for text on the badge)
+hf-color-status-warning, -warning-bg, ...
+hf-color-status-error, -error-bg, ...
+hf-color-status-info, -info-bg, ...
+```
+
+**Option B — Radix-style pair:**
+```
+hf-color-success
+hf-color-success-foreground
+hf-color-success-subtle  (the 15% bg)
+```
+
+→ **Recommended: Option A** (mirrors GitHub Primer + closer to Tailwind utility derivation).
+
+Full list (Option A):
+
+| Token | Aliases | Note |
+|-------|---------|------|
+| `hf-color-status-success` | `hf-green-500` (#59B59D) | success, due-in, clean |
+| `hf-color-status-success-bg` | `rgba(89,181,157,.15)` | 15% alpha — used in pills + alert tints |
+| `hf-color-status-warning` | `hf-amber-400` (#FFBD5A) | warning, waiting, new |
+| `hf-color-status-warning-bg` | `rgba(255,189,90,.15)` | |
+| `hf-color-status-warning-strong` | `hf-amber-600` (#FFC900) | frontdesk out-of-order (more saturated) |
+| `hf-color-status-error` | `hf-red-400` (#EA6565) | error, no-show, dirty, action-required |
+| `hf-color-status-error-bg` | `rgba(234,101,101,.15)` | |
+| `hf-color-status-error-strong` | `hf-red-700` (#D9534F) | btn-danger (deeper) |
+| `hf-color-status-error-alt` | `hf-red-500` (#FB5A56) | btn-cancel-red, deleted (between rouge and crimson) |
+| `hf-color-status-info` | `hf-color-accent` (alias) | alert-info uses accent |
+| `hf-color-status-info-bg` | `rgba(36,175,232,.15)` | |
+| `hf-color-status-cancel` | `hf-slate-500` (#7F8FA4) | cancellations, deleted, OOS |
+| `hf-color-status-cancel-bg` | `rgba(127,143,164,.15)` | |
+| `hf-color-status-coral` | `hf-orange-500` (#F87921) | check-out, in-progress |
+| `hf-color-status-coral-bg` | `rgba(248,121,33,.15)` | |
+| `hf-color-status-violet` | `hf-violet-500` (#5761D8) | offer, inspected |
+| `hf-color-status-violet-bg` | `rgba(87,97,216,.15)` | |
+| `hf-color-status-olive` | `hf-olive-700` (#5B7A02) | check-in (rare, very dark) |
+| `hf-color-status-olive-bg` | `rgba(91,122,2,.15)` | |
+| `hf-color-status-orange-deep` | `hf-orange-700` (#A55505) | due-out (rare brown-orange) |
+| `hf-color-status-orange-deep-bg` | `rgba(165,85,5,.15)` | |
+
+> **Decision needed (Q3):** the last 5 (coral, violet, olive, orange-deep, cancel) are really portal-specific status colors, not generic semantic feedback. Worth a sub-namespace `hf-color-status-domain-{name}`?  Or just leave under `status-*` and document them as "portal status colors"?
+
+### 4.6 Domain status badges (replaces `badge.{domain}.{state}`)
+
+The current `badge.booking.confirmed.color/bg` structure has 4 levels of nesting — ugly in CSS (`--color-hf-badge-booking-confirmed-color`). Phase 1B options:
+
+**Option A — keep, just rebind to semantic:**
+```
+badge.booking.confirmed.color → semantic: {hf-color-status-info}
+badge.booking.confirmed.bg    → semantic: {hf-color-status-info-bg}
+```
+
+Pros: backwards-compatible class names (`status-booking-confirmed` still works).
+Cons: keeps the awkward CSS variable names.
+
+**Option B — drop `badge.*`, generate CSS classes from semantic tokens directly:**
+```
+.status-booking-confirmed → color: var(--hf-color-status-info); background: var(--hf-color-status-info-bg);
+.status-booking-new       → color: var(--hf-color-status-warning); background: var(--hf-color-status-warning-bg);
+...
+```
+The mapping (booking.confirmed→info, booking.new→warning, etc.) lives in `components.css` (or, in Phase 2, in a separate `status-map.json` that the generator reads).
+
+Pros: simpler tokens; semantic intent visible.
+Cons: lose the per-status-color granularity in tokens (e.g. can't theme `booking.confirmed` to be green without changing `info` globally).
+
+→ **Recommended: Option B**. The portal CURRENTLY uses status colors uniformly — every "confirmed" status is the same blue, every "completed" is the same green. There's no business reason for `booking.confirmed.color` ≠ `order.confirmed.color`. They share an underlying meaning.
+
+The CSS classes (`.status-booking-confirmed`, `.status-order-completed`, etc.) stay — they're the public API. They just point to semantic tokens instead of per-domain ones.
+
+### 4.7 Non-color types (font/space/radius/shadow)
+
+Keep the Phase 1A naming since these don't have a strong semantic layer in the portal:
+
+- `text-hf-xs/sm/base/md/lg/xl/2xl/h2/page/hero` (unchanged)
+- `radius-hf-sm/md/lg/xl` (unchanged)
+- `spacing-hf-0..8` (unchanged)
+- `shadow-hf-default/subtle/wrapper/card/modal/outline/hover` (unchanged)
+- `font-hf-sans` (unchanged)
+- `font-weight-hf-regular/medium/semibold` (unchanged)
+- `line-height-hf-headings/body/tight` (unchanged)
+
+> **Decision needed (Q5):** do we ALSO want a semantic layer for non-color? E.g. `--hf-radius-card: var(--hf-radius-lg)`, `--hf-shadow-elevated: var(--hf-shadow-card)`. Probably not — current names are role-y enough. Default: no.
+
+## 5. Tailwind v4 utility names (after Phase 1B)
+
+After re-generating, the Tailwind utilities consumers would write:
+
+```html
+<button class="bg-hf-accent hover:bg-hf-accent-hover text-hf-on-accent">
+  Save
+</button>
+
+<div class="bg-hf-bg-surface text-hf-fg border border-hf-border rounded-hf-lg">
+  Card content with <span class="text-hf-fg-muted">muted text</span>
+</div>
+
+<span class="text-hf-status-success bg-hf-status-success-bg border border-hf-status-success px-5 py-1.5 rounded-hf-sm">
+  Success
+</span>
+```
+
+Yes — `bg-hf-fg-muted` reads weird (it's a foreground color used as background). Tailwind v4 generates ALL utilities for any `--color-*` token. We can't restrict — just discipline consumers ("use text-* with fg slots, bg-* with bg slots").
+
+## 6. Open questions (need user decision)
+
+| # | Question | Default |
+|---|----------|---------|
+| Q1 | `bg-hover` (#F5F5F5) vs `bg-muted` (#F1F3F6) — distinct or merge? | Merge — use `bg-muted` everywhere; drop #F5F5F5 as portal drift |
+| Q2 | Number of fg axes — 4 generic (default/muted/subtle/faint) or 6 with portal-specific (steel, emphasis)? | 4 generic + the 2 portal-specific kept as separate `fg-steel`, `fg-emphasis` |
+| Q3 | Domain-specific status colors (coral/olive/orange-deep) — under `status-*` or `status-domain-*`? | Under `status-*` flat (simpler) |
+| Q4 | Drop `-default` suffix (use `hf-color-fg` instead of `hf-color-fg-default`)? | Yes — `default` is implicit |
+| Q5 | Semantic layer for non-color (radius, shadow, spacing)? | No — current names are role-y enough |
+| Q6 | Color ramps (50–950) — generate full, or sparse-as-needed? | Sparse-as-needed; complete in Phase 2 when designer adds dark mode |
+| Q7 | Recommended status badge structure — Option A (keep `badge.*`) or B (drop, map in CSS)? | Option B (drop `badge.*` from tokens) |
+| Q8 | `hf-color-accent` vs `hf-color-primary` for brand slot? | `accent` — matches Radix/Primer; less overloaded than `primary` (which conflicts with "primary text") |
+
+## 7. Files affected (Phase 1B implementation, post-approval)
+
+- **`tokens.figma.json`** — full restructure into `primitive` + `semantic` groups; `$themes` block becomes meaningful
+- **`generate-tokens.cjs`** — resolve Tokens Studio `{path}` references (alias resolution)
+- **`pre-built/tokens.css` / `tailwind.css`** — regenerated, emits both primitive AND semantic tokens
+- **`pre-built/components.css`** — rebind to semantic (e.g. `var(--hf-color-fg)` instead of `var(--color-hf-text-primary)`)
+- **`components.html`** — `@theme` block + demo markup updated to semantic names (sizeable HTML rewrite)
+- **All docs** — `bg-hf-primary` → `bg-hf-accent` etc.
+
+## 8. Recommended decision path
+
+1. **You review this RFC** and answer Q1–Q8 (or override any defaults).
+2. I draft the **new `tokens.figma.json` structure** (just the JSON) for one more review pass.
+3. Generator gets alias-resolution; regenerate `pre-built/*`.
+4. Rewrite `components.css` to use semantic tokens.
+5. Update docs + smoke test.
+6. *(Optional)* update `components.html` demo markup to semantic — sizable HTML rewrite, lower priority than the rest.
+
+Estimate: 1–2 days post-approval. Bottleneck is Q1–Q8 decisions.
+
+---
+
+**Next step for you:** read §4 and §6, mark up the questions or comment inline. After that I'll execute.