Marque Documentation

Capture the design language of any website and inject it into every AI coding tool in your workflow. This guide covers installation, the MCP workflow, all CLI commands including blend and improve, configuration, output formats, and the architecture behind the stamp-synthesize-sync pipeline.

Try It

See how Marque captures a reference site, synthesizes a design mark, and syncs to all your AI tools. Pick a site and hit Capture.

marque

Enter any URL and click Capture to extract real design tokens.

Getting Started

Installation

Marque requires Node.js 18+. No account or API key needed.

$ npm install -g marque-cli

Install globally

$ npx marque-cli init

Or run directly without installing

The init wizard will ask you about your product:

Product name

Mission statement

Target audience

Brand personality (3-5 adjectives)

Product category

Visual personality (free-form description)

Design heroes (reference sites you admire)

Mood keywords

First capture

Point Marque at any reference site. It launches a headless Playwright browser, scrapes CSS tokens, typography, layout patterns, scroll choreography, and captures screenshots at every section boundary.

$ marque stamp https://linear.app

Scrapes the site and returns a synthesis prompt -- takes about 30 seconds

$ marque synthesize --apply

Your agent reads raw scrape data and produces a structured design mark

$ marque sync

Writes design language to all 10 agent instruction formats

MCP setup

$ marque mcp setup

Project-level -- writes to .claude/mcp.json, .cursor/mcp.json

$ marque mcp setup --global

Global -- persists across all projects

Once registered, your agent gets access to tools that mirror the CLI directly: status(), stamp(url), synthesize(mark), generate(section), diff(url), get_design_context_for(section), get_tokens(), and get_anti_defaults(). The agent explicitly states which CLI command it is running at each step.

MCP Workflow

When the Marque MCP server is active, your agent follows a structured workflow. Each MCP tool maps directly to a CLI command — the agent announces which command it is running at every step.

Setup workflow (first time)

01

status()→ marque status

Check project state — see what exists and what to do next. Returns projectRoot so you can verify files land in the right directory.

02

init(name, freeformBrief)→ marque init

Initialize Marque if no config exists. Pass product name and a free-form description of what it does and who uses it.

03

stamp(url)→ marque stamp <url>

Scrape a reference site. Returns raw design data and a synthesis prompt for the agent to fill.

04

(agent synthesizes)

Agent reads the synthesis prompt and generates a design mark JSON from the raw data using its own reasoning. No external API call.

05

synthesize(mark)→ marque synthesize --apply

Save the synthesized mark. Auto-syncs to .cursorrules, AGENTS.md, .claude/instructions.md, and 7 other rule files.

Build workflow (ongoing)

01

get_design_context_for(sectionType)

Call this before writing any component. Returns creative direction, tokens, anti-defaults, and blueprints for the specific section type.

02

get_anti_defaults()

Returns what NOT to build — common AI defaults that violate this product's mark. Check this before any design decision.

03

generate(sectionType)→ marque generate <section>

Returns a full grounded build prompt for a section — metaphor, anti-defaults, exact token values, tech stack profile, and animation sequence.

04

diff(url)→ marque diff --url <url>

Screenshots the running app, compares to reference, returns specific element-level corrections.

05

get_tokens()

Returns exact token values to use: color semantics, typography, spacing, border radius. Use these directly — do not substitute generic utilities.

CLI Reference

All commands are stateless filesystem operations. The .marque/config.json file is the source of truth.

Setup

init

marque init

Interactive wizard that creates .marque/config.json with your product identity. Auto-syncs agent rule files after setup.

stamp

marque stamp <url> [--label <name>]

Scrapes a website using Playwright. Extracts CSS tokens, colors, fonts, spacing, animations, scroll storyboard, and captures screenshots at section boundaries. Returns a synthesis prompt for your agent to fill. Takes about 30 seconds.

Flag	Type	Default	Description
-l, --label	string	domain	Custom label for this reference

example

$ marque stamp https://stripe.com

Launching Playwright...

Scraping CSS tokens done

Recording scroll story done

Capturing screenshots 22 saved

Synthesis prompt ready. Your agent will now generate the mark.

synthesize

marque synthesize [--apply [filepath]]

Without flags, re-prints synthesis prompts from stored raw scrape data. With --apply, reads the agent-produced design mark JSON from stdin or file, validates it against the schema, saves it to config, and auto-syncs all agent rule files.

Flag	Type	Default	Description
-a, --apply	string \| bool	.marque/pending-mark.json	Load and apply agent-produced mark from file or stdin

