Cree una guía de estilo directamente desde Sass | Programar Plus

El otoño pasado, nuestro equipo de desarrollo quería comenzar con las guías de estilo. Habíamos agregado un nuevo miembro al equipo y, a medida que se ponía al día, nos dimos cuenta de la falta de documentación de nuestro proyecto. Si alguna vez ha sido un nuevo desarrollador en un equipo con poca documentación, sabe lo confuso que puede ser tratar de familiarizarse con una docena de proyectos sin documentación.

Al decidir sobre un método de guía de estilo, se nos ocurrieron dos requisitos principales:

  1. Poca fricciónLa guía de estilo debe ser fácil de encontrar, fácil de leer y fácil de mantener. Algo que encajara en nuestro flujo de trabajo de desarrollo existente sería increíble. Agregar nuevos directorios para archivos de marcado y documentación de muestra no sería genial.
  2. Plataforma agnósticaTrabajamos en WordPress, Drupal y CakePHP con mayor frecuencia, y queríamos algo que funcionara de la misma manera en las tres plataformas. Queríamos que fuera fácil de mantener, y para nosotros eso significaba mantener la documentación junto con el CSS.

Los fundamentos de Node-KSS

Para lograr nuestros objetivos de una guía de estilo de baja fricción e independiente de la plataforma, aterrizamos en kss-node, que es en sí mismo una implementación de Node.js de Knyle Style Sheets (KSS), una biblioteca de Ruby que:

… proporciona una metodología para escribir CSS documentado y mantenible dentro de un equipo. Específicamente, KSS es una especificación de documentación y un formato de guía de estilo.

El principio básico es que tu guía de estilo se genera a través de los comentarios que creas en tu CSS, SCSS, Sass, LESS, etc.

Escribes algo de CSS como este:

// Bold Button
//
// Use this class for a bolder, stronger looking button.
//
// Markup:
// <button class="btn btn-bold">Click Me</button>
//
// Styleguide Components.Buttons.bold
.btn.btn-bold {
    position: relative;
    font-weight: bold;
    text-transform: uppercase;
}

Y obtén este hermoso resultado:

Captura de pantalla de la documentación generada para el botón en negrita

Puede organizar su documentación como desee y también genera una pequeña y agradable estructura de navegación y documentos para usted:

Debido a que vive dentro de su CSS, actualizarlo encaja naturalmente en los flujos de trabajo de desarrollo existentes. Si actualiza algunas propiedades de CSS, la guía de estilo se actualiza automáticamente. Si necesita actualizar la documentación, el texto de la documentación se encuentra justo encima del componente en el que está trabajando. Incluso si nunca visita la guía de estilo generada, verá la guía de estilo cada vez que abra un archivo CSS. ¿Poca fricción? Cheque.

Además, dado que usamos CSS y creamos procesos en todos nuestros proyectos web, es tan independiente de la plataforma como lo necesitamos.

¡Empecemos!

Configuración inicial

En el directorio de su proyecto, desea instalar kss-node como una dependencia del proyecto. También vamos a instalar michelangelo, un buen tema para la guía de estilo:

$ npm install --save-dev kss michelangelo

Puede verificar que se instaló ejecutando

$ ./node_modules/.bin/kss --version

Crearemos un archivo llamado kss-config.json para configurar nuestros ajustes de KSS.

Dentro de su archivo, cree un objeto como este (tenga en cuenta que mis comentarios a continuación son solo para referencia, para obtener mejores resultados, elimínelos de su archivo de configuración):

{
  "title": "Title of the Style Guide",

  // Source tells KSS where the CSS, Sass, or SCSS is that it should parse for documentation comments. 
  // Here we are assuming your sass is in a directory at the root level of your project.
  "source": "sass/",

  // Destination tells KSS where to compile your style guide to.
  "destination": "styleguide/",

  // Builder tells KSS where to look for a theme. 
  // If you aren't using michelangelo, you don't need this.
  "builder": "node_modules/michelangelo/kss_styleguide/custom-template/",

  // CSS gives KSS the path to your CSS, so it can pull your styles into the style guide. 
  // The path needs to be relative to your style guide destination.
  // Here, our style guide is in /styleguide and our compiled css is at our project root.
  "css": [
    "../main.css"
  ],

  // If you want to include any javascript files, add this block, with the path to your javascript file. 
  // Also relative to your style guide destination.
 // Optional.
  "js" : [
    "../bundle.js"
  ]
}

Esto supone un árbol de directorios de proyecto simple que se ve así:

js/
sass/
bundle.js
index.html
main.css

Puede intentar compilar su guía de estilo ejecutando:

$ ./node_modules/.bin/kss --config kss-config.json

Si desea que se ejecute un comando más limpio, agregue un script al bloque de scripts en su `package.json`:

"scripts": {
  "kss": "kss --config kss-config.json"
},

Ahora puedes correr $ npm run kss para compilar su guía de estilo. (Usaré este método en el futuro, pero puedes usar $ ./node_modules/.bin/kss --config kss-config.json si tu quieres).

