Spring Design Library — AI Agentic Workflow Overview

Audience: Engineering and design-system leadership
Purpose: Introduce the outcome-first agentic workflow — roles, guardrails, rules, and skills
Format: Copy-ready for Google Docs (tables, diagram, ~4–6 pages)

---

1. Executive Summary

Problem: Design-to-code work was inconsistent — wrong file targets, missing validation, duplicate components, and unclear handoff to product engineers.

Approach: An outcome-first workflow where AI agents classify every request before coding, reuse existing package and gallery patterns, stop for human approval when structure is uncertain, and close with named validation.

Benefit: Predictable placement in the monorepo, gallery routes as visual source of truth, and reviewable handoffs instead of opaque code dumps.

Most work starts from a ready Figma file. UX persona documentation is optional and used only for target-user variants or vibe-coded refinements.

---

2. How Work Flows (End-to-End)

Paste this diagram into Google Docs (Drawings, mermaid.live, or Lucidchart):

flowchart TD
  request[InboundRequest] --> classify[ClassifyOutcome]
  classify --> context[ContextCheck]
  context -->|"missing info"| askUser[AskUser]
  context -->|"ready"| investigate[InvestigateReuse]
  investigate --> plan[BuildPlan]
  plan --> gate[HumanApprovalGate]
  gate -->|"changes"| plan
  gate -->|"approved"| build[Implement]
  build --> inject[UpdateExportsRoutesNav]
  inject --> validate[ValidateLintBuild]
  validate -->|"fail max 3 loops"| correct[SelfCorrect]
  correct --> build
  validate -->|"blocked"| escalate[EscalateToHuman]
  validate -->|"pass"| handoff[DeveloperHandoff]

Caption: Every task starts with what we are building (outcome type), not with code. Humans approve the plan when new components, tokens, routes, or structural changes are involved. Validation (lint, build, token sync, etc.) must pass before handoff.

---

3. Seven Outcome Types (Cheat Sheet)

Key principle: One request = one classified outcome. Mixing outcomes (e.g. new component + token change + nav) triggers the approval gate.

---

4. Five Agent Roles

These are logical roles — one AI session may play several, but responsibilities stay separate.

Human touchpoints

• Plan approval before implementation when structure, new components, tokens, routes, or registries are uncertain.
• Token approval for any change to design-tokens.mjs.
• UX deviation approval when the agent proposes changes beyond supplied Figma.
• Escalation after 3 failed validation loops — agent stops with a blocker report.
• Resume after interruption — agent re-states phase, approval status, and changed files before continuing.

---

5. Three Layers: Docs vs Rules vs Skills

Analogy: Docs = policy manual; Rules = lint rules in the editor; Skills = runbooks ("how to ship an AppFlow screen").

---

6. Cursor Rules Reference (All 5)

---

7. Project Skills Reference (2)

spring-agentic-workflow — default for design-to-code work

• Triggers: components, gallery pages, AppFlow, Code Connect, tokens, repo structure
• Requires: outcome classification, build plan, validation commands, handoff artifacts

spring-ux-variant — optional, not default

• Triggers: persona variants, vibe-coded screens, copy/tone, drop-off, declined/success states, AppFlow logic review
• Sources: docs/ux/user-insights-report.md, ux-strategy-logic.md, personal-loans-flow.md
• When NOT used: complete Figma provided with no UX variation requested

Default path: Figma + existing patterns + workflow contracts.
UX skill path: Only when we need persona-specific variants or UX judgment beyond the approved design.

---

8. Quality Gates and Handoff

Before delivery, agents check

• Outcome matches files changed (docs/ai/review-checklist.md)
• Required injection points updated (exports, nav, registry, Code Connect, tokens)
• Commands run: typically npm run lint, npm run build; plus tokens:sync / code-connect:parse when relevant

Handoff package includes

• Outcome type and workflow phase
• Files changed + route/import path (/library/* for visual review)
• Validation results and any skipped checks
• Risks or pre-existing repo issues affecting confidence

Gallery as source of truth

Product engineers consume @spring/ds-react components and bind real data/APIs outside the gallery; /library/* is the approved visual reference.

---

9. Optional UX Knowledge Base (Injectable, Not Always On)

---

10. What We Do Not Automate

• Production API, analytics, database, or partner integrations in gallery or AppFlow previews
• Token changes without explicit approval
• Overriding an approved Figma design unless the user requests UX refinement
• Persisted workflow state files (.spring/) in normal Cursor sessions — resume relies on conversation and documented handoff state

---

11. Appendix — Deep Links for Engineers

Doc hub: docs/README.md

---

Last updated: June 2026. Copy into Google Docs; add title page and date; export the diagram from mermaid.live if needed.