brandvm/webflow-style-guide

Guía de estilos Webflow: un diseño, cada sitio

La guía de estilos es la primera página que se construye en el prototipo y la primera página que se construye en Webflow, antes que cualquier otra página. Verifica que las variables, los estilos de etiqueta y las clases estén correctos antes de que algo dependa de ellos, y contiene cada clase en un elemento, de modo que Clean up unused styles de Webflow nunca pueda eliminar una que solo use el CMS, un script o una página no construida.

Su diseño es fijo. Un proyecto proporciona el contenido, nunca el diseño:

• sg.css es el diseño propio de la página (las clases Sg).
• scripts/gen-style-guide.mjs escribe la página a partir de la captura de Webflow, el CSS y los especímenes del proyecto.
• scripts/check-style-guide.mjs falla cuando una clase falta en la página, las clases de un combo nunca están juntas en un elemento, o el diseño se ha desviado.
• scripts/sections.mjs es la lista de secciones que ambos scripts comparten.
• Cada espécimen de tipografía lleva data-sg-type (su nombre), de modo que pnpm measure:type del prototipo pueda imprimir el tipo renderizado a 1440 y 390 (tamaño, interlineado, tracking, peso) para compararlo con la hoja de tipos del diseño antes de que las clases vayan a Webflow.

Se aplican las reglas compartidas (webflow-build › rules.md: Diseñador primero, no hacer commit ni push sin un OK), y en Webflow las propias de la compilación: un visto bueno antes de cada lote.

El diseño

Marco. Una barra lateral fija a la izquierda lista las secciones, numeradas, como enlaces hacia ellas; la sección que se está leyendo está resaltada. Una columna de contenido a la derecha. A 991px y menos, la barra lateral se convierte en una tira de enlaces debajo de la navegación que se desplaza horizontalmente.

Escrito para alguien nuevo. La página debe tener sentido para una persona que nunca ha visto el sitio: un cliente o un desarrollador en su primer día.

• La sección de Descripción general comienza con qué es la página, cuatro tarjetas sobre cómo usarla (encontrarla, leer una fila, reutilizar antes de añadir, añadir aquí), el sitio de un vistazo (conteos), sus fuentes, sus colecciones de variables y los puntos de quiebre.
• Cada sección comienza con su número, su título y una línea que dice para qué sirve y cómo usarlo (el texto está en scripts/sections.mjs, el mismo en cada sitio).
• Los especímenes de botones, formularios y componentes se colocan en un panel; los nombres de clase se colocan en un chip; las tablas largas mantienen su nombre visible mientras se desplazan.
• Cada etiqueta usa la fuente del propio sitio. Sin monoespacio: una clase de Designer contiene una familia de fuentes, y una fuente monoespacio del sistema trae su propio cero barrado.
• El marco toma sus colores de la página (líneas neutras y paneles con baja opacidad), de modo que se lee igual en un sitio claro u oscuro.

Secciones, siempre en este orden, con estos nombres e ids. Una sección sin nada se omite; no se añade, renombra ni reordena nada.

#	Sección	id	Origen
1	Descripción general	overview	generado: cómo usar la página, conteos, fuentes, colecciones, puntos de quiebre
2	Colores	colors	cada variable de Color fuera de Colors Semantic
3	Temas	themes	Sección, cada clase que establece un modo de Colors Semantic, y la tabla de roles por modo
4	Tipografía	typography	cada clase que establece un modo de Typography Styles, los estilos de etiqueta nativos (encabezados, párrafos, enlaces), las características de fuente del estilo Body y la escala tipográfica
5	Utilidades	utilities	clases Size, Weight, Leading, Tracking, Text y Max Width
6	Espaciado, radio y diseño	spacing	las variables Spacing (cada una con una barra de su tamaño), Radius y Layout
7	Botones y enlaces	buttons	especímenes
8	Formularios	form-elements	especímenes (los elementos usan section=forms; Webflow rechaza forms como id de elemento)
9	Componentes	components	especímenes
10	Secciones de página	page-sections	especímenes, mostrados a media pantalla
11	Otras clases	other-classes	generado: cada clase que no aplica en lo anterior

