@hotelfriendag/design-tokens 0.3.0 → 0.3.3

package/README.md

@@ -22,7 +22,9 @@ portable-design/
 │   ├── _tokens.scss               · SCSS variables
 │   ├── tokens.ts                  · TypeScript const
 │   ├── shadcn-tokens.css          · shadcn/ui contract
-│   └── components.css             · .hf-* component primitives (extracted from components.html)
+│   └── components.css             · .hf-* component primitives (generated from src/components.css)
+│
+├── src/                       ← hand-edited sources for the generator (currently: components.css only)
 │
 ├── states-canonical.json      ← curated interactive states for new components (use this)
 ├── states.json                ← raw portal extraction (160 KB — prefer states-canonical.json)
@@ -239,7 +241,7 @@ 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.
+> `pre-built/components.css` is **generated** from `src/components.css` by `generate-tokens.cjs --target=components-css` (`npm run build`). Edit the source file under `src/`, never the output under `pre-built/`. CI runs `git diff --exit-code -- pre-built/` so any hand-edit to the output is caught as drift.
 
 Or wire token regeneration into `package.json`:
 
@@ -367,8 +369,14 @@ import { tokens } from '@hotelfriendag/design-tokens/tokens.ts';
 ### 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.
+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.
+
+`--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.
 
 ```bash
 # From the repo root, on main:
@@ -376,9 +384,19 @@ npm version patch                  # or minor / major → updates package.json,
 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).
+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:
+
+| Field | Value |
+|---|---|
+| Organization | `HotelFriendAG` |
+| Repository | `design-system` |
+| Workflow filename | `release.yml` |
+
+Changing the workflow filename, repo name, or org requires updating the npmjs binding before the next release will succeed.
 
-> 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.
+> 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
 
