Code Guide logo

Guía de Código

Estándares para desarrollar HTML y CSS consistentes, flexibles y sostenibles.

Creado por @mdo · v4.0.0 · Repositorio GitHub

Traducido por @hansfelix · v4.0.0 · Repositorio GitHub

Tabla de contenido

HTML

CSS

Regla de oro

Cumpla los siguientes estándares, o los suyos, en todo momento. No importa si el error es pequeño o grande, evite lo que es incorrecto. Para adiciones o contribuciones a esta Guía de código, cree un issue en GitHub.

Cada línea de código debe parecer escrita por una sola persona, no importa el número de contribuyentes que tenga el proyecto.

HTML

Sintaxis

<!doctype html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

Utilice el modo estándar para una representación más consistente en todos los navegadores declarando el doctype simple al comienzo de cada página HTML. Manteniendo la sintaxis sugerida use siempre minúsculas.

<!doctype html>
<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

Atributo de idioma

De acuerdo a las especificaciones HTML5:

Se recomienda a los autores a especificar el atributo lang en el elemento html raíz, dando el idioma del documento. Esto ayuda a las herramientas de síntesis de voz a determinar qué pronunciaciones usar y a las herramientas de traducción a determinar qué reglas usar, etc.

Lea más información sobre el atributo lang en las especificaciones de HTML5. Dirígase a la IANA para obtener una lista de códigos de idioma.

<html lang="es">
  <!-- ... -->
</html>

Modo de compatibilidad con IE

No es necesario incluir la etiqueta <meta> para compatibilidad de documentos de Internet Explorer en estos días, a menos que necesite soporte para IE10 y versiones anteriores. La etiqueta se eliminó en IE11 y no se usa en Microsoft Edge (heredado o no).

Para más información, lea este increíble artículo de Stack Overflow.

<!-- IE10 y versiones anteriores solamente -->
<meta http-equiv="x-ua-compatible" content="ie=edge">

Codificación de caracteres

Garantice una representación adecuada del contenido declarando una codificación de caracteres explícita. Esto también le permite usar caracteres regulares en lugar de sus entidades HTML, como — en lugar de &emdash;, siempre que su codificación coincida con la del documento. Para algunos caracteres XML reservados, como ampersand, espacios de no separación, menor/mayor que y comillas, es posible que aún necesite usar las entidades HTML.

UTF-8 es la codificación recomendada.

<head>
  <meta charset="utf-8">
</head>
<body>
  <p>Para usar un guión largo como — no es requerido una entidad HTML.</p>
</body>

Vinculación de archivos CSS y JavaScript

Según la especificación de HTML5, normalmente no es necesario especificar el atributo type cuando se incluyen archivos CSS y JavaScript, ya que text/css y text/javascript son sus respectivos valores predeterminados.

Especificaciones HTML5

<!-- CSS externo -->
<link rel="stylesheet" href="code-guide.css">

<!-- CS dentro del documento -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Practicidad sobre pureza

Esfuércese por mantener los estándares y semántica HTML, pero no a costa de la practicidad. Use la menor cantidad de marcado con la menor cantidad de complejidades, siempre que sea posible.

<!-- Correcto -->
<button>...</button>

<!-- Incorrecto -->
<div class="btn" onClick="...">...</div>

Orden de los atributos

Los atributos HTML deben seguir este orden particular para facilitar la lectura del código.

Los atributos que más se usan para identificar elementos deben ir primero— atributos class, id, name y data. Los atributos misceláneos exclusivos de elementos específicos ocupan el segundo lugar, seguidos de los atributos relacionados con la accesibilidad y el estilo.

<a class="..." id="..." data-toggle="modal" href="#">
  Link de ejemplo
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Atributos booleanos

Un atributo booleano es aquel que no necesita un valor declarado. XHTML requería que declarara un valor, pero HTML5 no tiene tal requisito.

Para más información, consulte la sección de WhatWG sobre atributos booleanos

La presencia de un atributo booleano en un elemento representa el valor verdadero y la ausencia del atributo representa el valor falso.

Si debe incluir el valor del atributo y no es necesario, siga esta guía de WhatWG:

Si el atributo está presente, su valor debe ser la cadena vacía o […] el nombre canónico del atributo, sin espacios en blanco al principio o al final.

En resumen, no añada un valor.

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

Reducir las etiquetas

Siempre que sea posible, evite los elementos padres redundantes al escribir HTML. Muchas veces esto requiere iteración y refactorización de código, pero produce menos HTML.

