daw/_claude/notes/upgrade-plan.md

daw v0.5.0 — Upgrade Plan (working doc)

Living plan for migrating the daw theme from a 22-year-old classic PHP theme to a modern FSE block theme. Update freely as we go. Companion: [[dependencies]].

Goal

Bring daw in line with how I build themes now (the srh theme is the reference), shedding accumulated cruft along the way — without losing the bespoke, hand-crafted character of the site.

Locked decisions (2026-06-15)

1. Full block / FSE theme — theme.json + templates/ + parts/ + patterns/ + blocks/, Site-Editor driven (like srh).
2. Build: @wordpress/scripts + webpack — replaces the gulp pipeline.
3. Homepage stays bespoke — keep the hand-rolled front-page.php (centered card, davo-bot, inline critical CSS); a classic PHP front-page coexists fine inside a block theme.

Target conventions (from the srh theme)

• Loader: thin functions.php → require_once of inc/<module>/loader.php; each subdir's loader requires its peers. Consistent dw_ function prefix.
• inc/ by concern: e.g. seo/, analytics/, perf/, a11y/, integrations/ — each procedural, hooked to wp_head/wp_footer/wp_enqueue_scripts.
• theme.json v3: settings (layout contentSize/wideSize, color palette, typography fontFamilies/fontSizes, spacing) + styles (elements). Design tokens live here, not in CSS.
• templates/ + parts/: block-markup *.html (index/single/archive/page/home/search/404/category); parts for header/footer.
• patterns/: auto-discovered from /patterns/ via PHP file headers (Title/Slug/Categories/Block Types). Categories registered in functions.php.
• blocks/: per-block block.json (apiVersion 3) + render.php; autoRegister:true for render-only blocks (WP 7.0+), manual register_block_type + editor script for interactive ones.
• Build: wp-scripts build/start, custom webpack.config.js for extra entries + BrowserSync, .babelrc with wp.element.createElement pragma.

---

Phases

Phase 0 — Get a handle on it (done)

• Document existing dependencies → [[dependencies]]
• [~] Refactor functions.php → modular inc/ — deferred (2026-06-15): it's only ~200 lines and readable enough; not worth chopping yet. The inc/ modularization will happen naturally as the FSE build grows. Map kept below for when we do.

Proposed functions.php → inc/ map (deferred — reference) (current responsibilities → modules):

Current (in functions.php)	New home
dw_setup() — theme supports, image sizes	inc/setup.php
dw_scripts() — the per-page enqueue ladder	inc/assets.php (the big readability win)
dw_editor() — editor styles	inc/assets.php
dw_analytics() — Matomo footer	inc/analytics/matomo.php
dw_login_session() — auth cookie filter	inc/auth.php
dw_ask_widget() — davo-bot loader	inc/integrations/davo-bot.php
dw_plugs() → smtp	inc/integrations/smtp.php (wraps existing inc/smtp.php)
existing inc/{utils,template,tweaks,form,analytics}.php	keep; fold into loader

functions.php ends up a thin bootstrap: define constants → require inc/loader.php. Behavior must be byte-for-byte identical at this stage (pure reorg, no feature change).

Phase 1 — Build toolchain (in progress)

• Stand up @wordpress/scripts + webpack: package.json (build/start scripts + deps), .babelrc, webpack.config.js (browser-sync proxying daw.stu:3030), src/ → build/ seed
• npm install + npm run build verified (compiles src/ → build/index.js). npm start wired (browser-sync daw.stu:3030), not yet run.
• Port front-end CSS/JS into src/ as the block templates need it (incremental, through Phases 2–4)

Decision (2026-06-15): new toolchain runs alongside the legacy gulp/v4-* build, not replacing it yet — the live theme still enqueues v4-style.min.css / v4-script.min.js, so gulp stays dormant (deps kept) until block templates supersede those assets. Retiring gulp + v4-* moves to Phase 5. New source is isolated in src/ → build/ so it never collides with the 40 legacy files in js/.

Phase 2 — theme.json foundation

• theme.json v3: layout, color palette, typography, spacing, element styles
• Port design tokens out of style.css/styles.scss

Phase 3 — Block templates + parts

• templates/: index, single, archive, page, home, search, 404, category, tag
• parts/: header, footer (retire header-*.php / footer-*.php variants)
• Keep front-page.php bespoke (coexists)
• Decide each legacy page-*.php: → block template, → pattern, → retire (see open questions)

Phase 4 — Patterns + custom blocks

• patterns/ for reusable sections
• blocks/ for dynamic bits (music/last.fm, desk loop → Query Loop, etc.)

Phase 5 — Cleanup (the "additional cleanup")

• Drop confirmed-dead deps per [dependencies]
• Resolve audits: Twilio call/SMS/chat, fullcalendar, simple_html_dom, Stripe v2, icon fonts
• Remove legacy build outputs + style.min.css

Phase 6 — New features

• TBD — to be specified

---

Open questions / decisions to make

• Sign-off on the Phase 0 inc/ module map above.
• Page audit: which legacy pages survive vs retire? Candidates to confirm: bio, cv, shop, archive, chat.
• Feature audits: is the Twilio phone/SMS/chat feature still live? Is fullcalendar still rendered anywhere? Is simple_html_dom still used?
• New features list (Phase 6).

Changelog

• 2026-06-15 — Plan created; dependencies documented; decisions locked (FSE / wp-scripts / bespoke homepage).