Capítulo 10

Este capitulo habla sobre:

Construyendo una biblioteca de patrones para documentar sus módulos
Incorporar una biblioteca de patrones en su proceso de desarrollo
Aplicar un enfoque de CSS First a la escritura de estilos
Editar y eliminar CSS de forma segura
Utilizando frameworks CSS como Bootstrap

Una vez que comience a escribir su CSS de forma modular, comenzará a cambiar la forma en que aborda la tarea de crear páginas web y aplicaciones web. Al principio, es posible que las páginas que cree no parezcan diferentes. Pero en algún momento, deberá armar una página en particular y encontrará que ya ha creado muchos de los módulos que requiere. Por ejemplo, si necesita un objeto multimedia, o un menú desplegable o de navegación, y ya ha creado uno, ya tiene los estilos listos para ello. Solo necesitará agregar los nombres de clase correctos a algunos elementos estructurados de la manera correcta.

Debido a que los módulos son reutilizables, podrá crear esas partes de la página sin agregar ningún CSS nuevo a su hoja de estilo. En lugar de escribir una página HTML y luego aplicar estilos, se encontrará tomando módulos que ya existen y usándolos para armar una nueva página. Cuanto más avance en el proyecto, menos tendrá que escribir CSS nuevo. En lugar de nuevos estilos, lo que necesitará es un inventario de todos los módulos que ya están disponibles en su hoja de estilo.

Se está convirtiendo en una práctica estándar en proyectos grandes reunir un conjunto de documentación que proporcione este inventario. Este conjunto de documentación se denomina biblioteca de patrones o guía de estilo. No forma parte de su sitio web ni de su aplicación; en cambio, es un conjunto separado de páginas HTML, que muestra cada módulo CSS. Esta es una herramienta de desarrollo que usted y su equipo utilizarán al crear el sitio.

En este capítulo, le mostraré cómo crear una biblioteca de patrones. Hay innumerables herramientas disponibles para ayudar con esto (aunque se puede hacer completamente sin herramientas, si es lo suficientemente emprendedor). Le mostraré una de esas herramientas, llamada KSS, aunque mi enfoque se extenderá más allá de esto para incluir principios que se aplican independientemente de la herramienta que utilice.

Una vez que comience su biblioteca de patrones, destacaré los beneficios clave que brinda y cómo puede mejorar su proceso de desarrollo, especialmente para proyectos grandes. Este capítulo es una continuación del capítulo 9, por lo que si avanzó hasta este punto, le animo a que vuelva atrás y lea ese capítulo primero.

Algunas bibliotecas de patrones a menudo se denominan guía de estilo (o "guía de estilo viviente"). De hecho, la guía de estilo es probablemente la más común; sin embargo, hay una distinción.

El nombre guía de estilo implica no solo instrucciones técnicas sobre cómo usar los módulos, sino también una dirección obstinada sobre cuándo y por qué debe o no debe usarlos. Esta dirección suele ser para guiar al desarrollador a través de los requisitos de la marca del producto.

Si la instrucción de marca es relevante en su proyecto, no dude en agregarla a su biblioteca de patrones. Pero eso entra en el ámbito del marketing en lugar del desarrollo. Debido a que este capítulo se centra en el aspecto de la documentación técnica, utilizaré la biblioteca de patrones de nombres en su lugar.

10.1. INTRODUCCIÓN A KSS

A lo largo del libro, me he propuesto no hablar mucho sobre herramientas. Los principios más importantes de CSS se aplican independientemente de su conjunto de herramientas, y quería que la atención se centrara en esos principios, no en qué preprocesador o herramienta de compilación utiliza.

La creación de una biblioteca de patrones, aunque es posible sin ninguna herramienta en particular, es mucho más fácil con la ayuda de las herramientas. Varias de estas bibliotecas están disponibles para ayudar con esto; ejecute una búsqueda en la web de "generador de guías de estilo" y encontrará muchas. No existe un líder claro de la industria, pero uno que permanece constantemente cerca de la parte superior de la lista es KSS. Esto significa hojas de estilo Knyle ("Knyle" es una referencia a Kyle Neath, el autor).

Le mostraré cómo configurar y ejecutar KSS. Una vez que está configurado, escanea su hoja de estilo en busca de bloques de comentarios que tengan una determinada anotación de guía de estilo. Utilizará cada uno de estos bloques de comentarios para describir el propósito y el uso de cada módulo; KSS usa esto para construir la documentación HTML. El comentario también puede incluir un fragmento de HTML, que ilustra el marcado necesario para representar el módulo. KSS usa esto para hacer una demostración en vivo del módulo en la documentación, similar a la captura de pantalla en la figura 10.1.

ibid — Figura 10.1. Documentación de KSS renderizada de un módulo desplegable

En esta captura de pantalla, puede ver un menú a la izquierda que enumera las secciones de la biblioteca de patrones. A la derecha está la documentación del módulo desplegable (como el que construyó en el capítulo 9). Esto incluye una versión renderizada de un menú desplegable, más el HTML utilizado para construirlo. Con esto como guía, cualquier persona versada en HTML puede luego replicar este marcado en una página, y su hoja de estilo aplicaría esta apariencia.

10.1.1. Configuración de KSS

KSS se escribió originalmente como una aplicación Ruby. Pero, debido a que se encuentra en el ámbito del desarrollo de front-end, es probable que esté más familiarizado con JavaScript, por lo que lo guiaré a través de la instalación de una implementación de Node.js de KSS.

Si no tiene Node.js instalado, puede encontrarlo gratis en https://nodejs.org. Descárguelo e instálelo de acuerdo con las instrucciones que se dan allí. Node viene con un administrador de paquetes (llamado npm), que usará para instalar KSS. Le mostraré los comandos necesarios para esto, pero si desea obtener más información sobre npm o necesita ayuda para solucionar cualquier problema, visite https://docs.npmjs.com/getting-started/.

