# Detecting and Extracting Layered Background Images versus Overlay Images in Web Pages

> Learn how to detect and extract layered background images versus overlay images in web pages with our AI Website Cloner. Analyze DOM hierarchy for accurate asset classification.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-07-09

---

**The AI Website Cloner Template implements a two-step browser automation pipeline that enumerates every `<img>` element and computed CSS `background-image`, then analyzes DOM hierarchy (sibling counts, z-index, and positioning) to classify assets as layered backgrounds or overlay images before persisting them to role-specific directories.**

Detecting and extracting layered background images versus overlay images in web pages requires distinguishing between CSS background layers and foreground image elements that create composite visual effects. The JCodesMore/ai-website-cloner-template solves this through an integrated discovery and classification system defined in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md). This approach ensures pixel-perfect replication by preserving the exact layering semantics of the original design.

## The Browser-Based Asset Discovery Pipeline

The template executes a JavaScript payload within the browser automation (MCP) environment to capture the complete visual asset inventory of a target page.

### Enumerating Visual Elements in SKILL.md

The discovery logic resides in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) (lines 191–225). It collects two distinct categories of visual assets:

1. **`<img>` elements** with their complete DOM context, including parent classes, sibling counts, and computed positioning styles.
2. **Computed `background-image` values** from every DOM node that has a non-none background image declaration.

The payload returns a structured JSON object that distinguishes between these asset types:

```javascript
{
  images: [...document.querySelectorAll('img')].map(img => ({
    src: img.src || img.currentSrc,
    alt: img.alt,
    width: img.naturalWidth,
    height: img.naturalHeight,
    parentClasses: img.parentElement?.className,
    siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
    position: getComputedStyle(img).position,
    zIndex: getComputedStyle(img).zIndex
  })),
  backgroundImages: [...document.querySelectorAll('*')].filter(el => {
    const bg = getComputedStyle(el).backgroundImage;
    return bg && bg !== 'none';
  }).map(el => ({
    url: getComputedStyle(el).backgroundImage,
    element: el.tagName + '.' + el.className?.split(' ')[0]
  }))
}

```

### Identifying Layered Compositions vs. Foreground Overlays

The classification logic distinguishes between **layered background images** and **overlay images** by analyzing the DOM relationships captured in the discovery phase:

- **Layered backgrounds** are identified when a container element reports a `backgroundImage` property **and** hosts one or more `<img>` children (indicated by `siblings > 0`). This signals a composite visual stack where a CSS background works in conjunction with foreground imagery.
- **Overlay images** are `<img>` entries whose `z-index` or `position` values (captured via `getComputedStyle`) place them visually above the background layer of their parent container.

This strict separation prevents the common error of flattening a multi-layer composition into a single rasterized asset.

## Downloading and Organizing Extracted Assets

Following discovery, a Node.js helper script (typically `scripts/download-assets.mjs`) consumes the JSON payload and establishes a predictable directory structure under `public/images/`. The script normalizes relative URLs, resolves absolute paths, and applies role-based naming conventions such as `bg-hero.webp` for backgrounds and `overlay-logo.png` for foreground elements.

```javascript
import { promises as fs } from 'node:fs';
import path from 'node:path';
import https from 'node:https';
import http from 'node:http';

async function download(url, dest) {
  const client = url.startsWith('https') ? https : http;
  await new Promise((resolve, reject) => {
    client.get(url, res => {
      if (res.statusCode !== 200) return reject(new Error(`Failed ${url}`));
      const file = fs.createWriteStream(dest);
      res.pipe(file);
      file.on('finish', () => file.close(resolve));
    }).on('error', reject);
  });
}

async function run() {
  const raw = await fs.readFile('assets.json', 'utf-8');
  const { images, backgroundImages } = JSON.parse(raw);

  // Process standard image elements
  for (const img of images) {
    const url = new URL(img.src);
    const out = path.join('public', 'images', path.basename(url.pathname));
    await download(url.href, out);
  }

  // Process CSS background images (strip url() wrapper)
  for (const bg of backgroundImages) {
    const match = /url\(["']?(.*?)["']?\)/.exec(bg.url);
    if (!match) continue;
    const url = new URL(match[1], 'https://example.com'); // Base URL resolved in practice
    const out = path.join('public', 'images', 'bg-' + path.basename(url.pathname));
    await download(url.href, out);
  }
}

run().catch(console.error);

```

The script preserves the hierarchical relationship between background containers and their overlay children, ensuring that the generated file paths reflect the layering semantics discovered in the browser.

## Integrating Assets into Component Specifications

Extracted assets are formally declared in component specification files located at `docs/research/components/*.spec.md`. These specifications explicitly map each asset to its intended rendering context:

```markdown

## Assets

- **Background image**: `public/images/hero-bg.webp` (applied via CSS `background-image: url('/images/hero-bg.webp')`)
- **Overlay image**: `public/images/logo-overlay.png` (rendered as `<Image src="/images/logo-overlay.png" alt="Logo" />`)

```

This documentation step guarantees that builder agents receive precise instructions for reconstructing the original layered composition, maintaining the visual separation between background textures and foreground graphics as implemented in the source web page.

## Summary

- **Discovery occurs in-browser** via the JavaScript payload defined in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md), which captures both `<img>` tags and computed `background-image` styles alongside positioning metadata.
- **Classification relies on DOM hierarchy**; containers with both CSS backgrounds and child `<img>` elements are flagged as layered compositions, while positioned images with elevated z-index are marked as overlays.
- **Organization follows role-based naming** in `public/images/`, with backgrounds and overlays stored according to their visual function rather than arbitrary categorization.
- **Component specs formalize the separation** by explicitly listing background URLs and overlay paths in `docs/research/components/*.spec.md`, enabling pixel-perfect replication in generated React components.

## Frequently Asked Questions

### How does the AI Website Cloner Template distinguish between layered backgrounds and overlay images?

The template analyzes the DOM relationships captured during asset discovery. When a container element has a non-none `backgroundImage` computed style and simultaneously contains one or more `<img>` child elements (indicated by a `siblings` count greater than zero), the system identifies this as a **layered background** composition. Conversely, `<img>` elements with `position` values of `absolute` or `fixed` and elevated `z-index` values are classified as **overlay images** that sit atop the background layer.

### Where is the image extraction logic defined in the repository?

The core discovery logic is embedded in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) at lines 191–225. This file contains the browser automation script that enumerates visual assets, extracts computed styles, and generates the JSON payload used in subsequent processing steps. The download and organization phase is typically implemented in a helper script such as `scripts/download-assets.mjs`.

### What naming conventions are used for extracted image assets?

The Node.js download helper applies role-based prefixes to distinguish asset types. Background images are typically prefixed with `bg-` (e.g., `bg-hero.webp`), while overlay images retain their original descriptive names or receive `overlay-` prefixes (e.g., `overlay-logo.png`). This convention ensures that designers and build agents can immediately identify the intended layering context of each file stored in `public/images/`.

### How are extracted assets referenced in the final generated components?

Each asset is formally documented in component specification files at `docs/research/components/*.spec.md`. These specifications list **background image URLs** for CSS application and **overlay image paths** for component import statements. The explicit separation in the spec files ensures that React components render backgrounds via CSS properties while overlay images are imported as `<Image>` or `<img>` elements, preserving the original visual stacking order.