Skip to main contentSkip to footer
For agents · Pro / Teams

The Design Agent

Call design.validate to get a Blueprint Readiness Score (0–100, grade A–F) on a real frontend artefact. The Design Agent reviews your component, screen, or flow against the 8 laws of the Experience Design Blueprint, returns a per-law verdict with cited evidence and a fix, and grades it on the same severity-weighted scorer architect.validate uses. Pro and Teams plans only.

Pro and Teams members. The Design Agent is the Blueprint's surface-craft review lens. It reads the full artefact source verbatim under a strict no-training policy, treats any instruction-shaped text inside the markup as inert untrusted data, and supports private_session=true to skip the stored run (operational security and cost logs are kept per the Privacy Policy). Non-visual code (backend, config, type aliases) is marked not_applicable, not failed. Submit the actual UI surface.

What you get back

Every run returns four things, in the same ValidationResponse shape architect.validate uses:

  1. surface_classification

    ui_surface or non_ui, non-visual code is marked not_applicable rather than failed, so submitting a backend handler never produces a fake design grade.

  2. per-law findings

    A verdict for each of the eight laws with severity_score (0–100), severity_class, evidence cited from your actual markup, and one specific recommendation.

  3. readiness

    Score, grade, and tier from the same severity-weighted scorer the architecture lens uses. The grade penalises only production_blocker findings, so a high grade means the experience floors hold, not that every pixel is perfect.

  4. surface dimension

    Runs persist to your validation-history dashboard tagged as the surface dimension, next to your architecture runs on the same project when you pass a repository.

The eight laws it scores against

The rubric is the Experience Design Blueprint: eight laws of perceptible craft, each scored with the same verdict vocabulary the architecture lens uses.

  • L1 · Jakob's Law

    Honour familiarity before invention: does the surface meet the model users bring from category-leading products?

  • L2 · Hick's Law

    Reduce choice at every decision point: one clear primary action per screen.

  • L3 · Fitts's Law + the accessibility floor

    Make targets easy to acquire: every interactive target clears WCAG 2.2's 24×24 minimum. A breach here is a production_blocker.

  • L4 · Miller's Law

    Respect the limits of working memory: how many chunks must the user hold at one decision moment?

  • L5 · Aesthetic-Usability Effect

    Make it beautiful so it feels easy: the polish bar holds across empty, loading, and error states, not just the happy path.

  • L6 · Peak-End Rule

    Engineer the peak and the ending: is the completion moment designed, or does a polished flow end on a bare 'Submitted.'?

  • L7 · Tesler's Law

    Place complexity where it belongs: the system absorbs irreducible complexity with a simple default and stays inspectable.

  • L8 · Mental-Model Gap

    Align the surface with the user's mental model: for agent-mediated surfaces, intent is previewable and every expectation-deviation is named in advance.

Accessibility is the floor

When two laws conflict, the order is fixed: accessibility first, aesthetic polish last. The validator does not average a floor breach into a friendly number. An interactive target under 24×24px, a missing focus state, or a destructive confirmation the user cannot reach is a production_blocker that caps the grade, exactly as a failed trust boundary does on the architecture lens. Polish is the most negotiable law. The floor is not negotiable at all.

How to call it

Send the full artefact source verbatim as implementation_context, the JSX, the markup, the styles, no truncation and no placeholder ellipses (they are read as literal code). If a surface is too large for your MCP client's tool-call budget, split into multiple calls scoped by component. Pass the same repository value across calls to group rounds under the surface dimension of one project. design.validate is sync-only. If the call times out client-side, do not retry, the run persists server-side; recover it via me.validation_history(run_id=...) using the run_id from the first progress event.

Sample

Sample surface review

What you see after every design.validate run on a UI surface. One frontend artefact, eight laws, one readiness grade.

Blueprint Readiness Score

acme/checkout-ui

C
68/ 100emerging5 of 8 laws aligned

Production blocker

L3 · Make targets easy to acquire

The inline “Remove item” control renders at 16×16 CSS px, below the WCAG 2.2 24×24 minimum target size. Severity 85, confidence high.

Enlarge the control to at least 24×24 (44×44 for a primary action) or expand its hit area with padding.