Una vez que Node y npm estén instalados, cree un directorio para su proyecto donde prefiera en su sistema de archivos. Navega hasta él en la terminal. Ejecute npm init -y para inicializar un nuevo proyecto. El indicador -y establece automáticamente los valores predeterminados para el nombre del proyecto, la licencia y otros valores. (Si omite el indicador -y, npm le solicita que ingrese estos valores).

Al inicializar su proyecto, npm crea un archivo llamado package.json. Este archivo contiene los metadatos npm de su proyecto en formato JSON.

          
{
  "name": "pattern-library",                1
  "version": "1.0.0",                       2
  "description": "",                        3
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "Keith J. Grant",
  "license": "ISC"
}
          
          Listado 10.1. Archivo package.json generado

Breve nombre de su proyecto npm
Número de versión
Aquí se puede completar una descripción más extensa del proyecto.

Con su paquete inicializado, puede instalar KSS como una dependencia. Ingrese npm install --save-dev kss en la terminal. Esto hace dos cosas: crea un directorio node_modules en su proyecto, donde se instalan KSS y sus dependencias, y agrega "kss" a una lista de dependencias de desarrollo (devDependencies) en el archivo package.json.

KSS necesitará un archivo de configuración. Este archivo le da a KSS las rutas a algunos directorios y archivos que usará para construir la biblioteca de patrones. Cree un archivo en el directorio de su proyecto llamado kss-config.json. Copie la siguiente lista en este archivo.

          
{
  "title": "My pattern library",
  "source": [
    "./css"                         1
  ],
  "destination":  "docs/",          2
  "css": [
    "../css/styles.css"             3
  ],
  "js": [
    "../js/docs.js"                 4
  ]
}
          
          Listado 10.2. Archivo de configuración de KSS (kss-config.json)

Ruta al directorio de archivos de origen CSS (que KSS escaneará)
Ruta a donde se escribirá la biblioteca de patrones generada
Ruta a la hoja de estilo (relativa al directorio de destino)
Ruta a cualquier javascript (relativo al directorio de destino)

La ruta de origen le dice a KSS dónde encontrar sus archivos de origen CSS, que escanea en busca de comentarios de documentación. Luego usa los comentarios para producir páginas de la biblioteca de patrones en el directorio de destino.

Los archivos enumerados en las claves css y js se agregarán a las páginas de la biblioteca de patrones. He configurado cada uno de estos para un directorio css y js, respectivamente. Continúe y cree estos directorios y archivos fuente en ellos (css/styles.css y js/docs.js). Deje los archivos vacíos por ahora; los agregará en breve.

En nuestro caso, la hoja de estilo que aparece en la clave css está en el mismo directorio que el directorio de origen. Cuando utiliza un preprocesador, como SASS o Less, el directorio de origen debe apuntar a sus archivos SASS o Less, pero la clave css debe hacer referencia a la hoja de estilo CSS compilada.

Como última parte de la configuración, agregará un comando al archivo package.json que le indica a KSS que cree la biblioteca de patrones. Agregue un nuevo elemento a la sección de scripts de su archivo package.json para que coincida con la siguiente lista.

          
"scripts": {
  "build": "kss --config kss-config.json",                1
  "test": "echo \"Error: no test specified\" && exit 1"
},
          
          Listado 10.3. Agregar un script de compilación a package.json

1 Define un comando de construcción

Esto agrega un comando de compilación a su paquete. Ahora, ejecutar npm run build en la terminal le dirá a NPM que ejecute KSS (desde el directorio node_modules), pasándole la ruta al archivo de configuración de KSS que creó. Ejecute npm run build ahora y verá un error: "Error: No se descubrió documentación de KSS en los archivos de origen". KSS está buscando documentación. Démosle un poco.

10.1.2. Redacción de documentación de KSS

Agregará algunos módulos del capítulo 9 a su biblioteca de patrones. El primero de ellos será el objeto multimedia, como se muestra en la figura 10.2. Cuando KSS cree esta página, agregará Media a la tabla de contenido a la izquierda y renderizará la documentación a la derecha.

KSS busca comentarios en su hoja de estilo que sigan un patrón particular. Esto incluye un título (generalmente el nombre del módulo), texto descriptivo, HTML de ejemplo y una anotación de la guía de estilo que indica a dónde pertenece el módulo en la tabla de contenido. Una línea en blanco debe separar cada uno de estos elementos para que KSS los distinga. Estrictamente hablando, la anotación final de Styleguide es la única pieza que requiere KSS, pero normalmente también debería incluir el resto.

Agregue el código que se muestra en la siguiente lista a su hoja de estilo en css/styles.css. Esto incluye algunos estilos básicos y el módulo media. Por encima de los estilos del módulo está el bloque de comentarios CSS para KSS.

          
:root {
  box-sizing: border-box;
}

*,
*::before,
*::after {
  box-sizing: inherit;
}

body {
  font-family: Helvetica, Arial, sans-serif;
}

/*
Media                                                 1

Displays an image on the left and body content        2
on the right.

Markup:                                               3
<div class="media">
  <img class="media__image"
    src="https://placehold.it/150x150" />
  <div class="media__body">
    <h4>Strength</h4>
    <p>
      Strength training is an important part of
      injury prevention. Focus on your core—
      especially your abs and glutes.
    </p>
  </div>
</div>

Styleguide Media                                      4
*/
.media {
  padding: 1.5em;
  background-color: #eee;
  border-radius: 0.5em;
}
.media::after {
  content: "";
  display: block;
  clear: both;
}

.media__image {
  float: left;
  margin-right: 1.5em;
}

.media__body {
  overflow: auto;
  margin-top: 0;
}

.media__body > h4 {
  margin-top: 0;
}
          
          Listado 10.4. Objeto media con comentario de documentación de KSS

