design-scope

A curated 204-card design reference library with a natural-language style search, site capture tooling, and a local MCP server. Free, local, and private: no subscription, no cloud, no analytics.

Every card is a real site's design captured as a four-layer profile:

• fingerprint: measured tokens (colors, typography, spacing, radii)

• semantic: named tokens, design intent, z-index layers, responsive rules

• annotation: LLM design intelligence (vibe, what works, search terms)

• behavior: hover diffs, scroll triggers, interaction model

# search the library in plain English
python library/style_search.py "warm minimal serif"

# or through the MCP server, from any agent
# style_search(query="editorial but not brutalist")

Why

Reference libraries like Mobbin are paid and closed. design-scope is the open alternative: capture any site you like, search the curated 204-card library by design qualities instead of by brand, and let any agent borrow concrete palettes and patterns. Everything runs on your own machine.

Related MCP server: taste-mcp

What ships in the repo

The library works with media missing. Search, filter, compare, and theme borrowing all function from the intelligence layer alone. Screenshots and motion media are gitignored and can be rebuilt locally at any time.

Install

git clone git@github.com:unfoldingdimensions/design-scope-mcp.git
cd design-scope-mcp
pip install -r requirements.txt
playwright install chromium

Python 3.11 or newer. Tested on Windows and Linux; CI runs both.

Capturing new cards also needs Node.js. The capture pipeline shells out to npx -y dembrandt for design-token extraction. Searching, filtering, comparing, and theme borrowing need no Node. Without it, a capture still produces screenshots, but the token extraction step is skipped.

Quickstart

Search the library (CLI, no server needed):

python library/style_search.py "funky"
python library/style_search.py "editorial but not brutalist"
python library/style_search.py --json "dark minimal serif"

Capture a new card:

python library/capture.py --url https://stripe.com --name Stripe --category fintech
# batch from a seed file:
python library/capture.py seed-batch-1.json --limit 5

Rebuild media for cards that lost it (for example after a fresh clone):

python library/regenerate_media.py            # cards missing media only
python library/regenerate_media.py --fast     # skip motion and behavior passes

Annotate cards with the LLM intelligence pass (optional, needs NVIDIA_API_KEY):

python library/annotate.py

Using the MCP server from an agent

The server speaks the Model Context Protocol (MCP) over stdio and over streamable HTTP, so any MCP client can use it. It exposes 11 tools for searching the library, borrowing design decisions, capturing new sites, and grading pages. The server is read-only for your projects: it never edits project source.

Start the server

# stdio (recommended for agent harnesses)
python library/mcp_server.py

# or HTTP (streamable)
cd library && uvicorn mcp_server:app --host 127.0.0.1 --port 8232

Startup validation runs at import on both transports. If index.json or style-index.json are missing, the server refuses to boot and prints the exact fix command instead of failing per request later.

Hermes

Add the server to your Hermes MCP config as a stdio server. The server entry is the stdio command above. In the JSON shape most harnesses use:

{
  "mcpServers": {
    "design-scope": {
      "command": "python",
      "args": ["<path-to-repo>/library/mcp_server.py"]
    }
  }
}

If the design-scope skill is installed in a Hermes profile, the server automatically finds that skill's copies of compare.py and theme.py, so card_compare and theme_borrow use the skill's versions. No configuration is needed for that to happen.

Claude Code

claude mcp add design-scope -- python "<path-to-repo>/library/mcp_server.py"

Cursor

Add to .mcp.json in the project root:

{"mcpServers": {"design-scope": {"command": "python",
  "args": ["<path-to-repo>/library/mcp_server.py"]}}}

Any other harness

Any MCP client works. Use the stdio JSON snippet from the Hermes section above with your client's config format, or point a streamable-HTTP client at the uvicorn server on port 8232. The tool reference below is the full tool surface; point your agent at it and let it call tools directly.

A typical agent session

An agent building or restyling a page with design-scope usually runs this loop:

1. style_search with a direction ("dark minimal serif") to rank candidate cards and pick one.

2. card_get on the chosen slug for the full four-layer profile, including absolute paths to screenshots and motion media.

3. theme_borrow to get a token remap and contrast-guarded CSS it can apply to the project.

4. get_page_structure and get_section_blueprint for the page's band contract when composing a page from scratch.

5. verdict.py (repo script) to grade the result, or capture to add the site that inspired the work back into the library.

Tool reference

card_compare and theme_borrow work out of the box: they import compare.py and theme.py, which ship in this repo's scripts/ directory. At runtime the server resolves those scripts in this order: the DESIGN_SCOPE_SKILL_SCRIPTS environment variable, an installed design-scope skill, then the repo's own scripts/. Point the env var at your own copies to override. See docs/OSS.md for details.

Capture notes

• fast=True (default): screenshots, tokens, and semantic pass in about 60 seconds; motion and behavior are skipped. fast=False runs the full four-layer pass in about 4 minutes.

• why (optional, up to 300 characters) becomes the card's rationale and is shown in the gallery and used by search fallback.

• A duplicate slug fails the job with a hint (use a different slug or capture.py --redo).

