Topics

Traditional Design Systems

Review what a Design System already does:

• Provides shared foundations
• Creates reusable components
• Standardizes patterns
• Connects design and engineering
• Reduces inconsistency
• Enables teams to scale

AI-Assisted Design Systems

Explain how AI can assist with:

• Generating code
• Creating documentation
• Auditing inconsistencies
• Finding hard-coded values
• Generating tests
• Creating product interfaces
• Supporting migrations

Agentic Design Systems

Introduce the idea that AI can become:

• A consumer of the system
• A contributor to the system
• A maintenance assistant
• A validation assistant

The Consistency Problem

Show typical failures when AI lacks system context:

• Random colors
• Hard-coded values
• Incorrect spacing
• Duplicate components
• Unsupported variants
• Ignored accessibility requirements
• Incorrect component choices
• UI that looks similar but does not use the system

AI-Generated UI vs. System-Aware AI

AI-generated UI:

The model attempts to create an interface from a request, screenshot, or loose description.

System-aware AI:

The model can inspect actual components, tokens, APIs, rules, and documentation before making decisions.

Key Terms in Plain Language

Introduce:

• LLM
• Agent
• Context
• Tool
• Instruction
• Skill
• MCP

Do not go deep into implementation yet.

Demonstration

Use the same interface request in two ways:

1. AI with little or no Design System context
2. AI with structured system context

Compare the output.

Student Takeaway

AI does not remove the need for a Design System. It increases the value of a well-structured one.

The Baseline

Set the benchmark the course is measured against. It is rerun in session 18.

Choose 8 to 12 representative scenarios from the product domain, real tasks covering varied component decisions. Deliberately include a few where more than one answer is defensible, and label them as such rather than pretending there is a single right choice.

Each scenario records:

• An id, and the user goal with its platform, constraints and interaction intent
• A stable task prompt and the system snapshot it ran against
• The expected component or pattern, and the acceptable alternatives
• Why that choice fits: interaction intent, content, density, accessibility, platform convention
• The choices that would be wrong, and why
• Grading criteria and severity, marking which are objective and which need review
• Who labeled it and when

Record enough of the run itself that it can be repeated:

• The exact prompt
• The repository state
• The environment
• Model and tool versions
• The date
• The expected UI requirements

Run them against an agent with minimal context, and score all three levels separately.

Lock a subset now and leave it alone until week 6. A benchmark you keep editing cannot measure anything.

Valid Is Not the Same as Right

Two generated screens can both pass every check and only one of them fit the task. That gap is what the rest of the course is built around, so the three questions are separated on the first evening.

A. Technical compliance

Did the agent use approved components, tokens, imports, props and variants? Static checks, contract tests and builds answer this, and they answer it the same way every time.

B. Contextual correctness

Did it choose an appropriate component and interaction pattern for this scenario? Labeled scenarios answer this, and a person adjudicates the ambiguous ones.

C. Experience quality

Is the result coherent, accessible and useful for the person and the task? Expert critique and accessibility review answer this, and automated compliance cannot.

Passing A tells you nothing about B. A dialog built perfectly from approved parts is still the wrong answer when a toast was wanted.

Cohort Project

Confirm the product domain selected through the pre-course student poll.

Possible domains:

• Fintech
• Travel
• Healthcare
• Marketplace
• SaaS productivity

Define the System

Students make initial decisions around:

• Product type
• User needs
• Core product flows
• System scope
• Supported platforms
• Visual direction
• First component set
• Foundations needed
• Token categories
• Naming approach
• Documentation expectations
• Accessibility expectations
• AI goals

Initial Component Inventory

Possible initial set:

• Button
• Input
• Select
• Checkbox
• Radio
• Switch
• Alert
• Dialog
• Tabs
• Card

The final course does not need a huge component library. The focus is architecture, reuse, and system quality.

Initial System Architecture

Define:

• Foundations
• Tokens
• Components
• Patterns
• Documentation
• Code
• Registry
• AI context
• Governance