sync

marque sync

Manually re-sync all agent rule files. Formats your design language and writes it to all 10 sync targets. Usually auto-triggered when config changes.

Agent Setup

mcp setup

marque mcp setup [--global]

Registers Marque as an MCP server in your AI tools. Project-level writes to .claude/mcp.json, .cursor/mcp.json, and mcp_servers.json. Global mode writes to ~/.claude/mcp.json and ~/.cursor/mcp.json for cross-project access.

Flag	Type	Default	Description
-g, --global	bool	false	Register globally instead of per-project

Build

generate

marque generate <section>

Generates an agent prompt for designing a UI section. Built-in section types: hero, features, pricing, cta, footer. The prompt includes creative intent, section guidance, anti-defaults, tokens, and patterns.

Flag	Type	Default	Description
-p, --prompt	bool	false	Force generation prompt even if template exists
-a, --apply	string	-	Write JSX directly to file

diff

marque diff --url <url> | --screenshot <path>

Screenshots your dev server (or uses an existing screenshot) and compares it against reference screenshots. Your agent produces corrections.

Flag	Type	Default	Description
-u, --url	string	-	Dev server URL to screenshot
-s, --screenshot	string	-	Use existing screenshot file
-a, --apply	string \| bool	-	Save corrections to .marque/corrections.md
-r, --resolved	bool	false	Mark all pending corrections as resolved

example

$ marque diff --url http://localhost:3000

Capturing screenshot...

Comparing against 3 reference sections...

Agent will produce corrections.

watch

marque watch

Watches tagged exemplar components for changes. Re-extracts patterns on file save and re-syncs rule files automatically.

Quality

audit

marque audit

Scans your codebase for anti-default violations. Checks colors, border radius, typography, and spacing against your design language. Outputs a compliance score 0-100 with letter grade.

Flag	Type	Default	Description
-s, --strict	bool	false	Treat all violations as critical
-t, --threshold	number	-	Exit with error if score below value (for CI)
-j, --json	bool	false	Output full result as JSON
-a, --apply	string \| bool	-	Generate fix prompt for every violation
-d, --src-dir	string	src	Source directory to scan

example

$ marque audit

Scanning src/...

Found 3 violations in 12 files

Score: 87/100 Grade: B+

ci setup

marque ci setup

Generates a GitHub Actions workflow file that runs design audits on every PR. Fails the build if the design score drops below the threshold.

Flag	Type	Default	Description
-t, --threshold	number	80	Fail build if score below this
-d, --src-dir	string	src	Source directory to audit

badge

marque badge

Prints a shields.io badge URL for your design compliance score. Add it to your README. Requires running marque audit first.

score

marque score --url <url>

Screenshots a live website and has your agent evaluate it against your design mark. Scores 6 areas: color, border-radius, typography, layout, anti-defaults, and cohesion. Returns overall score 0-100 with grade and observations.

Flag	Type	Default	Description
-u, --url	string	-	URL to screenshot and score
-s, --screenshot	string	-	Use existing screenshot
-a, --apply	string \| bool	-	Save score JSON to .marque/pending-score.json
--show	bool	false	Display last saved score

improve

marque improve <url> [--loop] [--target <score>]

Combined audit + diff + score improvement loop. Screenshots your running dev server, compares it to your design mark, and produces a corrections brief with specific element-level fixes. With --loop, watches your source directory and re-scores on every file change — running until the score reaches the target threshold.

Flag	Type	Default	Description
-l, --loop	bool	false	Watch src/ and re-run on every file change
-t, --target	number	85	Stop the loop when score reaches this threshold
-s, --section	string	-	Focus corrections on a specific section type

example

$ marque improve http://localhost:3000 --loop --target 85

Score: 61/100 8 violations found

Watching src/ for changes...

[change detected] Re-scoring...

Score: 74/100 5 violations

[change detected] Re-scoring...

Score: 88/100 Target reached.

Inspect

status

marque status

Shows your full design profile: identity card, references count, mark status, token summary, anti-defaults, section templates, pending corrections, and stale references.

context

marque context [-f format]

Prints the formatted design context that gets injected into agent rule files. Useful for debugging what your agents actually see.

Flag	Type	Default	Description
-f, --format	string	markdown	Output format: markdown, cursor, or json

refresh

marque refresh [--stale]

Re-scrapes all reference URLs and merges updated data. Use --stale to only refresh references older than 30 days.