La fila. Cada elemento de la página es una Sg Row: a la izquierda su nombre como lo muestra el Designer, su clase CSS y una nota en palabras simples (a qué se vincula, sus valores por punto de quiebre, sus estados); a la derecha el espécimen en vivo. Una sección es un encabezado y una lista de filas. Las tablas de valores (roles por modo, escala tipográfica, espaciado, diseño) se colocan en el espécimen de una fila como una Sg Table: la columna de nombre, luego una columna por modo o valor.

Ninguna clase de proyecto en el marco. El marco usa solo clases Sg, de modo que la página se ve igual independientemente de la escala tipográfica o el relleno de sección de un proyecto. Las clases de proyecto aparecen en los especímenes.

Las variables son un estándar, no un límite

La página muestra lo que tenga el sitio. Las colecciones, nombres y valores iniciales de la plantilla (webflow-build convenciones §4, incluyendo Geist como la fuente predeterminada) son el diseño estándar y la forma de usar las variables; un proyecto puede cambiar valores y añadir, renombrar o eliminar variables, modos y colecciones.

• Cualquier variable de Color fuera de la colección semántica es una muestra; cualquier clase que establezca un modo es una fila de tema o tipo; cualquier colección que el generador no reconozca por rol se muestra como una tabla bajo "Espaciado, radio y diseño".
• Un sitio que nombre las colecciones estándar de manera diferente lo indica en design/style-guide/config.json, por ejemplo { "collections": { "semantic": "Temas", "typeStyles": "Estilos de tipo" } } (claves: semantic, typeStyles, typeRole, typeScale, spacing, radius, layout).
• Lo que permanece fijo es el diseño: el marco, el orden de las secciones, la fila.

Especímenes (secciones 7 a 10)

Dos formas de proporcionarlos; ambas producen la misma fila.

1. Desde una página real, para que se mantenga alineado con ella. Encierra el marcado en la página:

<!-- sg:start section=components | name=Tarjeta | class=.card | note=Se usa en listas y en la página de inicio -->
<a class="card" href="/work/item" data-card>…</a>
<!-- sg:end -->

2. A mano, para lo que ninguna página muestra por sí sola (estados de botón, partes de formulario). Un archivo por sección en design/style-guide/items/, cada elemento un comentario de encabezado seguido de su marcado:

<!-- sg: section=buttons | name=Botón Es Secundario | class=.button.is-secondary | note=Combo en Button -->
<a class="button is-secondary" href="#buttons">Secundario</a>

• section es buttons, forms, components o page-sections; name es obligatorio; class y note son opcionales.
• Prefiere un bloque de página real para componentes y secciones de página. Un espécimen copiado a mano se desvía de la página, y en compilaciones anteriores los componentes construidos a partir de vistas previas copiadas manualmente perdieron sus enlaces de script.
• El generador elimina ids, for, ganchos data-* y referencias a ids de un espécimen y lo marca como inert: es una imagen del componente, no una copia funcional, por lo que ningún script se adjunta y nada en él recibe foco.
• La página tiene noindex, por lo que un segundo h1 está permitido: la sección de Tipografía muestra uno real como espécimen del estilo de etiqueta All H1 Headings, y un espécimen puede contener uno.
• Un espécimen de page-sections se muestra a mitad de tamaño en un marco sellado. Elimínalo una vez que su página exista en Webflow: la página entonces conserva sus clases. Las secciones 1 a 9 se quedan para siempre.
• Sin atributos style en línea: el importador de Webflow convierte cada uno en una clase combo basura. Las muestras de color, los cuadros de radio y las barras de espaciado usan un combo generado por variable.

En el prototipo (primera página)

