Page Decomposition

Analyze content sequences within a section and provide neutral descriptions without assigning block names.

When to Use This Skill

This skill is called by identify-page-structure for EACH section to:

• Identify content sequences within that section

• Provide neutral descriptions (NO block names yet)

• Identify breaking points between sequences

• Enable authoring-focused decisions later

IMPORTANT: This skill analyzes ONE section at a time, not the whole page.

Input Required

From the calling skill (identify-page-structure), you need:

• Section visual description and boundaries

• Screenshot showing the section

• Cleaned HTML content for the section

Related Skills

• page-import - Top-level orchestrator

• identify-page-structure - Invokes this skill for each section (Step 2b)

• block-inventory - Provides available blocks AFTER decomposition

• content-modeling - Makes authoring decisions AFTER decomposition

• content-driven-development - References section structure in html-structure.md

Key Concepts

Content Hierarchy:

DOCUMENT

├── SECTION (top-level, analyzed by identify-page-structure Step 2a)

│   ├── Content Sequence 1 ← THIS SKILL IDENTIFIES THESE

│   ├── Content Sequence 2 ← THIS SKILL IDENTIFIES THESE

│   └── ...

└── SECTION

    └── Content Sequence 1

What is a "content sequence"?

A vertical flow of related content that will eventually become:

• Default content (headings, paragraphs, lists, inline images), OR

• A block (structured, repeating, or interactive component)

Breaking points between sequences:

• Visual/semantic shift in content type

• Change from prose → structured pattern

• Change from one pattern → different pattern

Philosophy:

• Describe WHAT you see, not WHAT it should be

• "Two images side-by-side" not "Columns block"

• "Grid of 8 items with icons" not "Cards block"

• Stay neutral - authoring decisions come later

Decomposition Workflow

Context: identify-page-structure has already identified section boundaries (Step 2a). This skill is invoked FOR ONE SECTION to analyze its internal content sequences.

Step 1: Examine the Section

Look at the screenshot and HTML for THIS section only.

What to observe:

• Vertical flow of content from top to bottom

• Where content changes type or pattern

• Visual groupings or breaks

Ignore:

• Other sections (out of scope)

• Section styling (already identified by page-import)

• Block names (stay neutral)

Output: Mental model of content flow within this section

Step 2: Identify Breaking Points

Find where content shifts from one type/pattern to another.

Breaking point indicators:

• Prose text → Structured grid

• Heading/paragraph → Side-by-side images

• One repeating pattern → Different repeating pattern

• Structured content → Prose text

Example within a section:

Content flows top to bottom:

- Large heading

- Paragraph

- Two buttons

[BREAK] ← Visual/semantic shift

- Two images displayed side-by-side

Output: List of breaking points

Step 3: Define Content Sequences

Between each breaking point is a content sequence.

For each sequence, describe:

• What elements it contains (heading, paragraph, images, etc.)

• How they're arranged (stacked, side-by-side, in a grid)

• Quantity (one heading, two images, grid of 8 items)

Use neutral language:

• ✅ "Two images displayed side-by-side"

• ❌ "Columns block with two images"

• ✅ "Grid of 8 items, each with icon and short text"

• ❌ "Cards block"

• ✅ "Large centered heading, paragraph, two buttons stacked vertically"

• ❌ "Hero block"

Output: Neutral descriptions for each sequence

Step 4: Return Structured Output

Provide content sequences for this section in structured format.

Output format:

{

  sectionNumber: 1,  // From identify-page-structure

  sequences: [

    {

      sequenceNumber: 1,

      description: "Large centered heading, paragraph, two buttons stacked vertically"

    },

    {

      sequenceNumber: 2,

      description: "Two images displayed side-by-side"

    }

  ]

}

This enables:

• Clear understanding of section's internal structure

• Neutral foundation for authoring decisions

• Separation of description from implementation

Section Metadata Format

Table format:

+------------------------------+

| Section Metadata             |

+------------------+-----------+

| style            | light     |

+------------------+-----------+

Placement: At the start of each section, before content

Usage: Applied by generate-import-html skill when generating final HTML

Examples

Example 1: Hero Section

Input: "Section 1 (light background): Large prominent content at top of page"

Visual observation:

• Large centered heading

• Paragraph text below it

• Two call-to-action buttons

[BREAK - visual shift]

• Two large images displayed next to each other

Output:

{

  sectionNumber: 1,

  sequences: [

    {

      sequenceNumber: 1,

      description: "Large centered heading, paragraph, two call-to-action buttons stacked vertically"

    },

    {

      sequenceNumber: 2,

      description: "Two large images displayed side-by-side"

    }

  ]

}

Example 2: Features Section

Input: "Section 2 (light background): Grid of feature items"

Visual observation:

• Centered heading

[BREAK - shift to structured pattern]

• Grid of 8 items

• Each item has: small icon, short text description

[BREAK - shift back to simple elements]

• Two centered buttons

Output:

{

  sectionNumber: 2,

  sequences: [

    {

      sequenceNumber: 1,

      description: "Single centered heading"

    },

    {

      sequenceNumber: 2,

      description: "Grid of 8 items, each with small icon and short text description"

    },

    {

      sequenceNumber: 3,

      description: "Two centered buttons"

    }

  ]

}

Example 3: Article Cards Section

Input: "Section 3 (grey background): Blog articles"

Visual observation:

• Eyebrow text "Latest Articles"

• Large heading

• Paragraph description

• Browse button

[BREAK - shift to repeating pattern]

• 4 items in grid

• Each item: image, category tag, heading, short description, read link

Output:

{

  sectionNumber: 3,

  sequences: [

    {

      sequenceNumber: 1,

      description: "Eyebrow text, large heading, paragraph description, browse button - all stacked vertically"

    },

    {

      sequenceNumber: 2,

      description: "Grid of 4 items, each with image, category tag, heading, description, and read link"

    }

  ]

}

Example 4: Simple Content Section

Input: "Section 4 (light background): Body content"

Visual observation:

• Multiple paragraphs of text

• Some inline images within the text

• Headings interspersed (H2, H3)

• No clear breaking points - content flows naturally

Output:

{

  sectionNumber: 4,

  sequences: [

    {

      sequenceNumber: 1,

      description: "Flowing prose content: multiple paragraphs with inline images and headings (H2, H3)"

    }

  ]

}

Note: This entire section is one sequence because content flows naturally without structural breaks.

Common Mistakes to Avoid

Using block names in descriptions:

❌ "Hero block with heading and buttons"

✓ "Large centered heading, paragraph, two buttons stacked vertically"

Not identifying breaking points:

❌ Describing entire section as one sequence when there are clear shifts

✓ Identifying where content type changes and breaking into sequences

Being too granular:

❌ Each element as separate sequence: "Heading", "Paragraph", "Button"

✓ Related elements together: "Heading, paragraph, two buttons stacked vertically"

Mixing analysis levels:

❌ Analyzing multiple sections at once

✓ Focus on ONE section at a time (per invocation)

Making authoring decisions:

❌ "This should be a cards block because..."

✓ "Grid of 4 items with images and text" (neutral description)