Título (nombre del módulo)
Descripción del módulo y su uso
Ejemplo HTML que ilustra el uso del módulo
Anotación de la guía de estilo, agregando esto a la tabla de contenido como media

Ahora, ejecute npm run build en su terminal. KSS genera un directorio de documentos que incluye un archivo section-media.html. Abra esta página en su navegador para ver la biblioteca de patrones. KSS también registra una advertencia: "No se encontró contenido de página de inicio en homepage.md". Te mostraré cómo solucionar este problema en un momento. Por ahora, echemos un vistazo más de cerca a las partes del comentario de la documentación. Las primeras líneas se ven así:

          
/*
Media

Displays an image on the left and body content
on the right.

La primera línea del comentario define el título (Media) para esta sección de la documentación, y luego un texto que describe el propósito del módulo. Esta descripción puede estar escrita en formato markdown, por lo que puede agregarle el formato que desee. La descripción puede tener varios párrafos.

markdown: un formato de texto común que admite anotaciones para el formato básico. Rodee el texto con asteriscos para ponerlo en cursiva; envolver texto con tildes (`) para formatearlo como código. Consulte https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet para obtener una referencia completa.

Cuando cree un módulo, utilice la descripción para transmitir a otros desarrolladores todo lo que necesiten saber sobre su uso. A veces, una simple oración es suficiente. A veces, deberá indicar que el módulo requiere JavaScript o está destinado a utilizarse junto con otro módulo. Esta es su documentación sobre el uso de su hoja de estilo.

Después de la descripción es una Markup: anotación. A esto le sigue un bloque de código HTML que ilustra el uso del módulo. KSS procesa este HTML en la biblioteca de patrones para que el lector pueda obtener una vista previa. Luego, muestra el HTML en formato legible para que el lector pueda copiarlo:

          
Markup:
<div class="media">
  <img class="media__image"
    src="https://placehold.it/150x150" />
  <div class="media__body">
    <h4>Strength</h4>
    <p>
      Strength training is an important part of
      injury prevention. Focus on your core—
      especially your abs and glutes.
    </p>
  </div>
</div>

El texto y las imágenes exactos utilizados en el ejemplo no son importantes, siempre que ilustren al desarrollador cómo funciona el módulo. En este caso, utilicé una imagen de marcador de posición genérica del sitio web https://placehold.it. Cuando el desarrollador usa este módulo, puede agregar el contenido que necesita.

Sin embargo, es importante que no haya líneas vacías en el medio del HTML, ya que esto le indica a KSS que la sección de marcado está completa.

La última línea del comentario de KSS debe incluir la anotación de la guía de estilo, seguida de la etiqueta de la tabla de contenido (en este caso, Media):

          
Styleguide Media
*/

Esta debe ser la última línea del comentario. Sin él, KSS ignorará todo el bloque de comentarios.

Cuando actualice una hoja de estilo, actualice la documentación para que coincida. Tener la documentación allí mismo en el código fuente hace que esto sea fácil de hacer. Cuando agregue un nuevo módulo, agregue un bloque de documentación con él. Una vez que haya realizado los cambios, ejecute npm run build nuevamente para generar una copia nueva de la biblioteca de patrones.

KSS no elimina las páginas antiguas cuando genera otras nuevas. Si cambia el nombre o mueve una parte de la documentación en su código fuente, el archivo correspondiente en el directorio docs permanecerá en su lugar, junto con el nuevo. Cuando actualice su navegador, asegúrese de no volver a cargar el archivo anterior.

Debido a que la biblioteca de patrones “vive” con los estilos que documenta, cualquier desarrollador con acceso a la hoja de estilo tendrá acceso a su documentación. Es posible que también desee alojar la biblioteca de patrones en algún lugar en línea, donde su equipo de desarrollo pueda acceder a ella.

10.1.3. Documentar variantes de módulos

Documentemos otro módulo (listado 10.5). Llevará el módulo de botones del último capítulo. Este módulo ofrecía varias variantes: dos colores alternativos y dos tamaños alternativos. KSS proporciona una forma de indicar múltiples variantes, representando cada una en la biblioteca de patrones. Esto se verá como la figura 10.3.

El comentario de documentación de este módulo será similar al anterior, pero agregará una nueva sección después del marcado para indicar cada uno de los modificadores (listado 10.5). Esta será una lista de las clases de modificadores, cada una seguida de un guión y su descripción. También agregará la anotación {{modifier_class}} al ejemplo de marcado, indicando a dónde pertenecen las clases modificadoras.

          
/*
Buttons

Buttons are available in a number of sizes and
colors. You may mix and match any size with any
color.

Markup:


.button--success  - A green success button         2
.button--danger   - A red danger button            2
.button--small    - A small button                 2
.button--large    - A large button                 2

Styleguide Buttons
*/
.button {
  padding: 1em 1.25em;
  border: 1px solid #265559;
  border-radius: 0.2em;
  background-color: transparent;
  font-size: 0.8rem;
  color: #333;
  font-weight: bold;
}

.button--success {
  border-color: #cfe8c9;
  color: #fff;
  background-color: #2f5926;
}

.button--danger {
  border-color: #e8c9c9;
  color: #fff;
  background-color: #a92323;
}

.button--small {
  font-size: 0.8rem;
}

.button--large {
  font-size: 1.2rem;
}
          
          Listado 10.5. Boton module y documentación

Indica dónde se utilizan las clases modificadoras
Enumera las clases de modificadores disponibles

KSS escanea la lista de clases de modificadores que ha definido, renderizando cada una en la biblioteca de patrones. El {{modifier_class}} le dice dónde colocar las clases. (Si está familiarizado con las plantillas de manillares, esta sintaxis probablemente le resulte familiar. Esto es lo que KSS usa detrás de escena para renderizar el módulo). Ejecute npm run build para reconstruir su biblioteca de patrones y ver la documentación en su navegador.

