brandvm/webflow-style-guide

Guide de style Webflow : une mise en page, chaque site

Le guide de style est la première page construite dans le prototype et la première page construite dans Webflow, avant toute autre page. Il valide les variables, les styles de balises et les classes avant que quoi que ce soit ne dépende d'eux, et il contient chaque classe sur un élément, ainsi le Nettoyage des styles inutilisés de Webflow ne peut jamais supprimer une classe que seul le CMS, un script ou une page non construite utilise.

Sa mise en page est fixe. Un projet fournit le contenu, jamais la mise en page :

• sg.css est la mise en page propre à la page (les classes Sg).
• scripts/gen-style-guide.mjs écrit la page à partir de l'instantané Webflow, du CSS et des échantillons du projet.
• scripts/check-style-guide.mjs échoue lorsqu'une classe manque sur la page, que les classes d'une combinaison ne se trouvent jamais ensemble sur un élément, ou que la mise en page a dérivé.
• scripts/sections.mjs est la liste des sections que les deux scripts partagent.
• Chaque échantillon de typographie porte data-sg-type (son nom), afin que le pnpm measure:type du prototype puisse imprimer le type tel qu'affiché à 1440 et 390 (taille, hauteur de ligne, crénage, graisse) pour comparer avec la feuille de type du design avant que les classes n'aillent dans Webflow.

Les règles partagées s'appliquent (webflow-build › rules.md : Designer en premier, pas de commit ou de push sans un OK), et dans Webflow les propres règles du build : un feu vert avant chaque lot.

La mise en page

Cadre. Une barre latérale collante à gauche liste les sections, numérotées, avec des liens vers celles-ci ; la section en cours de lecture est mise en surbrillance. Une colonne de contenu à droite. À 991 px et en dessous, la barre latérale devient une bande de liens sous la navigation qui défile horizontalement.

Écrite pour quelqu'un de nouveau. La page doit avoir un sens pour une personne qui n'a jamais vu le site : un client, ou un développeur à son premier jour.

• Aperçu s'ouvre sur ce qu'est la page, quatre cartes sur comment l'utiliser (la trouver, lire une ligne, réutiliser avant d'ajouter, ajouter ici), le site en un coup d'œil (compteurs), ses polices, ses collections de variables et les points de rupture.
• Chaque section commence par son numéro, son titre et une ligne indiquant à quoi elle sert et comment l'utiliser (le texte se trouve dans scripts/sections.mjs, le même sur chaque site).
• Les échantillons de boutons, formulaires et composants reposent sur un panneau ; les noms de classes sont dans une pastille ; les longs tableaux gardent leur nom visible pendant qu'ils défilent.
• Chaque étiquette utilise la police propre du site. Pas de monospace : une classe Designer contient une seule famille de polices, et une police monospace système apporte son propre zéro barré.
• Le cadre prend ses couleurs de la page (lignes neutres et panneaux à faible opacité), afin qu'il se lise de la même manière sur un site clair ou sombre.

Sections, toujours dans cet ordre, avec ces noms et ces identifiants. Une section vide est omise ; rien n'est ajouté, renommé ou réorganisé.

