@hotelfriendag/design-tokens 0.3.2 → 0.3.4

package/README.md

@@ -1,574 +1,243 @@
 # 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.
+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. Distributed as the public npm package **`@hotelfriendag/design-tokens`**.
 
-> **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.
+> **Source repo:** `HotelFriendAG/design-system` (private). Extracted on 2026-05-25 from [`hotelfriend/backend-hf`](https://bitbucket.org/hotelfriend/backend-hf) `docs/portable-design/` to be the single source of truth 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.
+> **Status:** RFC-0001 Phase 1 complete (semantic three-tier model + collision-safe `hf-` prefix + drift CI). Published on npmjs.com via Trusted Publishing. See [`ROADMAP.md`](ROADMAP.md) for remaining items and [`CHANGELOG.md`](CHANGELOG.md) for phase history.
 
-## 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
+## Install
 
 ```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
+pnpm add @hotelfriendag/design-tokens
 ```
 
-## ⚠️ Existing-project integration
+Public package — no `.npmrc`, no auth, no CI secrets. Works from any project, any CI.
 
-> **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.
+## Wire it up (pick your stack)
 
-**Recommended setup for any project (greenfield or existing):**
+The package exposes each generated file via a subpath export, e.g. `@hotelfriendag/design-tokens/tailwind.css`, `/components.css`, `/status.css`, `/_tokens.scss`, `/tokens.css`, `/tokens.ts`, `/shadcn-tokens.css`.
+
+### Tailwind v4 (recommended — e.g. `ui-hf`)
 
 ```css
-/* app/globals.css */
+/* your main CSS entry, where @import "tailwindcss" lives */
 @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";
+@import "@hotelfriendag/design-tokens/tailwind.css";    /* @theme tokens, hf- prefix */
+@import "@hotelfriendag/design-tokens/components.css";  /* .hf-* primitives */
+@import "@hotelfriendag/design-tokens/status.css";      /* .status-{domain}-{state} */
 ```
 
-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**.
+Put the DS imports **after** any project-local `@theme {}` block so DS values win `--color-hf-*` collisions. Import `tailwind.css` only — `tailwind.additive.css` is byte-identical (the `hf-` prefix made the additive filter unnecessary), importing both duplicates every declaration.
 
-**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)
+```html
+<button class="bg-hf-accent hover:bg-hf-accent-hover text-white h-10 px-5 rounded-hf-sm text-hf-base font-semibold">Save</button>
+<span class="hf-pill status-booking-confirmed">Confirmed</span>
 ```
 
-## Stack-specific snippets
+### SCSS (Yii / Laravel / WP — e.g. `backend-hf`)
 
-### React + Tailwind v4 (recommended, greenfield)
+The package ships `pre-built/_tokens.scss` with 135 compile-time variables — `$colorAccent`, `$colorFg`, `$colorBorder`, `$radiusSm`, `$shadowModal`, … Semantic tokens are resolved to concrete values (e.g. `$colorAccent: #24AFE8;`), so no runtime cascade is needed. `node_modules` must be on your Sass load path.
 
-```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 */
-```
+```scss
+// Dart Sass (sass-embedded / dart-sass) — node_modules on loadPaths, then:
+@use '@hotelfriendag/design-tokens/pre-built/tokens' as ds;
 
-```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>
+.my-btn {
+  background: ds.$colorAccent;     // #24AFE8
+  color: #fff;
+  border-radius: ds.$radiusSm;     // 6px
+  box-shadow: ds.$shadowModal;
+}
 ```
 
-### React + Tailwind v3 (legacy)
+```scss
+// webpack sass-loader — bare path resolves node_modules (older sass-loader: prefix with ~)
+@import '@hotelfriendag/design-tokens/pre-built/tokens';
 
-```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}'],
-};
+.my-btn { background: $colorAccent; border-radius: $radiusSm; }
 ```
 