Volver a ejecutar KSS cada vez que realiza un cambio puede resultar tedioso. Si está utilizando un ejecutor de tareas como Gulp para sus proyectos, le sugiero que configure una tarea que observe los cambios y vuelva a ejecutar KSS automáticamente. La mayoría de los corredores de tareas tienen un complemento u otro mecanismo para hacer esto.

Ahora debería tener tres elementos en la tabla de contenido de su biblioteca de patrones (docs/index.html): Overview, Buttons y Media. Los dos últimos tienen vínculos a las partes de la documentación que ha escrito. El vínculo Descripción general está roto porque aún no ha creado una página de inicio. Esta es la causa de la advertencia "Sin contenido en la página de inicio".

10.1.4. Crear una página de descripción general

Agreguemos una página de inicio a la biblioteca de patrones. Dentro del directorio css, cree un nuevo archivo en css/homepage.md. Este será un archivo en markdown que servirá como una introducción a la biblioteca de patrones. Copie esta lista en el archivo.

          
# Pattern library                                1

This is a collection of all the modules in our
stylesheet. You may use any of these modules when
constructing a page.
          
          Listado 10.6. Markdown de la página de inicio

Encabezado de página

Ahora ejecute npm run build y la advertencia sobre el contenido de la página de inicio debería desaparecer. Si abre docs/index.html en su navegador, verá este contenido renderizado.

En sus proyectos, use esta página como una introducción a su biblioteca de patrones. Puede proporcionar instrucciones sobre cómo incluir la hoja de estilo o las hojas de estilo en la página, cómo incluir las fuentes web correctas (consulte el capítulo 13) o cualquier otra cosa para ayudar a los desarrolladores a familiarizarse con el uso de sus hojas de estilo.

Debido a que está abriendo los archivos de la biblioteca de patrones directamente desde el disco, es posible que observe que el vínculo Descripción general en la tabla de contenido aún no funciona. Esto se debe a que KSS lo vincula a la URL ./ en lugar de a index.html. Para que esto funcione, deberá entregar la biblioteca de patrones a través de un servidor HTTP para que ./ url se resuelva en index.html en el navegador. Dejaré esto para que lo haga usted, según el conjunto de herramientas con el que esté más familiarizado. Si no está seguro de por dónde empezar, pruebe el paquete npm http-server (https://www.npmjs.com/package/http-server).

10.1.5. Documentar módulos que requieren JavaScript

Algunos módulos están diseñados para funcionar con la ayuda de JavaScript. En estos casos, a menudo es útil agregar un poco de JavaScript básico a la página para demostrar el comportamiento del módulo. No es necesario que agregue una biblioteca de JavaScript completamente funcional a la biblioteca de patrones para hacer esto. La mayoría de las veces, solo necesitará lo suficiente para alternar entre las distintas clases estatales. Ya agregó la configuración a su archivo kss-config.json que agrega un archivo JavaScript a la página:

          
"js": [
  "../js/docs.js"
]

KSS agregará los scripts enumerados en esta matriz js a la página por usted. Puede agregar código a estos scripts que proporcione una funcionalidad mínima a los módulos. Para demostrar esto, agregará el módulo desplegable (capítulo 9) a su hoja de estilo, junto con cierta documentación (listado 10.7). También agregará algo de JavaScript para que al hacer clic en el botón Alternar se abra y se cierre el menú desplegable. Luego, el módulo funcionará dentro de la biblioteca de patrones para demostrar la funcionalidad prevista del módulo (figura 10.4).

Comience agregando los estilos y la documentación del listado 10.7 a su hoja de estilo. También es importante dar algunas indicaciones sobre cómo debe funcionar JavaScript. Los desarrolladores utilizarán esto para crear el sitio web o la aplicación web. Necesitarán suficiente información para poder hacerlo correctamente. Agrega este código a tu CSS.

          
/*
Dropdown

A dropdown menu. Clicking the toggle button opens
and closes the drawer.

Use JavaScript to toggle the `is-open` class in            1
order to open and close the dropdown.

Markup:
<div class="dropdown">                                     2
  <button class="dropdown__toggle">Open menu</button>
  <div class="dropdown__drawer">
    Drawer contents
  </div>
</div>

Styleguide Dropdown
*/
.dropdown {                                                3
  display: inline-block;
  position: relative;
}

.dropdown__toggle {
  padding: 0.5em 2em 0.5em 1.5em;
  border: 1px solid #ccc;
  font-size: 1rem;
  background-color: #eee;
}

.dropdown__toggle::after {
  content: "";
  position: absolute;
  right: 1em;
  top: 1em;
  border: 0.3em solid;
  border-color: black transparent transparent;
}

.dropdown__drawer {
  display: none;
  position: absolute;
  left: 0;
  top: 2.1em;
  min-width: 100%;
  background-color: #eee;
}

.dropdown.is-open .dropdown__toggle::after {
  top: 0.7em;
  border-color: transparent transparent black;
}
.dropdown.is-open .dropdown__drawer {
  display: block;
}
          
          Listado 10.7. Módulo desplegable y documentación

Proporciona instrucciones que indican cómo el desarrollador necesitará usar JavaScript para este módulo.
Ejemplo de marcado
Reglas del módulo desplegable (copiadas del capítulo 9)

Ejecutar npm run build compila esta documentación, pero en este punto, es estática. Agreguemos JavaScript a js/docs.js para darle vida. Agregue este listado a ese archivo.

          
(function () {
  var dropdowns = document.querySelectorAll('.dropdown__toggle');     1
  Array.prototype.forEach.call(dropdowns, function(dropdown) {
    dropdown.addEventListener('click', function 6#40;event) {             2
      event.target.parentNode.classList.toggle('is-open');            3
    });
  });
}());
          
          Listado 10.8. JavaScript mínimo para demostrar el módulo

