# Design system task contract
## 1. Role and outcome
You are acting as [design-system role].
Your single task is to [generate a new visual system | apply an existing system | document an existing implementation].
Intended outcome: [observable outcome].
## 2. Authority
Authoritative source: [approved document, kit, repository record, or decision set]
Source identity: [stable name or identifier]
Source revision: [version, date, commit, or content hash]
Approving owner: [person or role]
Treat references, screenshots, mood boards, existing UI, and this prompt as inputs only unless explicitly named above as authoritative. If supplied sources conflict, report the conflict and stop the affected work. Do not choose silently.
## 3. Audience and named consumer
Primary audience: [people who will use the system]
Named consumer: [application, repository, page, flow, component, or design file]
Representative surface: [one bounded surface]
Current stack: [framework, styling system, component library, token format, design environment]
Supported conditions: [light, dark, viewport, locale, density, interaction states]
## 4. Scope
In scope:
- [decision or deliverable]
- [decision or deliverable]
Non-goals:
- [excluded work]
- [excluded work]
Preserve:
- [approved component behavior]
- [application-owned permissions, validation, data flow, content, or accessibility mechanism]
- [existing mechanism outside this design task]
## 5. Known visual decisions
Color roles: [semantic light and dark roles, or source reference]
Typography: [families by role, available weights, scale, line-height and tracking rules]
Spacing and density: [scale and contextual rules]
Layout: [grid, widths, hierarchy, responsive rules]
Shape and elevation: [radius, borders, shadows]
Motifs and imagery: [allowed treatments, assets, restrictions]
Component states: [default, hover, focus, disabled, loading, error, empty, selected, open]
Intentional exceptions: [approved exceptions and scope]
Do not turn an unspecified value into a permanent system decision.
## 6. Unresolved decisions
For every unknown, record:
- Question
- Affected output or consumer
- Owner
- Blocking or non-blocking status
- Safe interim behavior: preserve current behavior, omit output, or use an explicitly temporary value
Prohibited assumptions:
- Do not invent brand rules, component APIs, assets, product behavior, permissions, breakpoints, accessibility claims, or test results.
- Do not infer approval from an attractive reference or existing implementation.
- Do not replace application policy with visual-system guidance.
## 7. Artifact routing
Intent, rationale, usage rules, and prohibitions: [DESIGN.md or equivalent]
Exact reusable values and aliases: [DTCG, CSS variables, or canonical token document]
Framework mappings: [Tailwind theme, shadcn registry, CSS, or target file]
Reusable structure and state behavior: [component contract or implementation]
Files and usage restrictions: [asset location plus guidance]
Application behavior and policy: [application-owned specification or code]
Undecided matters: [open-decision record]
For every repeated fact, name the authoritative representation and the derived or reviewed representations.
## 8. Workflow
1. Inspect the authoritative source and current consumer.
2. List conflicts, missing decisions, and blocked outputs.
3. Ask only questions that block the bounded task.
4. Propose a short plan naming artifacts to read, create, or change.
5. Preserve approved mechanisms and unrelated behavior.
6. Make the smallest complete change for the named consumer.
7. Stop if authority, required evidence, or permission is missing.
8. Verify the representative cases below.
## 9. Required response
Return:
- Source identity and revision used
- Task mode and named consumer
- Artifacts inspected, created, or changed
- Output identity for every generated artifact: path plus version, hash, or revision
- Authority and precedence notes
- Assumptions made
- Unresolved decisions and owners
- Expected and observed results for executed acceptance cases
- First divergent layer for every mismatch
- Final disposition: accept, revise, or block
Never mark an unexecuted check as passed.
## 10. Acceptance cases
For each relevant case, record:
- Component or surface
- State, mode, viewport, and representative content
- Expected observable result
- Observed result, or not executed
- Evidence identity
- First divergent layer, if any
- Disposition: accept, revise, block, or not executed
- Owner
- Retest triggerUse one task mode per run
Use separate runs to invent a visual system, integrate it into a product, and document the finished implementation. Each job needs different evidence and produces different outputs. When one run covers all three, a later file may look approved even though it merely repeats a choice the agent invented.
Choose the task mode before filling the prompt
The template covers three related jobs. Generation proposes visual decisions. Application maps approved decisions into a named consumer. Documentation describes an implementation that already exists. All three keep the authority fields because the agent still needs to know which facts it may rely on and which gaps must stay open.
| Generate a system | Apply a system | Document an implementation | |
|---|---|---|---|
| Starting authority | Approved brief, constraints, and existing brand decisions | Versioned design system or kit plus the current consumer | Versioned implementation, approved decisions, and observed behavior |
| Main output | Proposed system artifacts and an explicit decision record | Mapped project artifacts and a bounded consumer change | Documentation tied to actual variants, states, and implementation identity |
| Agent may decide | Only choices delegated by the brief | Mappings that follow approved precedence and component contracts | Organization and wording that do not alter behavior |
| Agent must not decide | Missing product policy, permissions, or undelegated brand choices | New visual authority, product behavior, or silent exceptions | Features, states, or guarantees absent from the implementation |
| Acceptance evidence | Proposal completeness and unresolved choices, not product adoption | Artifact identity, project mapping, and observed consumer states | Documentation checked against the named implementation and states |
Choose generation only when the visual direction is open and someone has authority to approve the proposal. Choose application when the system is approved and needs to enter a project without drift. Use documentation when the implementation already exists and readers need an accurate contract. If the work crosses modes, complete and approve one record before starting the next.
A screenshot can inspire a direction, but it can't establish token names, supported states, component behavior, or permission rules. An existing interface is ambiguous too. It may contain an approved exception, an old implementation, or an accidental local value. Name an authoritative source and revision before describing the desired style.
A source name alone isn't reproducible. Record a version, date, commit, or content hash. If the source changes later, its recorded revision tells a reviewer which decisions the agent received and whether the output needs another pass.
- Name one authority for each decision instead of calling every supplied file a source of truth.
- List unresolved choices with an owner and blocking status rather than inviting the agent to fill the gaps.
- State prohibited assumptions in terms of real risks, such as invented component APIs, assets, policies, or test results.
- Record non-goals so a focused styling task doesn't quietly become a component rewrite.
- Preserve application-owned validation, permissions, data flow, content, and recovery behavior unless changes are explicitly authorized.
A current implementation is evidence, not automatic authority
Existing code tells the agent what the product does today. It doesn't prove that every local value or detached component is approved. Record whether the implementation is authoritative, a consumer to be mapped, or evidence to reconcile.
Describe visual decisions as roles and constraints
A design prompt is fragile when it relies on adjectives such as clean, premium, or modern. Replace them with decisions an agent can locate and inspect: semantic color roles in both modes, typography roles and available weights, spacing relationships, layout constraints, component states, asset rules, and deliberate exceptions.
The prompt doesn't need to repeat every raw value. It can point to a versioned token document for exact values while naming the roles and conditions relevant to the task. For a button, that may include default, hover, focus, disabled, and destructive treatment. For a dashboard, it may cover light and dark surfaces, data typography, dense tables, empty states, and narrow containers.
Token specimen · real values
Ambient Sage
Live renderAmbient Sage's actual tokens — the same values its exports use.
Record limits and prohibitions too. If an accent is reserved for primary actions and focus rings, say so. If shadows are excluded, record that constraint. These rules narrow the available choices and make drift easier to spot.
Route each decision to the artifact that can carry it
One file can't carry every kind of authority. Written guidance, structured values, framework mappings, component behavior, and application policy make different promises. Route each one separately, then define precedence wherever the same fact must appear in more than one place.
| What it carries | Suitable carrier | Boundary | |
|---|---|---|---|
| DESIGN.md | Intent, rationale, selection rules, layout guidance, motifs, usage constraints, and prohibitions | A written brief or equivalent guidance artifact | Not the only copy of exact reusable values, application permissions, or proof of consumer adoption |
| Token document | Canonical reusable values, semantic roles, aliases, modes, and exchange metadata | DTCG, CSS variables, or another structured token representation | Not page composition, component behavior, or prose a resolver cannot enforce |
| Framework mapping | Target-specific translation of approved roles and values | Tailwind theme entries, shadcn variables, CSS mappings, or equivalent output | Must not hide new upstream design decisions inside a generated target file |
| Component contract | Supported structure, variants, content rules, interaction states, and reusable behavior | A component specification or shared implementation | Not application-specific permissions, business rules, or data policy |
| Application policy | Permissions, validation, side effects, data ownership, confirmation, and recovery rules | Application requirements, policy, and implementation code | Not portable brand intent or shared visual values |
| Open-decision record | Unknowns, conflicts, decision owners, blocking status, and safe interim handling | A versioned issue, decision log, or project record | Must not present guesses as approved system rules |
In this table, the row label identifies the layer. The first column states what it carries, the second names a suitable carrier, and the third marks its boundary. When a semantic value appears in canonical tokens, generated CSS, and a Tailwind mapping, the prompt should name the token document as authoritative and the others as derived outputs.
When a component state combines visual treatment with application behavior, split the responsibility. The design system can govern focus appearance. The application still decides whether an action is permitted and what happens when it runs.
Start from a real system, then check the consumer separately
Browse a public kit when you need versioned visual input for the contract. Treat the kit as upstream design evidence, then record your project's mapping and observed result.
Give the agent a bounded workflow
The contract should control the sequence as well as the deliverables. Ask the agent to inspect the current source and consumer, report conflicts, ask only blocking questions, and propose a short plan before editing. This brings stale files and missing authority into view before generated output buries them.
- Inspect the named source revision and the smallest set of consumer artifacts needed for the task.
- Report contradictions, missing states, unavailable assets, and undecided behavior.
- Ask only questions whose answers block the named output. Record other unknowns without guessing.
- Name every artifact to create or change and every approved mechanism that must be preserved.
- Produce one complete result for the representative surface without expanding into adjacent consumers.
- Record artifact identities, project mappings, executed checks, observations, mismatches, owners, and retest triggers.
Make stopping useful
A stop condition should produce a record, not a dead end. Ask the agent to name the missing authority or evidence, identify the affected output, record what can proceed safely, and assign the next decision to an owner.
Worked input: Ambient Sage without invented results
This example uses only facts verified on the public Ambient Sage kit page. It's intentionally incomplete. The example shows how to turn a real design-system artifact into bounded prompt input without claiming that files were generated, mapped into a project, or observed in a consumer.
Task mode: apply an existing system
Authoritative visual source: Ambient Sage public kit
Source identity and revision: ambient-sage, v1
Named consumer: [project and representative page or component]
Current stack: [fill from the real project]
Verified visual input:
- Heading role: Plus Jakarta Sans, available weights 400, 500, 600, 700
- Body role: Plus Jakarta Sans, available weights 400, 500, 600, 700
- Mono role: JetBrains Mono, available weights 400, 500, 700
- Typography scale: compact-product
- Color system: 28 semantic tokens covering light and dark roles
Still unresolved:
- Exact project files and mappings
- Font loading and fallback policy
- Required component states for the named consumer
- Application-owned behavior and accessibility requirements
- Generated artifact identities
- Rendered observations
Current disposition: block until the named consumer, stack, acceptance cases, and owners are filled. Do not report generated, mapped, or observed states as complete.The block disposition is correct here. A kit can supply visual decisions and delivery artifacts. It can't identify application files, confirm project mappings, or observe the finished consumer without a real target and an executed check.
Use compact variants without dropping the contract
Once a project has a full contract, later prompts can be shorter. Keep the authority, consumer, scope, unresolved decisions, output identity, and acceptance fields. Change only the mode-specific center of the request.
Coding-agent implementation variant
Apply [source identity and revision] to [named consumer]. Preserve [application-owned behavior and approved mechanisms]. Map [named roles] through [target artifacts]. Do not invent missing tokens, components, assets, breakpoints, or policy. Before editing, report conflicts and blocking unknowns. After editing, return changed artifact identities, project mappings, representative state observations, first divergence for any mismatch, owners, retest triggers, and an accept, revise, or block disposition.Documentation variant
Document [implementation identity and revision] for [audience]. Treat the implementation and approved decision record as separate sources with this precedence: [rule]. Describe only supported variants, states, usage rules, constraints, and observed behavior. Mark conflicts and undocumented behavior as unresolved. Return inspected files, documentation identity, claims still needing verification, owners, and acceptance cases used to compare the documentation with the implementation.Design-environment variant
Using [authoritative source and revision], create or update [named design file, library, or component set] for [consumer]. Preserve approved variables, components, assets, and intentional exceptions. Do not treat generated frames as new system authority. Record every created or changed artifact, unresolved decision, local exception, and representative state reviewed. Separate expected results from observed results and finish with an accept, revise, or block disposition.Verify one named consumer, not the prompt in isolation
A well-structured response can still produce the wrong interface. Verification must connect the prompt revision to a generated artifact, the artifact to a project mapping, and the mapping to an observed component or surface. Preview quality is useful feedback, but it doesn't establish that the product loads the intended artifact or preserves the required states.
# Named-consumer acceptance record
Prompt identity and revision: [identifier]
Authoritative source identity and revision: [identifier]
Task mode: [generate | apply | document]
Named consumer: [project, surface, flow, or component]
Environment: [framework, browser or design tool, viewport, mode, locale]
Generated or reviewed artifacts:
- [path or artifact name]: [version, hash, or revision]
Project mapping:
- Source role or rule: [identifier]
- Delivered artifact location: [path]
- Consumer mapping: [component property, variable, style, or import]
- Mapping status: [confirmed | missing | conflicting | not inspected]
Representative case:
- Component or surface: [name]
- State and condition: [state, mode, viewport, content]
- Expected result: [observable result written before inspection]
- Observed result: [observation or not executed]
- Evidence: [inspection, computed value, screenshot identity, or test]
- First divergence: [source | generated artifact | delivery | project mapping | component | local exception | environment | none found | unknown]
- Disposition: [accept | revise | block | not executed]
- Owner: [person or role]
- Retest trigger: [specific change]
Overall disposition: [accept | revise | block]
Reason: [evidence-based explanation]
Open decisions: [items with owners]Use accept when the bounded consumer matches the recorded expectations and all required evidence exists. Use revise for a specific, correctable mismatch with clear authority. Use block when a required path fails, authority is missing, artifacts conflict, or the result can't be traced far enough to support a decision.
What this record does not prove
One accepted consumer doesn't approve every page, framework, mode, locale, or agent. It proves only the source, artifact, mapping, state, environment, and observation recorded in that case. Expand the test set according to the risk introduced by the next change or consumer.
Run the smallest useful first test
Fill the authority fields. Choose one task mode and one representative component or page. Include an ordinary state and another likely to expose drift, such as focus, disabled, error, dark mode, or a narrow viewport. Run the prompt, record what the consumer actually does, and revise the contract before applying it more broadly.
Reuse the prompt only when another reviewer can identify the governing source, reproduce the artifact mapping, inspect the same cases, and understand why the result was accepted, revised, or blocked. Next, fill the authority fields and run one representative case.
Sources
- Prompts | Carbon Design System: Carbon's prompting guidance supports stating the UI purpose, implementation framework, required libraries, clarification needs, and plan before implementation.
- Creating ChatGPT prompt templates for Design System Documentation: The captured guide demonstrates a reusable documentation prompt built from an assigned role, required sections, and design-system-specific context.
- System Prompt Design: A Production Guide and Template: The guide presents prompts as structured specifications with role, context, task, boundaries, output requirements, edge cases, and testing.
- Design Prompts: The captured workflow lets a user choose a page template and visual direction, preview the result, and pass a generated prompt to a coding agent.
- Ambient Sage Design Kit: The public Ambient Sage kit uses Plus Jakarta Sans for heading and body roles, JetBrains Mono for technical strings, and 28 semantic light and dark color tokens.
- DESIGN.md vs design tokens: choose authority and prevent drift: The guide distinguishes reusable values in tokens, intent and usage rules in DESIGN.md, and structure and behavior in component contracts.
- AI UI review checklist: The checklist separates design authority, delivered artifacts, project mapping, required states, observed behavior, and release disposition.
- Brand guidelines as code: structure authority, outputs, and verification: The guide explains that generated artifacts and delivery routes do not prove adoption, which must be checked in a named consumer.