Design judgment,
available at the prompt.

#get_principles

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.

Parameters

contextrequired

What you’re designing (e.g. ’signup form’, ’pricing page’, ’mobile nav’, ’dark dashboard’)

categoryoptional

Filter to category: nielsen-heuristics, laws-of-ux, gestalt, accessibility, typography, color-theory, mobile-ux, d4d, color-systems, spacing-systems

platformoptional

Platform context. ’ios’ returns Apple HIG principles (Dynamic Type, 44pt targets, SF Symbols, safe areas, dark-mode, haptics, App Review privacy); ’react-native’ returns RN principles (44/48pt+hitSlop, accessibilityLabel/Role, font scaling, SafeAreaView, dark mode, iOS+Android parity, secrets). Both replace the web/CSS-oriented set. Default: web.

formatoptional

Output format: full (all details), checklist (implications + violations), brief (just summary). Default: full

#evaluate_design

Evaluate a design description against UX principles. Returns relevant principles, potential violations, and improvement suggestions.

Parameters

descriptionoptional

Description of the design to evaluate

before_screenshotoptional

Base64 PNG of the BEFORE state

after_screenshotoptional

Base64 PNG of the AFTER state. When both before+after are provided, returns a structured pixel diff with fix_confirmed.

goalsoptional

What to evaluate for (e.g. [’conversion’, ’accessibility’, ’mobile-usability’])

contextoptional

What the design is (e.g. ’pricing page for SaaS product’)

compactoptional

Return only ids+names for matched principles/patterns (drop their full bodies) plus counts and any before/after diff. Default false. Use when the full principle library payload would blow the tool-result budget.

#get_checklist

Get a pre-publish checklist for a specific UI type. Returns actionable yes/no items to verify before shipping.

Parameters

typerequired

What you’re shipping (e.g. ’signup form’, ’pricing page’, ’dashboard’, ’landing page’, ’modal’)

platformoptional

Platform context for platform-specific checks. ’ios’ = native SwiftUI/iOS (Apple HIG); ’react-native’ = RN/Expo (iOS HIG + Android Material: 44/48pt+hitSlop, accessibilityLabel/Role, font scaling, SafeAreaView, dark mode, platform parity, secrets). Both replace the web/mobile-web checks. — “desktop” | “mobile” | “responsive” | “ios” | “react-native”

#get_d4d_framework

Get the Design for Delight (D4D) framework templates. Returns customer problem statement, ideal state, hypothesis, LOFA, and experiment templates for structured product thinking.

Parameters

stageoptional

Which stage of the D4D loop to return. Default: full (all stages) — “frame” | “empathy” | “broad” | “narrow” | “experiment” | “recommendation” | “full”

#get_pattern

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.

Parameters

typerequired

Pattern type (e.g. ’signup-flow’, ’pricing-page’, ’navigation’, ’forms’, ’landing-page’, ’dashboard’, ’modals-dialogs’, ’empty-states’, ’error-states’, ’loading-states’, ’cta’, ’social-proof’, ’mobile-conversion’)

platformoptional

Filter patterns by platform context — “desktop” | “mobile” | “responsive”

goaloptional

Filter by primary goal — “conversion” | “usability” | “accessibility” | “delight”

#get_business_strategy

Get business and monetization strategies for digital products. Covers monetization models, retention strategies, onboarding optimization, growth mechanics, and product metrics frameworks.

Parameters

typerequired

Strategy type: monetization, retention, onboarding, growth, metrics

stageoptional

Company stage for contextual filtering — “startup” | “growth” | “mature”

#list_design_systems

Browse available design systems for tokens. Filter by category (fintech, productivity, developer, component-library, design-system) or search by name.

Parameters

categoryoptional

Filter by category: fintech, productivity, developer, component-library, design-system

searchoptional

Search by name or description

#get_design_system

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.

Parameters

idrequired

Design system ID (e.g. ’stripe’, ’linear’)

groupoptional

Filter to a token group: color, color-dark, color-light, typography, spacing, radius, elevation, motion

formatoptional

Output format: dtcg (W3C standard), css (custom properties), flat (key-value). Default: dtcg

#generate_design_system

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.

Parameters

namerequired

Name for the design system (e.g. ’Acme Corp’, ’NightOwl’)

base_systemoptional

Start from an existing system as foundation (e.g. ’stripe’, ’linear’). Colors will be replaced by brand_color if provided.

brand_coloroptional

