feat: phase 3

Author: Arukuen

AGENTS.md

@@ -27,7 +27,7 @@ When code and docs disagree, **PRD and contract win** (WordPress.org Theme Revie
 How-it-works maps describe current machinery only. They must not invent product law.
 
 Load [`docs/prd/start-stackable.agents.md`](./docs/prd/start-stackable.agents.md) before changing templates, `theme.json`, header behavior, onboarding, patterns, or theme e2e.
-Use [`docs/prd/start-stackable.plan.md`](./docs/prd/start-stackable.plan.md) when implementing a phase (Phases 0 and 1 are done; Phase 2 is in progress).
+Use [`docs/prd/start-stackable.plan.md`](./docs/prd/start-stackable.plan.md) when implementing a phase (Phases 0-2 are done; Phase 3 is in progress).
 Use [`docs/prd/start-stackable.check.md`](./docs/prd/start-stackable.check.md) to verify a finished (or phase-complete) theme without relying on e2e.
 
 Changing a shell-contract **primitive** requires updating the matching PRD/contract surfaces and tests in the same change.

docs/prd/start-stackable.agents.md

@@ -13,10 +13,10 @@ ADR: [`../adr/0002-theme-is-the-default.md`](../adr/0002-theme-is-the-default.md
 
 Law below is the **finished** theme.
 The tree is a **scaffold**.
-Phases 0 and 1 are done (bootstrap and the `theme.json` design system).
-Phase 2 is in progress (style variations).
-Phases 3-11 are not started.
-**Current: Phase 2** in the plan.
+Phases 0-2 are done (bootstrap, the `theme.json` design system, and style variations).
+Phase 3 is in progress (header and footer parts plus patterns).
+Phases 4-11 are not started.
+**Current: Phase 3** in the plan.
 Do not skip phases.
 Do not treat the file map or template-as-pattern-include as the current tree.
 Fix [gaps](#current-repo-gaps) on the matching phase only.
@@ -100,7 +100,7 @@ Kit Home uses the page's `full-width` template.
 
 When finished, templates are thin `wp:pattern` includes of template patterns.
 Parts are thin includes of header/footer patterns.
-Today they are still inline HTML (Phase 3+).
+Parts now use pattern includes; templates remain inline until Phase 4+.
 
 ## Patterns
 
@@ -115,23 +115,22 @@ Not allowed: a section catalog of heroes, pricing, testimonials, team, FAQ, logo
 Do not take a later gap first.
 Each item is gone or explicitly deferred in an ADR.
 
-- Phase 2: typography variations; at least one dark. Color hue files exist.
-- Phase 3: header/footer as pattern includes; footer copyright = site name, not a year-only stub.
+- Phase 3: header/footer patterns and thin part includes are implemented; acceptance verification is in progress.
 - Phase 4: first-activation grid must look designed (not an unstyled Query Loop). Templates must not reference missing slugs (`spacing|50`, color `secondary`).
 - Phase 5: `full-width` must drop extra main padding that blocks `alignfull`.
 - Phase 6: sticky / transparent / scroll state in `src/` (height token host already exists).
-- Phase 7-11: patterns empty; no Woo templates; no recommend-plugin notice; no `screenshot.png`; snap-in contract on paper only.
+- Phase 7-11: pattern catalog incomplete; no Woo templates; no recommend-plugin notice; no `screenshot.png`; snap-in contract on paper only.
 
 ## Implementation sequence
 
-Phases 0 and 1 are done; skip them.
+Phases 0-2 are done; skip them.
 Follow [`start-stackable.plan.md`](./start-stackable.plan.md) (numbered What/How).
 Do not skip a phase's **This phase is done when**.
 Then run that phase in [`start-stackable.check.md`](./start-stackable.check.md).
 
 1. Design system (`theme.json`, Plus Jakarta Sans headings, system body, shadows, radius, fluid type/spacing, element/block styles).
-2. Style variations. **Start here.**
-3. Header and footer parts + patterns (no `ref`, user copyright).
+2. Style variations.
+3. Header and footer parts + patterns (no `ref`, user copyright). **Current.**
 4. Blog templates (index/home/archive/search/404/single).
 5. Canvases (`page`, `full-width`, `blank`).
 6. Header flags.

docs/prd/start-stackable.md

@@ -18,9 +18,9 @@ What you have now is a working **scaffold**: it activates, the Site Editor opens
 Default (the designed blog you should see on first activation) is not a product yet.
 
 Work is organized as **phases 0 through 11** in the [implementation plan](./start-stackable.plan.md).
-Phases 0 and 1 are done.
-**The current work is Phase 2** (style variations).
-Do not skip ahead to headers, patterns, or Site Kit snap-in until that phase's **Done when** is true.
+Phases 0-2 are done.
+**The current work is Phase 3** (header and footer parts plus patterns).
+Do not skip ahead to blog templates, canvases, or Site Kit snap-in until that phase's **Done when** is true.
 
 If a word feels loaded (Default, shell, token, canvas, header flag), see [`CONTEXT.md`](../../CONTEXT.md).
 
@@ -36,7 +36,7 @@ If a word feels loaded (Default, shell, token, canvas, header flag), see [`CONTE
 | See the two big decisions (theme is shell, theme is Default) | [`../adr/`](../adr/) |
 | Work on Site Kits (plugin, not this theme) | Sibling `../Stackable/docs/prd/site-kits.md` |
 
-You do not need the plugin docs, the import contract, or the agent PRD to start Phase 2.
+You do not need the plugin docs or the import contract to start Phase 3.
 
 ## Block theme in 60 seconds
 
@@ -48,7 +48,7 @@ These are the files you will touch, and what each one is for:
 | `styles/colors/` and `styles/typography/` | Optional skins (style variations) that restyle the **same** named colors or fonts. Switching a variation in Site Editor → Styles should restyle the whole site. |
 | `templates/` | One HTML file per kind of page (blog home, single post, page, search, 404, and so on). WordPress picks the file automatically. |
 | `parts/` | Reusable header and footer pieces that templates include. |
-| `patterns/` | Reusable block layouts (post card, header markup, one optional Homepage starter). Empty until Phase 7. |
+| `patterns/` | Reusable block layouts. Phase 3 adds header/footer patterns; later phases add blog atoms, template patterns, and one optional Homepage starter. |
 | `functions.php` | The only PHP bootstrap WordPress loads from the theme. Must be this filename (not `function.php`). |
 | `src/` | Extra CSS and JS for behavior `theme.json` cannot express (sticky/transparent header). Compiles into `assets/build/`. |
 | `style.css` | Theme identity for WordPress (name, version, tags). It is not where the design system lives. |
@@ -63,50 +63,50 @@ CSS in `src/` is only for things `theme.json` cannot do, such as measuring heade
 
 ## Current state (you are here)
 
-Snapshot of the tree as of 26 August 2026.
+Snapshot of the tree as of 1 September 2026.
 If the files and this section disagree, trust the files and the [phase checklists](./start-stackable.check.md).
 
-**Phases 0 and 1 are complete.**
+**Phases 0-2 are complete.**
 The theme is a valid block theme that activates without a PHP fatal.
 `functions.php` enqueues `assets/build/frontend.*` and adds the body class `stk--is-stackable-theme`.
 `npm run start` compiles `src/` into `assets/build/`.
 Template and part **files** exist.
 Color palette **slugs** and content/wide widths already match the token contract below.
 
-**Phase 2 is in progress.**
-Phases 3-11 are not started.
+**Phase 3 is in progress.**
+Phases 4-11 are not started.
 What you see on `/` is a skeleton blog (site title, a basic post grid, a footer), not the designed Default the product requires.
 
 | Phase | Status | What is true now | What "done" looks like |
 | --- | --- | --- | --- |
 | 0 Bootstrap | Done | Theme activates; compile/zip works | (already met) |
 | 1 Design system | Done | Token contract, Jakarta headings, system body, fluid type and spacing, shadows, radius, and core-block styles are implemented | (already met) |
-| 2 Style variations | In progress | Eight color hue files; empty `styles/typography/`; no dark variation | Color + typography skins, including at least one dark, using the same slugs |
-| 3 Header and footer | Scaffold | Parts exist (title + nav; footer columns); not designed pattern includes | Designed, fresh-install-safe header/footer with no hardcoded Navigation `ref` |
+| 2 Style variations | Done | Nine color skins, including Dark, plus Compact and Editorial typography presets use the shared token contract | (already met) |
+| 3 Header and footer | In progress | Five core-only patterns own the shell markup; parts are thin pattern includes | Designed, fresh-install-safe header/footer with no hardcoded Navigation `ref` |
 | 4 First-activation blog | Scaffold | `index.html` is a basic two-column Query Loop | Crafted post cards, designed single/search/404, `/` looks like a product with Hello World |
 | 5 Canvases | Scaffold | `page`, `full-width`, and `blank` files exist; `full-width` still wraps content in padding | Ordinary pages have a title; kit pages are full-bleed with no theme title |
 | 6 Header flags | Stub | JS only sets `--stk-header-height`; no sticky/transparent CSS yet | Sticky, transparent overlay, scroll-to-solid, mobile nav above a hero, plugin off |
-| 7 Patterns | Not started | `patterns/` is empty | Header/footer/post-card/comments + exactly one Homepage starter; no hero/pricing catalog |
+| 7 Patterns | Not started | Header/footer patterns exist; blog atoms and `page-home` do not | Header/footer/post-card/comments + exactly one Homepage starter; no hero/pricing catalog |
 | 8 Woo templates | Not started | No Woo HTML templates | Shop/product/cart/checkout look designed if Woo is active; theme still works if it is not |
 | 9 PHP host | Partial | Setup, enqueue, body class | Dismissible "install Stackable" notice + optional breakpoint handshake |
 | 10 Directory packaging | Not started | No `screenshot.png`; tags incomplete | WP.org zip: screenshot of Default, licenses, honest tags |
 | 11 Snap-in | Not started | Contract is documented only | Plugin can assign `full-width` + header flags without a theme PHP change |
 
 Honest one-liner: this is a **legal scaffold**.
 Default is not designed yet.
-Continue Phase 2.
+Continue Phase 3.
 
 ## How we develop
 
 This is sequential craft, not "pick a random file."
 
 1. **Read this guide** so you know what the theme is allowed to own.
 2. **Open the next unfinished phase** in the [plan](./start-stackable.plan.md).
-   Right now that is Phase 2.
+   Right now that is Phase 3.
    Do not skip a phase.
 3. **Implement in the existing seam**, not a parallel system:
    - look → `theme.json` and `styles/`
-   - layout → `templates/` and `parts/` (later `patterns/`)
+   - layout → `templates/`, `parts/`, and `patterns/`
    - behavior `theme.json` cannot express → `src/css/` and `src/js/`
    - PHP → `functions.php` only, functions prefixed `start_stackable_`
 4. **Stay inside product law** (the rest of this file).
@@ -356,8 +356,8 @@ The zip must stand alone: `screenshot.png` that matches Default, designed templa
 ## Implementation
 
 Numbered what/how steps per phase: [`start-stackable.plan.md`](./start-stackable.plan.md).
-Skip Phases 0 and 1 (done).
-Continue Phase 2 and do the numbered items in order.
+Skip Phases 0-2 (done).
+Continue Phase 3 and do the numbered items in order.
 Do not skip a phase's **This phase is done when**.
 
 E2E specs to create once a surface exists: table in [`start-stackable.agents.md`](./start-stackable.agents.md#e2e-create-these).

docs/prd/start-stackable.plan.md

@@ -11,7 +11,7 @@ Do not start the next phase until the current one is checked off.
 
 ## How to use this file
 
-1. Confirm you are on the phase marked **in progress** (right now: Phase 2).
+1. Confirm you are on the phase marked **in progress** (right now: Phase 3).
 2. Read that phase's "is for" sentence so you know the job.
 3. Do the numbered items in order.
    Each item has **What** (the outcome) and **How** (the files and edits).
@@ -41,8 +41,9 @@ Constants for every file you add:
 | --- | --- |
 | 0 Bootstrap | **Done.** Skip it. |
 | 1 Design system | **Done.** Skip it. |
-| 2 Style variations | **In progress.** |
-| 3-11 | Later. Do not start these yet. |
+| 2 Style variations | **Done.** Skip it. |
+| 3 Header and footer | **In progress.** |
+| 4-11 | Later. Do not start these yet. |
 
 The file tree in the [appendix](#appendix-a-finished-zip) is the **destination**.
 It is not what the repo looks like today.
@@ -334,7 +335,7 @@ Then work the **Phase 1** list in [`start-stackable.check.md`](./start-stackable
 
 ## Phase 2 is for making "Browse styles" a real product
 
-**Status:** **in progress.**
+**Status:** done.
 
 **What you are making:** skins the user can switch in Site Editor → Styles.
 Not a second palette with different slug names.
@@ -399,7 +400,7 @@ Then work the **Phase 2** list in the acceptance check.
 
 ## Phase 3 is for designing the header and footer
 
-**Status:** later (after Phase 2).
+**Status:** **in progress.**
 
 **What you are making:** header and footer that look designed on a blank install, and that are safe (no broken menu IDs).
 The intended structure is: markup lives in a **pattern** file, and `parts/*.html` only includes that pattern.

e2e/readme.md

@@ -64,12 +64,11 @@ opens the editor. Do not listen for console `Block validation` messages.
 
 | Spec | Assertions (shipped now) |
 | --- | --- |
-| `e2e/tests/standalone-activate.spec.ts` | Theme activates from a default theme; admin Themes screen has no PHP error; front page shows header (site title) + footer; no `stackable/` markup; 404 template renders. |
+| `e2e/tests/standalone-activate.spec.ts` | Theme activates from a default theme; the front shows the pattern-backed header, navigation, footer, and user-site copyright; WordPress registers all five shell patterns; Site Editor shows no recovery UI; no `stackable/` markup; 404 template renders. |
+| `e2e/tests/tokens-and-variations.spec.ts` | WordPress discovers the Default token contract, all color variations keep the same palette slugs, Dark recolors the shell and content, and both typography presets change visible front-end type. |
 
 Deferred until those surfaces ship (see [`docs/prd/start-stackable.agents.md`](../docs/prd/start-stackable.agents.md#e2e-create-these)):
 
-- Navigation without stale `ref`
-- `tokens-and-variations.spec.ts`
 - `blog.spec.ts` (`home.html`, `search.html`, post card completeness)
 - `canvases.spec.ts` (`full-width` / `blank` contract)
 - `header-flags.spec.ts`

parts/footer-landing.html

@@ -1,7 +1 @@
-<!-- wp:group {"metadata":{"name":"Footer landing"},"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|x-large","bottom":"var:preset|spacing|x-large","left":"var:preset|spacing|xx-large","right":"var:preset|spacing|xx-large"}}},"layout":{"type":"flex","flexWrap":"wrap","justifyContent":"space-between"}} -->
-<div class="wp-block-group alignfull" style="padding-top:var(--wp--preset--spacing--x-large);padding-right:var(--wp--preset--spacing--xx-large);padding-bottom:var(--wp--preset--spacing--x-large);padding-left:var(--wp--preset--spacing--xx-large)"><!-- wp:site-title {"level":0} /-->
-
-<!-- wp:paragraph {"fontSize":"small"} -->
-<p class="has-small-font-size">Designed with <a href="https://wordpress.org" rel="nofollow">WordPress</a></p>
-<!-- /wp:paragraph --></div>
-<!-- /wp:group -->
+<!-- wp:pattern {"slug":"start-stackable/footer-landing"} /-->

parts/footer.html

@@ -1,60 +1 @@
-<!-- wp:group {"metadata":{"name":"Footer"},"style":{"spacing":{"margin":{"top":"var:preset|spacing|x-large","bottom":"var:preset|spacing|x-large"},"padding":{"top":"var:preset|spacing|xx-large","bottom":"var:preset|spacing|xx-large","left":"var:preset|spacing|xx-large","right":"var:preset|spacing|xx-large"}}},"layout":{"type":"constrained"}} -->
-<div class="wp-block-group" style="margin-top:var(--wp--preset--spacing--x-large);margin-bottom:var(--wp--preset--spacing--x-large);padding-top:var(--wp--preset--spacing--xx-large);padding-right:var(--wp--preset--spacing--xx-large);padding-bottom:var(--wp--preset--spacing--xx-large);padding-left:var(--wp--preset--spacing--xx-large)"><!-- wp:group {"align":"wide","layout":{"type":"default"}} -->
-<div class="wp-block-group alignwide"><!-- wp:columns -->
-<div class="wp-block-columns"><!-- wp:column {"width":"50%","style":{"spacing":{"blockGap":"var:preset|spacing|large"}},"layout":{"type":"default"}} -->
-<div class="wp-block-column" style="flex-basis:50%"><!-- wp:site-title {"level":3} /-->
-
-<!-- wp:site-tagline /-->
-
-<!-- wp:social-links {"iconColor":"base","iconBackgroundColor":"contrast","className":"is-style-default","style":{"spacing":{"blockGap":{"top":"var:preset|spacing|small","left":"var:preset|spacing|small"}}},"layout":{"type":"flex","justifyContent":"left"}} -->
-<ul class="wp-block-social-links has-icon-color has-icon-background-color is-style-default"><!-- wp:social-link {"url":"#","service":"twitter"} /-->
-
-<!-- wp:social-link {"url":"#","service":"instagram"} /-->
-
-<!-- wp:social-link {"url":"#","service":"linkedin"} /-->
-
-<!-- wp:social-link {"url":"#","service":"facebook"} /--></ul>
-<!-- /wp:social-links --></div>
-<!-- /wp:column -->
-
-<!-- wp:column {"width":"50%"} -->
-<div class="wp-block-column" style="flex-basis:50%"><!-- wp:columns -->
-<div class="wp-block-columns"><!-- wp:column {"width":"100%"} -->
-<div class="wp-block-column" style="flex-basis:100%"><!-- wp:group {"style":{"spacing":{"blockGap":"var:preset|spacing|large"}},"layout":{"type":"flex","flexWrap":"wrap","justifyContent":"right"}} -->
-<div class="wp-block-group"><!-- wp:group {"style":{"spacing":{"padding":{"right":"0","left":"0"}}},"layout":{"type":"constrained"}} -->
-<div class="wp-block-group" style="padding-right:0;padding-left:0"><!-- wp:heading {"level":3,"style":{"typography":{"fontStyle":"normal","fontWeight":"700"}},"fontSize":"medium"} -->
-<h3 class="wp-block-heading has-medium-font-size" style="font-style:normal;font-weight:700">Resources</h3>
-<!-- /wp:heading -->
-
-<!-- wp:navigation {"overlayMenu":"never","style":{"spacing":{"blockGap":"var:preset|spacing|medium"}},"fontSize":"medium","layout":{"type":"flex","orientation":"vertical"},"ariaLabel":"Stories"} /--></div>
-<!-- /wp:group -->
-
-<!-- wp:group {"style":{"spacing":{"padding":{"right":"0","left":"0"}}},"layout":{"type":"constrained"}} -->
-<div class="wp-block-group" style="padding-right:0;padding-left:0"><!-- wp:heading {"level":3,"style":{"typography":{"fontStyle":"normal","fontWeight":"700"}},"fontSize":"medium"} -->
-<h3 class="wp-block-heading has-medium-font-size" style="font-style:normal;font-weight:700">About</h3>
-<!-- /wp:heading -->
-
-<!-- wp:navigation {"overlayMenu":"never","style":{"spacing":{"blockGap":"var:preset|spacing|medium"}},"fontSize":"medium","layout":{"type":"flex","orientation":"vertical"},"ariaLabel":"Featured"} /--></div>
-<!-- /wp:group --></div>
-<!-- /wp:group --></div>
-<!-- /wp:column --></div>
-<!-- /wp:columns --></div>
-<!-- /wp:column --></div>
-<!-- /wp:columns -->
-
-<!-- wp:spacer {"height":"var:preset|spacing|x-large"} -->
-<div style="height:var(--wp--preset--spacing--x-large)" aria-hidden="true" class="wp-block-spacer"></div>
-<!-- /wp:spacer -->
-
-<!-- wp:group {"align":"full","layout":{"type":"flex","flexWrap":"wrap","justifyContent":"space-between"}} -->
-<div class="wp-block-group alignfull"><!-- wp:paragraph {"fontSize":"small"} -->
-<p class="has-small-font-size">©</p>
-<!-- /wp:paragraph -->
-
-<!-- wp:paragraph {"fontSize":"small"} -->
-<p class="has-small-font-size">
-			Designed with <a href="https://wordpress.org" rel="nofollow">WordPress</a>			</p>
-<!-- /wp:paragraph --></div>
-<!-- /wp:group --></div>
-<!-- /wp:group --></div>
-<!-- /wp:group -->
+<!-- wp:pattern {"slug":"start-stackable/footer"} /-->

parts/header-minimal.html

@@ -1,7 +1 @@
-<!-- wp:group {"metadata":{"name":"Header minimal"},"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|small","bottom":"var:preset|spacing|small","left":"var:preset|spacing|xx-large","right":"var:preset|spacing|xx-large"}}},"layout":{"type":"default"}} -->
-<div class="wp-block-group alignfull" style="padding-top:var(--wp--preset--spacing--small);padding-right:var(--wp--preset--spacing--xx-large);padding-bottom:var(--wp--preset--spacing--small);padding-left:var(--wp--preset--spacing--xx-large)"><!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap","justifyContent":"space-between"}} -->
-<div class="wp-block-group"><!-- wp:site-title {"level":0} /-->
-
-<!-- wp:navigation {"overlayMenu":"mobile","layout":{"type":"flex","justifyContent":"right"}} /--></div>
-<!-- /wp:group --></div>
-<!-- /wp:group -->
+<!-- wp:pattern {"slug":"start-stackable/header-minimal"} /-->