<!-- No tan bueno -->
<span class="avatar">
  <img src="...">
</span>

<!-- Mejor -->
<img class="avatar" src="...">

Preferencias del editor

Pepare su editor con las siguientes configuraciones para evitar inconsistencias de código comunes y diferencias:

Considere documentar y aplicar estas preferencias al archivo .editorconfig de su proyecto. Para ver un ejemplo, revise el de Bootstrap. Obtenga más información sobre EditorConfig.

CSS

Sintaxis CSS

¿Preguntas sobre los términos utilizados aquí? Consulte la sección de sintaxis del artículo Hojas de Estilo en Cascada en Wikipedia.

// Mal CSS
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

// Buen CSS
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgb(0 0 0 / .5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Orden en la declaración

Las declaraciones de las propiedades CSS deben agruparse en el siguiente orden:

  1. Posicionamiento
  2. Modelo de caja
  3. Tipografía
  4. Visual
  5. Misceláneo

El posicionamiento es lo primero porque puede eliminar un elemento del flujo normal del documento y anular los estilos relacionados con el modelo de caja. El modelo de caja—ya sea flex, float, grid o table—es lo siguiente, ya que dicta las dimensiones, la ubicación y la alineación del componente. Todo lo demás tiene lugar dentro del componente o no afecta a las dos grupos anteriores, por lo que quedan en último lugar.

Si bien border es parte del modelo de caja, la mayoría de los sistemas restablecen globalmente el box-sizing a border-box para que border-width no afecte las dimensiones generales. Todo esto, combinado con mantener el border cerca de border-radius, es la razón por la que está en la sección visual.

Los mixins y funciones de los preprocesadores deben aparecer donde sea más apropiado. Por ejemplo, un mixin border-top-radius() reemplazaría las propiedades border-radius, mientras que una función responsive-font-size() reemplazaría las propiedades font-size.

Para obtener una lista completa de propiedades y su orden, consulte el orden de propiedades de Stylelint utilizado por Bootstrap.

.declaration-order {
  // Posicionamiento
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  // Modelo de caja
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  width: 100px;
  height: 100px;

  // Tipografía
  font: normal 14px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;
  text-decoration: underline;

  // Visual
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  // Misceláneo
  opacity: 1;
}

Propiedades lógicas

Las propiedades lógicas son alternativas a las propiedades direccionales y dimensionales basadas en términos como block e inline. Por defecto, block se refiere a la dirección vertical (arriba y abajo) mientras que inline se refiere a la dirección horizontal (derecha e izquierda). Puede comenzar a usar estos valores en su CSS en todos los navegadores modernos y futuros.

¿Por qué usar propiedades lógicas? No todos los idiomas se escriben de izquierda a derecha como el español o inglés, por lo que el writing mode debe ser flexible. Con propiedades lógicas, puede admitir fácilmente idiomas que se pueden escribir horizontal o verticalmente (como el chino, japonés y coreano). Además, estas propiedades suelen ser más breves y fáciles de escribir.

Más información:

// Sin propiedades lógicas
.element {
  margin-right: auto;
  margin-left: auto;
  border-top: 1px solid #eee;
  border-bottom: 1px solid #eee;
}

// Con propiedades lógicas
.element {
  margin-inline: auto;
  border-block: 1px solid #eee;
}

Colores

Con el soporte de CSS Color Levels 4 en todos los principales navegadores, rgba() y hsla() ahora son alias para rgb() y hsl(), lo que significa que puede modificar los valores alpha en rgb() y hsl(). Junto con esto viene el soporte para la nueva sintaxis separada por espacios para los valores de color. Para compatibilidad con futuras funciones de color CSS use esta nueva sintaxis.

Independientemente de los valores y la sintaxis de color, siempre asegúrese de que sus opciones de color cumplan con las relaciones de contraste mínimas de WCAG (4,5:1 para 16 px y más pequeños, 3:1 para más grandes).

Más información:

.element {
  color: rgb(255 255 255 / .65);
  background-color: rgb(0 0 0 / .95);
}

Evite los @imports

En comparación con <link>, @import es más lento, ya que agrega solicitudes de página adicionales y puede causar otros problemas no previstos. Evítelos y opte por un enfoque alternativo:

Compared to <link>s, @import is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach:

Para más información, puede leer este artículo de Steve Souders.

<!-- Use elementos <link> -->
<link rel="stylesheet" href="core.css">

<!-- Evite los @imports -->
<style>
  @import url("more.css");
</style>

Ubicación de los media query

Ubique las sentencias media query lo más cerca posible de sus conjuntos de reglas relevantes, siempre que sea posible. No los agrupe todos en una hoja de estilo separada o al final del documento, hacer esti solo hará que sea más fácil que los desarrolladores los olviden a futuro. Aquí hay una configuración de ejemplo.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ... }
  .element-avatar { ... }
  .element-selected { ... }
}

