@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/actions.md

@@ -0,0 +1,74 @@
+# Page actions and row actions
+
+Actions that affect the page or many records sit in the page header or the bulk action bar; one or two frequent actions also sit on each row, and every row action is reachable from the selection too.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** If row actions and page actions live in different places on every screen, people miss them. Rows crowded with buttons are noisy, and actions that exist only on hover can't be found by keyboard or touch users.
+
+**Solution:** Global actions (Create listing, Export, actions on a selection) live in the page header and the bulk action bar. In-context actions live with the thing they change: a row's last column, a card or section header. The full set is always available globally; in-context copies are shortcuts for the common ones.
+
+**Built from:** Page header, Bulk action bar, List table, Data grid, Dropdown menu, Button, Command palette (⌘K)
+
+## How it works
+
+1. List every action and who it acts on: the page or collection (Create listing, Export), a selection (Close, Extend), or one record (Edit, Duplicate).
+2. Put page actions in the page header: up to four buttons, with the single primary action last on the right; more go in a More actions menu.
+3. Put selection actions in the bulk action bar. Any action that can apply to many records is offered there, so nobody repeats it row by row.
+4. On rows, keep one or two of the most used actions as icon buttons and the rest in a More actions menu in the last column. Choose them from usage data.
+5. Put actions for a section or card in that section's header, on the right.
+
+## When to use
+
+- Global: creating a record, exporting, importing, and any action on selected rows.
+- In-context: frequent one-record actions such as Duplicate listing or Copy link, and section actions such as Edit details in the side panel.
+- Section actions: Edit details on a side panel section, Add interviewer on an interview card.
+
+## When not to use
+
+- Row menus for bulk actions. Bulk work belongs in the bulk action bar.
+- A primary button inside a row. Rows use icon buttons or a menu, never filled buttons.
+- Hover-only actions with no menu fallback; touch and keyboard users would never find them.
+
+## Guidelines
+
+- One primary action per view, in the page header.
+- Header order from left to right: status actions (Pause, Reopen), View, Edit, other actions, Delete, then the primary action.
+- Row menus hold up to seven items, most used first, with destructive items last after a separator.
+- The More actions button on each row is always visible; quick icon buttons may appear on row hover or focus, and always on touch screens.
+- Keep the actions column sticky on wide tables so actions stay in view while scrolling sideways.
+- When an action depends on status, such as Reopen on a Closed listing, show the Status column so people see why it is offered.
+- Every action is also in the command palette (⌘K) with its shortcut.
+
+## Content
+
+- Button labels are a verb, plus a noun when the verb alone is unclear: "Create listing", "Export", "Close 2 listings".
+- Menu buttons name their set: "More actions", not "Options" or an unlabelled dots icon.
+- No end punctuation in button or menu labels.
+
+## Accessibility
+
+- Icon-only row actions have an accessible name that includes the record: "Duplicate Junior Product Designer".
+- The More actions button follows the menu button pattern: Enter or Space opens, arrows move, Esc closes and returns focus.
+- Hover-revealed icons also appear when the row has keyboard focus.
+
+## Do
+
+- Do keep the full action set in the header, bulk bar and ⌘K.
+- Do limit rows to one or two visible actions.
+- Do put the primary action last on the right.
+
+## Don't
+
+- Don't make hover the only way to find a row action.
+- Don't put two primary buttons on one page.
+- Don't put actions for the whole table in a row menu.
+
+## Related
+
+- Selection and bulk actions
+- Disabled and read-only states
+- Keyboard-first navigation
+- Page header
+- Bulk action bar
+- Dropdown menu

package/agent/docs-md/agent-activity-log.md

