Documentar sus sistemas de diseño con Fractal

Jan 20, 2026

Cómo

[dieciséis]

¿Te apetece aprender más sobre los sistemas de diseño? Entonces no te pierdas el ingeniero de UI Senior Mina Markham a Generar nueva york El 28 de abril, donde discutirá cómo creó Pantsuit, el sistema de diseño que impulsó muchas de las aplicaciones alojadas en Hillaryclinton.com. Y en la costa oeste, en Generar San Francisco El 9 de junio, Stephanie Rewis compartirá algunas de las lecciones que aprendió al construir el sistema de diseño de Salesforce.

A estas alturas, muchos de nosotros estamos familiarizados con Guías de estilo . Pero hay una nueva generación de documentación del sistema de diseño que gana Steam: The Pattern Library. La principal diferencia entre los dos es la fuente principal de la documentación de la herramienta.

La documentación de una guía de estilo tiende a originarse a partir de un archivo de descuento, por lo que para mostrar el marcado que el autor a menudo se ve obligado a copiarlo y pegarlo en el método de descuento. Esto es casi imposible de mantener al ajustar los múltiples componentes juntos.

Una biblioteca de patrones, por otro lado, trata nuestros archivos HTML componentes como ciudadanos de primera clase. Cada componente obtiene su propia página, donde muestra el marcado y se presenta HTML directamente desde el archivo HTML. Esto garantiza que los archivos HTML y la documentación nunca salgan de la sincronización.

Las bibliotecas de patrones se construyen a menudo utilizando un lenguaje de plantilla en lugar de HTML simple. Las plantillas pueden incluir variables y otra lógica, entonces podemos pasar varios conjuntos de datos, lo que permite que se muestre variaciones de un componente.

Es posible combinar varias plantillas para crear pantallas más complejas, o incluso páginas completas. ¡Estos archivos son tan flexibles que incluso podrían ser utilizados en la producción! Cualquier cambio realizado en nuestra biblioteca de patrones es automáticamente recogido por nuestro sitio web, ya que todos los marcadores, para la biblioteca o para la producción, se originan en un solo conjunto de plantillas canónicas.

Design systems will be covered at both Generate New York and San Francisco this year

Entrar fractal

Creado por Clearleft, Fractal Ayuda a construir y documentar bibliotecas de componentes web e integrarlas en sus proyectos. En este tutorial, vamos a echar un vistazo más de cerca a cómo funciona (descargue una versión terminada de la demostración en aquí ).

Fractal es un módulo node.js que se instala a través de NPM. Primero, desea instalar el módulo a nivel mundial para que pueda generar un nuevo proyecto:

npm install --global @frctl/fractal

Con este paquete instalado, cree un nuevo proyecto:

fractal new project-name

Este comando enciende una guía de instalación que lo guía a través del proceso de configuración. Le pedirá el título del proyecto; los nombres de los componentes, la documentación y las carpetas públicas; y si vas a usar GIT para el control de la versión. Una vez que se completen las preguntas, Fractal instalará todos los módulos requeridos y configure una estructura de carpetas según se especifica.

Si desea omitir la instalación global y crear el proyecto manualmente, las instrucciones de instalación manual se pueden encontrar en aquí .

Girarlo

Ahora tiene un proyecto Fractal completamente instalado, gírelo al entrar en la carpeta del proyecto Nombre del proyecto de CD y ejecutando el comando Fractal Sync. Esto inicia un servidor local, mira los archivos para los cambios y comienza automáticamente a BrowsySync:

fractal start --sync

Y así, tienes un ejemplo de trabajo de trabajo. Abra su navegador de elección y navegue hasta http: // localhost: 3000 Para ver el inicio de su nuevo proyecto Fractal. Para evitar requerir que todos instalen Fractal globalmente, cree un script en su Package.json Eso llama al binario fractal.

 "Scripts": {
    "Fractal": "./Node_Modules/.Bin/Fractal Start --SYNC"
}

Ahora puedes usar npm corre fractal Sin tener que instalar nada a nivel mundial.

Añadiendo un componente

Ahora ha comenzado un proyecto de fractal, es hora de agregar algunos componentes. Los archivos de inicio vienen con un componente llamado 'ejemplo', pero vamos a deshacerse de eso y hacer uno nuevo desde cero.

Una de las mejores cosas de Fractal es que puede organizar sus componentes, sin embargo, le guste dentro de la carpeta Componentes, y imitará automáticamente esa organización en la navegación de la biblioteca de patrones.

Para el primer componente, crearemos un nuevo botón primario dentro de una carpeta de botones . Para hacer eso, cree con un archivo de plantilla en Componentes / Botones / Botón primario / Primary-Button.HBS . Fractal admite plantillas de manillar fuera de la caja, así que use el .hbs extensión de archivo:

  & lt; Button Class = "Primary-Button" & GT; {{Text}} & lt; / Button & GT;

los {{texto}} cadena dentro de la etiqueta del botón es un marcador de posición variable, y esto le permite reutilizar la plantilla, pasando en diferentes valores para texto desde el archivo de datos.

