Index of every page on this site: llms.txt
All skills
Run it yourself

Use this skill whenever bootstrapping, scaffolding, or structuring a new Bolt CMS theme from scratch. Establishes the Component/Container/Page architecture (pure components with zero setcontent, smart containers with CMS queries, page orchestrators with minimal raw HTML, and page-scoped components) and the shared layout shell partials/_master.twig, configures Tailwind CSS v4 CLI, Rollup for TypeScript (menu accordions and mobile drawer, anchor scrolling, locale switcher, PhotoSwipe), links the theme in config/bolt/config.yaml, binds ContentTypes to their templates (example: products → product.twig / product.record.twig), and verifies the result automatically.

  • 26 files
  • 139.6 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vondry/bolt-skills/bolt-theme-init

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈172 tokens for metadata: the name and description. ≈8.6k when used: this file. ≈1.1k more on demand in 4 files.

Description uses 8.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈685 characters, or 8.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Bolt CMS Theme Initialization & Architecture Standard

When building a frontend for Bolt CMS, themes must be structured for high maintainability, predictable data flow, and modern asset bundling. This skill defines the complete bootstrapping runbook, build pipeline setup, the shared layout shell, and the Component / Container / Page design system architecture.

The folder names, layout blocks, token names and JavaScript hooks used here are the Integration Contract described in WORKFLOWS.md. The other theme-facing skills (bolt-menu, bolt-theme-templates, bolt-tailwind-theme, bolt-helper-pages, bolt-cookie-consent, bolt-extension-setup) plug into the same structure.


1. Architectural Philosophy: Components, Containers & Pages

To avoid messy templates where database queries, complex HTML markup, and business logic are mixed together, Bolt themes adhere to a strict three-tier separation of concerns:

public/theme/<theme-name>/
├── partials/                     # LAYOUT SHELL & SHARED PARTIALS
│   ├── _master.twig              # HTML shell: SEO, a11y skip link, cache-busted assets,
│   │                             #   blocks seo / head / header / main / footer / scripts   (this skill)
│   ├── _locale-switcher.twig     # Language switcher                                         (bolt-add-language)
│   ├── _cookie-banner.twig       # Two-layer opt-in cookie banner                            (bolt-cookie-consent)
│   └── _consent-mode.twig        # Consent configuration (JSON) for cookie-consent.ts        (bolt-cookie-consent)
│
├── components/                   # 1. PURE / PRESENTATIONAL COMPONENTS
│   │                             # Rule: ZERO setcontent. All data passed via parameters.
│   ├── ui/                       # button, badge, card, picture, breadcrumbs, pagination,
│   │                             #   empty-state, section-header                             (bolt-theme-templates)
│   ├── nav/                      # item, dropdown                                            (bolt-menu)
│   └── brand/
│       └── logo.twig             # Logo (SVG or image, sitename fallback)                    (bolt-menu)
│
├── containers/                   # 2. SMART / CONTAINER COMPONENTS
│   │                             # Rule: Reusable, can call setcontent / menu_array(), composes pure components.
│   ├── header/_menu.twig         # Header navigation, CTA, locale switcher, mobile drawer    (bolt-menu)
│   ├── footer/_footer.twig       # Footer columns, contacts, socials, legal links            (bolt-menu)
│   ├── contact/                  # _contact-section.twig, _contact-banner.twig               (bolt-theme-templates)
│   └── products/                 # _featured-products.twig                                   (bolt-theme-templates)
│
├── pages/                        # 3. PAGE ORCHESTRATORS (Linked to ContentTypes)
│   │                             # Rule: ZERO or minimal raw HTML. Pure composition.
│   ├── homepage/
│   │   ├── components/           # Page-scoped pure components (hero, hero-metrics)
│   │   └── homepage.twig         # Placeholder from this skill, replaced by bolt-theme-templates
│   └── product/
│       ├── components/           # Page-scoped pure components (spec-table, stock-badge)
│       ├── product.twig          # Products Listing Orchestrator
│       └── product.record.twig   # Product Detail Orchestrator
│
├── static-pages/                 # Templates served by TemplateController routes (e.g. gdpr.twig)
├── helper-pages/                 # 404 / 403 / 500 / 503 pages                               (bolt-helper-pages)
├── extensions/                   # llms.txt.twig                                             (bolt-extension-setup)
│
├── css/
│   ├── article/                  # Bolt Article / Redactor extension styles
│   │   ├── grid.css
│   │   └── utils.css
│   ├── fonts/                    # Self-hosted WOFF2 fonts (bolt-tailwind-theme)
│   ├── splide_4.1.2.min.css      # Splide carousel stylesheet
│   ├── tailwind/
│   │   └── index.css             # Tailwind v4 source: @source rules, @theme inline tokens, utilities
│   └── index.css                 # Compiled production CSS (build output — never edit)
│
├── js/
│   ├── splide_4.1.2.min.js       # Splide carousel library
│   ├── src/                      # Standard TypeScript modules (auto-added to all themes)
│   │   ├── auto-scroll.ts        # Anchor scroll with dynamic header height subtraction
│   │   ├── menu.ts               # Dropdown accordions + mobile drawer / collapse menu with a11y
│   │   ├── locale-switcher.ts    # Language switch with scroll position preservation
│   │   ├── photoswipe.ts         # PhotoSwipe 5 lightbox with history hash deep-linking
│   │   └── index.ts              # Entrypoint importing and mounting all modules
│   └── app.js                    # Compiled production JS bundle (build output)
│
├── index.twig                    # Root Entrypoint -> {% extends 'pages/homepage/homepage.twig' %}
├── product.twig                  # Root Entrypoint -> {% extends 'pages/product/product.twig' %}         (catalog sites)
├── product.record.twig           # Root Entrypoint -> {% extends 'pages/product/product.record.twig' %}  (catalog sites)
├── record.twig                   # Generic fallback record template (any ContentType)
├── listing.twig                  # Generic fallback listing template (any ContentType)
├── macros.twig                   # Typography, currency, admin edit & link helpers
└── theme.yaml                    # Theme name, assets_version, contact, analytics, socials