• Bot-walled sites (HTTP 403 or 429) fail the job with the underlying error; retry later.

• A successful capture rebuilds style-index.json automatically, so the new card is searchable immediately.

Error convention

MCP has no error types, so every failure returns structured JSON:

{"error": "card 'nope' not found", "hint": "see style_search for valid slugs"}

Environment variables

Showcase and verdict

showcase/index.html is the project's one-page sheet, built and graded with the library itself. Every figure on it is counted from the library at build time, and the page is graded by the same scored rubric an agent gets:

python scripts/build_showcase.py      # inject fresh stats, verdict, ledger
python scripts/verdict.py showcase/index.html --label "R1" \
    --ledger showcase/verdicts.json --json showcase/verdict.json
python scripts/build_showcase.py      # rebuild so rubric and ledger rows are real

verdict.py measures the rendered DOM against six checks (band allocation, mechanism budget, palette conformance, fabric floor, reduced motion, living artefacts) and appends PASS or UNDER rows to a ledger that is never edited after it lands. The ledger keeps its failures. The exit code equals the number of UNDER rows.

One-shot pipeline

showcase/one-shot/index.html is the sheet whose decisions were made by the server: the palette was borrowed (style_search then theme_borrow, with a usability gate that rejects collapsed or low-contrast borrows and records the rejects), the structure was measured (section_scan over the corpus, then get_page_structure), and the page prints its own machine-written build receipt.

python scripts/section_scan.py --all              # corpus band inventory
python scripts/one_shot.py scaffold --brief "blueprint sheet" --direction "measured technical"
# fill scripts/sheet_content.py; rendering is the agent's job
python scripts/one_shot.py grade --label "R1 one-shot"   # verdict, ledger, rebuild

The band skeleton is rendered by scripts/blueprint.py from the structure: data-band and data-band-type and data-mechanism attributes per band, a <meta> contract matching the structure, scroll-reveal scaffolding, and a content layer (sheet_content.py) that survives re-scaffolds. Structure is corpus-measured when band-index.json exists; the curated v1 plan is the fallback on a fresh checkout.

Repository layout

library/
  mcp_server.py        the MCP server (stdio and HTTP)
  capture.py           capture pipeline (screenshots, tokens, motion)
  annotate.py          LLM design-intelligence pass
  semantic_pass.py     named tokens, design intent, z-index, responsive
  behavior_pass.py     hover diffs, scroll triggers, interaction model
  style_index.py       rebuild style-index.json from cards
  style_search.py      natural-language search CLI
  regenerate_media.py  rebuild gitignored media locally
  gallery.py           HTML gallery generator
  backfill.py          motion, behavior, and semantic backfill for old cards
  index.json           card registry (204 cards)
  style-index.json     searchable style vectors, archetypes, tags
  cards/<slug>/        per-card intelligence layer
scripts/
  verdict.py           scored six-check rubric reviewer (PASS/UNDER plus ledger)
  stats.py             corpus numbers counted fresh from the library
  build_showcase.py    inject stats, verdict, ledger into a sheet
  one_shot.py          the pipeline: prepare, scaffold, grade
  page_structure.py    the band contract, corpus-measured with curated fallback
  section_scan.py      corpus band inventory
  section_blueprint.py the contracted recipe for one band type
  blueprint.py         renders the band skeleton from a structure
  sheet_content.py     the agent's fill layer, stable across re-scaffolds
  compare.py           borrow candidates (card fingerprint vs project)
  theme.py             token remap plus contrast-guarded CSS
showcase/
  index.template.html  the hand-built sheet (both themes, self-contained)
  index.html           built artifact; open this one
  verdicts.json        the ledger; every verdict, never edited after it lands
  one-shot/            the one-shotted sheet, its register, and its ledger
docs/
  mcp.md               MCP server reference
  OSS.md               packaging and regeneration documentation
tests/                 smoke and unit suites (no framework needed)

Tests

python tests/client_smoke.py                  # real stdio MCP transport and error paths
python tests/client_smoke.py --queue          # in-process capture queue mock (no network)
python tests/test_style_search.py             # search layer unit tests
python tests/test_semantic_pass.py            # classifier and vocabulary guard
python tests/test_style_index.py              # vectors and hue boundaries (temp fixture)
python tests/test_behavior_pass.py            # hover-diff regression guard
python tests/test_vocabulary_consistency.py   # producers are a subset of search vocabulary

The unit suites and the queue mock run in CI on every push, on both ubuntu-latest and windows-latest. Shared test plumbing lives in tests/_harness.py.

Data provenance

Cards describe the design of third-party sites: factual metadata such as color tokens, typography, layout measurements, and interaction behavior, plus LLM annotations that deliberately avoid brand commentary. design-scope has no affiliation with any captured site. Screenshots and motion media are regenerated locally and never shipped in the repo. If you capture a site, respect its terms of use.

Contributing

Issues and pull requests are welcome. Good first contributions: capturing a missing category, improving the search vocabulary, or adding a test. Keep changes additive and non-destructive; the library is data, not a build artifact.

License

MIT. See LICENSE.