Candor UI changelog

Candor UI 5.2.0

Fri, 13 Nov 2026 00:00:00 GMT

A minor, with CLI 3.2.0 and @candor-ui/react 5.2.0. Nothing a 5.1 app passes stops working; code that reads one of the widened prop types (listed below) may need ?? undefined. The fixes 5.1's streams and reviews found: a Thread that stays at the newest message (Storywrite's A-61), names from the app that read the right way round, and links your router follows in the nav. One Pro item is new (use-focus-within), so the kit has 408 items: 74 free and 377 in Pro.

What to do: npx candor-ui@3 update --to 5.2.0 takes a 5.1 project to 5.2.0, with no codemod. If you use @candor-ui/react, install 5.2.0, which carries the free fixes to Thread, Message and place(). The changes a 5.1 app sees, each with what to do:

Thread (free) stays at the newest message while its content lays out (KIT-295). Storywrite's A-61: "a Thread opened at its newest end stops following when its content grows just after the first draw", about 57 px short of the bottom in about 1 open in 4 in Chromium. In 5.1 any fall in scrollTop of more than 2 px unpinned the thread, and the browser's scroll anchoring makes one when content above the view changes size. In 5.2 the thread turns scroll anchoring off on its scroller while it follows (overflow-anchor: none), and back on once the reader scrolls up, so their place is kept. A fall in scrollTop counts as layout only up to how much the content's height, the view's height and the newest message's place changed since the last scroll or resize; the thread stays pinned and goes back to the bottom. Any larger fall is a scroll and unpins, while an agent streams too, whatever made it: a wheel, a touch, a key, the scrollbar, find in page, a screen reader, or your app through scrollerRef, as in 5.1. "Jump to latest" shows whenever the view is short of the bottom, not only once the reader has scrolled up. Nothing to do.
The Pro items' …Locked props and locked maps, and Inbox's and ApprovalQueue's defaultActiveId, accept null (KIT-282, KIT-291), as locked does since 5.1. For a …Locked prop or a locked value, null or left out is unlocked. For defaultActiveId, only null means "the list keeps the open row, with none at first"; left out, the list keeps no open row and marks none, as in 5.1. Code that passes them is unchanged. Code that reads one of these types into a string | undefined (ComponentProps<typeof Plan>["acceptLocked"]) fails the type check: add ?? undefined. The props: - RunEstimate's startLocked; PlanGate's upgradeLocked; DataControls' deleteAccountLocked, deleteHistoryLocked and exportLocked; SsoSetup's enforceLocked; AgentScreen's takeOverLocked; Plan's acceptLocked. - AccountState's actions[].locked. - The values of the locked maps on ArtifactToolbar, RestoreDialog, ReviewLadder and NotificationPreferences. - Inbox's and ApprovalQueue's defaultActiveId. Their selected behaves as in 5.1.
ApprovalQueue's (Pro) requester tile draws the name's first letter upper-cased, as a whole character, through the new initialOf in initials (KIT-285): an emoji or an Adlam letter is no longer cut in half, and a name that starts lower-case shows its capital. The tile still holds one letter.
ScopeBreadcrumb (Pro): a linked crumb opened with Ctrl, Cmd, Shift or Alt, or the middle button, follows the link and doesn't call onChange, as ScopeSwitcher's option does since 5.1 (KIT-269). A plain click calls onChange, as before.
AppSidebar, NavRail and TabBar (Pro) draw their in-app places through the app's link (LinkProvider, or CandorProvider's link), so your router's link handles them (KIT-268). With none set each draws the <a> it drew in 5.1. A plain click with onNavigate given calls it and the link doesn't navigate, as in 5.1; without onNavigate, your link navigates.

Translators: these keys are new. Until you translate them, each says its English words.

calendar.gridName ("{label}, {month}"), Calendar's grid name, which 5.1 joined with a typed ", " (KIT-271). The keys it read in 5.1 are still read, as its placeholders.
themeSetting.using ("Using {theme}"): with choices, a stored theme that isn't among them leaves the trigger reading "Choose a theme", and its description names the theme in force (KIT-292).

Some DOM your own CSS or tests may match has changed:

Names from the app drawn inside Candor's words have their direction controls marked, listed below; where the text read the same, it still does. DetailsList's row label is in a <bdi> inside its <dt>; ScoreRing's delta.vs, projection.basis and basis and StatCard's delta.vs are each in a <bdi>.
Thread (free): while it follows the newest message, its scroller has overflow-anchor: none as an inline style, which overrides an overflow-anchor your CSS sets there; it has none while the reader is scrolled up.
ThemeSetting (Pro): with a stored theme outside choices, the trigger has aria-describedby pointing at a hidden element with the themeSetting.using words.
ColumnMapper (Pro): the gap after a field's icon is a layout gap, not a typed space, so the text has no leading space (KIT-274).

Corrected in the 5.1.0 notes

The 5.1.0 section below is left as it was released.

locked accepts null on every locked prop, not on every item: in 5.1.0 the …Locked props (acceptLocked, startLocked, upgradeLocked …), AccountState's actions[].locked and the record-typed locked maps still take string | undefined (KIT-282). 5.2 widens them, listed above.
The widened types break code that reads a prop's type, not only the six data types: ComponentProps<typeof ConfirmButton>["locked"] read into a string | undefined needs ?? undefined, and Tree's two-parameter onSelect fails where a wrapper types it as (id: string) => void through ComponentProps<typeof Tree> (KIT-283).
Locked under the app's TooltipProvider opens its reason after the app's delay on hover, where 5.0's own provider gave none; only moving between locked controls inside the delay group skips it (KIT-289).

New items (Pro)

use-focus-within: useFocusWithin and its FocusWithin type (KIT-276). It tracks whether focus is inside an element, so an item moves focus only when focus is in it, or on its control that was just removed, and announces otherwise; a target held for the next render is dropped once the person moves focus out. Focus already inside when it mounts (a control's autoFocus) counts. NeedsYouLine, ModelKey, DriftChange, EnvironmentConnect and IntegrationConnect use it in place of their own checks; NeedsYouLine now keeps focus for any control in the line, not only Retry.

Components

Names from the app, a model or another person (KIT-266, KIT-267, KIT-277, KIT-284): drawn inside Candor's words or in an accessible name, their direction controls are neutralised, so a name can't turn the sentence round it. Message (free): the author's and agent's names in its aria-label. Shell and agents: DockWindow's title (Float, Go to window, Bring back, Move and the floating line), MembersTable's environments in roleOn. Data, reports, charts and evals: Tree, ReconcileTable, DataTable (its stacked name, agentPending and agentInputs), RunEstimate, EvalScorecard, SubscoreCard, ScoreRing, StatCard, ReportSheet, DetailsList, BoardCard, ReorderableList, ColumnMapper, DataImport, ImportReview, and the select hint of BarChart, LineChart, DonutChart and Heatmap. Work, collaboration, knowledge, admin and billing: ApprovalRequest, Plan, ShipReview, RunRecovery, ExtractionReview, InlineSuggestion, CodeListing, CodeEditor, CompareSlider, DocumentViewer, DocumentProgressQueue, AgentScreen, EnvironmentPromotion, HoldToConfirm, Proposal, RestoreDialog, RunHeartbeat, SteerComposer, UndoWindow, WorkflowEditor, AccessRequest, CommentThread, Escalation, HandoffCard, Presence, RaciChips, Diagram, ConfidenceMark, KnowledgeSources, MemoryManager, MemoryMode, MemoryUsed, ApiKeys, DataControls, DeviceSessions, ScheduleList, Webhooks, EnvironmentConnect, IntegrationConnect, SsoSetup, SetupChecklist, StepUpDialog, ProfileSettings, PlanGate, PlanPicker, DowngradeImpact and SubscriptionStatus.

The rest, by item:

Dialog, DropdownMenu, AlertDialog, MaskedInput, FloatLabelInput, Command and TabsList merge your ref with their own through useMergedRefs, as Tabs does since 5.1: an object ref and a callback ref both get the element, and a new callback ref takes over from the old one, where TabsList kept the first ref an app passed (KIT-265).
RunEstimate and ScheduleEditor read the clock after they mount, never while they render, so a Next 16 prerender with cacheComponents no longer fails on an unstable value (KIT-298). The server's HTML has no time left on RunEstimate and no next runs on ScheduleEditor; both appear once the page has mounted, before it paints, as RunEstimate's time left and ScheduleEditor's runs already did after hydration.
SheetContent: a sheet opened from another gives the outer sheet's width back when it closes, where 5.1 removed --cd-sheet-width and the push drawing fell back to min(75vw, 24rem) (KIT-290).
The Premium templates' server stores type no " · " into the labels they build: the approvals inbox names the customer in a refund's title, and the support copilot's store returns the parts its pages join with the locale's separator (KIT-275).

@candor-ui/react 5.2.0

Thread stays at the newest message while its content lays out, and "Jump to latest" shows whenever the view is short of the bottom (KIT-295, above).
Message marks the direction controls in the names in its aria-label (KIT-277).
place() (locale) reads only a placeholder the nodes hold themselves, so a translation holding {constructor} or {toString} draws it as written, where 5.1 drew a function and threw (KIT-286).
mcpInputView and mcpInputResponses (mcp-input) fill a placeholder in their words only from the values they were given, so a translation holding {constructor} or {toString} draws it as written, where 5.1 drew a function's source (KIT-297).
Locked's doc says when its reason opens: under the app's TooltipProvider, on hover after that provider's delay; with none, at once; on a press, at once (KIT-289).

Nothing to do.

CLI 3.2.0

update says when package.json lists a package below an updated item's new range, with the command to install it, and leaves package.json as it is ("lucide-react has ^1.60.0 in package.json; thread 5.2.0 needs ^1.67.0. Run npm install lucide-react@^1.67.0."). A package inside or above the range gets no line, and one that two items name is named once, at the higher range. A workspace: or file: specifier is named as not compared (CLI-45).
Every command migrate and theme print, and the theme usage line, names npx candor-ui@3: migrate's "Not run" line, usage, strings-keys' line on a spread and its pointers to update and add; theme check's fix for a renamed token, its file and motion hints and its pointers to update and init; theme apply's and theme from's lines, so a project with candor-ui@2 installed doesn't run CLI 2 (CLI-43).
The new string keys update and migrate strings-keys list count a key renamed inside a namespace as moved, not new (CLI-46).

Docs and the docs MCP

The docs MCP's theme_check names npx candor-ui@3 migrate tokens for a renamed token (CLI-43).
SubscoreCard's doc names FindingData (KIT-272). DocumentViewer's example shows defaultSelected and RestoreDialog's shows defaultOpen (KIT-273). Thread's scrollerRef doc says scrolling it up stops the thread following.
The upgrade page's 4.0 command names npx candor-ui@2 update --to 4.0.0.

For maintainers

release:check runs an upgrade check from 5.0.0 and from 5.1.0 to this version, on the 5.x fixture (tests/upgrade/5.0 and its also), and runs migrate only when a breaking entry is crossed (CLI-44). The 4.5 and 5.x steps run within 5.x; at another major one step fails and says where to add that major's upgrade steps.
check:motion: the calm/none rule needs [data-motion="calm"] and [data-motion="none"], and their descendants, in a :not(…), each compared whole (MOT-66); a negated container query doesn't allow a loop (MOT-67); an @ease value it can't read fails on either line (MOT-68); a loop needs its running state on every selector of a list.
layers.mjs fails for an engine named in CANDOR_LAYER_BROWSERS or --browsers that doesn't start; one of the default three that won't start here is still skipped with a line, and on CI any fails (KIT-287).
candorItemsOf (scripts/page-items.mjs) reads imports from the syntax tree, so a path in a comment or a string isn't listed (KIT-288).
A kit test checks that every data-slot an item draws is in the token manifest (KIT-280).
tests/browser/thread-follow.mjs opens a thread 20 times in Chromium with A-61's late change and checks each ends at the bottom, and that PageUp with focus on body, a text fragment (find in page's scroll) and scrollIntoView unpin it, with no streaming and while a token arrives every 30 ms; npm run test:browser runs it after the hosted demos.
The OrgSmith pack's package.json and a committed package-lock.json list the packages its Candor items import, and npm run candor puts both files back after add, so a later npm install keeps them (ARCH-39).
The short real-time sleeps left in the tests wait on fake timers (HK-9), and tests that type a bidi control use a \u escape (HK-10).

Candor UI 5.1.0

Fri, 13 Nov 2026 00:00:00 GMT

A minor, with CLI 3.1.0 and @candor-ui/react 5.1.0; nothing breaks a 5.0 project. The fixes 5.0 held back so its breaks could be read on their own: focus that stays put, links your router follows, locked controls that say why, and text that isn't joined in code. Six Pro items are new (link, merge-refs, use-settle, live-rows, email-heading and user-message-actions), so the kit has 407 items: 74 free and 376 in Pro.

What to do: npx candor-ui@3 update --to 5.1.0 takes a 5.0 project to 5.1.0, with no codemod. If you use @candor-ui/react, install 5.1.0, which carries the free fixes to Locked, Tooltip, ToolCall, Composer and Progress. The changes a 5.0 app sees, each with what to do:

Inbox and ApprovalQueue (Pro) keep their own selection when you pass onSelectedChange without selected: a ticked item shows ticked, and the callback is still called. In 5.0 the tick never showed. Pass selected to hold the selection yourself: once you have passed it, the list keeps none of its own, so clearing it to undefined draws none, as in 5.0.
ConfirmButton (Pro) stays armed for 6 seconds by default in English (4 in 5.0): left out, armedFor is long enough to hear the armed announcement at a slow screen-reader rate and then press again, in whole seconds and never under 4, and the announcement says how long. Pass armedFor={4000} to keep 5.0's window; a test that waited 4 seconds for it to disarm waits for the new window or sets armedFor.
Six data types' locked field accepts null (string | null | undefined): PaletteItem, ScopeLevel, SettingsItem, DashboardTileView, PermissionModeOption and PlanAutonomyOption. Code that builds them is unchanged; code that reads one into a string | undefined variable fails the type check: add ?? undefined.
Inside a HeadingScope, some headings sit one level below it, as 5.0's rule says, where 5.0 ignored the scope: the loading, empty and error heading of Inbox, SessionList, NotificationCenter, AgentRoster, ApprovalQueue, TraceViewer, EvalScorecard, MembersTable, AuditLog and ResultTable; A2uiSurface's model headings; EmailPreview's title; and AccessRequest's title, a <p> in 5.0, which is a heading inside a scope or with its new headingLevel. Outside a scope each draws what it drew in 5.0 (<h2>; A2uiSurface's levels; EmailPreview's <h3>; AccessRequest's <p>). A test that found one of them by level inside a scope looks one below the scope, or passes headingLevel; a test that found AccessRequest's title as text inside a scope finds it by role heading.
A stacked Carousel (Pro) changes slide on a finger or pen swipe only: a mouse drag over a slide selects its text. The slide change a person makes is announced ("2 of 3", carousel.slideOf).

Translators: these keys are new. Until you translate them, each says its English words.

graphView.putBack; modelKey.saving; dockWindow.goToWindow and goToWindowTitle.
board.unplaced (one and other) and board.columns; dataTable.sortCleared.
usageMeters.amount, usedOfLimit, limitAfter, unitAfter and withPending. The keys UsageMeters read in 5.0 are still read.
runTree.readoutStatus and readoutJoin. from, after and verdictNote are still read, as their placeholders.
The Premium templates' strings that held " · " (agentOpsConsole.topLine and topLineStopped, approvalsInbox.owner, member, ruleHeading, waitingLine and requestDescription, supportCopilot.threadCustomerLine and draftCardHeader) take {separator}, the locale's separator, in its place; agentOpsConsole.startedBy and approvalsInbox.appliedBy no longer hold it, since the template joins them. An override that kept its own " · " in startedBy or appliedBy shows it twice: take it out.

Some DOM your own CSS or tests may match has changed:

FilterChips (Pro): a chip's label and its value are each in their own <bdi>.
Board (Pro): the scrolling region keeps the board's label and the group of columns inside it is named "Columns of {label}"; the region's description says how many cards are in no column.
EmailPreview (Pro): the title carries data-slot="email-heading", drawn by the new email-heading part.
SheetContent (Pro) carries data-edge (top, right, bottom or left, flipped for RTL).
CardDeck (Pro): the hint is clipped while hidden, not invisible, so a screen reader's browse mode finds it.
Inbox and ApprovalQueue (Pro): the rows' list carries data-slot="live-rows", drawn by the new live-rows part.
A stacked Carousel (Pro): the slides' row is aria-live="off" ("polite" in 5.0), and CarouselStatus has no aria-live, since the carousel says a slide change the person makes once itself, through Candor's announcer. A test that asserted either live region checks the status's text, or the announcement, instead. A sliding carousel's are unchanged.
ToolCall and SearchTrace: a row that finishes with nothing to show while focus is on it keeps its locked button until focus leaves; then it is text, as in 5.0.

Corrected in the 5.0 upgrade notes

scripts/breaking.json's 5.0.0 entries, the [Upgrading to 5.0](https://candor.themethodic.com/upgrading-to-5) page and what update prints going to 5.1.0 or later say these now. update --to 5.0.0 reads the 5.0.0 snapshot, frozen as released, so it prints the old text; the page says so. The 5.0.0 section below is left as it was released.

heading-default (CLI-36): the free PermissionPrompt draws <h2> by default since 5.0 and reads no HeadingScope: pass headingLevel={3} to keep 4.x's <h3>. HeadingScope is named as Pro.
strings-separator (CLI-34): Formatter has two new members, separator and join, so an object you build as a Formatter yourself (a test double for useFormat) fails the type check until it adds them.
locked-not-disabled (CLI-40): the reasons the waiting controls give are 50 new locked… keys, on 31 items, which a translated app says in English until it translates them; the entry lists them. strings-sentences' list of new keys adds clarifyingQuestions.before.
props-active-id-nav (CLI-35): its search finds SettingsLayout's active= too.
The migration lines of the ten entries with a codemod name npx candor-ui@3 migrate, as the codemod lines do, so a project with candor-ui@2 installed doesn't run CLI 2 (CLI-37).

New items (Pro)

link: LinkProvider, useLink, LinkRender and LinkRenderProps. Set how Candor's items draw an address in the app (a Next or TanStack Link) once, or through CandorProvider's new link prop, and SessionList, ScopeBreadcrumb, ScopeSwitcher, PersonMenu (Help), NotificationCenter, NeedsYouLine, ScoreRing, PortfolioCard, DetailsList and BoardCard draw their in-app links with your router. With none set each draws the <a> it drew in 5.0. Downloads and links to other sites stay <a>.
merge-refs: mergeRefs and useMergedRefs, one callback ref from an app's ref and an item's own. Tabs uses it.
use-settle: useSettle, which calls back once a value has stopped changing for a set time. PlanPicker and ScheduleEditor use it, with their 5.0 timings.
live-rows: LiveRows, the rows of a list whose data changes under the person, as Inbox and ApprovalQueue draw them (both now draw through it; the rows' list gains data-slot="live-rows", listed below).
email-heading: EmailHeading, EmailPreview's title at the level the page's HeadingScope gives it; a client part, so EmailPreview, EmailLayout and renderEmail stay free of "use client".
user-message-actions: UserMessageActions, Copy and Edit and send again on the person's own message, placed in Message's meta. Edit hands the app the message's words through onEdit; what the person sends is a new message, and this one stays in the thread, so the app keeps the versions. Copy appears when text is given, and Edit when both text and onEdit are.

Components

New, additive props (Pro):

ThemeSetting: choices, the looks to offer, all four by default; choices={["system", "light", "dark"]} leaves out High contrast. A stored value outside the list shows as nothing chosen.
defaultActiveId on SessionList, SidePanel, AppSidebar, TabBar, NavRail, AgentRoster, Inbox, ApprovalQueue, Plan, RunTree, VersionHistory, GraphView and Tree; defaultSelected on DataTable, DocumentViewer and the four charts; defaultOpen on RestoreDialog and ReportReply (KIT-236). Where the item had no state of its own, it keeps one only when the default is given; an item given neither draws as in 5.0, except Inbox and ApprovalQueue, listed above. An app that holds the selection itself, with undefined as none, sees none when it clears it. A chart's defaultSelected and Tree's defaultActiveId take null to keep the selection with none at first. DataTable keeps its own selection without onSelectedChange, as in 5.0; with onSelectedChange and no selected, pass defaultSelected (an empty Set for none) to have it tick the rows a person selects.
Inbox takes activeId and marks the item open beside it (KIT-234).
AccessRequest takes headingLevel (KIT-252). useHeadingScope(), from heading-scope, gives the nearest HeadingScope's level, or undefined outside one.
DataTable: a column with sortable: false has no sort button, no aria-sort and no place in the stacked sort control (KIT-221).
Tree's onSelect passes the node as its second argument, as the tree drew it, loaded children included; onSelect={(id) => …} still type-checks (KIT-239).
TypedText takes render, which wins over as (KIT-238).
DateRangeField takes name (hidden inputs {name}.from and {name}.to) and error, as DateField does (KIT-190).
navRailTabs takes the rail's pinned places, so more counts a pinned place left off the bar (KIT-167).
locked accepts null on every item, free ones (Slider) included; null or left out is unlocked (KIT-189, KIT-237).

Focus that stays put (KIT-174, KIT-175, KIT-201, KIT-245, and others). An item moves focus only when focus is inside it, or on the control the person just used; a hold, a count or a check that arrives while the person is elsewhere is announced instead. EnvironmentConnect, IntegrationConnect, DriftChange, NeedsYouLine and ModelKey follow it. SessionList keeps focus on a row pinned in a virtualised list; SplitView keeps it when it narrows with the detail open; Toast passes on the key press after a swipe-dismiss; DataTable's stacked detail closes with focus back on the card's button; FilterChips' Clear all keeps focus in the bar (DataTable's search box); WorkflowEditor's keyboard Move ends, announced as put back, when focus goes nowhere; DockWindow's note in place has "Go to window", the keyboard's way to the floating window.

Locked controls: ResultButton and ProgressButton show the reason on a tap or click, as other locked controls do (KIT-177). DataTable's column picker, FilterBar's Add button and CheckpointList's Restore keep their own alignment when nothing locks them (KIT-241). PermissionMode gives its busy reason once (KIT-210). The gallery's Save draft is locked with a reason, not disabled (KIT-242).

Names from the app, a model or another person (KIT-187, KIT-255): drawn inside Candor's words or in an accessible name, their direction controls are neutralised and they are isolated in their own <bdi>: ThreadHeader, ModelPicker, FlipCard, Calendar, AiContentLabel, CopilotPanel, PersonMenu, ScopeSwitcher, AgentRoster, McpConnect, Inbox, ApprovalQueue, FilterChips, DataImport, ColumnMapper, CheckpointList, DocumentProgressQueue, ExtractionReview, CommentThread, AssigneePicker, MembersTable, TestResults, DriftChange and RunTree. PersonMenu's row form draws its initial through initialsOf (KIT-219).

Text not joined in code: IntegrationConnect and EnvironmentConnect type no spaces round the separator (KIT-240); SsoSetup and InviteChooser join lists as the locale does ("Editor and Viewer", KIT-249); UsageMeters' value text and RunTree's screen-reader sentence are keys with placeholders, numbers in the locale's digits (KIT-254, KIT-259); the Premium templates draw the locale's separator, not a typed " · " (KIT-256).

The rest, by item:

ModelKey says "Verified with {provider}, saving…" between a passed check and stored, and its key field is a new password to the browser (autoComplete="new-password") (KIT-160, KIT-191).
ScopeSwitcher: a linked option opened in a new tab or window doesn't call onChange; a plain click calls it and follows the link (KIT-166). AppLayout's hideHeader="on-scroll" doc says any scroll inside <main> hides the banner (KIT-168).
Board says how many cards are in no column, and its region and group have different names (KIT-158, KIT-183).
DataTable: hiding the sorted column clears the sort in both forms and says so (KIT-200).
ColumnMapper: a suggestion with no confidence reads "Suggested" alone, with no percentage and no warning colour; the percentage is in the locale's digits (KIT-244).
RunScrubber's drag preview names the event under the pointer and stays inside the track (KIT-165). ChartFrame: a nested frame's caption no longer moves the plot while busy (KIT-185).
ToolCall draws no line counts for a negative or non-finite count, rather than "+0" (KIT-159). Composer's locked, empty box draws a focus ring of its own (KIT-247).
SliderStops reads a controlled value that is none of its stops (KIT-162); SearchInput drops a pending search when the app changes its value (KIT-163); DateField round-trips years under 1000 and reads Adlam digits (KIT-164); DrawerSwipeArea passes a tap on an icon to its button (KIT-178); FloatLabelInput lowers its label on form.reset() (KIT-182); DialogBody pins the header and footer inside a <form> (KIT-186); ConfirmField calls onMatchChange(false) when it goes while a match stands (KIT-198); Tabs' refs are stable (KIT-215).
GraphView puts a node back where it was when it is let go far from every place, and says so; it scrolls when a pointer drag nears its edge; an arrow key pressed during the settle ends it, so the node moves from where it is drawn (KIT-197, KIT-222, MOT-53).
EnvironmentList clears "Disconnected" when the environment comes back (KIT-161). IntegrationConnect's doc says a hold passed once connected is ignored (KIT-211). ScheduleEditor announces a change back to its first rule (KIT-184).
ProvenanceTrace's lines and LogStream's live dot carry their motion chain on the element that moves, so their own timings and a brand's values reach them (MOT-54, MOT-55). BarChart's plot carries data-plot-dir="ltr", as LineChart's does (MOT-58).
The Premium templates compile under the React Compiler (ARCH-38).

@candor-ui/react 5.1.0

Locked passes every key but Enter and Space (and ArrowUp and ArrowDown on a popup's trigger) to the control's own onKeyDown, so a locked inline TypeToConfirm can still be cancelled with Escape (KIT-176).
Locked under the app's TooltipProvider joins its delay group, so moving between locked controls skips the delay (KIT-224). useTooltipProviderAbove(), from tooltip, says whether there is one; Locked uses it.
ToolCall: no counts for a negative or non-finite line count (KIT-159); a finished row keeps its locked button until focus leaves it (KIT-245). Composer: a locked, empty box draws a focus ring (KIT-247).
locked accepts null (Slider). PermissionPrompt's doc shows headingLevel={3} inside a dialog (KIT-243).
Forced colours reach an indicator given to Progress as children (MOT-63).

Nothing to do.

Motion (Pro `motion-drawings`)

SheetContent's push drawing finds the sheet's edge by data-edge and pushes the page by the sheet's own width, with a Tailwind prefix and in RTL (MOT-50). A 5.0 sheet, which has no data-edge, is still found by its side's class.
A dialog's, sheet's or drawer's nudge keeps its ring under a family-wide attention drawing (MOT-51).
The typing window on <body> and GlideHighlight's travel leave out data-motion="none" and calm (MOT-56, MOT-57).
The row-hover drawing on a <tr> is checked in WebKit (MOT-52).
With expand and the ripple, an icon button's name isn't trapped under the next button (MOT-65).

CLI 3.1.0

migrate constructor, toString and hasOwnProperty say there is no such codemod, as any unknown name does (CLI-39).
update --differing keep keeps its copies by number inside .candor-keep/, never outside it from a monorepo path; update and doctor say when one is left behind (KIT-192).
Where it can't work out what installing an item's new dependencies writes, a plain update no longer runs shadcn's dry run to list it; only --differing does, since only it reads that list (KIT-225).
types-data rewrites export type { ToolCall as Call } to ToolCallData as Call, and the other five types (CLI-38).
strings-keys lists standardCards inside observer(…) or an app's own wrapper, rather than rewriting it into the wrong scope (CLI-42).
update follows a monorepo theme moved out of the shared package and recorded (CLI-41).
The commands update prints, and the upgrade page's, name npx candor-ui@3 (CLI-37).
theme check: motion-value doesn't say a keyframe-named value plays nothing where it plays (MOT-61).
add and update leave a dependency's specifier alone when it already satisfies the item's range, so exact pins stay pinned.
Where the project's utils alias already exports cn, add and update write no lib/utils.ts and add no cn package; the plan and --dry-run name every npm package before anything is written.
migrate headings lists <AppLayout> only with chat, and leaves out a heading whose 5.0 level is already what 4.x drew; types-data writes MessageData, not MessageData as MessageData.
update and migrate strings-keys print the string keys a release adds to your installed items, under "New strings to translate", read from each item's strings table at both versions.
update names npm packages the updated items no longer import and no other recorded item needs ("No longer needed: cmdk"); it removes nothing.
--differing replace names every file it replaced, and its count matches its list.
A codemod says which files it didn't read (as installed, or from an older version), and migrate --verbose lists them.

Docs and the docs MCP

The docs MCP's theme_check description names motion-value (MOT-62).
PermissionPrompt's example shows headingLevel={3} in a dialog (KIT-243); SemanticBadge's doc names FindingData (KIT-257); LiveRows has an example.
Diagram's doc says that mermaid loads only when source is drawn, never for nodes and edges, and that it is still installed with the item, since the registry has no optional dependencies. Nothing changed in how it loads: 5.0 already loaded mermaid lazily, through import(), and a test now holds it.

For maintainers

scripts/motion-baseline.json's entries name a problem's place (file, at, rule, and a count where there are several), not its words, and check:motion says which entry no longer matches (MOT-59). With 5.1's fixes it is empty. check:motion strips a negated running state before it decides (MOT-60), and its @ease check says a value it can't read can't be checked, not that it doesn't overshoot (MOT-64).
release:check counts the tests from its one full run (ARCH-35).
The 4.5.0 upgrade check moves a theme and records it, then checks the move holds (CLI-41).
A kit suite checks the heading rule on every item that draws a heading, from HEADING_LEFT (KIT-258).
The layer checks run Firefox locally too, skipping an engine that can't start with a line saying why; on CI it fails (KIT-213). Check M asserts the app's popupClassName on the open menu (KIT-206); contracts.mjs --list is tested and its header names every group (KIT-208, KIT-209); fresh-app.mjs reads the Radix app's Candor items from the layer page's imports (KIT-212).
The OrgSmith pack installs through candor-ui add, so candor-lock.json is written, and its .gitignore covers what the install writes (ARCH-36, ARCH-37).
Two test files wait on fake timers, not real time (HK-8).

Candor UI 5.0.0

Fri, 13 Nov 2026 00:00:00 GMT

A major release, with CLI 3.0.0 and @candor-ui/react 5.0.0: one heading outline, one name per idea, and strings a translation can reach. Every item that draws a heading takes headingLevel (1 to 6) and, without it, draws one level below the nearest HeadingScope, else <h2>, so a page's outline skips no level; dialogs, sheets, drawers, settings sections and dashboard tiles set the scope. The nav items' selected item is activeId, Tree's and EnvironmentBand's onSelect passes an id, and an accessible name is label. The " · " between parts is one string, locale.separator, and sentences that were joined in code are one string each with {placeholders}. The six data types are MessageData, ToolCallData and so on, as @candor-ui/react already named them, and the English exports kept for compatibility are gone. CLI 3.0 runs the upgrade (npx candor-ui@3 update --to 5.0.0, then npx candor-ui@3 migrate 5.0.0) and no longer takes a 3.x project, which keeps CLI 2. heading-level and heading-scope are new, so the kit has 401 items: 74 free and 370 in Pro.

Upgrading from 4.x

Start from a committed tree, so you can see what each step changed. Then, from the app's folder (the one with components.json):

Look first: npx candor-ui@3 update --to 5.0.0 --dry-run prints what 5.0 changes for the items in candor-lock.json, and writes nothing.
Update: npx candor-ui@3 update --to 5.0.0 updates every item, merging your changes into Candor's as update always has.
Migrate: npx candor-ui@3 migrate 5.0.0 runs each of 5.0's codemods that an entry on your installed items names, in this order: types-data, props, strings-keys, headings. Each lists what it couldn't change under "Left for you". --dry-run shows it first.
Finish and check: make the changes the "Left for you" lines name and those marked "by hand" below, then type-check (npx tsc --noEmit) and build.

migrate parses your source with the project's TypeScript or, on TypeScript 7 (which has no JavaScript API) or with none, with the TypeScript 5 that CLI 3 brings, so there is nothing to install for the run. Strings you override are checked only where they are written as a strings object Candor can see: on LocaleProvider or CandorProvider, in a CandorConfig, or typed StringOverrides. The type check doesn't find an override of a key 5.0 removes, since StringOverrides takes any key: it still compiles and isn't read, so migrate strings-keys is what moves or lists it.

Every change, by its id in scripts/breaking.json (the same entries update --to 5.0.0 prints, and the [Upgrading to 5.0](https://candor.themethodic.com/upgrading-to-5) page lists):

types-data (codemod types-data): Message and ToolCall (lib/candor/chat), ApprovalRequest and ResultTable (lib/candor/work), Finding (lib/candor/data) and RunReceipt (lib/candor/ops) are MessageData, ToolCallData, ApprovalRequestData, ResultTableData, FindingData and RunReceiptData, the names @candor-ui/react already used. No alias is kept. The codemod renames each import and its uses; an import you aliased keeps your local name. Imports from @candor-ui/react don't change.
heading-default (codemod headings, which lists): without headingLevel, an item's top heading is one level below the nearest HeadingScope, else <h2>, and its sub-headings sit below it. Most items that drew <h3> or <h4> now draw <h2> outside a scope; they look the same. DialogContent, SheetContent, DrawerContent, AlertDialogContent, SettingsSection, DashboardTile, ArtifactPanel, AppLayout's chat, a floating DockWindow, ReportSheet and ReportSection put their content in a scope, so a Candor item inside draws one level lower than before. ReportSheet's cover, a fixed <h1> in 4.x, is <h2>: pass headingLevel={1} where a ReportSheet is the whole page. The free PermissionPrompt draws <h2> (was <h3>) and reads no scope. PageHeader stays <h1>, AccountState (a whole page) keeps its <h1>, EmailPreview keeps <h3>, and RestoreDialog's "not undone" heading keeps <h3>, under the dialog's <h2> title. The codemod lists each use without headingLevel with the level it drew in 4.x, and changes nothing: where a page or a test needs that level, pass headingLevel={n}, or wrap a section in <HeadingScope level={n}> (lib/candor/heading-scope).
heading-level-type (no codemod: nothing to change): headingLevel is HeadingLevel (1 to 6) on every item, where DataTable, ReorderableList, Board and BoardCard, NarrativeBlock, PortfolioCard, MonitorCard, DashboardTile and EnvironmentList took 2 | 3 | 4 | 5 | 6. A level you pass still type-checks. Where you type a level of your own, import HeadingLevel from lib/candor/heading-level (layout/heading still exports it).
props-active-id-nav (codemod props): TabBar's and NavRail's current, AppSidebar's activeNav and SettingsLayout's active are activeId, with the same value. Stepper's, PlanPicker's and InlineSuggestion's current mean something else and stay.
props-label-name (codemod props): SettingsLayout's and DocumentViewer's title, their accessible name, which isn't drawn, is label; title is Candor's word for a heading that is drawn.
props-popup-class (codemod props): PersonMenu's and ScopeSwitcher's layerClass prop, the classes for the menu's popup, is popupClassName.
on-select-id (by hand): Tree's and EnvironmentBand's onSelect passes the id of the node or environment, not the object. Write onSelect={(id) => …} and look it up by id where the handler needs it. migrate props lists each onSelect on them, and the type check finds a handler that still takes the object.
strings-compat-exports (codemod strings-keys): statusLabel (lib/candor/status), environmentLabel (lib/candor/team), approvalStateLabel (approval-request), reviewLevels (review-ladder) and standardCards (standard-cards), English only, are removed. The codemod rewrites standardCards used inside a component to const standardCards = useStandardCards() at its top, and lists the others, and standardCards used outside a component, with what to use: useStatusLabel() (label("running")); EnvironmentBand's production and nonProduction strings joined with useFormat().join; useStrings("approvalRequest", approvalRequestStrings); useStrings("reviewLadder", reviewLadderStrings). SessionList's statusLabel prop is a different thing and stays.
chart-strings (codemod strings-keys): barChart.byCategory, lineChart.over, lineChart.chartValues and heatmap.heatmap, unread since 4.2, are removed. An override of one still compiles and draws nothing; the codemod deletes it.
strings-separator (codemod strings-keys): the " · " between parts is one string, strings.locale.separator, read through useFormat().separator and useFormat().join. The keys that held it are removed: message.metaSeparator, payload.titleSeparator, permissionPrompt.scopeSeparator, reasoning.summarySeparator, composer.hintSeparator, searchTrace.domainSeparator, changeSetReview.hintSeparator, taskTray.countSeparator, workflowEditor.hintSeparator and markSeparator, and reviewQueue.hintSeparator. The codemod moves an override of one to locale.separator; where two give different values, it lists them for you to choose. subscoreCard.separator and tableScrubberMap.kindSeparator (", ") are removed too: those lists follow the locale's list format, and the codemod lists an override of either. These strings no longer hold the mark, since Candor joins the parts: integrationConnect.connectedSince ("since {when}") and checkedAt ("checked {when}"), subscriptionStatus.cardExpires ("expires {expires}"), membersTable.invitedBy ("Invited by {name}", with the new expiresIn), awayDigest.group ("{label}"), blastRadius.group ("{noun}s"), escalation.sentLine and acknowledged, environmentPromotion.requestedBy, promoted and declined (each without {when}), taskTray.started ("started"), clarifyingQuestions.progress ("question {step} of {total}", with the new before), agentRoster.failed ("{count} failed") and columnMapper.suggested ("Suggested", with the new percentSure, "{percent}% sure"). Four that held it between parts are removed, their parts joined by Candor: reconcileTable.summary (openCount, resolvedCount, matchedCount), evalScorecard.passedFailed (passedCount, failedCount), reviewQueue.progress (position, "{position} of {total}", and gradedCount) and dataTable.aggregateLine, which has nothing to translate; the codemod lists an override of one with the keys that say it now. An override of a kept string that kept its own " · " shows it twice. One that kept a placeholder Candor no longer fills ({when}, {count}, {status}, {expires} or {percent}) shows it as written: {when} on screen. The codemod lists an override that still has either: take it out.
strings-sentences (codemod strings-keys, which lists): sentences built by joining strings and numbers in code are one string each with {placeholders}, or are parts Candor joins with the separator. The removed keys, and what says them now: scheduleEditor.announceNext (announceRule, announceRuleAlone); dataRetention.policy (policyVersion, policyChanged); subscriptionStatus.price (pricePerSeat, priceTotal); inviteChooser.from (fromName, expiresIn); dualListbox.added and removed (addedNow and removedNow, "Added 3 to Members, which now holds 5.") and total; subscoreCard.outOf100 (scoreOutOf, "{score} / {max}"); freshnessStamp.stampOverdue (overdue); memoryManager.summary (inferredCount); blastRadius.reach (reachChanged, reachRead); changeSetReview.summary (keptCount, droppedCount, toDecide); documentProgressQueue.counts (countDone, countWorking, countQueued, countFailed); logStream.problemsCount and workflowEditor.graphProblems (problems); plan.sentBackSummary (notAccepted); shipReview.summary (createdCount, updatedCount, deletedCount); and environmentConnect.nameDetail, environmentPromotion.nameDetail and approvedAt, driftChange.where and plan.proposedSummary, whose parts Candor joins with nothing to translate; so do composer.scopeChip, composerScopePicker.scopeChip, searchTrace.counts, appSidebar.labelCount, inbox.needsYouCount and sessionList.contextKindShown, which held " · " in 4.x; and inbox.needsYouCountAtLeast (countAtLeast, "{count}+", joined to needsYou). The codemod lists each override of a removed key with the key to translate and its placeholders; your words can't be moved for you, since the sentence is different. New keys that replace none, so the codemod doesn't list them and a translated app says them in English until you translate them: modelKey.keyFor (ModelKey's field label for one provider), runTree.verdictNote, presence.hereStale, progressButton.measuredFailed and failedWithFiles.
card-deck-backspace (no codemod: behaviour): CardDeck no longer dismisses a card on Backspace; Delete does. The hint keeps its space and names "Left and right arrows" (cardDeck.keysMoveDismiss, keysMove). Where your own help names Backspace for CardDeck, name Delete. A dismissal is announced once the app has answered: on the redraw after onDismiss, or when the promise it returns settles. Where onDismiss saves before it takes the card out, return the promise (an async handler does), or the dismissal isn't announced.
locked-not-disabled (no codemod: behaviour): a control that waits on something stays focusable and is aria-disabled with the reason, through Locked, where it was natively disabled; a press does nothing until it can be used. It covers 32 items, three of them free (ToolCall, PermissionPrompt and Composer), each with its reasons as new locked… strings. Composer's box and TypeToConfirm's are readOnly while locked. With onGoTo, every StepWalker stage is a button: a stage not reached yet is locked, and the current one is marked aria-current="step", so the stage the person pressed keeps focus when it becomes the current one. A ToolCall or SearchTrace row that has finished with nothing behind it is text, not a button (one still running is locked until it has something to show). In a test, check toHaveAttribute("aria-disabled", "true") in place of toBeDisabled(), and find such a row by its text. Nothing changes in the app's code.
cli-3 (no codemod): use npx candor-ui@3 for 5.0. It works with Candor 4.0 and later. npx candor-ui@2 stays on npm for a 3.x project (upgrade it to 4.0 with @2 first), for update --fold, and for update --from, which records items installed before the lockfile.

New items (Pro)

heading-level: the HeadingLevel type (1 to 6), in lib/candor/heading-level. The free items type their headingLevel with the same union written out.
heading-scope: HeadingScope, which says the content inside sits under a heading of a level, so Candor items in it draw one below; useHeadingLevel(headingLevel), the level an item draws at; and belowLevel(level, n), for the headings under it. Never deeper than 6.

Components

Headings (KIT-226, KIT-205, KIT-220). These take headingLevel and follow the rule above, most for the first time or with a new default:

Shell: McpConnect and ModelKey draw <h2> (were <h3>); ArtifactPanel, StopAll, AppLayout's chat heading, DockWindow's window title and SettingsSection keep <h2> outside a scope and draw one below inside one. AccountState keeps <h1>, takes headingLevel, and its controls and steps sit one level below its title.
Chat: EntityDisambiguation (a fixed <h3> in 4.x), ThreadHeader and FormErrorSummary take headingLevel. The free MessageContent takes headingLevel, the level a model's # is drawn at (default 3, as before; ## and ### below it, to 6), and reads no scope; ArtifactPanel passes one below its title, so a document's headings sit under it where in 4.x they were always <h3> to <h5>.
Data, reports, ops and evals: DataTable, ReorderableList, Board, BoardCard, DetailsList, ReconcileTable, ColumnMapper, Finding, NarrativeBlock, PortfolioCard, ReportSheet, ReportSection, MonitorCard, RunLog, RunEstimate, FailureClusters, ReviewQueue and DashboardTile; ColumnMapper, RunEstimate, ReviewQueue, ReportSheet and ReportSection gain the prop. Without a title, DataTable's stacked group heads and cards take the table's own level, so no level is skipped. A loading, empty or failed list's heading sits below the list's own.
Work, knowledge and collaboration: ApprovalRequest, ApprovalDecision, ChangeSetReview, ExtractionReview (still <h2> outside a scope), ResultCard, FileList, Proposal, Plan, CheckpointList, RestoreDialog, WorkflowEditor, ProseDiff, VersionHistory, CommentThread, Escalation, BlastRadius, AgentScreen, ClarifyingQuestions, DocumentProgressQueue, DriftChange, EnvironmentPromotion, ShipReview, RunRecovery, KnowledgeSources, MemoryManager, RetrievalInspector and AwayDigest. ApprovalRequest sets a scope round change, ResultCard and Plan round their actions, EnvironmentPromotion round its diff.
Admin, team and billing: ApiKeys, ChannelSetup, DataRegion, DataRetention, DeviceSessions, EnvironmentConnect, EnvironmentList (default 3 to 2, and it accepts 1), IntegrationConnect, ScheduleEditor, ScheduleList, SsoSetup, Webhooks, AccountCreate, ConsentCeremony, InviteChooser, SetupChecklist, SignIn, TermsConsent, BillingDetails, InvoiceHistory and PlanGate. EmailPreview's prop is typed HeadingLevel and keeps its default of 3, since an email is rendered on the server and can't read a scope.

Names (KIT-227): TabBar, NavRail, AppSidebar and SettingsLayout take activeId; SettingsLayout and DocumentViewer take label; PersonMenu and ScopeSwitcher take popupClassName; Tree's and EnvironmentBand's onSelect passes the id. SettingsLayout's contentLabel doc says to set "{item}" where the items' labels already say "settings" (KIT-204).

The separator and sentences (KIT-229, KIT-202, KIT-188): every " · " typed into an item, about forty of them, reads locale.separator. Text from a model, a tool or another person stays in its own <bdi> beside it: Message's model and cost, ColumnMapper's sample values and DriftChange's agent name each are. ThreadHeader's agent names and InstructionsEditor's unknown variables are joined as the locale joins a list ("a and b"). DualListbox says one sentence in the list's own name, and ProgressButton names the files that failed. SubscoreCard's score is "{score} / {max}" in the locale's digits, and a total it can't compute says "Not computed".

CardDeck (KIT-157): Backspace no longer dismisses; the hint keeps its space; a dismissal the app refuses isn't announced later; onDismiss may return a promise, and a card the app takes out before it settles is announced. ScheduleEditor (KIT-156) no longer reads announceNext.

@candor-ui/react 5.0.0

PermissionPrompt's heading defaults to <h2> (was <h3>); pass headingLevel={3} to keep 4.x's.
PageState and ListStateView take headingLevel (default 2); PageHeader takes it (default 1). Additive.
MessageContent takes headingLevel (default 3, as before): the level a model's # heading is drawn at. Additive.
Message, Payload, PermissionPrompt, Reasoning, ToolCall, Composer, ThreadEvent and ShimmerLabel read strings.locale.separator; message.metaSeparator, payload.titleSeparator, permissionPrompt.scopeSeparator, reasoning.summarySeparator, composer.hintSeparator, composer.scopeChip and searchTrace.domainSeparator are gone, as above.
localeStrings is exported, with locale.separator; useFormat() gives separator and join(parts).
statusLabel is no longer exported: use useStatusLabel(). The data types' names don't change here.
ToolCall, PermissionPrompt and Composer: a control that waits on something is aria-disabled with the reason, and stays focusable, where it was natively disabled (locked-not-disabled above). Composer's box is readOnly while it is locked. A finished ToolCall row with no details is text (data-slot="tool-call-row"), not a button, and Composer's scope chip is a span unless you pass onScopeClick. In a test, check toHaveAttribute("aria-disabled", "true") in place of toBeDisabled(), and find such a row by its text. A translated app translates the new reasons: ToolCall's lockedNoDetail; PermissionPrompt's lockedBusy, lockedInvalid and lockedUnanswered; Composer's lockedUnavailable, lockedHeld, lockedEmpty, lockedSending and lockedStreaming.

CLI 3.0.0

New: migrate 5.0.0, with the codemods types-data, props (5.0's renames and onSelect listing), strings-keys (the separator, the removed keys and the English exports) and headings (lists only). A codemod table's row says which release it belongs to, so migrate 4.0.0 makes none of 5.0's changes.
add, update and migrate refuse a project older than 4.0, naming npx candor-ui@2 (and @1 for 2.x).
Removed, with 3.x: migrate motion-aliases and its tables; strings-keys' message.thinking and useAnsweringApprovals rows; update --fold, which now refuses and names npx candor-ui@2 update --fold; and update --from, which names npx candor-ui@2 update <items> --from <version>.
Kept: 4.0's codemods, and theme check's errors for 2.2's motion tokens, which now name npx candor-ui@2 migrate motion-aliases.
Fixed: a table rename keeps an inline type modifier on the import.
migrate, and update where it moves files, run on a TypeScript 7 project: where the project's typescript has no JavaScript API, or there is none, they parse with the TypeScript 5 candor-ui depends on, where CLI 2 stopped and said to install it. The Base UI asChild rewrite in add and update still uses the project's own, else shadcn's preview.

For maintainers

The react build fails on a name two modules both export, where it renamed the data types before.
scripts/check-slots.mjs looks through HeadingScope to an item's root.

Candor UI 4.5.0

Thu, 12 Nov 2026 00:00:00 GMT

A minor, with CLI 2.3.1 and @candor-ui/react 4.5.0; nothing breaks. Steps and conditions dragged into place in WorkflowEditor's graph, by pointer, keyboard or touch; heading levels on seven items, so they fit under a page's own headings; the fixes 4.4's reviews found, in the kit, the motion system and the docs MCP; and the fixes the Fable review of 4.3.0 and 4.4.0 found. The kit has 399 items: 74 free and 368 in Pro.

What to do: npx candor-ui@2 update takes a 4.4 project to 4.5.0, with no codemod. If you use @candor-ui/react, install 4.5.0, which carries the free fixes to Button, Locked and Progress. Three changes a 4.4 app sees, each with what to do:

MonitorCard (Pro) without onToggle says "On" or "Off" in words (span[data-slot=monitor-on], the new strings monitorCard.isOn and isOff) in place of a switch that did nothing when pressed. An unavailable monitor keeps its switch, locked with the reason. Pass onToggle where the person can turn the monitor on or off; a test that found the switch on a card without onToggle should find the words.
DriftChange (Pro) keeps its actions locked once Adopt or Revert has finished, saying "Waiting for the change to update." (the new string driftChange.waitUpdate), until its status leaves "open" or a new change arrives; then it announces the outcome. Set status to "adopted" or "reverted" when onAdopt or onRevert has done its work; an app that never sets it leaves the actions locked.
PersonMenu's avatar (Pro) is named after the initials it shows, then its 4.4 name: "PS, Priya Shah, account menu", through the new string personMenu.withInitials ("{initials}, {label}"), so its name starts with what can be seen. A test that found the avatar by its name should look for the new one; the row form is unchanged.

Translators: these keys are new. Until you translate them, each says its English words, except where noted.

scheduleEditor.announceRule and announceRuleAlone, the announcement once the person stops changing the rule. An app that translated 4.4's announceNext and not these still hears its own words, joined as 4.4 joined them. announceNext is no longer read otherwise; 5.0 removes it.
settingsLayout.contentLabel ("{item} settings"), the open section's region name. An app that translated SettingsLayout's other strings and not this one gets 4.4's name, the item's own label.
personMenu.withInitials; monitorCard.isOn and isOff; driftChange.waitUpdate and revertUndo; modelKey.cancelLocked; permissionMode.changingLocked; linkPreview.userinfo; dateField.readingWithProblem.
sessionList.contextWords and contextKindShown; cardDeck.dismissedNext, keysMoveDismiss, keysMove and keysDismiss; dataTable.sortBy, notSorted, order, ascending, descending and sortFirst.
IntegrationConnect's hold: integrationConnect.waitingTitle, waitingNote, blockedTitle, blockedNote, approveWho, approveWhere, blockedWhat, unblocker, askedAt, holdCheckedAt, checkAgain, checking, waitCheck, checkFailed and back.
The workflow graph's move: graphView.places, and workflowEditor.move, moveNode, moveHint, cancelMove, cancelMoveNode, triggerFixed, placeAt, placeHere, pickedUp and putBack.

Some DOM your own CSS or tests may match has changed:

SettingsLayout's open section (Pro) is a region named "{item} settings" ("Members settings"), no longer the item's label alone, so it no longer shares "Members" with MembersTable's section. A test that found the region by the item's label should use the new name.
PermissionMode (Pro), while a change of mode is on its way, keeps the other modes focusable, aria-disabled in Locked with the reason "Changing the mode" (permissionMode.changingLocked), not disabled, and focus stays where it was. A test that expected them disabled should check aria-disabled="true".
CardDeck (Pro) lists its keys in aria-keyshortcuts and describes them in [data-slot=card-deck-hint], shown while the stack has keyboard focus. Once the app has taken a dismissed card out, it announces "{card} dismissed. {next}, 2 of 5" once, in place of "{card} dismissed". A test expecting the shorter announcement should expect the sentence. Backspace still dismisses.
AppLayout's app frame (Pro) draws no <header> when there is no brand, no top and no menu button; the banner's row collapses. A test that expected an empty banner landmark there should expect none.
Locked (free), without a reason, hands back the control as it is: it no longer gives it an id or a tooltip trigger's attributes and handlers, so an app's own TooltipTrigger round it finds the app's Tooltip. Locked's tooltip now sits beside the control rather than round it. locked imports @base-ui/react/tooltip. Each Locked also has its own tooltip provider, on your TooltipProvider's timing, so moving from one locked control to the next waits the provider's delay again rather than opening at once within its timeout. Nothing to change in the app; a test that expected the next locked control's tooltip at once should wait for it.
LinkPreview (Pro) shows the scheme and host the browser goes to: lower-cased, an international name as its punycode, without a user name or password. An address that carries one has a note under it, [data-slot=link-preview-userinfo] (linkPreview.userinfo). A test that matched the address as written should match the host as the browser reads it.
DataTable's stacked form (Pro) has [data-slot=data-table-sort] above its cards whenever it has rows.
ReorderableList's drag ghost (Pro), [data-slot=reorderable-list-ghost], and GraphView's new one are drawn through LayerPortal, at the end of <body> (or in the layer host inside another library's dialog), so inside a Dialog or Sheet the ghost sits beside the pointer and isn't cut off by the window. A test that looked for the ghost inside the list should look in document.
Tabs (Pro) leave data-tab-value off a tab whose value is an object or a function, where 4.4 wrote "[object Object]"; strings, numbers, booleans, null and bigints keep it.
Added attributes, with nothing to do: LineChart's plot carries data-plot-dir="ltr"; GraphView's node buttons, and the backdrops of Dialog, AlertDialog, Sheet and Drawer, carry their moment's motion chain in their own style, with the caller's style merged over it; DriftChange's Revert confirmation has [data-slot=drift-change-revert-undo].

New items (Pro)

@candor/initials, a lib item: initialsOf(name, locale?), the first letter of each of a name's first two words, upper-cased in locale ("ilker" is "İ" in Turkish, "I" in English). Left out, the letters are upper-cased the same in every language, so the server and the browser agree. PersonMenu and Board import it, so installing Board no longer brings in PersonMenu; person-menu still exports initialsOf for apps that import it from there.

Components

WorkflowEditor (Pro): steps and conditions move in the graph view. Drag one with a mouse or pen to a place between two nodes or into a branch, or press the Move button on its card under the graph: the arrow keys choose a place, Enter drops it there and Escape puts it back, each step said; on a touch screen, tap a place, or Cancel. The layout stays automatic. A move is marked "Moved by you" and Undo takes it back. The trigger always comes first, and its Move button says so. Escape during a move or a drag doesn't close a Dialog or Sheet the editor is in.
GraphView (Pro) takes places, a function giving the places a node can go (GraphViewPlace, in the layout's layer and slot), onPlace (a drop) and moving (a keyboard move the app draws). While a move is on, each place is a button named by its place, out of the tab order. After a drop the nodes that moved slide, a settle moment in the move family. Without places a graph draws as before, so Plan, RunTree and Diagram are unchanged.
headingLevel (Pro) on ReorderableList (its group heads, default 4), Board (its column heads, default 4), BoardCard (one below its board's heads; used alone, 5), DataTable (its title, default 3; the stacked form's group heads and cards below it), ApprovalDecision (1 to 6, default 3), MonitorCard (default 3) and EnvironmentList (default 3), so each fits under a page's own headings. ApprovalRequest and PortfolioCard already had it. The defaults are 4.4's levels, so nothing a 4.4 page draws changes.
IntegrationConnect (Pro) takes hold (IntegrationHold, "waiting" or "blocked"), onCheckAgain and onBack, as EnvironmentConnect does: who has to approve the app, where and when it was asked and checked, or whose policy blocks it and who can unblock it. Without hold nothing changes; once connected, hold is ignored. The names in a hold are another tenant's text, neutralised and drawn in a <bdi>.
SessionList (Pro): contextKind="visible" prints the context's kind before its chip ("Approval · Quote over $50k"); the default, "name", reads it in the chip's name only, as in 4.4.
ScheduleEditor and SessionList (Pro) build their sentences from strings with placeholders (announceRule, announceRuleAlone, contextWords), not by joining words in code, so a translation can order them.
DataTable (Pro): stackBelow is measured before the first paint, so a phone never draws the wide table first; server-rendered HTML shows the wide table until it hydrates. The stacked form has a Sort by control (a column, or Not sorted) and Ascending and Descending above the cards: the same sort as the column heads, asked of the server in server mode and kept when the table widens. Nothing is chosen until the person chooses.
ConfirmField (Pro) takes entry and onEntryChange, to control the second entry; entry="" resets it and its judgement. Both entries are compared after normalize("NFC"), so a name typed with a combining accent matches; case and spacing still count. "Matches" is withdrawn as soon as either entry changes.
PlanPicker (Pro): the totals' value moment waits a second with no More or Fewer press, then plays once for the settled total; a typed seat number doesn't play it. A test of the moment should advance timers by 1000 ms.
NumberInput (Pro) replays its value moment only on a step: clearing attend no longer replays it, and a step pressed while attend rings doesn't replay the ring.
MaskedInput (Pro): a literal in the mask that would fit a slot ("+1 ###") is no longer read as typed input. MaskedInput and NumberInput read digits in every script.
DateField and DateRangeField (Pro) take onProblemChange: what is wrong with what the field last read (unreadable, pastMonthEnd, beforeMin, afterMax) or null. After text it couldn't read, the app's value is still the last date it read, so check this before saving a controlled field. In a locale whose calendar isn't the Gregorian one (Thai's Buddhist, Persian's Solar Hijri), the date in words carries its era. Enter announces the reading.
AppLayout (Pro): useHideOnScroll's header takes the element as well as a ref, so a header that mounts later still hides and comes back. When a hidden banner unmounts, the frame moves back.
DialogContent (Pro) gives the window to an app's ref, an object or a callback, and keeps from="trigger" working; before, an app's ref turned it off without a word. Dialog's nudge ring is drawn inside the window's edge, so a scrolling window doesn't clip it.
ModelKey (Pro): while a replacement key is being checked, Cancel is locked and says why (modelKey.cancelLocked); Replace opens with nothing from an earlier attempt.
DriftChange (Pro) takes revertUndo, whether a reverted change can be had again, in the app's words; left out, Revert's confirmation says it isn't kept (driftChange.revertUndo). See the list above for its locked actions.
Focus kept on the page (Pro): FlipCard moves focus to its button when the app sets flipped while focus is in the face turning away. NeedsYouLine passes Retry's focus to the line when Retry goes, even after a blur to nowhere. FilterChips' Clear all passes over what Tab can't reach (hidden, inert, disabled, aria-hidden, tabIndex -1), and removing the only chip keeps focus on the page. EnvironmentList takes focus back only from the page itself, not from where the person is.
ReorderableList and Board (Pro): removing the held item ends the move.
Tabs and DropdownMenu (Pro): an app's callback ref runs once, and its cleanup runs. Tabs find the chosen tab by its order, so the panel's arrive moment travels the right way for any value.
Command (Pro): a controlled value on a disabled item, or one two items share, no longer loops.
GlideHighlight (Pro) puts back its host's position and isolation when it unmounts.
RunEstimate (Pro) counts down from when endsAt is given, not from when the card mounted, and stops after it.
SliderMarks (Pro): a locked slider ignores the range input's change event.
ScopeSwitcher (Pro): a locked level's reason describes its items.
SectionNav (Pro) links sections that arrive after it mounts.
initialsOf takes an optional locale (see @candor/initials); PersonMenu and BoardCard pass LocaleProvider's language. Without a locale it now upper-cases the same in every language, where 4.4's followed the runtime's (a Turkish runtime gave "İ", now "I"). An app that calls it from person-menu without one and wants the language's letters passes useLocale().locale.
Button (free): Enter, Space or a click with no pointer clears the press point (--cd-press-x, --cd-press-y), so the Pro ripple grows from the middle; the app's own onKeyDown and onClick still run.
Progress (free) is seen in forced colours: a measured bar is filled in Highlight on a Canvas track edged in CanvasText, and an indeterminate bar shows a Highlight band, never a full bar.

Motion (Pro `motion-drawings`)

Backdrops follow their window. Dialog's, AlertDialog's, Sheet's and Drawer's backdrops carry their item's open chain, so they fade in their own open time and a brand's --cd-motion-<item>-open-* reaches them; in 4.4 a sheet's dim faded in 150 ms while its panel took longer.
--cd-draw-button-icon: expand shows an icon button's name beside it without widening it or moving its neighbours, and leaves its position and z-index to the app. Where the browser has anchor positioning the name is anchored to the button, so it adds no sideways scroll at the end of a row, and goes to the button's start when its end has no room for it.
At the Off level an indeterminate Progress with a Pro drawing (travel, refill, stripes) shows the free still band, in forced colours too; in 4.4 travel showed a still bar 40% full and refill a full one. In forced colours the Pro bands are drawn in Highlight.
Drawings travel the right way when an element's direction comes from dir="auto" or the browser (--cd-inline-sign from :dir()).
In a right-to-left page a line chart's line draws in from its first point, the end its points pop in from.
The button press spring falls back to the press family's 0.96 and 150 ms.
4.1's chart rule on svg[role="img"], which matched nothing since 4.2, is gone; charts still draw in.
--cd-tab-sign is the kit's own, set by TabsContent, not a token: theme check says so if a brand file sets it. Remove the line.

CLI 2.3.1

update --differing keep, where add can't plan the project itself (tsx: false, or no tsconfig paths), keeps every file on disk that shadcn's own dry run lists for the install, including ones the lockfile doesn't record, such as lib/utils.ts. 2.2.1 to 2.3.0 kept only the files the lockfile recorded as changed, and shadcn replaced the rest. Both modes name the files the install changed, and a dry run that can't be read stops before anything is written.
theme check (also the docs MCP's theme_check) warns motion-value on a --cd-show-* or --cd-draw-* value the item doesn't draw, naming the values it takes; none and var() aren't judged. The exit code doesn't change.
theme check and the theme builder no longer say that mark: fade and pop: rise need the Pro item: their keyframes are in the free candor.css.

Docs and the docs MCP

suggest_components answers "a table with sortable columns" and "a sortable table" with data-table first. DataTable's description now says what people ask for (search, sort, filter, page and select rows), and Table's says it is the plain elements; "a plain table" still answers table. With sdk: "claude", a related Premium block is judged as the version the ranking found, so its -claude version is no longer dropped for its own words; no answer on today's index changes.

Site and repository

/screens: the home-dashboard brief scores as a weighted mean of its subscores and uses DashboardGrid as /apps/workspace does; /screens/app-shell#topbar lands on "Workspace frame".
App examples: the board's TW-110 moves from Building, not "Waiting for you"; the workspace's "Value a year" and its client estimates say saved or reclaimable, as an estimate with its basis.
The 4.3.0 section of this file labelled Dialog, the menus, Command and nested dialogs "(free)"; they are Pro, and the labels say so.

For maintainers

check:motion checks each @ease line's overshoots against its values; that every show or control rule leaves out data-motion="calm" and "none", scales by a level and loops only while running; and that an element whose class names a family utility carries its moment's chain in its own style (a component's {...props} doesn't count). Known problems in files no stream owned are in scripts/motion-baseline.json, each with its row; an entry that stops matching fails, so the list can only shrink.
npm run test:browser -- --only <group> reaches the runner that has the group (tests/browser/run.mjs).
The layer checks open PersonMenu's and ScopeSwitcher's menus in a Radix dialog.
tests/repo/changelog-tiers.test.ts fails when a bold label in this file says "(free)" of a Pro item.

Candor UI 4.4.0

Thu, 12 Nov 2026 00:00:00 GMT

A minor, with CLI 2.3.0 and @candor-ui/react 4.4.0; nothing breaks. An app frame for workspace apps (one chrome in an L round an inset page, with a navigation rail, a top bar, a scope switcher and a person menu) and the items a workspace home and a board need; fields, buttons and cards for forms and show; the rest of the motion backlog in the Pro motion-drawings item; the fixes 4.3 left; a sturdier suggest_components; and whole app examples on the site at /apps. The kit has 398 items: 74 free and 367 in Pro.

What to do: npx candor-ui@2 update takes a 4.3 project to 4.4.0, with no codemod. To use the new drawings and motion for show, install or update the Pro motion-drawings item and import styles/candor-motion-drawings.css after candor.css; without a brand value naming them, nothing moves differently. If you use @candor-ui/react, install 4.4.0.

One behaviour changes: when more toasts arrive than Toaster shows (four), it now hides the extra ones and counts them ("Show 2 more") instead of dropping them. An app that relied on the dropped toasts vanishing sees them come back when the person shows them. A toast still waiting on toast.promise is never hidden. And if your brand already sets --cd-show-charts: cd-show-draw, the bar, line and donut charts now draw in, as 4.1 meant them to (see Motion).

Some DOM your own CSS or tests may match has changed:

A travelling highlight's box. DropdownMenu's popups and sub-menus hold an aria-hidden span[data-slot=glide-highlight] as their first child; TabsList holds one after its tabs-indicator; AppSidebar's places and NavRail hold one too. The container gets data-glide (and is isolate; a menu popup is also relative). The box draws nothing unless a brand sets --cd-draw-highlight. If your CSS or a test takes a popup's or a tab list's children by position (> :first-child, children[0]), select the items by their own data-slot, or skip [data-slot=glide-highlight].
AppSidebar's person menu is a PersonMenu. Its trigger is [data-slot=person-menu] (with data-form="row") in place of [data-slot=dropdown-menu-trigger]; its words and collapsed tooltip are as before. Select [data-slot=person-menu] instead. AppSidebar's places also carry data-slot="app-sidebar-item".
PopoverTrigger (free) and HoverCardTrigger (Pro) keep a rendered control's own data-slot, as TooltipTrigger has since 4.3: a Button given through render stays [data-slot=button]. Only the trigger's own element is popover-trigger or hover-card-trigger. If you styled such a Button through [data-slot=popover-trigger] or [data-slot=hover-card-trigger], select [data-slot=button] instead. To lock such a trigger, put Locked around it (<Locked reason={…}><PopoverTrigger render={<Button />} /></Locked>), not in render: Locked passes on nothing the trigger gives it, so in render the button would never open anything.
DataTable's selection boxes and ConsentCeremony's acknowledgement are Candor's Checkbox ([data-slot=checkbox], role="checkbox"), not input[type=checkbox], so the person's tick is drawn. The select-all box is aria-checked="mixed" when part of the page is selected. A test that read .checked or fired change on the input should find the box by role, read aria-checked, and click it.
StreamingText (free), when a brand names a stream drawing (--cd-show-stream, from the Pro motion-drawings item), draws text that arrives after its first draw in <span data-arrived> elements, which join the plain text as later chunks arrive. Without one it draws the text as one plain run, as in 4.3. With one, a getByText on a whole reply while it streams can miss it: read the [data-slot=streaming-text] element's textContent, or use a function matcher.
StatCard's figure is p[data-slot=stat-card-figure] holding [data-slot=stat-card-value] (and a unit or an "Estimate" badge when the Kpi has one), so only the number moves. KpiRow with five or more cards is a DashboardGrid, still [data-slot=kpi-row]. CSS aimed at the figure's text should select [data-slot=stat-card-value].
DegradedPanel's Retry (free) is aria-disabled inside Locked while a retry runs, not disabled. A test that expected it to be disabled should check aria-disabled="true".
PlanPicker's Fewer seats (Pro) is aria-disabled at the fewest seats, not disabled, and is described by why (the "At least …" line, or the new string planPicker.atFewest); a press does nothing and focus stays on it. A test that expected it to be disabled should check aria-disabled="true".
ToolCall's row (free): the line counts, badges, tool name, duration and chevron after the title are in a span[data-slot=tool-call-meta], which wraps to a line of its own on a narrow row; the title keeps at least 8rem and truncates. CSS that took those parts as the row's own children should select them inside [data-slot=tool-call-meta].
Some new items' controls have their own data-slot: ConfirmButton's button is confirm-button-trigger (the wrapper is confirm-button), and CorrectionOffer's Use and Keep are correction-offer-accept and correction-offer-dismiss, so brand CSS and drawings aimed at [data-slot=button] don't reach them; select them by these slots. AccordionGallery's panel buttons are accordion-gallery-trigger and CardDeck's focusable stack is card-deck-stack.
Smaller DOM changes: SetupChecklist's done tick is svg[data-slot=setup-checklist-tick], no longer lucide's svg.lucide-check; RadioGroup's indicator is absolute inset-0 flex, not relative flex; SplitView's detail body is div[data-slot=split-view-detail-body]; and DegradedPanel's Retry (free) always sits in span[data-slot=locked][data-unlocked] (display: contents), even when it isn't busy. Tests or CSS that matched .lucide-check, or Retry as the panel's > button, should select the new slots or find the button by role.
Toast's title and detail are each in a <bdi>. A getByText on the text alone still finds them.
Added attributes, with nothing to do: tab triggers carry data-tab-value; Switch's thumb carries data-turned="a" or "b" after a flip the person makes; the × of a Dialog, Sheet or Drawer, and the Close DialogFooter draws with showCloseButton, carry data-dismiss; chart marks carry data-mark; Button sets --cd-press-x and --cd-press-y in its own style where a pointer pressed it.

New items (Pro)

ComposerScopePicker, a picker for where the next message's work lands, for Composer's tools: scopes grouped by kind (environment, client, project, or personal, read "Just me") in a Popover, each with its icon and words, and production still a warning in words. The arrow keys, Home and End move without choosing. Props scope, scopes, onScopeChange; types ComposerScopeChoice (a ComposerScope with kind and id) and ComposerScopeKind; the pill's separator is the string scopeChip. Scope names are neutralised and drawn in a <bdi>. The free Composer's own scope is unchanged from 4.3: leave it out when you use the picker.
The app frame: TopBar, the bar across the top of an app, with start, middle and end slots; the middle gives way below compactAt of its own width. NavRail, the app's places as icons above words, in groups, with a pinned foot; places that don't fit scroll while the foot stays; a count is read in the place's name ("Approvals, 3 waiting") and filled only when urgent; navRailTabs() makes TabBar's destinations from the same places, the ones the app picks, and useNavRailTabs() does so in a component, naming a counted tab through the new string navRail.waiting with the count in the locale's numbers, as the rail reads it. ScopeSwitcher, where the person is working in one control: the name over the environment (production in words, in the warning colour), the mode the agent reports ("Changing to …" while another is asked for) and the connection in words; compact leaves out the environment line but keeps production's icon and the word "Production"; its menu has a radio group per level, a level with no value says "Choose …" with nothing checked, and options take a detail line and the menu actions. PersonMenu, the signed-in person's menu, as an avatar or a row: only the entries the app wires, a header with name and email, the theme as a radio group in ThemeSetting's words, and the app's own choices, with nothing checked while a value is null. NeedsYouLine, what waits on this person in one line: "Nothing needs you right now" only at a known zero, and "Couldn't check what needs you" with Retry when it isn't known; pass it the same count as the rail's badge.
Workspace: ScoreRing, a computed score as a figure, not a progressbar: computedAt and basis are required, the delta names its period, a null score says "Not computed" and why, and projected draws a projected score apart, as a dashed arc with its basis. PortfolioCard, one workspace in a portfolio: one link, its hue as identity only, what needs you in words, up to three figures, and an estimate labelled with its basis. MonitorCard, a rule that watches something: its switch shows what the service reports and says "Turning on" or "Turning off" while it waits, and an unavailable monitor keeps its switch, locked with the reason. EnvironmentList, the environments an app is connected to, with the connection in words, last sync, Set active, Reconnect, and a Disconnect that says in the row what stops and what stays before it acts; the buttons are named from the strings environmentList.setActiveName ("Set active: {name}"), reconnectName and disconnectName. Board and BoardCard, a kanban board on ReorderableList: column limits in words ("6 of 5, over the limit"), folding columns, one column at a time below 640 px of the board's width, agents drawn as agents, costs that say spent or estimated, and an agent's move with Undo, after which focus stays on the card.
Agents, admin and billing: ModelKey, the person's own key for a model provider: what a key unlocks, where data will go shown beside Add key, the key checked with the provider before it is stored, a refused key's reason with what to check, and once verified only its masked part; no provider is chosen for the person, on Replace too. DriftChange, a change made outside the app: what changed and where, how severe in words, who made it ("Not attributed" drawn loudest), when (or that it isn't known), its diff, and Review, Adopt and Revert, each saying what it undoes; Revert confirms in place. PlanGate, a feature the plan doesn't include: which plan has it, what it would show in words with no sample data, its controls drawn locked with the plan they need, and how to get it.
Fields: FloatLabelInput, whose label rises out of the way and is always the field's <label>. InputGroup with InputGroupAddon and InputGroupCount, a field with addons and a count against a limit that is announced only near and past it. MaskedInput, a field shaped by a pattern or grouped digits in the locale's way, that reads a paste through the mask and says its format. ConfirmField, a second entry judged on leaving it or after a pause. StrengthMeter, which needs the basis it was measured by and says "Not checked" for null. CorrectionOffer, a correction applied only when the person accepts it ("Use …", "Keep …"), its reason neutralised as untrusted text. SliderMarks, a slider with marks, detents and a readout; on a labelled mark the value is read with the mark's word ("1.0, Default", the new string sliderMarks.valueAtMark). LinkPreview, a link with another site's preview on hover and focus; the link's scheme and host always show whole, and only the path after them is cut.
Buttons: ResultButton, whose face reports the real result once the work settles. ProgressButton, whose fill is the measured progress, never past it; with unknown progress it says so, and a failed file's bar is empty, in forced colours too. Either, while aria-disabled or inside Locked, stays focusable, says why and does nothing when pressed. ConfirmButton, which asks for a second, separate press (a double-click or a held Enter arms it at most), says what can be undone, disarms on Escape, blur or its timer, and shows "Done" only once onConfirm resolves.
For show: FlipCard, a card with two faces turned by a button that keeps focus. CardDeck, a stack of cards to go through one at a time, by buttons, arrow keys or a drag, each step announced; a press becomes a drag only once it has moved 6 px, so a button or link in a card takes its click. AccordionGallery, panels side by side, one open at a time, a column when narrow; a panel whose content holds focus stays wide whatever the pointer passes over, and when narrow the open panel's content is still reached by Tab. StepCapsules, StepList's steps as a wrapping row of small cards. TypedText, the app's own words typing out once as the page first draws, with --cd-show-typing: type; a key, a press or a focus finishes it. Loader, which turns only while the work runs and is heard from, stops and says "Not heard from since …" past staleAfter, and stops when status says the work is over; its shape is shape or --cd-draw-loader, and its turning is a live moment of its own, so a brand's --cd-motion-loader-turning and its -dur reach every shape.
GlideHighlight (ui/), the box that travels behind the item under the pointer in DropdownMenu, Tabs, AppSidebar and NavRail when a brand sets --cd-draw-highlight; for your own lists too.

Components

AppLayout (Pro) frame="app": one chrome in an L round an inset canvas. brand is the banner's first child, laid into the navigation's column, so it sits over the rail level with the top bar; the navigation (a NavRail, or an AppSidebar as the wider arm) runs full height beside the page; only the canvas scrolls. The canvas is [data-slot=app-layout-canvas], round the page, the panel and the quick chat, and is drawn from three new tokens: --cd-canvas (from --background), --cd-canvas-border (from --border) and --cd-canvas-radius (from --cd-radius-xl), with the corner where the L's arms meet. Theme it flat (the canvas on var(--sidebar), a transparent border, a radius of 0) or sunken (var(--cd-sunken) in a --sidebar: var(--card) chrome). Below sidebarAt the banner holds the brand, the menu button and top. In this frame AppSidebar leaves out its own brand. The page frame, the default, draws the same DOM as 4.3. hideHeader="on-scroll" hides the banner (in the app frame, the whole row, brand included) as the page scrolls down and brings it back on a scroll up or a focus inside; it stays while focus is in it or a menu from it is open, the very end of the page doesn't bring it back, and in the app frame the navigation and the page still reach the frame's bottom while it is hidden. It is off by default in both frames, and useHideOnScroll does the same for an app's own header. --cd-nav-rail-width sets the rail's width.
TabBar (Pro): TabBarDestination.badgeLabel names a destination with a badge in your words ("Approvals, 3 waiting") where TabBar's "3 new" would be false; navRailTabs sets it.
StatCard and KpiRow (Pro): Kpi gains optional unit (drawn after the figure and read with it: "2.4M records"), note (a second line in words) and estimate: { basis } (the card says "Estimate", read as "estimated", and the basis in words). StatCard takes icon; KpiRow takes iconOf and lays five or more cards out through DashboardGrid, in the fewest rows that hold them, as even as the width allows: five where four fit are three and two. A card still sits alone where one column is all that fits, or two for an odd number of cards, and until the row is measured (as the server draws it) it is as many columns as fit. useCountUp is exported from stat-card for your own figures. A 4.3 Kpi draws as before.
ToolCall (free): ToolCall.lines: { added, removed }, when a tool counted the lines it changed, shows "+12 −3", read as "12 lines added, 3 removed". Left out, nothing is drawn; it is never estimated. On a narrow row the title keeps at least 8rem and truncates, and what follows it wraps to a line of its own, so a row fits a 320 px screen (see the DOM list).
SessionList (Pro): Session.context, an entity the thread is about, drawn as an EntityChip under the row's second line and read as the row's description. A pinned thread slides to its group, and focus stays on it.
ThreadHeader (Pro): its scope takes a kind ("environment", "client", "project" or "personal") as ThreadHeaderScope, drawn with the kind's icon and words; a personal scope reads "Just me", and production is still a warning. A scope without kind draws as in 4.3.
DataTable (Pro): stackBelow draws each row as a card of labelled values when the table itself is narrower than that many pixels; selection, details, groups, paging and totals keep working, each card's box is named by its row ("Select Alpha", the new string dataTable.selectRowNamed), and without it the table draws the same DOM. The select-all box shows a dash when part of the page is selected.
DetailsList (Pro): layout="grid" lays rows out as cells, label over value, in as many columns as fit; code values are identifiers (left to right, never translated); DetailRow.copy adds a "Copy {label}" control that says "Copied" only once the clipboard took the value.
SubscoreCard (Pro): layout="tiles": each subscore's tone as a dot with the app's word, its full name, "74 / 100", its weight and its findings in words. SubscoreTile extends Subscore, so 4.3 arrays still fit. Fixed from 4.3: the bars drew their scores, the total and their weight as raw numbers while screen readers heard them formatted, so under a locale such as ar-EG the two disagreed; tiles and bars now format them through LocaleProvider.
ReorderableList (Pro) gains groupHeader, collapsed and onCollapsedChange; a folded group is still a target for the menu and the arrow keys. Without them it draws the same DOM. Fixed from 4.3: a menu move into another group announced the wrong count, and a pointer drag into another group stayed held instead of dropping. And when the app moves an item while a control inside it has focus, and that control isn't drawn again, focus now goes to the item's handle in its new place instead of the page.
Dialog, Sheet and Drawer (Pro): Dialog and Sheet take onDismissAttempt (return false to stay open), as the drawer does, and DialogContent, SheetContent, DrawerContent and ResponsiveDialogContent take unsaved ("your reply"): a dismissal (Escape, the ×, or the Close DialogFooter draws) then asks first, in a bar in the window, and a refused press outside rings the window. ResponsiveDialog passes both on. DialogContent from="trigger" lets the window grow from its trigger with the Pro morph drawing. The drawer's backdrop follows the drag, and DrawerSwipeArea opens it by a finger's swipe in from its edge (the trigger stays the way in for everyone): a 12 px strip, not drawn while the drawer is open, that passes a tap that isn't a swipe to what is under it; keep scrolling content and small controls clear of that edge. Sheet and Drawer now import ui/dialog, so updating them installs it.
Drawer (Pro) measures a fling from the drag's last 100 ms, not one move: a fast first move, or a twitch just before letting go, no longer closes it. A release is a fling when the pointer went at least 10 px toward the edge in that time.
Toast (Pro): toast.promise(promise, { pending, success, failure }) says pending with a spinner, is never dismissed while it waits, then shows its result (a failure stays until dismissed) and returns the promise; if a success or failure function throws, it settles on the new strings toast.succeeded ("Done") or toast.failed ("That didn’t work"). A toast can be swiped toward the inline end to dismiss it (mirrored right to left), Escape dismisses the one with focus, and focus moves to the next toast or back where it was. The cap hides and counts instead of dropping (above). Fixed from 4.3: a timed toast ran on its clock with focus in it and dropped focus to the page. Its timer now waits while the pointer or focus is in it and runs on with the time it had left, and focus in a toast that goes any way (its timer, the cap, the app's dismissToast) moves to the next toast or back where it was. A toast's title and detail, and toast.promise's texts, which can carry an error's message, are now neutralised and drawn in a <bdi>, as are the words its live regions read.
CardDeck neutralises the card names it announces (labelOf, which may be an agent's).
FilterChips (Pro): Clear all no longer drops focus onto the page: it moves to the next control after the chips (else the one before), or to the new focusAfterClear ref. FilterBar sends it to Add filter.
DegradedPanel (free): Retry stays focusable while a retry runs and says "Already retrying"; it keeps focus when the retry starts. New string degradedPanel.retryingLocked.
Forms and fields (Pro): Field takes validating ("Checking…") and valid, the app's word that its check found nothing wrong: "Looks good" shows only while valid is set, and is never inferred from a check that stopped or an error that was cleared, so clear valid when the value changes. Its hint arrives when it appears or changes. NumberInput takes scrub, a grip the person drags to change the value (Shift for steps of ten, mirrored right to left); its docs example has a fine-tune card. Fixed from 4.3: a disabled, read-only or locked NumberInput still changed by its step buttons and arrow keys; now nothing changes it, the step buttons are aria-disabled and described by what describes the field (Locked's reason), and the grip is inert. ToolbarGroup takes reveal, for a selection's actions, announced once. SplitView takes detailKey, so the detail arrives when the selection changes without remounting. RunEstimate takes endsAt and counts down to it in the locale's units, hours included ("Expected to end in 4m 12s", the new string runEstimate.endsIn), then says "Past its expected end". PlanPicker's Fewer seats says why at the fewest seats and keeps focus (see the DOM list). PlanPicker, ScheduleEditor and RunEstimate follow the new "Values that depend on other values" pattern: only what the person changed moves, and the result is announced once after they stop. SetupChecklist draws a step's tick when it is confirmed done; RunScrubber shows the title of the event under the pointer.
UndoWindow (Pro) takes display="ring", a ring painted from the same clock as the bar.
Carousel (Pro) takes transition: slide (the default), fade, vertical, blur, zoom, uncover or fill. The stacked forms keep slides not shown inert and hidden from screen readers; a change plays only when the person makes it. Fixed from 4.3: the arrow keys, Home and End changed slide when pressed anywhere in CarouselContent, so in a field on a slide the caret and the slide moved at once; they now change slide only from the slides' own tab stop.
ChartFrame (Pro), while busy, says "Refreshing" in its header beside a turning icon. New string chartFrame.refreshing.
EnvironmentConnect (Pro) takes hold, for when the other side has to act first: "waiting" (an admin there must approve the app, with who, where and when it was asked and checked, and onCheckAgain) or "blocked" (their policy blocks it, and who can unblock it). The hold stands in place of the ways of connecting; onBack is the app's way back. Without hold, nothing changes.
RadioGroup, ClarifyingQuestions and FormErrorSummary (Pro) gain moments a brand can draw: a dot when the person presses a radio (never for the arrow keys or the app's choice), ticks, dots and a step in ClarifyingQuestions, and a ring on FormErrorSummary when a submit fails on screen. Nothing changes without a brand value.
ClarifyingQuestions (Pro): fixed from 4.3, an agent's question id that is also a property of every object (constructor, __proto__) was read through the prototype, so "Other" showed as picked before the person chose anything; answers are now read as the question's own keys only.
Free hooks, inert alone: Switch's thumb carries data-turned after each flip the person makes, Button notes where a pointer pressed it (--cd-press-x, --cd-press-y), and StreamingText, when a stream drawing is named, marks newly arrived text with data-arrived for 600 ms. The free kit draws none of them; motion-drawings does, and its file's header names them.
The attention family takes Pro drawings through the new --cd-motion-attention-variant, which falls back to cd-ring; nothing changes without a brand value.

Motion (Pro `motion-drawings`)

Everything here is off until a brand file names it, off at the Off level, under calm where it says so and under reduced motion, and ends on the real content.

Fixed: 4.1's chart draw-in never reached the charts from 4.2 on. Its rule selected svg[role="img"], and since 4.2 the bar, line and donut charts draw svg[role="group"]. cd-show-draw now reaches them. A brand that set --cd-show-charts: cd-show-draw sees its charts draw in.
Fixed: clip-path draw-ins appeared at the halfway point. 4.1's chart draw-in and the wipe drawing, like 4.4's sweep, grow and the carousel's uncover and fill, hid the element for the first half of their run and then showed it whole. They now draw along their whole run.
**Show (--cd-show-*):** --cd-show-entrance gains cd-show-bounce. --cd-show-lists (cd-show-fade, -rise, -scale, -blur, -bounce) brings a dashboard grid's tiles, a stack's children, a details list's rows and a data table's body rows in one after another as the page first draws. --cd-show-overlay-content: stagger brings an opening dialog's, sheet's, drawer's or menu's parts in from 0.4 opacity, never from nothing. --cd-show-charts gains cd-show-sweep (donuts and score rings sweep round from 12 o'clock) and cd-show-grow (bars grow from their baseline); --cd-show-points: pop pops a line chart's points in after its line; progress rings and bullet bars fill from empty in the first-draw window when the brand also sets an entrance, lists or numbers. --cd-show-numbers: count counts a stat card's figure up as the page first draws, ending on the measured figure. --cd-show-stream (words, blur, rise, pop) draws a streaming reply's chunks as they arrive (pop keeps each line breaking where it would without it), and --cd-show-typing: type turns on TypedText. --cd-show-hover gains shadow, border and background hovers (shadow-fade, shadow-grow, shadow-bounce, shadow-drop, shadow-rise, shadow-sweep, shadow-settle, border-thicken, border-draw, border-split, border-converge, border-pulse, bg-tint, bg-slide, bg-rise, bg-bloom, bg-diagonal) and tilt, and now reaches DashboardTile, lift and glow included. --cd-show-image (zoom, pan, tilt, focus, scrim) moves an image in a Card or AttachmentPreview inside its own box. --cd-show-backdrop: scale | push moves the page behind an open dialog, sheet or drawer.
**Drawings on controls (--cd-draw-*, in the builder's "Controls · Pro" group):** --cd-draw-switch (spring, bouncy, elastic, wind-up, swell, coin, skew, blur, fade) for the thumb. --cd-draw-button-hover (wipe, two-tone, centre, side, pinch, slide-out, collapse, skew, arrow-sweep, shine, zoom, flood, circle, frame, glow), --cd-draw-button-icon (nudge, fly, roll, morph, expand) and --cd-draw-button-press (spring, ripple), never on a link, a locked, disabled or aria-disabled button, or in forced colours. --cd-draw-focus: ripple on keyboard focus. --cd-draw-input-focus (underline, sweep, border, expand, lift, ring, glow) for Input, Textarea and OneTimeCode taking focus, drawn on an InputGroup as a whole; none changes a field's size (FloatLabelInput's and taller fields' included), lift and glow follow the field's box, not its letters, an invalid field keeps its red border (expand draws its edge in red there), and the focus ring stays. --cd-draw-highlight (glide, ease, bouncy, slow, pop) and --cd-draw-row-hover (wipe, wipe-end, wipe-centre, curtain-down, curtain-up, blur, slide, scale) for menus, sidebars, the rail, tabs and table rows. --cd-draw-loader for Loader's shapes (ring, dots, bars, grid, drive, orbit, pixel, equaliser, wave), and --cd-draw-progress (travel, refill, stripes) for the free Progress's indeterminate bar, which is unchanged; refill never fills the track.
New family drawings, for a -variant token: for opening and arriving, curtain and clip (reveal, overlay), circle, roll, stretch, slide-scale, blur-slide, elastic-slide and flip-x (overlay, arrive), and height, zoom-through and uncover (overlay); morph (overlay), for DialogContent from="trigger"; slide-from (arrive), tab panels coming in from the chosen tab's side; carousel-fade, -vertical, -blur, -zoom, -uncover and -fill; for ticks and dots, fade, zoom, spin-in, jelly, tick-rise, swing and blur (mark), and jelly, rise and ripple (pop), for example --cd-motion-checkbox-tick-variant: cd-spin-in; jolt, the error shake, and beat (attention), for example --cd-motion-input-invalid-variant: cd-jolt; flash and six number drawings, number-flip, -blur, -pop, -drop, -zoom and -skew (value), where an increase rolls up and a decrease rolls down; on a field such as NumberInput only the text moves, and the box stays in place.
Pro eases, named in a -ease token as var(--cd-ease-<word>): stiff, snappy and gentle, and bouncy and wobbly, which overshoot (move, pop, arrive); anticipate, linear-travel and snap (move); stepped and settle (fill, never past the value). No overshooting ease is ever allowed on a measured value.
Moments that play these: tab panels arrive when the person chooses a tab; NumberInput's step buttons play its value moment; DataTable plays changed on a cell whose value changes (not on first draw or paging), keeping the cell's element and any focus in it; ToolCall's line counts play value:lines.
Typing effects draw only text already on the page: text a person types into a native field isn't drawn character by character.

CLI 2.3.0

theme check reads what motion-drawings adds in 4.4 (also the docs MCP's theme_check): a -ease of var(--cd-ease-<word>) is accepted for the families that ease lists, with a note naming the item and saying that without it the family's easing, or Candor's own, is used; on another family it warns and names the families it is for; an ease that overshoots on a family that can't is the motion-spring error, as spring is. The attention family's -variant token and its drawings are known, and so are the --cd-draw-* tokens, from the token manifest. A 4.3 project's file reads as before.
theme check treats candor-motion-drawings.css as Candor's, as it does candor.css. It followed the app's @import of the file and checked it as the app's own CSS, with warnings telling you to remove lines the drawings need: about 290 on a clean 4.4 install (24 with 4.3's file). A clean install now shows none, and the app's own lines beside the import are still checked.
lint knows the new items. ProgressButton, ConfirmButton, InputGroup, InputGroupAddon, LinkPreview, MaskedInput, TopBar, NavRail, Board, BoardCard and Loader are names other libraries and apps also use, so importing one doesn't by itself mark a file as using Candor.

Docs and the docs MCP

suggest_components names a higher tier's item beside "Candor has no …" only when it matches two words of the task, or is named by one: "rich text editor for code" now names code-editor alone, and "wysiwyg editor" names nothing. "A kanban board of tasks" now answers board, and the gap that said Candor has no task board is gone.
ColumnMapper's description now says it maps the columns of an imported spreadsheet or CSV file to the object's fields, so "import a spreadsheet and map its columns to fields" leads with column-mapper, then data-import.
Screens: app-shell's "Top bar and command palette" layout is now "Workspace frame" (AppLayout's app frame with NavRail, TopBar, ScopeSwitcher and PersonMenu). There is a new home-dashboard screen (dashboard, quiet and phone layouts). A screen can name its running example, which get_screen returns; both of these point at /apps/workspace.
A new pattern, "Values that depend on other values". The design reference's Layout table lists the canvas tokens, and the accessibility page's motion paragraph covers drawings on controls, the loader and the indeterminate bar.

Theme builder

"Page ground" and "Page corner" theme AppLayout's app frame: the ground is the page, a card, sunken or the chrome (flat), and the corner none, small or large. Both are written to and read back from a brand file and a Share link, and named in the list of changes.
"Fully round" in a component's Shape section gives every radius 9999px, as round as its height allows: a composer can be a pill with no change to composer.tsx.
The Pro drawings' tokens are listed under "Controls · Pro", and Pro eases show in the easing menus as "(Pro)", with a hint that without the item the family's easing, or Candor's own, is used.

Site and repository

App examples, at /apps on the site: whole apps built from Candor's free and Pro items on sample data, free to view, beside the hosted Premium templates; each names the items it is built from and their tiers. The chat app (/apps/chat; /app now redirects there) has threads grouped by what needs you, a permission prompt, a draft in the side panel, prompt suggestions, quick settings, sharing and a free-items-only thread. The workspace app (/apps/workspace) shows the app frame with NavRail, TopBar, ScopeSwitcher and PersonMenu, and NeedsYouLine, StatCard's new fields, ScoreRing, SubscoreCard's tiles, DetailsList's grid, PortfolioCard, MonitorCard, EnvironmentList and ModelKey. The board app (/apps/board) shows Board with agents as assignees and an agent's proposal before it moves a card someone else owns. The Build menu has App examples; links to /app point at /apps.
/screens shows the workspace frame layout and the new home-dashboard screen, each with a link to its running example.

For maintainers

candor-motion-drawings.css is assembled by npm run theme from partials in src/styles/motion-drawings/; 4.1's and 4.3's rules are 01-base.css, unchanged but for the ends of two keyframes, cd-wipe and cd-show-draw (the clip-path fix), which theme.test.ts's guard takes out before comparing the rest with 4.3.0's. A buyer still imports one file. The motion manifest reads @draw, @name and @ease lines, check:motion checks the partials, and the token manifest lists the --cd-draw-* tokens.
Each stream's browser checks are a pair of files in tests/browser/motion/; run one group with node tests/browser/contracts.mjs --only <group>.

Candor UI 4.3.0

Thu, 12 Nov 2026 00:00:00 GMT

A minor, with CLI 2.2.1 and @candor-ui/react 4.3.0; nothing breaks. An app shell for phones and split views, form and navigation controls, richer tables and a reorderable list; a command palette on Base UI, which takes the last Radix packages out of your project; and the fixes 4.2's reviews and Storywrite asked for. The kit has 366 items: 74 free and 335 in Pro.

What to do: npx candor-ui@2 update takes a 4.2 project to 4.3.0, with no codemod. In CI or a coding agent, where there is no terminal, pass --differing keep (or replace) so update doesn't stop at a file of yours that the install would replace; --dry-run says first whether it would. If you use @candor-ui/react, install 4.3.0.

Some DOM your own CSS or tests may match has changed:

Command, Combobox and CommandPalette no longer use cmdk. Their exports, props and keys are the same. Gone: the cmdk-* attributes ([cmdk-root], [cmdk-input], [cmdk-item], [cmdk-group], [cmdk-group-heading], [cmdk-label], [cmdk-list-sizer]) and the hidden <label> (the box is named by aria-label, from Command's label). The highlighted item has data-highlighted instead of data-selected="true"; a disabled item has data-disabled present (and aria-disabled="true") instead of "true"/"false". Groups are [data-slot=command-group], headings [data-slot=command-group-heading]. Items keep the order you gave them instead of being sorted by score, and the default match is every typed word appearing in the value or keywords, ignoring case and accents, instead of cmdk's fuzzy match; pass filter for your own. Items sit in a [data-slot=command-group-items] element (role="group") inside each group, and there is no --cmdk-list-height. CommandEmpty now announces its words once as typing empties the list, so a getByText on them finds them twice: scope it to [data-slot=command-empty]. Replace data-[selected=true]: with data-highlighted: and [cmdk-item] with [data-slot=command-item].
Locked always draws its wrapper span[data-slot=locked], with display: contents and data-unlocked when there is no reason, so a control isn't drawn anew when a reason comes or goes. If your CSS selects a parent's children (> *, :first-child) around a locked control, also select [data-slot=locked] > *; a test that took the control as its container's first child should find it by its own data-slot. A control inside Locked keeps its own data-slot: before 4.3, a locked one took the tooltip trigger's data-slot="tooltip-trigger", so a locked Switch or Checkbox lost its checked state in forced colours. TooltipTrigger now sets its slot only on a button of its own; if your CSS reached a control through [data-slot="tooltip-trigger"], use the control's own slot.
DataTable's root section has tabIndex="-1", so focus has somewhere to go when a row's detail closes; with renderDetail a virtualised table's rows sit in one tbody each, and with groupBy each group is a tbody.
Every dialog is capped at the viewport's height less 2 rem and scrolls inside rather than running off the screen.
ProfileSettings' theme field is a ThemeSetting, with a data-slot="theme-setting" wrapper round the same label and trigger.

New items (Pro)

Shell: TabBar, a phone's bottom bar of up to five places, each with its word; give it to AppLayout's tabBar and below tabBarAt (640 px) it replaces the menu button, its More opening the sidebar. AppLayout's quick chat, chat={{ content, label }}, draws a chat with the agent beside the page or over it and keeps its thread when it is closed or moved (below chatAt, 900 px, it is drawn over the page); useAppLayout() gives your own buttons the frame's state. SplitView, a list and its detail side by side when there is room and one at a time when there isn't, with a Back button that says where it goes; the list keeps its state, scroll position and focus. DockWindow, content the person can float in a window over the page and bring back without losing its state, inside another library's dialog too; useDockMorph gives your own docking the same slide. useAutoDensity(choice?), the value for data-density: "spacious" for a touch pointer under "auto", or the person's own choice. ThemeSetting, the theme choice on its own (Match my system, Light, Dark, High contrast), controlled, nothing chosen without a value.
Forms: ChoiceCardGroup and ChoiceCard, a radio group drawn as cards, as many across as the group's width allows; nothing is chosen until the person chooses, and a locked card stays in the arrow order and says why. ButtonGroup, ButtonGroupSeparator and ButtonGroupText join buttons into one control, in a row or a column, right to left too. DateField and DateRangeField read a typed date in the order the locale writes dates, and ISO always, say in words which date they read, and never guess one they can't read. SliderStops, a slider over named stops that reads the stop's name and chooses nothing until moved (the free Slider doesn't change). DualListbox moves options between Available and Chosen with keys or buttons that say what, how many and why not; each move is announced.
Navigation: Toolbar and its parts, a row or column of controls that is one tab stop, the arrow keys swapped in right-to-left pages. SearchInput, a named search field whose onSearch hears the text once typing pauses, at once on Enter, and "" when cleared, with shortcut, busy, and the number of results announced once a search settles; SearchTrigger, a button drawn like a search field. SectionNav, "On this page" as real links, the section being read marked as the page scrolls. ScopeBreadcrumb, where the person is level by level, each level a menu, a level with no value saying "Choose …". Timeline and TimelineItem, a history on an icon rail, each tone with its own icon; a time not recorded says so.
Data: ReorderableList, a list a person orders by dragging a handle, from the keyboard (Space or Enter picks up, the arrows move, Escape puts back) or from a menu of moves; items move between groups, every step is announced, and focus stays on the moved item.
Dialogs: ResponsiveDialog, a dialog from 640 px wide (breakpoint) and a bottom drawer below, chosen when it opens and kept while open.

Components

DataTable (Pro): renderDetail gives a row a disclosure button that opens a full-width row under it (expanded, defaultExpanded, onExpandedChange, expandMode). groupBy puts rows under group headings ("Production (12)"), sorted within each group (groupOrder, groupLabel, and groupCounts in server mode; without it a heading says the count is this page's). page now works in memory too, with onPageChange, so a TableScrubberMap can drive an in-memory table: if you passed page to an in-memory table (it was ignored), it now applies, so pass onPageChange as well, or drop page. onOrderChange(rowIds) gives, in memory, every matching row's id in the order the table shows them, at first and whenever a search, a sort or grouping changes it: build TableScrubberMap's marks from it, since marks index the table's current order. A disclosure named by a numeric first column reads the number as the locale writes it.
Tree (Pro) loads children when a node opens: loadChildren(node, { offset, limit }), isLeaf and cap. A node whose children is left out has children to load ([] has none); each loads once, shows "Loading…", offers a retry when a load fails, and past cap a "Show more" row loads the next page. Loads are announced. Without loadChildren, a tree behaves as before, with aria-posinset and aria-setsize added.
SessionList (Pro): Session.archived moves a thread behind one "Archived (n)" row, which a search still finds; onArchive adds Archive and Unarchive to its menu; recency="long" adds Previous 30 days, this year's months and earlier years. Days are now read in LocaleProvider's timeZone when you set one. Archiving, unarchiving or deleting a thread moves focus to the next one.
Dialog (Pro): DialogContent takes size ("default", "wide", "full"); the new DialogBody scrolls between header and footer, focusable and named by the title while it overflows.
Composer (free): the row of mentioned records and attached files is a group named "Attached to this message" (composer.tray), so your attachmentPreview and composer strings reach it; removing a chip moves focus to the next chip, the one before, or the text box, not the page (Storywrite A-43).
Locked (free) keeps focus and a screen reader's place on the control when a reason comes or goes, and the control keeps its own data-slot.
Menus (Pro): a DropdownMenuItem, ContextMenuItem or MenubarItem inside Locked, or aria-disabled, or whose onClick calls preventDefault(), no longer runs onSelect, and the menu stays open.
Command (Pro): defaultValue and a controlled value set the first highlight (before, the first item was always highlighted, and a controlled value got onValueChange with the first item's value on mount). CommandDialog names its search box by its title, or "Search"; CommandInput no longer accepts defaultValue, which it never read; Enter and the arrow keys in another field inside a Command are left to that field.
CommandPalette (Pro): a locked item stays in the arrow-key order and is described by its reason.
DegradedPanel (free) takes live (default true): set it to false where something else already announces the failure. SettlingCard does, so its failure is read once.
HoldToConfirm: while locked, its "Press and hold" instructions aren't shown or read.
ArtifactChip takes kindLabel, the app's word for its kind, read before the title.
CopilotPanel keeps the name of the agent it names for screen readers on that agent's messages but doesn't repeat it on screen (nameShownAbove); renderMessage gets { nameShownAbove } as a second argument.
Heatmap (Pro) draws its cells and the "No data" hatch in SVG, so they show in forced colours.
FilterChips (Pro) announces a filter that goes ("Removed filter Status: Open"), or one replaced by another with the same label ("Changed filter Status to Closed").
Message (free): with markdownBlocks(text, { breaks: true }) (Storywrite A-46), a lone newline in an agent's paragraph is kept and shown as a line break; the default stays CommonMark. Such a paragraph block carries a new optional breaks: true; a paragraph your app builds with a "\n" in its text still shows it as a space.
Motion drawings (Pro motion-drawings): for picking up, swell, lift, tilt and ghost; for adding and removing, fall, slide-start (mirrored right to left), bounce and zoom.

CLI 2.2.1

update --differing keep|replace (Storywrite A-48): where installing a Candor item the new versions need would replace a file of yours that differs from what the install writes, update now works out every such file the way add does, before writing anything: a shared item you've changed, such as the tokens, and a lib/utils.ts of your own that candor-lock.json doesn't record. Without a terminal and without the flag, it stops there and names each file. --differing keep keeps every one of them, and their records in candor-lock.json; --differing replace takes what the install writes; both name the files. If the registry can't be read to tell, update stops before writing too (without a terminal, or with keep). --differing with --no-deps is refused. --dry-run says where the real run would stop and which files, and exits 1 if it would. While shadcn runs, keep holds a copy of your files in .candor-keep/ (ignored by git), so stopping the CLI with Ctrl-C or a signal still puts them back; if it can't, it says where the copies are. --record and --differing are refused on commands that don't use them.
add and update record one hash for one install (Storywrite A-49): without RSC, the same item at the same version recorded two hashes, and its file looked changed. Hashes written by earlier CLIs still match, and verify no longer calls a CLI 2.2.0 entry stale where shadcn had kept the file's "use client" line. verify names a stale entry, and where the file is Candor's as released, npx candor-ui verify --record records its hash again: it changes only candor-lock.json, writes no file and doesn't run shadcn. Use CLI 2.2.1 throughout a team: in a project without RSC, CLI 2.2.0 reading a lockfile 2.2.1 wrote takes files with a "use client" line for ones you've changed.
lint knows the new items; names other libraries and apps also use (Toolbar, SearchInput, Timeline, SplitView, TabBar, DialogBody) don't by themselves mark a file as using Candor.

Site and repository

Try Candor with no key and no install at https://candor.themethodic.com/try: the Vite starter, built with the site. The public README links it and shows the downloads.
For maintainers: npm run lint fails on any warning; the kit has none.

Candor UI 4.2.0

Thu, 12 Nov 2026 00:00:00 GMT

A minor, with CLI 2.2.0 and @candor-ui/react 4.2.0; nothing breaks. Layout components for building pages on Candor's tokens; dashboards with keyboard-readable charts, drill-down, tiles and new small charts; reports whose claims show their evidence; more for the thread (quick replies, cards that wait for a service, artifact chips, separators that fit the thread's span); nested dialogs that close as people expect; and CLI 2.2.0's update --fold. The kit has 349 items: 74 free and 318 in Pro.

What to do: npx candor-ui@2 update takes a 4.1 project to 4.2.0, with no codemod. If CLI 2.0.0 installed your project wholly under <app>/candor/candor/, run npx candor-ui@2 update --fold --dry-run, then --fold, then npx candor-ui@2 verify; this replaces the manual recipe in the 4.0.2 section. If you use @candor-ui/react, install 4.2.0.

Some DOM your own tests may match has changed, all of it for keyboard and screen-reader access:

BarChart's svg was a role="img" named "{series} by category"; it is now a role="group" named by the chart's title, and its one tab stop per category ("Mon: Passed 3, Failed 1") is one tab stop for the plot, with a role="img" per bar ("Mon: Passed 3").
LineChart's svg is a role="group" named by the title, with a role="img" per point; the focusable "Chart values" element is gone (the table view has them).
DonutChart's svg is named by the title, not the list of parts; each slice is its own role="img".
Heatmap's grid is named by the title, not "Heatmap"; it has rows with a hidden "Row" column header, and its cells take one tab stop with arrow keys instead of each being a tab stop.
DonutChart: a part of 0 draws no slice and is not a keyboard stop; the legend and the table still list it.
The strings barChart.byCategory, lineChart.over, lineChart.chartValues and heatmap.heatmap are no longer read, so an override of them does nothing; they will go at the next major.
A Dialog, Sheet or Drawer opened from another draws a transparent backdrop of its own.

A Testing Library getByRole("img", { name }) on a whole chart needs getByRole("group", { name: <title> }). report-sheet's onExport now receives a second argument, { provenance }; a handler that took an optional second argument of its own will now get that object.

New items (Pro)

Layout, in a new layout group: Text, Heading, Stack, VisuallyHidden, PageContainer, DashboardGrid with DashboardGridItem, and FormLayout with FormSection. They lay out pages on Candor's tokens without hand-written classes, follow data-density and right-to-left pages, and take render (there is no as): if you are moving from your own layout components, <Text as="span"> becomes <Text render={<span />}>. A Heading needs its level; its size is set apart from the level.
narrative-block: report prose as claims, each followed by the sources or report sections it rests on. A claim that states a figure with no evidence is marked "No evidence given for this figure" rather than shown as fact. claimStatesNumber() is exported, and numeric overrides it ("Q3", a year).
semantic-badge: a badge with an icon and a word for each neutral vocabulary (severity, risk, effort, confidence, provenance, autonomy, classification), whose values match the kit's own types. null reads "Unknown". Add your own vocabularies with VocabulariesProvider; change a built-in word through LocaleProvider under semanticBadge.
dashboard-tile: a titled tile with a freshness stamp, ChartFrame's loading, empty, partial and error states, a drill-down button in your words, a view switch whose disallowed views stay locked with the reason, and a toolbar slot. A chart inside shows its title once. ChartFrame exports ChartStateView and ChartNestedProvider.
artifact-toolbar: maximise, download (one format a button, several a menu) and "Ask about this" for an artifact or tile, each button naming it. Controls without a handler aren't drawn; locked ones say why. Your own actions go in as ArtifactToolbarButton.
share-bar: parts of one whole as one bar with a legend of values and shares. Unmeasured parts say so, and the caption says when the shares are of the measured parts only and how many were left out. Against a whole, a shortfall shows as "Not accounted for", and parts that add up to more than the whole say so instead of drawing shares. A value that isn't a finite number counts as not measured. Shares round down, so only the whole reads 100%, and a part under 0.1% reads "<0.1%". Drawn in SVG, so it shows in forced colours.
mini-bar: a bar for a table cell, beside Sparkline; "no data" for a missing value. Its fill shows in forced colours.
progress-ring: circular completion for a measured value, as a progressbar. The share shown is rounded down, so it never reads 100% before the total is reached, and past the total it says so ("120 of 100"). A value that isn't a finite number, or a total of zero or less, reads "Unknown". It starts at 12 o'clock and runs the reading direction's way. An unknown value draws the track only and says "Unknown"; for work of unknown length, use StatusDot.
table-scrubber-map: beside a server-mode DataTable, where the flagged rows are across pages, with a button per page that holds flags. With an unknown total it lists the pages without placing them. A DataTable paging in the browser keeps its page to itself, so it can't be driven from here.
chart-focus, pattern-fill, chart-views: the keyboard model, the patterns and the allowed views the charts below use, for your own plots too (useChartFocus; ChartPatterns, patternFor, patternStyle, markerPath; allowedViews and useAllowedViews, which say which views a dataset allows, and why not).
useAnnouncer: announces a message to screen-reader users from app code, politely or assertively, and says the same words again when they are repeated. One shared pair of hidden live regions is in the page while any component uses it.
QuickReplies: the replies an agent offers to its own question, as chips under its message that send the reply at once and say so. Nothing is chosen until one is pressed; while sending and once sent the chips are locked with a reason, and the sent one keeps a tick. Use PromptSuggestions for prompts that only fill the composer.
SettlingCard and useCardSettlement: a registry card whose write may not have settled. It says it is waiting for the named service, shows the service's reason with Retry and "Not applied" when it fails, and shows the card alone only once settled. A card definition reads the state to lock its own actions while pending. RegistryCard is unchanged.
ArtifactChip: a chip in the thread for a diff, approval, form, table or plan that lives in the app's panel. It opens that panel's tab, marks the tab that is showing, and gives its state in words and an icon.
useThreadSeparators: chooses where ThreadDividers go from how long the thread runs: by day, week, month or year, in the locale's time zone and with its first day of the week. Pass its result to the dividers you already draw.

Components

Charts you can read by keyboard (Pro). BarChart, LineChart, DonutChart and Heatmap put every bar, point, slice and cell on one tab stop per plot. Arrow keys move, PageUp and PageDown change series, and each mark is read as its series, category and value ("Mon: Passed 3"); a missing one says "no data". Focus shows the same tooltip as hover. A drawn heatmap now has proper rows, so axe passes on it.
Patterns in high contrast (Pro). Under the high-contrast theme and in forced colours, bars, donut slices and their legends carry hatch patterns, and line points a marker shape per series. patterns="always" shows them in any theme and "never" turns them off. The default themes look as before.
Drill down from a chart (Pro). The four charts take onSelect, selectLabel and selected. A mark becomes a button that says what pressing it filters to ("Filter to Mon", or your words), pressed by a click, Enter or Space. A mark with no data, or whose value isn't a finite number, can't be selected and says so.
DateRangePicker available (Pro). Pass the span your data covers. A window picked wider is narrowed to it, the value keeps the window asked for as requested, and the picker says "Data exists from … to …; showing that." A value or defaultValue you pass that is wider, or a window left wider when available narrows, is shown narrowed with the same note; your value is unchanged and onValueChange isn't called. With no available, nothing changes.
report-sheet provenance (Pro). A new provenance prop (where the data is from, provisional or final, missing sections) is said in the footer, which prints with the report. Candor doesn't write the downloaded files, so onExport now gets the same lines as a second argument, { provenance }, and exportProvenanceLines() returns them for files you write yourself. If you leave out the posture, the footer says "Not marked provisional or final." One-argument onExport handlers keep working.
Field trust (Pro). A new trust prop shows when a value is unverified, was filled by an agent (named by by), or has a source that is unavailable (with reason): an icon and words under the label, read out with the control, and a dashed edge on the control.
Message and MessageHeader: nameShownAbove (free). When the panel or chat above already names the agent or teammate, the header leaves the name out of sight but keeps it for screen readers. A header with nothing else to show isn't drawn. Nothing changes unless you set it.
Locked (free) adds its reason to the control's own aria-describedby instead of replacing it, so a hint or an error is still read on a locked control. A control you wrap in Locked that has its own description is now described by both. A locked DateRangePicker now says why it is locked (since 4.1 it didn't), and a locked HoldToConfirm reads its consequence as well as the reason.
DonutChart (Pro) shares follow the locale's number format ("33,3 %" in German).
Nested dialogs (Pro). A click outside a Dialog, Sheet or Drawer opened from another closes only the inner one, as Radix and the APG dialog pattern do; before, Base UI's nested dialogs ignored it. An AlertDialog still ignores outside clicks. The page is still dimmed once. A nested dialog with modal={false} or "trap-focus" draws no backdrop of its own, so the outer one stays usable.
Diagram (Pro) marks bidi controls in the labels Mermaid draws, so a Diagram given Mermaid source shows a control in a label as a mark, like every other model text. This closes 4.1's one exception.

CLI 2.2.0

update --fold folds a project CLI 2.0.0 installed wholly under <app>/candor/candor/ up into <app>/candor/: it moves the files, rewrites candor-lock.json, points imports of …/candor/candor/… at …/candor/…, keeps your edits for update to merge, stops before any change and names the place if a destination is taken, and with --dry-run lists the moves. doctor and update say when a lockfile is nested that way. Only JS and TS sources are rewritten: references to candor/candor in Markdown, MDX, stylesheets, Vue, Astro, Svelte and JSON files are listed under "Left for you" with their file and line, for you to point at candor/.
lint knows the new items. Text, Heading, Stack, VisuallyHidden and PageContainer are names other libraries and apps also use, so importing one doesn't by itself mark a file as using Candor.

Docs and the docs MCP

Every exported component has a doc comment, sub-parts such as CardHeader and the blocks' and templates' pages included (175 added), and the docs build fails on one without. If you add components to a fork of the kit, give each a one-sentence doc comment.
suggest_components leads with agent-screen for "a computer-use screen with its actions": a task word that only ends a compound item name counts for less than a word in an item's job, when the task has one. It no longer answers a map with table-scrubber-map, and a word that is both an item's name and its group's counts once more.

For maintainers

The test count the site quotes is the same on every machine: npm run stats counts the suite with CANDOR_STATS=1, which skips the tests that depend on the machine (tests/machine.ts). release:check no longer needs --keep-tests. A new machine-dependent test goes through onThisMachine(), or tests/scripts/stats.test.ts fails.
The suite doesn't time out when other work loads the machine: release:check caps Vitest's workers by the load average, and the suites that timed out under load get 30 seconds (tests/load.ts).
CI and release:check generate on Node 24, the version Vercel builds on; release:check stops on another major and says how to switch (--any-node runs it anyway). The weekly shadcn canary stays on Node 26.
WebKit runs the layer checks in CI again. Three checks its Linux build fails with no Candor code on the page (an app's Radix dialog in its Radix dialog) are reported as WebKit-on-Linux baseline, not counted.
No shadowed names in the tests; RELEASING's Start step names the home pill's link and the motion manifest.
The context menu's keyboard test no longer fails depending on timing. It pressed ArrowDown before the menu had taken focus, which Base UI gives it on the next animation frame, up to 17 ms later in jsdom. It now waits for the menu to have focus first. 4.1.0's test has the same race; the component was never at fault.

OrgSmith pack (in-house, not published)

New logo and domain-icons items, and the preset's delivery, business and knowledge-base status vocabularies for VocabulariesProvider.

Candor UI 4.1.0

Thu, 12 Nov 2026 00:00:00 GMT

A minor, with CLI 2.1.0 and @candor-ui/react 4.1.0; nothing breaks. Motion is now easy to find and choose in the theme builder, with named styles and motion for show in a new Pro item; text from a model or a tool can no longer reorder what a person reads; CLI 2.1.0 checks brand scopes and handles monorepos and @/candor projects better; and a round of fixes across the kit, docs and the docs MCP. The kit has 326 items: 74 free and 295 in Pro.

What to do: npx candor-ui@2 update takes a 4.0 project to 4.1.0, with no codemod. If your own components draw text from a model or a tool, call neutralizeBidi from the new free bidi item. To use the motion for show and the new drawings, install the Pro motion-drawings item and import styles/candor-motion-drawings.css after candor.css.

If you use @candor-ui/react, install 4.1.0; neutralizeBidi is exported from the package root. theme check now counts each brand scope towards its exit code, so a CI step that runs it on a file with several brands can fail with no change on your side: run npx candor-ui@2 theme check locally first. Some DOM your own tests may match has changed: a <bdi> now splits PermissionPrompt's blocked-path and server lines and ApprovalRequest's "You chose:" and "Can't be undone:", so a Testing Library getByText on the whole sentence needs a function matcher; TabsList has an aria-hidden first child, span[data-slot="tabs-indicator"]; the inline measured node is a <bdi>; and copied text (blocksToText, Payload) shows control characters as marks such as [U+202E].

The motion rule

The principle "Motion follows the outcome" is now "Motion never says something false" (the link /principles#motion-follows-the-outcome still works). Motion that reports something still waits for it: a tick is drawn after the result settles, a spinner turns only while work runs, and a progress bar fills only as far as the work has gone. Motion for show, such as content arriving as a page loads, a card lifting under the pointer or a chart drawing in, is welcome when it says nothing false: it doesn't look like a status, a measurement or a result that isn't so, never hides content or holds back input, ends on the measured values, and is off under reduced motion. The Principles page, design.md and both coding-agent skills say so.

Theme builder

Motion where you'd look for it. The Build menu and Start name motion and sound. The canvas has an Animations view that plays every kind of animation in turn, with Pause, and compares each kind's drawings and easings side by side on a plain stand-in shape, the current one marked "now" and nothing chosen. The Motion panel lists every component that has animations, with search. Plain words sit beside the design's terms ("Kinds of animation (families)", "Animations (moments)", "Animation · drawn as").
Named motion styles: Quiet, Crisp and Lively, on Start and at the top of Motion, each with Replay. Nothing is chosen until you press Use, and Undo takes it back. Quiet and Crisp write only tokens a brand file already takes. Lively also turns on motion for show (Pro): it writes --cd-show-*, tokens new in 4.1 that only the Pro motion-drawings item reads, so without that item they do nothing.
The Start presets carry a motion style: Candor keeps Candor's own, Slate and Console take Crisp, Paper takes Quiet and Signal takes Lively; one Undo takes back the preset and its motion. Another shape of the same preset keeps the motion you set. Motion is the whole file's, so a preset picked while a brand scope is open sets it for the base and every scope, and the builder says so. This is in the builder only: the installed gallery themes are unchanged, so your project's motion doesn't change on update.
For show · Pro in the Motion panel sets entrances, charts drawing in and hover, and the drawing selects offer the Pro drawings, marked Pro.
The download's note for coding agents says theme check (CLI 2.1.0) measures each brand scope.

New items

bidi (free): neutralizeBidi(text), hasBidiControls(text) and escapeBidiJson(json). Bidi control characters (U+202A to U+202E, U+2066 to U+2069) in text from a model or a tool now show as visible marks such as [U+202E], on screen, to screen readers and when copied, so a reply, file name, diff or log line can't be made to read in a different order. Names and labels from a model sit in an isolate (<bdi>), so genuine mixed Arabic or Hebrew and Latin text still lays out correctly; LRM, RLM and U+061C are left alone. Every item that draws model or tool text uses it, free and Pro: messages, attachments, prompt suggestions, cards, payloads, tool calls, logs, entities, sources, permission prompts, reasoning, searches, artifacts, change sets, diffs, code, plans, test results, approvals, questions, tables, run trees, A2UI surfaces and the standard cards; and memories, retrieved passages and the claims they back, knowledge sources, rewrites (ProseDiff and SelectionActions), diagrams given as data, tool settings, an agent's last failure, findings, import problems, DataTable's agent-filled cells, traces, run receipts, eval reviews and failure clusters, threads, the inbox and the away digest. PermissionPrompt's and ApprovalRequest's edit fields show a control character as its JSON escape (\u202e), and Allow or Approve still sends the input exactly; so do ImportReview's Apply, ProseDiff's resolved text and SelectionActions' Keep. One exception: a Diagram given Mermaid source draws its labels through Mermaid, which doesn't mark them; its source view does. If your own components draw text from a model or a tool, call neutralizeBidi; for a JSON field, escapeBidiJson.
motion-drawings (Pro): blur, flip, swing, skew and wipe drawings for dialogs, menus, arrivals and pops, each with its calm form; and motion for show, off until a brand file turns it on: cards, stat cards and chart frames arriving as the page draws (at most six, staggered), bar, line and donut charts drawing in with their values in the page for screen readers from the start, and cards that aren't controls lifting or glowing under the pointer. All of it is off at the Off level, under data-motion="calm" (on the card or around it) and under reduced motion. The entrance plays only as the page first draws, and the rules sit below your utilities, so your own animation on a Card wins.

Components

PermissionPrompt takes jsonEditor, the field the tool's input is edited in, typed by the new PermissionJsonEditorProps. With Pro, pass CodeEditor for line numbers, JSON colours, Tab to indent and the error read out with the field; left out, the prompt keeps its plain text field.
In a dialog that clips its content (a max height with its own scroll), your app's own Radix menu, select or dialog opened from a Candor layer is drawn above it, takes the pointer and closes with Escape; in 4.0 it was drawn underneath. Nothing changes outside such dialogs.
Separators come from the strings, so a translation can change them: ReviewQueue (hintSeparator, hintEither, hintItem), Composer (hintSeparator, hintItem, scopeChip), Message (metaSeparator), TaskTray (countSeparator), PermissionPrompt (scopeSeparator), Payload (titleSeparator) and Reasoning (summarySeparator). English text is unchanged.
Tabs (Pro): the selected tab's background or underline moves to the tab you choose; it is placed still on first draw. Under React's Strict Mode it never moved before; fixed, and the same in ToggleGroup.
DataTable (Pro): the "n selected" bar fades in. FilterChips (Pro): an added filter pops in and a removed one pops out. InviteMembers (Pro): each address pops in as a chip.
ProfileSettings (Pro): "Saved" appears only after onSave resolves; if it rejects, the form says "Not saved" with the reason and keeps your changes (before, it stayed on "Saving…"). New strings notSaved and notSavedNoReason.
BarChart and LineChart (Pro): when values change on screen, bars and lines move from the old measured values to the new; nothing moves on first draw and a resize redraws in place.
Inbox and ApprovalQueue (Pro): rows slide to their new place when the data re-sorts them.
AppLayout (Pro): a click on the panel divider moves the panel to its next width; dragging and the keys resize it at once.
Dialogs keep Tab inside (Storywrite): in a Candor Dialog, AlertDialog, Sheet or Drawer, Tab and Shift+Tab wrap inside the popup. Before, focus could rest for a frame on Base UI's focus guard outside it (Base UI 1.9.0 moves it back on the next frame), which happened on 4.0 too.
Inside a foreign dialog, layers your app portals into its own container are drawn above Candor's layer as well, and a Candor layer that leaves the top layer and comes back no longer covers your app's open menu.
Tabs (Pro): the indicator isn't placed until the tabs have a size, so hidden tabs don't slide it in when they show, and it follows a tab whose label grows. Inactive tabs meet 4.5:1 contrast in every theme (they were as low as 4.11:1 in the gallery themes).
Inbox and ApprovalQueue (Pro): only the rows a re-sort moved slide, and the selection boxes are 24px targets. BarChart and LineChart (Pro) redraw in place when resized during an update. FilterChips (Pro) keeps focus on the chips when one is removed.
TaskTray (Pro): its open popover is named by its title ("Background work").
ProfileSettings' notSaved is one sentence a translation punctuates: a select phrase on end (stop when the reason ends in its own punctuation, other otherwise).
ChartFrame's docs page describes its empty, partial, error and busy states, and a free foundation comment no longer names a product.

CLI 2.1.0

theme check checks each brand scope ([data-brand="<name>"], as the theme builder writes several brands in one file) as a theme of its own, in light, dark, high contrast and the system's dark setting, after the base. A scope is measured as the browser draws it on an element inside <html>: a value the page works out at :root from another (--primary: var(--brand-ink)) keeps the root's value there unless the scope sets it again, as the theme builder's scopes do; a scope whose rules can only be on <html> is measured there. Results are labelled Light in [data-brand="acme"], count towards the totals and the exit code, and the JSON adds themes[].brand. A scope that changes no colour (only --radius, say) is named in a note and not measured again. The Pro drawings are accepted with a note naming the item they need.
A monorepo set up by an earlier CLI: where candor-lock.json records tokens at a copy in the app's styles/ that nothing imports (a CLI before 2.1.0 wrote it on add), update records and updates the candor-tokens.css beside the shared package's candor.css instead, removes the app's copy if it hasn't changed since it was installed, and says so when it leaves one you changed. Before, the copy candor.css imports stayed at the old version, so from 3.x colours such as bg-sunken and text-warning-text were missing. doctor names such a copy. Run npx candor-ui@2 update from the app.
Monorepos: update updates Candor's stylesheets where init installed them, in the shared package (it stopped before, saying styles/candor.css wasn't on disk), and add from the app no longer writes a second candor-tokens.css into the app. In a monorepo app whose ui alias is in a shared package, add without a terminal no longer stops over a file that differs only in import paths, and the dry run lists it as kept: its imports name different modules, and shadcn leaves the file as it is. The README's Monorepos section says what builds in shadcn's Base UI monorepo template.
An @/candor project stays as it is when one add by an older CLI wrote files into a candor/ folder inside it: the files recorded directly in the folder decide, and update moves the nested ones up, points their imports there and records them where they are, including the files of an item already at the version it updates to. add and doctor say when the lockfile records nested files, and to run update.
add, add --dry-run and update say once when tsx: false or cssVariables: false in components.json sends them to shadcn's own preview, and why.
audit titles its motion group "Motion never says something false", as the Principles page does.

Docs and the docs MCP

The docs MCP's theme_check says it checks each brand scope, as CLI 2.1.0 does.
Every item page opens with a sentence about the item. Twenty pages (Accordion, Avatar, Card, Checkbox, Collapsible, Command, Dialog, Drawer, DropdownMenu, Kbd, Popover, ScrollArea, Separator, Sheet, Skeleton, Toggle, ToggleGroup, ChartFrame, LocaleProvider, Surface) led with a short registry description, a helper's text, or nothing.
suggest_components no longer names sound for "which tools the agent may use", permission-prompt for "delete confirmation prompt", or the PDF items for "a settings page for the agent"; a higher tier's list shows at most three items.

Site, registry and repository

The site's registry files, docs pages, llms.txt and the docs MCP's data are built from source at each deploy rather than committed. The files served are the same, and a released version's files are checked against its frozen snapshot, so a deploy that would change them fails instead.
The public repository's README has a table of its dot-folders and plugins/, saying which tool reads each.
The Next.js and TanStack Start starters' crossSite() says it is the starter's own copy and where the Premium version installs, and is tested to decide as that one does.

For contributors

After pulling, run npm run generate (about ten seconds) before typecheck, test or dev: the generated files are no longer in git; node scripts/generated.mjs --check says whether they are this checkout's, comparing public/r and site/ with the snapshot and the docs data and the skill's references with a fresh generate. upgrade-check.mjs --cli <path> runs a given CLI against the target, and a checkout a patch past its target runs its own; fresh-app.mjs --monorepo and upgrade-check.mjs --monorepo run shadcn's Base UI monorepo template, and release:check's full run includes both. CI runs the fresh-app and browser jobs on release pull requests and weekly, and docs/RELEASING.md says how to release when CI can't run. upgrade-check.mjs --to <version> takes a fixture to this checkout's registry and CLI (or a later release), and the full release:check runs 3.0 → this version too; upgrade-check.mjs --monorepo checks that the stylesheets the shared candor.css imports are the target's.

Candor UI 4.0.2

Wed, 11 Nov 2026 00:00:00 GMT

A patch release, with CLI 2.0.1 and @candor-ui/react 4.0.0 as before. CLI 2.0.1 is for a 3.x project moving to 4.0: it carries CLI 1.0.1's fixes to the 2.x line, for an app whose components alias is a folder named candor (@/candor), for theme files you moved and recorded, and for a Candor file you changed that stays where it is. The Upgrading to 3.0 and 4.0 pages now say which codemods migrate <version> runs, and Tabs' docs page opens with what Tabs is.

What to do: run the 4.0 upgrade with CLI 2.0.1 (npx candor-ui@2 update --to 4.0.0, then npx candor-ui@2 migrate 4.0.0), and have everyone on the project use it: 2.0.0 puts files where 2.0.1 doesn't, and a lockfile both have written can disagree with the files on disk. If 2.0.0 already put files in a candor/ folder inside your candor alias's folder (<app>/candor/candor/) and candor-lock.json records them there, 2.0.1 goes on using that folder, so a project isn't switched back and forth between runs. update --moved can't fold them back, since the lockfile's nested paths decide. To fold them into the alias's folder by hand: move the files from <app>/candor/candor/ to <app>/candor/, change @/candor/candor/ to @/candor/ in your imports, replace candor/candor/ with candor/ in candor-lock.json's paths (each item's file keys and its moved entries), then run npx candor-ui@2 verify.

CLI 2.0.1

A components (or lib) alias that is already Candor's folder isn't nested again (Storywrite). Candor installs its files in a candor/ folder under each alias; where the alias's folder is itself named candor (@/candor, ~/candor), 2.0.0 put them in a second one (web/candor/candor/layer.tsx), and update couldn't match the files CLI 1.0.1 had placed in web/candor/ to the release's. update, add and the lockfile now place them in the alias's own folder (web/candor/thread.tsx, primitives in web/candor/ui/), with their imports pointed there; add gives shadcn local copies of the items placed that way. candor-lock.json decides which way a project goes: files it records in a candor/ folder inside the alias's folder keep the nesting, and files it records directly in the folder keep them there; only a project whose lockfile records neither is decided by whether that candor/ folder exists.
A move candor-lock.json records decides where a release's file goes, for add as for update. With the theme's stylesheets moved out of src/styles/ and recorded, 2.0.0's add (and init, and the add that update runs for a release's new items) had shadcn write them again in src/styles/, and update put a release's new stylesheet there, where the moved candor.css doesn't find it. Now a file you moved stays where you put it, and a new stylesheet goes beside the moved ones when every file the lockfile records in its folder was moved to the same place; the lockfile records that move too. The lockfile records each file where it is and keeps the moves (2.0.0 dropped them when it recorded an item again). Code files are not placed by a folder's move, since their imports would need pointing: add of an item whose code file you moved still has shadcn write a fresh copy where it installs it, as 2.0.0 did, while the lockfile keeps your move; delete the fresh one.
update --to 4.0.0 takes the release's imports in a Candor file you changed that stays where it is (a block's page that imports a renamed preset). 2.0.0 merged it against a base already pointed at the new places, so your copy kept its import of github-kinds after the file had moved to github-preset (or, where the release changed the lines around it, the merge stopped at a conflict). If a file 2.0.0 merged this way doesn't build, point that import at the preset's new name by hand.
migrate <version> names the release's codemods it doesn't run, and why. It runs a codemod only when an entry of that release on an item candor-lock.json records names it, so strings-keys runs only for a project with an item it changes, as in 2.0.0. The line is Not run: …, with npx candor-ui migrate <codemod> to run one anyway. Nothing it runs or changes is different.

The upgrade pages

The Upgrading to 3.0 and Upgrading to 4.0 pages, and the 4.0.0 notes above, said migrate <version> runs each of the release's codemods that an entry on your items names, which read as if every codemod listed always runs. The pages now say it runs, in order, those of the release's codemods that an entry on one of your installed items names, lists the ones it leaves out, runs all of them where there's no candor-lock.json, and that npx candor-ui migrate <codemod> runs one anyway. The 3.0 page names CLI 1.0.1 or later, and the 4.0 page CLI 2.0.1 or later.

CLI 1.0.1, for 2.x → 3.0

CLI 1.0.1 shipped between kit releases, from a maintenance line (npx candor-ui@1), for a 2.x project moving to 3.0. It fixes the same four things for that hop: Candor's files nested under a candor alias folder, a recorded move of the theme undone by migrate paths (and 3.0's new tokens stylesheet installed in src/styles/), the merge base of a file that stays where it is, and a migrate 3.0.0 that didn't say which codemods it skipped. Its notes are in packages/cli/CHANGELOG.md on that line. Use it, not 1.0.0, for the 2.x → 3.0 upgrade.

Docs

Tabs (Pro): its docs page and Markdown opened with the description of tabsListVariants, since the Tabs component had no doc comment. It has one now; npx candor-ui update tabs brings the comment.

Candor UI 4.0.1

Wed, 11 Nov 2026 00:00:00 GMT

A patch release, with CLI 2.0.0 and @candor-ui/react 4.0.0 as before. Some item descriptions, the public README's init --yes line, and comments in context-menu, schedule-list, details-list and knowledge-sources said Candor's primitives are on Radix; they have been on Base UI since 4.0.0. The Vite and TanStack starters' components.json now names base-nova, so shadcn add there installs shadcn's Base UI components, as in the Next starter.

Nothing to do. The registry and docs carry the corrected descriptions, and npx candor-ui@2 update brings the corrected comments for the items you have. If your app began as the Vite or TanStack starter at 4.0.0, you can set style in its components.json to base-nova.

Candor UI 4.0.0

Wed, 11 Nov 2026 00:00:00 GMT

A major release, with CLI 2.0.0 and @candor-ui/react 4.0.0. Candor's primitives are built on Base UI (@base-ui/react) in place of Radix, and take render in place of asChild. Each idea has one prop name across the kit: busy for waiting, onValueChange for a callback with the value, headingLevel, locked for a control that can't be used, activeId with onSelect, and title for a visible heading. Candor's own tokens take the --cd- prefix (--cd-sunken, --cd-warning), so an app's own --warning can't collide with them, and its chart series are shadcn's --chart-1 to --chart-5, with --cd-chart-6 for the sixth. CLI 2.0 runs the upgrade (npx candor-ui@2 update --to 4.0.0, then npx candor-ui@2 migrate 4.0.0) and no longer changes a 1.x or 2.x project, which keeps CLI 1. page-header and page-state join the free tier, the five presets are renamed *-preset, and layer replaces render-prop, so the kit has 324 items: 73 free and 293 in Pro.

Upgrading from 3.x

Start from a committed tree, so you can see what each step changed. Then, from the app's folder (the one with components.json):

Look first: npx candor-ui@2 update --to 4.0.0 --dry-run prints what 4.0 changes for the items in candor-lock.json, with the files it would move (the presets' new names), the npm packages it would install (@base-ui/react) and the merges it would make, and writes nothing.
Update: npx candor-ui@2 update --to 4.0.0 installs @base-ui/react with your package manager when package.json doesn't list it (--no-deps names the command instead), into the package that holds Candor's primitives (in shadcn's monorepo, the shared ui package, not the app), moves each renamed preset's file (github-kinds.ts to github-preset.ts …) and points your imports at it, then updates every item, merging your changes into Candor's as update always has.
Migrate: npx candor-ui@2 migrate 4.0.0 runs each of 4.0's codemods that an entry on your installed items names, in this order: as-child, props, strings-keys, tokens. They change Candor's components only: shadcn's own components in components/ui/ and your own elements stay as they are. Each runs under its own heading, says what it changed, and lists what it couldn't under "Left for you". Candor's own files aren't rewritten, since update brings them; in one you've changed, which update's merge keeps, each old name or asChild a codemod finds is listed under "Left for you" with file:line, for you to change. --dry-run shows it first.
Finish and check: make the changes marked "by hand" below, then type-check (npx tsc --noEmit) and build. npx candor-ui@2 theme check reports a token name 4.0 renamed that is still in your CSS as an error, naming migrate tokens.

update, when it moves files, and migrate read your source with the project's own TypeScript 5. On TypeScript 7, which has no JavaScript API yet, install 5 for the run and put 7 back after; candor-ui never installs it itself.

Every change, by its id in scripts/breaking.json (the same entries update --to 4.0.0 prints, and the [Upgrading to 4.0](https://candor.themethodic.com/upgrading-to-4) page lists):

as-child (codemod as-child): Candor's primitives take render, not asChild: <Button render={<a href="/docs" />}>Read the docs</Button>. An asChild on one of them fails the type check, and the part draws its own element with the child inside it. The codemod rewrites each one on Candor's components, adds nativeButton={false} where a Candor part that takes it (Button, and the triggers and closes of Dialog, Popover, Select, Tabs and the others) renders a link, a span or a div, and lists an asChild it can't follow (no element child, or a value that isn't true).
primitives-base-ui (codemod props, and by hand): every one of Candor's 51 primitives is built on Base UI. The codemod renames TooltipProvider's delayDuration, skipDelayDuration and disableHoverableContent to delay, timeout and disableHoverablePopup. By hand: a dialog's or popover's onOpenAutoFocus and onCloseAutoFocus are initialFocus and finalFocus (an element, a ref, or a function that returns one); an onEscapeKeyDown or onInteractOutside handler moves into the root's onOpenChange(open, details), calling details.cancel() where you prevented the default; and a style that selects data-state on them (data-[state=open]) selects Base UI's attributes instead (data-open, data-closed, data-checked …). A project without @base-ui/react doesn't build; update installs it.
direction-moved (by hand): LocaleProvider hands the text direction to Base UI's DirectionProvider, and Candor's locale file no longer passes Radix's Direction through. TextDirection and directionOf are unchanged; code of yours that used Radix's Direction imports it from radix-ui.
props-busy (codemod props): Combobox's, DataTable's, PromptSuggestions' and ImportReview's loading, PermissionMode's and MemoryMode's pending, ClarifyingQuestions' submitting, WorkflowEditor's saving, CommandPalette's searching, AssigneePicker's assigning, ChangeSetReview's applying, ShipReview's shipping, DataImport's reading, DegradedPanel's retrying and ChartFrame's refreshing are busy, with the same boolean. ChartFrame marks its plot aria-busy while it is. DataTable's state={{ kind: "loading" }}, StopAll's inFlight, ThreadHeader's working and DocumentProgressQueue's retrying (a list of ids) are unchanged.
props-on-value-change (codemod props, and by hand): the onChange of Composer, DictationButton, PermissionMode, MemoryMode, InstructionsEditor, ModelSettings, ModelPicker, MessageBranches, ColumnMapper, RunScrubber, SoundSetting, CodeEditor and ReviewLadder is onValueChange, with the same value. An onChange on an element of your own, such as an <input>, stays. By hand: composer.onChange read from the props useCandorChat, useAgUi or useClaudeAgent return is composer.onValueChange (<Composer {...composer} /> keeps working), and useDictation's onChange option is onValueChange. The type check finds both. NotificationPreferences' and ToolPermissions' onChange, which report one row's change, are unchanged.
props-heading-level (no codemod: nothing to rename): every prop that sets a heading's level is headingLevel and takes 1 to 6. A level you pass today still type-checks; code of yours that passes the prop's type to something narrower needs its own type widened.
props-locked (by hand): DictationButton's disabled is locked, the reason the person is shown: locked={streaming ? "Wait for the reply to finish." : undefined}, in your own words. migrate lists each one under "Left for you".
props-active-id (codemod props): Tree's selectedId is activeId, and Plan's activeStepId and onSelectStep are activeId and onSelect, as in RunTree, SessionList and the other lists.
props-title (codemod props): PromptSuggestions' label, the heading above the suggestions, is title. The words under strings.promptSuggestions.label are unchanged.
props-base-ui-names (codemod props, and by hand): CandorConfig's tooltip takes delay, timeout and disableHoverablePopup where it took delayDuration, skipDelayDuration and disableHoverableContent, and gains closeDelay; the codemod renames them in a tooltip: { … } object in a file that imports CandorProvider or CandorConfig. By hand: CommandPalette's onCloseAutoFocus is finalFocus, which returns where focus goes (finalFocus={() => el}, or false to leave it); migrate lists each one under "Left for you".
strings-change-diff (codemod strings-keys): ChangeDiff's strings take its name: the metadataDiff namespace is changeDiff, and the metadataDiffStrings table is changeDiffStrings. Words given under strings.metadataDiff aren't read until they move.
preset-rename (no codemod: update makes the moves): github-kinds, hubspot-kinds, jira-kinds, linear-kinds and salesforce-kinds are github-preset, hubspot-preset, jira-preset, linear-preset and salesforce-preset, since they hold nouns as well as kinds. Their exports keep their names.
tokens-cd-prefix (codemod tokens, and by hand): 23 of Candor's colour roles take --cd- (--sunken is --cd-sunken, --warning is --cd-warning, and so on for --chrome, --faint-foreground, --border-strong, --primary-hover, the -weak and -text pairs, --on-success, --on-destructive, --surface-agent, --surface-user and --text-provisional). --series-1 to --series-5 are --chart-1 to --chart-5, and --series-6 is --cd-chart-6. Nothing fails to compile: a brand file that sets an old name no longer reaches Candor, and an app's shadcn chart colours now restyle Candor's charts too. shadcn's own tokens and the Tailwind classes (bg-sunken, text-warning-text) don't change. The codemod renames them in your stylesheets and, in your source, where a string reads or sets one: inside var(), in Tailwind's arbitrary values (bg-[var(--sunken)]), as a style object's key and in setProperty. Other strings that look like a token, such as a script's --chrome flag, stay. By hand: a file that sets both --series-N and --chart-N is listed under "Left for you", for you to choose the colour. The codemod can't tell a variable your app defines for itself from Candor's, so it renames those too: if your app had its own --warning (or another of these names), rename yours back after migrating. npx candor-ui@2 theme check, run before migrating, lists each place your CSS sets or reads one of these names, with its file and line, and migrate tokens --dry-run lists every rename it would make.

Also:

A Radix app keeps its own primitives. shadcn's components in components/ui/ and the radix-ui package stay yours; Candor's Base UI primitives sit beside them in components/candor/ui/, so the app carries both libraries. In a test Next.js app, six Radix primitives were 57.4 KB of client JavaScript (gzip), and the same six on Base UI added 68.3 KB. A Candor dialog, popover, select or tooltip opened inside or beside the app's own Radix dialog takes the pointer, focus and Escape (foundation/layer, checked in Chromium and WebKit).
Stored styles are data, not source. No codemod reaches a theme saved in a database or a CMS: rename its tokens once, where it is stored.
3.x stays installable. https://candor.themethodic.com/r/v/3.0.0/<name>.json serves every item as 3.0.0 shipped it, with the same licence check, and npx candor-ui add <item> --version 3.0.0 installs from there. Your licence covers 4.0 as it does every version.
A 2.x project upgrades to 3.0 first, with CLI 1: npx candor-ui@1 update --to 3.0.0, then npx candor-ui@1 migrate 3.0.0 ([Upgrading to 3.0](https://candor.themethodic.com/upgrading-to-3)). CLI 2.0 names those commands and changes nothing in a 2.x project.

Primitives on Base UI

Candor's API is kept where Base UI's differs: side, align and the other placement props on the content part, Accordion's and ToggleGroup's type="single" | "multiple" with string values, Checkbox's checked="indeterminate", Select's string value with "" for none (SelectValue shows the chosen item's text before the list has been opened), Slider's number[] with onValueCommit, Tabs' activationMode, menu items' onSelect (where preventDefault() keeps the menu open), and a checkbox or radio menu item closing the menu once ticked (closeOnClick={false} keeps it open). Accordion keeps arrow-key movement between headings. An onClick that calls preventDefault() on a dialog's close part still keeps it open.
What you'll notice: Escape closes a submenu before its menu; Tab, not ArrowDown, enters a navigation menu's panel, and its panels open in one shared box (viewport={false} only sets data-viewport); and a dialog opened from inside another doesn't close on an outside click. Their state shows in Base UI's attributes (data-open, data-checked, data-pressed …), which the kit's own classes, the forced-colours styles and the motion families read.
Size: the 51 ui modules are 186.4 KB gzip, from 131.3 KB on Radix.
Firefox: the layer and browser checks ran in Chromium and WebKit for this release; Firefox didn't run.
The free layer item (foundation/layer) holds what makes Candor's layers work inside another library's modal dialog; render-prop (withRender, RenderProp) is removed.

Components and the free tier

page-header and page-state are free (MIT), each with a docs example. page-state holds the ListState type, so the free item doesn't import the Pro data, which declares the same type.
Registry categories take the source folders' names: an item's categories in /r/<name>.json say foundation where they said lib, parts where they said blocks, and blocks where they said blocks-full. The docs' group titles are the same. locale and locked keep their install paths.
Locked holds a locked control still by every route. A locked Checkbox, Switch or Radio no longer changes when its label is clicked or its form is reset, and a locked Select's or Menu's trigger no longer opens on a press or an arrow key.
Tooltips describe their trigger to screen readers (aria-describedby) while open, so a reason given only in a tooltip, such as a locked permission's, is read out. A new describes prop on Tooltip turns it off; Locked does, since it describes the control itself.
standardCards keep their English export and gain standardCardsStrings and useStandardCards(), so the cards' labels and check messages can be translated.
DictationButton says "Transcribing…" while it transcribes, and is aria-disabled rather than disabled.
BulletBar's met target uses the success colour, not a chart series.
Layers in a dialog that clips its content: inside a scrolling dialog, Candor's popovers, menus and tooltips show in the browser's top layer, so the dialog doesn't clip them. The known limit: a Radix layer opened from inside one of them is drawn under it.

Blocks and templates (Premium)

About 840 strings in eleven blocks and four templates now go through their string tables: page titles, empty states, errors, forms, attribute text and the approve-from-anywhere email copy (approvalEmailStrings, and approvalEmail(r, t) takes an optional translator). The project workspace's amounts and the support copilot's pass rate go through the locale's formatters. Server-side sentences (there's no LocaleProvider there) and brand props stay typed.
Breaking: the card maps are hooks. Each block's and template's map of standard cards is built from its string table by a hook (useCostCards(), useDataCards(), useEvalCards(), useEvalDashCards(), useKbCards(), useOpsCards(), useRunCards(), useSupportCards(), useCopilotCards()), so the cards' labels and check messages follow the locale. The module constants (costCards and the rest) are gone: code that imported one calls the hook inside a component instead.
ChangeSetReview's keyboard hint takes its separators and key pairs from its strings (hintEither, hintItem, hintSeparator), so a translation can change them.
setAddress() in three templates: the approvals inbox, the support copilot and the project workspace take the router's address through setAddress() and useAddress(), as the ops console does. The project workspace reads it, so it now follows a move between pages.

@candor-ui/react 4.0.0

The package's version is the kit's again (3.0's was 3.0.1). It depends on @base-ui/react in place of radix-ui, and exports page-header and page-state with the other free items. The free items' changes above are in this version; in a project that uses the package, npx candor-ui@2 migrate 4.0.0 runs every 4.0 codemod (there is no candor-lock.json to choose from).

CLI 2.0.0

2.0 because it drops support for kit 1.x and 2.x projects. It works with Candor 3.0 and later; npx candor-ui@1 stays on npm for a 1.x or 2.x project, which update, migrate and add send there without changing anything.

Removed: the 15 v3-* lint and audit rules and audit's "What 3.0 changes" group; the 2.x → 3.0 codemods (orgdata, metadata-diff, card, terms, paths, refusal); migrate --for and update --no-move; and the 2.x branches in add, doctor and the @candor-ui/react findings.
Kept: strings-keys and motion-aliases, since a 3.0 project can still have what they change; and update's moves, for a release that renames an item.
migrate 4.0.0, new, runs as-child, props, strings-keys and tokens, each on Candor's components only. as-child, props and tokens are new; strings-keys gains metadataDiff → changeDiff.
update installs the npm packages the new versions declare that package.json doesn't list, with the project's package manager, as add does: a 3.0 app gets @base-ui/react. --no-deps names the command instead, --dry-run says what it would run, and a failed install exits 1.
update moves the renamed presets (github-kinds to github-preset and the other four) and points your imports at them.
init --yes sets up a Base UI project (--base base, shadcn's nova preset), as shadcn init does by default.
theme check against a 4.x kit reports a 3.x token name, set or read with var(), as an error that names migrate tokens, and token errors now fail the check.
add and doctor say that Candor's primitives are built on Base UI: on a Base UI project they're the app's own library, and on a Radix or React Aria one they install in components/candor/ui/ with @base-ui/react, beside the app's. The 2.x note that they install as Radix versions is gone.
update --to 4.0.0 ends its list of breaking changes with a link to the Upgrading to 4.0 page.
Fixes: with items named, update --to's heading names them, not "the items in candor-lock.json"; update --to a version that is not released yet for an item the lockfile doesn't record says its version is unknown and how to give it; a snapshot whose breaking entries couldn't be read is named, not dropped without a word; the line after update installs a Candor item says "the version this update moved to", not "the version you asked for with --version"; and a registry that still serves an item under its old name updates it in place.
migrate fixes: tokens renames a token in source only inside var(), Tailwind's arbitrary values, a style object's key and setProperty (it had renamed any string that looked like one, such as a --chrome flag); as-child reads .js and .mjs files as well as .jsx and .tsx; in a monorepo, the codemods read the shared ui package's source, and tokens reads the stylesheet components.json names, wherever it is; and as-child adds nativeButton={false} on every Candor part whose Base UI part takes it, not only Button.
add and migrate refuse a 2.x project and name CLI 1, as update does: add without --version, and migrate with no lockfile, working the version out from what is installed.

Docs

Upgrading to 4.0, new at /upgrading-to-4 (and /upgrading-to-4.md): the commands, then every entry of the 4.0 list with what breaks, where it shows, what to do and its codemod, built from the same list update prints. /upgrading-to-3 stays for 2.x projects.
The Design page and the Theme docs show the --cd- names and the chart series on --chart-*. The docs pages for the presets are at their new names, and the old addresses redirect; /docs/render-prop goes to the upgrade page.
The README, the install notes for coding agents and Get started say that init --yes sets up Base UI, and that Candor's primitives are built on it.

Theme builder

A theme saved from 3.x loads: the builder reads a downloaded theme's 3.x token names (--sunken, --series-1) as their 4.0 names.

For contributors

CLAUDE.md's "Both primitive worlds" is "Base UI primitives". scripts/fresh-app.mjs --radix builds a shadcn Radix app and runs the layer checks (tests/browser/layers.mjs) in it.
node scripts/upgrade-check.mjs --from 3.0.0 upgrades a 3.0 fixture project with update and migrate and builds it, in the normal flow, on Base UI and in a Radix app; release:check runs it with --fresh.
tests/templates/strings.test.tsx fails on typed English in any block or template, with an empty allowlist.
A test fails when a scripts/breaking.json 4.0 entry isn't named in this section and on the upgrade page.

Candor UI 3.0.0

Tue, 10 Nov 2026 00:00:00 GMT

A major release, with CLI 1.0.0 and @candor-ui/react 3.0.1. Candor's files install in folders of their own (components/candor/, components/candor/ui/ and lib/candor/), so they no longer sit among your app's files. The app's nouns move from TermsProvider into LocaleProvider, where they become arguments of its messages, with plural forms and gendered selects. The names 2.x marked for removal are gone. npx candor-ui@1 update --to 3.0.0 carries a 2.x project across: it moves Candor's files, points your imports at them and updates, and npx candor-ui@1 migrate 3.0.0 then runs the release's codemods. No item is new and metadata-diff is renamed change-diff; the free terms item is removed, so the kit goes from 325 to 324 items: 71 free and 293 in Pro.

Upgrading from 2.x

Start from a committed tree, so you can see what each step changed. Then, from the app's folder (the one with components.json):

Look first: npx candor-ui@1 update --to 3.0.0 --dry-run prints what 3.0 changes for the items in candor-lock.json, with the moves and merges the update would make, and writes nothing.
Update: npx candor-ui@1 update --to 3.0.0 moves Candor's files to components/candor/ and lib/candor/, copies Candor's ui primitives to components/candor/ui/, points the imports in your project at the new places, records the moves in candor-lock.json, and then updates every item, merging your changes into Candor's as update always has. components/ui/ stays: from now on it is yours, and candor-ui doesn't update it. An item 3.0 no longer has (terms) is listed, left where it is and dropped from candor-lock.json. --no-move keeps CLI 0.15's behaviour, which stops and names the moves instead of making them.
Migrate: npx candor-ui@1 migrate 3.0.0 runs each of 3.0's codemods that an entry on your installed items names, in this order: metadata-diff, paths, orgdata, card, terms, strings-keys, refusal, motion-aliases. Each runs under its own heading, says what it changed, and lists what it couldn't under "Left for you". --dry-run shows it first.
Finish and check: make the changes marked "by hand" below, then type-check (npx tsc --noEmit) and build. On a project whose candor-lock.json records 3.x, npx candor-ui lint reports a name 3.0 removed that is still in your code as an error, naming its codemod.

Every change, by its id in scripts/breaking.json (the same entries update --to 3.0.0 prints, and the [Upgrading to 3.0](https://candor.themethodic.com/upgrading-to-3) page lists):

paths (codemod: update --to 3.0.0 makes the moves; migrate paths --for 3.0.0 makes them on their own): imports of an item at its 2.x path (@/components/thread, @/lib/chat) stop resolving once its file has moved.
metadata-diff (codemod: update moves the file, then migrate metadata-diff renames the import and the tag): MetadataDiff is removed and the item is renamed change-diff, so it installs as components/candor/change-diff.tsx. Import ChangeDiff; the props are the same. Before the update, migrate metadata-diff refuses without --for 3.0.0, since 2.x's add still installs metadata-diff.tsx.
orgdata (codemod orgdata): the orgData inline node is removed. A block built as { kind: "orgData", … } fails the type check; in untyped data (a server's JSON, stored messages) nothing is drawn where the node was, though the message's plain-text copy keeps its text. Use kind: "measured"; the fields are the same.
card (codemod card): card-registry's Card, its first name for RegistryCard, is removed. Import RegistryCard; the props are the same. shadcn's own Card is not affected.
terms (codemod terms): TermsProvider, useTerms, capitalise, the Terms type and the terms item are removed. The app's nouns are set on LocaleProvider as nouns, or as CandorProvider's config.nouns, and fill {environment}, {Environment}, {account} and {product} in every message. useNouns() and startOf() replace useTerms() and capitalise(), NounTable and Nouns replace Terms, and the presets are githubNouns, hubspotNouns, jiraNouns and linearNouns. The codemod rewrites each of these and lists what it can't follow (a re-export under the old name, terms through an untyped spread); then delete the installed terms file, whose path the codemod names, once nothing imports it. Your 2.x words work as they are; add plural forms where a message counts them.
message-thinking (codemod strings-keys): Message's working line reads only message.working. An override of message.thinking alone shows Candor's own "Working" again. The codemod renames the key, unless working is already there.
answering-approvals-strings (codemod strings-keys): useAnsweringApprovals' words are read only under answeringApprovals in LocaleProvider's strings. An override under useAnsweringApprovals shows Candor's own sentence again when an answer fails to send. The codemod moves it, in an object given as strings or typed StringOverrides or CandorConfig.
block-refusal-export (codemod refusal): the Refusal re-export from the stores of plan-build-review, run-console, agent-ops-console and project-workspace is removed. Import Refusal from the server foundation, @/lib/candor/candor-server in a default install; it is the same class.
motion-aliases (codemod motion-aliases): the 2.2 motion tokens --cd-pop-from and --cd-motion-shake are no longer read, and data-motion="expressive" no longer sets their presets. --cd-pop-from becomes --cd-motion-pop-scale, which applies from the expressive level only. --cd-motion-shake has no single replacement, so the codemod lists it under "Left for you": set the refuse family's --cd-motion-refuse-distance, -dur and -ease, or its level, --cd-motion-refuse.
legacy-animations (codemod motion-aliases): the 2.2 animate-* utilities (animate-shimmer, -pulse-dot, -rise-in, -caret, -collapse-down, -collapse-up, -pop-in, -pop-out, -tick-draw, -fill, -shake, -attention, -attention-wait, -nudge) are removed, with the unprefixed keyframes only they ran. A class such as animate-pop-in stops animating, and animation: pop-in … finds no keyframes. The codemod moves classes to the motion families' cd-* utilities and renames keyframes where the frames are the same; it lists animate-attention-wait, animate-shimmer and the pop-out, collapse-* and shake keyframes with what to do for each. The shimmer keyframes stay, for shimmer-text.
attention-kinds (by hand): AttentionKind gains reply and silent. A Record<AttentionKind, number> built by hand needs reply: 0, silent: 0, and an exhaustive switch needs both cases or a default. Code that only reads counts.approval and the like changes nothing.
attention-sound-when (by hand): useAttention's sound plays only while the window isn't in front of the person, unless you pass when: "always", 2.x's behaviour. Nothing fails to compile, so check every useAttention with a sound.
block-viewer-of (by hand): the blocks' and templates' viewerOf(request) is removed. Use getViewer(request) or viewerName(request) from @/lib/candor/candor-server; both are async and answer null when nobody is signed in, where viewerOf gave the demo person.
block-context-of (by hand): contextOf(request) in audit-data-controls' and approvals-inbox's stores is removed. Use signedInContext(request) from the same store: it is async and answers null when nobody is signed in.
inbox-post (by hand): approvals-inbox's post(body) is removed. Use usePost() from the same file in a component; it says its errors in LocaleProvider's words.
block-db-connect (by hand): the fifteen blocks' and templates' db/connect.ts files are removed; each store opens the shared pool through database() from @/lib/candor/candor-database. If you swapped the driver or the URL in db/connect.ts, give your database to setDatabase() once at startup instead. update leaves your old db/connect.ts in place, with its imports pointed at the new places; delete it once nothing imports it.

Also:

Stored orgData messages are data, not source. No codemod reaches a database or a saved conversation: change their kind from orgData to measured once, where they are stored.
2.x stays installable. https://candor.themethodic.com/r/v/2.10.0/<name>.json serves every item as 2.10.0 shipped it, with the same licence check, and npx candor-ui add <item> --version 2.10.0 installs from there. Your licence covers 3.0 as it does every version.
Monorepos need CLI 1.0. 3.0 installs Candor's primitives in the app (components/candor/ui/), not in the shared ui package, and only CLI 1.0 follows that.
add at 3.0 on a 2.x project stops (CLI 1.0) and names update --to 3.0.0, so a 3.0 item never lands among 2.x files. To add to a 2.x project without upgrading, pass --version 2.10.0.
OrgSmith's pack is no longer built here: public/orgsmith is gone from the product build, and OrgSmith uses the v2.10.0 tag's copy until its own repository exists. No @candor item changes because of it.

Install paths

Candor's files are in folders of their own. A component installs at components/candor/<name>.tsx, a ui primitive at components/candor/ui/<name>.tsx, and a shared helper or type at lib/candor/<name>.ts (types are in @/lib/candor/chat). The server foundation is lib/candor/candor-server.ts and components/candor/candor-sign-in.tsx. Blocks, templates, the theme's stylesheets and the sounds keep the places they had. The aliases come from your components.json, so a project with its own components or lib alias gets the same folders under it.
Candor's imports name Candor's files. The files Candor installs import each other by their installed names (@/components/candor/message), so a components/message.tsx of your own no longer captures an import meant for Candor's.
The kit's source moved into new folders (lib/ to foundation/, the small parts in blocks/ to parts/, locked into ui/). Item names, the docs' groups and the registry's categories are the same as in 2.x; what changes for you is only where the files install, above.

Locale: the app's nouns

Nouns are message arguments. LocaleProvider takes nouns (CandorConfig.nouns in CandorProvider), and every message that names one ({environment}, {account}, {product}) is filled with the app's word, in the form the message's count picks; {Environment} starts a sentence with the environment value a component passes, or else with the app's noun. Nested providers merge noun by noun.
A noun can have plural forms ({ one: "workspace", other: "workspaces" }); when environment has them and environments isn't set, environments defaults to its other form, and an environments you set still wins. A noun can also have a gender that a select message chooses its case by ({ select: "environment", cases: { feminine: "…", other: "…" } }), and a start form for languages where upper-casing the first letter isn't how a sentence starts.
useNouns() gives each noun's singular form for your own code, and startOf(text, locale?) upper-cases the first letter as the locale writes it. Both come from locale; fill-strings (free, and safe on the server) has the types, nounDefaults, fill, pick and englishStrings(table, { nouns }).
An override that writes a noun's placeholder no longer needs it passed: { environmentBand: { environmentsIn: "{Environments} in {account}" } }. New keys, if you translate these components: environmentConnect.formLabel, runLog.environment, accessRequest.environmentLabel and auditLog.system.

CLI 1.0.0

1.0 because its commands and lockfile have been stable since 0.12; it works with any kit release from 1.0 on. update --to 3.0.0 and migrate 3.0.0 need it. Use npx candor-ui@1 to stay on it.

update makes a release's moves itself: where a release installs an item's files somewhere else, it moves them (copying ui primitives), points the imports in your project at the new places, records the moves in candor-lock.json, and then updates. --dry-run lists the moves with the merges; --no-move stops and names them, as 0.15 did.
migrate <version>, new, runs that release's codemods for the items your project has, in order.
migrate terms rewrites to LocaleProvider's nouns, where 0.15's listed the uses; strings-keys and refusal are new codemods; migrate paths takes its destinations from the release's own install targets.
On a 3.x project, lint and audit make a removed name an error naming its codemod (what a codemod lists rather than rewrites, --cd-motion-shake, stays a warning), and drop the v3-paths and v3-attention-* notes. theme check against a 3.0 kit makes --cd-pop-from and --cd-motion-shake errors.
add at 3.0 on a 2.x project stops and names update --to 3.0.0.
A plain update stays within the major you're on: without --to, it moves your items to the newest release in the major candor-lock.json records, the way add stays at the locked version, and when a newer major is out it prints one line naming it and the npx candor-ui@1 update --to <version> --dry-run that shows its breaking changes. To cross, pass --to 3.0.0.
add and doctor on Base UI and React Aria say that from 3.0 Candor's primitives install in components/candor/ui/, beside your own in components/ui/, and no longer name your files as replaced; on React Aria this is a note, not a fix. A project on 2.x keeps the 2.x warning.
doctor beside @candor-ui/react gives each import's move at 3.0's paths (@/components/candor/thread), names LocaleProvider's nouns from @/components/candor/locale in place of TermsProvider, and counts a copied components/candor/locale.tsx.
lint and audit link their 3.0 rules to the Upgrading to 3.0 page.

Docs

Upgrading to 3.0, new at /upgrading-to-3 (and /upgrading-to-3.md): the commands, then every entry of the 3.0 list with what breaks, where it shows, what to do and its codemod, built from the same list update prints.
The Locale page shows the app's nouns, with plural forms and a gendered select; the Terms page is gone, and /docs/terms redirects to Locale. CandorProvider's example sets config.nouns.
The Design page's motion section says what 3.0 removed and links to the upgrade page.

@candor-ui/react 3.0.1

This release's package is 3.0.1, not 3.0.0: 3.0.0 was published by mistake before the release and withdrawn, and npm doesn't reuse a version.

The free items' removals above are in this version: TermsProvider, useTerms, capitalise and Terms (use LocaleProvider's nouns, useNouns and startOf), the orgData node, card-registry's Card and message.thinking. In a project that uses the package, npx candor-ui@1 migrate 3.0.0 runs every 3.0 codemod (there is no candor-lock.json to choose from), and terms and card rewrite imports from @candor-ui/react as they do from Candor's installed files.

For contributors

The source folders are src/registry/foundation/ (was lib/) and src/registry/parts/ (was blocks/), with locked in ui/; internal/release-3.0/arch4-moves.mjs is the record of the moves.
OrgSmith's pack is packages/orgsmith, a private package that installs @candor as a buyer does; the build makes one registry.
node scripts/upgrade-check.mjs --from 2.10.0 upgrades a 2.10 fixture project with update and migrate and builds it, in the normal flow, the 0.15 flow and on Base UI; release:check runs it.
A test fails when a scripts/breaking.json 3.0 entry isn't named in this section.

Candor UI 2.10.0

Tue, 10 Nov 2026 00:00:00 GMT

The road to 3.0, and work an agent proposes that a person edits, promotes or passes on. 2.10 is the last 2.x minor and breaks nothing: each item's registry entry now lists what 3.0 changes in it, npx candor-ui update --to 3.0.0 prints those changes for the items your project has, npx candor-ui migrate makes the ones a codemod can, and lint, audit and development warnings point at the code they touch. Ten items are new: a workflow editor for an automation an agent proposes, a connect flow for an outside service, an environment promotion, an escalation outside the app, an assignee picker, a per-document progress queue, keyboard review for any list, a search trace, a proposal with the alternatives the agent weighed, and fill-strings, moved out of locale so server code can fill strings. All are Pro except fill-strings, which is free, so the kit grows from 315 to 325 items: 72 free and 294 in Pro. The sidebar can collapse to an icon rail, the Premium blocks and templates take more of their words from LocaleProvider, and the theme builder gains colour-vision views, a compare view and brand scopes. With CLI 0.15.0 and @candor-ui/react 2.10.0. Nothing is removed and no prop is renamed. A few behaviours change for code you already have; each is in "What to do" below and again in its section.

What to do

Everyone, before 3.0: run npx candor-ui update --to 3.0.0. It prints what 3.0 changes for the items in your candor-lock.json, where each change shows and its migration, and changes nothing. useAttention's sound default is on that list, and no compiler catches it.
Everyone updating, fill-strings: locale, which every project has, and every Premium block and template now import the new free item fill-strings (lib/fill-strings.ts). npx candor-ui update (CLI 0.15) installs it with them and records it in candor-lock.json. With --no-deps it only names it: run npx candor-ui add fill-strings, since the project doesn't compile without it. If installing it would move an item you didn't name (the shared tokens), update stops before writing anything and says which items to update together.
Tests that fail on console output: in development, Candor now logs a warning once per page for code 3.0 changes: useAttention given a sound that is on (enabled: true) without when, a message with an orgData inline node, and MetadataDiff. Nothing is logged in production. Pass when: "always" to keep 2.x's behaviour (or "away", 3.0's default), change kind: "orgData" to kind: "measured" (npx candor-ui migrate orgdata), and use ChangeDiff from the same file in place of MetadataDiff, by hand on 2.x (as you move to 3.0, npx candor-ui migrate metadata-diff --for 3.0.0 does it and moves the file). MetadataDiff is now a small component around ChangeDiff, so MetadataDiff === ChangeDiff is false.
Your own string overrides, ahead of 3.0: 3.0 reads only message.working (2.9's new key for Message's working line) and only answeringApprovals for useAnsweringApprovals' words. Move an override of message.thinking, or one under useAnsweringApprovals, to the new key now; 2.9 and later already read it first. candor-ui lint points at both.
Premium blocks and templates, the 2.7 shims: 3.0 removes viewerOf, contextOf, the approvals inbox's post, the stores' Refusal re-exports and db/connect.ts. candor-ui lint names each use in your own code and what to use instead.
DataTable's column picker: the last visible column's box is Locked with its reason ("At least one column stays shown.") instead of disabled, so it carries aria-disabled. A test that expects it toBeDisabled() should check aria-disabled instead. If you translate DataTable, add the new lastColumn string.
EnvironmentConnect, McpConnect and ConsentCeremony while busy: Test connection, Connect and the grant button are Locked with a reason instead of disabled while a test runs or the connection or consent is being saved, so they carry aria-disabled and stay in the tab order. A test that expects them toBeDisabled() while busy should check aria-disabled instead. If you translate them, add the new strings waitTest and waitSave (environmentConnect), waitConnect (mcpConnect) and waitRecord (consentCeremony).
AgentScreen: both views now keep the frame in a new agent-screen-body element (display: contents when collapsed). If your CSS or tests reach the collapsed view's frame as a direct child of the section, go through [data-slot="agent-screen-body"].
Base UI projects, Locked, AppSidebar, ToolPermissions and RestoreDialog: in a shadcn project on Base UI, every control Locked with a reason drew a button inside a button, an extra tab stop and a hydration error. Released versions have this, 2.8.0 included, and Locked is free. shadcn's rewrite of asChild to render drops asChild when its child is a variable, so the tooltip's own button went round the control. AppSidebar's collapsed rail and person menu, ToolPermissions' locked modes and RestoreDialog's trigger had the same problem. Run npx candor-ui update locked app-sidebar tool-permissions restore-dialog. Radix projects and @candor-ui/react are not affected.
Theme builder, a component's density: files from earlier versions wrote a component's density under :root:not([data-density]), so data-density on the component, or on a container around it, didn't win over it. Those files open as before; download your theme again to get the new selector.
Locked without a reason: its className now goes on the control; before, it was dropped. If you pass className to a Locked whose reason can be empty, check the control's layout.
AppSidebar: a count and the usage percentage are formatted in LocaleProvider's locale, and a counted item's tooltip comes from the new labelCount string. If you translate AppSidebar, add labelCount, and collapse and expand if you use the new rail.
Premium, the agent ops console with a router: if you followed 2.9's advice and changed the console to read your router's address, update's merge conflicts on those lines. Keep 2.10's, which read the address through useAddress(), and call the new setAddress() beside setNavigate() with the router's path and query (in Next.js, from usePathname() and useSearchParams() in an effect).
Premium, words you edited in blocks' and templates' files: much of their typed text now comes from a string table per block. If you changed that text in the files, keep the new lines and give your words to LocaleProvider's strings under the block's name. Some English is still typed.
Premium, the project workspace's downloads: a file is fetched before it is saved. If you serve the files another way than the template's api/file, answer with content-type: text/markdown; anything else is shown as a failure and nothing is saved.
The Vite and TanStack Start starters: their collapsible.tsx used animate-collapse-*, which 3.0 removes. If you started from either, replace your copy with the starter's, which uses the reveal motion family.
CLI, lint --strict in CI: CLI 0.15's 3.0 warnings don't fail --strict, so CI on an unchanged project stays green. They are printed and counted separately (breaking in --json).

Components

New (Pro):

workflow-editor, an automation an agent proposes and a person edits before it runs: a trigger (an event in your app, a schedule in schedule-editor's shape, or a person starting it) and steps and If/Else conditions built from the fields your app lists. Then and Else rejoin at the next node. The proposal is labelled as the agent's, and everything the person changes is marked against it. Problems your app finds show on the node they're about and lock Save, saying why. Nothing is saved until Save, which calls back with the definition and its change hash for your server to check; while a save is pending, edits make no change and the editor says the workflow is being saved. An edit is announced once, by the status line. Keyboard throughout, with the hint's joins as strings (hintEither, hintCombo, hintSeparator, hintItem), a list view for screen readers, and a graph view laid out by graph-layout.
integration-connect connects an outside service through the provider's sign-in or an API key, with the access it asks for in plain words (needed access listed as needed; optional access starts unticked). It runs a connection test and shows what the test found, or that it couldn't run and why, and says what the integration can and can't reach, or that it hasn't been described. An API key is used to test and to connect, then cleared from the field. Disconnect asks first, saying what stops and what stays.
environment-promotion promotes a configuration from one environment to another with the diff, who asked, who approved and when, which approvals are missing, and what can and can't be rolled back. Nothing is promoted without a decision: Promote stays locked, saying why, while approvals are missing, the target has changed since the diff, or nothing differs, and for production until the person ticks that they've read the change. The tick is for the change it was given on: when the diff or hash changes, or the target goes stale, it is cleared and the card says why. Approvals are counted by person: each by once, and never the requester's own (requestedBy.name); entries that don't count stay in the list, marked with why, so use the same name for a person in by and requestedBy. Pass your server's change hash as hash; it comes back to onPromote.
escalation hands a case off outside the app by a page, an email or a ticket. Before sending it shows who each way reaches now and exactly what will be sent (recipients, subject, message, attachments, and what isn't sent). A message an agent drafted says so and can be edited, and no way is chosen for the person. A new message from the agent replaces the subject and message if the person hasn't edited them; if they have, their text stays and the card says the message was redrafted, with "Use the new draft". Once your server records the send, pass it as sent.
assignee-picker chooses a person or an agent for a task. Each shows the load and availability your app passes, and what you don't pass reads as not known. Nothing is sorted, suggested or pre-chosen.
document-progress-queue shows per-document progress for a batch: queued, working with its stage, done, or failed with the reason and Retry. The summary counts states and documents finished and never shows time left or a percentage; pass adding while documents are still arriving. Screen readers hear failures and the batch finishing, not every document's step.
use-keyboard-review: useKeyboardReview gives any list of rows a person keeps or drops keyboard review: J/K or the arrows move, Y keeps, N drops, U undoes and returns to the row. The keys are strings under keyboardReview, so a translation can match its words, and each row lists them in aria-keyshortcuts. A decision made on a row that has since changed is cleared. Spread rowProps(i) on each row and put listRef on the list; row versions are worked out once per items and versionOf, so pass a versionOf that keeps its identity.
search-trace shows a search an agent ran as a tool-call row (title, status, duration, a count of searches and sources read). Opened, it lists each query as the agent ran it, with each source's title and domain under it, as text and never a link; the domain is read with the URL parser, so a host hidden in a user name shows the real host. A line says how many more sources the agent read only when the tool says so. Pass the ToolCall with queries beside it.
proposal shows one action an agent proposes with the alternatives it weighed beside it, each with its confidence through ConfidenceMark ("unknown" when the agent didn't say) and its reason introduced as "Its reasoning, not checked:" (proposal.reasonLabel). Nothing is chosen for the person: Accept and Edit are locked, saying why, until they pick, and Accept calls back with that option. Edit appears with onEdit, "None of these" with onDecline. With locked, "None of these" is locked with the same reason as Accept and Edit.

Integration connect, environment promotion and escalation wait for your app: after your handler resolves, Connect, Disconnect, Promote and Send stay locked, saying they are waiting for your app, until you pass sent, a new state or an error.

Changed (free unless marked):

fill-strings (new, free): fill, pick and englishStrings(table) in a module without "use client", so server code can fill a component's strings. locale imports it and still exports fill and pick.
Locked: without a reason, className goes on the control instead of being dropped. In a Base UI project, a locked control is one button again, not a button inside the tooltip's button; AppSidebar's collapsed rail and person menu, ToolPermissions' locked modes and RestoreDialog's trigger (Pro) are fixed the same way.
AppSidebar (Pro): the optional rail prop lets a person collapse the sidebar to its icons on a wide screen; each label becomes a tooltip, and accessible names, the current page, counts and tab order don't change. Keep the choice by storing what onCollapsedChange gives you and passing it back as defaultCollapsed. In a sheet it always shows its labels. Without rail, nothing changes. Counts and the usage percentage are formatted in the locale.
AppLayout (Pro): the sidebar's column follows the rail's width.
ChangeSetReview (Pro) runs on useKeyboardReview; its keys, focus and decisions behave as before.
DataTable (Pro): the column picker's last visible column is Locked with the reason (new string lastColumn) instead of disabled.
EnvironmentConnect, McpConnect and ConsentCeremony (Pro): while a test runs, or the connection or consent is being saved, Test connection, Connect and the grant button are Locked, saying why ("Wait for the test to finish.", "Wait for the connection to be saved.", "Wait for the connection to finish.", "Wait while your consent is recorded."), instead of disabled. A press while busy does nothing.
AgentScreen (Pro): changing between collapsed and expanded keeps the frame's element, so a video no longer restarts and a MediaStream isn't reattached (new agent-screen-body slot).
StopAll and RunScrubber (Pro): Play, and RunScrubber's Replay, are no longer mirrored in right-to-left.
Development warnings, once per page and never in production, for what 3.0 changes: useAttention (Pro) given a sound that is on (enabled: true) without when, as the CLI's lint rule does (3.0 plays sounds only while the person is away unless you pass when: "always"), a message with an orgData node (use measured), and MetadataDiff (Pro; use ChangeDiff). The deprecation notes on orgData and MetadataDiff said 2.0; they say 3.0.
Strings: AppSidebar's, WorkflowEditor's, DocumentProgressQueue's, SearchTrace's and IntegrationConnect's separators and colons are strings a translation can change.
PermissionMode, Diagram and Dictation (Pro) are now optimised by the React Compiler.

Blocks and templates (Premium)

fill-strings: every block and template now imports fill-strings. npx candor-ui update installs it with them.
Words through LocaleProvider: more of the typed English comes from a string table per block: prompts, deny reasons, placeholders, tool titles, the support copilot's customer page, the approvals inbox's Rules page and the ops console's top line. New tables agentAdmin, approvalGatedChange, approveFromAnywhere, auditDataControls, costGuard, evalDashboard, evalReviewLoop, humanHandoff, knowledgeBase and planBuildReview; runConsole, agentOpsConsole, approvalsInbox, projectWorkspace and supportCopilot gain keys. Some English is still typed. approvalsInboxStrings lives in the approvals inbox's agents.ts and is still exported from shell.tsx.
Tool titles take the block's translator as an optional third argument (English without it). Cost guard's also takes the locale's number format as a fourth, and its budget is written in the locale, reading "$5" for a whole amount.
Agent ops console: with a router given to setNavigate(), call the new setAddress() with the router's path and query, and the sidebar's current page, the sign-in check, ?run= and ?prompt= follow each move without a page load. When the section unmounts it forgets the router's address, so after a move out of the section and back it reads the browser's until your router reports again.
Project workspace: a file download is fetched first. Signed out (a 401, or a redirect to your sign-in) goes to sign-in; a refusal or a lost connection is shown in one sentence under the top bar, and nothing is saved.

Starters

The Vite and TanStack Start starters' Collapsible uses the reveal motion family instead of animate-collapse-*, which 3.0 removes.
The starters carry Candor 2.10.0's components, without the search tags.

CLI 0.15.0

update --to prints the breaking changes between each installed item's version and the version you update to: what breaks, where it shows, the migration, and the migrate codemod if there is one, each in the words of the release you update to, so a corrected entry reaches a project on an older 2.x. npx candor-ui update --to 3.0.0 shows what 3.0 asks of your project and changes nothing; run it before 3.0 is released.
migrate <codemod>, new, with orgdata, metadata-diff, motion-aliases, card, terms and paths. Each prints what it changed and lists what it couldn't, with --dry-run to look first. It reads your source with your project's own TypeScript 5. Your installed Candor files are left to update; without candor-lock.json, files named like Candor's in the folders Candor installs to (such as lib/chat.ts) are left alone and named, and if the registry's public lists can't be read, nothing is changed. terms lists the uses and changes nothing, since 3.0's form isn't designed yet. card and metadata-diff leave shadcn's Card, or another module's export of the same name, alone.
migrate paths and migrate metadata-diff move files (into components/candor/ and lib/candor/, and metadata-diff.tsx to change-diff.tsx), rewrite the imports that name them, and record the moves in candor-lock.json, so update follows them. Both run only as part of the move to 3.0: on a 2.x project they refuse unless you name the release, npx candor-ui migrate metadata-diff --for 3.0.0 and npx candor-ui migrate paths --for 3.0.0, followed by npx candor-ui update --to 3.0.0, once 3.0 is released. Until then add and update install to the old places and names; on 2.x, import ChangeDiff by hand. paths copies the ui primitives rather than moving them. In a monorepo, files in a shared package (shadcn's monorepo template) move within that package and every workspace package's imports are followed; names through package.json # imports are followed too. Nothing is removed until its new copy is written, a failed write puts everything back, and a name it can't resolve is listed.
lint and audit warn about what 3.0 removes in your own source and CSS, and name the codemod for each, including the message.thinking strings key, strings under useAnsweringApprovals, and the blocks' and templates' viewerOf, Refusal from a store, db/connect.ts, contextOf and the approvals inbox's post, each saying what to use instead. These warnings don't fail lint --strict; they are counted separately (breaking in --json). What 2.x can't take yet (Terms, the new install paths, AttentionKind's new kinds) prints as notes, which never fail.
update installs the Candor items a new version needs, as add would, and records them; --no-deps only names them, as before, and update exits 1 when one wasn't installed. If installing them would move an item you didn't name, it stops before writing anything and says what to update together.
update --moved accepts a renamed item's new file name (metadata-diff.tsx → change-diff.tsx), and a move recorded in candor-lock.json is looked at before the path the file was installed at.
Aliases through package.json imports (#components), and a monorepo app whose ui alias points into a shared package (shadcn's monorepo template): add, update and add --dry-run work out what shadcn writes themselves, instead of running a shadcn preview per item. In such a monorepo, a --path naming a file still uses shadcn's preview. Checked against real shadcn 4.23.0 installs into shadcn's monorepo template (Radix and Base UI) and three # projects: the files are the same.
The README says what type-checks in shadcn's monorepo template. With the template's own components.json the installed items don't type-check, which is shadcn's output for Candor's import form. The workaround: before init, set the app's ui alias to @/components/ui, and give the app's tsconfig "lib": ["es2023", "DOM", "DOM.Iterable"].

Docs and the docs MCP

suggest_components leaves out a hook or helper the task doesn't ask for or name when the components in the answer cover what it was found by, or cover more of the task; it no longer lists use-answering-approvals beside the approval components at the Pro tier, or beside citation for "citations for an answer". Ask for it by name, or say "hook", to have it listed. A block or template that covers the whole task keeps its place in the six-item answer.
At a tier, suggest_components no longer answers with an item found by one incidental word when the rest of the task is what a higher tier's items do, and a no-item answer names the higher tier's items. Where Candor has nothing for the task at any tier ("no rich-text editor"), a higher tier's items are called related, not "Candor has this in Pro".
search_docs finds items by the words people use for them ("modal", "login", "404", "onboarding", "signup"), from the same @keywords tags. A keyword is used only for a word no item says itself, so other searches rank as before. PermissionPrompt's description says what it is for, so searches for approving a tool call find it.
The new items have search tags, and the evaluation set has a task for each (forty in all).
New pattern: "Let an agent propose an automation" (/patterns/agent-proposed-automation): one rules function used as validate in the editor and on the server, and a save route that recomputes the hash.
Screens: a new Environment promotion screen; Human handoff gains a layout for escalating outside the app; Sign-in and first run names IntegrationConnect; Extraction review's queue adds DocumentProgressQueue, AssigneePicker and useKeyboardReview.
An indented code sample in a doc comment shows as a code block. Examples that play a sound pass when.

Theme builder

Colour-vision views: the View control adds protanopia, deuteranopia, tritanopia and achromatopsia, each labelled as a simulation, its strip saying what it models and what it can't show. The achromatopsia view shows lightness as typical sight judges it; with rods alone, reds look darker and blue-greens lighter.
Compare, beside View, puts a second copy of the canvas next to your theme: Candor's default, your theme in another mode, or another brand scope. Side by side on a wide canvas, one above the other on a narrow one; they scroll together.
Brand scopes let one candor-brand.css hold more than one brand. Add one in Start → Brand scopes and choose which you're editing in the bar over the canvas; each is checked on its own. A scope's own choices are colour, type, radius and density; motion, sound and component settings are shared. The file writes each scope under [data-brand="<name>"]: put data-brand="<name>" on <html> or any element, and text inside it takes the scope's font, size, tracking, text colour and ground (in the base layer, so a class on that element still wins). Menus, popovers, tooltips and dialogs open in a portal at the end of <body>, so they take a scope only when data-brand is on <html> or <body>; the file, DESIGN.md, the agent brief and the builder say so. data-density on the scope's element, or on a container around it, wins over the scope's density. A scope wins over lines kept as written from an opened file, with data-brand on <html> as on any other element. Every @import is written before every @font-face, so a scope's font from a stylesheet loads beside a base font file.
A component's density is written as [data-slot="…"]:not([data-density], [data-density] *), so data-density on the component, or on <html> or any container around it, wins over it. Files from earlier versions open as before.
Below 672 px the View control has its own row, so its options are no longer cut short.

Tokens and theming

The token manifest lists the new items' data-slot names and AgentScreen's agent-screen-body.

The site

The home page's "New in 2.10" link opens this section.

Registry

The 3.0 list: each item's registry entry carries the changes 3.0 makes to it (meta.breaking): what breaks, where it shows, the migration, and the candor-ui migrate codemod when there is one. Sixteen changes in all, including the removals Candor's deprecation notes already announced (message.thinking, the blocks' and templates' 2.7 shims, useAnsweringApprovals' string key). candor-ui update --to 3.0.0 reads them for the items your project has.
Search tags out of installed files: the files Candor installs no longer contain the @keywords and @job doc tags, which are search metadata for the docs MCP (it still reads them from the source).

@candor-ui/react 2.10.0

The free items' changes above (fill-strings, locale importing it, Locked's className, the orgData development warning in message-content, PermissionPrompt's description) are in this version.
The package no longer ships the @keywords and @job doc tags.

For contributors

npm run release:check runs the shadcn differential after the CLI build (25 to 40 s) and fails if the repo's shadcn is outside the CLI's pin; --quick skips it. RELEASING.md lists it and what --quick skips.
scripts/breaking.json is the 3.0 list (its shape is in its $comment). A test fails when an item's source announces a 3.0 removal with no entry, and the CLI's tests map every entry to a lint rule.
check:compiler's allowed list names its files, so a known skip in a new file fails.
doc-facts fails on a typed item count in the npm READMEs.
npm run agents writes nothing until every check passes.
A kit test fails if a registry, block or template file gives asChild anything but a single JSX element, since shadcn's Base UI rewrite drops it otherwise.

Candor UI 2.9.0

Tue, 10 Nov 2026 00:00:00 GMT

Documents, record changes, code and comments an agent produced, each reviewed in parts before anything applies; the agent's screen while it works. Fifteen items are new: a document viewer and an extraction review, a change set review and a reconcile table, a code listing and a small code editor, a comment thread and presence, a view of a computer-use agent's screen, a graph view, a model picker and connected sources for the composer, and two pieces moved out of code the blocks pasted (use-answering-approvals, format-elapsed). All are Pro except format-elapsed, which is free, so the kit grows from 300 to 315 items: 71 free and 284 in Pro. Premium templates load no database code until a route opens it, take your router, and fill their container. The CLI works out Base UI, Tailwind prefix and right-to-left installs itself. With CLI 0.14.0 and @candor-ui/react 2.9.0. Nothing is removed and no prop is renamed. A few behaviours change for code you already have; each is in "What to do" below and again in its section.

What to do

Premium templates, data routes: changes to a template's data routes now go in handlers.ts. Twelve routes moved their code, unchanged, into a new handlers.ts beside route.ts (approvals inbox: api/requests, api/history, api/rules; agent ops console: api/ops, api/runs, api/settings; support copilot: api/customer, api/desk, api/quality, api/thread; project workspace: api/workspace, api/file). If you changed one of those route.ts files, update's merge will conflict: move your changes into handlers.ts and keep the new route.ts.
Premium templates, your own server code: code of yours that reads a template's store must call openPostgresWhenSet() from the template's db/postgres.ts at the top of the module. With DATABASE_URL set (or setDatabase()), the store now refuses, with a sentence, rather than run on memory. On serverless hosting each route is its own function, so don't rely on a template route having run first. Calling it more than once changes nothing; without DATABASE_URL it opens nothing.
Premium blocks and templates, use-answering-approvals: run npx candor-ui add use-answering-approvals. Ten blocks and three templates import it, and update names it but doesn't install it.
Premium templates, layout: template shells fill their container, not the window; each template's new layout.tsx sets h-dvh. If you render a shell in your own page or layout, give its parent a height. If you already have app/<template>/layout.tsx, update keeps yours and writes the new one beside it as layout.tsx.candor-2.9.0: add the h-dvh wrapper to yours.
Premium templates, setNavigate(): new and optional. If you give it your router, also read the address from the router where the template reads window.location: the ops console's current page, its sign-in check, ?run= and ?prompt=, and the project workspace's ?project=.
The Next.js starter's /api/chat now refuses a POST another site's page sent, as /api/agent does. If you started from the starter, add if (crossSite(request)) return crossSiteRefused() as the first line of your /api/chat POST, importing it from app/_lib/cross-site.ts. The Next.js and TanStack Start agent routes answer 403 to another site's page; if your app is served from more than one origin, list the others in CANDOR_TRUSTED_ORIGINS.
Message's working line says "Working" before anything of a reply arrives, under the new key message.working. If you overrode message.thinking for that line, move your text to message.working; the old override still works until 3.0. Reasoning still says "Thinking".
codeEditor.hint: in CodeEditor, and in InstructionsEditor, which is built on it, Esc, then Shift+Tab now leaves the field backwards, and the hint says so. If you translate codeEditor.hint, update your text.
RunTree with graphView: the root element is always a wrapper, with data-slot="run-tree" and your className, around the switch and the tree, even before the work branches. If your CSS or tests expect the tree itself as the root when graphView is set, point them inside the wrapper. Without graphView the root is the tree, as before.
DataTable now depends on locked: its Previous and Next page buttons are Locked with a reason instead of disabled. When you update it, update names locked if your project doesn't have it; run the add command it gives. If you translate DataTable, add the new firstPage and lastPage strings.
CLI, add without a terminal (a coding agent, CI, a pipe): if a file of yours differs from the one the add would write and --overwrite isn't given, add installs nothing, names the files and exits 1, and add --dry-run says the add would stop and exits 1. A utils.ts from before shadcn 4.23 is such a file, and a file that differs only by trailing spaces now counts as different. Add --overwrite, or run add at a terminal.
candor-tokens.css beside candor.css: candor.css now imports candor-tokens.css instead of carrying its own copy. Keep styles/candor-tokens.css beside candor.css (npx candor-ui add tokens if it's missing; doctor says so). If your CSS imports both files, remove the candor-tokens.css import.
AppLayout: on a narrow frame the panel's sheet now draws its own label and Close in a row above the panel. If your panel has its own close button, pass panelCloses.

Components

New (Pro):

document-viewer shows a document's pages, which your app renders (an image URL, or a canvas or other element per page; Candor bundles no PDF engine), with labelled regions over them in the page's own units. Regions an agent proposed are drawn dashed and named as the agent's. Arrow keys or J and K move between regions, Enter selects, and onRegionSelect reports it. It has zoom and page turning, and a page still drawing or one that couldn't be drawn says so (with Try again through onRetry). Draw only the page on screen by rendering it when onPageChange names it. (KIT-15)
extraction-review puts the fields an agent extracted beside the document, each with its value, its confidence and basis, and where it came from; selecting a field selects its region, and the other way round. Nothing starts accepted. A changed value is marked "Changed by you" with the agent's value kept beside it, and onSubmit gets exactly the fields the person accepted or changed. Pass requireAll to wait for every field. A decision belongs to the value it was made on: if a re-extraction or streamed values change a field the person had accepted or changed, the field is open again, says why, and isn't sent until they decide again. Send review is locked while a review is on its way and after it is sent, until a decision changes. (KIT-15)
change-set-review lets a person review many record edits an agent proposes and keep or drop each one; none starts kept. It filters by kind, pages a large set, works from the keyboard (arrows, and K and D, which come from the strings keepKey and dropKey) and counts what's kept. It shows what can and can't be undone from your app's undo. Apply calls onApply(kept, hash) with exactly the kept edits and their changeHash, so your server applies only what was approved. The hash is named sha256: only when it comes from the default changeHash.
reconcile-table shows rows from two sources side by side: rows that match, rows found in only one source, and rows that conflict, with the differing fields marked and both values shown. Each row offers the resolve actions your app lists, and nothing is resolved for the person; a row reads as resolved once you record it through resolution. A summary says what's left. (KIT-16)
code-listing shows code to read, with line numbers that aren't copied with it, the language named, Copy, and lines that wrap by default (a switch scrolls them sideways instead). It can mark ranges of lines with your reason, and with previous it switches between the code and its changes line by line. (KIT-24)
code-editor is a small code field with line numbers, Tab indenting and your validation message tied to its line. Esc, then Tab or Shift+Tab, leaves the field. It is not a full editor; for autocomplete and linting, follow the code editor pattern to embed CodeMirror or Monaco. (KIT-24)
comment-thread, a discussion anchored to one thing in your app (a plan step, a diff line, a form field, an output), between people and agents. Pass the anchor's kind, id, label and a short quote; when your server finds the thing has changed or gone, pass status and the thread says so. Comments, replies, resolve and reopen with who and when, edit and delete of the viewer's own comments (the confirmation says what stays visible), unread marks, arrow-key navigation, and a screen-reader announcement for a new comment. Every action calls your server and shows as sending until the data you pass back has it. (KIT-19)
presence, who is looking at the same thing now, people and agents, from your presence data: viewing, editing, or idle since a time. A state you don't report shows as unknown, and null says who's here isn't known. Pass updatedAt and presence older than staleAfter is stamped "As of 10:42". Put it in ThreadHeader's actions or CommentThread's presence.
agent-screen, a live view of a computer-use or browser agent's screen, from an image per frame, a video URL or a MediaStream your app passes. It says who has control, with Take over and Hand back. Pause and Stop say what happens to the step in flight in your words (pauseNote, stopNote), or that you haven't said. The agent's current action is shown as text and is the frame's text alternative. Nothing is drawn while connecting. With frameAt, a frame older than staleAfter is stamped "No new frame since 10:42". Recording says what it records before it starts and stays marked while it runs.
graph-layout and graph-view, the layered layout and drawing behind the graph views below, for your own graphs. (KIT-22)
model-picker, a model menu for Composer's tools slot from ModelSettings' ModelOption list, grouped by vendor with cost. A model whose zero-retention terms aren't attested stays listed, says so and can't be picked; nothing is chosen for the person. It stays controlled as locked comes and goes.
composer-sources: useComposerSources(sources, { onSignIn }) puts MCP connections in the @ menu under "Connected sources": connected, needs sign-in (choosing it calls onSignIn), or unavailable with your reason.
use-answering-approvals: useAnsweringApprovals(respond) keeps a permission prompt from being answered twice; when an answer fails to send, the prompt can be answered again and failed gives a sentence to show. Premium blocks and templates use it, and a failed answer is no longer an unhandled rejection.

Chat (free unless marked):

Message: before anything of a streaming reply arrives, the line says "Working" instead of "Thinking", with a neutral icon. The new key is message.working; an override of message.thinking still works until 3.0. Reasoning still says "Thinking".
composer: an @ option can carry a status, be unavailable with a reason (shown, can't be chosen), or call onChoose in place of inserting. Existing mentions are unchanged.
format-elapsed (new, free): formatElapsed now lives in a free lib with no "use client", so server code can call it; importing it from streaming-text still works. useFormat is now optimised by the React Compiler.
Toaster: the toasts that stay slide on the move family's cd-move, so brand motion tokens apply.
mcp-input and sound: their first doc comment is no longer dropped on install.

Work and review (Pro):

Plan and RunTree: with graphView, when steps run side by side, a List / Graph switch shows the same work as a graph laid out from the dependencies the data already has; arrow keys move between steps. The switch is opt-in and the list stays the default, so apps that don't set graphView see no new control. With graphView, RunTree's root is the wrapper from the first render, so collapsed groups and focus are kept when a second agent starts. RunNode gains an optional dependsOn. Plan numbers its steps in the locale's digits. (KIT-22)
Diagram: pass nodes and edges instead of Mermaid source and Candor draws the diagram without loading Mermaid, laid out from the edges. A node with column and row stays where you put it. source is now optional. (KIT-22)
instructions-editor is built on code-editor: it numbers its lines and says which line an unknown variable is on when they share one. Its props are unchanged. The unknown-variable message is read politely with the field instead of as an alert.
artifact-panel previews tables: pass table with CSV or TSV text, or columns and rows. It shows the first 100 rows (set previewRows), says how many more there are (totalRows if you send only the start), and keeps the raw text, showing the same first rows, one toggle away. The Artifact type's description is back. (KIT-24)
selection-actions: with onRewrite, the toolbar offers your rewrites (improve, shorten, tone) and, with describeEdit, a box for the person's own words. The result shows as a read-only ProseDiff, labelled AI-generated, with Keep and Discard of equal weight; nothing is replaced until Keep (onKeep gets the original, the revision, what was asked and the selection's Range). Discard aborts a rewrite on its way. Closing the rewrite panel gives focus back.
ApprovalRequest, RunLog and FailureClusters take headingLevel (2 to 6, default 3, as before).
Focus: AgentScreen, ReconcileTable and SelectionActions keep keyboard focus when a pressed control is replaced. AgentScreen's Resume icon isn't mirrored in right-to-left.
CommentThread: an @ option that carries an entity types its label like any other.

Data and lists (Pro):

data-table column resizing with resizable: drag a header's edge, or focus it and use the arrow keys (Shift for bigger steps, Home for the narrowest); double-click gives the column its own width back; right-to-left follows the edge. Each column keeps to its minWidth or the table's minColumnWidth (64 px). Pass columnWidths and save what onColumnWidthsChange reports to keep the widths between visits. The resize handle has aria-valuemax.
data-table footer aggregates. A column's aggregate (count, sum, average, min, max) adds a footer row formatted through LocaleProvider (aggregateFormat takes Intl.NumberFormat options). Each cell says which rows it covers: in memory, every row matching the search and filters; in server mode, "this page" unless your server sends aggregateTotals. A page's sum is never shown as the total. Blanks are counted and said.
data-table pinned columns: pin: "start" | "end" keeps a column in view while the table scrolls sideways, in right-to-left too.
data-table columns an agent fills, with agent: { by, state, inputs?, onRetry? }: the header names the model or tool and what it reads; each cell waits, shows its value as text with an AI-generated mark, or says "Couldn't fill" with the reason (and Try again with onRetry). Cells still on their way are left out of the footer.
Pagers: ChangeSetReview's, ReconcileTable's and DataTable's Previous and Next page are Locked with a reason instead of disabled (new strings firstPage, lastPage). DataTable now depends on locked.
Charts and SpendBreakdown: pass onRetry and an error state shows Try again, as lists do.
RunLog and SpendBreakdown: a run's cost and the spend total are written in LocaleProvider's locale, as billing amounts are. A cost under a cent is shown, not rounded to $0.00. Whole amounts read without decimals ("$3"), and the total gains no floating-point digits.

Other (Pro):

AppLayout: on a narrow frame the panel's sheet shows the panel's label and Close in a row above the panel, so Close no longer covers the panel's first row. If your panel has its own close button, pass panelCloses.
NumberInput: range checks are your app's; check the number you get from onValueChange. The doc comment now says so.

Blocks and templates (Premium)

Each template's store loads no database code. Postgres is opened by openPostgresWhenSet() in the template's new db/postgres.ts, which every route file calls, and each data route's code is in a handlers.ts beside its route.ts. Installed with DATABASE_URL set, a template uses Postgres as before. If you added a route that reads a template's store, call openPostgresWhenSet() in it: a server with DATABASE_URL set now refuses, with a sentence, rather than keep that route's data in memory. Every template route that loads the store is tested to open the database.
Your router. Each template navigates through one function you can point at your router with setNavigate(). Left alone, it loads the page as before. Each template's sign-in page moves on through the template's go(), so the router covers signing in too; the server foundation's DemoSignIn takes onSignedIn(next) for this. The project workspace's downloads are links.
Shells fill their container instead of the window. A new layout.tsx in each template keeps a standalone install filling the window; inside your own layout, give their container a height.
Approvals answered once. The blocks and templates use useAnsweringApprovals, so a permission prompt can't be answered twice and a failed answer can be sent again; add use-answering-approvals when you update.
Headings: the approvals inbox's request page, the agent ops console's Runs page and the support copilot's Quality page no longer put an extra h2 above ApprovalRequest, RunLog and FailureClusters; they pass headingLevel={2}.
Words through LocaleProvider: the sign-in pages' brand and the run console's and support copilot's prompt notes (new keys under approvalsInbox, agentOpsConsole, supportCopilot, projectWorkspace, runConsole), and three more template words (the ops console gains team under agentOpsConsole).
Support copilot: the customer switch shows the new customer's thread at once.
Project workspace uses AppLayout's panelCloses.

Starters

The Next.js and TanStack Start agent routes refuse requests another site's page sent (403); set CANDOR_TRUSTED_ORIGINS to allow particular sites. The Next.js starter's /api/chat refuses them too: if you started from the starter, add if (crossSite(request)) return crossSiteRefused() as the first line of your /api/chat POST, importing it from app/_lib/cross-site.ts.
The starters' chats ignore a second press of Allow or Deny made before the screen updates.
The starters carry Candor 2.9.0's components.

CLI 0.14.0

Base UI, Tailwind prefix and right-to-left in-process. On a Base UI style, add, update and add --dry-run work out shadcn's asChild → render rewrite themselves, using your project's own typescript, instead of running a shadcn preview per item. With no TypeScript, or only TypeScript 7 (which has no JavaScript API), those items use shadcn's preview as before. Projects with a Tailwind prefix or rtl: true are worked out in-process the same way. tsx: false, cssVariables: false, and aliases through package.json imports or a workspace package still use shadcn's preview; the README says why for each. Checked against real shadcn 4.23 installs of the asChild items into a Base UI project and of every item into right-to-left and Tailwind-prefixed projects: the files are byte-identical.
add without a terminal (a coding agent, CI, a pipe): shadcn can't ask before replacing a file of yours that differs, so it stopped part-way. add now checks first: if a file differs and --overwrite isn't given, it installs nothing, names the files and exits 1, and add --dry-run says the add would stop and exits 1. A utils.ts from before shadcn 4.23 is such a file. Add --overwrite, or run add at a terminal. A file that differs only by trailing spaces now counts as different, because shadcn would ask about it. Without RSC (rsc: false), a file that differs only by its "use client" line counts as the same, and when nothing else differs add runs shadcn with --overwrite, which changes at most that line, so it doesn't stop to ask.
shadcn runs in the CLI's process group, as in 0.13, so a kill to that group (timeout -s KILL, a coding tool's timeout) stops shadcn too.
add --diff and add --view at a version other than the newest no longer point components.json at the snapshot for the run; shadcn's first line names a temporary file. The path after --diff or --view is now passed to shadcn as their value; before, it was taken for an item name.
update: when the new version of an item needs another your project doesn't have, update names it with the add command, even if the old version needed it too (a theme whose candor-tokens.css was never installed).
doctor: a candor.css that imports candor-tokens.css without that file beside it is a fix (npx candor-ui add tokens), and if you moved candor.css, the fix says to move the file beside it. Your CSS importing candor-tokens.css as well as candor.css is a note.
lint knows the new components.

Docs and the docs MCP

suggest_components reads the words people use for an item and the tasks it answers from the item's own doc comment (@keywords, @job), compiled by npm run docs into the docs data, instead of tables in the server. The items new in 2.9 carry tags, and the evaluation set has a task for each new job.
It no longer says Candor has no document or PDF viewer; a PDF or extraction task gets document-viewer and extraction-review. When a block or template answers the task, a hook or helper comes after it, so "an approvals inbox" lists the template again (ask for the hook by name, or say "hook", to have it listed). Tasks about deploys suggest the approvals inbox and the approval-gated change. "next to" in a task no longer matches items that say "next". A confirm-dialog task lists its four items in ranking order, and signup and 404 tasks no longer suggest account-state.
New patterns: "Document review" (render a PDF's pages with pdf.js in your app, review the extracted values beside them, and hash what was accepted with changeHash, checking the hash on your server); "Apply only the record edits a person kept" (/patterns/apply-reviewed-change-set: send the kept ids and the hash, rebuild the edits from the server's own copy, recompute the hash, check for drift, apply all or nothing); "Comments on agent work" (anchor threads to a run, plan or diff, decide on the server whether the thing has changed, and what is left to your app); "Show a computer-use or browser agent's screen".
New screen, "Extraction review", with three layouts: fields beside the page, a queue of documents, and in the conversation. Screens list the other new items where they fit.
Patterns updated: PDF rendering points at document-viewer; the code editor pattern starts from code-editor and names code-listing; the offline pattern uses PageState's offline kind.

Tokens and theming

candor.css imports candor-tokens.css, the file every item installs, instead of carrying its own copy; the resolved CSS is unchanged. Keep styles/candor-tokens.css beside candor.css. If your CSS imports both files, remove the candor-tokens.css import.
The token manifest lists the new items' data-slot names.

The site

The template demos work in browsers without the Navigation API, and their sign-in keeps the demo's data in every browser. The site build no longer needs a plugin to leave out the templates' database code.
The home page's "New in 2.9" link opens this section. The Accessibility page says what was checked for 2.9 (the browser suites; the 400% pass was 2.8's) and that copy fields wrap unless given truncate.
Roadmap: the Later column keeps "A shared task board"; the computer-use view shipped as agent-screen.

Registry

Each item's description comes from the item's own doc comment. Before, the first /** comment in the file was taken, so some items were described by a field's or helper's words.

@candor-ui/react 2.9.0

The free items' changes above (Message's working line, composer's option states, format-elapsed, Toaster, mcp-input and sound) are in this version. formatElapsed comes from format-elapsed, and importing it from streaming-text still works.
Both stylesheets are built with candor.css's imports inlined; the CSS is the same.

For contributors

Search tags: @keywords and @job in an item's doc comment feed the docs MCP; if you add or rename an item, tag it there. The tags are documented in scripts/build-docs.mjs's header.
One contrast implementation, packages/cli/src/contrast.ts (ARCH-12).
packages/cli/scripts/shadcn-differential.mjs compares the CLI's rewrites with shadcn's own on every registry code file in six project shapes; the weekly shadcn canary runs it against shadcn@latest. The canary workflow's token only reads the repository.
blobToken() treats [SENSITIVE] as no token for every caller.
Tests cover the registry function's Blob wiring and the docs MCP's caching.

Candor UI 2.8.0

Mon, 09 Nov 2026 00:00:00 GMT

The work under the kit: Candor's tokens published as data, docs kept for every release, a CLI that works out shadcn's files itself, @candor-ui/react as the trial path, a site where each page downloads only its own code, and the four Premium templates running on the site with sample data. Blocks and templates keep server errors on the server and refuse requests another site's page sent. Forms, admin and list components get the fixes from the 2.7 review. One item is new, candor-provider (Pro), so the kit grows from 299 to 300 items: 70 free, 269 Pro. With CLI 0.13.0 and @candor-ui/react 2.8.0. Nothing is removed and no prop is renamed. A few behaviours change for code you already have; each is in "What to do" below and again in its section.

What to do

NumberInput is now a text field with the spin button role. If you read the native field's valueAsNumber, or its min, max or step attributes from the DOM, read onValueChange instead.
ScheduleEditor: if you overrode the ruleWeekday string, add {days} to your text.
CopyField now wraps a long value instead of cutting it off. For the old one-line look, set truncate.
CLI: add --dry-run exits 1 where the add itself would stop. A script that relied on the dry run always exiting 0 should check its message. doctor exits 1 when @candor-ui/react is installed beside Pro or Premium items, or with a licence key set.
Premium blocks and templates: run npx candor-ui update for your blocks, templates and the server foundation. Block files now ship as components and libs, so the update shows changes in every block file. Routes that change something now answer 403 to a request another site's page sent, from another origin or a sibling subdomain, unless it's listed in CANDOR_TRUSTED_ORIGINS; if your app is served from more than one origin, list the others there. Errors that aren't a Refusal show a fixed sentence with a 500. If you call demoSessionRoutes()'s DELETE yourself, pass it the request.
Routes that changed something on GET now need a POST. human-handoff's inbox with ?visit=1 only reads; mark it seen with POST { action: "seen", at }. approve-from-anywhere's run page no longer resumes runs on GET; send POST { action: "carry-on" }. If you call these routes yourself, send the POST.
A block installed in a project whose tsconfig alias isn't @ (for example ~/*) didn't build. Run npx candor-ui add <block> --overwrite to install it again with your aliases.
Diagram: if you added it before, run npm install mermaid.
components.json without a "lib" alias: add one under aliases, pointing at the folder of your utils alias ("lib": "@/lib"). candor-ui init adds it when tsconfig.json's paths confirm the folder, and doctor says when it's missing.
A nested TooltipProvider now takes the outer one's timing for any setting it leaves out. If you nest one to reset the delay, pass delayDuration={0}.
audit-data-controls: a prepared export downloads only for a signed-in owner, and exporting from the page or through the agent is owner-only too. With Postgres, run the new migration 0001_exports_random_id.sql. If your own AuditDataRepo assigns export ids, make them unguessable (newExportId()).
Signed-out requests to block routes get 401, not 400. Every block route checks who is signed in before it reads the request.
plan-build-review, run-console, agent-ops-console: a write that lost a race answers 409 with a sentence saying to try again, not a 500. If you catch Refusal around these stores, these conflicts now reach your handler.

Components

New:

candor-provider (Pro): wraps an app in Candor's locale, terms, entity kinds, agent roles, cards and tooltip timing from one config object. The config is plain data, so a root layout or a coding agent can write it, and every field is optional; a field left out keeps its default or what an outer provider set. Kinds, roles and cards with their own icons or renderers go in as the kinds, roles and cards props. Install it with npx candor-ui add candor-provider, then replace the nested providers at your app's root with <CandorProvider config={…}>. It isn't in @candor-ui/react. ChartSizeProvider isn't included; nest it yourself. It always renders its six providers, so your app stays mounted when the config gains or loses a setting (a locale or tooltip preference that loads after the first render), and a setting you leave out passes through what an outer provider set.

Chat (free unless marked):

How long the agent thought. The AG-UI adapter's replies carry thoughtFor, shown by Reasoning as "Reasoning · 4s", measured from the agent's own REASONING_START and REASONING_END timestamps and formatted in your LocaleProvider's locale. An agent that sends no timestamps shows no time. fromAgUiEvents takes formatDuration if you format it yourself; without it, the time reads as formatElapsed does ("0.4s", "1.6s", "42s", "2m 5s"), always rounded down. The AI SDK and Claude Agent SDK adapters don't set it, because neither protocol says when reasoning started.
The working line counts. ShimmerLabel and Reasoning take startedAt (when the request went out), and the working line then counts the time since, live: "Thinking · 4.2s". A Message can carry startedAt too; until the reply's first words arrive it shows "Thinking", counting up from startedAt when it's given. Without startedAt nothing counts. The live count is hidden from screen readers, so Reasoning's button stays "Thinking" while the count runs instead of changing its name ten times a second. streaming-text is now a client component and exports formatElapsed.
PermissionPrompt takes headingLevel (2 to 6, default 3).
CopyField shows its whole value, wrapping long commands, keys and URLs, so it can be read on a phone or at 400% zoom. For the old one-line look, set truncate: the value still reads in full to screen readers and on focus.
Message and SourceList (Pro): source chips wrap long labels instead of cutting them off. Source popovers have a name.
LocaleProvider: format.date(value, style, { timeZone }) shows a time in the given IANA zone instead of the provider's, for a time that belongs to a place. With a locale set it renders the final text on the server. A zone the browser doesn't know shows the ISO form in UTC instead of throwing. { weekday: true } puts the short day name in front ("Tue, 10 Nov 2026, 9:00").
RelativeTime and the working line's timer: a time mounted between ticks, or after the clock went back, shows the current time.
TooltipProvider takes an outer TooltipProvider's timing for any setting it leaves out, instead of resetting to tooltips that open at once. If you nest one to reset the delay, pass delayDuration={0}.
CardRegistryProvider's cards is optional; left out, the cards of a provider above still apply.

Forms (Pro):

Combobox: a choice no longer reads as the placeholder when the current options don't include it. It keeps the label it had when chosen, or is counted ("1 chosen").
NumberInput is now a text field with the spin button role, read and shown in LocaleProvider's locale ("1,5" in German; Arabic-Indic and Persian digits). A form still gets plain digits ("1.5"). A value changed from outside replaces what was typed. With a negative min, phones show the full keyboard, which has a minus. Stepping from empty goes to 0, or the nearest end of the range. An arrow key pressed at the limit says why to screen readers. If you read the native field's valueAsNumber or used min, max or step attributes from the DOM, read onValueChange instead. A form reset clears typed text that isn't a number, and an uncontrolled field goes back to defaultValue.
Field: a group with a function child now renders it. A group's radios and checkboxes are aria-invalid while there's an error, and a required group's legend says "(required)" to screen readers. The error is in a polite live region, so an error that appears or changes as the person works is read out. Errors that arrive with a submit (attempt goes up) are shown and describe their control, but are not put in each field's live region, so a screen reader hears them once, from FormErrorSummary and the focus move. Pass attempt to get this.
PasswordInput: the Caps Lock note is announced when it appears. A shown password is hidden again when its form is submitted, so the browser doesn't save it as text.
OneTimeCode: digits typed in Arabic-Indic or Persian script are kept. The boxes run left to right in right-to-left pages. The highlighted box follows the caret.

Admin and billing (Pro):

ScheduleEditor: a time zone the browser doesn't know no longer breaks the editor; it says the next runs can't be worked out. New weekdays sets the days "Every weekday" means, and the rule names them. If you overrode ruleWeekday, add {days} to your text. nextRuns takes the same days as an optional fifth argument. Without now, the next runs move on as each one passes. The next runs are formatted through the locale formatter in the schedule's own time zone; the text is unchanged. With weekdays={[]}, an "Every weekday" rule reads "No working days are set, so it never runs" (new string scheduleEditor.ruleWeekdayNone).
ApiKeys: a new key's secret is no longer read aloud by screen readers. Focus moves to the "won't be shown again" note, and back to Create key afterwards. An expired key says "expired", checked against the page's clock, so a key that expires while the page is open says so; the server shows "expiry <date>", so hydration matches (new string apiKeys.expiry).
Webhooks: each webhook takes an optional label. Set it for Slack, Discord or any URL that carries a token, and the URL stays off the screen and out of screen readers. URLs without a label now wrap.
ScheduleList, ApiKeys, Webhooks: while a revoke, delete or remove is under way, Keep it is marked unavailable, looks locked and says why. After a delete, focus moves to the list's heading instead of dropping to the page; Keep it returns focus to the row's control.
ScheduleList: an open job menu is named "More for <job>" again.
EnvironmentConnect: with requireTest and no onTest, Connect says no test can run here.
InvoiceHistory: the "Not ready" reason is read by screen readers. BillingDetails: the country error is tied to the country field.
Billing: formatMoney ignores spaces around the currency code, so "eur " shows as €12.50.

Lists, logs and tables (Pro):

onRetry on SessionList, ApprovalQueue, NotificationCenter, RunLog, AuditLog, Inbox, MembersTable, KnowledgeSources, AgentRoster, ReviewQueue, TraceViewer, ResultTable, VersionHistory, EvalScorecard, FailureClusters, InvoiceHistory, DataTable, ApiKeys, DeviceSessions, ScheduleList and Webhooks. Under an error state they show Try again, but only when you pass it, so pass it only when it loads the list again.
Under a partial state, counts of what loaded say they are a lower bound: RunLog's tabs and KnowledgeSources read "12+", Inbox reads "Needs you · 3+", ResultTable "at least 40 rows" and FailureClusters "at least 12 failures". SpendBreakdown's total says some periods aren't known.
NotificationCenter: while loading or failed, the bell shows no unread count and there is no Mark all read. Under partial it reads "2+", named "Notifications, at least 2 unread".
LogStream: with virtualize and live, screen readers hear only lines that arrive, not lines scrolled back into view. An OSC escape sequence with no terminator no longer hides the rest of the line.
AuditLog: virtualised, each event tells screen readers its place in the whole list.
TraceViewer: a viewer first drawn while loading opens on the first failure, or the first span, once spans arrive.
DataTable: loading together with an error or empty state shows only the skeleton rows, not both.
KnowledgeSources: Escape closes the remove confirmation and keeps the source, without also closing a Dialog or Sheet the list sits in. After Remove, focus moves to the Sources heading.

Other:

ReportReply (Pro): until a reason is chosen, Report stays focusable and says "Choose what's wrong first." instead of being disabled; override it under reportReply.needsReason. While a report sends, Report is aria-disabled and aria-busy instead of disabled, so focus stays in the popover, and a second press sends nothing. A failed send leaves the form open and says the report wasn't sent. Its popover has a name.
email-layout (Pro): renderEmail no longer uses react-dom/server, so it runs in Next.js route handlers, server actions and server components, and a client page can import EmailPreview. The output is the same document as before. This lets the approve-from-anywhere block build in a new Next.js app.
SelectionActions (Pro): while an input or text area has focus, the toolbar doesn't appear.
Diagram (Pro) now declares mermaid as a dependency. Diagram loads it on first use, and the install used to leave it out. If you added Diagram before, run npm install mermaid.
Install: the header comments of the chat, know, highlight, mcp-input and sound libs (free) and the work, ops, team and change-hash libs (Pro) now survive shadcn add, which drops anything before a file's first line of code.

Blocks and templates (Premium)

Server errors stay on the server. The browser gets a plain sentence with an eight-character reference, and the server log has the error under the same reference. A rule's refusal is still shown as written. The server foundation has errorText(), errorResponse() and guardTools() for your own routes; wrap a Claude Agent SDK tool server as createSdkMcpServer(guardTools({ name, tools })). Server faults answer 500 (some routes used 404 or 409 for every error); a missing thread, reply, article or version answers 404, and someone who isn't an admin or owner gets 403.
AI SDK tools no longer pass a server error's words to the model. A tool that throws gives the model and the browser a fixed sentence with a reference, and the detail goes to the server log; a rule's refusal is still said as written. Wrap your own tools as streamText({ tools: guardToolSet({ … }) }).
Requests another site's page sent are refused. Every route that changes something asks crossSite(request) first and answers 403, which stops a page elsewhere acting as a signed-in person through their cookies. If your app is served from more than one origin, list the others in CANDOR_TRUSTED_ORIGINS. It doesn't protect against cross-site scripting, callers outside a browser, or a route that changes something on GET. demoSessionRoutes()'s DELETE now takes the request. CANDOR_TRUSTED_ORIGINS entries are compared as origins (case, a default port, a trailing slash or a path no longer stop a match); an entry that isn't a URL is left out, and the log says so once.
Signed out gets 401, not 400. Every block route checks who is signed in before it reads the request. The work, spend and runs routes of plan-build-review, cost-guard and run-console, and plan-build-review's AI SDK agent route, now answer 401 when nobody is signed in.
audit-data-controls: a prepared export downloads only for a signed-in owner (401 signed out, 403 otherwise). Exporting from the page or through the agent is owner-only too; a member sees the control locked with the reason. New exports get random ids (EXP- and 24 hex digits); existing EXP-001 ids keep working. With Postgres, run the new migration 0001_exports_random_id.sql. If your own AuditDataRepo assigns ids, make them unguessable (newExportId()).
Races: in plan-build-review, run-console and agent-ops-console, a write that lost a race answers 409 with a sentence saying to try again, not a 500. If you catch Refusal around these stores, these conflicts now reach your handler.
Routes no longer change anything on GET. Another site can make a browser send a GET with a plain link or an image, which crossSite() can't stop. human-handoff: loading the inbox with ?visit=1 only reads what changed since your last visit; the page marks it seen with POST { action: "seen", at }, and the store has sinceLastVisit() and markSeen() (visit() still does both). approve-from-anywhere: the run page's GET no longer resumes runs owed a decision; the page sends POST { action: "carry-on" } first, which needs someone signed in. If you call these routes yourself, send the POST. Reading an approval no longer records its expiry: an overdue approval reads as expired, and the expiry is recorded by the next decision or by the run page's carry-on POST.
Projects whose alias isn't @. Blocks and templates now install and build in a project whose tsconfig alias isn't @ (for example ~/*). Before, their own files kept @/registry/… and @/blocks/… imports there and the app didn't build. Their code now ships as components and libs, so shadcn writes the imports with your aliases, as it does for the kit; in an @/ project nothing changes. If you installed a block in such a project, run npx candor-ui add <block> --overwrite.
Opening comments survive install. A comment before a block file's first line of code used to be dropped by shadcn; the opening comment of candor-server.ts and of five block files now sits below the first line of code and is kept. Run npx candor-ui update to get them back.
Permission prompts in the blocks and templates wait while your answer is sent, so Allow can't be pressed twice, and use a level-2 heading under the page's h1.
Headings no longer skip a level on the approvals inbox's request page, the agent ops console's Runs page and the support copilot's Quality page.
Project workspace builds in a new Next.js 16 app, where Cache Components is on by default. On a narrow screen the project panel stays closed until you open it; it used to open as a sheet over the thread when the project loaded. In that sheet the Close button no longer covers the last tab.
Server foundation: demoSessionRoutes(people, { allowed }) lets your app decide whether the demo sign-in answers, instead of the route reading process.env on each request. Left out, nothing changes.

CLI 0.13.0

add, update and add --dry-run no longer run a shadcn preview per item and read its printed output. They work out shadcn's files themselves from the registry JSON, components.json and tsconfig paths, so a large add records its lockfile at once. A block whose own files import through @/ is now recorded in candor-lock.json; before, it was left unrecorded. add --path is recorded where the files went. Projects with tsx: false, a Tailwind prefix, cssVariables: false, rtl, aliases through package.json imports or a workspace package, or an asChild item on a Base UI style still use shadcn's preview, as before.
add --dry-run lists each file the install would write (create, same, differs, replace), no longer runs shadcn, and no longer rewrites components.json for a dry run at another version. It exits 1 where the add itself would stop, and says so, and it lists the whole install. Scripts that relied on the dry run always exiting 0 should check its message.
theme check checks token names and data-slot selectors. It reads the token manifest of the kit candor-lock.json records (the current one, and says so, for a release before 2.8.0). It warns, with file and line, on a --cd-* name the kit doesn't read (with the nearest name it does, or the shadcn name for a colour), a value outside a token's range, an internal --cd-* name a brand file shouldn't set, and a [data-slot] selector no component renders. Warnings don't change the exit code. --json adds tokens.
doctor and @candor-ui/react. With the package installed beside Pro or Premium items, or with a licence key set, doctor reports a fix and exits 1, listing every import of the package by file and line with the items to add and the import each becomes. Beside free copies only, it stays a note. It notes the package's stylesheet imported beside candor.css, and both of the package's stylesheets at once.
add --dry-run --path <file> lists the file shadcn actually writes there. shadcn installs an item's dependencies first, so a --path naming a file receives a dependency's file; the CLI follows shadcn's order, so the dry run and the lockfile match what was written. To put a particular file somewhere, give --path a folder.
The lib alias. init adds a lib alias to a components.json that has none, when tsconfig confirms the folder, so shadcn writes Candor's imports of lib files correctly; the README and --help say so. doctor names a missing one. The dry run names shadcn's lib/utils.ts as shadcn's own file.
candor-ui info <item> shows the page for the version you have, and says so when that version has no page.
candor-ui lint counts an import of CandorProvider as Candor in use.
An interrupted add or init also stops processes shadcn starts after the signal (macOS and Linux). With an unreadable candor-lock.json, mcp and init --mcp say why the MCP URL has no ?kit= version, and doctor says the entries' version can't be checked. On Windows, every argument passed to shadcn is quoted where cmd.exe needs it. theme watch sees a file saved while a check is running.

Docs and the docs MCP

Give this to your agent. Get started has a prompt to copy to your coding agent for adopting Candor into an app you already have. It asks about your stack and your agent's API before it writes code, installs with the CLI, leaves the licence key to you, and wraps the app in LocaleProvider, TermsProvider, EntityKindsProvider and AgentRolesProvider. It is also in llms.txt and at /adopt.md, and the docs MCP's get_started returns it with { "prompt": true }.
Versioned docs. Every release's docs are kept as published: /r/v/<version>/docs/<name>.md, plus the patterns, screens, Get started and llms.txt at the same paths under /r/v/<version>/. Pages go back to 1.3.0; 1.0.0 to 1.2.1 published only llms.txt. Each docs page lists the releases that have it. /docs/versions.json says which releases kept what.
version on the MCP's page tools. get_component_docs, get_brief, get_pattern, get_screen, get_started, get_design and get_review_checklist take version, and default to the version in the server's URL (?kit=, which npx candor-ui mcp writes from candor-lock.json). Run npx candor-ui mcp again after update so the URL follows the lockfile. A release without the page answers with the current page and a note saying so.
theme_check also checks token names and data-slot selectors against the kit's token manifest, as candor-ui theme check does. The warnings don't fail the check. The summary has the token lines, and the JSON gains tokens.
suggest_components reads "login page" as sign-in and "modal" or "pop-up" as a dialog. A word no item uses is taken as your app's own noun rather than counting against the task. "sign in" gives Sign in alone; "error page 404" gives PageState; "settings modal" starts with SettingsLayout; a credit card form no longer lists every card component.
The sign-in screen's brief names SessionExpiredDialog. A docs page's "Terms used here" links the glossary once and doesn't list the page's own term. The docs say how to add a "lib" alias to components.json.

Tokens and theming

The token manifest. Candor's tokens are published as data at /r/tokens-manifest.json, and from 2.8.0 at /r/v/<version>/tokens-manifest.json for each release: every token's name, layer, type, range, default per mode and density, the data-slot names the components render, and the --cd-* names that are internal. No licence key is needed. A release from before 2.8.0 answers 404 with a sentence saying they start at 2.8.0. Tools and agents that check a brand file can read it instead of guessing. Nothing changes in your CSS. --cd-toast-offset, which Toaster reads, is in it.
Theme builder: below 768 px, a panel or a component's settings opens as a sheet along the bottom with the canvas visible above it, so an edit shows as you make it. Drag its grip between a low peek and about half the screen, press it to switch between the two, or use the arrow keys, Home and End. The height is kept in your browser.
Theme builder: a View control beside the canvas tabs shows your theme as forced colours (Windows contrast themes) would draw it, in a dark or a light scheme. It is labelled as a simulation and lists where it differs from the real mode. With your browser already in forced colours, the canvas shows the real thing and the control says so.
Theme builder: /theme-builder downloads about half the script it did (566 → 354 KB gzipped). It reads the kit's tokens from the token manifest.

The site

Each page downloads only its own code. The licence and other legal pages load about 234 KB of compressed script instead of about 1.4 MB, and no page fetches the rest of the site while you read it. /docs, /patterns and /screens load about 170 to 220 KB instead of 410 to 505 KB: they read a small list of items and tiers, and only an item's own docs page loads the full catalogue. A link's page is fetched when you point at it, focus it or touch it. A page still loading says so, and one that can't be downloaded says so and offers a reload. A page whose CSS fails to load says "This page didn't load" and offers a reload, instead of going blank.
Try each Premium template before you buy. The approvals inbox, agent ops console, support copilot and project workspace run on the site with sample data at /approvals-inbox, /agent-ops-console, /support-copilot and /project-workspace, listed at /templates (in the Build menu). Each is the template's own pages and API route files running in your browser on its in-memory store, signing in and out through the template's own session route. A bar says so, and says what a real install adds: the routes on your server, your sign-in, Postgres and the agent with your model key. No agent runs, so each demo's chat is locked and says why. What you change lasts until you reload. The demos set no cookies. A link to a page inside a demo (for example /approvals-inbox/requests/CR-001) opens that page. The Pro and Premium pricing cards link to their demos (/app and /templates). The site doesn't ship the templates' database code.
Checked at 400% zoom and in the accessibility tree, in Chromium: /app's demo bar wraps and its Demo states menu no longer covers the composer; commands in the site's copy fields wrap; docs item names wrap; the header stops following the scroll on short screens; numbered headings, Get started's steps among them, read as "01: …"; the home page's component list is a single list for screen readers; the header's Build menu says it holds the current page (aria-current="true"). The Accessibility page says what was and wasn't tested: no real screen reader was used.
The home page counts the starters, and says what OrgSmith and Storywrite take from Candor: Methodic makes both, and both use Candor UI's components. Methodic's product is spelled Storywrite.

Registry

A missing or corrupt bundled index answers with a sentence instead of an empty 500. Reads of earlier versions' files from Vercel Blob give up after 10 seconds.

@candor-ui/react 2.8.0

The README says what the package is for: the trial path, the free tier on npm. Pro and Premium install through the CLI, and Pro items can't import from the package. Moving on means copying in the components you import and removing the package; npx candor-ui doctor says when a project has both.
A stylesheet without a font: @candor-ui/react/styles-no-font.css, the same theme and tokens as styles.css without Inter, for apps that bring their own typeface. Import it instead of styles.css and point --cd-font (and --cd-font-display) at your font. styles.css still loads Inter, so nothing changes for current apps.
The free items' changes above (the thinking time, PermissionPrompt's headingLevel, CopyField, source chips, LocaleProvider's time zones, RelativeTime) are in this version. The build fails if styles.css lacks Inter, if a font reaches styles-no-font.css, or if package.json's exports don't match the entries it builds.

For contributors

Tests mirror the source: tests/items/<group>/<name> for each registry item, and tests/blocks, tests/templates, tests/scripts, tests/api, tests/site, tests/repo and tests/kit for the rest. To find an item's tests, open the file with its name.
npm run test:browser measures the CSS promises in Chromium: control heights per density, motion durations per level and under reduced motion, the contrast of every pairing in light, dark and high contrast, RTL on Breadcrumb, Pagination, Switch and Sheet, and a reflow group for CopyField and source chips at 320 px. It also runs the hosted demos' suite, which npm test no longer does. CI runs it as its own job, and release:check runs it.
candor.css is generated by npm run theme from src/styles/partials/, its token values from src/styles/tokens.json. Edit those and run npm run theme, never candor.css. Its header says rows step 8 px per density. CI checks that every file npm run theme writes is current, candor.css and the tokens manifest included; a version bump leaves the manifest stale until npm run theme runs (RELEASING step 5). npm run registry stops when the token manifest is for another version.
The check scripts (check:neutral, check:client, check:exact, check:motion, check:slots, check:density, check:layers) read one TypeScript parse of each source, cached in node_modules/.cache/candor, instead of regular expressions. The findings on the tree are the same. They no longer count words in comments, prose or code samples as code. They now catch side-effect imports, export * as and import() in the layer check; window?. and functions passed as props in the client check; and classes inside a template's ${…} and .animate?.() in the motion check. check:neutral gives the line of each product word and says where it sits. CANDOR_AST_CACHE=0 runs without the cache.
The registry build reads each item's dependencies from the parsed source, so side-effect imports, export * as and import() are declared, and it refuses export … from "@/…", import("@/…") and import x = require("@/…").
npm run docs also writes src/docs/item-index.json and src/site/theme-builder/catalogue.json; commit them with api.json. CI and the release check fail when either is stale. src/site/stats.json gains starters, and the README's starter count is checked against it.
Release check and CI: npm run release:check fails if any file under snapshots/ is untracked, and checks candor.css and the tokens manifest. CI's agents check also covers snapshots/, and its workflow token is read-only. The overflow check measures /templates and each demo's base. snapshot-registry.mjs --ref refuses a release already in the store.
The fresh-app check installs and builds all 50 primitives on Base UI, not two, and builds a Premium block in a ~/* project and in one without lib/hooks aliases. The release check builds every block and template, both SDK variants, in a new ~/* Next.js app (fresh-app.mjs --all-premium) and checks the lockfile records everything installed.
npm run registry writes src/docs/api.json before the snapshot takes its API record from it, so one run leaves snapshots/r/<version>/api.json current.
Snapshots: a new workflow uploads the snapshot files to Vercel Blob on every push to main that changes snapshots/. It needs the repository secret BLOB_READ_WRITE_TOKEN and fails, saying so, without it; the upload from the release branch before merging stays. scripts/snapshot-upload.mjs treats a BLOB_READ_WRITE_TOKEN of [SENSITIVE] as no token, says so and points at DEPLOY.md. The upload workflow gives the Blob token only to the steps that use it and runs npm ci without install scripts.
Workflows pin their actions to commit SHAs: CI, the snapshot upload, the shadcn canary (whose header now describes what the CLI does since 0.13) and the public repository's starters workflow, which also pins wait-on to 8.0.5.
Starters: sync-starter.mjs --check also fails when a Candor file copied into a starter was edited by hand, and names the file.
The check scripts run when started through a symlinked folder.

Candor UI 2.7.0

Mon, 09 Nov 2026 00:00:00 GMT

The product around the agent: forms, lists and tables that carry their own states, a screen catalogue from sign-in to billing, blocks that share one server seam, a registry store built to hold many more releases, and the components an AI-first app reaches for early (a copilot panel, inline suggestions, schedules, keys and webhooks). The kit grows from 280 to 299 items: 70 free, 268 Pro. With CLI 0.12.0 and @candor-ui/react 2.7.0. Nothing is removed and no prop is renamed. A few behaviours do change for code you already have, and each is named, with what to do, under "Behaviour that changes" in Components and in Blocks and templates. The deprecations (the blocks' viewerOf, contextOf and connect…Db) are under Blocks and templates.

Components

New items (all Pro unless marked):

Forms. field wraps one control with its label, hint, error and required mark; pass the form's submit count as attempt and, after a failed submit, focus moves to the first field with an error. group renders a fieldset for radios and checkboxes. form-error-summary lists a form's problems at its top, each a link to its field. number-input (step buttons that lock at the range and say why, a unit read with the field), time-input ("HH:MM" with its zone), password-input (Show or Hide, and a Caps Lock note) and one-time-code (a row of boxes over one field, so autofill and paste work).
Filtering. date-range-picker offers rolling windows (each printed as its exact window) and a Custom window on two calendars, with useDateRangeText to word a window in the locale. filter-bar builds filters from a field, a condition and a value and hands the app FilterRule[]; useFilterChips gives the same chips elsewhere.
Chat and work. copilot-panel is an embeddable copilot for an existing product: a launcher with the app's unread count opens a panel that slides in on a wide screen and fills a narrow one, names the agent, says it is an AI system and shows guest or signed in. inline-suggestion shows an agent's proposed value beside an Input, Textarea or Select, labelled AI-generated, with Accept, Edit and Reject; the field keeps its own value until the person accepts.
Agents and team. stop-all is a workspace-wide "Pause every agent": it says how many runs are in flight (or that the app hasn't said), asks what happens to them with nothing chosen, and says what can and can't be undone. step-up-dialog checks it is the person again before a sensitive step, by passkey, a fresh SSO sign-in or a code, each shown only when the app provides it.
Admin. schedule-editor creates or edits a recurring job in words, with its time zone and the next five runs (worked out in the browser, and labelled so); a time the clocks skip is flagged, not moved. api-keys lists keys, their scopes, last use and expiry, shows a new secret once, and says what breaks when a key is revoked. webhooks lists endpoints, events and recent deliveries; a test send shows its result, adding needs an https address, and removing says what stops. environment-connect connects an environment by OAuth or credentials with a connection test; requireTest keeps Connect locked until a test with the current values has passed, and a saved secret is never shown back.
Billing. invoice-history lists invoices in their own currency with status and a download link your app serves. billing-details is the form for the billing email, name, tax ID (named by the app: "VAT number", "GSTIN") and address; it has no card field.
Foundation. tokens (free) and server (Premium): see Theme and foundation, and Blocks and templates.

Changes to existing items (optional props and widened types; existing code keeps working):

A state prop on eighteen lists (SessionList, ApprovalQueue, NotificationCenter, RunLog, AuditLog, Inbox, MembersTable, KnowledgeSources, ScheduleList, AgentRoster, ReviewQueue, TraceViewer, ResultTable, VersionHistory, EvalScorecard, FailureClusters, DeviceSessions, and SpendBreakdown, which hands it to its chart), shaped like ChartState. Loading draws PageSkeleton, empty and error draw PageState in the component's own words with the reason underneath, and partial shows the rows under its note. Counts not yet known are not shown. ListState (lib/data) and ListStateView (page-state) are the shared shape and renderer, and PageStateKind gains offline. Each list's docs example switches between its states.
DataTable server mode. With onQueryChange, rows is the page the server sent and search, sort and page changes come back as one DataTableQuery; total gives "Showing 11–20 of 248", page controls the page, and state takes the shared list state. virtualize shows thousands of in-memory rows in one scrolling body, numbered with aria-rowcount and aria-rowindex. Without the new props the table works as before.
LogStream and AuditLog: a search field (LogStream's is on by default; searchable turns it off) that never hides that lines are missing; virtualize; and in LogStream, ANSI colour and style codes drawn as text styles on the theme's colours. Every other escape sequence is dropped and nothing is ever HTML.
Bulk selection and export: ApprovalQueue and Inbox take selectable, selected, onSelectedChange and actions; nothing starts selected, and approving stays one exact change at a time. DataTable, AuditLog, RunLog and SpendBreakdown take onExport; the app writes the file.
KnowledgeSources takes onRemove (asks first, names the source, says it can't be undone here) and onCadenceChange. AgentRoster takes onToggle and onCreate. MemoryManager gains search, filters and onDeleteMany, with a confirmation that says how many memories and who taught them. ScheduleList gains onEdit, onRunNow and onDelete in a per-job menu; delete says what stops.
Combobox gains multiple (values, defaultValues, onValuesChange) and takes aria-describedby, aria-invalid and aria-required. Single mode is unchanged. In multiple mode a chosen option is marked with aria-checked and a "Selected" text, and aria-selected follows the highlight, as in single mode; the listbox is not aria-multiselectable.
ThreadHeader takes people beside working. SelectionActions takes source, a ref to the app's own content, and actions. MessageActions (free) takes report, a render function given the report's open state; a bad rating opens it, so the reason is asked once. ReportReply gains controlled open and onOpenChange.
SignIn gains optional providers (a "Continue with {name}" button each, through onProvider) and onPasskey; its code field is now OneTimeCode.
Widened types: ThreadHeader's working counts people; PageStateKind gains offline; the three money components share formatMoney (lib/ops), which shows an unknown currency code as the number and the code ("12.5 EURO") instead of throwing RangeError, and no longer rounds a fraction away (4.5 JPY reads "¥4.5").
BarChart's value labels get a halo in the card's colour, so a label never sits unreadable on a grid line; Toast's title and detail take dir="auto", so an identifier in a right-to-left page isn't scrambled; KpiRow lays out by its own width (a container query) instead of the window's; NotificationCenter's popover is named.
Selected states survive forced colours: see Theme and foundation.

Behaviour that changes (these are not additive; check them when you update):

Search is on by default in LogStream, AuditLog and MemoryManager. A page that used one of them now shows a search field. To keep the old look, pass searchable={false}. MemoryManager also shows scope and origin filters whenever the memories are mixed, and has no prop to turn those off.
LogStream draws ANSI colour and style codes as text styles. "x\u001b[31mred" showed the raw characters before and now shows "x" and "red" in the theme's red. It is still text, never HTML. If your logs held literal escape sequences you wanted to see, they are no longer shown.
formatMoney keeps every decimal it is given. $1.005 no longer rounds to $1.01, and ¥4.5 shows as ¥4.5 where it showed ¥5, so a zero-decimal currency (yen, won) can now show a fraction. Round the amount in your app if you want whole units. An unknown currency code shows as the number and the code ("12.5 EURO") where it threw.
SignIn's code field is now OneTimeCode (six boxes), and sign-in depends on one-time-code. Update with npx candor-ui update sign-in to get the new file and its dependency; a SignIn you edited merges as usual.
PageStateKind gains "offline". A switch over it that returns for every case, or a Record<PageStateKind, …>, no longer type-checks: add a case for "offline".
Smaller DOM changes. ApprovalQueue and Inbox rows gain a wrapper div even without selectable, so a selector such as li > button stops matching (use li button). AgentRoster with no agents renders a div holding the p. ScheduleList's history strip has role="img". DataTable's header wraps Export and Columns in a div. NotificationCenter's popover has an aria-label. The Toaster's text has dir="auto". KpiRow is wrapped in a container-query element, and its breakpoints follow its own width, not the window's.
KpiRow's columns follow its container's width. A window breakpoint class you passed, such as lg:grid-cols-3, no longer overrides them. Use a container variant instead, such as @3xl:grid-cols-3.

Theme and foundation

tokens, a new free item. Before, an item installed with plain shadcn (or shadcn's MCP) used classes such as cd-press, rounded-button and h-(--cd-control-h-sm) that generated nothing, with no error, because only the four gallery themes listed @candor/theme. tokens is styles/candor-tokens.css: Candor's --cd-* variables, @theme mapping, keyframes and motion utilities without its colours or dark variant, so a shadcn project keeps its own. It sets only Candor's --cd-* variables and utilities, and leaves a shadcn project's own radius, colours, sidebar and type scale alone. Every code item and block now depends on it; theme depends on it too and keeps its files. It is free because free items depend on it. candor.css is unchanged and stays the one import a Candor project uses. What to do: on your next add you get one new, unimported file; nothing you import changes.
A content-addressed snapshot store. Every release used to copy every item into snapshots/r/<version>/ (6,299 files, 127 MB over 26 versions), all bundled into the registry function, heading for Vercel's 250 MB limit. Each distinct file is now kept once in snapshots/blobs/<sha256>.json and each version has an index.json mapping item name to hash, type and the tier it was sold in (29 MB in all). A released version's index can't change, so a release stays exactly as sold; the 26 existing versions were migrated and read back byte for byte. The registry function bundles only indexes and manifests; an earlier version's paid file is read from a private Vercel Blob store by hash, with the licence check unchanged and every file checked against its hash. If none can be read the route answers 503 in a sentence. URLs (/r/v/<version>/<name>.json) are unchanged. Nothing to do as a consumer. The owner's steps for the Blob store and BLOB_READ_WRITE_TOKEN are in docs/DEPLOY.md and docs/RELEASING.md.
npm run check:layers keeps src/registry imports flowing down: foundation (lib/, and the locale, terms and locked providers), ui, blocks, domain. It fails on an upward import that isn't in the baseline; one is known (locked imports ui/tooltip). The folders themselves are renamed in 2.8.
Forced colours. Windows high contrast drops backgrounds and shadows, which is how most selected states were drawn. A section at the end of candor.css now marks selected rows, options, tree and command items, the chosen tab or segment, the current page and a pressed toggle or chip with an inset outline in the system's Highlight colour, using only system colour keywords. Checkboxes, radios and switches are drawn the way the system draws them.
A per-version API record, snapshots/r/<version>/api.json, is written from 2.7.0: see the docs MCP below.

Docs and the docs MCP

Six screens join the catalogue, which now has 28: sign-in and first run, account settings, billing and usage, import data, reports and dashboards, document review.
A types section. A component's page, its Markdown and so get_component_docs name the shared types its props take and show them.
A glossary (glossary.md: two-turn rule, blast radius, drift, change hash, calm level, the honesty rules), with a "Terms used here" section on the pages that use the words.
Examples for standard-cards, the Salesforce preset and the seven adapters.
Twenty-one patterns, eight of them new: Forms and validation (a server action with zod, and the same form with react-hook-form; patterns can now carry code), Payments and invoices (card entry goes to the provider's hosted checkout, never to the app or Candor), Sign in with an identity provider, Code editor embedding, PDF rendering, Offline, Task board, and In-app help.
item_changes(item, from, to), the docs MCP's thirteenth tool: props added, removed or retyped, exports and string keys, and files touched between two released versions, then the CHANGELOG entries that name the item. A version before 2.7.0 has no API record, so the start of such a range is said to be unknown and what is known from the first recorded release is labelled as part of it. /r/v/<version>/api.json serves each record publicly (names, types and hashes, no source). With ?kit=<version> on the server's URL, from defaults to your kit version.
suggest_components: a word for a screen's shape (dialog, page, table) counts for less than the word for its job, and a primitive that covers part of a task counts for half, so "approval dialog" finds the approval items and permission-prompt; the "gap" rules fire on a form's fields, a validation error or a map of places and no longer on "validate the change hash"; it no longer says Candor has no form field item; a whitespace-only task is refused as empty and one in another script is called unreadable; list_components' group counts add up to the number it says, and it says the -claude versions are the difference; the Premium install label says not to ask for the key, as the Pro one does. The evaluation set grows from fourteen to twenty tasks with expected answers and runs in CI; "document" finds the artifact panel.
llms.txt's Setup guides line reads its tool list from the guides, and the install command and tool list come from one source across the README, llms-install.md and both npm READMEs.

CLI 0.12.0

candor-ui theme watch [file] runs theme check now and whenever a file it reads changes (the CSS and its imports, candor-brand.css, the installed theme and motion manifest, components.json, candor-lock.json), until Ctrl-C (exit 130). --json prints one report per run. An unreadable components.json (half-written, say) is reported and watching goes on.
add --dry-run shows what --replace-edits would change: per edited file, your edits (<), the old lines (-) and the new (+), and what update would do instead. It writes nothing and exits 0. add --dry-run, --diff and --view are previews: they record nothing and exit 0.
mcp and doctor pass your kit version. With a lockfile, candor-ui mcp <tool> writes the server URL with ?kit=<version>; running it again after the lockfile moves updates that entry only. doctor says when an entry passes another version or none, and the command that fixes it.
Signals. The grace period now stops the whole shadcn tree, not only npx: it signals the processes under npx, waits, and after 10 s kills any still running (taskkill /T and /T /F on Windows). Before, a shadcn that ignored the signal kept writing.
init with a lockfile it can't read no longer stops: it says so, sets up the registry, the CSS import and the font settings, installs nothing, and exits 1 only if the theme still needs installing. The file is left as it is, and doctor reports it with git diff and git checkout.
add lists shared items and packages even with no lockfile (it reads the newest release's items and names the version); init --latest installs a missing font at the recorded theme's version; CANDOR_SHADCN=^4.24.0 keeps its caret on Windows; the CANDOR_SHADCN hint appears only when shadcn printed output the CLI couldn't read and the value can run a shadcn outside the pinned range.
Wording: "a, b (1.0.0) and c, d (2.0.0) to T" replaces "a and b (1.0.0) and c and d (2.0.0) to T", and the Base UI note reads "Candor's button would go where your Base UI components/ui/button.tsx is". The primitive and lint lists name the new items.
New CLI tests cover a real kill on the built CLI (SIGTERM, SIGHUP), the runner's environment, a hoisted @candor-ui/react, and an explicit 401 from a versioned snapshot.

Blocks and templates (Premium)

The server foundation. Every block and template used to carry its own identity stub (14 viewerOf copies) and its own database pool (15 db/connect.ts files), so four blocks opened four pools and replaced the stub four times. The new server item (Premium, so installing it needs a Premium or Team key; lib/candor-server.ts, lib/candor-database.ts) is the one place: getViewer(request) and setViewerSource() for your auth, signedOut() (a 401), database() and setDatabase() (one pool per server process), Refusal with a status, and the agent's runtime settings (agentModel, claudeQueryOptions, approvalSigning()). Each block keeps its own schema, store, repo and migrations.
Behaviour that changes (not additive; what to do is with each): - The demo sign-in is off in production (NODE_ENV=production) unless CANDOR_DEMO_AUTH=1 is set or the app registers its own setViewerSource(). With neither, nobody is signed in and every route answers 401. Before real use, call setViewerSource() with your auth; to keep the demo on a deployed preview, set CANDOR_DEMO_AUTH=1. - A route now answers 401 when the demo cookie is present but empty. In 2.6 an empty cookie meant the demo person (Riley). It now signs the person out. If you relied on an empty cookie to get the demo person, set a real demo value. Refusal carries a status, 409 unless you give one. - A block's db/connect.ts you customised keeps working only if you register your driver with setDatabase(). The shim calls the foundation's pool otherwise, so an edit that opened its own pool is not used until you do.
Deprecated, removed in 3.0: contextOf(request) in audit-data-controls/store.ts and approvals-inbox/store.ts stays synchronous and returns Ctx as in 2.6, reading the demo cookie only. Routes use the new async signedInContext(request), which asks getViewer() and returns Ctx | null (null when nobody is signed in); move your calls to it, await it and check for null. Also viewerOf(request) in each block's store.ts and connect…Db(url) in db/connect.ts. They are back as thin shims so a block you edited still compiles and update doesn't delete them. viewerOf answers as in 2.6 and reads the demo cookie only, not setViewerSource()'s source; connect…Db returns the shared pool for DATABASE_URL and a pool of its own for any other URL. What to do: if you replaced viewerOf with your auth, call setViewerSource() in candor-server.ts instead and move your calls to getViewer; if you edited db/connect.ts, keep your edit or move to database(). update merges both.
The templates sign in through a documented seam: each has a sign-in page (the kit's SignIn through the foundation's DemoSignIn) and a demo session route. The demo says it sends no email and which code to type. A 401 from any route goes to the sign-in page, and Sign out ends the session. To use your own auth, delete the session route and the sign-in page and call setViewerSource(); nothing else changes. The approvals inbox's words are a strings table (approvalsInboxStrings, overridable under approvalsInbox in LocaleProvider), and the shells show a skeleton, not a "Loading…" person, until the server says who is signed in.
PermissionPrompt in the chat views. The 14 chat views (10 blocks, 3 templates and the Next.js starter) use PermissionPrompt in place of a hand-rolled "Waiting for your go-ahead" banner; eval-dashboard uses Select.
meta.framework. Each block records "framework": "next-app" (the App Router) and the build refuses a block without one; it is carried into every block and template item's meta.framework. Nothing reads it yet: the CLI does not yet warn before installing into another framework.

The site

Candor and a free kit (/compare): what AI Elements, assistant-ui and CopilotKit say they ship, read from their own pages on 9 November 2026, each with the address it was read at; it names no winner. Linked from the hero and footer.
What you can check, on the home page: npm weekly downloads read when the site is built (with the day, and left out if npm gave none), the public repository and the release cadence. No customer counts, quotes or logos. Three Honest vs. typical toggles sit under "More than a chat box".
A Build menu in the header holds Examples, Patterns, Screens, Guides and the Theme builder.
A docs Preview shows a skeleton and a status while its example loads; /app has a skip link and its Demo states button sits in a landmark; the Methodic line leads with what Methodic ships on Candor; the accessibility page and the upgrade FAQ read their numbers from stats.json and the prices.
The overflow check sees clipped content, measures the 14 key pages at 320, 360 and 768 px and with the header menu open (444 loads), can fail (--self-test), and runs at a pinned Playwright. Its first run found /docs 18 px too wide at 320 px; fixed.

The theme builder (free tool)

From my brand is first in Start and previewed live: the canvas shows the mapped colours until you Apply, and each colour's role is a choice (Primary, Accent, Greys, Page, Ink, each status or Not used), with "You get" beside it.
Primary sets the theme's primary whichever theme the page shows; a dark-only primary is behind "Override the primary in Dark only". Derive from this primary brings hand-set colours around the primary back into line, as one undoable step. Hex, rgb() and hsl() colours in a hand-edited file are read and converted to oklch().
A line you add by hand survives the next download: a declaration the builder can't set is kept as written and written again under "Kept as written", listed in Download with Remove.
The load report separates "You changed" from "Follows from it". The library lists the open theme first, each with its primary. Check says when Running and Failed are hard to tell apart (OKLab distance below 0.12). The Download summary says Motion and Type in words. Your agent's name and place noun reach Approvals, Dashboards and the Brand sample.
Undo and redo history now survives a reload whatever order the values were set in, and Undo takes down the note that spoke for the step. Chosen options and swatches show in forced colours. Stat cards fit their column on Dashboards, one press in the Toast preview shows one toast, and a tall toast stack no longer clips. A full axe pass runs at 1440 and 390.
Fixed after review: moving Primary to another colour in the brand mapping swaps the two roles instead of dropping a colour; a hand-edited file's primary derives its dark and high-contrast colours, where Candor's blue stayed around it; a hex shown as typed is the hex you gave, not the rounded colour's; after Apply, focus moves to "Change the mapping", not the page body; and the brand sample names the colours set in Components that the theme's roles don't drive.

Build and checks

The release check runs check:layers, doc-facts --check and the overflow script's --self-test; from the dated CHANGELOG section it also runs sync-starter --check (the starters must not be behind the source). It checks the snapshot store and candor-tokens.css with git status, so new files count, and ignores Finder's untracked " 2" copies.
sync-starter writes .candor-sync.json (kept out of the public starters); public-repo, sync-starter and skills-publish skip Finder duplicates; a file sync-starter adds reaches the public starter before it is committed; public-release stops before a second commit. The public README says what is true, and the issue chooser's paid-item link is an https page. A public workflow builds the three starters and runs axe on the Vite starter.
The Blob upload now runs before the release commit (scripts/snapshot-upload.mjs, safe from release/2.7 because blobs are content-addressed and never overwritten), so a paid file of an older version is in the store when 2.7.0 deploys. Before, it ran after the merge and those versions answered 503 until it finished.
Stats count the new tests (4,091); RELEASING.md no longer creates a GitHub release from the private repository.

Candor UI 2.6.2

Mon, 09 Nov 2026 00:00:00 GMT

Fixes from six cold reviews of the kit, the site and the public repository (internal/review-2026-11/): the docs an agent reads carry every prop and type, suggest_components says when Candor has nothing, the site's numbers add up and its pages fit a phone, and the CLI survives a shadcn release. No item is added and no item's API changes in a way that breaks code: unions widen, optional props and one deprecated alias are added. With CLI 0.11.2 and @candor-ui/react 2.6.2.

Components (fixes reach every tier)

Plan ids, model vendors, channel kinds, notice kinds and inbox kinds take values Candor doesn't know ((string & {}) beside the known ones), with a plain label and icon for the unknown value, as AuditLog already did. Before, a plan called "starter" or a model from Mistral failed the type check.
Right to left: ProvenanceTrace draws its connectors across the gutter in RTL; Sheet and Drawer take start and end sides (left and right still work) and AppLayout uses them; TraceViewer places its bars with inset-inline-start.
ImportReview shows every issue in a group on request instead of eight and "and N more"; ReviewQueue says when it has nothing to review instead of rendering nothing, and summarises its progress past fifty items; CheckpointList, MembersTable, ScheduleList, AgentRoster and VersionHistory say when they are empty.
PlanPicker, SubscriptionStatus and DowngradeImpact format money through useFormat in a currency prop (default USD) instead of a hard-coded dollar sign.
card-registry exports RegistryCard; Card stays as a deprecated alias until 3.0, so it no longer collides with ui/card's Card in an app that imports both.
RunNode gains lastHeardAt and hostOffline, so RunTree shows a subagent that has gone quiet or lost its host, the way TaskTray and AgentActivity do.
withRender (lib/render-prop, free) keeps an element's own children when none are passed, and refuses Base UI's function form of render with a message instead of crashing.
DataImport and SourceIngest take an error for a rejected file; DataImport can give a loaded file back.
TestResults filters to failed tests and re-runs one (onRerun); SteerComposer attaches files.
BarChart and LineChart's focusable value rects carry a role, so axe passes on a page that shows them.
MembersTable and Stepper no longer widen a narrow page.
An agent's Message is labelled "Name (Role)", so a screen reader hears "agent" once; AppLayout draws its top row as the app's banner landmark when there is anything in it.
Twelve item descriptions say what the item does instead of carrying an internal code name ("Candor's ReviewCanvas") or restating the name ("A run that stopped.").
Three defaults changed, each for a fix above; an app that relies on the old one should check: Message's default agentLabel string is now "Name (Role)"; the billing items' price strings no longer carry a currency symbol, because the formatter adds it, so an override that includes one should drop it; AppLayout draws its top row as a <header>, so an app that put its own banner outside AppLayout should move it into top or it has two.

Docs and the docs MCP

Exported types and function signatures are shown whole; before, 85 types were cut off partway through.
Button, Badge, Toggle, ToggleGroup and Surface pages list their variant, size, tone and other variant props with values and defaults; exported constants such as standardCards and the preset kinds have their types, so those pages are no longer empty. Component pages show the Motion section the .md pages already had.
Blocks and templates no longer list GET and POST as components or repeat their exports; llms.txt, llms-full.txt, the skill's components.md and the MCP list each one once with its -claude version beside it. llms-full.txt lists the functions, values and types of the adapters and shared helpers. scale is listed under shared helpers.
Each setup guide has a Markdown version at /guides.md and /guides/<tool>.md, linked from the page.
suggest_components lists only items that fit the task; when nothing fits it says "Candor has no item for this" and names the nearest pattern or says the job is left to the app. It takes an optional sdk (ai-sdk, claude, ag-ui) and suggests only that SDK's adapter and block versions; without it, no adapter, and it says which to add. Install commands are split by tier. Coding agents should pass sdk.
The candor-ui skill names all twelve MCP tools and says to call list_screens first for a new screen.

CLI 0.11.2

candor-ui runs a pinned shadcn (shadcn@~4.23.0) instead of shadcn@latest, because add and update read what shadcn prints. CANDOR_SHADCN runs another version, range or tag. A weekly CI job runs the fresh-app check against shadcn@latest.
init installs the theme and Inter the way add installs an item: at the version candor-lock.json records, and recorded in it; init --latest takes the newest release. When the lockfile records the theme, init --overwrite stops and points to npx candor-ui update theme. Before, it installed the newest theme and left the lockfile naming the old one.
On SIGINT, SIGTERM or SIGHUP during add, the CLI passes the signal to shadcn and waits for it to exit before putting components.json back, then exits 128 plus the signal's number. Before, a signal to the CLI alone left shadcn running.
When a release's snapshot can't be read, add says the registry couldn't be reached and names the URL; the "an item added after x.y.z isn't in it" hint appears only on a 404.
With items at several versions, the stop-and-ask reads "move button (2.5.1) and motion, render-prop, status and locale (2.6.0) to 2.4.0".
add prints a line per item, shared item and npm package before shadcn runs and a line per item as it records them; no spinners when the output isn't a terminal. The time an install takes is unchanged: it is shadcn's per-item runs, which a later CLI replaces.
doctor notes when @candor-ui/react is installed beside copied items (the package's providers don't reach the copies). On a Base UI project, doctor and add say that Candor's primitives are Radix and name the project's own files they would go over; add says so before shadcn runs.

The site

Every /screens page, /docs/members-table and /docs/stepper fit a 390 px phone; a check in CI and the release check loads every sitemap page at 390 px and fails on sideways scrolling.
The home page and the pricing cards count by kind, from stats.json: agent components and hooks, restyled primitives, blocks and templates, themes; the cards add up to the headline. The theme builder's component index says what its count leaves out.
A "Skip to content" link on every page; props tables and code blocks that scroll are focusable and named.
"Most popular" is gone from the Pro card; the hero run is labelled an example. Each pricing card states its support terms as the licence has them; Support and Contact are in the footer; the 60-day continuity promise is under the cards; the FAQ says how to upgrade a tier (for the price difference, by email; the key moves; no downgrades), and the licence's section 4 says the same.
One install story everywhere: the candor-ui CLI, which wraps shadcn, with shadcn alone as the fallback.
The docs are ordered the way an app is built (Chat first, templates last), Pro and Premium are marked in the sidebar, the tier filter has three states, and a group card opens its group.
Get started from nothing: a step 0 that creates the app, a short first page without the Thread demo's controls, and the no-key Vite starter ("Try it in a minute, no key"), also in llms.txt. The guides say the components.json block is what init writes.
/app is pre-rendered with its own title and description, its way back goes to /examples, and its notice and top bar sit in landmarks; /gallery redirects to /examples.
On a phone the docs and examples keep their filter, and the docs their tier filter, above the component select.
Short inline code stays on one line and code has no ligatures; the roadmap's "In progress" shows the last release and the one being prepared; the changelog marks releases that changed no package and explains same-day dates; the home preview says how to see a locked control's reason on a phone; <html> no longer starts dark, the head script or the system setting picks the theme.

The theme builder (free tool)

The result line says "checks" and the Download panel has no stray count line; "Ship" is Download, with a download icon; fixes show the hex beside each OKLCH value.
axe passes: chart rects have a role, the title and toolbar sit in a landmark, the canvas has an h2; preset buttons carry the preset's name; the panel-width separator reads in pixels; copies say "Copied the …".
Toasts no longer cover the canvas; the leave prompt no longer fires on a plain reload; an unreadable paste changes nothing and says so; Hide and Show are at the top of the rail; no text is cut short in the settings select or the theme's name at 390 px.
The Button Locked figure shows every variant locked; the default motion level is Off, Subtle or Expressive, or "following Candor's", not a fourth level; Check names the solid focus ring apart from the ring at 80%.

The public repository (MethodicDev/candor)

Each release gets a tag and a GitHub Release with its changelog section (and the releases 1.9.0 to 2.6.1 are filled in). SECURITY.md, SUPPORT.md, CONTRIBUTING.md, issue forms and a pull request template.
The README opens with a permission prompt from the Vite starter, badges, "Try it in a minute, no key" first, how the repository works, the paid tiers with prices, refund window and key commands, "Why Candor" and "Tools", and "What's here" grouped by area with a link per item. It says that @candor-ui/react changes only when a free item does. The About text leads with the difference; two more topics.
The starters record the kit version they were generated from; the Vite starter builds without the chunk warning.

Build and checks

Every build and check script lists directories through scripts/fs-walk.mjs, which skips the "name 2.ext" copies Finder and iCloud leave behind; tsconfig and Vitest exclude them.
The registry build stamps every item's tier (meta.tier) and refuses a free item that depends on a paid one; the licence check and the README check read the stamp.
npm run registry builds the motion manifest itself; CI's stats check keeps the committed test count (stats.mjs --keep-tests), and the release check counts.

Candor UI 2.6.1

Mon, 09 Nov 2026 00:00:00 GMT

CLI 0.11.1, for Storywrite's ask 36: candor-ui add installs at the version your lockfile records, so adding one item no longer moves the items it shares with the rest of your project to a newer release; --latest and --version opt in, and add names anything it would move and asks first. No change to the kit or @candor-ui/react.

CLI 0.11.1

candor-ui add installs at the version candor-lock.json records (the theme's, else the newest installed item's), and so do the shared items the item uses (locale, render-prop, status, motion): for the shadcn run it points the @candor registry entry at that release's snapshot (/r/v/<version>/) and puts components.json back after, on failure and on interrupt too. Before, add always installed the newest release and rewrote shared items to it (Storywrite's ask 36).
New add --latest (the newest release) and add --version <x.y.z> (that release; a version /r/versions.json doesn't list is refused, with the list). A project with no lockfile installs the newest release, as before, and the last line says so.
Before shadcn runs, add names the installed items it would move to another version, and the edits it would overwrite, and stops unless --yes is given ("This would move locale, render-prop and status from 2.1.0 to 2.6.1… npx candor-ui update is the way to move them on purpose. Nothing was installed."). With --yes the same line is a notice. The last line says what was installed and at which version.
Unchanged, on purpose: init still installs theme and the font from the newest release.

Candor UI 2.6.0

Mon, 09 Nov 2026 00:00:00 GMT

Density that reaches controls: heights, paddings and row heights follow data-density, so the theme builder's Density control changes what it says. The builder keeps a library of themes in the browser and its undo history across a reload, and an override never erases a nested surface. The docs MCP gains theme_check, the same checks as the CLI, for a coding agent verifying its own edits. With CLI 0.11.0 (the checker shared with the MCP); @candor-ui/react 2.6.0 carries the free changes.

The theme builder (free tool)

Several themes in this browser: the list beside the theme's name has New theme (Candor's defaults, nothing chosen), Rename, Duplicate, Delete (asks first; can't be undone) and one-press switching. Download, Copy and Share take the open theme. A share link opened beside kept work opens as a new theme instead of replacing yours. The privacy page names every key the builder uses.
Undo and redo survive a reload, with their step names: the last fifty steps each way, kept for the tab.
A component's ground no longer hides the surfaces inside it: the override writes only the component's own ground; the card, bubble, well and popover inside keep their colour, or step from the ground just far enough to stay distinct and readable where their own colour would vanish. Check lists each surface inside a ground against it.
Density says what it sets since 2.6: field heights (32, 36 or 40 px), table heading rows (32, 40 or 48 px) with 4, 8 or 12 px above and below the text of the rows under them, and padding, as well as text and widths; exports carry the control and row tokens. A component's own density is written under :root:not([data-density]), so the person's data-density on <html> still wins over it.
Loading a hand-edited file: an edited primary is the theme's primary, the same as typing it, so its hover, focus ring, accent grounds and the dark and high-contrast primaries follow it; a role the file set itself is kept and the load report names it; the report lists only the values you edited and says once which values follow from them; something the builder can't read changes nothing and says so. Button's block also names a Button inside Locked ([data-slot="locked"] > button[data-slot="tooltip-trigger"][data-variant]), and the brief says so.
A reload never asks "Leave site?": the browser asks only if a change couldn't be kept in this browser; leaving by a site link still asks while the theme hasn't been downloaded, copied or shared. After "Apply this fix" focus moves to the next fix; each panel opens at its top; "Theme canvas" keeps the open panel.
The Chat view's Thread shows the plain thread; the docs page keeps its "600 messages" demo toggle.

Density (free theme; reaches every tier)

data-density="compact" | "spacious" now changes the height, padding and gaps of controls, menu items and table rows, not only text sizes and widths. One height ladder: --cd-control-h-2xs (24 px) to --cd-control-h-lg (40 px), with --cd-control-px-*, --cd-control-py, --cd-control-gap, --cd-area-min-h, --cd-item-*, --cd-row-* and --cd-cell-px, each with compact and spacious values; compact never goes under 24 px, so no target shrinks past WCAG's minimum. Utilities (h-control-sm, px-control, h-row, …) are registered; the components use the h-(--cd-control-h-sm) form so a consumer's h-10 still wins through cn().
Ninety-six components read the tokens, Button, Input, Textarea, Select, Combobox and DatePicker triggers, Toggle, Tabs, Pagination, the four menus, Command, the table primitive, DataTable, SessionList, Inbox, ApprovalQueue and the Composer's buttons among them. At the default density nothing changes (checked class by class against 2.5.1). The Console gallery theme now compacts controls as well as text.
Every density token read carries its default as a fallback (h-(--cd-control-h-sm,2rem)), so an app that updates a component without updating its theme item still draws the default sizes.
npm run check:density fails on a fixed control height or padding class in the registry, or on a token read without its fallback, with a short allowlist of honest fixed sizes (chart frames, drawings, skeletons); it runs in release:check and CI.

The docs MCP and CLI 0.11.0

theme_check in the docs MCP server (read-only, keyless, fetches nothing): send the contents of candor-brand.css (up to 256 KB) and it returns the contrast of every pairing in light, dark and high contrast and every --cd-motion-* and --cd-sound-* value against the current kit's manifest, as a short summary in the CLI's words and as JSON; sound files are reported as not measured because it can't see your public/. A file made for an older kit is checked against the current names, with a note. llms.txt, Get started and the skill say when to call it: after editing the brand file.
candor-ui theme check and the MCP's theme_check run the same code (packages/cli/src/check/); the CLI's output and exit codes are unchanged. Hostile input stays cheap: no suggestion for names over 64 characters or past 200 unknown names, nesting capped at 32 levels with a plain error, findings listed 200 per kind with exact counts.

Candor UI 2.5.1

Mon, 09 Nov 2026 00:00:00 GMT

Fixes from the cold review of the live site: the privacy page says what the theme builder keeps in the browser, the builder is linked from the header, Get started, the brand FAQ and the agent docs, the stale version copy is gone, a code block on the motion page renders, and a dozen small things in the builder and the site. Nothing under src/registry changed, so @candor-ui/react stays at 2.5.0 and the CLI at 0.10.0.

Site

The privacy page says what the theme builder keeps in your browser (the theme and panel width in local storage, the open panel and pasted brand colours in session storage; nothing is sent anywhere; how to clear them) and that light or dark is shared with themethodic.com through a cookie on .themethodic.com; the GDPR and DPA pages no longer say "no cookies".
The site's copy reads the kit's version: the home pill ("New in 2.5"), the Accessibility page and the Roadmap no longer name old releases, and a test fails on any copy older than the kit's minor.
The theme builder is in the header, in Get started as "Make it yours" (the @import lines and theme check), in the brand FAQ, and in llms.txt, the design reference and the theme docs, so a coding agent can find it. /themes points at the builder's checks and npx candor-ui theme check, not a script customers don't have.
Visitors who have chosen no theme get the one their system uses (before, dark); the home announcement pill wraps on a phone.

Docs

Docs pages keep fenced code in descriptions, so the code sample on /docs/motion renders as a code block, and a function's description is no longer repeated under Functions.

Theme builder

The Brand field shows a primary set by hand (and says so, with Remove); the right-to-left and other-theme previews are as wide as Default; the agent name you type reaches every example screen; leaving asks only when there is work not yet downloaded, copied or shared; canvas notes go after six seconds and wait while the pointer is on them; segmented controls no longer run their words together; Sound's fields are named with their event; the page opens with skip links to the toolbar and the canvas; the agent brief says "the CSS file named in components.json".

Candor UI 2.5.0

Sun, 08 Nov 2026 00:00:00 GMT

The theme builder, rebuilt a second time around what people come to do: Start, Colour, Type, Shape, Motion and Sound on a labelled rail, a Components workspace that shows one component with its states and settings side by side, every change visible where it is made, work kept in the browser, one theme switch for the whole page, and a token file beside the CSS. Candor's pages and the builder wear the Methodic site's header. @candor-ui/react 2.5.0 is 2.4.0's code with the new motion sentences in its doc comments.

The theme builder (free tool)

Rebuilt around the site header, whose theme control now themes the whole page, light, dark or high contrast, chrome included. A labelled rail: Start, Colour, Type, Shape, Motion, Sound; then Components, one at a time; then Check and Ship. Panels push the canvas and can be resized; below 768 px the rail is a bottom bar and panels open as sheets. Undo and Redo name their step.
Start offers each preset with four shapes (Candor, Soft, Crisp, Square), "From my brand" (paste hex codes; the primary can be locked so fixes adjust foregrounds and rings instead), Random that says what it chose, and Open a file. The Style panel and its duplicate controls are gone.
Colour edits whichever theme the page shows, with that theme's values in the fields; fixes that keep your primary come first. Type keeps Inter in the list, takes a custom font by name or address and says when it isn't installed here. Shape is radius and density together. Motion names each family in plain words first; "Preview as" lives there and is never exported. Sound plays the starter set; the local-file picker is gone.
Components is a workspace: an index in a curated order (by how often a component is met and how much it shows a theme) with search and filters; one component at a time with its states side by side (loading, error, locked, right to left and the other theme where it has them) and a labelled Replay for each moment; its settings by plain name with swatches. A change you make is applied to the component in front of you at once, as well as to the exported file, so a radius, colour or motion edit is visible within a frame.
The canvas opens on a brand sample (buttons, a link, a focus ring, every status, a chart, a selected row, an input with an error, a locked control) before Chat, Approvals, Run, Dashboards, Patterns and Screens, where templates and full-stack blocks appear as compositions of their own parts. Cards keep name, gear and reset only.
Check groups failures by fix. Ship shows what changed in every section as a diff with counts, downloads the CSS and a design-token file (candor-theme.json, DTCG: every role per theme with its checks, component overrides, motion and sound), and copies the brief for a coding agent, the DESIGN.md addendum, a PR summary (what changed since the loaded file, checks before and after) and your product's words as a provider config. A brand-intent field travels into all of them.
Your work is kept in this browser and in the page's address; a link pasted into an open tab is applied, a bad link says so, and leaving before a download asks first. Opening a hand-edited file keeps your edits and lists what differed from the builder's own line; a file without that line is mapped into the panels.
The brand path holds up: the hex you type is kept exactly, in the CSS comment and in the token file, and an edited hex loads back; a bright primary keeps its hue in dark and says when no dark value can pass; Random names a kept colour that blocks it and offers to replace it; a Google Fonts address loads (one that arrives in a link or a file loads only after a press); Density and Heading weight say what they reach. Density does not change control heights, which the kit's density tokens don't cover yet.
Every bug the cold review of the first build found has a test and is closed; the re-review of this build is internal/design/theme-builder-v2/REVIEW-UX-2.5.md, with its seven named fixes made.

The site

The site header is the Methodic family header on every page (the /app demo keeps its own shell): the tile and name with the page's section beside them, a sliding pill under the current page, a single theme button that still offers system, light, dark and high contrast, the call to action, and a full-width menu below 1024 px. Light and dark are shared with themethodic.com through its cookie, and the page's theme is set before first paint. The footer's family links include Candor UI.

Docs

Every motion moment now has its own sentence, in plain words, saying when it plays and what it never does; they show in each component's Motion section, in the MCP and in the theme builder, and a test keeps it so. An item's description is never one of its @motion tags.
A worktree's dev server serves fonts through its linked node_modules.

Candor UI 2.4.0

Sun, 08 Nov 2026 00:00:00 GMT

The motion layer put to work: the catalogue's behaviours on the components where decisions land, queues move, values change and checks return; sound as a closed set of five events with a CC0 starter set; the motion manifest the docs, the MCP and the CLI read; data-slot on every component root so a brand file can reach each one; candor-ui theme check for motion and sound and theme apply; and the 2.3 review's leftovers. With CLI 0.10.0; @candor-ui/react 2.4.0 carries the free changes. The theme builder that edits all of this per component is being reworked and follows in 2.5.

Motion follows the outcome, on more components

Every moment below plays only for a change seen on screen, never on first draw, and is set per family or per moment from a brand file (--cd-motion-<item>-<moment>-*). Each is tagged in the component and listed in the manifest.

Free - ContextMeter's percentage crossfades when the count changes; the upload bar's and setup ring's fills are documented as the fill moments they were. - Locked's shake ends with its animation instead of a fixed timer. Alert counts "first draw" from the page's load, so the first alert an app shows can rise in. Composer chips are flex children of the chip row again; EntityChip and AttachmentChip gain style. - useLeaving's fallback is 600 ms; useMotionMode(ref) is new in lib/motion.ts; families with one drawing are marked fixed in the design reference; check:motion requires literal defaults.
Pro - A decision lands: ApprovalRequest and EntityDisambiguation open the outcome line and draw its tick or cross only after the service confirms; Plan opens its heading line when the plan leaves "proposed". Nothing moves on the click, and a prompt that mounts already decided is still. - Rows arrive and leave: ApprovalQueue, Inbox, NotificationCenter, TaskTray, SessionList and RunLog rows rise in when added after first draw (never on a tab, filter, pin or scroll); ApprovalQueue and Inbox rows collapse out only once the data removes them, so a failed decision never shows as gone. - Toasts leave on dismiss or expiry and the rest slide to fill the gap (skipped under calm and none); error toasts still never leave on their own. - The undo window gains a bar that drains from the server's deadline, read from the clock each frame, so a slept tab jumps; it never pauses on hover and steps in tenths under calm. - Values in place: StatCard, UsageMeters, RunReceipt and Badge crossfade a figure that changes and pop a count that rises; nothing counts through numbers that were never measured. - Validation: Input and Textarea gain attend: one attention ring on the invalid field after a failed submit, never a shake, and never on first draw. AccountCreate and SignIn focus and ring the field the error concerns once the service has answered, and fade their messages in; InviteMembers fades in its "won't be sent" note. - TypeToConfirm pops each time the text comes to match exactly and shakes (expressive only) when it stops matching. EnvironmentBand rings once, in the environment's colour, when the environment in scope changes. - Measured fills: BulletBar and UsageMeters move between measured values; DataImport gains progress (0–1, a bar only while reading). - Checks draw as they return: ShipReview, TestResults and RestoreResult draw each check's mark when its result arrives; RestoreResult gains fresh. SteerComposer draws the read tick on picked-up, never on send. - Drawer's data-side is now data-edge (no alias: the old name meant a popover's side to the overlay family); an app that styled the old attribute changes its selector. ToggleGroup's first choice lands in place; Stepper's tick uses the done moment's tokens; Combobox and Carousel use the layer's hooks.

Sound

A closed set of five events, needs-you, finished, failed, reply and silent, off until the person turns them on, always beside a visible cue, raised from data and never from a mount, one sound per burst and the same event at most once in 3 s. The brand names the files: --cd-sound-<event>: "/sounds/needs-you.mp3", --cd-sound-volume and --cd-sound-<event>-volume (0–1), --cd-sound-<event>-ogg as an alternative. Nothing is fetched until a sound plays, and Candor's CSS sets no defaults.

Free: sound (lib/sound.ts): the event names and token reading; it plays nothing.
Pro: useAttention plays the brand's sound for each signal (sound.src is now optional; sound.when "away" | "always", "always" when left out; sound.events; per-signal sound; kinds map approval→needs-you, finished→finished, failed→failed); coalescing now also applies to an explicit src. New useArrivals(ids, onNew), which calls back only for ids not present at its first render. New sound-setting: Off / When I'm away / Always, the events as checkboxes with their cue in words, a Play button each; Off is the default and the kit stores nothing. New sounds: five short CC0 sounds from Kenney (0.18–0.57 s, under 5 KB each); the registry carries text, so it installs scripts/candor-sounds.mjs and public/sounds/LICENCE.txt, and node scripts/candor-sounds.mjs writes the five MP3s to public/sounds/.

The motion manifest and `data-slot`

src/docs/motion.json, written by npm run docs: every family's settings and, per item, its moments with family, defaults, utilities and the sentence from its @motion tag. Each item's docs page (and so the MCP) has a Motion section listing its moments and the token to set them with. Served at /r/motion-manifest.json and /r/v/<version>/motion-manifest.json, no key needed.
Every component's root carries data-slot="<item>" (npm run check:slots keeps it so), so a brand file's [data-slot="<item>"] block reaches each one. Radix-style parts keep their own slots.

Docs and rules

The design reference, the accessibility statement and the agent-UI skill describe the sound events, the manifest and candor-ui theme check; the design reference marks one-drawing families fixed. internal/PLAN-3.0.md gains the native AttentionKind mapping, the when: "away" default and the drawer rename.
tw-animate-css is no longer a dependency of the theme item, the site or @candor-ui/react; apps that installed it keep it. The fresh-app check also builds a Base UI (base-nova) project with switch and checkbox.

CLI 0.10.0

theme check reads motion and sound against the motion manifest of the kit you have installed (a motion.json beside candor.css, else the registry's copy for the version in candor-lock.json, else the latest with a note; if none can be had it says the motion checks didn't run): unknown names with "did you mean" or "known from <version>", levels outside 0–2, durations outside the family's range, speed outside 0.5–1.5, a spring where nothing can overshoot, attention past 5 s or 3 rings a second, a clock level below 1, raw animations on a Candor slot, sound paths that don't resolve, sounds over 1.5 s or 100 KB or in the wrong format, and a @candor-theme newer than 2. A sound length it can't read is "not measured", never a pass. --json adds motionAndSound.
New theme apply <file | url>: checks the file in memory, writes candor-brand.css next to candor.css (asks before replacing one; --overwrite), adds the import after candor.css's, lists the sound files the theme names as present or missing (it never downloads them), and says what changed in words. A builder share link is refused with a pointer to the builder's Download.
The CLI has its own vitest config, so cd packages/cli && npx vitest run passes.

Candor UI 2.3.0

Sun, 08 Nov 2026 00:00:00 GMT

The ground for per-component theming: a motion token layer with fourteen families and their variants, every hard-coded duration in the kit moved onto it, a defined calm level under reduced motion, and the twenty-two primitives the kit was missing, in Candor's theme and with their honest moments. With CLI 0.9.1; @candor-ui/react 2.3.0 carries the free changes. The theme builder that edits all of this per component follows in 2.4.

Motion is a theme layer (free)

Fourteen families, one per kind of change: reveal, arrive, pop, mark, fill, value, move, overlay, press, tint, refuse, attention, live and clock. Each has a level (0 off, 1 subtle, 2 expressive), a duration, an easing, an amplitude where it has one, and a closed set of variants (mark: draw | pop | drop, overlay: scale | slide | fade, arrive: rise | fade | pop, and so on; the full table is in the design reference). A brand file sets them for a family everywhere (--cd-motion-<family>-*) or for one moment of one component (--cd-motion-<item>-<moment>-*); --cd-motion-speed (0.5–1.5) scales every duration but the clock's and the attention ring's (which stays under five seconds). A brand changes how a change looks, never when it plays: triggers stay in the components.
New free item motion (lib/motion.ts): the family table, motion(item, moment, family) to build a moment's chain, and the hooks useSettled, useArrived, useLeaving and useMotionAllowed. The copies of these hooks in StatusDot, StepList and Composer are gone.
Every component is on it. Every moment in the kit is a chain on a family; no hard-coded duration or tw-animate class is left in the registry, blocks or templates, and npm run check:motion keeps it that way. Update theme together with your components, because they use its new cd-* utilities. 2.2's animate-* utilities and a brand's --cd-pop-from or --cd-motion-shake still work. Small visible differences at subtle: four chevrons turn in 200 ms (were 150), StepList's mark background in 150 ms (was 200), overlays use Candor's standard easing, and the sheet fades while it slides.
Reduced motion is the calm level, not "everything to 0.001 ms": only opacity and colour change over time, 150 ms at most, nothing loops; live goes still beside its word, attention is one ring that fades, clock steps, reveal snaps to its measured size. data-motion="calm" offers the same as a choice in the app; none stays the hard off and outranks everything, and subtle and expressive are unchanged. Your app's own transitions keep their duration under reduced motion (2.2 cut every one to 0.001 ms) and only the properties they may change are limited.
Fixes in spirit. StatusDot has two new optional props, lastHeardAt and staleAfter: a running dot pulses only while the run has been heard from within staleAfter, and is still, with its word, otherwise. PermissionPrompt's waiting pulse is 4.8 s (was 7.2 s). Messages, reasoning entries, StepList steps and StepWalker's stage no longer animate on first draw, and StepList's stagger is gone; Thread marks newly arrived messages with data-arrived. HoldToConfirm (Pro) steps in tenths under reduced motion.

Primitives

The Radix-based ones take Radix's asChild and Base UI's render; all respect data-motion, put their words through LocaleProvider, and lock rather than disable. Nothing is pre-selected.

Free: checkbox (the tick draws only after the person changes it), switch, slider (position follows the pointer with no easing; locked keeps it focusable and says why, and thumbLabels names the thumbs), progress (moves only between the values it is given; with no value it is indeterminate rather than a guessed fraction), label, alert (destructive is role="alert", the rest role="status") and accordion.
Pro: toggle and toggle-group (the highlight slides to the chosen item), alert-dialog (focus starts on Cancel; the irreversible prop prints what can't be undone and ties it to the action), drawer (follows the pointer one to one when dragged, no vaul; onDismissAttempt runs before Escape, an outside click or a drag closes it and can keep it open), menubar, context-menu and navigation-menu (submenus open from their trigger; items take locked with the reason beside them), breadcrumb, pagination (PaginationRange says nothing about a total it wasn't given; pageWindow picks the page numbers to draw), table (the plain table beside data-table; its scrolling box is a tab stop), stepper (a step is done only when your app says so; the tick and rail animate when that happens on screen), calendar and date-picker (months, weekdays and digits from the locale, via Intl, no react-day-picker; unavailable days say why; presets print their exact date), combobox (never invents an option; server search shows "Searching…", results fade in only after the first draw) and carousel (scroll-snap, "3 of 8", no auto-advance unless you set interval, and it pauses on hover, focus, reduced motion and data-motion="none").
No new npm dependencies.

Docs and rules

The accessibility statement, the Principles page's ninth rule, the design reference and the agent-UI skill describe the fourteen families, their variants, who decides (the OS, then the app, then the brand) and the calm level. The release runbook lists check:motion.
internal/PLAN-3.0.md opens the ledger of agreed breaking changes for a future 3.0, each with its migration.

CLI 0.9.1

audit reads the page as someone who asked for reduced motion: infinite-animation names what still loops, and the new calm-motion names transform, translate, scale, rotate and height animations and transitions that still run.
lint warns (motion-hardcoded) about raw durations, tw-animate classes and transition-all in files that use Candor components, and points at the motion families.
doctor's clash check knows the new primitives.

Candor UI 2.2.0

Sun, 08 Nov 2026 00:00:00 GMT

Theming from the terminal and a gallery of vetted themes, an audit command, the 2.0 and 2.1 review leftovers, a changelog feed and the policy pages, and the reach pieces: skills publishing and open-in-sandbox buttons. With CLI 0.9.0; @candor-ui/react 2.2.0 carries the free changes.

Theming

Theme gallery at /themes (free): four vetted looks beside the default, Slate (cool neutrals, blue accent), Paper (warm off-whites, ink text, terracotta accent), Console (dark-first, dense, green status accent) and Signal (a higher-saturation accent), each defined as colour data in scripts/theme.mjs, checked for every pairing in light, dark and high contrast like the default (CI fails if one fails), and shipped as the registry items theme-slate, theme-paper, theme-console, theme-signal: an override file imported after candor.css. The page previews the same components in each, with the measured totals, the install command and a download; the site's "132 checks" number still counts the default theme, the gallery's own checks are shown on its page.
CLI 0.9.0, candor-ui theme check [file]: reads your overrides on top of Candor's theme, resolves the colour roles per theme the way candor.css does, and reports every pairing's measured contrast and pass/fail with totals (exit 1 on a failure; --json); it changes nothing. candor-ui theme from <source> turns existing brand tokens (a shadcn globals.css, a Tailwind config, or a Figma variables export) into a candor-brand.css override file, runs the check, and prints failures with the nearest passing lightness as a suggestion, never applied; writes only with --out. The contrast module is a copy of src/lib/contrast.ts, with a test that fails if the two drift.

Checking an app

CLI 0.9.0, candor-ui audit [path|url]: with a path, runs lint; with a URL, if Playwright and axe-core resolve from the project, loads the page, runs axe, and checks the honesty rules visible in the DOM (disabled controls without a reason, pre-checked decisions, animations that loop, model-looking external links in messages). Writes AUDIT.md grouped by principle; exit 1 on an error-level finding; --json. Without Playwright or axe it says "page not audited: install …", still lints the project, and exits 2, so a CI step doesn't pass on an unaudited page.
candor-ui list --installed says "kit x.y.z available; this item unchanged since a.b.c" when the item itself did not change, instead of "x available".

Site

/changelog.xml: a feed with one entry per released version, linked from the changelog page and its <link rel="alternate">.
/dpa, /gdpr, /licence-key: a data-processing statement and GDPR notes true to how Candor works (the registry sees a key and an IP for rate limiting and stores nothing; Polar processes purchases), and a page for buyers about the licence key: where it is, how to set it, what each tier covers, how a refund affects it, how a team shares it. A "Legal" group in the footer.
"Open in StackBlitz" on free items' docs pages opens the public starter in StackBlitz (it does not yet pre-add the item; the install command is beside it).
Example screenshots: scripts/screenshots.mjs renders the templates and gallery pages in light, dark and high contrast at desktop and phone widths with Playwright, and /examples shows them with alt text. Not run in CI.
Skills publishing: scripts/skills-publish.mjs validates both skills' frontmatter for the skills.sh registry and prints the publish commands; docs/RELEASING.md step 8 names it.

Review leftovers from 2.0 and 2.1

compare-slider: the clipped side is inert, so keyboard focus can't reach controls that aren't visible.
details-list: folded rows stay in the DOM, hidden, so find-in-page reaches them; the doc comment says a group the person must read before confirming stays open.
session-list: the unread dot's name is visually hidden text, not an aria-label on a span.
Honest vs. typical: the estimate example's Start runs a scripted run to a measured result.
Theme builder: apply uses a functional update; the 2× cap on accent strength is shown beside the control.
Roadmap: the shipped items leave "In progress".

Assessed, not built

Managed Agents adapter: still beta with no stable event shapes as of 2026-11-08 (internal/MANAGED-AGENTS-2026-11.md has the evidence); the adapter waits for stable shapes.

Candor UI 2.1.0

Sun, 08 Nov 2026 00:00:00 GMT

Storywrite's agreement card and two SessionList fixes. With CLI 0.8.1; @candor-ui/react 2.1.0 carries the free change (RelativeTime). Nothing you installed needs changing.

details-list (new, Pro; Storywrite ask 35): DetailsList, titled groups of label-and-value rows for a card where a person reads and confirms how something will be built and checked: install commands, checks with time limits, services with image, port and health, risky paths. Each group is a real description list (dl, dt, dd) under a heading button with aria-expanded, folds away, and can show a summary while folded ("3 checks, 2 with time limits"); collapsible and defaultOpen say which. A command value is monospace, wraps, and has a copy control that says "Copied" only after the clipboard took it; code is the same without the control; a link is followed only inside the app; an unknown value shows as "Not known". AttributesRail stays the flat sibling. Install with npx candor-ui add details-list.
session-list (Pro; Storywrite ask 33): a row's time faded out on hover even when the row had no onRename, onPin or onDelete, leaving a blank where nothing replaced it. It now gives way only when there is a menu button to take its place.
session-list, relative-time (SessionList is Pro, RelativeTime is free; Storywrite ask 34): a row's link was named "Thread title 2 days", the bare time without its direction. RelativeTime with bare still draws "2 days" and now also names the whole phrase, "2 days ago", to a screen reader, in the locale; so the row's link reads "Thread title 2 days ago", and every other bare time benefits. The spoken phrase is visually hidden text inside the <time>, so a bare time's textContent now holds it as well as the short form ("2 days2 days ago"); a test that reads textContent should match on the short form or query the element it means. Update with npx candor-ui update session-list relative-time.
CLI 0.8.1: candor-ui lint knows DetailsList as a Candor component, so a file that uses only it counts as using Candor.

Candor UI 2.0.0

Sun, 08 Nov 2026 00:00:00 GMT

The platform release: a theme builder that checks contrast as you brand it, a catalogue of agent screens with variations, more starters, an interactive Honest vs. typical gallery, a roadmap, and candor-ui list and search. With CLI 0.8.0. It is a major version because of the platform step, not because anything broke: the theme builder, the screen catalogue, the starters and CLI browsing make Candor a platform rather than a kit. No installed code changes meaning, and nothing you installed needs changing. @candor-ui/react moves to 2.0.0 with the kit.

For people choosing and branding Candor

Theme builder at /theme-builder (free): brand Candor with your primary and accent colours, greys, font, radius and density, see real components in light, dark and high contrast, and read the full contrast report: the same 44 pairings per theme that npm run theme checks, now in src/lib/contrast.ts and shared by the script and the site. Nothing is fixed for you silently; failing pairings are named with a passing lightness you can apply. Download candor-brand.css (overrides after the candor.css import, with the result in its header) or copy a DESIGN.md addendum. Everything stays in the browser.
Screen catalogue at /screens (docs): 22 screens an agent product needs, 63 layouts with wireframes, each with when to pick it, the items it uses with their tiers, the honesty rules that matter most there, an install command and a brief a coding agent can take. Also as Markdown at /screens/<slug>.md, in llms.txt, and in the docs MCP as get_screen and list_screens; suggest_components names matching screens.
Honest vs. typical is a gallery: each moment has a Typical / Honest switch that swaps a live example in place, with the rule it illustrates linked; five more moments (an estimate shown as measured, a disabled control versus a locked one, markdown with a model-written link, a pre-selected Approve, "Deleted" without what stays).
Roadmap at /roadmap: in progress, next and later, with no dates; the changelog stays the record.
Starters: starters/vite-ag-ui (Vite + React 19 + the AG-UI adapter, with a scripted in-browser run when no agent URL is set) and starters/tanstack-start-claude (TanStack Start + the Claude Agent SDK adapter, the same to-do agent as the Next starter). scripts/sync-starter.mjs refreshes all three; the public repo publishes them as starter-vite-ag-ui/ and starter-tanstack-start-claude/ beside starter/.

CLI 0.8.0

candor-ui list [--tier] [--group] [--installed] [--json], search <words…> and info <item> read the site's docs index, so a person or an agent can find an item from the terminal; --installed marks what candor-lock.json has and whether a newer version exists; an unknown name suggests the item that exports it.

Free items

font-source-sans, font-ibm-plex (new): Source Sans 3 and IBM Plex Sans, self-hosted (OFL), beside Inter; import next to candor.css like font-inter.
theme: a spacious density preset, data-density="spacious", the other way from compact.

Pro items

compare-slider (new): CompareSlider, two versions under one draggable divider, both labelled so neither reads as the better one; a real slider (arrow keys 1%, Shift 10%, Home/End); a caption says what is compared and where it came from.
run-scrubber (new): RunScrubber, a timeline for replaying a run at its real timestamps: ticks where the events were, a thumb the person drags or steps with the keyboard, the current event beside it, onChange(index) for the app's own trace or log, and play at the measured intervals (speed labelled), stopping at the end; two events at one timestamp say so.
hubspot-kinds, github-kinds, jira-kinds, linear-kinds (new presets): each product's main objects as entity kinds with icons and nouns, named as the product names them, and a TermsProvider preset where its words differ; like salesforce-kinds.

Repo

docs/RELEASING.md publishes the MCP registry entry (com.themethodic/candor) with each version.

Candor UI 1.9.1

Sun, 08 Nov 2026 00:00:00 GMT

Fixes from the 1.9.0 review that could wait a week: motion edge cases, UndoWindow at expiry, useAttention while focused, and a motion scenario on the Honest vs. typical page. With CLI 0.7.1; @candor-ui/react 1.9.1 carries the free changes.

composer: a chip removed and added back within the ghost's 400 ms no longer shows a ghost beside the real chip.
permission-prompt: a press inside another prompt no longer nudges this one; only a press on inert space outside every prompt does. An outside press still never counts as deny.
use-attention: stays quiet (no title badge, no notification) while the window is focused and visible, and counts by kind: the hook returns AttentionWithCounts, Attention plus counts (the number waiting per kind); the Attention type itself is unchanged, so code that builds one by hand still compiles.
undo-window: when the window closes while a failure message is showing, it says "Can't be undone now." and fires onClose; the server and the client render the same first frame; after a failed undo with time left, Undo stays for a retry.
step-list, tool-call, undo-window: under reduced motion or data-motion="none" no animation delay remains (the cross's second stroke drew after 120 ms).
thread: "Jump to latest" pulses for any new message, however the messages are nested, once per arrival.
Site: Honest vs. typical gains a fifth moment, "A tick before the clipboard answered".
CLI 0.7.1: lint's estimate-as-measured also reaches props ending in Ms, Seconds, Minutes, Duration, Cost, Tokens or Count (your own wrappers' props, since no Candor component has most of them), keys inside an object literal such as call={{ durationMs: … }}, and template literals that multiply by a rate (${tokens * 0.002}). Exact unit changes and counts (* 1000, * 0.001, pages * perPage) are not flagged, and settledCount and retryCount are checked. Candor's own source still has no finding.

Candor UI 1.9.0

Sat, 07 Nov 2026 00:00:00 GMT

Reach and rigour: setup for every coding tool, a design system and fundamentals agents read, a lint for the honesty rules, honest motion, and components for the moments after an agent acts. With CLI 0.7.0; @candor-ui/react 1.9.0 carries the free changes.

A ninth principle: motion follows the outcome. Motion reports a change that happened and never predicts or decorates one. A success mark is drawn after the result settles, a rail fills only to the step that finished, and a state that was already final when the page drew does not animate. The Principles page has it.

For coding agents and their tools

Setup guides at /guides, one per tool: Claude Code, Cursor, Codex, VS Code with Copilot, Windsurf, Zed, Cline, OpenCode, JetBrains, v0, Lovable and Replit. Each gives the registry, the docs MCP server in that tool's own config (verified against the tool's documentation), the skill or the brief, and an example prompt. Linked from Get started, the footer and llms.txt.
Plugins. Claude Code: claude plugin marketplace add MethodicDev/candor, then claude plugin install candor-ui@candor installs the skill and the docs MCP server together (.claude-plugin/). Cursor, Codex and VS Code / Copilot packages under plugins/, with .cursor-plugin/marketplace.json and .github/plugin/marketplace.json (copilot plugin install candor-ui@candor). .mcp/server.json describes the docs MCP server for the MCP registry (com.themethodic/candor, remote, no auth). Every description says the server is docs-only and keyless. llms-install.md tells an agent how to set all of it up by itself. The public repo carries them.
A second skill, skills/candor-agent-ui (MIT, npx skills add MethodicDev/candor): design fundamentals for screens where an AI agent acts, in any framework and design system: the nine honesty rules with examples, approval ergonomics, the status vocabulary and the states of a tool call, folding turns, progress and finishing while away, blast radius and undo, AI disclosure, accessibility, and a review checklist to run after each screen.
A design system agents read: skills/candor-ui/references/design.md and /design.md, generated from the shipped CSS by scripts/build-design.mjs (every colour role and what it's for, the type scale, radius, shadows, motion, density, themes, how to re-token for a brand, and a do/don't per honesty rule); checked fresh in CI. The candor-ui skill gains an "After each screen" section pointing at the checklist and design.md.
Docs MCP: new tools get_design, get_review_checklist and get_brief (an item's brief, the same text the docs page's "Copy for a coding agent" copies).

CLI 0.7.0

candor-ui mcp <tool> and init --mcp <tool> add the docs MCP server (https://candor.themethodic.com/mcp, read-only, no key) as a server named candor to a tool's project-level config: Claude Code (.mcp.json), Cursor (.cursor/mcp.json), Codex (.codex/config.toml), VS Code (.vscode/mcp.json) and OpenCode (opencode.json). Existing servers, comments and formatting are kept, running it twice changes nothing, and doctor says which tools have it. Zed, Windsurf and Cline have no documented project-level file, so the command names them and points at their settings.
candor-ui lint [paths…] checks an app's .tsx/.ts/.jsx/.js files against the honesty rules: model-html (error: HTML rendered from a string in a file that shows a chat), disabled-without-reason, preselected-decision and estimate-as-measured (warnings). Prints path:line:col rule message, exits 1 on an error; --strict fails on warnings, --json for machines. Each rule is documented in the CLI README with the principle it serves. Candor's own source (the registry, blocks, templates, starter, site and docs examples) passes with one warning.

Free items

theme: data-motion="none" | "subtle" | "expressive" on <html> or any container, like data-theme. Subtle is the default and today's behaviour; none turns every animation and transition off, with or without the OS setting; expressive scales pops and lets a pressed locked control shake. Duration tokens --cd-dur-quick, --cd-dur-base, --cd-dur-slow (use as duration-(--cd-dur-base)), and keyframes collapse-down, collapse-up, pop-in, pop-out, tick-draw, fill, shake, attention. The reduced-motion rule stays last and wins. No new props anywhere in this list.
collapsible: content opens and closes to its measured height; ToolCall, Reasoning, FoldedTurns and a card's summary inherit it. Nothing moves on content that mounts open.
tool-call, step-list, status-dot: a mark whose status reaches done or failed while on screen draws its tick or cross; one that mounts finished is drawn still. StepList's rail fills under a finished step, never ahead of it. StatusDot pops into its final colour (too small for a drawn mark).
message-actions, copy-field: the copy icon stays until the clipboard write settles, then the tick (copied) or cross (failed) appears; data-copy carries the state.
context-meter: the ring sweeps to a new measured count and changes colour at the 80% line; neither the first render nor server markup sweeps from zero.
composer: mention and attachment chips added after the first draw pop in; a removed chip pops out as an inert ghost, hidden outright under data-motion="none".
locked: pressing a locked control keeps its reason open and emphasises a printed one; the shake exists only under data-motion="expressive". Activation stays blocked.
permission-prompt: pulses three times when a decision arrives, then stays still (and not at all while busy). A press on inert space outside it, the gesture that would dismiss a dialog, nudges it instead; nothing but Allow or Deny is ever a decision, as before.
thread: "Jump to latest" pulses once each time a message arrives while the reader is scrolled up, then stays still; the jump scrolls instantly under reduced motion or data-motion="none".

Pro items

hold-to-confirm (new): HoldToConfirm, a button held, by pointer or with Space or Enter, for holdMs (1200 unless the app says otherwise) before onConfirm fires. The bar fills from the clock; letting go early cancels and says so. The required reason (what it does, whether it can be undone) is read with the button; locked says why. Nothing pre-armed, no one-key path, never auto-focused.
undo-window (new): UndoWindow, an action just taken with Undo for exactly the window the server granted (until or seconds; no default, so without either the app's cannotUndo text shows and there is no Undo). Time left is read from the clock, so a slept tab catches up. Pending until onUndo settles, then "Undone." or "Couldn't undo: <the rejection's reason>"; when the window closes, "Can't be undone now." with what happened kept.
use-attention (new): useAttention, a count and a "(n) " title badge for what waits on a person or finished while they were away, cleared on focus, on the tab becoming visible, or by clear(). System notifications only with notify on and permission already granted (the hook never asks; requestPermission() is for the app's own button); sound only with a src the app passed and enabled: true. SSR-safe.

Site and repo

Home page: a "Built with Candor" strip naming OrgSmith and StoryWright as Methodic's products on Candor, and Methodic as a Salesforce consulting and AppExchange partner.
SECURITY.md: how to report a vulnerability privately, what's in scope, and how fixes reach installed components (npx candor-ui update).
The README quotes the measured counts; CI fails if the README or the Polar copy disagrees with src/site/stats.json.
docs/RELEASING.md is the release runbook, CLAUDE.md the repo's standing instructions, and npm run release:check runs CI's checks locally with a preflight on the version, the CHANGELOG and the package versions.

Candor UI 1.8.1

Fri, 06 Nov 2026 00:00:00 GMT

Three accessibility and theming fixes a customer found in 1.8. No new props.

CommandPalette: the search box also carries aria-label (the search string). In 1.8 it was named only by cmdk's label, hidden with display: none; Chromium follows that through aria-labelledby, but not every accessibility tree does, and there the box had no name.
SessionList: each group ("Today", or your own "Needs you", "Projects") is a group named by its heading, so a screen reader can move between groups and says which one a row is in. This holds with virtualize too, where a group's heading can be outside the rendered rows. The visible heading is hidden from screen readers so it isn't read twice.
AppLayout: the panel's sheet is 448px wide (max-w-md), as it was meant to be. The sheet primitive's own sm:max-w-sm (384px) had won at every width the panel is a sheet.

Candor UI 1.8.0

Fri, 06 Nov 2026 00:00:00 GMT

Links where things navigate, a palette and composer that say only what's true, agents that ask mid-call and connect to new servers, and plans that say when a run left them. New optional props and CLI 0.6.0; no breaking changes.

Shell and composer: a customer's asks

SessionList: a session with href (new on Session) is a real link, so it opens in a new tab, its address can be copied, and the open one is the current page to a screen reader. A plain click still goes through onOpen for your router; other clicks are the browser's. Without href, rows are buttons as before.
AppLayout: navOpen and onNavOpenChange control the sidebar sheet, so the app can close it when the person navigates. navButton={false} drops the built-in menu button for an app with its own top bar. The frame carries data-nav ("rail" or "sheet") and group/app-layout, so your own button can show only while the sidebar is a sheet (group-data-[nav=rail]/app-layout:hidden).
CommandPalette is named once: the dialog by its title, the search box "Search" and the list "Results" (new strings search and results). Before, a screen reader heard the title three times before the first item, and the list's name was cmdk's English "Suggestions" whatever the locale.
Composer's keyboard hints name only what's on: "@ mention" only with mentions, "/ command" (new string hintCommand) only with commands. hints={false} hides them.

Plan drift and autonomy (Pro)

Plan: drift. A step can say how the run left the approved plan, with drift on PlanStep ({ kind: "added" | "skipped" | "changed", note?, from? }), from your app's own records. Candor never works drift out by itself. - Each drifted step says so in words: "Added during the run, not in the approved plan", "Skipped by the run, though it was approved" or "Changed from the approved plan". A changed step can say what was approved ("Approved as: Backfill from billing country"), and any step can say why (note). - A line above the steps counts them: "The run left the approved plan: 1 step added and 1 step skipped".
Plan: autonomy on accept. With autonomy (a list of PlanAutonomyOption), accepting says what it allows. The person picks one before Accept is available; none is picked for them. onAccept gets the choice as its second argument. - Two options have built-in words: "askBeforeEdits" ("Ask before each edit") and "runWithoutAsking" ("Run without asking"). Your own take label and detail; locked says why one can't be picked.
The new words are in planStrings, so LocaleProvider can override them.

New optional props and fields only: a plan without drift or autonomy looks and accepts exactly as before. onAccept still gets the skipped steps first.

MCP servers that ask, and connecting one

MCP's 2026-07-28 revision stopped servers pushing questions at the client: a call that needs more comes back "input required", and the client asks the person and retries the call with the answers. Candor shows those questions with the components that already ask people things, and gives the person a straight account of a server before connecting it.

New: mcp-input (free lib): an MCP input_required result as Candor data, and the person's answers back as the retry. - mcpInputView(result, { server }) turns each of the server's inputRequests into an item, in the server's order. A form (elicitation/create) becomes questions in ClarifyingQuestions' shape: an enum (with or without titles, single or multiple) a choice, a boolean Yes or No, text and numbers a line. A field's title becomes the tag when it also has a description. A form with no fields, a plain "go ahead?", becomes a two-answer Decision for ApprovalDecision. - A link the server wants opened (URL mode: a sign-in, a payment) is a Decision too, with the page's host and its full address as facts, and a warning for an encoded (xn--) name or a page not on https. Nothing opens until the person accepts; an address that isn't http or https isn't offered at all. - The server's default is marked as its suggestion and never chosen for the person; a text field shows it as a hint and stays empty. A choice the server doesn't require offers "Leave unanswered" rather than assuming one. - What it can't show stays on screen as "not supported", with the method and why: a model prompt (sampling), a request for folders (roots), a form with a field it can't draw, or a kind newer than this file. Nothing is dropped. Answer those yourself and pass them as own. - mcpInputResponses(view, replies) checks the answers against each form's schema first (required fields, choices, whole numbers, minimum and maximum, length, email, URL and date formats, how many to pick) and returns the problems in words, or the inputResponses to send. Declined and dismissed requests are sent as such, and what wasn't sent is listed in notSent. - mcpRetryParams(original, view, inputResponses) is the original call's params with the answers and the server's requestState exactly as it came, and without an earlier round's state when this round has none. - The view keeps your app's name for the server (server) apart from the name the server gives itself (serverClaims), so the person sees who is asking as your app knows it. - Free items can't depend on paid ones, so the question and decision shapes are defined in the file; they fit ClarifyingQuestion and Decision as they are. The words are in mcpInputWords; pass your own.
New: McpConnect (mcp-connect, Pro): the card for connecting a new MCP server. - Where data goes first: the server's host, then its full address (or the command a local server runs with), and who runs it as your app knows it. Left out, it says the owner isn't known. - What it says it can do: each tool by name, with its title and description. A tool with no description says "Not described by the server". The server's own hints ("Says it only reads", "Says it can change or delete") are labelled as its claims, which nothing has checked. Past toolLimit (6), the rest fold behind "Show all". - What it asks for: each permission with a box nobody has ticked. One the server doesn't explain says "Not described by the server", never hidden. A permission it needs to connect is marked, and Connect stays locked, saying why, until it's ticked. onConnect gets only the ids the person ticked. - A list the server hasn't given is said to be unknown ("The server hasn't listed what it can do"), not shown as empty; an empty one says there's nothing. - How to disconnect later, always. An optional acknowledgement the person ticks themselves, busy and error. - Connect and Cancel are the same size and style, so neither is the easy way out. - Its words are under mcpConnect in LocaleProvider's strings.

New items only: nothing existing changes.

Usage that isn't metered yet (Pro)

UsageMeters: pending is work already done that the provider hasn't metered yet. It's drawn after what's used as a striped part of the bar and said in words ("about $1.10 not yet metered"), and read with the meter's value. mayExceedBy says how far a run may still go past the limit ("May go over the limit by up to $2."), from your own figure: a provider that checks the limit between steps, a run already under way. Both have …Text versions for server-formatted money. The meter never works either out.

React 19.3 and the React Compiler

SidePanel: keepTabs keeps tabs that aren't showing mounted, so switching back finds each as it was (its scroll, a half-filled form). On React 19.2 and later it uses React's <Activity>, so a hidden tab's effects pause until it's shown again; on 19.0 and 19.1 hidden tabs simply stay mounted. Without it, only the showing tab is rendered, as before.
CI now runs the React Compiler (1.0) over every component, block and template (npm run check:compiler), and fails if it has to skip one for a reason that isn't on a short, explained list (syntax the compiler can't lower yet, and demo code that writes a cookie in a click handler). Turn the compiler on in your app and Candor's components are optimised with it.
Candor still supports every React 19 release. Fragment Refs (19.3) would have meant dropping 19.0 to 19.2, so the Thread's focus handling stays as it is.

Claude Agent SDK adapter (free)

When the SDK summarises earlier messages to make room (compact_boundary), the thread now says so, as a system line between replies: "Earlier messages were summarised to make room. The agent works from that summary now; the messages above are unchanged." Before, a long session lost its history from the agent's view without a word.
A cleared conversation (conversation_reset, from /clear and similar) gets a line too: the agent doesn't see the messages above.
eventText gives these lines your own words, for other languages.
recalled on the adapter's state lists the memories the SDK recalled for each reply, by message id, with whose memory each is (personal, team or organization), ready for a MemoryUsed line in that message's footer.

CLI (candor-ui 0.6.0) and finding components

update <item> --moved a=b records the move even when the item is already at the target version; before, it said "already at" and wrote nothing, so the lockfile couldn't learn about a file moved between releases. A --moved naming a file no item here installed is refused, with the paths the lockfile does know.
add with a component's name (npx candor-ui add ApprovalDecision) says which item it lives in (approval-request) and installs nothing, instead of failing on a name no item has.
llms.txt and the docs MCP's list_components and search_docs name an item's other components: approval-request exports ApprovalRequest and ApprovalDecision. get_component_docs already found an item by any of its components.

Site

Honest vs. typical (/honest-vs-typical): four moments side by side, a plain rendering of what an agent UI typically shows beside the Candor component with the same data: an approval for a change that moved since it was asked for, a run that went quiet, a restore that missed a shell change, and a cost the SDK didn't report. Each links to the components' docs and the principle it keeps. No products are named.

Candor UI 1.7.0

Fri, 06 Nov 2026 00:00:00 GMT

Agents that work while nobody watches, approvals that can be edited and answered from anywhere, memory that says what it used, and the next round of a customer's asks for the thread, messages and composer. New items, optional props and CLI 0.5.0; no breaking changes. One behaviour to know: candor-ui add --overwrite now stops before replacing an item you've changed.

Background work hub (Pro)

Runs that go on without the person watching, shown honestly: a run is never called running when nothing has been heard from it.

New: RunHeartbeat (run-heartbeat, Pro): a run's state that never claims it's alive on no evidence. - With lastHeardAt, a running run heard from recently says "Running · heard 1 minute ago". Silent for longer than staleAfter (two minutes unless set), it says "No update since 10:42" instead, and that it may have stopped. A queued or waiting run is quiet by design, so it doesn't go stale. - hostOffline ({ host?, since? }) says the machine or worker can't be reached ("Runner 3 offline since 10:40"), with the last update. It comes ahead of everything but a finished run. - A run that needs the person (status "waiting", or needs) says what for, with a Respond your app handles (onRespond). An offline run that needs the person still says what for. - Before the page has a clock (server rendering), it gives the last update's time and claims nothing. - Without lastHeardAt, the app isn't tracking freshness, and the status is shown as given, as before. - compact is one line, for lists. useLivenessWords() gives the same words for your own lists.
New: SteerComposer (steer-composer, Pro): send a message into a run while it works. - Each message says where it is: sending, sent but not picked up yet ("Build agent hasn't picked it up yet"), picked up (and when), or not delivered, with the reason and a Retry. A message isn't shown as read until your service says so. - onWithdraw takes back a message the agent hasn't read yet; one it has read can't be withdrawn. - The note above the box says when the agent reads messages (pickupNote, "between steps" by default), or that the run is quiet, its host is offline, or it's waiting on the person: a message doesn't answer what it asked. - A finished run takes no messages and says so. Enter sends; Shift+Enter breaks a line.
lastHeardAt and hostOffline on BackgroundTask, AgentActivityEntry and Session, with a staleAfter prop on TaskTray, AgentActivity and SessionList. A silent or offline run stops showing as running in each: - TaskTray counts it as "not heard from" instead of running ("1 running · 2 not heard from"), and its row says "No update since 10:42" or that its host is offline. - AgentActivity shows the same line instead of the agent's status. - SessionList shows it instead of the status with showStatus; without it, the dot stops pulsing and its label says why.
status (free) gains runLiveness(run, now, staleAfter), the RunLiveness and HostOffline types, and STALE_AFTER.
The "Unknown stays unknown" principle now names run-heartbeat.

New optional props, fields and functions only: existing code renders and runs as before. Data without lastHeardAt or hostOffline looks exactly as it did.

Approvals (Pro)

ApprovalRequest: edit before approving. With onApproveEdited and the request's new input (the change as it will run, as the agent proposed it), the person deciding can edit it as JSON first. They see exactly what they changed against the proposal, the same view PermissionPrompt shows for an edited tool call, and the edited change's own hash once it's worked out. "Approve as edited" calls onApproveEdited(hash, input) with that hash; an edit that changes nothing approves through onApprove as before. Nothing is pre-selected, and an edit to a change in production or one that can't be undone needs one more tick ("I've checked my edit") before it can be approved. The compact density never edits: it opens the full request, as before. hashOf works the hash out (by default changeHash: the sha256 of the input's canonical JSON); pass your server's own, and have the server recompute it from the input it receives. Once decided, decision.editedFrom (the proposed change's hash) shows "Edited before it ran", the words the tool call uses. With the Claude Agent SDK, the edited input is the answer's updatedInput.
New: changeHash (change-hash): the sha256 of a change in the same canonical form (keys sorted at every depth) in the browser and on the server, so an approval made against a hash can be checked where the change runs.
New types: ApprovalRequest.input and decision.editedFrom (both optional).

Blocks (Premium)

Approve from anywhere (new, approve-from-anywhere and approve-from-anywhere-claude): an agent that changes feature-flag rollouts, whose one write pauses the run until someone else decides, however long that takes. - The approver gets an email (EmailLayout) with the approval's id and the change's hash, and no link: they open the approval page themselves and type the id. The email says to check the hash on the page matches. - The approval page is made for a phone: the compact ApprovalRequest, which opens the full request to decide a production change or to edit the percentage first (edit before approving, above). The server works out the edited change's hash again and refuses the approval if it isn't the one the approver was shown, and only the percentage can be edited. Only the people it was sent to (people, through mayDecide) can decide it, never the person whose run asked. - The decision is data, so the run resumes whether or not the process that paused it is still there. On the Vercel AI SDK the run is its saved messages, resumed from them as soon as someone decides. On the Claude Agent SDK the waiting process polls the block's ApprovalStore; if it went away (a restart or a deploy), its heartbeat stops, and the decision is applied and the agent carried on from its session (the SDK's resume). Browsers re-attach to a Claude run from its stored events (ClaudeRunStore, attachClaudeAgentRun). Resuming is claimed with a conditional write, so one process does it. The approver's answer comes back as soon as the decision is recorded; the run carries on after, so a long or second approval never holds their request open. - The change applies once, exactly as approved, only if the flag hasn't moved since it was asked for. A request nobody decides expires after a day and the run is told. The person who asked can't approve their own run's write, including by answering the adapter's approval directly. - Data is kept in memory, or in Postgres in the anywhere_ tables; only Postgres survives a restart. Emails go to an outbox table for your mailer.

Memory (Pro)

MemoryUsed (new, memory-used): the line under a reply that says what it remembered, "Used 2 memories", which opens them, each with who taught it and when. onOpen makes each one a button (to open it in MemoryManager, say) and onManage adds "Manage memory". fromHistory says the reply also drew on past chats, which can't be listed, in words rather than as an empty or made-up list ("Used past chats" when that's all it used). forgotten counts memories it used that have since been forgotten, without words it no longer has. With no memory used it renders nothing. Put it in Message's new footer.
MemoryMode (new, memory-mode): memory on, paused or off, with what each does to the memories already kept. Paused always says they're kept and come back. What off does is the app's to say (whenOff, required): "kept", or "deleted", which asks first, says how many go (count) and offers "Pause instead". The mode shown is the one the app reported; pending, error and locked work as in PermissionMode.
MemoryManager: history (with chats when known) says agents also learn from past chats, which can't be shown or forgotten one by one here, and an empty list then reads "No saved memories." instead of "Nothing remembered yet." mode says above the list when memory is paused (kept, not used) or off.
Message (free): footer, a node shown under an agent reply after who checked it and above the actions row, for lines like MemoryUsed. MessageFooter takes it too. Without it, nothing changes.
know: the MemoryModeValue type ("on", "paused", "off").

New strings: memoryUsed and memoryMode tables; memoryManager gains emptyWithHistory, history, historyCount, paused and off.

Thread, messages and composer (free)

Thread: anchor opens it at an element in it (a chapter divider, the card that needs the reader) instead of the bottom, and waits for the reader instead of following; scrollerRef hands over the scrolling element; onDrop takes files dropped on the thread; fade={false} turns off the soft fade at the bottom.
Message and MessageHeader: density="compact" draws a 12px name in a 24px row.
Message and MessageContent: bareCode shows code and other payload blocks without their frame.
ThreadEvent: align="start", a left-aligned line (right-aligned in RTL) with the time at its end; pair it with 1.6's timeFormat="time" for a clock time.
FoldedTurns: header replaces the dashed line with your own (a card with a title, how it ended, its cost), with Show and Hide after it.
Composer: - A held state, { kind: "held", reason }: typing stays open, sending waits, and the box says why ("Your partner is still thinking"). locked still disables the box. - textareaRef to focus the box from outside. - sendShape="round" for a round send button.

CLI (candor-ui 0.5.0)

add --overwrite stops before shadcn replaces an installed item you've changed: it names the files, installs nothing, and says to bring them up to date with update (which merges) first. --replace-edits replaces them anyway; it isn't passed to shadcn.
When shadcn writes nothing (it stops if a file it would update has your changes, and still exits 0), add says so, names that file, records nothing for those items and exits 1. Before, it said the items were "already installed".

Candor UI 1.6.0

Fri, 06 Nov 2026 00:00:00 GMT

From a team building on Candor: what got in their way, fixed. Strict TypeScript, moved files, money your server formats, absolute times, and the accessibility statement. New optional props, one new free item and CLI 0.4.0; no breaking changes. One thing to do if you use Inter: see "Inter is its own item".

Strict TypeScript

The kit, blocks and templates compile with exactOptionalPropertyTypes on. Every optional property is written ?: T | undefined, so passing a value that may be undefined to an optional prop works under both settings, and lock-reason maps (ToolSetting.locked, RestoreDialog, ReviewLadder, NotificationPreferences) accept undefined. CI checks it (npm run check:exact).
It also compiles with noImplicitOverride: the error boundaries in card-registry and a2ui-surface mark state and render as override.

Messages and times

Message, MessageHeader, MessageFooter and ThreadEvent take timeFormat: "relative" (the default), or an absolute "time", "date" or "datetime" in the locale, for every time the message shows.
Message takes meta: false hides the "You · time" line under a person's message, a node replaces it.
message-content installs safe-markdown, and the docs name plainBlocks and markdownBlocks as the way to build a message's blocks. Import them from safe-markdown: they run on the server too.

Money as your server wrote it

When your server decides what's exact and what's "about", give it the text and Candor shows it as written, never rounding or summing: UsageMeters (usedText, limitText, estimateText, read to screen readers through aria-valuetext), RunReceipt (totalText, and a model's costText), RunEstimate (costText), SpendBreakdown (totalText) and StatCard (valueText). The numbers still place bars and markers.

Toasts

Toaster takes offset (or the --cd-toast-offset token) to keep clear of something fixed at the bottom, such as a chat composer.
When the focused control is under the stack anyway, the stack moves to the top (WCAG 2.4.11). Your own className="bottom-…" on Toaster still wins over the default position.

Inter is its own item

The theme no longer imports Inter. It's the new free item font-inter (styles/candor-font-inter.css, OFL-1.1), so a project can keep its own font and its own font licences. Without it, --cd-font falls back to the system's sans-serif.
candor-ui init adds and imports it unless you pass --no-font. If you update the theme and want Inter, run npx candor-ui init again (it adds the font and changes nothing else), or npx candor-ui add font-inter and import styles/candor-font-inter.css after candor.css. update says so when it takes Inter away, and doctor notes when text uses the system font.

CLI (candor-ui 0.4.0)

update follows a file you moved: it finds it when it's still exactly as installed, or you say where with --moved <installed path>=<where it is now>, and candor-lock.json remembers the move. A move must stay inside the project and keep the file's name, so a typo can't merge Candor's file into another one.
An item with a file update can't find is now left alone: nothing of it is written, it stays at its old version, and update exits 1. Before, it moved on without that file.
verify, for CI: checks candor-lock.json against the registry's versioned snapshots and the files on disk, without running shadcn. Files you changed are listed, not failed.
Installing several items at once no longer leaves some unrecorded: small differences shadcn makes in a batch (a "use client" line, trailing spaces) count as the same install.
init --no-font, and doctor flags a monorepo's shared package that still points at the old GitHub registry.
The Get started guide now covers the lockfile, merges, --dry-run, --from, --moved and verify; /docs/cli and /docs/updating lead there.

Accessibility (WCAG 2.2 AA)

A public accessibility statement at [/accessibility](https://candor.themethodic.com/accessibility): WCAG 2.2 AA as the target, what's checked on every release, and the known gaps (no screen-reader pass by people yet).
Focus rings that carry focus on their own go from 40-50% to 80% opacity, meeting 3:1 on every surface in every theme; npm run theme now measures the ring as drawn, blended at 80%.
The chosen segment in segmented controls has a 1px edge as well as its fill.
RoleMatrix, DataRetention, ComparisonView, RunLog, MetadataDiff's file body, DataImport's preview, RestoreDialog's checks, TestResults' stack traces and Diagram can be scrolled from the keyboard. They're new tab stops: a test that counts Tab presses through these components needs one more for each.
AppSidebar takes help, which puts Help in the same place on every page (3.2.6).
A test fails on any new button or link smaller than 24px without a hit area (2.5.8).

Candor UI 1.5.1

Fri, 06 Nov 2026 00:00:00 GMT

Two fixes, both found by a team building on Candor.

Toast

A fifth toast no longer pushes out an error. The oldest toast that isn't an error goes first, the newest always shows, and errors stay until someone dismisses them, as the docs always said. Before, the toaster kept the newest four whatever their tone, so four notices after a failure hid it. Errors can now stack past four, so the stack scrolls once it reaches the top of the screen, keeping the newest in view. capToasts is exported for tests.

CLI (candor-ui 0.3.1)

init and key (including key --remove) move @candor off the pre-launch raw GitHub address (raw.githubusercontent.com/…/public/r/) to the public registry, and say so. Before, they kept it, so a project set up before launch stayed frozen at that commit and needed a GitHub token. --registry-url still sets any address you choose.
On the old address, add and update stop and say to run init, rather than sending your licence key to GitHub. doctor flags it (in a monorepo's shared package too) instead of saying "All good", and skips checking the key.

Candor UI 1.5.0

Thu, 05 Nov 2026 00:00:00 GMT

Approvals that last, AI that says it's AI. Seven new items (two free), durable approvals and the full Claude Agent SDK permission model in the adapters, and the CLI in monorepos. New optional props and functions only: existing code renders and runs as before. Two type changes widen what's accepted (AuditAction, ClaudeApproval); see below.

Durable approvals and runs (free adapters)

Claude Agent SDK, server half (claude-agent-server): - Permission requests wait in an ApprovalStore instead of only in process memory. memoryApprovalStore() is the default; pass your own (a table, a queue) as approvals, so any instance can take the answer. waitByPolling helps a store that can't push. Answering and closing each happen once, whichever comes first, so a late answer to a run that already ended is refused, not lost. - claudeCanUseTool({ approvals, emit, owner }) is the same canUseTool outside streamClaudeAgent, for an agent run by your own worker or workflow engine. Answer it from your own route, such as a workflow signal. - answerClaudeApproval(store, id, answer, { owner }) records the full answer: allowed, denied, allowed with an edited input, answers to the agent's questions, and the "always allow" rules the person picked. It checks the answer fits the request (an edited input must be an object; only offered rules can be kept). The 1.4 answerClaudeAgentApproval still works, synchronously, on the default store. - A ClaudeRunStore (memoryRunStore()) keeps a run's events. With detach, a run carries on when the browser goes away, and attachClaudeAgentRun streams it again from any point, then live. stopClaudeAgentRun stops it. Responses carry the run's id in x-candor-run-id. onEvent hands you every event to keep for replay, and prompt records what the person sent as the run's first event. A run store creates a run only on start, and memoryRunStore forgets only finished runs (oldest first, past maxRuns), so a live run keeps its owner. It keeps up to maxEvents (5,000) per run, after which partial-text events are dropped. - approvalTimeoutMs closes a request nobody answered as expired: the tool is denied, never allowed. Set one with detach, or a run can wait for ever. - editable(tool, input) says which tools' input a person may edit (every tool by default). An edit to any other tool is refused by the server, whatever the browser sends, and the request tells the browser (editable: false). - The input a person edited is recorded: candor_approval_closed carries it, and the tool card and any replay show what ran, marked "Edited before it ran", with the agent's proposal beside it. - A stop and an answer at the same moment: the request closes as stopped, and the answer is refused, so the record never says "approved" for a tool that didn't run. - setClaudeAgentPermissionMode(runId, mode, owner, { allowed }) changes a running agent's mode (the SDK's setPermissionMode, streaming input only) and tells the browser. The route enforces policy: modes outside allowed, or the run's modes, are refused, so a mode PermissionMode shows as locked can't be set by posting to the route directly. - The agent still runs in the process that started it: a store makes the answer and the record durable, not the run.
Claude Agent SDK, browser half (use-claude-agent): initialEvents replays a stored conversation; attachUrl and runId re-attach to a run after a reload (attach() does it on demand); onRespond answers through your own route instead of approveApi, which is now optional; stopApi stops a detached run; modeApi, permissionMode and setPermissionMode. respond takes a fourth argument with updatedInput, answers and alwaysAllow. Requests now send a promptId too: pass it to the server's prompt, and re-attaching with initialEvents replaces the run's events instead of adding them again.
Vercel AI SDK 7 (ai-sdk, use-candor-chat): runs on WorkflowAgent stream the same UI messages, so they work as they are. A tool waiting for approval stays waiting for as long as the workflow does, and an approval made automatically is marked on the tool call. Re-attaching after a reload is the AI SDK's own WorkflowChatTransport.

The Claude Agent SDK's permission model (free)

AskUserQuestion becomes questions: ClaudeApproval.questions, shaped for ClarifyingQuestions (claudeQuestions). Answers go back as the SDK expects, keyed by the question's text, several choices joined with ", ", the person's own words used as typed.
ClaudeApproval also carries suggestions (the SDK's "always allow" rules, offered and never kept unless the person picks one), noAlwaysAllow, mode, displayName, agentId and mcpServer. claudeSuggestions turns the rules into plain parts to show. claudePermissionResult(request, answer) turns an answer into the SDK's PermissionResult, wherever the answer lands.
fromClaudeAgentEvents reports permissionMode from the SDK's init and status messages and the new candor_mode event.
New: PermissionPrompt (permission-prompt, free): a tool call waiting on the person. It says why it reached them and the run's permission mode, lets them edit the input as JSON and shows exactly what they changed before "Allow as edited", offers "don't ask again" rules as boxes nobody has ticked, and opens on Deny when the request asks. Nothing carries over from one request to the next. A rule that switches to "Allow everything" or "Automatic" says what that hands away. When the agent asks questions, it shows them as a short form with nothing chosen. The Claude gallery demo uses it.
ToolCall takes approval: { by: "person" | "automatic", note } and marks a call "Approved automatically".

AI disclosure

New: AiDisclosure (ai-disclosure, free): tells people they're interacting with an AI system, as a first line in the thread or a compact "AI" badge for a header, with the app's own explanation. The agent is named only by the app. It helps with EU AI Act Article 50(1); it makes no legal claim, and whether it's enough is the deployer's call. Free by the owner's decision, as part of "a good agent chat".
New: AiContentLabel (ai-content-label, Pro): "AI-generated", "AI-modified", "No AI used" or "AI involvement not recorded", after the two categories in the EU's voluntary Code of Practice on marking and labelling AI-generated content (final, 10 June 2026): fully AI-generated and partially AI-modified. The level comes from the app's records, never a guess, and the mark is Candor's own. The label goes with the content: provenanceText, withProvenance for copied text, provenanceMetadata (ai:involvement, ai:by, ai:at) for downloads and sidecar files, and useCopyWithProvenance.
A docs page, "Telling people they're talking to an AI", says what the components do and what stays the deployer's.

Checkpoints and an honest restore (Pro)

New: CheckpointList (checkpoint-list): restore points per turn, what each holds (files, conversation or both, with counts when known), who made it, and where the work is now. A checkpoint that can't be restored stays listed with its Restore locked and the reason.
New: RestoreDialog (restore-dialog): restore code, conversation or both, with nothing chosen for the person. It says what a restore doesn't undo: shell commands run since (listed when the app knows them, or "not recorded"), changes made outside the agent, and effects such as sent messages and deployments. After a restore, RestoreResult shows what the app checked, item by item: "Restored" only when every check matched, a mismatch flagged with what differs, and "not checked" said as such. Restoring both needs a check of each: one that covers only the files is "Partly checked", naming the conversation (RestoreCheck.area).

Approvals (Pro)

ApprovalRequest: - target and values: a change to one thing shows each value before and after (from: null reads "Not set"; a from left out reads "Not recorded"). - restrictedTo: { who, reason }: a request only certain people may decide carries a badge saying who, with the reason shown and read to screen readers. - density="compact" for a narrow column, a phone or a notification: the values or summary, where, how many things it touches, the hash, expiry and what happens if nobody answers. Nothing is pre-selected. A change that can't be undone, or that changes production, has no Approve there; onOpen opens the full request.
New: TypeToConfirm (type-to-confirm): a step that can't be undone, confirmed by typing a name exactly. Pasting is allowed. DataControls now uses it; its string keys are unchanged.
New: PermissionMode (permission-mode): the agent's permission mode with what each mode allows written out, as a list or a compact toolbar button. "Allow everything" and "Automatic" ask "Switch to …?" first; a mode your policy turns off is locked with the reason (enforce the same policy on the server). It shows the mode the agent last reported, never the one just picked. One tab stop; arrow keys move between modes, Space or Enter changes it.
ClarifyingQuestions: a choice can offer other (the person's own words, sent as text), a tag above the question, and during drops "Before I plan" from the heading when the agent asks mid-run.
Changed type: AuditAction is now open: Candor's known actions (KnownAuditAction) or any string. AuditLog takes actions to label and group your own; one with no label shows its code. An "Other" filter appears only when a row needs it. Code that switched over every AuditAction should add a default branch, and a Record<AuditAction, …> map in your code no longer type-checks: key it by KnownAuditAction, with a fallback for other actions.

AG-UI 1.0 (free)

STATE_SNAPSHOT and STATE_DELTA fold into state (on fromAgUiEvents and useAgUi). Deltas apply all or nothing; a patch that fails keeps the last good state and sets stateOutOfDate with the reason until the next snapshot.
ACTIVITY_SNAPSHOT and ACTIVITY_DELTA become activities, in arrival order. Steps map to plan (shaped like PlanStep) and status content to agentActivity (shaped like AgentActivityEntry), only when every status is a known word.
New applyJsonPatch, a small RFC 6902 patcher that never changes its input. fromAgUiEvents and useAgUi take agents and initialState.

Citations from tool output (free)

The Claude adapter fills Message.sources from Claude's own citations and web search results, and places [n] only where a citation is, never from numbers in the text.
Both the Claude and the AI SDK adapters take sourcesFrom(tool, input, output) to read sources from your own tools' results. The ToolSource type is in lib/chat.

Docs MCP server

/mcp speaks MCP 2026-07-28: no handshake, server/discover, the version checked on every request (MCP-Protocol-Version must match _meta, else 400 HeaderMismatch -32020), and an unsupported version answered with -32022 listing the supported ones. A 2026-07-28 request must send Mcp-Method, and Mcp-Name for the methods that name something (400 HeaderMismatch without them); both are checked against the body. GET and DELETE answer 405, and no session is kept.
Older clients (2025-11-25 back to 2024-11-05) work as before, with initialize, ping and batches.

Docs

New pages: "Coming from AI Elements" (which Candor item does each job, what Candor adds, and how it sits beside shadcn's Trace and Message Scroller), "Durable approvals for long-running agents" and "Telling people they're talking to an AI".

Accessibility (WCAG 2.2 AA audit)

Every control now has a pointer target of at least 24×24 px (2.5.8), including the Dialog and Sheet close buttons, radios, chip remove buttons, tree chevrons, the approval's hash and the small text buttons. The look is unchanged, except that ProseDiff's accept and reject buttons now sit further apart.
AppLayout's side panel can be resized without dragging: a click on the divider steps through its widths, and Home and End jump to either end (2.5.7).
SignIn: pasting a code with a space or a dash ("123 456") works. Thread keeps a focused message clear of the "Jump to latest" button (2.4.11).
Scrolling code, excerpts, result tables, chart tables, logs and the restore dialog's lists can be reached and scrolled from the keyboard. Popovers fit a 320px screen, and charts show a clear focus outline.
What's left (the focus ring's contrast, segmented controls, toasts over focused controls, a few wide tables) is listed for 1.6 in internal/ACCESSIBILITY-2026-11.md, with the public conformance statement.

CLI (candor-ui 0.3.0)

Monorepos (pnpm and Turborepo, packages/ui plus apps/web) now work: - init from an app puts the theme in the shared UI package next to its CSS, imports it with a correct relative path (it used to be resolved from where candor-ui was launched), and adds the registry to both components.json files. - The licence key reaches shadcn when it runs in or writes to the shared package. - Run at the repository root, init, add, update and key stop, name the workspaces and say which --cwd to use; doctor checks every workspace with a components.json. - A root .gitignore that already covers .env*.local counts; React given as catalog: and Tailwind in the shared package are found; install commands use the project's package manager (pnpm --filter … add …). - candor-lock.json stays beside the app's components.json; update run from the shared package says where it is.
doctor says which base the project uses (Radix, Base UI or React Aria). Candor's components are built on Radix, so on React Aria it says what breaks and which of the project's primitives Candor's would replace. It checks that cn resolves, including after shadcn's migrate cn to the cn package, and gives the line and the install command when it doesn't.

Candor UI 1.4.0

Thu, 05 Nov 2026 00:00:00 GMT

The gaps the 1.3 blocks worked around, and a limit on the docs server. New optional props only: existing code renders as before, except that FailureClusters now prints a change of 0 as "0" instead of a dash (see below).

Knowledge and evals (Pro)

ProseDiff takes readOnly: the changes between two texts with no accept or reject, headed "Changes" with a count ("3 changes"), and onResolve is never called. Use it to show what changed between two published versions.
RetrievalInspector takes verb, the word before each passage's date, for what its readAt records: "Reviewed", "Published", "Synced". The default is still "Read". The knowledge-base blocks pass "Reviewed".
FailureClusters: - A cluster's delta can be null when there's nothing to compare with, shown as a dash and read as "change unknown". The new FailureClusterInput type (a FailureCluster whose delta may be null) is what it takes; FailureCluster itself is unchanged. - Changed: a change of 0 is now printed "0" and read as "no change since last period". Before, it showed a dash, the same as you'd now see for an unknown change. - since says what the change is measured against ("production's run"), read after "more than" and "fewer than". The default is "last period". New strings: since, unknown; more, fewer and noChange now take {since}. - The eval-dashboard blocks pass null before there's a production run to compare with, and since="production's run". Before, they showed no change. If your own code passed 0 to mean "nothing to compare with", pass null now. - FailureClusterInput lives in ops, so update ops with it: npx candor-ui update failure-clusters ops (a plain npx candor-ui update updates everything). candor-ui 0.2.3 says so when you leave one behind.

Docs MCP server

/mcp allows each client 120 messages a minute per server instance, counting every message in a batch, and answers past that with HTTP 429, Retry-After (readable from a browser) and a JSON-RPC error. A client is an IP address, or an IPv6 /64. createDocsMcpHandler takes rateLimit.

CLI (candor-ui 0.2.3)

update now says when an item it updates uses another installed item that stays on an older version, and gives the command to update it too. Before, it only listed dependencies you hadn't installed.

Candor UI 1.3.0

Thu, 05 Nov 2026 00:00:00 GMT

Docs for coding agents

Every docs page is also Markdown at its address plus .md: /docs/<name>.md for every item, /patterns/<slug>.md and /get-started.md. A page has the item's tier, its install command, its example with the import paths your app uses, every prop, function and type, and the LocaleProvider string keys. llms.txt lists them, and each web page links its Markdown version in its <head> and from a Markdown button. "Copy for a coding agent" copies the same text. Pages are built from the docs data, never from source; the build fails if a line of a paid item's code would appear in one.
A docs MCP server at https://candor.themethodic.com/mcp, free and read-only, with no licence key. Coding agents can search the docs, read any page, list items by group, read patterns and setup, and suggest_components for a task, with one install command. In Claude Code: claude mcp add --transport http candor https://candor.themethodic.com/mcp. Other clients add the URL as a remote (streamable HTTP) server. The agent skill and the Get started page point to it.

Composer (free)

tools puts your own controls in the composer's toolbar, after the attach button.

Dictation (Pro)

DictationButton and useDictation (new, dictation) let a person speak into the composer. It's opt-in: put <DictationButton value={value} onChange={setValue} /> in the composer's tools. Words appear in the box as they're recognised, then settle, and stay plain text the person can edit before they send. Nothing sends by itself. Editing while it listens keeps the edit. Emptying the box (sending) stops it with either engine and drops what it hadn't written yet, so nothing lands in the next message.
Audio goes only where your app chooses. With transcribe(audio, { lang, signal }), it records and hands the audio to your own speech-to-text. Without it, it uses the browser's speech recognition only where that runs on the device. allowBrowserService opts in to the browser's own service, which in some browsers sends audio to the browser maker.
While it records, the button is pressed and red, the state is written beside it and announced, and Escape is never taken from the composer. Where dictation can't run, the button is hidden, or with whenUnsupported="explain" it is locked with the reason. A blocked microphone, no microphone, nothing heard, a network or language problem, and a failed transcription each say what happened. It stops after maxSeconds (120, counted from when it starts listening) and when disabled, and pressing it again while the microphone is starting cancels it. Unmounting releases the microphone, even one granted after the component went away. Every word is in dictationStrings, under dictation in LocaleProvider.
Why Pro: the free tier stays the chat core, and dictation is an add-on to it. A separate item keeps free installs as they are, since a free item can't depend on a paid one. The free Composer gains only the generic tools slot.

Blocks (Premium)

Knowledge base (new, knowledge-base and knowledge-base-claude): - An agent answers only from published help-article versions and cites the article and version. The code checks each citation against what search_articles actually returned earlier in the same run, not against a question the model supplies, and the answer card shows the question that search was for. - Retrieval is deterministic word scoring, shown in the retrieval inspector. - Questions it can't answer are recorded as gaps. - The changes it drafts publish as a new version only after a person approves, and only against the version they were written for. - On a second page, people edit articles under the same conflict rule, mark them reviewed and dismiss gaps. - Data is kept in memory, or in Postgres in the kb_ tables.
Eval dashboard (new, eval-dashboard and eval-dashboard-claude): offline regression evals for an agent's versions. - A suite of cases, checked in code, runs against a version through a runner you plug in (setCaseRunner). The demo replays recorded outputs and says no model was called. A case the runner couldn't run is recorded as that, not as a fail. - The page shows the pass rate over runs, a run's scorecard against production's latest run, failure clusters, and regressions and fixes case by case. A second page compares any two runs. - The agent reads, compares and starts runs. Promoting a version needs a person's approval, and the server still refuses it when the version has no finished run on the current suite, production moved since it was asked, or its latest run fails a case production passes, naming the cases. - Data is kept in memory, or in Postgres in the evdash_ tables.

Candor UI 1.2.1

Thu, 05 Nov 2026 00:00:00 GMT

A patch: no component changes.

CLI (candor-ui 0.2.2)

Behind a proxy, key, doctor and update now send their own requests through HTTPS_PROXY (honouring NO_PROXY) on Node 24.14 or later. On Node 22.21+ and 24.0+, candor-ui says to set NODE_USE_ENV_PROXY=1; on older Node, to upgrade. shadcn already used the proxy.
update and the lockfile record matched each item file to an installed path by name and took the first match. When an item and one of its dependencies have a file of the same name, the file's type (ui, lib or component) now decides, and if that still leaves two, it stops rather than pick one.

Checks

CI now follows the Get started page in a brand-new Next.js app on every change: create-next-app, candor-ui init --yes, candor-ui add thread message composer, the "Render it" code as app/page.tsx, and next build, against that change's registry and CLI. It also checks that add recorded the items in candor-lock.json.

Docs

The agent skill explains theme nesting: dark and hc work on an inner element, light doesn't switch back inside a dark one.

Candor UI 1.2.0

Thu, 05 Nov 2026 00:00:00 GMT

App shell (Pro)

CommandPalette takes filter, passed to cmdk as (value, search, keywords) => score. The new matchEveryWord is a strict matcher: every word typed must start a word of the item's label, detail or keywords, in any order, ignoring case and accents. It reads keywords only, never cmdk's value, which holds ids.
Fixed: closing CommandPalette now puts focus back on what had it when the palette opened. Before, a palette opened by a shortcut (no DialogTrigger) dropped focus to the page. A chosen item now runs after focus is back and the closing animation is done, so an item that moves focus (to a tab, a field) keeps it there. Before, the return could undo it. onCloseAutoFocus lets you steer focus yourself.
AppLayout takes resizable (default true). With resizable={false} the panel stays at defaultPanel's width and the divider is a plain border with no handle.
SidePanel: a tab can carry a count (hidden at 0), read by screen readers as countLabel ("2 need you") or the sidePanel.count string (joined to the name by sidePanel.countAfterName), with countTone="attention" for things waiting on the person. actions puts buttons at the end of the tab row (hide the panel, open full width), outside the tab list.
SessionList takes groupBy (your own headings instead of pinned and days) with groupOrder, and showStatus to print each session's status in words with its dot. Session gains detail (a second line, such as what it is doing now) and statusLabel (your word for the status). Without these the list looks as before.

Artifact panel (Pro)

ArtifactPanel (new, artifact-panel) reads a document or file beside the work, as a SidePanel tab or full width. A document's text is read into safe blocks with markdownBlocks(text, { headings: true }), or you pass blocks. It is never rendered as HTML, so markup in a model's document stays text and its links aren't made. A file with no text shows its type and size, and an image shows the preview your app serves. onDownload gets the artifact's id and the chosen format (formats: Word, PDF…), and onFullWidthChange adds Open full width / Back to the panel. headingLevel (default 2) fits the title into your page's outline. New types in work: Artifact and FileFormat.

Variants (Pro)

Plan takes density="compact" for inside a thread: a smaller header and tighter rows, and a step's summary only while it's running or waiting (the "now" line). actions puts buttons under the steps (Pause, Stop) in any mode, beside Accept when proposed.
UsageMeters: a usage's estimate (your own figure, such as a quote) is a tick on the bar, printed under it as "Estimate: 2.6 USD", or with your estimateLabel ("My guess"). Without a limit it is printed with no tick. The meter never projects an estimate itself.
ApprovalDecision (new export of approval-request) is a decision the work stops for, with two answers. It shows the question, the facts, what carries on meanwhile, and an optional deadline with what happens if nobody answers. The two answers are equal buttons. Nothing is pre-selected and neither is styled as the default. The agent's pick is marked, not chosen. It covers recording, decided and failed states, and locked gives a reason. New types in work: Decision and DecisionChoice.
A setup gate from AccountState: steps lists what's left as a checklist in the card, children holds your own controls, and an action can be locked with its reason until the steps are done. email and onSignOut are now optional (the signed-in line shows when both are set). SetupChecklist takes bare to sit inside another card.

New components (Pro)

AgentActivity (agent-activity) shows who is working right now: each agent, what it is doing in plain words, and its state in words beside the dot (your statusLabel, or the status's own). An agent that isn't working shows only its state, with nothing made up for it to be doing. It is a panel list, not TaskTray's pill of background jobs. New type in work: AgentActivityEntry.
FileList (file-list) shows what the work produced. Each file has its type, size and state ("Checked", "Not yet checked", with a tone), Open for files the reader can show, and Download (a menu when there are several formats). Files can be grouped ("Result 2", "Sources"), with group headings at headingLevel (default 3). Nothing is a link: open and download go through your handlers. New type in work: Deliverable.
ResultCard (result-card) is a finished piece of work, handed over. It shows the answer first, as safe blocks, then a receipt of your own values as given (cost, time, what checked it), then the files, then your actions. Lines you don't pass aren't shown. New type in work: ReceiptLine.

Long histories

Thread takes virtualize (free): only the messages in or near view are rendered, each child being one item keyed by its key. The column stays a log, the message holding focus stays rendered as it scrolls away (with its neighbours, so Tab still reaches the next one, and by key, so it survives older messages being added), and Jump to latest works as before. The server and the first browser render show the newest 20, so hydration matches.
SessionList takes virtualize (Pro): only the rows in or near view, with their group headings. It starts from the top before it can be measured. Search still covers every session, and the focused row stays rendered.
Both use useVirtualList (new free item, use-virtual-list), which keeps measured heights by key, so a list that grows at either end keeps its place. Without virtualize, nothing changes.

Project workspace template (Premium)

project-workspace (Vercel AI SDK) and project-workspace-claude (Claude Agent SDK) install under app/project-workspace/. Each project is a conversation with an agent team. The rail lists projects grouped into Needs you, Projects and Finished (SessionList groupBy, with each state in words and a live line). The thread is in the middle. A fixed panel (AppLayout resizable={false}, 404px) has four tabs: Overview (spend against the limit with the agent's estimate marked as its own, steps done, AgentActivity), Plan, Files (FileList, with ArtifactPanel as the reader and Open full width) and History. The ⌘K palette uses matchEveryWord and opens panel tabs.
The rules it shows, enforced on the server: - No run goes past a project's spending limit without the person. At the limit the next run is refused and a decision opens: raise the limit, or finish with what's done. - While a decision waits (ApprovalDecision, nothing pre-selected), the agent doesn't work on the project. An answer is recorded once. - Files say whether they've been handed over. - The result (ResultCard) puts the answer first. Its receipt comes only from what was recorded: spend against the limit, steps done, and time from start to hand-over.
Spend comes from the AI SDK's token counts at list price (a model with no price set is refused, since its spend couldn't be kept to the limit), or from the Claude Agent SDK's own total_cost_usd. That figure is the session's running total, so each run adds only its change since the last total seen for the session. A file saved again under the same name replaces the earlier text. An answered decision stays in the thread, decided, with focus on it.
Storage runs in memory with no setup, or on Postgres through Drizzle when DATABASE_URL is set (tables start with workspace_, with migrations and a seed). It is tested on both, including two answers racing and two questions asked at once.

Candor UI 1.1.1

Thu, 05 Nov 2026 00:00:00 GMT

Fixed

Getting started works as pasted. /get-started has a "Render it" step, and every docs example is shown and copied with the import paths an app has after add (@/components/…, @/lib/…) and "use client". A test checks every example's imports against where shadcn installs each file.
The theme wins over shadcn's defaults. In a fresh Next.js app, the colour blocks and .dark variant that shadcn init writes came after the candor.css import and replaced Candor's theme (only system dark mode survived). candor-ui init --yes now comments out shadcn's default :root and .dark colour blocks and its dark variant; doctor flags them. Overrides you wrote yourself, and a dark variant of your own, are left alone, and overriding Candor's tokens after candor.css works as before.
candor-ui add records what it installs. Most fresh installs were reported as "already installed, with changes" and left out of candor-lock.json, so update couldn't merge them. The CLI is 0.2.1.
candor-ui key checks the key with the registry (10-second timeout) and says whether it's valid and for which tier; doctor does the same.
A paid item without a key now says to run npx candor-ui key <your key> and where the key is; errors carry a message so shadcn no longer prints "undefined".
One install story: docs pages, llms.txt and the skill use the candor-ui CLI, say where files land and which import paths to use, and the skill covers AG-UI. Twelve items' one-line descriptions now describe the item, not a helper in its file.

Candor UI 1.1.0

Thu, 05 Nov 2026 00:00:00 GMT

Languages and right to left

LocaleProvider (new free item, locale) sets the interface's words, the locale for dates and numbers, and the text direction. Every fixed string in the kit (labels, buttons, empty states, screen-reader text, "just now") is in a table per component, English by default, and you override any of them by the component's name: <LocaleProvider locale="fr" strings={{ thread: { jumpToLatest: "Aller au plus récent" } }}>. Strings take {name} placeholders and plural forms, so overrides stay plain data. Each docs page lists its keys. TermsProvider still names your nouns.
Right-to-left layouts: components use logical spacing and edges (ms-, ps-, start-, border-s), directional icons mirror, tree, inbox and the layout's resize handle swap their arrow keys, and AppLayout's navigation and panel sheets slide in from the matching sides. Sheet's side stays the physical edge you name. dir follows the locale (Arabic, Hebrew, Persian, Urdu…) or is set on the provider; set it on <html> as well.
RelativeTime takes format="date" | "datetime" | "time" for an absolute time, and its words and units follow the locale.

Messages

Message takes actions: false hides the row under an agent reply (copy, retry, rating), a node replaces it. Either way the model and cost stay visible, on their own line (MessageAttribution).
Message's parts are exported: MessageHeader (name, detail, time, and a slot for more), MessageBody (reasoning, blocks, the streaming caret) and MessageFooter (stopped and failed states, sources, who checked it, actions), to rebuild a message your way. App content still goes in a card block, so messages stay plain data.
Thread pieces (free): ThreadDivider marks a day ("Today", "Yesterday", a date) or a chapter; ThreadEvent is a quiet centred line for something that happened ("Sam joined"), with an attention tone and a time, and system messages are now drawn with it; FoldedTurns folds a run of turns into one line with your summary and opens them in place.
Attachments (free, attachment-preview): a new attachments message block shows sent files as tiles, with an image preview when your app supplies a previewUrl, an icon by type otherwise, and the size in the locale. A file is never a link: onOpenAttachment on Message makes each tile a button. AttachmentChip is the composer's chip, AttachmentList a row of tiles. Attachment gains optional mediaType and previewUrl.
Composer attaches files that are pasted or dropped on it (with a drop target while dragging), and takes accept for the picker.
New block kind. MessageBlock has a new kind, attachments. If you switch over block kinds in your own code, the default branch the 1.0 notes asked for covers it; without one, TypeScript will point at the switch.
Syntax highlighting in Payload (free, highlight): code is split into tokens (keywords, strings, comments, numbers, keys, tags) and rendered as spans of text, never HTML, by a small built-in tokenizer for JS/TS, Python, SQL, JSON, shell, YAML, CSS, HTML/XML, Go, Rust, Java and C. Off by default so nothing changes: turn it on with <Payload highlight> or data-syntax="highlight" on <html>. Its colours are in the theme's contrast checks.
Payload takes bare: just the code, without the frame, language label or copy button, for inside a card.

Theme

Size tokens on the --cd-* scheme: --cd-text-prose (conversation text, Tailwind text-prose; it follows --cd-text-md, 14px, as before), --cd-thread-width (48rem, the message column and composer) and --cd-sidebar-width (16rem, AppLayout's sidebar). Set them after candor.css to fit your brand.
A compact preset: data-density="compact" on <html> or any container gives 14px conversation text, 13px body and label text (text-base and below; headings keep their sizes), a 44rem thread and a 14rem sidebar.

Updates

npx candor-ui update (CLI 0.2.0) updates installed items and keeps your changes, with a three-way merge and a clear conflict report; add now writes candor-lock.json. See "How versions work" above.
The registry serves every release at /r/v/<version>/<name>.json, gated exactly like the latest, from 1.0.0 on.

Fixed

Dates and numbers no longer cause hydration mismatches when the server's locale or time zone differs from the browser's. Without a locale, numbers render as en-US on the server and switch to the browser's locale after hydration, and absolute times show their ISO date (UTC) until then. Set locale and timeZone on the provider to render the final text on the server.
Counts of one read in the singular where the English used to say "1 steps", "1 runs", "1 tests".
Product words that leaked from another app are gone: Know's labels read "Knowledge sources", "Nothing has been read yet.", "What was retrieved" and "Add knowledge"; doc comments no longer mention Salesforce or Know.
MetadataDiff is now ChangeDiff, labelled "Changes"; the old name still works and is deprecated until 2.0 (the item is still installed as metadata-diff). Doc comments in the work and chat types no longer use Salesforce examples.
AccessRequest shows the environment a request was sent for by its name (and Production or its detail), not the id onSend returned.
BulletBar bands now shade from the end when higherIsBetter={false}, so the darkest end is always the worst.
EmailPreview shows an email inline, without a whole <html> document, with its title at your page's heading level. renderEmail and EmailLayout take the email's language and words.
ChartFrame and AppLayout take defaultWidth, used until they can measure themselves (on the server, and in jsdom tests, which measure everything as 0). ChartSizeProvider sets it for every chart inside.
SsoSetup and SubscriptionStatus take a label for their landmark, so two on one page can be told apart.
Dates in the audit log, downgrade impact and subscription status use the locale's medium date style ("Nov 5, 2026"), the same as the rest of the kit.

Notes

Components that now read the provider call hooks, so about two dozen that were server components gained "use client". They still render in React Server Components apps. EmailLayout stays server-safe: it takes strings and lang as props, and so does renderEmail.
Text the adapters produce (tool errors, approval titles), the A2UI standard cards and applyA2uiMessage's diagnostics are data, not interface chrome, and stay English in this release.

Candor UI 1.0.1

Thu, 05 Nov 2026 00:00:00 GMT

Fixed

npx candor-ui init --yes sets up shadcn in a new project without stopping for questions; at a terminal, init runs shadcn's own setup. The CLI is 0.1.2.
Pro's pricing card counts what a Pro key unlocks (the full-stack blocks and templates are Premium).
Docs pages for blocks no longer scroll sideways on phones, inline code reads as code, and names read as written (AG-UI, MCP, SSO).
Unknown pages answer 404.
A malformed licence key is reported as not valid, and the no-key message says where to buy one.

Candor UI 1.0.0

Thu, 05 Nov 2026 00:00:00 GMT

The first public release.

Components

201 registry items: chat, agent work (plans, approvals, diffs, runs, recovery), the app shell, team and admin screens, knowledge, data and charts, ops and cost, evals and billing.
Honest by design: unknown values show as unknown, a control that can't be used says why, nothing is pre-selected in a decision, and model output is never rendered as HTML or a clickable link.
Light, dark and high-contrast themes, with 120 contrast checks. Every component has a live docs example, and CI runs axe on each one; tab lists, the toast and side panel also have keyboard and screen-reader tests.
Works in Vite and in Next.js with React Server Components ("use client" where needed, a hydration-safe clock).
Works in shadcn projects on Radix or Base UI styles: primitives take asChild and Base UI's render.

Adapters and agent UI

Vercel AI SDK 7, Claude Agent SDK and AG-UI adapters, all with the same shape: messages, a composer, and tool calls waiting for a person.
A person's own words are kept exactly as typed (a plain block: line breaks kept, nothing parsed); only an agent's text is read as safe markdown. markdownBlocks(text, { headings: true }) turns # lines into heading blocks. If you switch over MessageBlock kinds in your own code, give it a default branch: new kinds can arrive in a minor release.
The inline node for a value read from the user's system is measured (it was orgData, which still works and is deprecated until 2.0).
A2UI surfaces drawn with Candor's components, and an MCP Apps frame that runs only behind a separate-origin sandbox.

Blocks and templates (Premium)

Eight full-stack blocks, each for the Vercel AI SDK and the Claude Agent SDK: approval-gated change, plan-build- review, run console, eval review loop, cost guard, agent admin, audit and data controls, human handoff.
Three templates: an agent ops console, an approvals inbox and a support copilot.

For coding agents

A Candor skill (npx skills add MethodicDev/candor), llms.txt and llms-full.txt, and setup for shadcn's MCP server.

Licences

The free tier (43 items) is MIT. Everything else is under the Candor UI Commercial Licence.

Candor UI changelog

Candor UI 5.2.0

Corrected in the 5.1.0 notes

New items (Pro)

Components

@candor-ui/react 5.2.0

CLI 3.2.0

Docs and the docs MCP

For maintainers

Candor UI 5.1.0

Corrected in the 5.0 upgrade notes

New items (Pro)

Components

@candor-ui/react 5.1.0

Motion (Pro motion-drawings)

CLI 3.1.0

Docs and the docs MCP

For maintainers

Candor UI 5.0.0

Upgrading from 4.x

New items (Pro)

Components

@candor-ui/react 5.0.0

CLI 3.0.0

For maintainers

Candor UI 4.5.0

New items (Pro)

Components

Motion (Pro motion-drawings)

CLI 2.3.1

Docs and the docs MCP

Site and repository

For maintainers

Candor UI 4.4.0

New items (Pro)

Components

Motion (Pro motion-drawings)

CLI 2.3.0

Docs and the docs MCP

Theme builder

Site and repository

For maintainers

Candor UI 4.3.0

New items (Pro)

Components

CLI 2.2.1

Site and repository

Candor UI 4.2.0

New items (Pro)

Components

CLI 2.2.0

Docs and the docs MCP

For maintainers

OrgSmith pack (in-house, not published)

Candor UI 4.1.0

The motion rule

Theme builder

New items

Components

CLI 2.1.0

Docs and the docs MCP

Site, registry and repository

For contributors

Candor UI 4.0.2

CLI 2.0.1

The upgrade pages

CLI 1.0.1, for 2.x → 3.0

Docs

Candor UI 4.0.1

Candor UI 4.0.0

Upgrading from 3.x

Primitives on Base UI

Components and the free tier

Blocks and templates (Premium)

@candor-ui/react 4.0.0

CLI 2.0.0

Docs

Theme builder

For contributors

Candor UI 3.0.0

Motion (Pro `motion-drawings`)

Motion (Pro `motion-drawings`)

Motion (Pro `motion-drawings`)