@kommon-lab/tokens 0.1.5 → 0.1.7

package/README.md

@@ -116,6 +116,34 @@ var(--font-body-m-bold-font-weight)
 > **Responsive:** `display` and `title` tokens are defined mobile-first and automatically
 > override at `min-width: 768px`. No extra configuration needed.
 
+## Custom fonts
+
+Most brands use **Figtree** (Google Fonts) — no setup needed.
+
+**Ekstract** uses a custom font (`Ltt Recoleta`) bundled directly in this package. The `@font-face` declarations are injected automatically into `dist/css/ekstract.css` — just import the CSS and it works.
+
+**Beebs** uses `Really Sans Small` (font files not yet available). Figtree is used as a placeholder in the meantime.
+
+See `docs/tokens-guidelines.md` for details.
+
+## For AI tools & LLMs
+
+This package is designed to work with AI coding assistants.
+The file `docs/tokens-guidelines.md` included in this package describes token usage rules and semantic intent.
+
+**Key rules:**
+
+- `color.bg.*` → backgrounds (`base` = default, `alternate` = subtle, `brand` = brand color)
+- `color.fg.*` → text and icons (`neutral` = default, `subtle` = secondary, `brand` = brand color, `inverse` = on dark backgrounds)
+- `font.body.*` → all content text (paragraphs, descriptions, UI labels)
+- `font.title.*` / `font.display.*` → headings only — automatically responsive at 768px, no extra setup needed
+- `font.link.*` → clickable links — always match the size to the surrounding `font.body.*`
+- `space.*` → paddings and gaps (rem)
+- `size.*` → component dimensions (rem)
+- `border.radius.*` → rounded corners (rem) — `border.width.*` → border thickness (px)
+
+**Never use primitive tokens directly** (e.g. `--kiabi-900`). Always use the public tokens listed above.
+
 ## Versioning
 
 This package follows [Semantic Versioning](https://semver.org):

package/dist/css/beebs.css

@@ -1,3 +1,10 @@
+/* Really Sans Small — PLACEHOLDER using Figtree until font files are provided */
+@font-face {
+  font-family: 'Really Sans Small';
+  src: local('Figtree'), local('system-ui');
+  font-weight: 100 900;
+  font-style: normal;
+}
 /**
  * Do not edit directly, this file was auto-generated.
  */

package/dist/css/ekstract.css

@@ -1,3 +1,25 @@
+/* Ltt Recoleta — custom brand font for Ekstract */
+@font-face {
+  font-family: 'Ltt Recoleta';
+  src: url('../fonts/ekstract/LttRecoleta-Medium.woff2') format('woff2');
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: 'Ltt Recoleta';
+  src: url('../fonts/ekstract/LttRecoleta-SemiBold.woff2') format('woff2');
+  font-weight: 600;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: 'Ltt Recoleta';
+  src: url('../fonts/ekstract/LttRecoleta-Bold.woff2') format('woff2');
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
+}
 /**
  * Do not edit directly, this file was auto-generated.
  */

package/docs/tokens-guidelines.md

@@ -0,0 +1,73 @@
+# Token Guidelines
+
+Règles d'usage des tokens Kommon pour les développeurs et les outils IA.
+
+---
+
+## Typographie
+
+### Display
+
+| Token | Description |
+|---|---|
+| `font.display.l` | **Titre d'accroche de grande taille**, pour les heroes, tops de page ou ruptures éditoriales |
+| `font.display.m` | **Titre d'accroche de taille moyenne**, pour les heroes, tops de page ou ruptures éditoriales |
+
+### Title
+
+| Token | Description |
+|---|---|
+| `font.title.l` | **Titre de page ou de section**, à hiérarchie visuelle forte |
+| `font.title.m` | **Titre de page ou de section**, à hiérarchie visuelle moyenne |
+| `font.title.s` | **Titre de page ou de section**, à hiérarchie visuelle réduite |
+| `font.title.xs` | **Titre de page ou de section**, à hiérarchie visuelle minimale |
+
+### Body
+
+| Token | Description |
+|---|---|
+| `font.body.m` | **Taille par défaut** pour le texte d'interface et le contenu éditorial (paragraphes, descriptions, labels, etc.) |
+| `font.body.m.bold` | Variante de `font.body.m` pour **créer de l'emphase** sur un mot ou une information clé |
+| `font.body.s` | **Texte de taille réduite** pour les informations de support non essentielles, ou les éléments d'interface compacts |
+| `font.body.s.bold` | Variante de `font.body.s` pour **créer de l'emphase** sur un mot ou une information clé |
+| `font.body.xs` | **Texte de très petite taille**, réservé uniquement aux mentions légales |
+| `font.body.xs.bold` | Variante de `font.body.xs` pour **créer de l'emphase** sur un mot ou une information clé |
+
+### Link
+
+| Token | Description |
+|---|---|
+| `font.link.m` | **Lien cliquable** intégré dans un texte `font.body.m` |
+| `font.link.m.bold` | Variante de `font.link.m` pour créer davantage d'**emphase** sur le lien |
+| `font.link.s` | **Lien cliquable** intégré dans un texte `font.body.s` |
+| `font.link.s.bold` | Variante de `font.link.s` pour créer davantage d'**emphase** sur le lien |
+| `font.link.xs` | **Lien cliquable** intégré dans un texte `font.body.xs` |
+| `font.link.xs.bold` | Variante de `font.link.xs` pour créer davantage d'**emphase** sur le lien |
+
+---
+
+## Fonts personnalisées par brand
+
+Toutes les brands utilisent **Figtree** (Google Fonts) pour les textes body et link.
+Les fonts de titres (`font.display.*`, `font.title.*`) varient par brand.
+
+| Brand | Font | Source | Statut |
+|---|---|---|---|
+| kiabi | Figtree | Google Fonts | ✅ |
+| kitchoun | Figtree | Google Fonts | ✅ |
+| kiabi-home | Figtree | Google Fonts | ✅ |
+| ekstract | **Ltt Recoleta** | Fichiers woff2 embarqués dans le paquet (`fonts/ekstract/`) | ✅ |
+| beebs | Really Sans Small | Fichiers woff2 à venir | ⏳ Figtree utilisée en placeholder |
+
+### Ekstract — Ltt Recoleta
+
+La font `Ltt Recoleta` est embarquée directement dans le paquet npm. Les `@font-face` sont injectés automatiquement dans `dist/css/ekstract.css` — aucune configuration supplémentaire nécessaire.
+
+Les fichiers sont disponibles dans `fonts/ekstract/` si un usage direct est nécessaire :
+- `LttRecoleta-Medium.woff2` — font-weight: 500
+- `LttRecoleta-SemiBold.woff2` — font-weight: 600
+- `LttRecoleta-Bold.woff2` — font-weight: 700
+
+### Beebs — Really Sans Small ⏳
+
+La font `Really Sans Small` n'est pas encore disponible. En attendant, un `@font-face` placeholder redirige vers Figtree. Dès réception des fichiers woff2, remplacer le placeholder dans `scripts/build-tokens.js` → `FONT_FACES.beebs`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kommon-lab/tokens",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Design tokens for Kommon Lab multi-brand design system",
   "exports": {
     "./css/*": "./dist/css/*",
@@ -8,7 +8,9 @@
   },
   "files": [
     "dist/",
-    "tokens/"
+    "tokens/",
+    "fonts/",
+    "docs/tokens-guidelines.md"
   ],
   "scripts": {
     "transform": "node scripts/transform-tokens.js",