Forme DS

Adoption

Agents & runtime

Un agent qui écrit du code d'interface Forme® doit connaître un petit noyau de faits : quel paquet, quels imports, quel registre, quelles règles. Ces faits vivent dans un fichier llms.txt — la source de vérité DS pour agents. Cette page explique à quoi il sert et montre un extrait à jour pour le DS 2.0.

Le fichier llms.txt

llms.txt est un résumé condensé, lisible par un modèle, de tout ce qu'il faut savoir pour rester dans la ligne : installation, règle d'or, inventaire des composants avec leur intention, tokens, doctrine, et les pièges à éviter. Un agent le charge avant de générer du code d'UI ; il y trouve la bonne primitive pour une intention donnée plutôt que de réinventer un composant.

Attention à l'ancienne version. Le llms.txt legacy décrit @forme/ui v1 (React-Aria, registry.forme.ch). Ce socle est périmé. N'utilise que les faits DS 2.0 ci-dessous.

Les faits DS 2.0 qu'un agent doit connaître

  • Paquet composants : @forme-ch/ui (couche Forme sur Astryx).
  • Socle : @astryxdesign/core ; tokens & polices : @forme-ch/design-system.
  • Registre : GitHub Packages (npm.pkg.github.com), scope @forme-ch, token PAT read:packages.
  • Imports : contrôles depuis @forme-ch/ui/controls, icônes depuis @forme-ch/ui/icons, shell depuis @forme-ch/ui/shell.
  • CSS (ordre) : reset Astryx → astryx → design-system ; puis data-astryx-theme="forme".
  • Doctrine : source unique, API label, tokens obligatoires, jamais de CSS de composant dans une app.

Extrait llms.txt — cible DS 2.0

Modèle réécrit pour le socle actuel (format legacy conservé, contenu à jour) :

# Forme® Design System — llms.txt
> Source de vérité DS pour agents. Socle = Astryx (@astryxdesign/core) + charte Forme.
> Couche composants = @forme-ch/ui 2.5.0. Tokens & polices Aeonik = @forme-ch/design-system.
> Registre : GitHub Packages (npm.pkg.github.com, scope @forme-ch). Peers : react/react-dom >=19.
> L'ancien @forme/ui v1 (React-Aria, registry.forme.ch) est ABANDONNÉ.

## Installer
.npmrc:
  @forme-ch:registry=https://npm.pkg.github.com
  //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}   # PAT GitHub, read:packages
npm install @forme-ch/ui @forme-ch/design-system @astryxdesign/core
CSS (ordre strict):
  import "@astryxdesign/core/reset.css";
  import "@astryxdesign/core/astryx.css";
  import "@forme-ch/design-system/css/index.css";
Thème: poser data-astryx-theme="forme" haut dans l'arbre (ex. <html>).
Sous-chemins: @forme-ch/ui/controls (contrôles) · @forme-ch/ui (shell/lockups/icons/layout/date)
  · @forme-ch/ui/icons (Lucide RSC-safe) · @forme-ch/ui/shell.

## Règle d'or
Tout composant d'UI vient de @forme-ch/ui, JAMAIS dupliqué ni bricolé dans une app.
Chaque composant enrobe son équivalent Astryx sous l'API Forme : on hérite de l'a11y et du
comportement d'Astryx, on impose la charte et le vocabulaire Forme par-dessus. Lacune du socle
→ on fait évoluer le paquet, jamais du CSS d'app. Quand Forme diverge d'Astryx, Astryx l'emporte.

## Accessibilité
API label alignée sur Astryx : nom accessible garanti et découplé du visuel. Tout contrôle
icône seule exige label (IconButton l'impose). Glyphe texte ×/✕ banni → icône Lucide + label.

## Tokens (règles fermes)
Source unique = @forme-ch/design-system. JAMAIS de #hex en dur (var(--color-*), light-dark()).
Échelle typo : 10/11/12/13/14/16/18/20/28/48 — 15px INTERDIT (→ var(--fs-body)).
Radius via tokens (--radius-inner/element/container ; 50%/9999px réservé aux cercles purs).
Bloc teinté = fond color-mix + filet 1px complet ; PAS de border-left décorative.

## Surfaces
Admin · AI · Space · Frame partagent les MÊMES composants et tokens. La parité est un effet
mécanique de la source unique : ne pas la casser en réintroduisant du composant/CSS par-app.
Un agent conforme est un agent qui consomme. Il importe depuis @forme-ch/ui, référence des tokens, passe un label, et n'écrit jamais de CSS de composant. Les mêmes règles que pour un humain — voir Conformité.