Obtiene todas las instancias del botón desplegable__toggle
Agrega un detector de eventos de clic a cada instancia
Alterna la clase está abierta en el elemento desplegable

Esta secuencia de comandos alterna la clase está abierta en el menú desplegable cada vez que se hace clic en el botón Alternar. Una implementación completa en su sitio web necesitará más código para lidiar con los retrasos en el tiempo o para cerrar el menú si se hace clic en otra parte de la página. Nuevamente, en la biblioteca de patrones, el código puede ser mínimo; pero tendrá que diseñar correctamente los estados abierto y cerrado. Una vez hecho esto, usted (u otro desarrollador) puede concentrarse en el problema de obtener los puntos más finos de JavaScript exactamente correctamente, fuera de la biblioteca de patrones.

10.1.6. Organizar la biblioteca de patrones en secciones

Puede continuar agregando los módulos del capítulo 9 a su hoja de estilo, ingresando la documentación según sea necesario. No lo guiaré a través de todos y cada uno de ellos, ya que ahora tiene una comprensión básica del proceso.

Lo último que deberá poder hacer es organizar su biblioteca de patrones. El menú de la figura 10.4 está bien por ahora, con solo unos pocos elementos. Pero a medida que sus proyectos comiencen a crecer en tamaño, tendrá sentido categorizar sus módulos para que sean más fáciles de navegar.

Agreguemos documentación para las clases de servicios públicos. Cada uno deberá explicarse y demostrarse individualmente, por lo que tiene sentido agruparlos. En el listado 10.9, creará una nueva sección llamada Utilities, agregando las clases de utilidad cada una en una subsección dentro de eso para representar las secciones que se muestran en la figura 10.5.

Para crear subsecciones, use un punto en la anotación de la guía de estilo. Utilizará anotaciones como esta: Styleguide Utilities.clearfix. Esto coloca el bloque de documentación en una subsección de corrección clara dentro de una sección de Utilidades.

KSS admite secciones de hasta tres niveles de profundidad (por ejemplo, Utilities.alignment.text-center).

Agregue la siguiente lista a su hoja de estilo. Esto incluye tres clases de utilidad (text -center, float-left y clearfix) y sus comentarios de documentación. También incluí una anotación Weight, que controla el orden de las secciones.

          
/*
Text center

Center text within a block by applying `text-center`

Markup:
<p class="text-center">Centered text</p>

Weight: 1                                                    1

Styleguide Utilities.text-center                             2
*/
.text-center {
  text-align: center !important;
}

/*
Float left

Float an element to the left with `float-left`

Weight: 3                                                    1

Styleguide Utilities.float-left                              2
*/
.float-left {
  float: left;
}

/*
Clearfix

Add the class `clearfix` to an element to force it to
contain its floated contents

Markup:
<div class="clearfix">
  <span class="float-left">floated</span>
</div>

Weight: 2                                                     1

Styleguide Utilities.clearfix                                 2
*/
.clearfix::before,
.clearfix::after {
    content: " ";
    display: table;
}

.clearfix::after {
    clear: both;
}
          
          Listado 10.9. Agrupación de documentación en la misma categoría

Utiliza la anotación Weight para controlar el orden de las secciones
Utiliza una notación de puntos para colocar cada bloque de documentación en el mismo grupo

Al clasificar cada una de estas clases de servicios públicos en la misma categoría principal, todas se agruparán. Ahora, cuando reconstruya la biblioteca de patrones, habrá un elemento en la tabla de contenido llamado Utilidades. Haga clic en él para ver una página con todas las subsecciones enumeradas.

La anotación de la Styleguide distingue entre mayúsculas y minúsculas. Cuando coloque varios elementos dentro de la misma sección, asegúrese de ponerlos en mayúscula de manera consistente o KSS creará secciones separadas (por ejemplo, una llamada "Utilidades" y otra "utilidades").

De forma predeterminada, las secciones de una biblioteca de patrones de KSS se ordenan alfabéticamente, al igual que las subsecciones dentro de una sección. Puede cambiar esto usando la anotación Weight. KSS ordena las secciones de acuerdo con su peso, con pesos más altos cerca de la parte inferior. Puede indicar pesos en una sección de nivel superior para controlar su posición entre otras secciones de nivel superior, o (como en el ejemplo) para controlar el orden de las subsecciones dentro de su sección.

Ahora está familiarizado con todas las funciones esenciales de KSS. Si desea profundizar más por su cuenta, puede aprender a tener un poco más de control sobre la apariencia de la biblioteca de patrones en sí. Puede personalizar su hoja de estilo interna o la plantilla que utiliza para crear las páginas de la biblioteca de patrones. Para obtener más información, consulte la documentación en https://github.com/kss-node/kss-node.

10.2. CAMBIANDO LA FORMA DE CONSTRUIR CSS

Las bibliotecas de patrones no son necesarias para proyectos pequeños, pero con proyectos grandes, serán invaluables. Si desarrolla para un sitio web con cientos o miles de páginas, no podrá diseñarlas todas una a la vez. Pero al crear módulos reutilizables y documentarlos en un solo lugar, puede proporcionar un conjunto de herramientas con el que se pueden construir miles de páginas.

Si trabaja en una aplicación web grande con una docena de otros desarrolladores, posiblemente no podrá diseñar sus propios componentes sin encontrarse con conflictos de nombres de clases y muchas implementaciones duplicadas de las mismas IU. Pero con una biblioteca de patrones, los desarrolladores pueden encontrar los estilos de los demás, reutilizarlos y nombrar sistemáticamente los módulos para que los nombres de las clases no entren en conflicto.

Los editores y desarrolladores de contenido que usan su biblioteca de patrones ni siquiera necesitan saber CSS, solo necesitan tener conocimientos básicos de HTML. Pueden copiar los patrones que documente y colocarlos en su página donde quieran. CSS modular es la clave para escalar su CSS, y una biblioteca de patrones es un medio para mantener esos módulos organizados.

