Creating an
Agentic
Design System

I started this as a personal exploration of how far I could take a design system. Aegis already had components and a visual language. The next question was how an agent could understand the decisions behind them, and contribute without creating another competing system.

For people

Make the purpose, anatomy and behavior of a component easy to understand.

For agents

Expose the same knowledge as structured requirements, source facts and reusable instructions.

For the designer

Define the language, the boundaries for change and what a good result must preserve.

The agentic layer grows around a conventional React design system. I kept the foundations, controls, data displays, patterns and layouts usable without an agent, a service or an AI model being online.

Foundations

Tokens, typography, color, spacing, shape and motion provide a common vocabulary.

Components

Forms, tables, overlays, feedback and AI interaction components preserve their own behavior and ownership.

Compositions

Page layouts and shared patterns connect those parts into a working application.

I wanted Aegis to work as design-system infrastructure. Its default appearance is a starting point: a project profile configures brand, semantic color, typography, shape and density while keeping the underlying interaction contracts intact.

One profile

Aegis Original, Atlas Precision and Solstice Studio exercise distinct visual directions through the same compiler.

Independent axes

Light and dark remain separate from Fundamental and Fundamental Floating presentation.

Traceable values

Profiles feed Primitive → Semantic → Group tokens. Nested components retain the tokens of their own category.

I shaped Storybook around the questions a designer or engineer brings to a component. Anatomy, usage, states, API details and the authored contract live beside the real implementation, so the documentation explains decisions as well as properties.

See the parts

Connect the visible anatomy to the labels used in the component API and token mapping.

Understand the choice

Explain which decisions are independent, such as a Button’s intent and emphasis.

Follow the source

Keep generated API facts, authored guidance and behavior requirements identifiable.

An API can tell an agent that a prop exists. It does not explain who owns an asynchronous state, what loading must preserve or when a component is the wrong choice. I added authored contracts to make those obligations available alongside the code.

Component

Declare purpose, anatomy, states and invariants that the implementation must preserve.

Application

Name the host’s responsibilities, from meaningful labels to persistence and authorization.

Evidence

Keep requirements, implementation, linked checks and recorded results separate. A contract is not a certification.

I connected the same catalogue to Storybook, a portable command-line kit and a local MCP adapter. Skills guide the work; the tools let an agent discover contracts, inspect a project’s pinned context and validate a proposed composition.

Discover

Find existing capabilities and read the actual public API before creating something new.

Compose

Use the project profile, supported page recipes and shared product conventions.

Check

Validate the structure and audit the product patterns. The MCP adapter is read-only; it does not edit or release code.

The Forma pilot put the system under product pressure across Dashboard, Users, Products, Invoices and Settings. It exposed a gap: pages could obey the tokens while still disagreeing about headers, search widths and filtering behavior.

Page recipes

Collection, detail, settings and dashboard layouts supply a shared structural starting point.

Product policy

Canonical headers, controls and documented exceptions make product decisions explicit.

Visible behavior

The filtering panel pushes and resizes the results beside it. That interaction belongs to a shared pattern.

In the Relay experiment, two agents independently built the Requests page from the same brief, shared shell, product policy and installed kit. Both passed the measured checks. One discarded a cancelled draft; the other kept it.

Shared inputs

The experiment controlled the kit, profile, dataset and supplied patterns, rather than comparing unrelated products.

Unspecified behavior

The brief required Cancel to close without creating a record. It did not say what should happen when the form reopened.

Design judgment

Visual review also found clipped titles and unexplained counts that the passing checks had not identified.

TokenInput made the problem concrete. Two independently produced models passed their own tests but disagreed about duplicates, delimiters and confirmation. I used that disagreement to explore how a registry could support a deliberate consolidation.

Discover first

Search capabilities, aliases, status and canonical implementations before proposing another component.

Resolve behavior

Compare the contracts, choose explicit defaults and variants, then verify the combined implementation.

Carry the change

Record version and migration impact. The consolidated TokenInput is implemented and registered experimentally; it is not a stable, owner-approved release.

I extended the experiment beyond composition into operation. A project pins its release, profile and registry; an infrastructure service inventories configuration and prepares maintenance proposals. A shared workspace adds signed releases, reviewed activation and retained history.

Known context

Portable kits and exact pins make it possible to trace which decisions a project is using.

Deliberate observation

Usage collection starts disabled and requires both project and consumer opt-in. It accepts reviewed technical facts, not page content.

Controlled change

Prepare and inspect an update before activation. Rollback creates a new generation while retaining the previous evidence.

I separated deterministic repair of generated output from AI proposals that change source. In a controlled experiment, a real Codex request repaired a deliberately seeded MetricCard overflow, then faced the same browser and regression checks as the original implementation.

Reproduce

The healthy baseline passed 84 browser scenarios. The seeded CSS defect caused 56 of them to fail.

Propose and verify

One proposal removed the excessive minimum width. All 84 scenarios passed again, alongside 429 source tests and the recorded static checks.

Review

The result became a review commit. Source changes, merging, release and consumer updates remain separate decisions.

Aegis Agentic is now a working beta: a conventional library, configurable language, shared contracts, agent access and bounded maintenance experiments. Building it changed what I pay attention to, from the appearance of a component to how its decisions survive reuse and change.

Implemented

The current catalogue maps 124 API families to authored behavior and includes 127 component and pattern contracts, plus two separate service protocols.

Demonstrated

Independent component and page experiments, installed-kit consumption and one live seeded source repair provide specific evidence.

Still open

Broader repair reliability, production adoption and sustained delivery gains need further evaluation. Human judgment remains essential.