Primary brand hex color (e.g. ’#FF6B35’). Auto-generates a full harmonious palette using color theory.

styleoptional

Aesthetic direction — influences spacing, radii, shadows, motion, and typography. Default: minimal — “minimal” | “bold” | “warm” | “corporate” | “playful” | “dark”

dark_modeoptional

Generate dark mode tokens alongside light. Default: true

formatoptional

Export format: html (visual doc page), css (custom properties), dtcg (W3C JSON), figma (Figma Variables JSON), svg (color palette card), all. Default: html

#compose_system

Mix tokens from different design systems to create a custom composite. Example: Linear’s colors + Stripe’s typography.

Parameters

compositionsrequired

Array of system-group pairs to compose

formatoptional

Output format. Default: dtcg — “dtcg” | “css”

#configure_design_system_source

Save which local DESIGN.md file Raven should use for design-system inventory and comparison.

Parameters

project_dirrequired

Project directory where .raven configuration is stored

source_kindrequired

MVP source kind; only design-file is supported

design_file_pathoptional

DESIGN.md path relative to the project directory; defaults to DESIGN.md

platformoptional

Target platform: web-pointer, web-touch, ios, or android — “web-pointer” | “web-touch” | “ios” | “android”

aliasesoptional

Project component id to Raven canonical component id aliases

#inventory_design_system

Read component declarations and tokens from a local DESIGN.md file.

Parameters

project_diroptional

Project directory with a configured design-system source

design_file_pathoptional

Direct path to DESIGN.md; overrides project configuration

#list_design_system_components

List the components and provenance in the Raven canonical baseline.

Parameters

baselineoptional

Baseline id; defaults to raven-canonical

#diff_design_system

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.

Parameters

project_diroptional

Project directory with a configured design-system source

design_file_pathoptional

Direct path to DESIGN.md; overrides project configuration

baselineoptional

Baseline id; defaults to raven-canonical

platformoptional

Target platform; overrides project configuration — “web-pointer” | “web-touch” | “ios” | “android”

#list_content_systems

Browse available content design systems — brand voice and tone guides from real companies (Mailchimp, GOV.UK, Shopify Polaris, Atlassian). Filter by category or search by name.

Parameters

categoryoptional

Filter by category: marketing-saas, government, commerce-saas, productivity-saas, fintech

searchoptional

Search by name, description, or tag

#get_content_system

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.

Parameters

idrequired

Content system ID (e.g. ’mailchimp’, ’gov-uk’, ’shopify-polaris’, ’atlassian’)

sectionoptional

Return just one section. Default: all. — “all” | “voice” | “tone_shifts” | “vocabulary” | “grammar” | “content-patterns” | “inclusive-language”

#get_content_principles

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’).

Parameters

contextoptional

What you’re writing for (e.g. ’error messages’, ’onboarding copy’, ’empty state’, ’notification’). Omit to get all UX-writing principles.

formatoptional

Output format: full (all details), checklist (implications + violations), brief (just summary). Default: full

#get_content_pattern

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.

Parameters

typerequired

Content pattern type — “error-messages” | “empty-state-copy” | “notifications” | “form-validation”

#audit_content

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.

Parameters

itemsrequired

Array of content items to audit.

systemoptional

Optional content-system id (e.g. ’ux-writing’); recorded for traceability.

goalsoptional

Optional content goals (e.g. [’clarity’,’conversion’]); recorded for traceability.

#get_research_method

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.

Parameters

categoryoptional

Which family of methods. Default: all. — “qualitative” | “quantitative” | “usability” | “all”

searchoptional

Search within methods by name or description.

#get_metrics_framework

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?’

Parameters

idoptional

Framework id (heart, aarrr, north-star-metric, conversion-funnel, rice-scoring, okrs). Omit to list all.

searchoptional

Search for a framework by name or summary.

#get_service_pattern

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.

Parameters

typerequired

Service design pattern type — “service-blueprinting” | “human-handoff” | “signup-as-service” | “omnichannel-continuity” | “moments-of-truth”

#get_service_standard

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.

No parameters

#generate_service_blueprint

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.

Parameters

service_namerequired

Name of the service (e.g. ’Free trial signup’, ’Client intake’, ’Restaurant reservation’)

subtitleoptional

Short description or context line under the title

actorsoptional

Omit for classic single-actor Shostack blueprint. Provide to render a two-swim-lane HI-loop blueprint with a line of interaction between the two sides.

currentrequired

The current-state blueprint as an array of steps

idealoptional

Optional ideal-state blueprint — if provided, output shows current AND ideal side-by-side

#get_brand_system

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.

Parameters

companyrequired

The company whose branding to use (e.g. ’Spotify’, ’Stripe’, ’Apple’, ’Linear’, ’Airbnb’)

formatoptional

Output format: ’css’ for CSS variables, ’dtcg’ for W3C tokens, ’guide’ for full implementation guide. Default: guide

modeoptional

Color mode preference. Default: based on the system’s primary mode — “light” | “dark”

#get_brand_principles

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.

Parameters

topicoptional

Filter by topic: ’logo’, ’gradient’, ’imagery’, ’hierarchy’, ’system’, or a freeform search term. Omit to return all brand principles.

formatoptional

Output format. Default: full. — “full” | “checklist” | “brief”

#get_brand_trends

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.

No parameters

#audit_swiftui

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.

Parameters

sourcerequired

SwiftUI source — a single file/view as a string, or an array of file contents. Concatenated before analysis.

accent_color_contentsoptional

Optional raw Contents.json of AccentColor.colorset. When provided, the tool verifies AccentColor actually defines color components (flags an empty/undefined accent color as an error).

strictoptional

Strict mode — also count warnings as failures for grading. Default: false

projectoptional

Project identifier — resolves a saved taste surface binding (see bind_taste_surface). When the binding carries design_notes, each note is verified against the source (animation/material/haptic/font APIs) and returned in note_assessments; missing notes count toward the grade.