10.2.1. Usar un flujo de trabajo de CSS First

El uso de una biblioteca de patrones es un cambio de paradigma del enfoque típico de CSS. En lugar de tomar una página HTML y luego darle estilo, construye estilos modulares y luego ensambla una página web usando esos módulos. Este es un enfoque que llamo desarrollo CSS First. En lugar de escribir su HTML primero, comience con el CSS. Puede, y debe, desarrollar su CSS dentro de los límites de la biblioteca de patrones antes de utilizar esos estilos en su proyecto, por lo que su proceso de desarrollo se verá así:

Al crear una página, tenga un boceto o maqueta o una idea general de cómo debería verse esa página.
Vaya a la biblioteca de patrones. Busque módulos existentes que proporcionen lo que necesita para su página y utilícelos. Empiece desde el exterior (diseño de la página principal y contenedores) y avance hacia adentro. Si puede construir su página completa usando módulos existentes, hágalo. No es necesario que escriba ningún CSS nuevo.
De vez en cuando, encontrará que necesita algo que la biblioteca de patrones no proporciona. Esto sucederá mucho al principio de la vida del proyecto, pero mucho menos más adelante. Deberá crear un módulo o módulos nuevos, o una nueva variante para un módulo existente. Deje a un lado la página en la que está trabajando y constrúyala dentro de la biblioteca de patrones. Documente y asegúrese de que se vea y se comporte como espera.
Regrese a su página y, usando la nueva hoja de estilo, agregue los nuevos módulos a su página.

Este enfoque tiene varios beneficios. Primero, ayuda a proporcionar una interfaz más consistente para su sitio. Le anima a reutilizar los estilos existentes en lugar de desplegar otros nuevos. Por ejemplo, en lugar de diez páginas diferentes en su sitio con diez estilos de lista diferentes, tenderá a reutilizar los mismos tipos de listas. Te obliga a detenerte y pensar cada vez si necesitas un nuevo estilo o si uno que ya tienes es suficiente.

En segundo lugar, cuando desarrolle un módulo dentro de los límites de la biblioteca de patrones, podrá concentrarse en ese problema de forma aislada. Puede retirarse del panorama general de la página web en particular y concentrarse en la tarea singular de diseñar un módulo. En lugar de resolver un solo problema en una sola página, será más fácil pensar en dónde más podría usarse el nuevo módulo. Creará una solución más general y reutilizable.

En tercer lugar, este enfoque también permitirá que algunos miembros de su equipo se especialicen en CSS. Un desarrollador que sea menos experto en ello puede entregar un trabajo a uno que tenga más experiencia. Una vez que el desarrollador con mentalidad CSS termina el módulo, puede enviar un enlace al otro desarrollador, apuntando al módulo en la biblioteca de patrones.

Finalmente, este enfoque asegurará que su documentación esté actualizada. Las páginas de su biblioteca de patrones son donde prueba los cambios en el CSS, lo que significa que siempre demuestran el comportamiento actual y correcto. Cuando edita el CSS, la documentación está ahí en un bloque de comentarios. Esto hace que sea trivial mantener actualizada la documentación a medida que realiza cambios. (Hablaré más sobre la edición de módulos existentes en un momento).

Los desarrolladores a menudo preguntan cómo pueden escribir HTML que sea fácil de diseñar. Creo que esta es la pregunta equivocada. En cambio, deberíamos preguntarnos cómo podemos escribir estilos que se puedan reutilizar en cualquier número de páginas. Deberíamos escribir CSS primero; Seguirá HTML bien estructurado.

10.2.2. Usar una biblioteca de patrones como API

Cuando usa una biblioteca de patrones, está documentando una API para interactuar con su CSS. Cada módulo viene con algunos nombres de clase y un poco de estructura DOM. Siempre que la parte relevante de HTML siga esta estructura, la hoja de estilo le aplicará el estilo correcto (figura 10.6).

API: interfaz de programación de aplicaciones. Un conjunto de definiciones de subrutinas que describen cómo utilizar o interactuar con un sistema. Tradicionalmente, esto incluye nombres de métodos y parámetros (en el caso de un lenguaje de programación) o URL y parámetros de consulta 6#40;en el caso de una API HTTP). Utilizo la frase con respecto al CSS modular para ilustrar que los nombres de las clases y los elementos HTML son la forma en que HTML interactúa con los estilos.

El ejemplo de marcado en cada módulo ilustra una especie de contrato que su CSS hace con el HTML. Muestra cómo el HTML debe interactuar con el CSS.

Cuando crea sus módulos, esta API es la parte más importante porque es lo más difícil de cambiar más adelante. El HTML es libre de cambiar: puede cambiar el contenido de cada elemento. En algunos casos, puede agregar, eliminar o incluso reorganizar el orden de los elementos DOM dentro del módulo (asegúrese de indicar claramente en su documentación si los elementos son opcionales o si las cosas se pueden reorganizar). Y, el HTML puede dejar de usar un módulo por completo, cambiando en su lugar a un módulo diferente.

Del mismo modo, el CSS puede cambiar siempre que siga respetando esta API. Puede realizar pequeñas ediciones, como aumentar el relleno o ajustar un color o corregir cualquier error que surja. O bien, puede realizar ediciones grandes, como reelaborar un objeto multimedia para usar flexbox en lugar de flotantes, o rediseñar un módulo para que se apile verticalmente en lugar de horizontalmente. Siempre que las piezas clave de la API (nombres de clases y estructura DOM) permanezcan inalteradas, puede editar el CSS como desee.

Tenga en cuenta que realizar estas modificaciones puede afectar a muchas partes de su sitio web. Pero siempre que el HTML siga las instrucciones de la API, estos cambios se realizarán de acuerdo con el plan. Si desea cambiar el aspecto de todos los menús desplegables de su sitio, puede hacerlo. Debido a que todos los menús desplegables de su sitio utilizan el mismo módulo (y la misma API), los cambios serán consistentes.

