Referencia a estilo

¿Qué hace Referencia a estilo?

Convierte referencias en un estilo para todo el sitio, mostrado en un tablero visual (board.html) y respaldado por una guía de estilo medida (style.md). La apariencia proviene de las referencias; el contenido proviene del tema. Definir un estilo nunca cambia la app o el sitio. Aplicarlo sí lo hace, pero solo cuando el usuario nombre un estilo guardado para usar (ver Aplicar un estilo guardado).

Alinear el estilo una vez, antes de cualquier cambio de página. La guía es la fuente de verdad: construye cada elemento visual a partir de ella, y pon cada corrección primero en ella, para que nada construido a partir de ella se desvíe de lo que viste en el tablero.

Mide, no calcules a ojo. La vista es buena para ver lo que hace una referencia y mala para colores, tamaños y espaciados exactos. Cada valor que muestra una referencia proviene de scripts/measure.py (cualquier otro valor se deriva de esos o se elige, y se indica), y cada muestra del tablero se renderiza y mide de la misma manera con scripts/verify.py hasta que coincida. El tablero sigue siendo visual; los números viven en la guía y el informe.

Empieza suave, luego ajusta. Una referencia es su estilo a máxima concentración, y extender cada rasgo a cada elemento puede exagerarlo. Por eso la primera pasada usa cada rasgo distintivo solo donde hace más trabajo, con sus valores medidos, y el usuario sube o baja rasgos individuales en la revisión. Los cambios de intensidad afectan dónde aparece un rasgo, nunca sus valores medidos.

Cuándo no usarlo

• El usuario quiere una coincidencia exacta con su propio frame de Figma. Construye el frame.
• El proyecto ya tiene un estilo guardado en design/styles/. Aplícalo en su lugar (ver Aplicar un estilo guardado).

Requisitos

Antes del paso 1, ejecuta python3 <este skill>/scripts/doctor.py (en Windows, py -3 en lugar de python3 en todos los casos). Verifica cada dependencia e imprime el comando exacto de instalación para cada una que falte.

• Salida 0: listo.
• Salida 1: faltan paquetes de Python. Muestra al usuario los comandos impresos y espera; nada puede medirse sin ellos.
• Salida 2: el navegador no puede ejecutarse. Ofrece los comandos de instalación impresos. Si el usuario no puede instalarlo, continúa solo con referencias de imágenes (pide capturas de pantalla de sitios en vivo), ejecuta check.py con --unverified y di en la revisión que la precisión del tablero no está probada.
• Sin Python en absoluto (python3 no se encuentra, ni py -3 en Windows): doctor.py no puede ejecutarse. Dile al usuario que el skill necesita Python 3.9 o posterior, desde python.org o el gestor de paquetes de su sistema, y espera. No instales Python tú mismo.

Decisiones

Toma tú mismo cada decisión que necesite la ejecución, y detente solo en: el tablero. El tablero muestra al usuario el estilo completo de un vistazo, para que lo juzgue allí, no como una lista de preguntas por adelantado.

• Decide, no preguntes: qué rasgos tomar y dejar, la intensidad inicial de cada uno, el nombre y slug del estilo, la lista de temas, la dirección cuando las referencias coinciden, y cómo evitar un estilo existente. Registra cada elección en la guía (una fuente chosen: o una fila Tomar/Dejar), para que pueda cambiarse después.
• Pregunta temprano solo cuando no puedas continuar: una referencia no carga o es solo una miniatura, falta una dependencia, o las referencias apuntan a direcciones opuestas (como papel de borrador pálido y plano oscuro) que ni ellas ni el proyecto resuelven. Entonces haz una pregunta corta con las opciones, tu elección primero, y nada más.
• Mantén la parada corta. Los números viven en la guía y verify.md, por lo que el mensaje no lleva tablas ni medidas. Termínalo con este bloque, luego espera:

¿Tu opinión: algo que cambiar?

Tablero: <ruta a board.html> · Precisión: 35 de 35 medidas coinciden (verify.md) Decidido por ti: nombre y slug; los rasgos principales tomados y dejados; la dirección, si había elección Empezado suave: cada rasgo suave y dónde aparece, en pocas palabras

1. Sube o baja un rasgo: nómbralo, por ejemplo "más de la cuadrícula" o "menos rojo"
2. Cambia algo más: di qué
3. Nada: el estilo se guarda tal cual

Usándolo: el estilo está guardado en design/styles/<slug>/. Nómbralo cuando quieras usarlo, por ejemplo "aplica <slug> en todas partes". Hasta entonces la app o el sitio no cambian.

Con una herramienta de pregunta, pregúntalo allí también, comenzando con "Tu opinión". Nada necesita aprobación: cada estilo guardado está listo para usar, y el usuario elige uno por nombre después.