@@ -0,0 +1,70 @@
+# Agent activity log
+
+A chronological list of what agents and the assistant did across runs: time, an icon with a word for the outcome, a past-tense label that links to the run or message, grouped by day.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** A single run shows its own steps, but people ask broader questions: what did the listings agent do this week, which run changed LST-1044, when did someone approve that. Without a log they search through conversations and inbox items from memory.
+
+**Solution:** An activity log on each agent and on the assistant page lists events in time order, newest last within each day, grouped under Today, Yesterday and dated dividers. Each event has a time, a status icon with a word, and a past-tense label that opens the run step, message or record it refers to. A filter narrows by agent, event type or outcome.
+
+**Built from:** Agent run timeline, Grouped list, Filter pills and filter bar, Status badge, Separator, Side panel (drawer), Assistant page
+
+## How it works
+
+1. Group events by day with a labelled divider: Today, Yesterday, then dates such as "Tue 4 Nov 2026".
+2. Each row: time in a fixed-width column, outcome icon with a word, a past-tense label, and who started it.
+3. The label links to where it happened: the run step, the conversation message or the record.
+4. Filter by agent, event type (read, changed, waited, failed) or outcome using the filter bar.
+5. On a long conversation, the assistant page can show the same list as an outline whose rows jump to each message.
+
+## When to use
+
+- On each agent's detail to answer "what did it do and when".
+- On a long task conversation, as an outline to move between key moments.
+- When someone needs to trace which run changed a listing, for example during a review of closing dates.
+
+## When not to use
+
+- While a single run is in progress. Use the agent run timeline with its live steps and Stop.
+- For a record's own change history. Use the record's history, which also shows changes people made.
+- As a notification feed. Things that need someone go to the Inbox.
+
+## Guidelines
+
+- Every event an agent took is in the log: what it read, changed, waited for and failed, with who started the run.
+- Use the same step states and icons as the run timeline; outcome is a word plus an icon, never colour alone.
+- Mark events a person did differently from agent events, with the person's avatar, so approvals and rejections stand out.
+- Omit the time column where the label already links to a timestamped message.
+- Don't auto-scroll to new events unless the person is already at the end of the list.
+
+## Content
+
+- Agent events in the past tense: "Changed closing date on LST-1044", "Read 9 listings".
+- Person events start with the verb: "Approved 2 changes", "Rejected sending to Leeds team".
+- Times in the person's local time, with the full date and time on hover.
+
+## Accessibility
+
+- Day groups are lists with a heading each, so screen reader users can jump by day.
+- New events in an open log are announced politely, at most once every few seconds.
+- Outcome icons have text equivalents; the word is visible, not only in a tooltip.
+
+## Do
+
+- Do link every event to where it happened.
+- Do group by day once activity spans dates.
+- Do mark events people did with their avatar.
+
+## Don't
+
+- Don't pull people to the bottom while they read older events.
+- Don't leave out failed or skipped events to make the log look tidy.
+- Don't show a time column when the label already links to a timestamped message.
+
+## Related
+
+- Agents acting on your behalf
+- Showing reasoning and progress
+- Saved tasks and schedules
+- Agent run timeline

package/agent/docs-md/agent-permissions.md

