--- name: website-to-design-md description: Generate a reusable design.md or DESIGN.md from a live website by deeply inspecting the site with `agent-browser` and `agent-browser eval`, then synthesizing its visual language, layout system, interaction patterns, and content style into a structured markdown design system. Use when given one or more website URLs and asked to analyze a site, reverse-engineer its design, extract its look and feel, write DESIGN.md, create a style guide, or capture a site's UI rules for later AI-assisted design or implementation. Prefer this skill when the goal is documentation rather than rebuilding the page in code. Always use `agent-browser` as the primary browser runtime; if it is missing, help the user install or expose it instead of switching platforms or browser stacks. ---

# Website to DESIGN.md

## Overview

Use this skill to turn a real website into a reusable `design.md` or `DESIGN.md` document plus a companion HTML preview.

The goal is not to clone the site. The goal is to inspect it deeply enough that another agent can recreate the same design language, content tone, and interaction feel without needing to see the original website.

The HTML preview is a practical review surface. It should translate the markdown into a glanceable design board so the user can inspect palette, typography, spacing, component cues, and the raw markdown source without reopening the site.

## Universal Browser Rule

This skill should always use `agent-browser` first.

- Use `agent-browser open`, `agent-browser wait`, and especially `agent-browser eval` as the primary extraction workflow. - Do not start by checking which app or platform the user is on. - Do not branch logic based on whether the user is using Codex, Trae, Claude, Cursor, or another host. - Do not start by checking whether the current project folder contains Playwright, Chrome CLI, or a local browser package. - If `agent-browser` is unavailable, help the user install it or expose it on `PATH`, then continue with the same workflow. - Do not silently switch to Playwright, Chrome CLI, or screenshot-led extraction unless the user explicitly asks for a separate fallback.

## Working Style

Work browser-first and evidence-first.

- Prefer `agent-browser` over raw HTML fetches. A live website often hides important behavior behind hydration, scroll state, hover state, or responsive layout changes. - Treat `agent-browser eval` as the primary extraction layer. The main evidence should come from DOM structure, rendered HTML, computed styles, CSS variables, readable stylesheet rules, and interaction states gathered inside the browser runtime. - Do not use screenshots as a default evidence source. When `agent-browser eval` or an equivalent page-eval path is available, use DOM, computed styles, CSS variables, readable stylesheet rules, and extracted text as the primary evidence. - Only use screenshots as an optional last-resort cross-check when DOM evidence is insufficient or the user explicitly asks for a visual verification pass. - Do not silently fall back to Playwright or Chrome CLI. If `agent-browser` is unavailable, detect that explicitly and help the user install or expose it. - Treat static source files as supporting evidence, not the main truth source. - Translate technical details into design language. Do not dump CSS blindly; synthesize it into something an agent can actually use. - Distinguish observed facts from inference. If something is a judgment or a likely rule rather than a directly observed value, label it clearly. - Treat the HTML preview as part of the default deliverable, not as an optional extra, unless the user explicitly opts out.

## Preflight

1. Normalize the target into one or more URLs. 2. Check whether `agent-browser` is already usable. 3. If `agent-browser` is missing, use [scripts/check-browser-tooling.mjs](scripts/check-browser-tooling.mjs) and then help the user install or expose `agent-browser`. 4. Do not inspect the current folder for Playwright, Chrome CLI, or local browser executables as the primary path. 5. Do not silently fall back to Playwright or Chrome CLI unless the user explicitly asks for that fallback. 6. Default the markdown output file to `DESIGN.md`. 7. Default the companion preview file to the same basename plus `-preview.html`, for example `DESIGN-preview.html` or `design-preview.html`. 8. If the user explicitly asks for `design.md`, a custom filename, or a custom folder, honor that exactly and keep the HTML preview beside it unless the user asks not to. 9. If multiple URLs are provided, inspect each independently, then synthesize one shared design system only when the visual language is clearly consistent across pages.

## Browser Tooling Bootstrap

Treat browser tooling setup as part of the skill, not as a separate user chore.

### Detection

Check in this order:

- whether `agent-browser` is already callable - if not, whether it can be installed or exposed immediately

The bundled checker script reports:

- whether `node` and `npm` are available - whether `agent-browser` is callable - which tool should be used next - whether installation is recommended

### Installation Default

If `agent-browser` is unavailable, help the user install it or expose it on `PATH`, and verify it with `agent-browser --help` before using the skill.

### Installation Behavior

- Explain that installation is needed so the skill can consistently use `agent-browser`. - If the first install attempt fails because of network or sandbox restrictions, request the needed approval and retry. - If installation succeeds, continue directly into site analysis in the same turn. - If installation fails, tell the user clearly what is missing and stop rather than silently switching to a different extractor. - Do not silently downgrade to static HTML scraping just because tooling is absent.

## Required Extraction Passes

Use the checklist in [references/website-reading-checklist.md](references/website-reading-checklist.md) when you need a deeper reminder of what to inspect.

### 1. Scope the Page

