Skip to documentation
Boobstrap Docs
DocsIntroduction
Boobstrap v0.2.1

Build with Boobstrap.

A CSS-first framework for responsive layouts, polished components, practical utilities, and optional behavior. Bring your own JavaScript, use Boobstrap's dependency-free controllers, or add an official Alpine or React adapter.

148 classes 79 tokens 0 JavaScript dependencies
Get started

Installation

Install the same npm registry package with your preferred package manager, then import the compiled stylesheet once at your application entry point.

npm · Terminal
npm install @boobstrap/boobstrap
JavaScript
import "@boobstrap/boobstrap/dist/boobstrap.css";

Use from a CDN

For a plain HTML project, load the version-pinned stylesheet directly from jsDelivr:

HTML · jsDelivr
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@boobstrap/boobstrap@0.2.1/dist/boobstrap.css" />

To self-host instead, copy dist/boobstrap.css from the installed package into your assets.

Prefix guarantee

Every public framework class starts with bs-. Boobstrap does apply a small element reset and base typography, but component and utility styles stay namespaced.

Start shipping

Starter template

Download a minimal Vite project that imports @boobstrap/boobstrap from npm. It includes a responsive landing page, theme-token overrides, components, a labeled form, dependency-free inline SVG icons, and a production validation check.

Ready for npm, pnpm, Yarn, or Bun

A real project, not just a snippet

Install, run the Vite dev server, customize the semantic tokens, then validate the production bundle with one command.

index.html src/main.js src/styles.css scripts/validate.mjs package.json
Terminal
npm install
npm run dev
npm run validate
Foundations

Theming

Dark mode is the default. Set data-bs-theme="light" on any ancestor to switch that subtree to the built-in light palette. Theme attributes can live on <html>, a page shell, or an individual preview.

Dark

Night by default

Deep plum surfaces with warm pink accents.

Light

Bright when needed

The same semantic tokens, remapped for light surfaces.

HTML
<html data-bs-theme="light">

Customize semantic tokens

Override variables after importing Boobstrap. Components consume semantic tokens such as --bs-color-primary, so a small override updates the whole system.

CSS
:root {
  --bs-color-primary: #8b5cf6;
  --bs-color-primary-hover: #a78bfa;
  --bs-radius-md: 0.5rem;
}
Foundations

Typography

Headings and body copy receive sensible defaults. Use .bs-display for oversized hero text and .bs-lead for introductory copy.

Boobstrap

Heading one

Heading two

Heading three

Lead copy introduces a section with a larger, muted treatment.

Body copy inherits the framework text color and a comfortable 1.6 line height.

HTML
<h1 class="bs-display bs-text-gradient">Build boldly.</h1>
<p class="bs-lead">Thoughtful defaults, ready to ship.</p>
Foundations

Layout & grid

.bs-container centers content with a fluid gutter and a 90rem ceiling. Add a size modifier for narrower content. .bs-section provides fluid vertical rhythm.

ClassMaximum width
.bs-container--bs-container-2xl · 90rem
.bs-container-sm40rem
.bs-container-md48rem
.bs-container-lg64rem
.bs-container-xl76rem

12-column grid

Use .bs-grid or its alias .bs-row, then assign column spans. Unprefixed columns work at every width; md begins at 48rem and lg at 64rem.

12 / md 6 / lg 4
12 / md 6 / lg 4
12 / lg 4
HTML
<div class="bs-grid bs-gap-4">
  <div class="bs-col-12 bs-col-md-6 bs-col-lg-4">...</div>
  <div class="bs-col-12 bs-col-md-6 bs-col-lg-8">...</div>
</div>
Foundations

Responsive layout composition

Start every region at 12 columns, then opt into wider arrangements at md and lg. The markup stays in a useful reading order at every width.

Featured

A wide story at large screens

This region spans the full row on mobile and eight columns from the large breakpoint.

Supporting detail

Two equal cards from the medium breakpoint.

Another detail

Source order remains the mobile reading order.

HTML · Complete example
<section class="bs-container bs-section" aria-labelledby="features-title">
  <h2 id="features-title">Features</h2>
  <div class="bs-grid bs-gap-4">
    <article class="bs-card bs-col-12 bs-col-lg-8"></article>
    <aside class="bs-card bs-col-12 bs-col-md-6 bs-col-lg-4"></aside>
  </div>
</section>

Structure

Use a labeled <section> for the region, then place articles, asides, or plain containers directly inside the grid.

Class map

.bs-grid creates 12 tracks. .bs-col-12 is the mobile baseline; md applies from 48rem and lg from 64rem.

Accessibility

Keep the DOM in a logical small-screen reading order. Breakpoint classes should change presentation without changing meaning or focus order.

