CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/aem-edge-delivery-services

Skills for building AEM Edge Delivery Services sites — site creation, block development, content modeling, code review, testing, and page import.

Quality

91%

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

block-level-feasibility.mdskills/snowflake/knowledge/

Block-Level Feasibility — When to Use Block-Level vs Page-Level Conversion

Reference for the Analyze phase. After segmenting the source page into sections, evaluate whether each section can be converted to a standalone EDS block (block-level) or must stay in the page template (page-level).

Block-level conversion means: each content section becomes an independent EDS block with its own decorate() function, its own CSS file, and its content authored in a DA block table. The block JS reads authored rows and builds the source DOM structure (the "block-level template"). Header and footer remain static fragments.

Page-level conversion means: the standard snowflake overlay — one template with [data-slot] markers, one CSS file, DA doc with slot-keyed rows, overlay engine merges at runtime.

Quick decision

Block-level is the right choice when the source page has all of:

  1. Clear section boundaries in the DOM
  2. CSS scoped per-section
  3. Content that maps to DA block tables
  4. No cross-section JavaScript coupling
  5. Sections that render independently

If any section fails, that section uses page-level. If most sections fail, the whole page uses page-level.

The five checks

Run these during the Analyze phase, after identifying the header/footer boundaries and the main content sections.

1. Structural clarity

Look at the source DOM. For each content section between header and footer:

Pass — the section is:

  • A <section> or <div> with a unique, descriptive class name
  • A direct child of <main> (or of <body> when <main> is absent)
  • Self-contained: no sibling elements that visually belong to this section but sit outside it

Fail — the section is:

  • A fragment of a larger <div> with no clear boundary
  • Interleaved with another section's elements
  • A utility-class wrapper (<div class="flex flex-col gap-8">) with no semantic identity
  • Deeply nested in layout scaffolding (3+ levels of wrapper divs between <body> and the section content)

How to check:

# Count direct children of <main> (or <body>)
# Each should be a clear section
document.querySelectorAll('main > *').length
# vs total section-like elements
document.querySelectorAll('section, [data-section]').length

2. CSS scope

For each section, check whether its CSS rules are self-contained.

Pass — all of:

  • CSS rules for this section are prefixed with its class name (.hero .xxx, .shop-categories .xxx)
  • No layout rules (grid, flex, position) on a parent that spans multiple sections
  • No sibling combinators between sections (section.hero + section.cards { ... })
  • Design tokens (:root custom properties) are cleanly global — not section-specific variable names reused with different values

Fail — any of:

  • Utility-class CSS (Tailwind, Bootstrap utility layer) where styles live on individual elements, not in section-scoped rules
  • A page-level grid/flex container that positions sections as children (body { display: grid; grid-template-rows: ... })
  • Shared class names across sections with different visual intent (.card means different things in different sections)
  • CSS that targets elements by position rather than class (:nth-child(3) > div > p)

How to check:

# For each section class, count CSS rules that use it as a prefix
grep -c '\.sectionClass' styles.css

# Check for cross-section selectors
grep -E '\.[a-z-]+\s*\+\s*\.' styles.css    # sibling combinators
grep -E 'body\s*>' styles.css                # body-level layout

3. Content model fit

For each section, check whether its authorable content (text, images, links) maps cleanly to DA block table rows.

Pass — the section contains:

  • Headings, paragraphs, eyebrow/label text → text rows
  • Images (<img>, <picture>) → image rows
  • Links and buttons (<a>, <button> with labels) → link rows
  • A fixed or small-N repeating structure (e.g., 5 cards) → one row per item
  • Interactive form elements that are structural (search input, email signup) → generated by the decorator, not authored

Fail — the section contains:

  • Complex multi-field forms (contact form, checkout, configurator)
  • Data-driven content (product listings from an API, live feeds)
  • Deeply nested interactive trees (accordion → tabs → cards → modal)
  • Content that changes shape dynamically (filter results, infinite scroll)
  • Embedded third-party widgets (maps, chat, video players with custom controls)

Judgment call — these can go either way:

  • Repeating items where the author needs to add/remove (not just edit): works in DA but authoring UX is less clean
  • Rich text with complex inline formatting: works if the pipeline's inline-tag normalization (da-content, Inline tags) preserves what's needed
  • SVG icons embedded inline: stay as decorator chrome, not authored

4. JavaScript independence

Check whether any JavaScript in the source creates dependencies between sections.

Pass — any of:

  • No JavaScript at all (pure CSS page)
  • Only scroll animations (IntersectionObserver per section, GSAP timelines per section)
  • Only per-section interactivity (accordion toggle, carousel within one section)

Fail — any of:

  • Global state that multiple sections read/write (filter panel in section A affects product grid in section B)
  • Scroll-sync between sections (parallax where section A's scroll position drives section B's transform)
  • DOM traversal across sections (document.querySelector('.hero').nextElementSibling)
  • Event delegation on a parent element that spans sections
  • Shared animation timeline across section boundaries

How to check:

# Look for cross-section DOM queries
grep -n 'querySelector.*section\|closest.*section' script.js

# Look for global state patterns
grep -n 'window\.\|document\.body\.' script.js

5. Visual independence

Check whether each section can render correctly without its siblings.

