@hotelfriendag/design-tokens 0.3.0 → 0.3.2

package/README.md

@@ -367,8 +367,14 @@ import { tokens } from '@hotelfriendag/design-tokens/tokens.ts';
 ### Publishing (maintainer)
 
 Releases are tag-triggered via `.github/workflows/release.yml` — push a `v*` tag
-and the workflow builds, validates, then `npm publish`-es to npmjs.com using
-the `NPM_TOKEN` repository secret. No manual `npm publish` step required.
+and the workflow builds, validates, then `npm publish`-es to npmjs.com via
+**Trusted Publishing (OIDC)**. No `NPM_TOKEN` secret, no PATs: GitHub Actions
+mints a short-lived OIDC token that npm exchanges for publish credentials.
+
+`--provenance` is NOT used: npmjs rejects sigstore provenance from private
+source repositories, and this repo stays private (only the built artifact is
+public — see RFC-0001 for the rationale). The trade is a missing attestation
+badge on the npm page in exchange for keeping the source code private.
 
 ```bash
 # From the repo root, on main:
@@ -376,9 +382,19 @@ npm version patch                  # or minor / major → updates package.json,
 git push --follow-tags             # workflow runs on the pushed tag and publishes
 ```
 
-The `prepublishOnly` script re-runs the generator + validator so the published package is always self-consistent. If you need to publish manually from a local machine (bootstrap or hotfix), `pnpm publish` works the same way after `pnpm version <bump>` (you'll need to be logged in: `npm login` first).
+The `prepublishOnly` script re-runs the generator + validator so the published package is always self-consistent. If you need to publish manually from a local machine (hotfix), `npm publish` works the same way after `npm version <bump>` and `npm login` — but Trusted Publishing is the canonical path.
+
+The Trusted Publisher binding on npmjs (Package → Settings → Trusted publishing) is configured for:
+
+| Field | Value |
+|---|---|
+| Organization | `HotelFriendAG` |
+| Repository | `design-system` |
+| Workflow filename | `release.yml` |
+
+Changing the workflow filename, repo name, or org requires updating the npmjs binding before the next release will succeed.
 
-> Historical: versions `0.2.x` were briefly published to GitHub Packages while the registry decision was pending. `0.3.0+` is published exclusively to npmjs.com; consumers should install from there.
+> Historical: versions `0.2.x` were briefly published to GitHub Packages while the registry decision was pending. `0.3.0+` is published exclusively to npmjs.com; consumers should install from there. `0.3.0` itself was bootstrapped by a one-time manual publish from a maintainer's machine using a short-lived Granular Access Token (since Trusted Publishing requires the package to already exist on npm). The token was revoked immediately after; all subsequent versions use OIDC.
 
 ## Changelog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotelfriendag/design-tokens",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "HotelFriend Design System — portable bundle (tokens, components, AI rules). Three-tier model per RFC-0002.",
   "license": "MIT",
   "type": "commonjs",

package/README.uk.md

@@ -1,377 +0,0 @@
-# HotelFriend Design System
-
-Спільна дизайн-основа для всіх проєктів: токени, згенеровані файли під кожен стек (CSS / SCSS / TS / Tailwind v3 + v4 / shadcn), шар компонентів `.hf-*` та правила для AI-інструментів.
-
-> **Виокремлено 2026-05-25** із [`hotelfriend/backend-hf`](https://bitbucket.org/hotelfriend/backend-hf) (`docs/portable-design/`), щоб цей репозиторій став єдиним джерелом істини для решти проєктів HotelFriend.
->
-> **Статус:** RFC-0001 Фаза 1 завершена (семантична трирівнева модель + префіксація без колізій + CI-гейт на дрейф). Наступний крок — версійований npm-пакет (`@hotelfriend/design-tokens` через GitHub Packages). Повний чек-лист — у `RFC-0001-cross-project-design-system.md` §9.
-
-## Ієрархія файлів (читати в цьому порядку)
-
-```
-portable-design/
-│
-├── components.html            ← ОСНОВНЕ · канонічний візуальний референс (відкрити у браузері)
-├── UI_DESIGN.md               ← НАРАТИВ · обґрунтування, анатомія, рішення (AI читає це першим)
-├── tokens.figma.json          ← ТОКЕНИ · атомарний експорт Tokens Studio → живить Figma + генератори
-│
-├── pre-built/                 ← ЗГЕНЕРОВАНІ · підставляєте у свій білд-пайплайн
-│   ├── tailwind.css               · Tailwind v4 @theme-блок (рекомендовано)
-│   ├── tailwind.preset.js         · Tailwind v3 preset (легасі)
-│   ├── tokens.css                 · звичайні CSS custom properties
-│   ├── _tokens.scss               · SCSS-змінні
-│   ├── tokens.ts                  · TypeScript const
-│   ├── shadcn-tokens.css          · контракт shadcn/ui
-│   └── components.css             · примітиви `.hf-*` (витяг із components.html)
-│
-├── states-canonical.json      ← курований набір інтерактивних станів (використовуйте цей)
-├── states.json                ← сирий експорт із порталу (160 КБ — краще брати states-canonical.json)
-├── generate-tokens.cjs        ← Node-скрипт (без залежностей) — перетворює токени на Tailwind/CSS/SCSS/TS/shadcn
-│
-├── ai-rules/                  ← покладіть ОДИН файл у корінь нового проєкту
-│   ├── CLAUDE.md                  · для Claude Code (підхоплюється автоматично)
-│   ├── cursorrules.template       · перейменуйте на .cursorrules
-│   ├── github-copilot-instructions.md · покласти в .github/copilot-instructions.md
-│   └── system-prompt-compact.md   · компактний промпт для ChatGPT/v0/Lovable
-│
-├── portal-audit.html          ← АРХІВ · знімок аудиту старого порталу (НЕ для нового коду)
-└── README.md                  ← ви тут (швидкий старт)
-```
-
-### Правило пріоритету — коли файли суперечать одне одному
-
-1. **`components.html`** — канон для **візуальних рішень** (кольори, розміри, анатомія)
-2. **`tokens.figma.json`** — канон для **значень токенів**. Після редагування — перегенеруйте `pre-built/*`
-3. **`UI_DESIGN.md`** — канон для **ЧОМУ було прийнято рішення** (історія, компроміси, нотатки про дрейф порталу)
-4. **`pre-built/*`** — **згенеровані**, руками не правити. Після зміни JSON запускайте `generate-tokens.cjs`
-5. **`portal-audit.html`** — **тільки архів**. Показує поточний вигляд легасі-порталу — корисно для трекінгу міграції, НЕ для нового UI
-
-Якщо `components.html` і `UI_DESIGN.md` суперечать одне одному — **виграє `components.html`**, а `UI_DESIGN.md` вважається застарілим.
-
-## Швидкий старт за 60 секунд
-
-```bash
-# 1. Скопіювати цю папку у новий проєкт (куди завгодно; рекомендуємо docs/)
-cp -r /path/to/portable-design ../new-project/docs/
-
-# 2. Підключити CSS у білд (оберіть ОДНЕ)
-#    Tailwind v4: @import pre-built/tailwind.css
-#    Vanilla CSS: підключити tokens.css + components.css
-#    SCSS:        @import _tokens.scss
-
-# 3. Підключити AI до правил системи (оберіть ОДНЕ)
-cp docs/portable-design/ai-rules/CLAUDE.md ../../CLAUDE.md            # Claude Code
-cp docs/portable-design/ai-rules/cursorrules.template ../../.cursorrules
-mkdir -p ../../.github && cp docs/portable-design/ai-rules/github-copilot-instructions.md ../../.github/copilot-instructions.md
-```
-
-## ⚠️ Інтеграція у наявний проєкт
-
-> **Статус:** ✅ Вирішено у Фазі 1A (RFC-0001 §4.2). Усі згенеровані токени мають префікс `hf-` ВСЕРЕДИНІ категорії (`--color-hf-*`, `--text-hf-*`, `--radius-hf-*`, `--spacing-hf-*`, `--font-hf-*`, `--shadow-hf-*`). Жоден не може зіткнутися з дефолтами Tailwind v4. Повний `@import` у наявному проєкті — безпечний.
-
-**Рекомендована конфігурація для будь-якого проєкту (новий чи наявний):**
-
-```css
-/* app/globals.css */
-@import "tailwindcss";
-@import "./docs/portable-design/pre-built/tailwind.css";    /* @theme — додає --color-hf-*, --text-hf-* тощо */
-@import "./docs/portable-design/pre-built/components.css";  /* примітиви .hf-* */
-
-/* Опційно: виключити демо-HTML із пакета зі сканування Tailwind,
-   щоб легасі-класи / bg-[#hex] із showcase не потрапили у ваш бандл. */
-@source not "./docs/portable-design/components.html";
-@source not "./docs/portable-design/portal-audit.html";
-```
-
-Що ви отримуєте:
-
-- `bg-hf-accent` (= `#24AFE8` — бренд) — `bg-blue-500` із Tailwind лишається дефолтним
-- `text-hf-base` (= 14px — основний текст) — `text-base` із Tailwind лишається 16px
-- `rounded-hf-sm` (= 6px) — `rounded-sm` із Tailwind лишається 2px
-- `shadow-hf-modal` (= тінь модалки порталу)
-- … тощо. Ваші наявні утиліти **не змінюються**.
-
-**Для проєктів, чиї інтеграційні скрипти просять "additive"-таргет за назвою**, `--target=tailwind-v4-additive` — явний alias для `--target=tailwind-v4`. Вихідний файл ідентичний — префікс зробив additive-фільтр непотрібним.
-
-```bash
-node generate-tokens.cjs --target=tailwind-v4-additive > pre-built/tailwind.additive.css
-# (байт-у-байт як --target=tailwind-v4)
-```
-
-## Сніпети під конкретні стеки
-
-### React + Tailwind v4 (рекомендовано, новий проєкт)
-
-```css
-/* app/globals.css */
-@import "tailwindcss";
-@import "./docs/portable-design/pre-built/tailwind.css";    /* @theme токени */
-@import "./docs/portable-design/pre-built/components.css";  /* примітиви .hf-* */
-```
-
-```jsx
-<button className="bg-hf-primary hover:bg-hf-primary-hover text-white h-10 px-5 rounded-hf text-hf-md font-semibold">
-  Зберегти
-</button>
-<span className="hf-pill status-booking-confirmed">Підтверджено</span>
-<div className="hf-modal max-w-[500px]">
-  <div className="hf-modal__header">
-    <h2 className="hf-modal__title">Редагувати гостя</h2>
-    <button className="hf-modal__close">✕</button>
-  </div>
-  <div className="hf-modal__body">…</div>
-  <div className="hf-modal__footer"><button>Скасувати</button><button>Зберегти</button></div>
-</div>
-```
-
-### React + Tailwind v3 (легасі)
-
-```js
-// tailwind.config.js
-const hfPreset = require('./docs/portable-design/pre-built/tailwind.preset.js');
-module.exports = {
-  presets: [hfPreset],
-  content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],
-};
-```
-
-```html
-<link rel="stylesheet" href="docs/portable-design/pre-built/components.css">
-```
-
-### Next.js + shadcn/ui
-
-Допишіть `pre-built/shadcn-tokens.css` у `app/globals.css`. Компоненти shadcn автоматично підхоплять `--primary`, `--background`, `--ring` тощо.
-
-### Vue 3 / Nuxt
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  css: [
-    '~/docs/portable-design/pre-built/tokens.css',
-    '~/docs/portable-design/pre-built/components.css',
-  ],
-});
-```
-
-У шаблонах використовуйте `var(--color-hf-accent)`, `var(--font-size-hf-base)` або `.hf-modal` / `.hf-pill .status-booking-confirmed`.
-
-### SCSS-стек (Yii / Laravel / WP)
-
-```scss
-// _app.scss
-@import 'docs/portable-design/pre-built/tokens';
-@import 'docs/portable-design/pre-built/components.css';
-
-.my-btn {
-  background: $colorPrimaryDefault;
-  height: $sizeBtnDefault;
-  border-radius: $borderRadiusSm;
-}
-```
-
-### TS / CSS-in-JS
-
-```ts
-import { tokens } from './docs/portable-design/pre-built/tokens';
-
-const Button = styled.button`
-  background: ${tokens.color.primary.default};
-  height: ${tokens.size.btnDefault};
-  border-radius: ${tokens.borderRadius.sm};
-`;
-```
-
-### Ванільний / статичний HTML
-
-```html
-<link rel="stylesheet" href="docs/portable-design/pre-built/tokens.css">
-<link rel="stylesheet" href="docs/portable-design/pre-built/components.css">
-
-<span class="hf-pill status-booking-confirmed">Підтверджено</span>
-<button class="hf-modal__close">✕</button>
-```
-
-## Примітиви компонентів у `components.css`
-
-| Клас | Анатомія | Дивись |
-|---|---|---|
-| `.hf-pill` + `.status-{domain}-{state}` | Статус-бейдж — радіус 6px, фон 15% + текст 100% + рамка 1px | components.html#status |
-| `.hf-tab` / `.hf-tab--sm` / `.hf-pill-tabs` | Таби з підкресленням та сегментовані | components.html#tabs |
-| `.hf-pagination` + `__item` / `__ellipsis` | Активний — стриманий сірий (НЕ primary!) — 34×34, радіус 8px | components.html#pagination |
-| `.hf-modal` + `__header/__title/__body/__footer/__close` | Радіус 6px, у футера немає верхньої рамки | components.html#modal |
-| `.hf-alert` + `--success/--info/--warn/--error` | Білий фон + 3px акцентна смуга зверху + квадратна іконка 26×26 | components.html#alerts |
-| `.hf-alert--tinted` / `--banner` / `--compact` | Модифікатори — тонований фон / на всю ширину / компактний у картці | components.html#alerts |
-| `.hf-toast` | Плаваюче сповіщення (правий нижній кут) — радіус 9px | components.html#alerts |
-| `.hf-check` / `.hf-radio` | Кастомні чекбокс та радіо — 18×18, активний — заливка primary | components.html#inputs |
-| `.hf-dropdown-menu` + `__item / __header / __shortcut / __icon / __divider` | Дропдаун з радіусом 9px та тінню `0 1px 10px rgba(0,0,0,.1)` | components.html#dropdown |
-| `.skeleton` + `.hf-spin` | Примітиви станів завантаження (шимер + обертання) | components.html#empty |
-
-## Як цим користується AI
-
-Після того як ви поклали один із файлів `ai-rules/*` у корінь нового проєкту:
-
-1. **Claude Code / Cursor / Copilot** автоматично додають його до кожного чату. Агент знає:
-   - канонічну палітру (primary `#24AFE8`, кольори статусів, нейтральні)
-   - типографіку (Roboto, розміри 11/13/14/15/16/18/20/22/26/30, ваги 400/500/600)
-   - шкалу відступів (кратно 4)
-   - шкалу радіусів (6/8/9/12/99)
-   - набір тіней (default/subtle/wrapper/card/modal/outline/hover)
-   - бібліотеку компонентів (`.hf-modal`, `.hf-alert`, `.hf-pill`, `.hf-tab`, `.hf-pagination`, `.hf-check`, `.hf-dropdown-menu` тощо)
-   - жорсткі правила ("ніколи не зашивати hex", "завжди робити hover/focus/disabled", "не мішати іконкові набори")
-
-2. **Візуальний референс для нових проєктів:** відкрийте `components.html` у браузері — це канон, де відрендерені всі патерни `.hf-*`.
-
-3. **Для чат-AI** (ChatGPT, v0, Lovable): вставте `ai-rules/system-prompt-compact.md` або JSON-довідник токенів із `UI_DESIGN.md` §9 як system prompt перед запитом UI-завдання.
-
-## Оновлення згенерованих файлів
-
-Коли змінюється `tokens.figma.json`, перегенеруйте:
-
-```bash
-cd docs/portable-design
-node generate-tokens.cjs --target=tailwind-v4 > pre-built/tailwind.css        # v4 (рекомендовано)
-node generate-tokens.cjs --target=tailwind    > pre-built/tailwind.preset.js  # v3 (легасі)
-node generate-tokens.cjs --target=css         > pre-built/tokens.css
-node generate-tokens.cjs --target=scss        > pre-built/_tokens.scss
-node generate-tokens.cjs --target=ts          > pre-built/tokens.ts
-node generate-tokens.cjs --target=shadcn      > pre-built/shadcn-tokens.css
-```
-
-> `pre-built/components.css` поки **не генерується** — він вручну витягнутий із `components.html`. Якщо ви змінюєте блок `<style type="text/tailwindcss">` / `@layer components` у `components.html`, синхронізуйте витягнутий файл вручну. Заголовок `pre-built/components.css` містить координати джерела.
-
-Або вбудуйте регенерацію в `package.json`:
-
-```json
-{
-  "scripts": {
-    "tokens:build:v4": "node docs/portable-design/generate-tokens.cjs --target=tailwind-v4 > tailwind.css",
-    "tokens:build:v3": "node docs/portable-design/generate-tokens.cjs --target=tailwind    > tailwind.preset.js",
-    "prebuild": "npm run tokens:build:v3 && npm run tokens:build:v4"
-  }
-}
-```
-
-## Чек-ліст валідації
-
-Після перенесення у новий проєкт перевірте:
-
-- [ ] `cat CLAUDE.md` (або `.cursorrules`) показує правила дизайн-системи.
-- [ ] `node docs/portable-design/generate-tokens.cjs --target=css` відпрацьовує чисто і дає стабільний вивід.
-- [ ] AI-агент на питання "який primary color?" відповідає `#24AFE8`.
-- [ ] Перша згенерована AI кнопка відповідає `.btn-primary` (40px / 15px / 600 / `#24AFE8` / радіус 6px).
-- [ ] Бейджі статусів резолвляться через токени `--status-{domain}-{state}-color`.
-- [ ] `.hf-modal`, `.hf-alert`, `.hf-pagination` рендеряться коректно, коли підвантажений `pre-built/components.css`.
-
-## Що НЕ переноситься
-
-Ці файли у батьківському `docs/` — **специфічні для порталу HotelFriend** (легасі-аудит / детект дрейфу), копіювати їх НЕ треба:
-
-- `docs/migration-plan.md` — черга прибирання старого SCSS (тільки портал на Yii)
-- `docs/design-tokens-audit.md` — звіт про дрейф
-- `docs/ui-elements-catalog.*` — спостережені компоненти у порталі
-- `docs/icon-audit.*` — карта міграції FA→Lucide
-- `docs/component-anatomy.json` — обміри легасі-модалок
-- `scratch/` — Playwright-воркери, що сканують портал
-
-Вони лежать у вихідному репо для господарських потреб; новому проєкту вони не потрібні.
-
-`portal-audit.html` всередині цього пакета — єдиний легасі-артефакт, що подорожує разом із portable-папкою — залиште його як історичний референс і для трекінгу міграції. Новий код **ніколи** не повинен копіювати патерни з `portal-audit.html`.
-
----
-
-## Детект дрейфу та інтеграція з CI
-
-### Pre-commit hook (рекомендовано для будь-якого проєкту, що чіпає цей пакет)
-
-```bash
-# З husky (рекомендовано)
-pnpm add -D husky
-pnpm husky init
-cp docs/portable-design/scripts/pre-commit.sh .husky/pre-commit
-chmod +x .husky/pre-commit
-
-# Без husky (сирий git-hook)
-cp docs/portable-design/scripts/pre-commit.sh .git/hooks/pre-commit
-chmod +x .git/hooks/pre-commit
-```
-
-Хук запускає `validate-tokens.cjs`, коли в staging є будь-які файли з tokens / pre-built / docs / components.html. Падає на дрейфі. Мовчить на успіху.
-
-### Конфіг Stylelint (рекомендовано для проєктів-споживачів)
-
-Сумісний Stylelint-конфіг, який забороняє сирий hex / іменовані кольори / літеральні `box-shadow`:
-
-```js
-// .stylelintrc.cjs
-module.exports = {
-  extends: [
-    'stylelint-config-standard',
-    './node_modules/@hotelfriend/design-tokens/pre-built/stylelint-design-system.cjs'
-    // — або, якщо підключено через копіювання папки:
-    // './docs/portable-design/pre-built/stylelint-design-system.cjs'
-  ],
-  overrides: [
-    // У згенерованих файлах hex допустимий (fallback-и, примітиви) — opt-out
-    { files: ['**/pre-built/*.css'], rules: { 'color-no-hex': null } },
-  ],
-};
-```
-
-### Самостійний валідатор (одноразова перевірка у CI)
-
-```bash
-cd docs/portable-design
-node scripts/validate-tokens.cjs
-# ✓ validate-tokens: all checks passed
-#   168 CSS variables defined, all var() refs resolve, no bare hex.
-```
-
-Використовуйте у CI поруч із лінтом та тестами. Виходить із ненульовим кодом, якщо:
-1. `var(--*)` посилається на CSS-змінну, яка ніде не визначена
-2. У `components.css` / `status.css` є сирий hex (поза коментарями та fallback-ами `var()`; `#fff`/`#000` дозволені)
-3. У код-блоці документації згадано токен, якого нема в `pre-built/*`
-
-## NPM-пакет (приватний реєстр)
-
-Пакет публікується як `@hotelfriend/design-tokens` у приватний реєстр GitHub Packages:
-
-```bash
-# У проєкті-споживачі:
-echo "@hotelfriend:registry=https://npm.pkg.github.com" >> .npmrc
-pnpm add @hotelfriend/design-tokens
-```
-
-Імпорт під свій стек:
-
-```css
-/* CSS / Tailwind v4 */
-@import "@hotelfriend/design-tokens/tailwind.css";
-@import "@hotelfriend/design-tokens/components.css";
-@import "@hotelfriend/design-tokens/status.css";
-```
-
-```ts
-// TypeScript
-import { tokens } from '@hotelfriend/design-tokens/tokens.ts';
-```
-
-```scss
-// SCSS
-@import '@hotelfriend/design-tokens/_tokens';
-```
-
-### Публікація (для мейнтейнера)
-
-```bash
-cd docs/portable-design
-pnpm version patch                 # або minor / major
-pnpm publish                       # запускає prepublishOnly → build + validate
-```
-
-`prepublishOnly` перезбирає та валідує, тож опублікований пакет завжди узгоджений.
-
----
-
-Зібрано на основі HotelFriend Design System v0.1.0 — JSON-довідник токенів див. у `UI_DESIGN.md` §9, канонічний візуальний референс — у `components.html`. Англомовна версія цього файлу — [`README.md`](README.md), повний журнал фаз і змін — там же.