profileoptional

Taste profile owning the binding. Omit to search all stored profiles for one bound to the project.

#audit_rn

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.)

Parameters

sourcerequired

React Native source — a single screen/component as a string, or an array of file contents. Concatenated before analysis.

color_schemeoptional

The app’s declared appearance (Expo app.json userInterfaceStyle). ’light’ or ’dark’ means single-mode by design — the dark-mode adaptation check is then suppressed. Default: automatic.

strictoptional

Strict mode — also count warnings as failures for grading. Default: false

projectoptional

Project identifier — resolves a saved taste surface binding (see bind_taste_surface). When the binding carries design_notes, each note is verified against the source (Animated/Reanimated, BlurView, haptics, fonts) and returned in note_assessments; missing notes count toward the grade.

profileoptional

Taste profile owning the binding. Omit to search all stored profiles for one bound to the project.

#audit_ios_screen

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.

Parameters

projectoptional

Project identifier — resolves a saved taste surface binding (see bind_taste_surface). When the binding carries design_notes and a screenshot is passed, the screenshot’s pixels verify the color-scheme notes; results gain note_assessments.

profileoptional

Taste profile owning the binding. Omit to search all stored profiles for one bound to the project.

elementsoptional

Elements captured from the rendered screen via an accessibility/view-hierarchy snapshot

viewportoptional

Screen size in pt (iOS) or dp (Android) at capture time, e.g. {w:393,h:852} iPhone 15, {w:412,h:915} Pixel

screenshotoptional

Optional base64 PNG of the screen, for the caller’s reference. Geometry is scored from the snapshot, not decoded pixels.

#audit_ios_privacy

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.

Parameters

info_plistoptional

Raw Info.plist XML (native iOS / bare RN). Provide this OR app_json.

app_jsonoptional

Expo app.json / app.config JSON (managed RN). Its expo.ios.infoPlist, expo.android.permissions, plugins, and extra are audited.

privacy_mdoptional

Optional PRIVACY.md / privacy policy text to cross-reference against declared permissions and default behavior

entitlementsoptional

Optional .entitlements XML

sourceoptional

Optional concatenated source (Swift or JS/TS) — enables code-vs-declaration contradiction checks and default-egress detection

#audit_ios_a11y

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.

Parameters

elementsrequired

array

viewportrequired

object

optionsoptional

object

#audit_screen

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.

Parameters

platformoptional

Target platform — ’ios’ (default, 44pt minimum, iOS semantic colors) or ’android’ (48dp minimum, Material semantic roles)

scroll_settleoptional

boolean

projectoptional

Project identifier — resolves a saved taste surface binding (see bind_taste_surface). When the binding carries design_notes and a screenshot is passed, the screenshot’s pixels verify the color-scheme notes; results gain note_assessments.

profileoptional

Taste profile owning the binding. Omit to search all stored profiles for one bound to the project.

elementsoptional

Elements captured from the rendered screen via an accessibility/view-hierarchy snapshot

viewportoptional

Screen size in pt (iOS) or dp (Android) at capture time, e.g. {w:393,h:852} iPhone 15, {w:412,h:915} Pixel

screenshotoptional

Optional base64 PNG of the screen, for the caller’s reference. Geometry is scored from the snapshot, not decoded pixels.

#audit_device_frame

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.

Parameters

framesoptional

Device-frame geometry samples (from the DevTools snippet): container box + intrinsic media size + computed object-fit/position. Flags object-fit:cover crop loss.

clipsoptional

Per-clip first/last frame PNG file paths — detects baked-in pan/zoom (Ken Burns).

edge_framesoptional

Frame PNG file paths to check for content truncated at a frame edge (reuses edge-symmetry).

#audit_parity

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[].

Parameters

iosrequired

object

androidrequired

object

checklistrequired

array

#audit_video_playback

Render a page in headless Chromium and observe whether each <video> 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.

Parameters

urloptional

