@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/undo-destructive.md

@@ -0,0 +1,66 @@
+# Undo and destructive actions
+
+Decide between Undo after the fact and a confirmation before it, using one test: can the action be reversed, and who else does it reach?
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Confirming everything trains people to click Yes without reading; confirming nothing loses data. Teams pick differently on every screen.
+
+**Solution:** Reversible actions run at once and offer Undo in a toast and with ⌘Z. Irreversible actions, or ones that reach people outside the workspace, confirm in a dialog that states the consequence, with the safe option focused.
+
+**Built from:** Toast, Confirmation dialog, Bulk action bar, Button, Keyboard shortcut hint
+
+## How it works
+
+1. Ask: can TwoUX reverse this fully? Extending, renaming, archiving and moving can be reversed; deleting, emailing candidates and closing a listing that has notified applicants cannot.
+2. Reversible: run it, then show a toast such as "2 listings extended" with Undo. ⌘Z undoes the last action too.
+3. Irreversible: open a confirmation dialog titled with the action and count, stating what happens and what is kept.
+4. Buttons name the outcome: the safe option ("Keep open") and the action ("Close listings"). Focus starts on the safe option.
+5. For severe actions that also remove related records, such as deleting a workspace, ask the person to type the name.
+
+## When to use
+
+- Undo: for every reversible change made by a person or applied by the assistant.
+- Dialog: for deletion, sending to people outside the workspace, and actions that cascade.
+
+## When not to use
+
+- Don't confirm routine reversible actions; offer Undo instead.
+- Don't use a toast as the only record of something important; important outcomes also appear in the record's activity.
+
+## Guidelines
+
+- Scale friction to severity: none for low-risk, one dialog for high-risk, typed confirmation only for the rarest, most damaging actions.
+- The dialog body names the items, the consequence and what stays: "The 140 people who already applied stay in your pipeline."
+- Undo stays reachable after the toast goes: ⌘Z and the record's activity both reverse the last action.
+- An Undo toast stays while hovered or focused and does not close while the person is reading it.
+- The action button uses the danger style and sits to the right of the safe option, never on its own.
+
+## Content
+
+- Dialog title is a question with the count: "Close 2 listings?"
+- Never "Are you sure?", "Yes" or "OK". Use outcome labels.
+- Toast: past tense plus Undo: "Listing archived. Undo".
+
+## Accessibility
+
+- Confirmation dialogs use role alertdialog with aria-labelledby and aria-describedby.
+- Focus moves to the least destructive button, Tab is trapped, Esc cancels and focus returns to the trigger.
+- Toasts are announced as status messages; Undo also has a keyboard path (⌘Z) because toast actions are hard to reach with a keyboard.
+
+## Do
+
+- Do offer Undo after every reversible change, including bulk and assistant changes.
+- Do state the consequence in the dialog body.
+
+## Don't
+
+- Don't focus the destructive button by default.
+
+## Related
+
+- Selection and bulk actions
+- Propose, then apply
+- Notifications: inbox, bell, toast or email digest
+- Toast
+- Confirmation dialog

package/agent/docs-md/unsaved-changes.md