Practical Exercise

Create a simple system map.

Deliverable

A Design System project definition and architecture plan.

Authority and Evaluation

Decide, in writing, which artifact wins when two disagree:

• Git is the authoritative source for approved tokens, component APIs, contracts, tests and released registry entries
• Figma is where design intent is authored and explored
• Storybook documents and demonstrates what is implemented, and does not compete as a source of truth
• Agent instructions say where to read approved artifacts, and impose constraints

Then agree how a scenario is labeled, so that two people labeling the same task reach comparable answers: the expected pattern, the alternatives you would accept, the reasoning, and what counts as a disagreement worth escalating.

Scenarios change only through versioned edits from here on, and the locked subset does not change at all.

Topics

Introduce enough Figma structure to begin:

• Variable collections
• Primitive values
• Semantic intent
• Basic naming
• Auto Layout
• Component properties
• Variants

Do not try to teach the entire token architecture yet. Week 2 deepens it.

Practical Work

Students create:

• A small initial color foundation
• Basic spacing values
• Initial typography decisions
• One or two components
• Basic component states

Recommended First Component

Use Button to discuss:

• Anatomy
• Tokens
• Properties
• States
• Size
• Hierarchy
• Accessibility
• Naming

First AI Experiment

Give AI the design with minimal context and observe:

• What can it infer?
• What does it misunderstand?
• What context is missing?
• Which names are ambiguous?
• What would need to be documented?

Deliverable

A first working slice of the system plus a list of context gaps.

End-of-Week Outcome

Students have already started building and understand the course problem through direct experience rather than theory alone.

Capture the Starting Point

Run the locked scenarios against the first slice and record how the agent behaves while the system is still almost empty.

Write down the conditions as carefully as the results. A rerun in week 6 is only a comparison if the agent, the model version, the tools and the prompt are comparable, and when they are not, the honest report says so.

Keep at least one case where the output was technically valid and still the wrong component. It is the clearest thing you will show in the capstone.

Primitive Tokens

Examples:

• blue-500
• gray-100
• space-400
• radius-200

Explain why primitive tokens describe values rather than intent.

Semantic Tokens

Examples:

• color-action-primary-background
• color-text-default
• color-border-critical
• space-component-gap

Explain why semantic tokens communicate purpose.

Aliasing

Show relationships such as:

`color-action-primary-background` → `blue-600`

Explain why aliases make systems easier to theme and maintain.

Token Categories

Cover:

• Color
• Typography
• Spacing
• Sizing
• Radius
• Elevation
• Motion where relevant

Naming Principles

Discuss:

• Predictability
• Hierarchy
• Consistency
• Human readability
• Machine readability
• Avoiding ambiguous names

AI Connection

Show why `blue-500` contains less product intent than `color-action-primary-background`.

Semantic naming does not replace documentation, but it improves context.

Exercise

Review weak token names and restructure them.

Deliverable

Agreed token taxonomy for the project.

Mapping and Authority

Give every token a stable identifier and a documented correspondence between its Figma variable and its code token.

Separate the layers, because agents and people override them differently:

• Primitives
• Semantic tokens
• Component-level decisions
• Overrides that are actually permitted

Topics

• Variable collections
• Modes
• Aliases
• Scopes
• Organization
• Naming
• Primitive layer
• Semantic layer

Practical Work

Students implement:

Colors

• Brand
• Neutral
• Surface
• Text
• Border
• Action
• Feedback/status

Typography

• Families
• Sizes
• Weights
• Line heights
• Semantic text roles where appropriate

Spacing

Create a controlled spacing scale.

Radius

Define a small useful set.

Sizing

Define relevant size tokens.

Themes

Introduce how semantic architecture can support:

• Light/dark modes
• Brand variation

Do not let multi-brand or dark mode consume the whole course. They are examples of why token architecture matters.

Deliverable

Working Figma foundations and variable architecture.

Traceability and Overrides

