@hotelfriendag/design-tokens 0.3.0

package/README.uk.md

@@ -0,0 +1,377 @@
+# HotelFriend Design System
+
+Спільна дизайн-основа для всіх проєктів: токени, згенеровані файли під кожен стек (CSS / SCSS / TS / Tailwind v3 + v4 / shadcn), шар компонентів `.hf-*` та правила для AI-інструментів.
+
+> **Виокремлено 2026-05-25** із [`hotelfriend/backend-hf`](https://bitbucket.org/hotelfriend/backend-hf) (`docs/portable-design/`), щоб цей репозиторій став єдиним джерелом істини для решти проєктів HotelFriend.
+>
+> **Статус:** RFC-0001 Фаза 1 завершена (семантична трирівнева модель + префіксація без колізій + CI-гейт на дрейф). Наступний крок — версійований npm-пакет (`@hotelfriend/design-tokens` через GitHub Packages). Повний чек-лист — у `RFC-0001-cross-project-design-system.md` §9.
+
+## Ієрархія файлів (читати в цьому порядку)
+
+```
+portable-design/
+│
+├── components.html            ← ОСНОВНЕ · канонічний візуальний референс (відкрити у браузері)
+├── UI_DESIGN.md               ← НАРАТИВ · обґрунтування, анатомія, рішення (AI читає це першим)
+├── tokens.figma.json          ← ТОКЕНИ · атомарний експорт Tokens Studio → живить Figma + генератори
+│
+├── pre-built/                 ← ЗГЕНЕРОВАНІ · підставляєте у свій білд-пайплайн
+│   ├── tailwind.css               · Tailwind v4 @theme-блок (рекомендовано)
+│   ├── tailwind.preset.js         · Tailwind v3 preset (легасі)
+│   ├── tokens.css                 · звичайні CSS custom properties
+│   ├── _tokens.scss               · SCSS-змінні
+│   ├── tokens.ts                  · TypeScript const
+│   ├── shadcn-tokens.css          · контракт shadcn/ui
+│   └── components.css             · примітиви `.hf-*` (витяг із components.html)
+│
+├── states-canonical.json      ← курований набір інтерактивних станів (використовуйте цей)
+├── states.json                ← сирий експорт із порталу (160 КБ — краще брати states-canonical.json)
+├── generate-tokens.cjs        ← Node-скрипт (без залежностей) — перетворює токени на Tailwind/CSS/SCSS/TS/shadcn
+│
+├── ai-rules/                  ← покладіть ОДИН файл у корінь нового проєкту
+│   ├── CLAUDE.md                  · для Claude Code (підхоплюється автоматично)
+│   ├── cursorrules.template       · перейменуйте на .cursorrules
+│   ├── github-copilot-instructions.md · покласти в .github/copilot-instructions.md
+│   └── system-prompt-compact.md   · компактний промпт для ChatGPT/v0/Lovable
+│
+├── portal-audit.html          ← АРХІВ · знімок аудиту старого порталу (НЕ для нового коду)
+└── README.md                  ← ви тут (швидкий старт)
+```
+
+### Правило пріоритету — коли файли суперечать одне одному
+
+1. **`components.html`** — канон для **візуальних рішень** (кольори, розміри, анатомія)
+2. **`tokens.figma.json`** — канон для **значень токенів**. Після редагування — перегенеруйте `pre-built/*`
+3. **`UI_DESIGN.md`** — канон для **ЧОМУ було прийнято рішення** (історія, компроміси, нотатки про дрейф порталу)
+4. **`pre-built/*`** — **згенеровані**, руками не правити. Після зміни JSON запускайте `generate-tokens.cjs`
+5. **`portal-audit.html`** — **тільки архів**. Показує поточний вигляд легасі-порталу — корисно для трекінгу міграції, НЕ для нового UI
+
+Якщо `components.html` і `UI_DESIGN.md` суперечать одне одному — **виграє `components.html`**, а `UI_DESIGN.md` вважається застарілим.
+
+## Швидкий старт за 60 секунд
+
+```bash
+# 1. Скопіювати цю папку у новий проєкт (куди завгодно; рекомендуємо docs/)
+cp -r /path/to/portable-design ../new-project/docs/
+
+# 2. Підключити CSS у білд (оберіть ОДНЕ)
+#    Tailwind v4: @import pre-built/tailwind.css
+#    Vanilla CSS: підключити tokens.css + components.css
+#    SCSS:        @import _tokens.scss
+
+# 3. Підключити AI до правил системи (оберіть ОДНЕ)
+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
+```
+
+## ⚠️ Інтеграція у наявний проєкт
+
+> **Статус:** ✅ Вирішено у Фазі 1A (RFC-0001 §4.2). Усі згенеровані токени мають префікс `hf-` ВСЕРЕДИНІ категорії (`--color-hf-*`, `--text-hf-*`, `--radius-hf-*`, `--spacing-hf-*`, `--font-hf-*`, `--shadow-hf-*`). Жоден не може зіткнутися з дефолтами Tailwind v4. Повний `@import` у наявному проєкті — безпечний.
+
+**Рекомендована конфігурація для будь-якого проєкту (новий чи наявний):**
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "./docs/portable-design/pre-built/tailwind.css";    /* @theme — додає --color-hf-*, --text-hf-* тощо */
+@import "./docs/portable-design/pre-built/components.css";  /* примітиви .hf-* */
+
+/* Опційно: виключити демо-HTML із пакета зі сканування Tailwind,
+   щоб легасі-класи / bg-[#hex] із showcase не потрапили у ваш бандл. */
+@source not "./docs/portable-design/components.html";
+@source not "./docs/portable-design/portal-audit.html";
+```
+
+Що ви отримуєте:
+
+- `bg-hf-accent` (= `#24AFE8` — бренд) — `bg-blue-500` із Tailwind лишається дефолтним
+- `text-hf-base` (= 14px — основний текст) — `text-base` із Tailwind лишається 16px
+- `rounded-hf-sm` (= 6px) — `rounded-sm` із Tailwind лишається 2px
+- `shadow-hf-modal` (= тінь модалки порталу)
+- … тощо. Ваші наявні утиліти **не змінюються**.
+
+**Для проєктів, чиї інтеграційні скрипти просять "additive"-таргет за назвою**, `--target=tailwind-v4-additive` — явний alias для `--target=tailwind-v4`. Вихідний файл ідентичний — префікс зробив additive-фільтр непотрібним.
+
+```bash
+node generate-tokens.cjs --target=tailwind-v4-additive > pre-built/tailwind.additive.css
+# (байт-у-байт як --target=tailwind-v4)
+```
+
+## Сніпети під конкретні стеки
+
+### React + Tailwind v4 (рекомендовано, новий проєкт)
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "./docs/portable-design/pre-built/tailwind.css";    /* @theme токени */
+@import "./docs/portable-design/pre-built/components.css";  /* примітиви .hf-* */
+```
+
+```jsx
+<button className="bg-hf-primary hover:bg-hf-primary-hover text-white h-10 px-5 rounded-hf text-hf-md font-semibold">
+  Зберегти
+</button>
+<span className="hf-pill status-booking-confirmed">Підтверджено</span>
+<div className="hf-modal max-w-[500px]">
+  <div className="hf-modal__header">
+    <h2 className="hf-modal__title">Редагувати гостя</h2>
+    <button className="hf-modal__close">✕</button>
+  </div>
+  <div className="hf-modal__body">…</div>
+  <div className="hf-modal__footer"><button>Скасувати</button><button>Зберегти</button></div>
+</div>
+```
+
+### React + Tailwind v3 (легасі)
+
+```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
+
+Допишіть `pre-built/shadcn-tokens.css` у `app/globals.css`. Компоненти shadcn автоматично підхоплять `--primary`, `--background`, `--ring` тощо.
+
+### 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',
+  ],
+});
+```
+
+У шаблонах використовуйте `var(--color-hf-accent)`, `var(--font-size-hf-base)` або `.hf-modal` / `.hf-pill .status-booking-confirmed`.
+
+### SCSS-стек (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};
+`;
+```
+
+### Ванільний / статичний 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">Підтверджено</span>
+<button class="hf-modal__close">✕</button>
+```
+
+## Примітиви компонентів у `components.css`
+
+| Клас | Анатомія | Дивись |
+|---|---|---|
+| `.hf-pill` + `.status-{domain}-{state}` | Статус-бейдж — радіус 6px, фон 15% + текст 100% + рамка 1px | components.html#status |
+| `.hf-tab` / `.hf-tab--sm` / `.hf-pill-tabs` | Таби з підкресленням та сегментовані | components.html#tabs |
+| `.hf-pagination` + `__item` / `__ellipsis` | Активний — стриманий сірий (НЕ primary!) — 34×34, радіус 8px | components.html#pagination |
+| `.hf-modal` + `__header/__title/__body/__footer/__close` | Радіус 6px, у футера немає верхньої рамки | components.html#modal |
+| `.hf-alert` + `--success/--info/--warn/--error` | Білий фон + 3px акцентна смуга зверху + квадратна іконка 26×26 | components.html#alerts |
+| `.hf-alert--tinted` / `--banner` / `--compact` | Модифікатори — тонований фон / на всю ширину / компактний у картці | components.html#alerts |
+| `.hf-toast` | Плаваюче сповіщення (правий нижній кут) — радіус 9px | components.html#alerts |
+| `.hf-check` / `.hf-radio` | Кастомні чекбокс та радіо — 18×18, активний — заливка primary | components.html#inputs |
+| `.hf-dropdown-menu` + `__item / __header / __shortcut / __icon / __divider` | Дропдаун з радіусом 9px та тінню `0 1px 10px rgba(0,0,0,.1)` | components.html#dropdown |
+| `.skeleton` + `.hf-spin` | Примітиви станів завантаження (шимер + обертання) | components.html#empty |
+
+## Як цим користується AI
+
+Після того як ви поклали один із файлів `ai-rules/*` у корінь нового проєкту:
+
+1. **Claude Code / Cursor / Copilot** автоматично додають його до кожного чату. Агент знає:
+   - канонічну палітру (primary `#24AFE8`, кольори статусів, нейтральні)
+   - типографіку (Roboto, розміри 11/13/14/15/16/18/20/22/26/30, ваги 400/500/600)
+   - шкалу відступів (кратно 4)
+   - шкалу радіусів (6/8/9/12/99)
+   - набір тіней (default/subtle/wrapper/card/modal/outline/hover)
+   - бібліотеку компонентів (`.hf-modal`, `.hf-alert`, `.hf-pill`, `.hf-tab`, `.hf-pagination`, `.hf-check`, `.hf-dropdown-menu` тощо)
+   - жорсткі правила ("ніколи не зашивати hex", "завжди робити hover/focus/disabled", "не мішати іконкові набори")
+
+2. **Візуальний референс для нових проєктів:** відкрийте `components.html` у браузері — це канон, де відрендерені всі патерни `.hf-*`.
+
+3. **Для чат-AI** (ChatGPT, v0, Lovable): вставте `ai-rules/system-prompt-compact.md` або JSON-довідник токенів із `UI_DESIGN.md` §9 як system prompt перед запитом UI-завдання.
+
+## Оновлення згенерованих файлів
+
+Коли змінюється `tokens.figma.json`, перегенеруйте:
+
+```bash
+cd docs/portable-design
+node generate-tokens.cjs --target=tailwind-v4 > pre-built/tailwind.css        # v4 (рекомендовано)
+node generate-tokens.cjs --target=tailwind    > pre-built/tailwind.preset.js  # v3 (легасі)
+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` поки **не генерується** — він вручну витягнутий із `components.html`. Якщо ви змінюєте блок `<style type="text/tailwindcss">` / `@layer components` у `components.html`, синхронізуйте витягнутий файл вручну. Заголовок `pre-built/components.css` містить координати джерела.
+
+Або вбудуйте регенерацію в `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"
+  }
+}
+```
+
+## Чек-ліст валідації
+
+Після перенесення у новий проєкт перевірте:
+
+- [ ] `cat CLAUDE.md` (або `.cursorrules`) показує правила дизайн-системи.
+- [ ] `node docs/portable-design/generate-tokens.cjs --target=css` відпрацьовує чисто і дає стабільний вивід.
+- [ ] AI-агент на питання "який primary color?" відповідає `#24AFE8`.
+- [ ] Перша згенерована AI кнопка відповідає `.btn-primary` (40px / 15px / 600 / `#24AFE8` / радіус 6px).
+- [ ] Бейджі статусів резолвляться через токени `--status-{domain}-{state}-color`.
+- [ ] `.hf-modal`, `.hf-alert`, `.hf-pagination` рендеряться коректно, коли підвантажений `pre-built/components.css`.
+
+## Що НЕ переноситься
+
+Ці файли у батьківському `docs/` — **специфічні для порталу HotelFriend** (легасі-аудит / детект дрейфу), копіювати їх НЕ треба:
+
+- `docs/migration-plan.md` — черга прибирання старого SCSS (тільки портал на Yii)
+- `docs/design-tokens-audit.md` — звіт про дрейф
+- `docs/ui-elements-catalog.*` — спостережені компоненти у порталі
+- `docs/icon-audit.*` — карта міграції FA→Lucide
+- `docs/component-anatomy.json` — обміри легасі-модалок
+- `scratch/` — Playwright-воркери, що сканують портал
+
+Вони лежать у вихідному репо для господарських потреб; новому проєкту вони не потрібні.
+
+`portal-audit.html` всередині цього пакета — єдиний легасі-артефакт, що подорожує разом із portable-папкою — залиште його як історичний референс і для трекінгу міграції. Новий код **ніколи** не повинен копіювати патерни з `portal-audit.html`.
+
+---
+
+## Детект дрейфу та інтеграція з CI
+
+### Pre-commit hook (рекомендовано для будь-якого проєкту, що чіпає цей пакет)
+
+```bash
+# З husky (рекомендовано)
+pnpm add -D husky
+pnpm husky init
+cp docs/portable-design/scripts/pre-commit.sh .husky/pre-commit
+chmod +x .husky/pre-commit
+
+# Без husky (сирий git-hook)
+cp docs/portable-design/scripts/pre-commit.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+Хук запускає `validate-tokens.cjs`, коли в staging є будь-які файли з tokens / pre-built / docs / components.html. Падає на дрейфі. Мовчить на успіху.
+
+### Конфіг Stylelint (рекомендовано для проєктів-споживачів)
+
+Сумісний Stylelint-конфіг, який забороняє сирий hex / іменовані кольори / літеральні `box-shadow`:
+
+```js
+// .stylelintrc.cjs
+module.exports = {
+  extends: [
+    'stylelint-config-standard',
+    './node_modules/@hotelfriend/design-tokens/pre-built/stylelint-design-system.cjs'
+    // — або, якщо підключено через копіювання папки:
+    // './docs/portable-design/pre-built/stylelint-design-system.cjs'
+  ],
+  overrides: [
+    // У згенерованих файлах hex допустимий (fallback-и, примітиви) — opt-out
+    { files: ['**/pre-built/*.css'], rules: { 'color-no-hex': null } },
+  ],
+};
+```
+
+### Самостійний валідатор (одноразова перевірка у CI)
+
+```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.
+```
+
+Використовуйте у CI поруч із лінтом та тестами. Виходить із ненульовим кодом, якщо:
+1. `var(--*)` посилається на CSS-змінну, яка ніде не визначена
+2. У `components.css` / `status.css` є сирий hex (поза коментарями та fallback-ами `var()`; `#fff`/`#000` дозволені)
+3. У код-блоці документації згадано токен, якого нема в `pre-built/*`
+
+## NPM-пакет (приватний реєстр)
+
+Пакет публікується як `@hotelfriend/design-tokens` у приватний реєстр GitHub Packages:
+
+```bash
+# У проєкті-споживачі:
+echo "@hotelfriend:registry=https://npm.pkg.github.com" >> .npmrc
+pnpm add @hotelfriend/design-tokens
+```
+
+Імпорт під свій стек:
+
+```css
+/* CSS / Tailwind v4 */
+@import "@hotelfriend/design-tokens/tailwind.css";
+@import "@hotelfriend/design-tokens/components.css";
+@import "@hotelfriend/design-tokens/status.css";
+```
+
+```ts
+// TypeScript
+import { tokens } from '@hotelfriend/design-tokens/tokens.ts';
+```
+
+```scss
+// SCSS
+@import '@hotelfriend/design-tokens/_tokens';
+```
+
+### Публікація (для мейнтейнера)
+
+```bash
+cd docs/portable-design
+pnpm version patch                 # або minor / major
+pnpm publish                       # запускає prepublishOnly → build + validate
+```
+
+`prepublishOnly` перезбирає та валідує, тож опублікований пакет завжди узгоджений.
+
+---
+
+Зібрано на основі HotelFriend Design System v0.1.0 — JSON-довідник токенів див. у `UI_DESIGN.md` §9, канонічний візуальний референс — у `components.html`. Англомовна версія цього файлу — [`README.md`](README.md), повний журнал фаз і змін — там же.

