From superpowers-sage
Refactors existing ACF Composer blocks along 4 axes: rendering model, field composition, variants/styles, InnerBlocks adoption. Migrates legacy v1-v3, classifies phases, generates reports without breaking content.
npx claudepluginhub codigodoleo/superpowers-sage --plugin superpowers-sageThis skill uses the workspace's default tool permissions.
Analyze and improve an existing block after its first implementation. Four axes of
Scaffolds new ACF Composer Gutenberg blocks in Sage themes with custom element architecture, scoped CSS, theme variations, block.json, Blade views, and JS lifecycle.
Generates or edits WordPress Gutenberg blocks with Greenshift/GreenLight plugin. Converts HTML/CSS/JS designs or data/charts to paste-ready blocks for Gutenberg editor, or reverses to vanilla code.
Develops and debugs WordPress block themes: edits theme.json settings/styles, manages templates/parts/patterns/style variations, troubleshoots Site Editor (hierarchy, overrides, caching).
Share bugs, ideas, or general feedback.
Analyze and improve an existing block after its first implementation. Four axes of evolution: design drift detection, CSS coverage analysis, variation expansion, and gap/migration detection.
Announce at start: "I'm using the block-refactoring skill to evolve the block."
app.css/design-tokens.md that the block could leverage.b-{slug} class, dual selector, no custom element)/block-scaffolding instead/reviewing$ARGUMENTS
Resolve to {ClassName} and {slug}. If not provided, ask.
See references/evolution-axes.md for the 4 evolution axes.
Refactoring NEVER rebuilds from scratch. For a full re-scaffold, delegate to /block-scaffolding as a fallback.
From the argument, identify:
{ClassName} — e.g. HeroSection{slug} — e.g. hero-sectionapp/Blocks/{ClassName}.phpresources/views/blocks/{slug}.blade.phpresources/css/blocks/{slug}.cssresources/js/blocks/{slug}.js (may not exist — legacy)resources/css/editor.css (check for @import './blocks/{slug}.css')Read all present files.
Glob resources/views/components/*.blade.php in the target project (if a path is known, otherwise skip this step).
Build a component inventory table:
| Component slug | File | Likely use |
|---|---|---|
section-header | section-header.blade.php | <x-eyebrow> + <h2> pairing |
button | button.blade.php | <a> or <button> with utility classes |
card | card.blade.php | Repeated card structure |
Keep this table in context — G9 in Axis 4 will reference it to report concrete component names instead of generic suggestions.
If resources/views/components/ does not exist or is empty, note "No shared components found" and proceed.
Inspect the view file and the CSS file:
| Signal | Version |
|---|---|
View has <block-{slug}> custom element | v2 |
View uses $attributes->merge() on a <section class="b-{slug}"> | v1 |
CSS scoped to block-{slug} tag selector | v2 |
CSS scoped to .b-{slug} class selector | v1 |
CSS has dual selector &.is-style-*, .is-style-* & | v1 |
CSS has single selector .is-style-* block-{slug} | v2 |
JS file at resources/js/blocks/{slug}.js | v2 |
Mark the block's current version (v1 / v2 / mixed) before proceeding.
Prerequisites: a design reference must be available. Check in order:
docs/plans/*/assets/section-{slug}-ref.png on diskdocs/plans/*/assets/section-{slug}-spec.md on diskIf none available, report drift: NOT_VERIFIED and skip to Axis 2.
Execution:
visual-verifier agent with:
url: current environment's URL for a page rendering the blockselector: block-{slug} (v2) or .b-{slug} (v1)ref: the reference path found abovespec: spec file path if availableFor detailed axis procedures (CSS coverage, variation expansion, gap checks G1–G8), see references/evolution-axes.md.
Grep the view for co-occurring <x-eyebrow and <h2 inline — these should use
<x-section-header> instead. Also grep for <a elements carrying button utility
classes (e.g. btn-, rounded-, px-, py-, font-) — these should be
<x-button>.
Each instance where a component from the Phase 0b inventory exists but is not used: flag as IMPROVEMENT, naming the component (e.g., "use <x-section-header> instead of inline <x-eyebrow> + <h2>").
Detection — check the view for any of:
match($tone) expressions returning Tailwind class strings
(e.g. match($tone) { 'fg' => 'text-fg', 'dark' => 'text-depth-fg' })tone="fg" / tone="dark" / variant="*-dark" encoding
color context in PHP and passing it to child componentstext-depth-fg, text-identity, text-white)
applied directly on semantic elements (h2, p, span) instead of via
inherited CSS variablesColors must cascade from custom properties in the block's CSS; the view must not encode color context via conditional logic or hardcoded utilities. Each instance is CRITICAL.
When detected, generate corrected CSS for the Phase 6 report:
resources/views/components/*.blade.php,
grep each for var(--) patterns → build local variable name registry
(same logic as block-scaffolding Phase 0b; runs inline here, not delegated)design-guide.md ## Tokens → Colors to determine background context:
design-guide.md exists at docs/plans/*/components/*/design-guide.md
→ apply decision tabledesign-guide.md is absent → treat as Ambiguous; generate with
/* VERIFY: design-guide.md not found — confirm background context */| Token found | Background | CSS action |
|---|---|---|
bg-depth, bg-primary, bg-dark, bg-inverse | Dark | Override cascade vars with *-on-dark equivalents |
bg-identity, bg-sage, bg-accent | Identity (brand color bg) | Override cascade vars with *-on-identity equivalents (e.g. var(--color-identity-fg)) |
bg-bg, bg-surface, bg-muted, absent | Light (default) | No override — inherit :root defaults |
| Unrecognized token | Ambiguous | Generate with /* VERIFY: background context unknown */ |
For each nl2br(esc_html($var)) call in the view, trace the variable back to its
ACF field definition in app/Blocks/{ClassName}.php. If the field uses addText()
(single-line text), nl2br() is a no-op at best and misleading at worst. Flag as
IMPROVEMENT — remove nl2br() or change the field to addTextarea() / addWysiwyg().
See references/report-format.md for the refactoring report format.
After user approves proposals, apply in order: CSS removals → variation expansions → gap fixes. Run lando theme-build && lando flush to verify.
Use Playwright MCP to screenshot at canonical width and verify all variations. Then:
git commit -m "refactor(blocks): {slug} — {summary of applied changes}"
See /block-scaffolding anti-drift table — same rules apply during refactor. Every
proposal in Phase 6 should, after applied, produce code that would pass /block-scaffolding
as if the block were being created today.