# Bulma CSS — Complete Sass Reference

Full reference for Sass variables, mixins, extends, and customization architecture.

---

## 4-Tier Customization Architecture

Bulma uses a cascading system of variables:

1. **Tier 1 — Initial Sass Variables** (`utilities/initial-variables.scss`) — literal values
2. **Tier 2 — Derived Sass Variables** (`utilities/derived-variables.scss`) — computed from initial vars
3. **Tier 3 — Component Sass Variables** (per component file) — component-specific defaults
4. **Tier 4 — CSS Variables** (`:root` and component-level) — runtime-customizable

All Sass variables use `!default` — override them before importing Bulma.

---

## Complete Initial Variables

### Colors
| Variable | Default |
|----------|---------|
| `$black` | `hsl(221, 14%, 4%)` |
| `$black-bis` | `hsl(221, 14%, 9%)` |
| `$black-ter` | `hsl(221, 14%, 14%)` |
| `$grey-darker` | `hsl(221, 14%, 21%)` |
| `$grey-dark` | `hsl(221, 14%, 29%)` |
| `$grey` | `hsl(221, 14%, 48%)` |
| `$grey-light` | `hsl(221, 14%, 71%)` |
| `$grey-lighter` | `hsl(221, 14%, 86%)` |
| `$grey-lightest` | `hsl(221, 14%, 93%)` |
| `$white-ter` | `hsl(221, 14%, 96%)` |
| `$white-bis` | `hsl(221, 14%, 98%)` |
| `$white` | `hsl(221, 14%, 100%)` |
| `$orange` | `hsl(14, 100%, 53%)` |
| `$yellow` | `hsl(42, 100%, 53%)` |
| `$green` | `hsl(153, 53%, 53%)` |
| `$turquoise` | `hsl(171, 100%, 41%)` |
| `$cyan` | `hsl(198, 100%, 70%)` |
| `$blue` | `hsl(233, 100%, 63%)` |
| `$purple` | `hsl(271, 100%, 71%)` |
| `$red` | `hsl(348, 100%, 70%)` |

### Typography
| Variable | Default |
|----------|---------|
| `$family-sans-serif` | `"Inter", "SF Pro", "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Helvetica Neue", "Helvetica", "Arial", sans-serif` |
| `$family-monospace` | `"Inconsolata", "Hack", "SF Mono", "Roboto Mono", "Source Code Pro", "Ubuntu Mono", monospace` |
| `$render-mode` | `optimizeLegibility` |
| `$size-1` | `3rem` |
| `$size-2` | `2.5rem` |
| `$size-3` | `2rem` |
| `$size-4` | `1.5rem` |
| `$size-5` | `1.25rem` |
| `$size-6` | `1rem` |
| `$size-7` | `0.75rem` |
| `$weight-light` | `300` |
| `$weight-normal` | `400` |
| `$weight-medium` | `500` |
| `$weight-semibold` | `600` |
| `$weight-bold` | `700` |
| `$weight-extrabold` | `800` |

### Layout
| Variable | Default |
|----------|---------|
| `$block-spacing` | `1.5rem` |
| `$gap` | `32px` |
| `$column-gap` | `0.75rem` |
| `$aspect-ratios` | 15 tuples: (1,1), (5,4), (4,3), (3,2), (5,3), (16,9), (2,1), (3,1), (4,5), (3,4), (2,3), (3,5), (9,16), (1,2), (1,3) |

### Responsiveness
| Variable | Default |
|----------|---------|
| `$tablet` | `769px` |
| `$desktop` | `960px + 2 * $gap` (= 1024px) |
| `$widescreen` | `1152px + 2 * $gap` (= 1216px) |
| `$fullhd` | `1344px + 2 * $gap` (= 1408px) |
| `$widescreen-enabled` | `true` |
| `$fullhd-enabled` | `true` |

### Borders & Radius
| Variable | Default |
|----------|---------|
| `$radius-small` | `0.25rem` |
| `$radius` | `0.375rem` |
| `$radius-medium` | `0.5em` |
| `$radius-large` | `0.75rem` |
| `$radius-rounded` | `9999px` |

### Animation
| Variable | Default |
|----------|---------|
| `$duration` | `294ms` |
| `$easing` | `ease-out` |
| `$speed` | `86ms` |

### Configuration
| Variable | Default |
|----------|---------|
| `$variable-columns` | `true` |
| `$rtl` | `false` |
| `$class-prefix` | `""` |
| `$cssvars-prefix` | `"bulma-"` |
| `$helpers-prefix` | `"is-"` |
| `$helpers-has-prefix` | `"has-"` |

---

## Complete Derived Variables