@@ -0,0 +1,71 @@
+# Unsaved changes
+
+Don't let people lose work by accident: save drafts of long text automatically, and ask before discarding a changed form only when there really are changes.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Someone writing a job description clicks a breadcrumb or closes the tab and loses twenty minutes of work. The opposite failure is a "Discard changes?" dialog that appears when nothing changed, which trains people to click through it.
+
+**Solution:** Track whether a form is dirty. Long text (job descriptions, email templates) saves a draft as people type. A changed form that would be lost by leaving asks once, in TwoUX's confirmation dialog, with Keep editing as the safe default. Browser-level exits use the browser's own prompt.
+
+**Built from:** Confirmation dialog, Side panel (drawer), Button, Text input, Timestamp, Banner (inline alert)
+
+## How it works
+
+1. Track a dirty flag per form: true once a value differs from what was loaded, false again after save or if the person changes it back.
+2. For long text, save a draft every few seconds after typing stops and show "Draft saved 10 seconds ago" near the actions. A form whose draft is saved is not at risk, so no prompt is needed.
+3. When an in-app action would throw unsaved changes away (Cancel, a breadcrumb, a side navigation link, J or K to the next record, Esc on a panel form), open the confirmation dialog.
+4. While the form is dirty, register a beforeunload handler so closing or reloading the tab shows the browser's own prompt; remove it as soon as the form is clean.
+5. After the person chooses Discard, carry out the action they started; after Keep editing, return focus to where they were.
+
+## When to use
+
+- Create listing, Edit listing and other multi-field forms with a Save button.
+- Forms inside the side panel, where J, K or Esc would move away from the edit.
+- Long text such as a job description or an email template, where autosaved drafts replace the prompt.
+
+## When not to use
+
+- Inline edits in the data grid or side panel fields, which save on Enter or blur; there is never an unsaved state to lose.
+- When nothing has changed, everything is already saved, or the action opens a new tab.
+- When opening or closing a disclosure inside the same form, such as a Show advanced options section.
+
+## Guidelines
+
+- Ask every time there is a risk of loss, whatever the size of the change; consistency means people never have to guess.
+- Never offer "Don't ask again" on this dialog; there would be no way to turn it back on.
+- Discarding typed work cannot be undone, so this is one of the few places TwoUX confirms instead of offering Undo.
+- Mark a dirty form in text near the Save button ("Unsaved changes"), not only with a dot.
+- If a save fails, keep the form dirty and its values in place, with the error in a banner above the actions.
+
+## Content
+
+- Dialog title: "Discard changes to this listing?" Body: "Your changes to Junior Product Designer haven't been saved."
+- Buttons: "Keep editing" (safe, focused) and "Discard changes" (destructive). Not Yes and No.
+- Draft status: "Draft saved 10 seconds ago", or "Saving draft" while it saves.
+
+## Accessibility
+
+- The dialog follows the alert dialog pattern: focus moves to Keep editing, Tab is trapped, Esc means Keep editing.
+- Draft saved status updates in a polite live region, at most once per save, so screen readers aren't flooded.
+- The browser's own beforeunload prompt is accessible by default; don't try to replace it with custom text.
+
+## Do
+
+- Do save drafts of long text automatically.
+- Do ask only when the form is dirty.
+- Do make Keep editing the default.
+
+## Don't
+
+- Don't keep the beforeunload handler on a clean form.
+- Don't ask when someone opens a section inside the same form.
+- Don't add "Don't ask again".
+
+## Related
+
+- Undo and destructive actions
+- Inline editing and validation
+- Record detail: side panel, overlay or full page
+- Confirmation dialog
+- Timestamp

package/agent/docs-md/usage-meter.md

