insane0777/awwwards-skills

awwwards-design-md

Create an evidence-backed DESIGN.md for any public website URL.

Zobacz źródło

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/insane0777/awwwards-skills --skill awwwards-design-md

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

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:

text
url:      required, absolute public http(s) URL
outDir:   optional, default current directory
viewport: 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.

  1. Structure — call analyze_page_structure with publicOnly:true,

maxBands:20, and the same viewport.

  1. Screenshot — call capture_live_site with publicOnly:true,

inline:false, and the same viewport. Inspect the saved image yourself before writing visual claims.

  1. 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.

  1. Write — fill DESIGN.md using the template below and

design-evidence.json using the evidence contract.

  1. Validate — run the bundled validator. Optionally run Google's linter.
  2. 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:

json
{
  "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.

markdown
---
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

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:

bash
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:

bash
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.
z tego samego repozytorium

Więcej Skills

Wszystkie Skills
insane0777
Społeczność

awwwards-inspiration

Use when building a site that needs design references (e.g. "make it feel premium", "dark 3D portfolio vibes"), when the user asks for standalone inspiration research ("show me award-winning e-commerce sites", "what's trending in brutalism"), or when setting up or maintaining the awwwards-mcp local index or live-capture tooling (awwwards-index, capturelivesite).

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
18 lis
insane0777
Społeczność

awwwards-atlas

Use when working with the experimental Atlas section/component evidence layer in awwwards-mcp 1.19+ - enabling AWWWARDSMCPATLAS, importing or capturing Atlas evidence, searching sections/components, reading regions or status, exporting local evidence packs, or maintaining the Atlas cache. Atlas is opt-in, off by default, and its labels are candidate-only.

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
12 lis
insane0777
Społeczność

awwwards-doctor

Use when awwwards-mcp scraping or tools stop working — BlockedError, "layout may have changed" parser errors, empty results, failed captures, stale searches — or when the user reports the MCP behaving oddly. Guides running the doctor/drift/index scripts, applying their fixes, re-anchoring parsers after real awwwards.com drift, and recovering the in-flight task that surfaced the failure.

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
12 lis
insane0777
Społeczność

awwwards-motion-study

Use when building a site whose reference has animation — before writing any motion code, and again when verifying a build. Teaches what to record from a live site (and what to skip), how to study the recordings frame-by-frame (video input or ffmpeg tile-per-element), how to turn the study into a motion inventory, and how to verify the build's motion against the reference. Complements awwwards-inspiration (step 6) with the full capture→review→build procedure.

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
12 lis