### Scheme Colors
| Variable | Default |
|----------|---------|
| `$scheme-main` | `$white` |
| `$scheme-main-bis` | `$white-bis` |
| `$scheme-main-ter` | `$white-ter` |
| `$scheme-invert` | `$black` |
| `$scheme-invert-bis` | `$black-bis` |
| `$scheme-invert-ter` | `$black-ter` |

### Semantic Colors
| Variable | Default |
|----------|---------|
| `$primary` | `$turquoise` |
| `$info` | `$cyan` |
| `$success` | `$green` |
| `$warning` | `$yellow` |
| `$danger` | `$red` |
| `$light` | `$white-ter` |
| `$dark` | `$grey-darker` |
| `$link` | `$blue` |

### Text & UI Colors
| Variable | Default |
|----------|---------|
| `$text` | `$grey-dark` |
| `$text-invert` | `bulmaFindColorInvert($text)` |
| `$text-weak` | `$grey` |
| `$text-strong` | `$grey-darker` |
| `$background` | `$white-ter` |
| `$border` | `$grey-lighter` |
| `$border-weak` | `$grey-lightest` |
| `$code` | `$red` |
| `$code-background` | `$background` |
| `$pre` | `$text` |
| `$pre-background` | `$background` |
| `$shadow-color` | `$black` |

### Typography (Derived)
| Variable | Default |
|----------|---------|
| `$family-primary` | `$family-sans-serif` |
| `$family-secondary` | `$family-sans-serif` |
| `$family-code` | `$family-monospace` |
| `$size-small` | `$size-7` (0.75rem) |
| `$size-normal` | `$size-6` (1rem) |
| `$size-medium` | `$size-5` (1.25rem) |
| `$size-large` | `$size-4` (1.5rem) |

### Maps
| Variable | Default |
|----------|---------|
| `$custom-colors` | `null` |
| `$custom-shades` | `null` |
| `$colors` | `mergeColorMaps()` result |
| `$shades` | `mergeColorMaps()` result |
| `$sizes` | List of `$size-1` through `$size-7` |

---

## Sass Mixins

Import via `@use "bulma/sass/utilities/mixins"`.

### Element Mixins

| Mixin | Parameters | Description |
|-------|-----------|-------------|
| `mixins.arrow($color)` | `$color` | Down-facing arrow element |
| `mixins.burger($dimensions)` | `$dimensions` | Hamburger menu (3 bars, requires 4 `<span>` children) |
| `mixins.delete` | — | 20x20px circle with cross. Supports `.is-small`, `.is-medium`, `.is-large` |
| `mixins.loader` | — | 1em spinning circle animation |
| `mixins.fa($size, $dimensions)` | `$size`, `$dimensions` | Square inline-block for icon fonts |

### CSS Rule Mixins

| Mixin | Parameters | Description |
|-------|-----------|-------------|
| `mixins.block($spacing)` | `$spacing` | Adds margin-bottom (excluding last child) |
| `mixins.overlay($offset)` | `$offset` | Covers closest positioned ancestor |
| `mixins.center` | — | Absolute-centers a fixed-dimension element |
| `mixins.placeholder { }` | block | Styles `::placeholder` text |
| `mixins.clearfix` | — | `::after` with `clear: both` |
| `mixins.reset` | — | Soft style reset (useful for buttons) |
| `mixins.unselectable` | — | Prevents text selection |
| `mixins.overflow-touch` | — | `-webkit-overflow-scrolling: touch` |

### Direction Mixins (RTL support)

| Mixin | Parameters | Description |
|-------|-----------|-------------|
| `mixins.ltr { }` | block | Outputs when `$rtl: false` |
| `mixins.rtl { }` | block | Outputs when `$rtl: true` |
| `mixins.ltr-position($spacing, $right)` | `$spacing`, `$right` (bool) | Switches `left`/`right` |
| `mixins.ltr-property($property, $spacing, $right)` | `$property`, `$spacing`, `$right` | Flips margin/padding sides |

---

## Responsive Mixins

Import via `@use "bulma/sass/utilities/mixins"`.

### Parametric Mixins

| Mixin | Description | Output |
|-------|-------------|--------|
| `mixins.from($breakpoint)` | >= breakpoint | `@media screen and (min-width: $breakpoint)` |
| `mixins.until($breakpoint)` | < breakpoint | `@media screen and (max-width: $breakpoint - 1px)` |

### Named Shortcuts

| Mixin | Range |
|-------|-------|
| `mixins.mobile` | up to 768px |
| `mixins.tablet` | 769px and above |
| `mixins.tablet-only` | 769px — 1023px |
| `mixins.touch` | up to 1023px |
| `mixins.desktop` | 1024px and above |
| `mixins.desktop-only` | 1024px — 1215px |
| `mixins.until-widescreen` | below 1216px |
| `mixins.widescreen` | 1216px and above |
| `mixins.widescreen-only` | 1216px — 1407px |
| `mixins.until-fullhd` | below 1408px |
| `mixins.fullhd` | 1408px and above |

