Prompting Guide for Experience Modernization Agent prompting-guide

Migration follows a seven-step workflow:

1. The agent scrapes source page.
2. It identifies section structure.
3. It performs authoring analysis.
4. It maps the content to block variants.
5. It generates markdown.
6. It creates import infrastructure.
7. It previews the result.

The agent analyzes pages using a two-level hierarchy:

• First it identifies section boundaries (background changes, spacing shifts)
• Then it identifies content sequences within each section.

Authoring analysis follows David’s Model.

• for each content sequence, it first checks “Can an author create this by normal typing?”
• Default content (headings, paragraphs, lists, inline images) is preferred over blocks.

The agent attempts to reuse existing blocks from the repository’s block library before creating new ones.

• When content can not be mapped to an existing block, it creates new block variants.
• You can prompt for changes, request new variants, or adjust mappings interactively.

Block variants are tracked with metadata.

• When migrating multiple pages, the agent loads existing custom variants first and reuses them when styling matches (70% similarity threshold based on purpose, colors, typography, spacing, layout).

Header, navigation, and footer are excluded from page migration. These are handled by dedicated skills.

Each migration creates import infrastructure (page templates, block parsers, transformers) for future bulk imports.

• This includes page templates (section structure), transformers (site-wide DOM cleanup), and parsers (block-specific HTML to table conversion).

• It does not infer templates from scratch.

• Mixing templates in a single run is not supported.

This prompt is usually invoked automatically as the first step of page migration.

Content hidden via CSS is captured too if present in the DOM.

Lazy-loaded images and client-side rendered content is handled by scrolling through the page in headless Chromium and letting scripts execute.

WebP/AVIF/SVG images are converted to PNG for compatibility.

Metadata is extracted including title, description, Open Graph tags, JSON-LD structured data, canonical URL.

Images in DOM are fixed.

• background-image is converted to img.
• Picture elements are unwrapped
• srcset is resolved to src
• Relative URLs are converted to absolute
• Inline SVG to are converted to img files.

Sanitized document paths are generated (lowercase with no .html extension).

The following outputs are produced:

• screenshot.png
• cleaned.html (no scripts/styles)
• metadata.json
• images/ folder with local copies

Users can ask about screenshot dimensions and request specific device sizes (mobile, desktop) for content extraction.

Extracting content at multiple breakpoints increases processing time.

Design migration has two phases:

1. Phase 1 (site-wide) extracts the following to styles/styles.css:

   • Global color palette and accent colors
   • Typography system (fonts, sizes, weights)
   • Spacing system (padding, margins, gaps)
   • Section backgrounds (light, dark, colored)
   • Base component styles (buttons, links, images)
   • Outputs to

2. Phase 2 migrates individual block styles and creates block-specific CSS in /blocks/{name}/{name}.css.

Block styling (phase 2) requires site-wide design (phase 1) to be complete first.

• The global design system provides CSS custom properties that blocks reference.

Estimated time:

• Phase 1: 5-10 minutes
• Phase 2: 10-15 minutes

Ambiguous requests default to complete migration (both phases).

Block critique compares a migrated block against its original source and iteratively applies CSS fixes until an 85% visual similarity is achieved or three iterations are completed.

The skill requires the block to have been created by page migration first.

A block critique follows a six-step workflow:

1. It captures the original block from source page using an XPath selector.
2. It initializes the critique session.
3. It inspects the original block (screenshots, styles, HTML).
4. It inspects the migrated block.
5. It compares elements and generates a similarity score with CSS fixes.
6. It applies fixes and re-inspects until the 85% target is reached.

Each iteration displays a complete critique report with all differences, applies all CSS fixes (prioritized by visual impact), verifies in preview, re-inspects, and shows improvement metrics.

Use the block critique after design migration is complete.

Page critique performs a full-page visual comparison between the original and the migrated page, iterating until reaching an 85% similarity target or three iterations are completed.

A page critique has a five-step workflow:

1. It Initializes a critique session.
2. It inspects all elements on the original page.
3. It inspects all elements on the migrated page.
4. It compares and generates a similarity score with prioritized CSS fixes.
5. It applies fixes and re-inspects until the 85% target is reached.

A page critique needs the source page URL and the migrated path (e.g.,“/about”) as input.

Use page critique when validating overall page fidelity or validating multiple blocks simultaneously.

Use block critique for focused validation on specific components.

The following workflow is recommended:

1. Migrate a page.
2. Apply a design.
3. Run a block critique on key blocks
4. Run ap age critique for full validation.

This skill migrates one block at a time, not entire pages or full Figma files.

For best results:

• Select the specific block you want to migrate in Figma and copy its link (with node-id) or name.
• Provide the node-id parameter in the URL to target the exact block.

When you run this skill, the following steps are performed automatically in the hosted environment:

1. Block structure discovery — The agent reads the Figma node to understand layers and components.
2. Global style extraction — The agent pulls colors, typography, and spacing into styles/styles.css as CSS custom properties (design tokens).
3. Block-specific style creation — The agent creates additional CSS custom properties specific to the block being migrated.
4. Mapping to existing blocks — The agent identifies the closest matching block in your project’s block library and creates a custom variant.
5. CSS generation — The agent writes styles that reference the extracted CSS custom properties, ensuring design consistency.
6. Asset download — The agent saves images and icons from Figma to the hosted environment’s workspace.
7. Edge Delivery Services content generation — The agent creates the markdown file following EDS block structure
8. Output validation — The agent previews the result and performs visual comparison against the original Figma design.

The skill first reads metadata (step 1) to understand structure, and then extracts detailed design context (steps 2-5).

• This phased approach prevents issues with large or complex Figma files.

This skill takes a styles-first approach.

• All styles are extracted as CSS custom properties (design tokens) before any CSS is written.
• This ensures the migrated block stays consistent with your design system.

The prompt requires the Figma URL (with fileKey and optional node-id) or a Figma file key directly as input.

Edge Delivery Services navigation enforces a three-section structure (enforced by header.js):

1. Brand (section 1): Logo and primary branding link
2. Sections (section 2): Main navigation menu with optional dropdowns
3. Tools (section 3): Utility links (subscribe, login, cart)

Navigation content lives in nav.md in the root directory.

Sections are separated by (---) markers.

Bold items (**Text**) with nested lists create dropdowns.

Links in navigation may render as buttons due to Document Authoring’s auto-wrapping behavior.

• The header block includes code to strip button classes from nav links.

The agent follows Content-Driven Development (CDD), a mandatory process for all Edge Delivery Services development.

• It will ask about content models and test content before writing code.

The CDD philosophy is that author needs come before developer needs.

• Content models must be intuitive for authors, even if that means more complex decoration code.

Creating test content first provides:

• Immediate testing capability
• PR validation links for PSI checks
• Living documentation for authors
• Discovery of edge cases that code-first approaches miss

The agent will search for similar blocks in the Block Collection and Block Party before implementing, to find patterns and reusable code.

Skip CDD only for trivial CSS-only tweaks (but still identify test content for validation).

Edge Delivery Services has four canonical model types:

• Standalone: Distinct visual/narrative elements (hero, blockquote)
  • Single table with block content
• Collection: Repeating semi-structured content (cards, carousel)
  • Table with repeating row pattern
• Configuration: API-driven or dynamic content where config controls display (blog listing, search results)
  • Table with key-value config rows.
• Auto-Blocked: Complex structures that authors create as sections/default content, then get transformed (tabs, YouTube embeds)

There is a limit of four cells per row.

• Group related elements into cells.

Prefer block variants over config cells for styling differences.

Follow Postel’s Law: Be flexible about input structure.

• A hero block should work whether content is in one cell, split across two cells, or in separate rows.

This skill is usually invoked automatically by Content-Driven Development during block creation.

The Block Collection is Adobe-maintained and vetted for best practices, excellent content modeling, high performance, and accessibility.

• It is limited to commonly-needed blocks. Start here.

The Block Party is community-driven and offers a broader variety including experimental approaches.

• It also includes sidekick plugins, build tools (webpack, vite, sass), and integrations.
• Use when the Block Collection doesn’t have what you need.

Think about alternative names when searching

• FAQ = accordion
• Gallery = carousel/slideshow
• Navigation = menu/header

The Block Party only returns approved/curated entries.

Testing follows a “value vs. cost” philosophy where you create and maintain tests when their value exceeds cost.

• Keeper tests (unit tests) are for logic-heavy utilities, data processing, API integrations. These are fast, easy to maintain, and catch regressions in reused code.
• Throwaway tests (browser tests) are for DOM transformations and visual validation. Use to validate implementation, capture screenshots for PR review, then discard.

Throwaway tests go in test/tmp/ and test content in drafts/tmp/ (both gitignored).

Before opening a PR, ensure that:

• Existing tests pass
• Unit tests are written for new logic
• Browser validation is complete
• All variants are tested
• Responsive behavior is verified
• Linting passes

Common issues have known patterns:

• Images showing “about:error”: Usually missing createOptimizedPicture call in block JS, or called before DOM restructuring
• Blocks not rendering: Check block name format in markdown and verify that the block has both .js and .css files in blocks/.
• CSS not loading: Check file paths, verify CSS file exists, and check the Network tab in browser.
• Changes not appearing: Code sync takes 3-5 seconds. Try hard refresh (Ctrl+Shift+R).

The agent checks each layer systematically:

1. Source files
2. Rendered output
3. Block code
4. Browser console

The agent has the capability to check local previews at http://localhost:3000.