-```html
-<link rel="stylesheet" href="docs/portable-design/pre-built/components.css">
-```
+For the `.hf-*` component primitives, also pull the generated CSS once (it references `var(--color-hf-*)` — emit `tokens.css` into the page too so the custom properties exist at runtime):
 
-### Next.js + shadcn/ui
+```scss
+@use '@hotelfriendag/design-tokens/pre-built/tokens';      // SCSS variables
+```
+```css
+@import "@hotelfriendag/design-tokens/tokens.css";         /* :root custom properties */
+@import "@hotelfriendag/design-tokens/components.css";     /* .hf-* primitives */
+@import "@hotelfriendag/design-tokens/status.css";         /* status pills */
+```
 
-Append `pre-built/shadcn-tokens.css` to your `app/globals.css`. shadcn components automatically pick up `--primary`, `--background`, `--ring`, etc.
+> Why both? SCSS `$variables` are compile-time (good for your own rules); the `.hf-*` component CSS resolves `var(--color-hf-*)` at runtime, so the page needs `tokens.css` loaded for those custom properties to exist.
 
-### Vue 3 / Nuxt
+### Vue 3 / Nuxt (vanilla CSS variables)
 
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
   css: [
-    '~/docs/portable-design/pre-built/tokens.css',
-    '~/docs/portable-design/pre-built/components.css',
+    '@hotelfriendag/design-tokens/tokens.css',       // :root custom properties
+    '@hotelfriendag/design-tokens/components.css',   // .hf-* primitives
+    '@hotelfriendag/design-tokens/status.css',
   ],
 });
 ```
 
-Use `var(--color-hf-accent)`, `var(--font-size-hf-base)`, or `.hf-modal` / `.hf-pill .status-booking-confirmed` in any template.
+Then 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)
+### TypeScript / CSS-in-JS
 
-```scss
-// _app.scss
-@import 'docs/portable-design/pre-built/tokens';
-@import 'docs/portable-design/pre-built/components.css';
+```ts
+import { tokens } from '@hotelfriendag/design-tokens';   // compiled tokens.js + .d.ts
 
-.my-btn {
-  background: $colorPrimaryDefault;
-  height: $sizeBtnDefault;
-  border-radius: $borderRadiusSm;
-}
+const Button = styled.button`
+  background: ${tokens.color.accent.default};   // #24AFE8 (semantic + primitive share tokens.color.*)
+  border-radius: ${tokens.radius.sm};           // 6px
+`;
 ```
 
-### TS / CSS-in-JS
+### Next.js + shadcn/ui
 
-```ts
-import { tokens } from './docs/portable-design/pre-built/tokens';
+Append `shadcn-tokens.css` to `app/globals.css` (after `@import "tailwindcss"`). shadcn components pick up `--primary`, `--background`, `--ring`, etc.
 
-const Button = styled.button`
-  background: ${tokens.color.primary.default};
-  height: ${tokens.size.btnDefault};
-  border-radius: ${tokens.borderRadius.sm};
-`;
+```css
+@import "@hotelfriendag/design-tokens/shadcn-tokens.css";
 ```
 
 ### 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">
+<link rel="stylesheet" href="node_modules/@hotelfriendag/design-tokens/pre-built/tokens.css">
+<link rel="stylesheet" href="node_modules/@hotelfriendag/design-tokens/pre-built/components.css">
+<link rel="stylesheet" href="node_modules/@hotelfriendag/design-tokens/pre-built/status.css">
 
 <span class="hf-pill status-booking-confirmed">Confirmed</span>
-<button class="hf-modal__close">✕</button>
 ```
 