For any token, you should be able to answer three questions without guessing: where it is authoritative, how it appears in Figma, and what happens when the two disagree.

Write down which overrides are allowed, and which are a defect.

Component Anatomy

Break down:

• Container
• Content
• Icon
• Label
• Supporting text
• State
• Interaction

Properties and Variants

Teach how to decide what becomes:

• Variant
• Boolean property
• Text property
• Instance swap
• Separate component

States

Examples:

• Default
• Hover
• Focus
• Active
• Disabled
• Error

Component Boundaries

Discuss:

• When a component is too generic
• When it is too specific
• When to compose
• When to create a pattern
• When not to create a new component

AI-Readable APIs

Explain why predictable names and a small intentional API help AI use components correctly.

Practical Work

Students create or refine core components.

Deliverable

A coherent initial Figma component library.

Component API Inventory

Draft the inventory the contracts in week 4 are built from. For each component in scope:

• Its canonical name
• Its permitted props and values
• The tokens it is allowed to reference
• Its accessibility constraints

Then the half that a prop list cannot carry, and that an agent most often gets wrong:

• When this component is the right answer
• When it is not, and what to reach for instead
• The patterns it is commonly confused with

Dialog against Drawer, Alert against Toast, Tabs against Segmented Control, Select against Combobox, Button against Link. Write the distinction down, and connect each one to the scenarios it decides.

Not every pair has one right answer. Where the choice is genuinely contextual, say so rather than inventing a rule.

Explain MCP Simply

MCP is a standard way for AI tools to connect to other tools and retrieve structured context.

In this case:

AI ↔ Figma

Topics

• Figma MCP
• MCP servers
• Design context
• Component retrieval
• Variable retrieval
• Layout information
• Metadata
• Context vs. screenshots

Practical Demonstration

Connect Claude and/or Codex to Figma.

Ask:

• What components exist?
• What properties does this component have?
• Which variables are used?
• What states exist?
• What component should be used for this pattern?
• How is this layout structured?

Design-to-Code Experiment

Ask the agent to create implementation guidance or code from a structured Figma component.

Review accuracy.

Important Lesson

The goal is not:

Look at this screenshot and copy it.

The goal is:

Inspect the system and use its real structure.

Deliverable

Working Figma-to-agent connection.

What MCP Exposes, and What It Does Not

A connection is not a guarantee. Separate the two in your own notes:

• What the protocol actually exposes to an agent
• What it guarantees about correctness or freshness
• Where the answer came from, so a claim can be traced

Then keep one retrieval trace with its sources, because when an agent picks the wrong component there are four different faults it could be, and they have different fixes:

• The context was missing
• The context was stale
• Retrieval failed to find what was there
• Retrieval worked and the reasoning was still wrong

Nothing here synchronizes Figma and code by itself. Reconciliation is a reviewed step, not a feature.

Topics

Explain:

• Repository
• Files
• Folders
• Source files
• React
• JSX
• Components
• Props
• CSS
• Dependencies
• package.json
• Package manager concepts
• Imports
• Exports

Component Comparison

Compare one component across:

• Figma
• React
• Storybook later
• AI context

Use the same Button component where possible.

Teach Students to Recognize

• Where a component lives
• Where styles live
• Where tokens are referenced
• What a prop is
• What AI changed
• Whether the change looks safe
• When to ask an engineer or reject a change

Deliverable

Students can navigate the repository and explain how a component is represented in code.

Read the Authoritative API

Practise reading a component's real API in code rather than inferring it from a design or a name, because that is exactly the mistake an unconstrained agent makes.

Topics

• Git
• Repository
• Clone
• Commit
• Branch
• Diff
• Pull Request
• Merge Request
• Merge
• Revert
• History

GitHub and GitLab

Explain that the core concepts are transferable.

AI Connection

Show how an agent can:

• Modify files
• Create a branch
• Prepare changes
• Show a diff
• Assist with a PR/MR description

Practical Exercise

Students:

1. Open or clone the repository.
2. Create a branch.
3. Make a small controlled change.
4. Review the diff.
5. Commit it.
6. Understand how it would be reviewed before merge.

Deliverable

A working Design System repository and basic review workflow.

Reconcile a Drift

A mismatch is introduced on purpose, a variant or a token that disagrees between Figma and code.

1. Have the agent report it, with the file and source as evidence
2. Have it propose a reconciliation
3. Review the diff
4. Accept it as a Git change

The point is the review step. An agent that proposes is useful, an agent that silently applies is not.

Topics

• What shadcn is
• Source ownership
• Component installation
• Composition
• Customization
• Dependencies
• Utility styles
• Component APIs

Compare

Explain how shadcn differs from:

• A fixed packaged component library
• Copy/paste snippets
• A proprietary internal system

Why It Works for This Course

Students can:

• Own the source
• Change the system
• Apply tokens
• Control APIs
• Build a registry
• Make components available to agents

Practical Work

Initialize the component foundation.

Deliverable

Working shadcn setup aligned to the project.

Contracts in the Architecture

Decide how a contract is represented in this repository before writing any. A minimal documented schema the course actually validates, rather than a new standard.

Suggested Components

Use approximately 8 to 10 core components across the course.

Potential set:

• Button
• Input
• Textarea
• Select
• Checkbox
• Radio
• Switch
• Alert
• Dialog
• Tabs
• Card

The exact list can adapt to the chosen product.

Topics

• Design Tokens in code
• Component props
• Variants
• States
• Composition
• Accessibility
• Naming
• API consistency

AI Workflow

Use Claude or Codex to assist with implementation.

Students must review:

• Whether tokens are used
• Whether existing patterns are reused
• Whether props are sensible
• Whether accessibility is preserved
• Whether unnecessary abstractions were created

Deliverable

A working production component library.

Prop Maps and Negative Cases

Write the explicit prop map for each core component, and write the example that must fail at the same time as the rule, not after it:

• An unsupported property
• A forbidden value
• A hard-coded style where a token exists
• A component invented rather than reused

A check nobody has seen fail is not yet a check.

Then find the limit. Take a scenario where the generated code passes every contract you have written and still chooses the wrong component, and keep it next to the passing tests.

Four to six components documented and verified properly beat ten described and trusted. The rest are stretch work.

Explain the Registry Simply

A registry gives people and AI a predictable way to discover, install, and reuse the approved parts of the system.

Topics

• Registry purpose
• Registry structure
• Metadata
• Dependencies
• Component distribution
• Configuration
• Rules and conventions
• AI discoverability

Practical Work

Create the first custom registry entries.

Students should understand how this changes the system from:

“Some components in a repository”

to:

“A reusable system that can be discovered and consumed.”

Deliverable

Working custom registry.

Contract Discovery

Publish the contracts with the components, so that installing from the registry brings the rules along with the code.

Topics

• Storybook structure
• Stories
• Controls
• Props
• Variants
• States
• Examples
• Usage guidance
• Accessibility
• Interaction tests

Documentation Content

A component page can include:

• Purpose
• Anatomy
• Variants
• States
• Props
• Usage
• Accessibility
• Do
• Don't
• Related patterns
• Figma link where appropriate

Practical Work

Create Storybook stories for core components.

Deliverable

Initial documented Storybook environment.

Stories as Executable Examples

Write stories for the components the capstone actually uses, as working usage examples rather than a tour of the library.

Topics

Explain how agents can use Storybook to:

• Discover approved components
• Understand props
• Inspect variants
• Inspect states
• Read examples
• Generate missing stories
• Run interaction tests
• Run accessibility checks
• Validate implementation

Storybook MCP

Introduce where appropriate.

Explain the principle before the configuration:

The agent should inspect the real component system before deciding what to build.

Practical Exercise

Ask the agent to:

• Find a component
• Explain its API
• Recommend the correct variant
• Create or improve a story
• Run or interpret a validation check

Deliverable

