deploy

name	deploy
description	Convert per-page styled HTML prototypes (stardust under stardust/prototypes/**, or claude-design / Mobirise / Relume / Lovable / v0 / Figma-derived pages, or JSX prototypes pre-rendered to HTML, often under samples/) into Edge Delivery Services (EDS / AEM) blocks and content pages, then deploy via DA. Each prototype section becomes one EDS block; the prototype's per-section CSS becomes that block's CSS scoped under the block class. Use when the user wants to lift styled per-page HTML prototypes into a working EDS site under blocks/ and content/.
license	Apache-2.0

stardust:deploy — prototypes → EDS/AEM

When to use

The user has:

1. Per-page styled HTML prototypes — one file per page, each carrying its own CSS. Accept any of these shapes:
   • Single-file with inline <style> and :root tokens + semantic <section class="…"> (e.g. stardust output, or claude-design "Stardust"/Mobirise/Relume-style pages). Easiest — convert directly.
   • External per-page .css (the <style> lives in a sibling stylesheet). Read the linked CSS the same way you'd read an inline <style>.
   • <x-dc> document-content with everything inline-styled (per-element style="…"). Harder — you must lift inline styles into a scoped block stylesheet.
   • React/JSX prototypes (an HTML shell that mounts .jsx components at runtime). Pre-render to static HTML first (run it, or screenshot + read the JSX to reconstruct the DOM); you cannot decorate a shell that has no server-rendered <main>. The prototypes typically live under stardust/prototypes/** or a samples/<Name>/ folder — don't hard-code the path; discover them.
2. An EDS project at the repo root — vanilla aem-boilerplate (github.com/adobe/aem-boilerplate): scripts/aem.js + scripts/scripts.js, blocks/ with header/footer/fragment, styles/styles.css + styles/fonts.css, head.html. This is the ONLY runtime this skill targets — no runtime files are ever ported, vendored, or edited.
3. A goal to convert: prototypes → authorable EDS blocks + EDS content pages under content/**.

If the user has prototypes but no EDS scaffolding, stop and ask whether to scaffold from adobe/aem-boilerplate (use the template as-is; the conversion never modifies scripts/aem.js). If they have EDS but no prototypes, this skill doesn't apply.

Target runtime — vanilla aem-boilerplate (what the generated code can rely on)

The stock boilerplate provides everything the conversion needs; the runtime is never modified. The load chain (head.html → scripts.js → loadEager → loadLazy → loadDelayed) gives you:

• Section DOM: each main > div becomes <div class="section">; runs of default content are wrapped in div.default-content-wrapper; each block table gets a div.<name>-wrapper around <div class="<name> block" data-block-name="<name>">, and the section gains .<name>-container. Sections are hidden (data-section-status + inline display:none) until loaded — undecorated-content flash is handled by the runtime, not by foundation CSS.
• Cell normalization (wrapTextNodes, in decorateBlock — #104): any block cell whose FIRST element child is not in P/PRE/UL/OL/PICTURE/TABLE/H1–6 — or that leads with a <picture> followed by anything else — gets its ENTIRE content folded into one <p> before your decorate() runs. A media-led mixed cell (<img> + <h3> + <p>) therefore arrives as a single wrapper <p>; a collector reading cell.children sees ONE node and silently drops everything after the image. Decode with the wrapper-expanding collector (Step 8, #62/#104).
• Body gate: styles.css ships body { display: none } + body.appear { display: block }; loadEager() adds appear after decorateMain(). This gate is CORRECT — keep it. Any off-pipeline render (harness, probes) must load the real scripts/scripts.js so the gate is satisfied; a blank render means the runtime never booted, not that the gate should be removed.
• Buttons: decorateButtons() (in scripts.js) buttonizes ONLY author-formatted links — see Step 5 for the emitted class family.
• Chrome: header/footer BLOCKS (loaded by loadLazy) fetch authored fragment documents — /nav and /footer by default, overridable per page via nav/footer metadata. Block JS runs, so interactive chrome (hamburger, dropdowns) is real JS. See Step 6.
• Fonts: @font-face lives in styles/fonts.css, loaded by loadFonts() (eagerly on desktop / repeat views via a fonts-loaded session flag, always in loadLazy); styles.css carries the metric-matched fallback faces. See Step 4.
• Auto-blocking hook: buildAutoBlocks() in scripts.js is project-owned — the home for D1 auto-blocks (video/embed URLs, fragment links).
• Lint: generated blocks and styles lint under the project's own config; there is no vendored runtime to exempt. Do not create an .eslintignore for runtime files.

The boilerplate itself drifts (e.g. current main emits p.button-wrapper; older clones emit p.button-container and buttonize bare links). Never assume — the Runtime-detection probe below records what THIS target actually does, from its own scripts.js/aem.js.

Playwright re-probe (run before anything that renders)

--no-save playwright installs from earlier phases are pruned by any later real npm i — including any setup step adding a devDependency (extract SKILL.md § Setup → --no-save installs are ephemeral). Before the Local-QA harness, the computed-layout gate, or any probe below, verify node -e "import('playwright').then(()=>process.exit(0))" from the project root and re-install (npm i -D playwright --no-save --legacy-peer-deps) on failure.

Runtime-detection probe (run before Step 1 — write stardust/runtime-contract.json)

Boilerplate clones drift (button classes, wrapper names, buttonization rules differ across vintages), and a wrong assumption here is silent and sitewide. Before converting anything, read the TARGET's own scripts/scripts.js + scripts/aem.js — what the button decorator emits and requires, how decorateBlock wraps blocks — and record the answers:

{
  "runtime": "vanilla-eds",
  "blockWrapperClass": "block",
  "buttonClasses": ".button / .button.primary / .button.secondary / .button.accent, in p.button-wrapper",
  "buttonization": "formatted-only | bare-links-too",
  "fragmentScriptPolicy": "inert-innerHTML",
  "emptySectionCollapse": true
}

Block CSS/JS generation and the Local-QA harness read this contract instead of assuming. The values above are current adobe/aem-boilerplate main; the two known drift axes to verify per target:

• buttonClasses — current main emits a.button (+ .primary/.secondary/.accent) inside p.button-wrapper; older clones emit p.button-container, and some buttonize a bare <a> alone in a paragraph (buttonization: bare-links-too) while current main requires authored <strong>/<em>. Style the wrong container class and spacing/group layout silently breaks; assume the wrong buttonization rule and plain text links ship as buttons (or CTAs ship as bare links).
• blockWrapperClass — decorateBlock adds .block + data-block-name and wraps the block in div.<name>-wrapper (section gains .<name>-container). Scope block CSS under .<name> (the class every vintage sets); confirm empirically by asserting a grid container computes display: grid in a headless render — a wrong scoping guess makes every grid fall back to display: block ("mobile layout on desktop") while typography still looks fine.

When emptySectionCollapse is true (the page-metadata block leaves an empty padded section after its content is consumed into <head>), add main .section:empty { display: none } to the foundation — or an empty ~88px band sits between the header and the first real section.

Deploy (DA Source API, from a local agent)

Steps 1–9 are the conversion methodology; deploy is the one transport-specific step. From a local agent (Claude Code / CLI), each converted page deploys headlessly:

Stage	How
Code	git push the branch → AEM Code Sync builds it
Sanitise	skills/deploy/scripts/sanitise.js — run it before the write (DA corrupts raw UTF-8)
Content write	DA Source API: PUT admin.da.live/source/<org>/<repo>/<path>.html (multipart, field name data, type=text/html)
Make live	POST admin.hlx.page/preview/<org>/<repo>/<branch>/<path> (then optionally /live/...)
Auth	IMS token (DA_TOKEN) — see the da-content / da-auth skills

The content payload is a body fragment (see Step 9). The deploy needs the code branch pushed to GitHub so the branch preview (<branch>--<repo>--<org>.aem.page) renders with your blocks. See da-deploy-protocol.md for the full curl contract.

For more than a few pages, use the bundled driver instead of a hand-rolled loop (#4). node skills/deploy/scripts/deploy-batch.mjs --org <org> --repo <repo> --branch <branch> --content content [--concurrency 4] [--no-publish] runs PUT → preview → live across a content tree with bounded concurrency, a persistent ledger (content/.deploy-ledger.json) so a re-run skips pages already live and only re-drives FAILs, capped-backoff retries on 000/429/5xx, an append-only log (survives a restart), and a delivered-.plain.html check before flipping a page to live (admin 200 ≠ delivered). It's idempotent — safe to Ctrl-C and re-run, which is the documented recovery for a transient-blip half-deploy. A serial hand-rolled bash loop that truncates its own log on restart is the anti-pattern this replaces.

Per-page atomic delivery contract. A page is deployed only when the full chain passes, in order: davids-model-lint.mjs exit 0 (0 🔴 — the content-structure gate) → sanitise-wrapped file (scripts/sanitise.js) → PUT (multipart field data, type=text/html) → POST /preview/ → POST /live/ → GET the rendered .plain.html and assert: HTTP 200, the <body> wrapper intact, exactly one <h1>, zero about:error, no /img/ srcs — plus, when key facts are declared for the site (#86 — DESIGN.json.extensions.metadata.keyFacts[], written by direct; skip the gate and note the skip when the field is absent), grep the RAW full-page HTML (not the rendered DOM) for each fact string on the pages that carry them. Only then flip the page's ledger entry to deployed — never on the POST codes (admin 200 ≠ delivered).

A .plain.html pass is NOT a layout pass — add one computed-style assertion (#the silent-failure guard). The text-level asserts above are all satisfied while the page renders as a single stacked column, because a block-CSS scoping mistake (a selector keyed to a wrapper class the target runtime doesn't emit — see blockWrapperClass in the runtime contract) makes every grid fall back to display: block with the typography still correct. This shipped green on a real e2e site. So the contract's final gate is a headless computed-style check on the delivered live URL (not .plain.html): load the page in a headless browser and assert, for the first page of each template, that every block whose CSS declares a grid/flex layout computes display: grid/flex (not block), main .section count > 0, blocks are decorated (data-block-name present), zero pageerror, zero broken images. A block that should grid but computes block fails the page — do not flip it to deployed. This is the assertion blockWrapperClass in the runtime contract calls for; the atomic contract is where it must actually run, once per template. Two field-decodes worth pinning: a burst of PUT 400s is a malformed path, not rate limiting — lowercase every segment, never a double slash (content//… 400s the PUT while preview/live still 200), no trailing -/_ on a segment; and write long loops to a bash script file with absolute binary paths (/usr/bin/curl, the full node path) — zsh drops PATH inside while/for in some contexts, and the resulting command not found burst mimics a transport failure.

Token hygiene (#16). The IMS token typically lives in repo .env as DA_TOKEN. Before the first commit, make sure .gitignore excludes .env, .env.*, and qa/ (the local QA harness) on the branch you'll branch tests from — otherwise every test subbranch re-exposes the token. Keep samples/ out of commits too. Dev tokens last ~24h; a 401 with an empty body means expired → refresh and retry (the write is idempotent).

DA_TOKEN lifecycle — preflight and re-check, never fail pages on it. At setup, preflight the token: decode the JWT exp claim when present (base64-decode the middle segment) and smoke-test ONE authenticated DA call before any batch. Re-check before each long batch — a token fresh at setup can expire mid-run. On a 401 mid-batch: checkpoint the ledger (the batch driver's persistent ledger already records per-page state), stop the batch, and halt with a single actionable instruction — "DA_TOKEN expired; refresh it in .env and re-run the same command (the ledger skips delivered pages)" — instead of letting every remaining page fail red. Token expiry is the one credential failure the agent cannot self-recover; it is a legitimate hard stop even in a hands-off run.

The one rule that drives everything else

One distinct visual PATTERN = one EDS block — and a section with NO pattern is NOT a block at all. The content structure that lands in DA must follow David's Model (davids-model.md, bundled with this skill — the 15 rules mapped to this skill's contracts; cited as D#N throughout). Its first rule shapes everything here:

• D1 — blocks aren't ideal for authoring. A block is a table an author must maintain. A section whose content is plain prose — heading, paragraphs, an image, CTAs, with no repeating units and no bespoke interactive structure — is authored as DEFAULT CONTENT in its own section, never wrapped in a block. Its skin rides a minimal section-metadata style value (see Step 3); the section's semantics stay native <h2>/<p>/<picture>/<a>. Never create a text/heading/image block around bare default content — that is the D1 anti-pattern verbatim.
• Blocks are for structure default content can't express: repeating units (cards, FAQ, logos, team), genuinely bespoke compositions (a countdown, a stat band, a cinematic hero), and interactive components. For those, one distinct prototype pattern = one block. Don't abstract speculatively, and don't extract "patterns" across prototypes unless sections are genuinely the same pattern — each pattern's bespoke CSS can't be wrongly shared; violating this casually cost full resets (see ANTI-PATTERNS).

The one deliberate exception — collapse SAME-PATTERN sections into one block + VARIANT classes. When two or more sections are the same content pattern (card grids, prose/CTA bands, quotes, accordions) differing only in skin, emit ONE canonical block (cards, text, quote, accordion) and put each section's look behind a variant class (class="cards brands"), brand styling in the variant CSS. The block JS stays generic (classify cells by content); only the CSS differs per variant. This is the David's-Model library win (D9: small, reusable, variant-driven — not 20 bespoke names) and is proven to preserve fidelity. Keep genuinely-unique sections (a hero, a countdown widget) bespoke. Budget for it: variant CSS is careful work and some grids are count-specific.

The prototype is the visual spec. The block exists to AUTHOR its content — see The ENCODE contract below for what well-authored content looks like, and ANTI-PATTERNS for how a block must defensively PARSE it.

Output you will produce

For a typical 5–10 page site:

• One block per distinct prototype PATTERN (D1/D9). A 5-page site with 6 sections each → typically ~8–14 blocks: prose bands land as default content, same-pattern sections share one block + variants, and only genuinely bespoke sections get their own block.
• One EDS content page per prototype page. Same number of pages.
• Nav + footer documents at content/nav.html and content/footer.html — authored content, deployed and published like any page, fetched by the stock header/footer blocks (D12: chrome is the canonical fragment use case).
• Per-site blocks/header + blocks/footer CSS/JS reproducing the prototype's chrome (see Step 6).
• Updated styles/styles.css with brand tokens lifted from the prototype's :root, a reset, the EDS section scaffold, a global button system (see "Lean on EDS button conventions" below), and the styles for the few section-metadata style values default-content sections use. Nothing more.
• No shared utility modules. No wave systems. No motion library. The prototype already encodes these per-section; keep them inside the owning block. Section-metadata style values stay a SMALL closed set (dark, tinted, …) used only by default-content sections — blocks keep painting their own sections.

The ENCODE contract — what well-authored content looks like

The ANTI-PATTERNS below are the decode side: a block must parse robustly whatever DA hands it. This is the encode side: what the content page should EMIT in the first place — and it is where David's Model is enforced (davids-model.md for the full rule-by-rule mapping; node skills/deploy/scripts/davids-model-lint.mjs content/ is the mechanical gate — every page must exit 0 before any DA write). One principle drives all of it:

Decoration that must survive DA rides a semantic inline tag — never a class, never an invented delimiter. DA strips <span> and author classes from block cells, but PRESERVES <strong>, <em>, <code>, <a>, <picture>/<img>.

Structural rules (the lint's 🔴 tier):

• No nested block tables, ever (D2). A block cell never contains another block. Shared/repeated content is a fragment link or an auto-blocked URL; complex nested visuals (tabs, accordions) are modeled as sections and combined client-side.

• No row/column spans beyond the block-name header (D3), and blocks stay ≤ 4 columns (D10) — wider means the content was fragmented in a way that breaks default-content semantics. Exception: a genuine data table.

• Fully-qualified URLs in authored content (D4). Authors treat URLs as opaque tokens; code extracts pathnames. (Image-src specifics: see Images below.)

• No HTML, CSS, or JSON visible as TEXT in any cell (D15). A <tag>, a { } binding, or a CSS rule appearing as author-visible text is a modeling mistake — code lives in the repo, not in documents.

• Video/embed URLs are auto-blocked, not authored as blocks (D1). A YouTube/Vimeo/embed URL alone on its line stays a plain link in content; buildAutoBlocks() in scripts.js turns it into the embed at decorate time. Never make an author build an embed/video block table around a URL.

• Alt-text carries the image description only (D13) — never data a block parses.

• Accent / emphasis → <em>, never <span class="em"> — DA strips the span and the accent is silently lost. Ensure the block CSS targets BOTH em and .em.

• Key facts must live in SERVER-RENDERED page content, never solely in chrome (#86, D12). The header/footer blocks fetch /nav and /footer client-side after first paint, so anything that exists only there — a trust fact line ("Open source · Apache 2.0 · built by X"), pricing, contact facts — is INVISIBLE to non-rendering crawlers and AI bots on every page. If a fact matters for SEO/LLM answerability, author it in page content (a fact panel, an install-section sentence, the metadata description); the chrome copy is presentation, not the crawlable source of truth. Same D12 logic for any fragment: SEO-relevant copy belongs directly on the page. Verify by grepping the RAW served HTML (no JS) for the key-facts list — the rendered DOM check passes either way and hides the failure.

• Sub-fields → a leading preserved tag, never an in-band delimiter. Don't invent Step|Title, flag :: desc, name|tag micro-syntax (authors must learn it). Lead the cell with the field's tag — kicker → <strong>, code/flag/path → <code> — and the block reads the leading tag as the term, the rest as the value. (A block MAY still parse a delimiter as a back-compat fallback — that's decode, not what you emit.)

• No raw presentational HTML in content. No <sup> (move unit superscript into the block — split 185+ into number + generated <sup>); don't use <br> for layout (a deliberate editorial line break via Shift+Enter is fine — it's not "exposed code").

• Grouped item sets → one row per item. A band of N similar units (metrics, stats, feature cards) is ONE row per unit, its parts as flat siblings in that cell — not one cell per atom (loses which label pairs with which number) and not all-in-one-cell. The block segments per row.

• Lists / FAQ → rows, not nested lists or one blob (D5). An accordion/FAQ is a head cell then one row per Q/A (question cell + answer cell). Simple inferred lists (related articles) may be one cell holding the links; code pulls the links.

• Section head → DEFAULT CONTENT, not a block row (D1). The eyebrow/heading/lede that sits above a repeating block (cards, metrics, FAQ, insights) is prose, not part of the block's structure — author it as default content in the section, before the block, so DA and .plain.html keep it out of the block table. The block reabsorbs it at decorate time (see "Section heads" below), so this is a pure markup/authoring win with zero pixel change. (NOT for a genuine widget whose rows ARE its structure, e.g. countdown.)

• Buttons → the emphasis convention (D6): primary <strong><a>, secondary <em><a>, high-impact accent <em><strong><a> (use sparingly — one per band at most). Size/color come from the block/section context, never from author choices; needing more than these three slots means a design-system decision leaked to authors (see "Lean on EDS button conventions" for the >3-variant escape hatch).

• Headings → real outline, no level jumps: one <h1>; section titles <h2>; card/sub titles <h3> (never skip to <h4>). Canonicalising a prototype's card <h4> to <h3> is correct.

• Metadata stays name/value (D14) — config only, mapping to data-/<meta>; never name/value for displayed content (a heading, an image, body copy modeled as a value cell is the lint's 🔴).

Section heads: default content the block reabsorbs (zero pixel change)

A head-bearing block (one with a section eyebrow/heading/lede above repeating units) should NOT carry that head as block rows. Author the head as default content in the section, before the block; the block table holds only the repeating units. Then the block reabsorbs the head so the decorated DOM — and every pixel — is identical to the old in-table form:

• First choice — style the head IN PLACE, no JS at all. The runtime gives the section a .<name>-container class, so the head is directly addressable: .cards-container .default-content-wrapper { … }. When the prototype's head sits visually OUTSIDE the block's grid (the common case), this is the whole implementation — no reabsorption needed.
• Reabsorb only when the head must live INSIDE the block's layout container (e.g. the head is a grid cell of the same grid as the units). On decorate(block), read the section's leading default-content wrapper, build the SAME .section-head the block used to build from its first rows, and remove the wrapper. The head wrapper is a sibling of the block's .<name>-wrapper, not of the block itself: use block.parentElement.previousElementSibling, match .default-content-wrapper (block.previousElementSibling alone is null — the block is nested in its wrapper).
• Keep the old in-table head (leading non-unit rows) as a defensive decode fallback.
• Verify zero change: diff the decorated block outerHTML (ids/media_<hash> normalised) old-vs-new — it must be byte-identical, with 0 default-content wrappers left after decorate.

A FOUC is possible (head paints as default content, then reabsorbs); the final layout is identical — watch CLS only if default-content margins differ markedly from the head's.

Images: editorial → authored content, decorative → CSS only

Any raster/brand image that carries meaning is EDITORIAL and must be authorable content — including hero / feature / CTA-band backgrounds that sit behind text and a scrim (the author swaps them per campaign; they're the page's most important visual). For editorial images:

1. Upload the binary to DA: PUT https://admin.da.live/source/{org}/{repo}/media/<scope>/<file> (multipart, field name data, correct Content-Type; upload the JPG/PNG/webp source only — the pipeline generates responsive variants). SVGs: pure-vector only (#99). An authored SVG that embeds raster data (<image>/data:image base64 behind a pattern fill — common for exported award badges/logos) makes the preview of EVERY page that references it fail 409 "error from content-bus", with no per-asset error. Extract the embedded raster (data:image/png;base64,… → .png) or rasterize, and author the PNG; small pure-vector SVGs (logos, icons) ingest fine. The lint flags authored .svg media URLs as an advisory.
2. Author a single <img src="https://content.da.live/{org}/{repo}/media/<scope>/<file>" alt="…"> in the cell (branch-independent; the pipeline emits the responsive <picture>). Never a repo-relative /img/… in content (→ <img src="about:error">). Never bake imagery into block JS by index (CARD_IMAGES/LOGOS) — that isn't authorable.
3. The block renders the authored <img> into a background LAYER (.hero-bg / .card-media / .text-media); the scrim/gradient is a CSS ::before OVER it. Keep a fixed CSS asset as the no-image fallback.

Decorative = CSS only applies to image-LESS treatments (gradients, scrims, textures, solid washes) and to genuinely fixed brand assets referenced as CSS backgrounds root-relative (/img/<brand>/… — browser-fetched, never ingested, so no about:error and no upload).

The check that catches the #1 mistake: after preview, grep the delivered .plain.html for the expected <img>+alt count. "It renders" hides CSS-background images — they're absent from .plain.html, carry no alt, and are neither authorable nor AI/SEO-visible.

When the image src is a SOURCE/external URL (migration), verify it resolves BEFORE you author it. Re-using an image straight off the source page is the most common way to ship <img src="about:error">: the preview ingester fetches the authored URL, and if that fetch fails the delivered image is about:error — silent, since the page still renders. So verify every authored <img> whose src points at the source/CDN — but the verification fetch must match how extract reached the origin, and a failure is not automatically "omit".

Verify with the recorded fetch technique, not a bare curl (#2 — bot-managed origins). A large fraction of real migration targets sit behind Akamai / Cloudflare / Imperva / F5, which 403 a plain curl (and headless requests) while serving the same asset fine to a real browser. A blanket "curl it; if not 200, omit" therefore strips every real brand image off an entire bot-walled site — the exact failure the quality bar forbids. Instead: read _crawl-log.json#discovery.fetchTechnique. When it is headed-chrome, verify image URLs with an in-page fetch from the open browser context (page.evaluate(async u => (await fetch(u)).status, url)) — that inherits the JA3/H2 fingerprint and cookies (per extract/reference/playwright-recipe.md § Bot-management → Sub-resource fetches); a bare curl/request will falsely report the asset broken. Only when fetchTechnique is plain may a bare curl -s -o /dev/null -w '%{http_code}' <url> stand in.

Distinguish 403-bot-wall from 404-missing, and prefer rehost over omit. A 403/401 from a CDN means blocked-when-hotlinked, NOT missing — and even if the URL would 200 to the ingester now, hotlinking the source CDN from the delivery host is fragile (it can 403 cross-origin at preview time, yielding about:error). So the default remediation for a 403/blocked captured image is download-and-rehost, not omit: extract already saved a local copy under stardust/current/assets/media/ via the in-page fetch — upload it to DA (PUT …/source/{org}/{repo}/media/<scope>/<file>) and author the content.da.live URL (see Images, above). Omit only on a true 404 (asset genuinely gone) after attempting the rendition/delimiter repairs below — and never substitute a generic logo/placeholder (…-logo…) as if it were editorial. Two real failure signatures where the asset exists — fix the URL, don't drop it: (1) wrong rendition variant — the page exposes only a derivative that 404s while a sibling resolves (e.g. a portrait's …/4x3/768/… 404 vs …/original/768/… 200) → rewrite to the resolver; (2) missing query delimiter — …/<id>&wid=600&hei=… with no ? makes <id>&wid=… a bogus id → 403 → repair the first & after the id to ?.

content.da.live media URLs are auth-gated — don't anon-curl them. Once you've rehosted to DA, the recommended https://content.da.live/{org}/{repo}/media/… src returns 401 to an anonymous curl even though it is correct and the preview pipeline ingests it fine. Do not treat that 401 as "broken" and omit. The correct verification for an already-rehosted/DA-hosted image is post-preview: grep the delivered .plain.html for about:error (must be 0) and assert the expected <img>/alt count — see da-deploy-protocol.md step 3b. Exempt content.da.live (and admin.da.live) URLs from the pre-author 200-check entirely.

The ingester rehosts <img>/<picture> ONLY — video/audio/PDF must NOT ride content.da.live (#103). A content.da.live/....mp4 authored as a link survives verbatim into the block's <video src>, and because the host is auth-gated every anonymous VISITOR gets 401 — poster-only, silent (the page looks intentional; only a live video/console probe catches it). Ship video from the CODE ORIGIN: commit the mp4 and reference it root-relative (/media/<scope>/<file>.mp4, fixed-asset semantics per #67) or use an external video host; keep the poster as an authorable editorial <img>.

Steps

1. Audit (light)

First, normalize the input to static HTML. If a prototype is React/JSX (an HTML shell that mounts .jsx into #root), pre-render it to static HTML before auditing (#24). The reliable recipe:

# 1. serve the prototype's OWN folder with a plain static server (NOT file:// —
#    babel-standalone XHRs the .jsx and file:// CORS-blocks it; the aem dev
#    server CSP-blocks the inline scripts too).
( cd samples/<proto> && python3 -m http.server 8765 & )
# 2. load in Playwright (React/babel load from unpkg — needs internet), wait for
#    mount, capture #root's innerHTML, save it for the block agents to read:
#    page.goto('http://localhost:8765/<file>.html'); waitForTimeout(4000);
#    fs.writeFileSync('samples/<proto>/_rendered.html', root.innerHTML)

From there it converts like an external-CSS prototype (semantic classes + the prototype's .css). If it's <x-dc> document-content, the sections are still <section>/<div> elements; just expect inline style="…" instead of a <style> block. The rest of this skill assumes a static <main> exists.

View behind routing / sign-in (#27). If the view you want is not the default render (e.g. a signed-in dashboard behind a sign-on flow), seed the app's persisted state before it boots rather than capturing the landing page. Many prototypes persist their route to localStorage: page.addInitScript(() => localStorage.setItem('<key>', JSON.stringify({page:'dashboard', user:'Alex'}))) then navigate. Generic alternatives: drive the UI to the view (fill + submit the sign-on form, then capture) or set the router hash/URL. Capture #root for the view you actually intend to convert.

Read every prototype's <main> markup (skip the <style> for now) and produce a per-page section list:

home: hero, work, approach, team, clients, closing
approach: approach-hero, manifesto, tenets-detailed, cadence, closing
team: team-hero, team-roster, work-style, recent, careers, closing
…

A useful pattern: dispatch the Explore subagent at thoroughness=quick with this exact ask. You don't need a 22-pattern punch list — you need filenames + section names. Resist the urge to "find shared patterns." Pattern reuse will emerge organically when two sections turn out to be byte-identical.

Fingerprint per-instance variation BEFORE writing block code (#90). A section-name list is copy-level; it does NOT reveal that instances inside a repeated group look different — an active filter chip vs its outline siblings, a filled accent CTA among outline CTAs, image cards vs image-less title-cards. Those are the details a copy-driven conversion silently flattens (a whole grid of identical cards, one CTA styled like the rest), and the mandatory gates (one <h1>, grids compute grid) still pass. So run the proactive probe up front: node skills/deploy/scripts/style-fingerprint.mjs "file://<abs>/<proto>.html". For every group of sibling instances it clusters each instance by a COMBINED signature — computed style-delta (background/border/color/background-image/weight/align) AND structural (hasImg, hasSvg, child count) — and reports any group with >1 cluster as a candidate per-instance variation for the owning block to reproduce. It is advisory: it will also flag legitimate variation (a footer with one bold link among plain ones), so filter false positives with judgment — but never flatten a real variant (an active chip, an accent CTA, an image-less card) just because the block treats siblings uniformly. The structural half is load-bearing: image-vs-image-less cards (and any :has()/:not()-driven variant) share the same top-level computed style, so a style-only probe misses them — include the structural signals. The manifest becomes the block author's checklist; this is the pre-block complement to Step 10's post-deploy content-diff (which catches the same class of miss too late).

2. Decide names + reuse — LOCK BEFORE WRITING ANY CODE

Two triage questions come BEFORE naming, per section (record both in the conversion log):

1. Is it a block at all (D1)? No repeating units, no bespoke interactive structure → default content + a section-metadata style value. Not a block, no name needed.
2. Does it match a Block Collection pattern (D11)? Hero, cards, columns, accordion, quote, table, embed, carousel/tabs — if yes, mirror that block's name and content model (the authoring shape and row semantics from github.com/adobe/aem-block-collection), even when the CSS stays fully bespoke. An author who has seen any EDS site can then author yours. Only sections matching no collection pattern get an invented name.

Naming rules (for the sections that ARE blocks and match no collection pattern):

• Block name = the prototype's <section class="X"> value, kebab-cased (hero, work, closing, approach).
• Never name a block after a reserved EDS class (#15). section, block, wrap, and button are used by the runtime's section/decoration DOM, and names ending in -wrapper or -container collide with the wrapper/container classes decorateBlock derives (.<name>-wrapper, .<name>-container) — a block named section collides with <div class="section"> and breaks decoration. When the prototype's section class is generic/reserved (Festool uses class="section" twice), derive a semantic name from the section's data-screen-label / intent instead (new-products, discover) and carry any modifier like tinted as a block variant.
• When the same section appears on multiple pages with identical visual treatment, build ONE block and use it everywhere. The classic example: closing CTA at the end of every page.
• When a section appears on multiple pages but looks different (e.g. home hero vs case-study case-hero vs service service-hero), they are different blocks. Prefix with the page archetype.
• When two sections within one prototype share the same visual treatment but different copy (e.g. case-study discovery and decisions are both 2-col prose with eyebrow + headline), it is fine to merge into one block (case-prose-2col) with a single text variant cell ("tinted" / "default"). Use your judgment.

Scale the naming ceremony to the number of pages. For a single-page conversion where each <section class="X"> has a self-evident, unique name (hero, quick, used, stats…), there are no cross-page reuse decisions to make — just lock block name = section class and proceed; don't pepper the user with questions. The questions below matter for multi-page sites, where the same-looking section recurs and you must decide reuse vs. archetype-prefixing.

Surface 3–5 naming questions to the user before writing any block code (multi-page sites):

• "What's the home hero called? hero?"
• "Are the closing CTAs across all pages identical? Same closing block?"
• "Should case-study discovery/decisions/solutions be one block or three?"
• "Is the per-service hero distinct from the home hero? Build service-hero separately?"

Lock the answers in writing (in stardust/eds-conversion-log.md or similar). This is the single highest-leverage step in the whole process.

2b. Section schema + decode tier — close the round-trip BEFORE writing code (#93, #95)

The dropped-CTA / role-swap / flattened-variant class has ONE root cause: the authored rows (ENCODE) and the block's decorate() (DECODE) are written independently and hoped to be inverses. Two moves close the loop up front; the in-loop block-roundtrip gate (#94, Step 8) then proves it closed.

Emit the section schema — the shared ENCODE/DECODE contract (#93). Once names are locked, generate the per-section contract both sides are written FROM:

node skills/deploy/scripts/section-schema.mjs "http://localhost:8791/<prototype>.html" \
  --out stardust/eds-schema/<page>.json

Per section it emits the ordered role-classified inventory (heading / eyebrow / cta+href / body — the SAME classifier content-diff and block-roundtrip measure with, from skills/deploy/scripts/content-inventory.mjs) and the repeating-unit groups (count + per-unit composition: headings/ctas/imgs/textRuns, uniform or not). Use it on both sides:

• ENCODE: one row per repeat unit, fields in schema order; every schema item appears in the authored content. An item you deliberately drop is a decision recorded in the conversion log — never an accident.
• DECODE: the block's JSDoc cites its section's schema path; decorate() classifies exactly the roles the schema lists, and the schema's unit count is the post-decorate count assertion (#48/#52).

Cross-check repeats[].uniform against the #90 fingerprint: uniform: false means a per-instance variant (active chip, accent CTA, image-less card) the block must reproduce, not flatten.

Pick the decode tier per section — template-slotted vs reconstructive (#95). Reconstruction is where decode bugs live, so only reconstruct where authors need the structural freedom:

• Template-slotted (fidelity by construction). For fixed-composition sections whose structure never changes at authoring time (a bespoke hero, a cinematic band, a stat/countdown composition): decorate() holds the prototype section's inner DOM verbatim as a template literal and SLOTS the authored values into it by role — eyebrow text into the template's eyebrow node, heading into the <h1>, each CTA's text+href, the authored <picture> into the media slot. The decorated DOM ships byte-equal to the prototype, so the segmentation-bug class (#48/#52/#56/#76) cannot occur. Editors still own every line of copy — the content page is unchanged and server-rendered (this is NOT client-injected chrome; #86 doesn't bite). Structure edits need a developer: the right trade for sections whose structure nobody edits.
• Reconstructive (authorable structure). For repeating/data sections where authors add/remove units (cards, FAQs, listings, menus): classify + segment defensively per #48/#50/#52 — and let the schema + round-trip gate carry the burden of proof.

Record the tier per block in the conversion log. Default: template-slotted for bespoke one-offs, reconstructive for repeat groups.

Record two more things per section in the schema (D1/D11 + forward-compat): sections triaged to default content in Step 2 carry "defaultContent": true (the encode side emits prose, not a table — the lint flags a block wrapping bare default content); and every block's authored shape must be expressible as one of the three component-model shapes — simple (one property per row), key-value (config), or container (own rows + one row per child) — so a later Universal Editor adoption needs no content migration (see aem.live "component model definitions"). A shape that fits none of the three is a signal the model is wrong, not that a fourth shape is needed.

3. Foundation

Rebrand styles/styles.css — replace the boilerplate's DEMO layer (roboto tokens, demo type scale, demo button colors) while preserving its STRUCTURAL layer verbatim: the body { display: none } / body.appear { display: block } gate (the runtime adds appear — removing the gate is not a fix for a blank harness render, loading the real scripts.js is), the header { height: var(--nav-height) } + header .header { visibility: hidden } → [data-block-status="loaded"] chrome reservation, and the main > .section scaffold. What you author:

• Lift :root tokens verbatim from the prototype's <style> (colors, fonts, type scale, weights, tracking, layout, motion easing).
• Document reset (box-sizing, margin reset, scroll-behavior, body font + bg, ::selection, img defaults, button reset). The img reset MUST be img { display: block; max-width: 100%; height: auto; } (#36). EDS's media pipeline emits <img> with width/height attributes; without height: auto a width constraint stretches the image vertically (a landscape 1920×1258 rendered 677×1258). The bug is invisible on the prototype (raw <img>, no attrs) — it only appears post-pipeline.
• The section scaffold: keep the boilerplate's main > .section padding/margin rules, retuned to the prototype's rhythm. Undecorated-content hiding is the RUNTIME's job (data-section-status + the body gate) — do not add display: none rules for sections or main > div.
• Section style values for default-content sections (D1). Each style value used by a default-content section gets its rule here — a SMALL closed set (main .section.dark { … }, .tinted, …), typography/ground only. On current sites the pipeline renders these classes server-side (section-metadata style → classes on the section div; other keys → data-*; the metadata block itself is removed from served HTML — sites with rendering version ≥ 2 / created after 2026-05). Blocks still paint their own sections; this vocabulary exists ONLY so prose sections don't need blocks.
• A global button system (see next section). This is the one place per-block CSS does NOT own its paint — buttons are site-wide and convention-driven.
• Reserve the header's real height — or the late chrome load shifts the first section → CLS (#81). The header block loads in loadLazy, AFTER first paint. In the common layout where the header sits in flow ABOVE the first section (full-bleed hero below the nav), the hero would render at y=0, then jump DOWN by the header's height when the nav lands — a large layout shift the browser attributes to the hero block (a real page measured CLS 0.143, ~0.13 of it the hero; metric-matched fonts do NOT fix it because the cause is the header box appearing, not a font swap). The boilerplate reserves this natively — header { height: var(--nav-height) } plus header .header { visibility: hidden } until [data-block-status="loaded"] — so the job is to make the reservation MATCH your chrome: set --nav-height (responsive, per breakpoint) to the prototype header's real rendered height, and give the bare <header> the chrome's own background so any reserve-vs-actual delta is invisible:

  :root { --nav-height: 98px; }                                       /* desktop nav+banner height */
  header { background: var(--brand-ground); }
  @media (width <= 767px) { :root { --nav-height: 102px; } }
  @media (width <= 480px) { :root { --nav-height: 120px; } }          /* banner wraps to 2 lines */
  

  Make the header's height deterministic so the reserved value actually matches: keep the reservation breakpoints in sync with the header block's, and avoid nav-link wrap zones (e.g. extend the burger/hamburger breakpoint so the inline links can't wrap to a second row at awkward widths). A multi-row chrome (utility bar + nav) is taller than the stock 64px — measure it, don't keep the default. Reserve slightly OVER the natural height (a few px) so you never under-reserve and shift. The footer needs NO reservation — it's below the fold, so its late load shifts nothing above it. Verify with a CLS probe (Playwright PerformanceObserver({type:'layout-shift'})) that delays the woff2/nav fetches to reproduce the slow-network swap PSI measures — run it against the DEPLOYED preview URL only (#101): local assets load instantly, so a harness run hides the shift and false-passes.
• The hero must eager-load its LCP image AND reserve its media slot (#100). The metadata block leaves the page's FIRST section empty, so the runtime's loadSection(main.querySelector('.section'), waitForFirstImage) eager-izes NOTHING — the hero's pipeline-emitted <img loading="lazy"> stays lazy. And a hero image styled width: auto (contain-in-a-max-height layouts) has a zero-height box until it loads, so the hero grows by the image's full height when it lands, shifting every section below (a real page measured CLS 0.134 attributed to the section under the hero). Both halves in the hero block: decorate() sets loading="eager" + fetchpriority="high" on its first <img>, and the CSS reserves the media slot (min-height on the figure per breakpoint, or an explicit aspect-ratio). Run the CLS probe ONLY against the DEPLOYED preview URL (#101) — harness images are local and instant, so the harness measures ~0 while the live page shifts (this exact false-pass shipped once); a local CLS number carries no information either way.

That's it. No motion primitives. No utility classes beyond the button system. Section style values stay the small closed set above — never a parallel styling system for block-owned sections (see anti-pattern 2).

scripts/scripts.js stays stock except the project-owned hooks: buildAutoBlocks() gains the site's D1 auto-blocks (embed/video URLs); decorateMain()/loadEager are never restructured. No reveal-on-scroll. No marquee init. No header scroll-state. Per-block animation is owned by per-block CSS.

Token-completeness gate — every var(--x) a block references MUST be defined in :root (#91). Lifting a section's CSS into a block routinely drags in a token the block author never added to the foundation (var(--navy-700) in a gradient, var(--accent-2) in a hover). A referenced-but-undefined custom property silently invalidates the WHOLE declaration — background: linear-gradient(var(--navy) 0%, var(--navy-700) 100%) with --navy-700 undefined drops the entire background and the element falls back (a navy card renders light), with no error and no lint flag. Gate it mechanically after the foundation and before deploy:

comm -23 <(grep -rhoE 'var\(--[a-z0-9-]+\)' blocks/**/*.css | sed 's/var(//;s/)//' | sort -u) \
        <(grep -oE '\--[a-z0-9-]+' styles/styles.css | sort -u)   # MUST be empty

Any line printed is a token a block uses that :root doesn't define — add it to the foundation :root.

Favicon — ship the site's icon (the ONE permitted head.html addition). Extract captures the source site's favicon at stardust/current/assets/favicon.<ext>; the deployed EDS site must serve it:

1. Copy it to the repo root as favicon.<ext>, preserving the format. A favicon.ico is served automatically at /favicon.ico — nothing else needed.
2. When the format is NOT .ico (svg/png), add exactly ONE line to head.html: <link rel="icon" href="/favicon.<ext>">. This favicon link is the only head.html edit this skill ever makes — the font ban (Step 4, anti-pattern #10) stands untouched.
3. Sandboxed/app runs (the _eds/ bundle contract): write the file to _eds/code/favicon.<ext> instead — the host publisher pushes it with the code tree and injects the head.html link deterministically.

If extract captured no favicon, skip this step — never invent one.

4. Self-host fonts and minimize CLS — never put font loads in head.html

Four principles, applied in this order on every project:

0. Ship an @font-face for EVERY named family — not just the body face (#65). Prototypes name a display face AND a body face (--display: "Hebden Incised", …; --body: "Lekton", …). If you self-host only the body font, every heading/numeral/title whose stack names the un-shipped display family silently falls back to Times New Roman/Arial (generic serif/sans) — invisible to size/color checks (the glyphs differ but the metrics match; only the FONT MISMATCH probe flag #66 or an eyeball catches it). Distinct from #11/#22 (wrong weight) and #30 (opsz): here the family is NAMED but NEVER SHIPPED. For each quoted family in --display/--body/any heading stack, self-host a matching @font-face (download + commit the woff2 under fonts/, reference root-relative — never the prototype's brand-CDN origin, #44). Checklist: grep every quoted family in styles.css's font stacks against the @font-face { font-family } names declared — any unmatched name is a silent fallback.

Then four principles, applied in this order on every project:

1. Leave head.html untouched. No font lines, period. No Google Fonts <link>. No CDN <link rel="stylesheet"> for type. No <style> blocks declaring @font-face. No <link rel="preload" as="font"> either — even self-hosted preloads belong out of head.html. Brand @font-face declarations live in styles/fonts.css (the file loadFonts() loads — eagerly on desktop and repeat views via the fonts-loaded session flag, always in loadLazy); the metric-matched -fallback faces live in styles/styles.css (they must be available at first paint). The fallback split (principle 3) eliminates the CLS that preloading is normally meant to prevent.

2. Self-host EVERY brand face — including proprietary ones — and emit a licensing alert (#80). Inspect the prototype to identify each font family and its license:

• SIL OFL 1.1 (Inter, JetBrains Mono, Fraunces, Roboto, Open Sans, IBM Plex, Source Sans, etc.) → self-host. License permits redistribution, including embedding on the served domain.
• Apache 2.0 (some Google Fonts) → self-host.
• Proprietary commercial (Pangram Pangram, Adobe Fonts / Typekit, Monotype, foundry-direct) → self-host anyway for fidelity, BUT raise a LICENSING ALERT (#80). The DEFAULT is brand-faithful: a converted/presales page that silently degrades the brand display face to Arial reads as broken to the client (this is exactly what a stakeholder notices first). So lift the prototype's actual webfonts — if the prototype ships .otf/.ttf (claude-design/stardust prototypes usually do, under assets/fonts/), convert them to latin woff2 with fontTools (f.flavor='woff2'; f.save(...), ~30–60 KB each) and declare them in styles/fonts.css exactly like an OFL face. Because they're proprietary you MUST surface the licensing obligation in THREE places so it can't ship unnoticed:
  1. a banner comment at the top of styles/styles.css (⚠️ FONT LICENSING REQUIRED BEFORE GOING LIVE + foundry per family + "do not publish to aem.live until the webfont/embedding license is confirmed");
  2. a fonts/LICENSING.md file (table: file → family → foundry → status, plus the remove-and-fall-back instructions);
  3. the conversion log, AND your hand-off message to the user. Document the remove path: if licensing can't be confirmed, delete the .woff2 + their @font-face rules and the stacks fall back to the metric-matched system fallback (principle 3/4). This is the inverse of the old "keep CDN / accept Arial" guidance — prefer fidelity + a loud alert over a silent generic fallback. (Only keep a CDN load when the prototype itself loads from an Adobe/Typekit CDN AND you cannot obtain the font files — then document the CDN coupling + CLS cost.)

For OFL fonts, fetch latin-subset variable woff2 files. The fastest reliable source is jsDelivr's @fontsource-variable/<name> packages:

mkdir -p fonts
curl -sSL -o fonts/<name>-variable.woff2 \
  "https://cdn.jsdelivr.net/npm/@fontsource-variable/<name>@latest/files/<name>-latin-wght-normal.woff2"
# italic, if used:
curl -sSL -o fonts/<name>-italic-variable.woff2 \
  "https://cdn.jsdelivr.net/npm/@fontsource-variable/<name>@latest/files/<name>-latin-wght-italic.woff2"

Latin-only variable woff2 is typically 30–60 KB per file, weights 100–900 included.

Match the axes the prototype loads — incl. optical size (#30). Check the prototype's Google Fonts <link> URL. If it requests an opsz (optical-size) axis — e.g. Source+Serif+4:opsz,wght@8..60,400;… — the default @fontsource-variable/<name> file (<name>-latin-wght-normal.woff2) is wght-only (one fixed optical master) and headings will render subtly off (heavier/different letterforms at large sizes). Fetch the opsz file instead (carries both wght + opsz, ~2× the bytes); font-optical-sizing: auto (the CSS default) then tracks the size:

curl -sSL -o fonts/<name>-opsz.woff2 \
  "https://cdn.jsdelivr.net/npm/@fontsource-variable/<name>@latest/files/<name>-latin-opsz-normal.woff2"

More generally: self-host the variant whose axes match what the prototype loaded (wght-only vs opsz; italic if used).

Non-variable fonts (#11). Many Google fonts ship only as named static weights — no variable axis (e.g. Barlow, Barlow Condensed, Anton). For these, @fontsource-variable/<name> does NOT exist; use the static @fontsource/<name> package and fetch each weight you actually use:

curl -sSL -o fonts/<name>-700.woff2 \
  "https://cdn.jsdelivr.net/npm/@fontsource/<name>@latest/files/<name>-latin-700-normal.woff2"

Static @fontsource packages also do not publish a "Fallback" @font-face, so you must compute the metric-override values yourself (principle 3) from the woff2 with fonttools:

from fontTools.ttLib import TTFont
f = TTFont("fonts/<name>-400.woff2"); upm=f['head'].unitsPerEm; hhea=f['hhea']; os2=f['OS/2']
arial = dict(upm=2048, xavg=904)  # Arial reference (use Times metrics for a serif brand)
size_adjust = (os2.xAvgCharWidth/upm) / (arial['xavg']/arial['upm'])
adj = upm*size_adjust
print(f"size-adjust:{size_adjust*100:.2f}% ascent-override:{hhea.ascent/adj*100:.2f}% "
      f"descent-override:{abs(hhea.descent)/adj*100:.2f}% line-gap-override:{hhea.lineGap/adj*100:.2f}%")

Apply those to the <brand>-fallback @font-face (sourcing local("Arial") / local("Times New Roman")) exactly as in principle 3.

3. Deferred fonts.css with a metric-matched -fallback @font-face — the stock boilerplate mechanism, aimed at your brand. The brand font must NOT render at first paint — and under vanilla EDS it can't: the brand @font-face lives in styles/fonts.css, which loadFonts() loads after first paint (immediately on desktop/repeat views, in loadLazy otherwise). Until it lands, the stack's SECOND family renders — so make that second family a metric-matched local face, declared in styles/styles.css following the boilerplate's own roboto-fallback convention:

/* styles/fonts.css — loaded by loadFonts(), NOT parsed at first paint */
@font-face {
  font-family: "<Brand>";
  src: url("../fonts/<brand>-variable.woff2") format("woff2");
  font-weight: 100 900;
  font-display: swap;
}

/* styles/styles.css — available at first paint. A local system face
   re-declared with the BRAND font's metrics, named <brand>-fallback
   (the stock convention — see roboto-fallback in the boilerplate). */
@font-face {
  font-family: "<brand>-fallback";
  src: local("Arial");           /* local("Times New Roman") for a serif brand */
  size-adjust: <X>%;
  ascent-override: <Y>%;
  descent-override: <Z>%;
  line-gap-override: 0%;
}

:root {
  --body-font-family: "<Brand>", "<brand>-fallback", sans-serif;
}

body { font-family: var(--body-font-family); }

Every font stack that names the brand face MUST name its -fallback face second — the fallback does nothing from :root alone; it works per-stack.

Keep the body { display: none } / body.appear gate — it belongs to the runtime, not the foundation (#40). loadEager() adds appear right after decorateMain(), so on any real page (and any harness that loads the real scripts/scripts.js) the gate is satisfied before first paint. A blank OFF-pipeline render means the runtime never booted — the harness didn't load scripts.js, or it threw — fix the harness, never remove the gate. (The qa-gate runtime-booted check + the deployed computed-style guard are the backstops for a blank render.)

The metric-override values come from the @fontsource-variable/<name> package's published calibration — fetch their CSS:

curl -s "https://cdn.jsdelivr.net/npm/@fontsource-variable/<name>@latest/index.css" \
  | grep -A 6 "Fallback"

Each fontsource package publishes a <Name> Fallback @font-face with size-adjust, ascent-override, and descent-override values. Lift those three numbers verbatim into the <brand>-fallback face (whose src is local("Arial") / local("Times New Roman") / local("Courier New") per classification).

The CLS chain that results:

• Initial paint: fonts.css hasn't loaded, so "<Brand>" is an unknown family and the stack falls through to "<brand>-fallback" — the metric-adjusted local system face. Line box already matches the brand font's metrics.
• loadFonts() lands fonts.css: the brand woff2 starts fetching; the fallback keeps rendering with matching metrics. Zero shift.
• Brand font loads: swaps in (font-display: swap). Zero shift because metrics already match.

4. Match the fallback family to the brand font's classification. Use the SAME class of typeface for the fallback so visual rhythm is preserved during the load:

• Sans-serif brand → <brand>-fallback sources local("Arial"); stack ends sans-serif.
• Serif brand → <brand>-fallback sources local("Times New Roman"); stack ends serif.
• Monospace brand → <brand>-fallback sources local("Courier New"); stack ends monospace. (Note: skipping monospace metric-matching is acceptable when the mono font is only used in small eyebrows/labels — CLS impact is negligible. Document the choice in the conversion log.)

Never substitute classifications (don't match a serif brand to Arial; don't match a sans brand to Times). Even with metric overrides, character widths and rhythm differ enough that the visible shift is jarring.

Classification includes WIDTH — a condensed/narrow display face needs a condensed fallback, never plain Arial (#80). "Sans→Arial" is only right for a normal-width sans. A narrow/condensed display face (PP Formula Narrow, Bebas Neue, Oswald, Barlow/Archivo Condensed, Anton) falling back to plain Arial is a width-class mismatch: Arial runs ~15–20% wider with different letterforms, so headings lose the condensed character and wrap differently — a silent divergence the eye catches even when sizes/weights/tracking match exactly (a CardValet pass shipped PP Formula→Arial; the width probe showed Arial 975 vs PP Formula 839 for the same H1 string). When the condensed brand face is self-hosted (principle 2, now the default) this only bites if the webfont is blocked, but the fallback must STILL preserve width: put a condensed system/free face ahead of arial in the stack — "<Brand>", "Arial Narrow", arial, sans-serif (system Arial Narrow is present on macOS/Windows but NOT Android/Linux, so for guaranteed coverage self-host a free OFL condensed analog — Oswald / Barlow Semi Condensed / Archivo Narrow). Same logic for an extended/wide brand face. Quick check during foundation: for every --*-font-family token whose first face is condensed, confirm the final non-sans-serif fallback is also condensed.

Self-host the prototype's INTENDED fallback, not its accidental system render — and verify with a width probe, never document.fonts.check (#77). Prototypes routinely load zero @font-face and name a proprietary brand font first (--display: "Bellfort", "Bebas Neue", system-ui). On any machine missing the brand font the prototype silently renders system-ui — so its on-screen display face is an accident of the viewing machine, not the design intent. Do NOT match that accident (don't set EDS --display to system-ui because "that's what the proto shows"). The prototype's OWN stack documents the intent: self-host the first redistributable fallback (OFL/Apache — e.g. Bebas Neue) so EDS ships the condensed display face the design wants; keep proprietary families documented in the conversion log. Verify what actually rendered with a width probe — document.fonts.check('24px "X"') returns true for any family name the page references, installed or not, so it produces false "fonts match" reads. Instead measure: a span at font-family:"X",monospace whose width equals a known-absent name's width means X fell back (absent); a distinct width means X is really rendering. (A beermaker pass set --display to Bebas Neue via a fonts.check false-positive — the width probe later showed the proto actually renders system-ui, but Bebas Neue was still correct as the documented intended fallback.)

Multiple display families (#12). A brand may use several families — e.g. Barlow (body) + Barlow Condensed + Barlow Semi Condensed (display). All of them load late via fonts.css, so each family whose swap matters needs its own metric-matched -fallback; a stack without one falls back with the wrong metrics and shifts. Define each as a :root token (--font-cond, --font-semi) and reference it per-block on the elements that use it. Fully metric-matching every display family is optional polish — for display text used sparingly (eyebrows, big condensed headings) the CLS impact is small; document the trade-off in the conversion log rather than over-engineering it. But when a display family is used in an ABOVE-THE-FOLD heading (the hero <h1>, an LCP title), metric-match it too — compute its size-adjust/ascent-override/descent-override from the woff2 (the same fonttools recipe as #11) and put its dedicated fallback SECOND in that family's stack: --hero: "Lilita One", "lilita-one-fallback", …. The fallback family MUST have its own name — do NOT reuse the body face's -fallback (#11), since that carries the body font's metrics, not the display font's. (Note: in practice the dominant first-section CLS is usually the late header box, #81, not the display-font swap — fix the header reservation first, then metric-match above-fold display faces to zero the remainder.)

Match the prototype's effective weight (#22). A single-weight display font (e.g. Anton, ships only 400) often appears bolder in the prototype than its one weight: a bare <h1>/<h2> inherits the browser-default heading weight (700), and the browser faux-bolds the 400-only face. If your foundation sets h1,h2,h3 { font-weight: 400 }, headings render visibly lighter than the prototype. Set the weight the prototype actually shows (often 700) so the faux-bold matches — don't assume "one weight in the file ⇒ font-weight: 400".

5. Lean on EDS button conventions — DO NOT manufacture button anchors in block JS

The boilerplate's decorateButtons() (in scripts/scripts.js) applies button classes when authors wrap a link in inline emphasis (D6). It runs in decorateMain(), BEFORE any block's decorate() — so by the time block JS sees a cell, its anchors already carry the button classes; block JS just clones them as-is.

Author markup → auto-applied class (current adobe/aem-boilerplate main — confirm per target in runtime-contract.json, older clones differ):

Author markup	Class applied	Visual
<strong><a>	a.button.primary, parent p.button-wrapper	brand fill
<em><a>	a.button.secondary, parent p.button-wrapper	transparent + outline (color-aware)
<em><strong><a>	a.button.accent, parent p.button-wrapper	high-impact CTA — sparingly
bare <a> alone in a <p>	nothing (current main requires emphasis)	plain link

Two decode caveats: the decorator only matches p a[href] — a CTA must be paragraph-wrapped and alone in its paragraph (the ENCODE side already does this); and it REPLACES the emphasis tag with the classed anchor, so block JS must never assume a surviving <strong>/<em> wrapper — detect CTAs by a.button first, emphasis-wrapped <a> as the fallback for un-decorated shapes.

Restyle the boilerplate's button rules in styles/styles.css (keep its selectors, replace the demo paint with the brand system):

a.button:any-link, button.button {
  display: inline-flex;
  align-items: center;
  gap: 10px;
  padding: 16px 26px;
  font-size: 12px;
  font-weight: var(--weight-bold);
  letter-spacing: 0.08em;
  text-transform: uppercase;
  border: 1px solid transparent;
  transition: background 0.25s var(--ease-out), color 0.25s var(--ease-out), border-color 0.25s var(--ease-out);
}

a.button.primary { background: var(--color-wavelength); color: var(--color-ink-rich); border-color: var(--color-wavelength); }
a.button.primary:hover { background: var(--color-canvas); border-color: var(--color-canvas); }

a.button.secondary { background: transparent; color: currentcolor; border-color: rgb(255 255 255 / 40%); }
a.button.secondary:hover { border-color: currentcolor; background: rgb(255 255 255 / 5%); }

/* On light surfaces, secondary uses dark-tinted outline. List the dark sections explicitly. */
main .section:not(.dark, .closing, .hero, .team) a.button.secondary { border-color: var(--color-rule-strong); color: var(--color-ink-rich); }
main .section:not(.dark, .closing, .hero, .team) a.button.secondary:hover { border-color: var(--color-ink-rich); }

/* Trailing arrow on primary/accent. */
a.button.primary::after, a.button.accent::after { content: "→"; font-weight: 600; transition: transform 0.3s var(--ease-out); }
a.button.primary:hover::after, a.button.accent:hover::after { transform: translateX(4px); }

p.button-wrapper { display: inline-flex; flex-wrap: wrap; gap: 16px; align-items: center; margin: 0; }

(Adjacent CTAs land in separate p.button-wrappers — one per authored paragraph — so group spacing rides the wrappers' shared flex row inside the block's .actions container, not a single group element.)

Surface-aware variants: scope to the BLOCK class, not just the section (#41). When a button/link/text treatment differs on dark vs light surfaces, the prototype's dark-surface cue (e.g. .hero, .cta-dark) becomes a block class after conversion — a <div class="hero block"> nested inside the <div class="section">. So an override written as main .section.hero a.button.secondary never matches (the .hero is one level below .section), and the on-dark CTA silently renders dark-on-dark. Scope on-dark overrides to BOTH: main .section.dark a.button.secondary, main .hero a.button.secondary { … }. QA any block on a dark background for secondary/ghost-CTA contrast (light outline + light text) — the button "exists" in metrics, so only contrast/eyeball catches this.

Block JS pattern — just clone the cell:

// Get the cell that holds the CTAs
const ctaCell = rows[N]?.firstElementChild;
if (ctaCell && ctaCell.querySelector('a')) {
  const actions = document.createElement('div');
  actions.className = 'actions';
  [...ctaCell.childNodes].forEach((n) => actions.append(n.cloneNode(true)));
  container.append(actions);
}

DO NOT manufacture anchors with cta.className = 'btn-loud' or inject custom SVG arrows. The global ::after arrow + the convention's class system handle 95% of cases.

Block CSS pattern — only override what's actually different:

The closing block's CTA is slightly larger than the global default. That's a legitimate override:

.closing .actions a.button.primary { padding: 22px 32px; font-size: 13px; }

Three lines. Targets the global class, not a custom one. This is the entire "blocks slightly augment defaults" pattern.

When NOT to use the convention:

Some links are NOT buttons. Examples:

• A wavelength-underlined text link in a section footer ("How we work →"). It's a styled text link, not a chip.
• Whole-card anchors on tile grids (<a class="tile">…</a>). The whole tile is the click target.
• Channel values in a closing CTA (<a href="tel:…">801-363-0101</a>). It's a value, not a CTA.
• mailto: / tel: links inside prose.

For these: the author leaves the <a> as a plain anchor in content (no <strong> / <em> wrap), and the owning block styles it with per-block CSS. The convention is for buttons; if it's not a button, don't apply it.

Multi-variant button systems (#25). The strong/em convention only names three slots (primary / secondary / accent — and D6 says needing more usually means a design-system decision was wrongly delegated to authors, so first try to consolidate). When a prototype genuinely has more context-specific variants — e.g. JFK's .btn--accent (yellow), .btn--primary (blue), .btn--ghost (outline), .btn--onblue (white-on-blue) — author emphasis can't express them. Don't force it: lift the prototype's full button-variant system into styles/styles.css (keeping the prototype's own class names), author the CTAs as plain <a> in content, and have each block apply the right variant class to the cloned anchor (the block knows its section's variant — the choice stays with the design system, not the author). This is the same "if it doesn't fit, style it" escape hatch, applied at the button-system level rather than per-link.

6. Chrome — authored /nav + /footer documents, template-slotted header/footer blocks

Chrome is the canonical fragment use case (D12): content lives in two authored DA documents — content/nav.html and content/footer.html — and presentation lives in the per-site blocks/header and blocks/footer CSS/JS. The stock blocks fetch the documents (loadFragment('/nav') / loadFragment('/footer'), path overridable per page via nav/footer metadata); you replace their demo CSS/JS with the prototype's chrome. Nav links become authorable; block JS runs, so interactive chrome is REAL JS, not CSS hacks.

The nav/footer documents (ENCODE side). Same body-fragment format as any content page (Step 9), deployed and published through the same chain — they must be on the publish roster or the chrome 404s. Content is default-content only, structured by sections:

• content/nav.html: section 1 = brand (logo link), section 2 = the nav link list (<ul>), section 3 = tools/CTAs (the stock header block reads exactly these three sections into .nav-brand / .nav-sections / .nav-tools — keep that contract so the hamburger logic keeps working).
• Nav DECODE: the pipeline wraps each list item's trigger link in a <p> on live (#98). The authored/harness shape is <li><a>…<ul>, the delivered shape is <li><p><a></p><ul> — a :scope > a trigger lookup and any .nav-links > li > a CSS silently miss on live while the harness passes (the #79 class, hitting chrome). Normalize in decorate(): match :scope > a, :scope > p > a and unwrap the <p>. Verify the desktop nav's STYLED render on the deployed preview, not just the harness.
• content/footer.html: one section per footer band (link columns as lists, legal line, social links). The footer block renders them in order.
• Images (logo) follow the standard editorial-image rule: upload to DA /media, author a content.da.live <img> — the pipeline emits <picture>. Internal links root-relative; external fully-qualified (D4).

The header/footer blocks (DECODE side) — template-slotted (#95), pixel parity by construction. Replace the demo CSS of blocks/header/header.css with the prototype's chrome CSS (scoped under header .nav-* / footer .footer), and adapt header.js's decorate() to build the prototype's chrome DOM verbatim, slotting the authored content by role — logo into the brand slot, each authored <li> link into the nav-link template, tools/CTAs into their slot. KEEP the stock block's interaction machinery (hamburger toggleMenu, aria-expanded, escape/focus-out close, the isDesktop media-query switch) and restyle it — it is accessible, tested JS; the prototype's own menu script is only a visual reference.

• Lift the chrome element's OWN box styles (#31) — margin, padding, border set on the prototype's <header>/<footer> element itself — onto header/footer (the host elements sit OUTSIDE <main>), not just the inner content styles. The gap between the last section and the footer comes entirely from the footer's own top margin (e.g. footer { margin-top: 72px }). Easy to miss: the inner content looks right while the footer sits flush against the last block.
• Root-class hook (#26): the block renders inside header .header / footer .footer. If the prototype's chrome styling is keyed to a different root class (e.g. .utilnav / .site-footer), have decorate() emit a <div class="<that-class>"> wrapper so the lifted CSS matches unchanged.
• Multi-row chrome (utility bar + nav): author the utility bar as an extra section in /nav; the header block slots it above the nav row. Update --nav-height (#81) to the combined height.

What still can't run (#20, #102): authored content never carries <script> (D15), and EDS's delivered CSP (script-src 'nonce-…' 'strict-dynamic') means inline on* handlers in ANY markup never fire. Forms in chrome (a newsletter signup in the footer) are wired in BLOCK JS: render the <form> from the block, attach a real submit listener in decorate(). Scroll-state chrome (sticky shadow, shrink-on-scroll) is now fine too — wire it in the header block's JS, honoring prefers-reduced-motion. Block dependencies must not compile WebAssembly (#102): the CSP has no wasm-unsafe-eval, so WASM-based players (dotlottie, wasm codecs/parsers) silently fall back on every REAL environment while working locally — for Lottie use lottie-web's pure-JS svg renderer via a pinned-CDN module import() (strict-dynamic trusts module imports). Step 10: check the deployed page's browser console for CSP violations — a graceful fallback hides this class from every layout gate.

Per-page chrome variants: set nav: /nav-minimal (or footer: /footer-legal) in the page's metadata block to point that page at an alternate authored document — this replaces the old header: off switch (there is no stock off switch; a chrome-less page points at a minimal nav doc you author). Multilingual sites route the same way: /fr/nav, /fr/footer.

7. Blocks (parallel agents)

Dispatch one agent per page-archetype cluster (utility pages, services, case studies, etc.). Each agent owns a non-overlapping set of new blocks and content pages. Three to four parallel agents is the sweet spot.

The brief template:

Per the project's locked direction: each prototype <section> becomes its own EDS block. Lift the prototype's <style> for that section verbatim, scope it under the block class (.block-name .x instead of section.x .y), and rebuild the prototype's DOM through a decorate(block) function that consumes EDS table-block input.

You own: prototypes [list], content pages [list], sections [list].

Existing blocks — REUSE, do not recreate: [list with one-line authoring shape per block].

Brand tokens are global in styles/styles.css; do not redefine.

Round-trip contract (#93/#94): the page's authored rows AND your block's decode are both written from stardust/eds-schema/<page>.json (roles + repeat units — Step 2b); cite the schema path in the block JSDoc. After writing each block, run node skills/deploy/scripts/block-roundtrip.mjs "<protoURL>" content/<page>.html --blocks <name> — the block is NOT done until it exits 0 (0 structural 🔴).

Section layout — reproduce the prototype's max-width container (#13): if the prototype section wraps its content in a centered max-width container (<div class="wrap"> / .container / .inner), your block MUST recreate it — build the content into a .wrap div (block.replaceChildren(wrap)), so the colored/section background bleeds full-width but the content stays within the page max-width. Only render content edge-to-edge where the prototype section itself is full-bleed (no inner wrapper). Getting this wrong is invisible at ≤1440px and only shows at wide viewports.

Images — <image-slot> placeholders (#2): claude-design prototypes use <image-slot> custom elements as image drop-targets; there are usually NO real image assets. Treat each image as an optional authored cell holding a <picture>/<img> (const pic = cell.querySelector('picture, img'); if (pic) …). When the cell is empty, fall back to the prototype's background treatment (e.g. dark --ink, or a placeholder rectangle) via the block CSS so the section still looks right with no image. Leave image cells EMPTY in the authoring snippet.

Scroll-reveal / JS-hidden content (#14): if the prototype hides content behind a class an inline <script> toggles on scroll (.reveal { opacity:0 } + an IntersectionObserver that adds .in), do NOT lift the opacity:0 — the prototype script does not run in EDS, so the content would be permanently invisible. Render it visible; drop the reveal (keep only hover/:hover transitions). Honor prefers-reduced-motion.

Interactive / component-driven sections (#17): when a section is driven by a component (state, a list loop like <sc-for>, conditionals like <sc-if>, {{ }} bindings, a data-count counter, a tab/selector), split it: data → authorable rows (one row per list item, with the item's fields as cells) and behavior → block JS. Unlike static fragments, block JS runs — so decorate() is the right place to wire click handlers, an IntersectionObserver count-up, tab switching, etc. Render the default/active state in markup; drive the rest from JS-held local state. {{ }}/<sc-for>/<sc-if> are NOT EDS syntax — read them as "loop these rows" / "show one state".

David's Model (the authored-structure contract — davids-model.md): a prose section with no repeating units and no bespoke structure is DEFAULT CONTENT, not a block (D1 — the Step-2 triage in the conversion log says which of your sections these are); no nested block tables (D2); blocks stay ≤4 columns (D10); if your section matches a Block Collection pattern the conversion log names, follow that block's authoring shape (D11); no code visible as text in cells (D15). Your pages must pass node skills/deploy/scripts/davids-model-lint.mjs content/<page>.html with 0 🔴.