Lab 08 · Design System as AI Context

Restructure a deliberately messy component library into AI-consumable context — semantic naming, bound variables, published exemplars, and a written generation-rules file — then prove the work by prompting a new screen that lands on-system, built from real components instead of look-alikes.

Adaora owns the design system at Hearthstack, a fictional home-services marketplace, and the complaint from every designer using AI generation is identical: "It ignores our system." The truth is less flattering — the system is unreadable, to machines and honestly to humans. Names like Button/Final_v2_REAL, colors hardcoded per screen, three competing card components, no published guidance. AI generation is a mirror: it produces exactly the quality of system you feed it. This lab hands you a condensed version of Hearthstack's mess, plus an AI-drafted rules file that contains its own planted problems. You will clean the library, correct the rules, and run the proof: one generated screen, audited component by component.

You will need

Figma (free tier) for the rebuild — or a doc if you prefer to run this as a naming/structure exercise first.
A chat AIfree ChatGPT, Claude, or Gemini.
Timeabout 90 minutes.
No real datathe library inventory below is fictional and deliberately bad.

The library inventory (as found)

HEARTHSTACK LIBRARY — current state export

COMPONENTS
- Button/Final_v2_REAL          fill #E8590C, radius 8
- Button/Final_v2_REAL Copy     fill #E8590C, radius 8, bold
- btn-secondary-NEW             stroke #E8590C, radius 6
- Button (do not use??)         fill #F76707, radius 8
- Card_v3                       white, shadow-sm, padding 16
- Card_v3_forListings           white, shadow-sm, padding 16,
                                has image slot
- ServiceCard-mike-wip          white, shadow-md, padding 20
- input_1                       stroke #D0D4DA, radius 6
- Input/WithLabel               stroke #CED4DA, radius 6
- chip                          fill #FFE8D9, text #E8590C
- Badge/Status                  fill #D3F9D8, text #2B8A3E

STYLES / VARIABLES
- "orange" = #E8590C   (used by 2 of 4 buttons)
- "Orange 2" = #F76707 (used by 1 button, 14 raw layers)
- "gray-border" = #D0D4DA (Input/WithLabel uses #CED4DA raw)
- text styles: "Heading", "heading-2", "Body", "body copy",
  "small" — no documented scale or usage rules
- spacing: no variables; screens use 12/15/16/18/24 ad hoc

USAGE NOTES (from team chat)
- "which button is the real one lol" — asked 3x this month
- listings screens: half use Card_v3_forListings, half use
  detached copies of ServiceCard-mike-wip
- brand orange was changed to #E8590C in March; nobody
  updated Orange 2 or the 14 raw layers

The AI-drafted generation-rules file (to audit)

A teammate asked a chat model to draft the rules file. It contains planted problems — audit it in step 5.

HEARTHSTACK GENERATION RULES v0.1 (AI draft)

