awwwards-mcp 1.4.0 → 1.6.0

package/README.md

@@ -185,9 +185,9 @@ and content remain the property of Awwwards and the credited creators — don't
 bulk-scrape, redistribute, or republish them. If you use this commercially,
 review awwwards.com's terms yourself.
 
-## Built with awwwards-mcp: three real sites
+## Built with awwwards-mcp: four real sites
 
-Three complete sites were built through the full inspiration loop this MCP
+Four complete sites were built through the full inspiration loop this MCP
 enables, using nothing but the server's tools plus the shipped
 `awwwards-inspiration` skill. Each one exercised a different corner of the
 loop — and every correction the loop caught on the way became doctrine in the
@@ -203,7 +203,14 @@ skill.
 > results would be better still. The skill's frame-tile doctrine is what
 > closes that gap today.
 
-**1. [Fallow Press](fallow-press/index.html)**
+**1. [Ridge](showcase/ridge/index.html)**
+([source](showcase/ridge/)) — a Swiss-minimal single-page showcase for a fictional engineering-talent studio, direction **Aspen Search** (SOTD + Developer Award, jury 7.48): monochrome `#FAFAF8`/`#1A1A1A` + mint, giant grotesque section markers, halftone grain, asymmetric panel grid, dark discipline panels in an interior **horizontal pin passage**, count-up stats, client rows, theme toggle, cursor-follower. Built with the v1.4.0 toolkit: FTS5-ranked direction search, **both-viewports** reference captures and QA (desktop 7,849px + mobile 390×844), overflow audit (0px both), pin-center shots, film verification — and the skill-memory flywheel recorded the findings. QA evidence: `showcase/ridge/_qa/`.
+
+| Panel grid (desktop) | Horizontal discipline passage | Mobile 390×844 |
+|---|---|---|
+| ![Ridge desktop — Swiss panel grid with mint and grain](assets/ridge-home.jpg) | ![Ridge disciplines — pinned horizontal passage mid-slide](assets/ridge-disciplines.jpg) | ![Ridge mobile — stacked grid, zero overflow](assets/ridge-mobile.jpg) |
+
+**2. [Fallow Press](fallow-press/index.html)**
 ([source](fallow-press/)) — a flat-2D editorial journal, direction
 **Emergence Magazine** (SOTD): pink `#FF9398` on cream and black, torn-paper
 masthead (pure CSS `clip-path`, zero WebGL), giant grotesque display over
@@ -232,7 +239,7 @@ The loop as it ran:
    one-shot entrances**; QA pin shots land at panel **centers**, not uniform
    fractions, or you photograph empty transition zones.
 
-**2. Cerebrium recreation** (`C:/Users/Afjal/cerebrium-recreation/`) — a
+**3. Cerebrium recreation** (`C:/Users/Afjal/cerebrium-recreation/`) — a
 fidelity-first recreation of cerebrium.ai, pixel-checked against the live
 reference: full-page captures of both sides, `analyze_page_structure` band
 compare, and SVG icon/legend fixes until the build matched the reference to
@@ -242,7 +249,7 @@ never just totals.
 
 ![Cerebrium recreation — full-page build capture](assets/cerebrium-build.jpg)
 
-**3. The Meridian** (`C:/Users/Afjal/editorial-site/`) — an editorial journal
+**4. The Meridian** (`C:/Users/Afjal/editorial-site/`) — an editorial journal
 built from ORDR/Hearst references: the first build to run the whole loop
 end-to-end. `analyze_page_structure` caught a masthead band bug by comparing
 the build's band map against the reference's; the reference captures,
@@ -264,6 +271,8 @@ motion film, and the reusable pre-scroll capture script live in
 | `lenis` (library, via skill guidance) | smooth scrolling synced to ScrollTrigger on the Fallow Press home page. |
 | `tailwindcss` / plain CSS | All builds are plain hand-rolled CSS — flat 2D, no frameworks needed. |
 
+**The skills self-improve:** every loop pass records what verification caught (`scripts/skill-memory.mjs record`), and a deterministic distiller folds rules seen 2+ times into your installed skill copy — while the shipped copies only change via human PR. A techniques registry (`skills/_memory/techniques.json`) catalogs researched how-tos per domain (video understanding, motion detection, UI structure, micro-interactions, images).
+
 Reduced-motion, JS-less visits, and capture tools all get graceful fallbacks
 (vertical stacks; progressive-enhancement reveals).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awwwards-mcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Free MCP server giving AI agents design inspiration from Awwwards: search award-winning sites with inline screenshots and extract design DNA.",
   "type": "module",
   "license": "MIT",

