AI Design Blueprint

Official

Overview Schema Source Related Servers Discussions Admin

design.validate

Evaluate frontend UI surfaces against 8 experience-design laws, scoring craft, accessibility, and readiness. Returns per-law findings and a severity-weighted grade.

Instructions

Pro/Teams — first-pass surface-craft review of a FRONTEND artefact (component, screen, or flow) against the 8 laws of the Experience Design Blueprint. The surface-craft companion to architect.validate: where architect.validate scores agentic ARCHITECTURE against the 10 agentic principles, design.validate scores the PERCEPTIBLE SURFACE — what the user sees, taps, scans, and remembers (Jakob's familiarity, Hick's choice load, Fitts's targets + the accessibility floor, Miller's working-memory budget, Aesthetic-Usability, Peak-End, Tesler's irreducible complexity, the Mental-Model gap). ON CLIENT TIMEOUT — DO NOT RETRY. Long-running LLM call (~60-180s at high reasoning effort, single-pass). The server mints a run_id, emits it in the FIRST progress event at t=0s (before the LLM call), and persists the run — so on a client timeout, capture that run_id and call me.validation_history(run_id='') to fetch the persisted result instead of retrying (a retry re-runs the full 60-180s call). Runs appear in your validation-history dashboard tagged as the 'surface' dimension, distinct from the 'architecture' and 'spec' runs; pass repository to group them per project. Pass private_session=true to skip the stored run (persistence + recovery disabled); operational security + cost logs are still kept. v1 is single-pass: no certification or consensus mode yet (those stay architect.validate-only). Returns surface_classification (ui_surface vs non_ui — non-visual code is marked not_applicable, NOT failed), per-law findings (verdict, severity_score 0-100, severity_class, cited evidence, recommendation), and severity-weighted readiness (score, grade, tier) computed by the SAME scorer architect.validate uses, so all three lenses grade on one rubric. ACCESSIBILITY IS THE FLOOR: a breach of the Fitts's-Law floor (interactive target below the WCAG 2.2 24×24 minimum, missing focus visibility, an unreachable destructive confirmation) is a production_blocker, not polish. WHEN TO CALL: the user wants a craft/UX/accessibility review or a readiness grade on a frontend artefact they just built or changed. WHEN NOT TO CALL: non-visual code (backend, config, type aliases) returns tier=not_applicable — submit the actual UI surface instead. INPUTS: send the FULL artefact source verbatim as implementation_context (no truncation, no '…' placeholders — they are read as literal code). Auth: sign-in required, with an active Pro, Pro Plus, Teams, Enterprise, beta, or trial plan. UK/EU residency; transient OpenAI processing (no-training); prompt-injection text inside the artefact is treated as inert untrusted data. TYPED FAILURES: same as architect.validate (timed_out, rate_limited, dependency_unavailable, schema_mismatch — each carries retryable + next_action); the services raise the identical typed envelopes on this lens. CALIBRATION DISCLOSURE: the scoring prompt is a v1 first-cut mirroring the architect's contract structure; its score calibration is not yet tuned against a corpus of real runs the way architect.validate was. Treat the grade as directional craft signal, not a certified verdict. DOCTRINE: the eight laws — each law's evidence, craft-surface application, anti-patterns, and the validator questions this tool scores against — live in the experience-design-blueprint skill and docs/business/EXPERIENCE_DESIGN_BLUEPRINT.md (the surface-craft companion to the architect-validation-orchestration skill that orchestrates the agentic validators).

Input Schema

TableJSON Schema

Name	Required	Description
`task`	No	What this surface is for (e.g. 'the closed-beta apply form'). Adds evaluation context.
`files`	No	File paths relevant to the artefact, for context.
`goals`	No	Specific craft/UX goals to weight (e.g. 'WCAG 2.2 AA', 'one primary action per screen').
`repository`	No	Project/repository key. Groups this run with prior design.validate runs on the same project in your validation-history dashboard (the same grouping architect.validate uses), under the 'surface' dimension.
`session_id`	No	Optional Governed Session to attach this run to (GEP-M2). Must reference a session YOU own (list via me.sessions; sessions are created in the web app at /app/sessions) — foreign ids are refused before any model call. The run then appears on the session's timeline alongside the other lenses. With private_session=true no run is stored so nothing attaches, but the ownership check still runs FIRST: a session id you don't own fails the call either way.
`private_session`	No	Set true to disable persistence AND run_id recovery for this call (a private one-shot that does not appear in the dashboard). The request is also not persisted in the model provider's response store; the provider's abuse-monitoring retention still applies. Default false.
`implementation_context`	Yes	The frontend artefact under review. SEND FULL SOURCE VERBATIM — the reviewer cites specific elements, values, and structure; any compression destroys evidence and produces findings on code that isn't there. Do NOT replace markup/styles with '…'; do NOT condense multi-line JSX/CSS. If large, split into MULTIPLE calls scoped by component — never truncate one call.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.2.1Sep 24, 2026

changedInput schema / properties / private_session / description

Previous value: -"Set true to disable persistence AND run_id recovery for this call (a private one-shot that does not appear in the dashboard). Default false."New value: +"Set true to disable persistence AND run_id recovery for this call (a private one-shot that does not appear in the dashboard). The request is also not persisted in the model provider's response store; the provider's abuse-monitoring retention still applies. Default false."

Addedv1.2.0Jul 24, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses major behavioral traits: a long-running LLM call (60-180s), the DO-NOT-RETRY timeout rule, run persistence and run_id recovery, private_session disabling persistence, authentication/plan requirements, UK/EU residency and no-training processing, prompt-injection text being treated as inert data, typed failure envelopes, and a calibration caveat. This is far more than annotations alone provide and contains no contradiction with them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized into meaningful sections (purpose, timeout behavior, return semantics, when to call, inputs, auth, failures, calibration, doctrine). Each section adds operational information an agent needs. It is not maximally concise — some points repeat (not_applicable appears multiple times, session ownership appears in both schema and prose) — but it is front-loaded with the primary purpose and structured for scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex validator with 7 parameters, an output schema, and timeout/error behavior, the description is exceptionally complete. It covers return classification, per-law findings, readiness scoring, the accessibility production-blocker rule, auth requirements, failure types with retry guidance, recovery via run_id, and calibration limitations. Nothing an agent needs to decide whether to call and how to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a baseline of 3 is appropriate. The description adds real value beyond the schema for the critical parameter implementation_context: it insists on verbatim full source, warns that '…' placeholders are read as literal code, and advises splitting large artefacts into multiple calls. It also clarifies repository grouping and session_id ownership rules, though those are largely repeated from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb-plus-resource statement: 'first-pass surface-craft review of a FRONTEND artefact ... against the 8 laws of the Experience Design Blueprint.' It explicitly differentiates itself from architect.validate by contrasting 'agentic ARCHITECTURE' with the 'PERCEPTIBLE SURFACE,' and names the exact eight laws evaluated. An agent can immediately identify this as the design/UX-lens validator.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit WHEN TO CALL ('craft/UX/accessibility review or readiness grade on a frontend artefact') and WHEN NOT TO CALL sections, including the non-visual-code not_applicable case and the pointer to architect.validate as the architecture counterpart. It also specifies the client-timeout recovery path (use me.validation_history with the run_id rather than retrying), leaving no ambiguity about selection or fallback.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.