All guides › By use case

Design reference: build and test against the design

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.

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.
• 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 calls get_step for each step, or runs kaloko export --live, and implements the steps with the project's own skills.

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.

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: get_step for each step of FLOW-checkout, keep the
step ids and the token names, then run the implementation scenario with packs: [design] and fix the drift.

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

More guides