package/skills/_memory/techniques.json

@@ -0,0 +1,161 @@
+{
+  "version": 1,
+  "updated": "2026-09-19",
+  "description": "Techniques the awwwards skill loop can use to understand websites — per domain. Grown by the skill-memory flywheel: a finding that proposes a better technique gets promoted here by a human PR. Each entry: id, domain, when (when to use it), how (concrete steps/commands), source (where it came from).",
+  "domains": {
+    "video-understanding": {
+      "summary": "From recording to model-ready motion context. Field consensus 2025-2026: scene detection FIRST, keyframes per scene, adaptive any-k budget, then structured context to the model. Our tile-per-element doctrine is the special case for short UI loops.",
+      "techniques": [
+        {
+          "id": "scene-detect-first",
+          "when": "Before tiling any recording longer than ~20s or with multiple distinct animations (preloader → scroll → transition).",
+          "how": [
+            "ffmpeg -i ref.webm -vf \"select='gt(scene,0.3)',showinfo\" -vsync vfr keyframes/%03d.png  # scene-change keyframes",
+            "Alternative low-threshold pass for UI micro-motion: select='gt(scene,0.08)' (UI cuts are subtle vs film cuts)",
+            "Segment the recording at scene boundaries, then treat each segment as its own study passage"
+          ],
+          "source": "arXiv scene-detection survey (2025); Mixpeek production pipeline (2026); K-frames any-k selection (OpenReview)"
+        },
+        {
+          "id": "anyk-keyframe-budget",
+          "when": "Long recordings that exceed the tile budget — decide WHICH frames deserve model context instead of uniform sampling.",
+          "how": [
+            "One keyframe per detected scene (the scene's first stable frame)",
+            "Spend the remaining frame budget on scenes that contain the element under study",
+            "Feed keyframes WITH timestamps — timing is the data for easing inference"
+          ],
+          "source": "K-frames (OpenReview); TwelveLabs context engineering (2025)"
+        },
+        {
+          "id": "tile-within-scene",
+          "when": "Easing/overlap matters inside one scene (the existing 2-6fps tile rule, now scoped to the scene segment).",
+          "how": [
+            "ffmpeg -ss <scene-start> -to <scene-end> -i ref.webm -vf \"fps=6,scale=480:-1,tile=6x4\" scene-tile.jpg",
+            "Re-tile finer only for the frames where motion actually changes"
+          ],
+          "source": "awwwards-inspiration step 6 doctrine (ours), now scene-scoped"
+        }
+      ]
+    },
+    "motion-detection": {
+      "summary": "What a live site tells you about its motion stack BEFORE recording — fingerprint the libraries, diff the computed styles, poll the transforms.",
+      "techniques": [
+        {
+          "id": "library-fingerprint",
+          "when": "Capture phase, before recording — know which animation stack you are studying so build-side patterns match (GSAP vs Motion vs CSS scroll-timeline).",
+          "how": [
+            "In captured HTML: script srcs matching /gsap|ScrollTrigger|ScrollMagic|locomotive|motion|lenis|barba/i",
+            "Inline transforms set by GSAP (style=\"transform: translate(...) matrix(...)\") on scroll-coupled elements",
+            "CSS scroll-timeline / animation-timeline / scroll() functions → native CSS scroll-driven animation (uneven browser support — annnimate 2026)"
+          ],
+          "source": "Blink.new clone-from-URL approach; annnimate GSAP-vs-CSS 2026; motion.dev comparisons"
+        },
+        {
+          "id": "hover-pair-style-diff",
+          "when": "Micro-interactions: hover states that a screenshot cannot show. Captures the EXACT style delta instead of eyeballing film frames.",
+          "how": [
+            "For each interactive element (cursor:pointer discovery, as in record-scrollthrough.mjs):",
+            "  const rest = getComputedStyle(el); el.dispatchEvent(new MouseEvent('mouseover', {bubbles:true}));",
+            "  await new Promise(r => setTimeout(r, 700)); const hover = getComputedStyle(el);",
+            "  diff rest vs hover on: transform, opacity, color, background, box-shadow, letter-spacing, filter, clip-path",
+            "Record the diff per element — this IS the micro-interaction inventory"
+          ],
+          "source": "record-scrollthrough.mjs virtual-cursor pattern (ours) + computed-style diffing standard practice"
+        },
+        {
+          "id": "transform-polling",
+          "when": "Scroll-scrubbed animations where per-frame tiles cannot separate scroll-position coupling from time-based easing.",
+          "how": [
+            "During the stepped scroll, rAF-poll target elements: getComputedStyle(el).transform sampled per step",
+            "A transform that changes ONLY with scroll = scrub-coupled; one that keeps changing after scroll stops = time-based tween",
+            "This distinguishes ScrollTrigger scrub:true from scrub-timeline + toggleActions — the #1 rebuild mistake"
+          ],
+          "source": "GSAP ScrollTrigger docs pattern (ours, gsap-scrolltrigger skill)"
+        }
+      ]
+    },
+    "ui-structure": {
+      "summary": "Structure before pixels. Band maps exist (analyze_page_structure); these extend structure understanding to tokens, rhythm, and overflow.",
+      "techniques": [
+        {
+          "id": "band-map-compare",
+          "when": "Every build, before pixel polish.",
+          "how": ["analyze_page_structure on reference AND build; compare count/order/backgrounds/heights; never pad spacer bands"],
+          "source": "awwwards-inspiration step 8 doctrine (ours)"
+        },
+        {
+          "id": "design-token-extraction",
+          "when": "Recreating a reference faithfully — extract the tokens before writing CSS.",
+          "how": [
+            "Palette: sample band backgrounds + dominant colors (ffmpeg palettegen on hero capture, or canvas sampling in page.evaluate)",
+            "Type scale: histogram of computed font-sizes + families across headings/body (page.evaluate document.querySelectorAll('*') sample)",
+            "Spacing rhythm: computed margins/paddings of section boundaries → find the multiple (8/12/16 grid)"
+          ],
+          "source": "design-token standard practice; cerebrium 1px-fidelity loop (ours)"
+        },
+        {
+          "id": "overflow-audit",
+          "when": "After any responsive build — horizontal overflow at any breakpoint is a structural bug.",
+          "how": [
+            "For each viewport (desktop 1440, mobile 390): document.scrollWidth > window.innerWidth → report offending elements (walk tree for el.getBoundingClientRect().right > innerWidth)",
+            "Record the offender + the px — pin shots will show it as asymmetric whitespace"
+          ],
+          "source": "v1.3.0 mobile smoke lesson (fallow-press 43px overflow)"
+        }
+      ]
+    },
+    "micro-interactions": {
+      "summary": "Small feedback animations — capture the state PAIRS, not just the motion.",
+      "techniques": [
+        {
+          "id": "hover-pair-capture",
+          "when": "Any build with interactive cards/nav/buttons.",
+          "how": [
+            "Screenshot element bounding-box at rest AND at hover (elementHandle.screenshot()), pair them in the inventory",
+            "Pair with hover-pair-style-diff for the CSS-level truth"
+          ],
+          "source": "Meridian validation loop (ours)"
+        },
+        {
+          "id": "cursor-follower-detection",
+          "when": "Award sites with custom cursors — invisible in screenshots, disruptive if uncloned.",
+          "how": [
+            "mousemove listener audit: elements moved by rAF against mouse position (transform updated within 50ms of mousemove)",
+            "Detect mix-blend-mode: difference / exclusion overlays — the classic custom-cursor signature"
+          ],
+          "source": "fallow-press + showcase builds (ours)"
+        }
+      ]
+    },
+    "images": {
+      "summary": "Image evidence discipline — the doctrine that findings carry proof extends to capture sets.",
+      "techniques": [
+        {
+          "id": "palette-extraction",
+          "when": "Design DNA from a hero image when the site's own palette metadata is absent.",
+          "how": ["ffmpeg -i hero.png -vf palettegen=max_colors=8 - > palette.png; sample the PNG"],
+          "source": "ffmpeg standard; awwwards palette field gaps"
+        },
+        {
+          "id": "capture-set-dedupe",
+          "when": "QA sets with 13+ pin shots — near-duplicates waste context when reviewing.",
+          "how": [
+            "Perceptual hash (block-mean 8x8 grayscale) per frame; drop frames with hamming distance < 4 from a kept neighbor",
+            "Node implementation is ~30 lines, no deps"
+          ],
+          "source": "perceptual hashing standard practice; our QA shot review overhead"
+        }
+      ]
+    }
+  },
+  "webSources": [
+    "https://arxiv.org (Scene Detection Policies and Keyframe Extraction, 2025)",
+    "https://openreview.net (K-frames: Scene-Driven Any-k Keyframe Selection)",
+    "https://www.twelvelabs.io/blog (Context Engineering for Video Understanding, 2025)",
+    "https://blink.new (Interactive Web Animation Cloner)",
+    "https://annnimate.com/blog (GSAP vs CSS animations 2026 — scroll-timeline support)",
+    "https://www.mindstudio.ai (The Learnings Loop)",
+    "https://ryandoser.com (Claude Code skills auto-update, 2026)",
+    "https://creatoreconomy.so (Self-improving skills: eval + memory)"
+  ]
+}