1. Primary actions use component Button/Primary with token
   color.brand.primary (#E8590C).
2. Secondary actions use Button/Secondary (outlined).
3. All listing content uses Card/Listing with the image slot.
4. Form fields use Input/Labeled; never draw raw rectangles.
5. Status indicators use Badge/Status with semantic color
   tokens (color.success, color.warning, color.danger).
6. Spacing follows the 4pt grid: allowed values 4/8/12/16/24/32.
7. Text uses the type scale: Display/Heading/Body/Caption.
8. For photography-heavy layouts, prefer the Card/Hero
   component with the parallax variant.
9. Accent surfaces may use color.brand.secondary (#F76707)
   for visual variety.
10. When a needed component is missing, generate the closest
    match inline and flag it for the DS team.

Steps

Audit the inventory — name every disease. With your AI as a rubber duck, list what is wrong in machine-consumption terms: duplicate components with no canonical choice, names carrying version-control garbage instead of semantics, values hardcoded instead of bound to variables, drifted tokens (find the near-identical pair), and an orphaned old-brand color still live. Each disease gets one line: symptom → why generation chokes on it.
Design the target taxonomy. Write the naming scheme before touching anything: Component/Variant semantic names (Button/Primary, Button/Secondary, Card/Listing, Input/Labeled, Chip/Filter, Badge/Status), a token set (color.brand.primary, color.border.default, color.success, spacing scale on a 4pt grid, a four-step type scale with usage rules). Every current component maps to exactly one target — or to deletion. Write the mapping table; ambiguity here becomes ambiguity in every future generation.
Rebuild in Figma. Create the variables, rebuild the six canonical components bound to them, mark the deprecated ones (Figma's free tier lacks branching — prefix deprecated components with zz-deprecated/ so they sort last and are excluded from search-by-intent), and publish. Merge the card triplets into one Card/Listing with an image-slot boolean. Resolve the drifted border pair (#D0D4DA vs #CED4DA) into one token.
Create the exemplar page. One published page showing each canonical component in correct use with a one-line usage rule as a text annotation. Exemplars are the highest-value AI context you can produce: generation tools and teammates both copy what they can see.
Audit the AI-drafted rules file. Line by line against your actual rebuilt library. Three questions per rule: does the referenced component exist, does the referenced token exist, and is the rule safe? At least three rules reference things that do not exist or prescribe behavior that recreates the original mess. Rewrite the file to v1.0: only real names, only safe instructions.
Run the generation proof. Prompt your AI generation surface (Figma First Draft / Make, or a chat model if you are running doc-only) with the rules file as context plus: "Generate a 'service provider profile' screen for Hearthstack: provider photo and name, rating badge, three service listing cards, a primary 'Book now' action, and a message-provider secondary action. Use only the components and tokens in the rules file."
Audit the generated screen component-by-component. Build a table: Element | Component used | On-system? (real component / look-alike / off-system) | Fix. A look-alike — right appearance, not the actual component instance — counts as a miss: it will not receive updates and it poisons the file. Score the run: on-system elements / total elements.
Write the before/after memo. Half a page: the disease list, the taxonomy decisions, the rules-file corrections, and the generation score with one screenshot-worthy example of a component that landed on-system because of a specific fix you made. This memo is the argument for funding the full-library cleanup.

Pro Tip

Name components for what they mean, not what they look like or who made them — ServiceCard-mike-wip tells a generation model nothing, and Card/Listing tells it everything it needs.

Verify your work

A disease list covering duplicates, semantic-free names, hardcoded values, the drifted token pair, and the stale brand color.
A complete old→new mapping table with zero ambiguous rows.
Rebuilt canonical components bound to variables, plus a published exemplar page.
The rules-file audit catching all planted problems, with a corrected v1.0.
A generation proof scored component-by-component, with look-alikes counted as misses.

▸Answer key — the planted problems and expected resultsoptional deep dive — click to expand

Inventory diseases (step 1 ground truth). Four buttons for at most two real intents, with the canonical one identifiable only by tribal knowledge; Button (do not use??) still on the old brand orange #F76707 — the March rebrand left it and 14 raw layers behind; the drifted pair #D0D4DA vs #CED4DA — visually identical borders that are technically two values, so any generation rule targeting "the border color" is ambiguous; three card components for one job, one of them a personal WIP that half the team detached; five text styles with duplicate-but-differently-named entries ("Heading" vs "heading-2", "Body" vs "body copy"); no spacing system at all.

Rules-file plants (step 5 ground truth). Rule 5 references semantic tokens color.warning and color.danger that exist nowhere in the inventory — only a success-ish green pair exists; the AI invented a complete token family from convention. Rule 8 references Card/Hero with a "parallax variant" — no such component exists in any state; this is a pure hallucination that would send a generation tool inventing hero cards. Rule 9 blesses #F76707 as color.brand.secondary — it launders the stale pre-rebrand orange into an official accent token; accepting it re-institutionalizes the exact drift you were hired to remove. Rule 10 is the behavioral trap: "generate the closest match inline" is a standing instruction to produce look-alikes — the correct rule is the inverse (stop, use the nearest real component, and file the gap). Rules 1–4, 6, 7 are broadly sound after your rebuild exists — but note they referenced the target-state names before you built them, which is fine in a rules file only once the names are real.

Expected generation-proof results. With the corrected rules file and published exemplars, expect most elements on-system with one or two look-alikes (rating badges and avatar blocks are common misses — models draw them raw). A typical honest score is 70–90% on-system. The teachable miss: if your generated screen contains an orange that checks out as #F76707, rule 9 survived your audit.

Grading yourself. All four rules-file plants caught and a generation score computed with look-alikes counted honestly: excellent — you have both the artifact and the proof. Plants caught but generation not scored: run step 7; the score is what converts cleanup into a fundable argument. Rules file accepted as drafted: the hallucinated components and laundered color are now policy — recheck every AI-drafted config against ground truth before adoption, which is this lab's entire point.

Key Takeaway:

A design system is now documentation for two audiences — humans and generators — and it serves neither until names carry meaning, values live in tokens, exemplars are published, and the rules file contains nothing that does not actually exist.

© Anvi Innovate · BXUP — Be Exponentially Upskilled · BXUP is an independent learning platform, not affiliated with or endorsed by AWS, Microsoft, Google, NVIDIA, IBM, Salesforce, Databricks, Oracle or Anthropic. All trademarks belong to their respective owners. · bxup.in