Design System Architecture AGENTS.md Template

Overview

Direct answer: This AGENTS.md Template defines a project-level operating context for a design system architecture workflow. It coordinates AI coding agents across design tokens, component governance, accessibility validation, and multi-agent handoffs, enabling both single-agent and multi-agent orchestration with clear memory, source-of-truth, and escalation paths.

The template provides concrete roles, rules, and project structure so teams can paste it into AGENTS.md to drive design-system work with AI agents, ensuring consistency from token design to docs and release processes.

When to Use This AGENTS.md Template

• Model a design-system architecture that relies on AI coding agents for tokens, components, and docs.
• Coordinate token governance, component library changes, and accessibility checks across multiple agents.
• Enforce clear handoffs, memory, and source-of-truth for design-system tasks.
• Establish governance, security, and escalation rules before starting an AI-driven rollout.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Design System Architect (DSA) – Responsible for overall design system topology and governance across tokens, components, and docs.

Agent roster and responsibilities:
  - Planner/Orchestrator: schedules tasks, routes work between agents, maintains memory and source-of-truth, and escalates when policy is violated.
  - Architect: defines component library structure, naming conventions, and cross-platform contracts.
  - TokenManager: maintains design tokens, units, scales, and token-merge policies.
  - AccessibilityAgent: validates WCAG/ARIA conformance against component specs.
  - DesignerAgent: translates designs into component specs and token mappings.
  - DocumentationAgent: creates and updates docs, release notes, and usage guides.
  - Reviewer: performs quality checks and approves changes before production.
  - ResearchAgent: gathers standards, guidelines, and best practices.

Supervisor/Orchestrator behavior:
  - The Planner coordinates all tasks, enforces memory integrity, and enacts escalation rules for blocked or high-risk changes.
  - All agents operate under a single source of truth (design-system-repo) and must log changes via the Planner.

Handoff rules between agents:
  - Planner assigns tasks to Architect or TokenManager; Architect provides structure and tokens; TokenManager updates tokens and notifies DesignerAgent for integration; DesignerAgent implements designs and tokens into components; Reviewer validates before Docs and Release.
  - Handoffs require a versioned commit with a changelog entry and a PR review approval.

Context, memory, and source-of-truth rules:
  - Central memory store: design-system-memory.json in the repo; sources of truth: design-system-repo, token-api, and component specs.
  - All agents must read from and write to the same memory store; no local undocumented state.

Tool access and permission rules:
  - Tools allowed: DesignTokensAPI, ComponentRepoEditor, DocsGenerator, AccessibilityChecker, PRManager, SecretsVault.
  - Agents may not delete history; any modification must go through PRs and approvals.

Architecture rules:
  - Use a mono-repo with clear token-to-component contracts and versioned component APIs.
  - Tokens flow must be backward-compatible; breaking token changes require a migration plan.

File structure rules:
  - Design-system-root/
  - tokens/
  - components/
  - docs/
  - orchestration/
  - tests/
  - memory/

Data, API, or integration rules:
  - All integrations must expose read-only public endpoints unless write access is granted by Planner.
  - Token changes trigger a build and a token-usage validation pass before release.

Validation rules:
  - Validate token shapes, naming conventions, and versioning; ensure accessibility checks pass; ensure docs reflect changes.

Security rules:
  - Never expose secrets in memory; use SecretsVault; all secrets must be injected at runtime.
  - All changes are auditable via PR history and memory logs.

Testing rules:
  - Unit tests for token validation; integration tests for token-to-component mapping; end-to-end tests for docs and release flow.

Deployment rules:
  - Changes must pass CI, be merged to main via PRs, and deploy to staging before production.

Human review and escalation rules:
  - Any token breaking change requires design lead approval; high-risk changes escalate to engineering leadership.

Failure handling and rollback rules:
  - Roll back to previous design-system memory snapshot; revert PR; notify planners.

