Behavioral Annotation Kit
A Figma component system for specifying AI behavioral contracts at the UI layer. Nine annotation components, six pattern stamps, and a 19-token vocabulary — designed to make behavior as specifiable as color or typography.
- Components
- 9
- Pattern stamps
- 6
- Behavior tokens
- 19
- Handoff screens
- 2
Design systems tell AI how to build. Not how to behave.
Existing design systems — Material, Carbon, Polaris — specify visual and structural decisions. They tell AI systems what to render. They say nothing about what a system must do at moments of ambiguity, consent, or failure.
The Emote Annotation Kit fills that gap. It gives designers a component vocabulary for annotating behavioral obligations directly on UI frames — in Figma, alongside the visual spec, as part of the handoff package.
The result: engineers and AI systems receive not just a mockup, but a behavioral contract. What the system must do. Which pattern governs it. Which tokens apply. What happens if it fails.
Nine annotation components
Labels a frame or section with its governing Emote pattern (P01–P06). The primary way to link UI to behavioral spec.
Pins a specific behavior token to an element. Monospace, blue — visually distinct from the UI being annotated.
Explains the behavioral obligation in plain language. Answers “what must the system do here and why.”
Flags a moment where trust is at risk — ambiguity, consent, or repair. Forces explicit design attention.
Marks where behavioral coverage is absent or incomplete. Makes gaps visible rather than assumed away.
Attaches a compliance status to a frame: Specified, Partial, or Unspecified. Useful for audit and review.
Documents what happens when a behavioral contract cannot be fulfilled — the safe fallback path.
Inline variant of the GapMarker. Tags a specific element rather than a frame section.
Inline variant of the PatternStamp. For labeling individual elements rather than whole frames.
277 variables. Three tiers.
Every component property in the annotation kit is backed by a Figma variable. The system uses a three-tier token architecture — the same pattern used in production design systems like Material Design 3 and Polaris.
Primitive color scales (indigo, emerald, amber, slate) and raw typographic values. These are never used directly in components.
color/indigo/500, color/emerald/300
Semantic tokens that map primitives to roles. Type sizes, spacing scales, and color roles that apply across components.
type/size/mono-sm, type/size/body-base
Component-specific tokens. Every visual property of every annotation component — color, spacing, radius, stroke — is a named variable.
token-tag/bg, token-tag/border, token-tag/radius
This architecture means component appearance can be globally updated by changing Brand or Alias tokens — without touching individual components. It also means the system is themeable: swap the Brand layer and every component updates consistently.
The Mapped tier is what makes design-to-engineering handoff precise. When an engineer sees token-tag/border in the spec, they know exactly which value to implement — and when it changes, they know exactly where to change it.
The annotation in practice
The AI Handoff screen shows the annotation kit applied to a real product surface: the Veridian Health provider credentialing dashboard, a high-stakes workflow where providers initiate bulk renewals.
The frame is annotated with P01 (Expectation Setting) and P02 (Ambiguity Detection) stamps, TokenTags for the specific behavior tokens in play, TrustMomentCallouts flagging the consent confirmation step, and a BehaviorCallout explaining the safe failure path if consent cannot be obtained.
Alongside the annotated mockup: a JSON contract block showing exactly how this spec translates into a system prompt. The handoff is the spec, and the spec is machine-readable.
Veridian Health · Provider credentialing dashboard · Annotated with P01 + P02 patterns
Why it’s built this way
Annotation vs. UI
Every component is designed to be visually separable from the product UI it annotates. Color, typography, and stroke weight are all calibrated to read as “make an annotation layer” not “make a product component.” This matters in handoff — engineers need to immediately distinguish spec from screen.
Token vocabulary as the connective tissue
The 19-token vocabulary (behavior.pause_when_uncertain, behavior.verify_consent, etc.) appears across the annotation kit, the pattern spec, and the system prompt. Using the same names everywhere means a designer, an engineer, and an AI model are all working from the same contract — not three different interpretations of the same intent.
Gaps are first-class citizens
Most annotation systems only document what’s present. GapMarker and GapMarkerTag exist to document what’s absent. In AI systems especially, undocumented behavior is a trust risk — so gaps need to be marked, not ignored.
Handoff as a behavioral contract
The AI Handoff screens aren’t just mockups with annotations. They include a JSON contract block showing exactly how the behavioral spec translates to a system prompt. The handoff is the spec, and the spec is machine-readable.
Available on Figma Community
The Emote Design System is published to the Figma Community under MIT license. Import it into any file and start annotating behavioral obligations alongside your existing design system components.