@@ -0,0 +1,82 @@
+# Agent permissions
+
+Per-action access set in plain words with three levels, Off, Ask first and Allow, grouped into Read and Change.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Setting what an agent may read and change before it runs.
+- Adjusting automation per action as trust grows.
+
+## When not to use
+
+- Approving one specific change. Use Suggested changes (suggested-changes).
+- Connecting an outside account. Use Connected tools (connected-tools).
+
+## Structure
+
+1. Group header (Read, Change) with summary level
+2. Permission rows (action, what it covers, Off / Ask first / Allow segmented control)
+
+## Guidelines
+
+- Three levels per action: Off, Ask first, Allow.
+- Defaults: reading Allow, changes Ask first, anything that reaches people outside the workspace Off.
+- Group by Read and Change and describe each in plain words ("Sends from your address").
+- Ask first is just-in-time consent: the agent pauses with a proposal. Set up front only the default, not a one-off decision.
+- Remind people of the setting when it blocks a step ("Email is Off in permissions") with a link to change it.
+- Candidate data is personal data; keep it Ask first so a person reviews each use.
+- Per-run choices ("Allow once", "Allow in this conversation") never change the saved level; only "Always allow" does, and it shows here as Allow with who set it and when.
+- Allow is never preselected or focused when a level is offered for a risky action.
+
+## Content
+
+- Name actions, not systems: "Edit, extend or close listings", "Email candidates".
+- Detail line says what it covers or what happens ("Shows a proposal before each change").
+
+## Accessibility
+
+- Each segmented control is a group labelled by its row, with toggle buttons using aria-pressed (APG button).
+- Alternatively use a radiogroup with arrow keys; pick one and use it consistently (SC 3.2.4).
+- Changing a level must not change context (SC 3.2.2).
+- The selected state is shown with more than colour (SC 1.4.1, 1.4.11).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move between permission rows |
+| Enter / Space | Set the focused level |
+
+## Examples
+
+### levels
+
+```tsx
+import { AgentPermissions, type Permission } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Off, Ask first or Allow", description: "Reading defaults to Allow, changes to Ask first, anything that reaches people outside the workspace to Off. Decisions about candidates can never be set to Allow.", order: 1 };
+
+export default function Example() {
+	const [items, setItems] = useState<Permission[]>([
+		{ id: "r1", group: "Read", action: "Read listings and applicants", covers: "Titles, descriptions, stages and counts", level: "allow" },
+		{ id: "r2", group: "Read", action: "Read team files", covers: "Salary bands and the hiring handbook", level: "allow" },
+		{ id: "c1", group: "Change", action: "Edit listings", covers: "Titles, descriptions, closing dates", level: "ask" },
+		{ id: "c2", group: "Change", action: "Move candidates between stages", covers: "Screen, interview, offer, reject", level: "ask", neverAllow: true },
+		{ id: "c3", group: "Change", action: "Email candidates", covers: "Sends from your address", level: "off" },
+	]);
+	return <div className="w-full max-w-2xl"><AgentPermissions items={items} onChange={(id, level) => setItems((x) => x.map((p) => (p.id === id ? { ...p, level } : p)))} /></div>;
+}
+```
+
+## Related
+
+- Agent run timeline
+- Suggested changes
+- Connected tools
+- Segmented control
+- Plan preview
+- Change review
+- Connector picker

package/agent/docs-md/agent-run.md

