@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/list-table.md

@@ -0,0 +1,254 @@
+# List table
+
+A read-mostly table for scanning and triaging records such as listings or candidates, with a sticky header, sortable columns, J and K row focus and checkbox selection.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- People need to find records that match criteria, compare them, and act on one or several. These are the core table tasks.
+- Every record has the same attributes and the set will keep growing, such as all live listings or an applicant inbox.
+- People will scan, sort and analyse large volumes of rows rather than read each one.
+
+## When not to use
+
+- To edit cells, enrich with AI or total columns. Use the TwoUX Data grid, because a table is not an interactive widget and its cells are not focusable.
+- For a short list of items under shared headings, such as candidates by stage. Use the TwoUX Grouped list.
+- For page layout. Tables are only for structured data.
+- For one figure that matters. Use the TwoUX Stat card with comparison instead of a one-row table.
+
+## Structure
+
+1. Table header (title, item count, actions)
+2. Filter bar
+3. Sticky column header row
+4. Selection checkbox column
+5. Identifying column (Role)
+6. Data columns
+7. Row focus indicator
+8. Footer (count, selection count, pagination)
+
+## Guidelines
+
+- Keep the column header row visible on scroll when a table has more than 30 items per page, more than five columns or sortable columns.
+- Put a human-readable identifier (the Role) first and order the remaining columns by importance.
+- Only the sorted column shows its arrow; the others reveal it on hover. Expose the current sort with aria-sort on that header only.
+- J and K (or the arrow keys) move row focus, X toggles selection, Enter opens the row in the side panel, Esc clears. Show each shortcut on its button so experts learn it.
+- The header checkbox selects only the rows on the current page, and the footer reads "2 of 24 selected".
+- Open a row in a non-modal side panel so the table stays visible; modals hide neighbouring rows.
+- Never add cell editing or a totals row to a list table; that is the Data grid's job.
+- For spreadsheet-like data people scan many rows of, such as an inventory, a ledger, an import or a mapping, use size="dense" (28px rows) and the Dense table parts. Keep the default 36px rows for everything else. Dense is a variant for that data, never a setting people switch.
+
+## Content
+
+- Left-align text and right-align numbers with a consistent number of decimals, in tabular figures.
+- Write column labels as short, plain nouns.
+- Show the total next to the title, and the selected count before the total when rows are selected. Hide the count while loading.
+- Show a dash for an empty value and give it hidden text for screen readers, never a blank cell.
+- Status is a bordered pill with a word, never colour alone.
+
+## Accessibility
+
+- 1.3.1 Info and Relationships: mark up header cells with scope="col" (and scope="row" for the Role cell) so each value is tied to its column.
+- APG table pattern: use table semantics with an accessible name from a caption or aria-label, and aria-sort on the sorted header only.
+- 2.1.4 Character Key Shortcuts: J, K, X, E and / are single-key shortcuts, so TwoUX lets people turn them off in settings.
+- 2.4.7 Focus Visible: the focused row shows a visible indicator, and highlighted rows are never the only signal of selection or focus.
+- 2.4.11 Focus Not Obscured: the sticky header must not fully cover the focused row; use scroll padding.
+- Give repeated row actions unique names, for example "Open Junior Product Designer" rather than "Open".
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| J / ↓ | Move row focus down |
+| K / ↑ | Move row focus up |
+| ⇧J / ⇧K | Extend selection down or up |
+| X | Select or deselect the focused row |
+| Enter | Open the focused row in the side panel |
+| Esc | Close the side panel, or clear the selection |
+| / | Focus search |
+| F | Open the filter field list |
+| ⇧P | Switch the side panel between push and overlay |
+
+## Examples
+
+### listings
+
+```tsx
+import {
+	AlertDialog,
+	AlertDialogAction,
+	AlertDialogCancel,
+	AlertDialogContent,
+	AlertDialogDescription,
+	AlertDialogFooter,
+	AlertDialogHeader,
+	AlertDialogTitle,
+	Badge,
+	BulkActionBar,
+	Button,
+	Checkbox,
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuSeparator,
+	DropdownMenuTrigger,
+	Table,
+	TableBody,
+	TableCell,
+	TableHead,
+	TableHeader,
+	TablePagination,
+	TableRow,
+	TableSortHead,
+	toast,
+	useRowKeyboard,
+} from "@twoux/ui";
+import { type ColumnDef, type RowSelectionState, type SortingState, flexRender, getCoreRowModel, getPaginationRowModel, getSortedRowModel, useReactTable } from "@tanstack/react-table";
+import { CalendarPlus, CircleX, Copy, Ellipsis, Pencil, Trash2 } from "lucide-react";
+import { useMemo, useState } from "react";
+import { LISTINGS, type Listing, STATUS_VARIANT, formatDate } from "./data";
+
+export const meta = { title: "Listings", description: "Click a header to sort; only the sorted column shows its arrow. Select rows to bring up the bulk bar. Focus the table and use J/K to move, X to select, Esc to clear.", order: 1 };
+
+export default function Example() {
+	const [sorting, setSorting] = useState<SortingState>([{ id: "closes", desc: false }]);
+	const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+	const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 8 });
+	const [confirm, setConfirm] = useState(false);
+
+	const columns = useMemo<ColumnDef<Listing>[]>(
+		() => [
+			{
+				id: "select",
+				header: ({ table }) => (
+					<Checkbox
+						aria-label="Select all on this page"
+						checked={table.getIsAllPageRowsSelected() || (table.getIsSomePageRowsSelected() && "indeterminate")}
+						onCheckedChange={(v) => table.toggleAllPageRowsSelected(!!v)}
+					/>
+				),
+				cell: ({ row }) => <Checkbox aria-label={`Select ${row.original.role}`} checked={row.getIsSelected()} onCheckedChange={(v) => row.toggleSelected(!!v)} />,
+				enableSorting: false,
+			},
+			{ accessorKey: "role", header: "Role", cell: ({ row }) => <span className="font-medium text-ink">{row.original.role}</span> },
+			{ accessorKey: "location", header: "Location", cell: ({ getValue }) => <span className="text-ink-2">{getValue<string>()}</span> },
+			{ accessorKey: "status", header: "Status", cell: ({ row }) => <Badge variant={STATUS_VARIANT[row.original.status]} dot>{row.original.status}</Badge> },
+			{ accessorKey: "applicants", header: "Applicants", meta: { align: "right" }, cell: ({ getValue }) => <span className="tabular block text-right">{getValue<number>()}</span> },
+			{ accessorKey: "closes", header: "Closes", cell: ({ getValue }) => <span className="tabular text-ink-2">{formatDate(getValue<string>())}</span> },
+			{ id: "actions", header: () => <span className="sr-only">Actions</span>, enableSorting: false, cell: ({ row, table }) => <RowMenu listing={row.original} disabled={table.getSelectedRowModel().rows.length > 0} /> },
+		],
+		[],
+	);
+
+	const table = useReactTable({
+		data: LISTINGS,
+		columns,
+		state: { sorting, rowSelection, pagination },
+		onSortingChange: setSorting,
+		onRowSelectionChange: setRowSelection,
+		onPaginationChange: (u) => {
+			setPagination(u);
+			setRowSelection({}); // changing page clears the selection
+		},
+		getRowId: (r) => r.id,
+		getCoreRowModel: getCoreRowModel(),
+		getSortedRowModel: getSortedRowModel(),
+		getPaginationRowModel: getPaginationRowModel(),
+	});
+
+	const rows = table.getRowModel().rows;
+	const selected = table.getSelectedRowModel().rows.length;
+	const clear = () => setRowSelection({});
+	const keys = useRowKeyboard({ count: rows.length, onToggle: (i, v) => rows[i]?.toggleSelected(v), onOpen: (i) => toast(`Opened ${rows[i].original.role}`), onClear: clear, selected });
+
+	return (
+		<div className="w-full overflow-hidden rounded-sm border border-line bg-surface">
+			<BulkActionBar
+				count={selected}
+				noun={selected === 1 ? "listing" : "listings"}
+				onClear={clear}
+				actions={[
+					{ label: "Extend 30 days", icon: <CalendarPlus />, shortcut: "T", onSelect: () => { toast.success(`Extended ${selected} listing${selected === 1 ? "" : "s"} by 30 days`, { action: { label: "Undo", onClick: () => {} } }); clear(); } },
+					{ label: "Duplicate", icon: <Copy />, shortcut: "D", onSelect: () => { toast.success(`Duplicated ${selected} listing${selected === 1 ? "" : "s"}`); clear(); } },
+					{ label: "Close listings", icon: <CircleX />, destructive: true, onSelect: () => setConfirm(true) },
+				]}
+			/>
+			<Table aria-label="Listings">
+				<TableHeader>
+					{table.getHeaderGroups().map((hg) => (
+						<TableRow key={hg.id} className="hover:bg-transparent">
+							{hg.headers.map((h) => {
+								const right = (h.column.columnDef.meta as { align?: string } | undefined)?.align === "right";
+								if (!h.column.getCanSort()) return <TableHead key={h.id} className={h.id === "select" ? "w-9" : "w-10"}>{flexRender(h.column.columnDef.header, h.getContext())}</TableHead>;
+								return (
+									<TableSortHead key={h.id} sorted={h.column.getIsSorted()} onSort={() => h.column.toggleSorting(h.column.getIsSorted() === "asc")} align={right ? "right" : "left"}>
+										{flexRender(h.column.columnDef.header, h.getContext())}
+									</TableSortHead>
+								);
+							})}
+						</TableRow>
+					))}
+				</TableHeader>
+				<TableBody {...keys.bodyProps} aria-label="Listings, use J and K to move, X to select">
+					{rows.map((row, i) => (
+						<TableRow key={row.id} data-state={row.getIsSelected() ? "selected" : undefined} {...keys.rowProps(i)}>
+							{row.getVisibleCells().map((cell) => (
+								<TableCell key={cell.id}>{flexRender(cell.column.columnDef.cell, cell.getContext())}</TableCell>
+							))}
+						</TableRow>
+					))}
+				</TableBody>
+			</Table>
+			<TablePagination
+				page={pagination.pageIndex}
+				pageCount={table.getPageCount()}
+				pageSize={pagination.pageSize}
+				total={LISTINGS.length}
+				selected={selected}
+				noun="listings"
+				onPageChange={(p) => table.setPageIndex(p)}
+			/>
+			<AlertDialog open={confirm} onOpenChange={setConfirm}>
+				<AlertDialogContent>
+					<AlertDialogHeader>
+						<AlertDialogTitle>Close {selected} listings?</AlertDialogTitle>
+						<AlertDialogDescription>They come off every job board today. Applicants and notes are kept.</AlertDialogDescription>
+					</AlertDialogHeader>
+					<AlertDialogFooter>
+						<AlertDialogCancel>Keep open</AlertDialogCancel>
+						<AlertDialogAction variant="destructive" onClick={() => { toast.success(`${selected} listing${selected === 1 ? "" : "s"} closed`); clear(); }}>Close listings</AlertDialogAction>
+					</AlertDialogFooter>
+				</AlertDialogContent>
+			</AlertDialog>
+		</div>
+	);
+}
+
+function RowMenu({ listing, disabled }: { listing: Listing; disabled: boolean }) {
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button variant="ghost" size="icon-sm" aria-label={`Actions for ${listing.role}`} disabled={disabled}><Ellipsis /></Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="end">
+				<DropdownMenuItem><Pencil />Edit</DropdownMenuItem>
+				<DropdownMenuItem><Copy />Duplicate</DropdownMenuItem>
+				<DropdownMenuSeparator />
+				<DropdownMenuItem variant="destructive"><Trash2 />Close listing</DropdownMenuItem>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
+```
+
+## Related
+
+- Data grid
+- Filter pills and filter bar
+- Bulk action bar
+- Pagination and counts
+- Columns menu
+- Saved views
+- Grouped list
+- Dense table