Responsive breakpoints

Column spans are mobile-first. Start with an unprefixed span, then override it only where the composition needs more room.

PrefixStarts atExample
NoneAll viewport widths.bs-col-12
md48rem / 768px.bs-col-md-6
lg64rem / 1024px.bs-col-lg-4
Components

Buttons

Start with .bs-btn, add one visual variant, and optionally add a size or icon modifier. The same classes work on buttons and links.

HTML · Complete example
<button class="bs-btn bs-btn-primary" type="button">Save changes</button>
<a class="bs-btn bs-btn-secondary" href="/docs">Read docs</a>
<button class="bs-btn bs-btn-secondary bs-btn-icon" type="button" aria-label="Favorite"></button>

Structure

Use <button type="button"> for in-page actions and <a href> when the control navigates somewhere.

Class map

.bs-btn supplies structure. Add one of primary, secondary, or ghost, then an optional size or .bs-btn-icon.

Accessibility

Icon-only buttons need an aria-label. Hide a decorative SVG with aria-hidden="true", and use the native disabled attribute when unavailable.

Button API

Every button starts with the base class. Add one visual variant and, when needed, one size or shape modifier.

ClassPurposeUse when
.bs-btnShared sizing, alignment, focus, and interaction styles.Always required.
.bs-btn-primaryHigh-emphasis gradient action.One primary action per region.
.bs-btn-secondaryBordered, lower-emphasis action.Alternative or supporting actions.
.bs-btn-ghostMinimal transparent action.Tertiary actions and quiet navigation.
.bs-btn-iconSquare button dimensions.The accessible name is not visible.
.bs-btn-sm / .bs-btn-lgCompact or prominent sizing.Dense toolbars or hero actions.
Components

Badges

Badges are compact status and metadata labels. Use the base class alone for a neutral badge or add the primary modifier.

Draft New release Loved
HTML
<span class="bs-badge bs-badge-primary">New release</span>
Components

Cards

Cards establish a contained surface. Structure content with the body, title, and text classes; add .bs-card-raised when the card needs more visual elevation.

Standard

A thoughtful default

Contained content with a subtle border and surface treatment.

Explore the API →
Raised

Extra elevation

The raised modifier adds a stronger shadow without changing structure.

HTML · Complete example
<article class="bs-card bs-card-raised" aria-labelledby="launch-card-title">
  <div class="bs-card-body">
    <h3 class="bs-card-title" id="launch-card-title">Launch ready</h3>
    <p class="bs-card-text">Supporting copy.</p>
    <a class="bs-btn bs-btn-primary bs-btn-sm" href="/details">View details</a>
  </div>
</article>

Structure

Place content inside .bs-card-body, then use a real heading, supporting text, and the smallest set of actions the card needs.

Class map

.bs-card creates the surface, .bs-card-body adds inset spacing, and .bs-card-raised increases elevation without changing structure.

Accessibility

Use <article> only for standalone content. Give repeated cards headings, and avoid a whole-card link when nested controls are present.

Card API

Cards are intentionally small: one shell, one content wrapper, and optional typography and elevation helpers.

ClassPurpose
.bs-cardSurface, border, radius, clipping, and default elevation.
.bs-card-raisedStronger shadow for elevated or featured content.
.bs-card-bodyResponsive inset padding for card content.
.bs-card-titleConsistent spacing below the card heading.
.bs-card-textMuted supporting-copy color.
Components

Alerts

Alerts communicate inline feedback. Pair .bs-alert with a state modifier and use .bs-alert-title for a clear lead-in.

Heads upThis preview is ready for your custom theme.
SavedYour changes were published successfully.
Neutral noteThe base alert works without a state modifier.
HTML · Complete example
<div class="bs-alert bs-alert-success" role="status">
  <svg class="bs-icon bs-icon-lg" aria-hidden="true"></svg>
  <span><strong class="bs-alert-title">Saved</strong> Your changes were published.</span>
</div>

Structure

Combine an optional decorative icon with a text wrapper. Put the short summary in .bs-alert-title before the supporting message.

Class map

.bs-alert is neutral. Add .bs-alert-primary for highlighted guidance or .bs-alert-success for successful outcomes.

Accessibility

Use role="status" for dynamic, non-urgent feedback and role="alert" sparingly for urgent errors. Never rely on color alone.

Alert API

The visual variant describes emphasis; the ARIA role describes announcement behavior. Choose each independently.

ClassPurpose
.bs-alertNeutral alert layout, spacing, border, and surface.
.bs-alert-titleHigh-contrast summary placed before supporting copy.
.bs-alert-primaryBrand-highlighted guidance or informational emphasis.
.bs-alert-successSuccessful completion or confirmation feedback.
Components