The Three Tiers Defined

Tier Role & Responsibilities setcontent Allowed? Raw HTML Allowed?
components/ (Pure) Reusable UI atoms and molecules (buttons, cards, badges, section headers). Completely decoupled from Bolt database state. Accepts pure parameters, uses macros, and nests other pure components. ❌ NEVER ✅ Yes
containers/ (Smart) Reusable organism-level blocks across multiple pages (site header, footer, featured products, contact banner). Queries Bolt CMS or configuration and feeds data into pure components. ✅ YES ✅ Yes
pages/ (Orchestrators) Top-level view coordinators linked directly to ContentTypes or routes. Declaratively stacks containers and pure components. Passes the active record or records down. Layout wrappers (wrapper px-edge, a grid) are acceptable; anything reusable moves to a component or container. ⚠️ Avoid (use a container) ❌ Minimal/None
pages/<page>/components/ Page-Scoped Pure Components. One-off components relevant only to a single specific page (e.g. hero metric counters, product stock badge). Keeps the root components/ directory clean. ❌ NEVER ✅ Yes

2. Bolt Template Naming & Routing Standard: Products Example

Bolt CMS resolves templates either from config/bolt/contenttypes.yaml or through convention. To support explicit naming requirements:

  • Listing template: product.twig
  • Record detail template: product.record.twig

The page orchestrators themselves (pages/product/…) and their components are shipped by bolt-theme-templates; this skill defines the binding and the architecture they follow.

A. ContentType Definition (config/bolt/contenttypes.yaml)

products:
  name: Produkty
  singular_name: Produkt
  fields:
    title: { type: text, class: large, required: true }
    slug: { type: slug, uses: [ title ] }
    teaser: { type: textarea, height: 100px }
    body: { type: redactor, sanitise: true }             # sanitise: bolt-contenttypes rule 7
    image: { type: image }
    price: { type: number, label: 'Cena v Kč' }          # Bolt has no `integer` field type
    stock: { type: number, default: 0, label: 'Skladová zásoba' }
  show_in_menu: true
  listing_template: product.twig
  record_template: product.record.twig
  records_per_page: 9