package/skills/awwwards-doctor/SKILL.md

@@ -88,6 +88,11 @@ The user's build/research doesn't wait for the repair. Degrade gracefully:
 - After the MCP is healthy again, **re-run the failed calls** and reconcile
   with whatever the fallback produced.
 
+## Close the flywheel
+
+Repairs are the highest-value lessons — they were expensive to learn. After a successful diagnosis + fix:
+`node scripts/skill-memory.mjs record --skill awwwards-doctor --phase repair --symptom "..." --rule "..." [--evidence <report path>]`. Distill folds recurring failure signatures into this installed copy so the next repair starts knowing them. When a rule proves out, `promote --skill awwwards-doctor` outputs it cleaned (no machine-local evidence paths) for the shipped-copy PR.
+
 ## Anti-patterns
 
 - Retrying blocked requests in a loop — politeness rules and block
@@ -98,3 +103,6 @@ The user's build/research doesn't wait for the repair. Degrade gracefully:
   parse that can't find its anchors must error loudly (that is the drift
   signal).
 - Treating the doctor's UNHEALTHY verdict as done because one check passed.
+
+<!-- skill-memory:start -->
+<!-- skill-memory:end -->

package/skills/awwwards-inspiration/SKILL.md

@@ -34,6 +34,7 @@ Run this loop before building anything visual:
    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.
 4. **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