An AI-accessible Storybook workflow.

The Evaluation Harness

Build the harness that turns opinion into a result. It runs the locked scenarios and reports the three levels separately, because they are not answered the same way.

A, by machine

• Invalid imports and props
• Forbidden values and hard-coded styles
• Interaction tests
• Basic accessibility tests

B, by labeled comparison

Each choice is rated appropriate, a defensible alternative, inappropriate, or needing review. A person settles the ones that need review, and disagreements between labelers are recorded rather than averaged away.

C, by critique

An instructor-led review against an explicit checklist: is the result coherent, is it accessible, does it suit the task. No automated check establishes this.

Report the three separately. Collapsing them into one accuracy figure hides which kind of failure you are looking at.

If you use a model to judge another model's output, calibrate it against labeled samples and have a person settle the disagreements. A model's score is not ground truth.

Topics

• AGENTS.md
• CLAUDE.md
• DESIGN.md
• Repository instructions
• Skills
• Rules
• Context hierarchy
• Component usage policies

What Belongs in Persistent Context

Component Use

• Prefer existing components.
• Check the registry before creating a new component.
• Use documented variants.

Tokens

• Do not hard-code colors when a token exists.
• Do not hard-code spacing when a token exists.

Accessibility

• Preserve keyboard support.
• Preserve focus states.
• Use documented accessibility requirements.

Naming

• Follow system conventions.
• Do not introduce arbitrary naming styles.

New Components

• Confirm there is no equivalent before creating one.
• Explain why a new component is needed.

Foundations

• Do not modify foundations without explicit approval.

Preferred Patterns

Teach agents:

• What to use
• When to use it
• Why to use it
• Which alternatives exist

Forbidden Behaviors

Examples:

• Inventing colors
• Creating arbitrary spacing
• Duplicating components
• Adding unsupported variants
• Ignoring Storybook
• Bypassing accessibility
• Changing global tokens without approval

Core Principle

We are not teaching AI how to design.

We are teaching AI how our Design System works.

Deliverable

A persistent AI instruction layer for the system.

Instructions That Earn Their Place

Publish where instructions live, in AGENTS.md or CLAUDE.md, how they relate to the contracts, and how to avoid two directives that contradict each other.

Then revise at least one instruction or contract because of a failure you observed, and measure whether it changed anything.

Do not restate an authoritative contract inside a prompt. Point at it.

The Evaluation Report

Agree the shape of the report now, so the capstone is assembled rather than written from scratch. It carries:

• The system version and commit, the model, toolchain, prompts and date
• The locked scenarios evaluated, and what changed since the baseline
• A: invalid imports, props and hard-coded tokens, and the contract, build and accessibility results
• B: appropriate choices, defensible alternatives, inappropriate choices, those needing review, and two annotated examples giving expected, actual and why
• C: accessibility and usability findings, unresolved issues, and what human testing would still be needed
• Limitations: ambiguous labels, reviewer disagreements, tool or model drift, small sample size, and whether students had seen the answers
• Next actions: contract or instruction changes, and the regressions worth keeping

The limitations section is not a formality. A benchmark the class has already seen is a teaching exercise, not evidence about agents in general, and the report says which one it is.

Product Requirement

Give students a real product task inside the shared domain.

Expected Agent Workflow

1. Understand the product requirement.
2. Inspect the Design System.
3. Search available components.
4. Read relevant documentation.
5. Use existing tokens.
6. Compose existing components.
7. Follow system rules.
8. Build the interface.
9. Validate the result.

Student Review

Students check:

• Did the agent use the correct components?
• Did it create unnecessary components?
• Were tokens respected?
• Were spacing rules respected?
• Were APIs used correctly?
• Was accessibility preserved?
• Were documented patterns followed?
• Does the result feel like part of the same system?

Iterate

When AI gets something wrong, students should not only fix the output.

They should ask:

What information was missing from the Design System?

Possible fixes:

• Better documentation
• Better naming
• Better story
• Better rule
• Better component API
• Missing component
• Missing token

