Raven MCP
Raven MCP is a comprehensive design intelligence server that empowers coding agents with design knowledge, auditing tools, and creative workflows. Key capabilities include:
Design Knowledge & Research – Access principles (Nielsen's heuristics, WCAG, typography, etc.), UI patterns, business strategies, content systems, research methods, and metrics frameworks (HEART, AARRR, etc.).
Audit & Quality Assurance – Run automated audits on HTML/CSS, live URLs, SwiftUI, React Native, iOS screens, contrast ratios, typography scales, tap targets, layout rhythm, responsive visibility, video playback, cross-page consistency, device frames, asset integrity, and privacy posture (Info.plist). Score pages across 7 dimensions and get per-category scores.
Design Tokens & Systems – Browse, retrieve, and compose design tokens from systems like Stripe, Linear, and Vercel; generate custom design systems from a brand color; manage local DESIGN.md files; get brand systems styled like Spotify, Apple, etc.
Grab & Click-to-Change – Start a local bridge that injects an overlay into a running app, allowing you to click elements and send selectors, computed styles, and design tokens to the agent for modification; manage template slots and layer moves.
Taste Engine – Create and bind taste profiles with per-project design rules, calibration interviews, decision tracking, and automated audits that enforce those rules; Talon Scan for deterministic detection; generate taste portraits.
Decision Graph – Record, trace, and manage design decisions with evidence, supersession lineage, and gap analysis; mine git history and transcripts for decisions; review diffs against DESIGN.md tokens.
Creative Studio – Plan campaigns, register assets, create generation jobs (image/video/3D/audio), score creative concepts, and build brand/character profiles.
iOS & React Native Audits – Audit SwiftUI native code, iOS screen snapshots, accessibility, spacing, platform conventions, cross-platform parity, and Expo/React Native source.
Content & Brand – Retrieve brand voice guides (Mailchimp, GOV.UK, Shopify Polaris, Atlassian), UX-writing patterns, content audits, brand principles, and visual-design trends.
Service Design – Access service blueprint patterns, generate HTML blueprints, and use the GOV.UK Service Standard as a quality checklist.
Before/After Diffs – Compare base64 screenshots to measure pixel-level changes.
Adversarial Verification – Re-check audit findings against the live DOM to distinguish real issues from artifacts.
Local-First & Privacy – All usage logs, taste profiles, and creative assets are stored locally; nothing is sent to remote servers unless opted into hosted endpoints.
Reflection & Learning – Summarize usage patterns and recurring audit warnings to identify knowledge gaps.
Utilities – Register for updates, configure design system sources, audit API contracts and wire contracts for consistency.
Provides voice and tone guidance based on Atlassian's publicly documented brand system.
Provides design system tokens from Linear's design system.
Provides voice and tone guidance based on Mailchimp's publicly documented brand system.
Provides voice and tone guidance based on Shopify Polaris design system.
Provides design system tokens (colors, spacing, typography) from Stripe's design system.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Raven MCP What design principles apply to a signup form?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Raven MCP
Odin's ravens brought back knowledge of the world — Raven brings back design intelligence.
Raven is an MCP server for coding agents. Click any element in the app you have running locally and say what should change — Raven sends the agent the selector, the computed styles, and your design tokens — then audits the result for contrast, tap targets, and typography.
Raven MCP is a personal open-source project by Andrew Cunliffe. It is not endorsed by, affiliated with, or supported by Intuit Inc. or any other company referenced in its source data. See NOTICE for full attribution of upstream sources and their licenses.
What it does
Raven gives Claude access to a comprehensive design knowledge base:
Principles — Nielsen's 10 Heuristics, all 21 Laws of UX, Gestalt principles, WCAG accessibility, typography rules, color theory, mobile UX, D4D framework, UX writing, service design, brand, color-systems (palette-size discipline), and spacing-systems (base-unit grid + scale limits)
Patterns — Proven UI patterns for signup flows, pricing pages, navigation, dropdown/select menus, forms, landing pages, dashboards, modals, empty/error/loading states, CTAs, social proof, mobile conversion — plus content patterns (error messages, empty-state copy, notifications, form validation) and service patterns (service blueprinting, human handoff, signup-as-service, omnichannel continuity, moments of truth)
Content systems — Voice & tone guides: Conversational Product Voice, GOV.UK, Shopify Polaris, and Atlassian
Research — Qualitative, quantitative, and usability methods with do/don't protocols and checklists. Metrics frameworks: HEART, AARRR/Pirate, North Star Metric, conversion funnel, RICE, OKRs.
Service design — Service blueprinting (with HTML blueprint generation — current vs. ideal state), human-handoff patterns, signup-as-service, omnichannel continuity, moments of truth / recovery, and the GOV.UK Service Standard
Brand & visual — Logo usage (clear space, min sizes, variants, placement, restraint), gradient usage (hierarchy, palette, contrast, trend vs signature), imagery (consistency, representation, purpose), visual hierarchy, brand-as-system, and current (2026) visual-design trends
Business — Monetization models, retention strategies, onboarding optimization, growth mechanics, and product metrics frameworks
Tokens — Design system tokens for Stripe, Linear, and more
Creative studio — Local-first brand profiles, asset references, character reference profiles, provider-agnostic image/video/3D/audio generation jobs, campaign plans, and transparent creative scoring. Raven does not ship media-provider credentials; set
RAVEN_CREATIVE_RUNNERto route jobs to your own renderer.
Related MCP server: claude-design-mcp
Install
Local stdio (npx / from source) is the full product: 115 tools, including Grab, the pattern library, and the file-backed Taste Engine. Hosted endpoints are smaller subsets — pick one path and stick to it.
Path | How | Tools | Taste | Grab |
Local stdio |
| 115 | Yes | Yes |
Public remote |
| ~45 | No | No |
Auth remote |
| Taste + audits (no Grab) | Yes | No |
Claude Code — one command
claude mcp add raven -- npx -y raven-mcpPrefer one Raven entry. If both a local raven and a claude.ai / remote Raven are connected, the agent sees two overlapping toolsets — disable or rename one (e.g. raven-local vs raven-cloud) so it is obvious which product you are talking to.
Manual config (Claude Desktop or team .mcp.json)
{
"mcpServers": {
"raven": {
"command": "npx",
"args": ["-y", "raven-mcp"]
}
}
}Cursor
Same mcp.json snippet as above (~/.cursor/mcp.json or project .cursor/mcp.json) runs the full local server (Grab + Taste). Hosted options:
Public:
"url": "https://mcp.ravenmcp.ai/api/mcp"— ~45 stateless tools; no Grab, no Taste.Authenticated Taste:
"url": "https://mcp.ravenmcp.ai/api/mcp-user"— OAuth; Taste yes, Grab still local-only.
Codex
Add under mcp_servers in config.toml:
[mcp_servers.raven]
command = "npx"
args = ["-y", "raven-mcp"]Codex may prompt to approve many Raven tools on first use — that is client approval policy, not a smaller Raven.
Claude Desktop — one-click extension
Prefer not to edit JSON? Download raven.mcpb and double-click it. Claude Desktop installs Raven automatically — no Node, no terminal. Package version tracks npm.
From source
git clone https://github.com/rhinocap/raven-mcp.git
cd raven-mcp && npm install && npm run buildTools
Tool | Description |
| Get design principles relevant to a UI context |
| Get proven patterns for a specific UI type |
| Get business/monetization strategies |
| Evaluate a design description against principles. Pass base64 PNG screenshots ( |
| Search across all principles, patterns, and strategies |
| Get a pre-publish checklist for a UI type |
| Get Design for Delight framework templates |
| Browse available design systems |
| Get tokens for a specific design system |
| Mix tokens from different systems |
| Get a full system styled like a well-known brand |
| Audit HTML/CSS against Raven's quality standards — pass |
| Return a per-category (0–10) design score for a page — typography, accessibility, spacing, color, responsive layout, design tokens, structure — derived from the same checks as |
| Evaluate visual rhythm, alignment, and optical balance; detects orphan-stretch (a lonely last-row grid/flex card stretching far wider than siblings) |
| Render a URL at multiple breakpoints and flag content elements that are visible on desktop but hidden on mobile (display:none/opacity:0/zero-size) — categorises each as likely-oversight (content vanishing on mobile) vs intentional (decorative) |
| Compute WCAG contrast for rendered text with tri-state |
| Given failing WCAG color pairs, return the minimal fg/bg change that clears the AA/AAA target — concrete passing values to fix |
| Render a live URL at each viewport×theme, scroll-settle, fire interactions, capture real pixels + DOM, then run the page/contrast/responsive/blank-media checks plus sliced-image edge-symmetry and hover-state white-wash detection over the captures — every finding tagged confirmed/likely-artifact/inconclusive, ranked by severity. Pass |
| Per-item content verdicts (pass/warn/fail) for headings, prose, CTAs, labels, captions, metrics & outcomes against UX-writing principles + deterministic heuristics (metric needs number+unit; CTA action-led ≤4 words; prose flags passive/jargon/hedging; caption-vs-heading duplication) — with a before→after rewrite suggestion per item. Pure offline |
| Typographic-scale report over rendered DOM text nodes (or a supplied snapshot) — detects the dominant modular-scale ratio and flags off-scale sizes, checks line-height consistency vs the body rhythm, and flags weight ladders >4 weights or non-standard values. Goes beyond |
| WCAG 2.5.5 / Apple 44pt web tap-target audit — enumerates every interactive element (rendered URL or snapshot) and emits a per-element fix table: selector, role, text, measured w/h, per-axis pixel deficit, and a concrete CSS fix, sorted worst-first |
| Flag cropped content in device-mockup frames — |
| Render a page and observe whether each |
| Corpus/multi-page audit — compares ≥2 pages and flags cross-page divergence in content-container width and hero heading tier, inferring the canonical (modal) value from the corpus when no token is supplied — catching relational defects that single-page audits miss |
| Audit SwiftUI source against Apple HIG — Dynamic Type, semantic colors, 44pt targets, 4/8pt spacing, AccentColor |
| Score a rendered iOS screen from an accessibility/view-hierarchy snapshot — 44pt targets + contrast + rhythm, in points |
| Audit Info.plist (or Expo app.json) /PRIVACY.md/entitlements/source — usage-string honesty, ATS, Android permissions, bundled secrets, undisclosed default data-egress |
| Audit React Native / Expo source — touchable a11y labels, 44/48pt+hitSlop targets, font scaling, SafeAreaView, dark mode, against iOS HIG + Android Material |
| Generate a custom design system from a brand color |
| Browse brand voice & tone systems (Conversational Product Voice, GOV.UK, Shopify Polaris, Atlassian) |
| Get a brand's voice attributes, tone shifts, vocabulary, grammar, and content patterns |
| Get UX-writing principles — clarity, active voice, error anatomy, inclusive language |
| Get copy recipes for error messages, empty-state copy, notifications, form validation |
| Get qualitative, quantitative, or usability research methods with protocols and checklists |
| Get a product-metrics framework — HEART, AARRR, North Star, conversion funnel, RICE, OKRs |
| Get a service design pattern — blueprinting, human handoff, signup-as-service, omnichannel, moments of truth |
| Get the GOV.UK Service Standard — 14 points for evaluating service quality |
| Render a service blueprint as HTML — current state, or current vs. ideal side-by-side |
| Get brand/visual principles — logo, gradient, imagery, hierarchy, brand-as-system |
| Get current (2026) brand and visual-design trends with usage guidance |
| Browse provider-agnostic creative model slots for image, video, 3D, audio, character consistency, and analysis |
| Browse creative presets: product photoshoot, marketplace cards, UGC ads, TV spots, social packs, storyboards, infographics |
| Create or update a local brand profile for brand-aware creative jobs |
| Read a local creative brand profile |
| List local creative brand profiles |
| Register a local path or URL as a creative asset reference — no file bytes are uploaded by Raven |
| Create a local character/identity reference profile from registered assets |
| Create a provider-agnostic image, video, audio, 3D, campaign, or analysis job payload; optionally execute via |
| Read a creative generation job and its provider payload/output state |
| List local creative generation jobs |
| Plan a multi-asset campaign and optionally create draft generation jobs |
| Score a prompt/script/concept for hook, benefit clarity, product signal, CTA, channel fit, audience fit, and brand fit |
| Create a named taste profile — a portable design-judgment ruleset (rule_id, clause, category, severity, negative prompt, owner) + precedent corpus, from explicit rules and/or a DESIGN.md-style markdown doc — persisted locally under |
| Load a stored taste profile's full rule catalog, precedent corpus, and surface bindings |
| List locally stored taste profiles with rule/corpus counts |
| Append a human accept/revise/reject precedent to a profile's corpus — the growth loop; append-only, and accept-verdicts suppress that pattern in future audits |
| Calibration interview, two modes. |
| Persist a project's surface calibration — surface string, URL hosts, per-rule severity overrides (incl. |
| The learning loop — record a taste/direction/design decision the moment it's made during real work (what was chosen, what was rejected, why, and whether the user directed, approved, or corrected it). Recorded decisions evolve future kickoff interviews: recurring choices return as suggested defaults on their dimension's question, and decision categories no standard question covers become new interview questions |
| The decision ledger, filterable by project or dimension |
| Judge HTML, copy text, or a live URL against a taste profile — deterministic detectors for gradients, glow/neon, second accent hue, and banned words; pass |
| Render a bound taste surface as a self-contained designed HTML page (its rules, notes, voice, decisions, and wrong→right corpus) that obeys the surface it describes — art direction routes by the surface's own color permissions; sparse surfaces degrade gracefully. Omit |
| Find the places on a page where motion would help (hero, buttons, cards, sections, navigation, images) and build a motion playground for each from the page's own content, ranked by the project's motion note, each with a short reason that quotes the notes it relies on. Writes a map of the page with a numbered marker per suggestion. Tuned values and turn-downs recorded with |
| Summarize your local Raven usage log to find patterns + gaps |
Decision Graph
The local Decision Graph keeps three node kinds: decisions, evidence, and sources. Five edge types connect them: supersedes, scoped_alongside, supports, contradicts, and derived_from. Decision status is candidate, active, superseded, or contested; nodes are not hard-deleted.
decision_add— add an active decision with its scope, component, rationale, and rejected alternatives.decision_evidence— attach quantitative or qualitative evidence to a decision.decision_get— return one node, its connected neighbors, and attached evidence.decision_list— list active, superseded, contested, or candidate decisions. Candidates are excluded unlessinclude_candidates:trueorstatus:"candidate"is passed.decision_draft— capture a decision before its rationale is confirmed.decision_commit— confirm a rationale and surface similar active decisions for review.decision_supersede— replace a decision while keeping both nodes and their lineage.decision_scope— narrow two active decisions so they can coexist.decision_history— return a supersession lineage from oldest to newest.ingest_transcript— store a Source node and return the extraction prompt for the calling model.decision_import— read local git history and matching decision documents, then return source-bound extraction prompts.ingest_transcript_results— turn extracted JSON into candidate decisions linked withderived_fromedges.gap_scan— rank uncovered components, missing or thin rationales, contested decisions, and derived staleness;digest_only:trueis quiet when no action is needed.
For a cold start: call decision_import → run the returned extraction prompts with a model → pass each result to ingest_transcript_results → review the candidates → call decision_commit for each decision to keep. Candidates remain available through decision_get, but default decision_list and gap_scan ignore them until commit changes their status to active.
Figma comment archives (Markdown files under figma-comments-archive/ whose first line is # Figma comments archive: <label>, with ## Thread <n> headings) are picked up by default. Their settled threads use thread-aware extraction with path#Thread <n> provenance; imported candidates still require decision_commit and are never auto-committed.
Imported provenance is checked against its Source node before evidence is attached. Git references must be a full or unique-prefix match for a commit included by that import. Document references must match the imported path, optionally followed by a line (#L12) or heading fragment. Rejected references are returned in rejected_source_refs; the candidate remains available without an evidence node.
For transcripts: call ingest_transcript → run its extraction prompt → pass the result to ingest_transcript_results → review and commit the candidates. Resolve active conflicts with decision_supersede or decision_scope, inspect lineage with decision_history, and use gap_scan for health checks.
Evidence nodes and supports / contradicts edges capture quantitative and qualitative results linked to decisions.
review_diff severity policy
review_diff is advisory by default (verdict caps at warn). Two independent, combinable opt-ins escalate matching violations to error, producing a failing CI verdict:
fail_on— a rule allowlist. Valid rules:important,bare-hex-color,hardcoded-font-size,hardcoded-font-family,hardcoded-spacing. Start withimportant; add token rules once DESIGN.md tokens are mature.importantfindings can include intentional uses (email-client compatibility, responsive overrides), so expect to justify or restructure those hunks; token rules only fire when DESIGN.md defines tokens (checks_skippedtells you when they didn't run).fail_on_governed— escalates findings a recorded decision governs (lexical scope+category association, not a verified contradiction). Opt in as a team strict-mode signal.
Escalation is diff-scoped: only newly added lines can fail — existing violations don't block until a diff touches them. The applied policy is echoed back under severity_policy. Omitting both keeps the existing advisory behavior unchanged. review_diff is local-stdio only (not on the hosted remote endpoints), so wire the policy into CI via npx raven-mcp.
Archive Figma comments
Archive your Figma comment history to durable JSON/Markdown before you lose access:
FIGMA_TOKEN=<pat> node scripts/figma-comments-archive.mjs --md <fileKey>
The PAT needs file_comments:read. Add --resolve-nodes for best-effort node names; it also needs file_content:read, and archival still succeeds if resolution is unavailable.
Without credentials: in Figma, first show resolved comments and clear any comment filters (hidden threads won't be in what you copy — and they're unrecoverable after cancellation). Figma has no bulk "copy all comments", so select and copy the thread text from the comments panel, then run (macOS):
pbpaste | node scripts/figma-comments-archive.mjs --paste design-review
(the last word is your archive label — any name without spaces; add --out somedir to choose the folder). Or run the command bare and paste into the terminal, ending with Ctrl-D.
Separate threads with a blank line; within a thread, an author line followed by a timestamp line ("2 days ago", "Yesterday", "Mar 4, 2026") starts each comment.
Paste mode writes <label>.txt (your paste, byte-verbatim — the durable record) and always renders the readable <label>.md archive. Skim the .md against your paste: message lines that themselves look like a timestamp, or blank lines inside one comment, can shift how the .md groups things — the .txt is always exact. An existing label is never overwritten; pass --force to replace it.
Click-to-change (grab) + DESIGN.md
Grab is local-stdio only. Hosted Cursor/Claude remote endpoints do not expose Grab — click-to-change needs a loopback bridge on your machine. Use local npx / Cursor local mcp.json when you need Grab.
Raven Grab connects a local page to your agent so you can click an element, describe the change, and send its selector, computed styles, matching DESIGN.md tokens, and token choices back to the session. The bridge runs on loopback and the returned script tag carries the capability key required by its routes.
Computed styles are editable inline, and edits are sent to the agent as styleEdits.
Setup takes under a minute:
Start your local dev server.
Call
start_grab_sessionwithproxy_targetset to the local server URL.pathto aDESIGN.mdis optional whenproxy_targetis set (Raven creates a minimal temp DESIGN.md); required when you only inject the script without a proxy.Open the returned bridge URL. The overlay is already included on HTML pages served through it.
Click elements and enter the changes you want in the Grab panel.
Call
get_grabbed_elementsto receive the queued selections and instructions (draining frees queue capacity for later sends).
For a page you control, you can omit proxy_target and paste the returned <script> tag into the page instead.
Use read_design_md to inspect a DESIGN.md file and its flattened token index, init_design_md to create one from a stored Raven system, a blank template, or a getdesign.md starter, and update_design_md to set, rename, or remove one token without rewriting the rest of the file.
Pattern library — keep what you grab, then translate it
proxy_target also accepts a third-party URL, so you can grab from any site you are allowed to
view, not just your own dev server. What you grab is otherwise gone when the tab closes, and it
arrives as another site's literal values. Four tools close that loop:
capture_reference— persist a grabbed selection under~/.raven/references: selector, computed styles, hover/focus states, bounding rect, truncated HTML, your own note, and tags. One JSON record per capture, so grabbing the same element twice keeps both. It also renders the captured element back into a PNG beside the record, because nobody can pick a pattern out of a style map. That render is offline — every external request is aborted, so a stored reference never reaches back out to the site it came from — and it runs with scripting disabled, so a script in a captured element cannot execute. The record says so:fidelity: "offline".search_references— find it again later by free text, host, owner, or tags, with a per-result score and awhynaming the fields that matched. Each result carries adisplayobject holding the credit line and the image path together, so a consumer reaching for the picture carries the attribution out with it. Looking is not copying: a result reportshtml_availablebut omits the captured markup, because browsing a corpus of other people's work should not hand back their markup as a side effect of looking at it. Passinclude_html: truewhen you actually mean to read the structure — the response then names whose markup it contains. Everything a browse is for is in the default result: the picture, the selector, the rect and the computed styles.map_reference_to_tokens— translate the captured literals onto your DESIGN.md tokens, so the code an agent writes uses your type ramp and palette instead of pasted values. Every binding carries the resolved value and CSS variable alongside the token name — a name alone is not something you can write into a stylesheet — and an aliased token resolves to the literal at the end of its$refchain. Pure and deterministic: no model, no network. It reads the stored styles directly, so the whole show-it-then-translate-it path runs without the markup ever leaving Raven.forget_references— remove a single reference byref_id, or every reference from a host (subdomains included). Takes the PNGs with it. Destructive and permanent, so the host sweep refuses to run withoutconfirm: trueand tells you how many records that would remove first.
How the mapping decides, because a wrong binding is worse than a stated gap:
Colour matches on RGBA distance, not RGB — the same hex at a different opacity is a near miss, not an exact hit. Hex,
rgb()/rgba()in both comma and space form,hsl(), and the CSS named colours all resolve; a syntax the matcher cannot read (oklch(),lab()) says so by name instead of reporting your palette as empty.Lengths normalize to px at a 16px root. Percentages and viewport units need a containing size and are returned as gaps with that reason, never converted on a guess.
Family before proximity. A property that belongs to a token family binds inside it:
padding-toptakes a spacing token even when a type token is numerically closer, andline-heighttakes the leading token over an equally-exact size token. When no token in the right family is close enough, the result is a gap that names the cross-family near miss ("the closest token by value isspace.4(16px), but it belongs to a different family") rather than bindingfont-sizeto your spacing ramp.Ties break on distance, then family fit, then shortest and lexicographically-first token path, so the same inputs always produce the same binding regardless of token order.
Broken
$refchains and cycles in your DESIGN.md come back indiagnosticseven when every property still found a match — a defect in your own token file is reported, not swallowed.
Respect the source. Grab from sites you are permitted to access; the tools never bypass a paywall
or a login, and owner: "third-party" is recorded on every capture.
Attribution and takedown. Every third-party record keeps the URL, host, app name and capture
date it came from, and search_references derives a credit line from them on read — so the credit
cannot go stale, and it travels with the picture rather than beside it. Raven claims no ownership
of anything you capture.
Your corpus is local: it lives in ~/.raven/references on your own machine, and this project
hosts no copy of it. So a takedown is something you run, not something you request — if a rights
holder asks you to remove their material, forget_references with their host removes every record
from that host and every subdomain, and the images with it:
forget_references({ host: "example.com", confirm: true })It reports what it removed, what it could not read, and anything it tried to remove and failed —
those are three different answers and it does not collapse them into one. A removal that fails
part-way leaves the record in place rather than the picture, so running it again finds and finishes
what was left. The confirmation prompt names the exact records it would take, and passing those ids
back as expected_ref_ids pins the removal to them — anything captured in between is reported
rather than swept up. If you believe this project itself is distributing your material, open an
issue at https://github.com/rhinocap/raven-mcp/issues.
One boundary worth stating plainly: while the bridge is proxying a third-party site, that page is served from the bridge's own origin, so scripts on it are same-origin with the Raven overlay and can read your DESIGN.md token names and values. Raven withholds the DESIGN.md file path and every authoring route (layer moves, template and component writes, batch commits) for the duration of a proxy session, but proxy sites you would be comfortable showing your token list to.
Creative studio
Raven now covers the creative-production workflow around media generation without copying or depending on any closed vendor. The tools are orchestration primitives:
Store brand kits locally with
create_brand_profile.Register product photos, logos, references, or URLs with
register_creative_asset.Create character/identity reference sets with
create_character_profile.Generate provider-ready payloads with
create_generation_job.Build full campaign shot lists with
plan_creative_campaign.Score creative concepts with
score_creative.
By default, jobs are saved as local draft payloads under ~/.raven/creative (override with RAVEN_CREATIVE_HOME). To run real media generation, set RAVEN_CREATIVE_RUNNER to an executable that reads one job JSON object from stdin and returns JSON on stdout. That runner can call any provider you choose; Raven never stores API keys in source.
iOS / SwiftUI audits
Raven audits native iOS apps against the Apple Human Interface Guidelines, not web/CSS conventions. None of the web-only rules (lang, title, flex-wrap, clamp, max-width, CSS custom properties, bare hex) run on iOS input — and get_checklist/get_principles take platform: "ios" to return HIG items (Dynamic Type, 44pt targets, SF Symbols, safe areas, dark-mode parity, App Review privacy) instead of the web set.
audit_swiftui— paste SwiftUI source (source: a string or array of files). Statically flags hardcoded.font(.system(size:))below ~13pt, tiny semantic fonts (.caption/.caption2), hardcodedColor(red:green:blue:)/hex literals (vs. asset-catalog or semantic system colors), interactive frames under 44×44pt, and ad-hoc spacing off the 4/8-pt grid. Rewards semantic Dynamic Type fonts, semantic system colors, SF Symbols, and flexible frames. Pass the optionalaccent_color_contents(the rawAccentColor.colorset/Contents.json) and it verifies the accent color actually defines components — catching an empty/undefined AccentColor that would silently fall back to system blue.audit_ios_screen— the iOS analog ofaudit_layout. Call with no args for the expected snapshot shape and how to capture it (Accessibility Inspector / XCUITest). Call with{ elements: [{ label, rect, role, fontPt, fgColor, bgColor }], viewport }(plus an optional base64screenshot) to score 44×44pt touch targets, contrast (with iOSsecondaryLabel/tertiaryLabeltreated as platform-standard — a warning, not a hard fail), and visual rhythm (alignment, gap consistency, optical balance).audit_ios_privacy— the "no sketchy issues" gate. Readsinfo_plistor an Expoapp_json(managed RN apps have no Info.plist) plus optionalprivacy_md,entitlements, andsource. FlagsNS*UsageDescriptionstrings that are vague or contradict the code (e.g. anNSHealthUpdateUsageDescriptionwrite claim thatrequestAuthorization(toShare: [])never fulfills), unused entitlements, Android permissions (Expo), ATS cleartext exceptions, secrets/keys shipped in the bundle orapp.jsonextra, and default data-egress paths not disclosed at the point of choice (a pre-selected "Recommended" option that silently sends personal data to a hosted server).
All three return the same shape as audit_page — score, grade, summary, passes, errors, warnings, fix_priority (with audit_ios_screen adding a metrics block).
One command: node scripts/ios-audit.mjs <app-dir> [--snapshot snap.json] [--md report.md] discovers all the inputs and runs all three tools with an aggregated report.
React Native / Expo audits
Anyone building a React Native or Expo app gets the same treatment. RN renders to native iOS + Android widgets, so audit_ios_screen already scores its rendered output (an accessibility snapshot is platform-level); audit_rn covers the JSX/StyleSheet source — the RN analog of audit_swiftui — graded against the iOS HIG + Android Material conventions RN has to satisfy on both platforms. get_checklist/get_principles take platform: "react-native".
audit_rn— paste RN source (source: a string or array). Flags touchables (Pressable/Touchable*) missingaccessibilityLabel/accessibilityRole, touchables under 44pt with nohitSlop,allowFontScaling={false}(silently breaks Dynamic Type),fontSizebelow ~13, screens with noSafeAreaView/useSafeAreaInsets, and — for multi-mode apps — hardcoded colors with nouseColorScheme/Appearance. Passcolor_scheme: "dark"/"light"(your ExpouserInterfaceStyle) and the dark-mode check is suppressed for intentionally single-mode apps. RewardsSafeAreaView,hitSlop,Platform-aware code, and a theme.audit_ios_privacyalso accepts an Expoapp_json— it auditsexpo.ios.infoPlist, Android permissions, plugins, and scansexpo.extra/config for secrets and Google API keys.
One command: node scripts/rn-audit.mjs <app-dir> [--snapshot snap.json] [--md report.md] discovers screens + app.json (reading userInterfaceStyle so dark-only apps aren't false-flagged) and runs everything.
Responsive visibility audits
audit_responsive_visibility renders a page at multiple breakpoints (default: 390px mobile, 768px tablet, 1440px desktop, 2160px ultra-wide) and flags content elements that are visible on desktop but hidden on mobile — catching the "vanishes on mobile" bug class. Each flagged element is categorised as likely-oversight (content that shouldn't be hidden) or intentional (decorative elements). Detects hiding via CSS (hidden, display:none, opacity:0, visibility:hidden) and responsive Tailwind classes (hidden md:block, etc.).
Usage:
audit_responsive_visibility(url)— render at default breakpoints and flag mismatches.audit_responsive_visibility(url, [390, 768, 1440])— custom breakpoints.Optional
viewportHeight(default: 900px) for tall content.
Returns flagged elements with selector, hiding class, visibility at each breakpoint, and category.
Contrast audits
audit_contrast computes WCAG contrast for every text element, reporting a tri-state status: pass, fail, or indeterminate. Determinate rows include ratio, aa, aaa, and delta_to_aa; indeterminate rows keep required_aa but publish those four metrics as null. Gradient and layered backgrounds expose effective_bg plus ratio_min / ratio_max when a trustworthy candidate range exists, and results summarize indeterminate_bg_rows / indeterminate_bg_count separately from AA failures.
Real-backdrop compositing applies to URL mode. Raven walks the rendered DOM ancestor chain, composites parseable colors and gradient layers in CSS paint order, samples gradient interiors, and normalizes modern computed colors through the browser canvas. This intentionally stops at the DOM-ancestor ceiling: opacity, display:contents, positioned transparent chains, photos, unsupported layers, and cross-stacking-context sibling backdrops are reported indeterminate; Raven does not pixel-sample across stacking contexts. Snapshot mode retains the pre-existing supplied-bgColor / over-white model and announces that scope in mode_note.
Usage:
audit_contrast(url)— render a live page and audit all text.audit_contrast(dom_snapshot: [{ selector, color, bgColor, fontPx?, bold?, text? }])— audit a pre-captured snapshot (useful for dynamic or cookie-protected pages).
Returns all text rows with status, determinate failures with delta-to-pass, effective background evidence/ranges, and separate indeterminate summaries. suggest_contrast_fix accepts only determinate failing rows; indeterminate or null-ratio evidence is skipped rather than converted into a fake color recommendation.
WCAG math: Contrast ratio uses linearised luminance (WCAG 2.1 § 1.4.3) — black-on-white is exactly 21, white-on-black is exactly 21. Large text (18.66pt+ bold or 24pt+) needs only 3:1 / 4.5:1 AAA; regular text needs 4.5:1 / 7:1.
Headless browser audits
audit_page can render a live URL in headless Chromium, scroll to settle reveal-on-scroll elements, and play preload=none videos before capturing — preventing false "blank section" reports caused by whileInView states that haven't fired yet.
Usage:
Static HTML mode — pass
htmlstring for immediate static analysis (existing behavior, no change).Rendered URL mode — pass
url(full HTTP/HTTPS URL). Raven launches Chromium, renders the page, optionally scrolls, and audits the live DOM.scroll_settle: true— scroll from top to bottom in viewport-height steps with a short pause at each step soIntersectionObserver/ whileInView thresholds can fire, recomputing page height as lazy content appears and requiring consecutive stable-height observations at the bottom. Raven then waits for finite animations triggered anywhere in the walked page before returning to the top and re-settling for capture. Smooth scrolling is temporarily neutralized. The whole walk/settle is capped at 4s; if a very long, continuously growing, or still-animating page cannot fully settle, Raven emits a capture warning rather than silently trusting the result, andanimationsSettledremains false. Unloaded videos (preload="none") are played to detect if they render blank.Entrance-animation settle (always on) — before extracting content or screenshotting, Raven polls
document.getAnimations()until no finite animation in or near the viewport is still running (infinite spinners/loops are ignored), capped at 3s by default. Library callers can setanimation_settle_timeout_ms(hard maximum 10s). Pages whose heroes enter viaanimation-delay+backwardsfill are captured settled, not blank or mid-flight;animationsSettledin the capture metadata reports whether quiescence was reached.False-blank detection (always on) — at capture time Raven measures text-bearing leaf nodes and media/content elements across the captured page. If more than 30% are effectively invisible through
opacity:0,visibility:hidden, or a fully transparent text color,capture_warningsincludesreveal-gate-false-blank: …so capture-backed audit callers know the rendered audit may be untrustworthy.viewport: { w, h }— set the render viewport (default:{ w: 1440, h: 900 }).
Video artifacts detection: If any <video> with preload="none" (or missing preload) renders with readyState < 2 (i.e. would show a black box in a screenshot), Raven flags it as an unloaded-video-artifact in the result. This is informational — not a pass/fail — since preload=none is often intentional. On cookie-protected hosts, video requests may fail because iOS/Android media daemons don't send cookies; Raven notes this to help you troubleshoot (e.g. disable deployment protection, use a token-based bypass).
Adversarial verification: Set adversarial_verify: true to independently re-check each finding against the live DOM using a different method. Findings are tagged:
confirmed— the finding is real on the live page (e.g. missing<title>in the rendered DOM)likely-artifact— the finding is an artifact of the static audit method (e.g. a<video preload="none">rendered blank, which is expected behavior, not a missing resource)inconclusive— the finding cannot be independently verified (e.g. aggregate rules like color-palette size)
The result includes adversarial_verification: { debunked_count, confirmed_count, inconclusive_count }, where debunked_count is the number of likely-artifacts. This surfaces false positives so you only fix real issues. Backwards-compatible: when adversarial_verify is absent or false, the output is identical to prior versions.
Setup: First time only, run npx playwright install chromium to download the browser binary. If the binary is missing when you call audit_page with url, you'll see a clear instruction to run the install command.
Before/after design diffs
evaluate_design can now accept base64-encoded PNG screenshots to measure whether a fix actually changed the rendered output.
Usage:
Pass
before_screenshotandafter_screenshot(both base64 PNGs, with or without thedata:image/png;base64,prefix).Raven returns
fix_confirmed: trueif the images differ by > 0.1% of pixels (accounting for jpeg/PNG decode variance).changed_ratio— exact fraction of pixels that changed (0–1).changed_region— bounding box{ x, y, w, h }of the changed pixels (null if no changes detected).dimensions— image-derived measurements (canvas size, brightness, color shift) as context, with the caveat that these are pixel-level proxies, not Raven principle scores.
When before/after screenshots are provided alongside a description, evaluate_design returns both the principle-based evaluation and the pixel diff. When screenshots are provided without a description, the evaluation gracefully skips the principle search and returns the diff only. Backwards-compatible: without screenshots, the tool behaves identically to prior versions.
Close the token-polish loop against a real git worktree:
npx raven-polish --apply --verify "npm test"The CLI is dry-run by default (or node scripts/raven-polish.mjs in this repo); it exits 1 when polish is proposed or any finding has severity error, and exits 0 only when there is nothing to polish and no errors. Pass --range main...HEAD to review committed work. It checks a proposed patch before applying it, then runs review_diff again on the real repository state. For CI, copy the example workflow into .github/workflows/.
Release updates
Raven ships new principles, patterns, and brand systems regularly. For one email per minor/major release (patches stay quiet):
Web: ravenmcp.ai/#updates — 10 seconds, one email field.
In-product: ask Claude "register me for Raven updates at you@work.com" — Claude calls
raven_registerand you're in.
No marketing, unsubscribe anytime. Powered by Resend.
After you upgrade
Claude Code snapshots the tool list when the MCP server connects. After upgrading, restart the session or use /mcp to reconnect and see new tools.
Claude Desktop snapshots the tool list when the MCP server connects. After upgrading, restart the app to see new tools.
Codex CLI also requires a per-tool approval_mode entry in ~/.codex/config.toml; without it, calls to new tools are cancelled. Run node scripts/sync-codex-approvals.mjs to see what is missing, then add --write to append the entries.
The appended entries auto-approve those tools, so review the printed list; newer Codex versions can alternatively set a server-level default_tools_approval_mode.
Start every project calibrated
Taste is per-surface: the same designer wants monochrome one-accent rules enforced on their portfolio and none of them on a product site, with a slightly different voice on each. The Taste Engine handles this with a kickoff interview (once per project — every question skippable, most with plain-language multiple-choice options, from navigation pattern to aesthetic family to specialty libraries) whose answers persist as a surface binding that every future audit applies automatically. And when generated work misses, mode:'refine' turns that dissatisfaction into a re-interview against the stored binding instead of a dead end.
Starting a brand from nothing — no product, no palette, just an idea? The same interview is step one of a full genesis flow (invent the brand in conversation, generate assets with your own image tools, approve a mood board, land a design system in DESIGN.md): docs/brand-genesis-flow.md.
Raven ships this flow in its MCP server instructions, so agents that honor server instructions (Claude Code, Claude Desktop) run the interview at project kickoff on their own: get_taste_interview → ask the user → bind_taste_surface → done. If your client doesn't surface server instructions — or you want the ritual to be non-negotiable — add one line to the project's CLAUDE.md / AGENTS.md:
Before the first design/UI/copy work in this repo, run Raven's get_taste_interview
(profile <name>, project <repo-name>); if existing_binding is null, ask me its
questions and persist with bind_taste_surface. Pass project:'<repo-name>' on every
audit_taste after that.Already-calibrated projects cost one cheap call (existing_binding comes back non-null and the agent proceeds). Uncalibrated audits still work — scoped rules just demote to warn and the result carries a calibration_hint — so calibration is never a wall, only a sharpener.
Learning loop
Raven keeps a small local-only log of how you use it so you (and Claude) can spot which patterns you build most often and which gaps show up again and again.
Location:
~/.raven/usage.jsonl(override withRAVEN_USAGE_LOG=/path).What's written: tool name, timestamp, elapsed ms, and a tiny insight object — audit score/warning rule names, pattern
type, brand company name, search layer. Never the HTML you audit, never prompt text, never brand copy.What's never written: raw page bodies, client content, your work product.
Disable entirely:
RAVEN_NO_USAGE_LOG=1.Reflect: ask Claude "what have I been using Raven for?" and it will call
raven_reflect, which reads the log locally and summarizes the last N days — most-used tools, recurring audit warnings (likely knowledge gaps), patterns you request most, design systems you reach for.
Nothing is sent to a remote server. If a recurring gap is worth turning into a new Raven principle or pattern, you file an issue by hand — the automated pipeline at github.com/rhinocap/raven-mcp handles it from there.
Your data on the hosted server
Raven also runs a hosted remote MCP server with two endpoints. The anonymous endpoint is stateless — no store is ever attached to it, so nothing you send is written anywhere. The authenticated endpoint (used for the Taste Engine's cross-session profiles, surface bindings, and decisions) keys everything to your account and stores it in Upstash Redis, namespaced under your verified user id; your bearer token itself is never persisted.
You can erase all of it at any time with the delete_taste_data tool (confirm: "DELETE") — it removes every key under your namespace and confirms nothing remains. Full details, including the exact key layout and the rate-limit counters that aren't part of your data, are in docs/remote-mcp-privacy.md.
Development
npm run dev # Run with tsx (hot reload)
npm run build # Compile TypeScript
npm start # Run compiled outputLicense & attribution
Raven MCP is released under the Apache License, Version 2.0 — Copyright (c) 2026 Andrew Cunliffe.
If you fork, embed, or redistribute Raven (in whole or in part), retain the Apache-2.0 license notice, the LICENSE file, and the NOTICE file. If you ship Raven inside another product, include attribution to "Raven MCP — https://ravenmcp.ai" in your acknowledgements.
Raven's knowledge base references work from many third-party sources — Nielsen Norman Group, primary academic literature for the UX/psychology laws (Fitts, Hick, Miller, and others), Gestalt principles, WCAG (W3C), plainlanguage.gov (public domain), GOV.UK (Open Government Licence v3.0), Shopify Polaris, Atlassian Design, and others. Each entry carries a sources URL field. See NOTICE for the full list of upstream sources and license terms; some carry their own conditions beyond Apache-2.0.
This is a personal project. It is not endorsed by Intuit Inc. or any other company referenced in its source data.
Data structure
All knowledge lives in src/data/ as static JSON files:
src/data/
principles/ # Nielsen, Laws of UX, Gestalt, accessibility, typography, color, mobile, D4D
patterns/ # signup, pricing, nav, forms, landing, dashboard, modals, empty/error/loading, CTA, social proof, mobile
business/ # monetization, retention, onboarding, growth, metrics
tokens/ # registry.json + systems/ (stripe, linear, vercel, …)
content/ # voice & tone: Conversational Product Voice, GOV.UK, Shopify Polaris, Atlassian
systems/ # registry.json + brand-voice JSONs (conversational-product-voice, gov-uk, polaris, atlassian)
principles/ # UX-writing principles (clarity, active voice, error anatomy, …)
patterns/ # copy recipes for errors, empty states, notifications, form validation
research/ # study protocols + metrics frameworks
principles/ # research fundamentals (method match, bias, sample size, ethics, triangulation, …)
methods/ # qualitative, quantitative, usability
frameworks/ # HEART, AARRR, North Star, conversion funnel, RICE, OKRs
service-design/ # service-level principles + patterns + frameworks
principles/ # Stickdorn, Shostack, peak-end, moments of truth, handoff
patterns/ # service blueprinting, human handoff, signup-as-service, omnichannel, moments of truth
frameworks/ # GOV.UK Service Standard (14 points)
brand/ # brand & visual design
principles/ # logo, gradient, imagery, hierarchy, brand-as-system
trends/ # 2026-current.jsonAvailable Tools
115 toolsauditARead-onlyIdempotentInspect
Run all applicable Raven audits for a target. Detects the surface (web page / iOS screen / React Native / code diff / video) and fans out to the right checks — contrast, tap targets, typography, layout, responsive, and taste for web; the iOS or RN set for native; parity/contract for diffs. Use this instead of choosing individual audit_ tools.* Pass project to judge against bound taste.
Inputs: url, diff, html, nodes, +6 more.
audit_api_contractARead-onlyIdempotentInspect
Run adversarial queries against a live endpoint and return per-query verdict (shape-valid / shape-invalid / confident-wrong / uncertain) vs an expected shape schema + per-query expectations. Catches responses that are shape-valid but wrong.
Inputs: queries (required), endpoint_url (required), expected_shape_schema (required).
audit_asset_integrityARead-onlyIdempotentInspect
Detect PNG exports whose content is sliced/cut off at the bottom edge (e.g. a Figma export that ended mid-form). Dimension/ratio checks cannot catch cut content inside a correctly-sized file; this measures per-pixel luminance variance in the bottom strip — uniform background = clean, high-variance UI content running into the edge = likely-sliced. Accepts filesystem paths to PNGs.
Inputs: image_paths (required).
audit_consistencyARead-onlyIdempotentInspect
Audit multiple pages for cross-page consistency of content-container width and hero heading tier. Pass ≥2 pages ({name, html}) collected from different routes on the same site. Infers the canonical (modal) value from the corpus when no token is supplied, so you need not know the project's design token in advance. Flags the issue #9 single-blob blind spot: pages that each pass audit_page but silently disagree with each other on container width or hero size class. Returns per-page extraction (container_px, container_classes, hero_classes, signatures), consistency dimensions with reference values, outlier page names, issues[], score (100/50/0 → A/C/D), and a plain-text summary. Pure offline — no browser, no network.
Inputs: pages (required), hero_token, container_token.
audit_contentARead-onlyIdempotentInspect
Evaluate an array of content items (headings, prose, CTAs, labels, captions, metrics, outcomes) against UX-writing principles and deterministic heuristics. Returns a per-item verdict (pass/warn/fail) with matched principle ids, concrete issues grounded in principle text, a before→after rewrite suggestion, and an aggregate summary. Heuristics: metric items must carry a number+unit; cta/label must be action-led and ≤4 words; prose flags passive voice, jargon, and hedging; headings flag filler openers and buzzwords; captions flag duplication of any heading in the batch. Pure offline — no network or browser. Use this instead of evaluate_design when you need per-item content verdicts rather than the principle library.
Inputs: items (required), goals, system.
audit_contractARead-onlyIdempotentInspect
Verify a wire contract (token list / field set / schemaVersion) is identical across N independent source files (iOS Swift, proxy JS, Android Kotlin). Flags missing/inconsistent tokens, schemaVersion drift, and prefix-ordering bugs (a contained token matched before the longer one). BLOCK/PASS verdict.
Inputs: file_paths (required), contract_spec (required).
audit_contrastARead-onlyIdempotentInspect
Compute WCAG contrast ratios for every text element on a rendered page (pass url) or from a supplied dom_snapshot. Reports AA (4.5:1 normal, 3:1 large) and AAA pass/fail and surfaces failing pairs with selector, ratio, and delta-to-pass — replacing manual eyedropper + ratio math. dom_snapshot mode returns a row per supplied element; url mode returns counts plus every row that needs action (aa_failures, indeterminate_bg_rows) and OMITS the per-element rows for passing elements, because a real page produces hundreds of thousands of characters of them.
Inputs: url, screenshot, dom_snapshot.
audit_device_frameARead-onlyIdempotentInspect
Detect cropped content in device-mockup frames (phone/MacBook screenshots, app-preview clips). Three checks: (1) GEOMETRY — call with frames (container box + intrinsic media size + object-fit/position; call with NO args for a DevTools snippet) to flag object-fit:cover crop loss when the frame's aspect ratio ≠ the media's; (2) MOTION — pass clips (first/last frame PNG paths) to detect baked-in pan/zoom (Ken Burns) that drifts the composition; (3) EDGE — pass edge_frames (PNG paths) to flag content truncated at a frame edge. Catches the exact failure where a 16:9 clip in a 1.82-AR screen cutout silently slices the bottom, or a Ken-Burns-zoomed source crops content.
Inputs: clips, frames, edge_frames.
audit_ios_a11yARead-onlyIdempotentInspect
Score an accessibility-enriched iOS element snapshot — missing accessibilityLabel/value/traits, sub-44pt tap targets, per-text WCAG contrast, Dynamic Type clipping, and VoiceOver reading order. Provide {elements:[{label,value,hint,traits,role,rect,fontPt,fgColor,bgColor,dynamicTypeClipped}],viewport}. Capture via the AccessibilitySnapshot XCUITest / ios-capture harness.
Inputs: elements (required), viewport (required), options.
audit_ios_privacyARead-onlyIdempotentInspect
Audit an iOS or React Native/Expo app's privacy posture for App Review and user trust. Reads a native Info.plist XML OR an Expo app.json (managed Expo apps have no Info.plist) — plus optional PRIVACY.md, entitlements, and source. Flags: NS*UsageDescription strings that are vague/missing or contradict the code (e.g. a HealthKit write claim the code never fulfills), entitlements/permissions and Android permissions the app doesn't use, ATS cleartext exceptions and non-HTTPS endpoints, secrets/keys shipped in the bundle or app.json, and default data-egress paths not disclosed at the point of choice (a pre-selected 'Recommended' option that silently sends personal data to a server). Same return shape as audit_page.
Inputs: source, app_json, info_plist, privacy_md, +1 more.
audit_ios_screenARead-onlyIdempotentInspect
Audit a rendered iOS screen from a view-hierarchy/accessibility snapshot (and optional screenshot). Alias of audit_screen with platform:"ios". Call with no arguments for the expected snapshot shape. Call with {elements:[{label,rect:{x,y,w,h},role,fontPt,fgColor,bgColor}],viewport:{w,h}} to score 44×44pt touch targets, contrast (with iOS secondaryLabel/tertiaryLabel treated as platform-standard — warn not fail), and visual rhythm (alignment, gap consistency, optical balance) in points. Same return shape as audit_page.
Inputs: profile, project, elements, viewport, +1 more.
audit_layoutARead-onlyIdempotentInspect
Evaluate visual rhythm from a rendered page's geometry. Call with no arguments to get a DevTools snippet to paste into your page — it prints {elements, viewport} JSON. Call again with that JSON to get alignment, gap-rhythm, and optical-balance scores. This is the complement to audit_page for things only visible once rendered.
Inputs: elements, viewport.
audit_pageBDestructiveInspect
Audit HTML/CSS against Raven's design quality standards. Checks typography (min 13px, weight 400+, modular-scale heading ratios, line-height consistency), accessibility (WCAG touch targets, alt text, contrast), responsive patterns (flexbox over grid, clamp sizing, max-width containers), style guide compliance (CSS custom properties, no bare hex), and visual rhythm (4/8px spacing grid, tight spacing scale, palette size). Pass containerMaxWidth (your design system's canonical container token, in px) to make the max-width check token-aware — it then flags containers that diverge from your system (too narrow OR too wide) instead of a generic 1200px heuristic. Returns pass/fail per check with specific fix instructions.
Inputs: url, html, strict, compact, +5 more.
audit_parityARead-onlyIdempotentInspect
Compare iOS vs Android element snapshots against a checklist of named spatial relationships (vertical centering, baseline/left alignment, equal gap/size, presence, truncation) and flag per-relation match/mismatch/uncertain — catches cross-platform layout drift like status text centered on one platform but top-aligned on the other. Provide ios+android {elements,viewport} snapshots and a checklist[].
Inputs: ios (required), android (required), checklist (required).
audit_responsive_visibilityARead-onlyIdempotentInspect
Render a URL at multiple breakpoints and flag content elements that are visible on desktop but hidden on mobile (display:none / opacity:0 / visibility:hidden / zero-size). Categorises each flag as 'likely-oversight' (content that vanishes on mobile — the hidden-on-mobile content bug) vs 'intentional' (decorative). Returns a table of selector / hiding-class / mobile-visible / desktop-visible / category. Requires headless chromium.
Inputs: url (required), breakpoints, viewportHeight.
audit_rnARead-onlyIdempotentInspect
Audit React Native / Expo source (JSX/TSX + StyleSheet) against the iOS HIG + Android Material conventions RN must satisfy. Flags touchables missing accessibilityLabel/accessibilityRole, touchables below 44pt without hitSlop, allowFontScaling={false}, fontSize below ~13, screens without SafeAreaView, and (for multi-mode apps) hardcoded colors with no useColorScheme/Appearance dark-mode handling. Rewards SafeAreaView, hitSlop, Platform-aware code, and a theme. RN-native checks only — no web/CSS or SwiftUI rules. Same return shape as audit_page. (RN renders to native widgets, so audit_ios_screen scores the rendered screen.)
Inputs: source (required), strict, profile, project, +1 more.
audit_screenARead-onlyIdempotentInspect
Audit a rendered mobile screen (iOS or Android) from a view-hierarchy/accessibility snapshot. Call with no arguments for the expected snapshot shape and how to capture it. Pass platform:"android" to score against the 48dp Material touch minimum and Material muted roles (onSurfaceVariant/outline = warn not fail); default platform:"ios" scores 44pt and treats secondaryLabel/tertiaryLabel as platform-standard. Both score touch targets, contrast, and visual rhythm (alignment, gap consistency, optical balance). Same return shape as audit_page.
Inputs: profile, project, elements, platform, +3 more.
audit_swiftuiARead-onlyIdempotentInspect
Audit SwiftUI source against Apple's Human Interface Guidelines. Flags hardcoded .font(.system(size:)) below ~13pt and tiny semantic fonts (.caption/.caption2), hardcoded Color(red:green:blue:)/hex instead of asset-catalog or semantic system colors, an empty/undefined AccentColor, interactive frames below 44×44pt, and ad-hoc spacing off the 4/8-pt grid. Rewards semantic Dynamic Type fonts, semantic system colors, SF Symbols, and flexible frames. iOS-native checks only — no web/CSS rules. Returns pass/fail per check with fix instructions.
Inputs: source (required), strict, profile, project, +1 more.
audit_tap_targetsARead-onlyIdempotentInspect
WCAG 2.5.5 / Apple 44pt tap-target audit for the web. Collects every interactive element (a, button, [role=button], input[type=submit/button/checkbox/radio], select, summary, label[for], [onclick], [tabindex>=0]) and emits a PER-ELEMENT fix table for any whose rendered width or height is below the minimum (default 44px): selector, role, visible text, measured w/h, pixel deficit per axis, and a concrete CSS fix. Sorted worst-first. Two modes: pass url (renders in headless chromium, measures real getBoundingClientRect) or pass elements[] snapshot (pure, no browser).
Inputs: url, minSize, elements.
audit_tasteARead-onlyIdempotentInspect
Judge a target against a taste profile. Pass html (static page/CSS), text (a copy block), or url (rendered headless; also runs delegated WCAG-contrast/tap-target measurements for owner:raven rules). Pass source_text to deterministically verify that the target's visible text remains verbatim through a content port. owner:taste rules run deterministic detectors — gradients, glow/neon (large-blur colored shadows), second accent hue, banned-word lists from the rule's negative prompt; clauses with no deterministic detector are reported honestly under not_assessed instead of guessed. owner:raven rules route through Raven's existing audit engines (page checks, contrast, tap targets) and fold results in under the delegating rule_id. Every finding cites an existing rule_id + concrete evidence — the engine prefers silence over a speculative nit. accept-verdict corpus precedents suppress previously-approved patterns. When the resolved binding carries design_notes, audit_taste VERIFIES each note against the artifact instead of only echoing it: url mode measures the rendered page's traits (scheme/luminance, canvas+WebGL, animations, scroll effects, text density, fonts, heading scale, loader, backdrop-filter), html mode extracts what it can statically, and every note comes back in note_assessments as present/partial/missing/unverifiable with trait-number evidence — design_notes are ACCEPTANCE CRITERIA for a build, not mood words. Missing notes become fidelity_findings (NOTE-, warn — block when a named library like three.js/gsap/lottie/anime.js or a branded loader is wholly absent), the target is compared against the binding's captured references (REF-* deltas on scheme, density, motion, type scale), and sparse-and-empty pages are flagged (TASTE-restraint-earned: sparseness must be earned by craft density, not achieved by deletion). fidelity_findings count toward the verdict. When a note names an expensive technique (three.js/WebGL, GSAP scroll choreography, anime.js staggered motion, glassmorphism, a branded loader, lottie, kinetic display type…), the result carries build_hints — a concrete recipe + canonical public example sources for that technique, so a failing audit hands the fix ammunition next to the missing finding; an expensive note is never license to drop it. Rules may carry a scope (e.g. portfolio-monochrome); pass surface to say what you're judging — scoped rules run at full severity on a matching surface, are skipped (reported under skipped_out_of_scope) on a non-matching one, and can warn but never block when surface is omitted. Better: pass project (or audit a bound url host) so a saved surface binding supplies the surface, per-rule overrides, and voice note automatically — on a NEW project with no binding, run get_taste_interview first (results carry a calibration_hint when calibration is missing). Verdict: BLOCK (any block finding) / WARN (any warn) / PASS.
Inputs: profile (required), url, html, text, +4 more.
audit_typographyARead-onlyIdempotentInspect
Audit the typographic SCALE of a rendered page (pass url) or a pre-collected snapshot of text nodes. Emits a focused report: (a) MODULAR SCALE — detects the dominant ratio (~1.2/1.25/1.333/1.5) across distinct font sizes and flags off-scale outliers; (b) LINE-HEIGHT CONSISTENCY — unitless lh/fs ratio per node, identifies the body rhythm and flags outliers; (c) WEIGHT LADDER — distinct weights, flags >4 weights or non-standard CSS values. Returns scale, line_height, weight_ladder, nodes_analyzed, and findings[{rule,severity,selector,message,fix}]. Goes beyond audit_page's pass/fail typography checks. url mode requires headless chromium.
Inputs: url, nodes.
audit_urlADestructiveInspect
Layer 0 render-and-capture audit: renders a LIVE URL at each viewport×theme, scroll-settles (fires whileInView/IntersectionObserver reveals; plays preload=none videos), optionally fires caller-supplied hover/focus/click interactions, and captures real pixels + the rendered DOM. Then runs the existing audit_page rule engine, per-element WCAG contrast, responsive-visibility (desktop-shown/mobile-hidden), blank-media detection, sliced-image edge symmetry, and hover-state white-wash detection over the captures. Every finding is tagged confirmed | likely-artifact | inconclusive with its evidence, ranked by severity. This is the tool that catches real-world visual nits invisible to HTML-string/geometry audits: cropped images, blank videos, hover white-wash, sliced exports, and hidden-on-mobile content. Requires headless chromium.
Inputs: url (required), themes, compact, timeoutMs, +5 more.
audit_video_playbackARead-onlyIdempotentInspect
Render a page in headless Chromium and observe whether each actually advances (samples currentTime before/after a play attempt), classifying every clip into playing|paused|stalled|empty|error with a reason. Catches black/non-playing videos that static audits miss — the most common real-world defect on marketing sites with video backgrounds. Pass url to render + observe, or dom_snapshot to classify pre-collected observations without a browser.
Inputs: url, observeMs, dom_snapshot.
bind_taste_surfaceADestructiveInspect
Persist a project's surface calibration for a taste profile — the answers from get_taste_interview. A binding records: the surface string scoped rules match against (e.g. 'product-site'), URL hosts that identify the project in url-mode audits, per-rule severity overrides (block|warn|nit|off — 'off' silences a rule on this surface), an optional voice/tone note, per-dimension design_notes (typography, spacing, color, layout, motion, imagery, entrance, loading, navigation, aesthetic, libraries, special — the interview's design:* answers), and a first-class references array — the example sites the person pointed to. References are NOT lossy prose: each url is captured live and its PageTraits (scheme, luminance, animation/scroll motion, text density) are stored on the binding, then design_notes are consistency-checked against what the references ACTUALLY are. A 'dark, cinematic' color note against two references that both render light comes back as a consistency_warning to surface to the user. Upserts by project name (~/.raven/taste/.surfaces.json); on a re-bind, omitted references/design_notes/voice_note/overrides/hosts carry forward and are reported in carried_forward, while explicit empty values clear them. When the design_notes name an expensive technique (three.js/WebGL, GSAP scroll choreography, anime.js staggered motion, glassmorphism, a branded loader, lottie, kinetic display type…), the result carries build_hints — a concrete recipe + canonical public example sources per technique, so the builder sees the HOW at kickoff, BEFORE building; an expensive note is not license to drop it. After binding, audit_taste with project:'' or a bound url applies the calibration automatically: matching scoped rules run at full severity, non-matching ones are skipped, overrides re-tune the rest. ENFORCED: a bind whose RESULT has no calibration content (no design_notes/voice_note/references/overrides) is REFUSED — a brand-new surface bound bare (the fingerprint of a skipped kickoff interview) and a re-bind that explicitly clears every calibration field alike; a stored uncalibrated_ack carries forward on re-binds, so only a NEW clear-everything requires a fresh ack. Run get_taste_interview, ask the USER, and bind their answers; the uncalibrated_ack escape hatch exists only for a user who was interviewed and deliberately skipped every dimension.
Inputs: profile (required), project (required), surface (required), hosts, +5 more.
capture_referenceADestructiveInspect
Persist a pattern grabbed from any page so it survives the browser tab. Call it after get_grabbed_elements returns a selection, passing that selection's selector/styles/html/rect/stateStyles plus the URL it was grabbed from. Stores one JSON record under ~/.raven/references; html over 8000 chars is truncated and flagged, style maps over 200 properties are rejected, and non-http(s) URLs are rejected. Every save gets a fresh ref_id, so grabbing the same element twice keeps both. When html is supplied it also renders a PNG thumbnail beside the record by rebuilding that markup offline in headless Chromium — every external request is blocked, so remote images and webfonts are absent and the record says so (image.fidelity 'offline'). The thumbnail is best-effort: if no browser is available the capture still succeeds, with no image field. It does not fetch the source URL, and does not map anything onto the project's tokens — that is map_reference_to_tokens.
Inputs: url (required), tags (required), owner (required), styles (required), +8 more.
compose_systemARead-onlyIdempotentInspect
Mix tokens from different design systems to create a custom composite. Example: Linear's colors + Stripe's typography.
Inputs: compositions (required), format.
configure_design_system_sourceBDestructiveIdempotentInspect
Save which local DESIGN.md file Raven should use for design-system inventory and comparison.
Inputs: project_dir (required), source_kind (required), aliases, platform, +1 more.
create_brand_profileADestructiveInspect
Create or update a local brand profile used by Raven creative jobs. Stores colors, fonts, tone, audience, constraints, product notes, and asset references locally under ~/.raven/creative by default.
Inputs: name (required), id, tone, fonts, +6 more.
create_character_profileADestructiveInspect
Create a local character/identity reference profile for consistent image or video generation. Raven stores reference asset IDs and provider-training payloads; actual identity training happens only through a configured provider runner.
Inputs: name (required), reference_asset_ids (required), id, metadata, +3 more.
create_generation_jobADestructiveInspect
Create a Raven creative generation job for image, video, 3D, audio, campaign, or analysis. Returns a brand-aware provider payload. If execute=true and RAVEN_CREATIVE_RUNNER is configured, Raven submits the job to that local runner.
Inputs: prompt (required), media_type (required), model, preset, +11 more.
create_motion_playgroundADestructiveInspect
Build a motion playground: one self-contained HTML file with an animation on a stage, its controls labelled in designer language, live preview and copyable exports (params JSON, an SVG frame, a WAAPI snippet), written under the taste home's playgrounds/ directory or output_path. Use it when someone wants to tune an animation by hand rather than describe it. Pass profile and project to prefill the playground's Copy for Raven text and, for a motif, to start from the bound surface's motion notes (only the terms restrained, subtle, snappy and no bounce are mapped; anything else is listed in warnings). The user pastes the Copy for Raven text back so you can call record_taste_decision with it. A default that breaks a motif constraint is corrected to the nearest valid step and reported in warnings; an override that cannot be corrected inside the control's range is an error. Raven never draws new artwork. Pass exactly one of motif or timeline. motif builds from a built-in motif. timeline builds from a Motion Lab timeline document you write: text, phases and tracks, checked by Motion Lab's own validator, with text outlined from the font files it names. An element target animates a part of the page passed in fragment, keyed by its id. A timeline plays on load, on hover ({ on: 'hover', target, leave: 'reverse' or 'finish' }) or when scrolled into view ({ on: 'scroll', threshold, once }). Timeline track properties: opacity, translateX, translateY, scale, scaleX, scaleY, rotate, fill, stroke, color, background, draw, clip, blur. Target kinds: surface, text, element. Named easings: linear, ease-in, ease-out, ease-in-out, or { cubicBezier: [x1, y1, x2, y2] }, or { spring: { duration, bounce } }. Use ONLY these.
Inputs: seed, motif, title, profile, +5 more.
create_taste_profileADestructiveInspect
Create (or overwrite) a named taste profile — a portable design-judgment ruleset + precedent corpus persisted locally under ~/.raven/taste/.json (override dir with RAVEN_TASTE_HOME). Pass explicit rules[] (rule_id, clause_text, category, severity_default block|warn|nit, negative_prompt, owner taste|raven, delegate_to), and/or a DESIGN.md-style markdown doc to ingest (## headings = categories; '- ' bullets = rules; '(block)'/'(warn)'/'(nit)' severity markers; '(raven:)' delegates a rule to an existing Raven audit tool; '(scope:)' scopes a rule to one surface; 'Do NOT …' sentences become the rule's negative prompt). Ingest RULES-SHAPED docs only (actionable design constraints under category headings) — brand-story/mythology docs produce noise rules, not judgment. Local-first: nothing leaves the machine. Pass template:'portfolio'|'saas-marketing'|'app' for a cold start — seeds a small starter ruleset (color restraint, typography floor, spacing, voice, tap targets) BEFORE any calibration interview has run; template rules are added first, then any explicit rules/markdown you also pass are merged in on top. Still run get_taste_interview afterward — the template is a floor, not a substitute for calibrating to the actual person's taste.
Inputs: name (required), rules, corpus, markdown, +1 more.
decision_addBDestructiveInspect
Add an active decision to the local Decision Graph.
Inputs: scope (required), statement (required), component_ref (required), author, +2 more.
decision_commitADestructiveIdempotentInspect
Commit or confirm the rationale for a draft or extracted decision.
Inputs: id (required), rationale (required), similarity_threshold.
decision_contestADestructiveInspect
Contest an active decision: it stops governing immediately, without deleting it or requiring a replacement.
Inputs: id (required), reason (required), evidence_ref.
decision_draftADestructiveInspect
Capture a decision from working context with the why deferred for later confirmation.
Inputs: scope (required), statement (required), component_ref (required), alternatives_rejected.
decision_evidenceADestructiveInspect
Attach quantitative or qualitative evidence to an existing decision.
Inputs: type (required), confidence (required), source_ref (required), decision_id (required), +2 more.
decision_getADestructiveInspect
Get a Decision Graph node and every node connected to it by an edge in either direction.
Inputs: id (required).
decision_historyARead-onlyIdempotentInspect
Return the complete supersession lineage for a decision, ordered oldest to newest.
Inputs: id (required).
decision_importADestructiveInspect
Mine local git history and decision-bearing Markdown into provenance-tagged Decision Graph extraction prompts. Imported history remains review-only until decision_commit.
Inputs: repo_path (required), doc_globs, max_commits, max_chunk_chars.
decision_listADestructiveInspect
List decisions in the local Decision Graph. Defaults to ACTIVE decisions only — the ones that currently govern. Contesting a decision is what stops it governing, so contested decisions are deliberately excluded from the default: pass status:'contested' to review disputes, or include_contested:true to see both. A decision you cannot find is not the same as a decision that does not exist.
Inputs: status, drafts_only, include_contested, include_candidates.
decision_scopeADestructiveInspect
Narrow two decisions to distinct scopes so both can remain active alongside one another.
Inputs: id_a (required), id_b (required), scope_a (required), scope_b (required).
decision_supersedeADestructiveInspect
Explicitly supersede one decision with another while preserving both nodes and their lineage.
Inputs: new_id (required), old_id (required).
design_gauntletARead-onlyIdempotentInspect
Answers 'why does my page look less polished than theirs?' with numbers instead of adjectives. Give it your page and a page you admire (vercel.com, linear.app, anything); both are rendered headless and their LIVE computed CSS is measured — never recalled from memory — across the nine things that decide perceived polish: surfaces, hairlines, text roles, letter spacing, accent, type scale, radii, elevation, rhythm (the first four dominate). You get back both sets of raw measurements, a per-dimension diff flagging where yours is worse, a concrete bar derived from the reference's own values (e.g. 'at most 4 surface colors — yours has 11'), a fix list split into mechanical find-and-replace vs decisions a human has to make, and one boolean, verdict.on_par. That boolean is the exit gate of the loop the response spells out: build, critique with fresh-context critics against renders, re-run this tool, and only call the work done when on_par is true. The reference is a standard, not a source — never copy its copy, marks, imagery or brand color.
Inputs: subject_url (required), reference_url (required), viewport, color_scheme, +1 more.
diff_design_systemARead-onlyIdempotentInspect
Diff a project's declared design system (DESIGN.md) against the Raven canonical baseline: reports missing components, missing interaction/accessibility states, missing variants, and raw-literal token drift, as a scored report with fix priorities.
Inputs: baseline, platform, project_dir, design_file_path.
evaluate_designBRead-onlyIdempotentInspect
Evaluate a design description against UX principles. Returns relevant principles, potential violations, and improvement suggestions.
Inputs: goals, compact, context, description, +2 more.
forget_referencesADestructiveIdempotentInspect
Remove stored patterns from the local corpus — one by ref_id, or every pattern captured from a site. This is the takedown path: if a site asks that their design work not be kept, forget_references({ host: 'their.site', confirm: true }) removes every record and every rendered thumbnail from that host in one call. Host matching is exact plus subdomains ('linear.app' takes 'app.linear.app', never 'notlinear.app'; an IP address matches only itself), and a host-wide removal requires confirm:true because it is not reversible — there is no trash. The refusal names the ref_ids it would remove: pass them back as expected_ref_ids to pin the removal to what you were shown, and anything that appeared since is reported in appeared_since_preview[] rather than deleted. Returns the ref_ids actually removed, so a partial result is visible rather than assumed; records whose JSON could not be parsed are reported in skipped[] and left on disk rather than counted as cleared, and records that could not be deleted are reported separately in failed[]. Local only: it deletes files under the reference home and contacts nobody.
Inputs: host, ref_id, confirm, expected_ref_ids.
gap_scanARead-onlyIdempotentInspect
Scan the local Decision Graph for uncovered components, weak rationales, contested decisions, and derived staleness. Schedulers should call with digest_only:true and treat actionable:false as a no-op.
Inputs: use_cases, digest_only, reference_systems.
generate_design_systemADestructiveIdempotentInspect
Generate a complete, custom design system with full token set. Provide a brand color to auto-generate a harmonious palette, pick a style preset, and export as visual HTML documentation, CSS variables, W3C DTCG JSON, Figma Variables, or SVG palette card. The HTML export is a beautiful, self-contained page suitable for sharing with stakeholders. Pass save:true to store the system for reuse by id — this is how a taste-engine session's design system becomes durable.
Inputs: name (required), save, style, format, +3 more.
generate_mood_boardADestructiveInspect
Compose a mood board from what the Taste Engine already holds for a bound project — the binding's design_notes as chips, its captured references, and pattern-library thumbnails captured from those same reference sites — written as one self-contained HTML file (plus a best-effort PNG of the board) under the taste home's moodboards/ directory, or output_dir. Pass image_paths to embed the user's OWN images too — a generated brand pack, product shots, mood images — shown as a 'Your assets' section (they are the user's material, so no third-party credit rides on them). Use it right after the kickoff interview binds a surface ('get a mood board going'), or pass mode:'example' to show a labeled sample board to a user who has never made one, to get their thinking started BEFORE the interview. The board invents nothing: note text stays text (never fabricated color swatches), the ground (light/dark) is measured from the captured references' scheme traits, and every embedded pattern carries its credit. It is an APPROVAL STOP: the result and the board's footer name generate_design_system — the taste engine's core output — as the next step once the user says the direction is right; this tool never runs it. mode:'board' requires an existing surface binding and throws naming get_taste_interview when there is none.
Inputs: profile (required), mode, project, output_dir, +1 more.
generate_service_blueprintARead-onlyIdempotentInspect
Render a service blueprint as a self-contained HTML page. Supports two modes: (1) classic Shostack single-actor blueprint — user action, frontstage, backstage, support, evidence, pain/delight; (2) two-actor HI-loop blueprint — when actors is supplied, renders two swim lanes with a line of interaction between them (e.g. customer ↔ lawyer, patient ↔ doctor, buyer ↔ agent). Each actor gets their own actions, frontstage (what they see), and evidence. Optionally accepts an ideal-state to render side-by-side with the current state.
Inputs: current (required), service_name (required), ideal, actors, +1 more.
generate_taste_portraitADestructiveInspect
Render a bound Taste Engine surface as a self-contained designed HTML portrait. Pass project to render one binding, or omit project to render every binding plus a gallery index.html. Portraits are generated from the local taste store and should be verified with audit_taste against their own surface/project before sharing — pass document_kind:'portrait' on that audit: a portrait is a document ABOUT the surface, so design_notes (three.js scenes, branded loaders…) are not acceptance criteria for it; profile rules still bind in full.
Inputs: profile (required), output_dir (required), project.
get_brand_principlesARead-onlyIdempotentInspect
Get brand and visual-design principles — logo usage (clear space, min sizes, variants, placement, restraint), gradient usage (hierarchy, palette, contrast, trend vs signature), imagery (consistency, representation, purpose), visual hierarchy, and brand-as-system thinking. Use when the user asks about branding, logos, gradients, imagery, visual consistency, or how to treat a brand across surfaces.
Inputs: topic, format.
get_brand_profileARead-onlyIdempotentInspect
Read a local Raven creative brand profile by ID.
Inputs: id (required).
get_brand_systemARead-onlyIdempotentInspect
Get a complete design system for building an app with branding like a specific company. Say 'Make me an app with branding like Spotify' and get the full token set, style guide, and implementation instructions. Matches against 12 known design systems and provides closest match with ready-to-use CSS.
Inputs: company (required), mode, format.
get_brand_trendsARead-onlyIdempotentInspect
Get current brand and visual-design trends — what's working in 2026 and where each trend fits or fails. Includes bento grids, monospace type, neon-on-dark-glass, generative patterns, brutalism rebound, AI-generated imagery, lowercase/mixed case. Each trend is time-stamped — treat as a calibration signal, not a prescription.
Inputs: no named parameters.
get_business_strategyBRead-onlyIdempotentInspect
Get business and monetization strategies for digital products. Covers monetization models, retention strategies, onboarding optimization, growth mechanics, and product metrics frameworks.
Inputs: type (required), stage.
get_checklistARead-onlyIdempotentInspect
Get a pre-publish checklist for a specific UI type. Returns actionable yes/no items to verify before shipping.
Inputs: type (required), platform.
get_content_patternARead-onlyIdempotentInspect
Get content design patterns — copy recipes for error messages, empty-state copy, notifications, and form validation. Returns do's, don'ts, good/bad examples, evidence, and a checklist.
Inputs: type (required).
get_content_principlesARead-onlyIdempotentInspect
Get UX-writing principles — clarity over cleverness, active voice, error-message anatomy, inclusive language, voice vs tone, and more. Filter by the writing context (e.g. 'error messages', 'notifications', 'form labels').
Inputs: format, context.
get_content_systemARead-onlyIdempotentInspect
Get a brand's content design system — voice attributes, tone shifts by context, vocabulary (use/avoid/never), grammar rules, content patterns for errors/empty-states/buttons/etc., and inclusive language guidance.
Inputs: id (required), section.
get_d4d_frameworkARead-onlyIdempotentInspect
Get the Design for Delight (D4D) framework templates. Returns customer problem statement, ideal state, hypothesis, LOFA, and experiment templates for structured product thinking.
Inputs: stage.
get_design_systemBRead-onlyIdempotentInspect
Get design tokens for a specific design system. Returns colors, typography, spacing, radii, elevation, and motion tokens in W3C DTCG, CSS custom properties, or flat format.
Inputs: id (required), group, format.
get_generation_jobARead-onlyIdempotentInspect
Read a Raven creative generation job by ID.
Inputs: id (required).
get_grabbed_elementsCDestructiveInspect
Read newly sent grab selections without deleting their durable change records, optionally waiting up to timeout_ms. A batchCommit marker is the deterministic signal to implement the unified pending batch.
Inputs: timeout_ms.
get_grab_layersARead-onlyIdempotentInspect
Read the latest non-mutating layer-tree snapshot captured by the active local grab session. Any fixed/flexible permissions are cooperative advisory metadata: display labels only, not enforced.
Inputs: page.
get_grab_operationADestructiveInspect
Read or update one durable grab change, list legacy reorder operations, or request the unified style+reorder batch. Applied/rejected/superseded changes leave the pending set.
Inputs: mark, batch, operation_id.
get_metrics_frameworkARead-onlyIdempotentInspect
Get a product-metrics framework — HEART (Google), AARRR/Pirate (Dave McClure), North Star Metric, Conversion Funnel, RICE Scoring, or OKRs. Returns structure, when-to-use, pitfalls, and examples. Use when the user asks 'how should we measure success?' or 'what metrics should we track?'
Inputs: id, search.
get_motion_sendsADestructiveInspect
Receive what the designer sent from a motion playground opened with open_motion_playground. Each send carries the designer's note (instruction), what they were looking at (context), and the motion as tuned (packet), along with the playground's url and html_path. Act on the note using the packet; when the note is empty, the packet itself is what they want. Returns at once with anything already sent, and each send is returned only once. When you expect a send, pass timeout_ms, up to 240000, to wait for it.
Inputs: timeout_ms.
get_page_templateARead-onlyIdempotentInspect
Read the page-scoped template slots from the active grab session's DESIGN.md and merge the overlay's latest selector validation. fixed/flexible roles and allowedTokens are cooperative advisory metadata: display labels only, not enforced.
Inputs: page (required).
get_patternBRead-onlyIdempotentInspect
Get proven UI/UX patterns for a specific design type. Returns do's, don'ts, evidence, and checklists for signup flows, pricing pages, navigation, forms, landing pages, dashboards, modals, empty states, error states, loading states, CTAs, social proof, and mobile conversion.
Inputs: type (required), goal, platform.
get_principlesARead-onlyIdempotentInspect
Get design principles relevant to a UI context. Returns usability heuristics, laws of UX, Gestalt principles, accessibility requirements, typography rules, and color theory — matched to what you're designing.
Inputs: context (required), format, category, platform.
get_research_methodARead-onlyIdempotentInspect
Get research method details — qualitative (interviews, contextual inquiry, diary, field, intercept), quantitative (surveys, analytics, A/B tests, benchmarking, clickstream), or usability (moderated, unmoderated, 5-second, card sort, tree test, heuristic eval). Returns specific protocols, do/don't guidance, evidence, and a checklist. Use when the user is designing a study or asking how to measure something.
Inputs: search, category.
get_service_patternARead-onlyIdempotentInspect
Get a service design pattern — service blueprinting, human handoff, signup-as-service, omnichannel continuity, or moments of truth / recovery. Returns patterns, do/don't guidance, evidence, and a checklist. Use when the user is designing a service flow, escalation, cross-channel experience, or moment of truth.
Inputs: type (required).
get_service_standardARead-onlyIdempotentInspect
Get the GOV.UK Service Standard — 14 points the UK government uses to assess whether a public service is ready to launch. Widely applicable as a rigorous service-quality checklist beyond government. Use when the user asks how to evaluate a whole service.
Inputs: no named parameters.
get_taste_interviewARead-onlyIdempotentInspect
START HERE on a NEW project: returns a deterministic calibration interview. By default (depth:'first_run') it is COMPRESSED to just 6 core questions — identity, customer (who it is for, what they are trying to do when they arrive, what would make them leave; stored as design_notes.customer), genesis (what already exists for the project — a brand, a design system, brand assets — routing whatever is missing to generation: mood board approval stop, then generate_design_system save:true, then init_design_md), aesthetic, voice, matchers — so a first-time kickoff is fast; every other question (references, the remaining ten design dimensions, any learned dimensions, rule exceptions, and the open-ended special question) is still returned under more_questions for the agent to offer as optional deeper calibration. Pass depth:'full' to get everything at once as a single flat questions list (the eleven design dimensions — typography, spacing, color, layout, motion, imagery, entrance, loading, navigation, aesthetic, libraries — each grounded in what the profile already enforces and most carrying multiple-choice options; the libraries question names specialty tech in plain outcome language and states the default build target for sites: a Next.js app, unless the user prefers otherwise). The voice question always renders the same message in three registers (formal-technical / warm-conversational / punchy-editorial) so the user picks by ear, not by adjective — asked even when the profile has zero voice rules. Every question carries skippable + priority ('core'|'extended'); only identity is required. A 'references' question (offered in more_questions on first_run) invites example URLs/screenshots/files, each interviewed with follow-ups about what specifically draws the person, folded into the matching design_notes. The full interview closes with an open-ended 'special' question (any texture, signature detail, motif, or easter egg nothing else asked about); once the person has other bound surfaces, it carries suggestions — the special touches they chose elsewhere. Ask the user the returned questions conversationally, then persist the answers with bind_taste_surface (dimension answers go in design_notes). Run this BEFORE the first audit_taste on any project that has no binding yet — audit results include a calibration_hint when calibration is missing. When a user dislikes generated/designed output on an ALREADY-calibrated project, re-run with mode:'refine' instead of starting over — dissatisfaction is a calibration signal, not a dead end: it requires an existing binding, then interviews what specifically fell short, offers to keep/tighten/replace each stored design_notes value, re-asks voice, and offers to log a reject precedent via label_finding. mode defaults to 'kickoff'.
Inputs: profile (required), mode, depth, project.
get_taste_profileARead-onlyIdempotentInspect
Load a locally stored taste profile by name — returns its full rule catalog, precedent corpus, and per-project surface bindings. NOT a calibration step: bindings are per-surface and do not transfer — for design work on a project without a binding, call get_taste_interview and ask the user its questions before committing any direction.
Inputs: name (required).
ingest_transcriptADestructiveInspect
Store a transcript source and return an extraction prompt for the calling agent's model. Raven makes no model or network call.
Inputs: text (required), source_meta (required).
ingest_transcript_resultsADestructiveInspect
Parse model-produced extraction JSON into reviewable Decision Graph candidates linked to their source. Nothing is auto-confirmed.
Inputs: source_id (required), extraction_json (required).
init_design_mdADestructiveIdempotentInspect
Initialize a DESIGN.md file from a stored Raven token system, a getdesign.md starter slug, or a blank template.
Inputs: path (required), from.
inventory_design_systemBRead-onlyIdempotentInspect
Read component declarations and tokens from a local DESIGN.md file.
Inputs: project_dir, design_file_path.
label_findingADestructiveInspect
Append a labeled precedent to a taste profile's corpus — the growth loop. Use when a human accepts/revises/rejects an audit_taste finding or labels a new wrong→right example. Append-only: existing records are never rewritten. accept-verdict precedents suppress matching findings in future audit_taste runs.
Inputs: right (required), wrong (required), profile (required), verdict (required), +3 more.
list_brand_profilesARead-onlyIdempotentInspect
List local Raven creative brand profiles.
Inputs: no named parameters.
list_content_systemsBRead-onlyIdempotentInspect
Browse available content design systems — brand voice and tone guides (Conversational Product Voice, GOV.UK, Shopify Polaris, Atlassian). Filter by category or search by name.
Inputs: search, category.
list_creative_modelsARead-onlyIdempotentInspect
Browse Raven's provider-agnostic creative model catalog. These are capability slots for image, video, 3D, audio, character consistency, and creative analysis. Each entry lists typical inputs and best-for guidance.
Inputs: capability, media_type.
list_creative_presetsBRead-onlyIdempotentInspect
Browse Raven creative presets for product photoshoots, marketplace cards, UGC ads, TV spots, cinematic reveals, social launch packs, storyboards, and infographics.
Inputs: search, media_type.
list_design_system_componentsARead-onlyIdempotentInspect
List the components and provenance in the Raven canonical baseline.
Inputs: baseline.
list_design_systemsARead-onlyIdempotentInspect
Browse available design systems for tokens. Filter by category (component-library, consumer, developer, fintech, framework, platform, productivity) or search by name.
Inputs: search, category.
list_generation_jobsARead-onlyIdempotentInspect
List local Raven creative generation jobs.
Inputs: limit, status, media_type.
list_taste_decisionsARead-onlyIdempotentInspect
List the taste/direction/design decisions recorded for a profile (see record_taste_decision), optionally filtered by project or dimension — the ledger that evolves the kickoff interview.
Inputs: profile (required), project, dimension.
list_taste_profilesARead-onlyIdempotentInspect
List locally stored taste profiles with rule/corpus counts and last-updated timestamps.
Inputs: no named parameters.
list_templatesARead-onlyIdempotentInspect
List templates and their registered page pathnames from the active grab session. Template permissions and allowedTokens are cooperative advisory metadata: display labels only, not enforced.
Inputs: no named parameters.
map_reference_to_tokensARead-onlyIdempotentInspect
Translate a captured pattern's raw literals (font-size: 64px, color: rgb(247,248,248)) onto the project's own design tokens, so generated code uses the user's type ramp and palette instead of another site's values. Pure and deterministic — no model, no network. Colours compare by RGBA distance (exact at 0, near under 12; alpha counts), lengths normalize to px at root 16 (near under 2px), unitless numbers near within 1%, font families compare on the first family. A property with a known token family (font-size, line-height, gap, radius, …) only ever binds inside that family: if the closest token by value belongs to another ramp, the result is a gap naming it, not a binding. Winners are ordered by distance, then family fit, then shortest and lexicographic token path. Percent and viewport units, unparseable colour syntaxes, shadows, gradients, and other unmatchable classes become gaps with a stated reason — never a forced match. Broken token chains are reported in diagnostics whether or not anything else matched. A project with no tokens is not an error: every property returns as a gap at coverage 0. It does not invent tokens and does not write code.
Inputs: ref_id, tokens, captured, properties, +2 more.
move_grab_layerADestructiveInspect
Queue a same-page layer reorder or reparent intent (previewed when measuredRects are supplied, otherwise proposed) without mutating the live page. Reparent moves a node to a different parent (toParentSelector); reorder keeps a single parentSelector. Permissions and fixed/flexible roles are cooperative advisory metadata: display labels only, not enforced; caller-supplied roles are rejected. Shadow-root and iframe boundaries are out of scope.
Inputs: page (required), toIndex (required), fromIndex (required), operation (required), +13 more.
open_motion_playgroundADestructiveInspect
Open a motion playground at a local link where the designer can tune it in their browser and use Send to your agent to send you a note along with the motion as they tuned it. Pass the html_path that create_motion_playground returned. Hand the designer the url, not the file path: the file opened on its own cannot send. Then call get_motion_sends to receive what they send. This is separate from Raven Grab and puts nothing on top of the page. The link works on this computer only, for as long as this Raven process runs, and the file is read fresh on every load, so a rebuilt playground shows up when the designer reloads.
Inputs: html_path (required).
plan_creative_campaignADestructiveInspect
Plan a multi-asset creative campaign and optionally create draft generation jobs. Covers Higgsfield-like workflows: product photos, UGC/video ads, marketplace cards, launch/social packs, storyboards, and channel cutdowns.
Inputs: goal (required), audience (required), channels (required), campaign_name (required), +6 more.
polish_diffARead-onlyIdempotentInspect
Review added UI-code lines and propose deterministic DESIGN.md token substitutions without writing files. The returned unified patch applies on top of the reviewed diff's post-image; applying it is an explicit, separate step by the caller. Re-verifies the hypothetical polished lines and leaves judgment-heavy findings in manual.
Inputs: diff (required), project, design_md.
raven_reflectARead-onlyIdempotentInspect
Summarize how Raven has been used on this machine over the last N days. Reports which tools are called most, which audit warnings fire repeatedly (→ likely gaps in Raven's knowledge), which patterns and design systems you look up, and which companies you ask for brand styles. Call this when the user asks 'what have I been building with Raven' or 'what's Raven missing'. All data is read from a local log ($RAVEN_USAGE_LOG or ~/.raven/usage.jsonl) — nothing is fetched over the network.
Inputs: days.
raven_registerADestructiveInspect
Register your email to receive design updates and provide feedback to the Raven creator. Call this when a user wants to register, give feedback, or connect with the Raven team.
Inputs: email (required), name.
read_design_mdARead-onlyIdempotentInspect
Parse a DESIGN.md file and return its frontmatter, Markdown body, and flattened token index.
Inputs: path (required).
record_taste_decisionADestructiveInspect
The Taste Engine's learning loop — record a taste, direction, or design decision the MOMENT it is made during real work (an accent chosen, a nav pattern rejected, a name direction picked, a type pairing approved), not just at interview time. Each record carries the project, a short dimension name (a standard one like color/navigation or a new category like iconography/sound), what was chosen in the user's words, the alternatives rejected, why, and a source: 'user-directed' (the user asked for it), 'user-approved' (the user accepted a proposal), or 'user-corrected' (the user overrode a generated choice — the highest-signal record). Recorded decisions evolve every future get_taste_interview kickoff: recurring choices return as suggested defaults on their dimension's question, and decision categories no standard question covers become NEW interview questions. Record liberally — every committed decision is calibration data.
Inputs: profile (required), project (required), decision (required), dimension (required), +3 more.
register_creative_assetADestructiveInspect
Register a local or remote creative asset for Raven jobs. This is the local-first analog of upload: Raven stores metadata and a URI/path, not the file bytes.
Inputs: uri (required), type (required), name, tags, +2 more.
review_diffARead-onlyIdempotentInspect
Review added UI-code lines in a unified diff against the project's own DESIGN.md tokens and active recorded design decisions. Returns a structured CI verdict with file/line findings and nearest-token suggestions. Agents should call this on every PR or diff that touches UI code before merge.
Inputs: diff (required), fail_on, project, design_md, +1 more.
score_creativeARead-onlyIdempotentInspect
Score a creative prompt, script, or ad concept for hook strength, benefit clarity, product signal, call-to-action, channel fit, audience fit, and brand fit. This is a transparent heuristic, not a proprietary prediction model.
Inputs: creative_text (required), channel, audience, brand_profile_id.
score_pageARead-onlyIdempotentInspect
Score an HTML/CSS page across 7 design categories (Structure, Typography, Color & palette, Spacing & rhythm, Accessibility, Responsive layout, Design tokens), each rated 0–10. Scores are derived deterministically from the same checks as audit_page — no browser required. Pass html directly, or pass url to have Raven launch headless chromium, render the page, and score the RENDERED DOM. Also returns the same overall 0–100 score and A–D grade audit_page produces, the weakest category, and the three categories Raven does not mechanically assess (brand, conversion, motion) with guidance on which tools to use for those.
Inputs: url, html, strict, containerMaxWidth.
search_knowledgeARead-onlyIdempotentInspect
Search across all design principles, UI patterns, and business strategies. Use when you need to find specific guidance or don't know which category to look in.
Inputs: query (required), layer.
search_referencesARead-onlyIdempotentInspect
Find patterns previously kept with capture_reference — call it before rebuilding something already grabbed, or to recall 'that hero from Linear'. host, owner, and tags filters compose with AND; the free-text query expands recognized pattern intent through Raven's controlled vocabulary, then matches case-insensitively against note, app, tags, bound taxonomy ids, and selector. Every result carries a score and a 'why' naming the matched fields and any alias that connected the query to the record. Ordering is deterministic. Returns stored JSON records. Every result carries a display object holding the credit line, the source URL, and image_path — the PNG on disk for records captured with html, so results can be shown as pictures rather than style maps (the tool returns the path, never the bytes). Browsing does not hand back the other site's markup. A result reports html_available and html_truncated but omits the html itself; pass include_html:true to receive it, which is a deliberate step because that markup is the site's own authored expression rather than a measurement of it. Everything needed to LOOK at a pattern and to translate it onto this project's tokens — the picture, the selector, the rect, the computed styles — is in the default result. Show the credit whenever you show the pattern: this corpus holds other people's design work, Raven does not own it, and a third-party result also carries a notice saying so. Use these as references to build your own implementation, not as work to republish. Corrupt records are named in skipped[] instead of failing the call. It does not rank against live code and does not fetch the source site.
Inputs: host, tags, owner, query, +1 more.
set_template_slotBDestructiveIdempotentInspect
Persist an array of page-scoped template slots in one batched DESIGN.md update. fixed/flexible roles and allowedTokens are cooperative advisory metadata: display labels only, not enforced.
Inputs: page (required), slots (required), template_id.
start_grab_sessionBDestructiveInspect
Start a capability-keyed Raven grab bridge on loopback. Proxy mode is the preferred zero-paste path: it serves a running local app with the overlay injected into HTML; the manual script tag remains available when needed. When proxying the designer's own local dev server, Grab's Motion tab finds motion for the page and builds playgrounds itself; pass profile and project when the project has a taste binding so those suggestions follow the designer's notes and earlier motion decisions.
Inputs: path, port, role, profile, +2 more.
stop_grab_sessionADestructiveIdempotentInspect
Stop the current grab bridge and clear its queued selections.
Inputs: no named parameters.
suggest_contrast_fixARead-onlyIdempotentInspect
Given failing WCAG color pairs, return the MINIMAL color change that clears the target ratio. For each {fg,bg} pair, computes the smallest foreground adjustment (and an alternative background adjustment) that reaches AA/AAA — with the achieved ratio and direction. Feeds directly from audit_contrast's failing pairs: pass them here to get concrete passing values instead of brute-forcing colors by hand. Pure offline math.
Inputs: level, pairs.
suggest_motionADestructiveInspect
Find the places on a page where motion would help, and build a playground for each from the page's own content. Captures the page at url, picks moments (hero entrance, button hover, card hover, section reveal, navigation hover, image reveal), and for each writes a playground the designer can tune, built from the captured text, styles, images and fonts. Also writes a map: a picture of the page with a numbered spot on each suggestion and a list of why each was picked. Pass profile and project so the suggestions follow the designer's motion notes, customer note and earlier decisions; a 'none-instant' or 'no motion' note returns no suggestions. Anything the playground cannot show exactly, such as a gradient or a shadow, is listed in approximations. Then call open_motion_playground with map_path and hand the designer the url. When the designer names one element in chat ("add motion to the pricing cards"), find its CSS selector in the code or from get_grabbed_elements and pass selector (and trigger if they said when it should move): that builds one playground for that element from the same capture, with no map, and returns preview_url to give the designer. Captures only http and https pages; a local or private address is allowed only when url itself is one.
Inputs: url (required), max, profile, project, +3 more.
talon_rulesARead-onlyIdempotentInspect
Enumerate Raven's Talon detector rule corpus — id, category, severity, taste scope, and the src/data/principles/*.json entry each rule cites. No scan required; use this to show a client 'why' before or instead of running talon_scan.
Inputs: no named parameters.
talon_scanARead-onlyIdempotentInspect
Run Raven's deterministic detector engine over a page — no LLM, pure measurement. Covers color-system discipline (palette budget, near-duplicate hex, hue diversity), spacing-grid conformance (base-unit, scale count), type-scale/rhythm (size count, body line-height, measure, font-family budget), heading/landmark structure, motion-duration/easing sanity (flashing-animation risk, prefers-reduced-motion coverage), and orphan-stretch/horizontal-overflow geometry. Pass html, url (rendered headless), or pre-measured elements+viewport (the same DevTools-snippet shape audit_layout takes — required for the two geometry rules). Every finding cites the src/data/principles/*.json entry it derives from. Pass project (and profile) to resolve a saved taste surface binding (see bind_taste_surface) — a finding the binding silences via an 'off' override is still returned, flagged waived_by_taste:true, never dropped.
Inputs: url, html, profile, project, +3 more.
update_design_mdBDestructiveIdempotentInspect
Update one DESIGN.md token surgically while preserving the Markdown body.
Inputs: path (required), set, remove, rename.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 115 tools
The set contains many overlapping audit and evaluation tools, including `audit`, `audit_page`, `score_page`, `audit_url`, `talon_scan`, `design_gauntlet`, and numerous platform-specific audit variants. The `audit` description explicitly says to use it instead of choosing individual `audit_*` tools, which admits redundancy and makes tool selection confusing for an agent.
Almost all tools use readable snake_case and most follow a verb_noun pattern, such as `get_design_system`, `create_generation_job`, and `audit_contrast`. There are minor namespace inconsistencies (`raven_register`, `decision_*`, bare `audit`) but no chaotic mixed casing.
At 115 tools, this is far beyond a well-scoped surface and creates an extreme mismatch for an agent using the server as a coherent toolkit. Many tools appear to be layered alternatives or niche variants that should be discoverable through fewer entry points.
The surface is extremely broad, covering audits, design systems, taste calibration, references, motion, creative generation, and decision tracking. Some resource lifecycles lack obvious delete/update operations, but the major domains are well represented with only minor gaps.
Maintenance
Related MCP Connectors
The Figma MCP server brings Figma design context directly into your AI workflow.
A design harness for AI coding agents: design systems, design principles, icons and UI review.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
UI design from prompts, screenshots, and URLs for AI coding agents and theme tokens.
Related MCP Servers
- AlicenseCqualityDmaintenanceA comprehensive MCP server that enables Claude to read, create, edit, and generate code from Figma designs. Supports design tokens, code generation to multiple frameworks, and accessibility checks.1004MIT
- AlicenseBqualityDmaintenanceAn MCP server that drives Anthropic's Claude Design from agentic coding CLIs, providing tools to create, generate, iterate, and export design systems without a browser.32MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants structured access to a design system's tokens, components, guidelines, and patterns, enabling them to read, lint, and author design system data.1MIT
- AlicenseAqualityDmaintenanceMCP server that gives LLMs deep knowledge of design systems and tokens, enabling intelligent design evolution, token analysis, and designer-to-developer handoffs.3713 npm2MIT