The grade is capped by the accessibility floor: fix the L3 target-size breach before polish work. Re-run with the same repository value to chain the round under the surface dimension.

This is a sample. Real surface reviews are generated by design.validate and visible to you in /app/readiness-review/history (Pro/Teams), tagged as the surface dimension.

Grading agent code or a written spec instead of a UI surface? The other two seats of the trio run the same validator against their own doctrine.

How the grade is computed

Same scorer as the architecture lens

Each law receives a verdict and a severity_score; credit per finding is severity-weighted and the score is normalised over the applicable laws. production_blocker findings cap the grade; hardening_recommended and polish surface as next-iteration work without sinking the score.

A90+
B80–89
C65–79
D50–64
F<50

What is design.validate, and how is it different from architect.validate?

They are the same validator with the doctrine swapped. architect.validate scores agentic architecture, what the code does, against the 10 agentic principles. design.validate scores the perceptible surface, what the user sees, taps, scans, and remembers, against the 8 laws of the Experience Design Blueprint. Same first-pass pipeline, same ValidationResponse shape, same severity-weighted scorer, so a Blueprint Readiness Score is computed the same way on both. Runs share one validation-history dashboard: architecture runs are tagged architecture, surface runs are tagged surface. Pass the same repository and you get one project graded across three lenses: the spec (what to build), the machine behind the glass (architecture), and the interface in front of it (surface).

What plan do I need, and does it share a quota with architect.validate?

A Pro or Teams plan. design.validate has its own weekly run allocation, metered separately from the architecture bucket, so a heavy week of code review never eats your surface reviews and vice versa. Free and Basic accounts can read every doctrine principle, cluster, and example via the public MCP at no charge; the Design Agent is reserved for paid plans because it processes a real artefact under a no-training policy and persists per-project history. Current per-tier numbers are on the pricing page.

“Accessibility is the floor.” What does that mean for my grade?

The eight laws are not weighted equally. On conflict, accessibility comes first and aesthetic polish comes last. In practice: a breach of the Fitts's-Law floor, an interactive target below the WCAG 2.2 24×24px minimum, a missing focus state, or a destructive confirmation the user cannot reach, is scored as a production_blocker. It caps the grade and must be fixed before you ship, the same way a failed trust boundary caps the architecture grade. A soft peak-end moment or a thin empty state is hardening_recommended or polish: it surfaces in a next-iteration list without dragging the score down. A high grade means the experience floors hold, not that the design won an award.

Is the surface grade a certified verdict?

Not yet, and the tool says so on every run. design.validate v1 is a single-pass review at high reasoning effort. It has no consensus mode and no certification path, those stay architect.validate-only for now, and its score calibration is not yet tuned against a corpus of real runs the way the architect's was. Treat the grade as a directional craft signal, not a certified badge. The one part that is hard, not directional, is the accessibility floor: a production_blocker on a WCAG target-size or focus-visibility breach is a checkable fact, not a matter of taste.

What should I send, and what comes back marked not_applicable?

Send the full artefact source verbatim as implementation_context, the JSX, the markup, the styles, no truncation and no placeholders (they are read as literal code, and the reviewer will cite elements that are not there). If a surface is too large for your MCP client's tool-call budget, split into multiple calls scoped by component, never truncate one call. Non-visual code (a backend handler, a config file, a type alias) returns surface_classification: non_ui and tier: not_applicable, it is not failed, it is just not a surface. Submit the actual UI.

Is my artefact stored when I call design.validate?

Your artefact source is sent to OpenAI (US) to generate the review, as a sub-processor under the EU Standard Contractual Clauses and UK Addendum, on a no-training basis, retained under OpenAI's API data-retention terms. AI Design Blueprint stores the structured result (score and per-law verdicts) plus, when you pass repository, a project identifier for grouping. Pass private_session=true to skip server-side run persistence; operational cost and audit records (never your artefact source) are still kept. Any instruction-shaped text inside your markup is treated as inert untrusted data, not as instructions to follow. Compute runs on Google Cloud Run; data at rest is in Cloud SQL, kept in the UK/EEA (Google Cloud europe-west2, London). Full detail on the trust and data handling page.