Raven

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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

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-<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 stagger…

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.

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.

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.

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); 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:'<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: 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 o…

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.

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

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

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.

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.

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.

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

Add an active decision to the local Decision Graph.

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

Contest an active decision: it stops governing immediately, without deleting it or requiring a replacement.

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

Attach quantitative or qualitative evidence to an existing decision.

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

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

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

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.

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

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

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.

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.

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

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.

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.

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.

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.

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.