package/agent/docs-md/loading-skeleton.md

@@ -0,0 +1,91 @@
+# Loading skeleton
+
+Grey placeholder rows that keep the table or panel's shape while data loads.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- First load of a table, list or panel whose layout is known.
+- Loads that take roughly 1 to 10 seconds.
+- Several parts of a view load at once and each can fill in as it arrives.
+
+## When not to use
+
+- Loads under 1 second. Show nothing and render the data.
+- A single action in progress, such as Apply or Run. Use the button's inline spinner.
+- Work over 10 seconds or with known progress, such as an agent run. Use a progress indicator with a count ("2 / 5").
+- Popovers, menus, toasts or dialogs, whose content should already be loaded.
+
+## Structure
+
+1. Region header kept ("Loading listings…")
+2. Skeleton rows at the real row height (36px)
+3. Bars per column: checkbox, title, secondary, right-aligned figure
+4. Shimmer animation (off with reduced motion)
+
+## Guidelines
+
+- Match the real layout: same row height, same column positions, varied bar widths so it reads as text, numbers on the right.
+- Keep the header, filters and page actions live; only the data region shows the skeleton.
+- Replace the skeleton as soon as data arrives, section by section where possible.
+- Never combine a skeleton with a spinner in the same region.
+- Shimmer runs at 1.4 s per cycle and stops when prefers-reduced-motion is set.
+- If loading fails, swap to the Error state in the same space.
+
+## Content
+
+- The region header says what is loading, short, without articles: "Loading listings…".
+- No other text inside the skeleton; it holds space, it does not explain.
+- Never rely on a bare "Loading…" message alone for longer waits; the skeleton shows where the data will appear, and long runs show a count.
+
+## Accessibility
+
+- Mark the region aria-busy while loading and give it a label ("Loading listings"); skeleton bars are hidden from assistive technology.
+- Do not announce every load; announce only the result, such as the row count, through a polite live region (4.1.3).
+- Shimmer shown next to usable content must stop within 5 seconds or be pausable; TwoUX's reduced-motion setting stops it (2.2.2, 2.3.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| None | No keyboard interaction; filters and page actions stay usable while it loads |
+
+## Examples
+
+### table
+
+```tsx
+import { Skeleton } from "@twoux/ui";
+
+export const meta = { title: "Table rows", description: "Rows keep the real 36px height and column positions. Bars vary in width so they read as text; the figure sits on the right. The header stays live.", order: 1 };
+
+const WIDTHS = ["w-40", "w-52", "w-36", "w-48", "w-44"];
+
+export default function Example() {
+	return (
+		<div className="w-full max-w-xl overflow-hidden rounded-sm border border-line bg-surface" aria-busy="true" aria-label="Loading listings">
+			<div className="grid h-9 grid-cols-[16px_1fr_96px_64px] items-center gap-3 border-b border-line bg-surface-2 px-3 text-sm font-medium text-ink-2">
+				<span />
+				<span>Listing</span>
+				<span>Location</span>
+				<span className="text-right">Applicants</span>
+			</div>
+			{WIDTHS.map((w, i) => (
+				<div key={w + i} className="grid h-9 grid-cols-[16px_1fr_96px_64px] items-center gap-3 border-b border-line px-3 last:border-b-0">
+					<Skeleton className="size-3.5" />
+					<Skeleton className={`h-2.5 ${w}`} />
+					<Skeleton className="h-2.5 w-16" />
+					<Skeleton className="ml-auto h-2.5 w-6" />
+				</div>
+			))}
+		</div>
+	);
+}
+```
+
+## Related
+
+- Empty state
+- Error state (failed to load)
+- Side panel (drawer)

