# WordPress Theme using Bootstrap 5 **Author:** Marco Graetsch **Author URL:** **Author Email:** **Repository URL:** **Issues URL:** ## Project Overview This WordPress-Theme is built from scratch employing Bootstrap 5. Build modern Websites using the state-of-the-art Framework. All basic WordPress components are converted and are fully working. The theme uses Twig for rendering. It is also a good starting point as base theme for complex WordPress websites. ### Features - [ ] All native WordPress theme files converted to Boostrap 5 - [ ] Works seemlessly on default WordPress installations - [ ] Installable via WordPress admin #### Frontend - [ ] Fully responsive Design - [ ] Supports darkmode #### Administration - [ ] Compatible with the Gutenberg-Editor - [ ] Customizable with the Design-Editor ### Key Fact: 100% AI-Generated This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase was created through AI assistance. ## Temporary Roadmap **Note for AI Assistants:** Clean this section after the specific features are done or new releases are made. Effective changes are tracked in `CHANGELOG.md`. Do not add completed versions here - document them in the Session History section at the end of this file. Current version is **v1.0.0** - Release. See `PLAN.md` for details. ## Technical Stack - **Language:** PHP 8.3.x - **PHP-Standards:** PSR-4 - **Framework:** Latest WordPress Theme API - **Template Engine:** Twig 3.0 (via Composer) - **Frontend:** Bootstrap 5 Javascript & Vanilla JavaScript - **Styling:** Bootstrap 5 & Custom CSS (if necessary) - **Dependency Management:** Composer (PHP), npm (JS/CSS) - **Internationalization:** WordPress i18n (.pot/.po/.mo files) - **Canonical Plugin Name:** `wp-bootstrap` ### Security Best Practices - All user inputs are sanitized (integers for quantities/prices) - Nonce verification on form submissions - Output escaping in templates (`esc_attr`, `esc_html`, `esc_js`) - Direct file access prevention via `ABSPATH` check - XSS-safe DOM construction in JavaScript (no `innerHTML` with user data) ### Translation Ready All user-facing strings use: ```php __('Text to translate', 'wp-bootstrap') _e('Text to translate', 'wp-bootstrap') ``` Text domain: `wp-bootstrap` #### Translation Template - Base `.pot` file created: `languages/wp-bootstrap.pot` - Ready for translation to any locale - All translatable strings properly marked with text domain #### Available Translations - `en_US` - English (United States) [base language - .pot template] - `de_CH` - German (Switzerland, formal) There is no need to compile translation to *.mo locally as it will be done in the Gitea CD/CI pipeline ### Create Releases **Important Git Notes:** - Default branch while development is `dev` - Create releases from branch `main` after merging branch `dev` - Tags should use format `vX.X.X` (e.g., `v1.1.22`), start with v0.1.0 - Use annotated tags (`-a`) not lightweight tags - **ALWAYS push tags to origin** - CI/CD triggers on tag push - Commit messages should follow the established format with Claude Code attribution - `.claude/settings.local.json` changes are typically local-only (stash before rebasing) **CRITICAL - Release Workflow:** On every new version, ALWAYS execute this complete workflow: ```bash # 1. Commit changes to dev branch git add git commit -m "Description of changes (vX.X.X)" # 2. Merge dev to main git checkout main git merge dev --no-edit # 3. Create annotated tag git tag -a vX.X.X -m "Version X.X.X - Brief description" # 4. Push everything to origin git push origin dev main vX.X.X # 5. Switch back to dev for continued development git checkout dev ``` Never skip any of these steps. The release is not complete until all branches and the tag are pushed to origin. --- **For AI Assistants:** When starting a new session on this project: 1. Read this CLAUDE.md file first 2. Semantic versioning follows the `MAJOR.MINOR.BUGFIX` pattern 3. Check git log for recent changes 4. Verify you're on the `dev` branch before making changes 5. Run `git submodule update --init --recursive` if lib/ is empty (only if submodules present) 6. Run `composer install` if vendor/ is missing 7. Test changes before committing 8. Follow commit message format with Claude Code attribution 9. Update this session history section with learnings 10. Never commit backup files (`*.po~`, `*.bak`, etc.) - check `git status` before committing 11. Follow markdown linting rules (see below) Always refer to this document when starting work on this project. ### Markdown Linting Rules When editing CLAUDE.md or other markdown files, follow these rules to avoid linting errors: 1. **MD031 - Blank lines around fenced code blocks**: Always add a blank line before and after fenced code blocks, even when they follow list items. Example of correct format: - **Item label**: (blank line here) \`\`\`php code example \`\`\` (blank line here) 2. **MD056 - Table column count**: Table separators must have matching column counts and proper spacing. Use consistent dash lengths that match column header widths. 3. **MD009 - No trailing spaces**: Remove trailing whitespace from lines 4. **MD012 - No multiple consecutive blank lines**: Use only single blank lines between sections 5. **MD040 - Fenced code blocks should have a language specified**: Always add a language identifier to code blocks (e.g., `txt`, `bash`, `php`). For shortcode examples, use `txt`. 6. **MD032 - Lists should be surrounded by blank lines**: Add a blank line before AND after list blocks, including after bold labels like `**Attributes:**`. 7. **MD034 - Bare URLs**: Wrap URLs in angle brackets (e.g., ``) or use markdown link syntax `[text](url)`. 8. **Author section formatting**: Use a heading (`### Name`) instead of bold (`**Name**`) for the author name to maintain consistent document structure. ### Build Pipeline The build uses npm scripts defined in `package.json`: ```bash # Full build (CI and local) npm run build # Development watch mode npm run dev ``` Build steps (in order): 1. `copy:js` — Copy Bootstrap JS bundle from `node_modules` to `assets/js/` 2. `copy:theme-js` — Copy theme JS (e.g., `dark-mode.js`) from `src/js/` to `assets/js/` 3. `scss` — Compile SCSS (`src/scss/`) to CSS (`assets/css/`) 4. `postcss` — Autoprefixer + cssnano minification → `assets/css/style.min.css` **CI/CD note:** The Gitea workflow uses `npm install` and `npm run build`. ### Architecture Notes - **Dark mode:** Uses Bootstrap 5.3 `data-bs-theme` attribute on ``. An inline anti-flash script runs synchronously in `` (via `wp_add_inline_script` with `'before'`), while the full `dark-mode.js` is deferred. Preference stored in `localStorage` key `wp-bootstrap-theme`. - **Block styles:** Registered via `register_block_style()` with `inline_style` parameter in `functions.php`. Dark mode overrides for alert/card styles are in `src/scss/_custom.scss`. - **Style variations:** JSON files in `styles/` directory. All 15 variations (7 light, 7 dark, plus default) use the same 10 color slug names (base, contrast, primary, secondary, success, danger, warning, info, light, dark) to ensure patterns work across all schemes. - **Fonts:** Inter (sans-serif) and Lora (serif) variable fonts bundled as `.woff2` in `assets/fonts/`. Declared via `fontFace` in `theme.json` with `font-display: swap`. - **Patterns:** PHP files in `patterns/` with WordPress block markup and i18n. Hidden patterns (prefixed `hidden-`) are reusable components not shown in the pattern inserter. - **Twig frontend rendering:** `TemplateController` hooks `template_redirect` to intercept frontend requests and render Bootstrap 5 HTML via Twig, bypassing FSE block markup. FSE templates remain for the Site Editor. WordPress functions that produce output (`wp_head`, `wp_footer`, `body_class`, `language_attributes`) are captured via `ob_start()`/`ob_get_clean()` and passed to Twig as safe HTML strings. - **Navigation menus:** `NavWalker` converts flat `wp_get_nav_menu_items()` into a nested tree for Bootstrap dropdown rendering. Falls back to listing published pages when no menu is assigned. - **Docker development:** WordPress runs in Docker container `jobroom-wordpress`. The theme directory must be bind-mounted via `compose.override.yaml` (absolute path) for live changes to be visible. ## Session History ### Session 8 — v1.0.0 Release (2026-02-08) **Completed:** Sidebar widget area registration, Twig widget rendering with fallback, documentation refresh, v1.0.0 release. **What was built:** - `register_sidebar()` for `primary-sidebar` widget area with Bootstrap-styled wrapper markup - Widget area rendering in `ContextBuilder::getSidebarData()` via `ob_start()` + `dynamic_sidebar()` with fallback to built-in content - Twig sidebar template conditional: renders WordPress widgets when assigned, falls back to recent posts/search/tags otherwise - Updated README.md with accurate feature counts (15 variations, 41 patterns, 3 translations, accessibility, RTL, widget area) - Updated all translation files (.pot, de_CH.po, fr_FR.po) with widget area strings **Key learnings:** - `is_active_sidebar()` returns true only when widgets are assigned to the area, making it the right condition for fallback logic - `dynamic_sidebar()` outputs widget HTML directly, so `ob_start()`/`ob_get_clean()` is needed to capture it for Twig - Widget area `before_widget`/`after_widget` markup should use Bootstrap utility classes (`widget mb-4`) for consistent spacing - Widget title markup (`before_title`/`after_title`) should match existing sidebar heading styles (`sidebar-heading h6 text-uppercase fw-semibold`) ### Session 7 — v0.3.2/v0.3.3 Dark Mode & Style Variation Bridge (2026-02-08) **Completed:** Fixed dark mode rendering conflicts between WordPress global styles and Bootstrap, fixed form element styling in dark mode, bridged style variation colors to Bootstrap CSS custom properties, fixed variation detection to read from correct palette origin. **What was built:** - Style variation bridge function (`wp_bootstrap_variation_colors`) that maps WordPress palette colors to Bootstrap CSS custom properties via `wp_enqueue_scripts` - Helper functions for color manipulation: `wp_bootstrap_hex_to_rgb()`, `wp_bootstrap_build_surface_css()`, `wp_bootstrap_mix_hex()`, `wp_bootstrap_hex_to_rgb_array()`, `wp_bootstrap_relative_luminance()` - Variation detection comparing `theme` origin palette against hardcoded base defaults (base, contrast, primary) - Dark mode body override in `_custom.scss` using `!important` to defeat WordPress global styles specificity - Broad dark mode rules for all native form elements (`select`, `input`, `textarea`) to catch plugin-generated controls - Fixed `footer-columns.html.twig` to use semantic `bg-body-tertiary` instead of hardcoded `bg-dark text-light` **Key learnings:** - WordPress puts style variation colors in the `theme` palette origin, NOT `custom` -- `wp_get_global_settings(['color', 'palette', 'theme'])` returns the base theme.json merged with the active variation - The `custom` palette origin contains user manual edits from the Site Editor, but its data structure may lack expected `slug`/`color` keys - To detect an active variation, compare `theme` origin colors against known base theme.json defaults rather than checking for slugs in `custom` - WordPress `theme.json` `styles.color` generates `body { background-color: var(--wp--preset--color--base) }` directly on `body`, which overrides inherited CSS variables from `html[data-bs-theme="dark"]` -- removing `styles.color` from theme.json is the cleanest fix - CSS variables defined directly on `body` beat inherited values from `html` due to specificity, requiring `!important` on `html[data-bs-theme="dark"] body` to ensure Bootstrap dark mode works - Plugin-generated form elements (e.g., `