Awwwards DESIGN.md

Build a DESIGN.md plus a machine-readable design-evidence.json from a single public page. The document is a cited subset of what was observed, not an official brand system or the site's original source tokens.

Before starting

Require:

• an absolute public http(s) URL;
• the awwwards MCP available in the current agent;
• Playwright installed for the browser tools.

Supported inputs:

url:      required, absolute public http(s) URLoutDir:   optional, default current directoryviewport: desktop (default) or mobile

One URL and one viewport per run. No crawling, login, authenticated pages, asset downloads, or automatic motion recording.

If publicOnly is unavailable on the installed awwwards-mcp version, stop. Do not replace it with an unguarded capture. The skill requires the guarded capability added for arbitrary public URLs.

Workflow

Use full-profile tools. For the v2 surface, use the equivalents in v2-routing.md; do not mix profiles.

1. Guard check — call export_design_tokens with publicOnly:true, selector:"body", the requested viewport, and maxNodes:800. A refusal is final: report BLOCKED_DESTINATION or INVALID_URL.
2. Structure — call analyze_page_structure with publicOnly:true, maxBands:20, and the same viewport.
3. Screenshot — call capture_live_site with publicOnly:true, inline:false, and the same viewport. Inspect the saved image yourself before writing visual claims.
4. Components — choose up to three representative roots from the observed structure. Call capture_component with publicOnly:true, maxNodes:150, maxDepth:12, and compact:false. Do not guess selectors that the structure capture did not show.
5. Write — fill DESIGN.md using the template below and design-evidence.json using the evidence contract.
6. Validate — run the bundled validator. Optionally run Google's linter.
7. Report — summarize what was captured, what was omitted, and every inconclusive or blocked step.

Do not continue after a failed guard, robots block, navigation failure, or missing required evidence. Report the failure instead.

Evidence rules

Classify every material statement:

• observed — directly present in a tool response, screenshot, or node.
• inferred — a grouping or name derived from observed values.
• proposed — a recommendation for the user's project.

Never label inferred/proposed values observed. Never claim:

• an official brand system;
• recovered original token names;
• complete responsive, hover, focus, or dark-mode coverage;
• accessibility compliance;
• rights to reuse assets;
• pixel-perfect reconstruction.

Every design value in the document needs a claim in the sidecar with:

{  "id": "color-1",  "value": "#111111",  "classification": "observed",  "artifactId": "tokens",  "path": "/tokens/colors/0",  "property": "color",  "viewport": "desktop",  "state": "default",  "method": "computed-style aggregate",  "sampleCount": 37,  "limitations": []}

path is a JSON pointer into the captured tool response or a node path in a component pack. It is not a guaranteed reusable CSS selector.

DESIGN.md template

Use this exact section order. Keep the YAML front matter valid.

---version: alphaname: <site title or host>description: <one sentence: what this page appears to be>colors: {}typography: {}rounded: {}spacing: {}components: {}---
## Overview
<What was observed. One paragraph. Cite sources inline as [S1], [S2].>
## Colors
<Observed palette with counts. Distinguish page background, text, accents.>
## Typography
<Families, weights, sizes, line heights, letter spacing. Do not mergeindependently aggregated values into a heading style unless a componentcapture proves that tuple.>
## Layout
<Section bands, max widths, spacing rhythm, grid/flex evidence.>
## Elevation & Depth
<Shadows, borders, overlays, z-index evidence. Omit with a reason when absent.>
## Shapes
<Radii, borders, icon/button shapes.>
## Components
<Up to three components. For each: observed selector, node path, size,typography tuple, colors, spacing, border/radius/shadow, states actually seen.>
## Do's and Don'ts
<Only rules grounded in observed evidence or clearly marked proposals.>
## Sources
- [S1] `export_design_tokens` — `<redacted URL>` — `<capturedAt>` — `<artifactId>`- [S2] `analyze_page_structure` — ...- [S3] `capture_live_site` — `<saved file>`- [S4] `capture_component` — `<selector>` — `<node path>`
## Coverage and limitations
<What was not observed; mobile/dark/hover/state gaps; truncation; blockedresources; robots/auth restrictions.>
## Unresolved details
<Values the evidence cannot establish. Never fill these with guesses.>

Keep DESIGN.md at or below 24 KiB UTF-8.

design-evidence.json

{  "schemaVersion": "awwwards-design-evidence-v1",  "requestedUrlHash": "<sha256 of the requested URL>",  "redactedFinalUrl": "<origin+pathname>",  "capturedAt": 0,  "viewport": "desktop",  "toolVersion": "<installed awwwards-mcp version>",  "captures": [    {      "id": "tokens",      "tool": "export_design_tokens",      "artifactId": "tokens",      "capturedAt": 0,      "sha256": "<sha256 of the canonical tool JSON>",      "artifactPath": "tokens.json",      "coverage": "<complete|partial|unknown>",      "limitations": []    }  ],  "claims": [],  "omissions": [],  "validation": {    "documentBytes": 0,    "sidecarBytes": 0,    "localValidator": "pass",    "googleLint": "not-run"  }}

Every capture record must correspond to a real tool response saved next to the sidecar (artifactPath); its SHA-256 must match that file, and every claim path must resolve in the saved response. Keep the sidecar at or below 256 KiB. Never embed screenshots as base64 in Markdown; reference the saved file path.

Validation

From the installed skill directory:

node scripts/validate-design-md.mjs DESIGN.md design-evidence.json

The validator needs Node 22+, Python 3, and PyYAML (pip install pyyaml), because it parses the front matter with a real YAML parser instead of guessing. If Python/PyYAML is unavailable, use Google's linter below as the YAML check and keep the rest of the manual review.

Optional Google-format validation:

npx --yes --package="@google/design.md" designmd lint DESIGN.md

Lint success proves document structure, not extraction accuracy. Manually check at least ten emitted values against the tool responses and screenshot.

Stop conditions

Return a short failure report, not a document, for:

• INVALID_URL — not absolute public http(s);
• BLOCKED_DESTINATION — private/loopback/metadata/reserved host;
• ROBOTS_DISALLOWED or ROBOTS_UNAVAILABLE — when the MCP reports it;
• PAGE_BLOCKED or TIMEOUT;
• missing tokens/structure with no usable screenshot;
• a component capture that cannot identify a real root.

Do not

• Do not call create_design_brief as a substitute: it takes Awwwards slugs and synthesizes direction, not arbitrary-URL source evidence.
• Do not add a dedicated get_design_md tool or claim one exists.
• Do not crawl multiple pages, download assets, or bypass authentication.
• Do not invent CSS variables, source token names, or states.
• Do not write DESIGN.md from memory or from the screenshot alone.