DocumentationExamples
Versa Theme System

Themes

Customize Versa without fighting Bootstrap. Keep vendor, Versa and project layers independent and upgradeable.

Upgrade-safe by design

Four clean layers

Bootstrap and Versa are the untouched default. Add one optional theme file for a new visual identity, then reserve the custom layer for changes unique to one website. Bootstrap Icons remains a separate, optional vendor companion and does not add another design layer.

01

Bootstrap

Untouched Bootstrap CSS and JavaScript. Upgrade the framework independently from Versa and its optional icon companion.

02

Versa

The complete default design, components, tokens, layouts and interactions.

03

Theme

One optional token file changes colors, typography, gradients, shape, depth and component surfaces.

04

Custom

Project-specific exceptions that should not become part of a reusable theme.

assets/vendor/bootstrap/...
assets/vendor/bootstrap-icons/...  /* optional companion */
assets/versa/css/versa.css
assets/custom/theme.css
assets/custom/custom.css

Why icons are separate: Bootstrap Icons has its own version and license. Versa components can use its bi classes, but the library is not compiled into versa.css, is not modified by a theme file, and can be removed or replaced when a project uses another icon system. Read the icon setup guide.

Theme builder

Make Versa yours.

Build a complete, reusable Versa theme with coordinated light and dark palettes, live component previews and WCAG contrast checks. The builder exports the complete public Theme API for both color modes, including intelligently derived interaction colors and gradients. Load the generated file after versa.css and before custom.css.

Preview color mode

Light mode · showing light

Auto follows your operating system or browser color preference and updates if that preference changes.

Generated file: my-versa-theme.css

Brand and semantic colors

Choose colors by purpose. Versa derives coordinated interaction shades and readable foregrounds.

Surfaces and typography colors

Define the page, panel and alternate-section relationships used by every component.

Typography, layout, shape and motion

These structural tokens keep headings, buttons, cards and page spacing consistent everywhere.


Cutout media

Theme the optional circular frame while keeping ring-free cutouts available at the component level. Keep another Versa page open on the same site to preview these changes there in real time.

Application hero colors

Keep application panels and their actions coordinated with the active site theme.

Live theme preview

A flexible identity for every page.

Brand, surface, typography, shape, depth and motion tokens update together.

Reusable components

Cards, controls and content surfaces inherit the generated theme.

Explore components

Readable by default

Automated contrast checks flag important color pairs before export.

Semantic color
Application heroOne theme. Shared behavior.

WCAG AA contrast check

Light palette
Checking…

Normal text requires a contrast ratio of at least 4.5:1. Review both palettes and every real content combination before publishing.

Generated theme file

my-versa-theme.css
Color themes

Default first. Optional themes second.

Alternate themes override the public Theme API without replacing Bootstrap, Versa components, markup or JavaScript. Your selected integrated theme is remembered in this browser and applied across every Versa page. Copy a reusable theme into assets/custom/theme.css to make it the project's permanent default.

Design tokens

Customize intent, not individual components.

New Versa components should consume the same shared tokens so they automatically work with existing themes.

Versa theme token groups and examples
GroupControlsExample
BrandPrimary, secondary, accent--versa-primary
SemanticSuccess, information, warning, danger--versa-success
SurfaceBody, cards, alternate sections--versa-page
TypographyText, muted text, headings--versa-text
LayoutContainer width and section spacing--versa-container
ShapeComponent radii--versa-radius
ControlsButton height, padding and border width--versa-button-min-height
CardsBorders and hover lift--versa-card-hover-lift
DepthComponent shadows--versa-shadow
MotionTransitions and reduced motion--versa-transition
MediaPage, hero, artwork and overlay gradients--versa-gradient-hero
Media frameRing color, surface, width, directional shadow and cutout placement--versa-media-ring
ApplicationApplication heroes, panels and actions--versa-app-background