Align Spotlight editor styling with front-end foundations and document exceptions (LS-1712, LS-1713)

.coderabbit.yml

@@ -18,7 +18,7 @@ reviews:
         Ensure colour palette slugs are consistent with style variations.
         Ensure font family slugs are consistent with enqueued fonts.
         Flag any deprecated settings.
-        Check that placeholder tokens ({{...}}) have been replaced if this is not a starter template.
+        This is the Spotlight client theme, not a starter template — check that no {{...}} placeholder tokens remain unreplaced.
 
     - path: "styles/*.json"
       instructions: |
@@ -95,7 +95,7 @@ reviews:
       instructions: |
         Review for accuracy. This is the primary guidance file for AI agents.
         Ensure commands listed are consistent with package.json and composer.json.
-        Ensure placeholder strategy is documented.
+        Ensure the theme correctly documents itself as the Spotlight client theme (not a starter/template repo), with placeholder tokens already replaced by real values.
 
     - path: "README.md"
       instructions: |
@@ -109,7 +109,7 @@ reviews:
     - Check for WordPress coding standards
     - Check for consistent use of theme.json over PHP
     - Check for unnecessary complexity or dependencies
-    - Check that placeholder tokens have been replaced (if not a starter)
+    - Check that no {{...}} placeholder tokens remain unreplaced — this is the Spotlight client theme, not a starter template
     - Check for consistent text domain usage
 
 chat:

.github/copilot-instructions.md

@@ -8,7 +8,7 @@ For full AI and developer guidance, read [`AGENTS.md`](../AGENTS.md) at the root
 
 ## Repo Overview
 
-This is a **LightSpeed WordPress block theme starter repository**.
+This is **Spotlight** — a specific WordPress block theme for a specific client site (spotlightnsp.co.za), not a reusable starter or template repo. It was bootstrapped from LightSpeed's internal starter theme; all placeholder tokens have already been replaced with real values. Do not flag hard-coded, site-specific values (a real navigation menu `ref`, real asset paths, real content) as portability concerns.
 One theme, one repo. Not a monorepo.
 
 The theme uses the WordPress Full Site Editing (FSE) / block theme approach:

.github/reports/2026-08-12-editor-styling-parity-verification.md

@@ -0,0 +1,40 @@
+# Editor Styling Parity Verification (LS-1712)
+
+**Date:** 2026-08-12
+**Scope:** Verify front-end/editor parity for typography, spacing, widths, and core reusable styles across the real templates and template parts landed under LS-1705 (LS-1714–1718), now that they exist to check against. Prior verification (LS-1709–1711) could only exercise the editor canvas in isolation, with no real templates to render.
+
+## Method
+
+Read every file under `templates/` and `parts/`, plus `theme.json`, `functions.php`, `style.css`, and the three files in `assets/css/`, checking for:
+
+- Hardcoded typography/spacing/colour values that bypass `theme.json` presets
+- Any enqueue path that would apply a style on the front end but not in the block editor (post editor or Site Editor canvas), or vice versa
+- Layout/width usage inconsistent with `settings.layout.contentSize`/`wideSize`
+- Block markup or attributes that would render differently between contexts
+
+## Findings
+
+### 1. All authored styling is token-driven — no parity gap found
+
+Every `style="..."` attribute *authored by this theme* in `templates/*.html` and `parts/*.html` resolves to a `var(--wp--preset--...)` custom property (spacing, colour, font-size), not a literal value. Custom properties are emitted from the same `theme.json` in both the front end and the editor, so these render identically in both places.
+
+This excludes markup generated by the Icon Block plugin (`outermost/icon-block`), which does contain literal values — a `width:20px`-style inline style on its `.icon-container` wrapper and `fill="black"`/`fill="#F5F4F8"` on the SVG path — plus the ordinary block-level `width` attribute on `wp:site-logo`/`outermost/icon-block` (e.g. `{"width":140}`, `{"width":20}`). None of this is theme-authored styling to keep token-driven: it's serialised once into saved block markup at save time (see "Icon rendering depends on the Icon Block plugin" below), identical in both renderers, so it carries no parity risk even though it isn't token-based.
+
+### 2. Custom CSS is enqueued identically on the front end and in the editor
+
+`functions.php` enqueues all three stylesheets (`custom-button.css`, `core-button.css`, `template-parts.css`) via the `enqueue_block_assets` hook, which fires in both contexts. The code comment at `functions.php:43-47` notes this was deliberate: none of the three declares `global-styles` as a dependency, because that handle only exists during the front end's `wp_enqueue_scripts` flow and would silently drop the stylesheet inside `wp-admin` if depended on. This is the correct, and only, mechanism keeping these three files in parity — confirmed still correct against the now-real templates that consume the classes they style (`.trust-bar__item`, `.site-footer__certification`, button style-variation icons).
+
+### 3. `add_editor_style('style.css')` contributes nothing (harmless, not a gap)
+
+`style.css` contains only the required theme-header comment block — no actual rules. `add_theme_support('editor-styles')` plus `add_editor_style('style.css')` therefore have no effect on parity either way; there is nothing here to diverge. Not flagged as an exception for LS-1713 since no custom CSS actually ships through this path.
+
+### 4. Two-column and grid layouts use core layout types only
+
+`templates/single.html` and `templates/page.html` use `"layout":{"type":"grid","columnCount":2}` for the content/sidebar split; `templates/home.html`/`archive.html`/the "Recent stories" query in `single.html` use `"layout":{"type":"grid","columnCount":3}` for card grids. These are native Group/Query block layout types under `settings.appearanceTools`, rendered by the same block supports code in both contexts. No custom grid CSS exists or is needed.
+
+## Known parity limitations accepted for phase 1
+
+- **Pattern placeholders aren't visually representative yet.** `front-page.html`'s seven sections, `home.html`'s card template, `single.html`'s republish box, and `sidebar-editorial.html`'s newsletter form are real block structures (headings, groups, paragraphs) using real tokens, but their content is literal placeholder text (e.g. `[Blog Card pattern placeholder]`) rather than the finished patterns from Figma. Structural parity (spacing, widths, layout type) is verified and correct; the finished patterns' own internal styling can't be parity-checked until the patterns phase authors them. Re-verify typography/spacing on these specific sections once each pattern is built.
+- **Icon rendering depends on the Icon Block plugin, not theme CSS.** `outermost/icon-block` serialises a full inline SVG (with literal `fill` attributes, not preset colours) plus a literal `width` inline style on its `.icon-container` wrapper, at save time — so there is nothing for the theme to keep in sync — both renderers show the same saved markup. This is the source of the literal (non-token) values noted as excluded from finding 1's "all authored styling is token-driven" claim. Documented here because it's a real editor-availability dependency (the plugin must be active in both environments), even though it's not a styling risk.
+
+No editor-specific adjustments were required as a result of this verification — the enqueue strategy and token discipline already in place from LS-1709–1711 held up against the real templates.

