Design system case study

Basics Design System

A design system that documents itself by measuring the real component, and audits its own consumers through installable AI agents—so the rules hold even when a model writes the UI.

01 / Overview

A shared language for people and agents.

Basics is an agentic design system built for AI applications. It brings foundations, reusable components, and actionable guidelines into one system that supports both designers and coding agents.

The design agent, now the shadcn agent, helps build with the framework. The UI testing agent checks the implementation afterward, helping the product stay consistent as it grows.

My role
Design Systems Lead
Focus
AI application interfaces
Foundation
Tokens, components & guidelines
Agent layer
Design + UI testing
02 / The challenge

Fragmented experiences and inconsistent implementations.

AI speeds up implementation. The design system needs to make its rules just as accessible as its components.

  1. 01

    Guidelines get lost

    A component library is only part of the system. When usage rules live elsewhere, both people and AI agents fill the gaps with assumptions.

  2. 02

    Small differences multiply

    A new color here, an extra spacing value there. Repeated across generated screens, small decisions become an inconsistent product.

  3. 03

    Review happens too late

    Manual reviews struggle to keep up with AI-assisted development. Teams need a repeatable way to check the implementation against the system.

03 / Workflow

How it works?

One shared design system connects the tools teams use to make and build digital products.

Dev team

Applications or Projects
Micro-frontend
ReactClaude CodeCodex
Design system

Design Team

Figma design
Figma Make
Claude Design
Figma DesignClaude Design
04 / Foundations

Start with the shared language.

The foundations give designers, developers, and agents the same starting point for every interface decision.

  1. 01

    Color

    Semantic roles give every surface, action, and state a purpose.

  2. 02

    Typography

    A clear hierarchy separates instructions, responses, and supporting information.

  3. 03

    Spacing & shape

    Shared spacing and radius scales keep dense AI workspaces coherent.

  4. 04

    Iconography

    Consistent symbols make actions and agent states easier to recognize.

  5. 05

    Agent guidelines

    Composition, accessibility, and usage rules guide generation and review.

05 / Color system

Color with a clear purpose.

Brand, neutral, and destructive ramps form the palette. Components consume semantic roles, so meaning stays consistent across themes.

BrandActions & emphasis
#eaf5fa
#cfe6f1
#a4cfe2
#6fb1cd
#3d8fb2
#046289
#054f6d
#063d54
#072c3c
NeutralSurfaces, text & borders
#ffffff
#f5f5f5
#e5e5e5
#d4d4d4
#a3a3a3
#737373
#525252
#262626
#0a0a0a
DestructiveErrors & irreversible actions
#fef2f2
#fee2e2
#fecaca
#f87171
#ef4444
#dc2626
#b91c1c
#7f1d1d
#450a0a

Palette specimens from the Basics token architecture. Raw values belong in the foundation; semantic roles belong in components.

06 / Typography & rhythm

Typography that scales.

Tailwind-inspired tokens support any brand font.

Display / Product intent

Clarity drives interaction.

Heading / Task context

Clarity drives interaction.

Body / Useful detail

Clarity drives interaction.

Label / System feedback

Clarity drives interaction.

Spacing

Primitive tokens become semantic values for padding, margin, and responsive layout.

TokenValuePixelsUse for
--spacing-10.25rem4pxTight icon gap
--spacing-20.5rem8pxInline spacing
--spacing-30.75rem12pxCompact padding
--spacing-41rem16pxDefault component gap
--spacing-61.5rem24pxCard padding
--spacing-82rem32pxSection gap
--spacing-123rem48pxMajor layout rhythm
Iconography

One visual language for actions, agents, and feedback.

07 / Token architecture

From raw values to reusable UI.

Tokens create reusable UI patterns and keep every product surface consistent. Primitive values become semantic roles that components can use across themes.

01 / Primitive

The value

Raw color ramps and numeric scales.

--brand-600
02 / Semantic

The meaning

A named role that adapts to the theme.

--primary
03 / Component

The application

A utility applied to a component.

bg-primary
Basics token architecture: raw brand, neutral, and destructive ramps feed semantic roles, which feed component utilities.
One role connects a design decision to every component that uses it.
08 / Components for AI

Patterns for conversational and agentic AI.

Research-backed patterns create new AI experiences and scale content across conversations, agent workflows, and review.

Summarize this document.

Here are the key findings.

Conversations

Prompts, responses, and supporting context.

Agent activity
Read the source
Apply the guidelines
Review the implementation

Agent workflows

Steps, tool activity, and visible progress.

Ready for review

Check the result before moving forward.

Human decision point

Human oversight

Clear checkpoints, feedback, and decisions.

Illustrative compositions showing how the system supports AI application patterns.

09 / Documentation

Show the component. Explain the rules.

Clear usage guidance helps teams and agents apply components consistently across products.

  1. 01

    Preview

    See the real component and its source together.

  2. 02

    Anatomy

    Inspect rendered dimensions, spacing, and resolved tokens.

  3. 03

    Installation

    Bring editable component source into the project.

  4. 04

    Usage

    Follow documented composition patterns and guidelines.

Use the shared role

bg-primary text-primary-foreground

The component follows the theme and stays connected to the system.

Review one-off values

background: #046289

A value embedded in a component bypasses the semantic role and needs review.

10 / Design to development

Connected from build to review.

MCP or API access makes the rules available in the development workflow. The design agent and testing agent use that context at different stages.

  1. 01

    Connect the rules

    Make framework context, component guidance, and design rules available through MCP or API.

  2. 02

    Build with the agent

    The shadcn design agent uses that context to create and compose the interface.

  3. 03

    Review implementation

    The UI testing agent checks the resulting UI code against the shared rules.

  4. 04

    Refine & repeat

    Developers address findings, then run another review as the product evolves.

Post-implementation checks

UI-testing agent compares the UI with the design system and writes Jira stories.

The UI testing agent reviews the implementation against the shared system, checking design tokens, component architecture, and documented usage patterns. When it finds a discrepancy, it explains the issue and generates a Jira-ready story so the team can prioritize, fix, and verify the change.

  1. 01

    Scan the implementation

    Read the UI code and identify the components, tokens, and patterns in use.

  2. 02

    Check against the system

    Compare the implementation with the shared token architecture and usage rules.

  3. 03

    Explain discrepancies

    Describe what is out of alignment, where it occurs, and which rule is affected.

  4. 04

    Create Jira stories

    Turn each finding into a Jira-ready story with a clear fix and acceptance criteria.

11 / What Basics brings together

A system that stays in the conversation.

The goal is consistent development: shared decisions before implementation, useful checks afterward, and people in control of the final result.

01
Shared rule setOne reference for design, development, and review.
02
Complementary agentsThe shadcn design agent builds; the UI testing agent reviews.
03
Continuous consistencyA repeatable build, review, and refinement workflow.
Keep exploringNext case study / UI Testing Agent

UI Testing Agent

A code-level agent that spots visual inconsistencies, flags design drift, and reports before issues reach production.

Explore case study
UI testing agent report