URL to render and observe (http/https or file://). Requires headless chromium.

dom_snapshotoptional

Pre-collected video observations to classify without rendering (deterministic path)

observeMsoptional

Milliseconds to wait between currentTime samples after play() attempt. Default: 1000

#audit

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.

Parameters

urloptional

Web page or video URL.

htmloptional

Static web HTML.

nodesoptional

Pre-collected snapshot data for the applicable audits.

sourceoptional

iOS/SwiftUI or React Native source.

screenshotoptional

Screenshot input for native/device audits.

diffoptional

Unified diff or patch.

surfaceoptional

Surface override; otherwise detected from the supplied target. — “web” | “ios” | “react-native” | “diff” | “video”

intentoptional

Optional focus such as accessibility, contrast, content, copy, or pre-ship.

projectoptional

Project identifier for taste binding and project-aware audits.

profileoptional

Taste profile id for audit_taste.

#audit_page

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.

Parameters

htmloptional

The full HTML content of the page to audit

urloptional

If set, Raven launches headless chromium, renders the page, and audits the RENDERED DOM.

scroll_settleoptional

Before capturing, scroll to bottom and settle IntersectionObserver/whileInView reveals (300ms), and play preload=none videos. Prevents blank-section false positives.

interactionsoptional

Before capturing, fire each interaction in order (hover/click/focus the selector, then wait delay_ms). Captures the resulting dynamic state — e.g. an on-hover theme-toggle wash invisible to a static screenshot.

viewportoptional

object

strictoptional

Strict mode — also flags warnings as failures. Default: false

containerMaxWidthoptional

Your design system’s canonical content-container width in px (e.g. 1152). When set, the responsive/max-width check flags divergence from this token instead of using the generic 1200px heuristic.

adversarial_verifyoptional

After generating findings, independently re-check each against the live DOM/network and tag it confirmed / likely-artifact / inconclusive. Surfaces a debunked_count.

compactoptional

Return only the decision-grade signal — score, grade, summary, errors, warnings, fix_priority — and drop the embedded base64 screenshot and the passes list (replaced by passes_count). Default false. Use when the full payload would blow the tool-result budget.

#audit_url

Layer 0 render-and-capture audit: renders a LIVE URL at each viewport×theme, scroll-settles (fires whileInView/IntersectionObserver reveals; plays preload=none videos), fires hover/click/focus 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.

Parameters

urlrequired

URL to render and audit (http/https or file://)

viewportsoptional

Viewports to render. Default: iphone 393×852, desktop 1440×900, wide 2160×1200

themesoptional

Themes to toggle (prefers-color-scheme + data-theme/class). Default: [’light’,’dark’]

scroll_settleoptional

Scroll to bottom to fire reveal-on-scroll/IntersectionObserver content and play videos before capture. Default: true

interactionsoptional

Fire each interaction before capture; the resulting state is diffed against baseline to catch hover/click white-wash and obscured content.

containerMaxWidthoptional

Your design system’s canonical container width in px — makes the max-width check token-aware.

includeScreenshotsoptional

Include the base64 full-page PNG per capture in the result. Default: false (screenshots are large).

timeoutMsoptional

Per-navigation timeout in ms. Default: 30000

compactoptional

Drop per-capture base64 screenshots; keep findings, counts, and summary. Default false. Use when screenshots would blow the tool-result budget.

#score_page

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. 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.

Parameters

htmlrequired

The full HTML content of the page to score.

strictoptional

Strict mode — count warnings as failures in the overall score. Default: false.

containerMaxWidthoptional

Your design system’s canonical content-container width in px (e.g. 1152). Forwarded to the responsive/max-width check.

#audit_layout

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.

Parameters

elementsoptional

Array of element rects captured from the rendered page via the DevTools snippet

viewportoptional

Viewport dimensions {w,h} at capture time

#audit_typography

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.

Parameters

urloptional

URL to render and measure (http/https or file://). Requires headless chromium.

nodesoptional

Pre-collected text nodes to analyze without rendering.

#audit_tap_targets

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).

Parameters

urloptional

URL to render and measure. Requires headless chromium.

elementsoptional

Pre-collected interactive elements to score without rendering.

minSizeoptional

Minimum tap-target size in px on each axis. Default 44.

#audit_contrast

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 per element and surfaces failing pairs with selector, ratio, and delta-to-pass — replacing manual eyedropper + ratio math.

Parameters

urloptional

URL to render and measure (http/https or file://)

dom_snapshotoptional

Pre-collected text elements to score without rendering

screenshotoptional

Optional base64 PNG for caller reference; ratios are computed from the DOM, not pixels

#suggest_contrast_fix

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.

Parameters

pairsoptional

Color pairs to remediate. Each: { selector?, fg, bg, fontPx?, bold?, targetRatio? }. fontPx/bold pick the large-text threshold; targetRatio overrides the level.

leveloptional

WCAG level when targetRatio is not given per-pair. Default AA. — “AA” | “AAA”

#audit_responsive_visibility

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.

Parameters

urlrequired

URL to render (http/https or file://)

breakpointsoptional

Viewport widths in px. Default [390, 768, 1440, 2160]

viewportHeightoptional

Render height in px. Default 900

#audit_consistency

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.

Parameters

pagesrequired

At least 2 pages to compare. Each entry is {name, html}.

container_tokenoptional

Project’s canonical container width in px (e.g. 1152). When supplied, container divergence is measured against this token rather than the corpus modal.

hero_tokenoptional

Canonical hero heading class signature (e.g. "text-display-xl" or "64"). When supplied, hero divergence is measured against this token rather than the corpus modal.

#audit_asset_integrity

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.

Parameters

image_pathsrequired

Filesystem paths to PNG files to check for sliced/cut-off bottom content.

#audit_contract

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.

Parameters

contract_specrequired

object

file_pathsrequired

array

#audit_api_contract

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.

Parameters

endpoint_urlrequired

string

queriesrequired

array

expected_shape_schemarequired

object

#review_diff

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.

Parameters

diffrequired

Unified diff to review (maximum 400KB).

projectoptional

Project directory used to resolve DESIGN.md and match decision scopes. Omit when design_md is supplied and no project hint is needed.

design_mdoptional

Inline DESIGN.md content. Overrides project file lookup when supplied.

fail_onoptional

Rule names to escalate to a failing CI verdict. Valid values: important, bare-hex-color, hardcoded-font-size, hardcoded-font-family, hardcoded-spacing. Diff-scoped: only newly added lines can fail. Default: advisory-only (verdict caps at warn).

fail_on_governedoptional

When true, findings a recorded decision governs become fail-eligible (severity error → verdict fail). Governance is a lexical scope+category association, NOT a verified contradiction of the decision — opt in as a team strict-mode signal, not a turnkey safe blocker. Combines with fail_on. Default: advisory-only.

#polish_diff

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.

Parameters

diffrequired

Unified diff to review and polish (maximum 400KB).

projectoptional

Project directory used to resolve DESIGN.md and match decision scopes. Omit when design_md is supplied and no project hint is needed.

design_mdoptional

Inline DESIGN.md content. Overrides project file lookup when supplied.

#search_knowledge

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.

Parameters

queryrequired

Search term (e.g. ’touch targets’, ’pricing psychology’, ’color contrast’)

layeroptional

Which layer to search: principles, patterns, business, or all (default)

#create_taste_profile

Create (or overwrite) a named taste profile — a portable design-judgment ruleset + precedent corpus persisted locally under ~/.raven/taste/<name>.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:<tool>)’ delegates a rule to an existing Raven audit tool; ’(scope:<surface>)’ 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.

Parameters

namerequired

Profile name (becomes <name>.json; lowercase alnum/dash/underscore).

rulesoptional

Explicit rule objects.

corpusoptional

Seed precedent records.

markdownoptional

DESIGN.md-style markdown to ingest as rules.

#get_taste_profile

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.

Parameters

namerequired

Profile name.

#get_taste_interview

START HERE on a NEW project: returns a deterministic calibration interview — built from the taste profile’s own voice/tone rules and 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 (three.js, GSAP, anime.js, framer-motion, lottie, GraphQL, vanilla) in plain outcome language so a non-technical person can choose by what users would see, and states the default build target for sites: a Next.js app, unless the user prefers otherwise — asking how the taste should show up on THIS surface (e.g. a monochrome portfolio wants the one-accent rule at full block; a product site doesn’t want monochrome suggestions at all, and may tolerate a warmer voice). 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 — skipping the rest is fine but leaves that item uncalibrated and silent in future audits. A ’references’ question invites example URLs/screenshots/files, each interviewed with follow-ups about what specifically draws the person (element + quality), folded into the matching design_notes and listed under design_notes.references. The interview closes with an open-ended ’special’ question (any texture, signature detail, motif, or easter egg nothing else asked about — stored as design_notes.special); once the person has other bound surfaces, it carries `suggestions` — the special touches they chose elsewhere — so the interview starts proposing their own style back. 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’.

Parameters

profilerequired

Taste profile name (see list_taste_profiles).

projectoptional

Project identifier the binding will be saved under, e.g. ’raven-mcp’ or ’portfolio’. Include it so the interview can show any existing binding.

modeoptional

’kickoff’ (default) calibrates a project with no binding yet. ’refine’ re-interviews an ALREADY-bound project after the user rejects generated/designed output — requires an existing binding (throws naming get_taste_interview kickoff otherwise) and asks what fell short, then per-dimension keep/tighten/replace, then voice, then an optional reject precedent.

#bind_taste_surface

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/<profile>.surfaces.json). 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:’<name>’ 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: binding a BRAND-NEW surface with no calibration content (no design_notes/voice_note/references/overrides) is REFUSED — that is the fingerprint of a skipped kickoff interview. 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.

Parameters

profilerequired

Taste profile name.

projectrequired

Project identifier, e.g. ’raven-mcp’, ’portfolio’.

surfacerequired

What this surface IS, in scope-matchable words: ’monochrome portfolio’, ’product-site’, ’developer docs’. Scoped rules activate when their scope tokens overlap this string.

hostsoptional

URL hostnames that identify this project (e.g. ravenmcp.ai) — matched in url-mode audits, subdomains included.

overridesoptional

Per-rule re-tuning for this surface (e.g. relax a voice rule to nit on a product site).

voice_noteoptional

Short tone guidance for this surface (e.g. ’Product register: benefits may be stated plainly; still no hype verbs’). Echoed as voice_note in audit results.

design_notesoptional

Per-dimension design preferences from the interview’s design:* questions — keys are short dimension names (typography, spacing, color, layout, motion, imagery, entrance, loading, navigation, aesthetic, libraries, special; trimmed + lowercased, must match ^[a-z][a-z0-9_-]{0,31}$ after normalization, no two keys may collide), values are the user’s non-empty answers. Echoed as design_notes in every audit so generation is shaped by them, and treated as ACCEPTANCE CRITERIA a build must visibly satisfy.

referencesoptional

First-class reference examples the person pointed to. Each url is captured live (traits stored on the binding), and design_notes are consistency-checked against them — contradictions come back as consistency_warnings.

uncalibrated_ackoptional

ESCAPE HATCH — leave unset in the normal flow. Binding a BRAND-NEW surface with no calibration content (no design_notes/voice_note/references/overrides) is REFUSED, because that is the fingerprint of a skipped kickoff interview. Only if the user was genuinely interviewed and chose to skip every optional dimension, set this to a one-line note affirming that (e.g. ’user interviewed 2026-07-04, declined all dimension calibration’). It is recorded on the binding so the deliberate skip is auditable. Never set it to work around asking the user.

#record_taste_decision

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.

Parameters

profilerequired

Taste profile name (see list_taste_profiles).

projectrequired

Project the decision was made on.

dimensionrequired

Short lowercase dimension name — a standard one (typography, spacing, color, layout, motion, imagery, entrance, loading, navigation, aesthetic, libraries) or a new category the standard set doesn’t cover (iconography, sound, naming, …). New categories become new interview questions.

decisionrequired

What was chosen, in the user’s words — e.g. ’amber-phosphor accent, period-accurate not decorative’.

rejectedoptional

Alternatives considered and passed over.

whyoptional

The stated reason, if the user gave one.

sourceoptional

How the decision was made — defaults to ’user-directed’. ’user-corrected’ (user overrode a generated choice) is the highest-signal record. — “user-directed” | “user-approved” | “user-corrected”

#list_taste_decisions

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.

Parameters

profilerequired

Taste profile name.

projectoptional

Only decisions made on this project.

dimensionoptional

Only decisions on this dimension.

#list_taste_profiles

List locally stored taste profiles with rule/corpus counts and last-updated timestamps.

No parameters

#generate_taste_portrait

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.

Parameters

profilerequired

Taste profile name.

projectoptional

Optional bound project name. Omit to render every surface binding in the profile plus a gallery index.

output_dirrequired

Directory where the generated HTML files should be written.

#audit_taste

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). 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-<key>, 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.

Parameters

profilerequired

Taste profile name (see list_taste_profiles).

htmloptional

Full HTML/CSS of the page to judge.

textoptional

A copy/text block to judge (voice/banned-word rules).

urloptional

Live URL — rendered headless with scroll-settle; enables delegated contrast/tap-target measurement.

surfaceoptional

What surface is being judged (e.g. ’portfolio’, ’product-site’, ’deck’) — activates/skips scope-tagged rules by token match. Omit if unsure: scoped rules then warn instead of block.

projectoptional

Project identifier — resolves a saved surface binding (see get_taste_interview / bind_taste_surface) that supplies the surface and per-rule overrides automatically. url-mode audits also resolve bindings by hostname.

document_kindoptional

’artifact’ (default): the target is a build OF the surface — design_notes bind it as acceptance criteria (note_assessments/fidelity_findings run). ’portrait’: the target is a document ABOUT the surface (e.g. generate_taste_portrait output) — note-fidelity is skipped and the result announces it in note_fidelity_skipped. Profile rules run in full either way.

#label_finding

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.

Parameters

profilerequired

Profile name.

artifactrequired

What was judged (path, URL, or short description).

verdictrequired

accept = the flagged pattern is fine (suppresses future matches); revise/reject = confirmed wrong.

violated_rulerequired

The rule_id the label concerns (’’ if none). Must exist in the profile.

severityoptional

Severity the human assigns. — “block” | “warn” | “nit”

wrongrequired

The wrong pattern — use a verbatim snippet so accept-suppression can match it.

rightrequired

What right looks like.

#decision_add

Add an active decision to the local Decision Graph.

Parameters

statementrequired

Decision statement.

rationaleoptional

Reason for the decision. Omit when no rationale was recorded.

scoperequired

Scope where the decision applies.

component_refrequired

Component or surface the decision refers to.

alternatives_rejectedoptional

Alternatives considered and rejected.

authoroptional

Agent or person authoring the decision. Defaults to RAVEN_AGENT_ID or unknown.

#decision_draft

Capture a decision from working context with the why deferred for later confirmation.

Parameters

statementrequired

Decision statement.

scoperequired

Scope where the decision applies.

component_refrequired

Component or surface the decision refers to.

alternatives_rejectedoptional

Alternatives considered and rejected.

#decision_commit

Commit or confirm the rationale for a draft or extracted decision.

Parameters

idrequired

Decision node id to commit.

rationalerequired

Confirmed rationale for the decision.

similarity_thresholdoptional

Similarity threshold from 0 to 1. Overrides RAVEN_DECISION_SIMILARITY_THRESHOLD for this commit.

#decision_evidence

Attach quantitative or qualitative evidence to an existing decision.

Parameters

decision_idrequired

Existing decision node id.

typerequired

Evidence type. — “quant” | “qual”

source_refrequired

URL, experiment name, ticket, or transcript reference.

result_summaryrequired

Concise summary of the evidence result.

confidencerequired

Confidence from 0 to 1.

confoundsoptional

Known factors that may confound the result.

#decision_get

Get a Decision Graph node and every node connected to it by an edge in either direction.

Parameters

idrequired

Decision Graph node id.

#decision_list

List decisions in the local Decision Graph. Defaults to active decisions.

Parameters

statusoptional

Decision status to list. Omit to list active decisions. — “candidate” | “active” | “superseded” | “contested”

include_candidatesoptional

When true and status is omitted, include uncommitted imported candidates with active decisions.

drafts_onlyoptional

When true, return active decisions awaiting a rationale or confirmation.

#decision_history

Return the complete supersession lineage for a decision, ordered oldest to newest.

Parameters

idrequired

Existing decision id anywhere in the supersession lineage.

#decision_supersede

Explicitly supersede one decision with another while preserving both nodes and their lineage.

Parameters

old_idrequired

Existing decision id that is being superseded.

new_idrequired

Existing replacement decision id.

#decision_scope

Narrow two decisions to distinct scopes so both can remain active alongside one another.

Parameters

id_arequired

First existing decision id.

id_brequired

Second existing decision id.

scope_arequired

Narrowed scope for the first decision.

scope_brequired

Narrowed scope for the second decision.

#gap_scan

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.

Parameters

use_casesoptional

Use-case descriptions whose component terms should be covered by active decisions.

reference_systemsoptional

Pattern or design-system ids from Raven’s existing registries. Omit for a small built-in pattern set.

digest_onlyoptional

Hands-off mode. When healthy, return only the quiet actionable:false digest.

#decision_import

Mine local git history and decision-bearing Markdown into provenance-tagged Decision Graph extraction prompts. Imported history remains review-only until decision_commit.

Parameters

repo_pathrequired

Local repository directory to inspect.

doc_globsoptional

Repository-relative Markdown globs. Supports * and **.

max_commitsoptional

Maximum git commits to inspect (cap 1000).

max_chunk_charsoptional

Maximum material characters per extraction chunk. Oversized single items are continuation-split (cap 60000).

#ingest_transcript

Store a transcript source and return an extraction prompt for the calling agent’s model. Raven makes no model or network call.

Parameters

textrequired

Transcript text to extract design decisions from.

source_metarequired

Metadata identifying the transcript source.

#ingest_transcript_results

Parse model-produced extraction JSON into reviewable Decision Graph candidates linked to their source. Nothing is auto-confirmed.

Parameters

source_idrequired

Existing transcript Source node id.

extraction_jsonrequired

Raw JSON returned by the calling agent’s model.

#read_design_md

Parse a DESIGN.md file and return its frontmatter, Markdown body, and flattened token index.

Parameters

pathrequired

Path to DESIGN.md

#init_design_md

Initialize a DESIGN.md file from a stored Raven token system, a getdesign.md starter slug, or a blank template.

Parameters

pathrequired

Path to DESIGN.md to create

fromoptional

Source selector: blank, stored system, or starter slug

#update_design_md

Update one DESIGN.md token surgically while preserving the Markdown body.

Parameters

pathrequired

Path to DESIGN.md

setoptional

object

renameoptional

object

removeoptional

object

#start_grab_session

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.

Parameters

pathrequired

Path to DESIGN.md to expose over /tokens

portoptional

Optional port; defaults to an ephemeral loopback port

proxy_targetoptional

URL of a running local dev server; the bridge will serve that app with the grab overlay auto-injected into every HTML page — user opens the bridge URL, zero setup

roleoptional

Overlay role; consumer preserves the component-request flow, maintainer enables direct design-system component creation

#get_grabbed_elements

Drain the current grab queue, optionally waiting up to timeout_ms for the next selection.

Parameters

timeout_msoptional

Optional wait timeout in milliseconds

#stop_grab_session

Stop the current grab bridge and clear its queued selections.

No parameters

#get_grab_layers

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.

Parameters

pageoptional

Optional page pathname; omit to list all latest page snapshots

#move_grab_layer

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.

Parameters

operationrequired

“reorder” | “reparent”

pagerequired

parentSelectoroptional

Required for reorder — single parent

fromParentSelectoroptional

Required for reparent — source parent

toParentSelectoroptional

Required for reparent — destination parent

fromIndexrequired

toIndexrequired

orderedSelectorsrequired

baselineOrderoptional

toBaselineOrderoptional

selectionOrderoptional

measuredRectsrequired

approximaterequired

domSnapshotHashrequired

toDomSnapshotHashoptional

fromSelectoroptional

roleoptional

Rejected: roles are never accepted from callers

#get_grab_operation

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.

Parameters

operation_idoptional

Operation ID; omit to list all operations

markoptional

Mark a previewed reorder or sent style change — “applied” | “rejected”

batchoptional

Return the unified current batch of reorder and style records; cannot be combined with operation_id or mark

#get_page_template

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.

Parameters

pagerequired

Page pathname, matching location.pathname

#set_template_slot

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.

Parameters

pagerequired

Page pathname, matching location.pathname

template_idoptional

Template identifier; defaults to default

slotsrequired

All template slots to persist in this batched call

#list_templates

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.

No parameters

#list_creative_models

Browse Raven’s provider-agnostic creative model catalog. These are capability slots for image, video, 3D, audio, character consistency, and creative analysis. Use a configured RAVEN_CREATIVE_RUNNER to route jobs to any local CLI or API wrapper.

Parameters

media_typeoptional

Filter by media type. — “image” | “video” | “audio” | “3d” | “campaign” | “analysis”

capabilityoptional

Filter by capability, e.g. product-photoshoot, text-to-video, brand-kit, ugc-ad.

#list_creative_presets

Browse Raven creative presets for product photoshoots, marketplace cards, UGC ads, TV spots, cinematic reveals, social launch packs, storyboards, and infographics.

Parameters

media_typeoptional

Filter presets by media type. — “image” | “video” | “campaign”

searchoptional

Search preset name or description.

#create_brand_profile

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.

Parameters

namerequired

Brand or project name.

idoptional

Optional stable ID. If omitted, Raven creates one from the name.

descriptionoptional

What the brand/product is.

colorsoptional

Brand colors, preferably hex or token names.

fontsoptional

Brand fonts or type guidance.

toneoptional

Voice and tone guidance.

audienceoptional

Primary audience/customer.

productoptional

Product or offer notes.

constraintsoptional

Rules to honor: no claims, legal notes, visual constraints.

asset_idsoptional

Existing Raven creative asset IDs tied to this brand.

#get_brand_profile

Read a local Raven creative brand profile by ID.

Parameters

idrequired

Brand profile ID.

#list_brand_profiles

List local Raven creative brand profiles.

No parameters

#register_creative_asset

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.

Parameters

urirequired

Local path or URL to the asset.

typerequired

Asset type. — “image” | “video” | “audio” | “document” | “3d” | “url” | “other”

nameoptional

Human-readable name.

descriptionoptional

What this asset should be used for.

tagsoptional

Search tags.

metadataoptional

Optional non-secret metadata.

#create_character_profile

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.

Parameters

namerequired

Character, spokesperson, founder, avatar, or product persona name.

reference_asset_idsrequired

Raven creative asset IDs for reference images/videos.

idoptional

Optional stable ID.

descriptionoptional

Visual/personality description.

consistency_notesoptional

What must stay consistent across generations.

provider_training_idoptional

External provider training/character ID if already trained.

metadataoptional

Optional non-secret metadata.

#create_generation_job

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.

Parameters

media_typerequired

Output type. — “image” | “video” | “audio” | “3d” | “campaign” | “analysis”

promptrequired

Creative request.

objectiveoptional

Business or audience goal.

modeloptional

Raven model slot or external provider model ID.

provideroptional

Provider label for the downstream runner.

presetoptional

Preset ID from list_creative_presets.

brand_profile_idoptional

Local Raven brand profile ID.

character_profile_idoptional

Local Raven character profile ID.

reference_asset_idsoptional

Local Raven creative asset IDs.

aspect_ratiooptional

Target aspect ratio, e.g. 1:1, 16:9, 9:16.

duration_secondsoptional

Video/audio duration.

output_countoptional

Number of variants to request.

qualityoptional

Requested quality tier. — “draft” | “standard” | “high” | “4k”

channeloptional

Target channel, e.g. TikTok, YouTube Shorts, blog, marketplace.

executeoptional

Submit through RAVEN_CREATIVE_RUNNER now. Default false.

#get_generation_job

Read a Raven creative generation job by ID.

Parameters

idrequired

Generation job ID.

#list_generation_jobs

List local Raven creative generation jobs.

Parameters

statusoptional

Filter by status: draft, needs_runner, submitted, completed, failed.

media_typeoptional

Filter by media type. — “image” | “video” | “audio” | “3d” | “campaign” | “analysis”

limitoptional

Max jobs to return. Default 25.

#plan_creative_campaign

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.

Parameters

campaign_namerequired

Campaign name.

product_or_offerrequired

Product, service, feature, or offer.

audiencerequired

Target audience.

goalrequired

Primary campaign goal. — “awareness” | “conversion” | “retention” | “launch” | “research” | “sales”

channelsrequired

Target channels: TikTok, Reels, YouTube Shorts, web, marketplace, LinkedIn, etc.

brand_profile_idoptional

Local Raven brand profile ID.

source_asset_idsoptional

Raven creative asset IDs to use as source/reference.

formatsoptional

Preset IDs to force. Defaults inferred from channels.

variants_per_formatoptional

How many draft job variants per format. Default 2.

create_jobsoptional

Create draft generation jobs. Default true.

#score_creative

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.

Parameters

creative_textrequired

Prompt, script, ad copy, or creative concept to score.

channeloptional

Target channel.

brand_profile_idoptional

Local Raven brand profile ID.

audienceoptional

Target audience if not in a brand profile.

#talon_scan

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.

Parameters

htmloptional

Full HTML/CSS of the page to scan.

urloptional

Live URL — rendered headless with scroll-settle.

elementsoptional

Pre-measured element rects (DevTools-snippet shape from audit_layout) — enables the geometry rules (orphan-stretch, horizontal-overflow).

viewportoptional

Viewport used for the horizontal-overflow geometry check.

surfaceoptional

What surface is being scanned — activates/skips scope-tagged rules by token match. Omit if unsure.

projectoptional

Project identifier — resolves a saved surface binding (see bind_taste_surface) whose overrides can waive specific TAL-### rules. Requires profile.

profileoptional

Taste profile name to resolve project’s binding against (see list_taste_profiles). Only used when project or url is also given.

#talon_rules

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.

No parameters

#raven_reflect

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.

Parameters

daysoptional

How many days back to include. Default: 30.

#raven_register

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.

Parameters

emailrequired

User’s email address

nameoptional

User’s name (optional)