@hotelfriendag/design-tokens 0.3.0

package/ai-rules/CLAUDE.md

@@ -0,0 +1,80 @@
+# Project AI Instructions
+
+> Drop this file into the **root** of a new project (e.g. `/CLAUDE.md` next to `package.json`). Claude Code, Cursor (`@CLAUDE.md`), and Aider (`/add CLAUDE.md`) read it automatically. Replace `{{PROJECT_NAME}}` placeholders.
+
+## 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.
+
+## 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.
+
+## 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.
+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.
+7. **Transitions:** Default `200ms ease-in-out`. Use this for hover, focus, state changes — not `0.3s` or arbitrary timings.
+8. **Shadows:** Pick from the 7 documented shadows in `UI_DESIGN.md` §3 Border-radius & Shadows: `--shadow-default`, `--shadow-subtle`, `--shadow-wrapper`, `--shadow-card`, `--shadow-modal`, `--shadow-outline`, `--shadow-hover`. Don't roll one-off `box-shadow` declarations.
+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.
+
+## 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.
+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:
+
+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.
+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).
+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`)
+- ❌ 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)`
+- ❌ Bypassing the status-pill system with bespoke `<span class="bg-green-100 text-green-800">Active</span>`
+- ❌ Building a modal from scratch with `<div class="fixed inset-0 bg-black/40">…</div>` instead of using `.hf-modal`
+- ❌ Building an alert with `border-l-4 border-red` instead of `.hf-alert.hf-alert--error` (the portal alert has TOP border, not left)
+- ❌ 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
+
+## When in doubt
+
+Ask the user. Better to pause for 5 seconds than ship a one-off color that drifts the design system.
+
+---
+
+**System version:** Design System v0.1.0
+**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.

package/ai-rules/cursorrules.template

@@ -0,0 +1,39 @@
+# 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`.
+
+# 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.
+- **Status badges:** use `.hf-pill .status-{domain}-{state}`. Color via `var(--color-badge-{domain}-{state}-color)`, bg via `var(--color-badge-{domain}-{state}-bg)`. Never invent new status colors.
+- **Component primitives — reuse, never rebuild:** Use `.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`, `__icon`). Variants with `--` (`--success`, `--banner`, `--compact`). State classes with `.is-*` (`.is-active`, `.is-disabled`).
+- **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).
+- **Transitions:** `200ms ease-in-out`.
+- **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.
+
+# 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.
+
+# Anti-patterns to refuse
+
+- Hard-coded hex colors not in `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).
+- 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

@@ -0,0 +1,45 @@
+# GitHub Copilot instructions
+
+> 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`.
+
+## 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}`. Color via `var(--color-badge-{domain}-{state}-color)`, background via `var(--color-badge-{domain}-{state}-bg)` (15% alpha). Never invent new status colors.
+3. **Component primitives — reuse, never rebuild:** Use `.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.
+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.
+7. **Transitions:** `200ms ease-in-out` for all hover/focus/state changes. No `0.3s`, no arbitrary timings.
+8. **Shadows:** pick from documented set (`default`, `subtle`, `wrapper`, `card`, `modal`, `outline`, `hover`). No bespoke `box-shadow`.
+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.
+
+## When generating UI code
+
+- **Button classes:** `.btn-primary`, `.btn-hf-outline-primary`, `.btn-cancel`, `.btn-danger`, `.btn-reset-filters` + compact variants (`btn-b-gray`, `btn-add-grey`, `btn-edit-sm`, `btn-trash`, `btn-copy-sm`, `btn-plus-sm`)
+- **Form primitives:** `.form-control` (inputs), `.hf-check` (checkbox), `.hf-radio` (radio), toggle pattern
+- **Containers:** `.hf-modal` + `__header/__title/__body/__footer/__close`, `.hf-alert` + variants/modifiers, `.hf-toast`, bordered card `<div class="bg-white rounded-lg border border-border p-5">`, elevated card with `shadow-subtle`
+- **Navigation:** `.hf-tab` + `--sm` + `__count`, `.hf-pill-tabs` + `.hf-pill-tab`, `.hf-pagination` + `__item/__ellipsis`, `.hf-dropdown-menu` + `__header/__item/__shortcut/__icon/__divider`
+- **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`.
+
+## 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.
+- 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.
+- Bespoke `box-shadow` declarations.
+- Mixing icon libraries (Lucide + Font Awesome + Heroicons) in the same screen.
+- 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).
+- Skipping component states.
+
+When unsure, mirror an example from `components.html`.

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