Sin embargo, dado que aún no hemos escrito ninguna documentación, es probable que reciba un mensaje como:

Error: No se descubrió documentación de KSS en los archivos de origen.

¡Arreglemos eso documentando nuestro primer componente!

Crear y documentar un componente simple

Crearemos un componente de título de publicación de muestra.

Aquí está nuestro CSS:

.post-title {
  font-size: 3em;
  text-align: center;
  font-family: fantasy;
}

Para crear nuestra documentación, crearemos un comentario:

// Post Title (this will be the title of your component)
//
// Large, **in charge**, and centered. (this is the description of your component. you can use markdown in here.)
//
// Markup (define the markup to be used in your styleguide):
// <h1 class="post-title">A Post Title</h1>
//
// Styleguide Components.article.post-title 
// (ꜛ this controls the organization of your style guide. Here, I'm filing this component inside Components / Article / Post Title) 

.post-title { 
    font-size: 3em; 
    text-align: center;
    font-family: fantasy; 
}

Correr $ npm run kss ¡y tu guía de estilo debería compilarse! Puede acceder a él en función de la ruta de destino que le dio. En este ejemplo, tenemos un sitio estático y lo compilé en /styleguide, así que esa es la URL que usaré para encontrarlo. Así es como debería verse si está utilizando el tema de Miguel Ángel (he eliminado los comentarios entre paréntesis):

Título de la publicación Documentación

Esto es lo que sucedió:

  1. KSS creó una sección de documentación para el título de nuestra publicación, completa con el título, la descripción, el marcado y el CSS que proporcionamos. Puede ver el HTML y el CSS renderizados, así como el HTML sin formato.
  2. KSS vio que anidamos el título de nuestra publicación debajo de Componentes / Artículo, por lo que creó una sección de nivel superior de Componentes y una sección de Componentes. El título de nuestra publicación está anidado debajo de ambos.
  3. KSS generó una navegación basada en esta jerarquía.

Si desea proporcionar más información sobre los componentes, puede proporcionar un bloque de documentación (en cualquier parte de su CSS, en realidad) como este:

// Components
//
// Components are ingredients of our design system. They may be made up of smaller groups of styles.
//
// Styleguide Components

Del mismo modo, podría proporcionar más información sobre el componente del artículo definiendo un bloque de documentación que se dirija a ese elemento a través de la Styleguide Components.article método:

// Article
//
// An article is made up of a title, featured image, and some default
// typographic settings for links, italics, bold, and blockquotes.
//
// Styleguide Components.article

Con esos nuevos bloques de documentación, vuelva a compilar su guía de estilo ($ npm run kss) y verás que tu esquema se completa un poco más:

Componentes y documentación del artículo.

Documentación de estados y variaciones de componentes

Nuestro componente de título de publicación es muy simple, pero necesitaremos mostrar información más compleja en nuestra guía de estilo. KSS puede manejar fácilmente variaciones en los componentes, así como estados interactivos como :hover o :focus. Documentaremos un botón para mostrar esto.

Nuestro botón tendrá diferentes estilos para :focus y :hover, así como una pequeña variación y una gran variación. Aquí está el CSS con el que comenzaremos:

.button {
  padding: 1em 2em;
  margin: .5em;
  display: inline-block;
  font-size: .9em;
  font-family: Helvetica, sans-serif;
  font-weight: bold;
  text-transform: uppercase;
  color: #f56476;
  background-color: #fff;
  border: 2px solid #f56476;
  transition: .2s color, .2s background-color, .2s border-color;
}

.button:hover {
  color: #fff;
  background-color: #f56476;
}

.button:focus {
  color: #3ddc97;
  border-color: currentColor;
}

.button--small {
  font-size: .5em;
}

.button--large {
  font-size: 1.5em;
}

Daremos formato a nuestra documentación de la misma manera que hicimos con el título de nuestra publicación con 2 adiciones: vamos a agregar una clase de marcador de posición de {{modifier_class}} a todos nuestros elementos que obtendrán el modificador, y definiremos nuestros estados/variaciones directamente debajo de nuestro marcado. Nuestro bloque de comentarios se verá así (he agregado algunas notas entre paréntesis):

// Buttons (title, same as before)
//
// Various button styles. (description, just as before)
//
// Markup: (we add the `{{modifier_class}}` to every element that has a modifier)
// Link Button
// <button class="button {{modifier_class}}">Button Element</button>
// <input class="button {{modifier_class}}" type="button" value="Input Button" />
//
// (a new modifiers section)
// :hover - When user hovers over button.
// :focus - When button is focused.
// .button--small - A small button.
// .button--large - A large button.
//
// Styleguide Components.button (organization, just as before)

Puede ver que agregué una variación para cada una de las variaciones que declaré en mi CSS. El formato es:

// .class-name - Description

o

// :state - Description

Cuando se compila la guía de estilo, obtiene esta nueva documentación:

Documentación generada para botones.

Puede ver que ahora tiene un ejemplo de cada uno de los estados y variaciones que describió en la sección de modificadores, con el CSS adecuado aplicado.

