import { Meta, Source } from '@storybook/addon-docs/blocks';
import '../styles/shared.css';

<Meta title="Design Tokens/Utilisation" />

<div className="header">
  <h1>Utilisation</h1>
  <p>Comment consommer les design tokens (espacements, couleurs, arrondis, typographie) dans vos styles.</p>
</div>

Depuis la version **1.0.25**, les design tokens sont exposés sous forme de **variables CSS** (custom properties) `--v-…`, générées à partir du thème Vuetify de Synapse. Elles **s'adaptent automatiquement au thème actif** (cnam / pa / amelipro, clair / sombre).

> Cette page remplace l'ancien **export SCSS** de tokens (`$gap-2`, variables de couleur…) disponible jusqu'à la **1.0.24**. Voir la section [Migration](#migration-depuis-lexport-scss) en bas de page.

## Espacements (`gap`)

Échelle `--v-gap-N`, où `N` est un multiple de 4&nbsp;px.

<table>
  <thead>
    <tr>
      <th>Variable CSS</th>
      <th>Valeur</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>--v-gap-0</code></td>
      <td>0</td>
    </tr>
    <tr>
      <td><code>--v-gap-1</code></td>
      <td>4px</td>
    </tr>
    <tr>
      <td><code>--v-gap-2</code></td>
      <td>8px</td>
    </tr>
    <tr>
      <td><code>--v-gap-3</code></td>
      <td>12px</td>
    </tr>
    <tr>
      <td><code>--v-gap-4</code></td>
      <td>16px</td>
    </tr>
    <tr>
      <td><code>--v-gap-6</code></td>
      <td>24px</td>
    </tr>
    <tr>
      <td><code>--v-gap-8</code></td>
      <td>32px</td>
    </tr>
    <tr>
      <td>…</td>
      <td>… (par pas de 4&nbsp;px)</td>
    </tr>
  </tbody>
</table>

<Source dark language="scss" code={`
.mon-bloc {
  display: flex;
  gap: var(--v-gap-2);     /* 8px */
  padding: var(--v-gap-4); /* 16px */
}
`} />

Catalogue complet&nbsp;: [Design Tokens → Espacements](/docs/design-tokens-espacements--docs).

## Couleurs

Variables de thème `--v-theme-<nom>`. ⚠️ Si elles contiennent un **triplet RVB**, à envelopper dans `rgb()` / `rgba()`&nbsp;:

<Source dark language="scss" code={`
.element {
  color: rgb(var(--v-theme-primary));
  background-color: rgba(var(--v-theme-primary), 0.08); /* avec opacité */
  border: 1px solid rgb(var(--v-theme-onSurface));
}
`} />

Catalogue complet&nbsp;: [Design Tokens → Couleurs](/docs/design-tokens-couleurs--docs).

### Déclinaisons (`darken` / `lighten`)

Chaque couleur de la palette dispose d'une échelle de 11 paliers. ⚠️ **Le nom n'a pas de tiret avant le chiffre**&nbsp;: `grey-darken60`, et **non** `grey-darken-60`.

<Source dark language="scss" code={`
.element {
  border-color: rgb(var(--v-theme-grey-darken60));
  background: rgb(var(--v-theme-grey-lighten90));
}
`} />

Échelle, identique pour toutes les couleurs (`grey`, `blue`, `green`…)&nbsp;: `darken80`, `darken60`, `darken40`, `darken20`, `base`, `lighten20`, `lighten40`, `lighten60`, `lighten80`, `lighten90`, `lighten97`.

> Le format `…-darken-1` / `-lighten-2` (avec **tiret avant le chiffre**, petits paliers) est réservé à la palette **AmeliPro 2026** (`--v-theme-ap-grey-darken-1`)&nbsp;: il ne s'applique pas à l'échelle principale.

### Nommage des variables CSS — deux familles de `on-*`

Pour les couleurs de thème, deux familles de variables coexistent. **Une seule est l'API du Design System.**

<table>
  <thead>
    <tr>
      <th>Famille</th>
      <th>Forme</th>
      <th>Origine</th>
      <th>À utiliser&nbsp;?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Tokens sémantiques du DS</td>
      <td><code>--v-theme-onSurface</code>, <code>--v-theme-onSurfaceVariant</code>, <code>--v-theme-onPrimary</code>… (<strong>camelCase</strong>)</td>
      <td>Définis par le Design System</td>
      <td>✅ Oui</td>
    </tr>
    <tr>
      <td>Contrastes auto-générés par Vuetify</td>
      <td><code>--v-theme-on-surface</code>, <code>--v-theme-on-surfaceBright</code>… (<strong>kebab <code>on-</code></strong>)</td>
      <td>Générés automatiquement par Vuetify (un <code>on-&lt;couleur&gt;</code> par couleur de thème)</td>
      <td>❌ Non (couleurs techniques, hors API)</td>
    </tr>
  </tbody>
</table>

> **Règle simple&nbsp;:** si la variable a un **`on-` avec un tiret**, c'est une couleur technique générée par Vuetify&nbsp;: prenez plutôt la version **camelCase `onXxx`** du Design System.

Comme il n'y a plus de variables SCSS, une faute de nom ne génère **pas d'erreur de compilation** (la `var()` reste juste non résolue). En cas de doute sur le nom d'un token issu de Figma, reportez-vous à [Correspondances couleurs](/docs/design-tokens-couleurs-correspondances-couleurs--docs).

### Variable « non définie »&nbsp;?

Ces variables sont **générées au runtime par Vuetify** à partir du thème de Synapse, et **uniquement dans le périmètre du thème actif** — elles ne sont pas livrées dans un fichier CSS statique. Si une `var(--v-theme-…)` n'est pas résolue, vérifiez dans l'ordre&nbsp;:

1. **Le nom** — par ex. `grey-darken60` (sans tiret avant le chiffre).
2. **Le thème Vuetify de Synapse est bien câblé.** La palette n'est émise que si les `themes` de Synapse sont passés à `createVuetify`. Le plus simple&nbsp;: utiliser l'instance fournie.

<Source dark language="ts" code={`
import { createVuetifyInstance } from '@cnamts/synapse/vuetifyConfig'

app.use(createVuetifyInstance())
`} />

Voir [createVuetifyInstance](/docs/guide-du-dev-démarrage-createvuetifyinstance--docs).

3. **Le scope du thème.** Vuetify définit ces variables sous le sélecteur `.v-theme--<marque>` (posé sur `<v-app>`). Une règle CSS appliquée **hors de `<v-app>`** (style global sur `body`, overlay/teleport sorti de l'app…) ne résout pas `var(--v-theme-…)`.

> **Vérifier&nbsp;:** inspectez un élément **à l'intérieur de `<v-app>`** (onglet *Computed* des devtools) et cherchez la variable&nbsp;; ou recherchez son nom dans la balise `<style>` du thème injectée par Vuetify dans le `<head>`. Absente du `<style>` ⇒ cause n°2&nbsp;; présente mais non résolue à l'usage ⇒ cause n°3.

## Arrondis (`radius`)

<table>
  <thead>
    <tr>
      <th>Variable CSS</th>
      <th>Nom</th>
      <th>Valeur (thème cnam)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>--v-radius-rounded0</code></td>
      <td>rounded-0</td>
      <td>0</td>
    </tr>
    <tr>
      <td><code>--v-radius-rounded</code></td>
      <td>rounded</td>
      <td>4px</td>
    </tr>
    <tr>
      <td><code>--v-radius-roundedLg</code></td>
      <td>rounded-lg</td>
      <td>8px</td>
    </tr>
    <tr>
      <td><code>--v-radius-roundedPill</code></td>
      <td>rounded-pill</td>
      <td>64px</td>
    </tr>
  </tbody>
</table>

Les valeurs varient selon le thème (par ex. AmeliPro&nbsp;: `rounded` = 12px, `roundedLg` = 24px).

<Source dark language="scss" code={`
.card {
  border-radius: var(--v-radius-roundedLg); /* 8px en thème cnam */
}
`} />

Catalogue complet&nbsp;: [Design Tokens → Arrondis](/docs/design-tokens-arrondis--docs).

## Typographie

`font-family: var(--v-font-family)` et les tailles `--v-fontSize-…` (`titres`, `titresAlternatifs`, `corpsDeTexte`, `liensEtLibelles`…)&nbsp;:

<Source dark language="scss" code={`
.titre {
  font-family: var(--v-font-family);
  font-size: var(--v-fontSize-titres);
}
`} />

Catalogue complet&nbsp;: [Design Tokens → Styles typographiques](/docs/design-tokens-styles-typographiques--docs).

## Classes utilitaires (templates)

Pour la plupart des cas, les **classes utilitaires** Vuetify suffisent et suivent les mêmes échelles&nbsp;:

- Espacements&nbsp;: `ga-2` (gap), `pa-4` (padding), `ma-2` (margin)…
- Couleurs&nbsp;: `text-primary`, `bg-primary`, `border-primary`…
- Arrondis&nbsp;: `rounded-0`, `rounded`, `rounded-lg`, `rounded-pill`.

## Migration depuis l'export SCSS

Jusqu'à la **1.0.24**, les tokens étaient disponibles via un **export SCSS** (`$gap-2`, …). Depuis la **1.0.25**, cet export est remplacé par les **variables CSS** ci-dessus&nbsp;:

<table>
  <thead>
    <tr>
      <th>Avant (SCSS, ≤ 1.0.24)</th>
      <th>Maintenant (CSS, ≥ 1.0.25)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>$gap-2</code></td>
      <td><code>var(--v-gap-2)</code></td>
    </tr>
    <tr>
      <td>couleur primaire</td>
      <td><code>rgb(var(--v-theme-primary))</code></td>
    </tr>
    <tr>
      <td><code>$rounded-lg</code></td>
      <td><code>var(--v-radius-roundedLg)</code></td>
    </tr>
    <tr>
      <td>taille de texte</td>
      <td><code>var(--v-fontSize-…)</code></td>
    </tr>
  </tbody>
</table>

**Pourquoi ce changement&nbsp;?** Les variables CSS sont résolues au **runtime** et s'adaptent au thème actif, là où l'export SCSS produisait des valeurs **figées à la compilation**.

### Shim de compatibilité (optionnel)

Pour faciliter la migration d'un projet qui consommait encore l'ancien export SCSS, un **partial SCSS optionnel** ré-expose les anciennes variables (sous leurs anciens noms) vers les variables CSS. Sont couverts&nbsp;: **espacements** (`$gap-N`, `$padding-N`, `$spacing-*`), **arrondis** (`$radius-rounded-*`) et **typographie** (`$font-size-*`).

<Source dark language="scss" code={`
// Dans votre projet
@use '@cnamts/synapse/assets/compat/legacy-tokens' as *;

.box {
  gap: $gap-2;                       // -> var(--v-gap-2)
  padding: $padding-4;               // -> var(--v-padding-4)
  border-radius: $radius-rounded-lg; // -> var(--v-radius-roundedLg)
  font-size: $font-size-title;       // -> var(--v-fontSize-titres)
}
`} />

> ⚠️ Ces variables contiennent une `var(--…)` résolue au **runtime**&nbsp;: elles conviennent pour des affectations directes (`gap`, `padding`, `margin`, `border-radius`, `font-size`…) mais **pas** pour des opérations SCSS *compile-time* (`calc` Sass, fonctions de couleur…). C'est une aide à la transition&nbsp;: à terme, utilisez directement les variables CSS.

Les **couleurs** ne sont pas ré-exposées (palette > 100 valeurs, et triplet RVB)&nbsp;: utilisez directement `rgb(var(--v-theme-<nom>))` (voir la section [Couleurs](#couleurs)).