@overcrow/mcp 0.0.0 → 0.1.1

package/dist/content/docs/fr/style-properties.md

@@ -0,0 +1,272 @@
+# Propriétés de style et tokens
+
+Toutes les propriétés que `style.ocss` accepte dans un widget PlayerVox
+OverCrow, avec leurs valeurs et leur valeur initiale, puis les tokens du
+design system et les icônes. [Le style](style.md) explique les sélecteurs,
+la mise en page, les tokens et les animations ; cette page en est la liste.
+
+<!-- source: templates/chart/style.ocss -->
+```css
+.value {
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+}
+```
+
+Tout ce qui ne figure pas sur cette page est refusé à la vérification du
+widget : une propriété, un mot-clé ou une unité hors des listes ci-dessous
+est une erreur, accompagnée du nom le plus proche en suggestion.
+
+## Lire une propriété
+
+- **Valeur** utilise les notations de [valeurs](#valeurs) : `<px>`,
+  `<percent>`, `<color>`… Un `|` sépare des alternatives, `?` marque une
+  partie facultative.
+- **Valeur initiale** est la valeur d’un élément qu’aucune règle ne style.
+- **Héritée** : la propriété prend la valeur du parent quand aucune règle ne
+  la définit ; définissez-la sur un conteneur.
+- **Animable** : la propriété peut figurer dans une `transition` et dans un
+  bloc `@keyframes`.
+
+## Propriétés
+
+<!-- generated:style-properties -->
+### Mise en page
+
+| Propriété | Valeur | Valeur initiale | Héritée | Animable |
+| --- | --- | --- | --- | --- |
+| `display` | `flex` \| `grid` \| `none` | `flex` | non | non |
+| `position` | `relative` \| `absolute` | `relative` | non | non |
+| `top` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `auto` | non | non |
+| `right` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `auto` | non | non |
+| `bottom` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `auto` | non | non |
+| `left` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `auto` | non | non |
+| `flex-direction` | `row` \| `column` \| `row-reverse` \| `column-reverse` | `row` | non | non |
+| `flex-wrap` | `nowrap` \| `wrap` | `nowrap` | non | non |
+| `flex-grow` | nombre de 0 à 1000 | `0` | non | non |
+| `flex-shrink` | nombre de 0 à 1000 | `1` | non | non |
+| `flex-basis` | `<px>` \| `<percent>` \| `auto` | `auto` | non | non |
+| `justify-content` | `start` \| `end` \| `center` \| `stretch` \| `space-between` \| `space-around` \| `space-evenly` | `start` | non | non |
+| `align-items` | `start` \| `end` \| `center` \| `baseline` \| `stretch` | `stretch` | non | non |
+| `align-self` | `auto` \| `start` \| `end` \| `center` \| `baseline` \| `stretch` | `auto` | non | non |
+| `align-content` | `start` \| `end` \| `center` \| `stretch` \| `space-between` \| `space-around` \| `space-evenly` | `stretch` | non | non |
+| `justify-items` | `start` \| `end` \| `center` \| `stretch` | `stretch` | non | non |
+| `justify-self` | `auto` \| `start` \| `end` \| `center` \| `stretch` | `auto` | non | non |
+| `gap` | 1–2 × (`<px>` \| `<percent>`) | `0` | non | non |
+| `row-gap` | `<px>` \| `<percent>` | `0` | non | non |
+| `column-gap` | `<px>` \| `<percent>` | `0` | non | non |
+| `grid-template-columns` | `none` \| liste ≤ 24 de `<track>`, ou `repeat(<integer>, <track>)` | `none` | non | non |
+| `grid-template-rows` | `none` \| liste ≤ 24 de `<track>`, ou `repeat(<integer>, <track>)` | `none` | non | non |
+| `grid-auto-flow` | `row` \| `column` | `row` | non | non |
+| `grid-auto-columns` | `<track>`: `<px>` \| `<percent>` \| `<fr>` \| `auto` \| `min-content` \| `max-content` \| `minmax(<track>, <track>)` | `auto` | non | non |
+| `grid-auto-rows` | `<track>`: `<px>` \| `<percent>` \| `<fr>` \| `auto` \| `min-content` \| `max-content` \| `minmax(<track>, <track>)` | `auto` | non | non |
+| `grid-column` | `auto` \| `<integer>` \| `span <integer>` \| `<start> / <end>`, lignes de 1 à 24 | `auto` | non | non |
+| `grid-row` | `auto` \| `<integer>` \| `span <integer>` \| `<start> / <end>`, lignes de 1 à 24 | `auto` | non | non |
+
+### Boîte
+
+| Propriété | Valeur | Valeur initiale | Héritée | Animable |
+| --- | --- | --- | --- | --- |
+| `width` | `<px>` \| `<percent>` \| `auto` | `auto` | non | non |
+| `height` | `<px>` \| `<percent>` \| `auto` | `auto` | non | non |
+| `min-width` | `<px>` \| `<percent>` \| `auto` | `auto` | non | non |
+| `min-height` | `<px>` \| `<percent>` \| `auto` | `auto` | non | non |
+| `max-width` | `<px>` \| `<percent>` \| `none` | `none` | non | non |
+| `max-height` | `<px>` \| `<percent>` \| `none` | `none` | non | non |
+| `aspect-ratio` | nombre de 0.01 à 100 | `auto` | non | non |
+| `margin` | 1–4 × (`<px>` \| `<percent>` \| `auto`), valeurs négatives admises | `0` | non | non |
+| `margin-top` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `0` | non | non |
+| `margin-right` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `0` | non | non |
+| `margin-bottom` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `0` | non | non |
+| `margin-left` | `<px>` \| `<percent>` \| `auto`, valeurs négatives admises | `0` | non | non |
+| `padding` | 1–4 × (`<px>` \| `<percent>`) | `0` | non | non |
+| `padding-top` | `<px>` \| `<percent>` | `0` | non | non |
+| `padding-right` | `<px>` \| `<percent>` | `0` | non | non |
+| `padding-bottom` | `<px>` \| `<percent>` | `0` | non | non |
+| `padding-left` | `<px>` \| `<percent>` | `0` | non | non |
+| `overflow` | `visible` \| `hidden` | `visible` | non | non |
+
+### Apparence
+
+| Propriété | Valeur | Valeur initiale | Héritée | Animable |
+| --- | --- | --- | --- | --- |
+| `background-color` | `<color>` | `transparent` | non | oui |
+| `background` | `<color>` \| `linear-gradient(<angle>?, <color> <percent>?, …)`, arrêts ≤ 8 | `transparent` | non | non |
+| `border` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | non | non |
+| `border-top` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | non | non |
+| `border-right` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | non | non |
+| `border-bottom` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | non | non |
+| `border-left` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | non | non |
+| `border-width` | 1–4 × (`<px>`) | `0` | non | non |
+| `border-style` | `solid` \| `none` | `none` | non | non |
+| `border-color` | `<color>` | `currentColor` | non | oui |
+| `border-radius` | 1–4 × (`<px>` \| `<percent>`) | `0` | non | non |
+| `box-shadow` | `none` \| `var(--shadow-…)` seul \| liste ≤ 2 de `inset`? `<px> <px> <px>? <px>? <color>` | `none` | non | non |
+| `opacity` | nombre de 0 à 1 | `1` | non | oui |
+| `visibility` | `visible` \| `hidden` | `visible` | oui | non |
+| `object-fit` | `contain` \| `cover` \| `fill` \| `none` | `contain` | non | non |
+
+### Texte
+
+| Propriété | Valeur | Valeur initiale | Héritée | Animable |
+| --- | --- | --- | --- | --- |
+| `color` | `<color>` | `var(--color-text)` | oui | oui |
+| `font-family` | `ui` \| `mono` \| `display`, ou un token de police | `ui` | oui | non |
+| `font-size` | `<px>` de 6 px à 96 px, ou un token de taille | `var(--font-size-body)` | oui | non |
+| `font-weight` | `400` \| `500` \| `600` \| `700` \| `normal` \| `bold` | `400` | oui | non |
+| `font-style` | `normal` \| `italic` | `normal` | oui | non |
+| `font-variant-numeric` | `normal` \| `tabular-nums` | `normal` | oui | non |
+| `line-height` | nombre de 0.5 à 4 (× taille de police) \| `<px>` | `1.3` | oui | non |
+| `letter-spacing` | `<px>`, valeurs négatives admises | `0` | oui | non |
+| `text-align` | `start` \| `center` \| `end` | `start` | oui | non |
+| `text-decoration` | `none` \| `underline` \| `line-through` | `none` | non | non |
+| `text-transform` | `none` \| `uppercase` \| `lowercase` \| `capitalize` | `none` | oui | non |
+| `white-space` | `normal` \| `nowrap` \| `pre-wrap` | `normal` | oui | non |
+| `vertical-align` | `baseline` \| `middle` | `baseline` | non | non |
+| `text-overflow` | `clip` \| `ellipsis` \| `marquee` | `clip` | non | non |
+| `line-clamp` | entier de 0 à 64 | `0` | non | non |
+| `overflow-wrap` | `normal` \| `anywhere` | `normal` | oui | non |
+
+### Mouvement
+
+| Propriété | Valeur | Valeur initiale | Héritée | Animable |
+| --- | --- | --- | --- | --- |
+| `transform` | `none` \| jusqu’à 4 fonctions parmi `translate(<length>, <length>)` avec `<px>` ou `<percent>`, `translateX()`, `translateY()`, `scale(<number>{1,2})` de 0 à 8, `rotate(<angle>)` | `none` | non | oui |
+| `transform-origin` | 1–2 × (`left` \| `center` \| `right` \| `top` \| `bottom` \| `<percent>` \| `<px>`) | `center` | non | non |
+| `transition` | `none` \| liste ≤ 8 de `<animatable-property> <time> <easing>? <time>?` | `none` | non | non |
+| `animation` | `none` \| liste ≤ 8 de `<keyframes-name> <time> <easing>? <time>? (<integer> \| infinite)? <direction>? <fill-mode>?`, entier de 1 à 10000 | `none` | non | non |
+
+### Interaction
+
+| Propriété | Valeur | Valeur initiale | Héritée | Animable |
+| --- | --- | --- | --- | --- |
+| `cursor` | `default` \| `pointer` \| `text` \| `not-allowed` \| `grab` \| `grabbing` | `default` | oui | non |
+| `pointer-events` | `auto` \| `none` | `auto` | non | non |
+<!-- /generated:style-properties -->
+
+## Valeurs
+
+<!-- generated:style-values -->
+| Syntaxe | Signification |
+| --- | --- |
+| `<px>` | `12px` ; `0` peut se passer d’unité. Nombres décimaux, sans exposant. |
+| `<percent>` | `50%` du bloc conteneur, comme en CSS ; au plus 1000 dans un sens ou dans l’autre. |
+| `<fr>` | `1fr`, pour les pistes de grille seulement ; de 0 à 1000. |
+| `<time>` | `120ms` ou `0.12s`, de 0 à 300000 ms. |
+| `<angle>` | `4deg` ou `0.5turn`, au plus 3600 degrés dans un sens ou dans l’autre. |
+| `<color>` | `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb(r g b)`, `rgb(r g b / a)`, `transparent`, `currentColor`, ou un token de couleur. Pas de couleurs nommées. |
+| `var(--token)` | Token du design system, du type attendu, comme valeur entière ou comme composante d’une valeur composite. Pas d’argument de repli ; un widget ne peut pas déclarer de propriétés personnalisées. |
+| `<easing>` | `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, `steps(<integer 1..=MAX_EASING_STEPS>)`. |
+| `<direction>` | `normal`, `reverse`, `alternate`. |
+| `<fill-mode>` | `none`, `forwards`, `backwards`, `both`. |
+<!-- /generated:style-values -->
+
+## Tokens du design system
+
+Un token s’écrit `var(--name)` là où une valeur de son type est attendue.
+Les tokens de couleur et d’ombre ont une valeur par thème ; les autres sont
+identiques dans les deux thèmes.
+
+<!-- source: templates/list/style.ocss -->
+```css
+.summary {
+  font-size: var(--font-size-caption);
+  color: var(--color-text-secondary);
+}
+```
+
+<!-- generated:tokens -->
+### Couleurs
+
+| Token | Sombre | Clair | Signification |
+| --- | --- | --- | --- |
+| `--color-accent` | `#a3e635` | `#4d7c0f` | Accent de la marque : actions principales, état coché. |
+| `--color-accent-hover` | `#b5f153` | `#3f6212` | Accent sous le pointeur. |
+| `--color-accent-soft` | `#a3e6351c` | `#4d7c0f1f` | Voile d’accent derrière un contenu sélectionné. |
+| `--color-on-accent` | `#09090b` | `#ffffff` | Texte et icônes dessinés sur l’accent et sur son état de survol. |
+| `--color-surface-panel` | `#111114ee` | `#fafafaee` | Fond du panneau du widget, dessiné par l’hôte derrière le contenu. |
+| `--color-surface-raised` | `#1e1e22e0` | `#f4f4f5eb` | Surface en relief dans le panneau. |
+| `--color-surface-hover` | `#28282deb` | `#e4e4e7f0` | Surface sous le pointeur. |
+| `--color-surface-field` | `#0f0f12` | `#ffffff` | Fond d’un champ de texte. |
+| `--color-surface-popover` | `#18181c` | `#ffffff` | Fond d’un popover et d’une liste déroulante. |
+| `--color-border` | `#ffffff18` | `#0000001a` | Bordure par défaut. |
+| `--color-border-strong` | `#ffffff2a` | `#0000002e` | Bordure et séparateur accentués. |
+| `--color-text` | `#f7f7f8` | `#18181b` | Texte principal. |
+| `--color-text-secondary` | `#d4d4d8` | `#3f3f46` | Texte secondaire. |
+| `--color-text-muted` | `#a1a1aa` | `#52525b` | Légendes et métadonnées. |
+| `--color-text-subtle` | `#71717a` | `#71717a` | Indications des champs vides et texte désactivé. |
+| `--color-danger` | `#fb7185` | `#e11d48` | Erreurs et actions destructrices. |
+| `--color-danger-soft` | `#fb71851a` | `#e11d481a` | Voile de danger derrière les confirmations destructrices et les erreurs. |
+| `--color-warning` | `#fbbf24` | `#b45309` | Avertissements. |
+| `--color-success` | `#86efac` | `#15803d` | Réussite et états sains. |
+
+### Longueurs
+
+| Token | Valeur | Signification |
+| --- | --- | --- |
+| `--space-1` | `2px` | Espacement, palier 1. |
+| `--space-2` | `4px` | Espacement, palier 2. |
+| `--space-3` | `6px` | Espacement, palier 3 (espacement par défaut entre les éléments). |
+| `--space-4` | `8px` | Espacement, palier 4. |
+| `--space-5` | `12px` | Espacement, palier 5. |
+| `--space-6` | `16px` | Espacement, palier 6. |
+| `--radius-sm` | `6px` | Petits contrôles et images. |
+| `--radius-md` | `9px` | Boutons. |
+| `--radius-lg` | `10px` | Cartes. |
+| `--radius-pill` | `999px` | Pastilles et boutons ronds. |
+| `--control-height` | `28px` | Hauteur standard d’un contrôle. |
+| `--icon-button-size` | `22px` | Bouton-icône compact. |
+
+### Tailles de police
+
+| Token | Valeur | Signification |
+| --- | --- | --- |
+| `--font-size-caption` | `10px` | Surtitres et légendes. |
+| `--font-size-small` | `11px` | Métadonnées. |
+| `--font-size-button` | `13px` | Libellés des boutons. |
+| `--font-size-body` | `14px` | Texte courant. |
+| `--font-size-title` | `18px` | Titres de section. |
+| `--font-size-value` | `22px` | Valeurs mises en avant (horloge, FPS). |
+
+### Familles de police
+
+| Token | Valeur | Signification |
+| --- | --- | --- |
+| `--font-ui` | `ui` | Noto Sans UI, la police de l’interface. |
+| `--font-mono` | `mono` | Noto Sans Mono, pour les valeurs. |
+| `--font-display` | `display` | Space Grotesk, pour les grades et les scores. |
+
+### Durées
+
+| Token | Valeur | Signification |
+| --- | --- | --- |
+| `--duration-fast` | `120ms` | Transitions d’état. |
+| `--duration-medium` | `240ms` | Panneaux et popovers. |
+
+### Ombres
+
+| Token | Sombre | Clair | Signification |
+| --- | --- | --- | --- |
+| `--shadow-panel` | `0px 4px 16px 0px #00000066` | `0px 4px 16px 0px #0000001f` | Ombre du panneau du widget et des surfaces flottantes de l’hôte. |
+<!-- /generated:tokens -->
+
+## Icônes
+
+L’élément `icon` et les lignes du menu d’options prennent le nom d’une icône
+Lucide, dans sa graphie habituelle : `circle-check`, `rotate-ccw`,
+`chevron-down`.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+          <icon name="x"/>
+```
+
+<!-- generated:icons -->
+Lucide 1.34.0, 1777 icônes.
+<!-- /generated:icons -->
+
+Tout autre nom est refusé. Le type `IconName` du SDK les liste tous : un nom
+erroné dans la logique est donc une erreur TypeScript. Au sein de l’API v1,
+le jeu d’icônes peut grandir, mais il ne perd ni ne renomme jamais une
+icône. OverCrow dessine les icônes lui-même : un widget n’embarque aucune
+police d’icônes.

package/dist/content/docs/fr/style.md

@@ -0,0 +1,281 @@
+# Le style
+
+`style.ocss` met en forme la vue d’un widget PlayerVox OverCrow avec un
+sous-ensemble de CSS, réduit et borné : règles, sélecteurs de classe et
+d’élément, mise en page flex et grid, couleurs, bordures, typographie,
+transitions et animations. Si vous connaissez CSS, vous en connaissez la
+syntaxe ; la différence, c’est que le sous-ensemble est fermé. Une
+propriété, un sélecteur ou une valeur qui n’en fait pas partie est une
+erreur que signale `overcrow-widget check`, et non une déclaration ignorée
+en silence.
+
+<!-- source: templates/counter/style.ocss -->
+```css
+.counter {
+  flex-direction: column;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+
+.value {
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+}
+
+.actions {
+  gap: var(--space-2);
+}
+
+.step {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+}
+
+.step:hover {
+  background: var(--color-surface-hover);
+}
+```
+
+Le fichier est facultatif. Sans lui, le widget prend les valeurs par
+défaut : une `box` dispose ses enfants à l’horizontale, le texte a la
+couleur et la taille du thème.
+
+## Règles et sélecteurs
+
+Une règle est une liste de sélecteurs, suivie de déclarations entre
+accolades. Chaque propriété apparaît au plus une fois par règle ; le dernier
+`;` est facultatif. Les commentaires s’écrivent `/* … */`.
+
+<!-- generated:selectors -->
+| Sélecteur | Signification |
+| --- | --- |
+| `text` | Type d’élément ; spécificité (0, 1). |
+| `.name` | Classe ; spécificité (1, 0). |
+| `:hover :active :focus :disabled :checked` | État résolu par l’hôte ; spécificité (1, 0). `:checked` s’applique à `toggle` et à `checkbox`. |
+| `a b` | Combinateur de descendance. |
+| `a > b` | Combinateur d’enfant direct. |
+| `a, b` | Liste de sélecteurs ; chaque sélecteur garde sa propre spécificité. |
+<!-- /generated:selectors -->
+
+Un sélecteur composé est un nom d’élément facultatif, suivi de classes et
+d’états : `button.primary:hover`. Les sélecteurs composés s’enchaînent par
+une espace (descendant) ou par `>` (enfant).
+
+<!-- source: widgets/warframe-market/style.ocss -->
+```css
+.clear:focus,
+.result:focus,
+.copy:focus,
+.back:focus,
+.refresh:focus {
+  border-color: var(--color-accent);
+}
+```
+
+<!-- source: widgets/warframe-market/style.ocss -->
+```css
+.clear:disabled .clear-text {
+  color: var(--color-text-muted);
+}
+```
+
+Les états sont résolus par OverCrow, pas par votre logique : `:hover` et
+`:active` suivent le pointeur, `:focus` le focus clavier, `:disabled`
+l’attribut `disabled`, et `:checked` l’état d’un `toggle` ou d’une
+`checkbox`. OverCrow ne signale pas au widget les mouvements du pointeur :
+un effet de survol ne lui coûte rien.
+
+Quand deux règles définissent la même propriété, le sélecteur le plus
+spécifique l’emporte : les classes et les états comptent d’abord, puis les
+noms d’éléments. À sélecteurs égaux, la règle écrite en dernier l’emporte.
+Il n’y a pas de `!important`.
+
+## Mise en page
+
+Tout conteneur est par défaut un conteneur flex (`display: flex`, à
+l’horizontale). `display: grid` en fait une grille, et `display: none`
+retire l’élément et ses enfants de la mise en page tout en les gardant dans
+la vue.
+
+<!-- source: templates/list/style.ocss -->
+```css
+.checklist {
+  flex-direction: column;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+```
+
+<!-- source: widgets/warframe-market/style.ocss -->
+```css
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-3);
+}
+```
+
+Flex et grid fonctionnent comme en CSS, avec les propriétés du
+[groupe Mise en page](style-properties.md#mise-en-page) : `flex-direction`,
+`flex-grow`, `gap`, `justify-content`, `align-items`,
+`grid-template-columns`, `grid-column`… Un élément peut aussi sortir du flux
+avec `position: absolute` ; il se place alors par rapport à son parent avec
+`top`, `right`, `bottom` et `left`. Deux éléments placés dans la même
+cellule de grille se superposent. C’est ainsi que l’exemple du compte à
+rebours place le temps au milieu de son anneau :
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+/* The time sits in the middle of the ring: both share one grid cell. */
+.dial {
+  display: grid;
+  grid-template-columns: 72px;
+  grid-template-rows: 72px;
+  justify-content: center;
+  justify-items: center;
+  align-items: center;
+}
+```
+
+Un widget ne peut pas dessiner hors de son cadre : OverCrow le rogne.
+
+## Valeurs
+
+Les valeurs s’écrivent comme en CSS, dans certaines limites : les longueurs
+en `px` (`0` peut omettre l’unité) et les pourcentages, les couleurs sous la
+forme `#rrggbb`, `#rrggbbaa` ou `rgb(r g b / a)`, les durées en `ms` ou en
+`s`, les angles en `deg` ou en `turn`, et les tokens sous la forme
+`var(--name)`. La notation exacte de chaque sorte de valeur figure dans
+[valeurs](style-properties.md#valeurs).
+
+Les longueurs sont des pixels logiques : OverCrow les multiplie par
+l’échelle du contenu de l’utilisateur (de 50 % à 175 %) et par la densité de
+l’écran. `12px` a donc la même taille physique sur tous les écrans. Les
+propriétés raccourcies se développent comme en CSS : une à quatre valeurs
+pour les côtés et les coins, une ou deux pour les espacements.
+
+## Tokens du design system
+
+Un token est une valeur du design system d’OverCrow, écrite `var(--name)`.
+Les tokens de couleur changent avec le thème de l’utilisateur, clair ou
+sombre : un widget stylé avec des tokens suit le thème sans aucun code.
+Préférez-les aux couleurs littérales.
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+.start {
+  width: var(--control-height);
+  height: var(--control-height);
+  justify-content: center;
+  align-items: center;
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+  transition: background-color var(--duration-fast) ease-out;
+}
+```
+
+Un token représente une valeur entière ou une partie d’une valeur composée
+(`padding: var(--space-2) var(--space-4)`). Il doit avoir le type qu’attend
+la propriété : un token de couleur pour une couleur, un token de longueur
+pour une longueur. Il n’y a pas d’argument de repli, et un widget ne peut
+pas déclarer ses propres propriétés personnalisées. Tous les tokens sont
+listés dans
+[tokens du design system](style-properties.md#tokens-du-design-system).
+
+OverCrow dessine le panneau derrière le widget (`--color-surface-panel`),
+son cadre et son ombre : partez d’un fond transparent.
+
+## Texte
+
+Les propriétés de texte (`color`, `font-family`, `font-size`, `font-weight`,
+`line-height`, `text-align`…) sont héritées, comme en CSS : définissez-les
+sur un conteneur pour styler ce qu’il contient.
+
+- Il existe trois familles de police : `ui` (Noto Sans, la valeur par
+  défaut), `mono` (Noto Sans Mono, pour les valeurs) et `display` (Space
+  Grotesk, pour les grades et les scores). OverCrow les embarque ; les
+  polices du système ne sont jamais utilisées : un widget a donc le même
+  aspect sur toutes les machines.
+- `font-variant-numeric: tabular-nums` donne la même largeur à tous les
+  chiffres : un nombre qui change ne déplace pas ses voisins.
+- `text-overflow: ellipsis` coupe par `…` une ligne qui déborde ;
+  `text-overflow: marquee` la fait défiler dans un sens puis dans l’autre,
+  avec une pause à chaque extrémité. `line-clamp` limite un texte à un
+  nombre de lignes.
+- Une `icon` prend la `color` et le `font-size` de l’endroit où elle se
+  trouve, sauf si `width` et `height` sont définis. Dans une ligne de texte,
+  `vertical-align: middle` centre sur la ligne une `icon` ou une `image` en
+  ligne.
+
+Gardez le texte à 11 px ou plus (`--font-size-small`) : un texte plus petit
+se lit mal par-dessus un jeu.
+
+## Transitions et animations
+
+`transition` anime le changement d’une propriété animable ; `animation` joue
+un bloc `@keyframes` de la même feuille.
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+.ring.done {
+  color: var(--color-success);
+  animation: countdown-pulse 800ms ease-in-out 3 alternate;
+}
+```
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+@keyframes countdown-pulse {
+  from { opacity: 1; }
+  to { opacity: 0.4; }
+}
+```
+
+Seules les propriétés qui modifient le dessin, et non la mise en page,
+peuvent être animées : `opacity`, `color`, `background-color`,
+`border-color` et `transform`. Un bloc `@keyframes` ne contient que
+celles-là. OverCrow exécute l’animation lui-même : aucun minuteur ni aucun
+code du widget ne tourne pendant qu’elle joue, et rien n’est redessiné quand
+rien ne change. Un widget masqué ne s’anime pas.
+
+`@keyframes` est la seule règle @. Son nom est un identifiant qui n’est pas
+un mot-clé d’animation, unique dans la feuille.
+
+## Ce qui est refusé
+
+Chacune de ces constructions fait refuser la feuille entière :
+
+- `!important`, `@media`, `@import`, `@font-face` et toute autre règle @ ;
+- `url()`, `calc()` et les autres fonctions CSS ; les chaînes et les
+  échappements ;
+- les déclarations de propriétés personnalisées (`--name: …`) ;
+- les sélecteurs d’ID, d’attribut et universel (`*`), les pseudo-éléments,
+  les pseudo-classes fonctionnelles (`:not()`, `:nth-child()`), les
+  combinateurs de frères ;
+- les couleurs nommées (`red`), les exposants, les unités autres que `px`,
+  `%`, `fr`, `ms`, `s`, `deg` et `turn` ;
+- les caractères hors ASCII, sauf dans les commentaires.
+
+Il n’y a pas de requête média parce qu’il n’y a rien à interroger : la
+taille du widget est celle que lui donne l’utilisateur, et la logique la lit
+dans `host.viewport` quand la vue doit changer avec elle.
+
+## Quand le style est incorrect
+
+| Code | Problème |
+| --- | --- |
+| `style.syntax`, `style.encoding`, `style.size` | Le fichier n’est pas une feuille bien formée. |
+| `style.unsupported` | Une construction CSS hors du sous-ensemble (voir ci-dessus). |
+| `style.unknown_element`, `style.unknown_pseudo_class`, `style.invalid_selector` | Un sélecteur qui ne nomme aucun élément ou aucun état, ou qui est hors du sous-ensemble. |
+| `style.unknown_property`, `style.duplicate_property` | Une propriété hors du sous-ensemble, ou définie deux fois dans une règle. |
+| `style.invalid_value`, `style.unknown_token` | Une valeur que la propriété n’accepte pas, ou un token qui n’existe pas ou qui a un autre type. |
+| `style.not_animatable` | Une transition ou une étape de `@keyframes` sur une propriété qui ne peut pas être animée. |
+| `style.unknown_keyframes`, `style.duplicate_keyframes`, `style.invalid_keyframes` | Une `animation` qui ne nomme aucun bloc, un nom utilisé deux fois, ou un bloc invalide. |
+| `style.too_many_rules`, `style.too_many_selectors`, `style.too_many_compounds`, `style.too_many_simple_selectors`, `style.too_many_declarations`, `style.too_many_keyframes`, `style.too_many_stops` | Une [limite](limits.md) du style est dépassée. |
+
+Un nom inconnu est signalé avec, en suggestion, le nom le plus proche du
+schéma. Chaque propriété, ses valeurs et sa valeur initiale figurent dans
+[propriétés de style et tokens](style-properties.md).