Sass

Utiliza nuestros archivos Sass fuente para aprovechar las variables, mapas, mixins y más.

Estructura de archivos

Siempre que sea posible, evita modificar los archivos principales de Bootstrap. Para Sass, eso significa crear tu propia hoja de estilo que importe Bootstrap para que puedas modificarlo y extenderlo. Suponiendo que estás usando un gestor de paquetes como npm, tendrás una estructura de archivos que se ve así:

tu-proyecto/
├── scss/
│   └── custom.scss
└── node_modules/
    └── bootstrap/
        ├── js/
        └── scss/
└── index.html

Si has descargado nuestros archivos fuente y no estás utilizando un gestor de paquetes, deberás crear manualmente algo similar a esa estructura, manteniendo los archivos fuente de Bootstrap separados de los tuyos.

tu-proyecto/
├── scss/
│   └── custom.scss
├── bootstrap/
│   ├── js/
│   └── scss/
└── index.html

Importación

En tu custom.scss, importarás los archivos Sass de origen de Bootstrap. Tienes dos opciones: incluir todo Bootstrap o elegir las partes que necesitas. Recomendamos lo segundo, aunque ten en cuenta que existen algunos requisitos y dependencias entre nuestros componentes. También deberás incluir algo de JavaScript para nuestros complementos.

// Custom.scss
// Opción A: Incluir todo Bootstrap

// Incluye cualquier anulación de variable predeterminada aquí (aunque las funciones no estarán disponibles)

@import "../node_modules/bootstrap/scss/bootstrap";

// Luego agrega código personalizado adicional aquí

// Custom.scss
// Opción B: Incluir partes de Bootstrap

// 1. Incluye las funciones primero (para que puedas manipular colores, SVG, calc, etc.)
@import "../node_modules/bootstrap/scss/functions";

// 2. Incluye cualquier anulación de variable predeterminada aquí

// 3. Incluye el resto de las hojas de estilo de Bootstrap requeridas (incluidas las hojas de estilo de modo de color independientes)
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

// 4. Incluye cualquier anulación de mapa predeterminada aquí

// 5. Incluye el resto de las partes requeridas
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. Incluye cualquier otra hoja de estilo parcial opcional según lo desees; la lista a continuación no incluye todas las hojas de estilo disponibles
@import "../node_modules/bootstrap/scss/utilities";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/containers";
@import "../node_modules/bootstrap/scss/grid";
@import "../node_modules/bootstrap/scss/helpers";
// ...

// 7. Opcionalmente, incluye la API de utilidades al final para generar clases basadas en el mapa Sass en `_utilities.scss`
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. Agrega código personalizado adicional aquí

Con esa configuración implementada, puedes comenzar a modificar cualquiera de las variables y mapas de Sass en tu custom.scss. También puedes comenzar a agregar partes de Bootstrap bajo la sección // Opcional según sea necesario. Sugerimos utilizar la pila de importación completa de nuestro archivo bootstrap.scss como punto de partida.

Compilación

Para utilizar tu código Sass personalizado como CSS en el navegador, necesitas un compilador Sass. Sass se distribuye como un paquete CLI, pero también puedes compilarlo con otras herramientas de compilación como Gulp o Webpack, o con aplicaciones GUI. Algunos IDE también tienen compiladores Sass integrados o como extensiones descargables.

Nos gusta usar la CLI para compilar nuestro Sass, pero puedes usar el método que prefieras. Desde la línea de comandos, ejecuta lo siguiente:

# Instalar Sass globalmente
npm install -g sass

# Monitorear tu Sass personalizado para detectar cambios y compilarlo a CSS
sass --watch ./scss/custom.scss ./css/custom.css

Obtén más información sobre tus opciones en sass-lang.com/install y compilación con VS Code.

Inclusión

Una vez que tu CSS esté compilado, puedes incluirlo en tus archivos HTML. Dentro de tu index.html querrás incluir tu archivo CSS compilado. Asegúrate de actualizar la ruta a tu archivo CSS compilado si la has cambiado.

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bootstrap personalizado</title>
    <link href="/css/custom.css" rel="stylesheet">
  </head>
  <body>
    <h1>¡Hola, mundo!</h1>
  </body>