@@ -0,0 +1,43 @@
+# HotelFriend Design System — AI Reference (compact)
+
+## Colors
+Primary: `#24AFE8` · Hover: `#149AD1` · Light tint: `#E9F6FC`
+Neutrals: page-bg `#FBFBFC` · section-bg `#F6F7FB` · very-light `#F1F3F6` · border `#D1D6DD` · text `#2B2B2B` · secondary-text `#4B5675` · placeholder `#AEBCCF`
+Status: success `#59B59D` · warning `#FFBD5A` · error `#EA6565` · coral `#F87921` · violet `#5761D8` · cancellation/deleted `#7F8FA4`
+Status badges use `--color-badge-{domain}-{state}-color` + `--color-badge-{domain}-{state}-bg` (15% alpha). Domains: booking · order · fd (frontDesk) · clean (roomItem.cleaning). Cancellation reasons all share `.status-cancel`.
+
+## Typography
+Font: Roboto · Sizes: 11 / 13 / 14 / 15 / 16 / 18 / 20 / 24 / 26 / 30 px · Weights: 400 / 500 / 600
+Body: 14px/400 · Buttons: 15px/600 · Tabs (large): 16px/500 · Tabs (small/sub-filter): 15px/500 · Modal title: 18px/600 · Page title: 26px/600
+
+## Spacing & Shape
+Spacing: multiples of 4 px (4 / 8 / 12 / 16 / 20 / 24 / 30 / 32)
+Radius: 6 px (buttons/inputs/modals/alerts) · 8 px (pagination items) · 9 px (dropdowns/toasts/pill-tabs) · 12 px (large cards) · 99 px (rounded pills only)
+Shadows: default `0 1px 8px rgba(0,0,0,.1)` · subtle `0 2px 4px rgba(0,0,0,.05)` (dashboard cards) · modal `0 6px 18px rgba(0,0,0,.1)` · outline `0 1px 2px rgba(72,91,120,.18)` · hover `0 2px 3px rgba(0,0,0,.06)`
+
+## Component primitives (`.hf-*`)
+
+**Buttons** — `.btn-primary` 40 h / 15px / 600 / `#24AFE8` · `.btn-cancel` white bg muted text · `.btn-danger` red bg · `.btn-outline-primary` 1px primary border · `.btn-reset-filters` 38 h `#EFF6FF` bg
+**Inputs** — `.form-control` 39 h / 6 r / placeholder `#AEBCCF` / focus border darkens to `#B2BAC4` (portal) or add `box-shadow: 0 0 0 2px rgba(36,175,232,.2)` for accessibility
+**Checkbox/Radio** — `.hf-check` / `.hf-radio` 18×18 · transparent + 1px `#DBDFE9` border · checked = filled `#26ADE4` + white tick or dot
+**Toggle** — 52×28 track · off `#DFDFDF` / on `#24AFE8` · thumb 20×20 white shadow `0 1px 6px rgba(0,0,0,.3)`
+**Cards** — bordered `bg-white rounded-lg border border-border p-5` (no shadow, most common) · elevated `bg-white rounded border-[rgba(72,91,120,.05)] shadow-subtle p-4` (dashboard KPIs)
+**Status pills** — `.hf-pill.status-{domain}-{state}` 6 r · 15% bg + 100% text + 1px border · modifiers: `.is-active` (transparent + inset ring) / `--striped` / `--dd` (chevron) / `min-w-[130/160/180px]`
+**Tabs** — `.hf-tab` 16/500 padding 22 15 / `--sm` 15/500 padding 10 15 · active `#24AFE8` + 3px bottom · `__count` badge inside · `.hf-pill-tabs > .hf-pill-tab` segmented (Day/Week/Month)
+**Dropdown** — `.hf-dropdown-menu` 9 r shadow `0 1px 10px rgba(0,0,0,.1)` · `__header` (uppercase 11px) · `__item` 14/normal hover `#F5F5F5` · `__shortcut` right-aligned · `.is-active` primary-tint · `.danger`
+**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
+**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)
+
+## 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.
+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.
+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.