Flag	Type	Default	Description
-s, --stale	bool	false	Only refresh references older than 30 days

add component

marque add component <path>

Tags a component file as an exemplar (good pattern to follow) or anti-pattern (what to avoid). Extracts up to 2000 characters of pattern code for agent reference.

Flag	Type	Default	Description
-l, --label	string	-	Custom label for the component
-t, --type	string	exemplar	Component type: exemplar or anti-pattern
-n, --notes	string	-	Explanation of why this is exemplar/anti-pattern

review

marque review [dir]

Scans a directory for untagged components. Helps you find components that should be marked as exemplar or anti-pattern.

Flag	Type	Default	Description
-d, --dir	string	src/components	Directory to scan

Blend

Real design taste is rarely singular. You want the motion sensibility of one site and the information density of another. marque blend scrapes multiple reference URLs in parallel and synthesizes a weighted hybrid mark from their combined vocabularies.

$ marque blend lusion.co vercel.com

Equal-weight blend of two references

$ marque blend lusion.co vercel.com 0.7 0.3

70% lusion motion vocabulary, 30% vercel token system

How blending works

ColorsDominant reference wins background, surface, and text. Minor reference contributes its accent as accent-secondary. Unique semantic keys from either side are included.

TypographyFont family and letter-spacing come from the higher-weighted reference. Numeric size values are interpolated by weight across both scales.

MotionTiming rules and easing curves are merged. Conflicts resolve by weight. You can pin motion to a specific reference with --motion-ref first|second.

Anti-defaultsUnion of both references. If either site avoids something, the blend avoids it too — the more restrictive rule always wins.

PatternsStructural patterns are pulled from both references and deduplicated. Unique patterns from each side are included in full.

MetaphorA new conceptPhilosophy is generated that describes the creative tension between the two references as a design identity — not an average, but a resolution.

blend

marque blend <urlA> <urlB> [weightA] [weightB]

Scrapes both URLs in parallel (or uses cached snapshots), performs a weighted merge across all design dimensions, generates a new synthesis prompt, and saves the blended mark as the active design language.

Flag	Type	Default	Description
--motion-ref	string	dominant	Pin motion vocabulary to first, second, or dominant reference
-l, --label	string	blend	Label for the blended mark

Improve Loop

Marque front-loads design intelligence at the start of a build. The improve loop closes the other end: it actively measures your running implementation against the mark and pulls it back toward compliance on every iteration.

Without the loop, agents drift. They start with the right tokens and by the third component they are back to generic defaults. The improve loop treats the mark as a living contract.

How it works

ScreenshotCaptures your running dev server at the specified URL using Playwright.

ScoreSends the screenshot alongside the full mark to a vision model. Gets back specific element-level violations: selector, rule broken, what the mark says it should be.

WriteViolations are written to .marque/corrections.md with line-by-line fixes. Each iteration appends a timestamped snapshot.

WatchWith --loop, monitors your src/ directory for file changes. Any save triggers a re-screenshot and re-score.

DeltaAfter each iteration, shows score delta: what improved, what regressed, how many violations remain.

StopLoop exits automatically when the score reaches --target, or when you press Ctrl+C.

$ marque improve http://localhost:3000 --loop --target 85

Run until implementation scores 85/100 against the mark

$ marque improve http://localhost:3000 --section hero

Focus corrections on the hero section only

Configuration

All configuration lives in .marque/config.json at your project root. Marque searches upward from the current directory to find it.

Identity

Your product identity drives every synthesis decision. It is the first thing agents read.

.marque/config.json

