Arely Rivera
Alicia Rojas
Stop agents from inventing values, layouts, and patterns.
Onion turns design decisions into structures agents can discover, follow, and build inside: tokens, primitives, composed patterns, written rules, and enforcement.
Resources from “Layered Design, Layered Trust”
The design system's reader changed
Instead of asking an agent to interpret a design system from documentation alone, Onion moves repeatable decisions into the code environment itself.
Design systems were built for people to interpret. AI coding agents changed that relationship. An agent doesn't just read the design system. It generates the screen.
When a decision is left open, the model resolves it during generation. Sometimes correctly. Sometimes by inventing a value, selecting the wrong pattern, or interpreting a rule differently than intended.
The design system needs to become part of the environment the agent builds inside.
From documentation to an operating environment
The goal isn't to make an LLM deterministic. The goal is to make fewer design decisions depend on its non-determinism.
-
Traditional design system
People interpret the system, then people build the interface
Execution model: guidelines, tokens, components, and tools.
-
Onion Design Framework
The system constrains the environment, the agent builds inside it, and people evaluate the experience
Execution model: tokens, primitives, patterns, written rules, and gates.
The five layers
Design decisions ordered by how enforceable they are. The closer a decision moves toward the center, the less interpretation it requires from the agent.
Raw values for color, spacing, typography, radius, elevation, and motion. Prevents invented values and visual drift.
Base components (buttons, inputs, cards, dialogs, tables) carrying behavior, accessibility, states, and constraints. Prevents re-deriving basic interface behavior on every screen.
Solved structures for headers, detail panels, navigation, and record collections. Prevents rebuilding known layouts from scratch.
Contextual guidance explaining when and why a pattern should be used. Prevents using valid components in the wrong product context.
The assembled experience where the system gets tested. When a screen exposes a problem, the fix moves inward.
A fix belongs in the innermost layer capable of enforcing it, not the layer where the defect was noticed.
When a generated interface looks wrong
Evaluate in this order
- Can a token eliminate the decision?
- Can a primitive prevent the mistake?
- Can a composed pattern absorb it?
- Is a written rule missing or ambiguous?
- Is this a decision that still requires human judgment?
Surrounding structure with enforcement
Making a design decision available doesn't mean the agent will use it. Onion surrounds its inner layers with enforcement mechanisms.
Ring 1
A primitive that refuses
Components reject invalid composition before incorrect markup renders.
Ring 2
Editor gates
Fast checks catch violations while the agent is still making changes.
Ring 3
Local gates
Deterministic validation checks tokens, rules, and themes before work leaves the machine.
Ring 4
CI
Constraints run in an automated environment where skipping them is no longer an option.
Tested in code, not just documented
153
Files touched in a production Rails codebase
7,158
Lines added, against 1,920 removed
4
Green CI checks
41
Agent runs across two stacks
Onion began as an experiment inside a production Rails codebase. The production harness itself remained intentionally compact: 46 lines of tokens and base styles, 12 lines of shared partial used across 50 call sites, and 10 lines of agent contract.
That harness carried 131 color tokens across light and dark themes, and transferred to 61 Rails component files without changing the five-layer model.
Tested across React and Rails using Claude and Codex, with cold agents and minimal prompts.
Experiment 01
Exposing design systems
Evaluated structural constraints versus written guidance.
Experiment 02
Pattern recovery
Analyzed how agents recovered contextual design decisions across React and Rails.
Experiment 03
Harness impact
Compared identical tasks with and without the Onion harness.
One sentence changed, and the agents changed with it
Before the fix
18% of runs opened with cards. The rest opened the collection as a table.
After the fix
100% of harnessed runs opened with cards, from the same prompt and the same repository.
The only thing that changed between the two is one sentence in Layer 4. Same prompt, same model, same repository.
What else the runs showed
- Hard-coded hex values fell from 119 to 24 across the affected views in the original Rails experiment.
- 0 of 5 agents used the optional composed component. Making a component available does not ensure an agent will use it.
- No violations detected across 30 pre-registered checks in the first five Rails runs.
Key finding
Making the design system available was not the same as making it operational.
Limits
What Onion doesn't replace
Repeatability is not the same as quality. AI can assemble interfaces and propagate known decisions, but human design judgment is still required to:
-
Understand user needs and frame the right problem
-
Apply taste and evaluate rendered experiences
-
Decide when patterns should change, and evolve the system itself
Build an environment, not another prompt
As coding agents become part of product development workflows, the core question changes.
What decisions are we still asking the model to make?
Read the methodology, run the test yourself
Onion is a public method, not a product. Everything below is yours to read, copy, and run against your own codebase.
-
Framework methodology
The full five-layer method, the 41-run case study, the enforcement rings, and what Onion does not replace.
-
Fidelity testing recipe
Drop a cold agent into your Rails app and see what your design system fails to enforce. Ten minutes, one prompt.
Built at Telos Labs
The people behind the framework also build software for clients.
Telos Labs designs and builds custom software and AI-enabled operational tools.