AGENTS.md

@@ -7,8 +7,7 @@ Human developers should also read this file before contributing.
 
 ## Repo Purpose
 
-This is a **LightSpeed WordPress block theme starter repository**.
-It is designed to be used as a GitHub template for building custom WordPress block themes for client and commercial work.
+This is the **Spotlight** theme — a specific WordPress block theme built for a specific client site (spotlightnsp.co.za), not a reusable starter or GitHub template. It was bootstrapped from LightSpeed's internal WordPress block theme starter, and all placeholder tokens have already been replaced with Spotlight's real values (see `style.css`, `theme.json`, `composer.json`, `package.json`). Do not treat hard-coded, site-specific values here — a real navigation menu `ref`, real image paths, real content — as portability gaps to flag; they're correct for this site.
 
 It is **not** specifically packaged for WordPress.org submission.
 Do not add WordPress.org-specific bureaucracy unless there is clear value.
@@ -80,9 +79,9 @@ Do not add WordPress.org-specific bureaucracy unless there is clear value.
 
 ## Slug and Text Domain Consistency
 
-Replace all placeholder tokens before using this starter:
+This theme's identity is already set — these are the confirmed, final values, not placeholders awaiting replacement:
 
-| Placeholder         | Description                              |
+| Value               | Description                              |
 |---------------------|------------------------------------------|
 | `Spotlight Theme 2026`    | Human-readable theme name                |
 | `spotlight-theme-2026`    | Kebab-case slug (used in folder names)   |
@@ -97,8 +96,7 @@ Replace all placeholder tokens before using this starter:
 Rules:
 - `spotlight-theme-2026` must match `spotlight-theme-2026` everywhere.
 - Keep the slug consistent in `style.css`, `theme.json`, `composer.json`, and `package.json`.
-- Do not leave placeholder tokens blank — replace them with real values.
-- Search the repo for `{{` to find all remaining placeholders.
+- Do not reintroduce `{{...}}`-style placeholder tokens — that pattern belongs to the starter theme this project was bootstrapped from, not to this repo.
 
 ---
 
@@ -250,5 +248,5 @@ composer run lint:php
 12. **Keep agent personas in `.agents/agents/`.** Agent persona files describe specialist roles.
 13. **Do not modify `.github/workflows/` without understanding CI impacts.**
 14. **Always update `CHANGELOG.md`** when making meaningful changes.
-15. **Replace all placeholder tokens** before considering setup complete.
-16. **Use placeholder tokens** (`spotlight-theme-2026` etc.) rather than leaving metadata blank.
+15. **Do not reintroduce placeholder tokens.** This theme's identity (`spotlight-theme-2026` etc.) is already set — see "Slug and Text Domain Consistency" above.
+16. **Do not flag site-specific hard-coded values as portability gaps.** This is a specific client theme, not a starter template — a real navigation menu `ref`, real asset paths, and real content are correct here, not something to generalize.