- Identify the page purpose. - Identify whether the page is marketing, product, dashboard, docs, ecommerce, editorial, or mixed. - Identify the important visible sections from top to bottom. - Note any gated or inaccessible areas instead of inventing them.

### 2. Capture the Baseline

- Inspect the page at desktop first. - Also inspect tablet and mobile when the layout materially changes. - Scroll the full page slowly before writing anything so you do not miss delayed animation, sticky UI, or progressive disclosure. - Capture browser-side code evidence while the page is live: rendered HTML, key node `outerHTML`, root CSS variables, readable stylesheet rules, and computed styles for representative components. - Prefer direct `agent-browser eval` calls or an `agent-browser`-driven wrapper script rather than switching to another browser stack. - Use [scripts/extract-browser-evidence.mjs](scripts/extract-browser-evidence.mjs) only when the user explicitly wants a shell-generated JSON artifact while still staying on `agent-browser`. - Do not pause for screenshot capture during the default pass. Use page evaluation to extract the structure and styles directly from the running page.

### 2.1 Preferred Eval Workflow

When `agent-browser eval` or an equivalent browser-eval path is available, follow this order:

1. open the page 2. wait for load and hydration 3. scroll the page to trigger lazy content and sticky-state changes 4. extract rendered HTML for representative nodes 5. extract computed styles for headings, buttons, cards, navigation, and section wrappers 6. extract root CSS variables and readable stylesheet rules 7. extract visible text snippets and CTA copy 8. probe hover, active, sticky, or expanded states through DOM or computed-style changes

Do not replace steps 4 through 8 with screenshots.

### 3. Extract the Design System

Capture the reusable rules, not only the page-specific surface:

- colors and their roles - light and dark theme variants when the site supports them - typography hierarchy - spacing rhythm and grid behavior - corner radius language - border treatment - shadows and surface layering - imagery style - icon style - motion and transition style - density and whitespace philosophy - stylesheet and CSS variable conventions when observable - DOM patterns that explain how repeated components are actually structured

### 4. Extract Components and States

Inspect the major repeated patterns:

- navigation - announcement bars - hero blocks - buttons and links - cards - badges - forms and inputs - tabs or pills - accordions - tables - footers

For each important component, inspect the visible states that matter:

- default - hover - active or selected - focused if visible - disabled if visible - scrolled or sticky variants - open or expanded states - light-mode and dark-mode variants when the site supports theme switching

### 5. Extract Interaction Behavior

Do not stop at static visuals.

Document:

- what changes on scroll - what changes on hover - what changes on click - what changes when the user toggles between light and dark mode - what is animated into view - whether carousels, tabs, or sticky sidebars are click-driven, scroll-driven, or time-driven - how fast motion feels and whether it is subtle, crisp, cinematic, playful, or restrained - which CSS or DOM states change during those interactions when observable in the browser

### 6. Extract Content and Brand Voice

Capture the tone that shapes the design:

- headline style - CTA phrasing - sentence density - product framing - trust signals - feature naming patterns - whether copy is technical, playful, premium, direct, academic, or conversational

This is important because a good `DESIGN.md` should guide both visuals and presentation style.

### 6.1 Theme Mode Sweep

If the site supports appearance switching:

- trigger the light and dark mode toggle directly in the browser - extract DOM and computed-style evidence for both modes - document which tokens invert versus which accents stay stable - note whether imagery, shadows, borders, cards, and code blocks change treatment between modes - carry both modes into the final markdown and HTML preview

## Output Contract

Write the final document using the structure in [assets/DESIGN.template.md](assets/DESIGN.template.md).

After the markdown is written, generate a companion HTML preview using [scripts/render-design-preview.mjs](scripts/render-design-preview.mjs) when possible.

When browser tooling is available, prefer a DOM-and-style extraction pass before writing. The expected evidence order is:

1. rendered HTML and key node structure 2. computed styles and CSS variables 3. interaction-state diffs 4. optional screenshot cross-check only if the user explicitly asks for it or DOM evidence is ambiguous

If the page supports light and dark themes, the output contract also requires:

1. explicit `Theme Modes` documentation in `DESIGN.md` 2. separate light-mode and dark-mode token notes when they differ materially 3. a visible light/dark theme summary block in the companion HTML preview

The document should usually contain these sections:

1. `Visual Theme & Atmosphere` 2. `Color Palette & Roles` 3. `Typography Rules` 4. `Component Stylings` 5. `Layout Principles` 6. `Depth & Elevation` 7. `Do's and Don'ts` 8. `Responsive Behavior` 9. `Agent Prompt Guide`

Add optional appendices only when they add real value:

- `Interaction Patterns` - `Content & Messaging Patterns` - `Observed Pages` - `Evidence Notes`

Within those sections, prefer richer Stitch-style subsections when the site supports them:

- `Key Characteristics` - `Primary`, `Interactive`, `Neutral Scale`, `Surface & Overlay`, `Shadows & Depth` - `Font Family`, `Hierarchy`, `Principles` - `Buttons`, `Cards & Containers`, `Inputs & Forms`, `Navigation`, `Image Treatment`, `Distinctive Components` - `Spacing System`, `Grid