1. La carpeta del prototipo existe (webflow-prototype › Configuración del proyecto) y su captura de Webflow está actualizada (pnpm css).
2. pnpm style-guide. Escribe design/style-guide/index.html y src/css/style-guide.css. Nunca edites ninguno.
3. Añade los especímenes del proyecto (elementos de botón y formulario; bloques de componente y página a medida que se construyen las páginas) y ejecútalo de nuevo.
4. pnpm check:style-guide hasta que pase.
5. La persona revisa la página a 1440, 820, 667 y 390 y la aprueba antes de que se inicie la primera página de contenido.
6. A partir de entonces, cada nueva clase o componente obtiene su fila en el mismo trabajo: añade el espécimen, pnpm style-guide, pnpm check:style-guide.

En Webflow (primera página)

Después de que las variables, estilos de etiqueta, clases y el paquete del repositorio estén listos, y antes que cualquier otra página. Un visto bueno por lote.

1. Página. /design/style-guide en la carpeta design, en el shell estándar (webflow-build convenciones §1). noindex, nofollow en el código del encabezado de la página; excluida de la búsqueda del sitio y del mapa del sitio (la configuración del mapa del sitio necesita un plan de sitio: en un sitio sin uno, la etiqueta noindex es lo que lo mantiene fuera de la búsqueda, y la exclusión se establece una vez que el plan existe); los enlaces hacia ella cargan la página completa.
2. Clases Sg. Un sitio duplicado del iniciador ya las tiene. De lo contrario, la forma más rápida que conserva todos los valores: importar el marco con el constructor WHTML y pasar sg.css como su css (variables y calc() reemplazados por valores simples, rgb(r g b / a) escrito como rgba()). El importador crea cada clase con propiedades completas, estados y puntos de quiebre, nombradas por su slug; renombra cada una después al nombre que el Designer debe mostrar (Sg Row, Sg Row Meta, Sg Table Key…). Las reglas .w--current se convierten en el estado Current de Sg Sidebar Link, que la propia herramienta de estilo no puede escribir. Esto solo funciona mientras la clase sea nueva: para una clase que ya existe, el importador crea un duplicado numerado (webflow-build/lessons/mcp.md).
3. Combos de variables. Para cada variable de color, el combo Sg Swatch Color + Is … vinculando background-color; para cada variable de radio, Sg Radius + Is … vinculando border-radius; para cada variable de espaciado, Sg Bar + Is … vinculando width. El generado src/css/style-guide.css los lista, uno por línea.
4. Construye sección por sección a partir de la página generada, solo con clases. Crea cada clase y combo antes de importar el marcado (el importador descarta toda la lista de clases si falta una clase). Luego apunta cada enlace de la barra lateral a su sección (tipo de enlace: sección de página), para que Webflow marque la actual.
5. Las filas para componentes son instancias de componente, no copias de su marcado.
6. Verifica en staging: cada clase del sitio aparece en la página publicada o en el shell, y cada combo en un elemento (un combo cuyas clases solo aparecen separadas aún es eliminado por la limpieza); la barra lateral resalta la sección en vista; noindex está en el encabezado. Solo entonces es seguro ejecutar Clean up unused styles.

En un sitio existente

Un sitio no construido desde la plantilla puede obtener la misma página: crea una carpeta de prototipo desde el iniciador de prototipo del skill webflow-prototype, toma la captura del sitio, luego sigue "En el prototipo" y "En Webflow". Sus clases Sg aún no existirán; crea las en el paso 2.

Puertas

• Guía de estilos del prototipo aprobada [Persona]: antes de la primera página de contenido del prototipo.
• Base de la guía de estilos lista [Claude verifica, Persona aprueba]: la página de Webflow contiene cada clase que existe hasta ahora; publicada y verificada en tres anchos.
• Verificación final de la guía de estilos [Claude verifica]: en la entrega de la compilación, pnpm check:style-guide pasa y la página publicada contiene cada clase.

Cambiar el diseño

El diseño se cambia aquí, para cada sitio a la vez, nunca en un solo proyecto: edita sg.css, la lista de secciones o el generador en la plantilla, actualiza el sitio iniciador en el mismo lote de trabajo y publícalo (webflow-build › rules.md › Contributing). Los proyectos lo reciben con pnpm update-skills y pnpm style-guide.