package/agent/docs-md/managing-agents.md

@@ -0,0 +1,71 @@
+# Managing agents
+
+One Agents page lists every agent with its source, what it does, whether it is on and where it may act. People turn agents on and off with Undo, edit scope in the side panel, and agents are never switched off or deleted without someone choosing to.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** As a team adds agents (a listings checker, a scheduler, a third-party sourcing tool), nobody can see in one place which are on, who added them, what they can reach and which listings they touch. Trust drops when an agent acts somewhere people didn't expect.
+
+**Solution:** An Agents page with a list table: name and avatar, source, short description, capabilities as tags, scope, status as a word badge and an On switch. Selecting a row opens the agent in the side panel with its permissions, scope and activity log. Add agent sits in the page header.
+
+**Built from:** Page header, List table, Filter pills and filter bar, Switch, Status badge, Tag, Side panel (drawer), Agent permissions, Connected tools, Toast, Inbox (triage)
+
+## How it works
+
+1. List agents in a table with name, source (TwoUX, your team, or the third party that provides it), what it does, scope, owner and status.
+2. Turn an agent on or off with its switch. The change applies at once with a toast and Undo; runs in progress finish or stop as the person chooses.
+3. Open a row to see and edit its permissions per action, its scope (which teams, listings or locations) and its activity log.
+4. Add agent opens the templates gallery or connected tools; a new agent starts Off with changes set to Ask first.
+5. If an agent can't run (a connection expired), mark it "Needs attention" and send its owner an Inbox item. Don't switch it off.
+
+## When to use
+
+- When a workspace has more than one agent, or any agent from a third party.
+- To answer "what can act on our listings, and who said it could".
+- When an admin reviews access, for example before a new team joins the workspace.
+
+## When not to use
+
+- To set what one agent may do in a single run. Use the permission card in the run (Ask first, Allow).
+- For outside tools the assistant can read from. Use Connected tools.
+- For saved tasks a person runs themselves. Those live in Saved tasks.
+
+## Guidelines
+
+- Show the source next to the name so people can judge trust before turning an agent on.
+- Permissions and scope are visible on the page and editable in place, never only inside a setup flow.
+- Never switch off or delete an agent automatically. Failures are reported, not acted on.
+- Actions that decide on candidates (reject, advance, score for shortlisting) can't be set to Allow for any agent; they stay with a person.
+- Deleting an agent removes its schedule but keeps its activity log. It is irreversible, so it uses the confirmation dialog.
+
+## Content
+
+- Page title "Agents" with one line: "Agents that can read or change your hiring data, and where."
+- Status words: On, Off, Needs attention. Capability tags are verbs: "Reads listings", "Suggests closing dates".
+- Button: "Add agent".
+
+## Accessibility
+
+- Each switch is named with the agent: "Turn on Listings checker".
+- Status is a word in a badge, so it reads without colour.
+- The switch change and its Undo are announced as a status message.
+
+## Do
+
+- Do show source, scope and status at a glance.
+- Do start new agents Off with changes on Ask first.
+- Do let people edit scope from the row's side panel.
+
+## Don't
+
+- Don't auto-disable or delete an agent.
+- Don't let any agent be allowed to decide on candidates.
+- Don't hide permissions inside the setup flow.
+
+## Related
+
+- Agents acting on your behalf
+- Agent activity log
+- Saved tasks and schedules
+- Agent permissions
+- Connected tools