@@ -0,0 +1,90 @@
+# Agent run timeline
+
+The steps of an agent run with state in shape and colour, the filter each step used, a highlighted waiting step and Stop always visible.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Watching or reviewing an agent run, scheduled or started from a task.
+- When a run is waiting for approval, to show what it needs.
+
+## When not to use
+
+- A single answer. Use Thinking and steps (thinking-steps).
+- Applying a proposal you just approved. Use the Step card (step-card).
+- Listing everything that needs you across runs. Use the Inbox (inbox).
+
+## Structure
+
+1. Header (task name, status badge, Stop)
+2. Step rows (state icon, title, detail, action)
+3. Footer (started by, when, schedule)
+
+## Guidelines
+
+- Every step has a state: done, running, waiting for you, skipped, failed.
+- Steps that pick rows show the filter used and open it as a view.
+- A waiting step is highlighted and holds its action (Review).
+- Stop is always visible and in the same place.
+- Skipped steps say why and link to the setting.
+- Record who started it, when and on what schedule, and keep the log.
+- In parallel steps, a failed step shows its own error and Retry on its row while the rest keep running; the run isn't shown as blocked.
+- Failed and stopped steps are never counted as done; the counts add up to the steps shown.
+
+## Content
+
+- Step titles say what happened in past tense with counts ("Found 2 live listings under 3%").
+- Badge text is a state, not a mood: "Needs you", "Done", "Failed".
+
+## Accessibility
+
+- States combine an icon shape, colour and text (SC 1.4.1, 1.4.11).
+- Use a list with each step as a list item so the order is exposed (SC 1.3.1).
+- Announce new steps and a change to "Needs you" as status messages (SC 4.1.3).
+- Running runs are auto-updating content in parallel with the page; Stop meets SC 2.2.2.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through step actions |
+| Enter | Open the step's view or Review |
+| Enter on Stop | Stop the run |
+
+## Examples
+
+### run
+
+```tsx
+import { AgentRun, Button } from "@twoux/ui";
+
+export const meta = { title: "One run, step by step", description: "Every step has a state in shape and words. A step that picked rows names its filter; the waiting step is highlighted and holds its action.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="w-full max-w-xl">
+			<AgentRun
+				task="Weekly listing check"
+				status="Needs you"
+				meta="Started by Priya Shah · Monday 09:00 · Every Monday"
+				steps={[
+					{ title: "Found listings closing within 7 days", detail: "Filter: Closes is in the next 7 days · 3 listings", state: "done", action: <Button variant="ghost" size="xs">Open as view</Button> },
+					{ title: "Compared applicants with similar listings", state: "done" },
+					{ title: "Proposed extending 2 listings by 30 days", detail: "Waiting for your review", state: "waiting", action: <Button size="xs">Review</Button> },
+					{ title: "Post a summary to #hiring", state: "skipped", detail: "Skipped until the review is done" },
+				]}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Agent permissions
+- Task builder
+- Step card
+- Inbox (triage)
+- Plan preview
+- Change review

package/agent/docs-md/agents-on-behalf.md

@@ -0,0 +1,74 @@
+# Agents acting on your behalf
+
+Agents work within permissions set per action (Off, Ask first, Allow), show every run as a list of steps, stop to wait for you through the Inbox, and can always be stopped.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** An agent that renames listings or emails candidates on a schedule acts while nobody watches. Without clear permissions, run history and a single place to approve, people either don't trust agents or are surprised by them.
+
+**Solution:** Permissions are set up front per action in plain words, with safe defaults. Each run is a timeline of steps with state. A step that needs approval waits, is marked Needs you and appears in the Inbox. Stop is always visible.
+
+**Built from:** Agent permissions, Agent run timeline, Inbox (triage), Suggested changes, Connected tools, Clarifying question card
+
+## How it works
+
+1. Set permissions per action before the first run: Read defaults to Allow, changes to Ask first, anything that reaches people outside the workspace to Off.
+2. The run shows each step with its state in shape and colour: done, running, waiting for you, skipped, failed.
+3. Steps that pick rows show the filter they used and open it as a view.
+4. A step that needs approval holds its action, is highlighted, says which permission caused it ("Edit listings is set to Ask first") and appears in the Inbox as Needs you.
+5. Approve in the Inbox detail without leaving; the run continues. Rejecting is acknowledged in the run ("Skipped").
+6. Stop is always visible. A stopped run keeps what it did and says what it didn't.
+
+## When to use
+
+- For multi-step work that runs without the person watching: scheduled tasks, long enrichment, follow-ups.
+
+## When not to use
+
+- For high-risk actions where silence would count as consent. Those stay Off or Ask first, never notice-only.
+
+## Guidelines
+
+- Permissions are explicit, editable and never buried in setup; changing one is one click from the run that hit it.
+- Each permission says in plain words what it allows: "Sends from your address".
+- Before a scheduled run makes changes, a notice lets people review or cancel.
+- Every run records who started it, when, what it read and changed, in an activity log that can be queried.
+- A request waiting for approval never blocks forever; it expires and reports that nothing ran.
+- Start with low automation; people raise it per action once they trust the results.
+- Agents are never disabled or deleted without someone choosing to.
+- When a run needs approval in a conversation, show an approval card above the composer with what will run, in plain words, and the tool name in code style.
+- For a tool the run will call again, offer "Allow once" and "Allow in this conversation". "Always allow" changes the agent's permission to Allow and is offered only for Read and reversible changes inside the workspace.
+- Before approval, say whether it can be undone and who else will see it: "Can be undone for 7 days. Applicants won't be notified."
+- After a decision the card closes at once and the thread keeps a resolved line: Approved, Rejected, Approved automatically, or Expired with "Nothing was sent."
+- If the person rejects, the assistant acknowledges it and carries on without that step: "Skipped emailing the Leeds team."
+- Irreversible actions use the confirmation dialog; when one record is affected the person types its name, when several the dialog lists them. Never both.
+
+## Content
+
+- Run titles say the goal: "Rename low-performing listings". Footer: "Started by Rahul S. · 2 min ago · Every Monday".
+- Decisions are logged in past tense: "Approved", "Skipped: email hiring managers. Email is Off in permissions."
+
+## Accessibility
+
+- Step states use icon shape and a word, not colour alone.
+- The approval card is not a modal: focus moves to its heading, not to Allow, and the thread stays reachable.
+- Resolved states are text, and an expiry is posted as a message in reading order.
+
+## Do
+
+- Do default anything that reaches people outside the workspace to Off.
+- Do show which permission made a step wait or skip, with a Change link.
+
+## Don't
+
+- Don't hide permissions in settings only.
+- Don't treat silence as consent for risky actions.
+
+## Related
+
+- Propose, then apply
+- Notifications: inbox, bell, toast or email digest
+- Saved tasks and schedules
+- Showing reasoning and progress
+- Agent permissions
+- Agent run timeline

package/agent/docs-md/ai-column.md

@@ -0,0 +1,85 @@
+# AI column
+
+A generated table column that fills one row at a time, cites each row, shows when it was written and never overwrites real data.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Adding a judgement or summary per row, such as "Likely reason" for a low apply rate.
+- When people need to compare many rows on the same question.
+
+## When not to use
+
+- Changing real fields such as title or closing date. Use Suggested changes (suggested-changes).
+- One-off questions. Use the Assistant side panel (assistant-panel).
+- Decisions about candidates that would filter or rank them for hiring. These are high-risk; keep them as human decisions with the assistant as a reference only.
+
+## Structure
+
+1. Header (assistant mark, name, "2 min ago", Refresh)
+2. Cells (value and citation, writing state, failed state with Try again)
+3. Add a column menu (suggested columns, Describe your own…)
+
+## Guidelines
+
+- Mark the header once and show when the column was written.
+- Never overwrite real data; the column is separate and can be removed.
+- Cells fill one by one with a visible state and a Stop. A failed cell says why ("The listing has no description") and offers Try again.
+- Each cell cites its record.
+- When source data changes, mark the column out of date instead of silently rewriting.
+- Show the cost per row before running on the whole table, and test on a few rows first.
+
+## Content
+
+- Name columns by the question they answer ("Likely reason", "Risk of closing empty").
+- Cell text is short and leads with the judgement: "Many views, few applies."
+- Failed cells explain in plain words and say what to do.
+
+## Accessibility
+
+- Follow the grid pattern: arrow keys move between cells, Enter or F2 to act, Esc to return (APG grid).
+- Header is a columnheader; the Refresh button has a name ("Refresh column") (SC 4.1.2).
+- Announce progress and completion ("12 of 24 written") as a status message (SC 4.1.3); filling cells is auto-updating content that needs Stop (SC 2.2.2).
+- Writing, failed and out-of-date states use text, not colour alone (SC 1.4.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Arrow keys | Move between cells |
+| Enter / F2 | Act on the cell, for example Try again |
+| Esc | Return to grid navigation |
+
+## Examples
+
+### summaries
+
+```tsx
+import { AiCell, type AiCellState, AiColumnHeader, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "A generated column", description: "Marked once in the header with when it was written. Cells fill one at a time, each cites its record, and a failed cell says why with Try again. Real data is never overwritten.", order: 1 };
+
+const ROWS = [["LST-1040", "Junior Product Designer", "Portfolio, Figma, hybrid in Leeds"], ["LST-1041", "Frontend Engineer", "React and TypeScript, 3+ years"], ["LST-1043", "Recruitment Coordinator", ""], ["LST-1045", "QA Engineer", "Playwright, CI, test plans"]];
+
+export default function Example() {
+	const [n, setN] = useState(0);
+	useEffect(() => { if (n < ROWS.length) { const t = setTimeout(() => setN((x) => x + 1), 600); return () => clearTimeout(t); } }, [n]);
+	const cell = (i: number): AiCellState => (i > n ? { state: "queued" } : i === n ? { state: "writing" } : ROWS[i][2] ? { state: "done", value: ROWS[i][2], source: ROWS[i][0] } : { state: "failed", reason: "The listing has no description" });
+	return (
+		<div className="w-full overflow-hidden rounded-sm border border-line">
+			<Table aria-label="Listings with requirements summary">
+				<TableHeader><TableRow><TableHead>Listing</TableHead><TableHead className="bg-primary-soft/40"><AiColumnHeader name="Key requirements" written={n >= ROWS.length ? "just now" : "writing"} onRefresh={() => setN(0)} /></TableHead></TableRow></TableHeader>
+				<TableBody>{ROWS.map((r, i) => <TableRow key={r[0]}><TableCell className="font-medium text-ink">{r[1]}</TableCell><TableCell className="max-w-72 bg-primary-soft/20"><AiCell cell={cell(i)} onRetry={() => setN(i)} /></TableCell></TableRow>)}</TableBody>
+			</Table>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Prompt editor with fields
+- Citations and sources
+- AI origin label

package/agent/docs-md/ai-origin-label.md

@@ -0,0 +1,70 @@
+# AI origin label
+
+One small mark and short text on generated content, such as "Assistant · from your workspace data". No sparkle on every button and no separate AI colour.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Under every assistant answer, with the feedback actions.
+- On a generated column header, once for the group, not on every cell.
+- Where generated and human content sit together, so people can tell them apart.
+
+## When not to use
+
+- On buttons that start an action. Name the action instead ("Draft titles"), and keep the mark for content.
+- As decoration or branding across the product.
+- To say where a value came from. Use Citations and sources (citations-sources).
+
+## Structure
+
+1. Assistant mark (icon)
+2. Text (who and from what)
+3. Optional time ("2 min ago")
+
+## Guidelines
+
+- Label the origin, not the feature. Say what produced it and from what.
+- One mark per group of generated content: a column header, an answer.
+- No separate AI colour. TwoUX uses its neutral palette plus a faint tint on generated columns, always with the mark and text.
+- Do not use the sparkle as the universal AI sign; it loses meaning when it is everywhere.
+- Generated output must also be machine-detectable as generated, for example a data attribute or metadata on the record.
+
+## Content
+
+- "Assistant · from your workspace data". Never "AI-powered", "smart" or "magic".
+- When a person edits generated text, the label goes; the history keeps the original.
+
+## Accessibility
+
+- The mark is decorative (aria-hidden) and the text carries the meaning (SC 1.3.1, 1.4.1).
+- The tint on generated columns must keep text contrast; the column header text identifies it (SC 1.4.11 for the mark).
+- Use the same wording everywhere (SC 3.2.4).
+
+## Examples
+
+### labels
+
+```tsx
+import { AiOrigin } from "@twoux/ui";
+
+export const meta = { title: "Say what made it, from what", description: "One small mark and plain words, once per group of generated content. No separate AI colour, no gradients.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid gap-3">
+			<AiOrigin from="your workspace data" time="2 min ago" />
+			<AiOrigin from="24 listings and the 2026 salary bands" />
+			<div className="rounded-sm border border-line bg-surface p-3"><AiOrigin from="the job description" /><p className="mt-1.5 text-base text-ink">Junior designer with a portfolio of 2 or 3 product case studies; Figma required; hybrid in Leeds.</p></div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- AI column
+- Citations and sources
+- Confidence note
+- Why this choice

package/agent/docs-md/announcing-features.md

@@ -0,0 +1,73 @@
+# Announcing new and beta features
+
+Mark new or beta things where people meet them, with a small text label that opens a short explanation. Keep a What's new list for the rest. Never use toasts or banners for announcements.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Launch messages compete with the messages people need to act on. Banners about a new report push down the list, popovers open on page load, and New labels stay for months until nobody notices them.
+
+**Solution:** A New or Beta text label sits next to the new thing for 30 days. Pressing it opens a popover of one or two sentences and Learn more. A What's new list in the Help menu keeps the last 90 days. Beta pages also carry "Beta" after the page title and a feedback link. Status messages always come first.
+
+**Built from:** App shell and sidebar navigation, Page header, Popover rules, Banner (inline alert), Tabs (underline), List table
+
+## How it works
+
+1. Decide the size of the change. A new page or area: label in the sidebar. A new tab, column, field or option: label next to its name. A small fix: no label, What's new only.
+2. Add a text label "New" (or "Beta") after the name. It is a button that opens a popover: a heading, one or two sentences on what it does for the team, and Learn more.
+3. Remove New labels after 30 days. Beta labels stay until the feature is generally available.
+4. Add the item to What's new in the Help menu, which shows an unread dot until opened.
+5. For a beta page, add "Beta" after the page title too, since people arrive by links, with a line on what may change and a Send feedback link.
+
+## When to use
+
+- New: a whole new page, tab, column, field or option that changes what people can do.
+- Beta: a feature that may change, may be removed, or is not yet suitable for decisions that matter, such as an early AI shortlist summary.
+- A banner on Home only when the whole product or workspace is in beta. It cannot be dismissed on Home and can be elsewhere.
+
+## When not to use
+
+- Not for bug fixes, speed improvements or small layout changes.
+- Never as a toast, an auto-opening popover or a page banner for a single feature. Those slots are for status.
+- Don't mark something both New and Beta. Beta wins.
+
+## Guidelines
+
+- Status messages always win. If a page has an error or a warning, no announcement appears beside it.
+- The label is plain text in the accent colour at the caption size, not a status badge or a tag, so it is never mistaken for a record's state or a category.
+- Label each new page, never a group heading, so the label never competes with the group's own toggle.
+- Explanations lead with what the person can now do: "Compare time to hire across teams." Not the feature's name or the release.
+- Beta explanations say what that means for the work: "Results may change. Check them before you use them in a hiring decision."
+- Plan the end: a beta popover says when general availability is expected, if known.
+
+## Content
+
+- Labels are one word: "New" or "Beta". TwoUX has no "Preview" state.
+- Popover heading names the capability: "Interview load by person". Not "Introducing...".
+- Beta page title: "Pipeline forecast" followed by the Beta label, not "Pipeline forecast (Beta version)".
+
+## Accessibility
+
+- The label is a button with an accessible name such as "New: Interview load, more information", and opens its popover on Enter or Space.
+- The popover closes on Esc and returns focus to the label; it never opens on hover or page load.
+- The label is text, readable at the caption size against the sidebar background.
+
+## Do
+
+- Do announce in the place where the feature is used.
+- Do keep each explanation to two sentences and a link.
+- Do give every beta a way to send feedback.
+
+## Don't
+
+- Don't open an announcement on page load.
+- Don't leave New labels beyond 30 days.
+- Don't rely on email or release notes alone to tell people a feature is in beta.
+
+## Related
+
+- Onboarding to an empty workspace
+- Navigation: what goes in the sidebar and the top bar
+- Notifications: inbox, bell, toast or email digest
+- Labelling AI output
+- Banner (inline alert)
+- Popover rules