{

"identity": {

"name": "Acme",

"mission": "Project management for developers",

"targetAudience": "Engineering teams",

"brandPersonality": ["precise", "minimal", "fast"],

"productCategory": "Developer tools",

"visualPersonality": "Feels like Linear meets Terminal",

"designHeroes": ["linear.app", "vercel.com"],

"moodKeywords": ["sharp", "dark", "focused"]

}

References

Each reference captures a complete snapshot of a scraped site: colors, typography, layout, scroll storyboard, and screenshots.

reference structure

"references": [{

"id": "ref_abc123",

"url": "https://linear.app",

"label": "linear.app",

"snapshot": {

"fetchedAt": "2026-02-28T...",

"colors": ["#000", "#5E6AD2", "#8A8F98"],

"typographyScale": "Inter: 400,500,600; 72/56/40px",

"scrollStoryboard": { ... },

"screenshotPaths": ["./screenshots/ref-001.png"]

}

}]

Components

Tagged exemplar and anti-pattern components. Their extracted code is included in agent context so your agent learns from your best (and worst) work.

component tagging

"components": [{

"path": "src/components/Button.tsx",

"type": "exemplar",

"label": "Primary button",

"notes": "Follows token system perfectly",

"extractedPattern": "export function Button..."

}]

Generated files

Marque creates and manages these files in the .marque/ directory:

config.jsonPrimary configuration -- source of truth

pending-mark.jsonAgent-produced design mark awaiting --apply

pending-score.jsonAgent-produced visual compliance score

corrections.mdPending design corrections from diff

screenshots/Reference screenshots from capture

mark-export.jsonExported design mark for sharing

synthesis-prompt-*.txtGenerated synthesis prompts per reference

Output Formats

Sync targets

Marque writes your design language to 10 agent instruction files simultaneously. Each file is auto-generated and prefixed with a warning header.

.cursorrulesCursor (legacy)

.cursor/rules/marque.mdcCursor v0.47+

.github/copilot-instructions.mdGitHub Copilot

.claudecodeClaude Code (legacy)

.claude/instructions.mdClaude Code

.windsurfrulesWindsurf

AGENTS.mdOpenAI Codex CLI

.agent/rules/marque.mdAntigravity

.marque.mdStandalone reference

mission.mdAntigravity identity (shorter)

Context sections

The formatted context that gets injected into each file contains up to 10 prioritized sections, token-optimized to fit within agent context limits:

Identity + Creative Intent

Product name, mission, visual vocabulary, brand-to-design rationale

Design Philosophy

Core principles presented as internalized creative constraints

Visual Overrides (Anti-Defaults)

What NOT to use, what to use instead, and why

Design Tokens

Spacing, color semantics, typography, radius, shadows

Section Guidance

Composition direction for each section type

Pattern Library

Named patterns with descriptions, usage, and code examples

Scroll Choreography

Animation timing, pinning, parallax, library instructions

Animation Palette

Curated CSS + JSX animations that match the brand

Freedom Zones

Areas where the agent is encouraged to experiment

DO / DON'T Rules

Positive rules, negative rules, user principles, exemplars

Architecture

Marque operates as a three-phase pipeline. All commands are stateless filesystem operations -- the .marque/config.json file is the single source of truth.

Stamp

Playwright scrape

-->

Synthesize

Agent in-context

-->

Sync

10 rule files

-->

Improve

Score loop

Phase 1: Stamp

Marque launches a headless Chromium browser via Playwright (viewport 1440x900). It navigates to the target URL, waits for network idle, then extracts:

CSS properties: colors, typography, spacing, radius, shadows, backdrop filters

Typography hierarchy: font families, sizes, weights, H1-H3 and body scales

Layout patterns: container widths, grid patterns, alignment, density

Component blueprints: button styles, input styles, icon analysis

Scroll storyboard: section types, animation triggers, pinned elements, snap points

Screenshots: captured at strategic scroll points, stored in .marque/screenshots/

Phase 2: Synthesize

Your AI agent (in your editor or terminal) reads the raw scrape data plus your product identity. It produces a structured design mark JSON document containing tokens, anti-defaults, patterns, section guidance, scroll choreography, and animation palettes. This JSON is validated against a Zod schema before being saved.

Phase 3: Sync

The format engine takes your design mark and produces a token-optimized markdown string (default 4000-token budget). Content is prioritized: identity and anti-defaults first, patterns and animations last. This formatted context is written to all 10 sync targets simultaneously.

Presets

Marque ships with 5 hand-crafted design systems distilled from extensive analysis of real products. Use them as starting points or merge them with your own mark.

$ marque use linear

Apply the Linear preset

$ marque use stripe --base

Merge Stripe preset with your existing mark

linear

Maximum contrast, ruthless reduction, precision engineering. Pure black backgrounds, muted purple accent, near-sharp corners, no shadows.

stripe

Rich color with careful layering. Navy backgrounds, indigo accent, soft 12px radius, gradient borders, premium depth.

vercel

Pure black-white contrast, monochrome restraint. No color accents -- uses inversion (white-on-black CTAs), sharp 6px radius, flat borders.

notion

Warm off-white, editorial typography. Georgia serif body text, barely-rounded 4px corners, content-first hierarchy, book-like reading experience.

github

High-density information design. Cool-tinted dark canvas, muted blue links, GitHub green accents, developer-centric layouts.

marque