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

@hotelfriendag/design-tokens 0.4.0 → 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 (26) hide show

package/README.md +95 -7
package/UI_DESIGN.md +18 -2
package/ai-rules/CLAUDE.md +46 -24
package/ai-rules/cursorrules.template +11 -10
package/ai-rules/github-copilot-instructions.md +18 -7
package/ai-rules/system-prompt-compact.md +10 -4
package/components.html +341 -87
package/generate-tokens.cjs +218 -2
package/package.json +9 -1
package/pre-built/_ionic.scss +51 -0
package/pre-built/_tokens.scss +3 -2
package/pre-built/components.css +226 -18
package/pre-built/dark.css +30 -0
package/pre-built/tailwind.additive.css +2 -1
package/pre-built/tailwind.css +2 -1
package/pre-built/tailwind.preset.js +36 -35
package/pre-built/themes.json +75 -0
package/pre-built/tokens.css +3 -2
package/pre-built/tokens.d.ts +1 -0
package/pre-built/tokens.js +3 -2
package/pre-built/tokens.ts +3 -2
package/pre-built/utilities.css +165 -0
package/scripts/validate-tokens.cjs +173 -5
package/src/components.css +226 -18
package/states-canonical.json +1 -1
package/tokens.figma.json +25 -3

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
@@ -140,13 +169,15 @@ App code should reference **semantic** tokens (`accent`, `fg`, `bg-*`, `border`,
 | `.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` + `__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 |
@@ -223,11 +254,12 @@ Copy-paste markup for the main `.hf-*` components — framework-agnostic (works
 ### Toast
 ```html
-<div class="hf-toast">
+<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
@@ -264,6 +296,21 @@ Copy-paste markup for the main `.hf-*` components — framework-agnostic (works
 <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
@@ -288,6 +335,11 @@ Copy-paste markup for the main `.hf-*` components — framework-agnostic (works
 <!-- 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
@@ -330,6 +382,42 @@ Copy-paste markup for the main `.hf-*` components — framework-agnostic (works
 <!-- 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.
@@ -343,7 +431,7 @@ Tailwind v4 derives utilities from the `@theme` tokens (`bg-hf-*`, `text-hf-*`,
 | `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` | `#FFFFFF` (text on accent) |
+| `text-hf-on-accent` | `--color-hf-on-accent` | `#0B2F46` (AA text on accent — D1) |
 **Surfaces & borders**
@@ -366,7 +454,7 @@ Tailwind v4 derives utilities from the `@theme` tokens (`bg-hf-*`, `text-hf-*`,
 **→ https://unpkg.com/@hotelfriendag/design-tokens/components.html**
-Always serves the latest; pin a version with `…/design-tokens@0.4.0/components.html`. Or open the copy in your own project:
+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

package/UI_DESIGN.md CHANGED Viewed

@@ -248,7 +248,7 @@ Live observation: 25+ unique button variants across 13 sidebar sections + 7 sub-
 | 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.           |
@@ -433,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.
@@ -466,17 +467,19 @@ These are the **canonical component classes** shipped in `pre-built/components.c
 ### `.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, white text; hover `--color-hf-accent-hover` (`#149AD1`)
+  - `--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).
@@ -500,9 +503,22 @@ These are the **canonical component classes** shipped in `pre-built/components.c
 - **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.
 ---

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`.
+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 `pre-built/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`. 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.
+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,17 +36,38 @@ 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).
@@ -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`.

package/ai-rules/cursorrules.template CHANGED Viewed

@@ -1,13 +1,13 @@
 # Drop this file at the project root as `.cursorrules` (or `.cursor/rules/00-design-system.md` in newer Cursor).
 # Cursor reads it automatically and prepends it to every AI request.
-You are working in a project that uses the **HotelFriend Design System v0.1.0**. The canonical visual reference is `docs/portable-design/components.html` (open in browser). Narrative SSOT in `docs/portable-design/UI_DESIGN.md`. Token bindings in `pre-built/tailwind.css` (v4, recommended) or `pre-built/tokens.css` (vanilla). Component primitives in `pre-built/components.css`.
+You are working in a project that uses the **HotelFriend Design System** (@hotelfriendag/design-tokens — version per the installed package, see CHANGELOG.md). The canonical visual reference is `node_modules/@hotelfriendag/design-tokens/components.html` (open in browser, or https://unpkg.com/@hotelfriendag/design-tokens/components.html). Narrative SSOT in `node_modules/@hotelfriendag/design-tokens/UI_DESIGN.md`. Token bindings in `@hotelfriendag/design-tokens/tailwind.css` (v4, recommended) or `@hotelfriendag/design-tokens/tokens.css` (vanilla). Component primitives in `@hotelfriendag/design-tokens/components.css`.
 # Inviolable rules
-- **Colors:** only use tokens. Primary `#24AFE8` (`--color-primary` / Tailwind `primary`). Status colors success `#59B59D`, warning `#FFBD5A`, error `#EA6565`, coral `#F87921`. Cancellation reasons share `.status-cancel`. Never hard-code other hex codes.
+- **Colors:** only use tokens. Primary `#24AFE8` (`--color-hf-accent` / `$colorAccent` / Tailwind `bg-hf-accent`). Status colors success `#59B59D`, warning `#FFBD5A`, error `#EA6565`, coral `#F87921`. Cancellation reasons share `.status-cancel`. Never hard-code other hex codes.
 - **Status badges:** use `.hf-pill .status-{domain}-{state}` (rules in `status.css`). Color/bg come from `var(--color-hf-status-{role})` / `-bg` (15% alpha); the domain→role map is in `status-map.json`. Never invent new status colors.
-- **Component primitives — reuse, never rebuild:** Use `.hf-btn`, `.hf-input` / `.hf-textarea` / `.hf-select`, `.hf-switch`, `.hf-form-field`, `.hf-card`, `.hf-drawer`, `.hf-modal`, `.hf-alert`, `.hf-pagination`, `.hf-dropdown-menu`, `.hf-tab`, `.hf-check`, `.hf-radio`, `.hf-toast` from `pre-built/components.css` BEFORE writing new component CSS. BEM children with `__` (e.g. `__header`, `__body`, `__footer`, `__item`, `__icon`). Variants with `--` (`--primary`, `--success`, `--banner`, `--compact`, `--sm`). State classes with `.is-*` (`.is-active`, `.is-disabled`). For dropdowns the canonical children are `.hf-dropdown-menu__header / __item / __item-icon / __shortcut / __divider` (the older flat `.hf-dropdown-{header|item|divider}` names still work as deprecated aliases).
+- **Component primitives — reuse, never rebuild:** Use `.hf-btn`, `.hf-input` / `.hf-textarea` / `.hf-select`, `.hf-switch`, `.hf-form-field`, `.hf-card`, `.hf-drawer`, `.hf-modal`, `.hf-alert`, `.hf-pagination`, `.hf-dropdown-menu`, `.hf-tab`, `.hf-check`, `.hf-radio`, `.hf-toast` (`--success` / `--error` / `--warn` / `--info`), `.hf-table`, `.hf-empty` (`--compact` / `--row`), invalid state `[aria-invalid="true"]` / `.hf-input--error` from `@hotelfriendag/design-tokens/components.css` BEFORE writing new component CSS. BEM children with `__` (e.g. `__header`, `__body`, `__footer`, `__item`, `__icon`). Variants with `--` (`--primary`, `--success`, `--banner`, `--compact`, `--sm`). State classes with `.is-*` (`.is-active`, `.is-disabled`). For dropdowns the canonical children are `.hf-dropdown-menu__header / __item / __item-icon / __shortcut / __divider` (the older flat `.hf-dropdown-{header|item|divider}` names still work as deprecated aliases).
 - **Typography:** Roboto only. Sizes: 11 / 13 / 14 / 15 / 16 / 18 / 20 / 24 / 26 / 30 px. Weights: 400 / 500 / 600.
 - **Spacing:** multiples of 4. Default section gap 20px.
 - **Border radius:** 6 (buttons/inputs/modals/alerts), 8 (pagination items), 9 (dropdowns/toasts), 12 (cards), 99 (pills are square 6px, not round).
@@ -15,25 +15,26 @@ You are working in a project that uses the **HotelFriend Design System v0.1.0**.
 - **Shadows:** pick from the 7 documented (`default`, `subtle`, `wrapper`, `card`, `modal`, `outline`, `hover`). No bespoke shadows.
 - **Pagination active state:** subtle gray `bg: #E4E8EF; color: #252F4A` — NOT primary blue. Use `.hf-pagination__item.is-active`.
 - **Components:** check `components.html` (open in browser, search anchors `#buttons`, `#modal`, etc.) for an existing equivalent before writing new component code. Reuse beats duplicate.
+- **Accessibility (required markup — the DS is CSS-only, so the ARIA + JS behavior is yours; WCAG 2.1 AA floor):** Modal/Drawer = `role="dialog"` + `aria-modal` + labelled title + focus trap + Escape. Tabs = `role="tablist/tab/tabpanel"` + `aria-selected` + arrow keys. Dropdown = `role="menu/menuitem"` + arrow keys + Escape + focus return. Switch = native checkbox (or `role="switch"`) + label. Checkbox/radio = native inputs. Icon-only buttons = `aria-label`. Pagination = `<nav aria-label="Pagination">`. Toasts = `aria-live="polite"` region. Tables = `<th scope>`. Never strip the shipped `:focus-visible` outlines.
 # Workflow
-1. Open `docs/portable-design/UI_DESIGN.md` whenever starting a UI task.
-2. Open `docs/portable-design/components.html` in a browser to verify visual decisions.
-3. Reuse `.hf-*` primitives from `pre-built/components.css` before creating new ones.
-4. For interactive elements, mirror states declared in `states-canonical.json` (default + hover + focus + disabled + loading).
-5. If a token is missing for what the user asks, propose adding one in `tokens.figma.json` rather than hard-coding.
+1. Open `node_modules/@hotelfriendag/design-tokens/UI_DESIGN.md` whenever starting a UI task.
+2. Open `node_modules/@hotelfriendag/design-tokens/components.html` in a browser (or https://unpkg.com/@hotelfriendag/design-tokens/components.html) to verify visual decisions.
+3. Reuse `.hf-*` primitives from `@hotelfriendag/design-tokens/components.css` before creating new ones.
+4. For interactive elements, mirror states declared in `node_modules/@hotelfriendag/design-tokens/states-canonical.json` (default + hover + focus + disabled + loading).
+5. If a token is missing for what the user asks, propose adding one in `tokens.figma.json` (design-system repo) rather than hard-coding.
 # Anti-patterns to refuse
-- Hard-coded hex colors not in `tokens.css`.
+- Hard-coded hex colors not in `@hotelfriendag/design-tokens/tokens.css`.
 - Tailwind utility-only components for things that have primitives (e.g. building a modal with raw `<div class="fixed inset-0 bg-black/40">` instead of using `.hf-modal`).
 - One-off shadows / radii / paddings outside the documented scale.
 - Mixing icon sets within a single screen (Lucide + FA + Heroicons).
 - Pagination with `bg-hf-primary text-white` active state (it's subtle gray — use `.hf-pagination__item.is-active`).
 - Native checkboxes with `accent-color` (use `.hf-check`).
 - Alerts with left-border accent (portal uses TOP 3px accent bar — use `.hf-alert`).
-- Copying patterns from `portal-audit.html` (legacy archival snapshot — NOT canonical).
+- Copying patterns from `portal-audit.html` (`node_modules/@hotelfriendag/design-tokens/portal-audit.html`) — legacy archival snapshot, NOT canonical.
 - Skipping component states (always provide hover / focus / disabled at minimum).
 When unsure, prefer asking the user over inventing.

package/ai-rules/github-copilot-instructions.md CHANGED Viewed

@@ -2,13 +2,13 @@
 > Drop this file at `.github/copilot-instructions.md`. Copilot reads it for repository-wide context.
-This project uses the **HotelFriend Design System v0.1.0**. Canonical visual reference: `docs/portable-design/components.html` (open in browser). Token bindings: `pre-built/tailwind.css` (v4, recommended) or `pre-built/tokens.css` (vanilla). Component primitives: `pre-built/components.css`. Narrative SSOT: `docs/portable-design/UI_DESIGN.md`.
+This project uses the **HotelFriend Design System** (@hotelfriendag/design-tokens — version per the installed package, see CHANGELOG.md). Canonical visual reference: `node_modules/@hotelfriendag/design-tokens/components.html` (open in browser, or https://unpkg.com/@hotelfriendag/design-tokens/components.html). Token bindings: `@hotelfriendag/design-tokens/tailwind.css` (v4, recommended) or `@hotelfriendag/design-tokens/tokens.css` (vanilla). Component primitives: `@hotelfriendag/design-tokens/components.css`. Narrative SSOT: `node_modules/@hotelfriendag/design-tokens/UI_DESIGN.md`.
 ## Hard rules — never violate
 1. **Colors:** use only tokens. Brand accent `#24AFE8` (`var(--color-hf-accent)` / Tailwind `bg-hf-accent`). Status colors via `var(--color-hf-status-{success|warning|error|info})`. Cancellation reasons share `.status-cancel`. Never hard-code other hex codes.
 2. **Status badges:** use `.hf-pill .status-{domain}-{state}` (rules in `status.css`). Color/background come from a semantic slot `var(--color-hf-status-{role})` / `-bg` (15% alpha); the domain→role map is in `status-map.json`. Never invent new status colors.
-3. **Component primitives — reuse, never rebuild:** Use `.hf-btn`, `.hf-input` / `.hf-textarea` / `.hf-select`, `.hf-switch`, `.hf-form-field`, `.hf-card`, `.hf-drawer`, `.hf-modal`, `.hf-alert`, `.hf-pagination`, `.hf-dropdown-menu`, `.hf-tab`, `.hf-pill`, `.hf-check`, `.hf-radio`, `.hf-toast` from `pre-built/components.css` BEFORE writing new component CSS.
+3. **Component primitives — reuse, never rebuild:** Use `.hf-btn`, `.hf-input` / `.hf-textarea` / `.hf-select`, `.hf-switch`, `.hf-form-field`, `.hf-card`, `.hf-drawer`, `.hf-modal`, `.hf-alert`, `.hf-pagination`, `.hf-dropdown-menu`, `.hf-tab`, `.hf-pill`, `.hf-check`, `.hf-radio`, `.hf-toast` (`--success` / `--error` / `--warn` / `--info`), `.hf-table`, `.hf-empty` (`--compact` / `--row`), invalid state `[aria-invalid="true"]` / `.hf-input--error` from `@hotelfriendag/design-tokens/components.css` BEFORE writing new component CSS.
 4. **Typography:** Roboto only. Sizes from scale: 11 / 13 / 14 / 15 / 16 / 18 / 20 / 24 / 26 / 30 px. Weights: 400 / 500 / 600. Line-heights: 1.2 (headings), 1.5 (body), 1 (chips).
 5. **Spacing:** multiples of 4 only. Default section gap 20 px. Never write 7 / 13 / 18 px.
 6. **Border radius:** `6px` (buttons/inputs/modals/alerts), `8px` (pagination items), `9px` (dropdowns/toasts), `12px` (large cards), `99px` (pill-rounded). No intermediate values.
@@ -17,6 +17,17 @@ This project uses the **HotelFriend Design System v0.1.0**. Canonical visual ref
 9. **Pagination active state:** subtle gray (`bg: #E4E8EF; color: #252F4A`) — NOT primary blue. Use `.hf-pagination__item.is-active`.
 10. **Components:** check `components.html` (open in browser, search anchors `#buttons`, `#modal`, etc.) for an existing equivalent before writing new component code.
+## Accessibility — required markup
+The design system is **CSS-only**, so the ARIA wiring and JS behavior (focus trap, arrow keys, Escape, focus return, `aria-live`) are **yours to supply**. WCAG 2.1 **AA is the floor**.
+- **Modal / Drawer:** `role="dialog"` + `aria-modal="true"` + labelled title + focus trap + Escape-to-close.
+- **Tabs:** `role="tablist"` / `tab` / `tabpanel` + `aria-selected` + arrow-key navigation.
+- **Dropdown:** `role="menu"` / `menuitem` + arrow keys + Escape + focus return to the trigger.
+- **Switch:** native `<input type="checkbox">` (or `role="switch"`) + `<label>`. **Checkbox / radio:** native inputs.
+- **Icon-only buttons:** `aria-label`. **Pagination:** `<nav aria-label="Pagination">`. **Toasts:** `aria-live="polite"` region. **Tables:** `<th scope>`.
+- Keep the shipped `:focus-visible` outlines; don't rely on placeholder text for required info (its contrast is intentionally below AA).
 ## When generating UI code
 - **Button classes:** `.hf-btn` + variant — `.hf-btn--primary`, `.hf-btn--outline-primary`, `.hf-btn--outline-default`, `.hf-btn--cancel`, `.hf-btn--danger`; sizes `.hf-btn--sm`, `.hf-btn--icon` (compact portal-only variants like reset-filters / icon-square can be layered with Tailwind utilities until promoted)
@@ -25,12 +36,12 @@ This project uses the **HotelFriend Design System v0.1.0**. Canonical visual ref
 - **Navigation:** `.hf-tab` + `--sm` + `__count`, `.hf-pill-tabs` + `.hf-pill-tab`, `.hf-pagination` + `__item/__ellipsis`, `.hf-dropdown-menu` + `__header/__item/__item-icon/__shortcut/__divider` (+ `__item--danger`)
 - **Status:** `.hf-pill .status-{domain}-{state}` + modifiers (`--striped`, `--dd`, `.is-active`, `min-w-*`)
 - **Loading:** `.skeleton` for shimmer, `.hf-spin` for spinner
-- Every interactive element needs: default + `:hover` + `:focus-visible` + `:disabled` states at minimum. See `states-canonical.json`.
+- Every interactive element needs: default + `:hover` + `:focus-visible` + `:disabled` states at minimum. See `node_modules/@hotelfriendag/design-tokens/states-canonical.json`.
 ## Forbidden patterns
-- Hard-coded hex colors not in `pre-built/tokens.css`.
-- Building modals/alerts/dropdowns/pagination from scratch when `pre-built/components.css` has primitives.
+- Hard-coded hex colors not in `@hotelfriendag/design-tokens/tokens.css`.
+- Building modals/alerts/dropdowns/pagination from scratch when `@hotelfriendag/design-tokens/components.css` has primitives.
 - Tailwind utility classes for component chrome — only use them for layout (flex/grid/spacing).
 - Border-radius outside `6 / 8 / 9 / 12 / 99`.
 - Spacing values outside the 4-multiple scale.
@@ -39,7 +50,7 @@ This project uses the **HotelFriend Design System v0.1.0**. Canonical visual ref
 - Pagination active state with primary blue (use subtle gray).
 - Native checkboxes with `accent-color` (use `.hf-check`).
 - Left-border alerts (portal uses top accent bar — use `.hf-alert`).
-- Copying patterns from `portal-audit.html` (archival snapshot, NOT canonical).
+- Copying patterns from `portal-audit.html` (`node_modules/@hotelfriendag/design-tokens/portal-audit.html`) — archival snapshot, NOT canonical.
 - Skipping component states.
-When unsure, mirror an example from `components.html`.
+When unsure, mirror an example from `node_modules/@hotelfriendag/design-tokens/components.html` (or https://unpkg.com/@hotelfriendag/design-tokens/components.html).

package/ai-rules/system-prompt-compact.md CHANGED Viewed

@@ -27,17 +27,23 @@ Shadows: default `0 1px 8px rgba(0,0,0,.1)` · subtle `0 2px 4px rgba(0,0,0,.05)
 **Dropdown** — `.hf-dropdown-menu` 9 r shadow `0 1px 10px rgba(0,0,0,.1)` · `__header` (uppercase 11px) · `__item` 14/normal hover `#F5F5F5` · `__item-icon` · `__shortcut` right-aligned · `__divider` · `.is-active` primary-tint · `__item--danger` (legacy flat `.hf-dropdown-{header|item|divider}` still alias)
 **Modal** — `.hf-modal` 6 r border `1px rgba(72,91,120,.15)` shadow `0 2px 4px rgba(72,91,120,.18)` · `__header` bottom border / `__footer` NO top border · sizes sm 420 / md 500 / lg 720 / xl 960
 **Alerts** — `.hf-alert` white bg + 3px top accent bar + 26×26 squared icon · variants `--success/--info/--warn/--error` · modifiers `--tinted/--banner/--compact`
-**Toast** — `.hf-toast` 9 r modal-shadow · `__icon` 20×20 · floating bottom-right
+**Toast** — `.hf-toast` 9 r modal-shadow · `__icon` 20×20 · floating bottom-right · variants `--success` / `--error` / `--warn` / `--info`
+**Table** — `.hf-table` semantic token–driven table chrome
+**Empty state** — `.hf-empty` centered empty-state block · `--compact` (inline within a card) · `--row` (inline row in a table)
+**Invalid input** — `[aria-invalid="true"]` / `.hf-input--error` on `.hf-input` / `.hf-textarea` / `.hf-select` (red border + ring)
 **Pagination** — `.hf-pagination__item` 34×34 8 r · active SUBTLE GRAY `bg: #E4E8EF` `color: #252F4A` (NOT primary blue!) · hover `bg: #F1F3F6`
 **Skeleton/spinner** — `.skeleton` shimmer 1.4 s · `.hf-spin` rotate
 **Icons** — Lucide preferred (inline SVG `<use>`) · Font Awesome 4 legacy (avoid in new code)
+## Accessibility — required markup (DS is CSS-only; ARIA + JS behavior are YOUR job)
+WCAG 2.1 AA floor. Modal/Drawer: `role="dialog"` + `aria-modal` + labelled title + focus trap + Escape. Tabs: `role="tablist/tab/tabpanel"` + `aria-selected` + arrow keys. Dropdown: `role="menu/menuitem"` + arrow keys + Escape + focus return. Switch: native checkbox (or `role="switch"`) + label. Checkbox/radio: native inputs. Icon-only buttons: `aria-label`. Pagination: `<nav aria-label="Pagination">`. Toasts: `aria-live="polite"` region. Tables: `<th scope>`. Keep the shipped `:focus-visible` outlines.
 ## Hard Rules
-1. Never hard-code hex — use tokens (`--color-primary`, `$colorPrimaryDefault`, Tailwind class `primary`).
-2. Use `.hf-*` primitives BEFORE writing new component CSS — check `pre-built/components.css` first.
+1. Never hard-code hex — use tokens (`--color-hf-accent`, `$colorAccent`, Tailwind class `bg-hf-accent`).
+2. Use `.hf-*` primitives BEFORE writing new component CSS — check `@hotelfriendag/design-tokens/components.css` first. Wave-1 additions: `.hf-table`, `.hf-empty` (`--compact` / `--row`), `.hf-toast--success/--error/--warn/--info`, invalid state `[aria-invalid="true"]` / `.hf-input--error`.
 3. Every interactive element must have hover, focus, and disabled states.
 4. No mixed icon sets in one component.
-5. Status badge colors via `--color-badge-{domain}-{state}-color` / `--color-badge-{domain}-{state}-bg` — never raw hex.
+5. Status badge colors via `.hf-pill .status-{domain}-{state}` (rules in `status.css`). Color/bg come from `var(--color-hf-status-{role})` / `-bg` (15% alpha); the domain→role map is in `status-map.json`. Never invent badge colors or use raw hex — the old per-domain badge token namespace was removed in Phase 1B.
 6. Canonical primary is `#24AFE8`. The portal renders `#26ADE4` (`$light__Blue` SCSS) — visually identical but tokens use canonical.
 7. Pagination active is subtle gray, NOT primary blue (`.hf-pagination__item.is-active`).
 8. Alerts use TOP 3px accent bar (`.hf-alert`), NOT left-border. Modal footer has NO top border.