package/RFC-0001-cross-project-design-system.md

@@ -0,0 +1,273 @@
+# RFC-0001 — Evolving the HotelFriend Design System into a cross-project foundation
+
+> **Status:** Draft / proposal
+> **Author:** (fill in)
+> **Created:** 2026-05-20
+> **Reviewed against:** `portable-design_v2` (2026-05-21) — see §2.1
+> **Scope:** `docs/portable-design` bundle (tokens + generator + docs + AI rules)
+> **Supersedes:** nothing yet — first RFC for this bundle.
+
+## 1. Goal
+
+Make this design system usable as **one shared foundation for both new (greenfield) and
+existing projects**, so that several HotelFriend codebases (e.g. the Vue 3 / Tailwind v4
+`ui-hf` portal and the legacy Yii / SCSS portal) render with the **same visual design** and
+can be **updated from a single source of truth**.
+
+### Non-goals (for this RFC)
+
+- Rewriting the actual portal UI.
+- Picking a specific component framework. We discuss component strategy but defer the choice.
+- Visual redesign — this is about distribution, naming, and architecture, not new aesthetics.
+
+## 2. Why now / evidence
+
+This RFC is grounded in a real integration of the bundle into the `ui-hf` Tailwind v4 project.
+Concrete friction observed (these are the problems to fix):
+
+1. **Namespace collisions with framework defaults.** The generated `pre-built/tailwind.css`
+   redefines keys that Tailwind v4 (and the consuming project) already own — `--text-xs` (11px
+   vs default), `--text-sm` (13px vs 14px), `--text-xl` (18px vs the project's 26px), `--text-2xl`
+   (20px vs 24px), `--spacing-7` (30px vs 28px), `--radius-sm` (6px vs 2px), `--font-sans`.
+   A naïve `@import` silently resized utilities used **thousands** of times (`text-xs` ×1093,
+   `text-sm` ×113, `text-xl` ×57). Integration required a hand-written filter that imports
+   only the additive, non-colliding subset.
+2. **Token-name drift between docs and the generator.** None of the README examples compile
+   as-is:
+   - `ai-rules/CLAUDE.md` says the primary is CSS var `--color-primary-default`; the generator
+     emits `--color-primary`.
+   - README shows `bg-badge-booking-confirmed/15` + `text-badge-booking-confirmed` (and
+     `--status-{domain}-{state}-color`); the generator emits `--color-badge-booking-confirmed-color`
+     and `--color-badge-booking-confirmed-bg`, i.e. utilities are `bg-badge-booking-confirmed-bg` /
+     `text-badge-booking-confirmed-color`.
+3. **Generator breaks in modern toolchains.** `generate-tokens.js` is CommonJS (`require`); any
+   project with `"type": "module"` (Vite/Vue/most new repos) fails with
+   `ReferenceError: require is not defined`. We had to run a temporary `.cjs` copy.
+4. **Awkward generated utility names.** `--color-text-primary` yields the class `text-text-primary`.
+5. **Bundle is incomplete as a sole source.** No primitive ramps (gray/blue 25–950), no fluid
+   spacing, no column widths / table min-widths, no component utility classes (`btn-*`, `input-*`).
+   It can only *augment* an existing token layer, never replace it.
+6. **Copy-folder distribution guarantees drift.** Each project owns a divergent copy the moment
+   it is pasted; there is no mechanism keeping N projects on the same version.
+7. **The component layer re-hardcodes values and forks the token namespace** (introduced in v2 —
+   see §2.1). `pre-built/components.css` defines its own `--status-{domain}-{state}-color/-bg` set
+   with raw `rgb(...)` literals instead of binding to the canonical `--color-badge-*` tokens, and
+   contains ~56 hardcoded hex values (e.g. `#24AFE8`, `#50627E`) — violating the bundle's own
+   "never hardcode hex" rule. Change a token in `tokens.figma.json` and the components do not follow.
+
+### 2.1 Status against `portable-design_v2` (reviewed 2026-05-21)
+
+`portable-design` was archived as `portable-design_v1` and a new `portable-design_v2` was added.
+What v2 changed, mapped to the problems above and the proposal below:
+
+**Progress (mostly on §5 — components):**
+- **New `components.html`** — a canonical visual reference, declared authoritative ("when
+  `components.html` and `UI_DESIGN.md` disagree, components.html wins"). Genuine progress on the
+  §5 anatomy/visual-reference goal.
+- **New `pre-built/components.css`** — a real `.hf-*` primitive layer (pill, tab, …) wired into
+  the README setup snippets for every stack.
+- **New `portal-audit.html`** — partial progress toward the §4.6 drift audit.
+- Minor token additions: split `--color-text-placeholder` (`#AEBCCF`) vs `-legacy` (`#99A1B7`);
+  extra shadows (`subtle`, `modal`, `outline`); badge `cancel` / `deleted` + cancellation aliases.
+
+**Still open (verified unchanged in v2):**
+- §2.1 collisions — `--text-{xs,sm,base,lg,xl,2xl}`, `--spacing-7`, `--radius-sm`, `--font-sans`
+  remain unprefixed. No `--target=*-additive`, no `@source not` doc. (→ §4.2)
+- §2.2 doc/token drift — `ai-rules/CLAUDE.md` still says `--color-primary-default`; generator emits
+  `--color-primary`. (→ §4.3, §8)
+- §2.3 generator ESM — still `require()`; `node generate-tokens.js` still fails under `"type":"module"`.
+- `--color-text-primary` → still `text-text-primary`.
+- No semantic tier (§4.1); tokens remain flat/primitive-only.
+
+**New problems v2 introduced:**
+- §2 item 7 above (component layer hardcodes + forks namespace). There are now **three** color
+  namespaces: `--color-badge-*` (tailwind.css/tokens.css), `--status-*` (components.css), plus the
+  doc references in `ai-rules`.
+- `components.css` is **hand-maintained** ("extracted from components.html"), not generated —
+  another drift source. `generate-tokens.js` has no knowledge of components.
+- **Component class names diverge from token names:** `.status-clean-*` vs token
+  `room-item-cleaning-*`; `.status-order-action` vs `order-action-required`.
+- **Two competing visual SSOTs:** `components.html` is now authoritative and `UI_DESIGN.md` is
+  declared "stale" — a doc-rot risk rather than a single source of truth.
+
+## 3. Core thesis
+
+Cross-project consistency breaks in two places: **distribution** (copy-folder → instant drift)
+and **token naming** (collides in real projects). Everything else is downstream. The two highest-
+leverage changes are:
+
+1. A **semantic token layer** that both new and existing projects bind to.
+2. **Versioned package distribution** that is **collision-safe by construction**.
+
+## 4. Proposal
+
+### 4.1 Three-tier token architecture (the bridge between new ↔ existing)
+
+Adopt the W3C **DTCG** / Tokens Studio model with three explicit tiers:
+
+| Tier | Example | Used directly by app code? |
+|------|---------|----------------------------|
+| **Primitive** | `--hf-blue-500: #24AFE8`, `--hf-gray-300` | No |
+| **Semantic (role)** | `--hf-color-accent`, `--hf-color-bg-surface`, `--hf-color-fg-default`, `--hf-color-fg-muted`, `--hf-color-status-success` | Yes |
+| **Component** (optional) | `--hf-button-bg`, `--hf-input-border` | Yes |
+
+Why this serves both scenarios:
+
+- **New project** consumes semantic tokens directly.
+- **Existing project** aliases its legacy names onto the semantic layer — exactly the pattern
+  already used in `ui-hf` (`--color-hf-blue: var(--hf-color-accent)`). One semantic layer keeps
+  both worlds consistent.
+- **Theming / multi-brand** becomes trivial: override the semantic layer per brand/mode, leave
+  primitives untouched. Encode modes via Tokens Studio `$themes` (light/dark, per-brand).
+
+### 4.2 Collision-safe by construction
+
+This is the biggest practical fix.
+
+- **Prefix every token** (`--hf-text-*`, `--hf-radius-*`, `--hf-space-*`, `--hf-color-*`) so it can
+  never shadow a Tailwind/framework default or a host-project key.
+- Ship an explicit **`--target=tailwind-v4-additive`** that emits only safe keys (the filtering
+  `ui-hf` currently does by hand in `scripts/sync-design-system.mjs` belongs in the bundle).
+- Document, for Tailwind v4 consumers, the `@source not "<path>"` rule so the bundle's own
+  `ui-kit.html` showcase does not leak utilities (e.g. legacy `bg-[#26ADE4]`) into the app bundle.
+
+### 4.3 One SSOT, generated targets, zero doc drift
+
+- Replace the hand-rolled `generate-tokens.js` with **Style Dictionary** (mature, DTCG-native,
+  all targets out of the box) — and fix the ESM breakage along the way.
+- **Generate or test the doc examples.** Add a snapshot test asserting every token/utility shown
+  in README and `ai-rules/CLAUDE.md` actually exists in the generated output. This kills the
+  doc-drift class of bugs (§2.2) permanently.
+
+### 4.4 Versioned package distribution (the mechanism that keeps N projects in sync)
+
+- Publish `@hotelfriend/design-tokens` (and optionally `@hotelfriend/tailwind-preset`) to a private
+  registry, **SemVer**. Every project `pnpm update`s to the same version — *this* is what enforces
+  sameness.
+- Keep the copy-folder bundle only as a **generated fallback** for non-npm stacks (Yii/PHP), stamped
+  with version + origin so its lag is visible.
+- Maintain a changelog + migration notes per minor.
+
+### 4.5 Adapter + codemod for existing projects
+
+Formalize the manual `ui-hf` work:
+
+- A generated **compat layer** per project (`legacy → semantic` aliases).
+- A **codemod** "hardcoded hex → token" (done by hand across ~25 files in `ui-hf`; should be a script).
+
+### 4.6 Conformance / drift CI (or consistency rots within a month)
+
+- A shareable **ESLint/Stylelint rule**: forbid raw hex and arbitrary `bg-[#…]`, allow only DS tokens.
+  Drop it into every project.
+- A **drift audit** in CI comparing a project's computed values against the DS and failing on
+  divergence. The README mentions a Yii-only `design-tokens-audit.md` — generalize it to all projects.
+
+## 5. Do we need to describe components (buttons, inputs, …)? — Yes
+
+> **v2 status: partially started.** `components.html` (visual reference) and `pre-built/components.css`
+> (`.hf-*` CSS layer) now exist — the right *direction*. But the current implementation reproduces the
+> exact drift this RFC warns against (see §2 item 7 / §2.1): it hardcodes hex, forks a `--status-*`
+> namespace instead of binding to `--color-badge-*`, is hand-maintained rather than generated, and its
+> class names diverge from token names. The criteria below are the bar v2's component layer must meet.
+
+Tokens guarantee consistent **values** (color, spacing, radius). They do **not** guarantee a
+consistent **look** — that comes from components. So components must be described, but choose the
+*right layer* for a multi-framework reality (Vue portal + Yii/PHP):
+
+**Hard criteria for the component layer (must all hold):**
+
+- **(a) Bind to tokens, never hardcode.** Every declaration references a canonical token
+  (`var(--color-badge-…)` / `var(--hf-color-…)`); zero hex literals in `components.css`.
+- **(b) Generated, not hand-extracted.** The CSS layer is emitted by the generator from a single
+  source, so a token change propagates automatically.
+- **(c) One namespace.** Drop the parallel `--status-*` set; consume the canonical color tokens directly.
+- **(d) Class names equal token names.** `.status-room-item-cleaning-*` (not `.status-clean-*`),
+  `.status-order-action-required` (not `.status-order-action`).
+
+**Mandatory — framework-agnostic component contracts** (the portable, highest-value layer):
+
+- **Anatomy** — the parts of each component (button: container / label / icon / spinner).
+- **Token bindings** — which token each part uses (`button.bg = --hf-color-accent`,
+  `button.bg-hover = --hf-color-accent-hover`, `button.radius = --hf-radius-md`). This is what makes
+  a button identical across frameworks.
+- **All states** — default / hover / focus-visible / active / disabled / loading, with exact
+  declarations. `states-canonical.json` already does part of this; make it the normative source and
+  cover every primitive.
+- **Variants & sizes** — primary / secondary / outline / danger; sm / md / lg.
+
+**Recommended — a portable CSS component layer** (`.btn-*`, `.hf-card-*`, `.input-*`, `.hf-pill`) built
+on the semantic tokens. Both a Vue app and a PHP template can apply the same class and get the same
+result with zero framework lock-in. The `ai-rules` already reference these class names — make them
+real and generated.
+
+**Optional — per-framework component libraries** (Vue/React) that consume the same tokens + CSS layer.
+Justified only when projects share a framework. Bridge design↔code with **Figma Code Connect**
+(`.figma.ts` mappings) so the canonical component in Figma points at the canonical code.
+
+**Recommended priority for components:** contracts (anatomy + token bindings + states) first →
+portable CSS layer → framework libraries last.
+
+Minimum set to specify first (covers ~80% of screens): Button, Input/Select, Checkbox/Radio, Card,
+Modal/Dialog, Tabs, Table/DataGrid row, Status pill, Toast, Form field + error.
+
+## 6. Phased rollout
+
+1. **Phase 1 — foundation (unblocks everything):** semantic token tier (§4.1) + prefixing /
+   additive target (§4.2). Without these, the rest is held together with tape.
+2. **Phase 2 — distribution:** versioned npm package (§4.4); copy-folder becomes a generated artifact.
+3. **Phase 3 — integrity:** Style Dictionary + doc-example tests (§4.3) + drift CI & lint rule (§4.6).
+4. **Phase 4 — components:** contracts → CSS layer → (optional) framework libs (§5). Runs in parallel
+   with Phase 3. *(Partially started in v2 via `components.html` + `components.css`; must be reworked
+   to meet the §5 hard criteria — token-bound, generated, single namespace, matching class names.)*
+5. **Phase 5 — existing-project onboarding:** compat-layer generator + hex→token codemod (§4.5).
+
+## 7. Open questions
+
+- Private registry choice for the npm package (GitHub Packages / Verdaccio / npm org)?
+- Single multi-brand DS, or one base + per-product themes?
+- Component layer: ship CSS-first now, or wait for a shared framework decision?
+- Who owns the SSOT (`tokens.figma.json`) — Figma (Tokens Studio push) or repo, and which direction
+  is authoritative?
+
+## 8. Appendix — concrete bundle fixes (independent of the larger plan)
+
+These are small, shippable, and worth doing regardless of how the RFC lands. Checked against v2 —
+none are addressed yet:
+
+- [ ] Align token names across README / `ai-rules/CLAUDE.md` / `pre-built/*` (`--color-primary` vs
+      `--color-primary-default`; `badge-*-color/-bg` vs README examples).
+- [ ] Make `generate-tokens.js` run under ESM (rename to `.cjs`, or rewrite ESM, or `createRequire`).
+- [ ] Rename text-color tokens to avoid `text-text-primary` (e.g. `--hf-color-fg`, `--hf-color-fg-muted`).
+- [ ] Add a `--target=tailwind-v4-additive`.
+- [ ] Document the `@source not` exclusion for Tailwind v4 consumers.
+- [ ] Add an "existing project" setup section to the README, separate from greenfield, warning about
+      collisions.
+- [ ] **Fix `components.css` to bind to canonical tokens** — drop the self-defined `--status-*` set
+      and its raw `rgb(...)`/hardcoded hex; reference `--color-badge-*` (or the §4.1 semantic tokens).
+- [ ] **Normalize component class names to token names** (`.status-clean-*` → `room-item-cleaning-*`,
+      `.status-order-action` → `order-action-required`).
+- [ ] **Generate `components.css` from the source** instead of hand-extracting it from `components.html`.
+- [ ] **Resolve the two visual SSOTs** — either fold `UI_DESIGN.md` into `components.html` or mark it
+      explicitly non-normative, so there is one authoritative visual reference.
+
+## 9. Implementation status (verified 2026-05-22)
+
+Status of each proposal against the shipped bundle. Legend: ✅ done · 🟡 partial · ⏸ deferred (needs an external decision / low ROI).
+
+| § | Item | Status | Evidence / note |
+|---|------|--------|-----------------|
+| 4.1 | Three-tier token model (primitive → semantic → component) | ✅ | `tokens.figma.json` + generated `pre-built/*`; semantic `--color-hf-{fg,bg,border,…}`, component `--color-hf-input-border` |
+| 4.2 | Collision-safe prefixing + additive target | ✅ | All emitted tokens `--*-hf-*`; `pre-built/tailwind.additive.css`; `@source not` documented in README |
+| 4.3 | SSOT generated, zero doc drift | 🟡 | Doc-example token test ✅ (`validate-tokens.cjs` check 3). Style Dictionary migration ⏸ — custom generator covers all targets |
+| 4.4 | Versioned npm package | 🟡 | `package.json` (`@hotelfriend/design-tokens`) + `publishConfig` scaffolded. Actual publish ⏸ — pending registry decision (GitHub Packages) |
+| 4.5 | Adapter + hex→token codemod | ⏸ | Legacy portal unlikely to adopt; revisit if it does |
+| 4.6 | Conformance / drift CI + lint rule | ✅ | `stylelint-design-system.cjs` + `validate-tokens.cjs` + `.github/workflows/design-system.yml` (build → drift check → validate). `portal-audit.html` = computed-value audit |
+| 5a | Component layer binds to tokens, no hex | ✅ | `validate-tokens.cjs` check 2 enforces no bare hex |
+| 5b | Component layer generated, not hand-extracted | ❌ | `components.css` is still hand-maintained; drift caught by validator, not prevented |
+| 5c | One namespace (drop forked `--status-*`) | ✅ | No `--status-*` declarations; status colors come from canonical tokens |
+| 5d | Class names equal token names | ✅ | `.status-room-item-cleaning-*`, `.status-order-action-required` in `status.css` |
+| 8 | Appendix concrete fixes | ✅ 9/10 | Only "auto-generate components.css" (= 5b) outstanding |
+
+**Phases:** 1 (foundation) ✅ · 2 (npm publish) ⏸ · 3 (Style Dictionary ⏸ / doc-drift test ✅ / drift CI ✅) · 4 (components: started, not yet generated) · 5 (onboarding) ⏸.
+
+**True remaining work (intentional, needs external decisions):** GitHub Packages publish (§4.4 — registry decision), Figma Code Connect (§5 optional — needs designer's Figma file), Style Dictionary (§4.3 — premature), legacy codemod (§4.5 — low ROI), auto-generate `components.css` (§5b — validator covers drift).