Skip to main content
skill CX Codex

bootstrap-utility-api — Claude Code skill: what it does

bootstrap-utility-api — a skill for Claude Code that manages the Bootstrap 6 utility API. It helps add, modify, or remove utility classes by editing the $utilities Sass map.

MIT 676 installs ★ 175,109 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add twbs/bootstrap --skill bootstrap-utility-api -a claude-code
Open on GitHub

What bootstrap-utility-api does

This skill automates Bootstrap 6 utility configuration by working directly with Sass variables. Instead of writing standard CSS, you edit the $utilities map in scss/_config.scss. The skill helps generate responsive variants, states like hover or focus, and dark mode support for new or modified classes.

Configuration must happen before loading Bootstrap to avoid compilation errors. When modifying default utilities, copy the full definition from scss/_utilities.scss because map merging is shallow.

What it helps with

  • Add a custom utility class to the project
  • Modify the behavior of default Bootstrap classes
  • Remove unused utilities from the build
  • Configure responsive variants for custom properties

Example prompts for the agent

  • Add a cursor utility to scss/_config.scss using bootstrap-utility-api
  • Override the overflow class to support responsiveness

How to install bootstrap-utility-api

1Skills CLI (Vercel)

npx skills add twbs/bootstrap --skill bootstrap-utility-api -a claude-code

2Manually: put the files in place

~/.claude/skills/bootstrap-utility-api/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bootstrap-utility-api/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bootstrap-utility-api

How to install bootstrap-utility-api in Claude Code?

Run the command npx skills add twbs/bootstrap --skill bootstrap-utility-api -a claude-code.

What does bootstrap-utility-api do?

It simplifies customizing Bootstrap 6 CSS utilities via Sass maps without writing manual styles.

What is required to use bootstrap-utility-api?

A Bootstrap 6 project and access to Sass configuration files.

Source text

SKILL.md · MIT
---
name: bootstrap-utility-api
description: Use, extend, and customize Bootstrap 6's utility API. Use when adding a custom utility class, modifying or removing Bootstrap's default utilities, enabling responsive or state variants, or trimming the generated utility CSS.
guide: /utilities/api
---

# Bootstrap 6 utility API

Every utility class Bootstrap ships is generated from one Sass map, `$utilities`. Each entry describes a family of classes — the property it sets, the values it accepts, and which variants to generate. Customizing utilities means editing that map, not writing CSS.

## Workflow

- [ ] Step 1: Understand how generation works
- [ ] Step 2: Read a utility definition
- [ ] Step 3: Add a utility
- [ ] Step 4: Modify, rename, or remove a default utility
- [ ] Step 5: Generate responsive, state, print, and dark variants
- [ ] Step 6: Compose values with custom properties and advanced selectors
- [ ] Step 7: Trim the generated CSS
- [ ] Step 8: Add a utility to Bootstrap itself
- [ ] Step 9: Verify

---

## Step 1: Understand how generation works

`scss/utilities/_api.scss` is the whole pipeline:

```scss
@include generate-utility-at-properties($utilities);

@layer utilities {
  @include generate-utilities-loop($utilities, $breakpoints);
}
```

Three consequences worth knowing before you touch anything:

- **Utilities are the last cascade layer**, so they win over component styles without needing `!important`. Only groups that opt in with `important: true` add it.
- **`@property` registration happens outside the layer.** Every custom property a utility assigns (`--bg`, `--fg`, `--bc`, `--rounded-size`, …) is registered with `syntax: "*"; inherits: false`, so applying `.border-inverse` doesn't leak its composed value into descendants. New utilities that assign custom properties get this automatically.
- **The map is configured on the `config` module, not `bootstrap`.** `$utilities` is declared in `scss/_config.scss` and only *populated* in `scss/_utilities.scss` (which loads config with `@use "config" as *`). Configuring the wrong module fails:

```scss
// Does NOT work — "This variable was not declared with !default in the @used module."
@use "bootstrap/scss/bootstrap" with (
  $utilities: (…)
);

// Works — configure config first, then load Bootstrap
@use "bootstrap/scss/config" with (
  $utilities: (…)
);
@use "bootstrap/scss/bootstrap";
```

The same applies to any variable that lives in `_config.scss` (`$radius`, `$spacers`, `$breakpoints`, `$zindex-levels`). Variables declared in a partial that `bootstrap.scss` forwards — `$root-tokens`, `$colors`, `$blue` — can be configured on `bootstrap` directly.

---

## Step 2: Read a utility definition

A group is a map. The simplest form needs two keys:

```scss
"overflow": (
  property: overflow,
  values: auto hidden visible scroll,
),
```

The full option set, as validated by `generate-utility()`:

| Key | Required | What it does |
| --- | --- | --- |
| `property` | Yes | Property name, space-separated list of names, or a map of property-to-value pairs |
| `values` | Yes | List (class suffix equals the value) or map (keys become suffixes; a `null` key omits the suffix) |
| `class` | No | Class name to use instead of the property name |
| `selector` | No | `class` (default), `attr-starts`, or `attr-includes` |
| `child-selector` | No | Descendant selector, wrapped in `:where()` for zero specificity |
| `variables` | No | Custom properties to emit — a map of static values, or a list that each receive the utility value |
| `state` | No | Pseudo-class variants to generate, e.g. `hover focus` |
| `responsive` | No | Generate a class per breakpoint (default `false`) |
| `print` | No | Generate `print:`-prefixed classes (default `false`) |
| `dark` | No | Generate `dark:`-prefixed classes inside `prefers-color-scheme: dark` (default `false`) |
| `important` | No | Append `!important` (default `false`) |
| `enabled` | No | Set `false` to suppress output while keeping the definition (default `true`) |

The generator validates as it goes, which makes mistakes cheap to find: a missing `property` or `values` is a hard `@error`, a non-boolean `responsive` is a hard `@error`, and a misspelled key is a `@warn` listing the valid ones.

---

## Step 3: Add a utility

Your map is merged over Bootstrap's defaults, so pass only what's new:

```scss
@use "bootstrap/scss/config" with (
  $utilities: (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    ),
  )
);
@use "bootstrap/scss/bootstrap";
```

That yields `.cursor-auto`, `.cursor-pointer`, `.cursor-grab`, plus `.sm:cursor-*` through `.2xl:cursor-*`.

Value shapes control the class names:

```scss
// List — suffix is the value itself: .cursor-pointer
values: auto pointer grab,

// Map — keys become suffixes: .tint-brand
values: (brand: var(--purple-500), muted: var(--gray-200)),

// null key — no suffix at all: .shout
values: (null: uppercase),
```

---

## Step 4: Modify, rename, or remove a default utility

The merge is **shallow**: supplying an existing group key replaces that entire group. Overriding one option and omitting the rest fails loudly —

```scss
// Errors: "Utility is missing required `property` key"
"overflow": (
  responsive: true,
  values: visible hidden scroll auto,
),
```

so copy the full definition from `scss/_utilities.scss` and add your change:

```scss
@use "bootstrap/scss/config" with (
  $utilities: (
    // Make overflow responsive
    "overflow": (
      property: overflow,
      values: auto hidden visible scroll,
      responsive: true,
    ),
    // Remove a family entirely
    "width": null,
    // Rename .ms-* to v4-style .ml-*: drop the original, add a replacement
    "margin-start": null,
    "margin-start-alias": (
      property: margin-inline-start,
      class: ml,
      responsive: true,
      values: (0: 0, 1: var(--spacer-1), 2: var(--spacer-2), auto: auto),
    ),
  )
);
@use "bootstrap/scss/bootstrap";
```

Note the CSS tokens in that last group. The file configuring `config` can't read Bootstrap's Sass members — `$spacers`, `$negative-spacers`, and helpers like `map-merge-multiple()` aren't in scope yet — so restate values as CSS tokens (`var(--spacer-2)`, which tracks the spacer scale) or as literals.

To *extend* an existing family without copying its definition, register a new group that reuses the same `class`:

```scss
"width-extra": (
  property: width,
  class: w,
  responsive: true,
  values: (10: 10%, 15: 15%),
),
```

This adds `.w-10` and `.w-15` next to Bootstrap's `.w-25` … `.w-100`, and is usually the better choice — it survives Bootstrap updates that change the original group.

Prefer `enabled: false` over `null` when you want the definition to stay visible in the map (useful in a shared config where the group is documented but intentionally off).

---

## Step 5: Generate responsive, state, print, and dark variants

v6 uses **prefixes**, not infixes or suffixes. All four variant types compose with the base class name:

| Option | Generated class | Notes |
| --- | --- | --- |
| `responsive: true` | `.md:cursor-pointer` | One pass per key in `$breakpoints`; written `.md\:` in the CSS |
| `state: hover focus` | `.hover:cursor-pointer` | Selector is `.hover\:cursor-pointer:hover` |
| `print: true` | `.print:d-none` | Wrapped in `@media print` |
| `dark: true` | `.dark:bg-black` | Wrapped in `@media (prefers-color-scheme: dark)` |

`responsive` and `state` stack, producing `.md:hover:cursor-pointer`. Each variant multiplies the generated CSS, so enable them per group rather than globally.

---

## Step 6: Compose values with custom properties and advanced selectors

Most color-ish utilities don't set the property directly. They assign a local custom property and then consume it, which is what makes opacity and composition work:

```scss
"tint": (
  property: (
    "--tint": null,
    "background-color": var(--tint),
  ),
  class: tint,
  values: (brand: var(--purple-500)),
),
```

A `null` value in the property map means "receive the utility's value"; every other entry is emitted as written. The above generates:

```css
.tint-brand {
  --tint: var(--purple-500);
  background-color: var(--tint);
}
```

Related mechanics:

- **`variables`** emits extra custom properties. As a map, each gets a static value on every class in the group; as a list, each receives the utility's value.
- **Property maps plus map values.** When `property` is a map and a `values` entry is itself a map keyed by property name, each property picks its own value — useful for a group that sets several related properties at different values.
- **`selector: attr-starts` / `attr-includes`** targets `[class^="…"]` / `[class*="…"]` instead of a class, and requires a `class` key. Bootstrap uses it so `.ratio-16x9` can feed `aspect-ratio` through `--ratio`.
- **`child-selector`** wraps the rule in `:where()`, e.g. `:where(.stack-gap-1 > *)`. Zero specificity means a child's own styles still win.

Custom property names are written **unprefixed** in Sass. Bootstrap's dist and CDN CSS run PostCSS to add `--bs-`, so compiling the source yourself keeps them unprefixed.

---

## Step 7: Trim the generated CSS

Utilities are the biggest slice of Bootstrap's CSS, and the map is the cheapest place to cut:

1. Start from the utilities-only entry point if you don't need components:

   ```scss
   @use "bootstrap/scss/config" with ($utilities: (…));
   @use "bootstrap/scss/bootstrap-utilities";
   ```

2. Set unused groups to `null` (or `enabled: false`) rather than relying on the minifier or a purge step.
3. Turn `responsive` off on groups you only use at one breakpoint — a responsive group costs six copies of itself.
4. Narrow `values` maps instead of deleting whole groups when you only need a few steps.

See [Optimize]([[docsref:/customize/optimize/]]) for the wider picture, including Lightning CSS and purging.

---

## Step 8: Add a utility to Bootstrap itself

When contributing a utility to the framework rather than a project:

1. Add the group to the `$utilities` map in `scss/_utilities.scss`, near related groups, wrapped in `// scss-docs-start utils-<name>` / `// scss-docs-end utils-<name>` markers.
2. Prefer composing through a custom property when the utility should interact with opacity or theme colors, and reuse existing token values (`$spacers`, `$util-opacity`, `theme-color-refs()`) instead of literals.
3. Document it on the matching page in `site/src/content/docs/utilities/`, rendering the definition with `<ScssDocs name="utils-<name>" file="scss/_utilities.scss" />`, and add a `site/data/sidebar.yml` entry if the page is new.
4. Add coverage in `scss/tests/utilities/_api.test.scss`, which calls the generator mixins directly with a fixture map.
5. Run `npm run css`. Its `css-docs` step regenerates `dist/css/bootstrap-utilities.metadata.json`, which the docs read — commit it alongside your change.

---

## Step 9: Verify

1. `npm run css-lint`, then `npm run css`.
2. Grep the compiled CSS for the classes you expected, including the escaped variants (`\.md\\:cursor-pointer`), and confirm nothing you removed is still present.
3. Confirm new custom properties appear in the `@property` block at the top of the file — if one is missing, the utility isn't assigning it through `property` or `variables`.
4. Watch the Sass output for `@warn` lines about unknown keys; they're the fastest signal that an option was misspelled and silently ignored.
5. Check specificity in the browser: utilities should override component styles through the layer order alone, without `!important`.

© twbs · MIT · twbs/bootstrap

Similar skills

All skills for Frontend and UI →

From the same set11

The whole set →
bootstrap-color-system bootstrap-color-system — a Claude Code skill for editing Bootstrap 6 colors in Sass and CSS. It activates for theme color changes, color modes, and work with semantic tokens or color scales. CX Codex +1 703installs bootstrap-component bootstrap-component — a skill for Claude Code that automates the creation of Bootstrap 6 components. It generates CSS, markup, and token maps when building new UI elements. CX Codex +1 697installs bootstrap-component-js The bootstrap-component-js Claude Code skill guides JavaScript work on Bootstrap 6 components. It applies when adding a TypeScript module, wiring events and the data API, or wrapping a third-party library. CX Codex +1 687installs bootstrap-v6-install bootstrap-v6-install — a skill for Claude Code and Cursor that sets up Bootstrap 6 via CDN or package manager. The script configures Sass, JavaScript, and local paths. CX Codex +1 677installs bootstrap-v5-v6-migration bootstrap-v5-v6-migration is a Claude Code skill that guides project upgrades from Bootstrap 5 to 6. It runs when updating build tools, CSS classes, components, Sass tokens, or scripts. CX Codex +1 667installs bootstrap-vite The bootstrap-vite Claude Code skill sets up Bootstrap 6 CSS and JavaScript in a Vite project. It activates for project setup or when bundling Bootstrap Sass through Vite. CX Codex +1 641installs bootstrap-npm bootstrap-npm — a skill for Claude Code and Cursor builds a Bootstrap 6 starter project using npm and command-line tools without a bundler. Runs when setting up Bootstrap with npm or compiling Sass. CX Codex +1 639installs bootstrap-parcel The bootstrap-parcel Claude Code skill sets up Bootstrap 6 in a Parcel project. It connects Sass and JavaScript, adds a start script, and guides the build check. CX Codex +1 612installs

Project sponsors

Companies that keep this analytics open