+### No-npm fallback
+
+If a consumer can't reach npmjs.com, the repo also works as a **git submodule** (relative `@import` paths). See the appendix in [`INTEGRATION-ui-hf.md`](INTEGRATION-ui-hf.md).
+
+## What you get
+
+- `bg-hf-accent` = `#24AFE8` (brand) — Tailwind's `bg-blue-500` keeps its default
+- `text-hf-base` = 14px — Tailwind's `text-base` keeps its default 16px
+- `rounded-hf-sm` = 6px — Tailwind's `rounded-sm` keeps its default 2px
+- `shadow-hf-modal`, `text-hf-fg`, `border-hf-border`, `bg-hf-bg-surface`, … — full semantic set
+- Your existing utility usage is **untouched** (collision-safe prefix).
+
+App code should reference **semantic** tokens (`accent`, `fg`, `bg-*`, `border`, `status-*`) — primitives (`hf-blue-500`, `hf-gray-300`) are an implementation detail the theming layer can swap.
+
 ## 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-pagination` + `__item` / `__ellipsis` | Subtle gray active (NOT accent!) — 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
-```
+| `.hf-toast` | Floating notification — 9px radius | components.html#alerts |
+| `.hf-check` / `.hf-radio` | Custom checkbox+radio — 18×18, filled accent on check | components.html#inputs |
+| `.hf-dropdown-menu` + `__item / __header / __shortcut / __icon / __divider` | 9px radius dropdown, portal shadow | components.html#dropdown |
+| `.skeleton` + `.hf-spin` | Loading-state primitives (shimmer + rotation keyframes) | components.html#empty |
 
-> `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.
+## AI rules
 
-Or wire token regeneration into `package.json`:
+The package ships agent rules under `ai-rules/`. Drop one into the consumer's root so Claude / Cursor / Copilot follow the same UI rules:
 
-```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
+- `ai-rules/CLAUDE.md` → consumer root `CLAUDE.md` (Claude Code, autodetected)
+- `ai-rules/cursorrules.template` → `.cursorrules`
+- `ai-rules/github-copilot-instructions.md` → `.github/copilot-instructions.md`
+- `ai-rules/system-prompt-compact.md` → compact prompt for ChatGPT / v0 / Lovable
 
-They live in the source repo for housekeeping; a new project doesn't need them.
+If the consumer already has a `CLAUDE.md`, reference the package rules from it (e.g. point at `node_modules/@hotelfriendag/design-tokens/ai-rules/CLAUDE.md`) instead of overwriting. The agent learns the canonical palette, typography, spacing/radius/shadow scales, the `.hf-*` library, and the hard rules ("never hard-code hex", "always provide hover/focus/disabled").
 
-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)
+## Keeping a consumer up to date
 
 ```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
+pnpm update @hotelfriendag/design-tokens   # pull the latest published version
 ```
 
-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.
+A convenient consumer script: `"design-system:update": "pnpm update @hotelfriendag/design-tokens && pnpm ls @hotelfriendag/design-tokens"`. Commit the bumped lockfile with `chore: bump design-system to <version>`.
 
-### Stylelint config (recommended for consumer projects)
+## Drift detection & CI (for consumers)
 
-A shareable Stylelint config that forbids raw hex / named colors / literal `box-shadow` declarations:
+**Stylelint config** — forbids raw hex / named colors / literal `box-shadow`:
 
 ```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'
+    './node_modules/@hotelfriendag/design-tokens/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.
-```
+**Pre-commit hook** — `scripts/pre-commit.sh` runs the token validator when bundle files are staged (husky-compatible).
 
-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";
-```
+## Maintainer reference
 
-```ts
-// TypeScript / JavaScript (default export — uses compiled tokens.js + tokens.d.ts)
-import { tokens } from '@hotelfriendag/design-tokens';
+### Repo layout & precedence
 
-// 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';
+design-system/
+├── components.html          PRIMARY · canonical visual reference (open in browser)
+├── UI_DESIGN.md             NARRATIVE · rationale, anatomy, decisions
+├── tokens.figma.json        TOKENS · Tokens Studio export — single source of truth
+├── status-map.json          domain→semantic status mapping (feeds status.css)
+├── src/components.css        SOURCE for .hf-* rules (edit here)
+├── generate-tokens.cjs      Node generator (no deps)
+├── pre-built/               GENERATED — never hand-edit (CI drift gate)
+└── ai-rules/                agent rule files
 ```
 
