figma-to-content — Figma design → EDS content page in DA
Read a Figma frame, assemble a page from EDS blocks and default content, and
publish it to Document Authoring. Runs with a Figma MCP (to read the
design) and a DA IMS token (to write content) — no proprietary tooling
required.
This skill orchestrates existing skills; it does not reimplement DA rules,
block knowledge, or block-building. Invoke those skills — do not inline them.
The condensed rules quoted in this file are pointers to jog the right skill,
never a substitute for loading it: when a phase names a skill, invoke it and work
from its actual guidance. Running this file as a self-contained procedure —
hand-writing blocks, authoring DA HTML from memory, skipping the browser/visual
check — is the single most common way a run goes wrong. Phase 2.3 turns the
confirmed plan into an explicit manifest of the sub-skills you must invoke.
Two paths
Classify each section of the design, then follow the matching path:
- Content only — every section maps to a block that already exists in
the target project, or to default content (plain headings/paragraphs/
images/buttons — no block). Author content and deploy. No code changes.
- Content + code — a section needs a block the project does not have,
or an existing block matches structurally but its styling diverges (the
look lives in block-specific CSS you'd have to edit). Create it as a new,
isolated block (via the block-building skills), push the code, then author
content and deploy. Never skin an existing block or add per-section rules
to global CSS — new, additive blocks only. (Retargeting the project's
global design tokens is a separate, allowed theming step; see Guardrails.)
A single design usually mixes all three (known blocks + default content + one
or two new blocks).
When to use
- The user has a Figma frame representing a page and wants it as an EDS page in DA.
The common case: a customer already on EDS, with their own blocks, gets a
new design for a new page — some sections reuse existing blocks, some need new
ones.
- The default path is infer-and-confirm. Usually the frame is not
annotated (e.g. the user just says "migrate this page"): the skill infers
each section's mapping against the project's existing block palette and
confirms the plan before building, asking whenever a section is ambiguous
(Phase 2). This path needs nothing but the design itself.
- Annotations are an optional accelerator — never required. If a frame
happens to declare each section's block / default content / new block (see
references/annotation-contract.md),
those declarations are taken as authoritative and skip the inference for that
section. Absent them, nothing is lost — the skill infers and confirms.
When NOT to use
- Redesign / restyle an existing EDS site, or convert arbitrary generated
static HTML (Mobirise, Relume, v0, exported Figma HTML). Use snowflake.
- Universal Editor or AEM Cloud Service (Java/OSGi/JCR). Out of scope.
Related skills — orchestrated by this one
| For |
Use skill |
DA IMS token (DA_TOKEN) |
da-auth |
| DA body-fragment HTML rules, Source API, preview/publish, media |
da-content |
| Whether a block exists + its authoring model & examples |
block-collection-and-party |
| Surveying the whole available block palette |
block-inventory |
| Designing a content model for a new block |
content-modeling |
| Building a new block (full dev workflow) |
content-driven-development (invokes building-blocks, testing-blocks) |
| Rendering a block + visual comparison to the design (the reuse gate) |
testing-blocks (browser/Playwright screenshot + "compare implementation to design") |
The DA-write contract in Phase 5 is the same one da-content documents
(see its references/html-content.md and references/platform.md).
Inputs (gather before Phase 1; ask if missing — never guess)
- Figma reference — file key + node id of the page frame (from the
figma.com URL or the current Figma MCP selection). A file usually holds
many frames — desktop/mobile variants, A/B versions, work-in-progress
copies of the same page. Confirm exactly which frame to build; don't
assume the first or largest. Two frames that are variants of the same page
are one page, not two — ask which is canonical rather than deploying both.
- Target project — a local checkout of the EDS project repo (needed to see
existing blocks under
blocks/, and required for the content+code path to
add block code). Its GitHub {owner}/{repo} and the deploy {branch}.
- DA location —
daOrg, daRepo (the DA namespace), page PATH (no
extension, lowercase/dash only — see da-content platform rules). In the
standard EDS+DA setup daOrg/daRepo equal the GitHub {owner}/{repo};
confirm, because Phase 5 writes to daOrg/daRepo but previews/renders on
the GitHub {owner}/{repo}/{branch}.
DA_TOKEN — via da-auth, which exports $DA_TOKEN and caches it at
~/.aem/da-token.json (valid ~1h). Prefer the $DA_TOKEN da-auth already set
in this session; read the cache file only if that's unset. Two distinct
failures: a 401 with an empty body means the token expired → re-auth; a
cache file that can't be read because the execution sandbox has no $HOME
access means the token is unreachable, not expired (see Phase 0 step 3) —
don't conflate them.
Phase 0 — Preflight (fail fast, before any read or write)
Verify the run can actually complete before reading the design or writing to
DA — a missing prerequisite caught here is one actionable message; caught mid-run
it is a confusing, half-built page. Run these checks in order and, on the first
that fails, stop with the specific remediation below — do not proceed on a
guess or a partial capability.
- Figma MCP reachable. Confirm a Figma MCP is connected and responds via a
cheap call (e.g.
whoami, or listing its tools). If no Figma MCP tool is
available at all, stop: "No Figma MCP is connected. Connect one (Claude
desktop Dev Mode, an IDE Figma integration, or a remote Figma MCP) and
re-run." Record the authenticated identity (whoami) for the next check.
- Access to the specific file. Make one lightweight call against the target
fileKey (e.g. get_metadata scoped to the frame, or get_design_context
on the node). A permission / not-found error (403/404/"no access")
means the file is not shared with the authenticated account → stop: "Figma
reports no access to <fileKey> as <whoami>. Share the file with that
account, switch accounts, or provide a file you can open." Distinguish this
from a transport cap — a truncated, garbled, or JSON-parse-error response is
the size cap (see Phase 1), not an access failure: retry narrower, do not
report it as no access.
- DA write path available. Confirm a
DA_TOKEN is obtainable via da-auth
— prefer the $DA_TOKEN it exports into the session, else its cache at
~/.aem/da-token.json, else freshly minted. If the cache exists but can't be
read because this execution sandbox has no $HOME access, the token is not
missing — it is unreachable; do not loop re-minting. Stop with that
distinction spelled out: "A DA token exists but this sandbox can't read
~/.aem/da-token.json — run where the cache is readable, or provide the token
as $DA_TOKEN (or a readable path)." If no token can be obtained at all,
stop: "Can't obtain a DA token (da-auth) — authenticate to DA and re-run."
Either way, don't spend a full Figma read only to fail at the deploy step.
- Project checkout + orchestrated skills present. The target repo is checked
out locally (needed to see
blocks/ and to add new-block code) and the skills
this one orchestrates (da-auth, da-content, the block skills) are
available. If the checkout path is unknown, ask for it.
On all-pass, print a one-line preflight summary — Figma identity, the file/frame,
and the DA org/repo + branch you will write to — then proceed to Phase 1.
Phase 1 — Read the Figma design (Figma MCP)
Use a Figma MCP (Claude desktop / IDE / external). Introspect the actual tool
schemas — signatures differ between MCP implementations (the local Dev Mode
server often works off the current selection and may not take a fileKey; the
remote/desktop server takes fileKey + optional nodeId). The tools you need,
by capability:
- Structure (e.g.
get_metadata) — the frame's section/layer tree; node
ids, names, positions, sizes. Derive the section list from the content
groups in visual order (sort by y) — not the raw child list: full-
bleed background rectangles, overlays, and decorative shapes are part of a
section (its background), not sections of their own, and a single visual
section is often split across sibling nodes (e.g. a background rect + a tab
strip + a text group). Ignore the decorative layers and group the rest into
sections by position. Usually fileKey required, nodeId optional. Some
MCP servers cap response size — even a single frame's structure dump can
exceed it; scope the call to the frame or, if that still fails, one section
at a time. A truncated, garbled, or JSON parse-error response is the cap
being hit — retry narrower; do not read it as "no structure."
- Visual (e.g.
get_screenshot) — a per-section reference image to
sanity-check the block/content mapping.
- Content & assets (e.g.
get_design_context) — text, links, and image
asset download URLs for a node. For the content+code path this also provides
the layout/structure a new block must reproduce. Request the lean form —
exclude the screenshot from the context call (fetch visuals separately with
the screenshot tool) and disable any Code Connect lookup (e.g.
excludeScreenshot / disableCodeConnect-style options) unless you are
mapping to a real component library; both add payload and round-trips and can
push a large response over the transport cap. Icons are usually component
instances, not raster fills — obtain their SVG (export/copy as SVG),
never a PNG, for the /icons or DA /media reference in Phase 4.
- Design tokens (e.g.
get_variable_defs) — colors, spacing, type. Read
annotation values and, for new blocks, source token values.
Call budget & order — Figma MCP calls are rate-limited and payload-capped, so
spend them deliberately rather than re-fetching:
get_metadata first (scoped to the frame) — the structure/section tree.
The cheapest orienting call; every later call keys off the node ids it returns.
get_screenshot of the whole frame early — one full-frame reference image
up front is the anchor you reconcile the section count against (segmentation
heuristic) and, later, compare the rendered page to (Phase 5 Stage B). Take
per-section crops afterwards, only for the sections you actually build.
get_design_context targeted and lean, per section — request the lean
form (exclude the screenshot, disable Code Connect) and scope it to one
section's node at a time. A whole-frame context dump is the single call most
likely to blow the transport cap.
- Asset download last (
download_assets / export-as-SVG) — only for the
assets the confirmed plan references, after Phase 2. Don't pull binaries
for sections that end up reusing an existing block or being cut.
A 429/rate-limit or a truncated/garbled response is a budget/cap signal, not
"no data": back off, narrow the scope (frame → section), and retry — never read
it as an empty design or as missing access (Phase 0 step 2 draws the same line).
Produce an ordered section inventory: { sectionNodeId, annotation, screenshot, content, background } — capture each section's background /
theme (e.g. alternating light and dark sections), because the global token
retheme (Guardrails) recolors blocks but does not switch a section's
background: that carries via a section-metadata Style class or a block's
own defined dark/light variant (Phase 4). Read annotations per
references/annotation-contract.md.
Segmentation heuristic — when the frame has no explicit grouping, derive
the section list like this, not from the raw child order:
- Sort the frame's direct children by
y (top to bottom).
- Drop pure-decoration layers from the section list — full-bleed
background rectangles, gradients, blurs, absolutely-positioned shapes with
no text or interactive child. Record each as the background of the
content it sits behind (→ Phase 4
section-metadata); don't emit it as a
section of its own.
- Merge siblings that form one visual band — nodes whose vertical
extents overlap or sit within ~one line-height of each other (a background
rect + a heading group + a button row are one section, not three).
- Reconcile the count against the screenshot before resolving: the eye
sees the real sections; a mismatch means you over- or under-split — fix it
before Phase 2.
Placeholder content is common — don't ship it. Designs routinely contain
dummy copy (Lorem ipsum, a CTA literally labelled "Button" or "Lorem
Ipsum", the same card title repeated across every card) and unfilled slots
(empty or transparent image cells, blank stat boxes). Author from the real
text and media in the design context — not from the placeholder and not from
invented filler. Where it's clearly placeholder, flag it in the plan and
confirm the real copy/media with the user rather than publishing "Lorem
Ipsum" to a live page. Distinct items (cards, tabs, news entries) need
distinct copy and images — repeated-identical content is itself a
placeholder smell. If the design itself carries only placeholder, you cannot
manufacture the real content: stop and get it from the user before publish.
Site chrome (nav bar, footer) is usually not page body — in EDS it is
sourced from separate /nav and /footer documents via the header/footer
blocks. Don't author it into the page unless the user asks.
Phase 2 — Resolve each section
Every section resolves to exactly one of: existing block (→ 3A),
default content (→ 3C), or new block (→ 3B). How that decision is
reached depends on whether the section is annotated.
2.0 — Know the project's block palette (always)
Before resolving anything, enumerate what the project already has:
ls -d blocks/*/ plus block-inventory / block-collection-and-party for
each block's authoring model (row/cell structure, variants) and a
rendered example — the block's liveExampleUrl when it comes from the Block
Collection, or the project's own block rendered at localhost:3000. That
rendered example is the "block side" of the 2.1 / Phase 3A visual check. This
is the reuse-candidate set — essential when the customer is already on EDS with
their own blocks.
2.1 — Resolve each section (annotation-first, else infer)
If the section is annotated (see
references/annotation-contract.md), the
annotation is authoritative: named block that exists → existing block (3A);
marked new (or absent-and-user-confirmed) → new block (3B); plain prose/media
→ default content (3C).
If it is not annotated (e.g. "just migrate this page"), infer the
mapping — do not dump it as unresolved:
- Plain prose/media (headings, paragraphs, images, a standalone link) with no
repeating structure → default content (3C).
- Otherwise match it against the 2.0 palette using the reuse gate (structure
AND visual, Phase 3A): does its content model fit an existing block and
does that block's rendered example — under the project theme — look like the
section, allowing only token differences and variants the block defines?
- Both fit → existing block (3A).
- Structure fits but the look diverges (bespoke card/layout/decoration
the block's CSS can't produce without editing it), or nothing fits →
new block (3B).
- A section carrying an interactive control — tabs / segmented switch,
accordion, carousel or slider, toggle — is structural divergence no static
block reproduces: route it to a new block (3B), or, if the control is
non-essential chrome, confirm with the user whether to keep it or
flatten it to static content. Don't silently drop the interaction or fake
it with a look-alike static block.
- Attach a confidence to every inference:
high (clear reuse match, or
clearly novel) or low (structure fits but styling is borderline; two
blocks plausibly fit; new-variant-vs-new-block; content model ambiguous).
2.2 — Confirm the plan before deploying (never deploy a guess)
Present a resolution plan — one line per section: decision (reuse X /
default content / new block Y), confidence, a one-clause rationale, and a
content flag on any section whose copy or media is placeholder (Phase 1)
and needs real content before publish.
- High-confidence sections auto-proceed through building (Phases 3–4) —
don't block on them.
- Stop and ask before building any
low-confidence section or genuine
ambiguity, offering the concrete choice (reuse this block vs. new block;
which block; new variant vs. new block). Wait for the answer.
- Pause once before deploying (Phase 5) whenever the plan contains any
inferred (unannotated) mapping: show the final plan and get a single
confirmation before the da.live write/preview — deploy is outward-facing and
hard to reverse. Skip this pause only if the user pre-authorized an
unattended run. A fully annotated plan needs no pause — the annotations
are the authorization.
- Flag an existing target page. Before confirming, check whether the target
content/<PATH>.html already exists in DA (a cheap Source-API GET, Phase 5);
if it does, deploying overwrites it — say so in the plan and get explicit
overwrite confirmation. Never silently clobber a page you didn't create, even
on an otherwise pre-authorized unattended run. Record two facts per path for
Phase 5 to enforce: PLANNED_STATE (new if the check returned 404, exists
if 200) and OVERWRITE_OK (yes only when the user confirmed overwriting an
existing page). Phase 5 re-checks existence right before writing and refuses
if the state changed since planning (a page appeared in the gap) or overwrite
was never confirmed — the plan-time check alone is not a license to clobber.
- The user can override any line.
Never silently drop a section, and never deploy an inferred mapping the
user has not seen.
Worked example — an unannotated 4-section frame; this is the plan you
present in 2.2 (one line per section):
| # |
Section |
Decision |
Conf. |
Why |
Content |
| 1 |
Hero band — heading + 2 CTAs over a photo |
reuse hero |
high |
model fits; heading and CTAs stay legible on the media under the theme |
ok |
| 2 |
3 feature blurbs — icon + title + text |
reuse cards |
high |
content model and rendered look both fit |
ok |
| 3 |
Metric strip — 3 big numbers + labels |
new block stat-cards |
high |
bespoke panel look no existing block produces (3B) |
ok |
| 4 |
Newsletter row — heading + email field + button |
new block / confirm |
low |
carries an interactive control (input) — ask keep vs. flatten (G5) |
⚠ placeholder copy |
Then act on it: sections 1–2 build without blocking; #3 builds (high-confidence
new block); #4 stops for a decision (low-confidence + interactive control);
and because the plan contains inferred mappings, the whole thing gets one
pre-deploy confirmation before the da.live write. Section #4's ⚠ flag means
its real copy must be supplied before publish, not shipped as placeholder.
2.3 — Lock the orchestration manifest (which sub-skills this plan requires)
Turn the confirmed plan into an explicit manifest of the sub-skills it
requires and invoke each one — this is where the intro's orchestrate, don't
inline rule becomes a concrete, ticked list. This file's summaries never
substitute for loading the named skill.
Derive the manifest from the plan:
| The plan contains… |
You MUST invoke |
| Any section (always) |
da-auth (token) and da-content — load its real references/html-content.md, platform.md, and media.md, not the condensed rules in this file — before authoring (Phase 4) and deploying (Phase 5). |
| An existing-block reuse (3A) |
block-collection-and-party (authoring model + a rendered example) and testing-blocks for the visual reuse gate (rendered block vs. the Figma section screenshot). |
| A new block (3B) |
content-modeling (design the authoring model), then content-driven-development (which runs building-blocks and testing-blocks). Do not hand-write block JS/CSS from this file. |
| Default content (3C) |
da-content only (no block skills). |
Record the manifest as an evidence-bearing checklist and tick each item only
after you actually invoked the skill — "I know what it does" is not invocation,
and an un-invoked required skill means this phase is not complete:
If the environment genuinely cannot run a required skill (e.g. no browser for
testing-blocks), say so explicitly in the report and mark the affected checks
unverified — never silently substitute this file's summary and call it passed.
Phase 3A — Map content into an EXISTING block
Reuse gate — structure AND visual. An existing block is a valid target
only when the section both (a) fits the block's authoring model (its
row/cell structure and field types) and (b) matches the block's rendered
appearance under the project theme, using only tokens and variants the block
already defines. Structural fit alone is not enough: if the section's
visual identity — bespoke layout, corner radius, shadow, decorative treatment —
lives in that block's own CSS, you cannot reproduce it without editing the
block (forbidden), so route the section to Phase 3B (new block). Global,
token-level differences (palette, fonts, type scale) do not break reuse —
they are absorbed once by retargeting the project's design tokens (see
Guardrails). How to run the visual check — reuse testing-blocks, don't invent
one: get a rendered example of the candidate block — its liveExampleUrl
(block-collection-and-party / block-inventory) or the project's own block
rendered at localhost:3000 with the section's actual content — including
secondary text, captions, and CTAs over whatever background or media the block
places them on, not just placeholder cells — then follow testing-blocks'
browser/Playwright-MCP screenshot pass (mobile/tablet/desktop) and its "compare
implementation to design" step, comparing that screenshot against the Figma
section screenshot from Phase 1. Watch for treatments a block applies to
only its primary element: one that (say) whitens a heading over dark media but
leaves the supporting text and buttons at body color passes a structural check
yet renders that text illegibly — a divergence the token retheme cannot fix.
Divergence beyond what the token retheme explains ⇒ new block (or a new
variant), not reuse. This outcome is blocking: the section is not resolved
until its rendered look — that text included — is faithful, and the fix is a new
isolated block/variant, never an edit to the shared block. Recording the gap in
the plan and reusing the block anyway is a plan note, not a fix — the Phase 5
pre-publish gate treats such a box as failed.
Once the gate passes, invoke block-collection-and-party to learn the block's
authoring model (its examples show the row/cell structure and variants) — read
the block from the skill, don't guess its model from its CSS source. Then pour
the Figma content into that structure:
- Text → matching cells; preserve heading levels from the design.
- Variants → extra class tokens on the block (e.g.
cards highlight).
Only apply a variant the block actually defines. (Adding a new variant =
modifying an existing block = Phase 3B, not 3A.)
- Links/buttons → a standalone link (the only content of its
paragraph) auto-promotes to a button; wrap in
<strong> for a primary
button, <em> for secondary. Do not add target="_blank" (decoration
handles external links). Validate the href's URL scheme and escape the
link text/attributes before emitting — see Phase 4, Sanitize everything
derived from the design. (da-content html-content.md §8)
- Images → Phase 4 (they need real URLs).
Phase 3B — Create a NEW block (content + code)
Only for sections Phase 2 routed here (a needed block is missing, or an existing
block's look diverges) — the 3B case. Guardrails (strict):
- Create new, isolated block folders only (
blocks/<new-name>/).
- Do NOT skin this block by editing an existing block,
scripts.js, or
head.html, or by adding block-specific rules to global CSS — keep it
self-contained under blocks/<new-name>/. (Retargeting the project's
global design tokens in styles/styles.css — the :root custom properties
and base typography — is a separate, allowed project-theming step, not part
of building this block; see Guardrails.)
- New block names and variant tokens must obey EDS block-name rules
(da-content html-content.md §3.3): lowercase alphanumeric + single hyphens,
no underscores, no double dashes, must not start with a digit
(
pricing-table ✓, pricing_table / 2col / promo--wide ✗). Names must
be unique and not collide with existing blocks.
Build route — invoke content-driven-development (don't hand-write the block).
Build every new block by invoking content-driven-development — not by writing
block JS/CSS from scratch off this file's summary. It invokes content-modeling
(design the authoring model from the Figma structure/tokens) then
building-blocks and testing-blocks, and produces a self-contained
blocks/<name>/ — no source URL, no installed substrate, no page chrome, and no
global styles. That is the route that honors the 3B guardrails above, and its
testing-blocks pass is the block's Stage B verification (Phase 5). Build a bespoke, one-off section
the same way — it is still an ordinary isolated block, and "one-off" changes
nothing about how it is generated.
Do not use snowflake here. Snowflake converts an already-rendered page:
it requires a reachable Source URL, installs an overlay substrate into
the repo, and in block mode emits header/footer fragments and global
styles/tokens — each of which violates this skill's constraints (isolated new
block, don't touch globals, work from the Figma frame, not a live URL).
Snowflake is the right tool for a different entry point — converting an
existing static/rendered site — as noted under "When NOT to use".
Use the Figma design context/tokens from Phase 1 as the source of truth for
layout and styling. New-block CSS must target structure, not authored
classes — inline wrappers like <span class="…"> are stripped inside block
cells at delivery (da-content html-content.md §3.9), so a class you emit in a
cell will not survive.
Make the block responsive. A Figma page frame is almost always a single
desktop width, but EDS pages are responsive. Author the block mobile-first
(or with explicit breakpoints) so a multi-column layout collapses to one column
on narrow viewports, and verify at mobile / tablet / desktop via
testing-blocks — don't ship a fixed desktop-width block. If the design
provides a separate mobile frame, use it to derive the breakpoint behavior
(what stacks, what hides, how type scales) — it's the same page, so it feeds
one responsive block, not a second page (see Inputs on frame variants).
The new block's code must be committed and pushed to the deploy branch on
GitHub and built by Code Sync before the page can render it — see Phase 5
(content+code).
Phase 3C — Author DEFAULT CONTENT (no block)
For sections Phase 2 routed to default content — the 3C case — emit standard
document elements directly inside the section <div> (see Phase 4 skeleton) — no
block wrapper:
- Headings
<h1>–<h6> (preserve levels), paragraphs, lists, images.
- A standalone link in its own
<p> becomes a button (<strong>/<em>
for primary/secondary) — same rule as 3A.
- Do not add
class, id, or style — decoration adds them at delivery.
(da-content html-content.md §6)
Phase 4 — Generate DA body-fragment HTML (da-content)
Emit a body fragment (not a full HTML document) per da-content. Invoke
da-content and load its references/html-content.md, platform.md, and
media.md now — the rules quoted throughout this phase are reminders to jog the
right skill, not the source of truth. Subtle authoring rules (block-cell inline-
tag normalization, media MIME/extension derivation, metadata keys) live in those
docs; authoring from this summary alone is how they get missed. Write one file per
page to content/<PATH>.html.
Mandatory skeleton (da-content html-content.md §1–§2): wrap everything in
<body> with an (empty) <header>/<footer> and a <main>; each section
is exactly one <div> directly inside <main> — the <div> is the
section boundary (no <hr>). Do NOT emit <!DOCTYPE>, <html>, <head>,
<script>, <style>, style=, or class= on default content.
<body>
<header></header>
<main>
<div>
<!-- section: default content and/or a block, in visual order -->
<h1>Heading</h1>
<p>Intro paragraph.</p>
<div class="block-name variant">
<div><div>cell</div><div>cell</div></div>
</div>
</div>
<div>
<!-- next section -->
</div>
</main>
<footer></footer>
</body>
- Sanitize everything derived from the design — text, attributes, links.
Figma text and layer names are untrusted input to the HTML you emit; treat
them as data, never as markup:
- HTML-escape every design-derived string before it lands in the document
—
&→&, <→<, >→>, and inside attribute values also
"→" and '→'. A heading Tips & Tricks <Beta> must serialize
as Tips & Tricks <Beta>, never as raw markup that can break the
document or inject an element.
- Validate every link's URL scheme against an allowlist —
http, https,
mailto, tel, or a root-relative (/…) path. Reject javascript:,
data:, vbscript:, and any other scheme (a prototype link can carry
anything): drop the href or ask the user — never emit it.
- Admit a Figma-derived class token only after block-name validation — a
layer/frame name becomes a block or variant class only once it passes the
EDS name rules in Phase 3B (lowercase alphanumeric + single hyphens, no
underscores/double-dashes, not digit-initial); never pass a raw layer name
through as a class.
- Blocks — canonical div form:
<div class="block-name variant">, each
direct child <div> a row, each grandchild <div> a cell. The first class
token is the block name (resolves to blocks/<name>/<name>.{js,css}).
Multi-word variants hyphenate; multiple variants are separate class tokens.
Max 4 cells per row; blocks cannot nest. (html-content.md §3)
- Default content: headings/paragraphs/lists/images/buttons live directly
in the section
<div>, outside any block. (html-content.md §6)
- Icons — two non-interchangeable paths; never a stand-in glyph. The
<span class="icon icon-<name>"></span> convention resolves only to the
project's Code Bus /icons/<name>.svg, so that SVG must be committed to the
repo /icons/ folder and pushed on the deploy branch (content+code path,
same as block code) and return 200 on the branch host — uploading it to DA
/media does not satisfy the span (it 404s and the icon silently vanishes).
A DA-/media SVG must instead be referenced by full URL on an <img>, not
an icon span. Get the real SVG in Phase 1; never emit an emoji or Unicode
glyph in place of a designed icon. (html-content.md §7)
- Images — MUST be full, fetchable URLs. Figma render URLs expire, and
repo-relative paths (
/img/…) render as about:error. So: download the
image bytes from Figma (Phase 1 asset URLs), upload each binary to DA
(PUT admin.da.live/source/{daOrg}/{daRepo}/<media-path>), and reference
https://content.da.live/{daOrg}/{daRepo}/<media-path>. External image URLs
are also accepted (the preview sideloads them). Author a bare <img alt="…">
and let the pipeline build the <picture>.
- Normalize format, extension, and MIME together — from the bytes, never the
URL suffix. Detect the real format from the image's magic bytes (or the
asset's reported
format), then make all three agree: the multipart
type= MIME, the <media-path> file extension you PUT to, and the extension
in the content.da.live URL you author. Design tools routinely export JPEG
bytes under a .png-named asset; trusting the suffix gives you a .png path
served as image/jpeg (or the reverse) — a latent corruption bug. A layer
that looks vector (an icon, a logo, a shape) often comes back rasterized
— download_assets returns it under rawImages with svgAssets empty — so a
design that implies .svg can hand you PNG/JPEG bytes. Author each <img>
extension from the bytes you actually downloaded, never from the layer's
apparent type or name. Canonical
mapping: JPEG→.jpg/image/jpeg, PNG→.png/image/png, WebP→.webp/
image/webp, GIF→.gif/image/gif, SVG→.svg/image/svg+xml. If bytes
and asset-reported format disagree, trust the bytes.
(html-content.md §9 + media.md)
- Section styling → a
section-metadata block inside the section
(Style → CSS classes; other rows → data-*). (html-content.md §4)
- Page metadata → a single
metadata block (exact class), placed as the
last element of the last section inside <main> (never after </main>
or in <footer>); keys like title, description, image, template,
theme. Author it from the design — don't leave it empty or a bare
comment. Derive title from the frame name or the page <h1>, description
from the hero/intro copy (a concise real sentence, never lorem), and image
from the primary/hero image's uploaded DA URL when the design has one. This
block is required — the Phase 5 pre-publish gate blocks on its absence — so
populate it rather than deferring it. If the design offers no usable
title/description text, ask the user rather than inventing marketing copy.
(html-content.md §5)
Inside block cells the pipeline runs a stricter inline-tag normalization than
for default content — <span class> is unwrapped (class lost), <b>→<strong>,
<mark>→<em>, etc. Restrict cell content to the html-content.md §3.9 preserve
list. A wrong metadata key or block field silently corrupts output;
when unsure, read da-content.
Phase 5 — Deploy to DA
If a DA MCP server is available in the session, use its tools for auth and
source writes (da-auth and da-content both defer to it when present).
Otherwise use the Source API directly, below.
# Two identities — keep them separate. DA (Document Authoring) and GitHub are the
# same org/repo in the standard EDS setup, but nothing guarantees it, so never
# assume one from the other. DA endpoints (admin.da.live/source, content.da.live,
# da.live/edit) use the DA pair; the render host and admin.hlx.page (code, preview,
# live) use the GitHub pair.
DA_ORG=<da-org> # Document Authoring org
DA_REPO=<da-repo> # Document Authoring repo/site
GH_OWNER=<gh-owner> # GitHub owner
GH_REPO=<gh-repo> # GitHub repo
# In the standard setup all four match: DA_ORG=GH_OWNER=<owner>, DA_REPO=GH_REPO=<repo>.
BRANCH=<branch> # git deploy ref (usually main). For content+code this MUST be
# the branch the new-block code was pushed to and Code Sync built.
BRANCH_HOST=${BRANCH//\//-} # host label: slashes → dashes ('feature/x' → 'feature-x').
# Used BOTH for the aem.page/aem.live hostname AND as the ref
# segment in every admin.hlx.page path (code/preview/live): that
# ref is a SINGLE path segment, so a slashed branch ('figma/x')
# splits it and 404s — pass the dashed label ('figma-x'), which is
# what AEM actually resolves. Only git itself (push/checkout) uses
# the literal slashed $BRANCH. For a slash-free branch the two
# forms are identical, so $BRANCH_HOST is always the safe choice
# for admin.hlx.page.
P=<path-without-extension>
TOKEN="$DA_TOKEN" # from da-auth; 401 w/ empty body ⇒ expired, re-auth
# Fail fast if the branch host would be unresolvable (>63 chars won't resolve).
host="$BRANCH_HOST--$GH_REPO--$GH_OWNER"
[ "${#host}" -le 63 ] || { echo "❌ branch host '$host' is ${#host} chars (>63) — won't resolve; use a shorter branch/repo/org"; exit 1; }
# --- checked-request helper: every call asserts its status; a bare `curl -sS`
# exits 0 on 401/403/409/5xx, so an unchecked curl silently "succeeds" on a
# failed write. req <expected-codes> <curl-args…>: prints the body, retries a
# few times on network/429/5xx, and aborts (non-zero) on any other mismatch.
# Use it for every PUT/POST below; if a DA MCP server is used instead, apply
# the same rule — assert the returned status, don't assume success. ---
req() {
local expect="$1"; shift
local attempt out code body
for attempt in 1 2 3 4 5; do
if out=$(curl -sS -w $'\n%{http_code}' "$@"); then code="${out##*$'\n'}"; else code="000"; fi
body="${out%$'\n'*}"
case ",$expect," in *",$code,"*) printf '%s' "$body"; return 0;; esac
case "$code" in
000|429|5??) sleep $((attempt * 2)); continue;; # transient — bounded retry
401) echo "❌ 401 (empty body ⇒ token expired) — re-auth (da-auth) and retry" >&2; return 1;;
*) echo "❌ HTTP $code (expected $expect) — $*" >&2; return 1;; # 4xx: do not retry
esac
done
echo "❌ giving up after retries (last status $code) — $*" >&2; return 1
}
# --- content+code path ONLY: block code must be LIVE before the pag
…(truncated)
1---2name: figma-to-content3description: "Use this to turn a Figma design into an AEM Edge Delivery Services (EDS / AEM / Franklin / Helix) content page in Document Authoring (DA, da.live). Triggers: \"build this Figma frame in EDS\", \"turn this Figma design into a DA page\", \"publish this design to da.live\", or providing a figma.com URL for a page. Reads the frame (and any annotations) via a Figma MCP, resolves each section to an existing block, a new isolated block, or default content (inferred against the project's existing blocks and confirmed with you, or read from annotations when the frame happens to have them), generates DA-compliant body-fragment HTML, and deploys via the DA Source API + preview."4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/adobe/figma-to-content7 version: "1.0.0"8---910# figma-to-content — Figma design → EDS content page in DA1112Read a Figma frame, assemble a page from EDS blocks and default content, and13publish it to Document Authoring. Runs with a **Figma MCP** (to read the14design) and a **DA IMS token** (to write content) — no proprietary tooling15required.1617This skill **orchestrates existing skills**; it does not reimplement DA rules,18block knowledge, or block-building. **Invoke those skills — do not inline them.**19The condensed rules quoted in this file are *pointers* to jog the right skill,20never a substitute for loading it: when a phase names a skill, invoke it and work21from its actual guidance. Running this file as a self-contained procedure —22hand-writing blocks, authoring DA HTML from memory, skipping the browser/visual23check — is the single most common way a run goes wrong. Phase 2.3 turns the24confirmed plan into an explicit manifest of the sub-skills you must invoke.2526## Two paths2728Classify each section of the design, then follow the matching path:2930- **Content only** — every section maps to a block that **already exists** in31 the target project, or to **default content** (plain headings/paragraphs/32 images/buttons — no block). Author content and deploy. No code changes.33- **Content + code** — a section needs a block the project **does not have**,34 or an existing block matches structurally but its **styling diverges** (the35 look lives in block-specific CSS you'd have to edit). Create it as a **new,36 isolated block** (via the block-building skills), push the code, then author37 content and deploy. **Never skin an existing block or add per-section rules38 to global CSS** — new, additive blocks only. (Retargeting the project's39 global design tokens is a separate, allowed theming step; see Guardrails.)4041A single design usually mixes all three (known blocks + default content + one42or two new blocks).4344## When to use4546- The user has a Figma frame representing a page and wants it as an EDS page in DA.47 The common case: a customer **already on EDS**, with their own blocks, gets a48 new design for a new page — some sections reuse existing blocks, some need new49 ones.50- **The default path is infer-and-confirm.** Usually the frame is **not**51 annotated (e.g. the user just says "migrate this page"): the skill **infers**52 each section's mapping against the project's existing block palette and53 **confirms the plan** before building, asking whenever a section is ambiguous54 (Phase 2). This path needs nothing but the design itself.55- **Annotations are an optional accelerator — never required.** If a frame56 happens to declare each section's block / default content / new block (see57 [references/annotation-contract.md](./references/annotation-contract.md)),58 those declarations are taken as authoritative and skip the inference for that59 section. Absent them, nothing is lost — the skill infers and confirms.6061### When NOT to use6263- **Redesign / restyle an existing EDS site**, or convert arbitrary generated64 static HTML (Mobirise, Relume, v0, exported Figma HTML). Use **snowflake**.65- **Universal Editor or AEM Cloud Service (Java/OSGi/JCR).** Out of scope.6667## Related skills — orchestrated by this one6869| For | Use skill |70|---|---|71| DA IMS token (`DA_TOKEN`) | **da-auth** |72| DA body-fragment HTML rules, Source API, preview/publish, media | **da-content** |73| Whether a block exists + its authoring model & examples | **block-collection-and-party** |74| Surveying the whole available block palette | **block-inventory** |75| Designing a content model for a **new** block | **content-modeling** |76| Building a **new** block (full dev workflow) | **content-driven-development** (invokes **building-blocks**, **testing-blocks**) |77| Rendering a block + **visual comparison to the design** (the reuse gate) | **testing-blocks** (browser/Playwright screenshot + "compare implementation to design") |7879The DA-write contract in Phase 5 is the same one **da-content** documents80(see its `references/html-content.md` and `references/platform.md`).8182---8384## Inputs (gather before Phase 1; ask if missing — never guess)8586- **Figma reference** — file key + node id of the page frame (from the87 figma.com URL or the current Figma MCP selection). A file usually holds88 **many frames** — desktop/mobile variants, A/B versions, work-in-progress89 copies of the same page. Confirm **exactly which frame** to build; don't90 assume the first or largest. Two frames that are variants of the *same* page91 are one page, not two — ask which is canonical rather than deploying both.92- **Target project** — a local checkout of the EDS project repo (needed to see93 existing blocks under `blocks/`, and required for the content+code path to94 add block code). Its GitHub `{owner}`/`{repo}` and the deploy `{branch}`.95- **DA location** — `daOrg`, `daRepo` (the DA namespace), page `PATH` (no96 extension, lowercase/dash only — see da-content platform rules). In the97 standard EDS+DA setup `daOrg`/`daRepo` **equal** the GitHub `{owner}`/`{repo}`;98 confirm, because Phase 5 writes to `daOrg`/`daRepo` but previews/renders on99 the GitHub `{owner}`/`{repo}`/`{branch}`.100- **`DA_TOKEN`** — via **da-auth**, which exports `$DA_TOKEN` and caches it at101 `~/.aem/da-token.json` (valid ~1h). Prefer the `$DA_TOKEN` da-auth already set102 in this session; read the cache file only if that's unset. Two distinct103 failures: a `401` with an empty body means the token **expired** → re-auth; a104 cache file that **can't be read because the execution sandbox has no `$HOME`105 access** means the token is *unreachable*, not expired (see Phase 0 step 3) —106 don't conflate them.107108---109110## Phase 0 — Preflight (fail fast, before any read or write)111112Verify the run can actually complete **before** reading the design or writing to113DA — a missing prerequisite caught here is one actionable message; caught mid-run114it is a confusing, half-built page. Run these checks in order and, on the first115that fails, **stop with the specific remediation below** — do not proceed on a116guess or a partial capability.1171181. **Figma MCP reachable.** Confirm a Figma MCP is connected and responds via a119 cheap call (e.g. `whoami`, or listing its tools). If **no Figma MCP tool is120 available at all**, stop: *"No Figma MCP is connected. Connect one (Claude121 desktop Dev Mode, an IDE Figma integration, or a remote Figma MCP) and122 re-run."* Record the authenticated identity (`whoami`) for the next check.1232. **Access to the specific file.** Make one lightweight call against the target124 `fileKey` (e.g. `get_metadata` scoped to the frame, or `get_design_context`125 on the node). A **permission / not-found** error (`403`/`404`/"no access")126 means the file is not shared with the authenticated account → stop: *"Figma127 reports no access to `<fileKey>` as `<whoami>`. Share the file with that128 account, switch accounts, or provide a file you can open."* **Distinguish this129 from a transport cap** — a truncated, garbled, or JSON-parse-error response is130 the size cap (see Phase 1), **not** an access failure: retry narrower, do not131 report it as no access.1323. **DA write path available.** Confirm a `DA_TOKEN` is obtainable via **da-auth**133 — prefer the `$DA_TOKEN` it exports into the session, else its cache at134 `~/.aem/da-token.json`, else freshly minted. **If the cache exists but can't be135 read because this execution sandbox has no `$HOME` access**, the token is not136 missing — it is *unreachable*; do **not** loop re-minting. Stop with that137 distinction spelled out: *"A DA token exists but this sandbox can't read138 `~/.aem/da-token.json` — run where the cache is readable, or provide the token139 as `$DA_TOKEN` (or a readable path)."* If no token can be obtained at all,140 stop: *"Can't obtain a DA token (da-auth) — authenticate to DA and re-run."*141 Either way, don't spend a full Figma read only to fail at the deploy step.1424. **Project checkout + orchestrated skills present.** The target repo is checked143 out locally (needed to see `blocks/` and to add new-block code) and the skills144 this one orchestrates (**da-auth**, **da-content**, the block skills) are145 available. If the checkout path is unknown, ask for it.146147On all-pass, print a one-line preflight summary — Figma identity, the file/frame,148and the DA `org/repo` + `branch` you will write to — then proceed to Phase 1.149150---151152## Phase 1 — Read the Figma design (Figma MCP)153154Use a Figma MCP (Claude desktop / IDE / external). **Introspect the actual tool155schemas** — signatures differ between MCP implementations (the local Dev Mode156server often works off the current selection and may not take a `fileKey`; the157remote/desktop server takes `fileKey` + optional `nodeId`). The tools you need,158by capability:159160- **Structure** (e.g. `get_metadata`) — the frame's section/layer tree; node161 ids, names, positions, sizes. Derive the section list from the **content162 groups** in visual order (sort by `y`) — **not** the raw child list: full-163 bleed background rectangles, overlays, and decorative shapes are *part of* a164 section (its background), not sections of their own, and a single visual165 section is often split across sibling nodes (e.g. a background rect + a tab166 strip + a text group). Ignore the decorative layers and group the rest into167 sections by position. Usually `fileKey` required, `nodeId` optional. **Some168 MCP servers cap response size — even a single frame's structure dump can169 exceed it; scope the call to the frame or, if that still fails, one section170 at a time. A truncated, garbled, or JSON parse-error response *is* the cap171 being hit — retry narrower; do not read it as "no structure."**172- **Visual** (e.g. `get_screenshot`) — a per-section reference image to173 sanity-check the block/content mapping.174- **Content & assets** (e.g. `get_design_context`) — text, links, and image175 asset download URLs for a node. For the content+code path this also provides176 the layout/structure a new block must reproduce. **Request the lean form** —177 exclude the screenshot from the context call (fetch visuals separately with178 the screenshot tool) and disable any Code Connect lookup (e.g.179 `excludeScreenshot` / `disableCodeConnect`-style options) unless you are180 mapping to a real component library; both add payload and round-trips and can181 push a large response over the transport cap. Icons are usually **component182 instances**, not raster fills — obtain their **SVG** (export/copy as SVG),183 never a PNG, for the `/icons` or DA `/media` reference in Phase 4.184- **Design tokens** (e.g. `get_variable_defs`) — colors, spacing, type. Read185 annotation values and, for new blocks, source token values.186187**Call budget & order — Figma MCP calls are rate-limited and payload-capped, so188spend them deliberately rather than re-fetching:**1891901. **`get_metadata` first** (scoped to the frame) — the structure/section tree.191 The cheapest orienting call; every later call keys off the node ids it returns.1922. **`get_screenshot` of the whole frame early** — one full-frame reference image193 up front is the anchor you reconcile the section count against (segmentation194 heuristic) and, later, compare the rendered page to (Phase 5 Stage B). Take195 per-section crops afterwards, only for the sections you actually build.1963. **`get_design_context` targeted and lean, per section** — request the lean197 form (exclude the screenshot, disable Code Connect) and scope it to **one198 section's node at a time**. A whole-frame context dump is the single call most199 likely to blow the transport cap.2004. **Asset download last** (`download_assets` / export-as-SVG) — only for the201 assets the **confirmed** plan references, after Phase 2. Don't pull binaries202 for sections that end up reusing an existing block or being cut.203204A `429`/rate-limit or a truncated/garbled response is a **budget/cap signal, not205"no data"**: back off, narrow the scope (frame → section), and retry — never read206it as an empty design or as missing access (Phase 0 step 2 draws the same line).207208Produce an ordered **section inventory**: `{ sectionNodeId, annotation,209screenshot, content, background }` — capture each section's **background /210theme** (e.g. alternating light and dark sections), because the global token211retheme (Guardrails) recolors blocks but does **not** switch a section's212background: that carries via a `section-metadata` `Style` class or a block's213own defined dark/light variant (Phase 4). Read annotations per214[references/annotation-contract.md](./references/annotation-contract.md).215216> **Segmentation heuristic** — when the frame has no explicit grouping, derive217> the section list like this, not from the raw child order:218> 1. Sort the frame's direct children by `y` (top to bottom).219> 2. **Drop pure-decoration layers** from the section list — full-bleed220> background rectangles, gradients, blurs, absolutely-positioned shapes with221> no text or interactive child. Record each as the *background* of the222> content it sits behind (→ Phase 4 `section-metadata`); don't emit it as a223> section of its own.224> 3. **Merge siblings that form one visual band** — nodes whose vertical225> extents overlap or sit within ~one line-height of each other (a background226> rect + a heading group + a button row are *one* section, not three).227> 4. **Reconcile the count against the screenshot** before resolving: the eye228> sees the real sections; a mismatch means you over- or under-split — fix it229> before Phase 2.230231> **Placeholder content is common — don't ship it.** Designs routinely contain232> dummy copy (`Lorem ipsum`, a CTA literally labelled "Button" or "Lorem233> Ipsum", the same card title repeated across every card) and unfilled slots234> (empty or transparent image cells, blank stat boxes). Author from the **real235> text and media in the design context** — not from the placeholder and not from236> invented filler. Where it's clearly placeholder, **flag it in the plan and237> confirm the real copy/media with the user** rather than publishing "Lorem238> Ipsum" to a live page. Distinct items (cards, tabs, news entries) need239> **distinct** copy and images — repeated-identical content is itself a240> placeholder smell. If the design *itself* carries only placeholder, you cannot241> manufacture the real content: stop and get it from the user before publish.242243> Site chrome (nav bar, footer) is usually **not page body** — in EDS it is244> sourced from separate `/nav` and `/footer` documents via the header/footer245> blocks. Don't author it into the page unless the user asks.246247---248249## Phase 2 — Resolve each section250251Every section resolves to exactly one of: **existing block** (→ 3A),252**default content** (→ 3C), or **new block** (→ 3B). How that decision is253reached depends on whether the section is annotated.254255### 2.0 — Know the project's block palette (always)256257Before resolving anything, enumerate what the project **already has**:258`ls -d blocks/*/` plus **block-inventory** / **block-collection-and-party** for259each block's **authoring model** (row/cell structure, variants) **and a260rendered example** — the block's `liveExampleUrl` when it comes from the Block261Collection, or the project's own block rendered at `localhost:3000`. That262rendered example is the "block side" of the 2.1 / Phase 3A visual check. This263is the reuse-candidate set — essential when the customer is already on EDS with264their own blocks.265266### 2.1 — Resolve each section (annotation-first, else infer)267268**If the section is annotated** (see269[references/annotation-contract.md](./references/annotation-contract.md)), the270annotation is **authoritative**: named block that exists → existing block (3A);271marked `new` (or absent-and-user-confirmed) → new block (3B); plain prose/media272→ default content (3C).273274**If it is not annotated** (e.g. "just migrate this page"), **infer** the275mapping — do not dump it as unresolved:2762771. Plain prose/media (headings, paragraphs, images, a standalone link) with no278 repeating structure → **default content** (3C).2792. Otherwise match it against the 2.0 palette using the **reuse gate (structure280 AND visual, Phase 3A)**: does its content model fit an existing block *and*281 does that block's rendered example — under the project theme — look like the282 section, allowing only token differences and variants the block defines?283 - **Both fit → existing block** (3A).284 - **Structure fits but the look diverges** (bespoke card/layout/decoration285 the block's CSS can't produce without editing it), **or nothing fits →286 new block** (3B).287 - **A section carrying an interactive control** — tabs / segmented switch,288 accordion, carousel or slider, toggle — is structural divergence no static289 block reproduces: route it to a **new block** (3B), or, if the control is290 non-essential chrome, **confirm with the user** whether to keep it or291 flatten it to static content. Don't silently drop the interaction or fake292 it with a look-alike static block.2933. Attach a **confidence** to every inference: `high` (clear reuse match, or294 clearly novel) or `low` (structure fits but styling is borderline; two295 blocks plausibly fit; new-variant-vs-new-block; content model ambiguous).296297### 2.2 — Confirm the plan before deploying (never deploy a guess)298299Present a **resolution plan** — one line per section: decision (reuse `X` /300default content / new block `Y`), confidence, a one-clause rationale, and a301**content flag** on any section whose copy or media is placeholder (Phase 1)302and needs real content before publish.303304- **High-confidence sections auto-proceed through building** (Phases 3–4) —305 don't block on them.306- **Stop and ask before building** any `low`-confidence section or genuine307 ambiguity, offering the concrete choice (reuse this block vs. new block;308 which block; new variant vs. new block). Wait for the answer.309- **Pause once before deploying (Phase 5)** whenever the plan contains any310 **inferred** (unannotated) mapping: show the final plan and get a single311 confirmation before the da.live write/preview — deploy is outward-facing and312 hard to reverse. Skip this pause only if the user pre-authorized an313 unattended run. A **fully annotated** plan needs no pause — the annotations314 are the authorization.315- **Flag an existing target page.** Before confirming, check whether the target316 `content/<PATH>.html` already exists in DA (a cheap Source-API `GET`, Phase 5);317 if it does, deploying **overwrites** it — say so in the plan and get explicit318 overwrite confirmation. Never silently clobber a page you didn't create, even319 on an otherwise pre-authorized unattended run. **Record two facts per path** for320 Phase 5 to enforce: `PLANNED_STATE` (`new` if the check returned 404, `exists`321 if 200) and `OVERWRITE_OK` (`yes` only when the user confirmed overwriting an322 existing page). Phase 5 re-checks existence right before writing and **refuses**323 if the state changed since planning (a page appeared in the gap) or overwrite324 was never confirmed — the plan-time check alone is not a license to clobber.325- The user can override any line.326327Never silently drop a section, and never deploy an **inferred** mapping the328user has not seen.329330**Worked example** — an unannotated 4-section frame; this is the plan you331present in 2.2 (one line per section):332333| # | Section | Decision | Conf. | Why | Content |334|---|---|---|---|---|---|335| 1 | Hero band — heading + 2 CTAs over a photo | reuse `hero` | high | model fits; heading **and** CTAs stay legible on the media under the theme | ok |336| 2 | 3 feature blurbs — icon + title + text | reuse `cards` | high | content model and rendered look both fit | ok |337| 3 | Metric strip — 3 big numbers + labels | **new block** `stat-cards` | high | bespoke panel look no existing block produces (3B) | ok |338| 4 | Newsletter row — heading + email field + button | **new block** / confirm | low | carries an interactive control (input) — ask keep vs. flatten (G5) | ⚠ placeholder copy |339340Then act on it: sections 1–2 build without blocking; #3 builds (high-confidence341new block); **#4 stops for a decision** (low-confidence + interactive control);342and because the plan contains inferred mappings, the whole thing gets **one343pre-deploy confirmation** before the da.live write. Section #4's ⚠ flag means344its real copy must be supplied before publish, not shipped as placeholder.345346### 2.3 — Lock the orchestration manifest (which sub-skills this plan requires)347348Turn the confirmed plan into an explicit **manifest** of the sub-skills it349requires and **invoke each one** — this is where the intro's *orchestrate, don't350inline* rule becomes a concrete, ticked list. This file's summaries never351substitute for loading the named skill.352353Derive the manifest from the plan:354355| The plan contains… | You MUST invoke |356|---|---|357| **Any** section (always) | **da-auth** (token) and **da-content** — load its real `references/html-content.md`, `platform.md`, and `media.md`, *not* the condensed rules in this file — before authoring (Phase 4) and deploying (Phase 5). |358| An **existing-block reuse** (3A) | **block-collection-and-party** (authoring model + a rendered example) **and testing-blocks** for the visual reuse gate (rendered block vs. the Figma section screenshot). |359| A **new block** (3B) | **content-modeling** (design the authoring model), then **content-driven-development** (which runs **building-blocks** and **testing-blocks**). Do **not** hand-write block JS/CSS from this file. |360| **Default content** (3C) | **da-content** only (no block skills). |361362Record the manifest as an evidence-bearing checklist and tick each item **only363after you actually invoked the skill** — "I know what it does" is not invocation,364and an un-invoked required skill means this phase is **not complete**:365366- [ ] **da-content** reference docs loaded (`html-content.md` / `platform.md` / `media.md`)367- [ ] **block-collection-and-party** invoked for every reused block *(if any 3A)*368- [ ] **content-modeling** + **content-driven-development** invoked for every new block *(if any 3B)*369- [ ] **Default-content** sections authored via **da-content** alone — **no** block-building skills invoked for them *(if any 3C)*370- [ ] **testing-blocks** invoked — its browser render + visual comparison **is** the371 Stage B pre-publish check (Phase 5); a run with **no** browser available372 reports the page **preview-only, UNVERIFIED**, never "done".373374If the environment genuinely cannot run a required skill (e.g. no browser for375testing-blocks), **say so explicitly in the report and mark the affected checks376unverified** — never silently substitute this file's summary and call it passed.377378---379380## Phase 3A — Map content into an EXISTING block381382**Reuse gate — structure AND visual.** An existing block is a valid target383only when the section both (a) **fits the block's authoring model** (its384row/cell structure and field types) *and* (b) **matches the block's rendered385appearance** under the project theme, using only tokens and variants the block386already defines. Structural fit alone is **not** enough: if the section's387visual identity — bespoke layout, corner radius, shadow, decorative treatment —388lives in that block's own CSS, you cannot reproduce it without editing the389block (forbidden), so route the section to **Phase 3B** (new block). Global,390token-level differences (palette, fonts, type scale) do **not** break reuse —391they are absorbed once by retargeting the project's design tokens (see392Guardrails). **How to run the visual check — reuse testing-blocks, don't invent393one:** get a rendered example of the candidate block — its `liveExampleUrl`394(block-collection-and-party / block-inventory) or the project's own block395rendered at `localhost:3000` with the section's **actual** content — including396secondary text, captions, and CTAs over whatever background or media the block397places them on, not just placeholder cells — then follow **testing-blocks**'398browser/Playwright-MCP screenshot pass (mobile/tablet/desktop) and its "compare399implementation to design" step, comparing that screenshot against the Figma400**section screenshot** from Phase 1. Watch for treatments a block applies to401only its primary element: one that (say) whitens a heading over dark media but402leaves the supporting text and buttons at body color passes a structural check403yet renders that text illegibly — a divergence the token retheme cannot fix.404Divergence beyond what the token retheme explains ⇒ new block (or a new405variant), not reuse. This outcome is **blocking**: the section is not resolved406until its rendered look — that text included — is faithful, and the fix is a new407isolated block/variant, never an edit to the shared block. Recording the gap in408the plan and reusing the block anyway is a **plan note, not a fix** — the Phase 5409pre-publish gate treats such a box as failed.410411Once the gate passes, **invoke block-collection-and-party** to learn the block's412authoring model (its examples show the row/cell structure and variants) — read413the block from the skill, don't guess its model from its CSS source. Then pour414the Figma content into that structure:415416- **Text** → matching cells; preserve heading levels from the design.417- **Variants** → extra class tokens on the block (e.g. `cards highlight`).418 Only apply a variant the block actually defines. (Adding a *new* variant =419 modifying an existing block = Phase 3B, not 3A.)420- **Links/buttons** → a **standalone link** (the only content of its421 paragraph) auto-promotes to a button; wrap in `<strong>` for a primary422 button, `<em>` for secondary. Do not add `target="_blank"` (decoration423 handles external links). Validate the href's URL scheme and escape the424 link text/attributes before emitting — see Phase 4, *Sanitize everything425 derived from the design*. *(da-content html-content.md §8)*426- **Images** → Phase 4 (they need real URLs).427428---429430## Phase 3B — Create a NEW block (content + code)431432Only for sections Phase 2 routed here (a needed block is missing, or an existing433block's look diverges) — the **3B** case. **Guardrails (strict):**434435- Create **new, isolated block folders** only (`blocks/<new-name>/`).436- **Do NOT** skin this block by editing an existing block, `scripts.js`, or437 `head.html`, or by adding block-specific rules to global CSS — keep it438 self-contained under `blocks/<new-name>/`. *(Retargeting the project's439 global design tokens in `styles/styles.css` — the `:root` custom properties440 and base typography — is a separate, allowed project-theming step, not part441 of building this block; see Guardrails.)*442- New block **names and variant tokens** must obey EDS block-name rules443 (da-content html-content.md §3.3): lowercase alphanumeric + single hyphens,444 **no underscores, no double dashes, must not start with a digit**445 (`pricing-table` ✓, `pricing_table` / `2col` / `promo--wide` ✗). Names must446 be unique and not collide with existing blocks.447448**Build route — invoke content-driven-development (don't hand-write the block).**449Build every new block by **invoking content-driven-development** — not by writing450block JS/CSS from scratch off this file's summary. It invokes **content-modeling**451(design the authoring model from the Figma structure/tokens) then452**building-blocks** and **testing-blocks**, and produces a self-contained453`blocks/<name>/` — no source URL, no installed substrate, no page chrome, and no454global styles. That is the route that honors the 3B guardrails above, and its455testing-blocks pass is the block's Stage B verification (Phase 5). Build a **bespoke, one-off** section456the same way — it is still an ordinary isolated block, and "one-off" changes457nothing about how it is generated.458459> **Do not use snowflake here.** Snowflake converts an *already-rendered* page:460> it requires a reachable **Source URL**, **installs an overlay substrate** into461> the repo, and in block mode emits **header/footer fragments and global462> styles/tokens** — each of which violates this skill's constraints (isolated new463> block, don't touch globals, work from the **Figma frame**, not a live URL).464> Snowflake is the right tool for a *different* entry point — converting an465> existing static/rendered site — as noted under "When NOT to use".466467Use the Figma design context/tokens from Phase 1 as the source of truth for468layout and styling. New-block **CSS must target structure, not authored469classes** — inline wrappers like `<span class="…">` are stripped inside block470cells at delivery (da-content html-content.md §3.9), so a class you emit in a471cell will not survive.472473**Make the block responsive.** A Figma page frame is almost always a single474**desktop** width, but EDS pages are responsive. Author the block mobile-first475(or with explicit breakpoints) so a multi-column layout collapses to one column476on narrow viewports, and verify at mobile / tablet / desktop via477**testing-blocks** — don't ship a fixed desktop-width block. If the design478provides a **separate mobile frame**, use it to derive the breakpoint behavior479(what stacks, what hides, how type scales) — it's the *same page*, so it feeds480one responsive block, **not** a second page (see Inputs on frame variants).481482The new block's code must be **committed and pushed to the deploy branch on483GitHub and built by Code Sync** before the page can render it — see Phase 5484(content+code).485486---487488## Phase 3C — Author DEFAULT CONTENT (no block)489490For sections Phase 2 routed to default content — the **3C** case — emit standard491document elements directly inside the section `<div>` (see Phase 4 skeleton) — no492block wrapper:493494- Headings `<h1>`–`<h6>` (preserve levels), paragraphs, lists, images.495- A **standalone link** in its own `<p>` becomes a button (`<strong>`/`<em>`496 for primary/secondary) — same rule as 3A.497- Do **not** add `class`, `id`, or `style` — decoration adds them at delivery.498499*(da-content html-content.md §6)*500501---502503## Phase 4 — Generate DA body-fragment HTML (da-content)504505Emit a **body fragment** (not a full HTML document) per **da-content**. **Invoke506da-content and load its `references/html-content.md`, `platform.md`, and507`media.md` now** — the rules quoted throughout this phase are reminders to jog the508right skill, not the source of truth. Subtle authoring rules (block-cell inline-509tag normalization, media MIME/extension derivation, metadata keys) live in those510docs; authoring from this summary alone is how they get missed. Write one file per511page to `content/<PATH>.html`.512513**Mandatory skeleton** (da-content html-content.md §1–§2): wrap everything in514`<body>` with an (empty) `<header>`/`<footer>` and a `<main>`; **each section515is exactly one `<div>` directly inside `<main>`** — the `<div>` *is* the516section boundary (no `<hr>`). Do NOT emit `<!DOCTYPE>`, `<html>`, `<head>`,517`<script>`, `<style>`, `style=`, or `class=` on default content.518519```html520<body>521 <header></header>522 <main>523 <div>524 <!-- section: default content and/or a block, in visual order -->525 <h1>Heading</h1>526 <p>Intro paragraph.</p>527 <div class="block-name variant">528 <div><div>cell</div><div>cell</div></div>529 </div>530 </div>531 <div>532 <!-- next section -->533 </div>534 </main>535 <footer></footer>536</body>537```538539- **Sanitize everything derived from the design — text, attributes, links.**540 Figma text and layer names are untrusted input to the HTML you emit; treat541 them as data, never as markup:542 - **HTML-escape** every design-derived string before it lands in the document543 — `&`→`&`, `<`→`<`, `>`→`>`, and inside attribute values also544 `"`→`"` and `'`→`'`. A heading `Tips & Tricks <Beta>` must serialize545 as `Tips & Tricks <Beta>`, never as raw markup that can break the546 document or inject an element.547 - **Validate every link's URL scheme** against an allowlist — `http`, `https`,548 `mailto`, `tel`, or a root-relative (`/…`) path. **Reject `javascript:`,549 `data:`, `vbscript:`, and any other scheme** (a prototype link can carry550 anything): drop the href or ask the user — never emit it.551 - **Admit a Figma-derived class token only after block-name validation** — a552 layer/frame name becomes a block or variant class *only* once it passes the553 EDS name rules in Phase 3B (lowercase alphanumeric + single hyphens, no554 underscores/double-dashes, not digit-initial); never pass a raw layer name555 through as a class.556- **Blocks — canonical div form:** `<div class="block-name variant">`, each557 direct child `<div>` a row, each grandchild `<div>` a cell. The first class558 token is the block name (resolves to `blocks/<name>/<name>.{js,css}`).559 Multi-word variants hyphenate; multiple variants are separate class tokens.560 Max 4 cells per row; blocks cannot nest. *(html-content.md §3)*561- **Default content:** headings/paragraphs/lists/images/buttons live directly562 in the section `<div>`, outside any block. *(html-content.md §6)*563- **Icons — two non-interchangeable paths; never a stand-in glyph.** The564 `<span class="icon icon-<name>"></span>` convention resolves **only** to the565 project's Code Bus `/icons/<name>.svg`, so that SVG must be **committed to the566 repo `/icons/` folder and pushed on the deploy branch** (content+code path,567 same as block code) and return `200` on the branch host — uploading it to DA568 `/media` does **not** satisfy the span (it 404s and the icon silently vanishes).569 A DA-`/media` SVG must instead be referenced by **full URL on an `<img>`**, not570 an icon span. Get the real **SVG** in Phase 1; **never emit an emoji or Unicode571 glyph in place of a designed icon.** *(html-content.md §7)*572- **Images — MUST be full, fetchable URLs.** Figma render URLs expire, and573 **repo-relative paths (`/img/…`) render as `about:error`.** So: download the574 image bytes from Figma (Phase 1 asset URLs), **upload each binary to DA**575 (`PUT admin.da.live/source/{daOrg}/{daRepo}/<media-path>`), and reference576 `https://content.da.live/{daOrg}/{daRepo}/<media-path>`. External image URLs577 are also accepted (the preview sideloads them). Author a bare `<img alt="…">`578 and let the pipeline build the `<picture>`.579 - **Normalize format, extension, and MIME together — from the bytes, never the580 URL suffix.** Detect the real format from the image's magic bytes (or the581 asset's reported `format`), then make **all three agree**: the multipart582 `type=` MIME, the `<media-path>` file extension you PUT to, and the extension583 in the `content.da.live` URL you author. Design tools routinely export JPEG584 bytes under a `.png`-named asset; trusting the suffix gives you a `.png` path585 served as `image/jpeg` (or the reverse) — a latent corruption bug. A layer586 that *looks* vector (an icon, a logo, a shape) often comes back **rasterized**587 — `download_assets` returns it under `rawImages` with `svgAssets` empty — so a588 design that implies `.svg` can hand you PNG/JPEG bytes. Author each `<img>`589 extension from the bytes you actually downloaded, never from the layer's590 apparent type or name. Canonical591 mapping: JPEG→`.jpg`/`image/jpeg`, PNG→`.png`/`image/png`, WebP→`.webp`/592 `image/webp`, GIF→`.gif`/`image/gif`, SVG→`.svg`/`image/svg+xml`. If bytes593 and asset-reported format disagree, trust the bytes.594 *(html-content.md §9 + media.md)*595- **Section styling** → a `section-metadata` block **inside** the section596 (`Style` → CSS classes; other rows → `data-*`). *(html-content.md §4)*597- **Page metadata** → a single `metadata` block (exact class), placed as the598 **last element of the last section inside `<main>`** (never after `</main>`599 or in `<footer>`); keys like `title`, `description`, `image`, `template`,600 `theme`. **Author it from the design — don't leave it empty or a bare601 comment.** Derive `title` from the frame name or the page `<h1>`, `description`602 from the hero/intro copy (a concise real sentence, never lorem), and `image`603 from the primary/hero image's uploaded DA URL when the design has one. This604 block is **required** — the Phase 5 pre-publish gate blocks on its absence — so605 populate it rather than deferring it. If the design offers no usable606 title/description text, ask the user rather than inventing marketing copy.607 *(html-content.md §5)*608609Inside block cells the pipeline runs a stricter inline-tag normalization than610for default content — `<span class>` is unwrapped (class lost), `<b>`→`<strong>`,611`<mark>`→`<em>`, etc. Restrict cell content to the html-content.md §3.9 preserve612list. A wrong metadata **key** or block **field** silently corrupts output;613when unsure, read da-content.614615---616617## Phase 5 — Deploy to DA618619**If a DA MCP server is available in the session, use its tools** for auth and620source writes (da-auth and da-content both defer to it when present).621Otherwise use the Source API directly, below.622623```bash624# Two identities — keep them separate. DA (Document Authoring) and GitHub are the625# same org/repo in the standard EDS setup, but nothing guarantees it, so never626# assume one from the other. DA endpoints (admin.da.live/source, content.da.live,627# da.live/edit) use the DA pair; the render host and admin.hlx.page (code, preview,628# live) use the GitHub pair.629DA_ORG=<da-org> # Document Authoring org630DA_REPO=<da-repo> # Document Authoring repo/site631GH_OWNER=<gh-owner> # GitHub owner632GH_REPO=<gh-repo> # GitHub repo633# In the standard setup all four match: DA_ORG=GH_OWNER=<owner>, DA_REPO=GH_REPO=<repo>.634BRANCH=<branch> # git deploy ref (usually main). For content+code this MUST be635 # the branch the new-block code was pushed to and Code Sync built.636BRANCH_HOST=${BRANCH//\//-} # host label: slashes → dashes ('feature/x' → 'feature-x').637 # Used BOTH for the aem.page/aem.live hostname AND as the ref638 # segment in every admin.hlx.page path (code/preview/live): that639 # ref is a SINGLE path segment, so a slashed branch ('figma/x')640 # splits it and 404s — pass the dashed label ('figma-x'), which is641 # what AEM actually resolves. Only git itself (push/checkout) uses642 # the literal slashed $BRANCH. For a slash-free branch the two643 # forms are identical, so $BRANCH_HOST is always the safe choice644 # for admin.hlx.page.645P=<path-without-extension>646TOKEN="$DA_TOKEN" # from da-auth; 401 w/ empty body ⇒ expired, re-auth647648# Fail fast if the branch host would be unresolvable (>63 chars won't resolve).649host="$BRANCH_HOST--$GH_REPO--$GH_OWNER"650[ "${#host}" -le 63 ] || { echo "❌ branch host '$host' is ${#host} chars (>63) — won't resolve; use a shorter branch/repo/org"; exit 1; }651652# --- checked-request helper: every call asserts its status; a bare `curl -sS`653# exits 0 on 401/403/409/5xx, so an unchecked curl silently "succeeds" on a654# failed write. req <expected-codes> <curl-args…>: prints the body, retries a655# few times on network/429/5xx, and aborts (non-zero) on any other mismatch.656# Use it for every PUT/POST below; if a DA MCP server is used instead, apply657# the same rule — assert the returned status, don't assume success. ---658req() {659 local expect="$1"; shift660 local attempt out code body661 for attempt in 1 2 3 4 5; do662 if out=$(curl -sS -w $'\n%{http_code}' "$@"); then code="${out##*$'\n'}"; else code="000"; fi663 body="${out%$'\n'*}"664 case ",$expect," in *",$code,"*) printf '%s' "$body"; return 0;; esac665 case "$code" in666 000|429|5??) sleep $((attempt * 2)); continue;; # transient — bounded retry667 401) echo "❌ 401 (empty body ⇒ token expired) — re-auth (da-auth) and retry" >&2; return 1;;668 *) echo "❌ HTTP $code (expected $expect) — $*" >&2; return 1;; # 4xx: do not retry669 esac670 done671 echo "❌ giving up after retries (last status $code) — $*" >&2; return 1672}673674# --- content+code path ONLY: block code must be LIVE before the pag675676…(truncated)