wp-bootstrap/PLAN.md

WP Bootstrap - Development Plan

Project Vision

WP Bootstrap is a modern WordPress Block Theme built from scratch with Bootstrap 5. It provides a clean, responsive foundation for WordPress websites using the Full Site Editing (FSE) architecture with Bootstrap's design system.

Architecture

Theme Type

Full Site Editing (FSE) Block Theme following the WordPress 6.x template hierarchy:

• Templates (templates/): HTML files with WordPress block markup (Site Editor)
• Template Parts (parts/): Reusable header/footer components (Site Editor)
• Patterns (patterns/): PHP files with block markup and i18n support
• Design Tokens (theme.json): Colors, typography, spacing mapped to Bootstrap 5
• Twig Templates (views/): Bootstrap 5 HTML rendered on the frontend via template_redirect
• Template Engine (inc/Template/): Controller, context builder, and nav walker for Twig rendering

Technology Stack

• PHP 8.3+ with PSR-4 autoloading
• Twig 3.0 via Composer for custom block rendering
• Bootstrap 5.3+ CSS & JS served locally
• Dart Sass for SCSS compilation
• PostCSS with Autoprefixer and cssnano for production CSS

Build Pipeline

src/scss/style.scss → sass → assets/css/style.css → postcss → assets/css/style.min.css
src/scss/editor-style.scss → sass → assets/css/editor-style.css
node_modules/bootstrap/dist/js/ → copyfiles → assets/js/bootstrap.bundle.min.js

Version Roadmap

v0.0.1 - Getting Started (Complete)

• Theme scaffolding and project setup
• Bootstrap 5 CSS/JS integration
• SASS build pipeline
• Basic FSE templates and patterns
• Twig infrastructure
• Gitea CI/CD workflow
• i18n support (en_US, de_CH)

v0.1.0 - Core Theme (Complete)

• Complete set of block patterns
• Dark mode toggle implementation
• Custom block styles for Bootstrap components
• Style variations (color schemes)
• Sidebar template part
• Enhanced typography settings

v0.1.1 - Bootstrap Frontend Rendering (Complete)

• Twig-based frontend rendering via template_redirect hook
• TemplateController, ContextBuilder, NavWalker PHP classes
• 20 Twig templates (base layout, pages, partials, components)
• Bootstrap 5 navbar, cards, pagination, comments, sidebar
• Enhanced TwigService with WordPress functions and globals
• Navigation menu locations (primary, footer)
• Comment form Bootstrap styling
• README.md project documentation

v0.2.0 - Design Editor (Complete)

• Full Design Editor compatibility
• Custom block categories
• Page-level patterns and templates
• Enhanced header/footer variations
• Custom navigation styles

v0.3.0 - Polish (Complete)

• Performance optimization
• Accessibility audit and fixes
• Security audit and fixes
• RTL language support
• Additional translations
• Documentation

v1.0.0 - Release (Complete)

• All features complete and tested
• Widget area registration and Twig rendering with fallback
• Comprehensive documentation (README refresh, updated translations)
• Code quality audit passed (no TODO/FIXME, proper escaping, no security issues)

Bootstrap 5 Integration Strategy

CSS

Bootstrap SCSS is imported into the theme's build pipeline with variable overrides applied before import. The compiled CSS contains the full Bootstrap framework plus WordPress-specific overrides.

JavaScript

The Bootstrap JS bundle (including Popper.js) is served as a pre-built file copied from node_modules during the build step.

Design Tokens

theme.json colors, typography, and spacing are aligned with Bootstrap's default SCSS variables to ensure visual consistency between the WordPress editor and the frontend.

Dark Mode Plan

Bootstrap 5.3+ includes built-in dark mode via the data-bs-theme="dark" attribute. Implementation plan:

1. SCSS: $enable-dark-mode: true generates dark mode CSS custom properties
2. JavaScript: Toggle mechanism with localStorage persistence
3. WordPress: Integration with the Site Editor color scheme
4. Accessibility: Respect prefers-color-scheme media query