CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/stardust

Redesign an existing website to make it better. Built on top of impeccable.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

encode-contract.mdskills/deploy/reference/

stardust:deploy: the ENCODE contract

The text of this part of skills/deploy/SKILL.md, which keeps the heading and points here. "Above" and "below" refer to the order of the sections in that file.

The ENCODE contract — what well-authored content looks like

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

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

Structural rules (the lint's 🔴 tier):

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

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

  • Fully-qualified URLs in authored content (D4) — for MEDIA and EXTERNAL targets. Authors treat URLs as opaque tokens; code extracts pathnames. (Image-src specifics: see Images below.) Internal links to pages in the migration set are root-relative (/path, extensionless; a trailing slash only on a folder index): D4 is a capture-fidelity rule, never a delivery rule — localize-links.mjs (§ Deploy) rewrites captured source-host hrefs whose target exists locally and reports the ones that don't.

  • No HTML, CSS, or JSON visible as TEXT in any cell (D15). A <tag>, a { } binding, a CSS rule — or a bare CSS declaration / value (padding: 200px 10px 10px 50px, #1473e6, --accent: …, 48px) — appearing as author-visible text is a modeling mistake — code lives in the repo, not in documents. The lint flags a cell (or default-content paragraph) whose text IS a CSS declaration, a custom-property assignment or a bare length 🔴, and a lone hex colour 🟡 (davids-model-lint.mjs, D15). This includes inline-script text a scraper lifted as copy (try { window.X.wcm… }, campaign tokens like SPOFFCAR_PARTNER): a live-DOM importer reading textContent picks up <script> bodies and analytics tokens as paragraphs, and a keep-first-N cap then keeps the junk and drops the real sentence (recorded, two sections). Every text-collection step in an importer needs a standing exclusion list applied BEFORE any cap; the lint flags window./try {/function ( as text 🔴 and ALL_CAPS_TOKEN lookalikes 🟡.

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

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

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

  • Key facts live in SERVER-RENDERED page content, never solely in chrome or a fragment (#86, D12). /nav, /footer and fragment links are fetched client-side, so copy that exists only there is invisible to non-rendering crawlers; author citable facts on the page and verify by grepping the RAW served HTML. Full reasoning, the checker formula and the chrome trade-off: reference/ai-readability.md.

  • decorate() adds no words to the DOM (#100). Every visible string is authored; loop clones are presentational (no text, alt="", no href); listings are document-first (authored rows, index for non-text and top-up); generated text only for runtime values, allowlisted by block + string. Adobe's AI Content Visibility Checker scores served words ÷ rendered words — words the block adds are the whole defect, hidden text and chrome are not (reference/ai-readability.md).

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

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

  • Per-instance VISUAL variation is a NAMED VARIANT, never authored CSS (#134, D6/D15). When sibling units of one block (carousel slides, cards) differ in padding, offset, colour or alignment — each slide's copy hand-positioned around its artwork via an inline style="…" — the #90 fingerprint flags it and the tempting encoding is a knob cell (padding: 200px 10px 10px 50px) that decorate() copies into el.style. Recorded: a Magento PageBuilder slider whose three slides each carried their own overlay padding; the block ported that per-slide style as a padding: …; size: auto config cell tagged @ew-exempt config, so the editability gate counted it exempt, the lint knew only full prop: value; } rules, and the author saw CSS as body text in DA. A page-builder source (PageBuilder, Elementor, AEM-classic inline styles) stores per-instance style IN its content — that is the source's model, never ours; port the look, not the field. The encoding that keeps BOTH fidelity and authoring flexibility: each fingerprint cluster becomes one variant word — ONE plain word from a documented closed set (left / right, dark / light) in a dedicated cell present on EVERY row (aligned rows, D3), or a block variant class when it applies to the whole block. decorate() maps the word to a class (slide-cta-right), the block CSS carries each variant's exact source values, an empty or unknown word falls back to the declared default, and the JSDoc declares the vocabulary with @variants <cell>: left | right (default left) so the editability probe can fail an undeclared or misspelled word (EW5 keys the cell metadata). Budget: D6/D9 — more than 3–4 words means a design decision is being delegated; then collapse the closest clusters into one treatment and log the normalisation in the replica's inconsistency register (also the move for sub-16 px deltas that no one would ever choose). Never a declaration, a length, a colour, a class name or a --token: value in a cell, and never el.style.x = text / setProperty(…, text) / setAttribute('style', text) from authored content in block JS; no @ew-exempt tag covers such a cell — the probe reports it dead (#134).

  • Whitespace-only content never survives the pipeline (#112) — <p>&nbsp;</p> spacer paragraphs and trailing <br>&nbsp; are dropped. When the SOURCE renders real line boxes from them (AEM-classic richtext does), model those heights as block CSS (padding/margin), never as authored whitespace — the drop is silent and only a pixel probe sees the missing height.

  • Never author <hr> — it is the SECTION DELIMITER (#119). In DA/EDS authoring an <hr> splits the document into sections; authored inside a section it silently fractures that section into several, and every downstream section selector and style breaks. For a visible horizontal rule, author an empty section carrying a section-metadata style value and draw the line in CSS (a border or ::after). The lint blocks it (🔴).

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

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

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

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

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

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

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

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

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

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

Images: editorial → authored content, decorative → CSS only

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

  1. Upload the binary to DA: PUT https://admin.da.live/source/{org}/{repo}/media/<scope>/<file> (multipart, field name data, correct Content-Type; upload the JPG/PNG/webp source only — the pipeline generates responsive variants). The shipped uploader does this for a whole folder or manifest and prints the URL to author per file — DA_TOKEN=… node skills/deploy/scripts/da-media-upload.mjs --org <org> --repo <repo> --scope <name> --dir stardust/current/assets/media (--scope is the folder UNDER media/ — never media/<name>: the path would double to media/media/<name>, the script refuses it, a recorded run uploaded and deleted 242 files that way; --manifest <json> for the extract media list; --help for the rest): it skips non-images except mp4 (#161), refuses the unsafe SVGs below, keeps a resumable ledger, tells a source 403 from a 404, and proves the token with its first upload run alone (a 401 retries like a 429; only one that persists there halts, with the re-run instruction). Never hand-roll the PUT loop (one recorded run wrote a 112-file upload script from scratch). SVGs: pure-vector AND small (#99). An authored SVG that embeds raster data (<image>/data:image base64 behind a pattern fill — common for exported award badges/logos) makes the preview of EVERY page that references it fail 409 "error from content-bus", with no per-asset error. So does an SVG over ~40KB (a hard pipeline limit — even pure-vector; also surfaces only at preview, never at upload). Extract the embedded raster (data:image/png;base64,… → .png) or rasterize the oversized vector, and author the PNG; small pure-vector SVGs (logos, icons) ingest fine. The lint flags authored .svg media URLs as an advisory. When a preview 409 has no obvious culprit, run the two-step diagnosis in da-deploy-protocol.md step 3a (known-good doc to the same path, then the per-image SVG sweep) instead of dead-ending on the opaque error.
  2. Author a single <img src="https://content.da.live/{org}/{repo}/media/<scope>/<file>" alt="…"> in the cell (branch-independent; the pipeline emits the responsive <picture>). Never a repo-relative /img/… in content (→ <img src="about:error">). Never bake imagery into block JS by index (CARD_IMAGES/LOGOS) — that isn't authorable.
  3. The block renders the authored <img> into a background LAYER (.hero-bg / .card-media / .text-media); the scrim/gradient is a CSS ::before OVER it. Keep a fixed CSS asset as the no-image fallback. Never copy the pipeline's fallback <img src> into a CSS background (#110) — it carries width=750 (the smallest rendition), so a full-bleed layer renders soft at any hero width; rewrite the width param (width=2000) first. <picture>-rendered images are unaffected (the browser picks a real rendition).
  4. The <picture> wrapper adds an inline baseline descender (#111): the pipeline's <p><picture>… leaves the image inline on the text baseline — each image paragraph measures +6/+7px vs a bare-<img> source, systematic and invisible to text gates. line-height: 0 on the image paragraph restores parity.

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

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

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

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

Rehost from the CAPTURED src — never a reconstructed/guessed URL (#118). Asset CDNs (commerce catalogs especially) answer HTTP 200 with a GENERIC FALLBACK image for a wrong path — nothing errors, and the wrong pixels ship (recorded: six product images uploaded from guessed catalog URLs; the CDN served the same placeholder for all six, every status green). Always fetch from the exact URL string the lift/extract recorded (the capture map / stardust/current/assets/ inventory), and before uploading, diff the fetched asset's dimensions and byte size against the captured copy — on a fallback-serving CDN a 200 alone proves nothing.

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

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

Video: never author its content.da.live URL (#103, #161). The preview rehosts <img>/<picture> only; a content.da.live/....mp4 link reaches the <video src> verbatim and answers 401 to every visitor (poster-only, silent). An mp4 ≤ 36 MB goes through da-media-upload.mjs, which stores it under its web name (_ → -, lowercase), previews and publishes it, and prints the root-relative path to author (redirected to the media bus). A repo mp4 404s in DA's Layout view (preview.da.live serves no code-bus video); never commit the same path. Bigger mp4s, other formats, audio and PDF ship from the CODE ORIGIN (root-relative, #67) or an external host. The poster stays an editorial <img>.

skills

README.md

tile.json