insane0777 / awwwards-inspiration

Awwwards Inspiration

You have access to the awwwards MCP server: a searchable library of
award-winning websites with inline screenshots and per-site design DNA. Use
it to ground design decisions in real, proven references instead of guessing.

When to use this skill

1. First time on this machine? If ~/.awwwards-mcp/preferences.json
   does not exist yet, run the awwwards-setup skill first — it asks the
   user's preferences once (result density, viewport, captures, index,
   watches) and this skill applies them afterward.

2. During site builds — before writing any UI code, gather references and
   state a design direction.

3. Standalone research — the user wants inspiration, trends, or examples
   ("show me dark 3D portfolio sites").

4. Index & capture ops — building the local search index, or taking fresh
   screenshots of live URLs.

The inspiration loop

Run this loop before building anything visual:

1. Restate the goal as concrete attributes. Turn the user's request into
   mood, color, technology, and industry terms. "Make it feel premium" becomes
   e.g. "dark, elegant, WebGL, agency portfolio".

2. Ground your vocabulary. If unsure which filters exist, call
   list_categories first — it returns every color hex and tag/technology
   slug you can search by.

3. Search. Call search_sites with 1–3 filters (e.g.
   { color: "#404040", tags: ["3d", "portfolio"] }). Judge the results from
   the inline screenshots, not just titles. Shortlist 2–3 candidates.
   Free-text queries are porter-stem + prefix-matched and BM25-ranked
   ("magazines" finds Magazine-tagged sites, best matches first); multi-word
   queries keep AND semantics — both tokens must hit the same site.

3b. Techniques registry: skills/_memory/techniques.json catalogs researched how-tos per domain (video-understanding, motion-detection, ui-structure, micro-interactions, images). Consult it when a step needs a method — it grows via the flywheel.

1. Synthesize the direction. Once you have 2–5 shortlisted slugs, call create_design_brief with those slugs and the user's non-blank project goal. Optionally include audience and concrete constraints. Use the returned shared signals, deliberate outliers, build constraints, evidence, limitations, and Interaction Plan to define an original direction — do not copy any single reference. Apply only its evidence-backed cursor/hover, scroll/pin/scrub, entrance/reveal, easing, and duration cues. Treat empty or null interaction fields as missing evidence: do not invent effects, timings, or scroll behavior. Preserve the plan's prefers-reduced-motion, content-access, and keyboard-access guardrail. Set includeStructure: true only when optional page-band evidence is needed; it may run browser analysis for sources with usable live URLs. Cached Motion DNA is included when available, but the brief never records motion automatically.

2. Live reference URL named? Capture it full-page first. (and later capture
   your own build the same way — compare both against each other) If the user
   points at a specific live site (e.g. "recreate cerebrium.ai"), call
   capture_live_site on that URL before anything else and design from the
   full-page PNG — every section, top to bottom. Cached Awwwards screenshots
   are hero-only crops (~880×660) and hide everything below the fold: the
   sections that make a site's structure distinctive (pricing, feature
   layouts, contrast breaks, footer) were never visible in them. For
   mobile-excellence references pass viewport: "mobile" — and capture BOTH
   viewports when the desktop and mobile designs diverge.

3. Get the design DNA as follow-up evidence. Call get_site_details on the top pick when the brief reports missing or weak detail evidence, or when a specific source needs deeper inspection. If it reports a layout-drift error, fall back to judging the shortlisted screenshots, get_site_elements (which uses a different parser), or a capture_live_site of the site's URL for a first-hand full-page view.

4. Study MOTION before building (element videos, not posters). Call
   get_site_elements on shortlisted sites — it returns per-element video
   URLs (preloader, page transition, case study, about…). **Download those
   videos and tile them at 1–2 fps BEFORE writing any animation code**:
   curl -o e.mp4 <video-url> && ffmpeg -i e.mp4 -vf "fps=2,scale=480:-1,tile=6x4" -frames:v 1 tile-e.jpg,
   then Read the tile. (The full capture→review→build procedure — what to record, what to skip, motion inventories, build verification — is the awwwards-motion-study skill.) Element posters are single frames — they show
   layout, not motion; a 3D carousel looks like floating static cards in a
   poster (this exact mis-build happened). One tile per element shows you the
   whole animation arc (easing, overlap, entrance order). If a marquee
   animation needs finer study, re-tile that video at higher fps. The motion
   IS the design: every reference animation you ship must trace to frames
   you actually studied, and reference videos pass through
   showcase/ref-motion/ as the design's evidence trail.

5. State the design direction before writing code. In prose: palette
   (hexes from the references), type mood, layout patterns, page
   architecture (one page vs separate horizontal sections — judge this from
   the reference passages you studied in steps 4–6, not habit), and tech
   choices, each traceable to a reference. Then build. For a site's own
   marquee frontend skills, prefer proven patterns (GSAP ScrollTrigger for
   horizontal scroll chapters, Lenis for smooth scroll) over hand-rolled
   scroll math.

