Integration Standards — extension VS Code pour les templates
|
| Fonctionnalité | Réglage | Défaut | Rôle |
|---|---|---|---|
| Lint live | ftIntegrationStandards.features.lint |
🟢 activé | Souligne les écarts de convention en temps réel |
| Reformatage global | ftIntegrationStandards.features.format |
🟢 activé | Reformate le fichier entier (tri des objets, indentation, espacement, reflow) |
| Conversion Fractal → macro | ftIntegrationStandards.features.dsConverter.convertOnSave |
⚪ opt-in | {% component '@x' %} → {{- ds.x(…) -}} |
| FT Tokens (Figma → var CSS) | commandes/raccourcis (pas de réglage) | — | Colle une variable Figma convertie en var(--ft-…) |
Un interrupteur transverse — ftIntegrationStandards.enable — désactive le moteur de lint,
formatage et conversion, sans retirer le langage et sa coloration.
Chaque fonctionnalité a ensuite son propre réglage. Voir Réglages.
FT Tokens — coller une variable Figma en variable CSS France Travail
Un intégrateur copie le nom d'une variable depuis Figma (ex. Color/Decorative/blue-weaker) et
l'insère dans un .scss/.css sans conversion manuelle. Deux commandes (toujours actives,
indépendantes des réglages) lisent le presse-papier, transforment, et insèrent au curseur (en
remplaçant la sélection éventuelle) :
| Commande | Insère | Raccourci |
|---|---|---|
Coller la variable Figma en var(--ft-…) (ftTokens.pasteAsVar) |
var(--ft-color-decorative-blue-weaker) |
Cmd+Alt+V |
Coller la variable Figma en nom --ft-… (ftTokens.pasteAsName) |
--ft-color-decorative-blue-weaker |
Cmd+Alt+Shift+V |
- Transformation : minuscules ; chaque run de
/ou d'espaces →-; tirets internes préservés (blue-weaker,spacer-16) ; retrait des-de début/fin ; préfixe--ft-. - Presse-papier vide / non convertible → rien inséré + message d'info.
- Idempotent : une entrée déjà
--ft-…ouvar(…)est laissée telle quelle. - Raccourcis scopés aux langages
scss/css/sass/less(la commande reste disponible via la palette partout). Reprend le namespace--ft-du snippet historique.vscode/ft-tokens.code-snippets— mais, contrairement à un snippet, l'extension embarque le raccourci partagé.
Conversion Fractal → macro (opt-in)
- Conversion pure : retire le wrapper
params:(et dé-indente d'un niveau), remplace{% component %}par{{- ds.macro(…) -}}, et préserve la mise en page de l'auteur (un objet multi-ligne reste multi-ligne). Aucun autre reformatage ; un fichier sans{% component %}reste byte-identique. - Au save : désactivé par défaut (opt-in) — il faut passer
convertOnSaveàtrueet que l'extension soit le formateur des[nunjucks](voir l'astuce en bas des Réglages). - À la demande (toujours actif, indépendant des réglages) :
- Cmd+Alt+D — convertit la sélection dans l'éditeur ;
- clic droit sur un fichier
.njkou un dossier (dans l'explorateur, section dédiée « Convertir les {% component ... %} en macro DS ») → convertit ce fichier, ou en lot tous les.njkdu dossier.
- Intelligence de conversion : camelCase des variantes (
@button--icon→ds.buttonIcon), injection des paramètres manquants depuis les*.config.jsdu design-system, whitelist des macros DS existantes, blacklist des composants non équivalents (ex.@radio), alias de renommage, marqueurs de trim systématiques{{- … -}}. Idempotente. - Fonctionnalité temporaire de migration (destinée à disparaître une fois la migration finie).
Lint live (activé par défaut)
Analyse en temps réel — au fil de la frappe (debounce 250 ms), à l'ouverture et à la sauvegarde
— et souligne. Survoler le souligné affiche un message qui décrit directement le problème.
Chaque message commence par une catégorie explicite (Formatage, Convention, Syntaxe Nunjucks, Structure HTML ou Maintenabilité). Les identifiants internes des règles ne sont pas
affichés dans les diagnostics, et le nom de l'extension n'est pas répété à côté du message. Les
noms d'attributs et d'arguments cités sont présentés entre guillemets, par exemple
l'attribut "class".
Le niveau de chaque règle traduit l'effort de correction, pas une gravité abstraite :
🔴 erreur — casse le build ou le rendu ;
🟠 avertissement — le formateur le corrige tout seul (⇧⌥F ou à la sauvegarde) ;
🔵 information — demande une décision humaine (refonte, migration à coordonner). Ces règles restent listées dans le panneau Problems mais ne colorent pas le nom du fichier dans l'explorateur : pas de pression sur ce qui ne peut pas être corrigé dans l'immédiat.
format— littéral d'objet ou de tableau mal formaté, catégorisé pour un message précis, souligné pointé sur le caractère fautif :formatOrder— propriétés d'objet non classées par ordre alphabétique ;formatSpacing— espace en trop/manquant autour de:,,ou des accolades ;formatIndent— indentation (4 espaces par niveau) ;formatStructure— mise en ligne (élément unique à condenser / objet à éclater) ;format— écarts mixtes (repli).
camelCase— clé d'argument de macro non camelCase (jamais auto-renommé : le contrat de la macro prime ; safelist pour les snake_case légitimes).missingComma— 🔴 erreur : virgule oubliée entre deux propriétés d'un objet multi-ligne (ex. appel de macro), qui casserait le build Nunjucks.orphanTag— 🔴 erreur : balise laissée orpheline, c'est-à-dire encore ouverte quand une balise englobante se ferme (ex.<li><a href="#">Texte</li>). Le navigateur devine alors où l'élément se termine : le balisage suivant est avalé par le mauvais élément, et la mise en page, les sélecteurs CSS et les requêtes DOM cassent silencieusement, différemment selon les navigateurs. (Inspiré deH025de djlint.) ⚠️ Aucune tolérance pour les « fermetures optionnelles » de HTML (</li>,</p>,</td>,</option>…) : décision d'équipe, toute balise ouverte doit être fermée explicitement — la spec ne les autorise que selon la balise qui suit, ce que personne ne retient et qui rend la relecture ambiguë.unmatchedClose— 🔴 erreur : une balise fermante sans ouvrante correspondante à l'intérieur d'un{% block %}(fermeture en trop, ou balise mal nommée — ex. un</a>qui prétend fermer un<button>). Un{% block %}est auto-contenu : ce qui y est fermé doit y avoir été ouvert. En dehors d'un block, rien n'est signalé — un partial peut légitimement fermer un wrapper ouvert dans un autre fichier.FT001— Maintenabilité : l'attribut"class"contient plus de 5 classes ; envisager un composant réutilisable ou une classe CSS dédiée. Deux formes :class="a b c d e f"littéral, et une string de 6+ classes dans un| joinClasses.
Reformatage global (activé par défaut)
Reformate le fichier entier via Format Document (⇧⌥F) ou au save (si
editor.formatOnSave). Le formatage est idempotent et ne modifie jamais le contenu des chaînes
ni l'ordre des tableaux.
- formatSource — littéraux d'objets et de tableaux : propriétés d'objet classées
récursivement par ordre alphabétique, sans tenir compte de la casse ni des guillemets ;
collapse à ≤ 1 élément, objet-valeur toujours multi-ligne, espacement
clé: valeuret,. Tout objet contenant au moins 2 propriétés devient multi-ligne, sauf dans un attribut HTML ou au milieu d'une ligne de texte courant (<p>,<span>,<a>…), où il reste compact (trié) pour ne pas modifier les espaces visibles. Les retours des autres objets sont placés à l'intérieur de l'expression. Un objet utilisé comme collection sera parcouru dans cet ordre alphabétique ; - reflow — structure HTML : contenu inline vs bloc éclaté, jointures des délimiteurs
{{ }}/{% %}; - normalizeSpacing — espace intérieur (façon WordPress « Space Usage ») : après
{{{{-{%{%-, avant}}-}}%}-%}(ex.{{data.tag}}→{{ data.tag }}), et de chaque côté du pipe de filtre|(x|upper→x | upper). Crochets[ ]selon la règle WP « Array Members » : littéral de tableau et index variable espacés ([ 'a', b ],x[ i ]), index littéral collé (x['bar'],x[0]). Parenthèses( )non touchées ; - reindent — indentation de chaque ligne selon l'imbrication (4 espaces), y compris les
branches
case/defaultd'unswitchet leur contenu.
Pour utiliser ce formateur par défaut sur les
.njk, régler dans les settings du workspace :"[nunjucks]": { "editor.defaultFormatter": "ft-integration.standards" }.
Réglages
Un interrupteur maître, puis un réglage par fonctionnalité.
| Réglage | Défaut | Effet |
|---|---|---|
ftIntegrationStandards.enable |
true |
Interrupteur maître du moteur. Le langage et sa coloration restent disponibles. |
ftIntegrationStandards.features.lint |
true |
Lint live. À false, plus de soulignés. |
ftIntegrationStandards.features.format |
true |
Reformatage global (⇧⌥F / au save). À false, plus de reformatage. |
ftIntegrationStandards.features.dsConverter.convertOnSave |
false |
Opt-in. À true, convertit {% component %} → {{- ds.* -}} à la sauvegarde. Les commandes manuelles restent actives quel que soit ce réglage. |
Désactivation perso sans impacter l'équipe : mettre le réglage à
falsedans vos User Settings globaux (jamais poussés), pas dans le.vscode/settings.jsonversionné.
Portée par dossier : ces réglages se résolvent par fichier. Dans un workspace multi-racine, chaque dossier peut donc avoir son propre
.vscode/settings.json— les fichiers d'une racine où le moteur est désactivé ne sont plus traités, les autres gardent le comportement par défaut.
Conversion : par défaut rien ne se passe côté conversion à la sauvegarde (opt-in). Si tu actives
convertOnSave, alors seuls les{% component %}sont convertis ; tout le reste du fichier reste byte-identique. Dans tous les cas, la conversion reste disponible à la demande via Cmd+Alt+D et le clic droit sur un fichier.njkou un dossier.
Configuration des règles
La config est entièrement embarquée dans l'extension et uniforme : il n'y a pas de fichier de config par projet ni par workspace, et rien à paramétrer côté dépôt. Les règles appliquées sont celles décrites ci-dessus ; seuls les réglages du tableau précédent permettent d'activer ou de désactiver une fonctionnalité.
Notes techniques
- Aucune dépendance npm (API
vscodeuniquement, fournie à l'exécution). - Débounce 250 ms à la frappe ; analyse aussi à l'ouverture et à la sauvegarde.
- Langage détecté via
languageId === 'nunjucks'ou l'extension de fichier.njk. - Résilience : chaque module du moteur est chargé isolément — un module cassé ne désactive que SA fonctionnalité, l'extension s'active toujours.