Pasos

1. Ve las referencias, luego mide. Abre cada una: desplázate por sitios en vivo y observa su movimiento. Si una no carga o es solo una miniatura, pide una captura de pantalla. Nunca trabajes desde un título o URL. Guarda una captura de pantalla de cada una en references/, y anota cualquier movimiento que hayas visto. Prefiere PNG: JPEG desvanece las líneas de color finas.

   Luego lee references/measure.md y mide un recorte por cada rasgo que puedas tomar (un encabezado, un botón, una regla, un parche de fondo), todo en una sola ejecución.

2. Lee el proyecto. Haz esto antes de elegir un estilo, para que la dirección ya encaje:

   • Lee design/styles/index.md si existe, para que el nuevo estilo no choque con los anteriores, y anota qué slugs están ocupados.
   • Enumera 4–8 objetos, materiales, procesos, medidas o lugares reales, cada uno con su fuente. Empieza desde la lista de temas compartida del índice. Usa cosas reales, no símbolos del tema, y omite cualquier cosa que no puedas referenciar.
   • Encuentra los tokens del sitio (propiedades personalizadas CSS, clases del framework o variables de Webflow) y cada tipo de componente en uso, como encabezados, botones, tarjetas, figuras, filas de lista, navegación y formularios, con dónde vive cada uno. La guía rediseña su apariencia; su contenido y estructura se mantienen.

3. Lee el estilo. Con varias referencias, lee lo que comparten. Vincula cada rasgo al recorte que lo muestra; esa evidencia va en la guía, no en el chat.

   Tomar: el estilo	Dejar: lo que pertenece a una referencia
   Paleta, carácter tipográfico, línea y forma, superficie, densidad, ritmo, jerarquía, movimiento	Activos, logotipos, texto, diseños de página exactos, detalles únicos

   Dale a cada rasgo Tomar una intensidad, escrita en la columna Intensidad de la guía:

   Intensidad	Donde aparece el rasgo	Usado para
   quiet (suave)	Solo los 1–3 lugares donde hace más trabajo, nombrados	El inicio para cada rasgo distintivo (un color de acento, una fuente decorativa, una textura, un motivo)
   full (completo)	Cada componente al que encaja	El inicio solo para lo que toda página necesita: la superficie de la página, el color del texto y los rasgos que no establecen un estado de ánimo (como esquinas cuadradas)
   strong (fuerte)	Cada componente al que encaja, y con más espacio: más área, un uso destacado	Solo cuando el usuario pide más

   Bajar un rasgo suave significa moverlo a la columna Dejar.

   Decide el estilo tú mismo (ver Decisiones): elige los rasgos, un nombre cuyo slug no esté ocupado (a menos que el usuario haya pedido revisar ese estilo), y una dirección que no choque con un estilo existente. No te detengas aquí a menos que las referencias entren en conflicto de una manera que nada resuelva.

4. Escribe la guía. Cada ejecución tiene su propia carpeta, para que ninguna ejecución sobrescriba a otra:

   design/styles/
     index.md              cada estilo, dónde se aplica, lista de temas compartida
     <slug>/
       style.md            la guía
       board.html          la verificación visual
       measured.json       lo que measure.py leyó de las referencias
       verify.md           qué tan cerca está el tablero de las referencias
       references/         capturas de pantalla de referencia
   

   Copia assets/style.md de este skill a style.md y rellénalo. Mantén cada encabezado, en orden, y escribe None para una sección vacía, para que todas las guías se lean igual. Escribe valores exactamente (hex, px, nombres de fuente), para que otra sesión pueda reconstruir el estilo sin las referencias.

   • Evidencia: una fila por recorte medido, números copiados de la salida de measure.py.
   • Tokens: cada token dice de dónde vino: crop:<nombre> (el valor se midió allí; un color debe coincidir con la lectura de ese recorte o su valor likely), derived: <regla> (construido a partir de tokens medidos, como un tono de hover o un color de texto oscurecido a 4.5:1), o chosen: <motivo> para lo que ninguna referencia muestra, como estados y tipografía de cuerpo. Los tamaños también provienen de medidas: el tamaño de fuente es la altura de mayúscula (la altura de tinta de un recorte tipográfico de mayúsculas) ÷ la relación de altura de mayúscula de la fuente. Cada regla nombra una fuente de tema real y no usa nada de la columna Dejar. Prefija cada token con --<slug>-, para que los estilos puedan compartir una página sin conflicto.
   • Componentes: da a cada tipo de componente una tabla de propiedades (propiedad, luego token o valor exacto, para cada estado), para que pueda reconstruirse sin adivinar. Usa tokens donde exista uno. Sigue la intensidad de cada rasgo: un componente fuera de los lugares nombrados de un rasgo suave usa los tokens más planos del estilo en su lugar, como la fuente de cuerpo o el color de tinta.
   • Mapeo: mapea cada token, clase o variable existente del paso 2, y cada tipo de componente, a su nuevo token o especificación de componente. Esto es desde lo que trabaja la aplicación del estilo, así que no dejes nada en el proyecto sin mapear: escribe Keep (Mantener) o Drop (Descartar) con un motivo donde nada lo reemplace.

