@hotelfriendag/design-tokens 0.3.0

package/UI_DESIGN.md

@@ -0,0 +1,608 @@
+# UI Design System (HotelFriend Style)
+
+> **Version:** 0.1.0 · **Last reconciled:** 2026-05-20 · **Branch:** `feature/ui-design-docs`
+> **Maintainer:** Frontend platform team · **Changelog:** `docs/CHANGELOG.md`
+
+Reference for UI work (Figma, CSS frameworks, hand-rolled markup). This document serves as the foundational design system for applications adhering to the brand style, **designed to be framework-agnostic**. AI agents must use this as the Single Source of Truth (SSOT) to generate UI in any tech stack (Tailwind, SCSS, CSS Modules, etc.).
+
+## Precedence rule (when artefacts disagree)
+
+The design system ships in multiple places. They will drift over time. Use this priority chain to decide which source wins:
+
+1. **`components.html`** — **canonical visual reference**. Open in a browser. If a button in this doc looks different than in components.html, components.html wins. This is the file designers and devs use to verify visual decisions.
+2. **`UI_DESIGN.md`** (this file) — **canonical narrative SSOT**. Explains WHY decisions were made, anatomy, decision logs. Where components.html shows the rendered result, this doc explains the rationale.
+3. **`tokens.figma.json`** — atomic token export. Token-by-token values that drive `pre-built/*` generators and the Tokens Studio plugin in Figma. If it disagrees with components.html, regenerate.
+4. **`pre-built/*`** (tailwind.css / tokens.css / _tokens.scss / tokens.ts / shadcn-tokens.css / components.css) — **generated**, never hand-edit. Re-run `generate-tokens.cjs` after JSON changes. `components.css` is hand-extracted from components.html.
+5. **`web/css/scss/common/_variables.scss`** — runtime SCSS variables. The compiled CSS is what the browser actually paints in the legacy portal. **Live drift is logged in `docs/design-tokens-audit.md`** — when SCSS disagrees with this file, file an SCSS-only PR to fix the SCSS, never weaken this doc to match.
+6. **`portal-audit.html`** — **archival** snapshot of the legacy portal UI. NOT a source of truth for new code. Useful for migration tracking only.
+7. **`docs/ui-elements-catalog.json` / `.md`** — observational snapshot of what shipped. **Never used as truth** — only used for drift detection.
+
+Concrete rules:
+- A button class that exists in `_variables.scss` but not in this doc is **legacy** until documented.
+- A token in `tokens.figma.json` that is missing from this doc is a **bug** — either remove it from Figma export or document it here.
+- If you observe a legacy class in `ui-elements-catalog.md` or `portal-audit.html`, do not propagate it. Map it via `docs/migration-plan.md` instead.
+
+> **Reality check (2026-05-07).** Cross-referenced against live values extracted from production CSS via `scratch/extract-all-pages.js`. See companion artefacts:
+> - `docs/design-tokens.json` — every token observed live, with occurrence counts
+> - `docs/design-tokens-audit.md` — discrepancies between this doc and the actual CSS
+> - `docs/ui-elements-catalog.json` / `.md` — full inventory of components per page
+> - `docs/tokens.figma.json` — Tokens Studio export (importable into Figma)
+>
+> Where this document and reality disagree, items marked **⚠ live** show the actual portal value; items marked **canonical** are the design intent we are migrating toward. New UI must follow **canonical**, but be aware legacy CSS still ships the live values.
+
+---
+
+## 1. Brand & Palette
+
+### Primary
+| Token            | Hex       | Usage                                               |
+| ---------------- | --------- | --------------------------------------------------- |
+| `--primary-color` (canonical) | `#24AFE8` | Links, primary buttons, focus, active tab underline |
+| `$primary_hover` | `#149AD1` | Primary button hover                                |
+| `$light_primary` | `#E9F6FC` | Active state bg, light tint                         |
+| `$primary_tint_bg` | `#EFF6FF` | "Reset Filters" button bg (live) |
+| `$primary_tint_border` | `rgba(27, 132, 255, 0.2)` | "Reset Filters" button border (live) |
+
+
+*Note: `$st-arctic` is a legacy alias that equals `$primary`.*
+
+### Neutrals
+| Token                   | Hex       | Usage                              |
+| ----------------------- | --------- | ---------------------------------- |
+| `$white`                | `#fff`    | Surfaces, panels                   |
+| `$light__Grey`          | `#FBFBFC` | Page background top                |
+| `$bg_accent`            | `#F6F7FB` | Section backgrounds                |
+| `$very_light_gray`      | `#F1F3F6` | Header bars, hover, inputs bg      |
+| `$light_blue_gray`      | `#E4E8EF` | Default border, dividers, disabled |
+| `$border_color_primary` | `#D1D6DD` | Stronger border (buttons, chips)   |
+| `$border_color_hover`   | `#B2BAC4` | Border on hover                    |
+
+### Text
+| Token                   | Hex       | Usage                            |
+| ----------------------- | --------- | -------------------------------- |
+| `$text_color_primary`   | `#2B2B2B` | Body text, headings              |
+| `$text_color_secondary` | `#4B5675` | Secondary text, subdued labels   |
+| `$text_color_tertiary`  | `#4A5565` | Captions                         |
+| `$placeholder_color`    | `#AEBCCF` | Input placeholder + disabled input text — portal `$dark__Grey` ⚠ canonical 2026-05 (was `#99A1B7`) |
+| `$steel__blue`          | `#485b78` | Tab labels, secondary navigation |
+| `$useful`               | `#7E8EA6` | Helper text on dark              |
+
+> **Decision log:** Placeholder color changed from `#99A1B7` → `#AEBCCF` on 2026-05-20 to match the live portal's `$dark__Grey` value used for input placeholders + disabled input text. The legacy `#99A1B7` is preserved in `tokens.figma.json` as `text.placeholderLegacy` for any backwards-compatible needs.
+
+### Status (semantic)
+| Token                     | Hex       | Meaning           |
+| ------------------------- | --------- | ----------------- |
+| `$st-mint` / `$green`     | `#59B59D` | Success, new      |
+| `$st-buttermilk`          | `#FFBD5A` | Warning / waiting |
+| `$st-peach` / `$st-coral` | `#F87921` | Booking / coral   |
+| `$st-rouge` / `$red`      | `#EA6565` | Error / delete    |
+| `$st-violet`              | `#5761D8` | Special / accent  |
+| `--status-frontDesk-out-of-order-color` ⚠ live | `#FFC900` | Out-of-order rooms (frontDesk) |
+| `--status-booking-check-in-color` ⚠ live | `#5B7A02` | Check-in olive |
+| `--status-booking-due-out-color` ⚠ live | `#A55505` | Due-out brown |
+| `--status-*-canceled-by-*-color` ⚠ live | `#7F8FA4` | Canceled-by-* uniform muted blue-gray |
+
+#### Status badge token system (live)
+
+The portal ships a fully tokenized badge palette for every domain entity (booking, order, orderItem, frontDesk, roomItem cleaning). Each status has a `*-color` (text/border) and a `*-bg-color` (15% alpha tint of the same color). Pattern:
+
+```css
+--status-{domain}-{status}-color:    rgb(R, G, B);
+--status-{domain}-{status}-bg-color: rgba(R, G, B, 0.15);
+```
+
+| Domain | Statuses |
+| -- | -- |
+| booking | new, offer, confirmed, check-in, check-out, canceled-by-hotel, canceled-by-guest, canceled-by-hf, no-show, due-in, due-out, deleted |
+| order, orderItem | waiting, confirmed, completed, in-progress, canceled-by-hotel, canceled-by-guest, canceled-by-pos, action-required, deleted |
+| frontDesk | quota-free, quota-busy, out-of-order |
+| roomItem.cleaning | clean, cleaning, dirty, out-of-service, inspected |
+
+Use these tokens directly in markup (`status-hf status-order-confirmed`) — never hard-code badge colors.
+
+**Dark Mode Policy:** Dark mode is natively **not supported** by default. Applications should stick to the light palette above unless explicitly instructed otherwise.
+
+---
+
+## 2. Typography
+
+- **Family:** Roboto (`font-family: 'Roboto', sans-serif;`)
+- **Weights:** 400 (Body), 500 (Medium/Tabs/Labels), 600 (Semibold/Headings)
+- **Line-height:** `1.5` for body text, `1.2` for headings, `1` for strictly constrained UI elements (like chips).
+- **Letter-spacing:** Standard `0`. For uppercase sub-labels, use `0.05em`.
+- **Truncation:** Long text in table cells or tight containers must use standard truncation (`white-space: nowrap; overflow: hidden; text-overflow: ellipsis;`).
+
+| Token             | Size | Line-height | Usage                              |
+| ----------------- | ---- | ----------- | ---------------------------------- |
+| `$pagetitle`      | 26px | 1.2         | Top page title                     |
+| `$btn_size`       | 15px | 1.5         | Primary buttons                    |
+| `$general_size`   | 14px | 1.5         | Body, labels                       |
+| `$select__size`   | 14px | 1.5         | Selects, inputs                    |
+| `$grid_head_size` | 13px | 1.5         | Grid headers, chips, small buttons |
+| `$label_size`     | 11px | 1.2         | Tag labels, uppercase captions     |
+
+**Extended scale (live, not yet tokenized):**
+
+| Size | Where it shows up |
+| ---- | -- |
+| 12px | Helper text, tooltip body, debug bar (rare in product UI) |
+| 16px | Sub-headings, modal titles, larger body in info-blocks |
+| 17px | Single-step dialog headings (rare) |
+| 18px | Info-block titles (`$info-title`), section headers in cards |
+| 20px | Section heading inside dashboards |
+| 22px / 24px / 25px | Marketing-style headings (rare in admin) |
+| 30px | Hero numbers (e.g. dashboard stat cards) |
+
+> ⚠ The base scale documented above (26/15/14/13/11) is canonical — but production CSS uses **all of {11–18, 20, 22, 24, 25, 26, 30}**. When generating UI, prefer the canonical sizes. Do not introduce new sizes without an explicit token.
+
+---
+
+## 3. Layout, Skeleton & Spacing
+
+- **Base unit:** 4 px increments. Common values: 4, 8, 12, 16, 20, 24, 32.
+- **Default spacing:** `20px` (between sections).
+- **App Shell Anatomy:**
+  - **Sidebar:** Width `215px` (expanded), `80px` (collapsed).
+  - **Header:** Height `~60px` (varies by context).
+  - **Main Content Max-Width:** `1440px`.
+- **Breakpoints & Behavior:**
+  - `> 1024px` (Desktop): Sidebar fixed left.
+  - `< 1024px` (Tablet): Sidebar auto-collapses to 80px.
+  - `< 720px` (Mobile): Sidebar becomes a hidden off-canvas drawer. Padding shrinks.
+
+### Page Layout Anatomy (Portal Standard)
+When building standard list/grid pages (like Guests, Rooms, Hotels), the page is assembled using these basic blocks in this order:
+1. **Title Block** (`.hf-title-block`): Contains the page title, navigation tabs, and main call-to-action buttons (e.g., "Add Hotel").
+2. **Filters Bar** (`.hf-filters`): Contains search inputs, Select2 dropdowns, and a "Reset" button.
+3. **Data Grid** (`table`): The main content area. In legacy code, often uses responsive classes like `.mobile-grid__body` and `.mobile-grid-unit`.
+4. **Pagination / Footer Grid** (`.footergrid`): Located below the table, containing a "per page" selector (`.footergrid-left-block`) and summary/pagination controls (`.footergrid-right-block`).
+
+### Z-Index Scale (Factual Implementation)
+*Note: These are the exact z-indexes used in the live project.*
+- `z-sidebar`: 1000
+- `z-dropdowns / right-sidebar / tooltips`: 1001
+- `z-datepicker`: 3000
+- `z-sticky-topbars (search, notifications)`: 4000
+- `z-modal-backdrop (.fade)`: 10050
+- `z-modal-dialog / alert-box`: 10051
+- `z-preloader`: 99999
+
+### Border-radius & Shadows
+| Token                    | Value | Where                                    |
+| ------------------------ | ----- | ---------------------------------------- |
+| `$br-sm`                 | 6 px  | Buttons, inputs, checkboxes              |
+| `$br-xl`                 | 9 px  | Dropdowns, alerts                        |
+| `$br-xxl`                | 12 px | Cards, Grids, modals, main wrappers      |
+| `$br-pill`               | 99px  | Status badges (Inline chips)             |
+
+| Token              | Value                            | Where             |
+| ------------------ | -------------------------------- | ----------------- |
+| `--shadow-default` | `0 1px 8px rgba(0,0,0,.1)`       | Default elevation — buttons, sticky bars |
+| `--shadow-subtle`  | `0 2px 4px rgba(0,0,0,.05)`      | **Portal `.dashboard-card`** — very faint elevation on KPI tiles |
+| `--shadow-wrapper` | `0 3px 4px rgba(0,0,0,.03)`      | Card frame (legacy) |
+| `--shadow-card`    | `0 12px 24px rgba(26,26,30,.06)` | Large elevated surface — main reference cards |
+| `--shadow-modal`   | `0 6px 18px rgba(0,0,0,.10)`     | **`.hf-modal`, `.hf-toast`, dropdowns, popovers** — primary floating UI |
+| `--shadow-outline` | `0 1px 2px rgba(72,91,120,.18)`  | Outline button micro-elevation |
+| `--shadow-hover`   | `0 2px 3px rgba(0,0,0,.06)`      | Hover lift        |
+
+> **Decision log (2026-05-20):** Added `--shadow-subtle` (portal `.dashboard-card` exact extraction), `--shadow-modal` (formerly `--tooltip-shadow`, renamed since modal usage is primary), and `--shadow-outline` (portal outline-default button shadow). All shadows now documented match either an extracted portal value or a canonical design decision — no more `⚠ NOT IN LIVE CSS` orphans.
+
+> **Portal-exact modal shadow:** Note that the portal's `.modal-content` actually uses `0 2px 4px 0 rgba(72,91,120,0.18)` (a steel-blue tinted shadow) — not the more conventional `--shadow-modal`. The `.hf-modal` component in `components.html` and `pre-built/components.css` replicates this exact portal value.
+
+---
+
+## 3.1 Live extracted state values
+
+For 17 component classes the actual `:hover` / `:focus` / `:active` / `:disabled` declarations have been pulled from compiled CSS. Authoritative export: **`docs/component-states.json`**.
+
+Key rules (per-class, what the live CSS actually sets — not the canonical narrative):
+
+| Class | `:hover` | `:focus` | `:active` | `:disabled` / `[disabled]` |
+| -- | -- | -- | -- | -- |
+| `.btn-primary` | `bg: $primary_hover` | `outline: 2px solid $primary; outline-offset: 2px` | `transform: scale(0.98)` | inherited from `.btn` |
+| `.btn-hf-outline-primary` | border + text become `$primary` | outline ring | — | — |
+| `.btn-cancel` | `bg: $border-light` | outline ring | — | — |
+| `.btn-delete` | `filter: brightness(0.9)` | outline ring `$error` | — | — |
+| `.btn-reset-filters` | `bg: #DDEEFE` | — | — | `.disabled { opacity: 0.6; pointer-events: none }` |
+| `.form-control` | `border-color: $border_color_hover` | `border-color: $primary; box-shadow: 0 0 0 2px rgba(38,173,228,0.2)` | — | `[disabled] { bg: #f7f9fa; color: #7E8CA0; cursor: not-allowed }` |
+| `.dropdown-toggle` | underline removed; primary tint | outline ring | `bg: $primary; color: white` | — |
+| `.dropdown-menu .dropdown-item:hover` | `bg: $bg-muted` | — | — | `.disabled { opacity: 0.5; cursor: not-allowed }` |
+| `.pagination .page` | `bg: $bg-muted` | — | active class adds `bg: $primary; color: white; box-shadow: $hover_shadow` | `.disabled` opacity 0.5 |
+| `.select2-selection` | `border-color: $border_color_hover` | `border-color: $primary; box-shadow: 0 0 0 2px rgba(38,173,228,0.2)` | — | — |
+
+⚠ Use `docs/component-states.json` for the full set when generating Figma component variants.
+
+---
+
+## 4. Universal Component States & Interaction
+
+- **Motion (canonical):** `transition: all 200ms ease-in-out;` for hover, focus, and state changes.
+- ⚠ **Motion (live):** the codebase actually uses `transition: 0.3s` (35×) and `transition: 0.2s` (15×) most often. Pure `0.2s ease-in-out` shows up only 4 times in compiled CSS. New code should follow the canonical 200ms ease-in-out.
+- **Hover:** Slightly darken backgrounds (`$primary_hover`) or add border color (`$primary` on outline buttons). Add `$hover_shadow` to cards.
+- **Active/Pressed:** Scale down slightly (`transform: scale(0.98)`) or darken further.
+- **Focus Ring (Accessibility):** `outline: 2px solid #24AFE8; outline-offset: 2px;`. Never remove outlines without providing a visual alternative.
+- **Disabled:** `opacity: 0.6; cursor: not-allowed; pointer-events: none;`. Backgrounds turn to `$light_blue_gray` for solid elements.
+- **Loading:** Inline spinner icon (`Lucide`/`Heroicons`) rotating, alongside text. Disable the element while loading.
+- **Tap Targets:** Minimum clickable area for mobile is `44x44px`.
+
+---
+
+## 5. Components Anatomy
+
+### Cards / Panels
+```css
+background: #ffffff;
+border: 1px solid #d1d6dd;
+border-radius: 12px;
+padding: 20px;
+box-shadow: 0 3px 4px rgba(0, 0, 0, 0.03);
+```
+*Rule clarification:* Cards feature **both** a subtle border and a very soft shadow to provide structured definition without floating too high.
+
+### Buttons
+
+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 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.           |
+| **Outline neutral** | `.btn` (no modifier)   | White bg, `#AEBCCF` border, `#50627E` text. 38px h, 15/600. Used for split toggles like `No App / With App`. |
+| **Reset Filters** | `.btn-reset-filters`     | Light blue tint bg `#EFF6FF`, primary text `#24AFE8`, 1px border `rgba(27,132,255,0.2)`. 38px h, 14/500. |
+| **Filters trigger** | `.filters-btn`         | Same as Reset Filters but with funnel icon.                   |
+| **Cancel**  | `.btn.btn-cancel`              | `#F1F3F6` bg, `#4B5675` text. Hover: `#E4E8EF` bg.            |
+| **Delete**  | `.btn.btn-delete`              | Solid `#EA6565` bg, white text. Hover: darken 10%.            |
+| **Save** (form footer) | `.btn.btn-primary`      | Same as Primary, lives in form `<footer>`.                    |
+| **Show inline link** | `.btn-text-blue.p0`     | Plain text `#24AFE8`, 14/400, no bg. Used as table-cell mini-actions. |
+| **Icon-only** (Summernote toolbar) | `.btn.btn-default.btn-sm.note-btn` | 32×32, white bg, gray text `#333`. Used in WYSIWYG toolbar. |
+
+**Sizing:** Default 40px / 15/600 / radius 6px / padding `10px 20px`. SM 32px / 15/600 / padding `7px 14px`. Search-inline 38px / padding `10px 13px`. Reset Filters 38px / 14/500.
+
+### Status Badges (Pills)
+Use `$br-pill` (`99px`) for full rounded edges.
+- **Soft (Default):** Background is 15% opacity of the semantic color. Text is 100% semantic color. Example Success: `bg: #EAF7F4, text: #59B59D`.
+- **Outline:** `bg: #fff, border: 1px solid #D1D6DD, text: #4B5675`.
+
+### Modal / Dialog
+
+**Canonical (target):**
+- **Backdrop:** Fixed inset 0, `bg: rgba(0,0,0,0.4)`, `z-index: 10050`.
+- **Container:** Centered, `bg: #fff`, `border-radius: 12px`, `box-shadow: $card_shadow`, `z-index: 10051`. Max-width typically `500px` (sm) or `800px` (lg).
+- **Header:** `padding: 20px`, bottom border `1px solid #E4E8EF`. Includes Title + Close (X) button.
+- **Body:** `padding: 20px`.
+- **Footer:** `padding: 20px`, top border `1px solid #E4E8EF`, right-aligned action buttons (Cancel + Primary).
+
+**⚠ Live (drift, see `docs/component-anatomy.json`):**
+- Default modal width is **600px** (legacy Bootstrap), `modal-medium` is **400px**.
+- `.modal-content` has `border-radius: 6px` (not 12px) and `border: 1px solid rgba(72,91,120,0.15)`.
+- `.modal-content` shadow is `0 2px 4px rgba(72,91,120,0.18)` (not `$card_shadow`).
+- `.modal-header` / `.modal-body` padding is **15px** (not 20px). Some headers also have `pb0` modifier (no bottom padding).
+- Close button is a Bootstrap 3 `.close` element: 17×17, font-weight 700, font-size 21px (an "×" character).
+
+Migration row: `docs/migration-plan.md` G1.
+
+### Tabs
+- **Container:** Flex row, `border-bottom: 1px solid #d1d6dd`.
+- **Item:** `padding: 22px 15px`, `font-size: 15px`, `font-weight: 500`, `color: #50627e`.
+- **Active state:** `color: #24AFE8`, active visual border is often handled via pseudo-elements or inner `span` borders.
+
+### Toast / Notification
+- Position: Fixed top-right, spaced `20px` from edges.
+- Anatomy: `bg: #fff`, left accent border (`4px solid {status_color}`), padding `16px`, `box-shadow: $card_shadow`.
+
+### Dropdown Menus
+- **Trigger:** Button or Icon (cursor pointer).
+- **Menu Container:** `position: absolute`, `bg: #fff`, `border-radius: 9px` (`$br-xl`), `box-shadow: $card_shadow`, `z-index: 1001`. Minimum width typically `160px`.
+- **Menu Item:** `padding: 8px 16px`, `font-size: 14px`, `color: #4B5675`.
+- **Item Hover/Active:** `bg: #F1F3F6` (`$very_light_gray`), text changes to `#2B2B2B`.
+
+### Tooltips
+- **Container:** `bg: #2B2B2B`, `color: #fff`, `font-size: 12px`, `padding: 6px 10px`, `border-radius: 4px`, `z-index: 1001`, `box-shadow: $hover_shadow`.
+- **Arrow:** Small 4px triangle pointing to the trigger element.
+- **Timing:** Delay of `200ms` before appearing to prevent flickering on fast mouse movements.
+
+### Pagination
+- **Layout:** Flex row, `gap: 4px`. Align right by default.
+- **Item (Page Number):** `width: 32px`, `height: 32px`, flex centered, `border-radius: 6px` (`$br-sm`), `font-size: 13px`, `color: #4B5675`, `cursor: pointer`.
+- **Item Hover:** `bg: #F1F3F6`.
+- **Item Active:** `bg: #24AFE8` (`$primary`), `color: #fff`, `box-shadow: $hover_shadow`.
+- **Disabled State:** `opacity: 0.5`, `cursor: not-allowed` (e.g., for Prev/Next buttons when at limits).
+
+### Switch (Toggle)
+- **Container:** `.bootstrap-switch` or custom `.switch-box`. Often wrapped in `.form-group`.
+- **Visuals:** Usually composed of a primary-colored active state (`bg: #24AFE8`) and default gray inactive state.
+
+### Progress Bar
+- **Container:** `.hf-progress.progress-rounded` with track `.hf-progress-track-gray`.
+- **Value Bar:** `.progress-bar` with specific semantic colors (e.g., `.progress-bar-primary`, `.progress-bar-success`).
+- **Width:** Controlled via CSS variable `--progress-value` inline (e.g., `style=\"--progress-value: 75%\"`).
+- **Sizes:** Modifiers available like `.hf-progress-sm`, `.hf-progress-lg`.
+
+### Custom Inputs
+- **Quantity Input:** `.hf-input-quantity` wrapper containing `button.btn-minus_gray`, `input[type=\"number\"]`, and `button.btn-plus_gray`.
+- **Toggle Switcher Input:** `.input-toggle_wrap` containing an input and a `.toggle-box` that visually toggles between two units (e.g., `%` or `UAH`).
+
+### Title Block / Action Bars
+- **Container:** `.hf-title-block` or `.x-row.align-items-center`.
+- **Elements:** Back button (`.btn-hf-outline-default`), title (`.hf-title-block-h3`), tabs container, and right-aligned action buttons (`.hf-title-block-right`).
+
+### Info Blocks
+- **Container:** `.hf-info-block` (usually `margin-bottom: 20px`).
+- **Visuals:** An alert-style block with an icon, `18px / 600` title, and `15px` description text.
+
+### Copy Text Widget
+- **Container:** `.copy-widget` with `.copy-widget__content`.
+- **Text:** `.text-ellipsis.nowrap`.
+- **Action:** A button with data-attribute `data-toggle="copy-to-clipboard"`.
+
+### Select2 / Dropdowns
+- **Container:** `.select2-container--bootstrap`.
+- **Elements:** Integrates via Vue 3 or Kartik wrappers.
+
+### Empty State / Skeleton
+- **Empty State:** Centered layout. Large subdued icon (`color: #99A1B7`, size `48px`), Title (`16px / 600`), Description (`14px / 400`), optional Primary Action Button.
+- **Skeleton:** `bg: #E4E8EF` with a subtle shimmer animation (`linear-gradient` moving left to right).
+
+### Switch (Bootstrap-Switch)
+- **Library:** Bootstrap-switch (jQuery), wrapping classes `.bootstrap-switch.bootstrap-switch-animate.bootstrap-switch-wrapper`.
+- **Live sizes:** 68×32 (settings list), 72×32 (SEO pages list), 83×32 (form fields).
+- **States:** `.bootstrap-switch-on` (primary bg) / `.bootstrap-switch-off` (gray bg).
+- **Recommendation:** All new switches must use this widget — do not roll custom toggles.
+
+### Rich-text editor (Summernote)
+- **Library:** Summernote 0.8.18 — pulled from `cdn.jsdelivr.net` in `/portal/seo-pages/edit`.
+- **Toolbar:** Container `.note-toolbar.panel-heading`, button row `.note-btn-group`. Each tool button is `.btn.btn-default.btn-sm.note-btn` 32×32.
+- **Variants in toolbar:** `.note-btn-bold`, `.note-btn-italic`, `.note-btn-underline`, dropdown variants `.dropdown-toggle.note-btn` (with `#50627E` text) plus context-aware menus (`.dropdown-fontsize`, `.note-table`).
+- **Editable area:** `.note-editable`, white bg, padding 10px, no border-radius (by default).
+
+### Date / Time picker (Krajee + Bootstrap-Timepicker)
+- **Date input:** `input.form-control.krajee-datepicker` — 38px h, 6px radius, `#D1D6DD` border, calendar icon left.
+- **Time picker:** `.bootstrap-timepicker-widget.dropdown-menu` — opens as dropdown with hour/minute scrollers, white bg, `--tooltip-shadow`.
+- **Date range:** `input.custom-form-control.custom-form-daterange` — single field that opens a side-by-side calendar (krajee).
+
+### File input (Krajee FileInput)
+- **Wrapper:** `.kv-fileinput-caption` — visually styled "fake" input with attached browse button.
+- **Browse button:** `.btn.btn-primary` next to caption, often labeled "Browse...".
+- **Preview area:** `.file-preview` (160px tall, gray bg, dashed border) appears below input after selection.
+- **Recommendation:** Always use Krajee variant — never raw `<input type="file">`.
+
+### Sidebar (Portal nav)
+- **Container:** `<aside class="menu">` (Vue 3 component). Width 215px expanded, 80px collapsed (< 1024px).
+- **Item:** Anchor (`.menu-item`), padding `12px 5px 10px 31px` (icon + label), text `#2B2B2B` 14/400.
+- **Active item:** `.menu-item.active` adds `#24AFE8` left border + tinted bg.
+- **Mobile button:** `.menu-mobBtn` (hamburger), top-left, 32×32.
+
+---
+
+## 5.1 Component Primitives — `.hf-*` classes
+
+These are the **canonical component classes** shipped in `pre-built/components.css` and rendered in `components.html`. Use them as drop-in primitives in new projects. Each entry below has: anatomy summary, key tokens, link to the rendered demo, and notes on portal-exact vs adapted decisions.
+
+> Open `components.html` in a browser for the live rendered versions. Anchors like `#buttons` / `#inputs` correspond to the section IDs.
+
+### `.hf-pill` — Status badges
+- **Anatomy:** `display: inline-flex; padding: 6px 20px; border-radius: 6px; font: 14px/500; border: 1px solid currentColor`
+- **Colors:** 15% bg + 100% text + 1px border in the same `--status-{domain}-{state}-color` token
+- **Modifiers:**
+  - `.is-active` — selected filter chip (transparent bg + `box-shadow: inset 0 0 0 1px currentColor`)
+  - `--striped` — diagonal repeating-linear-gradient pattern (out-of-service rooms)
+  - `--dd` — adds chevron + cursor (clickable status switcher in tables)
+  - `min-w-[130px/160px/180px]` — Tailwind utilities for table column alignment
+- **Reference:** `components.html#status` · **Portal source:** `_status.scss .status-hf` · **Decision:** 1:1 portal match
+
+### `.hf-tab` / `.hf-tab--sm` / `.hf-pill-tabs` — Tabs
+- **Large** (page nav): padding `22px 15px`, 16px/500, active = 3px bottom border `#24AFE8`
+- **Small** (`--sm`, sub-filter Today/All): padding `10px 15px`, 15px/500
+- **Pill tabs** (segmented control): inline group with section bg, active = white + subtle shadow
+- **Count badge** (`.hf-tab__count`): 22min×18 pill inside tab — 11px/600
+- **Reference:** `components.html#tabs` · **Portal source:** `ul.nav-tabs` Bootstrap 3 · **Decision:** 1:1 portal match for both sizes
+
+### `.hf-pagination` — Pagination
+- **Anatomy:** 34×34 items, 8px radius, 14px/400, ink-steel `#485B78` inactive
+- **Active state:** `bg: #E4E8EF; color: #252F4A` (subtle gray — **NOT primary blue!** This is portal-exact behavior, easy to miss)
+- **Hover (inactive):** `bg: #F1F3F6; color: #2B2B2B`
+- **Disabled:** `color: #AEBCCF; pointer-events: none`
+- **Reference:** `components.html#pagination` · **Portal source:** Bootstrap `.pagination` · **Decision:** 1:1 portal match (the subtle gray active is what the portal actually ships — many other systems would use primary)
+
+### `.hf-modal` — Modal dialog
+- **Anatomy:** 6px radius, `border: 1px solid rgba(72,91,120,.15)`, `box-shadow: 0 2px 4px 0 rgba(72,91,120,.18)`, white bg
+- **Header:** padding 20px, bottom border 1px `#E4E8EF`, title 18px/600, close button 32×32 right-aligned
+- **Body:** padding 20px
+- **Footer:** padding 20px, **NO top border** (portal-exact), right-aligned actions with gap 12px
+- **Sizes:** `max-w-[420px]` (sm/confirm), `max-w-[500px]` (md/form, default), `max-w-[720px]` (lg/multi-col), `max-w-[960px]` (xl/drill-down)
+- **Variants:** `--with-footer-border` (opt-in separator)
+- **Reference:** `components.html#modal` · **Portal source:** `.modal-content` in `_custom.scss` · **Decision:** 1:1 portal match for chrome/shadow/border-radius. **Adapted:** title is 18px/600 (modern) — portal uses 15px/900 uppercase which is dated. Document if your project needs portal-legacy title styling.
+
+### `.hf-alert` — In-page alerts
+- **Anatomy:** white bg + 1px `rgba(72,91,120,.15)` border + `0 2px 4px rgba(72,91,120,.07)` shadow + **3px top accent bar** + 26×26 squared icon (filled accent color)
+- **Title:** 18px/500 `#2B2B2B` · **Description:** 15px/normal `#50627E`
+- **Variants** (set accent color via currentColor):
+  - `--success` (#59B59D) · `--info` (#24AFE8) · `--warn` (#FFBD5A) · `--error` (#EA6565)
+- **Modifiers:**
+  - `--tinted` — accent-coloured bg instead of white (6–10% opacity)
+  - `--banner` — full-width strip, accent bg, white text, semi-transparent icon container (use for page-level critical messages like "contract expired")
+  - `--compact` — 13px text, smaller padding (for inside cards/forms)
+- **Reference:** `components.html#alerts` · **Portal source:** `_widget.scss .alert` (with SVG data-URI icons) · **Decision:** 1:1 portal match for chrome. **Adapted:** uses inline SVG `<use>` instead of CSS-background data-URI (cleaner for theming).
+
+### `.hf-toast` — Floating notification
+- **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
+- **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.
+
+### `.hf-check` / `.hf-radio` — Checkbox & Radio
+- **Anatomy:** 18×18, 1px solid `#DBDFE9` border, transparent bg
+- **Checkbox:** 6px radius. Checked: filled `#26ADE4` bg, border same. After: white 5×10 ::after with bottom+right border, rotated 45deg.
+- **Radio:** 9999px radius. Checked: filled `#26ADE4`. After: 6×6 white centered dot.
+- **States:**
+  - Hover (not disabled): border becomes `#26ADE4`
+  - Disabled: opacity 0.5, cursor not-allowed
+  - Checked+disabled: bg/border `rgba(38,173,228,.5)`, opacity 1
+- **Reference:** `components.html#inputs` · **Portal source:** `_custom.scss .mt-checkbox-outline` · **Decision:** 1:1 portal match (replaces unstable `accent-color` native styling)
+
+### `.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:**
+  - `__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)
+  - `__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
+  - `.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).
+
+### `.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.
+- **Reference:** `components.html#empty` · **Decision:** New primitives — portal has no equivalent.
+
+---
+
+## 6. Forms
+
+- **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`).
+  2. Required marker (Red `*` next to label).
+  3. Input Control.
+  4. Helper / Error Text (`12px`, margin-top `4px`).
+- **Error State:** Input border becomes `#EA6565`. Error text appears below input in `#EA6565`.
+- **Validation Timing:** Prefer `onBlur` for inline validation, and `onSubmit` for overall form validation.
+- **Multi-column Forms (Grid Layout):**
+  - Use CSS Grid for robust layout: `.form-grid { display: grid; grid-template-columns: 1fr; gap: 20px; }`.
+  - For screens `> 768px` (Tablet+): Switch to 2 columns `grid-template-columns: repeat(2, 1fr)`.
+  - **Full-width fields:** Use `grid-column: 1 / -1;` for textareas, wysiwyg editors, or long descriptions inside a 2-column grid.
+  - **Sections:** Separate large forms into logical blocks using `border-bottom: 1px solid #E4E8EF` or wrapping them in `<fieldset>` with an `<legend>` or heading.
+
+---
+
+## 7. Tables / Grids
+
+- **Header:** `bg: #F1F3F6`, `13px / 500`, text `#4B5675`, `padding: 12px 16px`. Often sticky (`position: sticky; top: 0; z-index: 200`).
+  - **Sorting:** Header label acts as a button (`cursor: pointer`). Add an up/down arrow icon. On hover, text color changes to `#2B2B2B`. Active sorted column uses `#24AFE8` for the icon.
+- **Rows:** `padding: 12px 16px`, bottom border `1px solid #E4E8EF`.
+  - **Checkbox Columns:** Width fixed to `40px-48px`, centered content. Used for bulk actions. Checkbox `border-radius: 6px`.
+- **Hover:** Row background changes to `#FBFBFC`.
+- **Empty State:** A single row `<tr>` with `colspan="100%"`. The cell contains the standard Empty State component (Subdued icon 48px, Title 16px, Text 14px, centered).
+- **Pagination:** Bottom right aligned. Display "Showing X-Y of Z" on the left, and standard prev/next buttons on the right.
+
+---
+
+## 8. Canonical Page Example
+
+When requested to generate a standard "List View" or dashboard page, AI agents should strictly follow this architectural composition:
+
+```html
+<!-- App Shell Context assumed -->
+<div class="page-container p-20 max-w-[1440px] mx-auto">
+  
+  <!-- Page Header -->
+  <header class="flex justify-between items-center mb-20">
+    <div>
+      <!-- Optional Breadcrumbs: 12px, #4B5675 -->
+      <h1 class="text-[26px] font-semibold text-[#2B2B2B] leading-tight">Page Title</h1>
+    </div>
+    <div class="flex gap-12">
+      <!-- Secondary Action -->
+      <button class="btn-outline">Export</button>
+      <!-- Primary Action -->
+      <button class="btn-primary">+ Add New</button>
+    </div>
+  </header>
+
+  <!-- Filters / Tool bar -->
+  <div class="flex justify-between items-center bg-white p-16 border border-[#d1d6dd] rounded-t-[12px] border-b-0">
+    <div class="flex gap-16">
+       <!-- Search Input, Select filters -->
+       <input type="text" placeholder="Search..." class="form-control" />
+    </div>
+  </div>
+
+  <!-- Main Content / Table -->
+  <div class="bg-white border border-[#d1d6dd] rounded-b-[12px] shadow-[0_3px_4px_rgba(0,0,0,0.03)] overflow-hidden">
+    <table class="w-full text-left text-[14px]">
+      <thead class="bg-[#F1F3F6] text-[#4B5675] text-[13px] font-medium border-b border-[#E4E8EF]">
+        <tr>
+          <th class="p-16">Name</th>
+          <th class="p-16">Status</th>
+          <th class="p-16 text-right">Actions</th>
+        </tr>
+      </thead>
+      <tbody>
+        <!-- Data Rows or Empty State -->
+        <tr class="border-b border-[#E4E8EF] hover:bg-[#FBFBFC] transition-colors">
+          <td class="p-16 text-[#2B2B2B]">John Doe</td>
+          <td class="p-16"><span class="badge-soft-success">Active</span></td>
+          <td class="p-16 text-right">...</td>
+        </tr>
+      </tbody>
+    </table>
+    
+    <!-- Pagination Footer -->
+    <div class="p-16 border-t border-[#E4E8EF] flex justify-between items-center text-[13px] text-[#4B5675]">
+      <span>Showing 1-10 of 42</span>
+      <!-- Pagination Controls -->
+    </div>
+  </div>
+
+</div>
+```
+
+---
+
+## 8.1 Companion: live token export
+
+For machine-readable tokens see `docs/tokens.figma.json` (Tokens Studio format, importable directly in Figma → "Tokens Studio" plugin → Sync → File → Drop the JSON). Includes:
+
+- `colors/primary/*` — primary palette
+- `colors/neutrals/*` — surfaces, borders, backgrounds
+- `colors/text/*` — text hierarchy
+- `colors/status/*` — semantic colors
+- `colors/badges/*/{color,bg}` — full status-badge tokens for booking, order, frontDesk, roomItem
+- `typography/*` — composite tokens (size + weight + lineHeight)
+- `radius/*`, `shadow/*`, `spacing/*` — atomic tokens
+
+---
+
+## 9. JSON Token Reference
+
+```json
+{
+  "colors": {
+    "primary": "#24AFE8",
+    "primaryHover": "#149AD1",
+    "white": "#FFFFFF",
+    "bgPage": "#FBFBFC",
+    "bgAccent": "#F6F7FB",
+    "bgMuted": "#F1F3F6",
+    "borderLight": "#E4E8EF",
+    "border": "#D1D6DD",
+    "textPrimary": "#2B2B2B",
+    "textSecondary": "#4B5675",
+    "placeholder": "#99A1B7",
+    "status": {
+      "success": "#59B59D",
+      "warning": "#FFBD5A",
+      "error": "#EA6565"
+    }
+  },
+  "radius": {
+    "sm": "6px",
+    "xl": "9px",
+    "xxl": "12px",
+    "pill": "99px"
+  },
+  "shadows": {
+    "card": "0 12px 24px rgba(26,26,30,.06)",
+    "wrapper": "0 3px 4px rgba(0,0,0,.03)"
+  }
+}
+```