Feat/ls 1711 define spotlight global styles and shared block styling

AGENTS.md

@@ -159,8 +159,8 @@ Rules:
 - Style variations live in `styles/`.
 - Two starter variations are provided: `light.json` and `dark.json`.
 - Additional variations can be added as `styles/*.json`.
-- `styles/blocks/` and `styles/sections/` are organisational conventions for future per-block or per-section styles.
-- These nested JSON files are not automatically consumed by WordPress as global style variations — they are available for reference or tooling.
+- `styles/blocks/<block>/<variation-slug>.json` and `styles/sections/<variation-slug>.json` register **block style variations**: a JSON file with `slug`, `title`, `blockTypes`, and `styles` keys (see `styles/blocks/button/*.json`). WordPress core auto-registers these — confirmed working in this theme (LS-1711) — so they appear as selectable options in the block style picker for any block listed in `blockTypes`. No PHP registration is needed.
+- Keep each variation file scoped to one block and one look — one file, one responsibility (do not combine multiple unrelated looks in a single file).
 - Keep variation files small and focused.
 
 ---

CHANGELOG.md

@@ -13,12 +13,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Audited Spotlight design-token foundations in `theme.json`: colour palette (Brand Red, Accent Navy, and Neutral 9-step ramps, system colours, surface colours), self-hosted Libre Baskerville/Source Sans 3 variable fonts, a 7-step font-size scale, an 11-step spacing scale, a 7-step border-radius scale, and a `settings.custom.borderWidth` token family.
 - `openspec/specs/design-tokens/` capability spec, documenting the design-token requirements for future template/pattern work to build on.
+- Base element styling in `theme.json`: default button look, `core/quote`/`core/pullquote` border accent and citation styling, `core/list`/`core/list-item` marker colour and spacing, and heading top/bottom margin rhythm (see LS-1711). List marker/spacing and heading/paragraph spacing rhythm values are provisional (no design source yet) pending design confirmation.
+- Three named `core/button` block-style variations — `styles/blocks/button/primary.json`, `dark.json`, `dark-pill.json` — matching the dashboard CTA, article action, and header nav CTA button treatments confirmed in Figma dev-mode frames.
+- `openspec/specs/base-styles/` capability spec, documenting the base element/block styling requirements this change adds.
+- `openspec/changes/archive/2026-08-05-spotlight-global-styles-and-block-rules/` proposal, design, and task artifacts for LS-1711.
 
 ### Changed
 
 - Replaced the placeholder colour palette, font sizes, and spacing scale in `theme.json` with the audited Spotlight values (see LS-1704/LS-1709/LS-1710).
 - Updated `settings.layout.contentSize`/`wideSize` to 800px/1320px.
 - Cleaned up `styles/light.json` and `styles/dark.json`, which duplicated the old placeholder palette; `dark.json`'s background/text inversion is preserved with updated colours.
+- Corrected `styles.elements.link` colour from the brand ramp (`brand-500`/`brand-600`) to `accent-200`/`accent-300`, confirmed against real body-copy links; `brand-500` remains reserved for category badges/labels (see LS-1711).
+- Updated `AGENTS.md`'s guidance on `styles/blocks/`/`styles/sections/` files: WordPress core auto-registers these as selectable block style variations (confirmed working), correcting the previous claim that they required manual PHP registration.
 
 ### Deprecated
 
@@ -28,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Header navigation now uses the mobile overlay menu to keep narrow-screen navigation accessible.
 - Footer markup no longer nests the Site Title block inside a paragraph, preventing invalid heading-in-paragraph output.
+- Fixed `theme-utils.mjs`'s `validate-schema` command to check block-style-variation partial files (`styles/blocks/**/*.json`) at their real runtime position instead of the flat root `styles` shape, and to work around a confirmed upstream schema/`ajv` limitation with pseudo-selector property names.
 
 ### Security
 

assets/css/core-button.css

@@ -0,0 +1,36 @@
+/*
+ * Icon and hover states for WordPress core/button's own built-in "Fill" and
+ * "Outline" block styles, restyled to match Spotlight's design system (see
+ * custom-button.css for Spotlight's own bespoke button variations).
+ */
+
+/* Fill (default, unstyled — styles.elements.button in theme.json) */
+
+.wp-block-button .wp-block-button__link:hover {
+	background-color: var(--wp--preset--color--accent-300);
+	color: var(--wp--preset--color--base);
+}
+
+/* Outline (styles/blocks/button/outline.json) */
+
+.wp-block-button.is-style-outline .wp-block-button__link::after {
+	content: "";
+	display: inline-block;
+	width: 1.25em;
+	height: 1.25em;
+	vertical-align: -0.35em;
+	margin-inline-start: var(--wp--preset--spacing--5);
+	background-color: currentColor;
+	-webkit-mask-image: url('../icons/arrow-right.svg');
+	-webkit-mask-repeat: no-repeat;
+	-webkit-mask-size: contain;
+	mask-image: url('../icons/arrow-right.svg');
+	mask-repeat: no-repeat;
+	mask-size: contain;
+}
+
+.wp-block-button.is-style-outline .wp-block-button__link:hover {
+	background-color: var(--wp--preset--color--accent-300);
+	border-color: var(--wp--preset--color--neutral-200);
+	color: var(--wp--preset--color--neutral-200);
+}