Forms

Boobstrap styles native controls without replacing their semantics. Keep labels associated with controls and use .bs-form-group to establish consistent spacing.

HTML · Complete example
<form action="/contact" method="post">
  <div class="bs-form-group">
    <label class="bs-label" for="email">Email</label>
    <input class="bs-input" id="email" name="email" type="email" required />
  </div>
  <button class="bs-btn bs-btn-primary bs-mt-4" type="submit">Subscribe</button>
</form>

Structure

Group each visible label with one native control. The form owns submission details; every submitted control needs a stable name.

Class map

.bs-form-group controls spacing. Apply .bs-input, .bs-select, or .bs-textarea to the matching native element.

Accessibility

Match for and id, choose the correct type and autocomplete token, and connect help or error text with aria-describedby.

Form API

These classes style native controls without replacing their built-in semantics, validation, autocomplete, or keyboard behavior.

ClassApply toPurpose
.bs-form-groupWrapperConsistent label-to-control spacing.
.bs-label<label>Readable label size, weight, and color.
.bs-input<input>Text-like native input treatment.
.bs-select<select>Native selection control treatment.
.bs-textarea<textarea>Resizable multiline control treatment.
Components

Code windows

The code-window family provides a complete presentation shell and optional syntax-color helpers. It does not perform syntax highlighting; apply the token classes in server-rendered or hand-authored markup.

example.html
<!-- Build boldly -->
<button class="bs-btn bs-btn-primary">
  Ship it
</button>
const ready = true;
Composition: use .bs-code-window as the shell, .bs-code-toolbar for chrome, .bs-code-dots and three .bs-code-dot elements for the controls, and .bs-code-body on the <pre>.

Code window API

Syntax classes only color tokens you mark up; Boobstrap does not ship a parser or client-side highlighter.

ClassPurpose
.bs-code-windowOuter shell, border, background, and clipping.
.bs-code-toolbarOptional filename or control row.
.bs-code-bodyScrollable, formatted code content.
.bs-code-tagHTML tags and selectors.
.bs-code-attributeAttributes and property names.
.bs-code-stringQuoted values and literals.
.bs-code-commentComments and secondary annotations.
Utilities

Icons

Boobstrap keeps icons library-agnostic. Add .bs-icon to any inline SVG to normalize its size, alignment, and current-color stroke; use .bs-icon-sm, .bs-icon-lg, or .bs-icon-xl for scale.

HTML · inline SVG
<svg class="bs-icon bs-icon-lg" viewBox="0 0 24 24" aria-hidden="true">
  <path d="M12 3v18m9-9H3" />
</svg>

If you want a ready-made icon set, install one separately. For example, Lucide can replace matching SVG elements at runtime while Boobstrap remains CSS-only:

Shell · JavaScript
npm install lucide

import { createIcons, icons } from "lucide";
createIcons({ icons });
Accessibility: decorative icons should use aria-hidden="true"; meaningful icons need an accessible label or visible text.

Icon sizing

Icon utilities use em, so an icon follows the surrounding text or button size without a separate breakpoint system.

ClassRendered size
.bs-icon1em with normalized current-color stroke.
.bs-icon-sm0.875em
.bs-icon-lg1.25em
.bs-icon-xl1.5em
Interactivity

Choose your behavior layer

Boobstrap never requires a runtime. Static HTML can use the complete visual system by itself; interactive projects can initialize dependency-free controllers or let Alpine or React own the same component contract.

Base

CSS only

Use semantic markup and every bs- class without loading JavaScript.

Official

Boobstrap JS

Progressively enhance collapse, dropdown, and tabs through explicit, tree-shakable controllers.

Official adapter

Alpine.js

Keep reactive state in Alpine with reusable x-data providers and x-bind objects.

Official adapter

React

Use SSR-safe headless hooks with controlled or uncontrolled React state and consumer-owned markup.

Every interactive example below includes Boobstrap JS, Alpine.js, and React variants. The classes and accessibility contract stay consistent while the selected behavior layer owns state.

Importing the stylesheet remains runtime-free. Initialize all supported controllers, or import one component from a dedicated subpath.

JavaScript · Boobstrap JS
npm install @boobstrap/boobstrap

import "@boobstrap/boobstrap";
import { initBoobstrap } from "@boobstrap/boobstrap/js";

const boobstrap = initBoobstrap();
Do not stack behavior layers. Use Boobstrap JS, Alpine, or React on a component subtree—not more than one. Vue will target this same state, event, and accessibility contract.
Interactivity

Collapse

Reveal supporting content without removing it from the document. The controller synchronizes the native hidden attribute, aria-expanded, and data-bs-state.

