npm - @hotelfriendag/design-tokens - Versions diffs - 0.3.4 → 0.6.0 - Mend

@hotelfriendag/design-tokens 0.3.4 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md +324 -5
package/UI_DESIGN.md +65 -6
package/ai-rules/CLAUDE.md +50 -28
package/ai-rules/cursorrules.template +12 -11
package/ai-rules/github-copilot-instructions.md +23 -12
package/ai-rules/system-prompt-compact.md +16 -10
package/components.html +612 -81
package/generate-tokens.cjs +218 -2
package/package.json +9 -1
package/pre-built/_ionic.scss +51 -0
package/pre-built/_tokens.scss +6 -2
package/pre-built/components.css +521 -13
package/pre-built/dark.css +30 -0
package/pre-built/stylelint-design-system.cjs +12 -16
package/pre-built/tailwind.additive.css +5 -1
package/pre-built/tailwind.css +5 -1
package/pre-built/tailwind.preset.js +38 -34
package/pre-built/themes.json +75 -0
package/pre-built/tokens.css +6 -2
package/pre-built/tokens.d.ts +4 -0
package/pre-built/tokens.js +8 -4
package/pre-built/tokens.ts +8 -4
package/pre-built/utilities.css +165 -0
package/scripts/validate-tokens.cjs +191 -5
package/src/components.css +521 -13
package/states-canonical.json +1 -1
package/tokens.figma.json +30 -5

package/README.md CHANGED Viewed

