Bolt CMS Tailwind Theme Tokens & Utilities Standard
In modern Bolt CMS frontend themes, Tailwind CSS v4 serves as the design token engine and utility vocabulary. Before any Twig templates or components are created, the CSS foundation must be systematically extracted from the design hand-off (Figma, Penpot, or design specs) and established inside public/theme/<theme>/css/tailwind/index.css.
This skill synthesizes the proven design token architecture, scanning rules, and repeating utility classes established across production Bolt CMS projects. The token names defined here are part of the Integration Contract (WORKFLOWS.md): bolt-theme-init's baseline, bolt-menu, bolt-theme-templates, bolt-cookie-consent and bolt-helper-pages all use them, so keep the names and change only the values.
1. Core Architecture of css/tailwind/index.css
The theme entrypoint file css/tailwind/index.css is structured into five deterministic sections:
css/tailwind/index.css
├── 1. Scanning Directives (@source)
│ ├── translations/ scanner
│ ├── config/bolt/menu.yaml scanner
│ └── SAFEGUARDS: ignore ../index.css output, README.md & helper-pages/
│
├── 2. Design Tokens (@theme static inline)
│ ├── Breakpoints (--breakpoint-menu, etc.)
│ ├── Layout & Header offsets (--spacing-header)
│ ├── Themed Surface & Ink scales (--color-canvas, --color-surface, --color-ink)
│ ├── Brand & Contrast Accent palettes (--color-accent, --color-brand)
│ ├── Dark Zone / Night palette (--color-night)
│ ├── Fluid Typography Curves (clamp formulas)
│ └── Keyframe Animations (fade-in, dialog, skeleton)
│
├── 3. Root Palette & Contrast Baseline (:root)
│ └── CSS variables with documented WCAG AA contrast ratios
│
├── 4. Base Layer Resets & Fonts (@layer base)
│ ├── Self-hosted Latin + Latin-ext WOFF2 font-faces (Czech glyphs)
│ ├── Sticky header anchor scroll offset (:where([id]))
│ ├── No double-tap zoom on links and buttons (touch-action)
│ └── Accessible focus-visible & text selection
│
└── 5. Repeating Utility Classes (@utility & @layer components)
├── Layout: .wrapper, .px-edge, .py-section, .no-scrollbar
├── Typography: .eyebrow, .eyebrow-rule, .mono, .badge, .tag
├── Buttons: .btn, .btn-primary, .btn-secondary, .btn-outline, .btn-on-accent
├── Cards & Links: .card, .link-arrow
├── Navigation & Pager: .pagination, .dropdown, .rotate-svg
└── CMS Redactor Prose: .cms-redactor, .cms-article, .cms-redactor-on-accent2. Scanning Directives & Compilation Safeguards
Tailwind CSS v4 replaces the v3 content array with @source directives. To ensure all classes are captured while preventing build loops, configure:
@import 'tailwindcss';
/* 1. Scan the translation catalogs in the project root */
@source "../../../../../translations";
/* 2. Scan Bolt's menu configuration (classes of menu items) */
@source "../../../../../config/bolt/menu.yaml";
/* 3. CRITICAL SAFEGUARD: never scan the build output itself.
css/index.css is the compiled file. Without this line every class that was ever
generated would stay in the build forever. */
@source not "../index.css";
/* 4. Ignore documentation that mentions old class names */
@source not "../../README.md";
/* 5. Helper/error pages ship their own scoped styles — their one-off classes must not
grow the main bundle (bolt-helper-pages) */
@source not "../../helper-pages";3. Design Tokens Blueprint (@theme static inline & :root)
Configure tokens in @theme static inline:
inline— utilities use the token's value directly. Tokens that point at a:rootvariable (--color-ink: var(--ink)) therefore follow that variable at runtime.static— every token is also emitted as a CSS variable (--color-accent: …) even when no utility uses it. Without it, Tailwind v4 emits only variables something references: a build where no CSS readsvar(--color-accent)has no--color-accentat all (tested with Tailwind 4.3.3), and the helper pages' scoped styles — which are excluded from scanning and readvar(--color-accent)— silently fall back to their hard-coded colours.
[!NOTE] The values below are neutral placeholders (a slate/blue palette and the open-source fonts Source Serif 4, Source Sans 3 and JetBrains Mono) that already meet the WCAG AA rules of section 6. Replace every value with the one extracted from the design; keep the token names — the templates of
bolt-theme-init,bolt-menu,bolt-theme-templates,bolt-cookie-consentandbolt-add-languageuse them.
@theme static inline {
/* --- Layout Breakpoints --- */
--breakpoint-2xs: 24rem; /* 384px */
--breakpoint-xs: 36rem; /* 576px */
--breakpoint-menu: 62rem; /* Where the desktop bar replaces the burger menu */
--breakpoint-3xl: 112.5rem; /* 1800px */
/* --- Sticky header height --- */
--spacing-header: 4.5rem; /* Drives the header bar height and the scroll margin of anchors */
/* --- Font families --- */
--font-display: 'Source Serif 4', ui-serif, Georgia, serif;
--font-body: 'Source Sans 3', ui-sans-serif, system-ui, sans-serif;
--font-mono: 'JetBrains Mono', ui-monospace, 'SFMono-Regular', monospace;
/* --- Povrchy a Inky (propojeno s :root) --- */
--color-canvas: var(--canvas);
--color-surface: var(--surface);
--color-surface-2: var(--surface-2);
--color-ink: var(--ink);
--color-ink-2: var(--ink-2);
--color-ink-3: var(--ink-3);
--color-stroke: var(--stroke);
/* --- Brand / primary accent --- */
--color-accent: #1d4ed8;
--color-accent-hover: #1e40af;
--color-accent-soft: #dbeafe;
--color-accent-ink: #ffffff;
--color-accent-ink-2: #bfdbfe;
/* --- Night zone (fixed dark palette for the footer and dark bands) --- */
--color-night: #0f172a;
--color-night-deep: #020617;
--color-night-stroke: #1e293b;
--color-night-ink: #ffffff;
--color-night-ink-2: #cbd5e1;
--color-night-ink-3: #94a3b8;
/* --- Fluid heading sizes clamp(min, base + vw, max) --- */
--text-hero: clamp(2.25rem, 1.5rem + 3vw, 4rem);
--text-section: clamp(1.75rem, 1rem + 2.5vw, 2.75rem);
--text-card: clamp(1.125rem, 0.95rem + 0.7vw, 1.375rem);
/* --- Copy type scale: 11 / 13 / 15 / 17 px --- */
--text-micro: 0.6875rem; /* 11px — labels, badges, uppercase annotations */
--text-meta: 0.8125rem; /* 13px — meta, captions, compact buttons */
--text-body: 0.9375rem; /* 15px — body text */
--text-lead: 1.0625rem; /* 17px — lead paragraph */
/* --- Easing and animations --- */
--ease-out-soft: cubic-bezier(0.22, 1, 0.36, 1);
--animate-fade-in: fade-in 0.5s ease-in-out;
--animate-dialog: dialog 0.3s ease-in-out;
--animate-skeleton: skeleton 1.8s ease-in-out infinite;
@keyframes fade-in {
0% { opacity: 0; }
100% { opacity: 1; }
}
@keyframes dialog {
0% { opacity: 0.2; transform: translateY(-15%); }
100% { opacity: 1; transform: translateY(0); }
}
@keyframes skeleton {
0%, 100% { background-color: var(--color-stroke, #e2e8f0); }
50% { background-color: var(--color-surface-2, #f1f5f9); }
}
}
:root {
/* Hairlines and borders in rem (they scale with the root font size) */
--hairline: 0.0625rem;
--canvas: #ffffff;
--surface: #f8fafc;
--surface-2: #f1f5f9;
--ink: #0f172a;
--ink-2: #475569;
/* Lightest ink: 5.44:1 on --canvas, 5.2:1 on --surface, 4.97:1 on --surface-2 (WCAG AA) */
--ink-3: #5b6b80;
--stroke: #e2e8f0;
}Tokens over arbitrary values
Templates use the token utilities (rounded-card, text-meta, tracking-label, pt-page), never the arbitrary form of the same value (rounded-[var(--radius-card)], text-[0.9375rem]). When a value repeats in two or more templates with the same meaning, add it here as a token named by its role (--tracking-label, --spacing-page, --text-page with --text-page--line-height, --breakpoint-3xs) instead of repeating the arbitrary class. bolt-theme-templates checks it: the IDE's "can be written as" warning while editing, and scripts/canonical-classes.mjs (Tailwind's own canonicalize) in verify.sh, which also rewrites the templates with --fix. One-off design measurements stay arbitrary.
4. Self-Hosted Fonts with Czech Support (unicode-range)
Fonts are self-hosted in public/theme/<theme>/css/fonts/: loading them from Google Fonts sends every visitor's IP address to Google before any consent (GDPR), and late-loading fonts shift the layout (CLS).
Czech (ě, š, č, ř, ž, ý, á, í, é, ů, ú, ň, ť, ď) requires both the Latin and the Latin-ext range:
@layer base {
/* Latin (basic) — every family needs both the latin and the latin-ext file */
@font-face {
font-family: 'Source Sans 3';
font-style: normal;
font-weight: 200 900;
font-display: swap;
src: url(fonts/source-sans-3/source-sans-3-latin.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
/* Latin extended (contains the Czech diacritics) */
@font-face {
font-family: 'Source Sans 3';
font-style: normal;
font-weight: 200 900;
font-display: swap;
src: url(fonts/source-sans-3/source-sans-3-latin-ext.woff2) format('woff2');
unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
/* Offset of anchor targets (#section), so the sticky header does not cover them */
:where([id]) {
scroll-margin-top: var(--spacing-header);
}
/* Accessible keyboard focus */
:focus-visible {
outline: 0.125rem solid var(--color-accent);
outline-offset: 0.1875rem;
}
}5. Blueprint of Recurring Utilities and Classes
These utilities and classes recur in every production theme and are the building blocks of the Twig components:
A. Layout
/* Centred container capped at the artboard width (typically 1440px / max-w-360) */
@utility wrapper {
@apply mx-auto w-full max-w-360;
}
/* Horizontal page gutter (distance from the screen edges) */
@utility px-edge {
@apply px-6 sm:px-10 lg:px-20;
}
/* Vertical section rhythm */
@utility py-section {
@apply py-12 lg:py-16;
}
/* Hide the scrollbar of horizontal swipe rows while keeping them scrollable */
@utility no-scrollbar {
scrollbar-width: none;
&::-webkit-scrollbar {
display: none;
}
}
/* Two consecutive sections of the same background share their vertical space */
section:where(.bg-canvas) + section:where(.bg-canvas) > .wrapper,
section:where(.bg-surface) + section:where(.bg-surface) > .wrapper {
padding-top: 0;
}B. Typography, Labels and Annotations
/* Small label above a section heading */
@utility eyebrow {
@apply font-body uppercase text-micro font-medium tracking-[0.12em] text-ink-3;
}
/* Decorative line before the eyebrow label */
.eyebrow-rule {
@apply inline-block h-0.25 w-6 shrink-0 bg-accent;
}
@utility mono {
@apply font-mono uppercase text-xs tracking-wider;
}
@utility badge {
@apply inline-flex items-center gap-1.5 font-mono uppercase text-xs tracking-wider px-2.5 py-0.5 rounded-full;
}
@utility tag {
@apply inline-flex items-center text-xs px-2.5 py-1 rounded bg-surface-2 text-ink-2;
}C. Buttons and CTAs
@utility btn {
@apply inline-flex items-center justify-center gap-2 rounded-sm font-body text-body font-medium px-6 py-3 transition-colors cursor-pointer disabled:pointer-events-none disabled:opacity-50;
}
@utility btn-primary {
@apply btn bg-accent text-white hover:bg-accent-hover;
}
@utility btn-secondary {
@apply btn border border-ink text-ink hover:bg-ink hover:text-canvas;
}
@utility btn-outline {
@apply btn border-ink text-ink hover:bg-ink hover:text-canvas;
border-width: var(--hairline);
border-style: solid;
}
@utility btn-ghost {
@apply btn bg-transparent text-ink hover:text-accent hover:bg-surface;
}
/* Contrasting button pair for dark bands (dark contact section, footer) */
@utility btn-on-accent {
@apply btn bg-white text-accent hover:bg-accent-soft;
}
@utility btn-on-accent-outline {
@apply btn border-white/40 text-white hover:bg-white/10;
border-width: var(--hairline);
border-style: solid;
}D. Cards and Interactive Links
/* Karta obsahu s jemnou linkou */
@utility card {
@apply rounded-sm bg-canvas;
border: var(--hairline) solid var(--color-stroke);
}
/* Link whose SVG arrow moves on hover */
@utility link-arrow {
@apply inline-flex items-center gap-1.5 font-body text-meta font-medium text-accent transition-colors hover:text-ink;
}
.link-arrow svg {
transition: transform 0.3s var(--ease-out-soft);
}
@media (hover: hover) {
.link-arrow:hover svg {
transform: translateX(0.25rem);
}
}
@media (prefers-reduced-motion: reduce) {
.link-arrow svg {
transition: none;
}
}E. Bolt Pager Styling (.pagination)
Bolt's {{ pager() }} renders <ul class="pagination">:
.pagination {
@apply flex flex-wrap items-center justify-center gap-2 m-0 p-0;
list-style: none;
}
.pagination li a,
.pagination li > span {
@apply inline-flex h-9 min-w-9 items-center justify-center px-3 font-mono text-xs tracking-widest border border-stroke text-ink-2 transition-colors duration-200;
}
.pagination li a:hover {
@apply border-ink text-ink;
}
.pagination li.active a,
.pagination li a[aria-current] {
@apply border-ink bg-ink text-canvas;
}
/* li.disabled: the gap marker of components/ui/pagination.twig; li[disabled]: older templates. */
.pagination li.disabled,
.pagination li[disabled],
.pagination li[disabled] a {
@apply opacity-40 pointer-events-none;
}F. CMS Redactor Typography Wrapper (.cms-redactor)
Editors insert arbitrary HTML through Redactor (lists, quotes, headings). The .cms-redactor class scopes its styles:
@layer components {
.cms-redactor, .cms-article {
ul, ol {
list-style: initial;
@apply m-0 pl-5;
}
a {
@apply text-accent underline underline-offset-[0.125rem] transition-colors hover:text-ink;
}
:where(p, ul, ol, blockquote, pre, h2, h3, h4, h5)
+ :where(p, ul, ol, blockquote, pre, h2, h3, h4, h5) {
@apply mt-4;
}
h2, h3, h4, h5 {
@apply font-display text-card font-medium text-ink;
}
:where(p, ul, ol, blockquote, pre) + :where(h2, h3, h4, h5) {
@apply mt-7;
}
blockquote {
@apply pl-5 text-ink;
border-left: var(--hairline) solid var(--color-accent);
}
strong, b {
@apply font-semibold text-ink;
}
em, i {
font-style: italic;
}
small {
@apply text-meta text-ink-3;
}
pre {
@apply overflow-x-auto rounded-sm bg-surface p-4 text-meta;
}
}
/* Variant for text on a dark background */
.cms-redactor-on-accent {
a {
@apply text-white hover:text-accent-ink-2;
}
h2, h3, h4, h5, strong, b, blockquote {
@apply text-white;
}
blockquote {
border-left-color: var(--color-accent-ink-2);
}
small {
@apply text-accent-ink-2;
}
}
}G. Mobile Menu and Accordion Animation
Dropdown panels use .dropdown (components/nav/dropdown.twig of bolt-menu, the language switcher): js/src/menu.ts of bolt-theme-init animates their height between 0 and scrollHeight and toggles aria-expanded and inert. An arrow with .rotate-svg turns when its button has aria-expanded="true".
.dropdown {
overflow: hidden;
height: 0;
transition: height 0.15s ease-in-out;
max-width: calc(100vw - 2rem);
}
.rotate-svg {
transition: transform 0.3s ease;
}
button[aria-expanded="true"] .rotate-svg {
transform: rotate(180deg);
}
[data-dropdown-toggle] > * {
pointer-events: none;
}H. Gallery Lightbox Caption (.pswp__custom-caption)
Every photo gallery opens in the PhotoSwipe 5 lightbox (js/src/photoswipe.ts of bolt-theme-init). Keep @import '../../node_modules/photoswipe/dist/photoswipe.css'; right after @import 'tailwindcss';. The module registers a caption element filled from the slide's .photoswipe-gallery__caption (the image alt); style it with the night tokens so it stays readable over any photo:
.pswp__custom-caption {
position: absolute;
z-index: 10;
right: 0;
bottom: 0;
left: 0;
padding: 1rem 1.5rem;
background: linear-gradient(transparent, color-mix(in srgb, var(--color-night) 85%, transparent));
@apply font-body text-sm text-night-ink text-center text-pretty pointer-events-none;
}I. Double-Tap Zoom on Controls
Quick repeated taps on a control — slider arrows above all — zoom the page on phones, because the browser reads them as a double-tap. Every theme sets this in @layer base:
a, button, summary, label, input, select, textarea, [role="button"] {
touch-action: manipulation;
}Pinch zoom keeps working, so never replace this with user-scalable=no or maximum-scale=1 in the viewport meta tag: those block zooming for people who need it (WCAG 1.4.4). Swiping is unaffected: a slider's track sets its own touch-action.
6. Extracting Tokens from a Design (Figma / Penpot / Pencil)
Work in this order:
- Header height (
--spacing-header):- Measure the sticky navigation in the desktop and the mobile artboard. Set
--spacing-header(e.g.4.5rem) and keep:where([id]) { scroll-margin-top: var(--spacing-header); }in the base layer.
- Measure the sticky navigation in the desktop and the mobile artboard. Set
- Colour scale and contrast (WCAG AA):
- Surfaces:
--canvas,--surface,--surface-2. - Text (inks):
--ink(primary),--ink-2(secondary),--ink-3(annotations, labels). - Contrast rule:
--ink-3needs at least 4.5:1 against--canvas,--surfaceand--surface-2(every surface text appears on). The same for--night-ink-3against--nightand--night-deep.
- Surfaces:
- Fluid type with
clamp():- Scale smoothly between the mobile (e.g. 375px) and the desktop artboard (e.g. 1440px): $$\text{clamp}(\text{min}, \text{base} + \text{slope} \cdot \text{vw}, \text{max})$$
- Example: a hero heading from 36px on mobile to 64px on desktop:
--text-hero: clamp(2.25rem, 1.5rem + 3vw, 4rem);
- Self-hosted fonts (WOFF2):
- Download the weights as WOFF2, including the Latin-ext files for Czech.
- Put them in
public/theme/<theme>/css/fonts/and add the@font-facerules withunicode-range.
- Build and verify:
- Run
npm run build:cssin the theme folder. - Run the verification:
./skills/bolt-tailwind-theme/scripts/verify.sh
- Run
7. Automated Verification (scripts/verify.sh)
The script checks:
public/theme/<theme>/css/tailwind/index.cssexists.- The
@sourcerules, including the safeguard against scanning the build output (@source not "../index.css"). - The
@themeblock,--spacing-headerand the accent colours. - The anchor offset (
scroll-margin-top). - The recurring utilities (
@utility wrapper,@utility btn,.cms-redactor). - The theme compiles with
@tailwindcss/cli— into a temporary file, so the check never changescss/index.css— and the output defines--color-accentas a CSS variable (the helper pages read it).