Wrench.ai UX governance skill. Apply this skill whenever making any design, copy, agent, or engineering decision on the Wrench.ai platform. This skill encodes the UX Constitution (11 principles), the Six Pillars initiative, the Seven Empirical Gaps, and the pre-ship checklist. Trigger when someone says "does this pass the constitution", "run the checklist", "review this design", "is this on-brand UX", "check this against our principles", or any time a feature, flow, component, or agent message is being designed, reviewed, or shipped. Also trigger proactively whenever a PR, design review, or agent prompt update is in progress.
How this skill is triggered — by the user, by Claude, or both
Slash command
/wrench-ux-constitution:wrench-ux-constitutionThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill is the single source of truth for how Wrench.ai **feels, behaves, and communicates** —
This skill is the single source of truth for how Wrench.ai feels, behaves, and communicates — across every surface: product UI, agent interactions, support tools, onboarding flows, error states, and live tests. Every feature, every message, every animation is measured against these principles before it ships. When there is a disagreement about a design decision, this document settles it.
Paired with the brand DNA: The visual source of truth (colors, typography, spacing,
radius, shadows, chart styling, artifact templates) lives in the wrench-dna GitHub repo under
docs/brand/. This skill governs behavior and experience; the DNA governs pixels. The two are
designed to cross-reference — when this skill and the DNA disagree on a visual token, the DNA
wins and this skill is out of date. Open a PR to realign.
Authoritative DNA references:
When this skill is triggered, Claude should:
These are not guidelines. They are constitutional rules.
The rule: At every moment, in every state, the user can answer three questions without clicking anything: What is the system doing right now? Did it succeed or fail? What do I do next? If any of those three are unclear, the UX has failed.
The test:
The anti-pattern: Silent background processes. Spinners with no context. Success states with no confirmation. Error messages that disappear before the user reads them. HTTP error codes in the UI.
Applies to: All product states, all agent interactions, all support flows, all background jobs.
The rule: When something goes wrong, Wrench takes responsibility for the user's experience — regardless of whose fault it is. Every error message is written in first person, communicates cause, communicates next steps, and — when it's our fault — says so plainly.
The test:
Error attribution framework:
The anti-pattern: Raw HTTP status codes. Stack traces. "Something went wrong." "An error occurred." Error messages that imply user error when the system failed.
Applies to: All error states, toast messages, empty states, agent responses, network failures.
The rule: Wrench is built on Shapley values, embeddings, and vector similarity. Our users run marketing campaigns. The gap between those two realities is our responsibility to bridge — completely, on every surface. If a user needs to understand a technical concept to use a feature, we've failed the feature.
The test:
The canonical language map:
| Never say | Always say |
|---|---|
| Shapley values | Signal strength |
| Meta-measures | Ingredients |
| Embeddings | How your AI thinks about your brand |
| Enrichment job | Contact lookup |
| Model run | AI scoring update |
| Vector similarity | How well a contact matches your profile |
| API error | Something went wrong on our end |
| Pipeline | Workflow |
| Data source | Contact list |
| Webhook | Automatic update |
The anti-pattern: Technical jargon in primary UI. Tooltip-free field labels. Empty states with no explanation. Forms that ask for things without explaining why.
Applies to: All UI copy, all agent responses, all error messages, all onboarding flows, all tooltips, all email notifications.
The rule: Every field we ask a user to fill out costs them something. Every step they take before reaching value is friction we chose to impose. The goal is always: minimum inputs, maximum outputs, as fast as possible.
The test:
Progressive disclosure principle: Show what matters now. Reveal everything else only when it's relevant. Advanced configuration always goes behind an expandable section, never in the critical path.
The anti-pattern: Long onboarding flows before first value. Required fields that serve our data needs, not the user's. Asking a user to configure something they won't understand until they've used the product.
Applies to: Onboarding, all forms, all configuration flows, all setup wizards.
The rule: The Wrench agent has a personality, a voice, a memory, and a perspective. It is not a chatbot. It is not a search bar. It is a knowledgeable assistant that knows the user's workspace, tracks what's happening, notices when things change, and proactively surfaces what matters.
Agent voice principles:
The test:
The anti-pattern: Generic responses that could apply to any user. Responses that use technical language. Responses that are longer than they need to be. The agent apologizing for things that aren't its fault.
Applies to: All agent messages, welcome screens, notifications, proactive alerts, support interactions.
The rule: Micro-animations, personalized messages, and contextual celebrations are powerful when they're relevant — and annoying when they're not. Delight is not decoration. Every animated moment must be triggered by something the user actually did or achieved.
Earned delight triggers (approved):
Unearned delight (never do):
Applies to: Animations, agent messages, notification copy, onboarding milestones, score updates.
The rule: When a user has a problem, the speed and quality of our response is part of the product experience. The support experience is designed with the same rigor as the product.
Support lifecycle (every issue must pass through all states, visibly):
The anti-pattern: Silent issue queues. "We'll get back to you" with no timeline. Resolution with no explanation. Support that feels like shouting into a void.
Applies to: In-app support, email notifications, agent escalation flows, incident communications.
The rule: Every interface element follows the same design language, the same tone, and the same behavioral rules. Inconsistency signals a team that doesn't communicate. Users trust consistent products and abandon inconsistent ones.
Source of truth for visual tokens: All colors, fonts, spacing, radius, shadows, and chart
styling are defined in the wrench-dna repo at docs/brand/. These files are synced from Figma
(Wrench.ai_aligned-Metronic-library, file key XDABmqgxsih9ChiulLu1Wn) and are authoritative.
Never invent off-palette values. If a value isn't defined in docs/brand/design-tokens.css,
it isn't a valid Wrench.ai value.
The Wrench design token baseline (mirrors the DNA — update here when the DNA updates):
#5E80A8 steel blue (--color-primary). Dominant interactive color —
CTAs, links, active states, key metrics.#F1956F warm orange (--color-secondary). Eyebrow labels, section
markers, badges, warm call-outs. Punctuates; never dominates. Never a background fill on
large surfaces.--surface-base #1D2835 (page), --surface-raised
#243347 (cards), --surface-overlay #2C3E55 (modals/dropdowns), --surface-border
#36404A (dividers), --surface-hover #4F5E6C.--text-primary #FFFFFF, --text-secondary #9AADC0,
--text-tertiary #687B8E, --text-brand #5E80A8, --text-accent #F1956F.--color-success #6DD48F, --color-danger #F8285A,
--color-warning #F4AD8F.--font-semibold (600). Minimum body size
--text-base (13px).--radius-sm 4px (tags, badges), --radius-md 8px (inputs, small
cards, buttons), --radius-lg 12px (cards, panels), --radius-xl 16px (feature cards),
--radius-2xl 24px (large panels), --radius-full 9999px (pills, avatars).--transition-fast 150ms ease, --transition-base 200ms ease,
--transition-slow 300ms ease, --transition-spring 400ms cubic-bezier(0.34, 1.56, 0.64, 1).body { background: var(--surface-base); color: var(--text-primary); }. Light mode requires an explicit request.Artifact-governance rules that also apply here (the DNA's artifact-governance.md is binding
for anything styled — HTML/React, decks, PDFs, Notion pages, emails, social assets):
:root { } block from docs/brand/design-tokens.css in every HTML/React
deliverable (artifact-governance.md Rule 1).--chart-1 through --chart-8, custom dark tooltip,
Poppins labels, JetBrains Mono values.The test:
docs/brand/design-tokens.css
first. If not, it's a brand defect.Applies to: All UI components, all agent messages, all email notifications, all in-app notifications, all Claude artifacts, all slide decks, all PDFs, all Notion pages bearing the Wrench.ai brand.
The rule: There is no such thing as a default state. Loading is a state. Empty is a state. Error is a state. Partial data is a state. Every state the platform can be in has been intentionally designed — with appropriate copy, visual treatment, and guidance.
Required states for every major feature:
The anti-pattern: Blank screens. Raw data with no context. Empty tables with no explanation.
Applies to: All product screens, all data tables, all agent states, all onboarding steps.
The rule: Wrench is a platform users return to repeatedly over months and years. Every decision should optimize for the long-term relationship, not the individual session. The experience should feel meaningfully different on day 1 vs. day 100.
Relationship-building features (prioritize):
Applies to: Agent design, product roadmap prioritization, data retention decisions, notification strategy.
The rule: Every user deserves to use Wrench — including users with motor impairments, visual disabilities, vestibular disorders, or cognitive differences. Accessibility is the baseline quality standard. A platform that can't be used by a screen reader or a keyboard-only user is unfinished.
Accessibility baseline:
@media (prefers-reduced-motion: reduce) and disable or
substitute static alternativesThe anti-pattern: Animations without prefers-reduced-motion gates. Color-only status indicators. Modals that trap keyboard focus. Buttons with no accessible label.
Applies to: All product UI, all animations, all toast/notification components, all form elements, all agent interface elements, all onboarding flows.
The Six Pillars are the active build framework derived from the UX Constitution. They translate principles into shippable feature categories. Every UX task in the backlog maps to one of these.
[P1-VIS] Pillar 1: System Status Visibility Users must always know what the system is doing. Covers: loading states, background job indicators, real-time status updates, progress communication, and agent activity signals. Maps to P1 of the Constitution.
[P2-LANG] Pillar 2: Plain Language Design All user-facing copy must use the canonical language map. No technical jargon anywhere in the product. Covers: UI copy audits, tooltip rewrites, error message rewrites, agent response language, onboarding copy. Maps to P3 of the Constitution.
[P3-ONBOARD] Pillar 3: Onboarding Simplification New users reach first value in under 15 minutes with 3 or fewer decisions. Covers: onboarding flow redesign, progressive disclosure implementation, default-value strategies, first-session experience. Maps to P4 of the Constitution.
[P4-AGENT] Pillar 4: Agentic Chat The agent is a character with memory, voice, and workspace context. Covers: agent personality, proactive insight surfacing, workspace-aware responses, clarifying question logic, Gulf of Evaluation transparency (see Empirical Gaps). Maps to P5 of the Constitution.
[P5-PERSONAL] Pillar 5: Personalization The experience evolves with the user. Covers: day-1 vs. day-100 experience differentiation, "since your last visit" summaries, score trend history, persistent agent memory. Maps to P10 of the Constitution.
[P6-SUPPORT] Pillar 6: Live Support Escalation Support is a designed product experience. Covers: in-app support lifecycle, issue status visibility, agent-to-human escalation, incident communication. Maps to P7 of the Constitution.
The Seven Empirical Gaps are specific, research-backed UX problems identified in the Wrench.ai platform that the Six Pillars initiative is designed to close. Every gap has a backlog tag prefix.
[GAP1-ACCESS] Gap 1: Accessibility / WCAG 2.1 AA The platform has not been fully audited against WCAG 2.1 AA. Zero critical violations is the target. Includes prefers-reduced-motion compliance for all animations, color contrast verification for brand palette, keyboard navigation audit, and screen reader compatibility.
[GAP2-UNCERT] Gap 2: AI Uncertainty Communication Users don't know when AI is uncertain. The platform must communicate AI confidence levels in plain language — not probabilities or percentages, but clear signals like "This score is based on limited data" or "We're still learning this contact." Grounded in Microsoft Research Human-AI Interaction Guidelines (2019).
[GAP3-CONTROL] Gap 3: User Control and Reversibility Users cannot easily undo or override AI decisions. Every AI-driven action must have a clear reversal path. Users must feel in control of the AI, not subject to it. Covers: score overrides, ingredient edits, agent action confirmation before execution.
[GAP4-NOTIF] Gap 4: Notification Fatigue Proactive notifications must be relevant and rare enough to stay meaningful. Covers: notification frequency logic, relevance scoring for proactive agent messages, user-controlled notification preferences, suppression after repeated dismissals.
[GAP5-REPAIR] Gap 5: Conversational Repair When the agent misunderstands or gives a wrong answer, the user needs a clear, low-friction path to correct it and teach the agent. Covers: thumbs down / correction flow in agent UI, agent acknowledgment of correction, memory update on correction.
[GAP6-EVAL] Gap 6: Gulf of Evaluation for Agent Commitments Users cannot tell what the agent has committed to doing. This is the highest-priority agentic UX problem. When an agent says it will do something, the user must be able to see: (a) what it committed to, (b) whether it has started, (c) whether it completed, (d) what the result was. This is not a secondary concern — it is first-class.
[GAP7-FEEDBACK] Gap 7: Feedback Loops into the Model User behavior and explicit feedback (ratings, corrections, dismissals) must feed back into the AI to improve it over time. Users who give feedback must see evidence that it made a difference. Covers: feedback capture UI, model improvement transparency, "based on your feedback" messaging.
Run this before every PR, every design review, every agent prompt update, every support flow change. If any item is unchecked, the feature is not ready to ship.
docs/brand/design-tokens.css? Poppins + JetBrains Mono only? Steel blue dominant,
warm orange punctuates? No emojis in product UI?docs/brand/artifact-governance.md?The authoritative versions of these behavioral principles live in Notion. The visual tokens
they reference live in wrench-dna/docs/brand/. Always fetch from source before making
constitutional amendments.
UX Constitution (source): 3345eef4866d818eb60af3b3945dd6b4
https://www.notion.so/3345eef4866d818eb60af3b3945dd6b4
Agent Experience and World Class UX project (parent):
3335eef4866d8042a5cbd2c6eb6c7b36
https://www.notion.so/3335eef4866d8042a5cbd2c6eb6c7b36
Task backlog DB collection ID: 6360cc78-9379-4535-bc80-c9262c3bde60
Projects & Priorities DB collection ID: a00de035-0465-403e-a479-0ff6ffe798cb
Task naming convention: All UX initiative tasks are prefixed with their Pillar or Gap code,
e.g. [P1-VIS], [GAP3-CONTROL], [GAP6-EVAL].
These principles are grounded in:
Source: Wrench.ai UX Constitution, last updated 2026-04-23 | Owner: Dan Baird
Visual source of truth: wrench-dna/docs/brand/ (design-tokens.css, artifact-governance.md)
Skill compiled: 2026-04-23 | Status: Living document — update when Constitution or brand DNA changes
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub wrenchai/wrench-plugins --plugin wrench-ux-constitution