Skills for building AEM Edge Delivery Services sites — site creation, block development, content modeling, code review, testing, and page import.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Append entries as ## YYYY-MM-DD — short title at the top. The date
indicates when the entry was written, not when the underlying rule
applies. When an entry stabilizes (it has held across multiple
inputs), promote it to architecture.md or eds-da-mechanics.md
as a verified fact, and link back here.
Categories to look for as the list grows:
Surfaced on: photoshop-features (run 010) — 7 CTA links with SVG chevrons.
When an <a> element contains both authorable text AND decorative
non-authorable content (inline SVG icons, glyph spans, pseudo-element
triggers), do NOT put data-slot on the <a>. The link writer replaces
innerHTML, destroying the decorative content.
Pattern to detect during Analyze (Phase 2):
Any <a> that is a slot candidate AND contains:
<svg> child elements<img> child elements (decorative icons, not the primary content)Fix: Wrap only the text portion in <span data-slot="...">, leaving
the decorative elements as siblings inside the <a>. The href stays
static in the template (not authorable). If href authoring is also
needed, use a separate attribute-level mechanism (not currently supported
by the slot writer).
Scope: This applies to ALL slot writer types that replace innerHTML,
not just links. Any element where writeSlot() would overwrite children
that include decorative template chrome is at risk. The link case is the
most common because CTAs frequently pair text with arrow/chevron icons.
The general rule: Before placing data-slot on ANY element, inspect
its children. If the element contains non-authorable siblings of the
authorable text (SVGs, decorative images, icon fonts), wrap only the
authorable portion and leave the rest as template chrome.
styles/fonts.css contaminates overlay pagesSurfaced on: ups-gb refresh (run 017) — visible font rendering divergence.
The AEM EDS boilerplate ships styles/fonts.css with Roboto and Roboto-Condensed
@font-face rules. The substrate's scripts.js loadFonts() loads this file
on every page, including overlay pages. The boilerplate's font declarations
were leaking into overlay rendering for any source that mentions Roboto in
its font-family fallback chain.
A source page like UPS UK declares:
body { font-family: "Roboto, Tahoma, Helvetica, Arial, sans-serif"; }…but does NOT load a Roboto webfont. The source intends system Tahoma fallback. The converted overlay page on EDS:
styles/fonts.css via scripts.js loadFonts()@font-face { font-family: roboto; src: url('../fonts/roboto-bold.woff2'); }font-family: Roboto, Tahoma, ... declaration now finds a real RobotoVisual outcome: font weights, x-heights, kerning, letter shapes all subtly differ from the source. The page LOOKS converted but doesn't feel 1:1.
The substrate now ships its own empty styles/fonts.css and the install
manifest replaces the boilerplate's version. Overlay pages render with the
source's declared fallback chain — no boilerplate-injected webfonts.
If a per-template needs a webfont (the source page DID load Roboto via
<link> or @font-face), declare it in that template's
/styles/<template>.css. The page CSS extraction in Phase 3 already
preserves source-side @font-face declarations.
After wiring, compare the source page's document.fonts set against the
converted page's document.fonts set (both via playwright-cli run-code).
If the converted page has additional loaded fonts that the source doesn't,
investigate — usually a sign of leaked boilerplate fonts or a webfont the
template CSS injected that wasn't in the source.
Pre-1.0.5 branches that were converted with the boilerplate's Roboto still
ship the leaky fonts.css. They'll be fixed automatically on next refresh
(substrate install at v1.0.5+ overwrites the file with the empty version).
For an immediate fix without refresh, empty out styles/fonts.css at the
branch level and push.
Surfaced on: polestar refresh (run 010) — <sup>¹</sup> footnote marker.
Source page has an inline element mid-sentence in a heading:
<h2 class="incentive__head">Not the status quo. Tesla owners receive $14,000.<sup>¹</sup></h2>The trap: A sub-agent looked at this and reasoned "the sup is structural, the text is content — give the author a slot for just the text and keep the sup as static template chrome." Result:
<!-- WRONG: sup outside the slot -->
<h2 class="incentive__head">
<span data-slot="head">Not the status quo. Tesla owners receive $14,000.</span>
<sup>¹</sup>
</h2>DA cell: Not the status quo. Tesla owners receive $14,000. (no sup).
This breaks two things:
.md representation is incomplete. Authors see the headline text
without the footnote marker. If they remove the footnote later, the
orphan sup is invisible to them — they can't clean it up.Mid-sentence inline elements are CONTENT, not chrome. Put them inside
the slot value. Use a single data-slot on the heading/paragraph element
itself, not a sub-<span>:
<!-- RIGHT: data-slot on the heading, sup inside -->
<h2 class="incentive__head" data-slot="head">Not the status quo. Tesla owners receive $14,000.<sup>¹</sup></h2>DA cell: Not the status quo. Tesla owners receive $14,000.<sup>¹</sup> —
visible and editable in the DA editor.
The EDS pipeline preserves the same semantic-inline set listed in the
2026-05-20 <span class="..."> entry below: <sup>, <sub>, <strong>,
<em>, <del>, <ins>, <mark>, <code>, <kbd>, anchors, images.
All of these belong inside the slot when they appear mid-sentence.
Rare, but possible:
<sup>
decorating the whole slot's content, not a fragment mid-sentence —
unusual).For everything mid-sentence, default to "inside the slot."
When constructing slot markers, scan the source heading/paragraph being
slotted. If it contains any inline elements from the preserved list AND
those elements sit between text runs (not wrapping the whole element),
put data-slot on the heading/paragraph itself and include the inline
elements in the slot value. Do NOT introduce a <span data-slot> that
excludes them.
<span class="..."> from DA cell contentSurfaced on: glossier refresh (run 008) — sale prices.
The EDS post-pipeline drops <span class="..."> wrappers — the tag
disappears and the class is lost, text content survives bare in the
parent. See da-content (Inline tags) for the preserve/rewrite/strip
behavior across inline tags.
Generator pages frequently use <span class="foo"> purely as styling hooks:
<p class="product-card__price">
<del>CHF 20.90</del>
<span class="product-card__price-now">CHF 14.63</span>
</p>.product-card__price-now { color: var(--color-sale-orange); }After DA round-trip, the live page renders as:
<p class="product-card__price">
<del>CHF 20.90</del>
CHF 14.63 <!-- span and its class are gone -->
</p>…and the CSS rule has nothing to match → sale price shows in default color.
When source CSS targets a <span class="..."> for styling and the span isn't
load-bearing semantically, choose ONE of:
CSS-only fix using structural selectors (preferred — no markup change):
Use :has(), sibling combinators, or :nth-child() to target the position
instead of the class. Example for the price pattern:
/* whole <p> orange when it contains a <del>; del rule overrides back grey */
.product-card__price:has(del) { color: var(--color-sale-orange); }
.product-card__price del { color: var(--color-fg-muted); }Swap <span> for a semantic element that survives the pipeline.
Per da-content the safest targets are tags in the
preserve list (<strong>, <em>, <u>, <del>, <code>,
<sub>, <sup>). Rewrite-target tags (<b>, <i>, <s>,
<mark>, <kbd>) work too but their wrapper tag changes on the
way out — page CSS must target the rewritten tag, not the source
one. Update the page CSS to target the element instead of the class:
<p><del>CHF 20.90</del> <strong>CHF 14.63</strong></p>.product-card__price strong {
color: var(--color-sale-orange);
font-weight: inherit; /* override default <strong> bold */
}When mapping CSS selectors to slot opportunities, flag any rule that targets
.<class> on a <span> and emit a decisions.json note. Then choose the
strategy above during Phase 3 (Generate).
data-slotA <span data-slot="..."> does survive — the substrate's writeSlot writes
text into it before DA serialization ever happens. The pipeline only strips
spans from the FINAL DA-stored content. Spans that are template-only
(populated at runtime by the overlay engine) are unaffected.
Don't flatten <del>X</del> <span>Y</span> to X → Y plain text in DA. The
arrow is a presentation artifact of the strikethrough rendering, not part of
the content. Storing → literally:
<del>)Keep <del> in the DA cell. Handle the sale-price color via CSS (option 1
above) or semantic-element swap (option 2). Branch fix: see
glossier-a styles/glossier.css .product-card__price:has(del) rule.
footer > .footer { visibility: hidden } leaks into fragment inner divsThe substrate lifecycle CSS uses footer > .footer { visibility: hidden } to hide
the EDS footer block wrapper until JS decoration completes. The selector is
footer > .footer — a direct-child combinator.
The leak: When a footer FRAGMENT uses <footer> as its root element (a
common pattern — the source page's <footer> tag is preserved verbatim in the
fragment), the DOM structure becomes:
<footer> <!-- EDS landmark -->
<div class="footer block"> <!-- EDS wrapper, matched by footer > .footer -->
<footer> <!-- fragment root, also a <footer> element -->
<div class="footer"> <!-- inner nav div, matched by footer > .footer ! -->The inner <div class="footer"> is a direct child of the fragment's <footer>
element. That <footer> element is itself a <footer> tag. So footer > .footer
ALSO matches the inner nav div, making it visibility: hidden permanently (it
has no data-block-status attribute to trigger the override rule).
Visual symptom: Footer navigation columns are invisible. The legal text / copyright
row (if not a .footer element) is visible. Structurally the DOM is complete.
Fix in page CSS: Add visibility: visible to the scoped inner-nav rule:
footer[data-section="footer"] > .footer {
visibility: visible; /* counteract substrate footer > .footer { visibility: hidden } */
...
}Substrate fix (recommended): Change the substrate rule from
footer > .footer { visibility: hidden } to
footer > .footer.block { visibility: hidden }.
The .block qualifier limits it to EDS block wrappers only, which is the intent.
Observed: polestar-a (footer nav entirely invisible without this fix).
writeSlot() heading-in-heading nesting creates empty DOM elementsWhen a DA cell value contains a heading element (<h2>text</h2>) and the
template slot target is also a heading (<h2 data-slot="title">), calling
el.innerHTML = value causes the browser's HTML parser to auto-close the
outer <h2> before opening the inner one. Result: an empty <h2> in the
rendered DOM, followed by the authored heading outside the template hierarchy.
Visual symptom: Empty <h2> elements appear in the DOM with no content.
Accessibility tree is polluted. Layout may shift.
Fix in writeSlot(): Detect when target is a heading element and value
contains a same-tag heading; unwrap inner heading content:
if (/^H[1-6]$/.test(el.tagName)) {
const tmp = document.createElement('div');
tmp.innerHTML = value;
const inner = tmp.querySelector(el.tagName.toLowerCase());
el.innerHTML = inner ? inner.innerHTML : value;
return;
}Observed: lovesac-a (4 empty headings in DOM from slot values that contained
<h2> elements as wrappers around the authored text).
The CSS class collision pattern from heathrow run-001 (phases/phased-expansion)
recurred 4 more times in the batch run. Pattern:
<section class="ugc-grid section"> (Glossier).ugc-grid { display: grid; grid-template-columns: repeat(3,1fr) }Affected pages and their collision classes:
| Page | Collision class | Fix |
|---|---|---|
| heathrow | phases | → phased-expansion |
| glossier | ugc-grid | → ugc |
| aman | audience-grid | → section (removed first-class) |
| lovesac | lifestyle-grid | → removed from section |
The rule MUST be enforced during the Analyze phase: For every candidate section first-class, grep the page CSS for that class name. If it appears as a CSS selector with layout properties (display, grid, flex, width, height, visibility), it CANNOT be the section first-class. Choose a different discriminator.
This is now the most common single source of post-conversion layout bugs. It should be added to the Generate phase self-check (step 3.9) as:
# 6) No section first-class appears as a CSS selector with layout properties
for cls in $(grep -oE 'class="[^"]+' output/templates/<tpl>.html \
| grep '<section' | awk '{print $1}'); do
grep -q "\.${cls}[[:space:]]*{" output/styles/<tpl>.css \
&& echo "COLLISION: $cls appears in CSS — rename section first-class"
donesection, header, footer { padding } leaks into EDS landmark <header>/<footer>Bug: A common pattern in source pages is to set section padding with a generic selector like:
section, header, footer { padding: var(--section-padding) var(--spacing-lg); }In the SOURCE page this is fine — the source's own <header>/<footer> use
specific class overrides (.promo-strip, .site-header) with class-level
padding that wins on specificity. But in the converted EDS page, the EDS
landmark <header> and <footer> elements have NO such overriding class —
they're just bare <header> / <footer> wrapping the fetched fragment. The
generic rule fires on them with full force, adding (typically) 128px+ of
vertical padding the source never had. The hero ends up pushed down ~200px.
Symptom: Hero / first-visible content sits much lower than in source. First-fold CTAs may end up below the viewport.
Substrate fix (in styles/styles.css):
body > header,
body > footer {
padding: 0;
margin: 0;
}Specificity (0,0,2) for body > header wins over plain header (0,0,1),
no !important needed. Only resets the EDS landmark wrappers — inner
fragment elements (.promo-strip, .site-header, .site-footer) keep
their own padding from page CSS unchanged.
Observed: frescopa-a refresh (hero pushed down 199px; CTAs below the fold).
writeSlot heading-in-heading nesting creates empty DOM elements [PROMOTED to substrate v1.0.3]When a DA cell value contains a heading element (<h2>text</h2>) and the
template slot target is also a heading (<h2 data-slot="title">), calling
el.innerHTML = value causes the browser's HTML parser to auto-close the
outer <h2> before opening the inner one. Result: an empty <h2> in the
rendered DOM, followed by the authored heading outside the template hierarchy.
Originally fixed at the branch level for lovesac-a (run 016). The fix lived
on the branch only — the substrate kept producing the bug on fresh runs.
Surfaced again on frescopa-a refresh (substrate v1.0.2 installed; empty h1
in hero). Now promoted to substrate v1.0.3 — writeSlot adds a heading
branch that unwraps the inner heading's innerHTML before assigning.
if (/^H[1-6]$/.test(tagName)) {
const tmp = document.createElement('div');
tmp.innerHTML = value;
const inner = tmp.querySelector(tagName.toLowerCase());
el.innerHTML = inner ? inner.innerHTML : value;
return;
}Lesson learned: branch-level patches don't survive snowflake refresh
(which resets the branch to vanilla main). If a fix is generic enough to
recur, promote to the substrate immediately — don't leave it on a single
branch. Refreshes are the canary that surfaces missed promotions.
writeSlot dispatch: background-image check must come before the <a> (link) checkBug: When a slot target is <a data-slot="X" style="background-image:url(...)">, the
writeSlot() function dispatches on tagName === 'A' (link branch) before reaching the
background-image branch. The link handler copies href + innerHTML from the DA cell, which
is an <img> element. This replaces the entire inner tile structure (label, CTA, etc.)
with just <img>, silently wiping all nested [data-slot] children.
Symptom: Section appears empty or loses inner content. Activity labels, card captions, tile CTAs all gone despite being present in the template and DA cells.
Fix (substrate writeSlot):
// Guard the <a> branch so background-image tiles fall through
if (tagName === 'A' && !(el.style && el.style.backgroundImage)) {
...link handler...
return;
}
// background-image branch now catches <a> tiles correctly
if (el.style && el.style.backgroundImage) { ... }Observed: patagonia-a (activity tile grid — 6 tiles with <a data-slot="tile-N.bg">).
The overlay engine's readBlockSlots keys slots by block.className.split(/\s+/)[0] from
the DA post-pipeline HTML. applySlotsToTemplate matches by
section.className.split(/\s+/)[0] from the template. If the source uses prefixed
class names (e.g. Lemonade's ds-hero, ds-valueprops), the DA block div's class must
carry that same prefix — not a stripped form like hero.
Concrete failure: DA block <div class="hero"> + template <section class="ds-hero"> →
no match → slots silently not applied, template defaults displayed for all slots in that section.
Fix: Derive DA block class names from the template section's actual first class, not
from the block's semantic label or the data-section attribute.
The DA pipeline validates SVG sizes when converting DA HTML to Markdown at POST preview
time. SVGs over ~40KB cause a 409 AEM_BACKEND_FETCH_FAILED with "Images N have failed
validation". This is enforced even for publicly-reachable images.
Asymmetry: Template/fragment HTML fetches SVGs via the browser directly — no size cap.
DA cell <img> SVG references go through Media Bus html2md conversion — 40KB cap applies.
Lemonade example sizes that failed: home-left (45KB), home-right (76KB), press logos (251KB), bundle card illustrations (81–158KB), pizza diagram (176KB).
Fix: Omit over-limit SVG image slots from the DA doc. The template default values display those images at runtime (browser fetches SVG directly from CDN, no cap). Only include DA image slots for SVGs under 40KB and for any PNG/WEBP/AVIF images.
Pre-flight check to add: During Analyze phase, for each image slot candidate, HEAD the URL and note content-length. Flag any SVG ≥ 40KB as "template-default-only" in decisions.json.
data-slot on a container that has nested data-slot childrenThe slot writer for every element type (<a>, <picture>, default
text) writes to the target's innerHTML (or replaces the element
entirely). When the target has nested [data-slot] children, those
markers and their content are destroyed before they can be processed.
Common failure: a card wraps icon + title + body in an
<a class="card-link" data-slot="card-N.link">, AND the inner
<h3>/<p>/<img> also carry data-slot. The link writer runs
first, sets innerHTML to the DA cell value (e.g.
<a href="#">Learn more</a>), and obliterates the inner slot markers.
The card renders as a bare label with no content.
The rule. For any element pattern where a container wraps multiple authorable children: slot the children individually, leave the container static. Conversely, if you want the whole block to be authorable as one chunk, don't slot its children. Never both.
Edge cases. An <a data-slot="cta">Learn more <img></a> (text
plus decorative icon, no nested data-slot) is fine — the icon is
lost on edit but that's acceptable for buttons. The trigger is
nested [data-slot], not "any inner content".
Substrate implications. The engine COULD detect this and warn (or skip the outer slot when inner data-slots exist). For now, this is a methodology-level rule applied during the Generate phase.
@font-face requires CORS headers on the font hostBrowsers strictly enforce CORS on @font-face url(…) requests,
unlike <img>, <script src>, <source src>, or CSS
url(image.jpg) references, which all work cross-origin without
explicit headers.
When a source page self-hosts fonts on a different origin from the served EDS page, every font URL produces:
Access to font at '…' from origin '…' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header…
Fonts then fall back to system-ui. For mainstream typefaces (Adobe Clean, Inter), the visual difference is subtle but noticeable.
Mitigation paths.
Access-Control-Allow-Origin: *
(or matching) on font responses./fonts/ directory (counts as
asset migration — out of methodology scope).@font-face with a font CDN that does send CORS headers
(Adobe Fonts kit, Google Fonts).about:error)EDS Media Bus, which optimises <img> URLs in DA-source HTML, only
handles absolute URLs. Root-relative paths
(/assets/section-2/card-image-1.png) are resolved against the DA
content host (content.da.live) where those paths don't exist — the
pipeline serves them as <img src="about:error"> and the browser
surfaces a console ERR_UNKNOWN_URL_SCHEME error.
Cards using a background-image slot writer end up with
style="background-image: url('about:error')" and render as black
tiles.
Fix. Use absolute URLs in DA cells. After re-upload, Media Bus
correctly fetches and optimises:
./media_<sha>.png?width=750&format=webply&optimize=medium.
The asymmetry that's easy to miss.
/assets/... — the BROWSER
resolves these against the rendered page host, which is the
code-bus host. Code-bus serves /assets/. Works fine.<img src=...> refs — the EDS PIPELINE (Media Bus)
resolves these. Media Bus resolves against the DA content host.
Doesn't work unless the URL is absolute to a publicly reachable
image source.Generic rule for DA cells with images. Always use absolute URLs. Common shapes that work:
https://<branch>--<repo>--<owner>.aem.page/assets/...https://<source-host>/assets/...https://content.da.live/<org>/<repo>/media_<sha>.../assets/ in the repo is a viable option for locally-hosted source pagesWhen the source URL is private/local-only, the cleanest alternative
to "skip production" is to copy the source's asset tree (or just the
referenced subset) into /assets/ at the repo root. Code-bus serves
them at the same paths the source used, so:
url(…) refs (e.g. @font-face) keep working same-origin.Trade-offs.
Steps that work.
cp -R <source-assets-dir> ./assets/.DS_Stores and unreferenced files.%20).sed pass to rewrite source-host URLs to root-relative
/assets/... in template/fragments/CSS/DA-output files.%20 (spaces in paths)When a source asset directory has spaces in its name, browsers
URL-encode them (e.g. Adobe%20Clean%20Display). The AEM CLI's
static-file middleware returns 404 for the encoded form even though
the file exists at the decoded path on disk.
Fix. Rename directories to remove spaces before committing.
Replace with PascalCase (AdobeCleanDisplay) or kebab-case
(adobe-clean-display), and update CSS url(…) refs to match.
When the source URL is on a private host (localhost, 127.0.0.1,
intranet IP), the production preview host cannot reach those assets.
Initial conversions that rewrite asset paths to absolute private
URLs will work locally but break on production.
Three forward paths when the source URL is local-only:
/assets/. Same paths work
locally and on production via code-bus. Caveat: binary assets in
git. Acceptable for one-off bespoke prototypes. DA cell image
refs still need absolute URLs (see Media Bus learning above)./media/. Cleaner long-term. Needs a
tool to walk asset references, upload via DA admin API to
/media/, rewrite paths in DA cells. Out of methodology scope.ngrok http 8080 for a one-off — anything that gives the
production preview host a reachable URL.Don't default to path #1 without asking. Vendoring is often ~30 minutes of mechanical work and gives a fully working production deploy. Surface the choice instead of silently scoping production out.
<div>, not <section> — rewrite to <section>The overlay engine's applySlotsToTemplate does
templateMain.querySelectorAll('section[class]') — so a <div>-shaped
hero would never match a block name from the DA doc.
Generic rule. In the Generate phase, when a logical section in
the source uses any tag OTHER than <section> (most common: hero
divs, nav wrappers, footer-like callouts), rewrite the outermost
element to <section class="originalClassListHere">. Keep the inner
DOM intact. The CSS continues to work because the original classes
carry through.
This complements the existing methodology rule about synthesizing
<main> when the source doesn't have one.
Source pages that use position: sticky hero with parallax plus
IntersectionObserver-driven .anim-enter fades break full-page
screenshots. A fullPage: true capture renders the page at its
top-of-scroll state — sticky positioning leaves visual gaps, and
.anim-enter elements stay at opacity: 0 because they were never
scrolled into view to trigger their observers.
What works. For each section, call
element.scrollIntoView({ block: 'start' }) followed by a 400–800ms
settle, then take a viewport screenshot.
Rule of thumb. If the source page uses position: sticky,
scroll-driven JS, IntersectionObserver, or any of the well-known
scroll-animation patterns, default to per-section viewport
screenshots in the Round-trip phase.
<main> wrapperThe overlay engine queries doc.body.querySelector('main') to extract
the template's main content — if the parser returns null, the engine
bails with console.warn('[overlay] template "X" has no <main>').
Some source pages omit <main> entirely, with top-level sections as
direct children of <body>, sandwiched between <header> and
<footer>. This is valid HTML5.
Generic rule. The Generate phase must wrap the body-level
sections in a synthesized <main> when the source doesn't already
have one. The <main> is not authored content; it's a contract
boundary between the overlay engine and the template.
data-sectionThe overlay engine matches DA block tables to template sections by
the template <section> element's first class
(section.className.split(' ')[0]). When the input contains multiple
<section class="section" ...> blocks (or any other shared first
class), they all collide on section.section selectors and the
engine can't tell them apart.
Generic rule. The Generate phase must ensure each template
<section>'s first class is unique within the template. When
the source's first class isn't unique, derive a unique first-class
from data-section (Stardust's stable discriminator) and reorder
so it's first in the class list. The original classes stay in the
list — CSS rules depending on them still apply.
Example:
- <section class="section" data-section="activity-tile-grid">
+ <section class="activity-tile-grid section" data-section="activity-tile-grid">Pattern observed across Stardust 0.2.0 outputs: when a generator
emits semantically distinct sections that happen to share a utility
class (section, card, tile, etc.), use the data-section (or
equivalent per-instance label) as the canonical unique identifier.
The DA admin source API has no merge semantics.
PUT /source/<org>/<repo>/<path>.html replaces the document
wholesale. If the user has made content edits in the DA editor
since the last upload, a PUT of your local copy silently discards
their edits.
Generic rule for any "edit local file → upload to DA" workflow.
A safer pattern for incremental updates: fetch the DA source first, modify in place (e.g., insert new slot rows but keep author-edited slot values), then PUT.
Static pages often use CSS-driven photos rather than <img> tags
— hero backdrops, tile/card "media" divs with
style="background-image:url(…)". None are authorable through a
slot writer that only knows <img>/<picture>/<a>.
Substrate addition in scripts/overlay-engine.js writeSlot(): when the
target element has a truthy el.style.backgroundImage, treat it as
a background-image slot. The DA cell carries an <img>; the engine
extracts the src and writes
el.style.backgroundImage = \url('${src}')``, preserving any other
inline styles. ~8 lines.
Template authoring: add data-slot to the existing background-
image-bearing element. No DOM restructuring required.
DA authoring: an <img src="…" alt="…"> in the cell. Authors get
DA's standard image picker.
Bonus: the EDS pipeline's Media Bus auto-rewrites <img> URLs
in DA cells to optimised references (e.g.
./media_<sha>.jpg?width=750&format=jpg&optimize=medium). The
engine writes that URL into background-image — so the overlay-
rendered page gets responsive, optimised images even when the source
markup is CSS-driven.
data-section is absent, derive first-class from a label or eyebrowNot every source has data-section attributes — hand-crafted pages
and non-Stardust generators won't. When multiple sections still share
a first class, derive a slug from the section's visible label
(the <p class="label"> or similar eyebrow typically present at the
top of every section in static-page designs):
<p class="label label--accent">About this consultation</p>
→ about-consultation becomes the first class<p class="label label--accent">A phased expansion</p>
→ phased-expansion becomes the first classDiscriminator hierarchy (in order):
data-section attribute (Stardust convention).id attribute on the section element.section-N.Some sources use absolute CDN URLs for their images
(https://investor.example.com/…, https://cdn.shopify.com/…).
These work unchanged in the overlay because absolute URLs resolve
identically from any host.
Other sources use relative paths (assets/photos/hero.jpg,
assets/logos/logo.png). These resolve against the serving host. On
the overlay-served URL (localhost:3000/drafts/<page>.html or
<branch>--<repo>--<owner>.aem.page/<da-root>/<page>), they 404
because the assets don't exist at the corresponding paths on the
serving host.
Generic rule for the Generate phase. Scan the source for relative
asset references (matches like ="assets/, url('assets/, etc., or
any non-http(s)/non-data: URL in src/href/url() positions).
Rewrite to absolute URLs pointing back to the source's host.
Asset migration is explicitly out of scope — link back to the
source's CDN/host for images, fonts, etc. If a future iteration wants
self-hosted assets, the DA /media/<site-slug>/ pattern is the
path. For now, "rewrite to source-absolute" keeps things simple.
The boilerplate styles/styles.css ships a visibility-lifecycle rule
for the empty header/footer placeholders:
/* before */
header .header,
footer .footer { visibility: hidden; }
header .header[data-block-status="loaded"],
footer .footer[data-block-status="loaded"] { visibility: visible; }The intent: hide the EDS block wrapper (the <div class="header block">
that's the direct child of <header>) until JS decoration flips
data-block-status to "loaded".
The bug: header .header is a DESCENDANT selector. It matches any
.header inside a <header>. If the fetched fragment contains its
own <header class="header"> (same class name), the descendant rule
matches and hides it. The override rule needs data-block-status on
the matched element, which the fragment-internal header doesn't
have → permanently hidden.
Substrate fix (in styles/styles.css): tighten to direct-child:
/* after */
header > .header,
footer > .footer { visibility: hidden; }
header > .header[data-block-status="loaded"],
footer > .footer[data-block-status="loaded"] { visibility: visible; }header > .header only matches the immediate .header child of
<header> — the EDS block wrapper. Fragment-internal
<header class="header"> or <footer class="footer"> are nested
deeper and escape.
Generic rule. When adding cascading CSS to the boilerplate
substrate that targets standard HTML element classes (.header,
.footer, .nav, etc.), prefer direct-child selectors. Fragment
markup is opaque to the substrate; you don't know what class names
authors will use inside.
EDS auto-loads /blocks/<blockname>/<blockname>.css for every
decorated block. The aem-boilerplate's blocks/header/header.css
(272 lines) and blocks/footer/footer.css define element-level
rules scoped to the BOILERPLATE's DA-authored nav markup:
/* from boilerplate blocks/header/header.css */
header nav { display: grid; ... margin: auto; ... }
header .nav-wrapper { ... position: fixed; ... }In the overlay model, blocks/header/header.js fetches a static
/fragments/<template>/header.html containing the source page's
real nav markup. The boilerplate's element-level selectors match the
fragment's <nav> elements too and cascade destructively (e.g.
display: grid killing flex-row layouts, margin: auto competing
with margin-left: auto on utility items).
Fix. Empty blocks/header/header.css and
blocks/footer/footer.css with a comment explaining why. Don't
keep them as dead-but-loaded files. For overlay-controlled pages,
ALL header/footer styling comes from /styles/<template>.css —
the source's inline <style> extracted faithfully.
Generic rule. When the overlay model takes over a block's behaviour by replacing its JS (as for header/footer), the matching boilerplate CSS becomes a hazard, not an asset. Empty it. If another block ever gets the same treatment, do the same.
<link> resources must be lifted into document.headIf the source <head> has <link> elements (Google Fonts
preconnects, external stylesheets, preload hints) that the mechanical
CSS extraction misses, fonts and other resources named in the
extracted inline <style> won't resolve. The browser falls back to
system-ui, which is visually similar to many design fonts but
distinctly not the same.
Substrate fix. scripts/overlay-engine.js applyTemplateOverlay lifts
any top-level <link> elements from the template file into
document.head (deduping by href+rel). Templates self-describe
their head-level resource needs.
Conversion-phase rule. When extracting head resources, capture
all <link> elements — not just stylesheets, also preconnects and
any preload hints. Put them at the top of the template file, above
<main>. They get picked up automatically.
This gap is easy to miss when the source's fonts happen to be system-installed on the developer's machine (e.g. Adobe Clean for users with Adobe apps installed). It only surfaces when a font nobody has locally needs to load.
If delayed.js always loads GSAP + ScrollTrigger + Lenis before
checking whether the page's template actually has an animation
engine, plain-HTML templates pay ~150 KB of motion libs downloaded
for nothing, plus a 404 on the missing engine script.
Fix in scripts/delayed.js. HEAD-probe
/scripts/<template>-animations.js before loading CDN deps. If the
probe 404s, skip everything silently.
Residual: the HEAD probe's own 404 still logs as a network error in
the browser console (cosmetic — page renders fine). A future polish
could use a <meta name="has-animations"> flag in the DA metadata
block instead of file-presence probing.
When the Generate-phase subagent prompt is just "read methodology.md + learnings.md + project docs, then produce template
This validates the "promote learnings to knowledge/, then a future agent reads them and doesn't re-make the mistake" model. Knowledge files act as durable, machine-readable memory for the substrate.
| Generator | Placeholder marker |
|---|---|
| Stardust 0.3.0 | <element data-placeholder="true"> attr + nested placeholder-eyebrow / placeholder-shape spans |
| Stardust 0.2.0 | <span class="placeholder-tag"> inline marker inside the containing element |
The Generate phase needs to detect which convention is in the input and tell the slot extractor what to skip. Both produce the same "static template content, not a slot" outcome — but the marker differs.
Generic rule. The Analyze phase should document the input's
placeholder convention in notes.md; the Generate subagent reads
that and applies the right skip pattern. Don't hardcode either
convention into methodology — sniff and pass.
<main>, not <footer>Empirically, a <footer><table>...</table></footer> in DA source is
ignored by the pipeline — zero <meta> tags emitted in the rendered
head beyond EDS-injected viewport / twitter:* defaults. The overlay
engine then bails (no <meta name="template"> → standard EDS
decoration falls through → one 404 per block trying to load
/blocks/<name>/<name>.{css,js}).
Snowflake emits metadata as <div class="metadata"> inside <main>.
Block format itself is covered by da-content (Page metadata).
Two things worth confirming about the DA admin source API:
PUT https://admin.da.live/source/{org}/{repo}/{path}.html with
multipart/form-data (field data) returns 200 plus a JSON
payload with the four canonical URLs (editUrl, contentUrl,
previewUrl, liveUrl). The Content-Type for the field is sniffed
from the data; passing type=text/html on the form part works.
What you PUT is what DA stores. Uploading a table-format doc
with <table> + <th> + <tr><td>slot</td><td>value</td></tr>
rows preserves the table shape byte-for-byte on GET. DA does not
normalize tables → divs server-side. The table → div conversion
happens only at pipeline render time (post-publish). The DA editor
presents the table view of source for authoring.
This contradicts the (implicit) assumption that "DA's editor
canonicalizes everything to divs on save." If a doc has been through
DA's prose editor (open + edit + save), it can come back in
div-format with <p> wrappers around cell contents — but that's an
editor-roundtrip artifact, not DA's storage behavior. Direct PUT
preserves source exactly.
Both models work in DA and produce valid post-pipeline EDS markup. The choice has author-UX and engine-design implications.
| Aspect | Slot-keyed | Positional |
|---|---|---|
| Row shape | slot-name | value (2 cells) | value only (1 cell) |
| Block id | <th>Hero</th> header row | <div class="hero"> class |
| Author UX | Sees slot names — clearer for partial edits | Sees just values — terser, EDS-native |
| Engine needs | Custom slot-resolution (overlay) | Standard EDS block decorators |
| Add/remove rows | Slots keyed by name; safe to add | Position-coupled; reordering changes meaning |
| Schema clarity | Slot names self-document fields | Schema is implicit in block JS |
The overlay engine + template [data-slot] markers lock in the
slot-keyed model. Positional is worth revisiting in a future
iteration to compare editor UX side-by-side.
Two specific gotchas worth flagging:
aem content push ≠ published. Drafts stage in DA's source
endpoints. To make a page reachable at aem.page, you must
POST admin.hlx.page/preview/{owner}/{repo}/{branch}/{path}.
For aem.live, POST admin.hlx.page/live/.... Either step
without the other looks like a successful push but produces a
404 at the public URL.
SVG cap is 40 KB. Tight enough that complex illustrations often exceed it. AI generators that emit SVG-heavy hero or decoration markup may push you into rejection. Sniff SVG sizes during the Analyze phase.
For image migration, prefer /media/<site-slug>/<filename> so
assets don't collide across projects. Same DA path → same Media Bus
content-addressed name across branches.
aem up) serves drafts content verbatimaem up --html-folder drafts does not run the EDS pipeline on
files served from the drafts folder. The DA-format <table> blocks
stay as tables, the <head> is not injected from head.html,
metadata-table → <meta> conversion doesn't happen.
Drafts is for raw post-pipeline content, not DA-shape content.
Implication. Every conversion needs a DA-to-post-pipeline
transformer step before drafts becomes usable locally. The
production .aem.page pipeline does run on DA-uploaded content
correctly — DA → pipeline is the normal flow. The local drafts
shortcut just bypasses it.
EDS's decorateSections queries main > div. Overlay templates use
main > section.<blockname> (and main > div.<wrapper> for
pin-spacer cases). Half of a template's main children are
<section> elements that EDS would ignore; the other half are
<div> wrappers that EDS would mistake for sections and re-wrap.
Either way, running standard EDS decoration on overlay-controlled main produces broken DOM.
Solution. The overlay sets main.dataset.overlay = templateName.
loadEager skips decorateMain / loadSection when the marker is
present. loadLazy similarly skips loadSections on overlay main
(header/footer fragment loading is unchanged).
appear gives a free no-flicker overlay windowEDS's styles/styles.css has body { display: none } and
body.appear { display: block }. The appear class is added at
the end of loadEager. This is the EDS pattern for "no CLS, no
flash of unstyled content" — but it doubles as an overlay window.
Sequence:
scripts.js loadEager runs.body.appear added → body shown for the first time.Result: user sees the overlay-merged DOM, never the intermediate EDS-shape DOM. Zero flicker.
Some slots contain inline HTML
(<span class="accent">everywhere</span> inside a hero title,
<a href> content in CTAs). The writer function in
applySlotsToTemplate dispatches by tag:
IMG → copy src, altPICTURE → replace element with new pictureA → copy href, set innerHTML to anchor's innerHTMLinnerHTML (preserves inline HTML)Using innerHTML for the default handler is the key. textContent
would emit <span class="accent">... literally and break the
typography accent.
toClassName makes block names case-toleranttoClassName("Closing Cta") → closing-cta. So is
toClassName("Closing CTA"). The block-table-to-class mapping is
normalized: only alphanumerics survive, hyphens between words, all
lowercase.
Conversion implication. Match block tables to template sections by class slug (lowercased, hyphenated). Title-case of the block-table label is human-readable cosmetic; whatever the converter chooses is fine as long as the slug round-trips.
Stardust marks not-yet-authored slots with
<element data-placeholder="true"> containing a placeholder-eyebrow
span and a placeholder-shape span. The result is a visible
"PLACEHOLDER · image" UI that the designer intends to stay visible
until real content arrives.
These elements look like slots but should not become slots.
They're visible static template content with future intent. The
converter marks them data-slot-skip="placeholder" and leaves the
markup alone. The rendered DOM stays identical to the original;
authors get a clear flag that those positions are reserved.
Different generators will have different placeholder conventions (or none). The rule generalises: anything explicitly tagged as placeholder / template-state in the source is not authorable content — preserve as-is.
<header> is fineEDS adds header-wrapper / footer-wrapper classes and wraps the
header/footer block content. A header fragment that includes its
own <header> element produces nested landmarks in the rendered
DOM:
<header class="header-wrapper">
<div class="header block">
<section class="announcement-banner">...</section>
<header class="gnav">...</header>
...
</div>
</header>HTML5 allows nested <header> (the inner one is sectional content
inside an enclosing landmark). CSS class selectors target the inner
classes directly so the nesting is invisible.
Constraint surfaced. If a future source's CSS uses
body > header or body > .announcement-banner (direct-child
selectors targeting the bare body), the EDS wrappers will break
those. Check generator CSS for direct-child selectors during the
Analyze phase.
<header>; footer broader than <footer>AI-generated pages often have global UI elements that don't sit
inside the <header> or <footer> semantic landmarks:
<header> but functionally coupled)The fragment-extraction rule that works:
<body> start to <main> start → header fragment</main> end to <footer> end → footer fragment<main> content onlyThe fragment-load code injects fragments into EDS's <header> and
<footer> elements. CSS class selectors keep working.
A .reduce(..., Promise.resolve()) chain that loads GSAP →
ScrollTrigger → Lenis sequentially with a single .catch aborts the
rest of the chain (and any engine script that depends on them) if a
single CDN miss occurs.
Fix. Use Promise.allSettled so each CDN is loaded
independently. The engine script can defensively check for gsap,
Lenis, ScrollTrigger and degrade gracefully if any are missing.
Reduced-motion guards in animations.js that wrap each timeline
already let missing libs no-op rather than crash.
.tessl-plugin
skills
aem-block-library
aem-cli
aem-layout-view
block-collection-and-party
brand-setup
references
building-blocks
code-review
content-driven-development
references
content-modeling
create-site
da-auth
figma-to-content
find-test-content
generate-import-html
identify-page-structure
migrate-header
page-decomposition
page-import
preview-import
scrape-webpage
slicc-handoff
snowflake
assets
substrate
substrate-milo
examples
knowledge
scripts
testing-blocks
ue-component-model