Bulma Design System

A complete design system package built on Bulma CSS. All color tokens are Bulma's actual CSS custom property definitions. Downstream code references variables — never hardcoded values.

---

Product Overview

What Bulma is: A modern CSS framework based on Flexbox that provides clean, semantic, and modular web interface primitives using class-based modifiers. No JavaScript required. (Source: Bulma's project description, bulma.css — zero JS files, class-driven architecture.)

• Source repository: github.com/jgthms/bulma — MIT licensed
• CDN source: https://cdn.jsdelivr.net/npm/bulma/css/bulma.css
• Documentation: bulma.io/documentation

Primary UI Surfaces: Responsive web applications, admin dashboards, content management UIs, SaaS product interfaces, marketing pages, and component libraries.

Core Capabilities (evidenced by source files):

• Flexbox-based responsive grid: Grid with semantic column sizing and breakpoint prefixes (source: bulma.css .columns/.column system, breakpoints at 769px, 1024px, 1216px, 1408px from colors_and_type.css).
• 20+ pre-built component patterns: Buttons, cards, forms, tables, modals, navigation, hero, footer, pagination, breadcrumbs, dropdowns, panels, messages, notifications, tags, progress bars (source: Bulma documentation at bulma.io, preserved in DESIGN.md §7).
• Semantic color system: Primary, info, success, warning, danger — each with inverted, light, and outlined variants (source: .is-primary, .is-info, etc. modifiers in bulma.css).
• Standardized spacing scale: 0–6 mapping 0 to 3rem with directional suffixes (source: --bulma-spacing-0 through --bulma-spacing-6 in colors_and_type.css).
• Typography scale: 7 size levels (12px–40px), 5 weight levels, and alignment utilities (source: --bulma-size-* and --bulma-weight-* in colors_and_type.css).
• Class-driven composition: .button.is-primary.is-outlined.is-small instead of custom CSS (source: Bulma's core architecture in bulma.css).

---

Source Context

Evidence	Location	Provenance
Bulma CSS source	github.com/jgthms/bulma	MIT-licensed Flexbox CSS framework by Jeremy Thomas
CDN stylesheet	https://cdn.jsdelivr.net/npm/bulma/css/bulma.css	Runtime CSS loaded by all preview cards
Token definitions	colors_and_type.css	Bulma's default :root custom property definitions extracted from CSS source (brand colors, neutral palette, derived surfaces, typography, spacing, radius, breakpoints)
Component patterns	DESIGN.md §7 Components	Markup preserved from Bulma's official documentation at bulma.io/documentation with class names exact
Spacing scale	DESIGN.md §5 Spacing	Values match Bulma's variable definitions (--bulma-spacing-0 through --bulma-spacing-6, 0 to 3rem)
Responsive breakpoints	DESIGN.md §6 Layout	Bulma's documented breakpoints: 769px (--bulma-container-max-tablet), 1024px (--bulma-desktop), 1216px (--bulma-widescreen), 1408px (--bulma-fullhd) from colors_and_type.css
Type scale	DESIGN.md §4 Typography	Bulma's --bulma-size-* variable definitions (12px–40px, 7 levels) and --bulma-weight-* (300–700, 5 levels)
Anti-patterns	DESIGN.md §10 Anti-patterns	Derived from common misuse patterns in Bulma community forums and the framework's own documentation guidelines
Composition rules	context/source-context.md	Source intake notes: Pages → Sections → Components → Bulma primitives, zero hardcoded colors, class-driven styling

---

Package Contents

ds-bulma-design-system/
├── DESIGN.md                        # Canonical rules: color, type, spacing, layout, components, motion, voice (source-backed)
├── colors_and_type.css              # Theme token definitions (Bulma's actual :root variable definitions + extended tokens)
├── README.md                        # This file — reusable package guide with product overview and reuse workflow
├── SKILL.md                         # Agent-facing skill entry with YAML frontmatter and provenance chain
├── context/
│   └── source-context.md            # Source evidence, composition hierarchy, provenance notes, intake runbook
├── preview/
│   ├── brand-assets.html            # Logo, wordmark, color palette, typography identity
│   ├── colors-primary.html          # Brand palette swatches with live computed values (getComputedStyle)
│   ├── colors-neutral.html          # Neutral palette (white → black) with usage map
│   ├── typography-specimens.html    # Type scale, weights, alignments, text color utilities
│   ├── spacing-tokens.html          # Spacing scale, directional suffixes with pixel equivalents
│   ├── spacing-radius.html          # Border radius variants (default, small, rounded/pill)
│   ├── spacing-shadows.html         # Shadow tokens and interactive hover demo
│   ├── components-buttons.html      # Button colors, sizes, states, grouping
│   ├── components-cards.html        # Card, media, notification patterns
│   ├── components-inputs.html       # Form inputs, validation, selects, checkboxes, file upload
│   ├── components-tables.html       # Table variants: striped, bordered, narrow, fullwidth
│   ├── components-modals.html       # Modal, message, panel, tag patterns
│   └── components-navigation.html   # Navbar, tabs, breadcrumb, pagination
├── assets/                          # Brand assets (logos, wordmarks, icons — preserve when available)
├── build/                           # Runtime build assets (installer icons, tray icons — preserve when available)
├── fonts/                           # Font files (bind with @font-face in colors_and_type.css when available)
└── source_examples/                 # High-signal original component snapshots (preserve when available)

---

Preview Manifest

Each preview card is a standalone HTML file. All color swatches display computed values from the live Bulma theme via getComputedStyle — no hardcoded hex strings. Each card loads Bulma CSS from CDN so the theme is live at render time.

Preview File Path	What It Demonstrates	Components/Tokens Tested
preview/brand-assets.html	Logo variants, wordmark, color palette, typography identity using system tokens	Brand identity patterns using Bulma token references
preview/colors-neutral.html	Neutral palette (white → black) with detailed usage mapping	--bulma-white through --bulma-black neutral tokens
preview/colors-primary.html	Brand and state palette swatches with live computed HSL value display	--bulma-primary, --bulma-info, --bulma-success, --bulma-warning, --bulma-danger, --bulma-link
preview/components-buttons.html	Comprehensive button catalog (colors, sizes, states, outlines, icons, groupings)	.button with classes .is-primary, .is-info, .is-success, .is-warning, .is-danger, .is-link, .is-light, .is-outlined, .is-loading, .is-rounded
preview/components-cards.html	Card component layout and light/dark color notification patterns	.card, .card-image, .card-content, .media, .notification
preview/components-inputs.html	Complete form input catalog (text inputs, textarea, select dropdowns, checkboxes, radios, file upload, states)	.field, .control, .input, .textarea, .select, .checkbox, .radio, .file
preview/components-modals.html	Interactive modal layouts, primary/secondary message panels, and contextual tags	.modal, .message, .panel, .tag
preview/components-navigation.html	Standard navigation elements (navbar, boxed tabs, breadcrumbs, pagination)	.navbar, .tabs, .breadcrumb, .pagination
preview/components-tables.html	Data table styling (striped, bordered, narrow, hoverable, full-width)	.table, .is-striped, .is-hoverable, .is-bordered, .is-narrow, .is-fullwidth
preview/spacing-radius.html	Border radius token variants with visual examples	--bulma-radius-default, --bulma-radius-small, --bulma-radius-rounded
preview/spacing-shadows.html	Shadow and elevation tokens with interactive hover transition demos	.has-shadow styling class and transition duration tokens
preview/spacing-tokens.html	Margin and padding spacing scale from 0 to 6 with directional suffixes and pixel equivalents	--bulma-spacing-0 through --bulma-spacing-6, .mt-4, .px-3, .my-5
preview/typography-specimens.html	Complete font family specimens, weight levels, text alignments, size hierarchy, and text color utilities	--bulma-size-1 through --bulma-size-7, --bulma-weight-light through --bulma-weight-bold, --bulma-family-sans-serif, --bulma-family-monospace

---

Preserved Assets

The following directories are reserved as part of the package structure for storing source-backed assets when available:

• assets/: Designated for branding assets (logos, wordmarks, icons). Currently empty as Bulma is a pure CSS framework with no bundled brand assets.
• build/: Designated for runtime build assets (installer icons, tray icons). Currently empty.
• fonts/: Designated for local custom font files. Currently empty.
• source_examples/: Designated for preserving high-signal original source-code component examples. Currently empty.

Note: While some or all of these directories are currently empty because Bulma is a pure CSS framework without bundled assets, they are maintained as expected directories in the package structure to allow for seamless downstream intake of brand assets, icons, or custom fonts.

---

Reuse Workflow

For AI Agents

1. Read SKILL.md for agent-facing usage instructions, skill frontmatter, and provenance chain.
2. Read DESIGN.md for visual principles, component rules, source-backed context, and anti-patterns.
3. Load colors_and_type.css for token references (or include via <link> in HTML).
4. Browse preview/*.html for 13 focused component patterns and live token examples.
5. Consult context/source-context.md for provenance, composition hierarchy, and intake evidence.
6. Check assets/, build/, fonts/, source_examples/ for preserved source-backed resources.

For Human Designers

1. Include Bulma CSS in your project:

   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma/css/bulma.css">

2. Include colors_and_type.css after Bulma for extended tokens (typography, spacing, radius, semantic aliases).
3. Use Bulma's class-based modifiers for all styling — not custom CSS.
4. Override --bulma-* variables at the :root level to retheme:

   :root {
     --bulma-primary: hsl(250, 100%, 50%);
     --bulma-link: hsl(250, 100%, 50%);
   }

5. Reference preview/*.html for component patterns and token usage examples.

For Retheming

Override Bulma's base variables before loading the CSS to change the entire palette:

:root {
  --bulma-primary: hsl(250, 100%, 50%);
  --bulma-link: hsl(250, 100%, 50%);
}

All downstream tokens (--accent, --bg, --surface, --fg, --muted, --border) and component states follow automatically (Source: colors_and_type.css semantic alias tokens that reference var(--bulma-*)).

For Component Composition

Follow the hierarchy proven from Bulma's architecture:

Pages → composed from Sections
Sections → composed from Components
Components → composed from Bulma primitives (.button, .card, .columns, etc.)

(Source: context/source-context.md §Component Composition.)

---

Key Design Principles

1. Theme-derived colors: Every color is a CSS custom property; retheme by overriding variables (source: Bulma colors_and_type.css :root block).
2. No hardcoded downstream values: Components use var(--bulma-*), never write hex/HSL inline (source: Zero hardcoded colors rule derived from Bulma's CSS custom property architecture).
3. Class-driven composition: Bulma modifiers replace custom CSS for all component styling (source: Bulma's core architecture in bulma.css).
4. Semantic color states: Primary, info, success, warning, danger for all interactive elements (source: Bulma semantic modifier system).
5. Responsive by default: Mobile-first column system with breakpoint prefixes (source: Bulma grid documentation).
6. Accessible foundations: Visible focus states, ARIA labels, semantic HTML, prefers-reduced-motion (source: Bulma component accessibility patterns).
7. Pure CSS, no JS runtime: Interactivity via CSS selectors, not JavaScript (source: Bulma's zero-JavaScript architecture).

---

Anti-patterns

• ❌ Hardcoding hex/HSL values when tokens exist (source: Zero hardcoded colors rule).
• ❌ Using style="color: #fff" instead of style="color: var(--bulma-white);" (source: Theme-driven colors rule).
• ❌ Using style="background: hsl(171, 100%, 41%)" instead of style="background: var(--bulma-primary);" (source: Theme-driven colors rule).
• ❌ Using Bulma color utility classes like has-text-white, has-text-black, has-background-white, has-background-black, etc. — these hardcode specific color names that don't adapt when the theme is overridden.
• ❌ Mixing frameworks (e.g., Bootstrap + Bulma) (source: context/source-context.md styling rules).
• ❌ Skipping form labels or ARIA attributes (source: Bulma form and accessibility documentation).
• ❌ Overriding Bulma variables without documenting the retheme (source: Bulma retheming architecture).
• ❌ Writing custom CSS when a Bulma class already covers the need (source: Bulma class-based modifier architecture).
• ❌ Using JavaScript for interactions Bulma handles with CSS selectors (source: Bulma's zero-JS architecture).