bootstrap-component — Claude Code skill: what it does, how to install
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.
MIT 697 installs ★ 175,109 updated 2026-11-16
npx skills add twbs/bootstrap --skill bootstrap-component -a claude-codeWhat bootstrap-component does
This skill assists in maintaining Bootstrap 6 architectural standards while authoring component styles. It automates the setup of partial files, token map declarations, and modifier classes according to the framework's internal logic.
The skill requires an existing project with Sass files. It utilizes defaults() for managing overrides and enforces the use of mixins like border-radius and transition. Note that you should never edit generated output in dist/ or js/dist/, as the skill operates on source files in scss/ or js/src/ directories.
What it helps with
- create a new Bootstrap component structure
- configure a CSS token map for a component
- add component modifiers and variants
- implement responsive sizing for elements
Example prompts for the agent
- Create a new component named
cardinscss/ - Configure the token map for the
widgetcomponent - Add an
outlinevariant to the current component
How to install bootstrap-component
1Skills CLI (Vercel)
npx skills add twbs/bootstrap --skill bootstrap-component -a claude-code2Manually: put the files in place
~/.claude/skills/bootstrap-component/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/bootstrap-component/
1Skills CLI (Vercel)
npx skills add twbs/bootstrap --skill bootstrap-component -a codex2Manually: put the files in place
.agents/skills/bootstrap-component/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add twbs/bootstrap --skill bootstrap-component -a cursor2Manually: put the files in place
.cursor/skills/bootstrap-component/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install twbs/bootstrap skills/bootstrap-component2Manually: put the files in place
.github/skills/bootstrap-component/SKILL.md1Skills CLI (Vercel)
npx skills add twbs/bootstrap --skill bootstrap-component -a gemini-cli2Platform CLI
gemini skills install https://github.com/twbs/bootstrap --path skills/bootstrap-componentManually: put the files in place
.devin/skills/bootstrap-component/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add twbs/bootstrap --skill bootstrap-component -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about bootstrap-component
How to install bootstrap-component in Claude Code?
Run the command npx skills add twbs/bootstrap --skill bootstrap-component -a claude-code in your project terminal.
What does bootstrap-component do?
It helps developers build Bootstrap 6 components by automatically generating the necessary CSS file structure, token maps, and modifier classes following framework standards.
What is required to use bootstrap-component?
You need a project that uses Bootstrap source files (Sass), as the skill works directly with the scss/ directory.
Source text
SKILL.md · MIT
---
name: bootstrap-component
description: Build a Bootstrap 6 component's CSS and markup. Use when creating a new component, adding modifier or variant classes, or authoring component styles with Bootstrap's Sass token maps and theme overrides.
guide: /customize/components
---
# Bootstrap 6 component CSS
Author a component's styles and markup — the non-JavaScript pieces. Bootstrap 6 components are built from a Sass map of CSS custom properties (the token map), a base class that emits those tokens, and modifier classes that override them.
For interactive behavior, see the `bootstrap-component-js` skill. For palettes, theme colors, and color modes, see the `bootstrap-color-system` skill.
## Workflow
- [ ] Step 1: Plan the component
- [ ] Step 2: Create the partial and token map
- [ ] Step 3: Write the base class
- [ ] Step 4: Add modifiers, variants, and sizes
- [ ] Step 5: Wire up theme colors
- [ ] Step 6: Markup and accessibility
- [ ] Step 7: Register the partial
- [ ] Step 8: Document the component
- [ ] Step 9: Verify
---
## Step 1: Plan the component
1. Pick a singular, kebab-case name. It drives everything: the partial `scss/_<name>.scss`, the base class `.<name>`, the token prefix `--<name>-*`, and the map `$<name>-tokens`.
2. Decide what the component needs before writing CSS:
- **Tokens only** — one look, customized through CSS variables. Model on `scss/_alert.scss`.
- **Variants** — contextual color treatments like `.badge-subtle`. Model on `scss/_badge.scss`.
- **Variants and sizes** — model on `scss/buttons/_button.scss`.
3. Check whether an existing component already covers the need. Extending one with a modifier is preferable to adding a near-duplicate.
Never edit generated output in `dist/`, `js/dist/`, or `_site/`. Source lives in `scss/` and `js/src/`.
---
## Step 2: Create the partial and token map
Create `scss/_<name>.scss`. Declare the empty map first, then fill it through `defaults()`:
```scss
@use "config" as *;
@use "functions" as *;
@use "mixins/border-radius" as *;
@use "mixins/tokens" as *;
$widget-tokens: () !default;
// scss-docs-start widget-tokens
// stylelint-disable-next-line scss/dollar-variable-default
$widget-tokens: defaults(
(
--widget-gap: var(--spacer-2),
--widget-padding-x: var(--spacer-4),
--widget-padding-y: var(--spacer-2),
--widget-color: var(--theme-fg, inherit),
--widget-bg: var(--theme-bg-subtle, var(--bg-1)),
--widget-border-color: var(--theme-border, var(--border-color)),
--widget-border-radius: var(--radius-5),
),
$widget-tokens
);
// scss-docs-end widget-tokens
```
Rules that matter here:
- The `$widget-tokens: () !default;` line is what makes the map overridable — `@use "bootstrap/scss/bootstrap" with ($widget-tokens: (…))` writes into it, and `defaults()` merges those overrides over your defaults. Passing `null` for a key removes that token entirely.
- The second assignment needs the `stylelint-disable-next-line scss/dollar-variable-default` comment, since it intentionally reassigns without `!default`.
- Token names are namespaced to the component and written **unprefixed**. Bootstrap's dist and CDN CSS run PostCSS to add the `--bs-` prefix (`--bs-widget-bg`); compiling the source yourself keeps them unprefixed.
- Build values from existing global tokens — `var(--spacer-3)`, `var(--radius-5)`, `var(--border-width)`, `var(--font-weight-semibold)` — rather than hardcoded lengths, so the component scales with the rest of the framework.
- The `scss-docs-start` / `scss-docs-end` markers are load-bearing: the docs page renders the map with `<ScssDocs>`, which throws at build time if the markers are missing.
---
## Step 3: Write the base class
Declarations go inside a cascade layer, with the token map emitted on the root selector:
```scss
@layer components {
.widget {
@include tokens($widget-tokens);
display: flex;
gap: var(--widget-gap);
align-items: center;
padding: var(--widget-padding-y) var(--widget-padding-x);
color: var(--widget-color);
background-color: var(--widget-bg);
border: var(--border-width) solid var(--widget-border-color);
@include border-radius(var(--widget-border-radius));
}
}
```
- Pick the right layer. Components use `@layer components`, form controls `@layer forms`, helpers `@layer helpers`. The order is declared once in `scss/_root.scss`: `colors, config, root, reboot, layout, content, forms, components, custom, helpers, utilities`.
- `@include tokens($widget-tokens)` comes first, then declarations, then nested rules. Declarations read `var(--widget-*)`, never the Sass map directly.
- Use `@include border-radius()` and `@include transition()` instead of the raw properties — stylelint blocks the raw ones because the mixins honor `$enable-rounded`, `$enable-transitions`, and `prefers-reduced-motion`.
- Use logical properties (`padding-inline-start`, `margin-block-end`, `inset-inline-start`) so the component works in RTL without an override.
- No `lighten()` / `darken()` — use `color-mix()`, relative `oklch()`, or `light-dark()`. No `border: none` / `outline: none` — use `0`.
---
## Step 4: Add modifiers, variants, and sizes
A modifier only overrides tokens; it should not repeat the base declarations:
```scss
.widget-lg {
--widget-padding-x: var(--spacer-6);
--widget-padding-y: var(--spacer-3);
--widget-border-radius: var(--radius-7);
}
```
When a component has a set of contextual treatments, drive them from an overridable map whose values are **theme sub-keys**, then loop. This is the `scss/_badge.scss` pattern:
```scss
// scss-docs-start widget-variants
$widget-variants: () !default;
$widget-variants: defaults(
(
"subtle": (
"color": "fg",
"bg": "bg-subtle",
"border-color": "transparent"
),
"outline": (
"color": "fg",
"bg": "transparent",
"border-color": "border"
)
),
$widget-variants
);
// scss-docs-end widget-variants
@layer components {
// scss-docs-start widget-variant-loop
@each $variant, $properties in $widget-variants {
.widget-#{$variant} {
@each $property, $value in $properties {
@if $value == "transparent" {
--widget-#{$property}: transparent;
} @else {
--widget-#{$property}: var(--theme-#{$value});
}
}
}
}
// scss-docs-end widget-variant-loop
}
```
Mapping to theme sub-keys rather than literal colors is what lets `.widget-outline.theme-success` work without a variant-per-color explosion.
Sizes follow the button pattern: a list run through `defaults()`, looped into classes that re-point the component's tokens at the shared `--btn-input-<size>-*` scale.
```scss
$widget-sizes: () !default;
$widget-sizes: defaults(
("sm", "lg"),
$widget-sizes
);
```
`defaults()` turns a list into a map, so a project can drop a size with `$widget-sizes: ("sm": null)` or add its own.
---
## Step 5: Wire up theme colors
Theme classes (`.theme-primary`, `.theme-danger`, …) are generated from `$theme-colors` and set a fixed set of variables: `--theme-base`, `--theme-fg`, `--theme-fg-emphasis`, `--theme-bg`, `--theme-bg-subtle`, `--theme-bg-muted`, `--theme-border`, `--theme-focus-ring`, and `--theme-contrast`.
A component gets theme support for free by reading those variables with a neutral fallback, which is why the defaults in Step 2 look like this:
```scss
--widget-color: var(--theme-fg, inherit),
--widget-bg: var(--theme-bg-subtle, var(--bg-1)),
--widget-border-color: var(--theme-border, var(--border-color)),
```
Unthemed markup uses the fallbacks; adding a theme class recolors the component with no extra CSS:
```html
<div class="widget theme-danger">…</div>
```
Use `.theme-reset` on a nested subtree to drop inherited `--theme-*` tokens and return to those fallbacks.
Do not hardcode `var(--red-500)` or a specific theme color in component tokens. Adding or overriding theme colors themselves is covered by the `bootstrap-color-system` skill.
---
## Step 6: Markup and accessibility
- Start from the semantic element. Add ARIA only where the markup can't convey meaning on its own — for example `role="alert"` on a live message, `aria-expanded` on a disclosure trigger.
- Interactive parts must be reachable by keyboard and show a visible focus ring. The `.focus-ring` helper applies `outline: var(--focus-ring-width) solid var(--theme-focus-ring, var(--focus-ring-color))` on `:focus-visible`; theme-aware components inherit the right color automatically.
- Give icon-only controls an accessible name with `.visually-hidden` text or `aria-label`.
- Never signal state through color alone; pair it with text, an icon, or an ARIA attribute.
- Keep the markup RTL-safe: logical properties in CSS, no left/right assumptions in the DOM order.
---
## Step 7: Register the partial
Forward the partial from `scss/bootstrap.scss` in the components block, keeping the existing ordering:
```scss
@forward "widget";
```
Components that live in a subdirectory (`scss/buttons/`, `scss/forms/`, `scss/helpers/`) are forwarded from that directory's `index.scss` barrel, and the barrel is forwarded from `scss/bootstrap.scss`. Add new files to the barrel, not to `bootstrap.scss`, in that case.
---
## Step 8: Document the component
1. Add `site/src/content/docs/components/<name>.mdx`:
```markdown
---
title: Widget
description: Documentation and examples for Bootstrap’s widget component.
toc: true
css_layer: components
---
```
Add `js: optional` (or `js: required`) when the component ships a JavaScript plugin.
2. Add an entry to `site/data/sidebar.yml` under the Components section. The sidebar drives the nav, the page ordering, and inclusion in `llms.txt`, so a page without an entry is effectively invisible:
```yaml
- title: Widget
meta:
- added: 6.0.0
```
3. Show usage with `<Example>` for live demos, and render the token map under a `### Variables` section:
```markdown
<CSSVariables component="Widgets" className="widget" />
<ScssDocs name="widget-tokens" file="scss/_widget.scss" />
```
4. Link internally with `[[docsref:/components/widget/]]` rather than a hardcoded versioned path.
---
## Step 9: Verify
1. `npm run css-lint` — catches disallowed properties, wrong declaration order, and missing logical properties.
2. `npm run css` — compiles, prefixes, and minifies. Confirm the tokens land in `dist/css/bootstrap.css` with the `--bs-` prefix.
3. `npm run docs-build` — fails on a broken `docsref`, a missing sidebar entry, or missing `scss-docs` markers.
4. Check the component in the browser: with and without a theme class, in both color modes, with `dir="rtl"` on `<html>` (v6 has no separate RTL stylesheet — logical properties do the work), and with reduced motion enabled if it animates.
---
## In your own project
The same pattern works for your own components on top of Bootstrap. In `custom.scss`, `@use` the pieces you need and follow Steps 2–6 unchanged:
```scss
@use "bootstrap/scss/config" as *;
@use "bootstrap/scss/mixins/tokens" as *;
@use "bootstrap/scss/bootstrap";
$widget-tokens: () !default;
$widget-tokens: defaults(
(
--widget-bg: var(--theme-bg-subtle, var(--bg-1)),
),
$widget-tokens
);
@layer custom {
.widget {
@include tokens($widget-tokens);
background-color: var(--widget-bg);
}
}
```
Use the `custom` layer, which sits after `components` and before `helpers` and `utilities`, so your styles win over component defaults while utilities still override yours. Retuning an existing Bootstrap component doesn't require any of this — override its CSS variables at runtime, or pass its `$*-tokens` map through `with ()` at compile time.
© twbs · MIT · twbs/bootstrap