Sass

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

Estructura de archivos

Siempre que sea posible, evita modificar los archivos core de Bootstrap. Para Sass, eso significa crear tu propia hoja de estilos que importa Bootstrap para que puedas modificarlo y extenderlo. Asumiendo que usas un gestor de paquetes como npm, tendrás una estructura de archivos que se ve así:

your-project/
├── scss/
│   └── custom.scss
└── node_modules/
│   └── bootstrap/
│       ├── js/
│       └── scss/
└── index.html

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

your-project/
├── scss/
│   └── custom.scss
├── bootstrap/
│   ├── js/
│   └── scss/
└── index.html

Importar

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

// Custom.scss
// Option A: Include all of Bootstrap

// Include any default variable overrides here (though functions won’t be available)

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

// Then add additional custom code here

// Custom.scss
// Option B: Include parts of Bootstrap

// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import "../node_modules/bootstrap/scss/functions";

// 2. Include any default variable overrides here

// 3. Include remainder of required Bootstrap stylesheets (including any separate color mode stylesheets)
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

// 4. Include any default map overrides here

// 5. Include remainder of required parts
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. Include any other optional stylesheet partials as desired; list below is not inclusive of all available stylesheets
@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. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. Add additional custom code here

Con esa configuración en su lugar, puedes empezar a modificar cualquiera de las variables y mapas de Sass en tu custom.scss. También puedes empezar a añadir partes de Bootstrap bajo la sección // Optional según sea necesario. Sugerimos usar la pila completa de imports de nuestro archivo bootstrap.scss como punto de partida.

Compilar

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

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

# Install Sass globally
npm install -g sass

# Watch your custom Sass for changes and compile it to CSS
sass --watch ./scss/custom.scss ./css/custom.css

Aprende más sobre tus opciones en sass-lang.com/install y compilar con VS Code.

Incluir

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="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Custom Bootstrap</title>
    <link href="/css/custom.css" rel="stylesheet">
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

Valores predeterminados de variables

Cada variable de Sass en Bootstrap incluye el flag !default permitiéndote sobrescribir 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 el flag !default. Si una variable ya ha sido asignada, no se reasignará con los valores predeterminados de 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 sobrescriban en tu configuración.

Las sobrescrituras de variables deben ir después de que se importen nuestras funciones, pero antes del resto de los imports.

Aquí hay un ejemplo que cambia el background-color y el color del <body> al importar y compilar Bootstrap mediante npm:

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

// Default variable overrides
$body-bg: #000;
$body-color: #111;

// Required
@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";

// Optional Bootstrap components here
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

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

Mapas y bucles

Bootstrap incluye un puñado de mapas de Sass, pares clave-valor que facilitan la generación de familias de CSS relacionadas. Usamos mapas de Sass para nuestros colores, puntos de interrupción del grid y más. Al igual que las variables de Sass, todos los mapas de Sass incluyen el flag !default y pueden sobrescribirse y extenderse.

Algunos de nuestros mapas de Sass se combinan con mapas vacíos por defecto. Esto se hace para permitir la fácil expansión de un mapa de Sass dado, pero tiene el coste de hacer la eliminación de elementos de un mapa un poco más difícil.

Modificar mapa

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

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

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

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

Añadir al mapa

Añade nuevos colores a $theme-colors, o cualquier otro mapa, creando un nuevo mapa Sass con tus valores personalizados y combinándolo con el mapa original. En este caso, crearemos un nuevo mapa $custom-colors y lo combinaremos con $theme-colors.

// Create your own map
$custom-colors: (
  "custom-color": #900
);

// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

Eliminar del mapa

Para eliminar colores de $theme-colors, o 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:

// Required
@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";

// Optional
@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 las usamos y extendemos nosotros mismos. Al personalizar los mapas incluidos, puedes encontrar errores donde se está usando una clave específica de un mapa de Sass.

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

Funciones

Colores

Además de los mapas de Sass que tenemos, los colores del tema también pueden usarse como variables independientes, como $primary.

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

Puedes aclarar u oscurecer 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 lighten() y darken() de Sass que cambian la luminosidad en una cantidad fija, lo que a menudo no conduce al efecto deseado.

shift-color() combina estas dos funciones oscureciendo el color si el peso es positivo y aclarando 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 Web Content Accessibility Guidelines (WCAG), los autores deben proporcionar un contraste mínimo de color de texto de 4.5:1 y un contraste mínimo de color no textual de 3:1, con muy pocas excepciones.

Para ayudar con esto, incluimos la función color-contrast en Bootstrap. Usa el algoritmo de relación de contraste WCAG para calcular los umbrales de contraste basándose 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) basándose en el color base especificado. Esta función es especialmente útil para mixins o bucles donde estás generando 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 puntuales:

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

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

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

Escapar SVG

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

Funciones de suma y resta

Usamos las funciones add y subtract para envolver la función calc de CSS. El propósito principal de estas funciones es evitar errores cuando un valor “sin unidades” 0 se pasa 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 el calc es válido:

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

.element {
  // Output calc(.25rem - 1px) is valid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output the same calc(.25rem - 1px) as above
  border-radius: subtract($border-radius, $border-width);
}

Ejemplo donde el calc no es válido:

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

.element {
  // Output calc(.25rem - 0) is invalid
  border-radius: calc($border-radius - $border-width);
}

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

Mixins

Nuestro directorio scss/mixins/ tiene un montón de mixins que potencian partes de Bootstrap y que también pueden usarse en tu propio proyecto.

Esquemas de color

Un mixin abreviado para la media query prefers-color-scheme está disponible con soporte para esquemas de color light y dark. Consulta la documentación de modos de color para 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) {
    // Insert light mode styles here
  }

  @include color-scheme(dark) {
    // Insert dark mode styles here
  }
}