B. Thin Theme Entrypoints

In the theme root, keep entrypoints as single-line wrapper files:

{# public/theme/<theme>/product.twig #}
{% extends 'pages/product/product.twig' %}
{# public/theme/<theme>/product.record.twig #}
{% extends 'pages/product/product.record.twig' %}

Pointing listing_template / record_template directly at pages/product/product.twig works as well. Never point the generic root record.twig / listing.twig at one ContentType's pages: they are the fallbacks for every ContentType without its own template (see section 3G).

C. Listing Page Orchestrator (pages/product/product.twig)

Composes pure components and page-scoped components; the only markup is layout wrappers:

{% extends 'partials/_master.twig' %}
{% import 'macros.twig' as macros %}

{% block main %}
    <div class="wrapper px-edge">
        {% include 'components/ui/breadcrumbs.twig' with { items: [ { label: __('products.title') } ] } %}
    </div>

    <section aria-labelledby="products-listing-title" class="wrapper px-edge pb-section">
        {% include 'components/ui/section-header.twig' with {
            title: __('products.title'),
            title_id: 'products-listing-title',
            eyebrow: __('products.eyebrow'),
            lead: __('products.perex'),
            heading_level: 1,
            layout: 'center'
        } %}

        {% if records|length > 0 %}
            {# role="list" keeps list semantics in Safari when list-style is removed #}
            <ul role="list" class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6 lg:gap-8">
                {% for item in records %}
                    <li class="flex">
                        {% include 'components/ui/card.twig' with {
                            title: item|title,
                            href: item|link,
                            image: item.image|default(null),
                            description: item.teaser|default(item|excerpt(100)),
                            price: item.price is defined and item.price ? macros.formatPrice(item.price) : null,
                            badge_markup: include('pages/product/components/stock-badge.twig', { stock: item.stock|default(0) }),
                        } %}
                    </li>
                {% endfor %}
            </ul>

            {# Bolt's pager() with the theme's accessible pagination template #}
            {{ pager(records, template = 'components/ui/pagination.twig') }}
        {% else %}
            {% include 'components/ui/empty-state.twig' with {
                title: __('products.empty_title'),
                message: __('products.empty_message')
            } %}
        {% endif %}
    </section>

    {% include 'containers/contact/_contact-banner.twig' %}
{% endblock main %}

D. Record Detail Orchestrator (pages/product/product.record.twig)

{% extends 'partials/_master.twig' %}
{% import 'macros.twig' as macros %}

{% block main %}
    <div class="wrapper px-edge flex items-center justify-between gap-4">
        {% include 'components/ui/breadcrumbs.twig' with {
            items: [ { label: __('products.title'), href: '/produkty' }, { label: record|title } ]
        } %}
        {{ macros.edit(record) }}
    </div>

    <article class="wrapper px-edge py-10 lg:py-16">
        <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-start">
            {# One PhotoSwipe gallery for the main image (and thumbnails, if any) #}
            <div class="photoswipe-gallery">
                {% if record.image is not empty %}
                    {% include 'components/ui/picture.twig' with {
                        image: record.image, alt: record|title, aspect: 'aspect-4/3', loading: 'eager', pswp: true
                    } %}
                {% else %}
                    <div class="aspect-4/3 flex items-center justify-center bg-surface text-ink-3">{{ __('products.no_image') }}</div>
                {% endif %}
            </div>

            <div class="flex flex-col gap-6">
                {% include 'pages/product/components/stock-badge.twig' with { stock: record.stock|default(0) } %}

                <h1 class="font-display text-section font-semibold text-ink">{{ macros.typo(record|title) }}</h1>

                {% if record.price is defined and record.price is not empty %}
                    <p class="font-display text-section font-semibold text-accent">{{ macros.formatPrice(record.price) }}</p>
                {% endif %}

                {% if record.teaser is defined and record.teaser is not empty %}
                    <p class="text-lead text-ink-2 leading-relaxed">{{ record.teaser }}</p>
                {% endif %}

                {# '#kontakt' scrolls to the contact section; or open a contact page with the
                   product preselected: '/kontakt?produkt=' ~ record.slug #}
                {% include 'components/ui/button.twig' with {
                    label: __('products.inquire_cta'), href: '#kontakt', variant: 'primary', size: 'lg'
                } %}

                {# Redactor/article output is already safe HTML; .cms-redactor styles it (bolt-tailwind-theme).
                   Do not use Tailwind's `prose` classes: the typography plugin is not installed. #}
                {% if record.body is defined and record.body is not empty %}
                    <div class="pt-6 border-t border-stroke cms-redactor">{{ record.body }}</div>
                {% endif %}
            </div>
        </div>
    </article>

    {% include 'containers/contact/_contact-section.twig' %}
{% endblock main %}

3. Tooling & Build Pipeline Configuration

The theme directory encapsulates its own Node.js build environment using Tailwind CSS v4 CLI and Rollup for bundling TypeScript without heavy Webpack/Vite runtime overhead.

A. package.json

{
  "name": "THEME_NAME",
  "version": "1.0.0",
  "scripts": {
    "watch:css": "npx @tailwindcss/cli --input ./css/tailwind/index.css --output ./css/index.css --minify --watch",
    "watch:js": "rollup -c --watch",
    "dev": "concurrently \"npm run watch:css\" \"npm run watch:js\"",
    "build:css": "npx @tailwindcss/cli --input ./css/tailwind/index.css --output ./css/index.css --minify",
    "build:js": "rollup -c",
    "prod": "npm run build:css && npm run build:js"
  },
  "license": "ISC",
  "devDependencies": {
    "@rollup/plugin-node-resolve": "^16.0.3",
    "@rollup/plugin-terser": "^1.0.0",
    "@rollup/plugin-typescript": "^12.3.0",
    "@tailwindcss/cli": "^4.3.3",
    "@tailwindcss/postcss": "^4.3.3",
    "concurrently": "^10.0.5",
    "rollup": "^4.64.1",
    "tailwindcss": "^4.3.3",
    "tslib": "^2.8.1",
    "typescript": "^6.0.3"
  },
  "dependencies": {
    "photoswipe": "^5.4.4"
  }
}

The production build script is prod (build:css + build:js); there is no build script.

B. Tailwind CSS v4 Scanning Safeguards & Baseline Tokens (css/tailwind/index.css)

@import 'tailwindcss';
@import '../../node_modules/photoswipe/dist/photoswipe.css';   /* galleries only */

/* 1. Skenovat překladové soubory v kořeni projektu */
@source "../../../../../translations";

/* 2. Skenovat Bolt menu konfiguraci (třídy pro navigační položky, např. class: cta) */
@source "../../../../../config/bolt/menu.yaml";

/* 3. ZABRÁNIT ZPĚTNÉ VAZBĚ: NIKDY neskenovat vlastní vygenerovaný výstup */
@source not "../index.css";

/* 4. Ignorovat dokumentaci obsahující zastaralé názvy tříd v textu */
@source not "../../README.md";

/* 5. Helper stránky mají vlastní scoped styly (bolt-helper-pages) */
@source not "../../helper-pages";

@theme inline {
    --color-canvas: var(--canvas);
    --color-ink: var(--ink);
    --color-accent: #1d4ed8;
    --spacing-header: 4.5rem;
    /* … the full baseline uses every token NAME of bolt-tailwind-theme with neutral values */
}

The baseline (examples/index.css) already uses the token names of bolt-tailwind-theme (canvas, surface, surface-2, ink, ink-2, ink-3, stroke, accent*, night*, font and text-size tokens, --spacing-header, --breakpoint-menu) with neutral placeholder values, plus minimal .wrapper, .px-edge, .py-section, .card and .dropdown rules, so every template renders correctly before bolt-tailwind-theme replaces the values with the design's.

C. Theme Configuration & Versioning (theme.yaml)

Provides theme metadata, contact details (used on privacy policy, error pages, footer and in /llms.txt), tracking IDs, socials, and zero-cost asset cache-busting in partials/_master.twig (?v={{ theme.assets_version }}). Read it in Twig as theme.<key> or config.get('theme/<key>'):

name: 'THEME_NAME'

# Cache buster appended to built CSS and JS (?v=X.X)
assets_version: '1.0'

# Operator / company contact details, shown on privacy policy, error helper pages, footer, and /llms.txt
contact:
  name: ~          # legal name, exactly as registered (privacy policy, bolt-legal-cz)
  ico: ~           # company ID (IČO), quoted
  address: ~       # registered seat (sídlo)
  email: 'info@example.cz'
  phone: '+420 123 456 789'
  hours: ~
  bio: ~

# Tracking IDs (bolt-cookie-consent; its scaffold also appends the privacy: block —
# controllers, purposes, recipients and the cookie inventory)
analytics:
  sklik_id: ~

# Social networks
socials:
  facebook: ~
  youtube: ~
  instagram: ~
  linkedin: ~
  twitter: ~

D. Baseline Client Modules & Vendor Assets

Every theme initialized with this skill automatically receives a production-tested suite of client TypeScript modules and static assets:

  1. js/src/auto-scroll.ts:
    • In-page smooth scrolling to #anchors.
    • Dynamically measures the sticky header height ([data-sticky-header], #main-menu, or #hlavni-menu) and subtracts it so target sections are never obscured.
    • Safe against PhotoSwipe hashes (#&gid=1&pid=2) and updates URL without clobbering browser history.
  2. js/src/menu.ts — navigation behaviour for the markup rendered by bolt-menu:
    • Dropdown accordions for every [data-dropdown-toggle="<id>"] → panel #<id> (submenus, locale switcher, breadcrumbs): sets aria-expanded / aria-controls, keeps closed panels inert (out of tab order and a11y tree), animates height 0 ↔ scrollHeight and then switches to height: auto so nested panels can grow, opens with click or ArrowDown (focusing the first link), closes with Escape — on the trigger or inside the panel, so also when it was opened with the mouse or holds no links — returning focus to the trigger, a press outside the trigger and the panel, a second click on the trigger, or a click on an in-page link (other links leave the page). Panels use the .dropdown class (overflow: hidden; height: 0; transition: height).
    • Mobile menu, one opener [data-menu-toggle] and one panel [data-mobile-menu], in two modes:
      • data-mobile-menu="drawer" — slide-in drawer (translate-x-full) with [data-menu-backdrop], body scroll lock, focus trap, Escape / backdrop / [data-menu-close] / link click closes it, focus returns to the opener.
      • data-mobile-menu="collapse" (or the legacy ids #mobile-menu / #mobilni-menu) — height-animated panel below the header bar between 0 and scrollHeight, .menu-icon-open / .menu-icon-close icon swap, Escape / link click / a press outside the panel and the opener closes it (Escape returns focus to the opener), recalculates height on resize.
    • Outside presses are detected with pointer events (pointerdown + pointerup outside, ignored after pointercancel), not a click listener on the document: iOS Safari sends no click for a tap on text, images or plain sections, so a document click listener never closes the menu on an iPhone. A press that becomes a scroll does not close it. Never copy the older pattern that adds the document click listener on transitionend: it misses taps on iOS, never runs without the transition, and the listener left behind closes the panel again on the next open.
    • Accessible labels: the opener's aria-label switches between data-label-open and data-label-close; aria-expanded is always kept in sync.
  3. js/src/locale-switcher.ts:
    • Progressive enhancement for language switchers ([data-locale-switch]).
    • Stores window.scrollY in sessionStorage and restores exact scroll position after the next page layout settles (waiting two requestAnimationFrames).
    • Preserves active URL query parameters and hashes across locale switches.
  4. js/src/photoswipe.ts:
    • Full PhotoSwipe v5 lightbox wiring for .photoswipe-gallery containers with a.photoswipe-gallery__link slides (href = full-size image, data-pswp-width, data-pswp-height; optional .photoswipe-gallery__caption).
    • Deep-linking URL hash sync (#&gid=1&pid=2) with browser history integration (closing on Back button).
    • Custom caption registration (.pswp__custom-caption, styled by bolt-tailwind-theme 5.H) and intrinsic aspect-ratio fallbacks.
    • Localised UI: PhotoSwipe's English button titles and error message are replaced by the first gallery's data-pswp-close-title, data-pswp-zoom-title, data-pswp-arrow-prev-title, data-pswp-arrow-next-title and data-pswp-error-msg (rendered from the gallery.* translation keys by components/ui/lightbox-labels.twig of bolt-theme-templates, which every gallery container includes).
    • Keeps up to 12 slides decoded (contentLoader.limit) instead of PhotoSwipe's default 5.
    • Every photo gallery gets this lightbox, even when the design does not show one (a static design cannot show a click state) — same as the reference sites. Remove the module only when the site has no gallery at all.
  5. js/src/index.ts: imports the modules above; remove the ones the site does not need (e.g. photoswipe together with its npm dependency and CSS @import when the site has no gallery). Delete the file of a module you remove; verify.sh requires locale-switcher.ts only on multilingual sites and photoswipe.ts only where index.ts imports it. verify.sh fails when templates use .photoswipe-gallery without the import, the dependency or the CSS. bolt-cookie-consent adds import './cookie-consent';.
  6. js/splide_4.1.2.min.js & css/splide_4.1.2.min.css:
    • Standard carousel library and styles ready for immediate use (load them in {% block head %} of the pages that use a carousel).
  7. css/article/grid.css & css/article/utils.css:
    • Complete CSS styles for the Bolt CMS Article / Redactor extension (12-column grid and layout alignments).

E. Layout Shell (partials/_master.twig)

The single layout every page, static page and 404/403 helper page extends. It defines the blocks other skills fill:

Block / include Filled by
{% block seo %} with seo.title() and seo.metatags() bolt-extension-setup (AppoloDev/bolt-seo); helper and static pages override it
partials/_consent-mode.twig (include, ignore missing) bolt-cookie-consent — consent configuration (JSON) read by cookie-consent.ts; trackers load only after consent
{{ asset('css/index.css') }}?v={{ theme.assets_version }} and js/app.js this skill + bolt-asset-caching (cache-busting). Bolt registers the active theme as the default asset package, so asset() paths are relative to the theme folder
{% block head %} page-specific additions (helper scene styles, carousel CSS, preloads)
skip link to #obsah (a11y.skip_to_content) this skill
partials/_cookie-banner.twig (include, ignore missing) right after the skip link bolt-cookie-consent — early in the tab order
{% block header %} → containers/header/_menu.twig (ignore missing) bolt-menu
{% block main %} inside <main id="obsah"> page orchestrators
{% block footer %} → containers/footer/_footer.twig (ignore missing) bolt-menu
{% block scripts %} page-specific scripts

The partials owned by other skills are included with ignore missing, so the shell renders as soon as this skill has run and fills in as later skills add their files. The full file is examples/_master.twig.

F. Macros (macros.twig)

  • macros.editList(items|first) — one pencil for a list of records without pages of their own, opening the ContentType's overview.
  • macros.edit(record, tab, class) — the editor's pencil, rendered only for logged-in editors (record|edit_link is empty otherwise). It opens the record in the language of the page, on the tab named by tab (the field's group). bolt-edit-links applies it across the finished theme.
  • macros.typo(text) — Czech typography glue: escapes the text and inserts &nbsp; after one-letter prepositions and conjunctions (a i k o s u v z, upper- and lowercase) and &. Twig string literals do not support \u escapes — ' ' would render literally as u00A0 — so the macro uses the HTML entity.
  • macros.formatPrice(price) — 1290 → 1 290 Kč.
  • macros.linkAttributes(href) — href through locale_link() for internal paths, target="_blank" rel="noopener noreferrer" for external URLs.

G. Generic Fallbacks & Homepage Placeholder

  • record.twig and listing.twig render any ContentType that has no dedicated template (title, image, excerpt; listing cards with pager()). They extend partials/_master.twig and must stay generic.
  • index.twig extends pages/homepage/homepage.twig. This skill writes a placeholder homepage marked {# bolt-theme-init:placeholder #}; bolt-theme-templates' scaffold replaces every file that still carries the marker with its real page.

H. Translation Units

examples/translations.cs.xlf / translations.en.xlf hold the units used by the layout shell and the fallbacks (a11y.skip_to_content, listing.empty). Merge them into the project catalogs:

php vendor/tomvondracek/bolt-skills/scripts/merge-xliff.php \
    vendor/tomvondracek/bolt-skills/skills/bolt-theme-init/examples/translations.cs.xlf translations/messages.cs.xlf

4. Step-by-Step Initialization Procedure

Step 1: Link Theme in Bolt Config

Edit config/bolt/config.yaml:

theme: <theme-name>

Limit Twig's cache warm-up to templates in config/packages/twig.yaml (under twig:). The theme folder also holds node_modules/; without the pattern bin/console cache:clear compiles every file there as Twig (typescript.js alone is 18 MB) and runs out of PHP's 128 MB memory limit. The scaffold adds it; verify.sh step 6 checks it:

twig:
  default_path: '%kernel.project_dir%/vendor/bolt/core/templates'
  # Warm up and lint only templates: the theme folder also holds node_modules (typescript.js
  # alone is 18 MB), which the cache warm-up otherwise compiles until it runs out of memory.
  file_name_pattern: '*.twig'

Step 2: Scaffold Theme Directory Hierarchy

mkdir -p public/theme/<theme-name>/{partials,static-pages,helper-pages,extensions,img}
mkdir -p public/theme/<theme-name>/components/{ui,nav,brand}
mkdir -p public/theme/<theme-name>/containers/{header,footer,contact}
mkdir -p public/theme/<theme-name>/pages/homepage/components
mkdir -p public/theme/<theme-name>/css/{tailwind,article,fonts}
mkdir -p public/theme/<theme-name>/js/src

Step 3: Copy Boilerplate Files

Copy starter files from skills/bolt-theme-init/examples/:

  • package.json, postcss.config.mjs, rollup.config.js, tsconfig.json, theme.yaml
  • index.css → css/tailwind/index.css, and js/src/*.ts
  • Splide (js/splide_4.1.2.min.js, css/splide_4.1.2.min.css) and css/article/*.css
  • macros.twig and _master.twig → partials/_master.twig
  • Generic fallbacks: record.twig, listing.twig
  • Homepage placeholder: pages/homepage/homepage.twig; root index.twig → {% extends 'pages/homepage/homepage.twig' %}

(Or execute the automated scaffold script below.)

Step 4: Install Dependencies, Update & Run Initial Build

cd public/theme/<theme-name>
npm install
npm update --save
npm run prod

[!IMPORTANT] Always update libraries upon installation: Run npm update --save immediately following npm install. This upgrades @tailwindcss/cli, rollup, typescript, and related packages to their latest semver-compatible releases and records them into package.json. Immediately execute npm run prod to verify that the build succeeds with the updated packages and that no build regressions were introduced.

Verify that css/index.css and js/app.js have been generated and are non-empty.

Step 5: Merge Translations, Clear Bolt CMS Cache & Test Render

php vendor/tomvondracek/bolt-skills/scripts/merge-xliff.php \
    vendor/tomvondracek/bolt-skills/skills/bolt-theme-init/examples/translations.cs.xlf translations/messages.cs.xlf
php bin/console cache:clear

Open the homepage in the browser or run a test request to ensure HTTP 200 is returned (the placeholder page renders inside the layout shell).

Step 6: Continue with the Skills That Fill the Shell

  1. bolt-menu — scaffold.sh --profile=<landing|catalog|conditional> --templates --force (header, footer, nav components, logo).
  2. bolt-tailwind-theme — design tokens and utilities from the design.
  3. bolt-theme-templates — UI components, containers and page orchestrators (replaces the homepage placeholder).

5. Automated Scaffolding & Verification Scripts

Automated Scaffolding Script

To bootstrap a complete theme foundation in a single command:

# From bolt-skills repo or vendor/tomvondracek/bolt-skills:
./skills/bolt-theme-init/scripts/scaffold.sh <theme-name> [project-root] [--force]

Existing files are kept (reported as [skip]) unless --force is given. The script creates the directories, copies tooling, TypeScript modules, vendor assets, the layout shell, macros, fallbacks and the homepage placeholder, links the theme in config/bolt/config.yaml, runs npm install, npm update --save and npm run prod, checks that css/index.css and js/app.js are non-empty, and clears the Bolt cache.

Verification Script

Run the automated verification test from the project root:

./skills/bolt-theme-init/scripts/verify.sh

The script verifies:

  1. config/bolt/config.yaml points to the active theme.
  2. public/theme/<theme-name>/ exists.
  3. Directory hierarchy (components/, containers/, pages/) and the layout shell partials/_master.twig defining the seo, head and main blocks; a legacy layouts/ folder is reported.
  4. Purity Enforcement: Zero setcontent calls inside components/.
  5. Template bindings: every record_template / listing_template configured in contenttypes.yaml exists in the theme (e.g. product.twig and product.record.twig for products); viewless ContentTypes and singleton listings are skipped.
  6. Tooling files (package.json, theme.yaml, css/tailwind/index.css) exist with required npm scripts.
  7. Compiled production assets (css/index.css and js/app.js) are built and non-empty.

6. Common Pitfalls & Anti-Patterns

Anti-Pattern Why It Breaks Correct Pattern
setcontent in components/ Destroys reusability and testability. Hardwires UI atoms to database queries. Pass data as parameters. Move data-fetching into containers/.
Raw HTML in pages/ Makes page templates brittle and unreadable. Logic and styling leak into view coordinators. Keep pages/ strictly declarative; compose pure components & containers.
Polluting root components/ Dumping single-use widgets into components/ causes bloat and confusion. Scope single-use components in pages/<page>/components/.
Second layout file (layouts/_master.twig, _base.twig) Skills extend partials/_master.twig and fill block main; a different file or block name renders empty pages or "template not found". One shell: partials/_master.twig with seo, head, header, main, footer, scripts.
Root record.twig / listing.twig extending one ContentType's page Every other ContentType renders with that page (prices, stock badges, wrong buttons). Keep them generic; bind ContentTypes with record_template / listing_template.
' ' in Twig strings Twig has no \u escapes; the text renders literally as u00A0. Use &nbsp; on escaped text (macros.typo).
type: integer in contenttypes.yaml Not a Bolt field type. type: number.
prose classes The Tailwind typography plugin is not installed; the classes generate nothing. Wrap rich text in .cms-redactor (bolt-tailwind-theme).
Dynamic Tailwind class strings Classes like bg-{{ variant }}-500 are invisible to the Tailwind scanner. Use static lookup dictionaries (variant_classes[...] in Twig).
Colour names outside the token set (stone-*, brand, ink-800) Undefined names generate no CSS; ad-hoc palettes drift from the design. Use the token names of bolt-tailwind-theme (canvas, surface, ink, accent, night, …).
Scanning css/index.css in @source Causes a feedback loop where removed utility classes stay alive forever. Add @source not "../index.css"; to css/tailwind/index.css.
No file_name_pattern in config/packages/twig.yaml cache:clear dies with "Allowed memory size … exhausted" in Twig/Source.php: the warm-up compiles node_modules/ of the theme. file_name_pattern: '*.twig' under twig: (Step 1).
Hardcoding asset paths without ?v= Browsers cache old stylesheets indefinitely after updates. Use {{ asset('css/index.css') }}?v={{ theme.assets_version }} linked to theme.yaml.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 083eb14. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 weeks ago

README badge

README badge for vondry/bolt-skills/bolt-theme-init