#	Section	id	Provient de
1	Aperçu	overview	généré : comment utiliser la page, compteurs, polices, collections, points de rupture
2	Couleurs	colors	chaque variable de couleur en dehors des Couleurs sémantiques
3	Thèmes	themes	Section, chaque classe qui définit un mode Couleurs sémantiques, et le tableau des rôles par mode
4	Typographie	typography	chaque classe qui définit un mode Styles de typographie, les styles de balises natives (titres, paragraphes, liens), les caractéristiques de police du style Body, et l'échelle typographique
5	Utilitaires	utilities	classes Taille, Graisse, Interlignage, Crénage, Texte et Largeur max
6	Espacement, rayon et mise en page	spacing	les variables d'Espacement (chacune avec une barre de sa taille), de Rayon et de Mise en page
7	Boutons et liens	buttons	échantillons
8	Formulaires	form-elements	échantillons (les éléments utilisent section=forms ; Webflow refuse forms comme identifiant d'élément)
9	Composants	components	échantillons
10	Sections de page	page-sections	échantillons, affichés en taille moitié
11	Autres classes	other-classes	généré : chaque classe à laquelle rien ci-dessus ne s'applique

La ligne. Chaque élément de la page est une Sg Row : à gauche son nom tel que le Designer le montre, sa classe CSS, et une note en termes simples (à quoi elle se lie, ses valeurs par point de rupture, ses états) ; à droite l'échantillon en direct. Une section est un titre et une liste de lignes. Les tableaux de valeurs (rôles par mode, l'échelle typographique, l'espacement, la mise en page) se trouvent dans l'échantillon d'une ligne sous la forme d'un Sg Table : la colonne du nom, puis une colonne par mode ou valeur.

Aucune classe du projet dans le cadre. Le cadre utilise uniquement les classes Sg, donc la page se présente de la même manière quelle que soit l'échelle typographique ou le remplissage de section d'un projet. Les classes du projet apparaissent dans les échantillons.

Les variables sont une norme, pas une limite

La page affiche ce que le site possède. Les collections, noms et valeurs de départ du modèle (webflow-build conventions §4, y compris Geist comme police par défaut) sont la mise en page standard et la manière d'utiliser les variables ; un projet est libre de modifier les valeurs et d'ajouter, renommer ou supprimer des variables, des modes et des collections.

• Toute variable de couleur en dehors de la collection sémantique est un nuancier ; toute classe qui définit un mode est une ligne de thème ou de type ; toute collection que le générateur ne connaît pas par rôle est affichée sous forme de tableau sous « Espacement, rayon et mise en page ».
• Un site qui nomme les collections standard différemment le dit dans design/style-guide/config.json, par exemple { "collections": { "semantic": "Thèmes", "typeStyles": "Styles de type" } } (clés : semantic, typeStyles, typeRole, typeScale, spacing, radius, layout).
• Ce qui reste fixe est la mise en page : le cadre, l'ordre des sections, la ligne.

Échantillons (sections 7 à 10)

Deux façons d'en fournir un ; les deux produisent la même ligne.

1. Depuis une page réelle, afin qu'il reste en phase avec elle. Encadrez le balisage sur la page :

<!-- sg:start section=components | name=Carte | class=.card | note=Utilisé dans les listes et sur la page d'accueil -->
<a class="card" href="/work/item" data-card>…</a>
<!-- sg:end -->

2. À la main, pour ce qu'aucune page n'affiche seule (états de bouton, parties de formulaire). Un fichier par section dans design/style-guide/items/, chaque élément étant un commentaire d'en-tête suivi de son balisage :

<!-- sg: section=buttons | name=Button Is Secondary | class=.button.is-secondary | note=Combinaison sur Button -->
<a class="button is-secondary" href="#buttons">Secondaire</a>

• section est buttons, forms, components ou page-sections ; name est requis ; class et note sont optionnels.
• Préférez un bloc de page réelle pour les composants et les sections de page. Un échantillon copié à la main dérive de la page, et sur les builds antérieurs, les composants construits à partir d'aperçus copiés à la main avaient perdu leurs accroches de script.
• Le générateur supprime les identifiants, for, les accroches data-* et les références d'identifiant d'un échantillon et le marque inert : c'est une image du composant, pas une copie fonctionnelle, donc aucun script ne s'attache et rien ne prend le focus.
• La page est noindex, donc un second h1 sur elle est acceptable : la section Typographie montre un vrai comme échantillon du style de balise Tous les H1, et un échantillon peut en contenir un.
• Un échantillon page-sections est affiché à moitié taille dans un cadre scellé. Supprimez-le une fois que sa page existe dans Webflow : la page conserve alors ses classes. Les sections 1 à 9 restent pour de bon.
• Pas d'attributs style en ligne : l'importateur Webflow transforme chacun en une classe de combinaison indésirable. Les nuanciers de couleur, les boîtes de rayon et les barres d'espacement utilisent chacun une combinaison générée par variable à la place.

Dans le prototype (première page)

1. Le dossier du prototype existe (webflow-prototype › Configuration du projet) et son instantané Webflow est à jour (pnpm css).
2. pnpm style-guide. Il écrit design/style-guide/index.html et src/css/style-guide.css. Ne les modifiez jamais.
3. Ajoutez les échantillons du projet (éléments de bouton et de formulaire ; blocs de composant et de page au fur et à mesure que les pages sont construites) et exécutez-le à nouveau.
4. pnpm check:style-guide jusqu'à ce qu'il réussisse.
5. La personne examine la page à 1440, 820, 667 et 390 et l'approuve avant que la première page de contenu ne soit commencée.
6. À partir de là, chaque nouvelle classe ou composant obtient sa ligne dans le même lot de travail : ajoutez l'échantillon, pnpm style-guide, pnpm check:style-guide.

Dans Webflow (première page)

Après l'ajout des variables, styles de balises, classes et du bundle du dépôt, et avant toute autre page. Un feu vert par lot.

1. Page. /design/style-guide dans le dossier design, sur le shell standard (webflow-build conventions §1). noindex, nofollow dans le code head de la page ; exclue de la recherche du site et du plan de site (le paramètre de plan de site nécessite un plan de site : sur un site sans plan, la balise noindex est ce qui la maintient hors de la recherche, et l'exclusion est définie une fois le plan existant) ; les liens vers celle-ci effectuent un chargement complet de la page.
2. Classes Sg. Un site dupliqué à partir du starter les possède déjà. Sinon, le moyen le plus rapide qui conserve chaque valeur : importez le cadre avec le constructeur WHTML et passez sg.css comme son css (les variables et calc() remplacées par des valeurs simples, rgb(r g b / a) écrit comme rgba()). L'importateur crée chaque classe avec des propriétés longues, des états et des points de rupture, nommés par son slug ; renommez chacun ensuite avec le nom que le Designer doit afficher (Sg Row, Sg Row Meta, Sg Table Key…). Les règles .w--current deviennent l'état Current de Sg Sidebar Link, que l'outil de style lui-même ne peut pas écrire. Cela ne fonctionne que lorsque la classe est nouvelle : pour une classe qui existe déjà, l'importateur crée un doublon numéroté (webflow-build/lessons/mcp.md).
3. Combinaisons de variables. Pour chaque variable de couleur, la combinaison Sg Swatch Color + Is … liant background-color ; pour chaque variable de rayon, Sg Radius + Is … liant border-radius ; pour chaque variable d'espacement, Sg Bar + Is … liant width. Le fichier généré src/css/style-guide.css les liste, une par ligne.
4. Construisez section par section à partir de la page générée, avec des classes uniquement. Créez chaque classe et combinaison avant d'importer le balisage (l'importateur supprime une liste de classes entière si une classe manque). Ensuite, pointez chaque lien de la barre latérale vers sa section (type de lien : section de page), afin que Webflow marque la section en cours.
5. Les lignes pour les composants sont des instances de composant, pas des copies de leur balisage.
6. Vérifiez sur l'environnement de préproduction : chaque classe du site apparaît sur la page publiée ou dans le shell, et chaque combinaison sur un élément (une combinaison dont les classes n'apparaissent que séparément est toujours supprimée par le nettoyage) ; la barre latérale met en surbrillance la section en vue ; noindex est dans le head. Ce n'est qu'alors que le Nettoyage des styles inutilisés est sûr.

Sur un site existant

Un site non construit à partir du modèle peut obtenir la même page : créez un dossier prototype à partir du starter de prototype du skill webflow-prototype, prenez l'instantané du site, puis suivez « Dans le prototype » et « Dans Webflow ». Ses classes Sg n'existeront pas encore ; créez-les à l'étape 2.

Portes

• Guide de style du prototype approuvé [Personne] : avant la première page de contenu du prototype.
• Base du guide de style terminée [Claude vérifie, Personne approuve] : la page Webflow contient chaque classe qui existe à ce jour ; publiée et vérifiée à trois largeurs.
• Vérification finale du guide de style [Claude vérifie] : lors de la remise du build, pnpm check:style-guide réussit et la page publiée contient chaque classe.

Modifier la mise en page

La mise en page change ici, pour chaque site en une fois, jamais dans un seul projet : modifiez sg.css, la liste des sections ou le générateur dans le modèle, mettez à jour le site starter dans le même lot de travail, et publiez-le (webflow-build › rules.md › Contribuer). Les projets reçoivent la mise à jour avec pnpm update-skills et pnpm style-guide.