-### Publishing (maintainer)
+Precedence when files disagree:
+1. **`components.html`** — visual decisions (colors, sizes, anatomy)
+2. **`tokens.figma.json`** — token values (regenerate `pre-built/*` after edits)
+3. **`UI_DESIGN.md`** — WHY decisions were made
+4. **`pre-built/*`** — generated, never hand-edit
+5. **`portal-audit.html`** — archival only (legacy portal snapshot)
 
-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 via
-**Trusted Publishing (OIDC)**. No `NPM_TOKEN` secret, no PATs: GitHub Actions
-mints a short-lived OIDC token that npm exchanges for publish credentials.
+### Regenerating outputs
 
-`--provenance` is NOT used: npmjs rejects sigstore provenance from private
-source repositories, and this repo stays private (only the built artifact is
-public — see RFC-0001 for the rationale). The trade is a missing attestation
-badge on the npm page in exchange for keeping the source code private.
+`tokens.figma.json` is the single source of truth; `src/components.css` is the source for the `.hf-*` layer. After editing either:
 
 ```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
+npm run build      # regenerates all pre-built/* (tokens, tailwind v3+v4, scss, ts/js/dts, shadcn, status.css, components.css)
+npm run validate   # drift detector: every var() resolves, no bare hex
 ```
 
-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 (hotfix), `npm publish` works the same way after `npm version <bump>` and `npm login` — but Trusted Publishing is the canonical path.
-
-The Trusted Publisher binding on npmjs (Package → Settings → Trusted publishing) is configured for:
+CI runs `git diff --exit-code -- pre-built/` so outputs must be reproducible from source. Edit `src/`, never `pre-built/`.
 
-| Field | Value |
-|---|---|
-| Organization | `HotelFriendAG` |
-| Repository | `design-system` |
-| Workflow filename | `release.yml` |
+### Publishing
 
-Changing the workflow filename, repo name, or org requires updating the npmjs binding before the next release will succeed.
+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 via **Trusted Publishing (OIDC)**. No `NPM_TOKEN` secret, no PATs: GitHub Actions mints a short-lived OIDC token that npm exchanges for publish credentials.
 
-> 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. `0.3.0` itself was bootstrapped by a one-time manual publish from a maintainer's machine using a short-lived Granular Access Token (since Trusted Publishing requires the package to already exist on npm). The token was revoked immediately after; all subsequent versions use OIDC.
-
-## 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.
+`--provenance` is intentionally NOT used: npmjs rejects sigstore provenance from private source repositories, and this repo stays private (only the built artifact is public).
 
 ```bash
-node scripts/validate-tokens.cjs
-# ✓ validate-tokens: all checks passed
-#   168 CSS variables defined, all var() refs resolve, no bare hex.
+npm version patch        # or minor / major → bumps package.json, creates v* tag, commits
+git push --follow-tags   # workflow runs on the tag and publishes
 ```
 
-**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)
-```
+The Trusted Publisher binding on npmjs (Package → Settings → Trusted publishing) is configured for org `HotelFriendAG`, repo `design-system`, workflow `release.yml`. Changing any of those requires updating the binding before the next release.
 
-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
+`prepublishOnly` re-runs the generator + validator so the published package is always self-consistent.
 
 ---
 
-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.
+- **Changelog / phase history:** [`CHANGELOG.md`](CHANGELOG.md)
+- **Remaining work:** [`ROADMAP.md`](ROADMAP.md)
+- **First-consumer playbook:** [`INTEGRATION-ui-hf.md`](INTEGRATION-ui-hf.md)
+- **Architecture rationale:** [`RFC-0001`](RFC-0001-cross-project-design-system.md) · [`RFC-0002`](RFC-0002-semantic-tier-naming.md)
+- **Visual reference:** `components.html` · **Token narrative:** `UI_DESIGN.md`