Esta técnica también funciona para componentes más complejos que este botón. Di que tienes un .card componente con elementos secundarios dentro que deben cambiar cuando un usuario pasa el mouse sobre la tarjeta. Para documentar eso, agregaría el {{modifier_class}} solo a la .card elemento y especifique el estado de desplazamiento tal como lo hicimos anteriormente.

Organización

De forma predeterminada, las secciones se organizarán alfabéticamente por su título. Por ejemplo, nuestro componente de botón vendrá después de nuestro componente de artículo en los ejemplos anteriores. Sin embargo, si desea cambiar el orden de los componentes u otras secciones, puede proporcionar un peso al componente. Un mayor peso hará que el componente baje en su sección. Un peso más bajo moverá el componente más arriba en la sección.

Cuando uso Sass o SCSS, pongo mis comentarios organizacionales dentro de mi main.sass o donde sea que esté importando mis parciales. Por ejemplo, en un proyecto reciente, tenía una sección de Tipografía y una sección de Elementos archivadas debajo de una sección de nivel superior Base. Naturalmente, KSS organizaría estas secciones alfabéticamente, pero yo quería que la tipografía fuera lo primero. Así es como cambié el peso en mi main.sass Archivo:

// Typography
//
// Weight: 1
//
// Styleguide base.typography
@import "base/typography"

// Elements
//
// Weight: 2
//
// Styleguide base.elements
@import "base/elements"

Paletas de colores

El tema de Miguel Ángel que estamos usando proporciona un generador de paleta de colores genial. Si está utilizando Sass o SCSS, puede documentar los nombres de las variables de color y KSS formateará un pequeño bloque de paleta de colores.

Con un comentario como este:

// Highlight Colors
//
// Colors we use for higlighting states.
//
// $highlight-blue - #1460aa; primary blue
// $highlight-purple - #674172; secondary purple
// $highlight-red - #d50000; danger red
//
// Styleguide Base.colors

KSS creará una paleta de colores para una fácil referencia como esta:

Compilación automática de la guía de estilo

en lugar de correr $ npm run kss cada vez que hacemos un cambio en el CSS, podemos agregar una tarea de observación para regenerar la guía de estilo cada vez que cambien nuestros archivos CSS. A continuación, documentaré cómo hacerlo con npm Scripts ya través de Grunt.

Guiones npm

Ya estamos usando secuencias de comandos npm para crear la guía de estilo, solo necesitamos agregar una secuencia de comandos que observará nuestra guía de estilo.

Usaremos el paquete onchange. Primero instalarlo:

$ npm install onchange --save-dev

Luego agregue un nuevo script en nuestro objeto scripts:

"scripts": {
  "watch": "onchange 'sass/**/*.sass' -- npm run kss",
  "kss": "kss --config kss-config.json"
},

La tarea del reloj dice onchange para ver los archivos que especificamos en nuestro patrón global ('sass/**/*.sass') y cuando detecte un cambio, ejecute el comando que especificamos después del --: npm run kss.

ahora corriendo $ npm run watch observará nuestro .sass archivos y regenerar nuestra guía de estilo cada vez que detecte un cambio en nuestro Sass.

Gruñido

Hay un complemento oficial de Grunt para KSS, grunt-kss. Puede configurarlo para ver su .sass o .scss archivos para los cambios y vuelva a compilar la guía de estilo a medida que la desarrolla.

Aquí hay un ejemplo de configuración de Grunt. Con esta configuración, no necesita una kss-config.json archivo, toda la configuración puede ocurrir en su Gruntfile.

module.exports = function(grunt) {
  grunt.initConfig({
    kss: {
      options: {
        title: 'Title of the Style Guide',
        builder: "./node_modules/michelangelo/kss_styleguide/custom-template/",
        css: [
          "../path/to/compiled/css.css",
        ],
        js: [
          "../path/to/compiled/javascript.js",
        ]
      },
      dist: {
        src: "path/to/css/src",
        dest: "styleguide/",
      }
    },
    watch: {
      sass: {
        files: [
          './path/to/**/*.sass'
        ],
        tasks: ['kss']
      },
    }
  });

  grunt.loadNpmTasks('grunt-kss');
  grunt.loadNpmTasks('grunt-contrib-watch');

  grunt.registerTask('dev', ['kss', 'watch']);
}

Corriendo $ grunt dev primero generará la guía de estilo y luego verá nuestra .sass para los cambios y regenerar la guía de estilo cuando detecta un cambio.

Envolver

Hay más detalles sobre el análisis de comentarios y otras características que no he mencionado aquí en el repositorio oficial de KSS. Tiene más que suficiente para comenzar aquí, pero hay algunas cosas en las que no entré, incluida una página de inicio personalizada, indicadores experimentales/de desaprobación y ayudantes para preprocesadores.

Si quiere ir aún más lejos, puede desarrollar su propia guía de estilo en lugar del tema de Miguel Ángel que usamos. Consulte los documentos sobre el uso de plantillas personalizadas para obtener más información.

(Visited 10 times, 1 visits today)