Pass — the section:

  • Has its own background color/image (not transparent, relying on a parent's background)
  • Has its own padding/margin (doesn't depend on adjacent sections for spacing)
  • Has no z-index stacking that depends on sibling order
  • Has no absolute/fixed positioned elements that visually overlap other sections
  • Has no CSS clip-path or overflow: hidden on a parent that clips across section boundaries

Fail — the section:

  • Uses background: transparent and relies on a page-level background gradient that spans multiple sections
  • Has decorative elements (::before/::after) that visually extend into adjacent sections
  • Uses position: absolute relative to a container that wraps multiple sections
  • Has a "bleed" effect (image or shape extends beyond section bounds into the next)

How to check (visual test): Render each section in isolation (wrap in a minimal HTML page with only global styles). If it looks correct alone, it passes. If it looks broken or incomplete, it fails.

Scoring and decision

After running all five checks on each content section:

ResultRecommendation
All sections pass all 5 checksBlock-level conversion — each section becomes an EDS block
Most sections pass; 1-2 failHybrid — passing sections become blocks; failing sections become static fragments (like header/footer)
Most sections failPage-level conversion — standard snowflake overlay
Utility-class CSS throughout (Tailwind, Bootstrap utilities)Page-level — CSS extraction per-block is impractical
Complex JS coupling across sectionsPage-level — block independence is impossible

The hybrid option

When a few sections fail, they can stay as static fragments or become "passthrough" sections in the template. The passing sections still become blocks. This is the most common real-world outcome — most pages have some sections that are block-friendly and some that aren't.

Example: a page with a clean hero, clean cards grid, clean CTA band, but a complex interactive product configurator in the middle. The configurator becomes a static fragment or a custom block with no DA authoring. Everything else is block-level.

Signals from the source

Quick heuristics to assess feasibility before running the full five checks:

Strong signals for block-level:

  • Source was hand-crafted or generated by a design-aware tool (Stardust, Framer, Webflow in custom-code mode)
  • CSS uses BEM or section-scoped naming (.hero__title, .hero .title)
  • <section> elements with semantic class names
  • Design tokens in :root with a clear naming system
  • Each section has a distinct background color/treatment

Strong signals for page-level:

  • Source uses Tailwind, Bootstrap utilities, or similar utility-first CSS
  • No <section> elements — content is a flat list of divs
  • CSS file is one large unstructured block
  • Heavy JavaScript framework (React/Vue/Svelte SPA) with hydration state
  • Complex page-level layout (CSS Grid on body with named areas)

Ambiguous — need the full five checks:

  • WordPress theme output (varies wildly by theme)
  • Squarespace / Wix exports (sometimes clean, sometimes not)
  • AI-generated pages (depends on the generator and prompt)
  • Design-to-code tools (Figma plugins, Locofy, Anima)

Integration with the snowflake workflow

This analysis happens in Phase 2 (Analyze), after capturing the source and identifying header/footer boundaries. The output is a decisions.json field:

{
  "conversionLevel": "block-level" | "page-level" | "hybrid",
  "sections": [
    {
      "name": "hero",
      "level": "block",
      "checks": {
        "structure": "pass",
        "cssScope": "pass",
        "contentModel": "pass",
        "jsIndependence": "pass",
        "visualIndependence": "pass"
      }
    },
    {
      "name": "configurator",
      "level": "fragment",
      "checks": {
        "structure": "pass",
        "cssScope": "pass",
        "contentModel": "fail — complex multi-step form",
        "jsIndependence": "fail — reads global filter state",
        "visualIndependence": "pass"
      },
      "failReason": "Interactive widget with cross-section state"
    }
  ]
}

Phase 3 (Generate) reads conversionLevel and follows the corresponding path:

  • block-level: generate block JS/CSS per section + DA block tables
  • page-level: generate template + slots + DA slot-keyed rows (standard snowflake)
  • hybrid: mix of both — blocks for passing sections, template sections for failing ones

Worked example: Frescopa (block-level)

Source: AI-generated (Stardust), single-page, 9 sections.

SectionStructureCSS scopeContent modelJSVisualLevel
promo-strip✅ <header class="promo-strip">✅ .promo-strip .xxx✅ text + link✅ none✅ own bgfragment (header)
site-header✅ <header class="site-header">✅ .site-header .xxx✅ logo + nav links✅ none✅ own bgfragment (header)
hero✅ <section class="hero">✅ .hero .xxx✅ image, text, links✅ none✅ own bg + photoblock
shop-categories✅ <section class="shop-categories">✅ .shop-categories .xxx✅ heading + 5 card rows✅ none✅ own bgblock
subscription✅ <section class="subscription-card-on-bay">✅ scoped✅ text + image + link✅ none✅ own bgblock
locations-finder✅ <section class="locations-finder">✅ scoped✅ text + form (structural)✅ none✅ own bgblock
featured-coffee✅ <section class="featured-coffee">✅ scoped✅ image + text + link✅ none✅ own bg (porcelain)block
rewards-cta-band✅ <section class="rewards-cta-band">✅ scoped✅ text + link✅ none✅ own bgblock
site-footer✅ <footer class="site-footer">✅ .site-footer .xxx✅ columns + links✅ none✅ own bgfragment (footer)

Result: all sections pass → block-level conversion.

skills

README.md

tile.json