@@ -6,6 +6,15 @@ Cross-project design foundation: tokens, generated outputs for every stack (CSS
 >
 > **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.
+## Contract
+[`CONTRACT.md`](CONTRACT.md) is the **normative design-system contract** — the single home for
+versioning & breaking-change policy, the governed variation model (density / theme / brand),
+error-UX mapping, the accessibility responsibility split, i18n posture, performance budgets, the
+consumer build pipeline, token/Figma governance, the supported-stack matrix, and the proposal
+process. Read it before proposing changes or integrating; this README and the integration playbooks
+are the *consumption* detail under it.
 ## Install
 ```bash
@@ -16,7 +25,7 @@ Public package — no `.npmrc`, no auth, no CI secrets. Works from any project,
 ## Wire it up (pick your stack)
-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`.
+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`, `/dark.css`, `/utilities.css`, `/_ionic.scss`, `/themes.json`.
 ### Tailwind v4 (recommended — e.g. `ui-hf`)
@@ -32,7 +41,7 @@ The package exposes each generated file via a subpath export, e.g. `@hotelfriend
 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.
 ```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>
+<button class="bg-hf-accent hover:bg-hf-accent-hover text-hf-on-accent h-10 px-5 rounded-hf-sm text-hf-base font-semibold">Save</button>
 <span class="hf-pill status-booking-confirmed">Confirmed</span>
 ```
@@ -46,7 +55,7 @@ The package ships `pre-built/_tokens.scss` with 135 compile-time variables — `
 .my-btn {
   background: ds.$colorAccent;     // #24AFE8
-  color: #fff;
+  color: ds.$colorOn-accent;       // #0B2F46 — AA text-on-accent (decision D1)
   border-radius: ds.$radiusSm;     // 6px
   box-shadow: ds.$shadowModal;
 }
@@ -87,6 +96,26 @@ export default defineNuxtConfig({
 Then use `var(--color-hf-accent)`, `var(--font-size-hf-base)`, or `.hf-modal` / `.hf-pill .status-booking-confirmed` in any template.
+### Dark theme
+`dark.css` is a `[data-theme="dark"]` override of the ~15 semantic tokens (surfaces, text, borders, accent tints). Import it after `tokens.css` and flip `<html data-theme="dark">`:
+```css
+@import "@hotelfriendag/design-tokens/tokens.css";
+@import "@hotelfriendag/design-tokens/dark.css";   /* [data-theme="dark"] overrides */
+```
+Then `<html data-theme="dark">` (or any container) switches the whole subtree. `pre-built/themes.json` is the machine-readable list of which semantic vars a theme overrides (the validation contract for custom themes).
+### Utilities (non-Tailwind)
+For Angular / plain-SCSS apps without Tailwind, `utilities.css` ships atomic helpers `.bg-hf-{name}`, `.text-hf-{name}`, `.border-hf-{name}`, `.shadow-hf-{name}` for the semantic tier (primitives via `tokens.css` vars directly). Requires `tokens.css` loaded:
+```css
+@import "@hotelfriendag/design-tokens/tokens.css";
+@import "@hotelfriendag/design-tokens/utilities.css";   /* .bg-hf-*, .text-hf-*, .border-hf-*, .shadow-hf-* */
+```
 ### TypeScript / CSS-in-JS
 ```ts
@@ -134,17 +163,307 @@ App code should reference **semantic** tokens (`accent`, `fg`, `bg-*`, `border`,
 | Class | Anatomy | See |
 |---|---|---|
+| `.hf-btn` + `--primary` / `--danger` / `--outline-primary` / `--outline-default` / `--cancel` (sizes `--sm` / `--icon`) | Buttons — 40px h, 6px radius, token-driven chrome | components.html#buttons |
+| `.hf-input` / `.hf-textarea` / `.hf-select` (+ `.hf-select-wrap`) | Form controls — 39px h, accent focus ring, token caret | components.html#inputs |
+| `.hf-form-field` + `__label` / `__hint` / `__error` (`--required`, `--error`) | Field wrapper — label + control + hint/error | components.html#inputs |
+| `.hf-switch` | Toggle — styled checkbox, 40×22 track, accent when on | components.html#inputs |
+| `.hf-card` + `__header/__title/__description/__body/__footer` (`--flat`) | Elevated card — 12px radius, card shadow | components.html#cards |
+| `.hf-drawer` + `__backdrop/__panel/__header/__body/__footer` (`--left`) | Side-panel — backdrop + sliding panel | components.html#layout |
+| `.hf-table` (+ `__num`, `--static`) | Table — thead section bg, subtle row dividers, warm hover; style a plain `<table>` | components.html#table |
+| `.hf-empty` + `__icon/__title/__text/__action` (`--compact`, `--row`) | Empty state — page-level, in-card, in-table-row | components.html#empty |
 | `.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 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 — 9px radius | components.html#alerts |
+| `.hf-toast` + `--success/--error/--warn/--info` | Floating notification — 9px radius; variant colors the icon + 3px left edge | 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 |
+| `.hf-dropdown-menu` + `__header / __item / __item-icon / __shortcut / __divider` (+ `__item--danger`) | 9px radius dropdown, portal shadow (legacy flat `.hf-dropdown-{header\|item\|divider}` kept as deprecated aliases) | components.html#dropdown |
 | `.skeleton` + `.hf-spin` | Loading-state primitives (shimmer + rotation keyframes) | components.html#empty |
+## Usage examples
+Copy-paste markup for the main `.hf-*` components — framework-agnostic (works in HTML, Vue, JSX; swap `class`/`className`). Icons are illustrative; wire your own (Lucide, etc.).
+### Status pill
+```html
+<span class="hf-pill status-booking-confirmed">Confirmed</span>
+<span class="hf-pill status-order-waiting">Waiting</span>
+<span class="hf-pill status-room-item-cleaning-dirty">Dirty</span>
+```
+### Tabs
+```html
+<div class="flex border-b border-hf-border">
+  <button class="hf-tab is-active">Overview</button>
+  <button class="hf-tab">Bookings <span class="hf-tab__count">12</span></button>
+  <button class="hf-tab">Guests</button>
+  <button class="hf-tab" disabled>Reports</button>
+</div>
+<!-- compact sub-filter variant: add .hf-tab--sm -->
+```
+### Pagination
+```html
+<div class="hf-pagination">
+  <button class="hf-pagination__item" disabled aria-label="Previous">‹</button>
+  <button class="hf-pagination__item is-active">1</button>
+  <button class="hf-pagination__item">2</button>
+  <button class="hf-pagination__item">3</button>
+  <span class="hf-pagination__ellipsis">…</span>
+  <button class="hf-pagination__item">12</button>
+  <button class="hf-pagination__item" aria-label="Next">›</button>
+</div>
+```
+### Modal
+```html
+<div class="hf-modal max-w-[500px] mx-auto">
+  <div class="hf-modal__header">
+    <h2 class="hf-modal__title">Edit Guest</h2>
+    <button class="hf-modal__close" aria-label="Close">✕</button>
+  </div>
+  <div class="hf-modal__body">…</div>
+  <div class="hf-modal__footer">
+    <button class="hf-btn hf-btn--cancel">Cancel</button>
+    <button class="hf-btn hf-btn--primary">Save</button>
+  </div>
+</div>
+<!-- footer with top border: add .hf-modal--with-footer-border on .hf-modal -->
+```
+### Alert
+```html
+<div class="hf-alert hf-alert--success">
+  <div class="hf-alert__icon"><!-- icon svg --></div>
+  <div class="hf-alert__body">
+    <div class="hf-alert__title">Saved successfully</div>
+    <p class="hf-alert__text">Booking #1284 has been updated.</p>
+  </div>
+  <button class="hf-alert__close" aria-label="Dismiss">✕</button>
+</div>
+<!-- variants: --success | --info | --warn | --error · modifiers: --tinted | --banner | --compact -->
+```
+### Toast
+```html
+<div class="hf-toast hf-toast--success">
+  <span class="hf-toast__icon"><!-- icon svg --></span>
+  <span class="hf-toast__text">Booking <strong>#2841</strong> confirmed</span>
+  <button class="hf-toast__close" aria-label="Dismiss">✕</button>
+</div>
+<!-- variants color the icon + 3px left edge: --success | --error | --warn | --info -->
+```
+### Dropdown menu
+```html
+<div class="hf-dropdown-menu w-52">
+  <div class="hf-dropdown-menu__header">Actions</div>
+  <div class="hf-dropdown-menu__item">View details</div>
+  <div class="hf-dropdown-menu__item">Edit <span class="hf-dropdown-menu__shortcut">⌘E</span></div>
+  <div class="hf-dropdown-menu__item is-disabled">Refresh</div>
+  <div class="hf-dropdown-menu__divider"></div>
+  <div class="hf-dropdown-menu__item hf-dropdown-menu__item--danger">Delete</div>
+</div>
+<!-- pre-0.4 flat names (.hf-dropdown-header / -item / -divider) still work as deprecated aliases -->
+```
+### Checkbox & radio
+```html
+<input type="checkbox" class="hf-check" checked />
+<input type="checkbox" class="hf-check" disabled />
+<input type="radio" name="grp" class="hf-radio" checked />
+```
+### Buttons
+```html
+<button class="hf-btn hf-btn--primary">Save</button>
+<button class="hf-btn hf-btn--outline-primary">Preview</button>
+<button class="hf-btn hf-btn--outline-default">Settings</button>
+<button class="hf-btn hf-btn--cancel">Cancel</button>
+<button class="hf-btn hf-btn--danger">Delete</button>
+<button class="hf-btn hf-btn--primary hf-btn--sm">Small</button>
+<button class="hf-btn hf-btn--icon hf-btn--outline-default" aria-label="Edit">✎</button>
+```
+### Density / touch mode
+Buttons and inputs read their height from a density scope — switch a whole app (or one container) with `data-density`; no per-component change. Default = desktop (40px); `touch` (POS/mobile) = 48px controls + 44px tap.
+```html
+<html data-density="touch">        <!-- 48px controls -->
+<div data-density="comfortable">…</div>   <!-- 44px, scoped -->
+```
+| density | button | small | input |
+|---|---|---|---|
+| default | 40px | 32px | 39px |
+| `comfortable` | 44px | 36px | 44px |
+| `touch` | 48px | 40px | 48px |
+### Form controls & field
+```html
+<div class="hf-form-field">
+  <label class="hf-form-field__label hf-form-field__label--required">Email</label>
+  <input type="email" class="hf-input" placeholder="guest@example.com" />
+  <span class="hf-form-field__hint">We'll never share it.</span>
+</div>
+<div class="hf-form-field hf-form-field--error">
+  <label class="hf-form-field__label">Room</label>
+  <div class="hf-select-wrap">
+    <select class="hf-select">
+      <option>Deluxe</option>
+      <option>Suite</option>
+    </select>
+  </div>
+  <span class="hf-form-field__error">Please choose a room.</span>
+</div>
+<textarea class="hf-textarea" placeholder="Notes…"></textarea>
+<!-- toggle: a styled checkbox -->
+<input type="checkbox" class="hf-switch" checked />
+<!-- standalone invalid (no .hf-form-field wrapper) — for framework form state, e.g. Angular.
+     Either trigger gives the red border + red focus ring: -->
+<input class="hf-input" aria-invalid="true" />
+<input class="hf-input hf-input--error" />   <!-- alias class, same effect -->
+```
+### Card
+```html
+<section class="hf-card">
+  <header class="hf-card__header">
+    <div>
+      <h3 class="hf-card__title">Channel settings</h3>
+      <p class="hf-card__description">Enable the sales channels for this property.</p>
+    </div>
+    <button class="hf-btn hf-btn--outline-default hf-btn--sm">Edit</button>
+  </header>
+  <div class="hf-card__body">…</div>
+  <footer class="hf-card__footer">
+    <button class="hf-btn hf-btn--cancel">Cancel</button>
+    <button class="hf-btn hf-btn--primary">Save</button>
+  </footer>
+</section>
+<!-- borderless/flat variant: add .hf-card--flat -->
+```
+### Drawer (side-panel)
+```html
+<div class="hf-drawer">
+  <div class="hf-drawer__backdrop"></div>
+  <aside class="hf-drawer__panel">
+    <header class="hf-drawer__header">
+      <h2 class="hf-drawer__title">Reservation #2841</h2>
+      <button class="hf-drawer__close" aria-label="Close">✕</button>
+    </header>
+    <div class="hf-drawer__body">…</div>
+    <footer class="hf-drawer__footer">
+      <button class="hf-btn hf-btn--cancel">Close</button>
+      <button class="hf-btn hf-btn--primary">Check in</button>
+    </footer>
+  </aside>
+</div>
+<!-- slide from the left: add .hf-drawer--left on .hf-drawer -->
+```
+### Table
+```html
+<!-- style a plain <table>; wrap in a bordered container for the card look -->
+<div class="rounded-lg border border-hf-border overflow-hidden">
+  <table class="hf-table">
+    <thead>
+      <tr><th>Guest</th><th>Status</th><th class="hf-table__num">Total</th></tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Amanda Peterson</td>
+        <td><span class="hf-pill status-booking-confirmed">Confirmed</span></td>
+        <td class="hf-table__num">€ 1,240</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<!-- disable the row hover (static summary tables): add .hf-table--static -->
+```
+### Empty state
+```html
+<!-- empty when the request SUCCEEDS with no results; use .skeleton while it's IN FLIGHT -->
+<div class="hf-empty">
+  <div class="hf-empty__icon"><!-- icon svg --></div>
+  <h3 class="hf-empty__title">No bookings found</h3>
+  <p class="hf-empty__text">Try adjusting your filters.</p>
+  <div class="hf-empty__action">
+    <button class="hf-btn hf-btn--primary">New booking</button>
+  </div>
+</div>
+<!-- --compact (in-card) · --row (inside an .hf-table colspan cell) -->
+```
+## Cheat-sheet — common tokens & utilities
+Tailwind v4 derives utilities from the `@theme` tokens (`bg-hf-*`, `text-hf-*`, `rounded-hf-*`, `shadow-hf-*`). Vanilla CSS uses the `var(--color-hf-*)` form; SCSS uses `$colorAccent`, `$radiusSm`, … See [`UI_DESIGN.md`](UI_DESIGN.md) §9 for the full token list.
+**Brand & text color**
+| Utility | Token | Value |
+|---|---|---|
+| `bg-hf-accent` / `text-hf-accent` | `--color-hf-accent` | `#24AFE8` (brand) |
+| `hover:bg-hf-accent-hover` | `--color-hf-accent-hover` | `#149AD1` |
+| `bg-hf-accent-subtle` / `-subtler` | `--color-hf-accent-subtle` | light tints |
+| `text-hf-fg` | `--color-hf-fg` | body `#2B2B2B` |
+| `text-hf-fg-muted` / `-subtle` / `-faint` | `--color-hf-fg-*` | secondary → placeholder |
+| `text-hf-on-accent` | `--color-hf-on-accent` | `#0B2F46` (AA text on accent — D1) |
+**Surfaces & borders**
+| Utility | Token |
+|---|---|
+| `bg-hf-bg-surface` | card / modal / popover (white) |
+| `bg-hf-bg-page` / `-section` / `-muted` | page → section → muted grays |
+| `border-hf-border` / `-subtle` / `-strong` | default → faint → hover border |
+**Scales**
+- **Text:** `text-hf-xs` 11 · `text-hf-sm` 13 · `text-hf-base` 14 · `text-hf-md` 15 · `text-hf-lg` 16 · `text-hf-xl` 18
+- **Radius:** `rounded-hf-sm` 6 · `-md` 8 · `-lg` 9 · `-xl` 12 · `-pill` 99
+- **Shadow:** `shadow-hf-subtle` · `shadow-hf-card` · `shadow-hf-modal` · `shadow-hf-hover`
+- **Status:** `text-hf-status-{success|warning|error|info|cancel}` + `bg-hf-status-{…}-bg` — or just use `.hf-pill .status-{domain}-{state}`
+## Visual reference (live)
+`components.html` is the canonical rendered showcase of every `.hf-*` component. The package is public on npm, so **unpkg serves it rendered in the browser** — no hosting needed:
+**→ https://unpkg.com/@hotelfriendag/design-tokens/components.html**
+Always serves the latest; pin a version with `…/design-tokens@0.5.0/components.html`. Or open the copy in your own project:
+```bash
+open node_modules/@hotelfriendag/design-tokens/components.html       # macOS
+xdg-open node_modules/@hotelfriendag/design-tokens/components.html   # Linux
+start node_modules\@hotelfriendag\design-tokens\components.html      # Windows
+```
+> Use the **unpkg** link, not jsDelivr — jsDelivr serves `.html` as `text/plain` (shows source); unpkg serves it as `text/html` (renders).
 ## AI rules
 The package ships agent rules under `ai-rules/`. Drop one into the consumer's root so Claude / Cursor / Copilot follow the same UI rules:

package/UI_DESIGN.md CHANGED Viewed

@@ -241,11 +241,14 @@ box-shadow: 0 3px 4px rgba(0, 0, 0, 0.03);
 ### Buttons
+> **Design-system API (v0.4+):** these portal recipes now ship as the `.hf-btn` primitive in `pre-built/components.css`. Use `.hf-btn` + a modifier in new code; the legacy portal classes below are the source these were extracted from:
+> `.btn-primary`→`.hf-btn--primary` · `.btn-hf-outline-primary`→`.hf-btn--outline-primary` · neutral `.btn`→`.hf-btn--outline-default` · `.btn-cancel`→`.hf-btn--cancel` · `.btn-delete`→`.hf-btn--danger` · `.btn-sm`→`.hf-btn--sm` · icon-only→`.hf-btn--icon`.
 Live observation: 25+ unique button variants across 13 sidebar sections + 7 sub-tabs + 7 edit forms. Below is the canonical set; legacy variants (e.g. `btn.btn-b-gray`, `btn-text-blue`) exist but should be migrated.
 | Style       | Class                          | Look                                                         |
 | ----------- | ------------------------------ | ------------------------------------------------------------ |
-| **Primary** | `.btn.btn-primary`             | Solid `#24AFE8` bg, white text, 40px h, 15/600. Hover: `#149AD1` bg. |
+| **Primary** | `.btn.btn-primary`             | Solid `#24AFE8` bg, AA dark text `#0B2F46` (founder decision D1 — white failed WCAG AA at 2.51:1), 40px h, 15/600. Hover: `#149AD1` bg. |
 | **Primary sm** | `.btn.btn-primary.btn-sm`   | Solid bg, 32px h, 15/600, padding `7px 14px`.                |
 | **Primary search** | `.btn.btn-primary.pr13` | 38px h, padding `10px 13px` — used as inline search submit.  |
 | **Outline** | `.btn.btn-hf-outline-primary`  | White bg, `#24AFE8` border + text. 40px h, 15/600.           |
@@ -430,6 +433,7 @@ These are the **canonical component classes** shipped in `pre-built/components.c
 - **Anatomy:** white bg, 9px radius, `0 6px 18px rgba(0,0,0,.10)` shadow, 1px border `rgba(72,91,120,.15)`
 - **Layout:** inline-flex with `__icon` (20×20) + `__text` (flex:1) + optional `__close` (20×20)
 - **Sizing:** min-width 280px, max-width 420px
+- **Variants (v0.6):** `--success` / `--error` / `--warn` / `--info` — bound to the `--color-hf-status-*` families (same structure as `.hf-alert--*`). The variant sets the accent color via `currentColor` (which tints the `__icon`) and adds a 3px left edge; the message text stays `--color-hf-fg`. Use these instead of hand-coloring the icon.
 - **Positioning:** typically `position: fixed; bottom: 16px; right: 16px; z-index: 50`
 - **Reference:** `components.html#alerts` · **Portal source:** `.alert-box` (different DOM structure) · **Decision:** New modern primitive — portal `.alert-box` is positioned but uses heavier `.alert` chrome. Toast is lighter.
@@ -445,29 +449,84 @@ These are the **canonical component classes** shipped in `pre-built/components.c
 ### `.hf-dropdown-menu` — Dropdown
 - **Anatomy:** 9px radius, white bg, `box-shadow: 0 1px 10px 0 rgba(0,0,0,.1)` (portal's `$dropdown_shadow`), 1px border `rgba(228,232,239,.6)`, padding `6px 0`, min-width 180px
-- **Children:**
+- **Children** (canonical BEM, v0.4+):
   - `__header` — uppercase 11px/600 `#99A1B7` section label
   - `__item` — flex row, padding `8px 16px`, 14px text, gap 10px
-  - `__item__icon` — 16px, color `#99A1B7` (faint), becomes `#50627E` on item hover
-  - `__item__shortcut` — right-aligned 12px text (for ⌘keys or counts)
+  - `__item-icon` — 16px, color `#99A1B7` (faint), becomes `#50627E` on item hover
+  - `__shortcut` — right-aligned 12px text (for ⌘keys or counts)
   - `__divider` — 1px `#E4E8EF` separator
 - **Item states:**
   - Default → hover `bg: #F5F5F5`
   - `.is-active` → `bg: #EFF6FF; color: #24AFE8` (primary tint + primary text)
   - `:focus-visible` → outline 2px primary inset
-  - `.danger` → red text, red-tint hover
+  - `__item--danger` → red text, red-tint hover
   - `.is-disabled` / `[aria-disabled="true"]` → `#AEBCCF` color, pointer-events none
-- **Reference:** `components.html#dropdown` · **Portal source:** `.dropdown-menu.open` in `_custom.scss` · **Decision:** 1:1 portal match for shadow/radius/colors. **Adapted:** uses flat `<div>` structure instead of Bootstrap 3 `<ul><li><a>` (modern, framework-agnostic).
+- **Deprecated aliases (still work, remove in v1.0):** the pre-0.4 flat names `.hf-dropdown-header`, `.hf-dropdown-item`, `.hf-dropdown-item__icon`, `.hf-dropdown-item__shortcut`, `.hf-dropdown-divider`, `.hf-dropdown-item.danger`.
+- **Reference:** `components.html#dropdown` · **Portal source:** `.dropdown-menu.open` in `_custom.scss` · **Decision:** 1:1 portal match for shadow/radius/colors. **Adapted:** uses flat `<div>` structure instead of Bootstrap 3 `<ul><li><a>` (modern, framework-agnostic); renamed to BEM children of `.hf-dropdown-menu` in v0.4 for consistency with `.hf-modal__*` / `.hf-alert__*`.
+### `.hf-btn` — Buttons (v0.4+)
+- **Anatomy:** `inline-flex` center, height 40px, padding `0 20px`, 6px radius, 15px/600, `border: 1px solid transparent`, 200ms transitions. `:focus-visible` → 2px accent outline (offset 2px). `:disabled` / `.is-disabled` → opacity .6, not-allowed.
+- **Variants:**
+  - `--primary` — accent bg, AA dark text `--color-hf-on-accent` (`#0B2F46`, 5.55:1 — founder decision D1; white failed AA); hover `--color-hf-accent-hover` (`#149AD1`)
+  - `--danger` — `--color-hf-status-error-strong` (`#D9534F`) bg; hover `--color-hf-status-error-strong-hover` (`#C9302C`)
+  - `--outline-primary` — white bg, accent text + border; hover bg-muted
+  - `--outline-default` — white bg, steel text, neutral border, `--shadow-hf-outline`; hover bg-muted
+  - `--cancel` — transparent, muted text; hover bg-muted
+- **Sizes/shapes:** `--sm` (32px / 14px), `--icon` (square — width = height), `--block` (full width)
+- **Density (v0.5):** height follows the `[data-density]` scope — desktop 40 / `comfortable` 44 / `touch` 48px (vars `--hf-btn-h` / `-sm`). Set `data-density="touch"` on a container/`<html>` for POS/mobile; see `ADOPTION.md`.
+- **Reference:** `components.html#buttons` · **Portal source:** `.btn-primary` / `.btn-hf-outline-*` / `.btn-cancel` / `.btn-delete` · **Decision:** consolidates 25+ portal button recipes into one base + modifiers. Compact portal-only families (reset-filters, icon-square) stay Tailwind-utility recipes until promoted.
+### `.hf-input` / `.hf-textarea` / `.hf-select` — Form controls (v0.4+)
+- **Anatomy:** width 100%, height 39px, padding `0 12px`, 6px radius, 1px `--color-hf-input-border` (`#DBDFE9`), 14px text. Placeholder `--color-hf-fg-faint`.
+- **Focus:** accent border + 3px `--color-hf-accent-subtle` ring (accessible — portal had no ring).
+- **Invalid (v0.6):** a red border + red focus ring fires from any of three equivalent triggers — inside an `.hf-form-field--error` wrapper, the standalone `[aria-invalid="true"]` attribute, or the alias class `.hf-input--error` / `.hf-textarea--error` / `.hf-select--error`. The standalone forms let framework form wrappers (Angular) flag a control without the `.hf-form-field` wrapper.
+- **Disabled:** bg-muted, faint text, not-allowed.
+- **Textarea:** auto height, min-height 80px, vertical resize.
+- **Select:** `appearance:none` + wrapper `.hf-select-wrap` draws a token-colored caret (clip-path triangle, same technique as `.hf-pill--dd` — no data-URI, so no bare hex).
+- **Reference:** `components.html#inputs` · **Portal source:** `.form-control` · **Decision:** 1:1 geometry; adds the accessible focus ring the portal lacks.
+### `.hf-switch` — Toggle (v0.4+)
+- **Anatomy:** styled `<input type="checkbox">`, 40×22 track (999px radius), 18px white knob with `--shadow-hf-hover`. Off = `--color-hf-border`; `:checked` = accent bg + knob slides 18px right. `:focus-visible` outline; `:disabled` opacity .5.
+- **Reference:** `components.html#inputs` · **Decision:** new lightweight token-driven primitive (portal shipped only a Bootstrap-Switch).
+### `.hf-form-field` — Field wrapper (v0.4+)
+- **Anatomy:** `flex column gap 6px`. `__label` (14px/500), `__label--required::after` red `*`, `__hint` (13px subtle), `__error` (13px error).
+- **State:** `--error` colours the contained `.hf-input` / `.hf-textarea` / `.hf-select` border + focus ring in `--color-hf-status-error`.
+- **Reference:** `components.html#inputs` · **Decision:** new primitive — standardises label + control + hint/error so consumers stop re-inventing field structure.
+### `.hf-card` — Card (v0.4+)
+- **Anatomy:** white bg, 1px `--color-hf-border-subtle`, 12px radius, `--shadow-hf-card`. `__header` (20px, bottom border) + `__title` (18px/600) + `__description` (14px muted) + `__body` (20px) + `__footer` (20px, top border, right-aligned).
+- **Variant:** `--flat` removes the shadow.
+- **Reference:** `components.html#cards` · **Portal source:** `.dashboard-card` · **Decision:** elevated card; for the lighter look use the bordered pattern `bg-white rounded-lg border p-5`.
+### `.hf-drawer` — Side-panel (v0.4+)
+- **Anatomy:** `position:fixed; inset:0; z-index:10051` (= `zIndex.modalDialog`), flex justify-end. `__backdrop` (`rgba(0,0,0,.4)`), `__panel` (max-width 480px, full height, `--shadow-hf-modal`, slide-in keyframe). `--left` slides from the left. `__header` / `__title` / `__close` / `__body` (scroll) / `__footer` mirror `.hf-modal`.
+- **Reference:** `components.html#layout` · **Decision:** new primitive — consolidates the repeated backdrop + sliding-panel pattern (reservation / room / guest drawers).
+### `.hf-table` — Table (v0.6+)
+- **Anatomy:** style a plain `<table class="hf-table">` with element selectors — `thead` gets `--color-hf-bg-section` bg; `th` are uppercase 13px/500 `--color-hf-tab-fg-inactive` (steel) with `padding: 12px 20px`; `td` get a 1px `--color-hf-border-subtle` top divider (the first body row has none). Row hover = `--color-hf-menu-bg-hover` (the legacy portal `$table__hover`).
+- **Helpers:** `.hf-table__num` on a th/td right-aligns (numeric / action columns). `--static` disables the row hover (summary tables).
+- **Usage:** wrap in `bg-white rounded-lg border overflow-hidden` for the card look. An empty result renders `.hf-empty--row` inside a `<td colspan>` cell.
+- **Reference:** `components.html#table` · **Decision:** new primitive — the thead-bg + divider + hover recipe was hand-rolled on every dashboard page; no new token (reuses existing semantic + component-tier tokens).
+### `.hf-empty` — Empty state (v0.6+)
+- **Anatomy:** centered flex column — `__icon` (64px disc, `--color-hf-bg-muted` bg, faint icon) + `__title` (18px/600) + `__text` (14px muted, max-w 28rem) + `__action` (button row).
+- **Modifiers:** `--compact` (in-card — 40px transparent icon, tighter padding, 14px title) · `--row` (inside an `.hf-table` `<td colspan>` — single centered line + optional secondary action).
+- **Usage rule:** empty states are for when the request **succeeds with no results**; use `.skeleton` while the request is **in flight** — they are not interchangeable (documented in the CSS).
+- **Reference:** `components.html#empty` · **Decision:** new primitive — promotes the three demo recipes (page / in-card / in-table) into shipped CSS; no new token.
 ### `.skeleton` / `.hf-spin` — Loading primitives
 - **Skeleton:** linear-gradient shimmer animation, 1.4s infinite, 4px radius. Use as block element with width/height utilities (e.g. `<div class="skeleton h-3 w-3/4">`)
 - **Spinner:** `@keyframes hf-spin` rotate animation. Apply `.hf-spin` to an SVG.
+- **Reduced motion (v0.6):** a `@media (prefers-reduced-motion: reduce)` block stops the infinite shimmer + spin (skeleton keeps a flat muted block) and neutralizes the drawer slide-in.
 - **Reference:** `components.html#empty` · **Decision:** New primitives — portal has no equivalent.
 ---
 ## 6. Forms
+> **Design-system API (v0.4+):** these ship as `.hf-input` / `.hf-textarea` / `.hf-select` + `.hf-form-field` + `.hf-switch` in `pre-built/components.css` (see §5.1). Use those in new code; the portal-observed specs below are the source. The DS focus ring (accent border + 3px `--color-hf-accent-subtle`) is the accessible variant.
 - **Inputs (Text / Select):** Height `39px`, Padding `6px 12px`, Radius `6px`, Border `1px solid #d1d6dd`. Placeholder `#AEBCCF`. **Focus (portal-exact):** border darkens only to `#B2BAC4`, **no ring**. **Focus (accessible, recommended for new projects):** add `box-shadow: 0 0 0 2px rgba(36,175,232,0.2)` for WCAG compliance.
 - **Field Anatomy:**
   1. Label (`14px / 500`, color `#2B2B2B`, margin-bottom `8px`).

package/ai-rules/CLAUDE.md CHANGED Viewed

@@ -4,29 +4,30 @@
 ## Project: {{PROJECT_NAME}}
-This project follows the **HotelFriend Design System v0.1.0**. The design system is the SSOT for all UI work — tokens, components, states, spacing, typography. Do NOT introduce off-system colors, sizes, or one-off shadows.
+This project follows the **HotelFriend Design System** (@hotelfriendag/design-tokens — version per the installed package, see CHANGELOG.md). The design system is the SSOT for all UI work — tokens, components, states, spacing, typography. Do NOT introduce off-system colors, sizes, or one-off shadows.
 ## Where the design system lives in this repo
-- **`docs/portable-design/components.html`** — **PRIMARY visual reference** (open in browser). Canonical rendering of every component. When in doubt, look here.
-- `docs/portable-design/UI_DESIGN.md` — narrative SSOT (read this first for context, anatomy, decision rationale)
-- `docs/portable-design/tokens.figma.json` — atomic tokens (Tokens Studio format)
-- `docs/portable-design/states-canonical.json` — canonical interactive states for 24 components (modal, alert, pagination, dropdown items, checkboxes etc.)
-- `docs/portable-design/pre-built/`:
-  - `tailwind.css` (Tailwind v4, recommended) — `@theme {}` token bindings
-  - `tailwind.preset.js` (Tailwind v3 legacy)
-  - `tokens.css` (vanilla CSS variables)
-  - `_tokens.scss` (SCSS variables)
-  - `tokens.ts` (TypeScript const)
-  - `shadcn-tokens.css` (shadcn/ui contract)
-  - **`components.css`** — `.hf-*` component primitives (extracted from components.html — import this in your CSS!)
-- `docs/portable-design/portal-audit.html` — **archival** legacy portal snapshot. Do NOT copy patterns from here for new code.
+Files are shipped in the `@hotelfriendag/design-tokens` npm package. After `pnpm add @hotelfriendag/design-tokens` they are available via subpath exports:
+- **`node_modules/@hotelfriendag/design-tokens/components.html`** — **PRIMARY visual reference** (open in browser, or use the public URL https://unpkg.com/@hotelfriendag/design-tokens/components.html). Canonical rendering of every component. When in doubt, look here.
+- `node_modules/@hotelfriendag/design-tokens/UI_DESIGN.md` — narrative SSOT (read this first for context, anatomy, decision rationale)
+- `node_modules/@hotelfriendag/design-tokens/states-canonical.json` — canonical interactive states for 24 components (modal, alert, pagination, dropdown items, checkboxes etc.)
+- Import paths (use `@hotelfriendag/design-tokens/<file>` in build tools):
+  - `@hotelfriendag/design-tokens/tailwind.css` (Tailwind v4, recommended) — `@theme {}` token bindings
+  - `@hotelfriendag/design-tokens/tokens.css` (vanilla CSS variables)
+  - `@hotelfriendag/design-tokens/components.css` — `.hf-*` component primitives
+  - `@hotelfriendag/design-tokens/status.css` — `.status-{domain}-{state}` rules (generated from status-map.json)
+  - `@hotelfriendag/design-tokens/pre-built/_tokens.scss` (SCSS variables — Dart Sass: `@use '@hotelfriendag/design-tokens/pre-built/tokens' as ds`)
+  - `@hotelfriendag/design-tokens/tokens.ts` (TypeScript const)
+  - `@hotelfriendag/design-tokens/shadcn-tokens.css` (shadcn/ui contract)
+- `portal-audit.html` — **archival** legacy portal snapshot. Do NOT copy patterns from here for new code.
 ## Hard rules — never violate these
-1. **Colors:** Use only tokens defined in `pre-built/tailwind.css` / `pre-built/tokens.css`. Never hard-code hex codes. The primary brand color is `#24AFE8` (CSS var `--color-primary`, Tailwind `primary`). The four status colors are success `#59B59D`, warning `#FFBD5A`, error `#EA6565`, coral `#F87921`.
-2. **Status badges:** Use `.hf-pill .status-{domain}-{state}`. Color is `var(--color-badge-{domain}-{state}-color)`, background is `var(--color-badge-{domain}-{state}-bg)` (15% alpha). Cancellation reasons (`canceled-by-hotel/guest/hf/pos`) all share the `.status-cancel` alias. Do NOT invent new status colors.
-3. **Component primitives — reuse, never rebuild:** Before writing a modal, alert, dropdown, pagination, tabs, checkbox, or toggle, **check `pre-built/components.css` for an existing `.hf-*` primitive**. Use `.hf-modal`, `.hf-alert`, `.hf-pagination`, `.hf-dropdown-menu`, `.hf-check`, etc. with their BEM-style children (`__header`, `__body`, `__footer`, `__icon`, `__title`, `__close`, etc.) and modifiers (`--success`, `--tinted`, `--banner`, `--compact`, `--sm`). See `UI_DESIGN.md` §5.1 for the full list.
+1. **Colors:** Use only tokens defined in `@hotelfriendag/design-tokens/tailwind.css` / `@hotelfriendag/design-tokens/tokens.css`. Never hard-code hex codes. The primary brand color is `#24AFE8` (CSS var `--color-hf-accent`, SCSS `$colorAccent`, Tailwind `bg-hf-accent`). The four status colors are success `#59B59D`, warning `#FFBD5A`, error `#EA6565`, coral `#F87921`.
+2. **Status badges:** Use `.hf-pill .status-{domain}-{state}` (rules in `status.css`). Each class sets `color`/`background` from a semantic slot — `var(--color-hf-status-{role})` and `var(--color-hf-status-{role}-bg)` (15% alpha) — and the domain→role map lives in `status-map.json`. Cancellation reasons (`canceled-by-hotel/guest/hf/pos`) all share the `.status-cancel` alias. Do NOT invent new status colors.
+3. **Component primitives — reuse, never rebuild:** Before writing a button, input, modal, alert, dropdown, pagination, tabs, checkbox, toggle, card, or drawer, **check `@hotelfriendag/design-tokens/components.css` for an existing `.hf-*` primitive**. Available: `.hf-btn` (`--primary` / `--danger` / `--outline-primary` / `--outline-default` / `--cancel`, sizes `--sm` / `--icon`); `.hf-input` / `.hf-textarea` / `.hf-select` (wrap `<select>` in `.hf-select-wrap`); `.hf-switch`; `.hf-form-field` (`__label` / `__hint` / `__error`, state `--error`); `.hf-card`; `.hf-drawer`; `.hf-modal`; `.hf-alert`; `.hf-pagination`; `.hf-dropdown-menu`; `.hf-check` / `.hf-radio`; `.hf-pill`; `.hf-tab`; `.hf-toast` (`--success` / `--error` / `--warn` / `--info`); `.hf-table`; `.hf-empty` (`--compact` / `--row`); invalid state `[aria-invalid="true"]` / `.hf-input--error`. Use BEM-style children (`__header`, `__body`, `__footer`, `__title`, `__close`, `__item`, …) and modifiers (`--primary`, `--success`, `--tinted`, `--banner`, `--compact`, `--sm`). For dropdowns the canonical children are `.hf-dropdown-menu__header / __item / __item-icon / __shortcut / __divider` and modifier `.hf-dropdown-menu__item--danger` (the older flat `.hf-dropdown-{header|item|divider}` names still work as deprecated aliases). See `UI_DESIGN.md` §5.1 for the full list.
 4. **Typography:** Family is **Roboto**. Sizes from canonical scale only: 11/13/14/15/16/18/20/24/26/30 px. Weights only 400 / 500 / 600. Line-heights 1.2 (headings), 1.5 (body), 1 (chips).
 5. **Spacing:** Multiples of 4 only. Default section gap is 20px. Never write 7px / 13px / 18px — round to the scale. (Exception: portal-exact padding `7px 10px 9px` for `.hf-alert` `help-block` is documented in components.html.)
 6. **Border radius:** `6px` (buttons/inputs/checkboxes/modals/alerts), `8px` (pagination items), `9px` (dropdowns/toasts/pill-tabs), `12px` (large cards), `99px` (status pills are 6px square — pills are NOT round). Never invent intermediate values.
@@ -35,29 +36,50 @@ This project follows the **HotelFriend Design System v0.1.0**. The design system
 9. **Pagination active state:** Pagination active is a **subtle gray** (`bg: #E4E8EF; color: #252F4A`) — NOT primary blue. This is portal-exact and easy to get wrong. Use `.hf-pagination__item.is-active`.
 10. **Components:** Before creating a new component, check `components.html` for an existing equivalent (open in browser, search section IDs `#buttons`, `#inputs`, `#cards`, `#status`, `#tabs`, `#dropdown`, `#modal`, `#alerts`, `#pagination`, `#empty`, `#layout`). Reuse beats duplicate.
+## Accessibility — required markup
+The design system ships CSS only; the **JS behaviors and ARIA wiring below are YOUR responsibility**
+(focus trap, arrow-key navigation, Escape/dismissal, focus return, `aria-live`). Always supply the
+required markup for these components:
+- **Modal** — `role="dialog"` + `aria-modal="true"` + a labelled title (`aria-labelledby`) + a focus trap + Escape-to-close.
+- **Drawer** — same as modal (dialog semantics, focus trap, Escape).
+- **Tabs** — `role="tablist"` / `role="tab"` / `role="tabpanel"` + `aria-selected` + arrow-key navigation.
+- **Dropdown menu** — `role="menu"` / `role="menuitem"` + arrow keys + Escape + focus return to the trigger on close.
+- **Switch** — a native `<input type="checkbox">` (or `role="switch"`) with an associated `<label>`.
+- **Checkbox / radio** — native `<input type="checkbox|radio">` (`.hf-check` / `.hf-radio` style native inputs).
+- **Icon-only buttons** — `aria-label` (the icon is not an accessible name).
+- **Pagination** — wrap in `<nav aria-label="Pagination">`.
+- **Toasts** — render inside an `aria-live="polite"` region.
+- **Tables** — `<th scope="col">` / `<th scope="row">` on header cells.
+WCAG 2.1 **AA is the floor.** Keep `:focus-visible` outlines (the design system ships them — never
+remove without a visual replacement) and don't rely on placeholder text to convey required
+information (placeholder contrast is intentionally below AA).
 ## When the user asks for UI work
-1. **Read `UI_DESIGN.md`** — start here for new sessions.
-2. **Open `components.html`** in a browser — see the canonical rendering.
-3. **Pick existing `.hf-*` primitives** from `pre-built/components.css` first. Use Tailwind utility classes only for layout (flex/grid/spacing) — not for component chrome (colors, shadows, borders).
-4. **States matter:** every interactive element needs default + hover + focus + disabled + loading. See `states-canonical.json` for the exact declarations to mirror.
+1. **Read `UI_DESIGN.md`** (at `node_modules/@hotelfriendag/design-tokens/UI_DESIGN.md`) — start here for new sessions.
+2. **Open `components.html`** in a browser (`node_modules/@hotelfriendag/design-tokens/components.html`, or https://unpkg.com/@hotelfriendag/design-tokens/components.html) — see the canonical rendering.
+3. **Pick existing `.hf-*` primitives** from `@hotelfriendag/design-tokens/components.css` first. Use Tailwind utility classes only for layout (flex/grid/spacing) — not for component chrome (colors, shadows, borders).
+4. **States matter:** every interactive element needs default + hover + focus + disabled + loading. See `states-canonical.json` (`node_modules/@hotelfriendag/design-tokens/states-canonical.json`) for the exact declarations to mirror.
 5. **No "raw HTML" answers** — wrap markup in the documented component class system. If the design system lacks something, propose a NEW token or primitive in a comment, do not silently introduce one.
 ## When the user asks for "the same look as the portal"
-The visual reference is `components.html`. If the user asks "make a settings page like the portal", do this in order:
+The visual reference is `components.html` (`node_modules/@hotelfriendag/design-tokens/components.html` or https://unpkg.com/@hotelfriendag/design-tokens/components.html). If the user asks "make a settings page like the portal", do this in order:
 1. Open `components.html`, find Page Layouts section (`#layout`). Pick the matching pattern (List / Detail / Form / Dashboard).
 2. Replicate the structure (Title bar → Tabs → Filters → Data grid → Footer pagination).
-3. Use only `.btn-primary`, `.btn-outline-primary`, `.btn-cancel`, `.btn-danger` for buttons.
+3. Use `.hf-btn` + a variant (`.hf-btn--primary`, `.hf-btn--outline-primary`, `.hf-btn--cancel`, `.hf-btn--danger`) for buttons.
 4. Use `.hf-pill .status-{domain}-{state}` for status indicators.
-5. Wrap data sections in `.bg-white rounded-lg border border-border p-5` (the bordered card pattern — most common in portal).
+5. Wrap data sections in `.hf-card` (`__header` / `__body` / `__footer`), or the lighter bordered pattern `.bg-white rounded-lg border border-border p-5` — both common in the portal.
 6. Use `.hf-pagination` for pager.
 7. Use `.hf-modal` / `.hf-alert` / `.hf-dropdown-menu` for floating UI.
 ## Anti-patterns
-- ❌ `<button class="bg-blue-500 text-white px-4 py-2 rounded">Save</button>` (Tailwind native classes for what should be a `.btn.btn-primary`)
+- ❌ `<button class="bg-blue-500 text-white px-4 py-2 rounded">Save</button>` (Tailwind native classes for what should be a `.hf-btn.hf-btn--primary`)
 - ❌ Inventing colors like `#1F8FCE` because "it's close to primary"
 - ❌ Border-radius `8px` because "it looks better than 6px" (8px is reserved for pagination items only)
 - ❌ Adding a new shadow `0 4px 12px rgba(...)` instead of `var(--shadow-hf-modal)`
@@ -67,7 +89,7 @@ The visual reference is `components.html`. If the user asks "make a settings pag
 - ❌ Pagination with `bg-hf-primary text-white` active — use `.hf-pagination__item.is-active` (subtle gray)
 - ❌ Using native `<input type="checkbox" class="accent-primary">` instead of `<input type="checkbox" class="hf-check">` — accent-color doesn't match portal's filled-blue-with-white-tick design
 - ❌ Mixing icon sets (Lucide + Font Awesome + Heroicons in the same screen)
-- ❌ Copying patterns from `portal-audit.html` — that's the legacy snapshot, NOT canonical reference
+- ❌ Copying patterns from `portal-audit.html` (`node_modules/@hotelfriendag/design-tokens/portal-audit.html`) — that's the legacy snapshot, NOT canonical reference
 ## When in doubt
@@ -75,6 +97,6 @@ Ask the user. Better to pause for 5 seconds than ship a one-off color that drift
 ---
-**System version:** Design System v0.1.0
+**System version:** @hotelfriendag/design-tokens — version per the installed package (see CHANGELOG.md)
 **Maintained:** alongside `UI_DESIGN.md`
-**Refresh policy:** when `tokens.figma.json` changes, run `node generate-tokens.cjs --target=tailwind-v4 > pre-built/tailwind.css` (and repeat for other targets as needed). Script is in the same folder as `tokens.figma.json`. The `pre-built/components.css` file is hand-extracted from `components.html`'s `@layer components` block — re-sync manually after component changes.
+**Refresh policy:** when `tokens.figma.json` changes in the design-system repo, run `npm run build` (which runs `node generate-tokens.cjs` for all targets). The `pre-built/components.css` file is generated from `src/components.css` by `node generate-tokens.cjs --target=components-css`; hand-edits to `pre-built/` are wiped by the next build and CI fails on drift. Consumer repos update with `pnpm update @hotelfriendag/design-tokens`.