The handbook
A designer's handbook.
Everything you need to use Tenet day to day. Written for designers, not engineers: where something needs a developer, it says so.
The five-minute version
Tenet holds three things: the rules your team agreed on, the people you're designing for, and why you decided what you decided. Then it checks your work against them.
The single most useful thing you can do on day one:
- Go to Review.
- Paste the URL of something you've built — a staging link is fine.
- Read the results.
You'll get problems grouped by rule, worst first, each one marked on a screenshot of the page. If one rule broke in 37 places, that's usually one component used everywhere — fix it once.
That's the whole product in one action. Everything else makes that check smarter.
What the words mean
Five terms. They're worth learning because they appear everywhere.
| Word | What it means | Where it lives |
|---|---|---|
| Rule | One thing that can be checked, like "tap targets must be at least 44×44". Has a severity: high, medium, low | Rulebook |
| Rulebook | A set of rules your team turned on. WCAG and Apple's guidelines come built in | Rulebook |
| Signal | One thing your team learned or agreed — a research finding, a decision, a risk. Has a source and a status | Knowledge → Signals |
| Document | A file kept whole. A spec, a report, an interview. Nothing is extracted from it unless you ask | Knowledge → Documents |
| Persona | Someone you build for, with the research behind each claim attached | Personas |
The one that trips people up: a Document is kept as-is; a Signal is a single claim pulled out of something. Uploading a research report doesn't create signals. Promoting it does, and that's a separate, deliberate step.
Checking a page or a design
A live page
Review → paste a URL → Review. Takes about 15 seconds; it opens the page in a real browser and measures what actually rendered.
Reading the results:
- Grouped by rule, worst first. The number beside each is how many places it happens.
- Click a finding and every place it occurs lights up on the screenshot.
- Click a mark on the screenshot and it selects that finding.
- Each occurrence carries the exact element, so you can hand it to a developer without
them hunting for it.
A clean result means "nothing broke the rules you turned on." It does not mean the page is perfect. Tenet only checks rulebooks your team adopted — deliberately, so that a pass is worth something.
Pasted HTML or a screenshot
Same screen. Use A screenshot for something not yet built, or paste HTML directly. Screenshot reviews check copy only — there's no rendered page to measure.
Copy on its own
Paste text into Review and pick the voice & tone lens. Optionally pick a persona, and the step of their journey they're at. This matters more than it sounds: wording that reads fine in general is often wrong for someone in the middle of a task.
Rulebooks
Rulebook in the top nav.
Turning rules on
Rules do nothing until a workspace adopts them. Browse Rulebooks shows what's available; adopting copies it into your workspace so you can edit your own version without affecting anyone else.
Three levels:
- Universal — WCAG 2.1 AA and Apple's HIG, available to everyone
- Organisation — your company's rules, cascading to every project
- This workspace — just this project
Adding your own
Three ways, in order of least effort:
- From a Storybook — New Rulebook → Storybook. Paste the URL of a published
- From a document — paste your existing guidelines and Tenet turns them into draft
- By hand — Blank Rulebook, then Add Rule.
Storybook and Tenet reads the component inventory and suggests rules. Review them and keep the ones you'd actually enforce.
rules.
Severity
High, medium, low. It decides what you see first, so be honest: if everything is high, nothing is.
Only rules with a code run automatically. A rule you write by hand is recorded and visible but won't be checked by the scanner unless it maps to one of the built-in checks. Tenet is honest about this rather than pretending to enforce prose.
Personas
Personas in the top nav.
Making one
- New persona — write it yourself.
- Generate from knowledge — Tenet drafts one from the research already in this
workspace. Nothing is saved until you review and accept it.
Fill in what you actually know. Leave the rest blank — an invented detail is worse than a gap, and Tenet won't guess a face or a demographic for you if you haven't said.
Why personas here are different
Every claim keeps a link to the research it came from. Two things follow:
- Drift. If a source is edited after being cited, the claim is flagged and shows you
- Contradiction. If new research disagrees with a persona, Tenet shows both sides and
the old wording next to the new one.
asks a steward to decide. It never rewrites the persona — deciding what's true now is a judgement about a real person, and that stays with you.
Show your work on a persona lists what was cited, what was merely in context, and what has changed since.
If a persona is out of date
- Re-validate — "I've read the new source text and this still holds." Adopts the
- Edit — change the claim itself.
- Restore — put it back to an earlier version. This is itself undoable.
current wording as what the claim rests on.
Journeys
Open a persona → Edit journey.
Columns are the steps someone goes through; rows are what you need to know at each. Click a step and it opens up while the others make room. Changes save as you type.
Three rows per step:
- What's true here — the situation
- Tasks & jobs — what they're doing
- Opportunities — what could be better
The line above the columns is how it feels at each step. The low point is usually where the work is.
Two shortcuts:
- Generate with AI — drafts the whole journey from the persona and your own research.
- Import from a live flow — give it a starting URL and say what the person is trying
Edit it afterwards; it's a starting point, not an answer.
to do. Tenet walks through your real product and screenshots each step.
Getting knowledge in
One button: Add, in the top bar. It asks one question, and it is the only one you need to be able to answer:
Keep the whole thing A spec, a PRD, a research report, a page from your wiki. Never broken into signals — it will not appear in Approvals and it never becomes a claim your team governs by.
That does not mean it sits in a drawer. A kept document is still read: it answers questions in Ask, and a copy review will flag wording that contradicts it — a "spec drift" finding, cited to the document and section rather than to a rule. So a spec can fail your marketing copy without ever having become a signal.
Which generative surfaces may use it depends on the document's kind, set when you add it and editable afterwards in the document viewer:
| Kind | Used for |
|---|---|
research |
Personas, journeys, Ask, spec drift |
spec |
Journeys, Ask, spec drift |
voice |
Copy review's tone check, Ask, spec drift |
reference |
Ask and spec drift only |
Pull out what matters An interview, a usability session, a sales call, a meeting. Tenet reads it and proposes what's worth keeping. You approve each one before it counts.
Pick the outcome first; how it arrives — a file, a recording, or talking it through with Tenet — is the second choice, inside whichever you picked. Documents and Signals each have their own Add that opens the same sheet with the likely outcome led, so you never have to learn a second set of words for the same act.
Below the line is the third case: write one thing down yourself. No file, no extraction, nothing to approve — just a claim you already know.
| You have | Where it goes |
|---|---|
| A spec, PRD or report you want kept intact | Keep the whole thing |
| An interview or meeting recording | Pull out what matters → pick the recording |
| Something in your head | Pull out what matters → talk it through |
| A page in Confluence | Settings → Integrations → Atlassian, then import |
| One specific thing to record | Or write one thing down yourself |
The signal lifecycle
Draft → Verified → Policy
Anything AI-generated starts as a Draft and waits in Approvals for a person. Verified means someone checked it. Policy means the team governs by it.
Working in Figma
Install the plugin, then Plugins → Tenet.
First time: paste your Tenet URL and a personal access token (Account → API tokens → create one). Stored locally in the plugin, on your machine.
Three tabs:
- Review — select a frame, optionally pick a persona and the step they're at, then
- Ask — what does the team already know about this? Answered from your workspace.
- Capture — record a decision while you're in the file. It's linked to what you're
Review selection. Click a finding and Figma selects that layer. Accept a suggested rewrite and it's written straight into the text.
looking at.
Figma reviews check structure, not pixels: hardcoded colours, missing text styles, layer naming, deprecated components. Contrast is measured on the web review, because that needs a real rendered page.
Working with AI tools
If your team uses Claude Code, Cursor or similar, it can read your rules, personas and research before it writes anything — and check its own work afterwards.
A developer sets this up once (Settings → Figma plugin has the token instructions; the MCP server details are in mcp/README.md). After that, you can ask the AI things like:
"What do we already know about the checkout flow?" "Build this screen for Priya at the first-purchase step." "Review the deploy preview against our rulebook."
AI can read everything and change nothing. If it wants to update a persona it files a proposal instead, and you'll see a word-by-word diff of exactly what would change before anything happens.
Approving things
Review → Approvals (or the bell).
Anything proposed — by AI, by an import, by a teammate — waits here. You'll see what it says and where it came from. Approve, or reject with a reason the author will see.
Persona proposals appear on the persona itself, or on the Personas page for a proposed new one.
If nobody works this queue it becomes noise and people stop opening it. One person owning it is worth more than everyone half-owning it.
Your account, your workspace, your team
| Where | What | |
|---|---|---|
| Your account | Avatar → Account | Your name, password, API tokens. Follows you everywhere |
| Workspace settings | Avatar → Settings | This project: integrations, rulebooks, the Figma plugin |
| Workspace members | Settings → Members | Who can see and edit this project's work |
| Organisation members | Avatar → Organisation members | Company-level. Lets someone create projects — does not give access to any project's content |
| Workspaces | Avatar → Workspaces, or the switcher | Switch between projects |
Roles, in order:
- Viewer — read
- Editor — create and edit; drafts go to Approvals
- Steward — approve, promote, edit rulebooks, connect integrations
- Org admin — everything, plus people and billing
When something looks wrong
The review found nothing on a page I know is broken. Almost always: no rulebook is adopted in this workspace. Rulebook → Browse Rulebooks. The Review screen tells you how many rules are active before you run it — if it says 0, that's your answer.
The review found far too much. Look at the rule count, not the place count. Six rules across 132 places is six problems. Start at the top.
A finding points at something that looks fine. Some checks measure what the browser computed, not what you designed — text over a background image, for example, has no single backdrop colour, and Tenet declines to fail those rather than guessing. If it still looks wrong, it's worth reporting: a rule that cries wolf is worse than no rule.
No screenshot with my findings. Screenshot storage isn't configured for this deployment. The findings are still real; ask whoever runs Tenet to set S3_BUCKET.
An invite never arrived. Email is off unless a mail provider is configured. Ask your admin — the invite itself is real, and signing in with that address claims it.
The Figma plugin says it can't reach Tenet. Your token was revoked, or the URL is wrong. Account → API tokens to make a new one.
What Tenet can't do yet
Being straight with you, so you don't spend an afternoon looking for these.
- Reviews only run when someone runs them. There's no automatic check yet unless a
- The Drift page isn't trustworthy. Its numbers are keyed on when you last scanned
- Contradiction detection can miss things. It compares signals that share tags, so two
- Documents are plain to read. Research isn't as visually rich as personas and
- Reviews are synchronous. A URL review holds the screen for 10–20 seconds. Fine for
- Dovetail and GitHub aren't connected yet. Jira, Confluence, Fullstory, Fathom and
developer has wired up the CI action (scripts/tenet-review.mjs). Ask.
rather than when a problem appeared. Being rebuilt — TNT-105. Don't make decisions on it.
that conflict while tagged differently are invisible to it.
journeys yet — TNT-107.
one page, awkward for twenty.
Granola are. Slack is slash-commands only.
One rule of thumb
If something in Tenet can't be checked automatically, shown to be out of date, or read by a machine, it probably belongs in your wiki and Tenet should link to it.
If you find something in the product that fails all three, say so. That's a feature worth removing, and it's easier to spot for someone who didn't build it.