Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/insane0777/awwwards-skills --skill awwwards-design-mdAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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) URL
outDir: optional, default current directory
viewport: desktop (default) or mobileOne 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.
- Guard check — call
export_design_tokenswithpublicOnly:true,
selector:"body", the requested viewport, and maxNodes:800. A refusal is final: report BLOCKED_DESTINATION or INVALID_URL.
- Structure — call
analyze_page_structurewithpublicOnly:true,
maxBands:20, and the same viewport.
- Screenshot — call
capture_live_sitewithpublicOnly:true,
inline:false, and the same viewport. Inspect the saved image yourself before writing visual claims.
- 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.
- Write — fill
DESIGN.mdusing the template below and
design-evidence.json using the evidence contract.
- Validate — run the bundled validator. Optionally run Google's linter.
- 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: alpha
name: <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 merge
independently aggregated values into a heading style unless a component
capture 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; blocked
resources; 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.jsonThe 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.mdLint 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_DISALLOWEDorROBOTS_UNAVAILABLE— when the MCP reports it;PAGE_BLOCKEDorTIMEOUT;- missing tokens/structure with no usable screenshot;
- a component capture that cannot identify a real root.
Do not
- Do not call
create_design_briefas a substitute: it takes Awwwards slugs
and synthesizes direction, not arbitrary-URL source evidence.
- Do not add a dedicated
get_design_mdtool 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.mdfrom memory or from the screenshot alone.