6. Verify structure, then polish. After building, capture your own build
   full-page (capture_live_site on its file:// or served URL) and run
   analyze_page_structure on BOTH the reference and the build. Compare band
   maps section by section (count, order, backgrounds, heights). Match the
   reference's viewport when comparing: for mobile-excellence references pass
   viewport: "mobile", and capture BOTH viewports when the design diverges.
   Fix distribution mismatches first — a section that is 3× the reference's height
   is a structural bug no amount of pixel polish fixes. Match the reference's
   band structure, never just its total height.

7. Close the flywheel: end every loop pass by recording what the verification caught — node scripts/skill-memory.mjs record --skill awwwards-inspiration --phase <phase> --symptom "..." --rule "..." [--evidence path]. "Nothing new learned" is a recorded negative. Then distill folds rules seen ≥2× into your installed copy’s managed section; recall prints them at loop start. When promoting a confirmed rule into the shipped copy (human PR), promote --skill awwwards-inspiration prints it with machine-local evidence paths stripped.

Anti-patterns

• Vague single-word searches ("modern", "nice") — use concrete color/tag/
  technology/award filters instead.

• Skipping to code without stating a direction — the references are
  worthless if nothing is derived from them.

• Dumping raw tool output at the user — curate: show the shortlist, the
  chosen direction, and why.

• Designing from a thumbnail or element poster — thumbnails are hero-only
  crops, posters are single video frames, and neither shows real structure OR
  motion. When the reference URL is known, capture it full-page (step 4);
  when an element has motion, tile its video (step 6) — never animate from
  posters.

• One filmstrip for everything — a single N×N tiling of the *whole
  recording* makes late tiles tiny and animation arcs illegible. Tile per
  element/per passage at 1–2 fps instead; re-tile finer passages at higher
  fps when easing or overlap matters.

• Padding empty bands to match total height — if your build's total height
  matches the reference but a spacer/background band is far taller than the
  reference's equivalent, the height was stolen from real content sections.
  Compare band maps, not totals. Spacer and decorative elements are measured
  against the reference's equivalent band — never invented to absorb height.

Tool reference

All image results arrive as MCP image content blocks — look at them, don't
just read the text blocks.

Staying current

For research that should reflect what's winning now (trend questions,
"latest" anything), open the session with new_winners — it reports today's
freshly-crowned SOTD/Developer/Honorable winners and quietly folds each
winner's elements into the searchable corpus. To track a studio, tag, or
specific site over time, add a watch (watch_site, action: "add",
kind: studio|tag|url) after your first sweep; every later new_winners /
search_sites run refreshes the pool and watch_site list reports what's
new per watch. Watches never fetch on their own — the sweep feeds them.

Index & capture ops

Local index. search_sites works out of the box but unindexed depth is
limited by polite live scraping (~31 sites per filter page). Build the index
once for searches across thousands of sites:

npx -y -p awwwards-mcp awwwards-index      # from the published package
npm run index                              # from a repo checkout

• Crawls all ~200 tag pages at 1 request/second (~4 minutes) into a SQLite
  cache at ~/.awwwards-mcp/.

• Resumable: interrupt and re-run; completed pages are skipped.

• The MCP server re-indexes automatically in the background whenever the
  index is stale — you rarely need to run this by hand.

Live captures. capture_live_site needs playwright installed once (see
table above). Two uses: (1) the user wants a screenshot of a URL that is not
an Awwwards site, or a fresher view than the cached thumbnails; and (2) —
the more important one — the user names a live site as the design reference
for a build: capture it full-page first and derive the structure from that
image (see step 4 of the loop).

Motion capture. Static images can't show preloaders, scroll-driven
animation, or transitions — and most award-winning sites are built around
exactly those. When the reference site has motion, record it: launch
Playwright with recordVideo, wait out the preloader (~7 s), scroll slowly
to the bottom in small steps so every scroll-triggered animation fires on
camera, then extract a filmstrip of frames with ffmpeg (`npm i -D
ffmpeg-static`, one frame every ~3 s) and Read the frames — or call
record_site_motion directly: the filmstrip comes back inline and the .webm
path as text.

Filmstrip is the fallback, not the default. First try Reading the
video file directly — if your model supports video input, watching the
scroll-through gives you timing, easing, and transitions the frames can't.
If the Read comes back with media omitted / "model does not support video
input", extract the filmstrip and Read the frames instead. A ready-made
recorder ships in this repo at
scripts/record-scrollthrough.mjs (run it from the repo root; playwright
and ffmpeg-static are devDependencies).

<!-- skill-memory:start -->
<!-- skill-memory:end -->