Fix AI instruction standard to enforce JSON-first styling (LS-2338) - #21
Conversation
Add explicit JSON-first/CSS-last-resort rule to AGENTS.md, matching kwv-theme-2026's standard, plus a JSON-vs-CSS gate to the styling auditor agent and pattern-extractor skill so Sass/GSAP/is-styles are only used when theme.json genuinely cannot express the style. Fixes the incorrect claim that styles/blocks/ and styles/sections/ aren't auto-consumed by WordPress (AGENTS.md and theme-json.instructions.md). Integrates Zared's new wp-block-style-audit skill as the authoritative decision procedure. Docs/config only — no theme output changes.
brandonmarshal
added
ai-ops:instructions
|
Warning Review limit reached
Next review available in: 40 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
Note
|
| Layer / File(s) | Summary |
|---|---|
Block style audit foundation .agents/skills/wp-block-style-audit/SKILL.md, .agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md |
Adds procedures for auditing block style JSON, classifying CSS, validating tokens, assigning ownership, and verifying supported and unsupported cases. |
Theme policy and auditing AGENTS.md, .github/instructions/theme-json.instructions.md, .agents/agents/wordpress-theme-styling-auditor.agent.md |
Makes style JSON authoritative, documents recursively discovered style-picker options, and requires CSS rules to be checked for JSON equivalents. |
Pattern extraction JSON-first gate .agents/skills/pattern-extractor/SKILL.md |
Requires JSON styles before authored CSS and limits GSAP to interactions that CSS cannot implement. |
WordPress version requirement style.css |
Raises the minimum supported WordPress version from 6.4 to 6.9. The existing code/pre rule remains unchanged. |
Estimated code review effort: 2 (Simple) | ~15 minutes
Possibly related PRs
- lightspeedwp/ls-theme#3: Establishes related JSON-first styling and auditing guidance.
- lightspeedwp/ls-theme#4: Adds related
theme.jsonand modular style JSON guidance. - lightspeedwp/ls-theme#13: Contains styling changes governed by the JSON-first rules.
Suggested labels: area:theme, comp:theme-json, lang:css
Suggested reviewers: zaredrogers
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
| Check name | Status | Explanation |
|---|---|---|
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
| Title check | ✅ Passed | The title clearly summarizes the main change: enforcing a JSON-first styling standard in AI instructions. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
| Linked Issues check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
- Create stacked PR
- Commit on current branch
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Commit unit tests in branch
feature/ls-2338-phase-0-fix-the-ai-instruction-standard-agentsmd-skills
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands.
|
Tick the box to add this pull request to the merge queue (same as
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md:
- Line 9: Update the "$schema" example in the block-style JSON anatomy
documentation to use the WordPress 6.6 schema URL as the compatibility lock,
replacing the WordPress 6.9 URL. Keep the documented theme.json v3 support
aligned with this schema reference.
In @.agents/skills/wp-block-style-audit/SKILL.md:
- Around line 74-79: Update the token-reference guidance in SKILL.md section
“Check token references use the correct format” to document custom-token syntax:
var:custom|path|to|key for JSON values and var(--wp--custom--path--to--key) for
CSS strings. Extend validation instructions to verify custom tokens against
theme.json settings.custom in addition to preset tokens against
settings.presets.
- Line 4: Keep the WordPress 6.9+/theme.json v3 requirement explicit in the
compatibility metadata of .agents/skills/wp-block-style-audit/SKILL.md:4 because
this rule covers per-block :hover/:focus JSON support. Ensure the schema URL and
compatibility guidance in
.agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md:7-10
use the same 6.9 baseline; no 6.6 alignment is needed.
In `@AGENTS.md`:
- Around line 85-87: Scope the CSS exception-comment requirement to new or
modified rules so existing valid exceptions remain compliant without retroactive
comments. Update AGENTS.md lines 85-87 and
.agents/agents/wordpress-theme-styling-auditor.agent.md lines 56-61 to use the
same scoped policy and ensure the audit condition matches it.
- Around line 88-91: Update the structural-properties rule in AGENTS.md to be
conditional: require JSON or block attributes when the property has a supported
key, but permit unsupported properties such as overflow, max-width, and width in
Sass/CSS when the limitation is documented. Keep the existing guidance that
filename or folder does not exempt properties from the rule.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro Plus
Run ID: 7fee7f01-9b27-485e-8c71-412251129a26
📒 Files selected for processing (6)
.agents/agents/wordpress-theme-styling-auditor.agent.md.agents/skills/pattern-extractor/SKILL.md.agents/skills/wp-block-style-audit/SKILL.md.agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md.github/instructions/theme-json.instructions.mdAGENTS.md
There was a problem hiding this comment.
Pull request overview
Updates the repo’s AI and theme documentation to enforce a stricter JSON-first (theme.json/style JSON) styling standard, and documents WordPress 6.6+ auto-discovery of block/section style JSON files, with a small metadata bump in the theme header.
Changes:
- Tightened the “Theme-First Approach” guidance to make JSON the default styling layer and Sass/CSS/GSAP explicit exceptions.
- Corrected documentation to reflect that
styles/blocks/andstyles/sections/are auto-discovered as editor-facing style options in WP 6.6+. - Added a new
wp-block-style-auditskill and wired it into existing agent/skill guidance to standardise JSON-vs-CSS decisions.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
style.css |
Bumps the theme’s minimum required WordPress version to 6.9. |
AGENTS.md |
Adds explicit JSON-first / CSS-last-resort rules and updates style variation discovery guidance. |
.github/instructions/theme-json.instructions.md |
Aligns theme.json instructions with WP 6.6+ style JSON auto-discovery behaviour. |
.agents/skills/wp-block-style-audit/SKILL.md |
Introduces a new audit procedure for migrating CSS-heavy block style JSON into structured JSON. |
.agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md |
Adds a reference doc describing block style JSON structure, supported keys, and decision rules. |
.agents/skills/pattern-extractor/SKILL.md |
Adds a mandatory JSON-first gate before allowing Sass/CSS/GSAP/is-style work. |
.agents/agents/wordpress-theme-styling-auditor.agent.md |
Updates the agent’s operating rules/workflow to treat Sass/CSS as an exception layer and reference the audit skill. |
… (LS-2338) Fix schema URL to match the theme's actual trunk convention, document missing var:custom token syntax, align UK spelling, and scope the JSON-limitation-comment and structural-properties rules to new/modified CSS only so they don't retroactively invalidate existing valid exceptions (e.g. transitions/overflow/max-width that JSON has no key for). Applies to AGENTS.md, the styling auditor agent, and the new wp-block-style-audit skill.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/wp-block-style-audit/SKILL.md:
- Around line 81-82: Update the token validation guidance to resolve preset
references by category under the corresponding theme.json settings collection,
such as settings.color.palette, settings.typography.fontSizes, or
settings.spacing.spacingSizes, rather than a generic settings.presets
collection. Continue validating custom token paths against settings.custom.
- Around line 13-15: Update the guidance in the style-audit bullets to
distinguish block-root color and background rules from descendant element
styles: map root `.wp-block-*` styles to `blocks["block/name"].color`, while
mapping selectors such as `.wp-block-button__link` or `a` to the appropriate
`elements` configuration. Keep descendant nested-block and third-party block
guidance separate.
In `@style.css`:
- Line 8: Synchronize the documented WordPress minimum by updating the WordPress
version requirement in the README’s requirements section to match the 6.9
minimum declared by the style.css “Requires at least” metadata, or consistently
lower both declarations if 6.9 is not intended.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro Plus
Run ID: 6c38a201-386d-4f79-a615-d9cc84e19c89
📒 Files selected for processing (5)
.agents/agents/wordpress-theme-styling-auditor.agent.md.agents/skills/wp-block-style-audit/SKILL.md.agents/skills/wp-block-style-audit/references/block-style-json-anatomy.mdAGENTS.mdstyle.css
🚧 Files skipped from review as they are similar to previous changes (2)
- .agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md
- .agents/agents/wordpress-theme-styling-auditor.agent.md
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.
Suppressed comments (4)
.agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md:59
- This sentence says both
linkandbuttonsupport:visited, but elsewhere in the same doc:visitedis only listed underelements.link. Buttons don’t have a visited state, so this is misleading.
`link` and `button` elements support `:hover`, `:focus`, `:active`, `:visited` as sibling keys:
.agents/skills/wp-block-style-audit/SKILL.md:82
theme.jsondoesn’t have asettings.presetskey. Presets live under specific sections (e.g.settings.color.palette,settings.typography.fontFamilies, etc.), so this instruction is currently pointing readers at a non-existent path.
Verify every preset token slug exists in `theme.json` `settings.presets` and
every custom token path exists in `theme.json` `settings.custom` before using it.
.agents/skills/wp-block-style-audit/references/block-style-json-anatomy.md:10
- The minimal JSON example uses the
trunktheme.json schema URL, but this repo’s style JSON files (and this skill’s compatibility note) are targeting the WP 6.9 schema. Using the versioned schema here would keep the guidance consistent with the rest of the theme.
This issue also appears on line 59 of the same file.
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
style.css:9
- Theme header metadata now requires WP 6.9 / tested up to 7.0, but
readme.txtstill says "Requires at least: 6.4" and "Tested up to: 6.7". These should be kept consistent so tooling and users don’t get conflicting compatibility signals.
Requires at least: 6.9
Tested up to: 7.0
…on (LS-2338) Distinguish blocks["block/name"].color (block-root) from elements.* (descendant selectors like .wp-block-button__link) in the audit skill's guidance table — these were previously conflated. Correct the token validation reference from the non-existent settings.presets to the real per-category theme.json collections (settings.color.palette, settings.typography.fontSizes, settings.spacing.spacingSizes). Sync README.md's documented WordPress minimum (6.4+ -> 6.9+) with style.css.
ZaredRogers
left a comment
ZaredRogers
left a comment
There was a problem hiding this comment.
Looks good @brandonmarshal
Summary
AGENTS.md's Theme-First Approach, matching the standard used by thekwv-theme-2026reference theme.agents/agents/wordpress-theme-styling-auditor.agent.mdand.agents/skills/pattern-extractor/SKILL.mdso Sass/GSAP/is-styles are only used when theme.json genuinely cannot express the styleAGENTS.mdand.github/instructions/theme-json.instructions.mdstatingstyles/blocks/andstyles/sections/aren't auto-consumed by WordPress (they are, WP 6.6+)wp-block-style-auditskill fromAGENTS.mdas the authoritative JSON-vs-CSS decision procedureTest plan
AGENTS.mdstates an explicit JSON-first / CSS-last-resort ruleSummary by CodeRabbit
New Features
Documentation
theme.jsonand style JSON are the primary styling systems.Compatibility