Para crear el archivo de datos, use el mismo nombre de base que el archivo del manillar, pero con una diferente yml extensión. Ahora el Botón primario.config.yml sentado dentro de la Componentes / Botones / Botones primarios La carpeta debe verse así:

 Título: Botón principal
contexto:
    Texto: haga clic en mí

Todo esto juntos crea su primer componente nuevo, el botón principal, un miembro de la categoría Botón, con el texto: 'Haga clic en ME'.

Variaciones de componentes

Fractal admite variaciones del mismo componente, lo que nos permite mostrar el mismo componente con varias clases de modificadores o atributos. Así que digamos que queríamos tener la opción de usar un botón temático oscuro. Podríamos crear un nuevo archivo de plantilla llamado Botón primario - Dark.hbs Junto a nuestra plantilla original (el Double Dash denota estas variaciones de componentes). En esta plantilla aplicaremos un modificador que podemos enganchar para conectar nuevos estilos.

 & lt; Button Class = "Primary-Button" Data-Theme = "Dark" & GT; {{Text}} & lt; / Button & GT;

Ahora, cuando escribimos nuestro CSS, podemos incluir el siguiente selector para alterar esta plantilla con modificación de estilos.

 .Primary-button [Data-Theme = "Dark"] {}

Variaciones de datos

Al igual que podemos definir variaciones creando múltiples archivos de plantillas, también podemos crear variaciones dentro de nuestros datos. Podemos hacer esto dentro de la Botón primario.config.yml Archivo agregando una matriz de variantes.

 Título: Botón principal
contexto:
    Texto: Haz click en mí
Variantes:
- Nombre: Descargar
    contexto:
Texto: Descargar ahora
- Nombre: Instalar
    contexto:
Texto: instalar ahora

Esto creará nuevas variaciones llamadas 'Descargar' y 'Install', con un texto diferente pasado en el botón. Un ejemplo más práctico podría ser si estabas usando este mismo botón principal.hbs Plantilla en fractal, así como producción. En este caso, en lugar de crear una nueva plantilla para su tema oscuro, puede aprobar el valor temático como variable y usar las variaciones de datos para mostrar todos los temas de los diferentes botones.

 & lt; Button Class = "Primary-Button" Data-Theme = "{{theme}}" & gt; {{texto}} & lt; / button & gt;

Título: Botón principal
contexto:
    Texto: Haz click en mí
    TEMA: LUZ
Variantes:
- Nombre: Tema oscuro
    contexto:
Texto: Haz click en mí
Tema: Dark

Manejo de otros activos

Fractal también manejará los archivos que no sean el marcado y los datos. Cualquier CSS, JavaScript, imágenes u otros activos que agregue a la carpeta Componente se mostrará en la pestaña 'Activos'. Puedes especificar un Readme.md Archivo para el componente para que pueda escribir notas sobre cómo se usa el componente, o enlace a otras partes de la documentación.

Próximos pasos

Repetir el ejemplo anterior para todos sus componentes principales crea un catálogo útil de los principales bloques de construcción de su sitio. Pero el poder real de una biblioteca de patrones proviene de la capacidad de combinar estas piezas juntas. Asegúrate de revisar el Documentación fractal Para saber cómo puede comenzar a crear componentes más complejos combinando elementos atómicos más pequeños para crear otros más grandes.

La carpeta DOCS es un gran lugar para poner la información de la guía de estilo tradicional y las notas complementarias. Esto podría cubrir cosas como la documentación a bordo, las directrices en la voz y el tono de su marca, listas de colores y variables, etc. Sigue la misma navegación basada en la carpeta, ya que los componentes hacen, y si organiza sus archivos dentro de las carpetas de asunto, encontrará navegar por el Documentos fractales una brisa.

Fractal también admite fuentes de datos más complejas. Si necesita generar un gran conjunto de datos para una plantilla, o desea tirarlo de una API de terceros, puede usar componente-name.config.js Para devolver un objeto JavaScript en lugar de los datos del archivo YML.

Por último, Fractal le permite usar una serie de idiomas de plantación diferentes. Asegúrese de revisar la lista completa en su documentación. ¡Y sobre todo, diviértete!

Reserve sus boletos para Generar ¡hoy dia! En Nueva York Puede aprender de Mina Markham, quien construyó el sistema de diseño para la campaña presidencial de Hillary Clinton, y en San Francisco Stephanie Rewis explicará cómo puede arquitecto y construir un marco de CSS moderno para un 'sistema de diseño vivo' en la escala empresarial.

Este artículo se publicó originalmente en la revista Net Magazine 285, cómpralo aquí

Documentar sus sistemas de diseño con Fractal

Entrar fractal

Girarlo

Añadiendo un componente

Variaciones de componentes

Variaciones de datos

Manejo de otros activos

Próximos pasos

Cómo - Artículos más populares

Cómo usar el bosquejo de la gravedad

Cómo dibujar Asuka de Neon Genesis Evangelion

Cómo diseñar con formas CSS: una introducción

Crea un efecto de aberración cromático

Recrear un clásico manga

Cómo diseñar una experiencia de Chatbot

4 consejos para mejorar el rendimiento de su página

Cómo esculpir un goblin impreso 3D

Categorías