assets/css/custom-button.css

@@ -0,0 +1,74 @@
+/*
+ * Icon and hover states for Spotlight's own custom core/button block-style
+ * variations (i.e. not WP core's built-in "Fill"/"Outline" styles — see
+ * core-button.css for those). One rule block per variation.
+ */
+
+/* Republish Article (styles/blocks/button/republish-article.json) */
+
+.wp-block-button.is-style-republish-article .wp-block-button__link::before {
+	content: "";
+	display: inline-block;
+	width: 1.25em;
+	height: 1.25em;
+	vertical-align: -0.35em;
+	margin-inline-end: var(--wp--preset--spacing--5);
+	background-color: currentColor;
+	-webkit-mask-image: url('../icons/arrow-line-up-right.svg');
+	-webkit-mask-repeat: no-repeat;
+	-webkit-mask-size: contain;
+	mask-image: url('../icons/arrow-line-up-right.svg');
+	mask-repeat: no-repeat;
+	mask-size: contain;
+}
+
+.wp-block-button.is-style-republish-article .wp-block-button__link:hover {
+	background-color: var(--wp--preset--color--accent-600);
+	color: var(--wp--preset--color--base);
+}
+
+/* Secondary (styles/blocks/button/secondary.json) */
+
+.wp-block-button.is-style-secondary .wp-block-button__link::after {
+	content: "";
+	display: inline-block;
+	width: 1.25em;
+	height: 1.25em;
+	vertical-align: -0.35em;
+	margin-inline-start: var(--wp--preset--spacing--5);
+	background-color: currentColor;
+	-webkit-mask-image: url('../icons/arrow-right.svg');
+	-webkit-mask-repeat: no-repeat;
+	-webkit-mask-size: contain;
+	mask-image: url('../icons/arrow-right.svg');
+	mask-repeat: no-repeat;
+	mask-size: contain;
+}
+
+.wp-block-button.is-style-secondary .wp-block-button__link:hover {
+	background-color: var(--wp--preset--color--accent-300);
+	color: var(--wp--preset--color--base);
+}
+
+/* Dashboard (styles/blocks/button/dashboard.json) */
+
+.wp-block-button.is-style-dashboard .wp-block-button__link::before {
+	content: "";
+	display: inline-block;
+	width: 1.25em;
+	height: 1.25em;
+	vertical-align: -0.35em;
+	margin-inline-end: var(--wp--preset--spacing--5);
+	background-color: currentColor;
+	-webkit-mask-image: url('../icons/chart-line-up.svg');
+	-webkit-mask-repeat: no-repeat;
+	-webkit-mask-size: contain;
+	mask-image: url('../icons/chart-line-up.svg');
+	mask-repeat: no-repeat;
+	mask-size: contain;
+}
+
+.wp-block-button.is-style-dashboard .wp-block-button__link:hover {
+	background-color: var(--wp--preset--color--accent-600);
+	color: var(--wp--preset--color--base);
+}

functions.php

@@ -28,15 +28,33 @@ function spotlight_theme_2026_setup() {
 add_action( 'after_setup_theme', 'spotlight_theme_2026_setup' );
 
 /**
- * Enqueues front-end assets.
+ * Enqueues block assets on both the front end and in the editor (post
+ * editor and Site Editor canvas alike).
  *
  * Add CSS and JS files to assets/css/ and assets/js/ and uncomment
  * the relevant lines below once those files exist.
  */
 function spotlight_theme_2026_enqueue_assets() {
-	// Main stylesheet (the theme header stylesheet is loaded automatically).
-	// Add wp_enqueue_style() here when assets/css/main.css exists.
+	// Icon and hover states for Spotlight's own custom core/button block-style variations.
+	// No dependency on 'global-styles' here — that handle is only registered
+	// during the front end's wp_enqueue_scripts flow, which never runs in
+	// wp-admin, so declaring it as a dependency silently drops this
+	// stylesheet from the block editor's iframe.
+	wp_enqueue_style(
+		'spotlight-theme-2026-custom-button',
+		get_theme_file_uri( 'assets/css/custom-button.css' ),
+		array(),
+		wp_get_theme()->get( 'Version' )
+	);
+
+	// Icon and hover states for WordPress core/button's own "Fill"/"Outline" styles.
+	wp_enqueue_style(
+		'spotlight-theme-2026-core-button',
+		get_theme_file_uri( 'assets/css/core-button.css' ),
+		array(),
+		wp_get_theme()->get( 'Version' )
+	);
 
 	// Add wp_enqueue_script() here when assets/js/main.js exists.
 }
-add_action( 'wp_enqueue_scripts', 'spotlight_theme_2026_enqueue_assets' );
+add_action( 'enqueue_block_assets', 'spotlight_theme_2026_enqueue_assets' );

openspec/changes/archive/2026-08-05-spotlight-global-styles-and-block-rules/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-05