</html>

Valores predeterminados de variables

Cada variable de Sass en Bootstrap incluye la bandera !default que te permite anular el valor predeterminado de la variable en tu propio Sass sin modificar el código fuente de Bootstrap. Copia y pega las variables según sea necesario, modifica sus valores y elimina la bandera !default. Si una variable ya ha sido asignada, entonces no será reasignada por los valores predeterminados en Bootstrap.

Encontrarás la lista completa de variables de Bootstrap en scss/_variables.scss. Algunas variables están establecidas en null; estas variables no generan la propiedad a menos que se anulen en tu configuración.

Las anulaciones de variables deben realizarse después de que se importen nuestras funciones, pero antes del resto de las importaciones.

Aquí hay un ejemplo que cambia el background-color y el color para el <body> al importar y compilar Bootstrap a través de npm:

// Requerido
@import "../node_modules/bootstrap/scss/functions";

// Anulaciones de variables predeterminadas
$body-bg: #000;
$body-color: #111;

// Requerido
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Componentes opcionales de Bootstrap aquí
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

Repite según sea necesario para cualquier variable en Bootstrap, incluidas las opciones globales a continuación.

Mapas y bucles

Bootstrap incluye un puñado de mapas de Sass, pares de clave-valor que facilitan la generación de familias de CSS relacionados. Usamos mapas de Sass para nuestros colores, puntos de interrupción de cuadrícula y más. Al igual que las variables de Sass, todos los mapas de Sass incluyen la bandera !default y se pueden anular y extender.

Algunos de nuestros mapas de Sass se fusionan en mapas vacíos de forma predeterminada. Esto se hace para permitir una fácil expansión de un mapa de Sass determinado, pero tiene el costo de hacer que la elimación de elementos de un mapa sea un poco más difícil.

Modificar mapa

Todas las variables en el mapa $theme-colors se definen como variables independientes. Para modificar un color existente en nuestro mapa $theme-colors, agrega lo siguiente a tu archivo Sass personalizado:

$primary: #0074d9;
$danger: #ff4136;

Más adelante, estas variables se establecen en el mapa $theme-colors de Bootstrap:

$theme-colors: (
  "primary": $primary,
  "danger": $danger
);

Agregar al mapa

Agrega nuevos colores a $theme-colors, o a cualquier otro mapa, creando un nuevo mapa de Sass con tus valores personalizados y fusionándolo con el mapa original. En este caso, crearemos un nuevo mapa $custom-colors y lo fusionaremos con $theme-colors.

// Crea tu propio mapa
$custom-colors: (
  "custom-color": #900
);

// Fusionar los mapas
$theme-colors: map-merge($theme-colors, $custom-colors);

Eliminar del mapa

Para eliminar colores de $theme-colors, o de cualquier otro mapa, usa map-remove. Ten en cuenta que debes insertar $theme-colors entre nuestros requisitos justo después de su definición en variables y antes de su uso en maps:

// Requerido
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

$theme-colors: map-remove($theme-colors, "info", "light", "dark");

@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Opcional
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

Claves requeridas

Bootstrap asume la presencia de algunas claves específicas dentro de los mapas de Sass, ya que nosotros mismos las usamos y extendemos. A medida que personalices los mapas incluidos, es posible que encuentres errores donde se esté utilizando una clave de mapa de Sass específica.

Por ejemplo, usamos las claves primary, success y danger de $theme-colors para enlaces, botones y estados de formulario. Reemplazar los valores de estas claves no debería presentar problemas, pero eliminarlos puede causar problemas de compilación de Sass. En estos casos, deberás modificar el código Sass que utiliza esos valores.

Funciones

Colores

Junto a los mapas de Sass de colores que tenemos, los colores del tema también se pueden usar como variables independientes, como $primary.

.custom-element {
  color: $gray-100;
  background-color: $dark;
}

