Skip to content

Your first Better Design win in 90 minutes

Connect Better Design, add DESIGN.md, review one interface, fix three findings, and record the result in 90 minutes.

The 90-minute path

  1. 0–10 min

    Connect Better Design

    Install the MCP for your coding agent and confirm that the Better Design tools are available.

    Open the install guide

  2. 10–30 min

    Create or import DESIGN.md

    Record the product goal, source files, approved tokens, shared components, accessibility floor, and review rules. Start from the template when the repository has no design contract.

    Download the DESIGN.md template

  3. 30–50 min

    Review one existing interface

    Choose one bounded screen or flow. Ask the agent to inspect the current system, load the relevant UI and UX principles, and return findings with rendered evidence where possible.

    Use the UI quality checklist

  4. 50–80 min

    Fix the three highest-impact findings

    Prioritize blockers to task completion, accessibility, hierarchy, and consistency. Keep the change small enough to verify in the same session.

    Follow the drift-control loop

  5. 80–90 min

    Show the improvement

    Capture the same state before and after, list the three changes, and record the checks that passed. Label illustrative examples, internal benchmarks, and verified customer results separately.

    Use the evidence record

Start with DESIGN.md

DESIGN.md gives the agent a small, versioned source of truth for the product. Import existing decisions before adding new ones. The template keeps unknown project details as visible placeholders.

Download DESIGN.md
Preview the template
# Product design contract

This file tells coding agents which design decisions govern this repository.
Replace every bracketed placeholder with verified project information. Delete
sections that do not apply.

## Product and users

- Product: [name and one-sentence purpose]
- Primary users: [specific users]
- Critical task: [the main job the interface must make easy]
- Supported surfaces: [web, iOS, Android, Shopify, or other]

## Sources of truth

- Design tokens: [path to globals.css, token JSON, or theme source]
- Components: [path to the shared component library]
- Design files: [verified Figma or other design-tool URL, or "none"]
- Product copy: [path or owner]
- Existing interface references: [routes, stories, or screenshots]

When sources disagree, use this order: [write the project-specific precedence].
Ask a person when the conflict changes product behavior or brand direction.

## Tokens and theming

- Use semantic tokens for color, type, spacing, radius, and depth.
- Do not add literal colors or one-off theme values when an approved token exists.
- Preserve [light, dark, high-contrast, or other verified themes].
- New tokens require [owner or review step].

## Components and patterns

- Reuse an existing component or variant before creating a new one.
- Approved component paths: [paths]
- Approved page and flow patterns: [paths or stories]
- Do not duplicate [known primitives or patterns].

## Accessibility floor

- Meet WCAG AA contrast for text and interface elements.
- Keep every task keyboard-operable with visible focus.
- Give controls accessible names and errors useful recovery text.
- Verify reflow at the smallest supported width and at 200 percent zoom.
- Preserve content and task completion when reduced motion is enabled.

## Change rules

- Keep each interface task bounded to [scope rule].
- Do not change [protected areas] without approval.
- Record new design decisions in this file or [decision-log path].
- Human design judgment owns unresolved product, brand, and interaction choices.

## Review evidence

Before calling UI work complete, record:

1. The interface and state reviewed.
2. The three highest-impact findings and why they were prioritized.
3. The files and design decisions changed.
4. Before and after captures of the same state and viewport.
5. Keyboard, responsive, accessibility, type, lint, and test results.
6. Open questions that still need a person.

Three illustrative fixes

These examples show how a rule changes a concrete interface decision. They are not customer results or measured benchmarks.

Visual drift

Before
A page adds a literal purple color, a new radius, and a local button style.
After
The revision uses the product's semantic primary token, shared radius, and existing Button component.

Factual summary: The example removes three local style decisions and returns the control to the shared system.

Accessibility

Before
An icon-only close control has no accessible name or visible focus evidence.
After
The revision uses a button with an accessible name and the project's visible focus treatment.

Factual summary: The control now exposes its purpose to assistive technology and keyboard users.

Consistency

Before
A new settings screen invents a second card and form pattern.
After
The revision composes the existing Card, Form, Input, and Button variants.

Factual summary: The screen uses the same component language as the rest of the product.

Record evidence, not claims

Use one evidence record for each before-and-after. A case study only becomes customer proof after its quotes, measures, method, and permission have been verified.

# [Case study title]

- Evidence status: [illustrative | internal benchmark | customer verified]
- Interface and state: [route, screen, or flow]
- Date and product version: [verified date and version]
- Team and agent setup: [tools, model, rules, and relevant settings]

## Before

- Capture: [link or file]
- Observed problem: [what a person or test could verify]
- Baseline checks: [commands, audit results, or review method]

## Three changes

1. [finding, severity, change, and reason]
2. [finding, severity, change, and reason]
3. [finding, severity, change, and reason]

## After

- Capture: [same state and viewport]
- Checks passed: [commands and results]
- Remaining limitations: [what was not tested or fixed]

## Verified outcome

- Metric: [value, method, sample, and time period]
- Customer quote: [approved quote, speaker, role, company, and permission]
- Source: [link to the evidence or approval record]

If a metric or quote has not been verified, keep the placeholder or omit the
field. Never turn an illustrative example into a customer result.

Continue with the advanced path

Expand the workflow after the first interface is verified. Keep design exploration in full design tools and keep final judgment with people.

Questions

Who is the 90-minute path for?

It is for developer-led, AI-first, and code-heavy teams that already use a coding agent and want to improve one existing interface before adopting a wider design-governance workflow.

Does Better Design replace a designer or Figma?

No. Better Design carries approved rules, tokens, components, and review steps into the coding-agent workflow. People still own product and design judgment, and full design tools still support exploration, prototyping, and collaboration.

Can I use Better Design in an existing product?

Yes. Start with one bounded screen, import the existing tokens and components into DESIGN.md, and keep the rest of the product unchanged. The advanced brownfield guide covers incremental adoption.

Does the illustrative before-and-after prove a customer outcome?

No. It demonstrates how a rule changes a concrete interface decision. Measurable outcomes and customer quotes require verified evidence from real users or controlled benchmarks.