From superpowers-sage
Refactors ACF Composer blocks along four axes: rendering model, field composition, block variants, and InnerBlocks adoption. Handles legacy migration, v2-to-v3 upgrades, and block evolution reports.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers-sage:block-refactoring <BlockClassName or block-slug><BlockClassName or block-slug>The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Analyze and improve an existing block after its first implementation. Four axes of
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.
npx claudepluginhub hekivo/superpowers-sageScaffolds ACF Composer blocks with custom element architecture, scoped CSS, theme variations, and JS lifecycle. Use when creating new Gutenberg blocks in Sage-based WordPress themes.
Guides editing existing WordPress blocks: read all files first, make minimal targeted changes, update block.json/edit/save consistently, handle static-to-dynamic conversion and interactivity.
Generates or edits WordPress Gutenberg blocks for the Greenshift/GreenLight plugin and converts data or vanilla HTML+CSS+JS to WordPress blocks.