### Usage Example
```scss
@use "bulma/sass/utilities/mixins";

.my-element {
  font-size: 14px;

  @include mixins.tablet {
    font-size: 16px;
  }

  @include mixins.desktop {
    font-size: 18px;
  }

  @include mixins.from(1600px) {
    font-size: 20px;
  }
}
```

---

## Form Control Mixins

Import via `@use "bulma/sass/utilities/controls"`.

| Mixin | Description |
|-------|-------------|
| `controls.control` | Base control styles (shared by `.button`, `.input`, `.select`, `.file-cta`, `.file-name`, pagination) |
| `controls.control-small` | `font-size: $size-small` |
| `controls.control-medium` | `font-size: $size-medium` |
| `controls.control-large` | `font-size: $size-large` |

### Usage
```scss
@use "bulma/sass/utilities/controls";

.my-control {
  @include controls.control;
  background: deeppink;
  color: white;

  &.is-small { @include controls.control-small; }
  &.is-medium { @include controls.control-medium; }
  &.is-large { @include controls.control-large; }
}
```

---

## Sass Extends (Placeholders)

Import via `@use "bulma/sass/utilities/extends"`.

8 available placeholders:

| Placeholder | Description |
|------------|-------------|
| `%control` | Shared form control styles |
| `%unselectable` | Prevents text selection |
| `%arrow` | Down-facing arrow |
| `%block` | Margin-bottom spacing |
| `%delete` | Circle with cross |
| `%loader` | Spinning animation |
| `%overlay` | Covers positioned ancestor |
| `%reset` | Soft style reset |

### Usage
```scss
@use "bulma/sass/utilities/extends";

.my-control {
  @extend %control;
  background-color: purple;
  color: white;
}
```

---

## Customization with Sass (@use syntax, v1.x)

### Setup
```bash
npm install sass bulma
```

### package.json
```json
{
  "scripts": {
    "build-bulma": "sass --load-path=node_modules my-bulma.scss my-bulma.css",
    "start": "npm run build-bulma -- --watch"
  }
}
```

### Override Pattern (v1.x)
```scss
@use "bulma/sass" with (
  $family-primary: '"Nunito", sans-serif',
  $primary: #7952b3,
  $link: #e91e63,
  $control-border-width: 2px,
  $input-shadow: none
);
```

### Modular Import with Overrides
```scss
@use "bulma/sass/utilities";
@use "bulma/sass/base";
@use "bulma/sass/themes";

@use "bulma/sass/elements/button";
@use "bulma/sass/elements/title";
@use "bulma/sass/components/navbar";

@use "bulma/sass/layout/section" with (
  $section-padding: 3rem,
  $section-padding-desktop: 4.5rem
);
```

### Required Base Dependencies
Most components require:
```scss
@use "bulma/sass/base";    // Base styles and minireset
@use "bulma/sass/themes";  // CSS variables and theming
```

Exception: **Columns** are self-contained:
```scss
@use "bulma/sass/grid/columns"; // Works alone
```

### File Structure
| Path | Contents |
|------|----------|
| `bulma/sass/base` | Foundational styles, minireset |
| `bulma/sass/themes` | CSS variables and theming |
| `bulma/sass/utilities/` | Variables, functions, mixins |
| `bulma/sass/elements/` | button, title, tag, table, etc. |
| `bulma/sass/components/` | card, modal, navbar, etc. |
| `bulma/sass/form/` | input, select, textarea, etc. |
| `bulma/sass/grid/` | columns, grid |
| `bulma/sass/layout/` | section, hero, footer, container |
| `bulma/sass/helpers/` | Utility classes |

---

## Customization with CSS Variables

### Naming Convention
All CSS variables use `--bulma-` prefix (configurable via `$cssvars-prefix` Sass variable).

Pattern: `--bulma-[component/property]-[attribute]`

### Two Scope Levels

**Global scope** (`:root`):
```css
:root {
  --bulma-size-medium: 1.25rem;
  --bulma-primary-h: 171;
  --bulma-primary-s: 100%;
  --bulma-primary-l: 41%;
  --bulma-family-primary: "Nunito", sans-serif;
}
```

**Component scope** (overrides global):
```css
.button {
  --bulma-size-medium: 1.5rem;
}
.title {
  --bulma-title-color: #fff;
  --bulma-title-line-height: 1.6;
}
```

### Component CSS Variable Example
```css
/* What Bulma generates for .title */
.title {
  color: var(--bulma-title-color);
  font-size: var(--bulma-title-size);
  font-weight: var(--bulma-title-weight);
  line-height: var(--bulma-title-line-height);
}
```

### Custom Prefix
```scss
@use "bulma/sass" with (
  $cssvars-prefix: "my-"
);
// Result: --my-primary, --my-link, etc.
```