@yojahny/wp-design-library 0.1.0

package/.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+.library
+inbox
+models
+dist
+.git
+tests
+.superpowers
+.tokensave
+.claude
+.env

package/.env.example

@@ -0,0 +1,7 @@
+LIBRARY_TOKEN=change-me
+LIBRARY_DATA=/data
+PORT=4180
+LIBRARY_FETCH_MODELS=0    # 1 = fetch the vector-search models on server start (one-time, ~450 MB); set back to 0 after
+LIBRARY_MODELS=/data/models    # where the models land on the /data volume
+LIBRARY_EMBED=    # empty = real models when present, stub = deterministic vectors for checks, off = FTS only
+CHROME_SANDBOX=0    # 1 = let Chrome use its own sandbox; only where user namespaces are allowed (not the default container)

package/Dockerfile

@@ -0,0 +1,27 @@
+FROM node:22-bookworm
+# Base tools in their own layer so a Chrome failure is attributable.
+RUN apt-get update && apt-get install -y --no-install-recommends wget gnupg ca-certificates ffmpeg fonts-liberation \
+ && rm -rf /var/lib/apt/lists/*
+ARG WITH_CHROME=1
+# Chrome is for URL measurement (Phase 2). Set build arg WITH_CHROME=0 to skip it. Google ships amd64 only, so on any other
+# architecture the image says so and continues; the measure step refuses loudly at run time.
+RUN if [ "$WITH_CHROME" = "1" ] && [ "$(dpkg --print-architecture)" = "amd64" ]; then \
+      wget -qO- https://dl.google.com/linux/linux_signing_key.pub | gpg --dearmor -o /usr/share/keyrings/google.gpg \
+   && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google.gpg] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google.list \
+   && apt-get update && apt-get install -y --no-install-recommends google-chrome-stable \
+   && rm -rf /var/lib/apt/lists/* ; \
+    else echo "chrome: skipped (WITH_CHROME=$WITH_CHROME, arch $(dpkg --print-architecture))"; fi
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+# Vector-search models are not baked into the image: they land on the /data volume
+# under models/ and are fetched at container start when LIBRARY_FETCH_MODELS=1.
+ENV LIBRARY_DATA=/data PORT=4180 CHROME_PATH=/usr/bin/google-chrome NODE_ENV=production
+EXPOSE 4180
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s \
+  CMD node -e "fetch('http://localhost:4180/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+# Starts as root (needed to chown a volume from an older, root-owned run) and drops to
+# `node` via setpriv before exec'ing the real command; see docker/entrypoint.sh.
+ENTRYPOINT ["docker/entrypoint.sh"]
+CMD ["node", "bin/library.mjs", "serve", "--http"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yojahny Chavez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,382 @@
+# wp-design-library
+
+A library of design references for `claude-wp-builder`. You feed it recordings
+of sites you like; it stores a description of each one, tags, a contact sheet,
+and an honest note on the motion; and the plugin's `/wp-demo` reads it over MCP
+when it writes a brief, so every demo starts from real references instead of
+from memory.
+
+Two tiers. **Inspiration** entries describe a reference (any licence). **Ported**
+entries carry real HTML/CSS under the plugin's motion contract and are allowed
+only for `own` or `open` sources; the licence gate refuses anything else.
+
+## What you need
+
+- Node 22 or newer.
+- For video input: an animated **webp**, **gif**, or **mp4/mov/webm/mkv** (needs
+  the system `ffmpeg`/`ffprobe`). Record a scroll of the page with any screen
+  recorder and hand the file straight to `add`.
+- For URL input (`add https://…`, `refresh`): a system **Chrome or Chromium**
+  binary, pointed at by `CHROME_PATH`. See "Adding a live site" below.
+- A Claude Code session, for the tagging step. The server never guesses what a
+  design feels like; the session that runs the ingest does.
+
+```bash
+git clone git@github.com:yojahny55/wp-design-library.git
+cd wp-design-library && npm install
+npm test          # 24 checks, all should PASS (measure.sh SKIPs without a system Chrome)
+```
+
+## Adding an entry
+
+Adding is two steps by design: the tool does the mechanical part, a Claude
+session does the judgement part.
+
+### 1. Ingest: `library add`
+
+```bash
+node bin/library.mjs add ~/Desktop/site.webp \
+  --slug   acme-dark-hero \
+  --title  "Acme: dark landing with a pinned product hero" \
+  --source public-site \
+  --url    https://acme.example \
+  --license "captured from the live site; description only"
+```
+
+| Flag | Meaning |
+|---|---|
+| first argument | path to the webp/gif |
+| `--slug` | lowercase, digits and dashes; becomes the folder name |
+| `--title` | one line, what it is |
+| `--source` | `own`, `open`, `paid` or `public-site` (see Licence below) |
+| `--url` | where it came from (optional for `own`) |
+| `--license` | free text, required; say what you may do with it |
+| `--force` | overwrite an existing draft (otherwise a second `add` is refused) |
+
+This writes `entries/<slug>/strip.png` (6–12 sampled frames) and a draft
+`entries/<slug>/entry.md` with the mechanical fields filled and every
+judgement field blank. The output lists those blanks:
+
+```
+roles, feel, motion.devices, motion.notes, type.display, type.body, body,
+palette.canvas, palette.ink, palette.accent
+```
+
+### Adding a live site
+
+Point `add` at an `http://`/`https://` URL instead of a file and it measures the live
+page with the system Chrome (`playwright-core`) instead of sampling a recording:
+computed-style tokens (canvas, ink, accent, the display and body font stacks), a
+per-section animation inventory (CSS scroll-driven timelines included), and two
+screenshots (1440/390). `palette` and `type` are filled mechanically from those
+tokens — the raw font-family strings, not a human's words — and the draft still
+waits for a session to fill `roles`, `feel`, `motion.devices`/`motion.notes` and `body`.
+
+```bash
+CHROME_PATH=/usr/bin/google-chrome node bin/library.mjs add https://acme.example \
+  --slug   acme-live-hero \
+  --title  "Acme: dark landing" \
+  --source public-site \
+  --license "measured from the live site; description only" \
+  --record
+```
+
+| Flag | Meaning |
+|---|---|
+| `--record` | also scroll top to bottom in 12 steps at 1440 and build `strip.png` from those stops (`captured.method: both`); without it, `strip.png` is the single 1440 screenshot and `captured.method: measured` |
+
+`CHROME_PATH` must point at a Chrome or Chromium binary. Without it (or with a path
+that does not exist) `add` refuses with `chrome not available: …` and nothing is
+written under `entries/`. If `--record` captures its frames but the token/section
+measurement itself then fails, the draft is still written — `captured.method: frames`,
+with the reason in `captured.error`.
+
+#### Keeping a live entry current: `library refresh`
+
+```bash
+node bin/library.mjs refresh acme-live-hero
+```
+
+Re-measures `source.url` with the same system Chrome, rewrites `measure.json` and
+`captured.at`, and reindexes. Every judgement field (`roles`, `feel`, `palette`,
+`type`, `motion`, `body`…) and `strip.png` are left exactly as they were. Refuses an
+entry with no `source.url`, or one whose `captured.method` is `frames` (nothing came
+from a URL to re-measure). Over MCP, the same as the `refresh` tool: `{ slug }`.
+
+### Inbox: draft everything in the drop folder
+
+Drop recordings into `<data>/inbox` (webp, gif, mp4, mov, webm, mkv) and draft
+them all in one pass, without typing a slug or title per file:
+
+```bash
+node bin/library.mjs add --inbox --source public-site --license "captured from the live site; description only"
+```
+
+The slug comes from the file name (lowercased, non `[a-z0-9]` runs collapsed
+to a dash, trimmed) and the title from the slug with dashes turned back into
+spaces. A sidecar `<file>.json` next to a recording — `{"kind", "url",
+"license", "title"}` — wins over the flags for that file; a file with neither
+a sidecar nor `--source`/`--license` is refused, one line named, and the run
+still processes every other file. A file whose slug already has an entry is
+skipped, not overwritten. Two files that derive the same slug in one run are
+not both drafted: the second is refused, naming the first. A file name that
+derives no slug at all (`___.webp`) is refused rather than silently dropped.
+A `kind` outside `source.kind`'s vocabulary is refused at draft time, the
+same as `add`, not first at `save`. Output is one JSON line per file:
+
+```
+{"file":"acme-dark-hero.webp","slug":"acme-dark-hero","status":"drafted","frames":8}
+```
+
+`status` is `drafted`, `skipped`, or `refused` (with a `reason`); the process
+exits 1 if any file was refused. `--inbox` never saves — every draft still
+waits for a tagging session and `library save`.
+
+### From a Claude Code session: `/mcp__wp-design-library__add-entry`
+
+With the server registered in a session (the `claude-wp-builder` plugin registers it,
+or add it to any project's `.mcp.json`), the whole add is one slash command:
+
+```
+/mcp__wp-design-library__add-entry path=/abs/site.webp source=public-site
+```
+
+The server renders the prompt with the current vocabulary, the session ingests,
+reads the strip, fills every judgement field per the rubric, shows you the draft
+and waits for a yes, saves, and offers the commit and PR. The rubric lives in
+`src/mcp/prompts.mjs`; the plugin that consumes the library ships nothing for it.
+
+### 2. Tag: fill the blanks, then `library save`
+
+Open the strip and the draft in a Claude Code session and ask it to fill the
+blanks. The same works from the plugin: with the MCP server registered, say
+"add `~/Desktop/site.webp` to the design library as `acme-dark-hero`" and the
+session calls `add`, reads the strip, fills the draft, and calls `save_entry`.
+
+What goes where, with the values checked against `vocab.yaml`:
+
+| Field | What to write |
+|---|---|
+| `roles` | the page sections, from the role list: `hero, proof, feature, process, offer, testimonial, faq, closing, capability, explainer, page-head, footer` |
+| `feel` | 3–6 tags from the feel list: `dark, light, premium, playful, editorial, brutalist, saas, depth, minimal, warm, cold` |
+| `palette` | three hex values, eyeballed from the strip: canvas, ink, accent |
+| `type` | display and body: family feel, weight, tracking, in words |
+| `motion.devices` | from the motion list: `reveal, pin, pan, wipe, kinetic, parallax, count, drift, tilt, magnet, spotlight, stagger, marquee, stack, tabs` |
+| `motion.notes` | what was **seen**, per section; say it was eyeballed, and name what you could not tell |
+| body | three headed sections: `## What it does`, `## Section roster`, `## Why it works` |
+
+Aliases work (`pricing` → `offer`, `cta` → `closing`, `testimonials` →
+`testimonial`); anything outside the vocabulary is refused with the facet and
+term named. A term is added by editing `vocab.yaml` in a PR, never by an
+ingest.
+
+Then:
+
+```bash
+node bin/library.mjs save acme-dark-hero
+```
+
+`save` validates every field, applies the licence gate, and reindexes. On
+refusal it prints one line per problem and exits 1. On success:
+
+```
+{"ok":true,"slug":"acme-dark-hero","errors":[]}
+```
+
+Tip: a 12-frame strip is one frame every two seconds and can miss a device that
+lives in one section. If the recording is long, sample more frames yourself
+(any image tool) and read two sheets before writing the motion note.
+
+### 3. Ship it
+
+```bash
+git checkout -b content/acme-dark-hero
+git add entries/acme-dark-hero
+git commit -m "content: acme dark hero"
+git push -u origin content/acme-dark-hero    # then open a PR
+```
+
+After the merge, redeploy the hosted instance. On every start the server copies
+entries it does not have yet into the volume and never overwrites what is
+already there, so the new entry appears without touching the volume by hand.
+
+## Licence and the two tiers
+
+`source.kind` says where a reference came from and decides what may be built
+from it:
+
+| kind | meaning | may become `tier: ported` |
+|---|---|---|
+| `own` | you made or recorded it | yes |
+| `open` | openly licensed (MIT, CC, …), named in `license` | yes |
+| `paid` | a paid or proprietary resource, kit media, template pack | no |
+| `public-site` | a live site you did not make | no |
+
+A ported entry adds `ported/section.html`, `ported/section.css`, a README, and
+`ported_from: <inspiration slug>`. `save` and `index` refuse `tier: ported` on
+a `paid` or `public-site` source, and there is no override flag.
+
+## Searching
+
+The plugin does this for you, but from the CLI:
+
+```bash
+node bin/library.mjs index         # rebuild the index from entries/
+node bin/library.mjs check         # validate every entry, 1 line per problem
+```
+
+Over MCP, six tools: `search` (keyword + facet filters, aliases resolved),
+`get_entry`, `similar`, `add`, `refresh`, `save_entry`. `search` and `similar` carry
+`arms` (which retrieval arms ran; `["fts"]` in Phase 1); any tool may instead respond
+with `refused` and the reason.
+
+## Vector search
+
+`index` also builds a `vec` arm — two `sqlite-vec` tables (`vec_text` 384-d,
+`vec_image` 768-d) alongside the FTS5 one — when an embedder is available.
+`getEmbedder` picks one of three arms:
+
+- `LIBRARY_EMBED=stub` — a deterministic, offline, hash-derived vector. No
+  semantics, no download; it exists so checks can exercise the `vec` arm
+  without a network.
+- unset, both model dirs present under `paths().models` — the real
+  `@huggingface/transformers` embedder (`Xenova/all-MiniLM-L6-v2` for text,
+  `Xenova/siglip-base-patch16-224` for images).
+- `LIBRARY_EMBED=off`, or unset with a model dir missing — no embedder;
+  `index` builds `fts` only and reports why on stderr
+  (`embeddings: skipped (<reason>)`).
+
+Fetch the real models once with:
+
+```bash
+node bin/library.mjs check --fetch-models   # downloads into <models>, prints both dirs
+```
+
+On the container, set `LIBRARY_FETCH_MODELS=1` instead: `serve --http` fetches the
+models onto the `/data` volume between the seed sync and the index build, logs the
+attempt to stderr, and continues either way — the MCP API never depends on it. It's a
+one-time download (~450 MB); set the flag back to `0` once the volume has both model
+dirs so every later start skips it. Swapping a model requires `library index` (or a
+restart) afterward — the index is disposable and does not notice a model change on
+its own.
+
+Known ceiling: the vector arm has no relevance floor, so a query with no keyword
+match still returns its nearest neighbours, distinguishable only by `ranks.fts === null`.
+
+## Running the server
+
+```bash
+node bin/library.mjs serve          # stdio, for a local Claude Code session
+LIBRARY_TOKEN=… node bin/library.mjs serve --http    # Streamable HTTP on :4180
+```
+
+`serve` builds the index on start, so a fresh clone answers `search` at once.
+Over HTTP, `/mcp` needs `Authorization: Bearer <LIBRARY_TOKEN>`, `/healthz`
+reports the entry count, and `add`/`similar` may only read files under
+`<data>/inbox`, including a path that turns out not to exist (a dangling
+symlink included).
+
+`node bin/library.mjs export > entries.tar` tars `<data>/entries` to stdout
+(the entry count goes to stderr) — a way to pull every entry back out of a
+running volume without shelling into the container (buffered in memory, 1 GiB
+ceiling). The tar includes drafts whose judgement fields are still blank; save
+or delete them before committing an export into `entries/`, or every server
+start will log them as refused. `export --saved-only` leaves drafts (an entry
+whose `entry.md` fails validation) out of the tar and prints how many were
+skipped to stderr.
+
+| Env | Default | Purpose |
+|---|---|---|
+| `LIBRARY_DATA` | repo root | where `entries/` and the index live (the volume in Docker) |
+| `LIBRARY_SEED` | `<repo>/entries` | entries copied into `LIBRARY_DATA` on start when missing |
+| `LIBRARY_TOKEN` | none | required for `--http`; the server refuses to start without it |
+| `PORT` | `4180` | HTTP port |
+| `LIBRARY_EMBED` | none (real embedder if models present, else skipped) | `stub` for the offline deterministic embedder, `off` to skip the `vec` arm |
+| `LIBRARY_MODELS` | `<data>/models` | where the `@huggingface/transformers` model files live |
+| `LIBRARY_FETCH_MODELS` | `0` | `1` = `serve --http` fetches the models onto `LIBRARY_MODELS` on start (one-time, ~450 MB); set back to `0` after |
+| `CHROME_PATH` | none | path to a Chrome/Chromium binary; required by `add <url>` and `refresh` (the Docker image sets it to `/usr/bin/google-chrome`) |
+| `CHROME_SANDBOX` | `0` | `1` = let Chrome use its own sandbox; only where user namespaces are allowed (not the default container, see "Known ceilings") |
+
+## Gallery
+
+A static gallery so a human can browse what the MCP server serves: a grid of
+every entry, filterable by the same five facets as `search` (role, feel,
+motion, source, tier), and a per-entry page with the strip, tags, licence and
+prose. Drafts (an entry whose `entry.md` fails validation) are included with a
+`draft` badge, behind a `Show drafts` toggle — never hidden silently.
+
+```bash
+node bin/library.mjs ui                    # builds <data>/ui from entries/
+node bin/library.mjs ui --serve            # ...and serves it on :4180 (no auth)
+node bin/library.mjs ui --serve --port 4181
+```
+
+`serve --http` builds the same gallery on every start and serves it at `/`
+(a build failure logs to stderr and the MCP API starts anyway — the gallery
+never gates it). `library ui --serve` serves the identical files standalone,
+without `/mcp` or `/healthz`. Both paths refuse to serve anything outside
+`<data>/ui`, including an encoded `/%2e%2e/`.
+
+`manifest.json` is a build artefact — `tests/checks/ui-build.sh` asserts against it,
+and the server otherwise just serves it as-is alongside the HTML. Because the
+gallery is rebuilt at server start, not on every save, an entry saved over MCP
+does not appear at `/` until the next restart.
+
+### Registering in claude-wp-builder
+
+The plugin ships `.mcp.json` pointing at `npx -y @yojahny/wp-design-library serve`.
+To use the hosted instance instead, put in your project's `.mcp.json`:
+
+```json
+"wp-design-library": {
+  "type": "http",
+  "url": "https://wp-design-library.yojahny.dev/mcp",
+  "headers": { "Authorization": "Bearer <token>" }
+}
+```
+
+## Deploying (Coolify)
+
+Docker Compose build pack, compose file at `/docker-compose.yml`, one service
+`library`, one volume at `/data`, `LIBRARY_TOKEN` as a secret. Build arg
+`WITH_CHROME=0` skips the Chrome install on hosts that cannot reach Google's
+apt repo (Chrome is for `add <url>`/`refresh`, see "Adding a live site" above —
+without it, both refuse with `chrome not available`). Verify with
+`curl https://<domain>/healthz`.
+
+The container runs as `node` (uid 1000), not root: `docker/entrypoint.sh` starts as
+root only to `chown` an existing (possibly root-owned) `/data` volume, then drops to
+`node` via `setpriv` before exec'ing the server.
+
+## Known ceilings
+
+- **Chrome runs without its own sandbox inside the container.** Docker's default
+  seccomp profile blocks the user namespaces Chrome's sandbox needs, so
+  `chromiumSandbox: true` would fail to launch there; the non-root container user is
+  the isolation instead. Set `CHROME_SANDBOX=1` only where user namespaces are
+  allowed (e.g. bare metal, not the default container).
+- **The URL guard checks the address once, before launch.** Hosted `add` and
+  `refresh` refuse a host that resolves to a private address at call time. A DNS
+  answer that changes between that lookup and Chrome's own resolution, or a public
+  page that redirects to a private address, is followed inside Chrome and not
+  re-checked. The bearer token is the boundary those two cases rely on.
+- **The entrypoint chowns `/data` on every start.** It walks the whole volume
+  (models and entries) so an old root-owned volume keeps working with no operator
+  step; start latency grows with the corpus. Replace it with an ownership probe if it
+  ever shows up in the health-check window.
+
+## Layout
+
+```
+entries/<slug>/entry.md   frontmatter + prose (the corpus, reviewable in PRs)
+entries/<slug>/strip.png  contact sheet
+vocab.yaml                controlled vocabulary, five facets, aliases
+src/ingest/               frames, draft, save
+src/index/                SQLite FTS5 build and query
+src/mcp/                  tool table, stdio and HTTP transports
+src/ui/                   static gallery: build, templates, app.js, the shared static server
+tests/checks/*.sh         one contract per script, PASS or non-zero
+```
+
+The index (`.library/index.sqlite`) is disposable; delete it and any `serve`
+or `index` rebuilds it from the markdown.

package/bin/library.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+const cmds = {
+  check: () => import('../src/cli/check.mjs'),
+  index: () => import('../src/cli/index.mjs'),
+  serve: () => import('../src/cli/serve.mjs'),
+  add: () => import('../src/cli/add.mjs'),
+  refresh: () => import('../src/cli/refresh.mjs'),
+  save: () => import('../src/cli/save.mjs'),
+  export: () => import('../src/cli/export.mjs'),
+  ui: () => import('../src/cli/ui.mjs'),
+};
+const [cmd, ...args] = process.argv.slice(2);
+if (!cmds[cmd]) {
+  process.stderr.write(`usage: library <${Object.keys(cmds).join('|')}> [args]\n`);
+  process.exit(64);
+}
+const mod = await cmds[cmd]();
+const code = await mod.run(args);
+process.exit(typeof code === 'number' ? code : 0);

package/docker/entrypoint.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Adopts a root-owned /data volume (from an older container run, or a fresh
+# Docker-created volume) onto the `node` user, then drops root before exec'ing
+# the real command. Not root already (e.g. `docker run --user`) -> nothing to do.
+set -e
+if [ "$(id -u)" = "0" ]; then
+  mkdir -p /data
+  chown -R node:node /data || true
+  exec setpriv --reuid=node --regid=node --init-groups "$@"
+fi
+exec "$@"

package/docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+  library:
+    build: .
+    ports:
+      - "4180:4180"
+    environment:
+      LIBRARY_TOKEN: ${LIBRARY_TOKEN:?LIBRARY_TOKEN must be set}
+      LIBRARY_DATA: /data
+      PORT: 4180
+      LIBRARY_FETCH_MODELS: ${LIBRARY_FETCH_MODELS:-0}
+      LIBRARY_MODELS: ${LIBRARY_MODELS:-/data/models}
+      LIBRARY_EMBED: ${LIBRARY_EMBED:-}
+      CHROME_SANDBOX: ${CHROME_SANDBOX:-0}
+    volumes:
+      - library-data:/data
+    restart: unless-stopped
+volumes:
+  library-data:

package/entries/ais-community-dark-depth/entry.md

@@ -0,0 +1,76 @@
+---
+slug: ais-community-dark-depth
+title: 'AI Automation Society: dark community landing with mountain parallax hero'
+tier: inspiration
+source:
+  kind: paid
+  url: https://github.com/nateherkai/scroll-craft/blob/main/media/ais.webp
+  license: scroll-craft media file; description only, no redistribution of the source
+captured:
+  method: frames
+  at: '2026-09-14'
+  tool: wp-design-library@0.1.0
+media:
+  frames: 228
+  duration_ms: 22800
+roles: [hero, explainer, capability, feature, proof, offer, faq, closing, footer]
+feel: [dark, premium, saas, depth, minimal, cold]
+palette:
+  canvas: '#0b1218'
+  ink: '#f2f5f8'
+  accent: '#7fb6ff'
+type:
+  display: geometric sans (Montserrat-like), medium weight, tight tracking, two-line headlines with a soft break
+  body: same family, regular, small and muted at roughly 60% ink
+motion:
+  devices: [parallax, drift, reveal, stagger, pin, stack, tabs]
+  notes: >-
+    Eyeballed from 12 sampled frames, not measured. The hero is a layered scene: a
+    dark-blue sky gradient, two mountain silhouettes and a treeline, with the
+    app frame in front. On scroll the frame rises faster than the bed and the
+    bed than the sky (parallax, three depths), and the frame keeps drifting up
+    into the next section before the about copy takes over. The about copy is
+    painted dim and brightens as it enters (reveal on the text block, not on a
+    wrapper). Then the stacked cards, the page's second set piece: four
+    feature cards (Courses, Weekly calls, Rooms, Certification) each pin at
+    the same screen position while the next slides up over it, so the reader
+    scrolls through a deck rather than down a list; the hand-off is a slide
+    from below, not a fade, and the covered card stays put underneath. Before
+    them, the "One place to learn" panel is a tabbed card (Classroom, Live
+    calls, Events, Leaderboards) whose active tab changes on its own. The
+    three pricing cards and the video cards arrive as staggered reveals. The
+    closing section repeats the hero scene and frame at a smaller scale, so
+    the page ends where it began.
+ported_from: null
+---
+
+## What it does
+
+A community landing page in a single dark world. The mountain scene is the
+only illustration and it carries the whole feel; everything else is glassy
+dark cards with hairline borders and one cool accent. Copy is short and
+confident, section labels are small pill badges above each headline, and the
+same sentence shape ("Where 450,000 people learn to use AI for real work")
+returns at the end as "Start where 450,000 others started".
+
+## Section roster
+
+hero (scene + floating app frame), explainer (two paragraphs of dimmed long
+copy, no image), capability ("One place to learn": tabbed panel with a call
+grid), feature (the stacked deck: Courses step by step with tiled chips,
+Weekly calls with a call grid, Rooms with a photo, Certification with a
+photo, each card pinning while the next covers it), offer (three tiers: free, monthly, cohort, with check lists), faq
+(accordion with a side card), feature (video card row "Practical AI, every
+week"), closing (hero scene repeated, small), footer (four columns).
+
+## Why it works
+
+One illustration at three depths gives the page more presence than any number
+of stock photos would, and because it is dark the glassy cards read as lit
+from the scene. The dimmed-then-bright copy makes a wall of text feel like a
+reveal instead of a paragraph. The stacked deck turns four feature cards into
+one continuous motion, so the middle of the page has a set piece of its own
+instead of a row of equal boxes. Reusing the hero scene at the close makes the
+CTA feel like a return rather than a new ask. Cost to weigh: everything
+depends on that one scene being good; with a weak illustration the page is
+just dark cards.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@yojahny/wp-design-library",
+  "version": "0.1.0",
+  "description": "Design reference corpus and MCP server for claude-wp-builder",
+  "type": "module",
+  "bin": { "library": "bin/library.mjs" },
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "test": "bash tests/run.sh",
+    "check": "node bin/library.mjs check",
+    "index": "node bin/library.mjs index",
+    "serve": "node bin/library.mjs serve"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "4.2.0",
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "better-sqlite3": "^12.2.0",
+    "js-yaml": "^4.1.0",
+    "playwright-core": "1.63.0",
+    "sharp": "^0.34.3",
+    "sqlite-vec": "0.1.9",
+    "zod": "^3.25.0"
+  },
+  "license": "MIT",
+  "private": false
+}