magdev/wp-bootstrap
1
Fork 0
Code Issues Pull Requests Actions Releases 24 Activity

Update CLAUDE.md with v0.1.0 session learnings

Browse Source 
Add build pipeline docs, architecture notes, session history,
and CI/CD learnings. Clean up completed roadmap items.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Marco Grätsch
2026-02-08 03:17:46 +01:00
parent 954e24288e
commit 0847f5a2d0
1 changed files with 59 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
CLAUDE.md
View File

@@ -34,19 +34,7 @@ This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase w
**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. **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.
### Getting started (v0.0.1) Next milestone is **v0.2.0 - Design Editor**. See `PLAN.md` for details.
- [ ] Create a new Theme, use `wp-core/wp-content/themes/twentytwentyfive/` as blueprint (but not as base-theme, we're building from scratch!).
- [ ] Include Bootstrap 5 (CSS/JS) (serve locally, not from CDN, use Yarn for install).
- [ ] Use SASS as Stylesheet language, use node-sass for compilation.
- [ ] Integrate custom stylesheets using SASS.
- [ ] Add Gitea CI/CD workflow to create WordPress compatible release packages. Perform as much as possible build tasks in the workflow.
- [ ] Create `PLAN.md` with a comprhensive plan to create the custom theme.
- [ ] Create `README.md` with current information.
- [ ] Create `CHANGELOG.md` with initial information
- [ ] Commit to `main` and `dev`, but don't tag yet. Push to `origin`.
Planning is moved to `PLAN.md`
## Technical Stack ## Technical Stack
@@ -56,7 +44,7 @@ Planning is moved to `PLAN.md`
- **Template Engine:** Twig 3.0 (via Composer) - **Template Engine:** Twig 3.0 (via Composer)
- **Frontend:** Bootstrap 5 Javascript & Vanilla JavaScript - **Frontend:** Bootstrap 5 Javascript & Vanilla JavaScript
- **Styling:** Bootstrap 5 & Custom CSS (if necessary) - **Styling:** Bootstrap 5 & Custom CSS (if necessary)
- **Dependency Management:** Composer (PHP), Yarn (JS/CSS) - **Dependency Management:** Composer (PHP), npm/Yarn (JS/CSS)
- **Internationalization:** WordPress i18n (.pot/.po/.mo files) - **Internationalization:** WordPress i18n (.pot/.po/.mo files)
- **Canonical Plugin Name:** `wp-bootstrap` - **Canonical Plugin Name:** `wp-bootstrap`
@@ -170,3 +158,60 @@ When editing CLAUDE.md or other markdown files, follow these rules to avoid lint
6. **MD032 - Lists should be surrounded by blank lines**: Add a blank line before AND after list blocks, including after bold labels like `**Attributes:**`. 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., `<https://example.com>`) or use markdown link syntax `[text](url)`. 7. **MD034 - Bare URLs**: Wrap URLs in angle brackets (e.g., `<https://example.com>`) 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. 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` (not `yarn`). The CI runner does not have `yarn` available.
### Architecture Notes
- **Dark mode:** Uses Bootstrap 5.3 `data-bs-theme` attribute on `<html>`. An inline anti-flash script runs synchronously in `<head>` (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 4 variations 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.
## Session History
### Session 2 — v0.1.0 Core Theme (2026-02-08)
**Completed:** Full v0.1.0 milestone implementation.
**What was built:**
- 16 block patterns across 7 new categories (hero, features, CTA, testimonials, pricing, contact, text)
- Dark mode toggle with SVG sun/moon icons, localStorage persistence, `prefers-color-scheme` detection
- 17 custom block styles mapping Bootstrap components to WordPress blocks
- 4 style variations: Ocean, Forest, Sunset, Midnight
- Sidebar template part + "Blog with Sidebar" custom template
- Inter + Lora variable web fonts with Display font size
**Key learnings:**
- `actions/setup-node@v4` does not install `yarn` — use `npm install` / `npm run build` in CI workflows
- Bootstrap 5 alert colors are hardcoded (not CSS variables), so explicit dark mode overrides are needed in SCSS
- Anti-flash for dark mode requires a synchronous inline script via `wp_add_inline_script('handle', '...', 'before')` — the deferred JS alone causes a flash
- Variable fonts use `fontWeight: "100 900"` range syntax in `theme.json` `fontFace` declarations
- Style variation JSON files must maintain identical color slug names across all variations for patterns to work correctly
- When re-tagging a release, delete the remote tag first (`git push origin :refs/tags/vX.X.X`) then recreate and push
### Session 1 — v0.0.1 Getting Started (2026-02-08)
**Completed:** Initial theme scaffolding, Bootstrap 5 integration, SASS pipeline, Twig setup, CI/CD workflow, basic FSE templates and patterns, i18n support.