Para ilustrar, supongamos un escenario hipotético en el que desea realizar un cambio en la forma en que funciona el módulo de medios. En lugar de una imagen, la necesita para admitir dos imágenes, una a cada lado del contenido, como en la figura 10.7.

Esto requiere algunos cambios en el CSS. Siempre que se asegure de que sus cambios sigan respetando la API (es decir, los objetos multimedia existentes en su sitio continúen funcionando como se esperaba con una sola imagen), puede cambiar los estilos. Hará esto modificando el módulo para usar flexbox. Realicemos estos cambios.

Primero, deberá agregar al marcado de ejemplo en el bloque de comentarios. Mantenga el ejemplo anterior allí, para que pueda probar que permanece sin cambios después de realizar sus ediciones. Pero también agregará un segundo ejemplo al marcado para probar el nuevo comportamiento. Actualice el comentario de la documentación para que coincida con la siguiente lista.

          
/*
Media

Displays images and/or body content beside one      1
another.

Markup:
<div class="media">                                 2
  <img class="media__image"
    src="https://placehold.it/150x150" />
  <div class="media__body">
    <h4>Strength</h4>
    <p>
      Strength training is an important part of
      injury prevention. Focus on your core—
      especially your abs and glues.
    </p>
  </div>
</div>
<div class="media">                                 3
  <img class="media__image"
    src="https://placehold.it/150x150" />
  <div class="media__body">
    <h4>Strength</h4>
    <p>
      Strength training is an important part of
      injury prevention. Focus on your core—
      especially your abs and glues.
    </p>
  </div>
  <img class="media__image"
    src="https://placehold.it/150x150" />
</div>

Styleguide Media
*/
          
          Listado 10.10. Agregar un nuevo ejemplo de medios a la documentación

Actualiza la descripción para permitir múltiples imágenes
Mantiene el ejemplo de marcado original en su lugar
Agrega un nuevo ejemplo con dos imágenes.

Esta lista le brinda dos instancias del módulo en su biblioteca de patrones. Reconstruya la biblioteca de patrones para verla renderizar. Antes de realizar cambios en el CSS, puede ver que uno funciona y el otro no. Luego puede realizar cambios (listado 10.11) hasta que ambos funcionen. Luego, tendrá el resultado que se muestra en la figura 10.8.

La biblioteca de patrones ahora sirve como respaldo. Le indica si sus cambios romperían los objetos multimedia existentes en su sitio y actúa como una prueba de la validez del código.

Ahora puede refactorizar el CSS para tener en cuenta el nuevo escenario. Realice estos cambios en su hoja de estilo para que el segundo ejemplo funcione, y asegúrese de que el primer ejemplo no se interrumpa en el proceso.

          
.media {
  display: flex;                     1
  align-items: flex-start;           2
  padding: 1.5em;
  background-color: #eee;
  border-radius: 0.5em;
}

.media > * + * {
  margin-left: 1.5em;                3
}

.media__body {
  margin-top: 0;
}

.media__body > h4 {
  margin-top: 0;
}
          
          Listado 10.11. Módulo media rediseñado para usar flexbox

Cambia el contenedor a contenedor flexible; media__image y media__body se convertirán en elementos flexibles
Alinea los elementos en la parte superior en lugar de estirarlos para llenarlos y evita la distorsión de la imagen.
Elimina el margen derecho de la imagen y lo reemplaza con un margen general entre todos los elementos flexibles

Ejecute npm run build y abra la página en la biblioteca de patrones. Verá que sus cambios se realizaron correctamente. El objeto media es ahora un poco más versátil. Y, como aún respeta la API original del módulo, puede estar seguro de que sus cambios no afectaron el sitio web.

Sin estilos modulares y una biblioteca de patrones, la edición de CSS puede causar estragos en un sitio web; no tiene idea exacta de cómo se podría estructurar el HTML en todas partes y si los selectores seguirán apuntando a los elementos correctos. Pero con una API documentada y estable, las ediciones pueden ser sencillas e incluso satisfactorias.

A veces, no podrá realizar los cambios que desea sin modificar la API. Esto está bien. Significará un poco más de trabajo, pero es factible. Puede realizar los cambios que desee, luego recorrer todo su sitio o aplicación y actualizar cada instancia del HTML para que coincida con la nueva API. Pero a menudo encuentro que el mejor curso de acción es desaprobar el módulo (indicándolo en la documentación) y crear un módulo completamente nuevo para la nueva funcionalidad que necesito. De esta manera, el módulo anterior continúa funcionando donde se usa, pero puedo comenzar a migrar al módulo nuevo mientras ambos sean compatibles.

Para ayudar a facilitar esto, encuentro que es muy beneficioso versionar mi CSS usando un semver de tres números. Cuando cambia el número de versión, comunica a los desarrolladores la naturaleza de esos cambios.

semver: abreviatura de Semantic Versioning, un sistema para versionar paquetes de software utilizando tres números, cada uno separado por un punto (por ejemplo, 1.4.2). Los tres números representan las versiones mayor, menor y parche, respectivamente. Consulte https://semver.org/ para obtener más información.

Cuando hago pequeños ajustes, como correcciones de errores, incremento el número de versión del parche (de 1.4.2 a 1.4.3, por ejemplo). Cuando agrego un nuevo módulo o una nueva funcionalidad que no interrumpe la API, o cuando marco un módulo como obsoleto, incremento el número de versión menor, restableciendo la versión del parche a 0 (por ejemplo, 1.4.2 a 1.5.0) . Luego, en raras ocasiones, reviso la hoja de estilo y elimino los módulos obsoletos, pasando a la siguiente versión principal (por ejemplo, 1.4.2 a 2.0.0). También creo una versión principal cuando realizo cambios sustanciales en el diseño (como un rediseño del sitio), incluso si la API permanece intacta.