@@ -445,7 +463,7 @@ The embedded `@theme {}` block now mirrors `pre-built/tailwind.css` (canonical h
 
 **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`)
+- ✅ ~~Fully *generate* `pre-built/components.css` from sources~~ — done 2026-05-27 (ROADMAP #4): source moved to `src/components.css`, `--target=components-css` added to the generator, drift gate covers regeneration.
 - 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)
@@ -550,7 +568,7 @@ Addresses critique from `RFC-0001-cross-project-design-system.md` §2 + §8 —
 - 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)
+- ✅ ~~`pre-built/components.css` is hand-mirrored from `components.html` rather than generated (RFC §5b)~~ — resolved 2026-05-27 (ROADMAP #4): now generated from `src/components.css` by `--target=components-css`.
 - Two competing visual SSOTs (`components.html` vs `UI_DESIGN.md`) — Phase 2 will pick one
 
 ---

package/generate-tokens.cjs

@@ -15,6 +15,8 @@
  *   --target=js                   → module.exports = { tokens: {...} }            (CommonJS module — Node consumers)
  *   --target=dts                  → export declare const tokens: {...}            (TypeScript declarations)
  *   --target=shadcn               → :root { --primary: ...; --background: ... }   (shadcn/ui CSS contract — unprefixed by contract)
+ *   --target=status-css           → .status-{domain}-{state} { color: var(...) }  (read from status-map.json)
+ *   --target=components-css       → .hf-* component primitives                     (read from src/components.css)
  *
  * Usage (from this folder, or anywhere — paths are relative to the script):
  *   node generate-tokens.cjs --target=css                  > pre-built/tokens.css
@@ -26,6 +28,8 @@
  *   node generate-tokens.cjs --target=js                   > pre-built/tokens.js
  *   node generate-tokens.cjs --target=dts                  > pre-built/tokens.d.ts
  *   node generate-tokens.cjs --target=shadcn               > pre-built/shadcn-tokens.css
+ *   node generate-tokens.cjs --target=status-css           > pre-built/status.css
+ *   node generate-tokens.cjs --target=components-css       > pre-built/components.css
  *
  * Pass --in=path/to/tokens.figma.json to override the input file.
  *
@@ -638,6 +642,22 @@ function emitStatusCss() {
   return lines.join('\n');
 }
 
+// ── components-css target ────────────────────────────────────────────────────
+// Reads `src/components.css` and emits it verbatim to pre-built/components.css.
+// The .hf-* rules have heterogeneous shapes (pseudo-elements, keyframes, BEM
+// modifiers, hardcoded geometry) so a data-driven JSON model would just be
+// CSS-in-JSON — net negative ergonomics. The split here is purely "source vs
+// generated output": you edit src/, the build emits pre-built/, the CI drift
+// gate fails any hand-edit to pre-built/components.css.
+function emitComponentsCss() {
+  const srcPath = path.resolve(__dirname, 'src/components.css');
+  if (!fs.existsSync(srcPath)) {
+    throw new Error(`src/components.css not found at ${srcPath}. Required for --target=components-css.`);
+  }
+  // Strip trailing whitespace so dispatch's appended '\n' yields exactly one trailing newline.
+  return fs.readFileSync(srcPath, 'utf8').replace(/\s*$/, '');
+}
+
 // ── Dispatch ─────────────────────────────────────────────────────────────────
 //
 // `tailwind-v4-additive` is an explicit alias for `tailwind-v4`:
@@ -660,6 +680,7 @@ const out =
   target === 'tailwind-v4-additive' ? emitTailwind4() : // alias — see comment above
   target === 'shadcn'               ? emitShadcn() :
   target === 'status-css'           ? emitStatusCss() :
-  (() => { throw new Error(`Unknown target: ${target}. Use css | scss | ts | js | dts | tailwind | tailwind-v4 | tailwind-v4-additive | status-css | shadcn`); })();
+  target === 'components-css'       ? emitComponentsCss() :
+  (() => { throw new Error(`Unknown target: ${target}. Use css | scss | ts | js | dts | tailwind | tailwind-v4 | tailwind-v4-additive | status-css | components-css | shadcn`); })();
 
 process.stdout.write(out + '\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotelfriendag/design-tokens",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "HotelFriend Design System — portable bundle (tokens, components, AI rules). Three-tier model per RFC-0002.",
   "license": "MIT",
   "type": "commonjs",
@@ -41,6 +41,7 @@
     "pre-built/",
     "ai-rules/",
     "scripts/",
+    "src/",
     "tokens.figma.json",
     "status-map.json",
     "states-canonical.json",
@@ -65,7 +66,9 @@
     "build:tokens:js": "node generate-tokens.cjs --target=js                   > pre-built/tokens.js",
     "build:tokens:dts": "node generate-tokens.cjs --target=dts                  > pre-built/tokens.d.ts",
     "build:tokens:shadcn": "node generate-tokens.cjs --target=shadcn               > pre-built/shadcn-tokens.css",
-    "build:components": "node generate-tokens.cjs --target=status-css           > pre-built/status.css",
+    "build:components": "npm-run-all build:components:*",
+    "build:components:status": "node generate-tokens.cjs --target=status-css           > pre-built/status.css",
+    "build:components:css": "node generate-tokens.cjs --target=components-css       > pre-built/components.css",
     "validate": "node scripts/validate-tokens.cjs",
     "smoke": "bash scripts/integration-smoke.sh",
     "prepublishOnly": "npm-run-all build validate"

package/pre-built/components.css

@@ -1,6 +1,10 @@
 /*
  * HotelFriend Design System — Component classes (.hf-*)
  *
+ * ➜ THIS IS THE SOURCE FILE. `pre-built/components.css` is generated from
+ *   this file by `generate-tokens.cjs --target=components-css` (`npm run build`).
+ *   Edit here, then rebuild — do not edit pre-built/.
+ *
  * Drop-in companion to `tokens.css` / `tailwind.css`. Defines the `.hf-*`
  * component primitives used throughout `components.html`. Framework-agnostic
  * — works with Tailwind v4, plain CSS, SCSS, Vue, React.
@@ -13,7 +17,9 @@
  *   ✅ Class names equal token names — domain→semantic mapping NOW LIVES in `status-map.json`
  *      and is emitted to `pre-built/status.css` by `generate-tokens.cjs --target=status-css`.
  *      This file no longer contains the mapping — consumers should `@import` both files.
- *   ⚠ `pre-built/components.css` is still hand-mirrored from components.html (Phase 2D will generate).
+ *   ✅ `pre-built/components.css` is now GENERATED from this file by
+ *      `generate-tokens.cjs --target=components-css`. CI drift gate prevents
+ *      hand-edits to the output.
  *
  * Phase 2 TODOs (tracked here):
  *   1. ✅ Phase 2A done — status-map.json + emitStatusCss(). See `pre-built/status.css`.
@@ -22,7 +28,11 @@
  *        --color-hf-pagination-fg-inactive / -fg-active
  *        --color-hf-input-border  (#DBDFE9 — was bare hex)
  *        --color-hf-menu-bg-hover (#F5F5F5 — was bare hex)
- *   3. Phase 2C — generate this whole file from tokens.figma.json + status-map.json (TODO).
+ *   3. ✅ Phase 2C done — emitted by `generate-tokens.cjs --target=components-css`
+ *        from `src/components.css` (this file). Going further to a fully data-driven
+ *        model would not pay off: the .hf-* rule shapes are heterogeneous (pseudo-
+ *        elements, keyframes, BEM modifiers, hardcoded geometry) so a CSS-in-JSON
+ *        DSL would just reformat CSS with worse ergonomics.
  *   4. Phase 2D — reconcile components.html @theme block with Phase 1B token names (TODO).
  *
  * BREAKING CHANGES vs Phase 1A:

package/src/components.css

@@ -0,0 +1,525 @@
+/*
+ * HotelFriend Design System — Component classes (.hf-*)
+ *
+ * ➜ THIS IS THE SOURCE FILE. `pre-built/components.css` is generated from
+ *   this file by `generate-tokens.cjs --target=components-css` (`npm run build`).
+ *   Edit here, then rebuild — do not edit pre-built/.
+ *
+ * Drop-in companion to `tokens.css` / `tailwind.css`. Defines the `.hf-*`
+ * component primitives used throughout `components.html`. Framework-agnostic
+ * — works with Tailwind v4, plain CSS, SCSS, Vue, React.
+ *
+ * Phase 1B (RFC-0002) status:
+ *   ✅ All chrome bound to SEMANTIC tokens (var(--color-hf-fg), -bg-*, -border, -accent, -status-*).
+ *   ✅ Primitives never referenced directly (except Phase-2 escape hatches — see TODOs below).
+ *   ✅ One namespace — no forked --status-* declarations; all status colors come from
+ *      `--color-hf-status-{role}` (semantic) which alias `--color-hf-{family}-{step}` (primitive).
+ *   ✅ Class names equal token names — domain→semantic mapping NOW LIVES in `status-map.json`
+ *      and is emitted to `pre-built/status.css` by `generate-tokens.cjs --target=status-css`.
+ *      This file no longer contains the mapping — consumers should `@import` both files.
+ *   ✅ `pre-built/components.css` is now GENERATED from this file by
+ *      `generate-tokens.cjs --target=components-css`. CI drift gate prevents
+ *      hand-edits to the output.
+ *
+ * Phase 2 TODOs (tracked here):
+ *   1. ✅ Phase 2A done — status-map.json + emitStatusCss(). See `pre-built/status.css`.
+ *   2. ✅ Phase 2B done — 4 component-tier tokens introduced:
+ *        --color-hf-tab-fg-inactive / -count-fg
+ *        --color-hf-pagination-fg-inactive / -fg-active
+ *        --color-hf-input-border  (#DBDFE9 — was bare hex)
+ *        --color-hf-menu-bg-hover (#F5F5F5 — was bare hex)
+ *   3. ✅ Phase 2C done — emitted by `generate-tokens.cjs --target=components-css`
+ *        from `src/components.css` (this file). Going further to a fully data-driven
+ *        model would not pay off: the .hf-* rule shapes are heterogeneous (pseudo-
+ *        elements, keyframes, BEM modifiers, hardcoded geometry) so a CSS-in-JSON
+ *        DSL would just reformat CSS with worse ergonomics.
+ *   4. Phase 2D — reconcile components.html @theme block with Phase 1B token names (TODO).
+ *
+ * BREAKING CHANGES vs Phase 1A:
+ *   - `--color-hf-primary*`   → `--color-hf-accent[ -hover / -subtle / -subtler ]`
+ *   - `--color-hf-text-*`     → `--color-hf-fg[ -muted / -subtle / -faint ]`
+ *   - `--color-hf-neutral-*`  → `--color-hf-bg-*` / `--color-hf-border[ -subtle ]`
+ *   - `--color-hf-badge-*`    → removed; replaced by domain→semantic CSS map below
+ *
+ * Usage:
+ *   <link rel="stylesheet" href="tokens.css">     ← variables first
+ *   <link rel="stylesheet" href="components.css"> ← components after
+ *   <link rel="stylesheet" href="status.css">     ← .status-{domain}-{state} rules (Phase 2A — generated from status-map.json)
+ *
+ *   Or with Tailwind v4:
+ *     @import "tailwindcss";
+ *     @import "./tailwind.css";
+ *     @import "./components.css";
+ *     @import "./status.css";
+ *
+ * STATUS PILLS — the domain→semantic mapping lives in `status-map.json` and is
+ * emitted to `pre-built/status.css` by `generate-tokens.cjs --target=status-css`.
+ * To add a new status (e.g. `booking.partial-refund`), add it to status-map.json
+ * and re-run the generator — no CSS edit needed here.
+ */
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * PILL — .hf-pill (uses currentColor inherited from .status-* above)
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-pill {
+  display: inline-flex; align-items: center; justify-content: center;
+  padding: 6px 20px;
+  border-radius: var(--radius-hf-sm, 6px);
+  font-size: var(--font-size-hf-base, 14px);
+  font-weight: var(--font-weight-hf-medium, 500);
+  line-height: var(--line-height-hf-tight, 1);
+  white-space: nowrap;
+  border: 1px solid currentColor;
+  text-align: center;
+  user-select: none;
+  transition: opacity 200ms, background-color 200ms;
+}
+.hf-pill:hover { opacity: .9; }
+.hf-pill.is-active {
+  background: transparent !important;
+  box-shadow: inset 0 0 0 1px currentColor;
+}
+.hf-pill--striped {
+  background-image: repeating-linear-gradient(
+    -45deg, currentColor 0, currentColor 1px, transparent 1px, transparent 6px
+  );
+  background-color: var(--color-hf-white, #fff) !important;
+}
+.hf-pill--dd {
+  padding-right: 32px;
+  cursor: pointer;
+  position: relative;
+}
+.hf-pill--dd::after {
+  content: '';
+  position: absolute; right: 12px; top: 50%;
+  width: 8px; height: 5px;
+  background-color: currentColor;
+  clip-path: polygon(0 0, 100% 0, 50% 100%);
+  transform: translateY(-50%);
+}
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * TABS (.hf-tab) — large underline (page-nav) + small (sub-filter)
+ *
+ * ⚠ Phase 2 TODO: gray-700 used here for inactive tab color is portal-specific.
+ *    Promote to component-tier token `--hf-tab-fg-inactive`.
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-tab {
+  padding: 22px 15px;
+  font-size: var(--font-size-hf-lg, 16px);
+  font-weight: var(--font-weight-hf-medium, 500);
+  color: var(--color-hf-tab-fg-inactive, #50627E);
+  cursor: pointer;
+  transition: color 200ms;
+  position: relative;
+  white-space: nowrap;
+  border: 0; background: 0;
+  line-height: var(--line-height-hf-tight, 1);
+  display: inline-flex; align-items: center; gap: 8px;
+}
+.hf-tab:hover { color: var(--color-hf-fg, #2B2B2B); }
+.hf-tab.is-active { color: var(--color-hf-accent, #24AFE8); }
+.hf-tab.is-active::after {
+  content: ''; position: absolute; left: 0; right: 0; bottom: -1px;
+  height: 3px; background: var(--color-hf-accent, #24AFE8);
+}
+.hf-tab:disabled { color: var(--color-hf-fg-faint, #AEBCCF); cursor: not-allowed; }
+.hf-tab:disabled:hover { color: var(--color-hf-fg-faint, #AEBCCF); }
+
+.hf-tab--sm {
+  padding: 10px 15px;
+  font-size: var(--font-size-hf-md, 15px);
+}
+
+.hf-tab__count {
+  display: inline-flex; align-items: center; justify-content: center;
+  min-width: 22px; height: 18px; padding: 0 6px;
+  background: rgba(72,91,120,.1);
+  color: var(--color-hf-tab-count-fg, #50627E);
+  border-radius: 9999px;
+  font-size: var(--font-size-hf-xs, 11px);
+  font-weight: var(--font-weight-hf-semibold, 600);
+  line-height: var(--line-height-hf-tight, 1);
+}
+.hf-tab.is-active .hf-tab__count {
+  background: var(--color-hf-accent-subtler, #EFF6FF);
+  color: var(--color-hf-accent, #24AFE8);
+}
+
+.hf-pill-tabs {
+  display: inline-flex; gap: 4px; padding: 4px;
+  background: var(--color-hf-bg-section, #F6F7FB);
+  border-radius: var(--radius-hf-lg, 9px);
+}
+.hf-pill-tab {
+  padding: 8px 14px;
+  font-size: var(--font-size-hf-base, 14px);
+  font-weight: var(--font-weight-hf-medium, 500);
+  color: var(--color-hf-tab-fg-inactive, #50627E);
+  background: transparent;
+  border: 0;
+  border-radius: var(--radius-hf-sm, 6px);
+  cursor: pointer;
+  transition: background 200ms, color 200ms;
+  white-space: nowrap;
+}
+.hf-pill-tab:hover { color: var(--color-hf-fg, #2B2B2B); }
+.hf-pill-tab.is-active {
+  background: var(--color-hf-bg-surface, #fff);
+  color: var(--color-hf-accent, #24AFE8);
+  box-shadow: 0 1px 2px rgba(0,0,0,.05);
+}
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * PAGINATION (.hf-pagination) — subtle gray active (NOT accent!)
+ *
+ * ⚠ Phase 2 TODO: gray-950 (#252F4A) used for active text is portal-specific.
+ *    Promote to component-tier `--hf-pagination-fg-active`.
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-pagination {
+  display: inline-flex; align-items: center; gap: 4px;
+  padding: 0; list-style: none;
+}
+.hf-pagination__item {
+  display: inline-flex; align-items: center; justify-content: center;
+  min-width: 34px; height: 34px;
+  padding: 0 12px;
+  font-size: var(--font-size-hf-base, 14px);
+  font-weight: var(--font-weight-hf-regular, 400);
+  color: var(--color-hf-pagination-fg-inactive, #485B78);
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--radius-hf-md, 8px);
+  cursor: pointer;
+  transition: background-color 200ms, color 200ms, border-color 200ms;
+  text-decoration: none;
+}
+.hf-pagination__item:hover {
+  background: var(--color-hf-bg-muted, #F1F3F6);
+  color: var(--color-hf-fg, #2B2B2B);
+}
+.hf-pagination__item.is-active {
+  background: var(--color-hf-border-subtle, #E4E8EF);
+  border-color: var(--color-hf-border-subtle, #E4E8EF);
+  color: var(--color-hf-pagination-fg-active, #252F4A);
+  cursor: default;
+}
+.hf-pagination__item.is-active:hover { background: var(--color-hf-border-subtle, #E4E8EF); }
+.hf-pagination__item:disabled,
+.hf-pagination__item.is-disabled {
+  color: var(--color-hf-fg-faint, #AEBCCF);
+  cursor: not-allowed;
+  pointer-events: none;
+}
+.hf-pagination__ellipsis {
+  display: inline-flex; align-items: center; justify-content: center;
+  min-width: 34px; height: 34px;
+  color: var(--color-hf-gray-700, #485B78);
+  cursor: default;
+}
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * ALERT (.hf-alert)
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-alert {
+  position: relative;
+  display: flex; align-items: flex-start; gap: 16px;
+  padding: 16px 48px 14px 20px;
+  background: var(--color-hf-bg-surface, #fff);
+  border: 1px solid rgba(72,91,120,.15);
+  border-radius: var(--radius-hf-sm, 6px);
+  box-shadow: 0 2px 4px 0 rgba(72,91,120,.07);
+  overflow: hidden;
+}
+.hf-alert::before {
+  content: '';
+  position: absolute;
+  left: 0; right: 0; top: 0;
+  height: 3px;
+  background: currentColor;
+}
+.hf-alert__icon {
+  flex-shrink: 0;
+  width: 26px; height: 26px;
+  border-radius: 5px;
+  display: inline-flex; align-items: center; justify-content: center;
+  background: currentColor;
+}
+.hf-alert__icon > svg {
+  width: 16px; height: 16px;
+  color: var(--color-hf-on-accent, #fff);
+  stroke: var(--color-hf-on-accent, #fff);
+  fill: none;
+}
+.hf-alert__body { flex: 1; min-width: 0; color: var(--color-hf-fg, #2B2B2B); }
+.hf-alert__title {
+  font-size: var(--font-size-hf-xl, 18px);
+  font-weight: var(--font-weight-hf-medium, 500);
+  line-height: 1.3;
+  margin: 0 0 4px;
+  color: var(--color-hf-fg, #2B2B2B);
+}
+.hf-alert__text {
+  font-size: var(--font-size-hf-md, 15px);
+  line-height: 1.4;
+  color: var(--color-hf-gray-700, #50627E); /* TODO Phase 2 — review fg axis */
+  margin: 0;
+}
+.hf-alert__close {
+  position: absolute; top: 12px; right: 12px;
+  width: 24px; height: 24px;
+  display: inline-flex; align-items: center; justify-content: center;
+  background: transparent; border: 0; border-radius: 4px;
+  color: var(--color-hf-gray-500, #99A1B7);
+  cursor: pointer;
+  transition: color 200ms, background 200ms;
+}
+.hf-alert__close:hover {
+  color: var(--color-hf-fg, #2B2B2B);
+  background: var(--color-hf-bg-muted, #F1F3F6);
+}
+
+/* Variants — set accent color via currentColor */
+.hf-alert--success { color: var(--color-hf-status-success); }
+.hf-alert--info    { color: var(--color-hf-accent); }
+.hf-alert--warn    { color: var(--color-hf-status-warning); }
+.hf-alert--error   { color: var(--color-hf-status-error); }
+
+/* Tinted modifier */
+.hf-alert--tinted.hf-alert--success { background: rgba(89,181,157,.06); }
+.hf-alert--tinted.hf-alert--info    { background: rgba(36,175,232,.06); }
+.hf-alert--tinted.hf-alert--warn    { background: rgba(255,189,90,.10); }
+.hf-alert--tinted.hf-alert--error   { background: rgba(234,101,101,.06); }
+
+/* Page banner */
+.hf-alert--banner {
+  border-radius: 0;
+  border-left: 0; border-right: 0;
+  box-shadow: none;
+  background: currentColor;
+}
+.hf-alert--banner::before { display: none; }
+.hf-alert--banner .hf-alert__body { color: var(--color-hf-on-accent, #fff); }
+.hf-alert--banner .hf-alert__title,
+.hf-alert--banner .hf-alert__text { color: var(--color-hf-on-accent, #fff); }
+.hf-alert--banner .hf-alert__icon { background: rgba(255,255,255,.18); }
+.hf-alert--banner .hf-alert__close { color: rgba(255,255,255,.7); }
+.hf-alert--banner .hf-alert__close:hover { color: var(--color-hf-on-accent, #fff); background: rgba(255,255,255,.12); }
+
+/* Compact */
+.hf-alert--compact { padding: 10px 36px 10px 14px; gap: 10px; }
+.hf-alert--compact .hf-alert__icon { width: 20px; height: 20px; border-radius: 4px; }
+.hf-alert--compact .hf-alert__icon > svg { width: 12px; height: 12px; }
+.hf-alert--compact .hf-alert__title {
+  font-size: var(--font-size-hf-base, 14px);
+  font-weight: var(--font-weight-hf-semibold, 600);
+  margin-bottom: 0;
+}
+.hf-alert--compact .hf-alert__text { font-size: var(--font-size-hf-sm, 13px); }
+.hf-alert--compact .hf-alert__close { top: 8px; right: 8px; }
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * TOAST (.hf-toast)
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-toast {
+  display: inline-flex; align-items: center; gap: 10px;
+  padding: 10px 14px;
+  background: var(--color-hf-bg-surface, #fff);
+  border: 1px solid rgba(72,91,120,.15);
+  border-radius: var(--radius-hf-lg, 9px);
+  box-shadow: var(--shadow-hf-modal, 0 6px 18px rgba(0,0,0,.10));
+  min-width: 280px; max-width: 420px;
+  color: var(--color-hf-fg, #2B2B2B);
+  font-size: var(--font-size-hf-base, 14px);
+}
+.hf-toast__icon { flex-shrink: 0; width: 20px; height: 20px; }
+.hf-toast__text { flex: 1; }
+.hf-toast__close {
+  flex-shrink: 0;
+  width: 20px; height: 20px;
+  display: inline-flex; align-items: center; justify-content: center;
+  background: transparent; border: 0; border-radius: 4px;
+  color: var(--color-hf-gray-500, #99A1B7);
+  cursor: pointer; transition: color 200ms;
+}
+.hf-toast__close:hover { color: var(--color-hf-fg, #2B2B2B); }
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * MODAL (.hf-modal)
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-modal {
+  background: var(--color-hf-bg-surface, #fff);
+  border: 1px solid rgba(72,91,120,.15);
+  border-radius: var(--radius-hf-sm, 6px);
+  box-shadow: 0 2px 4px 0 rgba(72,91,120,.18);
+  overflow: hidden;
+  width: 100%;
+}
+.hf-modal__header {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 20px;
+  border-bottom: 1px solid var(--color-hf-border-subtle, #E4E8EF);
+}
+.hf-modal__title {
+  font-size: var(--font-size-hf-xl, 18px);
+  font-weight: var(--font-weight-hf-semibold, 600);
+  color: var(--color-hf-fg, #2B2B2B);
+  margin: 0;
+}
+.hf-modal__close {
+  width: 32px; height: 32px;
+  display: inline-flex; align-items: center; justify-content: center;
+  background: transparent;
+  border: 0;
+  border-radius: var(--radius-hf-sm, 6px);
+  color: var(--color-hf-gray-700, #50627E);
+  cursor: pointer;
+  transition: background 200ms, color 200ms;
+}
+.hf-modal__close:hover {
+  background: var(--color-hf-bg-muted, #F1F3F6);
+  color: var(--color-hf-fg, #2B2B2B);
+}
+.hf-modal__body { padding: 20px; }
+.hf-modal__footer {
+  display: flex; justify-content: flex-end; gap: 12px;
+  padding: 20px;
+  border-top: 0;
+  background: transparent;
+}
+.hf-modal--with-footer-border .hf-modal__footer {
+  border-top: 1px solid var(--color-hf-border-subtle, #E4E8EF);
+}
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * CHECKBOX & RADIO (.hf-check, .hf-radio)
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-check,
+.hf-radio {
+  appearance: none; -webkit-appearance: none;
+  position: relative; flex-shrink: 0;
+  width: 18px; height: 18px;
+  margin: 0;
+  background: transparent;
+  border: 1px solid var(--color-hf-input-border, #DBDFE9);
+  cursor: pointer;
+  transition: border-color 200ms, background-color 200ms;
+}
+.hf-check { border-radius: var(--radius-hf-sm, 6px); }
+.hf-radio { border-radius: 9999px; }
+.hf-check:hover:not(:disabled),
+.hf-radio:hover:not(:disabled) { border-color: var(--color-hf-accent, #26ADE4); }
+.hf-check:checked,
+.hf-radio:checked {
+  background: var(--color-hf-accent, #26ADE4);
+  border-color: var(--color-hf-accent, #26ADE4);
+}
+.hf-check:checked::after {
+  content: '';
+  position: absolute; top: 2px; left: 5px;
+  width: 5px; height: 10px;
+  border: solid var(--color-hf-on-accent, #fff);
+  border-width: 0 2px 2px 0;
+  transform: rotate(45deg);
+}
+.hf-radio:checked::after {
+  content: '';
+  position: absolute; top: 50%; left: 50%;
+  width: 6px; height: 6px;
+  background: var(--color-hf-on-accent, #fff); border-radius: 9999px;
+  transform: translate(-50%, -50%);
+}
+.hf-check:disabled,
+.hf-radio:disabled { cursor: not-allowed; opacity: .5; }
+.hf-check:checked:disabled,
+.hf-radio:checked:disabled {
+  background: rgba(38,173,228,.5);
+  border-color: rgba(38,173,228,.5);
+  opacity: 1;
+}
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * DROPDOWN (.hf-dropdown-menu)
+ * ════════════════════════════════════════════════════════════════════════════ */
+.hf-dropdown-menu {
+  background: var(--color-hf-bg-surface, #fff);
+  border-radius: var(--radius-hf-lg, 9px);
+  box-shadow: 0 1px 10px 0 rgba(0,0,0,.1);
+  min-width: 180px;
+  padding: 6px 0;
+  border: 1px solid rgba(228,232,239,.6);
+}
+.hf-dropdown-header {
+  padding: 10px 16px 8px;
+  font-size: var(--font-size-hf-xs, 11px);
+  font-weight: var(--font-weight-hf-semibold, 600);
+  color: var(--color-hf-gray-500, #99A1B7);
+  text-transform: uppercase;
+  letter-spacing: .04em;
+}
+.hf-dropdown-item {
+  display: flex; align-items: center; gap: 10px;
+  padding: 8px 16px;
+  font-size: var(--font-size-hf-base, 14px);
+  color: var(--color-hf-fg, #2B2B2B);
+  cursor: pointer; transition: background 150ms;
+  line-height: 1.4;
+}
+.hf-dropdown-item:hover { background: var(--color-hf-menu-bg-hover, #F5F5F5); }
+.hf-dropdown-item.is-active {
+  background: var(--color-hf-accent-subtler, #EFF6FF);
+  color: var(--color-hf-accent, #24AFE8);
+}
+.hf-dropdown-item:focus-visible {
+  background: var(--color-hf-menu-bg-hover, #F5F5F5);
+  outline: 2px solid var(--color-hf-accent, #24AFE8);
+  outline-offset: -2px;
+}
+.hf-dropdown-item.danger { color: var(--color-hf-status-error, #EA6565); }
+.hf-dropdown-item.danger:hover { background: rgba(234,101,101,.08); }
+.hf-dropdown-item[aria-disabled="true"],
+.hf-dropdown-item.is-disabled {
+  color: var(--color-hf-fg-faint, #AEBCCF);
+  cursor: not-allowed;
+  pointer-events: none;
+}
+.hf-dropdown-item__shortcut {
+  margin-left: auto;
+  color: var(--color-hf-gray-500, #99A1B7);
+  font-size: 12px;
+}
+.hf-dropdown-item__icon {
+  color: var(--color-hf-gray-500, #99A1B7);
+  width: 16px; height: 16px;
+  flex-shrink: 0;
+}
+.hf-dropdown-item:hover .hf-dropdown-item__icon { color: var(--color-hf-gray-700, #50627E); }
+.hf-dropdown-item.danger .hf-dropdown-item__icon { color: currentColor; }
+.hf-dropdown-divider {
+  height: 1px;
+  background: var(--color-hf-border-subtle, #E4E8EF);
+  margin: 4px 0;
+}
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * SKELETON + SPINNER
+ * ════════════════════════════════════════════════════════════════════════════ */
+@keyframes hf-shimmer {
+  0%   { background-position: -200% 0; }
+  100% { background-position:  200% 0; }
+}
+.skeleton {
+  background: linear-gradient(
+    90deg,
+    var(--color-hf-bg-muted, #F1F3F6) 25%,
+    var(--color-hf-border-subtle, #E4E8EF) 50%,
+    var(--color-hf-bg-muted, #F1F3F6) 75%
+  );
+  background-size: 200% 100%;
+  animation: hf-shimmer 1.4s infinite;
+  border-radius: 4px;
+}
+
+@keyframes hf-spin { to { transform: rotate(360deg); } }
+.hf-spin { animation: hf-spin .6s linear infinite; }

package/README.uk.md

@@ -1,377 +0,0 @@
-# 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), повний журнал фаз і змін — там же.