Puedes aclarar u oscurecer los colores con las funciones tint-color() y shade-color() de Bootstrap. Estas funciones mezclarán colores con negro o blanco, a diferencia de las funciones nativas de Sass lighten() y darken() que cambiarán la luminosidad en una cantidad fija, lo que a menudo no produce el efecto deseado.

shift-color() combina estas dos funciones sombreando el color si el peso es positivo y tiñendo el color si el peso es negativo.

// Tint a color: mix a color with white
@function tint-color($color, $weight) {
  @return mix(white, $color, $weight);
}

// Shade a color: mix a color with black
@function shade-color($color, $weight) {
  @return mix(black, $color, $weight);
}

// Shade the color if the weight is positive, else tint it
@function shift-color($color, $weight) {
  @return if($weight > 0, shade-color($color, $weight), tint-color($color, -$weight));
}

En la práctica, llamarías a la función y pasarías los parámetros de color y peso.

.custom-element {
  color: tint-color($primary, 10%);
}

.custom-element-2 {
  color: shade-color($danger, 30%);
}

.custom-element-3 {
  color: shift-color($success, 40%);
  background-color: shift-color($success, -60%);
}

Contraste de color

Para cumplir con los requisitos de contraste de las Pautas de accesibilidad para el contenido web (WCAG), los autores deben proporcionar un contraste mínimo de color de texto de 4.5:1 y un contraste mínimo de color que no sea de texto de 3:1, con muy pocas excepciones.

Para ayudar con esto, incluimos la función color-contrast en Bootstrap. Utiliza el algoritmo de relación de contraste WCAG para calcular los umbrales de contraste basados en la luminancia relativa en un espacio de color sRGB para devolver automáticamente un color de contraste claro (#fff), oscuro (#212529) o negro (#000) basado en el color base especificado. Esta función es especialmente útil para mixins o bucles donde generas múltiples clases.

Por ejemplo, para generar muestras de color a partir de nuestro mapa $theme-colors:

@each $color, $value in $theme-colors {
  .swatch-#{$color} {
    color: color-contrast($value);
  }
}

También se puede usar para necesidades de contraste únicas:

.custom-element {
  color: color-contrast(#000); // devuelve `color: #fff`
}

También puedes especificar un color base con nuestras funciones de mapa de colores:

.custom-element {
  color: color-contrast($dark); // devuelve `color: #fff`
}

Escape SVG

Usamos la función escape-svg para escapar los caracteres <, > y # para las imágenes de fondo SVG. Al usar la función escape-svg, las URI de datos deben estar entre comillas.

Funciones Add y Subtract

Usamos las funciones add y subtract para envolver la función CSS calc. El propósito principal de estas funciones es evitar errores cuando se pasa un valor 0 "sin unidad" a una expresión calc. Expresiones como calc(10px - 0) devolverán un error en todos los navegadores, a pesar de ser matemáticamente correctas.

Ejemplo donde calc es válido:

$border-radius: .25rem;
$border-width: 1px;

.element {
  // La salida calc(.25rem - 1px) es válida
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Produce la misma salida calc(.25rem - 1px) que arriba
  border-radius: subtract($border-radius, $border-width);
}

Ejemplo donde calc no es válido:

$border-radius: .25rem;
$border-width: 0;

.element {
  // La salida calc(.25rem - 0) no es válida
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Salida .25rem
  border-radius: subtract($border-radius, $border-width);
}

Mixins

Nuestro directorio scss/mixins/ tiene una gran cantidad de mixins que potencian partes de Bootstrap y también se pueden usar en tu propio proyecto.

Esquemas de color

Está disponible un mixin abreviado para la consulta de medios prefers-color-scheme compatible con esquemas de color light y dark. Consulta la documentación de los modos de color para obtener información sobre nuestro mixin de modo de color.

@mixin color-scheme($name) {
  @media (prefers-color-scheme: #{$name}) {
    @content;
  }
}

.custom-element {
  @include color-scheme(light) {
    // Inserta estilos del modo claro aquí
  }

  @include color-scheme(dark) {
    // Inserta estilos del modo oscuro aquí
  }
}