Hablando en términos prácticos, hay varias formas de realizar este control de versiones. Esto depende de la naturaleza del proyecto en el que utilice los estilos. Si empaqueta el CSS en un módulo NodeJS o Ruby Gem, por ejemplo, use el control de versiones integrado en estos sistemas. O, si está alojando su CSS de forma estática en un servidor, incluya el número de versión en la URL (https://example.com/css/1.4.2/styles.css) y aloje varias versiones simultáneamente.

De esta forma, el proyecto se puede configurar para usar cualquier versión de CSS que necesite. Puede lanzar una versión 3.0.0 con cambios importantes, pero la aplicación web puede continuar usando la versión anterior hasta que los desarrolladores puedan revisar y actualizar el HTML siempre que use módulos obsoletos. Los cambios que realice en su CSS no interrumpirán la aplicación hasta que la aplicación se actualice deliberadamente a una nueva versión de la hoja de estilo.

Su biblioteca de patrones documenta el uso de la hoja de estilo, pero los autores del HTML tienen el control de si usan los estilos y qué versión usan. El HTML y CSS están desacoplados. El CSS debe desarrollarse primero antes de que el HTML pueda usarlo, pero el HTML tiene el control cuando se trata de actualizar a una nueva hoja de estilo. Este es el beneficio del desarrollo de CSS First.

Estas decisiones no pueden suceder en el vacío. Deberá comunicarse con otros desarrolladores de su equipo cuando desee desaprobar o eliminar módulos. Necesitará su opinión sobre qué módulos siguen siendo valiosos y cuáles ya no son necesarios.

Es posible que esté familiarizado con uno o más marcos CSS que proporcionan un conjunto de estilos preempaquetados. Estos suelen incluir estilos para botones, formularios, menús y algún tipo de sistema de cuadrícula. Los marcos populares incluyen Bootstrap (https://getbootstrap.com/), Foundation (https://foundation.zurb.com/) y Pure (https://purecss.io/). También hay muchos otros. Algunas de estas son bibliotecas robustas con docenas de módulos; otros son mínimos y proporcionan solo lo esencial.

A medida que avanza en la construcción de su biblioteca de patrones, puede comenzar a sentir que está construyendo su propio marco en la misma línea. ¡Eso es exactamente lo que estás haciendo! Ésta es la razón por la que estos marcos tienen éxito: cada uno es una biblioteca de patrones. Consisten en CSS construido prestando atención a hacer que los estilos sean reutilizables en muchos contextos. Algunos siguen los principios del CSS modular mejor que otros, pero todos los siguen hasta cierto punto. Y siempre están versionados.

La diferencia entre estos marcos y su propia biblioteca de patrones es que los marcos son de uso general. En su biblioteca de patrones, puede crear módulos adaptados específicamente a su proyecto y puede combinar con precisión un aspecto y una sensación específicos de la marca. Puede crear dos tipos diferentes de módulo Tile si lo necesita, y puede adaptarse más rápidamente cuando lo necesite.

Los desarrolladores a menudo me preguntan si creo que deberían usar un framework como Bootstrap. Mi respuesta es sí y no.

Los frameworks son útiles para que un proyecto despegue rápidamente. Casi sin trabajo, puede tener botones, mosaicos y menús desplegables con estilo. Pero, en mi experiencia, nunca proporcionan todos los módulos que necesitará. A excepción de los proyectos pequeños, siempre tendrá que agregar más módulos propios. También proporcionan muchos módulos que probablemente no necesitará.

Si desea utilizar un framework con el que está familiarizado, mi sugerencia es que tome solo las partes que necesite y deje el resto. No se limite a pegar un archivo bootstrap.css en su página. En su lugar, copie solo los módulos que desee en su propia hoja de estilo (suponiendo que la licencia del framework lo permita). Toma esas piezas de CSS y hazlas tuyas.

Cuando agrega un framework a la página antes de su propia hoja de estilo, se encontrará escribiendo un montón de estilos para anular y aumentar el framework. Si, en cambio, trae los estilos del framework a su hoja de estilo, podrá modificarlos directamente. Esto hará que el CSS de la página sea más ágil y más fácil de seguir.

En lugar de utilizar ciegamente un framework, adopte la mentalidad de un framework. Imagine que su biblioteca de patrones es una biblioteca de uso general para uso de terceros desconocidos. Esto le ayudará a mantener sus estilos reutilizables y le proporcionará un medio para realizar cambios en el futuro con menos roturas en la página.

A menudo, CSS es un lenguaje "solo aditivo". Los desarrolladores tienen miedo de editar o eliminar cualquier estilo existente porque no tienen forma de conocer todas las ramificaciones de esos cambios. Solo modifican CSS, agregan más al final de la hoja de estilo, anulan las reglas anteriores y aumentan la especificidad del selector hasta que la hoja de estilo es una maraña de código que no se puede mantener.

Al tener cuidado de organizar su CSS de una manera modular y mantener una biblioteca de patrones para ello, no tiene que caer en esta trampa. Siempre sabe dónde residen los estilos de un módulo. Cada módulo es responsable de una cosa. Y la biblioteca de patrones ayuda a los desarrolladores a controlar todo lo que sucede dentro de la hoja de estilo.

RESUMEN

Utilice una herramienta como KSS para documentar e inventariar sus módulos.
Utilice una biblioteca de patrones para documentar ejemplos de marcado, variantes de módulo y JavaScript para sus módulos.
Desarrolle sus módulos "CSS first".
Considere la API que define su CSS, teniendo cuidado de nunca romperla de manera impredecible.
Versión de su CSS usando semver.
No agregue ciegamente un framework CSS a su página; tome selectivamente solo las piezas que necesite.