package/agent/docs-md/message-composer.md

@@ -0,0 +1,105 @@
+# Message composer
+
+The message box with context chips, a + menu, @ mentions, / saved tasks, typeahead completions and the Quick or Thorough answer mode.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Any free question or instruction to the assistant, in the panel or on the full page.
+- When people need to add or narrow context: @ adds a record as a chip, the + menu attaches files and tools.
+- When the trade-off between speed and depth matters: Quick reads what is on screen, Thorough also reads candidates and past listings and says what it costs.
+
+## When not to use
+
+- A task that repeats with the same inputs. Use the Task builder (task-builder) with slots.
+- A prompt that runs on every row. Use the Prompt editor (prompt-editor), which lists inputs and outputs with types.
+- Searching records by name. Use the table filters (filters), not the assistant.
+
+## Structure
+
+1. Context chips (selection, filters, mentions)
+2. Text area
+3. Typeahead list
+4. + menu (Mention a listing, Run a saved task, Attach a file, toggles, Writing style submenu, Connected tools submenu)
+5. Answer mode button (Quick or Thorough)
+6. Send or Stop button
+
+## Guidelines
+
+- The box stays clean. Everything that changes context or output lives in the + menu, grouped: inserts, toggles, writing style, connected tools.
+- @ and / work without opening the menu. @ suggests listings and adds the chosen one as a removable chip; / suggests saved tasks.
+- Typeahead suggests whole questions from your own records and saved tasks. What you typed stays regular and the completion is bold. Enter still sends what you typed unless you moved into the list.
+- Answer mode is a stable contract: Quick or Thorough, each with one line on what it does and what it costs. The model name is shown but set by an admin.
+- Allow attachments at any point, including follow-ups, and cite files when an answer relies on them.
+- While running, Send becomes Stop in the same place. People can still draft the next message.
+- One symbol per menu: / for saved tasks and actions, @ for records and files. Each also has a button in the composer bar with the same symbol.
+- Only one menu is open at a time; group items under labels such as "Saved tasks" and "Actions".
+- A hint under the composer says what the symbols do: "/ for tasks, @ to add a record".
+- The Quick or Thorough setting stays visible as a chip and carries over to the next message until changed.
+
+## Content
+
+- Placeholder says what to do: "Ask, or type @ for a listing and / for a saved task".
+- Menu items are verbs with the shortcut shown: "Mention a listing @", "Run a saved task /".
+- Mode descriptions state the trade-off in plain words: "Answers from what's on screen, in seconds" and "Also reads candidates and past listings. About 5 credits."
+- Never name controls with branded or vague words such as "Magic" or "Boost".
+
+## Accessibility
+
+- The text area is an editable combobox: aria-autocomplete="list", aria-controls pointing at the suggestions listbox, aria-expanded reflecting whether it is shown, and aria-activedescendant on the highlighted option.
+- Down Arrow moves into suggestions, Enter or Tab accepts the highlighted one, Esc closes the list and keeps focus in the box.
+- The + and mode buttons are menu buttons (aria-haspopup="menu", aria-expanded). Toggles are menuitemcheckbox and writing styles are menuitemradio with aria-checked.
+- The text area has a programmatic label ("Message") even though the label is visually hidden (SC 3.3.2, 4.1.2).
+- @ and / only trigger while the text area has focus, so they are not global character key shortcuts (SC 2.1.4).
+- Each context chip's remove button names what it removes, for example "Remove 2 listings from context".
+- Typing / or @ opens a combobox list; arrows move, Enter inserts, Esc closes and leaves the typed symbol.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter | Send, or accept the highlighted suggestion |
+| Shift+Enter | New line |
+| Down / Up arrow | Move through suggestions |
+| Tab | Accept the highlighted suggestion |
+| Esc | Close suggestions or the open menu |
+| @ | Suggest listings to add as context |
+| / | Suggest saved tasks |
+| Right arrow / Left arrow | Open or close a submenu in the + menu |
+
+## Examples
+
+### composer
+
+```tsx
+import { DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, MessageComposer, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Ask with context", description: "The selection and filters arrive as chips; removing one narrows what the assistant reads. Type @ for a listing or / for a saved task. Enter sends, Shift+Enter adds a line.", order: 1 };
+
+export default function Example() {
+	const [chips, setChips] = useState([{ id: "sel", label: "3 selected listings" }, { id: "f", label: "Team is Engineering" }]);
+	return (
+		<div className="w-full max-w-xl">
+			<MessageComposer
+				noun={{ one: "listing", many: "listings" }}
+				chips={chips}
+				onRemoveChip={(id) => setChips((c) => c.filter((x) => x.id !== id))}
+				mentions={[{ id: "1", label: "FrontendEngineer" }, { id: "2", label: "DataAnalyst" }, { id: "3", label: "QAEngineer" }]}
+				tasks={["Weekly-pipeline-summary", "Draft-rejection-reasons"]}
+				onSend={(t, m) => toast(`Sent (${m}): ${t}`)}
+				plusMenu={<><DropdownMenuLabel>Insert</DropdownMenuLabel><DropdownMenuItem>Mention a listing</DropdownMenuItem><DropdownMenuItem>Run a saved task</DropdownMenuItem><DropdownMenuItem>Attach a file</DropdownMenuItem><DropdownMenuSeparator /><DropdownMenuLabel>Connected tools</DropdownMenuLabel><DropdownMenuItem>Calendar</DropdownMenuItem></>}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- Assistant page
+- Task builder
+- Connected tools
+- Team instructions and files

package/agent/docs-md/migrating.md

@@ -0,0 +1,49 @@
+# Migrating an existing app
+
+Move an existing product onto TwoUX one screen at a time, keeping its brand and the way it already works. Primitives come over quietly behind the app's own names; the change people notice comes from rebuilding composites and page flows on TwoUX patterns.
+
+Kind: foundation · Group: Adopting TwoUX
+
+## How it works
+
+1. Check the platform. TwoUX components need React 19 and Tailwind CSS 4; upgrade those first, on their own branch, and run the app's tests before any TwoUX change. twoux init warns when a version is too old.
+2. Install @twoux/ui and run npx twoux init. It links AGENTS.md and CLAUDE.md, adds the guard hook, the five skills and twoux.theme.json, and never overwrites existing files.
+3. Set the theme before touching a component: the product's primary colour, corner radii and font in twoux.theme.json, then npx twoux theme. The generator refuses colours that fail WCAG contrast.
+4. Decide who owns each shared token name. Apps built on shadcn define many of the same CSS variables as TwoUX (primary, border, muted, radius, font). Whichever stylesheet loads last repaints the other's components, so pick one owner per name and delete the other definition.
+5. Keep raw Tailwind colours building while you migrate. TwoUX switches off Tailwind's default palette; if the app still uses classes such as text-slate-500, add those colour families back in an @theme block after TwoUX's stylesheet, and remove them once the codemod in step 6 has run.
+6. Swap primitives behind the app's own names. Write one thin adapter per component (same name and props, TwoUX inside) so importing files don't change; map variants and sizes to TwoUX's. Expect tests that assert class names to fail, and fix the tests, not the adapters.
+7. Codemod raw colour classes to roles (text-slate-500 to text-ink-3, border-slate-200 to border-line, bg-primary-50 to bg-selected). A person reviews the mappings that change meaning, such as light grey text that would fail contrast.
+8. Move one screen at a time. Map each composite to the TwoUX job and pattern (filters to the filter bar, record detail to the side panel, delete to Undo, errors in place, the assistant's output to the origin label), rebuild it with /twoux-build and /twoux-design, and keep the product's layout where it already works.
+9. Lock it in. Run npx twoux check in CI on every migrated folder, so new drift fails the build while the rest of the app is still moving.
+
+## Principles
+
+- Replace gradually. Each screen moves on its own and ships when it is done; the old and new run side by side until the last screen moves.
+- Keep the brand and the workflow. TwoUX takes the product's colour, corners and font through the theme file, and the flows people already know stay where they are unless a TwoUX pattern fixes a real problem in them.
+- Start where people see the difference. Swapping buttons and inputs changes little in an app that is already tidy; the rough edges live in composites (filter chips, review cards, dialogs, the sidebar) and in how pages combine them.
+- Propose, then apply. Every step is shown as a list of changes the team approves before anything is rewritten.
+
+## Guidelines
+
+- Ask /twoux-audit for the migration plan: it measures the app (versions, shared token names, raw colour classes, primitives that match TwoUX's names, composites that map to TwoUX patterns) and proposes the steps above in order, applying only what the team approves.
+- Before moving a screen, decide which of its differences from TwoUX are product decisions to keep and which are drift to remove. Write the kept ones down; they are candidates for a TwoUX proposal, not exceptions to repeat.
+- Keep each migration change small enough to review: one adapter, one codemod pass or one screen per pull request.
+
+## Do
+
+- Theme TwoUX with the product's brand colour and font, then swap primitives behind adapters so nothing else changes in that pull request.
+- Rebuild the product's own review card as a TwoUX list row with a side panel, because that is the screen people use all day.
+
+## Don't
+
+- Don't rebuild the app in TwoUX's demo look; people should still recognise their product.
+- Don't load both stylesheets and leave shared token names to load order.
+- Don't stop after the primitives and call the migration done; the visible gains come from the composites.
+
+## Related
+
+- Consistency
+- Design tokens
+- Colours
+- Writing
+- Voice and tone