Deliverable

A real working product interface built with the Design System.

Build and Score

Build the product interface from the registry, and score the agent's work with the harness as you go rather than at the end.

Audit Tasks

Agents can help identify:

• Hard-coded colors
• Hard-coded spacing
• Token inconsistencies
• Duplicate components
• Duplicate patterns
• Missing stories
• Missing states
• Deprecated components
• Accessibility issues
• Documentation gaps
• Design/code inconsistencies
• Unused tokens
• Inconsistent APIs

Advanced Examples

Explore how AI can assist with:

• Token migration
• Component migration
• Documentation generation
• Refactoring
• Component consolidation
• Story generation
• Accessibility fixes

Human Review Principle

AI proposes. Humans evaluate.

Practical Work

Create repeatable maintenance prompts, instructions, or workflows.

Deliverable

AI-assisted maintenance toolkit.

Regression and Drift

Fold the checks into maintenance, so a system that was correct in week 5 can be shown to still be correct:

• Drift checks between Figma and code
• Regression evaluation against the stored tasks
• Accessibility and automated checks on change

AI Permission Model

Level 0, Read

AI can inspect the system.

Level 1, Recommend

AI can suggest changes.

Level 2, Generate

AI can create proposed code, documentation, or stories.

Level 3, Branch

AI can create changes in a separate branch.

Level 4, Pull Request / Merge Request

AI can prepare a change for human review.

Level 5, Test

AI can run automated validation.

Level 6, Automated Maintenance

Selected low-risk tasks may be automated.

Students should not assume Level 6 is the desired goal.

Governance Questions

Students decide:

• Can AI create components?
• Can AI modify tokens?
• Can AI update documentation?
• Can AI generate stories?
• Can AI fix accessibility issues?
• Can AI create PRs/MRs?
• Can AI merge?
• What always needs a human?
• Who owns the final decision?

Introduce the Ongoing Operating Loop

Consume → Validate → Maintain → Evolve

Explain:

The full course moved through the system lifecycle.

Once the Design System exists, the recurring work becomes:

1. Consume the system
2. Validate the result
3. Maintain what needs attention
4. Evolve the system based on new needs
5. Consume it again

Final Presentation

Each student presents:

• System architecture
• Token model
• Figma components
• Code components
• Registry
• Storybook
• Agent instructions
• AI consumption example
• Product implementation
• Maintenance workflow
• Governance decisions

Deliverable

Completed capstone and governance model.

Agentic Design System Lifecycle

The course moves through this lifecycle across six weeks:

1. Define
2. Structure
3. Encode
4. Document
5. Connect
6. Consume
7. Validate
8. Maintain
9. Evolve

Do not describe all nine stages as repeating every week.

The ongoing loop after the system exists is:

Consume → Validate → Maintain → Evolve

Certification Outcome

Students who successfully complete the capstone receive:

Certified AI Design Systems Practitioner

The certification should validate practical application rather than simple attendance.

Evaluation areas should include:

• Architecture
• Tokens
• Components
• Figma
• Code
• Registry
• Storybook
• Accessibility
• Agent instructions
• AI system usage
• Maintenance
• Governance
• Final product implementation

The final scoring rubric will be defined separately.

Baseline Comparison and Governance

Rerun session 1's locked scenarios in comparable conditions and compare each level on its own terms:

• A: valid component usage, and forbidden prop and token violations
• B: appropriate choices, defensible alternatives and wrong choices, against the same labels
• C: the critique findings, and what remains unresolved

Analyze the failures and the tradeoffs rather than only the totals. Results are directional, not proof, and where the model or the toolchain has moved underneath you they may not be comparable at all. Say which.

Then set the governance the system is handed over with:

• Risk tiers, and which changes need which approval
• Architecture decision records for the major choices
• The contextual regressions worth rerunning, not just the technical ones

Nobody is required to improve on every measure. An honest regression you can explain is worth more than a number that went up.