@@ -80,6 +81,8 @@ Run this loop before building anything visual:
    is a structural bug no amount of pixel polish fixes. Match the reference's
    band structure, never just its total height.
 
+9. **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/
@@ -160,3 +163,6 @@ 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 -->

package/skills/awwwards-motion-study/SKILL.md

@@ -48,6 +48,8 @@ Three animation classes must all be on camera:
   (keep them in `ref-motion/` or `_qa/`). Awwwards content and site media
   belong to their creators — study them, don't republish them.
 
+Before recording, fingerprint the motion stack (techniques registry `skills/_memory/techniques.json` → motion-detection): library fingerprints in the captured HTML, hover-pair style diffs, transform-polling — the site names its own animation stack, and scene-detect-first (video-understanding domain) scopes your tiles.
+
 ## 2. How to capture
 
 Fast path first, fall back when it can't:
@@ -148,6 +150,11 @@ Verification is the same skill pointed at yourself:
    transition zones and look broken when they aren't.
 4. Fix what mismatches, re-record, repeat — one loop, not ten.
 
+## Close the flywheel
+
+End every capture/study pass by recording what verification caught:
+`node scripts/skill-memory.mjs record --skill awwwards-motion-study --phase motion-study --symptom "..." --rule "..." [--evidence tile.jpg]`. Distill folds rules seen ≥2× into your installed copy; recall prints them at the next study. The techniques registry (`skills/_memory/techniques.json`) grows from promoted findings — propose better methods by recording them. For the human PR that promotes a rule into the shipped copy, `promote --skill awwwards-motion-study` strips machine-local evidence paths.
+
 ## Anti-patterns
 
 - **Designing from posters or thumbnails** — posters are single frames; the
@@ -161,3 +168,6 @@ Verification is the same skill pointed at yourself:
 - **Studying nothing, animating from vibes** — "it probably fades in" is
   how builds drift from references.
 - **Republishing recordings** — captures are local study evidence.
+
+<!-- skill-memory:start -->
+<!-- skill-memory:end -->