Things Agents must not do:
  - Do not bypass approvals; do not modify the production tokens without reviewer sign-off; do not drift from the source of truth.
  - Do not perform unsanctioned migrations or bypass design-system governance.

Recommended Agent Operating Model

The operating model assigns clear responsibilities and decision boundaries for each role. The Planner coordinates, the Architect designs topology, the TokenManager administers tokens, and the DesignerAgent translates designs into component specs. Escalations route to a human reviewer when risk thresholds are exceeded. Multi-agent orchestration emerges from validated handoffs and a shared memory store, ensuring predictable outputs and traceable decisions.

Recommended Project Structure

design-system-architecture/
├── agents/
│   ├── planner/
│   ├── architect/
│   ├── token-manager/
│   ├── accessibility/
│   ├── designer/
│   ├── reviewer/
│   └── researcher/
├── orchestrator/
├── tokens/
├── components/
├── docs/
├── tests/
└── memory/

Core Operating Principles

• Operate with a single source of truth and a verifiable memory log.
• Handoffs must be explicit and auditable with versioned changes.
• Governance and security are integral, not afterthoughts.
• Decisions must be contestable and escalatable to human review when risk is detected.
• Minimize duplication and avoid context drift across agents.

Agent Handoff and Collaboration Rules

Agent collaboration patterns:

• Planner assigns tasks to Architect and TokenManager with dependency-based sequencing.
• Architect delivers component topology and token contracts; TokenManager updates tokens and pushes to Designer.
• Designer implements visuals and tokens into components; Reviewer and Accessibility validate before Docs and Release.
• Researchers periodically refresh standards and feed changes to Planner for scheduling.

Tool Governance and Permission Rules

• Command execution and file edits require Planner approval and PR-based changes.
• API calls to production services are restricted; use sandbox/test endpoints unless production scope is explicitly approved.
• Secrets must be retrieved from a vault; never hard-code credentials.
• All changes must pass security checks and be reviewed before deployment.
• External services require documented approvals and access controls.

Code Construction Rules

• Code must be modular, well-documented, and aligned to design-system contracts.
• Follow token naming conventions and semantic versioning for all changes.
• Tests must cover unit, integration, and end-to-end scenarios for tokens and components.
• Documentation must reflect any design-system changes and usage guidance.

Security and Production Rules

• Protect secrets; rotate keys regularly; use secure vaults.
• Limit production access; require approvals for any production changes.
• Audit logs must be retained for all agent actions.

Testing Checklist

• Token validation tests pass for all token changes.
• Component mapping tests verify token-to-component integrity.
• Accessibility tests pass for updated components.
• Docs generation tests reflect the latest changes.
• CI validates all tests before deployment.

Common Mistakes to Avoid

• Bypassing the Planner or governance gates.
• Allowing context drift between agents or memory stores.
• Making unsupervised production changes without escalation.
• Duplicating work across tokens, components, and docs without one source of truth.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is the purpose of this AGENTS.md Template for Design System Architecture?

This AGENTS.md Template standardizes how AI coding agents operate within a design-system workflow, ensuring token, component, and docs governance with clear handoffs and escalation rules.

Which roles are included in the agent roster for this workflow?

The roster typically includes Planner/Orchestrator, Architect, TokenManager, AccessibilityAgent, DesignerAgent, Reviewer, DocumentationAgent, and ResearchAgent to cover design tokens, components, accessibility, and docs.

How are handoffs between planner, architect, and token manager managed?

Handoffs occur via versioned commits with changelogs and PR reviews. The Planner assigns tasks, Architect defines structure, TokenManager updates tokens, and subsequent agents implement the change.

What safety and governance rules govern tool access and production changes?

All tool calls must be authenticated, secrets kept in vaults, and production changes require approvals and traceability via PRs and audit logs.

What should trigger human review or escalation?

Escalation triggers include security risks, major design-system changes, or failed validation tests in tokens, components, or accessibility checks.