Declaraciones de una línea

En los casos en que un conjunto de reglas incluya solo una declaración, considere eliminar los saltos de línea para facilitar la lectura y una edición más rápida. Cualquier conjunto de reglas con múltiples declaraciones debe dividirse en líneas separadas.

El factor clave aquí es la detección de errores, por ejemplo, un validador de CSS que indica que tiene un error de sintaxis en la línea 183. Con una sola declaración, no se puede perder. Con múltiples declaraciones, las líneas separadas son imprescindibles para su entendimiento.

// Declaración de una sola línea
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

// Declaraciones de varias líneas, una por línea
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url("../img/sprite.png");
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Notaciones abreviadas

Limite el uso de propiedades abreviadas a instancias en las que debe establecer explícitamente todos los valores disponibles. Las propiedades abreviadas que se suelen usar en exceso frecuentemente incluyen:

Por lo general, no necesitamos establecer todos los valores que representa una propiedad abreviada. Por ejemplo, los encabezados HTML solo establecen el margen superior e inferior, por lo que si es necesario, solo anule esos dos valores. Un valor 0 implica una anulación de un valor predeterminado del navegador o un valor especificado previamente.

El uso excesivo de propiedades abreviadas conduce a un código más descuidado con anulaciones innecesarias y efectos secundarios no deseados.

La Mozilla Developer Network tiene un excelente artículo sobre propiedades abreviadas para aquellos que no esten familiarizados con su notación y comportamiento.

// Mal ejemplo
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

// Buen ejemplo
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

Anidamiento en preprocesadores

Evite el anidamiento innecesario en los preprocesadores siempre que sea posible—manténgalo simple y evite el anidamiento inverso. Considere anidar solo si debe aplicar estilos a un padre y si este tiene varios elementos para anidar.

Más información:

// Sin anidamiento
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// Con anidamiento
.table > thead > tr {
  > th { … }
  > td { … }
}

Operadores en preprocesadores

Para mejorar la legibilidad, encierre todas las operaciones matemáticas entre paréntesis separadas con un espacio en blanco entre valores, variables y operadores.

// Mal ejemplo
.element {
  margin: 10px 0 @variable*2 10px;
}

// Buen ejemplo
.element {
  margin: 10px 0 (@variable * 2) 10px;
}

Comentarios

El código es escrito y mantenido por varias personas. Asegúrese de que su código sea descriptivo, correctamente comentado y accesible para los demás. Los grandes comentarios de código transmiten contexto o propósito. No reitere simplemente el nombre de un componente o clase. Utilice la sintaxis de comentario // al escribir CSS con preprocesadores. Al enviar CSS a producción elimine todos los comentarios.

Asegúrese de escribir oraciones completas para comentarios más extensos y frases breves para notas generales.

// Mal ejemplo
// Cabecera del modal
.modal-header {
  ...
}

// Buen ejemplo
// Elemento que encierra a .modal-title y .modal-close
.modal-header {
  ...
}

Nombre de las clases

También es útil aplicar muchas de estas mismas reglas al crear propiedades personalizadas y nombres de variables de preprocesadores.

// Mal ejemplo
.t { ... }
.red { ... }
.header { ... }

// Buen ejemplo
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selectores

Más información:

// Mal ejemplo
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

// Buen ejemplo
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Selectores de hijos y de descendientes

Cuando sea necesario, puede ser útil usar el selector de hijos (>) para limitar la cascada de algunos estilos en elementos como <table> que a menudo están anidados recursivamente. Úselo para limitar los estilos a los elementos secundarios inmediatos de un elemento principal para evitar anulaciones innecesarias más adelante.

.custom-table > tbody > tr > td,
.custom-table > tbody > tr > th {
  /* ... */
}

Organización

//
// Encabezado de la sección de componentes
//

.element { ... }


//
// Encabezado de la sección de componentes
//
// A veces es necesario incluir un contexto opcional para todo el componente. Haz eso aquí arriba si es algo importante.
//

.element { ... }

// Subcomponente contextual o modificador
.element-heading { ... }