5. Muestra el estilo, luego itera. Lee references/board.md, copia assets/board.html como copia de archivo (no reescribiéndolo) y rellena sus marcadores de posición solo desde la guía: cada tipo de componente con estados, una sección de Estilos, una sección real muy pequeña, y movimiento, cada uno etiquetado con data-crop para el recorte del que proviene. Luego verifícalo contra las referencias y compruébalo contra la guía, y corrige cada fallo tú mismo, durante como máximo tres rondas:

   python3 <este skill>/scripts/verify.py design/styles/<slug>
   python3 <este skill>/scripts/check.py design/styles/<slug>
   

   Abre el tablero en el navegador del usuario y da las rutas a board.html y verify.md.

   Luego añade el estilo y cualquier nuevo elemento de tema a design/styles/index.md, creándolo desde assets/index.md si es necesario. design/styles/ es el único lugar en el proyecto que este skill modifica.

   Detente para la revisión con el bloque de Decisiones: ¿algo que cambiar? La precisión se muestra mediante verify.md, junto con cualquier cosa que siga fallando después de tres rondas, para que el usuario juzgue solo la dirección y la intensidad. Por cada ronda de comentarios, actualiza la guía, reconstruye solo las partes afectadas del tablero, luego ejecuta verify y el check una vez y corrige lo que informen durante como máximo tres rondas sin deshacer los cambios del usuario. Actualiza el índice si el nombre o la lista de temas cambiaron, vuelve a abrir el tablero y pregunta de nuevo. Cada ronda termina medida, por lo que el estilo guardado siempre es preciso, independientemente de cuándo se detenga el usuario. Para subir o bajar un rasgo, cambia su Intensidad (escribe (comentarios del usuario) después) y los componentes que alcanza; los valores se mantienen medidos, por lo que esto no necesita data-accept. Si el usuario quiere un rasgo más atrevido que la propia referencia (más grande, más pesado, más saturado), eso cambia un valor: trátalo como a continuación. Un cambio que el usuario pide es intencionado incluso cuando se aleja de una referencia: da al token chosen: comentarios del usuario y marca su muestra data-accept con el mismo motivo, para que verify lo informe como intencionado en lugar de marcarlo como fallo, y nunca lo deshagas para que verify pase. Si el usuario rechaza la dirección en sí misma en lugar de los detalles, no parchees tokens: vuelve al paso 3, relee las referencias, elige una nueva dirección, reconstruye y detente para la revisión de nuevo.

   La ejecución termina cuando el usuario no tiene nada que cambiar o pasa a otra cosa. No hay un paso de aprobación. Para usar el estilo más tarde, el usuario lo nombra, y el skill lo aplica (ver Aplicar un estilo guardado).

Aplicar un estilo guardado

Cuando el usuario nombre un estilo guardado para usar, por ejemplo "aplica <slug> en todas partes" o "usa <slug> en la página de precios", lee references/rollout.md y síguelo. Trabaja solo desde la guía: añade los tokens de la guía al proyecto, luego recorre el Mapeo fila por fila, rediseñando cada componente desde su tabla de propiedades sin cambiar su contenido o estructura. Omite los pasos 1–5: el estilo ya está definido.

Ejemplo

Lee examples/drafting-sheet/style.md y verify.md; los archivos JSON y board.html son salida generada, que vale la pena abrir solo para ver las etiquetas data-crop. examples/drafting-sheet/ es una ejecución completa: una referencia de hoja de dibujo medida en ocho recortes, la guía y un tablero cuyas 36 medidas coinciden (una a propósito).

Referencias: dibujos técnicos y planos, para un sitio sobre una rueda en crecimiento.

• Tomar: línea fina y precisa, cuadrículas con reglas, etiquetas técnicas pequeñas, anotaciones densas.
• Dejar: el bloque de título de cada dibujo, las piezas y la disposición de la hoja.
• Tema: una rueda en crecimiento de 5,5 m, dimensiones reales del soporte, dibujos de ingeniería.
• Regla: líneas de cota del plano + dimensiones reales del soporte = figuras anotadas con sus valores medidos.