HTML · Boobstrap JS
<button class="bs-btn bs-btn-secondary" type="button"
  data-bs-toggle="collapse" aria-controls="details">
  Toggle details
</button>

<div class="bs-collapse" id="details" hidden>
  Progressive by design.
</div>

Structure

Give the panel a unique id and reference it from the trigger's aria-controls.

State

.bs-collapse supplies the visual contract; hidden is the readable initial state.

Accessibility

Use a real button. The controller maintains aria-expanded and fires cancelable show/hide events.

Collapse API

Import Collapse from @boobstrap/boobstrap/js/collapse for direct control.

ContractPurpose
show() / hide()Change visibility and synchronized public state.
toggle()Invert the current panel state.
bs:collapse:*Cancelable before-events and bubbling completed-events.
Interactivity

Tabs

Tabs use automatic activation and a roving tabindex. Horizontal lists use Left/Right; vertical lists use Up/Down. Both support Home and End.

Profile settings
HTML · Boobstrap JS
<div class="bs-tabs" role="tablist" aria-label="Account" data-bs-tabs>
  <button class="bs-tab" id="profile-tab" type="button" role="tab"
    aria-controls="profile-panel" aria-selected="true">Profile</button>
  <button class="bs-tab" id="security-tab" type="button" role="tab"
    aria-controls="security-panel">Security</button>
</div>
<div class="bs-tab-panel" id="profile-panel" role="tabpanel"
  aria-labelledby="profile-tab">Profile settings</div>
<div class="bs-tab-panel" id="security-panel" role="tabpanel"
  aria-labelledby="security-tab" hidden>Security settings</div>

Structure

Each tab's aria-controls and panel's aria-labelledby form a two-way relationship.

State

The selected tab gets aria-selected="true"; every inactive panel uses hidden.

Accessibility

Use tabs only when panels are peer views. Preserve meaningful headings inside complex panels.

Tabs API

Import Tabs from @boobstrap/boobstrap/js/tabs.

ContractPurpose
activate(tab)Select a tab element and synchronize all controlled panels.
bs:tabs:changeCancelable before-event with previous and next tab/panel detail.
bs:tabs:changedBubbling event after the completed transition.
Reference

Utilities

Utilities are single-purpose helpers designed for composition. Responsive display helpers use the md breakpoint at 48rem.

Display & flex

.bs-block, .bs-inline-block, .bs-flex, .bs-inline-flex, .bs-hidden, .bs-stack, .bs-flex-wrap, .bs-flex-1.

Alignment

.bs-items-start, .bs-items-center, .bs-items-end, .bs-justify-start, .bs-justify-center, .bs-justify-between, .bs-justify-end, .bs-self-center.

Sizing & position

.bs-w-full, .bs-h-full, .bs-relative, .bs-overflow-hidden.

Responsive display

.bs-md-flex, .bs-md-block, and .bs-md-hidden apply from 48rem upward.

Gap

.bs-gap-{n} supports 1, 2, 3, 4, 5, 6, 8, 10, 12 and maps directly to spacing tokens.

Margin

.bs-m-0, .bs-mx-auto, .bs-mt-{n} for 2, 3, 4, 6, 8, 10, and .bs-mb-{n} for 0, 2, 4, 6.

Padding

.bs-p-{n} for 0, 2, 3, 4, 5, 6, 8; .bs-px-{n} for 4, 6; .bs-py-{n} for 2, 4, 6, 8.

Text

Sizes .bs-text-xs through .bs-text-3xl; alignment, semantic colors, gradient text, font weights, italic, link decoration, and screen-reader-only helpers.

Spacing scale

Reference

Design tokens

All framework decisions are exposed as CSS custom properties. Color tokens may be remapped by a theme; typography, spacing, radius, elevation, container, and motion tokens are shared.

Reference

All classes

This index is generated from the exact compiled stylesheet used by this site. It includes every public bs- selector and its core declaration.

Guidance

Accessibility

Boobstrap supplies visible focus treatment, reduced-motion safeguards, accessible color foundations, and .bs-sr-only. Your markup still owns semantics and behavior.

  • Use native elements first: <button> for actions and <a> for navigation.
  • Associate every form control with a visible <label>, or use .bs-sr-only when the visual design cannot accommodate one.
  • Add aria-label to icon-only buttons.
  • Use role="status" for non-urgent dynamic alerts and role="alert" for urgent messages.
  • Do not rely on color alone to communicate state; pair it with text or an icon.
  • When overriding tokens, re-check text and focus-ring contrast in both themes.
Motion preference built in

The base reset reduces animation and transition durations when the user enables prefers-reduced-motion: reduce.