Keeping people and coding agents on the same page

I was already working on the Design System when a different problem started becoming obvious: coding agents could generate interfaces quickly, but speed wasn’t the hard part.

Consistency was.

Product intent, component rules and interaction decisions lived in too many places, or sometimes only in someone’s head. If agents were going to participate in product development, that knowledge had to become part of the system.

Snapshot

Team

Falabella's Artificial Intelligence area, with multidisciplinary teams in Chile and India

Scope

The Design System, its agent-readable documentation, an internal model-agnostic GenAI framework, and the internal products built with them

Coding agents

Claude Code · OpenAI Codex · GitHub Copilot · OpenCode, as implementation environments

In production

The Design System is used across multiple internal products; the framework is used in several of those projects. All of it is internal, which is why this case shows structure instead of screens.

# Story: S-014 — Run history filterStatus: READY · Type: frontend · Risk: low## User storyAs an operator, I want to filter runs by status and date,so that I can find failed runs without scrolling.## Acceptance criteria1. status = failed → only failed runs, count updates2. no match → DS empty state with reset3. reload → filter persists in the URL## DS componentsSelect · DateRange · EmptyState  ← from the Design SystemNo new components. Tokens only.

The Design System came first

I created it from zero: a three-tier token layer (primitive, semantic, component), a production component library adapted from Radix and shadcn/ui, and a CLI that installs component source into each project. Its principles fit in one line: clarity over complexity, consistency with purpose, accessibility as the foundation, tokens before values.

Making components and tokens legible to coding agents improved implementation consistency, but it exposed a larger gap. An agent could use the right component and still make the wrong product decision when states, interaction rules or the reason behind the interface remained implicit.

Before, a ticket might name a control but leave loading, error, empty and responsive behavior open to interpretation. After, a design brief recorded those decisions before implementation, so the owner, designer, coding agent and reviewer worked from the same contract.

That became an internal, model-agnostic GenAI framework designed to carry product intent, stories, interaction rules, Design System guidance and implementation constraints from idea to code.

In practice the framework travels with each project. It packages lifecycle guidance, role definitions, stack-specific conventions, shared context and a Definition of Done in a form both people and coding agents can use.

The Design System enters through a synchronized semantic layer containing components, tokens and agent guidance. Projects can update that layer without editing it by hand, and completion checks the code for hardcoded values and reimplemented components.

Why not just write better prompts?

Prompts and documentation still leave room for interpretation. The framework turns the non-negotiable parts into a contract: reuse an existing component before creating one, use tokens instead of hardcoded values, write the design brief before implementation, and check structural thresholds mechanically at completion.

What “agent-readable” means

A story is the unit a coding agent works from. Its structure is fixed so that every section is readable by the owner and parseable by the agents that refine, implement, test and review it. The illustrative example above shows the key pieces: user intent, verifiable acceptance criteria, Design System choices and implementation tasks.

Every UI story also gets a design brief before code is written. It records the user goal, pattern, components, tokens, screen and control states, responsive behavior and accessibility requirements. Implementation reads the brief first.

One source, different coding agents

I didn’t want the workflow tied to one vendor, so it was designed around the specification and the Design System rather than around a particular coding agent. Guidance is maintained once and adapted to what each environment understands. Critical work can also be reviewed through a different model without changing the product contract.

I’ve used the workflow with:

React only lasted two weeks

The first version assumed React.

That lasted about two weeks, until a documentation-only project couldn’t even install it. Internal products didn’t all use the same stack, and hard-coding the framework around one implementation technology would have defeated the point.

I moved stack-specific behavior out of the core structure, into profiles the framework installs after detecting the stack, so the product specification could remain stable while the implementation environment changed.

Adoption became the real design problem

If trying it required a long setup, nobody was going to use it.

So installation and onboarding became product problems too: pre-flight checks, one command to install, a short quickstart, one command to update, and a doctor script that tells you what’s missing.

Part of adoption was also people. I mentor designers and developers on agentic workflows and spec-driven development, across teams in Chile and India. A shared product language matters more when the people sharing it are several time zones apart.

Where it runs

The Design System is in production across multiple internal products in Falabella’s GenAI and Data area. The framework is used in several projects and can be added as new work starts.

• Internal Agentic Platforms
• Internal Data Platforms
• Internal Events Platforms
• Operational Tools

Once people and agents depend on the same rules, documentation stops being supporting material. It’s part of the system.