superpowers-sage:block-scaffolding

Block Scaffolding — Custom Element Contract per Block

Scaffold a new ACF block with the full custom element architecture: scoped CSS, theme variations, optional JS lifecycle, selective enqueue, and documentation.

Announce at start: "I'm using the block-scaffolding skill to create the block."

When to use

• Auto-invoked by /building: after lando acorn acf:block produces a new stub
• Standalone new block: a block outside of a plan

When NOT to use

• Existing block that needs evolution → use /block-refactoring instead.
• Non-block UI component (Button, Card) → Blade component, not ACF block.

Input

$ARGUMENTS

Resolve to {ClassName} (PascalCase) and {slug} (kebab-case) before proceeding.

---

Quick Start

# Generate block stub (PascalCase name required)
bash skills/block-scaffolding/scripts/create-block.sh HeroBlock
# → app/Blocks/HeroBlock.php
# → resources/views/blocks/hero-block.blade.php

---

Hard Prerequisites

P1. Slug produces a valid custom element tag — block-{slug}. The block- prefix guarantees the required hyphen.

P2. Design system foundation:

resources/css/design-tokens.css   — must exist
resources/views/components/ui/    — must contain button + heading

P3. BaseCustomElement in theme:

resources/js/core/BaseCustomElement.js   — must exist

---

Operation Modes

Mode	When	$styles	CSS variations
Full	Theme switching (light/neutral/dark)	3 entries	3 .is-style-* selectors
Minimal	Fixed appearance (footer, nav, ticker)	absent	base tokens only

---

Phase 0 — Generate

lando acorn acf:block {ClassName} --localize

Produces:

• app/Blocks/{ClassName}.php — controller stub (localization-ready)
• resources/views/blocks/{slug}.blade.php — view stub

---

Phase 0b — Shared component inventory

Before writing the view, build a local registry of available shared components:

1. Glob resources/views/components/*.blade.php — list all component files
2. For each component: a. Read its @props declaration → note prop names + defaults b. Grep for var(--) patterns → note CSS variable names consumed
3. Build local registry:

   {
     "section-header": { props: ["eyebrow","title","align"] },
     "eyebrow":        { consumes: ["--eyebrow-color","--decorator-color"] },
     "button":         { consumes: ["--btn-bg","--btn-text"] }
   }