@@ -0,0 +1,80 @@
+# Usage meter
+
+Credits or seats used against a limit, when it resets, and what used them. An upgrade link appears only near the limit.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing consumption against a plan limit, such as credits or seats.
+- A measured value within a known range.
+
+## When not to use
+
+- Progress of a task. Use a progress indicator (nng-progress).
+- A permanent plan promotion. Upgrade is not an always-visible bright button.
+
+## Structure
+
+1. Name of the unit and "used of limit"
+2. Meter bar
+3. Warning from 80% (what stops at the limit)
+4. Resets date
+5. What used them link
+6. Add more link (only near the limit)
+
+## Guidelines
+
+- Say "13.2k of 20k credits": used, limit and unit.
+- Say when it resets, for example "Resets 1 Dec".
+- Link "What used them" to a breakdown, so people can reduce usage.
+- From 80% used, warn and say what stops at the limit: "Agents pause until 1 Dec".
+- Show the upgrade link only near the limit. Never a permanent bright button.
+- Use role="meter" with min, max and now values, and a name.
+- Never use colour alone: the warning has an icon and words as well as the amber bar.
+
+## Content
+
+- "86% used. Agents pause until 1 Dec."
+- Link: "Add more", not "Upgrade now".
+
+## Accessibility
+
+- role="meter" with aria-valuemin, aria-valuemax, aria-valuenow and an accessible name (APG meter, SC 4.1.2).
+- Warning is text with an icon, so it does not depend on colour (SC 1.4.1).
+- The bar meets 3:1 against its track (SC 1.4.11).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to What used them and Add more |
+| Enter | Open the breakdown or the upgrade options |
+
+## Examples
+
+### states
+
+```tsx
+import { toast, UsageMeter } from "@twoux/ui";
+
+export const meta = { title: "Plenty, close, and at the limit", description: "The upgrade link appears from 80% used, and the warning says what stops. Colour is never the only signal.", order: 1 };
+
+export default function Example() {
+	const common = { unit: "credits", limit: 20000, resets: "1 Dec", atLimit: "Agents pause until 1 Dec", onDetails: () => toast("Opens the usage breakdown"), onUpgrade: () => toast("Opens the plans") };
+	return (
+		<div className="grid w-full max-w-xs gap-6">
+			<UsageMeter {...common} used={8400} />
+			<UsageMeter {...common} used={17200} />
+			<UsageMeter {...common} used={20000} />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Stat card with comparison
+- Banner (inline alert)
+- Empty state
+- Status badge

package/agent/docs-md/user-feedback.md

@@ -0,0 +1,71 @@
+# Collecting product feedback
+
+Ask "Was this helpful?" in a quiet spot after people have read or used something, record the Yes or No straight away, then offer one short optional question.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Feedback pop-ups mid-task annoy people and get dismissed, long surveys get abandoned, and a free-text box in a hiring tool invites people to paste candidate names and other personal data.
+
+**Solution:** Use the feedback prompt at the end of help topics, reports and new features. A Yes or No vote is sent on its own. An optional follow-up of one to three questions appears after the vote, with a reminder not to include personal data.
+
+**Built from:** Feedback prompt, Help panel, Button, Text input, Radio, Checkbox
+
+## How it works
+
+1. Place the prompt at the end of the content, after people have read or used it: the foot of a help topic, the end of a report, the side of a new feature's page.
+2. Ask one specific question about that content: "Was this helpful?" with Yes and No.
+3. Send the vote as soon as it is chosen. Show a loading state on the button, then a short thank you with the chosen answer.
+4. After the vote, reveal an optional follow-up: one to three fields, such as "What was missing?". Send it separately.
+5. If sending fails, say so beside the prompt and offer Try again.
+
+## When to use
+
+- At the end of each help topic and help centre article.
+- On a feature in beta, such as a new pipeline report, to learn whether it is useful.
+- After a new workflow is used for the first time, such as the first bulk extend, as a quiet line in the result banner rather than a pop-up.
+
+## When not to use
+
+- On assistant answers. They have their own good and bad controls next to the origin label.
+- In a dialog or pop-up that interrupts a task.
+- For more than three questions. Link to a separate survey page instead.
+
+## Guidelines
+
+- Never interrupt. The prompt sits in the page flow, never as a modal or a toast.
+- One prompt per page, with at most one follow-up form.
+- Keep the follow-up to three questions or fewer; more lowers response and adds data to process.
+- Free text carries a privacy line, and the feedback store strips email addresses and phone numbers before saving.
+- In a side panel, place the expanding follow-up so the page doesn't jump; on narrow screens, the prompt moves to the end of the content.
+- Don't promise a reply. Only say "We'll get back to you" if someone really will.
+
+## Content
+
+- Question: "Was this helpful?" or "Was this report useful?". Answers: "Yes" and "No".
+- Thank you: "Thanks, your feedback is recorded." with the chosen answer shown as selected.
+- Privacy line under free text: "Don't include candidate names or other personal details."
+
+## Accessibility
+
+- Yes and No are buttons with visible text, not icon-only thumbs.
+- After a successful vote, focus moves to the thank you message so it isn't lost.
+- Send errors are announced through a live region.
+
+## Do
+
+- Do record the vote before asking anything else.
+- Do ask about the specific content, not "How are we doing?".
+- Do keep the prompt in the page flow, at the end of the content.
+
+## Don't
+
+- Don't show a feedback pop-up during a task.
+- Don't put two follow-up forms on one page.
+- Don't collect personal data in feedback free text.
+
+## Related
+
+- Contextual help
+- Labelling AI output
+- Feedback prompt
+- Help panel

package/agent/docs-md/voice-and-tone.md

@@ -0,0 +1,60 @@
+# Voice and tone
+
+TwoUX sounds like a capable colleague who knows the data: precise, calm, candid and respectful of people's expertise. The voice is the same on every screen and in the assistant. The tone moves with the moment, from strictly practical in an error to one sentence warmer when someone is starting out or has just finished.
+
+Kind: foundation · Group: Key principles
+
+## Principles
+
+- Precise. Name the thing, the number and the result: '3 listings closed', not 'Items updated'. Translate system detail into what it means for the person's work.
+- Calm. Use the same level voice for success and failure. Excitement comes from what happened, not from punctuation or adjectives: no exclamation marks, no hype, no apologies.
+- Candid. Say what is known and what is not, what can't be undone, and what the assistant did. Never promise more than the product does.
+- Respectful of expertise. Write for people who do this work every day. Teach only on first run, in empty states and when help is asked for. Never say a task is easy, quick or simple.
+
+## Guidelines
+
+- Voice is fixed; tone varies. Before writing, ask three questions: how does the person probably feel, how often will they see this, and what is at stake? The answers set the tone, never the voice.
+- TwoUX sits at one end of three of the four common tone dimensions: serious, not funny; respectful, not irreverent; matter-of-fact, not enthusiastic. On formal to casual it sits in the middle: plain and conversational, with common contractions and no slang. Tone moves within this range, never outside it.
+- Inform to build trust: the default for every screen. Statuses, warnings, errors and assistant caveats say what happened, what it affects and what to do next, and only what is needed now. Banner, ErrorState, ConfidenceNote, AiOrigin.
+- Empower to act: wherever a decision is needed. State the consequence and both choices plainly and leave the choice to the person; never nudge. ConfirmationDialog, PlanCard, approval cards, AgentPermissions.
+- Encourage people along the path: wherever work is stuck or partly done. Say how much is done, what is left and one way forward. EmptyState, RunStatusBar, CsvImport, SetupChecklist.
+- Motivate by showing possibilities: only where someone is starting something. Say what it lets them do in their own terms, as an outcome, never a superlative. OnboardingStep, empty workspace, FeatureLabel popover, ConnectorPicker.
+- Satisfy by meeting expectations: the routine. Saves, completions and toasts are short, past tense, with a count and Undo. Nothing more is added.
+- Delight: in TwoUX, delight comes from speed and precision, not from words. A quiet line is allowed at a real milestone people reach rarely, such as a finished setup checklist or an empty Inbox ('You're all caught up.'). Never in errors, never on repeated messages, never a joke, pun or emoji.
+- Tone by person: experienced, daily users get the short form. First-run screens, empty states and help get one more sentence saying why. Both use the same words for the same things; there is no beginner vocabulary.
+- Tone by stakes: the higher the stakes (money, people outside the workspace, decisions about candidates, permanent deletes), the plainer and more complete the copy. Never soften a risky action with 'just', 'quickly' or 'simply'.
+- Address the person as 'you'. The product does not say 'we' or 'I': in a shared workspace 'we' could mean the vendor or the team. State the event instead: 'Listing not saved', not 'We couldn't save your listing'.
+- The assistant speaks in the same voice. It opens with the answer, does not greet, praise the question or claim feelings ('I'd love to'), uses 'I' only for what it did ('I drafted 3 replies'), and states its limits as one specific caveat.
+- When an agent or model writes copy, give it these four traits and a short sample of existing TwoUX copy, not a single adjective such as 'friendly'. Models exaggerate a single tone word; then edit the result by hand.
+
+## Content
+
+- Words to cut: just, simply, easy, quick (unless measured), seamless, powerful, robust, smart, magic, AI-powered, awesome, great, oops, whoops, sorry, please, successfully, exclamation marks. 'twoux check' warns on the most common ones.
+- Common contractions (can't, don't, isn't, you're) are fine because they read as speech. Avoid unusual ones (it'd, mustn't, should've). Write 'not' in full when the negative is the point and could be missed: 'Do not close this window while the import runs.'
+
+## Accessibility
+
+- Plain, literal words translate and read aloud well. Avoid idioms, wordplay and cultural references, which screen reader users, people reading in a second language and translation tools often get wrong.
+- Tone never replaces information: a reassuring sentence does not stand in for the cause and the fix an error must give.
+
+## Do
+
+- Error, inform: 'Listing not published. The closing date is in the past. Change the date and publish again.'
+- Stuck, encourage: '12 of 240 rows have no email. Import the other 228, or fix them first.'
+- Starting, motivate: 'Connect your calendar to offer candidates interview times that are really free.'
+- Routine, satisfy: '3 candidates moved to Interview. Undo'
+- High stakes, empower: 'Delete 3 candidates permanently? Their CVs and notes are erased. Interview history stays.'
+
+## Don't
+
+- Don't celebrate routine work: 'Woohoo! Your listing was successfully published!'
+- Don't be playful when work is blocked: 'Uh-oh, our robots tripped over your file.'
+- Don't minimise effort: 'Just connect your ATS, it's easy.'
+- Don't make the assistant perform: 'Great question! I'd be happy to help you with that.'
+
+## Related
+
+- Writing
+- Error messages
+- Labelling AI output
+- Consistency

package/agent/docs-md/why-choice.md

@@ -0,0 +1,93 @@
+# Why this choice
+
+A small Why? control beside a choice an agent made. On demand, it names the deciding factors and the options that lost, then offers Change this or Keep it.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- When an agent picked between options for the person: a time, a supplier, a template, a route, a recipient list.
+- When a requirement could not be met and the person should know.
+- When the choice is easy to change and people may want to change it after seeing why.
+
+## When not to use
+
+- By default, on every output. Explanations on demand keep the screen quiet; use the origin label (ai-origin-label) to say where something came from.
+- Sources for a claim. Use Citations and sources (citations-sources).
+- Risks or doubt about the output. Use a Confidence note (confidence-note).
+
+## Structure
+
+1. Why? link beside the choice
+2. Popover ("Why <choice>", deciding factors)
+3. Not chosen (each option and why it lost)
+4. Couldn't meet (a requirement that was dropped, if any)
+5. Footer (Change this, Keep it)
+
+## Guidelines
+
+- Show the reasoning on demand, from a Why? link. Do not show it by default.
+- Name the deciding factors in plain language, with the most important first.
+- Name the options that lost and why, so the person can see the alternatives were considered.
+- Say if a requirement could not be met ("Couldn't meet: no room free before 10:00"), not only what was satisfied.
+- End with Change this and Keep it, so the explanation leads to control.
+- Store the reasoning with the choice when it is made. Do not rebuild it later, or the explanation can drift from what actually happened.
+
+## Content
+
+- Title the popover "Why <the choice>": "Why Thursday at 14:00".
+- Write each factor as a fact the person could check: "Everyone invited is free", not "Best fit".
+- Write each lost option as its name, then the reason: "Wednesday 10:00: Imogen is out until 11:00".
+- Keep buttons as verbs: "Change this" opens the choice for editing; "Keep it" closes the popover.
+
+## Accessibility
+
+- The control is a button with the hidden text "Why <choice>", so it is not just "Why?" out of context (SC 2.4.6, 4.1.2).
+- The popover is a non-modal dialog opened by the button; Escape closes it and focus returns to the button (APG dialog).
+- Deciding factors use a check icon and text, and the icon is hidden from assistive technology (SC 1.4.1).
+- The target is padded to at least 24 by 24 CSS pixels (SC 2.5.8).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter / Space | Open the Why? popover |
+| Tab | Move through Change this and Keep it |
+| Esc | Close the popover and return focus to Why? |
+
+## Examples
+
+### why
+
+```tsx
+import { WhyChoice, toast } from "@twoux/ui";
+
+export const meta = { title: "Why the agent picked this", description: "A Why? link beside the choice. On demand it names the factors, the options that lost and what could not be met, then offers Change this or Keep it.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="flex w-full max-w-xl items-center gap-2 rounded-sm border border-line bg-surface px-3 py-2.5 text-base text-ink">
+			<span className="min-w-0 flex-1">Interview scheduled for <span className="font-medium">Thursday 14:00</span></span>
+			<WhyChoice
+				choice="Thursday at 14:00"
+				factors={["Everyone invited is free", "It is inside the applicant's availability window", "Room 2 is booked for the full hour"]}
+				alternatives={[
+					{ name: "Wednesday 10:00", why: "Imogen Hart is out until 11:00" },
+					{ name: "Friday 09:30", why: "Falls after the applicant's deadline to reply" },
+				]}
+				dropped="No slot was free before 12:00, which you asked for."
+				onChange={() => toast("Opened the schedule for editing")}
+				onKeep={() => toast("Kept Thursday at 14:00")}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Citations and sources
+- Confidence note
+- AI origin label
+- Agent run timeline
+- Change review

package/agent/docs-md/workspace-onboarding.md

@@ -0,0 +1,74 @@
+# Onboarding to an empty workspace
+
+A new workspace shows a short setup checklist in the sidebar and empty states that each offer one way in: create, import or start from a template.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** A new team lands on empty tables and a blank assistant. Product tours get skipped and forgotten, and each feature invents its own first-run screen.
+
+**Solution:** "Get set up 3 / 5" sits in the sidebar until done or dismissed. Each empty page explains what goes there and offers the fastest way in. Templates open as drafts, never run on their own.
+
+**Built from:** App shell and sidebar navigation, Empty state, Templates gallery, Connected tools, Assistant side panel, Button, Setup checklist, Onboarding step
+
+## How it works
+
+1. Show a setup checklist in the sidebar with a count ("Get set up 3 / 5") and the next step underneath.
+2. Each step is an action people need anyway: connect your careers page, invite the team, create a first listing, set team instructions, try a saved task.
+3. Steps complete themselves when the thing is done anywhere in the product.
+4. Each empty page explains what will appear and offers one primary way in, with import or a template as the second.
+5. Templates open as an editable draft that names the tools it uses. Nothing runs until the person chooses Run.
+6. The checklist can be dismissed and reopened from Settings.
+
+## When to use
+
+- For a new workspace, and for a feature someone opens for the first time (a blank slate).
+
+## When not to use
+
+- Don't open a product tour or deck of cards on first login; show help when people reach the feature.
+- For a list that is empty because of filters. Use the zero results state.
+
+## Guidelines
+
+- Keep the checklist to five steps or fewer, ordered by value to the team.
+- Offer starter content (sample listings) only if it is clearly marked and easy to remove; keep a plain empty state for when it is gone.
+- Show help in context and on request, not up front.
+- The assistant's empty state offers two or three tasks based on what is on screen, not a blank "How can I help?".
+- Say early what the assistant can and can't do with the workspace's data.
+- Track checklist steps as tasks done or not done, not progress inside a task. A step left halfway still shows as not done.
+- Recommend a setting when it helps, but never stop people choosing another one. Warn only when their choice blocks the goal of the step.
+- Show steps that can't start yet and say what they need first, such as "Connect your careers page first". Don't hide them.
+- Support both people who read first and people who try first: a short line and Learn more on each step, and an action that starts the task straight away.
+- Once the checklist is dismissed it stays dismissed on every page until reopened from Settings.
+
+## Content
+
+- Blank slate titles invite the action: "Create your first listing". Body says why in one sentence.
+- Checklist steps start with a verb and say the benefit: "Connect your careers page to import roles automatically".
+
+## Accessibility
+
+- The checklist progress is text ("3 of 5 done"), not only a ring.
+- Completing a step is announced as a status message.
+- Recommendation popovers attached to a step open one at a time, never on their own, and close with Esc.
+
+## Do
+
+- Do show progress through setup.
+- Do give every empty page a way in.
+
+## Don't
+
+- Don't block the product behind a setup wizard.
+- Don't run a template without the person choosing Run.
+
+## Related
+
+- Empty, loading and error states
+- Saved tasks and schedules
+- Ask about what's on screen
+- Empty state
+- Templates gallery
+- Onboarding step
+- Setup checklist
+- Sign in

package/agent/docs-md/writing.md

@@ -0,0 +1,48 @@
+# Writing
+
+TwoUX speaks plain UK English. Buttons start with a verb, everything is in sentence case, and every message says what happened and what to do next. AI is described by what it does, never as smart or magic. How the copy should sound is set in Voice and tone.
+
+Kind: foundation · Group: Key principles
+
+## Principles
+
+- Plain English first.
+- Say what happened, then what to do. Error messages should state the problem in plain language and point to a fix.
+- Verbs on actions. Lead buttons with a verb that says what will happen.
+- Same thing, same word, everywhere.
+
+## Guidelines
+
+- UK English spelling and conventions: organise, colour, licence (noun); dates as 6 November 2026 with no ordinal; numerals for all numbers including 2 to 9; commas in numbers over 999.
+- Sentence case for everything: headings, buttons, tabs, menu items, column headers.
+- Buttons: verb first, 2 to 4 words, a noun when the target is unclear. 'Close listing', 'Extend 30 days', 'Export CSV'. Never 'OK'; name the action.
+- Errors and empty states: what happened, why if useful, one action. 'No listings match these filters. Clear filters.' Do not blame the user.
+- Confirmations: past tense and a count. '3 listings closed. Undo'.
+- Device-independent words: select or choose, not click.
+- No exclamation marks and no 'please'.
+- AI: describe the job, not the technology. 'Ask', 'Draft a reply', 'Summarise applicants'. Mark generated output with AiOrigin ('Assistant · from …') beside it, never a 'Generated by AI' badge or an AI colour. Do not write AI-powered, magic, smart or intelligent.
+- Common contractions (can't, isn't, you're) are fine. Write 'not' in full when the negative is the point and could be missed: 'Do not close this window while the import runs.'
+
+## Accessibility
+
+- Error messages include a suggested fix when one is known.
+- Button text and accessible names match, so speech users can say what they see.
+- Never refer to things by position or colour alone ('the red one', 'above'); avoid directional language.
+
+## Do
+
+- 'Listing closed. It no longer appears on your careers page.'
+- 'Couldn't save' becomes 'Changes not saved. Check your connection and try again.'
+
+## Don't
+
+- Do not write 'Oops! Something went wrong.'
+- Do not write 'Smart suggestions' or 'AI-powered search'.
+- Do not use Title Case In Buttons.
+
+## Related
+
+- Voice and tone
+- Consistency
+- Iconography
+- Accessibility