---
title: Design reference: build and test against the design
description: An accepted design version is the reference: agents build from its live files and tokens, and every run is checked for pixels, structure and tokens.
query: check implementation against design
kind: use-case
order: 61
demo: false
---
Once the team accepts a version of the design, it becomes the design reference of the scenario. Development builds from it and QA checks against it, step by step, with the same step ids.

## The problem

Handoff files go stale the day the design changes. Nobody notices a button one shade off, a missing label or padding outside the scale until a designer reviews production by eye.

## What changes with Kaloko

- **One reference per scenario.** An accepted version is marked as the design reference (the baseline stays the last good implementation run). A design branch linked to a git branch has its own reference.
- **Handoff an agent can read.** `get_step` over MCP, or `kaloko export --live`, gives the live files, the token set, the page structure and the open comments of each step.
- **Dev mode for people and agents.** In the step detail, *Dev mode* (`D`) shows an element's box and distances, its colors, type and spacing with the token each value comes from, contrast against WCAG AA, its hover, focus and disabled states, and its images. An agent reads the same as the step spec: `kaloko spec <step>` or MCP `get_step_spec`.
- **Checks, not opinions.** `packs: [design]` adds three criteria to implementation steps: pixels (AC801), structure (AC802) and tokens (AC803). Add `a11y` for contrast and the other accessibility basics. They show on the canvas like any criteria.
- **Precise findings.** Token drift counts only authored values: browser defaults and values the reference itself uses don't count. Each finding suggests the token to use.

## How it works

1. **Accept a version** in the canvas, then *Set as design reference* (or `kaloko reference --design --version 4`).
2. **Build from it.** Your agent reads `kaloko spec <step>` (or `get_step_spec`) for each step, takes the live files from `get_step` or `kaloko export --live` if it needs them, and implements the steps with the project's own skills and the token names.
3. **Turn on the pack** in the implementation scenario: `packs: [design]` on the steps that have a design.
4. **Run as usual.** `kaloko walk`, `kaloko evaluate`, `kaloko share`. The evaluation fetches the reference and fills the design criteria; `kaloko drift` lists, element by element, the expected token next to what the page has, and fails until they match.
5. **Follow changes.** When the reference moves, `list_step_changes` names the steps to touch, and followers get *reference changed* in their inbox.

## Skills and prompts

```
Implement the checkout steps from the design reference: read kaloko spec for each step of FLOW-checkout, build
with its tokens and keep the step ids, walk the implementation scenario with packs: [design], then run
kaloko drift and fix what it lists.
```

```
List the steps that changed between the design reference and the draft, and plan the implementation work.
```

## What it looks like

An implementation run shows AC801–AC803 per step and viewport. For example, *5 values outside the token set: padding 15px → space.m; background #2e6bfe → color.accent*, or *missing actions: "Pay"*. Compare offers the design reference next to the baseline.

## What you get

- a design reference development and QA share, with a history
- drift found by the run, not by a designer eyeballing production
- handoff that stays current, because it is the accepted version itself
