Documentation
Install CogWheel, seed the demo set, and author cognitive tokens that define how an AI product looks, speaks, and behaves.
Install the plugin
- Clone github.com/jit170621/Cogwheel.
- Run
npm install then npm run build in the repo root. - In Figma: Plugins → Development → Import plugin from manifest… and select
manifest.json. - Run Cognitive Tokens. Use Seed full set on the home screen to load the demo pack.
- For local development, run
npm run build:watch and reload the plugin after changes.
Every token needs a dot-notation name, a typed value, a description, at least one consumedBy consumer, and at least one mode. If it cannot name who consumes it, it is not a token yet — it is an idea.
Token schema
Every token shares one shape — name, type, value, description, consumers, modes, and status — whether it is a colour or a guardrail.
Plugin data + Figma Variables (by category)UIorchestrationbackendTTS/STTavataranalytics
How to configure
- Name tokens in dot.notation (e.g. latency.acknowledgmentDelay).
- Pick a type that matches the runtime value: color, number, duration, boolean, string, enum, ref, map, rule, or promptFragment.
- Fill description, consumedBy, and at least one mode (chat / voice / avatar).
- Status flows proposed → review → approved. Patch version bumps automatically on save.
Subcategories
Required fieldsname, value, description, consumedBy, modes
Status workflowproposed → review → approved
VersioningStarts at 0.1.0; patch bumps on each save
Example tokens
escalation.threshold
type rulevalue sentiment.frustration > 0.7 for 2 consecutive turns
Hands off to a human when frustration stays high.
Configure: Choose type rule, write the condition in plain language the orchestration layer can evaluate, set consumedBy to orchestration + backend.
Foundation
Pure scales and alias roles — hex and number live here; meaning lives in Semantic. Syncs to a Figma Variables collection named Cognitive Tokens.
Figma VariablesUI component library
How to configure
- Open Foundation in the sidebar and filter by Color, Typography, Spacing, Size, Opacity, Motion, Elevation, or Z-index.
- Create or edit a token — colour types sync as COLOR variables; numbers/durations as FLOAT.
- Use Seed full set on the home screen to load the full foundation ramp pack.
- Reference foundation names from Semantic (e.g. color.accent.default) instead of hard-coding hex twice.
Subcategories
ColorGray, accent, status, and dataviz ramps
TypographyFamilies, sizes, weights, tracking
SpacingScale plus chat-specific gaps
SizeControls, icons, avatars, layout widths
OpacityDisabled, hover, overlay washes
MotionDurations and easings in ms
ElevationShadows, radii, border widths
Z-indexStacking for menus, modals, toasts
Example tokens
color.accent.500
type colorvalue #0D99FF
Accent mid (brand).
Configure: Type color, paste hex or use the colour picker. Modes usually chat + voice + avatar.
borderWidth.hairline
type numbervalue 1
Default hairline border width.
Configure: Type number. Synced as a FLOAT variable under foundation/…
duration.enter
type durationvalue 200
Entrance motion (ms).
Configure: Type duration; value is milliseconds. Consumed by UI motion systems.
space.12
type numbervalue 12
Compact spacing step used by dense chat layouts.
Configure: Keep the space.* ramp consistent; Semantic density tokens should ref these.
Semantic
Meaning over raw values — surfaces, feedback, density, trust, and chat roles that alias Foundation. Also syncs to Figma Variables.
Figma Variables (refs → aliases)UI component libraryavatar renderer
How to configure
- Prefer type ref pointing at a foundation token (e.g. color.accent.default).
- Name by role, not by look: action.primary, state.thinking, chat.bubbleAgent.
- Filter by State, Action, Feedback, Chat, and other roles in the subcategory tabs.
- When you change a foundation colour, semantic refs update through Variables aliases.
Subcategories
Stateidle, listening, thinking, warning…
Actionprimary, danger, ghost interactive fills
Feedbacksuccess / warning / danger surfaces
ChatBubble and composer surface roles
Trust / confidenceCues for disclosure and certainty
Example tokens
action.primary
type refvalue color.accent.default → #0D99FF
Primary action fill.
Configure: Type ref, pick color.accent.default from the ref picker. Mode: chat.
action.danger
type refvalue color.danger.default → #D63B2F
Destructive action fill.
Configure: Keep danger refs pointed at the danger ramp so product-wide red stays consistent.
state.thinking
type refvalue color.accent.100
Agent is generating / thinking.
Configure: Avatar and chat UIs both consume this; include voice + avatar modes if needed.
Behavioral
What the agent does — timing, retry, escalation, turn-taking, and error recovery. Stored as plugin data (structured forms), not Variables.
Plugin data on figma.rootorchestrationbackend
How to configure
- Use duration for latency budgets (ms), boolean for barge-in, rule for escalation conditions.
- Set consumedBy to orchestration / backend so engineers know who reads the token.
- Seed includes defaults like latency.acknowledgmentDelay = 400ms.
- Export JSON when ready to hand off — these do not appear in Figma Variables.
Subcategories
TimingAcknowledgment and thinking delays
Retry / fallbackAttempts, backoff, fallback copy refs
EscalationThresholds, queues, triggers
Turn-takingBarge-in and silence
Error recoveryClarifying questions and paths
Example tokens
latency.acknowledgmentDelay
type durationvalue 400
Delay before the acknowledgment indicator appears.
Configure: Type duration, value in ms. Modes: chat (+ voice if shared).
interrupt.allowBargeIn
type booleanvalue true
Allow the user to interrupt the agent mid-turn.
Configure: Type boolean. Pair with voice audio.bargeInSensitivity for spoken modes.
escalation.targetQueue
type stringvalue support.tier1
Human queue for escalations.
Configure: Plain string matching your routing taxonomy.
error.maxClarifyingQuestions
type numbervalue 2
Cap clarifying questions before fallback or handoff.
Configure: Type number. Orchestration should hard-stop after this count.
Accessibility
Constraints enforced at author time — contrast, motion reduction, modality equivalence, and cognitive-load limits.
Mixed (Variables + plugin data)UIorchestrationcontent
How to configure
- Treat these as gates, not audits: products should fail authoring if they violate them.
- contrast.minimum defaults to 4.5; large text to 3.
- Set motion.reduceDefault and captioning.autoEnable for voice/avatar surfaces.
- readingLevel.max and response.maxLength keep copy cognitively light.
Subcategories
VisualContrast and motion defaults
Modality equivalenceCaptions and parity across modes
Cognitive loadReading level and response length
Example tokens
contrast.minimum
type numbervalue 4.5
Minimum contrast ratio for body text.
Configure: Type number (WCAG ratio). Consumed by UI lint / design QA.
motion.reduceDefault
type booleanvalue false
Prefer reduced motion unless the user opts into richer motion.
Configure: Wire to prefers-reduced-motion and product settings.
response.maxLength
type numbervalue 120
Soft cap on assistant response length (words or tokens — document which).
Configure: Align the unit with your prompt layer; keep description explicit.
Content
Persona voice, copy templates, and terminology — the product’s personality, versioned like any other token.
Plugin dataUIorchestrationTTS
How to configure
- Author greeting, refusal, handoff, and error copy as string tokens.
- Use enum for tone / formality registers.
- Terminology maps keep preferred vs banned wording in sync across surfaces.
- Modes matter: voice copy may differ from chat even when the intent is the same.
Subcategories
Persona voiceTone and formality registers
Copy templatesGreeting, refusal, handoff, errors
TerminologyPreferred and banned terms
Example tokens
copy.greeting
type stringvalue Hi — how can I help today?
Default first-turn greeting.
Configure: Type string. Keep short; pair with copy.greetingReturning for known users.
copy.refusal
type stringvalue I can’t help with that, but I can help with…
Out-of-scope refusal template.
Configure: Align wording with guardrail.refuseOutOfScope in AI Prompt.
copy.confirmDestructive
type stringvalue This can’t be undone. Do you want me to continue?
Confirm before destructive actions.
Configure: Consumed by UI dialogs and orchestration confirmation turns.
AI Prompt
Persona instructions, guardrails, composition, and model routing — prompt files become governed design-system assets.
Plugin dataorchestrationbackendmoderation
How to configure
- Use promptFragment for long-form persona / preamble text.
- Use rule for guardrails the model or router must obey.
- Model temperature and selection rules live beside the persona, not in a private doc.
- Export JSON and map into your prompt assembly pipeline.
Subcategories
Persona instructionBase instruction and boundaries
GuardrailsJailbreak, PII, out-of-scope
Prompt compositionPreamble and few-shot refs
Model routingSelection rules and temperatures
Example tokens
persona.baseInstruction
type promptFragmentvalue You are a calm, precise product assistant…
System persona preamble.
Configure: Type promptFragment. Large textarea in the editor. Modes: chat + voice.
guardrail.piiHandling
type rulevalue Never echo full SSN, card number, or…
PII redaction / refusal rule.
Configure: Type rule. consumedBy should include moderation + orchestration.
model.temperatureDefault
type numbervalue 0.3
Default sampling temperature.
Configure: Type number 0–2. Pair with model.temperatureCreative for generative turns.
model.selectionRule
type rulevalue Use fast model for FAQ/routing; use …
Router policy for model choice.
Configure: Keep human-readable; implement in your gateway.
Conversation
Memory, modality switching, and state machine rules that do not belong to any single surface.
Plugin dataorchestrationbackendavatar
How to configure
- Set memory.retentionScope (session / user / none) and turn caps.
- Define modality.switchBehavior so chat ↔ voice handoffs keep context.
- Encode the high-level state machine as a rule token.
- Timeout behaviour should return the agent to a safe idle state.
Subcategories
MemoryRetention scope and summarization
Modality switchingPreferred mode and switch rules
State machineidle → listening → speaking…
Example tokens
context.maxTurnsRetained
type numbervalue 12
Max turns kept in active context.
Configure: Type number. Orchestration truncates or summarises beyond this.
memory.retentionScope
type enumvalue session
Where conversational memory lives.
Configure: Type enum: session | user | none.
state.machineDefinition
type rulevalue idle → listening|thinking → speaking…
Allowed state transitions.
Configure: Document transitions clearly; avatar + voice both depend on this.
Voice / Audio
Voice identity, prosody, and turn-taking audio thresholds for spoken experiences.
Plugin dataTTSSTTorchestration
How to configure
- Set voice.id to your TTS voice key (e.g. alloy).
- Prosody tokens control pause and emphasis mapping into Semantic colours/states.
- audio.bargeInSensitivity (0–1) tunes interrupt detection with interrupt.allowBargeIn.
- Always mark mode voice on these tokens.
Subcategories
Voice identityid, pitch, speed
ProsodyPauses and emphasis mapping
Turn-taking audioBarge-in and silence thresholds
Example tokens
voice.id
type stringvalue alloy
TTS voice identity key.
Configure: Type string matching your TTS catalogue.
voice.speed
type numbervalue 1
Speech rate multiplier.
Configure: Type number; document the allowed range in description.
audio.bargeInSensitivity
type numbervalue 0.55
Sensitivity for detecting barge-in (0–1).
Configure: Subcategory Turn-taking audio. consumedBy: orchestration, stt, tts. Mode: voice.
prosody.pauseDuration
type durationvalue 200
Default pause between phrases (ms).
Configure: Type duration. Consumed by TTS / prosody engine.
Avatar
Expression mapping, gesture triggers, and render quality for generative avatars.
Plugin dataavatar rendererorchestration
How to configure
- Map expressions to Semantic state refs (idle, listening, thinking, warning).
- Gesture triggers are rule tokens describing when to wave, nod, etc.
- renderQuality enum (low / medium / high) lets runtime pick a fidelity tier.
- Mode should include avatar; often also chat when the face coexists with transcript.
Subcategories
Expression mappingidle / listening / thinking / warning
Motion / gestureIdle loops and gesture triggers
RenderingLip-sync model and quality
Example tokens
avatar.expression.listening
type refvalue state.listening → #0D99FF
Listening expression cue.
Configure: Type ref → Semantic state.listening.
avatar.gestureTriggers
type rulevalue On greeting → wave; on success → nod…
When to fire gestures.
Configure: Type rule. Keep triggers aligned with Behavioral and Content events.
avatar.renderQuality
type enumvalue medium
Default render fidelity.
Configure: Type enum: low | medium | high.
Governance
Moderation, human handoff, and compliance profiles that keep the product safe and accountable.
Plugin datamoderationorchestrationbackendanalytics
How to configure
- Set moderation.contentFilterLevel (strict / standard / permissive).
- Encode handoff triggers as rules; set SLA targets as durations (ms).
- compliance.regulatoryProfile enums (gdpr, hipaa, soc2) drive logging retention.
- Pair with Telemetry confidence thresholds for automatic escalation.
Subcategories
ModerationFilter level and sensitive topics
Human handoffTriggers and SLA
ComplianceProfiles and audit retention
Example tokens
moderation.contentFilterLevel
type enumvalue standard
Default content filter strength.
Configure: Type enum. consumedBy: moderation.
handoff.slaTarget
type durationvalue 300000
Target human response SLA (ms).
Configure: 300000 = 5 minutes. Document the unit in the description.
compliance.regulatoryProfile
type enumvalue gdpr
Active regulatory profile.
Configure: Affects audit.logRetention and logging pipelines.
Telemetry
Success metrics, confidence thresholds, and latency budgets the runtime uses to evaluate and degrade gracefully.
Plugin dataanalyticsorchestration
How to configure
- Define what “task complete” means as a rule token.
- confidence.minScoreToAnswer gates whether the model answers or clarifies.
- budget.maxResponseTime and degradedModeThreshold drive UX fallbacks.
- Export for analytics and orchestration — both should share the same numbers.
Subcategories
Success metricsCompletion and satisfaction signals
ConfidenceDisclosure and answer thresholds
Latency budgetMax response and degraded mode
Example tokens
confidence.minScoreToAnswer
type numbervalue 0.55
Minimum confidence required to answer directly.
Configure: Type number 0–1. Below this, use clarifying or low-confidence copy.
budget.maxResponseTime
type durationvalue 3000
Target max response time (ms).
Configure: Pair with budget.degradedModeThreshold (e.g. 6000).
metric.taskCompletionDefinition
type rulevalue Task complete when user confirms resolution.
Success definition for analytics.
Configure: Type rule. Align product, support, and ML eval on this wording.
Export & settings
Local JSON export for handoff, plus seed and reset tools for this Figma file.
Download / clipboarddesignengineeringAI/ML
How to configure
- Open Export, select categories (or keep all), then Generate.
- Copy JSON to clipboard or Download cognitive-tokens.json.
- Settings → Seed full token set adds missing seed names without overwriting yours.
- Settings → Clear all tokens wipes plugin data and linked Variables for this file.
Subcategories
ExportCategory filters, copy, download
SeedLoad the full demo pack
ResetClear file-local token store
Example tokens
cognitive-tokens.json
type exportvalue { version, exportedAt, categories: { … } }
Export envelope grouped by category.
Configure: No repo sync in v0.1 — wire CI yourself from the downloaded JSON.
