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
AI codegen tools (Stardust, Mobirise, Relume, Lovable, v0, etc.) produce polished static HTML+CSS+JS sites. They are great for launch but painful for non-technical authors to update. We want to keep the generated DOM exactly as-is while making the editable parts (texts and images) authorable in Document Authoring.
Constraint: this must work for arbitrary static input, not one specific generator's output.
Every artifact is template-keyed so multiple templates coexist in one EDS repo without colliding.
┌──────────────────────────────────────────────────────────────────────┐
│ ONE-TIME CONVERTER (per static page → five kinds of artifact) │
│ │
│ static page.html ─┬─► /fragments/<template>/header.html (code bus) │
│ ├─► /fragments/<template>/footer.html (code bus) │
│ ├─► /templates/<template>.html (code bus) │
│ │ ↳ original <main> with [data-slot] │
│ │ markers where texts and images sat │
│ ├─► /styles/<template>.css (code bus) │
│ ├─► /scripts/<template>-animations.js (optional) │
│ └─► DA doc (pushed via admin API) │
│ ↳ divs-with-class shape, body fragment │
│ ↳ one <div class="blockname"> per block │
│ ↳ rows: slot-name | value (paired divs) │
│ ↳ <div class="metadata"> in <main> for │
│ template/title/og:* meta tags │
└──────────────────────────────────────────────────────────────────────┘
AT REQUEST TIME (browser)
GET /<path> → pipeline serves DA-stored body (divs-with-class)
with <meta name="template"> populated from the
Metadata block
│
▼
scripts.js loadEager — overlay step:
1. resolveTemplateName():
<meta name="template"> || body[data-template] || null
2. readBlockSlots(main): walk DA-shape divs →
{ blockClassName: { slotName: html, ... } }
3. start loadCSS('/styles/<template>.css') and
fetch('/templates/<template>.html') in parallel
4. applySlotsToTemplate(newMain, slots): for each
section[class], find [data-slot] elements and
writeSlot() with element-typed semantics
(text→innerHTML, img→src/alt, a→href+innerHTML)
5. main.innerHTML = newMain.innerHTML
6. main.dataset.overlay = templateName ← sentinel
7. await cssLoaded
8. body.appear → first paint
│
▼
loadLazy:
- blocks/header/header.js reads main.dataset.overlay,
fetches /fragments/<template>/header.html
- blocks/footer/footer.js — same for footer
- loadSections(main) runs unconditionally (harmless no-op
on overlay pages — see note below)
│
▼
loadDelayed:
- if main.dataset.overlay set: load CDN motion deps in
parallel (Promise.allSettled), then attempt
/scripts/<template>-animations.js (404 is silent —
templates without animations don't need it)
│
▼
Final rendered DOM == original static page DOM ✅loadLazy needs no overlay guard for loadSectionsloadSections(element) in aem.js queries element.querySelectorAll('div.section').
The overlay template (/templates/<template>.html) contains the original static page's
<main> markup — plain design elements (<section>, <header>, etc.), not EDS
wrapper <div class="section"> elements. Therefore loadSections(main) finds zero
matching nodes and returns immediately: it is a harmless no-op on overlay pages.
The old woven scripts.js wrapped this call in if (!main.dataset.overlay) { ... } as
a defensive guard, but the guard is unnecessary. The new hook-based approach deliberately
omits it: loadEager injects the overlay logic and sets the sentinel, while loadLazy
calls loadSections(main) unconditionally — with no ill effect on overlay pages.
| Artifact | Path |
|---|---|
| Template HTML | /templates/<template>.html |
| Page-scoped CSS | /styles/<template>.css |
| Header fragment | /fragments/<template>/header.html |
| Footer fragment | /fragments/<template>/footer.html |
| Animation engine | /scripts/<template>-animations.js |
| Local test (drafts) | /drafts/<page-slug>.html (post-pipeline shape) |
| DA content | /<da-root>/<page-slug>.html |
Nothing in head.html references a specific template. The overlay
engine resolves the template at runtime and loads everything scoped
under that name.
| Decision | Who decides | Encoded as |
|---|---|---|
| Which template a page uses | Author (via DA) | <meta name="template"> in DA doc |
| Page structure / classes | Original generator | /templates/<template>.html |
| Header & footer markup | Original generator | /fragments/<template>/header.html |
| Editable text/image values | Author | DA block-table rows |
| Block grouping (semantics) | Converter (LLM) | <div class="blockname"> in DA |
| Slot naming | Converter (LLM) | data-slot in template, row key |
loadEager,
before body.appear flips. EDS's body-hidden-until-appear
invariant gives a free no-flicker window.decorateSections / decorateBlocks assume an
EDS-shape main (main > div > div.classname) and would mis-decorate
the template (main > section.classname). The overlay sets
main.dataset.overlay = <name> as the sentinel; loadEager /
loadLazy skip EDS decoration when it's present.blocks/header/header.js and
blocks/footer/footer.js fetch the static fragment and inject it
(no DA-shaped table parsing).curl and view-source match the original DOM too), the same
merge function moves into a Cloudflare worker / pipeline transform
with minimal change.Equality is checked on the rendered DOM after loadEager completes,
not on the initial HTML response. EDS hides <body> until decoration
completes, so users see no intermediate state; humans rendering the
page get pixel-perfect parity; only curl / view-source see the
EDS-flavored HTML.
If a future requirement demands raw-HTML parity (SEO crawlers without JS, view-source inspection workflows, etc.), promote to a publish-time / edge-merge implementation. The merge logic is identical.
Five writer cases in writeSlot() (dispatch by target element).
Each branch returns early; cases are checked in this order:
Image slots: [data-slot] on <img>. Runtime parses an
<img> from the cell value and copies its src/alt.
Picture slots: [data-slot] on <picture>. Runtime parses
a <picture> from the cell and replaces the template element
entirely with it.
Link slots: [data-slot] on <a>. Runtime parses an <a>
from the cell and copies href + innerHTML. Falls back to
setting innerHTML = value if the cell has no <a>.
Background-image slots: [data-slot] on any element with an
inline style="background-image:url(…)". Runtime parses an
<img> from the cell, extracts its src, and writes it back
into el.style.backgroundImage, preserving any other inline
styles on the element. Use for CSS-driven photos without
restructuring source markup. Bonus: EDS Media Bus rewrites the
<img> URLs in DA cells to optimised paths
(./media_<sha>.jpg?width=…&format=…&optimize=…), so overlay
pages get image optimisation for free.
Text slots (default fall-through): any other element with
[data-slot]. Runtime sets el.innerHTML = value. Preserves
inline HTML the pipeline keeps (<strong>/<em>/<a>/<img>/
<picture>/<h*>/<p>); avoid <b>/<i>/<u>/<mark>/
<br>/<span class> per the preserve-list rules in
methodology.md Generate phase.
data-slot-skip="placeholder": not a slot. Used to mark
generator-emitted placeholder UIs (e.g. Stardust 0.3.0's
data-placeholder="true" elements, 0.2.0's
<span class="placeholder-tag"> markers) that should stay
visible in the rendered DOM but never appear as authorable
rows in DA.
The default pattern for repeating children is flat indexed slot
names: card-1.label, card-1.tagline, card-2.label,
card-2.tagline, etc. This works for fixed counts but doesn't let
authors add/remove items.
A repeating-table pattern is worth considering when:
<img>/<picture> and background-image elements. Attribute
slots (aria-label, title, alt, form-input placeholders) are
not currently exposed as authorable slots.<section> tags as the primary boundary signal. Less-tagged
inputs require the LLM to segment from layout cues alone.title, eyebrow) can
appear in multiple blocks; the runtime matches by section[class]
first, then [data-slot] within.<style> is extracted to a
per-template CSS file (/styles/<template>.css), loaded
dynamically by the overlay engine.<head> content — common content (CSP, viewport, project
scripts) lives in head.html. Per-page metadata (title, og:*,
template) is authored in a DA Metadata block and emitted as
<meta> tags by the pipeline..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