@hotelfriendag/design-tokens 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HotelFriend AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,558 @@
+# HotelFriend Design System
+
+Cross-project design foundation: tokens, generated outputs for every stack (CSS / SCSS / TS / Tailwind v3 + v4 / shadcn), the `.hf-*` component layer, and AI-tool rules.
+
+> **Extracted on 2026-05-25** from [`hotelfriend/backend-hf`](https://bitbucket.org/hotelfriend/backend-hf) `docs/portable-design/` to make this the single source of truth that other HotelFriend projects consume.
+>
+> **Status:** RFC-0001 Phase 1 complete (semantic three-tier model + collision-safe prefixing + drift CI). Versioned package distribution (`@hotelfriendag/design-tokens` via GitHub Packages) is the next step — see `RFC-0001-cross-project-design-system.md` §9 for the full status checklist.
+
+## File hierarchy (read in this order)
+
+```
+portable-design/
+│
+├── components.html            ← PRIMARY · canonical visual reference (open in browser)
+├── UI_DESIGN.md               ← NARRATIVE · rationale, anatomy, decisions (AI reads this first)
+├── tokens.figma.json          ← TOKENS · atomic Tokens Studio export → feeds Figma + generators
+│
+├── pre-built/                 ← GENERATED · drop one into your stack's build pipeline
+│   ├── tailwind.css               · Tailwind v4 @theme block (recommended)
+│   ├── tailwind.preset.js         · Tailwind v3 preset (legacy)
+│   ├── tokens.css                 · vanilla CSS custom properties
+│   ├── _tokens.scss               · SCSS variables
+│   ├── tokens.ts                  · TypeScript const
+│   ├── shadcn-tokens.css          · shadcn/ui contract
+│   └── components.css             · .hf-* component primitives (extracted from components.html)
+│
+├── states-canonical.json      ← curated interactive states for new components (use this)
+├── states.json                ← raw portal extraction (160 KB — prefer states-canonical.json)
+├── generate-tokens.cjs         ← Node script (no deps) — turns tokens into Tailwind/CSS/SCSS/TS/shadcn
+│
+├── ai-rules/                  ← drop ONE into the new project's root
+│   ├── CLAUDE.md                  · for Claude Code (autodetected)
+│   ├── cursorrules.template       · rename to .cursorrules
+│   ├── github-copilot-instructions.md · put at .github/copilot-instructions.md
+│   └── system-prompt-compact.md   · compact prompt for ChatGPT/v0/Lovable
+│
+├── portal-audit.html          ← ARCHIVAL · legacy portal audit snapshot (NOT for new code)
+└── README.md                  ← you are here (quickstart)
+```
+
+### Precedence rule — when files disagree
+
+1. **`components.html`** — canonical for **visual decisions** (colors, sizes, anatomy)
+2. **`tokens.figma.json`** — canonical for **token values**. Regenerate `pre-built/*` after editing
+3. **`UI_DESIGN.md`** — canonical for **WHY decisions were made** (history, trade-offs, portal drift notes)
+4. **`pre-built/*`** — **generated**, never hand-edit. Re-run `generate-tokens.cjs` after JSON changes
+5. **`portal-audit.html`** — **archival only**. Shows what the legacy portal currently looks like — useful for migration tracking, NOT for new product UI
+
+When `components.html` and `UI_DESIGN.md` disagree, **components.html wins** and `UI_DESIGN.md` is stale.
+
+## 60-second quickstart
+
+```bash
+# 1. Copy this whole folder into the new project (anywhere; we suggest docs/)
+cp -r /path/to/portable-design ../new-project/docs/
+
+# 2. Wire the CSS into your build (pick ONE)
+#    Tailwind v4: @import the pre-built tailwind.css
+#    Vanilla CSS: link tokens.css + components.css
+#    SCSS:        @import _tokens.scss
+
+# 3. Wire AI to follow the system (pick ONE)
+cp docs/portable-design/ai-rules/CLAUDE.md ../../CLAUDE.md            # Claude Code
+cp docs/portable-design/ai-rules/cursorrules.template ../../.cursorrules
+mkdir -p ../../.github && cp docs/portable-design/ai-rules/github-copilot-instructions.md ../../.github/copilot-instructions.md
+```
+
+## ⚠️ Existing-project integration
+
+> **Status:** ✅ Solved in Phase 1A (RFC-0001 §4.2). All emitted tokens carry the `hf-` prefix INSIDE the category segment (`--color-hf-*`, `--text-hf-*`, `--radius-hf-*`, `--spacing-hf-*`, `--font-hf-*`, `--shadow-hf-*`). None of them can collide with Tailwind v4 defaults. The full `@import` is now safe in existing projects.
+
+**Recommended setup for any project (greenfield or existing):**
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "./docs/portable-design/pre-built/tailwind.css";    /* @theme — adds --color-hf-*, --text-hf-*, etc. */
+@import "./docs/portable-design/pre-built/components.css";  /* .hf-* primitives */
+
+/* Optional: exclude the bundle's own demo HTML from your Tailwind scan
+   so legacy classes / bg-[#hex] from the showcase don't leak into your bundle. */
+@source not "./docs/portable-design/components.html";
+@source not "./docs/portable-design/portal-audit.html";
+```
+
+What this gives you:
+
+- `bg-hf-accent` (= `#24AFE8` — brand) — Tailwind's `bg-blue-500` keeps its default
+- `text-hf-base` (= 14px — body) — Tailwind's `text-base` keeps its default 16px
+- `rounded-hf-sm` (= 6px) — Tailwind's `rounded-sm` keeps its default 2px
+- `shadow-hf-modal` (= portal modal shadow)
+- … etc. Your existing utility usage is **untouched**.
+
+**For projects whose integration scripts ask for an "additive" target by name**, `--target=tailwind-v4-additive` is an explicit alias of `--target=tailwind-v4`. Identical output — the prefix made the additive filter unnecessary.
+
+```bash
+node generate-tokens.cjs --target=tailwind-v4-additive > pre-built/tailwind.additive.css
+# (same bytes as --target=tailwind-v4)
+```
+
+## Stack-specific snippets
+
+### React + Tailwind v4 (recommended, greenfield)
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "./docs/portable-design/pre-built/tailwind.css";    /* @theme tokens */
+@import "./docs/portable-design/pre-built/components.css";  /* .hf-* primitives */
+```
+
+```jsx
+<button className="bg-hf-primary hover:bg-hf-primary-hover text-white h-10 px-5 rounded-hf text-hf-md font-semibold">
+  Save
+</button>
+<span className="hf-pill status-booking-confirmed">Confirmed</span>
+<div className="hf-modal max-w-[500px]">
+  <div className="hf-modal__header">
+    <h2 className="hf-modal__title">Edit Guest</h2>
+    <button className="hf-modal__close">✕</button>
+  </div>
+  <div className="hf-modal__body">…</div>
+  <div className="hf-modal__footer"><button>Cancel</button><button>Save</button></div>
+</div>
+```
+
+### React + Tailwind v3 (legacy)
+
+```js
+// tailwind.config.js
+const hfPreset = require('./docs/portable-design/pre-built/tailwind.preset.js');
+module.exports = {
+  presets: [hfPreset],
+  content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],
+};
+```
+
+```html
+<link rel="stylesheet" href="docs/portable-design/pre-built/components.css">
+```
+
+### Next.js + shadcn/ui
+
+Append `pre-built/shadcn-tokens.css` to your `app/globals.css`. shadcn components automatically pick up `--primary`, `--background`, `--ring`, etc.
+
+### Vue 3 / Nuxt
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  css: [
+    '~/docs/portable-design/pre-built/tokens.css',
+    '~/docs/portable-design/pre-built/components.css',
+  ],
+});
+```
+
+Use `var(--color-hf-accent)`, `var(--font-size-hf-base)`, or `.hf-modal` / `.hf-pill .status-booking-confirmed` in any template.
+
+### SCSS-based (Yii / Laravel / WP)
+
+```scss
+// _app.scss
+@import 'docs/portable-design/pre-built/tokens';
+@import 'docs/portable-design/pre-built/components.css';
+
+.my-btn {
+  background: $colorPrimaryDefault;
+  height: $sizeBtnDefault;
+  border-radius: $borderRadiusSm;
+}
+```
+
+### TS / CSS-in-JS
+
+```ts
+import { tokens } from './docs/portable-design/pre-built/tokens';
+
+const Button = styled.button`
+  background: ${tokens.color.primary.default};
+  height: ${tokens.size.btnDefault};
+  border-radius: ${tokens.borderRadius.sm};
+`;
+```
+
+### Vanilla / static HTML
+
+```html
+<link rel="stylesheet" href="docs/portable-design/pre-built/tokens.css">
+<link rel="stylesheet" href="docs/portable-design/pre-built/components.css">
+
+<span class="hf-pill status-booking-confirmed">Confirmed</span>
+<button class="hf-modal__close">✕</button>
+```
+
+## Component primitives shipped in `components.css`
+
+| Class | Anatomy | See |
+|---|---|---|
+| `.hf-pill` + `.status-{domain}-{state}` | Status badge — 6px radius, 15% bg + 100% text + 1px border | components.html#status |
+| `.hf-tab` / `.hf-tab--sm` / `.hf-pill-tabs` | Underline + segmented tabs | components.html#tabs |
+| `.hf-pagination` + `__item` / `__ellipsis` | Subtle gray active (NOT primary!) — 34×34, 8px radius | components.html#pagination |
+| `.hf-modal` + `__header/__title/__body/__footer/__close` | 6px radius, footer no top border | components.html#modal |
+| `.hf-alert` + `--success/--info/--warn/--error` | White bg + 3px top accent bar + 26×26 squared icon | components.html#alerts |
+| `.hf-alert--tinted` / `--banner` / `--compact` | Modifiers — bg tint / full-width strip / compact-in-card | components.html#alerts |
+| `.hf-toast` | Floating notification (bottom-right) — 9px radius | components.html#alerts |
+| `.hf-check` / `.hf-radio` | Custom checkbox+radio — 18×18, filled primary on check | components.html#inputs |
+| `.hf-dropdown-menu` + `__item / __header / __shortcut / __icon / __divider` | 9px radius dropdown with portal-shadow `0 1px 10px rgba(0,0,0,.1)` | components.html#dropdown |
+| `.skeleton` + `.hf-spin` | Loading state primitives (shimmer + rotation keyframes) | components.html#empty |
+
+## How the AI uses this
+
+After you drop one of the `ai-rules/*` files at the new project's root:
+
+1. **Claude Code / Cursor / Copilot** automatically prepend it to every chat. The agent learns:
+   - canonical palette (primary `#24AFE8`, status colors, neutrals)
+   - typography (Roboto, sizes 11/13/14/15/16/18/20/22/26/30, weights 400/500/600)
+   - spacing scale (multiples of 4)
+   - radius scale (6/8/9/12/99)
+   - shadow set (default/subtle/wrapper/card/modal/outline/hover)
+   - component library (`.hf-modal`, `.hf-alert`, `.hf-pill`, `.hf-tab`, `.hf-pagination`, `.hf-check`, `.hf-dropdown-menu`, etc.)
+   - hard rules ("never hard-code hex", "always provide hover/focus/disabled", "no mixed icon sets")
+
+2. **Visual reference for new projects**: open `components.html` in a browser — canonical reference with all `.hf-*` patterns rendered.
+
+3. **For chat-based AI** (ChatGPT, v0, Lovable): paste `ai-rules/system-prompt-compact.md` or `UI_DESIGN.md` §9 JSON token reference as a system prompt before asking for UI work.
+
+## Refresh the bindings
+
+When `tokens.figma.json` changes, regenerate the bindings:
+
+```bash
+cd docs/portable-design
+node generate-tokens.cjs --target=tailwind-v4 > pre-built/tailwind.css        # v4 (recommended)
+node generate-tokens.cjs --target=tailwind    > pre-built/tailwind.preset.js  # v3 (legacy)
+node generate-tokens.cjs --target=css       > pre-built/tokens.css
+node generate-tokens.cjs --target=scss      > pre-built/_tokens.scss
+node generate-tokens.cjs --target=ts        > pre-built/tokens.ts
+node generate-tokens.cjs --target=shadcn    > pre-built/shadcn-tokens.css
+```
+
+> `pre-built/components.css` is **not generated** — it's hand-extracted from `components.html`. If you change the `<style type="text/tailwindcss">` `@layer components` block in components.html, manually re-sync the extracted file. The `pre-built/components.css` file header has the source coordinates.
+
+Or wire token regeneration into `package.json`:
+
+```json
+{
+  "scripts": {
+    "tokens:build:v4": "node docs/portable-design/generate-tokens.cjs --target=tailwind-v4 > tailwind.css",
+    "tokens:build:v3": "node docs/portable-design/generate-tokens.cjs --target=tailwind    > tailwind.preset.js",
+    "prebuild": "npm run tokens:build:v3 && npm run tokens:build:v4"
+  }
+}
+```
+
+## Validation checklist
+
+After porting to a new project, verify:
+
+- [ ] `cat CLAUDE.md` (or `.cursorrules`) shows the design-system rules.
+- [ ] `node docs/portable-design/generate-tokens.cjs --target=css` runs cleanly and produces stable output.
+- [ ] AI agent answers "what's the primary color?" with `#24AFE8`.
+- [ ] First button generated by AI matches `.btn-primary` (40px / 15px / 600 / `#24AFE8` / 6px radius).
+- [ ] Status badges resolve via `--status-{domain}-{state}-color` tokens.
+- [ ] `.hf-modal`, `.hf-alert`, `.hf-pagination` render correctly when `pre-built/components.css` is loaded.
+
+## What's NOT portable
+
+These files in the parent `docs/` are **specific to the HotelFriend portal** (legacy audit / drift detection) and should NOT be copied:
+
+- `docs/migration-plan.md` — legacy SCSS cleanup queue (Yii portal only)
+- `docs/design-tokens-audit.md` — drift report
+- `docs/ui-elements-catalog.*` — observed components in the portal
+- `docs/icon-audit.*` — FA→Lucide migration map
+- `docs/component-anatomy.json` — measurements of legacy modals
+- `scratch/` — Playwright walkers that crawl the portal
+
+They live in the source repo for housekeeping; a new project doesn't need them.
+
+The `portal-audit.html` inside this bundle is the only legacy artifact that ships with the portable folder — keep it for historical reference and migration tracking. New code should never copy patterns from `portal-audit.html`.
+
+---
+
+## Drift detection & CI integration
+
+### Pre-commit hook (recommended for any project that touches this bundle)
+
+```bash
+# With husky (recommended)
+pnpm add -D husky
+pnpm husky init
+cp docs/portable-design/scripts/pre-commit.sh .husky/pre-commit
+chmod +x .husky/pre-commit
+
+# Without husky (raw git hook)
+cp docs/portable-design/scripts/pre-commit.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+The hook runs `validate-tokens.cjs` when any tokens / pre-built / docs / components.html file is staged. Fails the commit if there's drift. Silent on success.
+
+### Stylelint config (recommended for consumer projects)
+
+A shareable Stylelint config that forbids raw hex / named colors / literal `box-shadow` declarations:
+
+```js
+// .stylelintrc.cjs
+module.exports = {
+  extends: [
+    'stylelint-config-standard',
+    './node_modules/@hotelfriendag/design-tokens/pre-built/stylelint-design-system.cjs'
+    // — or, if pulled in via copy-folder:
+    // './docs/portable-design/pre-built/stylelint-design-system.cjs'
+  ],
+  overrides: [
+    // Generated files may contain hex (fallbacks, primitives) — opt-out
+    { files: ['**/pre-built/*.css'], rules: { 'color-no-hex': null } },
+  ],
+};
+```
+
+### Standalone validator (one-shot CI check)
+
+```bash
+cd docs/portable-design
+node scripts/validate-tokens.cjs
+# ✓ validate-tokens: all checks passed
+#   168 CSS variables defined, all var() refs resolve, no bare hex.
+```
+
+Use this in CI alongside lint/test. Exits non-zero on:
+1. `var(--*)` reference that doesn't resolve to a defined CSS variable
+2. Bare hex literal in `components.css` / `status.css` (outside comments + `var()` fallbacks)
+3. Token reference in doc code-blocks that doesn't exist in `pre-built/*`
+
+## NPM package (npmjs.com — public)
+
+The bundle ships as [`@hotelfriendag/design-tokens`](https://www.npmjs.com/package/@hotelfriendag/design-tokens) on the public npmjs.com registry — no `.npmrc`, no tokens, no CI secrets:
+
+```bash
+# In any consumer project:
+pnpm add @hotelfriendag/design-tokens
+```
+
+Then import per stack:
+
+```css
+/* CSS / Tailwind v4 */
+@import "@hotelfriendag/design-tokens/tailwind.css";
+@import "@hotelfriendag/design-tokens/components.css";
+@import "@hotelfriendag/design-tokens/status.css";
+```
+
+```ts
+// TypeScript / JavaScript (default export — uses compiled tokens.js + tokens.d.ts)
+import { tokens } from '@hotelfriendag/design-tokens';
+
+// Or the TS source directly (Vite / Vue / Next handle this natively):
+import { tokens } from '@hotelfriendag/design-tokens/tokens.ts';
+```
+
+```scss
+// SCSS
+@import '@hotelfriendag/design-tokens/_tokens';
+```
+
+### Publishing (maintainer)
+
+Releases are tag-triggered via `.github/workflows/release.yml` — push a `v*` tag
+and the workflow builds, validates, then `npm publish`-es to npmjs.com using
+the `NPM_TOKEN` repository secret. No manual `npm publish` step required.
+
+```bash
+# From the repo root, on main:
+npm version patch                  # or minor / major → updates package.json, creates v* tag, commits
+git push --follow-tags             # workflow runs on the pushed tag and publishes
+```
+
+The `prepublishOnly` script re-runs the generator + validator so the published package is always self-consistent. If you need to publish manually from a local machine (bootstrap or hotfix), `pnpm publish` works the same way after `pnpm version <bump>` (you'll need to be logged in: `npm login` first).
+
+> Historical: versions `0.2.x` were briefly published to GitHub Packages while the registry decision was pending. `0.3.0+` is published exclusively to npmjs.com; consumers should install from there.
+
+## Changelog
+
+### Phase 3 — Distribution + governance scaffolding (2026-05-21)
+
+Closes the remaining RFC-0001 governance items. The bundle is now SHIPPABLE as a versioned npm package with drift-detection enforcement.
+
+- **Phase 3A** — `components.html` Phase 2D reconciliation closed. Embedded `@layer components` stays standalone (Tailwind v4 browser CDN doesn't support nested `@import`). The @theme block already mirrors `pre-built/tailwind.css` (canonical hf-prefixed) + legacy aliases for demo continuity.
+- **Phase 3B** — `pre-built/stylelint-design-system.cjs` ships as a shareable Stylelint config. Forbids raw hex, named CSS colors, literal `box-shadow` declarations, and arbitrary-value Tailwind hex. Consumer projects extend it in their `.stylelintrc.cjs`.
+- **Phase 3C** — `scripts/pre-commit.sh` ships as a Git pre-commit hook scaffold (husky-compatible). Runs `validate-tokens.cjs` when bundle files are staged. Skips silently when no bundle changes are present.
+- **Phase 3D** — `package.json` defines the npm package skeleton:
+  - Exports map for every generated file + ai-rules + JSON sources
+  - `scripts.build` chains all generator targets (8 in total)
+  - `scripts.validate` runs the drift detector
+  - `scripts.prepublishOnly` re-builds + validates before publish
+  - `publishConfig` points at GitHub Packages registry (private/restricted access)
+
+### Phase 2 — Component-tier + status externalization + verification (2026-05-21)
+
+Closes the RFC-0001 §5 + RFC-0002 §Q7 refinement TODOs that Phase 1B left behind. Three sub-phases — all shipped.
+
+**Phase 2A — Status mapping externalized (`status-map.json`)**
+
+The domain→semantic-status mapping (which `.status-booking-confirmed` resolves to → semantic `info`, etc.) lived as a hardcoded block in `components.css`. That re-introduced the drift RFC-0001 §5b warned about. Now:
+
+- **New file:** `status-map.json` — JSON dictionary `{domain.state}` → `semantic-status-name`
+- **New target:** `node generate-tokens.cjs --target=status-css > pre-built/status.css` emits the `.status-{domain}-{state}` CSS rules with `var(--color-hf-status-*)` references
+- **`pre-built/components.css`** — the `.status-*` block REMOVED; now you `@import` both files
+- Adding a new status is JSON-only — no CSS edit
+
+**Phase 2B — 4 component-tier tokens promoted**
+
+Bare hex values that didn't fit a generic semantic slot but were used by exactly one component:
+
+| Token | Value | Used by |
+|---|---|---|
+| `--color-hf-tab-fg-inactive` | `var(--color-hf-gray-700)` (#485B78) | `.hf-tab` default, `.hf-pill-tab` |
+| `--color-hf-tab-count-fg` | `var(--color-hf-gray-700)` | `.hf-tab__count` (inactive tab) |
+| `--color-hf-pagination-fg-inactive` | `var(--color-hf-gray-700)` | `.hf-pagination__item` default |
+| `--color-hf-pagination-fg-active` | `var(--color-hf-gray-950)` (#252F4A) | `.hf-pagination__item.is-active` |
+| `--color-hf-input-border` | `#DBDFE9` (raw — between gray-200 and gray-300) | `.hf-check`, `.hf-radio` |
+| `--color-hf-menu-bg-hover` | `#F5F5F5` (raw — portal `$table__hover`) | `.hf-dropdown-item:hover/:focus-visible` |
+
+Naming convention: `{component}.{slot}` under `semantic.color` in `tokens.figma.json`. Generator emits `--color-hf-{component}-{slot}` which gives Tailwind utilities `bg-hf-tab-fg-inactive` etc.
+
+**Phase 2C — Verifier (`scripts/validate-tokens.cjs`)**
+
+Drift-detection script. Three checks:
+1. Every `var(--*)` in `pre-built/*.css` resolves to a defined CSS variable
+2. No bare hex literals in `components.css` / `status.css` (outside comments + `var()` fallbacks; `#fff`/`#000` allowed)
+3. Every token reference in doc code-blocks exists in `pre-built/*` (anti-RFC-0001 §2.2 drift)
+
+Exits 1 on any failure — suitable for pre-commit hook or CI step.
+
+```bash
+node scripts/validate-tokens.cjs
+# ✓ validate-tokens: all checks passed
+#   168 CSS variables defined, all var() refs resolve, no bare hex.
+```
+
+**Phase 2D — `components.html` reconciled with Phase 1B+2 tokens**
+
+The embedded `@theme {}` block now mirrors `pre-built/tailwind.css` (canonical hf-prefixed three-tier model) + adds legacy aliases for the demo's existing class refs. Result: BOTH `bg-primary` AND `bg-hf-accent` resolve to `#24AFE8` in the demo. The demo continues to render without a 500+ class rewrite, and the canonical `hf-` naming is documented in the @theme source.
+
+**What was tracked as Phase 2 TODO but stays open for Phase 3 / future:**
+
+- Fully *generate* `pre-built/components.css` from sources (currently still hand-authored, but verified by `validate-tokens.cjs`)
+- Rewrite `components.html` demo HTML to use the new prefixed class refs (`bg-hf-accent` everywhere) and drop legacy aliases entirely
+- Add ESLint/Stylelint plugin (RFC-0001 §4.6 forbid raw hex)
+- Publish as `@hotelfriendag/design-tokens` npm package (RFC-0001 §4.4)
+
+### Phase 1B — RFC-0002 semantic tier (2026-05-21)
+
+Introduces the three-tier model: **primitive → semantic → (Phase 2) component**. Per RFC-0002. App code should now reference SEMANTIC tokens (`var(--color-hf-accent)`, `var(--color-hf-fg)`, etc.) — primitives (`hf-blue-500`, `hf-gray-300`) are an implementation detail. Themes swap the semantic layer without touching primitives.
+
+**Breaking changes (consumers must update):**
+
+| Phase 1A name | Phase 1B replacement |
+|---|---|
+| `--color-hf-primary*` | `--color-hf-accent` / `-hover` / `-subtle` / `-subtler` |
+| `--color-hf-text-primary` | `--color-hf-fg` |
+| `--color-hf-text-secondary` | `--color-hf-fg-muted` |
+| `--color-hf-text-useful` | `--color-hf-fg-subtle` |
+| `--color-hf-text-placeholder` | `--color-hf-fg-faint` |
+| `--color-hf-neutral-light-grey` | `--color-hf-bg-page` |
+| `--color-hf-neutral-bg-accent` | `--color-hf-bg-section` |
+| `--color-hf-neutral-very-light` | `--color-hf-bg-muted` |
+| `--color-hf-neutral-border` | `--color-hf-border` |
+| `--color-hf-neutral-light-blue-gray` | `--color-hf-border-subtle` |
+| `--color-hf-neutral-border-hover` | `--color-hf-border-strong` |
+| `--color-hf-status-success` etc. | unchanged ✓ (already canonical) |
+| `--color-hf-badge-{domain}-{state}-*` | **removed** — see status-map note below |
+
+**New: SEMANTIC status colors** (replace per-domain `badge.*` tokens):
+
+```
+--color-hf-status-success / -bg / -strong
+--color-hf-status-warning / -bg / -strong
+--color-hf-status-error   / -bg / -strong / -alt
+--color-hf-status-info    / -bg
+--color-hf-status-cancel  / -bg
+--color-hf-status-coral   / -bg     (portal-specific)
+--color-hf-status-violet  / -bg     (portal-specific)
+--color-hf-status-olive   / -bg     (portal-specific)
+--color-hf-status-orange-deep / -bg (portal-specific)
+```
+
+Domain→semantic mapping for CSS classes (e.g. `.status-booking-confirmed` → uses `--color-hf-status-info`) currently lives **hardcoded in `pre-built/components.css`** with `TODO Phase 2` markers. RFC-0002 §Q7 refinement requires extraction to `status-map.json` consumed by the generator — tracked as Phase 2.
+
+**New: tier-aware generator** (`generate-tokens.cjs`):
+- Recognises `primitive.*` and `semantic.*` top-level groups in `tokens.figma.json`
+- Resolves Tokens Studio `{path.to.token}` references — CSS targets emit `var()` chain (so theming works at runtime), TS/SCSS/v3-preset inline the resolved value
+- All existing `--prefix=` / `--target=` flags unchanged
+
+**Files affected:**
+- `tokens.figma.json` — restructured: `primitive.color.{family}.{step}` + `semantic.color.{slot}.{variant}`
+- `generate-tokens.cjs` — alias resolution + tier path normalisation
+- `pre-built/*` — all regenerated; tokens.css now has primitives + semantic aliases
+- `pre-built/components.css` — fully rewritten; binds chrome to semantic, hardcodes status-map (TODO externalize)
+- `components.html` — **NOT touched** (still self-contained with its own pre-Phase 1B @theme). Phase 2 will reconcile.
+
+### Phase 1A — RFC-0001 collision-safe prefixing (2026-05-21)
+
+Solves the biggest RFC-0001 critique (§2.1, §4.2) — namespace collisions with Tailwind v4 defaults that silently resized utilities used thousands of times in `ui-hf`.
+
+**Breaking change for `ui-hf` and any other consumer:** all token names now carry the `hf-` prefix INSIDE the category segment.
+
+- `--color-primary` → `--color-hf-primary` (Tailwind utility: `bg-hf-primary`)
+- `--text-base` → `--text-hf-base` (utility: `text-hf-base` = 14px; Tailwind's default `text-base` keeps 16px — no more silent override)
+- `--radius-sm` → `--radius-hf-sm` (utility: `rounded-hf-sm` = 6px; default `rounded-sm` stays 2px)
+- `--spacing-7` → `--spacing-hf-7` (utility: `p-hf-7` = 30px; default `p-7` stays 28px)
+- `--font-sans` → `--font-hf-sans` (utility: `font-hf-sans` = Roboto)
+- `--shadow-modal` → `--shadow-hf-modal` (utility: `shadow-hf-modal`)
+- All `--color-badge-{domain}-{state}-*` → `--color-hf-badge-{domain}-{state}-*`
+
+**Why the prefix goes INSIDE the category** (e.g. `--color-hf-primary`, not `--hf-color-primary`):
+Tailwind v4 only generates utility classes from CSS variables that start with its known utility-prefixes (`--color-*`, `--text-*`, `--spacing-*`, `--radius-*`, `--shadow-*`, `--font-*`, etc.). A variable like `--hf-color-primary` would NOT generate any utility. The current convention preserves the utility-class derivation while keeping the namespace conflict-free.
+
+**Files touched:**
+- `tokens.figma.json` — unchanged (the prefix is applied at generation time, not in source)
+- `generate-tokens.cjs` — new `--prefix=` argument; PREFIX defaults to `hf-`. Override with `--prefix=` (empty) for legacy unprefixed output
+- `pre-built/*.css/scss/ts/js` — all regenerated with `--hf-` prefix in CSS targets (Tailwind v3 / SCSS / TS / shadcn unchanged for now)
+- `pre-built/components.css` — all `var(--*)` refs updated to new prefixed names
+- Docs — all `var(--color-primary)` etc. updated to `var(--color-hf-primary)` form
+
+**What's NOT changed yet (Phase 1B):**
+- `components.html` `@theme {}` block still uses unprefixed names (it's a self-contained demo — no collision risk in standalone use). Phase 1B will reconcile when the semantic tier lands.
+- Tailwind v3 preset, SCSS, TS outputs stay unprefixed (legacy paths — less risk of collision in those ecosystems).
+
+### Phase 0 — RFC-0001 quick wins (2026-05-21)
+
+Addresses critique from `RFC-0001-cross-project-design-system.md` §2 + §8 — small fixes that don't require architectural decisions:
+
+- **ESM compatibility** — renamed `generate-tokens.js` → `generate-tokens.cjs` so the script runs under Node in `"type":"module"` projects (Vite/Vue 3/Next).
+- **Token name fix** — `color.primary.default` JSON key no longer emits `--color-primary-default` (awkward `bg-primary-default` utility). Generator now strips trailing `default`/`DEFAULT` so emit is `--color-primary` → utility `bg-primary` works. Same logic applies to any future `.default` sub-keys.
+- **Shadow token namespace** — JSON group `boxShadow` → `shadow` so emit is `--shadow-modal` (was `--box-shadow-modal`). Matches what `components.html` and docs already reference.
+- **`components.css` — RFC §5 conformance:**
+  - **No more hardcoded hex** (RFC §5a) — all values reference `var(--color-*)` / `var(--font-*)` / `var(--border-radius-*)` with hex fallbacks. The 4 remaining bare hex (`#fff`, `#252F4A`, `#DBDFE9`, `#F5F5F5`) are commented as Phase 1 TODOs for the semantic tier.
+  - **One namespace** (RFC §5c) — dropped the parallel `:root { --status-* }` declarations; consumes canonical `--color-badge-*` tokens directly.
+  - **Class names match token paths** (RFC §5d) — breaking renames:
+    - `.status-clean-*` → `.status-room-item-cleaning-*`
+    - `.status-fd-*` → `.status-front-desk-*`
+    - `.status-order-action` → `.status-order-action-required`
+- **Doc/output snapshot** — added a smoke test verifying every `var(--*)` referenced in docs exists in `pre-built/tokens.css` or `pre-built/components.css`. Currently 0 missing.
+- **Existing-project integration warning** — new "⚠️ Existing-project integration" section above documents the Tailwind v4 collision issue + `@source not` exclusion until Phase 1 lands prefixed tokens.
+
+### Still open (deferred to Phase 1+, per RFC roadmap)
+
+- Token namespace prefix (`--hf-*`) + `--target=tailwind-v4-additive` (RFC §4.2)
+- Three-tier token architecture: primitive → semantic → component (RFC §4.1)
+- `text-text-primary` awkward utility — fix when semantic tier introduces `--hf-color-fg` (RFC §8.3)
+- `pre-built/components.css` is hand-mirrored from `components.html` rather than generated (RFC §5b)
+- Two competing visual SSOTs (`components.html` vs `UI_DESIGN.md`) — Phase 2 will pick one
+
+---
+
+Built from the HotelFriend Design System v0.1.0 — see `UI_DESIGN.md` §9 for the JSON token reference and `components.html` for the canonical visual reference.