Changelog
Looking ahead? The roadmap says what is being built; this page is the record of what shipped. To follow releases in a feed reader, subscribe to the changelog feed. Several releases can share a date (6.1.2, 6.1.3 and 6.2.0 all came out on 15 November 2026): each is a version of its own, and the higher number is the later one.
What changed in Candor UI, newest first.
How versions work
Candor UI follows semantic versioning for the kit as a whole:
- Patch (1.0.1): fixes only. Safe to take.
- Minor (1.1.0): new components, blocks, templates and optional props. Existing code keeps working, with two limits. A minor can add a kind to
MessageBlock, which aswitchover a block'skindhandles with adefault. And 6.1.0 is the one minor with breaking changes, to Pro items: plainnpx candor-ui updatedoesn't take a project across it,update --to 6.1.0lists each break before it installs, and most come with a codemod. - Major (2.0.0): a change that can break code you installed, such as a renamed or removed prop. Each one is listed here with what to change.
Because shadcn installs copy the code into your app, you own it and can change it. To take a new version without losing your changes, install with npx candor-ui add, which records each item's version and file hashes in candor-lock.json, and later run npx candor-ui update: files you haven't touched are replaced, files you changed get a three-way merge against the copy of each file kept in .candor/base/, and where your change and ours touch the same lines you get conflict markers to resolve.
The registry serves the current release: https://candor.themethodic.com/r/<name>.json, and the same file at /r/v/<version>/<name>.json, with the same licence check. Earlier releases aren't served. What you installed stays in your project, and CLI 4 keeps a copy of each file in .candor/base/, which update merges against when you move to the next release. The free items' earlier versions stay on npm as @candor-ui/react. Your licence includes every version of Candor UI we publish, major versions included.
6.2.0 - 2026-11-15
Charts write money exactly and take your own text per value, the usage glance takes slots, and Thread lands a new reply at its start when it virtualizes. With @candor-ui/react 6.2.0.
`@candor-ui/react` 6.2.0
Only these free items change.
- Thread lands a tall new message at its start when it virtualizes (thread).
landNew="start"now works withvirtualize. In a long history where only the messages near the view are drawn, a new message taller than the view stops at its start, and a shorter one is followed to its end. The rules are the same as withoutvirtualize: the reader's own message is followed to its end, and nothing moves once the reader has scrolled up.
Pro
- Charts write money exactly (BarChart, LineChart, DonutChart, Heatmap, ShareBar, MiniBar, BulletBar, ProgressRing, StatCard, ComparisonView). A measured amount such as $0.28 read "$0" in tooltips and tables. Now tooltips and tables are exact: a fraction keeps its cents ("$0.28", "$4.50") and a whole amount has none ("$20"). Axes, labels, legends and figures stay compact from 1,000 up, in the locale's own units ("$1.2K", "₹1.5L"), and never write a small amount as "$0". The symbol comes from the locale. Axis ticks take more digits when two would otherwise read the same, and BarChart's and LineChart's value axis widens to fit longer labels such as "150.000 €". A StatCard figure that counts up is written to its own decimals while it counts.
- Each of those charts takes
currency, an ISO 4217 code that defaults to USD, and so do aKpiand aComparisonRow. If your amounts aren't in US dollars, pass it. - Charts take your text per value (BarChart, DonutChart, ShareBar). BarChart's series take
valueTexts, lined up withvalues, and DonutChart's and ShareBar's parts takevalueText. Your text replaces the formatted number in the tooltip, the table, the name read out, and the label or legend. The numbers still draw the chart, axis ticks and totals stay formatted, and a value that is null or not a finite number still reads as no data. - The usage glance takes your controls (usage-meters).
UsageMeter's glance takesleadingandtrailing, for controls at the start and end of the line such as a help button and an edit button. They sit outside the label's link. A control in a slot needs its own accessible name, and one shown on hover must also show on keyboard focus. The bar and ring ignore them, with a warning in development.
6.1.3 - 2026-11-15
With @candor-ui/react 6.1.3: numbered lists in model text keep their numbering. No CLI change.
`@candor-ui/react` 6.1.3
Only these free items change.
- Numbered lists in model text keep their numbering (safe-markdown, message-content). Blank lines between items no longer end a list, numbered or bulleted, so the numbers go on. A fenced code block indented two columns or more past an item is drawn inside that item, and the list goes on after it. A numbered list that starts at another number, such as
3.after a paragraph, is drawn from that number, and copying the message keeps the same numbers. While a reply streams, a list doesn't restart and rejoin as a blank line or an item's code arrives. - A list block gains
start(its first number, left out when it is 1 or isn't a safe integer), and a block under an item can be apayload. If you draw blocks yourself, set<ol start>fromstart, and give aswitchover a nested block'skindadefaultbranch.
6.1.2 - 2026-11-15
With CLI 4.2.0 and @candor-ui/react 6.1.2: the registry serves only the current release, 6.0's codemods and the Upgrading to 6.0 page are removed, and nested lists in model text are drawn nested.
CLI 4.2.0
update,addandmigratework with Candor 6.1 and later. 6.1 is the first release CLI 4 installs with a copy of each file in.candor/base/, which is whatupdatemerges against now that the registry serves only the current release. On a project before 6.1 they change nothing and say how to move on: commit, deletecandor-lock.json, run the codemods of the releases you crossed on your own code (with no lockfile, each runs all of its release's), thennpx candor-ui@4 add <your items> --overwriteand take your edits back from git. An item 6.1 removed can't be added; Upgrading to 6.1 says what replaced it.- On a project on 6.1 or later but behind the current release, no command stops on an earlier version the registry no longer serves.
updatemerges against.candor/base/, and for an item without a usable copy stops before changing anything and namesgit checkout -- .candor/baseornpx candor-ui@4 add <item> --latest --overwrite.addnamesupdate, or--latest.infoshows the current page and says so.verify --remotechecks the items at the current release and names the others as not checked.list --installed,theme check,add --dry-run's preview andmigrate's list of new strings use.candor/base/where they can, and otherwise say why they can't compare. migrateno longer has 6.0's codemods:data-types,propsandheadings, and 6.0's rows ofstrings-keys.npx candor-ui@4.1 migrate 6.0.0runs them. 6.1's (items,strings-keys,tokens) stay.mcpanddoctorno longer mentionitem_changes, which the docs server no longer has.
Registry and site
- The registry serves only the current release.
/r/versions.jsonlists it;/r/v/<another version>/…answers 410 with a line namingnpx candor-ui@4 update, which merges against your project's.candor/base/and needs no earlier version. If you install with shadcn from a versioned URL, use the current one. - The docs MCP server has twelve tools:
item_changesis gone, and a page asked for at another version is the current one, which it says. - Upgrading to 6.0 is gone:
/upgrading-to-6and its.mdredirect to 6.0.0's section of this changelog. Upgrading to 6.1 stays as the list of 6.1's changes and their codemods. - The docs no longer have a version list: only the current release's are published.
`@candor-ui/react` 6.1.2
Only these free items change.
- Nested lists in model text (safe-markdown, message-content):
markdownBlocksreads an item indented two columns or more past the item above it as nested in that item, ordered and unordered in each other, to four levels; an item deeper than that is one more item of the fourth level, with its text kept. A tab counts as four columns. An indented line that isn't an item continues its item, and after a blank line is a paragraph inside it. A list in a quote is read as a list, and a quote whose lines include a list is split into paragraphs around it. Before 6.1.2 each of these was a flat item, or a paragraph after the list. MessageContent draws what is under an item inside it, with hollow markers on a nested unordered list, and copies it as lines indented by its marker's width a level. The Claude Agent SDK adapter places a citation after the deepest last item. While a reply streams, an item is drawn at its own level from its marker on. - A list block gains
nested(what sits under each item) and a quote blocklists(which of its paragraphs is a list); both are left out when there is nothing to put in them, so a flat list's block and markup are as before. If you draw blocks yourself, drawnestedinside each item; left undrawn, the nested items are missing, not flattened. - Thread lands a tall new message at its start (thread): with
landNew="start", a new message taller than the view, whether it arrives whole or grows there while it streams, stops the view at its start and the thread stops following, so the opening of a long reply stays in view and Jump to latest shows; the reader's own message (data-role="user") and anything shorter than the view are followed to the end. A reply that takes the place of a placeholder row lands as a new message does. If you draw the reader's messages yourself rather than with Message, mark themdata-role="user", or they can land too. The default,"end", follows as before. The newest message in a thread now carriesdata-newest, so you can find it without relying on Message'sdata-slotanddata-role.
For maintainers
- A released version's files are held to
scripts/released.json(everypublic/rfile and docs page by hash), written bynode scripts/released.mjs --writeat RELEASING step 6 and checked bygenerated.mjs --check. The snapshot store in Vercel Blob, its scripts and workflow, and the upgrade fixtures and harness are gone. released.mjs --writewon't write over a record of the same dated version whose files differ (--forcedoes, for a Release commit not yet merged), and--checkalso holds the record to the one taggedv<version>.release:checkwarns on a note marking wording only the owner gives in any file that ships or is served, and fails on one under--fullor once the version is dated.
6.1.1 - 2026-11-14
No package of the kit changed. Only the candor-ui CLI did, to 4.1.0. The registry’s items and @candor-ui/react are as in the release before, and the package wasn’t published again, so it keeps the earlier version number.
With CLI 4.1.0: 4.0's and 5.0's codemods, and the Upgrading to 3.0, 4.0 and 5.0 pages, are removed. No change to the kit's items.
CLI 4.1.0
migrateno longer has 4.0's and 5.0's codemods and rows:as-childandtypes-dataare gone, andprops,strings-keys,headingsandtokenskeep only 6.0's and 6.1's rows.migrate 4.0.0,migrate 5.0.0,migrate as-childandmigrate types-datasay they are CLI 3's and namenpx candor-ui@3. CLI 4 already refused a project before 5.4 and named CLI 3, so nothing changes for a 5.4 or 6.x project:update --to 6.1.0, thenmigrate 6.0.0andmigrate 6.1.0, work as before. A project before 5.4 usesnpx candor-ui@3to reach 5.4 first.theme checkstill reports a token 4.0 renamed (--sunken) as an error, and now says the new name to use (--cd-sunken) in place of namingmigrate tokens.scripts/breaking.json, and so each item'smeta.breakingand/r/breaking.jsonfrom 6.1.1, has only the 6.0.0 and 6.1.0 entries. The snapshots of earlier releases are unchanged, soupdate --to 6.1.0prints what it printed.
Site
- The Upgrading to 3.0, 4.0 and 5.0 pages and their Markdown are gone:
/upgrading-to-3,-4and-5(and their.md) redirect to that release's section of the changelog, which keeps its upgrade notes. Upgrading to 6.0 and Upgrading to 6.1 stay. A project before 5.4 moves to 5.4 withnpx candor-ui@3first, as the CLI's README says.
6.1.0 - 2026-11-14
One component per job, tables in model text, and upgrades that keep their own history. With CLI 4.0.0 and @candor-ui/react 6.1.0.
Seven Pro items are folded into the items that do the same job: DecisionCard and DecisionBar join DecisionReview in decision-review, PermissionMode takes ReviewLadder's place with your own levels, a docs example takes ReviewCanvas', UsageMeter draws one usage as a bar, a glance or a ring in usage-meters, ChangeDiff picks its file from a tree, and Digest says what happened since the last visit. This is the one minor release that breaks Pro items; each break has an entry below, and CLI 4's codemods make most of the changes. Model text reads as it was written: a fenced block keeps its language and is highlighted in it, a pipe table is a table and > lines are a quote, text only as always. CLI 4 keeps a copy of each file as Candor installed it in your project, so update merges against your own history. The kit has 413 items, and Pro has 382 of them, the 76 free ones included.
Breaking
Each entry has its id in scripts/breaking.json (the same entries update --to 6.1.0 prints, and the Upgrading to 6.1 page lists), what changed, and what to do. Only message-block-kinds is on free items.
decision-card(codemoditems; approval-request, decision-review; Pro): ApprovalDecision is DecisionCard, indecision-reviewbeside DecisionReview and DecisionBar, andapprovalDecisionStringsisdecisionCardStrings. Its props, its markup anddata-slot="approval-decision"are unchanged, and it still takes aDecision. ApprovalRequest stays inapproval-request.npx candor-ui@4 migrate itemsmoves each import and renames its uses,<ApprovalDecision …>included.decision-card-strings(codemodstrings-keys; approval-request, decision-review; Pro): theapprovalDecisionstrings are thedecisionCardtable, with the same keys and words. An override underapprovalDecisionisn't read.migrate strings-keysrenames the table in a strings object written as a literal and lists one built at run time.decision-bar-merged(codemoditems; decision-bar, decision-review; Pro): thedecision-baritem is gone. DecisionBar,decisionBarStringsanddecisionBarChangeGuardare exported bydecision-review, with the same props, strings and markup.DecisionBarActionandDecisionReviewActionare one type,DecisionAction.update --to 6.1.0installsdecision-reviewif you haven't got it, and keeps decision-bar's file as your own;migrate itemspoints each import atdecision-reviewand renames the action types. Delete decision-bar's file once nothing imports it.review-ladder-removed(codemoditems, which lists; review-ladder, permission-mode; Pro): ReviewLadder andReviewLevelare removed. Draw your levels with PermissionMode: each level is one of yourmodes(itslabel,detailandlocked),valueismode,onValueChangegets the mode's id, andlabel="Review level"names the control. PermissionMode's newlabelprop is the control's name in place of "Permission mode".migrate itemslists each<ReviewLadder>andReviewLevelimport with this mapping. A ladder with noonValueChangebecomes a PermissionMode with noonValueChange: the other modes say "Can’t be changed here", or passlockedwith your reason. Delete review-ladder's file when you have moved.review-ladder-strings(codemodstrings-keys, which lists; review-ladder, permission-mode; Pro): thereviewLadderstrings are gone.migrate strings-keys(andmigrate 6.1.0) lists each override: the rungs' words are your modes'labelanddetail, andlabelis PermissionMode'slabel. Then delete them.review-canvas-removed(codemoditems, which lists; review-canvas; Pro): ReviewCanvas is removed. ApprovalRequest's docs have "Approve with the evidence beside it", which composes Plan, LogStream, ChangeDiff, BlastRadius, Reasoning and ApprovalRequest: copy it into your app, keeping its rule that a tab with nothing for the chosen step says so.migrate itemslists each<ReviewCanvas>and import. Delete review-canvas's file when you have moved.review-canvas-strings(codemodstrings-keys, which lists; review-canvas; Pro): thereviewCanvasstrings are gone, and nothing reads them.migrate strings-keyslists each override; delete them.usage-meter-variants(codemoditems; usage-glance, usage-ring, usage-meters, portfolio-card; Pro): UsageGlance and UsageRing are UsageMeter'sglanceandringvariants, inusage-meters, with the props they took (periodandhreffor a glance,estimateBasisfor a ring,unknownandpausedfor every variant). They draw the same markup anddata-slotvalues, withdata-varianton the root. UsageMeters is unchanged. PortfolioCard draws its line with UsageMeter's glance, so it needsusage-metersin place ofusage-glance.update --to 6.1.0installsusage-meters;migrate itemswrites<UsageGlance …>as<UsageMeter variant="glance" …>and<UsageRing …>as<UsageMeter variant="ring" …>. A prop for another variant is ignored, with a warning in development. Delete the two old files once nothing imports them.usage-meter-strings(codemodstrings-keys; usage-glance, usage-ring, usage-meters; Pro): theusageGlanceandusageRingtables are gone and their keys are inusageMeters. The glance's and ring'susedOfLimitisusedOfLimitWords, and the ring'sestimateValueisestimateWithBasis; the bar's words don't change.migrate strings-keysmoves each override, and where the glance and the ring worded a key differently it writes the glance's and lists the ring's for you to choose.change-tree-merged(codemoditems; change-tree, change-diff; Pro): thechange-treeitem is gone. ChangeTree,ChangeTreeFileandchangeTreeStringsare exported bychange-diff, with the same props.migrate itemsmoves the imports, and lists each file with a ChangeTree beside a ChangeDiff, which can become one<ChangeDiff navigation="tree">by hand if you want.change-tree-strings(codemodstrings-keys; change-tree, change-diff; Pro): ChangeTree's chips readchangeDiff.create,updateanddelete(the same words), andchangeTree.create,updateanddeleteare gone.migrate strings-keysmoves an override of them tochangeDiffwherechangeDiffdoesn't set them, and lists it where it does.away-digest-merged(codemoditems, which lists; away-digest, digest, digest-email; Pro): AwayDigest andDigestItemare removed; Digest does the job. Draw aDigestwithsince, your heading asdigest.title, the waiting items inneedsYou, the failed ones infailedand the finished ones indone(a finished item'sdetailgoes into its title, or is left out:DigestDonehas none).onOpen(id)is unchanged. The since line reads "Since you were last here · 3 hours ago · 5 things", as AwayDigest's did.migrate itemslists each<AwayDigest>andDigestItemwith this mapping. Delete away-digest's file when you have moved.away-digest-strings(codemodstrings-keys; away-digest, digest; Pro): theawayDigeststrings are gone.sinceLastHereisdigest.since,failedisdigest.failedandnothingHappenedisdigest.nothingSince, whichmigrate strings-keysmoves.whileAwayis yourdigest.title; the sections are headed bydigest.needsYou("Needs you") anddigest.done("What was done");thingsisdigest.total, whichmigrate strings-keysalso moves, andgrouphas no counterpart.digest-open-rows(by hand; digest; Pro): Digest callsonOpenfor a done or failed row withouthreftoo, not only a needs-you row, so withonOpenpassed those rows are buttons. Give them anhref, open them inonOpenby id, or leaveonOpenout.DigestDone'sbyis optional, and a done row without it names no one: code that readsdone.byneeds a check, which the type check finds.consolidation-motion(codemodtokens; usage-glance, usage-ring, approval-request, decision-review, review-ladder; Pro):--cd-motion-usage-glance-fillis--cd-motion-usage-meters-glance-filland--cd-motion-usage-ring-fillis--cd-motion-usage-meters-ring-fill, each with its suffixes. DecisionCard's answer and its mark read--cd-motion-decision-review-card-outcomeand-card-outcome-mark, where they read ApprovalRequest'soutcomeandoutcome-mark, which ApprovalRequest keeps.--cd-motion-review-ladder-rungis gone.migrate tokensrenames the usage tokens, adds a DecisionCard declaration beside each approval-request outcome one (keep the one you meant), and lists the ladder's as removed. Nothing fails to build.message-block-kinds(by hand; chat, safe-markdown, message-content; free):MessageBlockgainstableandquote, so aswitchover a block'skindthat ends in anevercheck fails the type check until it handles them or has a default. From 6.1 a minor may add a kind, andMessageBlock's doc comment says so. A model's pipe table now draws as a table, its>lines as a quote, and a fence in a language Payload highlights is highlighted when highlighting is on: check any CSS that matched those as paragraphs or plain code.
Upgrading from 5.4 and 6.0
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@4 update --to 6.1.0 --dry-runprints what 6.1 (and, from 5.4, 6.0) changes for the items incandor-lock.json, with the merges it would make, and writes nothing. - Update:
npx candor-ui@4 update --to 6.1.0updates every item, merging your changes into Candor's, installs the item that takes over from one 6.1 removes, and keeps the removed item's file as your own. It writescandor-lock.jsonas version 2 and a copy of each installed file in.candor/base/: commit both. - Migrate 6.0.0, if you are coming from 5.4:
npx candor-ui@4 migrate 6.0.0runs 6.0's codemods (data-types,props,strings-keys,headings), as on Upgrading to 6.0. - Migrate 6.1.0:
npx candor-ui@4 migrate 6.1.0runsitems,strings-keysandtokensfor the entries on your installed items. Each lists what it couldn't change under "Left for you".--dry-runshows it first. - Finish by hand: make the changes the "Left for you" lines name and those marked "by hand" above, then delete the removed items' files once nothing imports them.
- Type-check and build:
npx tsc --noEmitand your build, then your tests. - Verify:
npx candor-ui@4 verifychecks each installed file and its base copy againstcandor-lock.json, without the network.
A project on 6.0.x has run 6.0's codemods, so it skips that step. Plain npx candor-ui@4 update on 6.0.x stays on 6.0 and says that 6.1.0 has breaking changes; --to 6.1.0 takes it there. A project before 5.4 takes Upgrading to 6.0's commands with CLI 3 first (npx candor-ui@3 update --to 5.4.0). From now on run every command as npx candor-ui@4: CLI 3 can't read a version-2 lockfile.
Components (Pro)
- DecisionReview's page says which of its three components fits: one decision with two equal answers (DecisionCard), a mixed queue reviewed one at a time (DecisionReview), or the bar that decides the item on screen (DecisionBar).
- PermissionMode gains
label, the control's name in place of "Permission mode", andpermissionMode.currentNamed("{label}: {mode}"), the compact button's name whenlabelis given. Itsmodeis the mode in force, as the app or the agent reports it. WithoutonValueChangeit only shows the mode: the other modes are unavailable (aria-disabled, notdisabled) and say "Can’t be changed here", the newpermissionMode.readOnlyLocked. Passlockedfor your own reason. - UsageMeter (
usage-meters): one usage against its limit as a bar (UsageMeters' card, the default), a one-line glance or a ring. The bar takesunknown("Not known yet", or "Not known yet, of {limit}", with no bar and never zero) andpaused(an icon and "Paused", or "Paused: {reason}"). A figure that isn't a finite number is drawn as not known in all three, and in UsageMeters' cards.usageMetersgains 13 keys. - UsageMeter's ring fits its figure (KIT-366): the ring is 10rem across, or as wide as a narrower container, and stays square. The figure is sized with the ring, 30px for a short figure at 10rem and smaller for a longer one, and when one line would be too small its unit goes to a second line. A figure is never cut off, ellipsised or rounded to fit. Nothing to do: a ring in a narrow column now fits it.
- UsageMeter's ring measures its figure (KIT-375) once it is on screen, again when the figure changes and when the fonts have loaded, so a figure in a narrower font is drawn larger and one in a wider font still fits. Nothing to do.
- ChangeDiff takes
navigation="tree", which picks the file from a ChangeTree beside the diff (above it when the item is narrower than 42rem), andtreeLabel, the tree's name. - Digest takes
since, drawn under the title as "Since you were last here", how long ago and how many things need the person, failed or were done (digest.total, "{count} things"), afailedsection (DigestFailed) under a heading with a cross icon in the destructive tone, andaton needs-you, failed and done rows, drawn as relative times.digestgainssince,failed,nothingSinceandtotal. - DigestEmail writes the failed section;
digestEmail.failedis added. - ShipReview's
windowdoc no longer names a review level. - NavRail (KIT-369):
NavItemandTabBarDestinationare declared inapp-layout;app-sidebar,tab-barandnav-railexport them by name, so every import still works. Installingnav-railno longer bringsapp-sidebar,person-menuortab-bar. Nothing to do; a project that already has them keeps them.
Blocks (Premium)
- human-handoff (both versions): the inbox's "since your last visit" is a Digest titled "While you were away" (
humanHandoff.awayTitle).sinceLastVisitandvisitreturn{ since, needsYou, done }in place of{ since, items }, so the inbox route'sdigestfield has that shape. No stored data changes.
New exports
DecisionCard,decisionCardStringsandDecisionAction(decision-review, Pro);DecisionBar,decisionBarStringsanddecisionBarChangeGuardmove there.UsageMeter(usage-meters, Pro).DigestFailed(digest, Pro).ChangeTree,ChangeTreeFileandchangeTreeStringsmove tochange-diff(Pro).NavItemandTabBarDestinationare declared inapp-layoutand exported bynav-railtoo (Pro).- Removed:
ApprovalDecision,approvalDecisionStrings,DecisionReviewAction,DecisionBarAction,ReviewLadder,reviewLadderStrings,ReviewLevel,ReviewCanvas,reviewCanvasStrings,UsageGlance,usageGlanceStrings,UsageRing,usageRingStrings,AwayDigest,awayDigestStringsandDigestItem.
`@candor-ui/react` 6.1.0
The free items are unchanged but for these, and mcp-input's doc comments, which name DecisionCard.
- Model code is highlighted in its language (safe-markdown, payload):
markdownBlockskeeps a fence's language, lower-cased, with common aliases mapped (pyis python,tsandtsxtypescript,jsandjsxjavascript,sh,bashandzshshell,ymlyaml), for every language Payload highlights; one it doesn't is plain text with its name as the title, as before. The caption names a recognised language once ("Python", not "Python · python"), and keeps the fence's word for a dialect the label doesn't name ("TypeScript · tsx"). safe-markdown now installs with highlight. - Payload names more languages (payload): its caption says "Go", "Rust", "Java", "Kotlin", "C", "C++", "C#" and "JavaScript" where it upper-cased or capitalised the word ("GO", "CPP", "Csharp", "Javascript"), and
shellandzshread thepayload.shellstring ("Shell"), asbashandshdid. Nothing to do, unless a test or style matches the old caption. - Tables in a model's text (chat, safe-markdown, message-content): a GFM pipe table becomes
{ kind: "table" }, a header and rows of inline text cells with each column's alignment. MessageContent draws a<table>with column headers in an area that scrolls sideways and takes focus, named by the newmessageContent.tablestring ("Table"). A table whose rows don't match its header stays a paragraph. It copies as a pipe table. Seemessage-block-kinds. - Quotes in a model's text (chat, safe-markdown, message-content):
>lines become{ kind: "quote" }, drawn as a<blockquote>of paragraphs; one level, a deeper>is text. UndermarkdownBlocks(text, { breaks: true })a quote keeps its line breaks, as a paragraph does (the block's optionalbreaks). It copies as>lines. Seemessage-block-kinds. - A switch over a block's kind needs a default (chat): MessageContent draws nothing for a kind it doesn't know, and its copy leaves it out.
- Streaming converts one message (use-candor-chat, claude-agent-sdk, ag-ui): while a reply streams, useCandorChat converts only the messages that changed, and the Claude Agent SDK and AG-UI adapters read only the text that grew as markdown. The output is the same. A Claude reply's citation markers pass over a table or a quote, as they pass over code. Nothing to do.
Some DOM your CSS may match
- MessageContent: a model's pipe table was a
<p>of pipes; it is nowdiv[data-slot="message-table"][role="group"]holding a<table>. Its>lines were a<p>without the>; they are nowblockquote[data-slot="message-quote"]of<p>s. - Payload from a model's fence:
data-languageis the language's name (python,typescript,shell…) where it wastext, the label names it ("Python" where it said "Text"), the caption has no title beside a recognised language, and the code is token spans. - UsageMeters: each card carries
data-slot="usage-meter",data-variant="bar", anddata-level,data-knownanddata-paused, as the glance and ring have them. The ring's box is@container aspect-square w-40 max-w-full(wassize-40), its centrepx-[18cqi](waspx-5), the figure's size an inlinefont-sizeincqi(wastext-3xl, ortext-smwhen not known), and the ring's root gainsmin-w-0. - PortfolioCard's usage line gains
data-variant="glance". - ChangeDiff with
navigation="tree":data-slotchange-diff-body,change-diff-fileandchange-diff-tree. Digest:digest-sinceanddigest-failed. - Payload: the caption's language name for
go,rust,java,kotlin,c,cpp,csharpandjavascriptis the language's own ("Go", "C++", "C#", "JavaScript"…), andshellandzshread "Shell". - Digest: the failed section's heading carries an
svgicon andtext-destructive-textin place oftext-muted-foreground, and the since line ends "· 5 things" when there are rows. - PermissionMode with no
onValueChange: the modes other than the one in force carryaria-disabled="true",data-lockedandaria-describedby, and a<p>under the list says "Can’t be changed here".
Docs and site
- App scaffolding: billing, team, admin, charts and layout are labelled "App scaffolding" (the screens every app has, in Candor's theme, not agent surfaces) and listed after the agent groups in the docs,
llms.txt, the skill and the MCP. No item, tier or API changes. The site counts them on their own, not as agent components. - The home page leads with approvals and work surfaces, provenance in the type and the honesty rules; the item counts are on the pricing cards.
CLI 4.0.0
- Run the CLI as
npx candor-ui@4. It works with Candor 5.4 and later; on an older projectupdate,addandmigratestop, change nothing and namenpx candor-ui@3 update --to 5.4.0(withmigrate 5.0.0from 4.x). CLI 3, 2 and 1 stay on npm. addandupdatekeep each installed file as Candor installed it in.candor/base/(<path>.base, besidecomponents.json;.candor/.ignorekeeps Tailwind out). Commit.candor/:updatemerges your changes against these copies and needs only the release you update to from the registry. Don't edit them.candor-lock.jsonislockfileVersion: 2, recording each copy's hash. CLI 4 reads version 1 and rewrites it on the firstaddorupdate. CLI 3 can't read version 2 ("candor-lock.json isn't a lockfile this version of candor-ui reads."): from then on use@4.verifychecks your files and their base copies without the network;verify --remotealso checks the registry's snapshots, as before.updatewithout--tostays before a minor with breaking changes, as before a major, and namesupdate --to <release> --dry-run.update --toprints the entries of items a release removes, installs the item that holds a removed one's job (usage-glance 5.4.0 → 6.1.0: merged into usage-meters), keeps the old file as yours, and ends naming the guide and eachmigrate <release>to run, oldest first.migrate 6.1.0runsitems,strings-keysandtokens. A stylesheet that sets--cd-motion-approval-request-outcome(or-mark) gets a copy at--cd-motion-decision-review-card-outcome;migrate 6.1.0makes only 6.1's token rows (migrate tokensby name makes 4.0's too).- A self-hosted registry serves
/r/v/<version>/breaking.jsonper release from 6.1, or a removed item's entry doesn't print. updatealso writes the base copies of items already at the target that lack them. For a project an older CLI set up,npx candor-ui@4 update --to <version> <items>, at the version they're at, writes their copies and moves nothing;verifynames that command.migrate 6.1.0runs an entry's codemod where its old forms are in your source though the lockfile no longer records the item (a removed item's kept file).- On a 6.1 project
theme checkreports a motion token 6.1 renamed as an error namingmigrate 6.1.0,--cd-motion-review-ladder-rungas a warning, and--cd-motion-approval-request-outcomeset without--cd-motion-decision-review-card-outcomeas a warning where the project hasdecision-review. The theme builder reads an older file's names as 6.1 does. - "New strings to translate" no longer lists a table that moved into another item with its component.
updateprints 6.0's entries withnpx candor-ui@4 migrate ….
For maintainers
- The OrgSmith pack has left this repository (
packages/orgsmith, its test and its aliases); it lives in its own private repository, which installs Candor as a buyer does. - Plans and reviews before 6.0 are in
internal/archive/, under the paths they had ininternal/. - The site, MCP and docs tests read the CLI's major from
packages/cli/package.jsonfor the install line they expect. npm run registryremoves an item's file frompublic/ronce registry.json no longer lists it, so a checkout that built an earlier release doesn't serve a removed item.npm run test:browserrunstests/browser/usage-ring.mjs, the ring's figure checked in Chromium at 6, 8, 10 and 14rem, in both directions;--only usage-ringruns it alone.npm run release:checkis the quick run;npm run release:check -- --fulladds the browser, the shadcn differential, the fresh apps and the upgrade steps, and is the run before RELEASING step 6.--quickstill works.- release:check runs independent steps side by side, prints each step's output whole with its time, and stops at the first failure naming the step.
npm run checkruns the source checks as one walker over one read of the sources;npm run check:<rule>runs one, as before. A new rule,frozen-groups, fails a new file in billing, team, admin, charts or layout.npm run generateruns each generator once;npm run docsalone is unchanged.docs/RELEASING.mdis the steps a release needs; its history is ininternal/RELEASE-LOG.md.- CI's long jobs (on release pull requests, weekly and by hand) also run the snapshot store check, the pinned shadcn differential, the Premium and monorepo fresh apps and the upgrade steps, with the store's token only where the store is read.
6.0.1 - 2026-11-14
No package of the kit changed. The registry’s items and @candor-ui/react are as in the release before, and the package wasn’t published again, so it keeps the earlier version number.
The WebKit-on-Linux layer baseline, verified, and OrgSmith's autonomy levels in its private pack. No change to the kit.
For maintainers
- The layer checks' WebKit-on-Linux baseline (
tests/browser/layers.mjs) is empty, so every layer check counts in WebKit on Linux, as in Chromium and Firefox (ARCH-27). Nothing to do. - OrgSmith's private pack (
packages/orgsmith, unpublished) has its three autonomy levels as customPermissionModemodes: Recommends only, Builds, asks to deploy, and Autonomous in sandbox. On a sandbox the agent starts in Autonomous in sandbox; elsewhere, or while that isn't known, in Recommends only, and a person moving to Autonomous in sandbox is asked to confirm. The two that write areLockedunless the org is known to be a sandbox, whatever the strings say; production is never a level, and promotion goes through ApprovalRequest for the decision and EnvironmentPromotion for the move (IH-8). Nothing in the kit changed.
6.0.0 - 2026-11-14
A major release, with CLI 3.4.0 and @candor-ui/react 6.0.0: one way to say who, approvals that invent nothing, and headings the free tier can follow. Who did something is one type, Actor, wherever Candor draws it; ApprovalRequestData's onBehalfOf stays { name }, since it is always a person, the one an agent asked for. An approval needn't be a deploy: its environment, production flag and build hash are optional, and Candor draws nothing for one that is missing. HeadingScope and HeadingLevel are free, and the free items that draw a heading follow the nearest scope, as the Pro items already do. Five things a minor couldn't change are put right: TypedText has one composition prop, ColumnMapper's percent is the locale's, UsageMeters says "No limit set", a linked ScopeSwitcher or ScopeBreadcrumb option calls onChange as every other Candor nav item does, and the nulls earlier minors let in are recorded. CLI 3.4 runs the upgrade (npx candor-ui@3 update --to 6.0.0, then npx candor-ui@3 migrate 6.0.0). No item is new; heading-level and heading-scope move to the free tier, so the kit has 420 items: 76 free and 389 in Pro.
Upgrading from 5.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 6.0.0 --dry-runprints what 6.0 changes for the items incandor-lock.json, and writes nothing. - Update:
npx candor-ui@3 update --to 6.0.0updates every item, merging your changes into Candor's asupdatealways has. - Migrate:
npx candor-ui@3 migrate 6.0.0runs each of 6.0's codemods that an entry on your installed items names, in this order:data-types,props,strings-keys,headings. Each lists what it couldn't change under "Left for you".--dry-runshows it first. - Finish by hand: make the changes the "Left for you" lines name and those marked "by hand" below.
- Check: type-check (
npx tsc --noEmit) and build, then run your tests.
A project still on 4.x goes to 5.0 first, with the same CLI: npx candor-ui@3 update --to 5.0.0, then npx candor-ui@3 migrate 5.0.0 (Upgrading to 5.0), then the steps above. update --to 6.0.0 and migrate 6.0.0 on a 4.x project stop, change nothing and name them.
The codemods change your own files only: Candor's installed files come with the update, and in one you've changed, what a codemod finds is listed. 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 usageMeters.noCap, since StringOverrides takes any key: it still compiles and isn't read, so migrate strings-keys is what moves it.
Each entry below has its id in scripts/breaking.json (the same entries update --to 6.0.0 prints, and the Upgrading to 6.0 page lists), what changed, and what to do:
actor(codemoddata-types; work, digest, digest-email, change-list, decision-review, approval-request, approval-queue, review-canvas, environment-promotion; Pro): who did something is one type,Actor({ kind: "agent"; agent } | { kind: "person"; name }), fromlib/candor/work(KIT-346).DigestActor(Digest, DigestEmail) andChangeListAuthor(ChangeList) were already that shape and are gone.ApprovalRequestData'srequester(ApprovalRequest, ApprovalQueue, ReviewCanvas, the approvals-inbox template, approve-from-anywhere and approval-gated-change) was{ name }or{ agent }, andDecisionReviewItem'srequestera string or anAgentIdentity; both take anActor. Each item draws what 5.4 drew for the same who.migrate data-typesmoves each import of the old names toActorfromlib/candor/workand renames their uses (an import you aliased keeps its local name). In a file that imports fromlib/candor/work, ApprovalRequest, ApprovalQueue or ReviewCanvas, it writes a literalrequester: { name }or{ agent }as{ kind: "person", name }or{ kind: "agent", agent }, and lists every other requester there; in a file that imports DecisionReview, it lists each requester not written with akind(a string or anAgentIdentityin 5.x). A requester built in a file that imports none of these isn't seen. The type check finds the rest; a check like"agent" in requesterstill narrows anActor. The Premium blocks' storedrequestercolumn is unchanged; requesters stored in your own database are data, so map them to thekindshape where you read them. EnvironmentPromotion'srequestedBytakes anActorwithatas well as{ name, at }(KIT-358), so code that reads it throughComponentPropsfails the type check atrequestedBy.name. No codemod lists it: by hand, read the name by its shape ("agent" in requestedBy ? requestedBy.agent.name : requestedBy.name).approval-optional(codemoddata-types; work, approval-request, approval-queue, review-canvas, approvals-inbox; Pro and Premium):ApprovalRequestData'senvironment,productionandartifactHashare optional, so an approval that isn't a deploy says nothing about an environment or a build (KIT-233). ApprovalRequest, ApprovalQueue and ReviewCanvas draw nothing for a missing one: no Where line, no hash, no production warning, and never "Non-production" for aproductionleft out. A request with all three draws as in 5.4.onApproveandonRejecton ApprovalRequest and ReviewCanvas takehash: string | undefined,undefinedfor a request without a hash.migrate data-typeslists each read of the three fields in a file that importsApprovalRequestData, and eachonApproveoronRejecton ApprovalRequest or ReviewCanvas whose handler's first parameter is typedstring(written inline, or as a function orconstin the same file), with its file and line (CLI-62). By hand: handleundefinedthere, and where a handler passeshashon as astring; withstrictNullChecksthe type check finds each.typed-text-as(codemodprops; typed-text; Pro): TypedText'sasis gone;render(since 5.1) chooses the element (KIT-262).migrate propswritesas="h2"asrender={<h2 />}, keeping the other props, and lists anasthat isn't an element's name (as={tag}: passrender={<Tag />}) and a TypedText with bothasandrender.column-mapper-percent(codemodstrings-keys; column-mapper; Pro):{percent}incolumnMapper.percentSureis the locale's percent, sign and all ("85%", "85 %" in French), and the default is "{percent} sure" (KIT-263). An override that typed its own%would draw it twice.migrate strings-keystakes the%(and a space before it) out where it follows{percent}, and lists an override it can't read or with%anywhere else. Translations stored outside your source: take it out there.usage-meters-no-limit(codemodstrings-keys; usage-meters; Pro): UsageMeters says "No limit set" (usageMeters.noLimit) for a usage with no limit, as UsageRing does, where it said "No cap on your plan." (KIT-355).usageMeters.noCapis gone.migrate strings-keysmoves an override ofnoCaptonoLimit, and lists a table that has both, for you to keep one. TranslatenoLimitif you hadn't.scope-link-click(codemodprops; scope-switcher, scope-breadcrumb; Pro): a plain click (or Enter) on an option withhrefcallsonChangeinstead of following the link, as every other Candor nav item does; a click that opens a new tab (a modifier key, or the middle button) follows the link and calls nothing (KIT-270). Choosing the option already in place does neither, where 5.x followed its link. An app that passeshrefwith anonChangethat only sets state stops going to the option's page.migrate propslists each ScopeSwitcher and ScopeBreadcrumb withonChange; by hand, navigate inonChange(with your router), or leave outhrefwhere the option isn't a page of its own.locked-null(by hand; command-palette, scope-switcher, scope-breadcrumb, settings-layout, dashboard-tile, permission-mode, plan, tree, app-sidebar, nav-rail, tab-bar, know and the other items 5.1 to 5.3 widened;knowandsliderare free): 5.1 to 5.3 widened these to acceptnull, which a minor shouldn't have done for code that reads them, and 6.0 records it (KIT-281);know'slockedmap (ToolSetting.locked) acceptsnulltoo (KIT-294). 5.1: thelockedfield ofPaletteItem,ScopeLevel,SettingsItem,DashboardTileView,PermissionModeOptionandPlanAutonomyOption, thelockedprop of 28 components, and Tree'sonSelect's second parameter. 5.2: the…Lockedprops of RunEstimate, PlanGate, DataControls, SsoSetup, AgentScreen and Plan, AccountState'sactions[].locked, thelockedmaps of ArtifactToolbar, RestoreDialog, ReviewLadder and NotificationPreferences, and Inbox's and ApprovalQueue'sdefaultActiveId. 5.3: AppSidebar's, NavRail's and TabBar'sdefaultActiveId. Code that reads one into astring | undefinedof its own fails the type check, as does a wrapper that types Tree'sonSelectas(id: string) => voidthroughComponentProps. No codemod: where you read one, write?? undefined(nulland left out both mean unlocked), and type a TreeonSelectwrapper(id: string, node: TreeNode) => void. Code that passes them is unchanged.heading-default-free(codemodheadings, which lists; heading-scope, heading-level, permission-prompt, page-state, message-content, message, accordion; free):HeadingScopeandHeadingLevelare free (D109, D110). PermissionPrompt, PageState (and ListStateView), AccordionTrigger and the headings in a model's message (MessageContent, and Message through it) draw one level below the nearestHeadingScope, as the Pro items have since 5.0 (KIT-261, KIT-260); Candor's dialogs, sheets, drawers, settings sections and dashboard tiles set one. Outside a scope PermissionPrompt and PageState stay<h2>and a model's#stays<h3>; AccordionTrigger is<h2>there, where 5.x drew<h3>always. PageHeader is unchanged: its title stays<h1>, and it sets no scope, since it draws no page content.migrate headingschanges nothing: it lists each use withoutheadingLevelthat draws at a new level, with the level it drew in 5.x (a model's message only inside a scope; Message, which takes noheadingLevel, with a<HeadingScope>to wrap it in). By hand: passheadingLevelwhere a page or a test needs 5.x's level (headingLevel={3}keeps AccordionTrigger's<h3>), or take the new outline.thread-jump-safe-area(by hand; thread; free): Thread's Jump to latest pill sits above the phone's safe area (env(safe-area-inset-bottom)), so it isn't under the home indicator (KIT-349). Elsewhere the inset is 0 and nothing moves; a screenshot test on a phone that pins its place differs. To keep 5.x's place, set--cd-thread-jump-offset: calc(-1 * env(safe-area-inset-bottom, 0px))where you style the thread.
Free tier
On the owner's calls (D197): no item is added, and none leaves Pro.
heading-levelandheading-scopeare free (D109, D110's alternative):HeadingLevel,HeadingScope,useHeadingLevel,useHeadingScope(the nearest scope's level, orundefinedoutside any) andbelowLevel, inlib/candor/heading-levelandlib/candor/heading-scopeas before. The free items'headingLevelprops are typed withHeadingLevelrather than the union written out. Breaking for the free items that follow a scope:heading-default-freeabove.ListStateis declared once, in the freestatus(KIT-232).page-statere-exports it, and the Prodatamodule'sListStateandChartStateare the same type, so every name you import still works.
New exports
useStringsOverridden(name)(locale, free):(key) => boolean, whether the app set a key of a component's strings undernamein LocaleProvider'sstrings, even to the default's own words, which comparingt(key)with the default can't tell (KIT-352).useStringsis unchanged.isShown(element)(use-announcer, Pro): whether an element is on screen for a screen reader and a sighted person alike: not underhidden,inertoraria-hidden="true", and notdisplay: noneorvisibility: hidden(KIT-353).Actor(work, Pro): above.DigestActorandChangeListAuthorare removed.
Components (Pro)
- An app's words marked for bidi controls (KIT-350, KIT-357): EnvironmentBand (the account, the environment's name and detail), Inbox (the environment filter, an app's own kind), NotificationCenter (a notice's title, detail and action), CommandPalette (an item's label, detail and locked reason, a group's heading), SettingsLayout (the nav's labels, a locked reason, a section's title, and its description when it is a string), AccountState (its title, a detail given as a string, the actions' labels and the signed-in email), ServiceNotice (its title, detail and action) and SectionNav (its labels) draw them with
neutralizeBidi, in a<bdi>where they sit among other words. - The rest of the kit's words marked for bidi controls (KIT-360): every free and Pro item was read for text the app or a model supplies that it drew without
neutralizeBidi, and 182 Pro items now mark it: titles, headings, labels, names, emails, descriptions, details, badges, reasons (a locked reason among them) and the values Candor puts into its own sentences andaria-labels, in a<bdi>where they sit among other words. Among them ChartFrame (so every chart's title, legend, table and tooltip), DataTable, DetailsList, Board and Tree, the work items (ApprovalRequest, Plan, ChangeList, WorkflowEditor and 28 more), the shell's navigation (AppSidebar, NavRail, TabBar, PersonMenu), the team, admin and billing screens, CommentThread, Escalation, McpConnect, ModelKey and the report cards. An app's own note, label or sentence passed whole in place of one of Candor's (astringsoverride of one too),children, and an attribute passed whole are left as they were. A value Candor puts into one of its visible sentences sits in its own<bdi>, except in a list joined by the locale, an<option>, text read only by a screen reader, and email markup. Text the person edits and values that are copied or sent stay exactly as given (CopyField and DetailsList copy the value itself). Nothing to do. - DecisionBar, TurnRequest and ScreenGuide announce a change only while shown, through
isShown(KIT-353). DecisionBar now stays quiet underaria-hiddenandvisibility: hiddentoo (it checkedinertandhidden); ScreenGuide checked nothing, and a step that changes while it is hidden isn't said later. - FilterChips announces a filter that goes only while the chips are shown; once the last chip has gone, that is asked of the element they were in (KIT-356).
- ChangeDiff: a click after a click asks again; only the click that follows a focus request in the same press is dropped, where two bare clicks counted as one (KIT-354).
- SettingsLayout reads which of its strings the app set with
useStringsOverridden, so one set to the default's own words counts as the app's (KIT-352). - EnvironmentPromotion's
requestedBytakes anActorwithatas well as{ name, at }, so an agent asking for a promotion is named as one; its own approval isn't counted, as a person's isn't (KIT-358). A wrapper that reads the prop throughComponentPropssees the wider type (actor, under Upgrading from 5.x). - ApprovalRequest says "What this changes has changed since it was requested…" (
approvalRequest.staleUnnamed) for a stale request with no hash, andproductionShortis the warning for a production request with no environment (KIT-233).
`@candor-ui/react` 6.0.0
HeadingScope,HeadingLevel,useHeadingLevel,useHeadingScopeandbelowLevelare in the package (D109, D110's alternative).- PermissionPrompt, PageState and ListStateView follow the nearest
HeadingScope; outside one they draw<h2>as before (KIT-261). Breaking:heading-default-free. - MessageContent's model headings start one below the nearest
HeadingScope; outside one they start at<h3>as before. Message passes no level, so its content follows the scope round it (KIT-261). Breaking, as above. - AccordionTrigger takes
headingLevel; left out, it is one below the scope, else<h2>(5.x: always<h3>) (KIT-260). Breaking, as above. - Thread's Jump to latest sits above the phone's safe area (KIT-349). Breaking:
thread-jump-safe-area. know'sToolSetting.lockedtakesnullper permission, unlocked as left out (KIT-294). Code reading a value intostring | undefinedadds?? undefined(locked-null).ListStateis declared once, instatus;page-state's is the same type (KIT-232). No change to make.- PageHeader's breadcrumb and tab labels, and PageState's action and secondary labels, are marked for bidi controls in a
<bdi>(KIT-350). - The free items' words are marked for bidi controls too (KIT-360): Locked's reason (so every control locked through it), Slider's locked reason, Progress's label, StepList's steps, CopyField's label and value, DegradedPanel's reason and what's missing, PageHeader's title and description, PageState's title, detail and ListStateView's note and reason, AgentBadge's name and an app's own role noun, AiDisclosure, AttachmentPreview, CardRegistry, Citation, Composer (its menus' options, commands, reasons and scope), ContextMeter's segments, EntityChip, FoldedTurns' summary, Message, PermissionPrompt, PromptSuggestions, Reasoning, ThreadDivider's label and ToolCall. CopyField still copies the value as given. Nothing to do.
useStringsOverriddenis exported fromlocale(KIT-352).- FoldedTurns'
defaultOpendoc says when it holds its own state: givenopen, the app does; givendefaultOpenalone, it starts there; given neither, it starts folded, as in 5.x (KIT-279). No change. - The package doesn't export
Actor,DigestActororChangeListAuthor, which are Pro. Update it with your package manager.
New string keys
Translators: one key is new, one is removed, and two defaults change.
- New:
approvalRequest.staleUnnamed("What this changes has changed since it was requested. The change is re-checked before it applies, and refused if it no longer matches."). Until you translate it, it says its English words. - Removed:
usageMeters.noCap;usageMeters.noLimit("No limit set") is drawn instead (usage-meters-no-limit). - Changed:
columnMapper.percentSureis "{percent} sure", and{percent}brings its own sign (column-mapper-percent).
Some DOM your CSS may match
- AccordionTrigger's header is an
<h2>outside aHeadingScope, where it was an<h3>; inside one, one below it. - A
<bdi>round an app's words where there was a<span>or bare text: PageHeader's crumbs and tabs, PageState's buttons, and the Pro items under Components above. In NotificationCenter, CommandPalette, SettingsLayout and Inbox's detail, the<bdi>takes the old span's classes. ServiceNotice's title is in a<bdi>. Nothing looks different. - KIT-360's
<bdi>s, round an app's or a model's words that sit among other words or beside an icon, in the items the sweep changed (a string that is a whole block, cell, heading or flex item is marked with no<bdi>, so Locked's reason and AgentBadge's name keep their markup). Where a<span>held only the words, the<bdi>takes its classes. Email markup (EmailLayout, DigestEmail) gets none. Nothing looks different. - Thread's Jump to latest wrapper's bottom margin is
mb-[calc(env(safe-area-inset-bottom,0px)+var(--cd-thread-jump-offset,0px))], where it wasmb-[var(--cd-thread-jump-offset,0px)].
Docs
- Upgrading to 6.0 (
/upgrading-to-6and its Markdown) lists every change above with its codemod (CLI-58). - The site's and the docs' install lines name the CLI's major,
npx candor-ui@3 add: the docs MCP's install commands, the Get started steps and prompt, the patterns', themes' and screens' lines (CLI-56), and the setup guides, the hosted templates' pages, the apps' note, the theme builder's export, brief and sound panel, the home page's install answer and the licence key page (CLI-59). - An item's page lists a type it re-exports from another item, saying where it is declared:
ListStateon page-state's,HeadingLevelon heading's, the phrase and noun types on locale's (DOC-18). - PermissionPrompt's example shows the prompt in a Dialog following the Dialog's scope; heading-scope's example uses native tags, so a free reader can copy it (KIT-261).
--cd-thread-jump-offset's description says the pill sits above the safe area and how to keep 5.x's place.
CLI 3.4.0
- New:
migrate 6.0.0runsdata-types,props,strings-keysandheadings.data-types(new) movesDigestActorandChangeListAuthortoActorinlib/candor/work, rewrites literal requesters, and lists the approval fields' reads and eachonApproveoronRejecthandler on ApprovalRequest or ReviewCanvas whose first parameter is typedstring(CLI-62);propswrites TypedText'sasasrenderand lists ScopeSwitcher's and ScopeBreadcrumb'sonChange;strings-keystakes the%out ofcolumnMapper.percentSureand movesusageMeters.noCaptonoLimit;headingslists the free items whose level 6.0 changes.update --to 6.0.0ends its list with a link to Upgrading to 6.0 (CLI-58). - New:
update --to 6.0.0(or later) andmigrate 6.0.0on a 4.x project stop, changing nothing, and nameupdate --to 5.0.0,migrate 5.0.0, thenupdate --to 6.0.0,migrate 6.0.0(CLI-58, CLI-60). - Fixed:
updatetook items that answered 404 at the target as removed when any breaking entry was there for them, an unrelated one too, and cleared them fromcandor-lock.json. It reads the registry's index of the target (/r/v/<version>/index.json) instead: an index it can't read, or one that lists an item it 404s on, stops the update with nothing changed (CLI-57). - Fixed: the docs MCP's install commands and the site's install lines name
npx candor-ui@3(CLI-56, CLI-59).
For maintainers
- The registry serves each released version's index, public, at
/r/v/<version>/index.json(vercel.json,api/registry.ts), andscripts/registry-server.mjsserves the same, this branch's frompublic/r/registry.json(CLI-57). It must be live before CLI 3.4.0 is published. - The registry's earlier versions are served from the snapshot store in Vercel Blob, and git no longer tracks
snapshots/(ARCH-34); the tests that read earlier releases fetch them from the store or skip (HK-17). Only the build's own version is static. While the store can't answer, an earlier version's files answer 503, and/r/versions.jsonanswers with the version list the build read (build/versions.json, bundled with the function and not served), socandor-ui updateand the docs MCP still start. release:check's upgrade steps are a row per kit major (UPGRADE_STEPS): for 6.x, the 5.4 fixture (tests/upgrade/5.4/) in the normal,--base,--radixand--monorepoapps, and the 5.0 fixture to this checkout. The 4.5 fixture leftrelease:check(4.5 to 6.0 crosses two majors) (CLI-58).migrate headings' table has 6.0's rows; a model's message is listed only inside a scope (onlyInScope), andtests/kit/heading-outline.test.tsxruns the free items' rows.- ProgressRing's
aria-valuetextalready said the value past the limit; a test now says so (KIT-351). - The markup tests for the
Actoritems compare full server renders captured at 5.4 (*.5-4.json), with 6.0's<bdi>round a name or environment inside a sentence applied to the capture first; the rest is compared exactly.
5.4.0 - 2026-11-13
A minor, with CLI 3.3.1 and @candor-ui/react 5.4.0: the rows 5.3's streams and reviews left, made right. No item is new, so the kit still has 420 items: 74 free and 389 in Pro. Nothing a 5.3 app passes stops working, and no default text changes.
What to do: npx candor-ui@3 update --to 5.4.0 takes a 5.3 project to 5.4.0, with no codemod. If you use @candor-ui/react, install 5.4.0, which carries the free fixes listed under it.
What Storywrite asked for (A-74 and A-80), and where each is:
- A-74 Plain type: the names that draw beside code now read
--cd-font-namein LogStream's writer column (KIT-347), ChangeTree's file names (KIT-345) and, when you ask for it withtitleFont="name", CodeListing's title (KIT-335). EntityChip and ChangeDiff have read it since 5.3.0. Unset, each draws as in 5.3, but for a title you set totitleFont="name": with the token unset, it falls back to the monospace font, as the other names do. - A-80 Room for the app's own floating element: Thread's Jump to latest button sits
--cd-thread-jump-offsethigher (KIT-348). Unset, it sits where it did.
Components (Pro)
- TurnRequest (KIT-330):
taken, the app's word that the person has the screen now. It reads "You have the screen. Hand it back when you're done." with Hand back (onHandBack), keeps what the agent won't do and whether it sees the screen in view, and locks Take the screen saying why. It is never inferred from a press of Take, and focus stays where it was. When the app clearstakenwith no report yet and focus was in the request, as after Hand back, focus goes to the request's heading rather than falling to the page. - TurnRequest (KIT-341): a new request (new
why,todoor asking agent) is announced by its title once, when focus is elsewhere and the request is shown; nothing on mount. The report's announcement is no longer made while the request is hidden. A new asking agent (a newagent.id) is now a new request on its own, so with focus in the request it also moves focus to the heading, as new words did in 5.3. - DecisionReview (KIT-333):
actionKeys, a key per action id that moves focus to that action's button; Enter or Space then presses it. No key decides. The key is shown on the button and in itsaria-keyshortcuts("Plus" for+). It is ignored in fields, with Ctrl, Alt or Meta, with Shift on a letter (a key typed with Shift, such as?, works), after the app's handler callspreventDefaultand in the app's composite widgets; J, K and a key already taken are ignored, with a development warning. The composite widgets it leaves keys to now include a menubar, treegrid, toolbar and combobox (a button one too), for J, K and the arrows as well: 5.3 moved between items on those keys there. - DecisionBar (KIT-342): a new title is announced only while the bar is shown, not under AppLayout's quick chat or while the app hides it. (KIT-332):
safeAreapads the bar's foot byenv(safe-area-inset-bottom)on top of its ownpy-2, for the foot of a phone's screen when no TabBar is under it; apy-*orpb-*inclassNamereplaces both. Left out, the HTML is 5.3's. - AgentScreen (KIT-340): the docs for
frameAt,markersandonFrameStaleChangesay a live frame with noframeAtis never judged stale, so its markers stay shown and the callback says false. PassframeAtto have it judged. The behaviour is 5.3's. - ChangeDiff (KIT-336): left to keep its own shown file, it keeps it by path, not by place in the list: a shorter or reordered
fileskeeps the same file shown while it is there, and shows the first file when it isn't. 5.3 could show nothing afterfilesgot shorter. (KIT-344): withselected, pressing a tab the app declined asks again on the next press; 5.3 stayed silent until the shown file changed. - ChangeTree (KIT-345): file names draw in
--cd-font-namewhen you set it, so the tree matches ChangeDiff beside it. Unset, nothing changes. - CodeListing (KIT-335):
titleFont="name"draws the title in--cd-font-name, and in the monospace font when the token is unset, as the other names that read it do."body", the default, draws it as before. - LogStream (KIT-347): the writer beside each line draws in
--cd-font-namewhen you set it; the log text stays monospace. Unset, nothing changes. - UsageMeters (KIT-337):
usageMeters.noLimit, a new opt-in key for a usage with no limit. Override it and UsageMeters draws your words there in place ofnoCap's; left as it is, it draws "No cap on your plan." as in 5.3. An override with the default's own words ("No limit set") can't be told from none, so it drawsnoCap's too. In 6.0 the default moves to "No limit set", UsageRing's words. - UsageGlance, UsageMeters and UsageRing (KIT-343): past its limit, a meter reports
aria-valuenowat the limit, not above it, and itsaria-valuetextsays the measured figure. UsageGlance and UsageRing said it already ("140 runs of 100 runs"); UsageMeters now sets one past the limit ("140 / 100 runs"). Inside the limit the markup is 5.3's. - FreshnessStamp: a
readAtit can't read ("soon") says "Read time unknown" (itstimeUnknownkey) with no date and notitle, where 5.3 threw a RangeError. - EmailLayout (KIT-339):
emailMarkup(node), new, writes an email's element tree to an HTML string with noreact-dom/server, so it runs in a route handler, a server action, a worker or the browser. It writes host elements, text, fragments, a context provider's children and components without hooks,memoandforwardRefones included; anything else, such as a class or lazy component or one that uses hooks, throws an error naming it rather than being left out.EmailLayouttakes optionalchildren, drawn in the document's<body>in place of the notice's card; left out, ornull,undefinedor a boolean, the card is drawn. DigestEmail'srenderDigestEmailnow usesemailMarkuprather than a copy of it; its output is byte for byte 5.3's. - Names from the app have their direction controls neutralised in AppLayout's quick chat heading and region name and in
panelLabelin the panel's names (KIT-331), and in ArtifactPanel's download items, NavRail's and TabBar's counted names where the kit puts the label in (TabBar's own name,navRailTabs' defaultwaitinganduseNavRailTabs; an app's ownbadgeLabel, or what its ownwaitingreturns, is read as the app gives it, as in 5.3), SettingsLayout's select and the collapsed AppSidebar's person tooltip (KIT-327).
`@candor-ui/react` 5.4.0
- RelativeTime draws "Time not known" for a date it can't read (
"soon",new Date(NaN)) instead of throwing a RangeError, with nodateTimeand notitle, from the new keyrelativeTime.unknown(KIT-334). The free Message and ThreadEvent, and the Pro items that show a time through RelativeTime, draw it too.formatRelativereturns""for a date it can't read, where it threw (or, withbare, returned "NaN seconds"). A valid date draws what it did. - Thread's Jump to latest button sits
--cd-thread-jump-offsethigher, a new token for an app with its own floating element at the thread's foot (KIT-348). Unset, it sits where it did.
Nothing to do.
The new token
--cd-thread-jump-offset (KIT-348): how much higher Thread's Jump to latest button sits than its own place at the thread's foot. It is 0px by default. Set it to a length on the thread or any element around it; it inherits.
--cd-font-name's description names every item that reads it, and says what Tailwind 4.0.0 to 4.0.14 draw for its fallback: the theme's --font-mono as it was at build time, so CSS outside @theme that changes --font-mono isn't followed there; set --cd-font-name too (DOC-17). From Tailwind 4.0.15 the fallback is font-mono's exactly.
New string keys
Translators: these keys are new. Until you translate them, each says its English words. No key read in 5.3 changed.
relativeTime:unknown("Time not known").usageMeters:noLimit("No limit set"), read only when your app overrides it; until 6.0,noCapis drawn otherwise.turnRequest:taken,takenLockedandhandBack.
Some DOM your CSS may match
- Thread's Jump to latest wrapper keeps 5.3's classes and adds one,
mb-[var(--cd-thread-jump-offset,0px)]: a bottom margin, which raises the absolutely placed wrapper. Unset, it is0px. - TurnRequest with
takenhas a new row,data-slot="turn-request-taken", anddata-phase="taken"on its root. DecisionReview withactionKeysdraws each key in a<kbd data-slot="decision-review-action-key">on its button. Without those props, the HTML is 5.3's but for React's generated ids, which can differ. - AppLayout's quick chat heading and its panel sheet's title draw the app's words in a
<bdi>. - ChangeTree's tree carries one more utility class (the font token). LogStream's writer
<bdi>and, withtitleFont="name", CodeListing's title<bdi>carryfont-[family-name:var(--cd-font-name,--theme(--font-mono))]; LogStream's writer is insidefont-monoas before.
Docs
- TurnRequest's example puts a line in the request's place after Not now and focuses it, so focus doesn't fall to the page (DOC-16); it also shows
takenwith Hand back. DecisionReview's example passesactionKeys. - Each item's install line names the CLI major,
npx candor-ui@3 add <name>, on the docs pages, incomponents.md,llms-full.txtand the docs MCP'sget_component_docsandget_brief(CLI-53). - The upgrade guides' lines for keeping an older version installable name the CLI for each:
@1for 2.10.0,@2for 3.0.0 and 4.5.0 (SITE-37).
CLI 3.3.1
updatestops, naming the registry and changing nothing, when every item it asks for answers 404 and none of them has a breaking entry of any kind, or when the registry's list of versions can't be read. Before, when every item answered 404, it clearedcandor-lock.json(CLI-54). One 404 among items that answer is still a removal of that item.infoandsearchprintnpx candor-ui@3 add <name>(CLI-53).- A test keeps every
migrate <name>the CLI prints in step with its codemods (CLI-55).
For maintainers
release:checktakes its 5.x--fromlist fromtests/upgrade/5.0/fixture.json'salso(CLI-52), with 5.3.0 added, anddocs/RELEASING.mdsays so.tests/date-trap.tstraps every way a render could read the clock,new Date()as well asDate.now, for the five clock-after-mount tests (HK-15).- Tests for React 19's ref cleanup through the merged refs:
merge-refs, and the free Popover, Composer and Thread (HK-16). They found no bug. - The docs-snapshot test reads and hashes each blob once, not once per release that keeps it (HK-14): 1.6 s alone to 0.2 s.
Upgrading from 5.3
Nothing to do. npx candor-ui@3 update --to 5.4.0.
5.3.0 - 2026-11-13
A minor, with CLI 3.3.0 and @candor-ui/react 5.3.0. New Pro items for decisions reviewed one at a time, usage at a glance, changes read file by file, a periodic digest and an agent that asks for the screen, and the fixes 5.2 found. Nothing a 5.2 app passes stops working; code that reads the nav items' defaultActiveId type may need ?? undefined (below). Twelve Pro items are new, so the kit has 420 items: 74 free and 389 in Pro.
What to do: npx candor-ui@3 update --to 5.3.0 takes a 5.2 project to 5.3.0, with no codemod. If you use @candor-ui/react, install 5.3.0, which carries the free fixes listed under it.
What Storywrite asked for (A-62 to A-78), and where each is:
- A-62 Focused review: DecisionReview, new. The keys move between items and never decide; the what-gets-checked box isn't green unless the app reports a pass.
- A-63 Turn request: TurnRequest, new, as a card or
variant="strip". - A-64 Guide overlay: AgentScreen's
markers, and ScreenGuide, new, for a question or a walk-through over them. - A-65 Driver signal and waiting: AgentScreen's
controlStyle="strip"andwaiting. - A-66 Budget pill: UsageGlance, new. A-67 Budget ring: UsageRing, new. Both take UsageMeters' levels, now in the new
usage-level. - A-68 Change reasons: ChangeDiff's
reasonsandfileName="entity", and ChangeList, new. - A-69 Activity filters: RunLog's
toolbarandstatusFilter. - A-70 Digest sections: Digest and DigestEmail, new.
- A-71 Project cap tile: PortfolioCard's
usageandaction. - A-72 Tabs as page navigation: PageTabs, new, a
navof links rather than a Tabs variation. - A-73 Change tree: ChangeTree, new, on Tree.
- A-74 Plain type: the token
--cd-font-name, read by ChangeDiff's file names and EntityChip. CodeListing's title is drawn in the body font already, so it doesn't read the token. - A-75 Role words: RaciChips'
show="word". A-76 Plain scope: IntegrationConnect'sscopeIds="hidden". - A-77 Sticky decision bar: DecisionBar, new, and AppLayout's
bottomBar. - A-78 Thread list on a phone: SplitView's docs example now shows it (below).
New items (Pro)
Shell:
- DecisionBar (KIT-326): the decision for the item on screen, for AppLayout's
bottomBar. It names the item it decides; whenitemIdchanges it locks its actions for half a second (changeGuard,decisionBarChangeGuard) and announces the new title once; a destructive action says what can and can't be undone;locked, and each action'slocked, say why. - PageTabs (KIT-321): page navigation as a
navof links through the app's link render, the current page markedaria-current="page". On a narrow width the row scrolls sideways with a fade at the edge that has more, and the current tab is scrolled into view without moving focus.
Work:
- DecisionReview (KIT-308): a mixed queue of decisions, one at a time: "{position} of {total}", the kind (the app's
kinds), the outcome sentence (named as the agent's when an agent wrote it), the facts ("Not known" for null; money in the app's currency), what gets checked (in future words; green only when the app reports a pass), what happens if you stop (or "The app hasn't said what happens if you stop."), the actions, and the whole queue beside it. J, K and the arrow keys move and focus the item's heading; no key decides. When the item shown changes, the actions lock for half a second (changeGuard), as DecisionBar's do.currentIdwithonCurrentChange, ordefaultCurrentId(nullfor none at first). An approval reaches ApprovalRequest through thedetailrender prop. - TurnRequest (KIT-309): the agent asks the person to take the screen, for a sign-in, a one-time code or a check it must not pass itself. It says why, what to do, what the app says the agent won't do meanwhile (
wontDo, or that the app hasn't said), and whether the agent can still see the screen (seesScreen, or that the app hasn't said). Take the screen, an optional quieteralternativeand Not now sit side by side, none focused or pre-selected. After hand-back the agent'sreportis shown as its words, not checked. Your app must stop the agent's input while the person has the screen: Candor sends no input. - ScreenGuide (KIT-311): a question ("Which of these, 1 or 2?") or a walk-through (Step 2 of 4, Back, Next, the steps) over AgentScreen's markers. Nothing is chosen for the person, and the step moves only on Back, Next or the app's report. Pass it the same
markersas AgentScreen: both number them throughnumberedMarkers. WhileframeStale(from AgentScreen'sonFrameStaleChange) it says the markers may be out of date and locks the answers. WithoutonAnswerthe answers are locked, and withoutonStepChangeBack and Next are, each saying why. - ChangeList (KIT-316): changes newest first, with who made each (an agent through its mark, or a person), when, and lines added and removed when known; a choice of since the last review or everything. Without a recorded review (
lastReviewedAt) that choice is locked and says "No review recorded yet". - ChangeTree (KIT-322): changed files as a tree of folders, on Tree: a chip and the word for each change in ChangeDiff's words (N New, C Changed, D Deleted; an unchanged file has a dot, not a letter), deleted files struck through and still listed, the count of changes per folder, and a folder holding one folder joined to it in one row. Its selection drives ChangeDiff (
selected,onSelect).
Ops:
- UsageGlance (KIT-313): one usage as one line for a top bar's
end: "{used} of {limit}", a thin bar, the period in your words (period), and the label as a link through your router (href). From 75 % the level is said in words with an icon. No limit, no bar;unknownsays "Not known yet", never zero;paused(true, or your reason) is your statement, never inferred from what's used. - UsageRing (KIT-314): one usage against its limit as a large ring: the figure, "of {limit}", "{percent} used" (rounded down below 100), UsageMeters' levels, pending as a striped arc and may-exceed in words. The pace is your usage's
estimate, a dashed inner arc said under the ring withestimateBasis(or that you gave none); the kit computes no pace. Over the limit the ring is full and the words keep the measured figure. No limit, no ring;unknownandpausedas UsageGlance.
Foundation:
usage-level(a lib item):usageLevel(usage)returns the ratio of used to limit, the level ("normal","warning"from 75 %,"danger"from 90 %) and its tone, with null for the ratio and level when there is no limit.usageLevelThresholdsandusageLevelToneshold the numbers and colours. Safe on the server. UsageMeters reads its levels from it and draws what it drew in 5.2.
Collaboration and admin:
- Digest (KIT-318): a periodic summary in sections in a fixed order: what needs you (each row a link, a button through
onOpen, or text), health (a figure, a sparkline and its change against a named period), what was done (by agent or person) and notes in the app's groups. A trend with fewer points thanminPoints(default 4) says "Not enough data yet" with the count, never a flat line; a figure not known says "Not known" and the app's reason, never 0. - DigestEmail (KIT-319): the same
DigestDataas an email on EmailLayout's colours, server-safe (no"use client", noreact-dom):DigestEmailas a whole document,renderDigestEmail(digest, options)for an HTML string, andDigestEmailPreviewto show it on a page. Trends are in words, with no sparklines; links are the app's URLs. It imports Digest's types only, so installingdigest-emailalso installsdigest.
Components (Pro)
- AgentScreen (KIT-310, KIT-312):
markers, numbered points in the frame's own pixels, drawn over the picture where it is placed in the box (and as the box resizes), each with its number and label, and listed in text beside the frame. While the frame is stale, lost or ended they're hidden, with "The markers are hidden: the picture may be out of date."; with no frame, none.onFrameStaleChangetells the app when the picture becomes stale, lost or ended, and current again. New exportsAgentScreenMarkerandnumberedMarkers.controlStyle="strip"says who drives as a strip along the frame's top in the driver's colour, with the words in it, and outlines the frame to match; forced colours use system colours.waiting(true, or the app's reason) draws "Waiting for you" beside the run's state; it is a prop, not a newAgentScreenRunmember. - AppLayout (KIT-326):
bottomBar, pinned under the page indata-slot="app-layout-bottom-bar": a row just abovetabBarwhile the tab bar shows, otherwise the last row of the column beside the navigation. It takes its own room, so nothing scrolls under it, and the page isn't remounted when it comes or goes; it is hidden while the quick chat is over the page. Without it the markup is 5.2's. - ChangeDiff (KIT-315, KIT-322):
reasons(path to one line) draws "The agent's reason, not verified: …" above that file's diff, as text.fileName="entity"names files by their entity in the tab and heading, with the path in the accessible name and a tooltip.selected(a path) andonSelectlet the app, or a ChangeTree, hold the shown file; withoutselectedit keeps its own, as in 5.2. - PortfolioCard (KIT-320):
usagedraws the workspace's usage against its own limit as UsageGlance's line, withusageUnknown,usagePausedandusagePeriodas UsageGlance'sunknown,pausedandperiod;action({ label, onClick }, the newPortfolioAction) is one button after the name's link. Withoutusageoraction, the card is 5.2's. - RaciChips (KIT-324):
show="word"draws the role's word ("Accountable: Maya") from theraciChipstrings. The letter in the default chip now comes from four new strings, so a translation can change it. - IntegrationConnect (KIT-325):
scopeIds="hidden"draws each scope by its label and description only. The id stays in the scope's accessible description and in whatonStartandonConnectsend back;writesis still marked. - RunLog (KIT-317):
toolbar, your own filters (a FilterBar) drawn in the log's header, andstatusFilter={false}to hide RunLog's All, Failed and Running filter. RunLog doesn't filter by your toolbar: pass it the filtered runs. link:opensElsewhere(event)is exported, for a menu of places that are also links; ScopeBreadcrumb and ScopeSwitcher import it (KIT-301).- EmailLayout:
renderEmailwrites a link only when it is http:, https:, mailto:, tel:, sms: or relative, read as a browser reads it (tabs and newlines removed, leading spaces and controls trimmed); anything else is dropped and the link reads as text. 5.2 dropped only a link beginningjavascript:. DigestEmail keeps the same links. - UndoWindow and WorkflowEditor read the clock after they mount, never while they render, so a Next 16 prerender with
cacheComponentsno longer fails on them (KIT-307). UndoWindow's server HTML still draws the action and, with no window given, the app'scannotUndowords; the time left and its bar appear once mounted, before paint. WorkflowEditor's schedule lists its next runs once mounted. - Names from the app drawn inside Candor's words have their direction controls neutralised (KIT-299, KIT-300, KIT-302): ArtifactToolbar, SessionList's archived and unarchived announcements, SettingsLayout, SidePanel, SplitView, CommandPalette's
searchFailed, PermissionMode, PersonMenu's initials, EnvironmentBand'senvironmentsIn, Toast's announcement, DockWindow's dialog, AppLayout's quick-chat Close, and EvalScorecard'sunitand FailureClusters'unitandsince.
`@candor-ui/react` 5.3.0
use-ag-uireads the clock after it mounts, never while it renders (KIT-307). Until then no events exist and nothing is judged expired.- Popover's anchor, Composer's
textareaRefand Thread'sscrollerRefgive the element to a ref the app passes after the first render, and a new ref takes over from the old one (KIT-296). - PageHeader's views name its title with the direction controls neutralised (KIT-299).
- EntityChip draws in the new
--cd-font-nametoken, which is unset by default: the chip then draws asfont-monodid, so it looks as in 5.2 until you set the token (KIT-323).
Nothing to do.
The new token
--cd-font-name (KIT-323): the typeface for names of things drawn beside code. It is unset by default, and the names then draw as Tailwind's font-mono does: your theme's --font-mono if it sets one, else --cd-font-mono. So nothing looks different until you set it. ChangeDiff's file names and path (Pro) and EntityChip (free) read it. Set it on :root or on any element around them (--cd-font-name: var(--cd-font) for your body font); it inherits.
Widened props
AppSidebar's, NavRail's and TabBar's (Pro) defaultActiveId accept null (KIT-303): the item holds the current place, with none marked at first, as Inbox's and ApprovalQueue's do since 5.2. Left out, as in 5.2. Code that passes it is unchanged. Code that reads its type into a string | undefined (ComponentProps<typeof TabBar>["defaultActiveId"]) fails the type check: add ?? undefined.
New string keys
Translators: these keys are new. Until you translate them, each says its English words. No key read in 5.2 changed.
agentScreen:markers,markerUnlabelled,markerOffFrame,markersHidden,waiting,waitingFor.changeDiff:reason,pathAside.raciChip:letterR,letterA,letterC,letterI(R, A, C and I).- New tables, one per new item:
decisionBar,decisionReview,turnRequest,screenGuide,changeList,changeTree,usageGlance,usageRing,digestandpageTabs. DigestEmail's words are its ownstringsoption (digestEmailStrings), since it renders outside LocaleProvider.
Some DOM your CSS may match
- ChangeDiff's file tab names and path line, and EntityChip's chip, no longer carry
font-mono; they carryfont-[family-name:var(--cd-font-name,--theme(--font-mono))]. A rule selecting.font-monoinside them no longer matches. - CommandPalette's
searchFailed, PermissionMode's confirm title, Cancel and failure line, EnvironmentBand'senvironmentsInand DockWindow's dialog heading draw the app's words in a<bdi>. - AppLayout with
bottomBarhas a new row,data-slot="app-layout-bottom-bar"; without it, nothing changes.
Docs
- SplitView's example is the phone composition Storywrite asked about in A-78 (DOC-15): SessionList and Thread in a SplitView inside AppLayout with a TabBar, the list then the thread with Back. It still shows SplitView alone, both panes wide.
- AgentScreen's example shows
controlStyle="strip"and a marker; each new component has an example. - The design doc's type table names
--cd-font-name.
CLI 3.3.0
- Every command the CLI prints names its own major,
npx candor-ui@3 …:update's "Update everything together",init's,doctor's,add's,key's,list's,search's andinfo's lines and the help, asmigrateandthemehave since 3.2.0. A project withcandor-ui@2installed no longer runs CLI 2 from a copied line (CLI-48). updatechecks every npm package the updated items name againstpackage.json, not only the ranges this update raised, so a project still below a range an earlier update raised is told again, with the same line and command (CLI-50). A specifierupdatecan't compare (workspace:,latest,1.x,||) is named only where this update raised the package's range, and*,xandlatestare never below one.- Where two items name one package with different ranges,
updatenames only the items whose own range is the highest with it, and past three gives a count. An open>=range inpackage.jsonthat already allows an item's range is no longer named as below it. lintknows the twelve new component names:DecisionReview,DecisionBar,TurnRequest,ScreenGuide,UsageGlance,UsageRing,ChangeList,ChangeTree,Digest,DigestEmail,DigestEmailPreviewandPageTabs, so a file that uses only one of them counts as using Candor.migrate strings-keysmoves an override of a string key renamed inside a namespace, for when a release renames one; none does yet (CLI-47).
For maintainers
release:checkruns an upgrade check from 5.2.0 too (tests/upgrade/5.0'salso, CLI-49), anddocs/RELEASING.mdsays each new minor adds its row there and toscripts/release-check.mjs'--fromlist.check:motionreads:not(…)inside:has(…)as not negating the element, and a loop under a container query needs a loader or progress drawing in everyorbranch (MOT-69).- The data-slots test fails on a
data-slotvalue it can't read unlessUNREADlists it (KIT-305). candorItemsOfreadsimport()andexport … from(KIT-306).check:neutralcountsstorywrite(ARCH-40).- The raw bidi scan reads
tests/andscripts/, and the tests that held a raw control write it as a\uescape (HK-13). - The home page's toggle tests load the lazy moments first, so they no longer fail under load (HK-12).
- The 5.0-to-5.1 strings test reads 5.1.0's snapshot (CLI-51).
Upgrading from 5.2
Nothing to do. npx candor-ui@3 update --to 5.3.0.
5.2.0 - 2026-11-13
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
scrollTopof 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 inscrollTopcounts 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 throughscrollerRef, 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'
…Lockedprops andlockedmaps, and Inbox's and ApprovalQueue'sdefaultActiveId, acceptnull(KIT-282, KIT-291), aslockeddoes since 5.1. For a…Lockedprop or alockedvalue,nullor left out is unlocked. FordefaultActiveId, onlynullmeans "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 astring | undefined(ComponentProps<typeof Plan>["acceptLocked"]) fails the type check: add?? undefined. The props: - RunEstimate'sstartLocked; PlanGate'supgradeLocked; DataControls'deleteAccountLocked,deleteHistoryLockedandexportLocked; SsoSetup'senforceLocked; AgentScreen'stakeOverLocked; Plan'sacceptLocked. - AccountState'sactions[].locked. - The values of thelockedmaps on ArtifactToolbar, RestoreDialog, ReviewLadder and NotificationPreferences. - Inbox's and ApprovalQueue'sdefaultActiveId. Theirselectedbehaves as in 5.1. - ApprovalQueue's (Pro) requester tile draws the name's first letter upper-cased, as a whole character, through the new
initialOfininitials(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 callsonChange, as before. - AppSidebar, NavRail and TabBar (Pro) draw their in-app places through the app's link (
LinkProvider, orCandorProvider'slink), so your router's link handles them (KIT-268). With none set each draws the<a>it drew in 5.1. A plain click withonNavigategiven calls it and the link doesn't navigate, as in 5.1; withoutonNavigate, 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}"): withchoices, 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'sdelta.vs,projection.basisandbasisand StatCard'sdelta.vsare each in a<bdi>. - Thread (free): while it follows the newest message, its scroller has
overflow-anchor: noneas an inline style, which overrides anoverflow-anchoryour CSS sets there; it has none while the reader is scrolled up. - ThemeSetting (Pro): with a stored theme outside
choices, the trigger hasaria-describedbypointing at a hidden element with thethemeSetting.usingwords. - 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.
lockedacceptsnullon everylockedprop, not on every item: in 5.1.0 the…Lockedprops (acceptLocked,startLocked,upgradeLocked…), AccountState'sactions[].lockedand the record-typedlockedmaps still takestring | 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 astring | undefinedneeds?? undefined, and Tree's two-parameteronSelectfails where a wrapper types it as(id: string) => voidthroughComponentProps<typeof Tree>(KIT-283). Lockedunder the app'sTooltipProvideropens its reason after the app'sdelayon 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:useFocusWithinand itsFocusWithintype (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'sautoFocus) 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
cacheComponentsno 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-widthand the push drawing fell back tomin(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).mcpInputViewandmcpInputResponses(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'sTooltipProvider, 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
updatesays whenpackage.jsonlists a package below an updated item's new range, with the command to install it, and leavespackage.jsonas it is ("lucide-react has ^1.60.0 in package.json; thread 5.2.0 needs ^1.67.0. Runnpm 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. Aworkspace:orfile:specifier is named as not compared (CLI-45).- Every command
migrateandthemeprint, and thethemeusage line, namesnpx candor-ui@3:migrate's "Not run" line, usage,strings-keys' line on a spread and its pointers toupdateandadd;theme check's fix for a renamed token, its file and motion hints and its pointers toupdateandinit;theme apply's andtheme from's lines, so a project withcandor-ui@2installed doesn't run CLI 2 (CLI-43). - The new string keys
updateandmigrate strings-keyslist count a key renamed inside a namespace as moved, not new (CLI-46).
Docs and the docs MCP
- The docs MCP's
theme_checknamesnpx candor-ui@3 migrate tokensfor a renamed token (CLI-43). - SubscoreCard's doc names
FindingData(KIT-272). DocumentViewer's example showsdefaultSelectedand RestoreDialog's showsdefaultOpen(KIT-273). Thread'sscrollerRefdoc 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:checkruns an upgrade check from 5.0.0 and from 5.1.0 to this version, on the 5.x fixture (tests/upgrade/5.0and itsalso), and runsmigrateonly 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@easevalue it can't read fails on either line (MOT-68); a loop needs its running state on every selector of a list.layers.mjsfails for an engine named inCANDOR_LAYER_BROWSERSor--browsersthat 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-slotan item draws is in the token manifest (KIT-280). tests/browser/thread-follow.mjsopens a thread 20 times in Chromium with A-61's late change and checks each ends at the bottom, and that PageUp with focus onbody, a text fragment (find in page's scroll) andscrollIntoViewunpin it, with no streaming and while a token arrives every 30 ms;npm run test:browserruns it after the hosted demos.- The OrgSmith pack's
package.jsonand a committedpackage-lock.jsonlist the packages its Candor items import, andnpm run candorputs both files back afteradd, so a laternpm installkeeps 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
\uescape (HK-10).
5.1.0 - 2026-11-13
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
onSelectedChangewithoutselected: a ticked item shows ticked, and the callback is still called. In 5.0 the tick never showed. Passselectedto hold the selection yourself: once you have passed it, the list keeps none of its own, so clearing it toundefineddraws none, as in 5.0. - ConfirmButton (Pro) stays armed for 6 seconds by default in English (4 in 5.0): left out,
armedForis 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. PassarmedFor={4000}to keep 5.0's window; a test that waited 4 seconds for it to disarm waits for the new window or setsarmedFor. - Six data types'
lockedfield acceptsnull(string | null | undefined):PaletteItem,ScopeLevel,SettingsItem,DashboardTileView,PermissionModeOptionandPlanAutonomyOption. Code that builds them is unchanged; code that reads one into astring | undefinedvariable 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 newheadingLevel. 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 passesheadingLevel; a test that found AccessRequest's title as text inside a scope finds it by roleheading. - 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.goToWindowandgoToWindowTitle.board.unplaced(one and other) andboard.columns;dataTable.sortCleared.usageMeters.amount,usedOfLimit,limitAfter,unitAfterandwithPending. The keys UsageMeters read in 5.0 are still read.runTree.readoutStatusandreadoutJoin.from,afterandverdictNoteare still read, as their placeholders.- The Premium templates' strings that held " · " (
agentOpsConsole.topLineandtopLineStopped,approvalsInbox.owner,member,ruleHeading,waitingLineandrequestDescription,supportCopilot.threadCustomerLineanddraftCardHeader) take{separator}, the locale's separator, in its place;agentOpsConsole.startedByandapprovalsInbox.appliedByno longer hold it, since the template joins them. An override that kept its own " · " instartedByorappliedByshows 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
labeland 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 newemail-headingpart. - SheetContent (Pro) carries
data-edge(top,right,bottomorleft, 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 newlive-rowspart. - A stacked Carousel (Pro): the slides' row is
aria-live="off"("polite"in 5.0), andCarouselStatushas noaria-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 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 noHeadingScope: passheadingLevel={3}to keep 4.x's<h3>.HeadingScopeis named as Pro.strings-separator(CLI-34):Formatterhas two new members,separatorandjoin, so an object you build as aFormatteryourself (a test double foruseFormat) fails the type check until it adds them.locked-not-disabled(CLI-40): the reasons the waiting controls give are 50 newlocked…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 addsclarifyingQuestions.before.props-active-id-nav(CLI-35): its search finds SettingsLayout'sactive=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 withcandor-ui@2installed doesn't run CLI 2 (CLI-37).
New items (Pro)
link:LinkProvider,useLink,LinkRenderandLinkRenderProps. Set how Candor's items draw an address in the app (a Next or TanStackLink) once, or throughCandorProvider's newlinkprop, 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:mergeRefsanduseMergedRefs, 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 gainsdata-slot="live-rows", listed below).email-heading:EmailHeading, EmailPreview's title at the level the page'sHeadingScopegives it; a client part, soEmailPreview,EmailLayoutandrenderEmailstay free of"use client".user-message-actions:UserMessageActions, Copy and Edit and send again on the person's own message, placed in Message'smeta. Edit hands the app the message's words throughonEdit; what the person sends is a new message, and this one stays in the thread, so the app keeps the versions. Copy appears whentextis given, and Edit when bothtextandonEditare.
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. defaultActiveIdon SessionList, SidePanel, AppSidebar, TabBar, NavRail, AgentRoster, Inbox, ApprovalQueue, Plan, RunTree, VersionHistory, GraphView and Tree;defaultSelectedon DataTable, DocumentViewer and the four charts;defaultOpenon 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, withundefinedas none, sees none when it clears it. A chart'sdefaultSelectedand Tree'sdefaultActiveIdtakenullto keep the selection with none at first. DataTable keeps its own selection withoutonSelectedChange, as in 5.0; withonSelectedChangeand noselected, passdefaultSelected(an emptySetfor none) to have it tick the rows a person selects.- Inbox takes
activeIdand marks the item open beside it (KIT-234). - AccessRequest takes
headingLevel(KIT-252).useHeadingScope(), fromheading-scope, gives the nearestHeadingScope's level, orundefinedoutside one. - DataTable: a column with
sortable: falsehas no sort button, noaria-sortand no place in the stacked sort control (KIT-221). - Tree's
onSelectpasses 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 overas(KIT-238). - DateRangeField takes
name(hidden inputs{name}.fromand{name}.to) anderror, as DateField does (KIT-190). navRailTabstakes the rail'spinnedplaces, somorecounts a pinned place left off the bar (KIT-167).lockedacceptsnullon every item, free ones (Slider) included;nullor 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'shideHeader="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 callsonMatchChange(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
holdpassed 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
Lockedpasses every key but Enter and Space (and ArrowUp and ArrowDown on a popup's trigger) to the control's ownonKeyDown, so a locked inline TypeToConfirm can still be cancelled with Escape (KIT-176).Lockedunder the app'sTooltipProviderjoins its delay group, so moving between locked controls skips the delay (KIT-224).useTooltipProviderAbove(), fromtooltip, 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).
lockedacceptsnull(Slider). PermissionPrompt's doc showsheadingLevel={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-edgeand pushes the page by the sheet's own width, with a Tailwind prefix and in RTL (MOT-50). A 5.0 sheet, which has nodata-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 outdata-motion="none"and calm (MOT-56, MOT-57). - The row-hover drawing on a
<tr>is checked in WebKit (MOT-52). - With
expandand the ripple, an icon button's name isn't trapped under the next button (MOT-65).
CLI 3.1.0
migrate constructor,toStringandhasOwnPropertysay there is no such codemod, as any unknown name does (CLI-39).update --differing keepkeeps its copies by number inside.candor-keep/, never outside it from a monorepo path;updateanddoctorsay when one is left behind (KIT-192).- Where it can't work out what installing an item's new dependencies writes, a plain
updateno longer runs shadcn's dry run to list it; only--differingdoes, since only it reads that list (KIT-225). types-datarewritesexport type { ToolCall as Call }toToolCallData as Call, and the other five types (CLI-38).strings-keyslistsstandardCardsinsideobserver(…)or an app's own wrapper, rather than rewriting it into the wrong scope (CLI-42).updatefollows a monorepo theme moved out of the shared package and recorded (CLI-41).- The commands
updateprints, and the upgrade page's, namenpx candor-ui@3(CLI-37). theme check:motion-valuedoesn't say a keyframe-named value plays nothing where it plays (MOT-61).addandupdateleave a dependency's specifier alone when it already satisfies the item's range, so exact pins stay pinned.- Where the project's
utilsalias already exportscn,addandupdatewrite nolib/utils.tsand add nocnpackage; the plan and--dry-runname every npm package before anything is written. migrate headingslists<AppLayout>only withchat, and leaves out a heading whose 5.0 level is already what 4.x drew;types-datawritesMessageData, notMessageData as MessageData.updateandmigrate strings-keysprint 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.updatenames npm packages the updated items no longer import and no other recorded item needs ("No longer needed: cmdk"); it removes nothing.--differing replacenames 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 --verboselists them.
Docs and the docs MCP
- The docs MCP's
theme_checkdescription namesmotion-value(MOT-62). - PermissionPrompt's example shows
headingLevel={3}in a dialog (KIT-243); SemanticBadge's doc namesFindingData(KIT-257); LiveRows has an example. - Diagram's doc says that
mermaidloads only whensourceis drawn, never fornodesandedges, 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 loadedmermaidlazily, throughimport(), and a test now holds it.
For maintainers
scripts/motion-baseline.json's entries name a problem's place (file,at,rule, and acountwhere there are several), not its words, andcheck:motionsays which entry no longer matches (MOT-59). With 5.1's fixes it is empty.check:motionstrips a negated running state before it decides (MOT-60), and its@easecheck says a value it can't read can't be checked, not that it doesn't overshoot (MOT-64).release:checkcounts 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
popupClassNameon the open menu (KIT-206);contracts.mjs --listis tested and its header names every group (KIT-208, KIT-209);fresh-app.mjsreads the Radix app's Candor items from the layer page's imports (KIT-212). - The OrgSmith pack installs through
candor-ui add, socandor-lock.jsonis written, and its.gitignorecovers what the install writes (ARCH-36, ARCH-37). - Two test files wait on fake timers, not real time (HK-8).
5.0.0 - 2026-11-13
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-runprints what 5.0 changes for the items incandor-lock.json, and writes nothing. - Update:
npx candor-ui@3 update --to 5.0.0updates every item, merging your changes into Candor's asupdatealways has. - Migrate:
npx candor-ui@3 migrate 5.0.0runs 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-runshows 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 page lists):
types-data(codemodtypes-data):MessageandToolCall(lib/candor/chat),ApprovalRequestandResultTable(lib/candor/work),Finding(lib/candor/data) andRunReceipt(lib/candor/ops) areMessageData,ToolCallData,ApprovalRequestData,ResultTableData,FindingDataandRunReceiptData, the names@candor-ui/reactalready 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/reactdon't change.heading-default(codemodheadings, which lists): withoutheadingLevel, an item's top heading is one level below the nearestHeadingScope, 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>: passheadingLevel={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 withoutheadingLevelwith the level it drew in 4.x, and changes nothing: where a page or a test needs that level, passheadingLevel={n}, or wrap a section in<HeadingScope level={n}>(lib/candor/heading-scope).heading-level-type(no codemod: nothing to change):headingLevelisHeadingLevel(1 to 6) on every item, where DataTable, ReorderableList, Board and BoardCard, NarrativeBlock, PortfolioCard, MonitorCard, DashboardTile and EnvironmentList took2 | 3 | 4 | 5 | 6. A level you pass still type-checks. Where you type a level of your own, importHeadingLevelfrom lib/candor/heading-level (layout/headingstill exports it).props-active-id-nav(codemodprops): TabBar's and NavRail'scurrent, AppSidebar'sactiveNavand SettingsLayout'sactiveareactiveId, with the same value. Stepper's, PlanPicker's and InlineSuggestion'scurrentmean something else and stay.props-label-name(codemodprops): SettingsLayout's and DocumentViewer'stitle, their accessible name, which isn't drawn, islabel;titleis Candor's word for a heading that is drawn.props-popup-class(codemodprops): PersonMenu's and ScopeSwitcher'slayerClassprop, the classes for the menu's popup, ispopupClassName.on-select-id(by hand): Tree's and EnvironmentBand'sonSelectpasses the id of the node or environment, not the object. WriteonSelect={(id) => …}and look it up by id where the handler needs it.migrate propslists eachonSelecton them, and the type check finds a handler that still takes the object.strings-compat-exports(codemodstrings-keys):statusLabel(lib/candor/status),environmentLabel(lib/candor/team),approvalStateLabel(approval-request),reviewLevels(review-ladder) andstandardCards(standard-cards), English only, are removed. The codemod rewritesstandardCardsused inside a component toconst standardCards = useStandardCards()at its top, and lists the others, andstandardCardsused outside a component, with what to use:useStatusLabel()(label("running")); EnvironmentBand'sproductionandnonProductionstrings joined withuseFormat().join;useStrings("approvalRequest", approvalRequestStrings);useStrings("reviewLadder", reviewLadderStrings). SessionList'sstatusLabelprop is a different thing and stays.chart-strings(codemodstrings-keys):barChart.byCategory,lineChart.over,lineChart.chartValuesandheatmap.heatmap, unread since 4.2, are removed. An override of one still compiles and draws nothing; the codemod deletes it.strings-separator(codemodstrings-keys): the " · " between parts is one string,strings.locale.separator, read throughuseFormat().separatoranduseFormat().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.hintSeparatorandmarkSeparator, andreviewQueue.hintSeparator. The codemod moves an override of one tolocale.separator; where two give different values, it lists them for you to choose.subscoreCard.separatorandtableScrubberMap.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}") andcheckedAt("checked {when}"),subscriptionStatus.cardExpires("expires {expires}"),membersTable.invitedBy("Invited by {name}", with the newexpiresIn),awayDigest.group("{label}"),blastRadius.group("{noun}s"),escalation.sentLineandacknowledged,environmentPromotion.requestedBy,promotedanddeclined(each without{when}),taskTray.started("started"),clarifyingQuestions.progress("question {step} of {total}", with the newbefore),agentRoster.failed("{count} failed") andcolumnMapper.suggested("Suggested", with the newpercentSure, "{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}", andgradedCount) anddataTable.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(codemodstrings-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.addedandremoved(addedNowandremovedNow, "Added 3 to Members, which now holds 5.") andtotal;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.problemsCountandworkflowEditor.graphProblems(problems);plan.sentBackSummary(notAccepted);shipReview.summary(createdCount,updatedCount,deletedCount); andenvironmentConnect.nameDetail,environmentPromotion.nameDetailandapprovedAt,driftChange.whereandplan.proposedSummary, whose parts Candor joins with nothing to translate; so docomposer.scopeChip,composerScopePicker.scopeChip,searchTrace.counts,appSidebar.labelCount,inbox.needsYouCountandsessionList.contextKindShown, which held " · " in 4.x; andinbox.needsYouCountAtLeast(countAtLeast, "{count}+", joined toneedsYou). 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.measuredFailedandfailedWithFiles.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 afteronDismiss, or when the promise it returns settles. WhereonDismisssaves before it takes the card out, return the promise (anasynchandler does), or the dismissal isn't announced.locked-not-disabled(no codemod: behaviour): a control that waits on something stays focusable and isaria-disabledwith the reason, throughLocked, where it was nativelydisabled; 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 newlocked…strings. Composer's box and TypeToConfirm's arereadOnlywhile locked. WithonGoTo, every StepWalker stage is a button: a stage not reached yet is locked, and the current one is markedaria-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, checktoHaveAttribute("aria-disabled", "true")in place oftoBeDisabled(), and find such a row by its text. Nothing changes in the app's code.cli-3(no codemod): usenpx candor-ui@3for 5.0. It works with Candor 4.0 and later.npx candor-ui@2stays on npm for a 3.x project (upgrade it to 4.0 with@2first), forupdate --fold, and forupdate --from, which records items installed before the lockfile.
New items (Pro)
heading-level: theHeadingLeveltype (1 to 6), in lib/candor/heading-level. The free items type theirheadingLevelwith 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; andbelowLevel(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>, takesheadingLevel, and its controls and steps sit one level below its title. - Chat: EntityDisambiguation (a fixed
<h3>in 4.x), ThreadHeader and FormErrorSummary takeheadingLevel. The free MessageContent takesheadingLevel, 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 roundchange, 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
HeadingLeveland 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>); passheadingLevel={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.scopeChipandsearchTrace.domainSeparatorare gone, as above. localeStringsis exported, withlocale.separator;useFormat()givesseparatorandjoin(parts).statusLabelis no longer exported: useuseStatusLabel(). The data types' names don't change here.- ToolCall, PermissionPrompt and Composer: a control that waits on something is
aria-disabledwith the reason, and stays focusable, where it was nativelydisabled(locked-not-disabledabove). Composer's box isreadOnlywhile 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 aspanunless you passonScopeClick. In a test, checktoHaveAttribute("aria-disabled", "true")in place oftoBeDisabled(), and find such a row by its text. A translated app translates the new reasons: ToolCall'slockedNoDetail; PermissionPrompt'slockedBusy,lockedInvalidandlockedUnanswered; Composer'slockedUnavailable,lockedHeld,lockedEmpty,lockedSendingandlockedStreaming.
CLI 3.0.0
- New:
migrate 5.0.0, with the codemodstypes-data,props(5.0's renames andonSelectlisting),strings-keys(the separator, the removed keys and the English exports) andheadings(lists only). A codemod table's row says which release it belongs to, somigrate 4.0.0makes none of 5.0's changes. add,updateandmigraterefuse a project older than 4.0, namingnpx candor-ui@2(and@1for 2.x).- Removed, with 3.x:
migrate motion-aliasesand its tables; strings-keys'message.thinkinganduseAnsweringApprovalsrows;update --fold, which now refuses and namesnpx candor-ui@2 update --fold; andupdate --from, which namesnpx 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 namenpx candor-ui@2 migrate motion-aliases. - Fixed: a table rename keeps an inline
typemodifier on the import. migrate, andupdatewhere it moves files, run on a TypeScript 7 project: where the project'stypescripthas 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 UIasChildrewrite inaddandupdatestill 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.mjslooks throughHeadingScopeto an item's root.
4.5.0 - 2026-11-12
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
onTogglesays "On" or "Off" in words (span[data-slot=monitor-on], the new stringsmonitorCard.isOnandisOff) in place of a switch that did nothing when pressed. An unavailable monitor keeps its switch, locked with the reason. PassonTogglewhere the person can turn the monitor on or off; a test that found the switch on a card withoutonToggleshould 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 itsstatusleaves"open"or a new change arrives; then it announces the outcome. Setstatusto"adopted"or"reverted"whenonAdoptoronReverthas 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.announceRuleandannounceRuleAlone, the announcement once the person stops changing the rule. An app that translated 4.4'sannounceNextand not these still hears its own words, joined as 4.4 joined them.announceNextis 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.isOnandisOff;driftChange.waitUpdateandrevertUndo;modelKey.cancelLocked;permissionMode.changingLocked;linkPreview.userinfo;dateField.readingWithProblem.sessionList.contextWordsandcontextKindShown;cardDeck.dismissedNext,keysMoveDismiss,keysMoveandkeysDismiss;dataTable.sortBy,notSorted,order,ascending,descendingandsortFirst.- IntegrationConnect's hold:
integrationConnect.waitingTitle,waitingNote,blockedTitle,blockedNote,approveWho,approveWhere,blockedWhat,unblocker,askedAt,holdCheckedAt,checkAgain,checking,waitCheck,checkFailedandback. - The workflow graph's move:
graphView.places, andworkflowEditor.move,moveNode,moveHint,cancelMove,cancelMoveNode,triggerFixed,placeAt,placeHere,pickedUpandputBack.
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-disabledinLockedwith the reason "Changing the mode" (permissionMode.changingLocked), notdisabled, and focus stays where it was. A test that expected them disabled should checkaria-disabled="true". - CardDeck (Pro) lists its keys in
aria-keyshortcutsand 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 nobrand, notopand 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 ownTooltipTriggerround it finds the app'sTooltip. Locked's tooltip now sits beside the control rather than round it.lockedimports@base-ui/react/tooltip. EachLockedalso has its own tooltip provider, on yourTooltipProvider's timing, so moving from one locked control to the next waits the provider'sdelayagain rather than opening at once within itstimeout. 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 throughLayerPortal, 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 indocument. - Tabs (Pro) leave
data-tab-valueoff a tab whose value is an object or a function, where 4.4 wrote "[object Object]"; strings, numbers, booleans,nulland 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 ownstyle, 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 inlocale("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-menustill exportsinitialsOffor 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) andmoving(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, asettlemoment in the move family. Withoutplacesa 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"),onCheckAgainandonBack, 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. Withoutholdnothing changes; once connected,holdis 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):
stackBelowis 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
entryandonEntryChange, to control the second entry;entry=""resets it and its judgement. Both entries are compared afternormalize("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
attendno longer replays it, and a step pressed whileattendrings 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) ornull. After text it couldn't read, the app'svalueis 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'sheadertakes 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 keepsfrom="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
flippedwhile 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
valueon 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
endsAtis 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.
initialsOftakes 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 fromperson-menuwithout one and wants the language's letters passesuseLocale().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 ownonKeyDownandonClickstill run. - Progress (free) is seen in forced colours: a measured bar is filled in
Highlighton aCanvastrack edged inCanvasText, and an indeterminate bar shows aHighlightband, 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: expandshows an icon button's name beside it without widening it or moving its neighbours, and leaves its position andz-indexto 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-signfrom: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-signis the kit's own, set by TabsContent, not a token:theme checksays so if a brand file sets it. Remove the line.
CLI 2.3.1
update --differing keep, whereaddcan'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 aslib/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'stheme_check) warnsmotion-valueon a--cd-show-*or--cd-draw-*value the item doesn't draw, naming the values it takes;noneandvar()aren't judged. The exit code doesn't change.theme checkand the theme builder no longer say thatmark: fadeandpop: riseneed the Pro item: their keyframes are in the freecandor.css.
Docs and the docs MCP
suggest_componentsanswers "a table with sortable columns" and "a sortable table" withdata-tablefirst. 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 answerstable. Withsdk: "claude", a related Premium block is judged as the version the ranking found, so its-claudeversion is no longer dropped for its own words; no answer on today's index changes.
Site and repository
/screens: thehome-dashboardbrief scores as a weighted mean of its subscores and usesDashboardGridas/apps/workspacedoes;/screens/app-shell#topbarlands 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:motionchecks each@easeline'sovershootsagainst its values; that every show or control rule leaves outdata-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 inscripts/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.tsfails when a bold label in this file says "(free)" of a Pro item.
4.4.0 - 2026-11-12
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-hiddenspan[data-slot=glide-highlight]as their first child; TabsList holds one after itstabs-indicator; AppSidebar's places and NavRail hold one too. The container getsdata-glide(and isisolate; a menu popup is alsorelative). 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 owndata-slot, or skip[data-slot=glide-highlight]. - AppSidebar's person menu is a
PersonMenu. Its trigger is[data-slot=person-menu](withdata-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 carrydata-slot="app-sidebar-item". PopoverTrigger(free) andHoverCardTrigger(Pro) keep a rendered control's owndata-slot, asTooltipTriggerhas since 4.3: aButtongiven throughrenderstays[data-slot=button]. Only the trigger's own element ispopover-triggerorhover-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, putLockedaround it (<Locked reason={…}><PopoverTrigger render={<Button />} /></Locked>), not inrender:Lockedpasses on nothing the trigger gives it, so inrenderthe button would never open anything.- DataTable's selection boxes and ConsentCeremony's acknowledgement are Candor's
Checkbox([data-slot=checkbox],role="checkbox"), notinput[type=checkbox], so the person's tick is drawn. The select-all box isaria-checked="mixed"when part of the page is selected. A test that read.checkedor firedchangeon the input should find the box by role, readaria-checked, and click it. StreamingText(free), when a brand names a stream drawing (--cd-show-stream, from the Promotion-drawingsitem), 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, agetByTexton a whole reply while it streams can miss it: read the[data-slot=streaming-text]element'stextContent, 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 theKpihas one), so only the number moves.KpiRowwith five or more cards is aDashboardGrid, still[data-slot=kpi-row]. CSS aimed at the figure's text should select[data-slot=stat-card-value]. DegradedPanel's Retry (free) isaria-disabledinsideLockedwhile a retry runs, notdisabled. A test that expected it to be disabled should checkaria-disabled="true".- PlanPicker's Fewer seats (Pro) is
aria-disabledat the fewest seats, notdisabled, and is described by why (the "At least …" line, or the new stringplanPicker.atFewest); a press does nothing and focus stays on it. A test that expected it to be disabled should checkaria-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 isconfirm-button-trigger(the wrapper isconfirm-button), and CorrectionOffer's Use and Keep arecorrection-offer-acceptandcorrection-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 areaccordion-gallery-triggerand CardDeck's focusable stack iscard-deck-stack. - Smaller DOM changes: SetupChecklist's done tick is
svg[data-slot=setup-checklist-tick], no longer lucide'ssvg.lucide-check; RadioGroup's indicator isabsolute inset-0 flex, notrelative flex; SplitView's detail body isdiv[data-slot=split-view-detail-body]; and DegradedPanel's Retry (free) always sits inspan[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>. AgetByTexton the text alone still finds them. - Added attributes, with nothing to do: tab triggers carry
data-tab-value; Switch's thumb carriesdata-turned="a"or"b"after a flip the person makes; the × of a Dialog, Sheet or Drawer, and the Close DialogFooter draws withshowCloseButton, carrydata-dismiss; chart marks carrydata-mark; Button sets--cd-press-xand--cd-press-yin its own style where a pointer pressed it.
New items (Pro)
ComposerScopePicker, a picker for where the next message's work lands, for Composer'stools: scopes grouped by kind (environment, client, project, or personal, read "Just me") in aPopover, each with its icon and words, and production still a warning in words. The arrow keys, Home and End move without choosing. Propsscope,scopes,onScopeChange; typesComposerScopeChoice(aComposerScopewithkindandid) andComposerScopeKind; the pill's separator is the stringscopeChip. Scope names are neutralised and drawn in a<bdi>. The free Composer's ownscopeis 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 belowcompactAtof 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()makesTabBar's destinations from the same places, the ones the app picks, anduseNavRailTabs()does so in a component, naming a counted tab through the new stringnavRail.waitingwith 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;compactleaves 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 adetailline and the menuactions.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 inThemeSetting's words, and the app's ownchoices, 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:computedAtandbasisare required, the delta names its period, a null score says "Not computed" and why, andprojecteddraws 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 stringsenvironmentList.setActiveName("Set active: {name}"),reconnectNameanddisconnectName.BoardandBoardCard, a kanban board onReorderableList: 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>.InputGroupwithInputGroupAddonandInputGroupCount, 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 thebasisit was measured by and says "Not checked" fornull.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 stringsliderMarks.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, whilearia-disabledor insideLocked, 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 onceonConfirmresolves. - 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 …" paststaleAfter, and stops whenstatussays the work is over; its shape isshapeor--cd-draw-loader, and its turning is alivemoment of its own, so a brand's--cd-motion-loader-turningand its-durreach 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.brandis the banner's first child, laid into the navigation's column, so it sits over the rail level with the top bar; the navigation (aNavRail, or anAppSidebaras 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 onvar(--sidebar), a transparent border, a radius of 0) or sunken (var(--cd-sunken)in a--sidebar: var(--card)chrome). BelowsidebarAtthe banner holds the brand, the menu button andtop. 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, anduseHideOnScrolldoes the same for an app's own header.--cd-nav-rail-widthsets the rail's width. - TabBar (Pro):
TabBarDestination.badgeLabelnames a destination with a badge in your words ("Approvals, 3 waiting") where TabBar's "3 new" would be false;navRailTabssets it. - StatCard and KpiRow (Pro):
Kpigains optionalunit(drawn after the figure and read with it: "2.4M records"),note(a second line in words) andestimate: { basis }(the card says "Estimate", read as "estimated", and the basis in words). StatCard takesicon; KpiRow takesiconOfand lays five or more cards out throughDashboardGrid, 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.useCountUpis exported fromstat-cardfor your own figures. A 4.3Kpidraws 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 anEntityChipunder 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
scopetakes akind("environment", "client", "project" or "personal") asThreadHeaderScope, drawn with the kind's icon and words; a personal scope reads "Just me", and production is still a warning. A scope withoutkinddraws as in 4.3. - DataTable (Pro):
stackBelowdraws 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 stringdataTable.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;codevalues are identifiers (left to right, never translated);DetailRow.copyadds 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.SubscoreTileextendsSubscore, 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 throughLocaleProvider. - ReorderableList (Pro) gains
groupHeader,collapsedandonCollapsedChange; 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):
DialogandSheettakeonDismissAttempt(returnfalseto stay open), as the drawer does, andDialogContent,SheetContent,DrawerContentandResponsiveDialogContenttakeunsaved("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 Promorphdrawing. The drawer's backdrop follows the drag, andDrawerSwipeAreaopens 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 importui/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 })sayspendingwith a spinner, is never dismissed while it waits, then shows its result (a failure stays until dismissed) and returns the promise; if asuccessorfailurefunction throws, it settles on the new stringstoast.succeeded("Done") ortoast.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'sdismissToast) moves to the next toast or back where it was. A toast's title and detail, andtoast.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
focusAfterClearref. 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):
Fieldtakesvalidating("Checking…") andvalid, the app's word that its check found nothing wrong: "Looks good" shows only whilevalidis set, and is never inferred from a check that stopped or an error that was cleared, so clearvalidwhen the value changes. Its hint arrives when it appears or changes.NumberInputtakesscrub, 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 arearia-disabledand described by what describes the field (Locked's reason), and the grip is inert.ToolbarGrouptakesreveal, for a selection's actions, announced once.SplitViewtakesdetailKey, so the detail arrives when the selection changes without remounting.RunEstimatetakesendsAtand counts down to it in the locale's units, hours included ("Expected to end in 4m 12s", the new stringrunEstimate.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 showninertand 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 inCarouselContent, 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 stringchartFrame.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, andonCheckAgain) or"blocked"(their policy blocks it, and who can unblock it). The hold stands in place of the ways of connecting;onBackis the app's way back. Withouthold, 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 carriesdata-turnedafter each flip the person makes, Button notes where a pointer pressed it (--cd-press-x,--cd-press-y), andStreamingText, when a stream drawing is named, marks newly arrived text withdata-arrivedfor 600 ms. The free kit draws none of them;motion-drawingsdoes, and its file's header names them. - The
attentionfamily takes Pro drawings through the new--cd-motion-attention-variant, which falls back tocd-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 drawsvg[role="group"].cd-show-drawnow reaches them. A brand that set--cd-show-charts: cd-show-drawsees its charts draw in. - Fixed: clip-path draw-ins appeared at the halfway point. 4.1's chart draw-in and the
wipedrawing, 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-entrancegainscd-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: staggerbrings an opening dialog's, sheet's, drawer's or menu's parts in from 0.4 opacity, never from nothing.--cd-show-chartsgainscd-show-sweep(donuts and score rings sweep round from 12 o'clock) andcd-show-grow(bars grow from their baseline);--cd-show-points: poppops 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: countcounts 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: typeturns onTypedText.--cd-show-hovergains 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 | pushmoves 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 oraria-disabledbutton, or in forced colours.--cd-draw-focus: rippleon 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-loaderfor 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
-varianttoken: for opening and arriving,curtainandclip(reveal, overlay),circle,roll,stretch,slide-scale,blur-slide,elastic-slideandflip-x(overlay, arrive), andheight,zoom-throughanduncover(overlay);morph(overlay), forDialogContent from="trigger";slide-from(arrive), tab panels coming in from the chosen tab's side;carousel-fade,-vertical,-blur,-zoom,-uncoverand-fill; for ticks and dots,fade,zoom,spin-in,jelly,tick-rise,swingandblur(mark), andjelly,riseandripple(pop), for example--cd-motion-checkbox-tick-variant: cd-spin-in;jolt, the error shake, andbeat(attention), for example--cd-motion-input-invalid-variant: cd-jolt;flashand six number drawings,number-flip,-blur,-pop,-drop,-zoomand-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
-easetoken asvar(--cd-ease-<word>):stiff,snappyandgentle, andbouncyandwobbly, which overshoot (move, pop, arrive);anticipate,linear-travelandsnap(move);steppedandsettle(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
changedon 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 playvalue: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 checkreads whatmotion-drawingsadds in 4.4 (also the docs MCP'stheme_check): a-easeofvar(--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 themotion-springerror, asspringis. Theattentionfamily's-varianttoken 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 checktreatscandor-motion-drawings.cssas Candor's, as it doescandor.css. It followed the app's@importof 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.lintknows the new items.ProgressButton,ConfirmButton,InputGroup,InputGroupAddon,LinkPreview,MaskedInput,TopBar,NavRail,Board,BoardCardandLoaderare 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_componentsnames 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 namescode-editoralone, and "wysiwyg editor" names nothing. "A kanban board of tasks" now answersboard, 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, thendata-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-dashboardscreen (dashboard, quiet and phone layouts). A screen can name its running example, whichget_screenreturns; 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;/appnow 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/apppoint at/apps. /screensshows the workspace frame layout and the newhome-dashboardscreen, each with a link to its running example.
For maintainers
candor-motion-drawings.cssis assembled bynpm run themefrom partials insrc/styles/motion-drawings/; 4.1's and 4.3's rules are01-base.css, unchanged but for the ends of two keyframes,cd-wipeandcd-show-draw(the clip-path fix), whichtheme.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,@nameand@easelines,check:motionchecks 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 withnode tests/browser/contracts.mjs --only <group>.
4.3.0 - 2026-11-12
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: thecmdk-*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 byaria-label, fromCommand'slabel). The highlighted item hasdata-highlightedinstead ofdata-selected="true"; a disabled item hasdata-disabledpresent (andaria-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; passfilterfor your own. Items sit in a[data-slot=command-group-items]element (role="group") inside each group, and there is no--cmdk-list-height.CommandEmptynow announces its words once as typing empties the list, so agetByTexton them finds them twice: scope it to[data-slot=command-empty]. Replacedata-[selected=true]:withdata-highlighted:and[cmdk-item]with[data-slot=command-item]. Lockedalways draws its wrapperspan[data-slot=locked], withdisplay: contentsanddata-unlockedwhen 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 owndata-slot. A control insideLockedkeeps its owndata-slot: before 4.3, a locked one took the tooltip trigger'sdata-slot="tooltip-trigger", so a locked Switch or Checkbox lost its checked state in forced colours.TooltipTriggernow 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
sectionhastabIndex="-1", so focus has somewhere to go when a row's detail closes; withrenderDetaila virtualised table's rows sit in onetbodyeach, and withgroupByeach group is atbody. - 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 aThemeSetting, with adata-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'stabBarand belowtabBarAt(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 (belowchatAt, 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;useDockMorphgives your own docking the same slide.useAutoDensity(choice?), the value fordata-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:
ChoiceCardGroupandChoiceCard, 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,ButtonGroupSeparatorandButtonGroupTextjoin buttons into one control, in a row or a column, right to left too.DateFieldandDateRangeFieldread 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 freeSliderdoesn't change).DualListboxmoves options between Available and Chosen with keys or buttons that say what, how many and why not; each move is announced. - Navigation:
Toolbarand 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 whoseonSearchhears the text once typing pauses, at once on Enter, and""when cleared, withshortcut,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 …".TimelineandTimelineItem, 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 betweengroups, 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):
renderDetailgives a row a disclosure button that opens a full-width row under it (expanded,defaultExpanded,onExpandedChange,expandMode).groupByputs rows under group headings ("Production (12)"), sorted within each group (groupOrder,groupLabel, andgroupCountsin server mode; without it a heading says the count is this page's).pagenow works in memory too, withonPageChange, so aTableScrubberMapcan drive an in-memory table: if you passedpageto an in-memory table (it was ignored), it now applies, so passonPageChangeas well, or droppage.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: buildTableScrubberMap'smarksfrom 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 }),isLeafandcap. A node whosechildrenis left out has children to load ([]has none); each loads once, shows "Loading…", offers a retry when a load fails, and pastcapa "Show more" row loads the next page. Loads are announced. WithoutloadChildren, a tree behaves as before, witharia-posinsetandaria-setsizeadded. - SessionList (Pro):
Session.archivedmoves a thread behind one "Archived (n)" row, which a search still finds;onArchiveadds 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'stimeZonewhen you set one. Archiving, unarchiving or deleting a thread moves focus to the next one. - Dialog (Pro):
DialogContenttakessize("default", "wide", "full"); the newDialogBodyscrolls 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 yourattachmentPreviewandcomposerstrings 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 owndata-slot.- Menus (Pro): a
DropdownMenuItem,ContextMenuItemorMenubarIteminsideLocked, oraria-disabled, or whoseonClickcallspreventDefault(), no longer runsonSelect, and the menu stays open. - Command (Pro):
defaultValueand a controlledvalueset the first highlight (before, the first item was always highlighted, and a controlledvaluegotonValueChangewith the first item's value on mount).CommandDialognames its search box by itstitle, or "Search";CommandInputno longer acceptsdefaultValue, which it never read; Enter and the arrow keys in another field inside aCommandare 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 tofalsewhere 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);renderMessagegets{ 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 optionalbreaks: 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,tiltandghost; for adding and removing,fall,slide-start(mirrored right to left),bounceandzoom.
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,updatenow works out every such file the wayadddoes, before writing anything: a shared item you've changed, such as the tokens, and alib/utils.tsof your own thatcandor-lock.jsondoesn't record. Without a terminal and without the flag, it stops there and names each file.--differing keepkeeps every one of them, and their records incandor-lock.json;--differing replacetakes what the install writes; both name the files. If the registry can't be read to tell,updatestops before writing too (without a terminal, or withkeep).--differingwith--no-depsis refused.--dry-runsays where the real run would stop and which files, and exits 1 if it would. While shadcn runs,keepholds 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.--recordand--differingare refused on commands that don't use them.addandupdaterecord 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, andverifyno longer calls a CLI 2.2.0 entry stale where shadcn had kept the file's"use client"line.verifynames a stale entry, and where the file is Candor's as released,npx candor-ui verify --recordrecords its hash again: it changes onlycandor-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.lintknows 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 lintfails on any warning; the kit has none.
4.2.0 - 2026-11-12
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
svgwas arole="img"named "{series} by category"; it is now arole="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 arole="img"per bar ("Mon: Passed 3"). - LineChart's
svgis arole="group"named by the title, with arole="img"per point; the focusable "Chart values" element is gone (the table view has them). - DonutChart's
svgis named by the title, not the list of parts; each slice is its ownrole="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.chartValuesandheatmap.heatmapare 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
layoutgroup:Text,Heading,Stack,VisuallyHidden,PageContainer,DashboardGridwithDashboardGridItem, andFormLayoutwithFormSection. They lay out pages on Candor's tokens without hand-written classes, followdata-densityand right-to-left pages, and takerender(there is noas): if you are moving from your own layout components,<Text as="span">becomes<Text render={<span />}>. AHeadingneeds itslevel; 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, andnumericoverrides 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.nullreads "Unknown". Add your own vocabularies withVocabulariesProvider; change a built-in word through LocaleProvider undersemanticBadge.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 exportsChartStateViewandChartNestedProvider.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 asArtifactToolbarButton.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 awhole, 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, besideSparkline; "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, useStatusDot.table-scrubber-map: beside a server-modeDataTable, 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;allowedViewsanduseAllowedViews, 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. UsePromptSuggestionsfor prompts that only fill the composer.SettlingCardanduseCardSettlement: 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.RegistryCardis 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 whereThreadDividers 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,selectLabelandselected. 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. DateRangePickeravailable(Pro). Pass the span your data covers. A window picked wider is narrowed to it, the value keeps the window asked for asrequested, and the picker says "Data exists from … to …; showing that." AvalueordefaultValueyou pass that is wider, or a window left wider whenavailablenarrows, is shown narrowed with the same note; your value is unchanged andonValueChangeisn't called. With noavailable, nothing changes.report-sheetprovenance (Pro). A newprovenanceprop (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, soonExportnow gets the same lines as a second argument,{ provenance }, andexportProvenanceLines()returns them for files you write yourself. If you leave out the posture, the footer says "Not marked provisional or final." One-argumentonExporthandlers keep working.Fieldtrust (Pro). A newtrustprop shows when a value is unverified, was filled by an agent (named byby), or has a source that is unavailable (withreason): an icon and words under the label, read out with the control, and a dashed edge on the control.MessageandMessageHeader: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 ownaria-describedbyinstead 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
sourceshows 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 --foldfolds a project CLI 2.0.0 installed wholly under<app>/candor/candor/up into<app>/candor/: it moves the files, rewritescandor-lock.json, points imports of…/candor/candor/…at…/candor/…, keeps your edits forupdateto merge, stops before any change and names the place if a destination is taken, and with--dry-runlists the moves.doctorandupdatesay when a lockfile is nested that way. Only JS and TS sources are rewritten: references tocandor/candorin Markdown, MDX, stylesheets, Vue, Astro, Svelte and JSON files are listed under "Left for you" with their file and line, for you to point atcandor/.lintknows the new items.Text,Heading,Stack,VisuallyHiddenandPageContainerare 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
CardHeaderand 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_componentsleads withagent-screenfor "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 withtable-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 statscounts the suite withCANDOR_STATS=1, which skips the tests that depend on the machine (tests/machine.ts).release:checkno longer needs--keep-tests. A new machine-dependent test goes throughonThisMachine(), ortests/scripts/stats.test.tsfails. - The suite doesn't time out when other work loads the machine:
release:checkcaps Vitest's workers by the load average, and the suites that timed out under load get 30 seconds (tests/load.ts). - CI and
release:checkgenerate on Node 24, the version Vercel builds on;release:checkstops on another major and says how to switch (--any-noderuns 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
logoanddomain-iconsitems, and the preset's delivery, business and knowledge-base status vocabularies forVocabulariesProvider.
4.1.0 - 2026-11-12
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 Promotion-drawingsitem 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)andescapeBidiJson(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, callneutralizeBidi; 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, underdata-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 newPermissionJsonEditorProps. With Pro, passCodeEditorfor 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
onSaveresolves; if it rejects, the form says "Not saved" with the reason and keeps your changes (before, it stayed on "Saving…"). New stringsnotSavedandnotSavedNoReason. - 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'
notSavedis one sentence a translation punctuates: a select phrase onend(stopwhen the reason ends in its own punctuation,otherotherwise). - 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 checkchecks 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:rootfrom 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 labelledLight in [data-brand="acme"], count towards the totals and the exit code, and the JSON addsthemes[].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.jsonrecordstokensat a copy in the app'sstyles/that nothing imports (a CLI before 2.1.0 wrote it onadd),updaterecords and updates thecandor-tokens.cssbeside the shared package'scandor.cssinstead, 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 copycandor.cssimports stayed at the old version, so from 3.x colours such asbg-sunkenandtext-warning-textwere missing.doctornames such a copy. Runnpx candor-ui@2 updatefrom the app. - Monorepos:
updateupdates Candor's stylesheets whereinitinstalled them, in the shared package (it stopped before, sayingstyles/candor.csswasn't on disk), andaddfrom the app no longer writes a secondcandor-tokens.cssinto the app. In a monorepo app whoseuialias is in a shared package,addwithout a terminal no longer stops over a file that differs only in import paths, and the dry run lists it askept: 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
@/candorproject stays as it is when oneaddby an older CLI wrote files into acandor/folder inside it: the files recorded directly in the folder decide, andupdatemoves 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.addanddoctorsay when the lockfile records nested files, and to runupdate. add,add --dry-runandupdatesay once whentsx: falseorcssVariables: falseincomponents.jsonsends them to shadcn's own preview, and why.audittitles its motion group "Motion never says something false", as the Principles page does.
Docs and the docs MCP
- The docs MCP's
theme_checksays 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_componentsno longer namessoundfor "which tools the agent may use",permission-promptfor "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.txtand 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.
4.0.2 - 2026-11-11
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(orlib) alias that is already Candor's folder isn't nested again (Storywrite). Candor installs its files in acandor/folder under each alias; where the alias's folder is itself namedcandor(@/candor,~/candor), 2.0.0 put them in a second one (web/candor/candor/layer.tsx), andupdatecouldn't match the files CLI 1.0.1 had placed inweb/candor/to the release's.update,addand the lockfile now place them in the alias's own folder (web/candor/thread.tsx, primitives inweb/candor/ui/), with their imports pointed there;addgives shadcn local copies of the items placed that way.candor-lock.jsondecides which way a project goes: files it records in acandor/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 thatcandor/folder exists. - A move
candor-lock.jsonrecords decides where a release's file goes, foraddas forupdate. With the theme's stylesheets moved out ofsrc/styles/and recorded, 2.0.0'sadd(andinit, and theaddthatupdateruns for a release's new items) had shadcn write them again insrc/styles/, andupdateput a release's new stylesheet there, where the movedcandor.cssdoesn'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:addof 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.0takes 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 ofgithub-kindsafter the file had moved togithub-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 itemcandor-lock.jsonrecords names it, sostrings-keysruns only for a project with an item it changes, as in 2.0.0. The line isNot run: …, withnpx 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 theTabscomponent had no doc comment. It has one now;npx candor-ui update tabsbrings the comment.
4.0.1 - 2026-11-11
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.
4.0.0 - 2026-11-11
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-runprints what 4.0 changes for the items incandor-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.0installs@base-ui/reactwith your package manager whenpackage.jsondoesn't list it (--no-depsnames 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.tstogithub-preset.ts…) and points your imports at it, then updates every item, merging your changes into Candor's asupdatealways has. - Migrate:
npx candor-ui@2 migrate 4.0.0runs 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 incomponents/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, sinceupdatebrings them; in one you've changed, whichupdate's merge keeps, each old name orasChilda codemod finds is listed under "Left for you" withfile:line, for you to change.--dry-runshows 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 checkreports a token name 4.0 renamed that is still in your CSS as an error, namingmigrate 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 page lists):
as-child(codemodas-child): Candor's primitives takerender, notasChild:<Button render={<a href="/docs" />}>Read the docs</Button>. AnasChildon 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, addsnativeButton={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 anasChildit can't follow (no element child, or a value that isn'ttrue).primitives-base-ui(codemodprops, and by hand): every one of Candor's 51 primitives is built on Base UI. The codemod renames TooltipProvider'sdelayDuration,skipDelayDurationanddisableHoverableContenttodelay,timeoutanddisableHoverablePopup. By hand: a dialog's or popover'sonOpenAutoFocusandonCloseAutoFocusareinitialFocusandfinalFocus(an element, a ref, or a function that returns one); anonEscapeKeyDownoronInteractOutsidehandler moves into the root'sonOpenChange(open, details), callingdetails.cancel()where you prevented the default; and a style that selectsdata-stateon them (data-[state=open]) selects Base UI's attributes instead (data-open,data-closed,data-checked…). A project without@base-ui/reactdoesn't build;updateinstalls it.direction-moved(by hand): LocaleProvider hands the text direction to Base UI's DirectionProvider, and Candor's locale file no longer passes Radix'sDirectionthrough.TextDirectionanddirectionOfare unchanged; code of yours that used Radix'sDirectionimports it fromradix-ui.props-busy(codemodprops): Combobox's, DataTable's, PromptSuggestions' and ImportReview'sloading, PermissionMode's and MemoryMode'spending, ClarifyingQuestions'submitting, WorkflowEditor'ssaving, CommandPalette'ssearching, AssigneePicker'sassigning, ChangeSetReview'sapplying, ShipReview'sshipping, DataImport'sreading, DegradedPanel'sretryingand ChartFrame'srefreshingarebusy, with the same boolean. ChartFrame marks its plotaria-busywhile it is. DataTable'sstate={{ kind: "loading" }}, StopAll'sinFlight, ThreadHeader'sworkingand DocumentProgressQueue'sretrying(a list of ids) are unchanged.props-on-value-change(codemodprops, and by hand): theonChangeof Composer, DictationButton, PermissionMode, MemoryMode, InstructionsEditor, ModelSettings, ModelPicker, MessageBranches, ColumnMapper, RunScrubber, SoundSetting, CodeEditor and ReviewLadder isonValueChange, with the same value. AnonChangeon an element of your own, such as an<input>, stays. By hand:composer.onChangeread from the props useCandorChat, useAgUi or useClaudeAgent return iscomposer.onValueChange(<Composer {...composer} />keeps working), and useDictation'sonChangeoption isonValueChange. 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 isheadingLeveland 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'sdisabledislocked, the reason the person is shown:locked={streaming ? "Wait for the reply to finish." : undefined}, in your own words.migratelists each one under "Left for you".props-active-id(codemodprops): Tree'sselectedIdisactiveId, and Plan'sactiveStepIdandonSelectStepareactiveIdandonSelect, as in RunTree, SessionList and the other lists.props-title(codemodprops): PromptSuggestions'label, the heading above the suggestions, istitle. The words understrings.promptSuggestions.labelare unchanged.props-base-ui-names(codemodprops, and by hand): CandorConfig'stooltiptakesdelay,timeoutanddisableHoverablePopupwhere it tookdelayDuration,skipDelayDurationanddisableHoverableContent, and gainscloseDelay; the codemod renames them in atooltip: { … }object in a file that imports CandorProvider or CandorConfig. By hand: CommandPalette'sonCloseAutoFocusisfinalFocus, which returns where focus goes (finalFocus={() => el}, orfalseto leave it);migratelists each one under "Left for you".strings-change-diff(codemodstrings-keys): ChangeDiff's strings take its name: themetadataDiffnamespace ischangeDiff, and themetadataDiffStringstable ischangeDiffStrings. Words given understrings.metadataDiffaren't read until they move.preset-rename(no codemod:updatemakes 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(codemodtokens, and by hand): 23 of Candor's colour roles take--cd-(--sunkenis--cd-sunken,--warningis--cd-warning, and so on for--chrome,--faint-foreground,--border-strong,--primary-hover, the-weakand-textpairs,--on-success,--on-destructive,--surface-agent,--surface-userand--text-provisional).--series-1to--series-5are--chart-1to--chart-5, and--series-6is--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: insidevar(), in Tailwind's arbitrary values (bg-[var(--sunken)]), as a style object's key and insetProperty. Other strings that look like a token, such as a script's--chromeflag, stay. By hand: a file that sets both--series-Nand--chart-Nis 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, andmigrate tokens --dry-runlists every rename it would make.
Also:
- A Radix app keeps its own primitives. shadcn's components in
components/ui/and theradix-uipackage stay yours; Candor's Base UI primitives sit beside them incomponents/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>.jsonserves every item as 3.0.0 shipped it, with the same licence check, andnpx candor-ui add <item> --version 3.0.0installs 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, thennpx candor-ui@1 migrate 3.0.0(Upgrading to 3.0). 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,alignand the other placement props on the content part, Accordion's and ToggleGroup'stype="single" | "multiple"with string values, Checkbox'schecked="indeterminate", Select's string value with""for none (SelectValue shows the chosen item's text before the list has been opened), Slider'snumber[]withonValueCommit, Tabs'activationMode, menu items'onSelect(wherepreventDefault()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. AnonClickthat callspreventDefault()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 setsdata-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
layeritem (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-headerandpage-stateare free (MIT), each with a docs example.page-stateholds theListStatetype, so the free item doesn't import the Prodata, which declares the same type.- Registry categories take the source folders' names: an item's
categoriesin/r/<name>.jsonsayfoundationwhere they saidlib,partswhere they saidblocks, andblockswhere they saidblocks-full. The docs' group titles are the same.localeandlockedkeep their install paths. Lockedholds 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 newdescribesprop on Tooltip turns it off;Lockeddoes, since it describes the control itself. standardCardskeep their English export and gainstandardCardsStringsanduseStandardCards(), so the cards' labels and check messages can be translated.- DictationButton says "Transcribing…" while it transcribes, and is
aria-disabledrather thandisabled. - 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, andapprovalEmail(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 andcheckmessages follow the locale. The module constants (costCardsand 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 throughsetAddress()anduseAddress(), 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 --forandupdate --no-move; and the 2.x branches inadd,doctorand the@candor-ui/reactfindings. - Kept:
strings-keysandmotion-aliases, since a 3.0 project can still have what they change; andupdate's moves, for a release that renames an item. migrate 4.0.0, new, runsas-child,props,strings-keysandtokens, each on Candor's components only.as-child,propsandtokensare new;strings-keysgainsmetadataDiff→changeDiff.updateinstalls the npm packages the new versions declare thatpackage.jsondoesn't list, with the project's package manager, asadddoes: a 3.0 app gets@base-ui/react.--no-depsnames the command instead,--dry-runsays what it would run, and a failed install exits 1.updatemoves the renamed presets (github-kindstogithub-presetand the other four) and points your imports at them.init --yessets up a Base UI project (--base base, shadcn's nova preset), asshadcn initdoes by default.theme checkagainst a 4.x kit reports a 3.x token name, set or read withvar(), as an error that namesmigrate tokens, and token errors now fail the check.addanddoctorsay 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 incomponents/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.0ends 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 --toa 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 afterupdateinstalls 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. migratefixes:tokensrenames a token in source only insidevar(), Tailwind's arbitrary values, a style object's key andsetProperty(it had renamed any string that looked like one, such as a--chromeflag);as-childreads.jsand.mjsfiles as well as.jsxand.tsx; in a monorepo, the codemods read the shared ui package's source, andtokensreads the stylesheetcomponents.jsonnames, wherever it is; andas-childaddsnativeButton={false}on every Candor part whose Base UI part takes it, not only Button.addandmigraterefuse a 2.x project and name CLI 1, asupdatedoes:addwithout--version, andmigratewith 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 listupdateprints./upgrading-to-3stays 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-propgoes to the upgrade page. - The README, the install notes for coding agents and Get started say that
init --yessets 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 --radixbuilds a shadcn Radix app and runs the layer checks (tests/browser/layers.mjs) in it.node scripts/upgrade-check.mjs --from 3.0.0upgrades a 3.0 fixture project withupdateandmigrateand builds it, in the normal flow, on Base UI and in a Radix app;release:checkruns it with--fresh.tests/templates/strings.test.tsxfails on typed English in any block or template, with an empty allowlist.- A test fails when a
scripts/breaking.json4.0 entry isn't named in this section and on the upgrade page.
3.0.0 - 2026-11-10
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-runprints what 3.0 changes for the items incandor-lock.json, with the moves and merges the update would make, and writes nothing. - Update:
npx candor-ui@1 update --to 3.0.0moves Candor's files tocomponents/candor/andlib/candor/, copies Candor's ui primitives tocomponents/candor/ui/, points the imports in your project at the new places, records the moves incandor-lock.json, and then updates every item, merging your changes into Candor's asupdatealways 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 fromcandor-lock.json.--no-movekeeps CLI 0.15's behaviour, which stops and names the moves instead of making them. - Migrate:
npx candor-ui@1 migrate 3.0.0runs 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-runshows it first. - Finish and check: make the changes marked "by hand" below, then type-check (
npx tsc --noEmit) and build. On a project whosecandor-lock.jsonrecords 3.x,npx candor-ui lintreports a name 3.0 removed that is still in your code as an error, naming its codemod.
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 3.0.0 prints, and the Upgrading to 3.0 page lists):
paths(codemod:update --to 3.0.0makes the moves;migrate paths --for 3.0.0makes 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:updatemoves the file, thenmigrate metadata-diffrenames the import and the tag):MetadataDiffis removed and the item is renamedchange-diff, so it installs ascomponents/candor/change-diff.tsx. ImportChangeDiff; the props are the same. Before the update,migrate metadata-diffrefuses without--for 3.0.0, since 2.x'saddstill installsmetadata-diff.tsx.orgdata(codemodorgdata): theorgDatainline 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. Usekind: "measured"; the fields are the same.card(codemodcard): card-registry'sCard, its first name forRegistryCard, is removed. ImportRegistryCard; the props are the same. shadcn's ownCardis not affected.terms(codemodterms):TermsProvider,useTerms,capitalise, theTermstype and thetermsitem are removed. The app's nouns are set onLocaleProviderasnouns, or asCandorProvider'sconfig.nouns, and fill{environment},{Environment},{account}and{product}in every message.useNouns()andstartOf()replaceuseTerms()andcapitalise(),NounTableandNounsreplaceTerms, and the presets aregithubNouns,hubspotNouns,jiraNounsandlinearNouns. The codemod rewrites each of these and lists what it can't follow (a re-export under the old name,termsthrough an untyped spread); then delete the installedtermsfile, 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(codemodstrings-keys): Message's working line reads onlymessage.working. An override ofmessage.thinkingalone shows Candor's own "Working" again. The codemod renames the key, unlessworkingis already there.answering-approvals-strings(codemodstrings-keys):useAnsweringApprovals' words are read only underansweringApprovalsin LocaleProvider'sstrings. An override underuseAnsweringApprovalsshows Candor's own sentence again when an answer fails to send. The codemod moves it, in an object given asstringsor typedStringOverridesorCandorConfig.block-refusal-export(codemodrefusal): theRefusalre-export from the stores of plan-build-review, run-console, agent-ops-console and project-workspace is removed. ImportRefusalfrom the server foundation,@/lib/candor/candor-serverin a default install; it is the same class.motion-aliases(codemodmotion-aliases): the 2.2 motion tokens--cd-pop-fromand--cd-motion-shakeare no longer read, anddata-motion="expressive"no longer sets their presets.--cd-pop-frombecomes--cd-motion-pop-scale, which applies from the expressive level only.--cd-motion-shakehas no single replacement, so the codemod lists it under "Left for you": set the refuse family's--cd-motion-refuse-distance,-durand-ease, or its level,--cd-motion-refuse.legacy-animations(codemodmotion-aliases): the 2.2animate-*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 asanimate-pop-instops animating, andanimation: 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 listsanimate-attention-wait,animate-shimmerand thepop-out,collapse-*andshakekeyframes with what to do for each. Theshimmerkeyframes stay, forshimmer-text.attention-kinds(by hand):AttentionKindgainsreplyandsilent. ARecord<AttentionKind, number>built by hand needsreply: 0, silent: 0, and an exhaustiveswitchneeds both cases or adefault. Code that only readscounts.approvaland 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 passwhen: "always", 2.x's behaviour. Nothing fails to compile, so check everyuseAttentionwith asound.block-viewer-of(by hand): the blocks' and templates'viewerOf(request)is removed. UsegetViewer(request)orviewerName(request)from@/lib/candor/candor-server; both are async and answer null when nobody is signed in, whereviewerOfgave the demo person.block-context-of(by hand):contextOf(request)in audit-data-controls' and approvals-inbox's stores is removed. UsesignedInContext(request)from the same store: it is async and answers null when nobody is signed in.inbox-post(by hand): approvals-inbox'spost(body)is removed. UseusePost()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.tsfiles are removed; each store opens the shared pool throughdatabase()from@/lib/candor/candor-database. If you swapped the driver or the URL indb/connect.ts, give your database tosetDatabase()once at startup instead.updateleaves your olddb/connect.tsin place, with its imports pointed at the new places; delete it once nothing imports it.
Also:
- Stored
orgDatamessages are data, not source. No codemod reaches a database or a saved conversation: change theirkindfromorgDatatomeasuredonce, where they are stored. - 2.x stays installable.
https://candor.themethodic.com/r/v/2.10.0/<name>.jsonserves every item as 2.10.0 shipped it, with the same licence check, andnpx candor-ui add <item> --version 2.10.0installs 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. addat 3.0 on a 2.x project stops (CLI 1.0) and namesupdate --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/orgsmithis gone from the product build, and OrgSmith uses thev2.10.0tag's copy until its own repository exists. No@candoritem 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 atcomponents/candor/ui/<name>.tsx, and a shared helper or type atlib/candor/<name>.ts(types are in@/lib/candor/chat). The server foundation islib/candor/candor-server.tsandcomponents/candor/candor-sign-in.tsx. Blocks, templates, the theme's stylesheets and the sounds keep the places they had. The aliases come from yourcomponents.json, so a project with its owncomponentsorlibalias 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 acomponents/message.tsxof your own no longer captures an import meant for Candor's. - The kit's source moved into new folders (
lib/tofoundation/, the small parts inblocks/toparts/,lockedintoui/). 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.
LocaleProvidertakesnouns(CandorConfig.nounsin CandorProvider), and every message that names one ({environment},{account},{product}) is filled with the app's word, in the form the message'scountpicks;{Environment}starts a sentence with theenvironmentvalue 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" }); whenenvironmenthas them andenvironmentsisn't set,environmentsdefaults to itsotherform, and anenvironmentsyou set still wins. A noun can also have agenderthat a select message chooses its case by ({ select: "environment", cases: { feminine: "…", other: "…" } }), and astartform 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, andstartOf(text, locale?)upper-cases the first letter as the locale writes it. Both come fromlocale;fill-strings(free, and safe on the server) has the types,nounDefaults,fill,pickandenglishStrings(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.environmentLabelandauditLog.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.
updatemakes 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 incandor-lock.json, and then updates.--dry-runlists the moves with the merges;--no-movestops and names them, as 0.15 did.migrate <version>, new, runs that release's codemods for the items your project has, in order.migrate termsrewrites to LocaleProvider'snouns, where 0.15's listed the uses;strings-keysandrefusalare new codemods;migrate pathstakes its destinations from the release's own install targets.- On a 3.x project,
lintandauditmake a removed name an error naming its codemod (what a codemod lists rather than rewrites,--cd-motion-shake, stays a warning), and drop thev3-pathsandv3-attention-*notes.theme checkagainst a 3.0 kit makes--cd-pop-fromand--cd-motion-shakeerrors. addat 3.0 on a 2.x project stops and namesupdate --to 3.0.0.- A plain
updatestays within the major you're on: without--to, it moves your items to the newest release in the majorcandor-lock.jsonrecords, the wayaddstays at the locked version, and when a newer major is out it prints one line naming it and thenpx candor-ui@1 update --to <version> --dry-runthat shows its breaking changes. To cross, pass--to 3.0.0. addanddoctoron Base UI and React Aria say that from 3.0 Candor's primitives install incomponents/candor/ui/, beside your own incomponents/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.doctorbeside@candor-ui/reactgives each import's move at 3.0's paths (@/components/candor/thread), namesLocaleProvider'snounsfrom@/components/candor/localein place ofTermsProvider, and counts a copiedcomponents/candor/locale.tsx.lintandauditlink 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 listupdateprints. - The Locale page shows the app's nouns, with plural forms and a gendered select; the Terms page is gone, and
/docs/termsredirects to Locale. CandorProvider's example setsconfig.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,capitaliseandTerms(useLocaleProvider'snouns,useNounsandstartOf), theorgDatanode, card-registry'sCardandmessage.thinking. In a project that uses the package,npx candor-ui@1 migrate 3.0.0runs every 3.0 codemod (there is nocandor-lock.jsonto choose from), andtermsandcardrewrite imports from@candor-ui/reactas they do from Candor's installed files.
For contributors
- The source folders are
src/registry/foundation/(waslib/) andsrc/registry/parts/(wasblocks/), withlockedinui/;internal/release-3.0/arch4-moves.mjsis the record of the moves. - OrgSmith's pack is
packages/orgsmith, a private package that installs@candoras a buyer does; the build makes one registry. node scripts/upgrade-check.mjs --from 2.10.0upgrades a 2.10 fixture project withupdateandmigrateand builds it, in the normal flow, the 0.15 flow and on Base UI;release:checkruns it.- A test fails when a
scripts/breaking.json3.0 entry isn't named in this section.
2.10.0 - 2026-11-10
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 yourcandor-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 itemfill-strings(lib/fill-strings.ts).npx candor-ui update(CLI 0.15) installs it with them and records it incandor-lock.json. With--no-depsit only names it: runnpx 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),updatestops 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:
useAttentiongiven asoundthat is on (enabled: true) withoutwhen, a message with anorgDatainline node, andMetadataDiff. Nothing is logged in production. Passwhen: "always"to keep 2.x's behaviour (or"away", 3.0's default), changekind: "orgData"tokind: "measured"(npx candor-ui migrate orgdata), and useChangeDifffrom the same file in place ofMetadataDiff, by hand on 2.x (as you move to 3.0,npx candor-ui migrate metadata-diff --for 3.0.0does it and moves the file).MetadataDiffis now a small component aroundChangeDiff, soMetadataDiff === ChangeDiffis 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 onlyansweringApprovalsforuseAnsweringApprovals' words. Move an override ofmessage.thinking, or one underuseAnsweringApprovals, to the new key now; 2.9 and later already read it first.candor-ui lintpoints at both. - Premium blocks and templates, the 2.7 shims: 3.0 removes
viewerOf,contextOf, the approvals inbox'spost, the stores'Refusalre-exports anddb/connect.ts.candor-ui lintnames each use in your own code and what to use instead. DataTable's column picker: the last visible column's box isLockedwith its reason ("At least one column stays shown.") instead ofdisabled, so it carriesaria-disabled. A test that expects ittoBeDisabled()should checkaria-disabledinstead. If you translate DataTable, add the newlastColumnstring.EnvironmentConnect,McpConnectandConsentCeremonywhile busy: Test connection, Connect and the grant button areLockedwith a reason instead ofdisabledwhile a test runs or the connection or consent is being saved, so they carryaria-disabledand stay in the tab order. A test that expects themtoBeDisabled()while busy should checkaria-disabledinstead. If you translate them, add the new stringswaitTestandwaitSave(environmentConnect),waitConnect(mcpConnect) andwaitRecord(consentCeremony).AgentScreen: both views now keep the frame in a newagent-screen-bodyelement (display: contentswhen 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,ToolPermissionsandRestoreDialog: in a shadcn project on Base UI, every controlLockedwith a reason drew a button inside a button, an extra tab stop and a hydration error. Released versions have this, 2.8.0 included, andLockedis free. shadcn's rewrite ofasChildtorenderdropsasChildwhen 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. Runnpx candor-ui update locked app-sidebar tool-permissions restore-dialog. Radix projects and@candor-ui/reactare not affected. - Theme builder, a component's density: files from earlier versions wrote a component's density under
:root:not([data-density]), sodata-densityon 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. Lockedwithout a reason: itsclassNamenow goes on the control; before, it was dropped. If you passclassNameto aLockedwhosereasoncan 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 newlabelCountstring. If you translate AppSidebar, addlabelCount, andcollapseandexpandif 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 throughuseAddress(), and call the newsetAddress()besidesetNavigate()with the router's path and query (in Next.js, fromusePathname()anduseSearchParams()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
stringsunder 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 withcontent-type: text/markdown; anything else is shown as a failure and nothing is saved. - The Vite and TanStack Start starters: their
collapsible.tsxusedanimate-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 --strictin 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 (breakingin--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 inschedule-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 bygraph-layout.integration-connectconnects 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-promotionpromotes 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 orhashchanges, or the target goes stale, it is cleared and the card says why. Approvals are counted by person: eachbyonce, 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 inbyandrequestedBy. Pass your server's change hash ashash; it comes back toonPromote.escalationhands 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 newmessagefrom 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 assent.assignee-pickerchooses 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-queueshows 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; passaddingwhile documents are still arriving. Screen readers hear failures and the batch finishing, not every document's step.use-keyboard-review:useKeyboardReviewgives 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 underkeyboardReview, so a translation can match its words, and each row lists them inaria-keyshortcuts. A decision made on a row that has since changed is cleared. SpreadrowProps(i)on each row and putlistRefon the list; row versions are worked out once peritemsandversionOf, so pass aversionOfthat keeps its identity.search-traceshows 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 theToolCallwithqueriesbeside it.proposalshows one action an agent proposes with the alternatives it weighed beside it, each with its confidence throughConfidenceMark("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 withonEdit, "None of these" withonDecline. Withlocked, "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,pickandenglishStrings(table)in a module without"use client", so server code can fill a component's strings.localeimports it and still exportsfillandpick.Locked: without a reason,classNamegoes 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 optionalrailprop 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 whatonCollapsedChangegives you and passing it back asdefaultCollapsed. In a sheet it always shows its labels. Withoutrail, 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 onuseKeyboardReview; its keys, focus and decisions behave as before.DataTable(Pro): the column picker's last visible column isLockedwith the reason (new stringlastColumn) instead of disabled.EnvironmentConnect,McpConnectandConsentCeremony(Pro): while a test runs, or the connection or consent is being saved, Test connection, Connect and the grant button areLocked, 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 (newagent-screen-bodyslot).StopAllandRunScrubber(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 asoundthat is on (enabled: true) withoutwhen, as the CLI's lint rule does (3.0 plays sounds only while the person is away unless you passwhen: "always"), a message with anorgDatanode (usemeasured), andMetadataDiff(Pro; useChangeDiff). The deprecation notes onorgDataandMetadataDiffsaid 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,DiagramandDictation(Pro) are now optimised by the React Compiler.
Blocks and templates (Premium)
fill-strings: every block and template now importsfill-strings.npx candor-ui updateinstalls 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,knowledgeBaseandplanBuildReview;runConsole,agentOpsConsole,approvalsInbox,projectWorkspaceandsupportCopilotgain keys. Some English is still typed.approvalsInboxStringslives in the approvals inbox'sagents.tsand is still exported fromshell.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 newsetAddress()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 --toprints the breaking changes between each installed item's version and the version you update to: what breaks, where it shows, the migration, and themigratecodemod 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.0shows what 3.0 asks of your project and changes nothing; run it before 3.0 is released.migrate <codemod>, new, withorgdata,metadata-diff,motion-aliases,card,termsandpaths. Each prints what it changed and lists what it couldn't, with--dry-runto look first. It reads your source with your project's own TypeScript 5. Your installed Candor files are left toupdate; withoutcandor-lock.json, files named like Candor's in the folders Candor installs to (such aslib/chat.ts) are left alone and named, and if the registry's public lists can't be read, nothing is changed.termslists the uses and changes nothing, since 3.0's form isn't designed yet.cardandmetadata-diffleave shadcn'sCard, or another module's export of the same name, alone.migrate pathsandmigrate metadata-diffmove files (intocomponents/candor/andlib/candor/, andmetadata-diff.tsxtochange-diff.tsx), rewrite the imports that name them, and record the moves incandor-lock.json, soupdatefollows 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.0andnpx candor-ui migrate paths --for 3.0.0, followed bynpx candor-ui update --to 3.0.0, once 3.0 is released. Until thenaddandupdateinstall to the old places and names; on 2.x, importChangeDiffby hand.pathscopies 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.lintandauditwarn about what 3.0 removes in your own source and CSS, and name the codemod for each, including themessage.thinkingstrings key, strings underuseAnsweringApprovals, and the blocks' and templates'viewerOf,Refusalfrom a store,db/connect.ts,contextOfand the approvals inbox'spost, each saying what to use instead. These warnings don't faillint --strict; they are counted separately (breakingin--json). What 2.x can't take yet (Terms, the new install paths,AttentionKind's new kinds) prints as notes, which never fail.updateinstalls the Candor items a new version needs, asaddwould, and records them;--no-depsonly names them, as before, andupdateexits 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 --movedaccepts a renamed item's new file name (metadata-diff.tsx→change-diff.tsx), and a move recorded incandor-lock.jsonis looked at before the path the file was installed at.- Aliases through package.json
imports(#components), and a monorepo app whoseuialias points into a shared package (shadcn's monorepo template):add,updateandadd --dry-runwork out what shadcn writes themselves, instead of running a shadcn preview per item. In such a monorepo, a--pathnaming 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.jsonthe installed items don't type-check, which is shadcn's output for Candor's import form. The workaround: beforeinit, set the app'suialias to@/components/ui, and give the app's tsconfig"lib": ["es2023", "DOM", "DOM.Iterable"].
Docs and the docs MCP
suggest_componentsleaves 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 listsuse-answering-approvalsbeside the approval components at the Pro tier, or besidecitationfor "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_componentsno 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_docsfinds items by the words people use for them ("modal", "login", "404", "onboarding", "signup"), from the same@keywordstags. 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 asvalidatein 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.csshold 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>"]: putdata-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 whendata-brandis on<html>or<body>; the file, DESIGN.md, the agent brief and the builder say so.data-densityon 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, withdata-brandon<html>as on any other element. Every@importis 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] *), sodata-densityon 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-slotnames and AgentScreen'sagent-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 thecandor-ui migratecodemod 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.0reads them for the items your project has. - Search tags out of installed files: the files Candor installs no longer contain the
@keywordsand@jobdoc 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,localeimporting it,Locked'sclassName, theorgDatadevelopment warning inmessage-content, PermissionPrompt's description) are in this version. - The package no longer ships the
@keywordsand@jobdoc tags.
For contributors
npm run release:checkruns the shadcn differential after the CLI build (25 to 40 s) and fails if the repo's shadcn is outside the CLI's pin;--quickskips it.RELEASING.mdlists it and what--quickskips.scripts/breaking.jsonis 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-factsfails on a typed item count in the npm READMEs.npm run agentswrites nothing until every check passes.- A kit test fails if a registry, block or template file gives
asChildanything but a single JSX element, since shadcn's Base UI rewrite drops it otherwise.
2.9.0 - 2026-11-10
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 newhandlers.tsbesideroute.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 thoseroute.tsfiles,update's merge will conflict: move your changes intohandlers.tsand keep the newroute.ts. - Premium templates, your own server code: code of yours that reads a template's store must call
openPostgresWhenSet()from the template'sdb/postgres.tsat the top of the module. With DATABASE_URL set (orsetDatabase()), 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: runnpx candor-ui add use-answering-approvals. Ten blocks and three templates import it, andupdatenames it but doesn't install it. - Premium templates, layout: template shells fill their container, not the window; each template's new
layout.tsxsetsh-dvh. If you render a shell in your own page or layout, give its parent a height. If you already haveapp/<template>/layout.tsx,updatekeeps yours and writes the new one beside it aslayout.tsx.candor-2.9.0: add theh-dvhwrapper to yours. - Premium templates,
setNavigate(): new and optional. If you give it your router, also read the address from the router where the template readswindow.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/chatnow refuses a POST another site's page sent, as/api/agentdoes. If you started from the starter, addif (crossSite(request)) return crossSiteRefused()as the first line of your/api/chatPOST, importing it fromapp/_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 inCANDOR_TRUSTED_ORIGINS. Message's working line says "Working" before anything of a reply arrives, under the new keymessage.working. If you overrodemessage.thinkingfor that line, move your text tomessage.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 translatecodeEditor.hint, update your text.RunTreewithgraphView: the root element is always a wrapper, withdata-slot="run-tree"and yourclassName, around the switch and the tree, even before the work branches. If your CSS or tests expect the tree itself as the root whengraphViewis set, point them inside the wrapper. WithoutgraphViewthe root is the tree, as before.DataTablenow depends onlocked: its Previous and Next page buttons areLockedwith a reason instead ofdisabled. When you update it,updatenameslockedif your project doesn't have it; run theaddcommand it gives. If you translate DataTable, add the newfirstPageandlastPagestrings.- CLI,
addwithout a terminal (a coding agent, CI, a pipe): if a file of yours differs from the one the add would write and--overwriteisn't given,addinstalls nothing, names the files and exits 1, andadd --dry-runsays the add would stop and exits 1. Autils.tsfrom before shadcn 4.23 is such a file, and a file that differs only by trailing spaces now counts as different. Add--overwrite, or runaddat a terminal. candor-tokens.cssbesidecandor.css:candor.cssnow importscandor-tokens.cssinstead of carrying its own copy. Keepstyles/candor-tokens.cssbesidecandor.css(npx candor-ui add tokensif it's missing;doctorsays so). If your CSS imports both files, remove thecandor-tokens.cssimport.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, passpanelCloses.
Components
New (Pro):
document-viewershows 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, andonRegionSelectreports it. It has zoom and page turning, and a page still drawing or one that couldn't be drawn says so (with Try again throughonRetry). Draw only the page on screen by rendering it whenonPageChangenames it. (KIT-15)extraction-reviewputs 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, andonSubmitgets exactly the fields the person accepted or changed. PassrequireAllto 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-reviewlets 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 stringskeepKeyanddropKey) and counts what's kept. It shows what can and can't be undone from your app'sundo. Apply callsonApply(kept, hash)with exactly the kept edits and theirchangeHash, so your server applies only what was approved. The hash is namedsha256:only when it comes from the defaultchangeHash.reconcile-tableshows 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 throughresolution. A summary says what's left. (KIT-16)code-listingshows 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 withpreviousit switches between the code and its changes line by line. (KIT-24)code-editoris 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, passstatusand 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, andnullsays who's here isn't known. PassupdatedAtand presence older thanstaleAfteris stamped "As of 10:42". Put it inThreadHeader'sactionsorCommentThread'spresence.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. WithframeAt, a frame older thanstaleAfteris stamped "No new frame since 10:42". Recording says what it records before it starts and stays marked while it runs.graph-layoutandgraph-view, the layered layout and drawing behind the graph views below, for your own graphs. (KIT-22)model-picker, a model menu for Composer'stoolsslot from ModelSettings'ModelOptionlist, 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 aslockedcomes and goes.composer-sources:useComposerSources(sources, { onSignIn })puts MCP connections in the @ menu under "Connected sources": connected, needs sign-in (choosing it callsonSignIn), 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 andfailedgives 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 ismessage.working; an override ofmessage.thinkingstill works until 3.0. Reasoning still says "Thinking".composer: an @ option can carry astatus, beunavailablewith a reason (shown, can't be chosen), or callonChoosein place of inserting. Existing mentions are unchanged.format-elapsed(new, free):formatElapsednow lives in a free lib with no"use client", so server code can call it; importing it fromstreaming-textstill works.useFormatis now optimised by the React Compiler.Toaster: the toasts that stay slide on the move family'scd-move, so brand motion tokens apply.mcp-inputandsound: their first doc comment is no longer dropped on install.
Work and review (Pro):
PlanandRunTree: withgraphView, 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 setgraphViewsee no new control. WithgraphView, RunTree's root is the wrapper from the first render, so collapsed groups and focus are kept when a second agent starts.RunNodegains an optionaldependsOn. Plan numbers its steps in the locale's digits. (KIT-22)Diagram: passnodesandedgesinstead of Mermaidsourceand Candor draws the diagram without loading Mermaid, laid out from the edges. A node withcolumnandrowstays where you put it.sourceis now optional. (KIT-22)instructions-editoris built oncode-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-panelpreviews tables: passtablewith CSV or TSV text, or columns and rows. It shows the first 100 rows (setpreviewRows), says how many more there are (totalRowsif you send only the start), and keeps the raw text, showing the same first rows, one toggle away. TheArtifacttype's description is back. (KIT-24)selection-actions: withonRewrite, the toolbar offers yourrewrites(improve, shorten, tone) and, withdescribeEdit, 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 (onKeepgets 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,RunLogandFailureClusterstakeheadingLevel(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 anentitytypes its label like any other.
Data and lists (Pro):
data-tablecolumn resizing withresizable: 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 itsminWidthor the table'sminColumnWidth(64 px). PasscolumnWidthsand save whatonColumnWidthsChangereports to keep the widths between visits. The resize handle hasaria-valuemax.data-tablefooter aggregates. A column'saggregate(count,sum,average,min,max) adds a footer row formatted through LocaleProvider (aggregateFormattakes 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 sendsaggregateTotals. A page's sum is never shown as the total. Blanks are counted and said.data-tablepinned columns:pin: "start" | "end"keeps a column in view while the table scrolls sideways, in right-to-left too.data-tablecolumns an agent fills, withagent: { 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 withonRetry). Cells still on their way are left out of the footer.- Pagers: ChangeSetReview's, ReconcileTable's and DataTable's Previous and Next page are
Lockedwith a reason instead ofdisabled(new stringsfirstPage,lastPage). DataTable now depends onlocked. - Charts and
SpendBreakdown: passonRetryand an error state shows Try again, as lists do. RunLogandSpendBreakdown: 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, passpanelCloses.NumberInput: range checks are your app's; check the number you get fromonValueChange. 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 newdb/postgres.ts, which every route file calls, and each data route's code is in ahandlers.tsbeside itsroute.ts. Installed with DATABASE_URL set, a template uses Postgres as before. If you added a route that reads a template's store, callopenPostgresWhenSet()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'sgo(), so the router covers signing in too; the server foundation'sDemoSignIntakesonSignedIn(next)for this. The project workspace's downloads are links. - Shells fill their container instead of the window. A new
layout.tsxin 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; adduse-answering-approvalswhen 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 gainsteamunderagentOpsConsole). - 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_ORIGINSto allow particular sites. The Next.js starter's/api/chatrefuses them too: if you started from the starter, addif (crossSite(request)) return crossSiteRefused()as the first line of your/api/chatPOST, importing it fromapp/_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,updateandadd --dry-runwork out shadcn'sasChild→renderrewrite themselves, using your project's owntypescript, 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 Tailwindprefixorrtl: trueare 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 theasChilditems into a Base UI project and of every item into right-to-left and Tailwind-prefixed projects: the files are byte-identical. addwithout 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.addnow checks first: if a file differs and--overwriteisn't given, it installs nothing, names the files and exits 1, andadd --dry-runsays the add would stop and exits 1. Autils.tsfrom before shadcn 4.23 is such a file. Add--overwrite, or runaddat 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 differsaddruns 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 --diffandadd --viewat 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--diffor--viewis 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,updatenames it with theaddcommand, even if the old version needed it too (a theme whosecandor-tokens.csswas never installed).doctor: acandor.cssthat importscandor-tokens.csswithout that file beside it is a fix (npx candor-ui add tokens), and if you movedcandor.css, the fix says to move the file beside it. Your CSS importingcandor-tokens.cssas well ascandor.cssis a note.lintknows the new components.
Docs and the docs MCP
suggest_componentsreads the words people use for an item and the tasks it answers from the item's own doc comment (@keywords,@job), compiled bynpm run docsinto 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-viewerandextraction-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 suggestaccount-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 fromcode-editorand namescode-listing; the offline pattern uses PageState'sofflinekind.
Tokens and theming
candor.cssimportscandor-tokens.css, the file every item installs, instead of carrying its own copy; the resolved CSS is unchanged. Keepstyles/candor-tokens.cssbesidecandor.css. If your CSS imports both files, remove thecandor-tokens.cssimport.- The token manifest lists the new items'
data-slotnames.
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-inputandsound) are in this version.formatElapsedcomes fromformat-elapsed, and importing it fromstreaming-textstill works. - Both stylesheets are built with
candor.css's imports inlined; the CSS is the same.
For contributors
- Search tags:
@keywordsand@jobin an item's doc comment feed the docs MCP; if you add or rename an item, tag it there. The tags are documented inscripts/build-docs.mjs's header. - One contrast implementation,
packages/cli/src/contrast.ts(ARCH-12). packages/cli/scripts/shadcn-differential.mjscompares 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.
2.8.0 - 2026-11-09
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 itsmin,maxorstepattributes from the DOM, readonValueChangeinstead. - ScheduleEditor: if you overrode the
ruleWeekdaystring, 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-runexits 1 where the add itself would stop. A script that relied on the dry run always exiting 0 should check its message.doctorexits 1 when@candor-ui/reactis installed beside Pro or Premium items, or with a licence key set. - Premium blocks and templates: run
npx candor-ui updatefor 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 inCANDOR_TRUSTED_ORIGINS; if your app is served from more than one origin, list the others there. Errors that aren't aRefusalshow a fixed sentence with a 500. If you calldemoSessionRoutes()'s DELETE yourself, pass it the request. - Routes that changed something on GET now need a POST. human-handoff's inbox with
?visit=1only 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. Runnpx candor-ui add <block> --overwriteto install it again with your aliases. - Diagram: if you added it before, run
npm install mermaid. - components.json without a
"lib"alias: add one underaliases, pointing at the folder of yourutilsalias ("lib": "@/lib").candor-ui initadds it whentsconfig.json's paths confirm the folder, anddoctorsays when it's missing. - A nested
TooltipProvidernow takes the outer one's timing for any setting it leaves out. If you nest one to reset the delay, passdelayDuration={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 ownAuditDataRepoassigns 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
Refusalaround 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 thekinds,rolesandcardsprops. Install it withnpx 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.ChartSizeProviderisn'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 byReasoningas "Reasoning · 4s", measured from the agent's ownREASONING_STARTandREASONING_ENDtimestamps and formatted in your LocaleProvider's locale. An agent that sends no timestamps shows no time.fromAgUiEventstakesformatDurationif you format it yourself; without it, the time reads asformatElapseddoes ("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.
ShimmerLabelandReasoningtakestartedAt(when the request went out), and the working line then counts the time since, live: "Thinking · 4.2s". AMessagecan carrystartedAttoo; until the reply's first words arrive it shows "Thinking", counting up fromstartedAtwhen it's given. WithoutstartedAtnothing 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-textis now a client component and exportsformatElapsed. PermissionPrompttakesheadingLevel(2 to 6, default 3).CopyFieldshows 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, settruncate: the value still reads in full to screen readers and on focus.MessageandSourceList(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 alocaleset 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").RelativeTimeand the working line's timer: a time mounted between ticks, or after the clock went back, shows the current time.TooltipProvidertakes 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, passdelayDuration={0}.CardRegistryProvider'scardsis optional; left out, the cards of a provider above still apply.
Forms (Pro):
Combobox: a choice no longer reads as the placeholder when the currentoptionsdon't include it. It keeps the label it had when chosen, or is counted ("1 chosen").NumberInputis 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 negativemin, 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'svalueAsNumberor usedmin,maxorstepattributes from the DOM, readonValueChangeinstead. A form reset clears typed text that isn't a number, and an uncontrolled field goes back todefaultValue.Field: agroupwith a function child now renders it. A group's radios and checkboxes arearia-invalidwhile 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 (attemptgoes 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. Passattemptto 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. Newweekdayssets the days "Every weekday" means, and the rule names them. If you overroderuleWeekday, add{days}to your text.nextRunstakes the same days as an optional fifth argument. Withoutnow, 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. Withweekdays={[]}, an "Every weekday" rule reads "No working days are set, so it never runs" (new stringscheduleEditor.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 stringapiKeys.expiry).Webhooks: each webhook takes an optionallabel. 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: withrequireTestand noonTest, 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:
formatMoneyignores spaces around the currency code, so"eur "shows as €12.50.
Lists, logs and tables (Pro):
onRetryon SessionList, ApprovalQueue, NotificationCenter, RunLog, AuditLog, Inbox, MembersTable, KnowledgeSources, AgentRoster, ReviewQueue, TraceViewer, ResultTable, VersionHistory, EvalScorecard, FailureClusters, InvoiceHistory, DataTable, ApiKeys, DeviceSessions, ScheduleList and Webhooks. Under an errorstatethey show Try again, but only when you pass it, so pass it only when it loads the list again.- Under a
partialstate, 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. Underpartialit reads "2+", named "Notifications, at least 2 unread".LogStream: withvirtualizeandlive, 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:loadingtogether with an error or emptystateshows 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 underreportReply.needsReason. While a report sends, Report isaria-disabledandaria-busyinstead ofdisabled, 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):renderEmailno 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 declaresmermaidas a dependency. Diagram loads it on first use, and the install used to leave it out. If you added Diagram before, runnpm 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()andguardTools()for your own routes; wrap a Claude Agent SDK tool server ascreateSdkMcpServer(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 inCANDOR_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_ORIGINSentries 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); existingEXP-001ids keep working. With Postgres, run the new migration0001_exports_random_id.sql. If your ownAuditDataRepoassigns 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
Refusalaround 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=1only reads what changed since your last visit; the page marks it seen with POST{ action: "seen", at }, and the store hassinceLastVisit()andmarkSeen()(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, runnpx 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.tsand of five block files now sits below the first line of code and is kept. Runnpx candor-ui updateto 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 readingprocess.envon each request. Left out, nothing changes.
CLI 0.13.0
add,updateandadd --dry-runno 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 --pathis recorded where the files went. Projects withtsx: false, a Tailwind prefix,cssVariables: false,rtl, aliases through package.json imports or a workspace package, or anasChilditem on a Base UI style still use shadcn's preview, as before.add --dry-runlists 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 checkchecks token names anddata-slotselectors. 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.--jsonaddstokens.doctorand@candor-ui/react. With the package installed beside Pro or Premium items, or with a licence key set,doctorreports 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--pathnaming 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--patha folder.- The
libalias.initadds alibalias 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--helpsay so.doctornames a missing one. The dry run names shadcn'slib/utils.tsas 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 lintcounts an import ofCandorProvideras Candor in use.- An interrupted
addorinitalso stops processes shadcn starts after the signal (macOS and Linux). With an unreadable candor-lock.json,mcpandinit --mcpsay why the MCP URL has no?kit=version, anddoctorsays the entries' version can't be checked. On Windows, every argument passed to shadcn is quoted where cmd.exe needs it.theme watchsees 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_startedreturns 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 andllms.txtat 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.jsonsays which releases kept what. versionon the MCP's page tools.get_component_docs,get_brief,get_pattern,get_screen,get_started,get_designandget_review_checklisttakeversion, and default to the version in the server's URL (?kit=, whichnpx candor-ui mcpwrites from candor-lock.json). Runnpx candor-ui mcpagain afterupdateso the URL follows the lockfile. A release without the page answers with the current page and a note saying so.theme_checkalso checks token names anddata-slotselectors against the kit's token manifest, ascandor-ui theme checkdoes. The warnings don't fail the check. The summary has the token lines, and the JSON gainstokens.suggest_componentsreads "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.jsonfor each release: every token's name, layer, type, range, default per mode and density, thedata-slotnames 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 doctorsays when a project has both. - A stylesheet without a font:
@candor-ui/react/styles-no-font.css, the same theme and tokens asstyles.csswithout Inter, for apps that bring their own typeface. Import it instead ofstyles.cssand point--cd-font(and--cd-font-display) at your font.styles.cssstill loads Inter, so nothing changes for current apps. - The free items' changes above (the thinking time,
PermissionPrompt'sheadingLevel,CopyField, source chips,LocaleProvider's time zones,RelativeTime) are in this version. The build fails ifstyles.csslacks Inter, if a font reachesstyles-no-font.css, or ifpackage.json's exports don't match the entries it builds.
For contributors
- Tests mirror the source:
tests/items/<group>/<name>for each registry item, andtests/blocks,tests/templates,tests/scripts,tests/api,tests/site,tests/repoandtests/kitfor the rest. To find an item's tests, open the file with its name. npm run test:browsermeasures 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 areflowgroup for CopyField and source chips at 320 px. It also runs the hosted demos' suite, whichnpm testno longer does. CI runs it as its own job, andrelease:checkruns it.candor.cssis generated bynpm run themefromsrc/styles/partials/, its token values fromsrc/styles/tokens.json. Edit those and runnpm run theme, nevercandor.css. Its header says rows step 8 px per density. CI checks that every filenpm run themewrites is current,candor.cssand the tokens manifest included; a version bump leaves the manifest stale untilnpm run themeruns (RELEASING step 5).npm run registrystops 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 innode_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 * asandimport()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=0runs without the cache. - The registry build reads each item's dependencies from the parsed source, so side-effect imports,
export * asandimport()are declared, and it refusesexport … from "@/…",import("@/…")andimport x = require("@/…"). npm run docsalso writessrc/docs/item-index.jsonandsrc/site/theme-builder/catalogue.json; commit them withapi.json. CI and the release check fail when either is stale.src/site/stats.jsongainsstarters, and the README's starter count is checked against it.- Release check and CI:
npm run release:checkfails if any file undersnapshots/is untracked, and checkscandor.cssand the tokens manifest. CI's agents check also coverssnapshots/, and its workflow token is read-only. The overflow check measures /templates and each demo's base.snapshot-registry.mjs --refrefuses 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 withoutlib/hooksaliases. 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 registrywritessrc/docs/api.jsonbefore the snapshot takes its API record from it, so one run leavessnapshots/r/<version>/api.jsoncurrent.- Snapshots: a new workflow uploads the snapshot files to Vercel Blob on every push to
mainthat changessnapshots/. It needs the repository secretBLOB_READ_WRITE_TOKENand fails, saying so, without it; the upload from the release branch before merging stays.scripts/snapshot-upload.mjstreats aBLOB_READ_WRITE_TOKENof[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 runsnpm ciwithout 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-onto 8.0.5. - Starters:
sync-starter.mjs --checkalso 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.
2.7.0 - 2026-11-09
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.
fieldwraps one control with its label, hint, error and required mark; pass the form's submit count asattemptand, after a failed submit, focus moves to the first field with an error.grouprenders a fieldset for radios and checkboxes.form-error-summarylists 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) andone-time-code(a row of boxes over one field, so autofill and paste work). - Filtering.
date-range-pickeroffers rolling windows (each printed as its exact window) and a Custom window on two calendars, withuseDateRangeTextto word a window in the locale.filter-barbuilds filters from a field, a condition and a value and hands the appFilterRule[];useFilterChipsgives the same chips elsewhere. - Chat and work.
copilot-panelis 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-suggestionshows 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-allis 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-dialogchecks 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-editorcreates 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-keyslists keys, their scopes, last use and expiry, shows a new secret once, and says what breaks when a key is revoked.webhookslists endpoints, events and recent deliveries; a test send shows its result, adding needs an https address, and removing says what stops.environment-connectconnects an environment by OAuth or credentials with a connection test;requireTestkeeps Connect locked until a test with the current values has passed, and a saved secret is never shown back. - Billing.
invoice-historylists invoices in their own currency with status and a download link your app serves.billing-detailsis 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) andserver(Premium): see Theme and foundation, and Blocks and templates.
Changes to existing items (optional props and widened types; existing code keeps working):
- A
stateprop on eighteen lists (SessionList,ApprovalQueue,NotificationCenter,RunLog,AuditLog,Inbox,MembersTable,KnowledgeSources,ScheduleList,AgentRoster,ReviewQueue,TraceViewer,ResultTable,VersionHistory,EvalScorecard,FailureClusters,DeviceSessions, andSpendBreakdown, which hands it to its chart), shaped likeChartState. Loading drawsPageSkeleton, empty and error drawPageStatein 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) andListStateView(page-state) are the shared shape and renderer, andPageStateKindgainsoffline. Each list's docs example switches between its states. DataTableserver mode. WithonQueryChange,rowsis the page the server sent and search, sort and page changes come back as oneDataTableQuery;totalgives "Showing 11–20 of 248",pagecontrols the page, andstatetakes the shared list state.virtualizeshows thousands of in-memory rows in one scrolling body, numbered witharia-rowcountandaria-rowindex. Without the new props the table works as before.LogStreamandAuditLog: a search field (LogStream's is on by default;searchableturns it off) that never hides that lines are missing;virtualize; and inLogStream, 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:
ApprovalQueueandInboxtakeselectable,selected,onSelectedChangeandactions; nothing starts selected, and approving stays one exact change at a time.DataTable,AuditLog,RunLogandSpendBreakdowntakeonExport; the app writes the file. KnowledgeSourcestakesonRemove(asks first, names the source, says it can't be undone here) andonCadenceChange.AgentRostertakesonToggleandonCreate.MemoryManagergains search, filters andonDeleteMany, with a confirmation that says how many memories and who taught them.ScheduleListgainsonEdit,onRunNowandonDeletein a per-job menu; delete says what stops.Comboboxgainsmultiple(values,defaultValues,onValuesChange) and takesaria-describedby,aria-invalidandaria-required. Single mode is unchanged. Inmultiplemode a chosen option is marked witharia-checkedand a "Selected" text, andaria-selectedfollows the highlight, as in single mode; the listbox is notaria-multiselectable.ThreadHeadertakespeoplebesideworking.SelectionActionstakessource, a ref to the app's own content, andactions.MessageActions(free) takesreport, a render function given the report's open state; a bad rating opens it, so the reason is asked once.ReportReplygains controlledopenandonOpenChange.SignIngains optionalproviders(a "Continue with {name}" button each, throughonProvider) andonPasskey; its code field is nowOneTimeCode.- Widened types:
ThreadHeader'sworkingcounts people;PageStateKindgainsoffline; the three money components shareformatMoney(lib/ops), which shows an unknown currency code as the number and the code ("12.5 EURO") instead of throwingRangeError, 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 takedir="auto", so an identifier in a right-to-left page isn't scrambled;KpiRowlays 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,AuditLogandMemoryManager. A page that used one of them now shows a search field. To keep the old look, passsearchable={false}.MemoryManageralso shows scope and origin filters whenever the memories are mixed, and has no prop to turn those off. LogStreamdraws 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.formatMoneykeeps every decimal it is given.$1.005no longer rounds to$1.01, and¥4.5shows as¥4.5where 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 nowOneTimeCode(six boxes), andsign-independs onone-time-code. Update withnpx candor-ui update sign-into get the new file and its dependency; aSignInyou edited merges as usual.PageStateKindgains"offline". Aswitchover it that returns for every case, or aRecord<PageStateKind, …>, no longer type-checks: add a case for"offline".- Smaller DOM changes.
ApprovalQueueandInboxrows gain a wrapperdiveven withoutselectable, so a selector such asli > buttonstops matching (useli button).AgentRosterwith no agents renders adivholding thep.ScheduleList's history strip hasrole="img".DataTable's header wraps Export and Columns in adiv.NotificationCenter's popover has anaria-label. The Toaster's text hasdir="auto".KpiRowis 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 aslg: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 ascd-press,rounded-buttonandh-(--cd-control-h-sm)that generated nothing, with no error, because only the four gallery themes listed@candor/theme.tokensisstyles/candor-tokens.css: Candor's--cd-*variables,@thememapping, 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;themedepends on it too and keeps its files. It is free because free items depend on it.candor.cssis unchanged and stays the one import a Candor project uses. What to do: on your nextaddyou 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 insnapshots/blobs/<sha256>.jsonand each version has anindex.jsonmapping 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 andBLOB_READ_WRITE_TOKENare indocs/DEPLOY.mdanddocs/RELEASING.md. npm run check:layerskeepssrc/registryimports flowing down: foundation (lib/, and thelocale,termsandlockedproviders), ui, blocks, domain. It fails on an upward import that isn't in the baseline; one is known (lockedimportsui/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.cssnow 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_docsname 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.jsonserves each record publicly (names, types and hashes, no source). With?kit=<version>on the server's URL,fromdefaults 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 andpermission-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-claudeversions 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.mdand both npm READMEs.
CLI 0.12.0
candor-ui theme watch [file]runstheme checknow 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).--jsonprints one report per run. An unreadablecomponents.json(half-written, say) is reported and watching goes on.add --dry-runshows what--replace-editswould change: per edited file, your edits (<), the old lines (-) and the new (+), and whatupdatewould do instead. It writes nothing and exits 0.add --dry-run,--diffand--vieware previews: they record nothing and exit 0.mcpanddoctorpass 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.doctorsays 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 /Tand/T /Fon Windows). Before, a shadcn that ignored the signal kept writing. initwith 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, anddoctorreports it withgit diffandgit checkout.addlists shared items and packages even with no lockfile (it reads the newest release's items and names the version);init --latestinstalls a missing font at the recorded theme's version;CANDOR_SHADCN=^4.24.0keeps its caret on Windows; theCANDOR_SHADCNhint 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
serverfoundation. Every block and template used to carry its own identity stub (14viewerOfcopies) and its own database pool (15db/connect.tsfiles), so four blocks opened four pools and replaced the stub four times. The newserveritem (Premium, so installing it needs a Premium or Team key;lib/candor-server.ts,lib/candor-database.ts) is the one place:getViewer(request)andsetViewerSource()for your auth,signedOut()(a 401),database()andsetDatabase()(one pool per server process),Refusalwith 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) unlessCANDOR_DEMO_AUTH=1is set or the app registers its ownsetViewerSource(). With neither, nobody is signed in and every route answers 401. Before real use, callsetViewerSource()with your auth; to keep the demo on a deployed preview, setCANDOR_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.Refusalcarries astatus, 409 unless you give one. - A block'sdb/connect.tsyou customised keeps working only if you register your driver withsetDatabase(). 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)inaudit-data-controls/store.tsandapprovals-inbox/store.tsstays synchronous and returnsCtxas in 2.6, reading the demo cookie only. Routes use the new asyncsignedInContext(request), which asksgetViewer()and returnsCtx | null(null when nobody is signed in); move your calls to it, await it and check for null. AlsoviewerOf(request)in each block'sstore.tsandconnect…Db(url)indb/connect.ts. They are back as thin shims so a block you edited still compiles andupdatedoesn't delete them.viewerOfanswers as in 2.6 and reads the demo cookie only, notsetViewerSource()'s source;connect…Dbreturns the shared pool forDATABASE_URLand a pool of its own for any other URL. What to do: if you replacedviewerOfwith your auth, callsetViewerSource()incandor-server.tsinstead and move your calls togetViewer; if you editeddb/connect.ts, keep your edit or move todatabase().updatemerges both. - The templates sign in through a documented seam: each has a sign-in page (the kit's
SignInthrough the foundation'sDemoSignIn) 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 callsetViewerSource(); nothing else changes. The approvals inbox's words are a strings table (approvalsInboxStrings, overridable underapprovalsInboxinLocaleProvider), and the shells show a skeleton, not a "Loading…" person, until the server says who is signed in. PermissionPromptin the chat views. The 14 chat views (10 blocks, 3 templates and the Next.js starter) usePermissionPromptin place of a hand-rolled "Waiting for your go-ahead" banner;eval-dashboardusesSelect.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'smeta.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;
/apphas 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 fromstats.jsonand 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/docs18 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()andhsl()colours in a hand-edited file are read and converted tooklch(). - 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 --checkand the overflow script's--self-test; from the dated CHANGELOG section it also runssync-starter --check(the starters must not be behind the source). It checks the snapshot store andcandor-tokens.csswithgit status, so new files count, and ignores Finder's untracked " 2" copies. sync-starterwrites.candor-sync.json(kept out of the public starters);public-repo,sync-starterandskills-publishskip Finder duplicates; a filesync-starteradds reaches the public starter before it is committed;public-releasestops 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 fromrelease/2.7because 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.mdno longer creates a GitHub release from the private repository.
2.6.2 - 2026-11-09
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, asAuditLogalready did. Before, a plan called "starter" or a model from Mistral failed the type check. - Right to left:
ProvenanceTracedraws its connectors across the gutter in RTL;SheetandDrawertakestartandendsides (leftandrightstill work) andAppLayoutuses them;TraceViewerplaces its bars withinset-inline-start. ImportReviewshows every issue in a group on request instead of eight and "and N more";ReviewQueuesays when it has nothing to review instead of rendering nothing, and summarises its progress past fifty items;CheckpointList,MembersTable,ScheduleList,AgentRosterandVersionHistorysay when they are empty.PlanPicker,SubscriptionStatusandDowngradeImpactformat money throughuseFormatin acurrencyprop (default USD) instead of a hard-coded dollar sign.card-registryexportsRegistryCard;Cardstays as a deprecated alias until 3.0, so it no longer collides withui/card'sCardin an app that imports both.RunNodegainslastHeardAtandhostOffline, soRunTreeshows a subagent that has gone quiet or lost its host, the wayTaskTrayandAgentActivitydo.withRender(lib/render-prop, free) keeps an element's own children when none are passed, and refuses Base UI's function form ofrenderwith a message instead of crashing.DataImportandSourceIngesttake anerrorfor a rejected file;DataImportcan give a loaded file back.TestResultsfilters to failed tests and re-runs one (onRerun);SteerComposerattaches files.BarChartandLineChart's focusable value rects carry a role, so axe passes on a page that shows them.MembersTableandStepperno longer widen a narrow page.- An agent's
Messageis labelled "Name (Role)", so a screen reader hears "agent" once;AppLayoutdraws 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 defaultagentLabelstring is now "Name (Role)"; the billing items'pricestrings no longer carry a currency symbol, because the formatter adds it, so an override that includes one should drop it;AppLayoutdraws its top row as a<header>, so an app that put its own banner outsideAppLayoutshould move it intotopor 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,toneand other variant props with values and defaults; exported constants such asstandardCardsand the preset kinds have their types, so those pages are no longer empty. Component pages show the Motion section the.mdpages already had. - Blocks and templates no longer list
GETandPOSTas components or repeat their exports;llms.txt,llms-full.txt, the skill'scomponents.mdand the MCP list each one once with its-claudeversion beside it.llms-full.txtlists the functions, values and types of the adapters and shared helpers.scaleis listed under shared helpers. - Each setup guide has a Markdown version at
/guides.mdand/guides/<tool>.md, linked from the page. suggest_componentslists 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 optionalsdk(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 passsdk.- The
candor-uiskill names all twelve MCP tools and says to calllist_screensfirst for a new screen.
CLI 0.11.2
candor-uiruns a pinned shadcn (shadcn@~4.23.0) instead ofshadcn@latest, becauseaddandupdateread what shadcn prints.CANDOR_SHADCNruns another version, range or tag. A weekly CI job runs the fresh-app check againstshadcn@latest.initinstalls the theme and Inter the wayaddinstalls an item: at the versioncandor-lock.jsonrecords, and recorded in it;init --latesttakes the newest release. When the lockfile records the theme,init --overwritestops and points tonpx 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 puttingcomponents.jsonback, 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,
addsays 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".
addprints 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.doctornotes when@candor-ui/reactis installed beside copied items (the package's providers don't reach the copies). On a Base UI project,doctorandaddsay that Candor's primitives are Radix and name the project's own files they would go over;addsays so before shadcn runs.
The site
- Every
/screenspage,/docs/members-tableand/docs/stepperfit 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-uiCLI, 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 thecomponents.jsonblock is whatinitwrites. /appis pre-rendered with its own title and description, its way back goes to/examples, and its notice and top bar sit in landmarks;/galleryredirects 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/reactchanges 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;tsconfigand 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 registrybuilds the motion manifest itself; CI's stats check keeps the committed test count (stats.mjs --keep-tests), and the release check counts.
2.6.1 - 2026-11-09
No package of the kit changed. Only the candor-ui CLI did, to 0.11.1. The registry’s items and @candor-ui/react are as in the release before, and the package wasn’t published again, so it keeps the earlier version number.
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 addinstalls at the versioncandor-lock.jsonrecords (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@candorregistry entry at that release's snapshot (/r/v/<version>/) and putscomponents.jsonback after, on failure and on interrupt too. Before,addalways installed the newest release and rewrote shared items to it (Storywrite's ask 36).- New
add --latest(the newest release) andadd --version <x.y.z>(that release; a version/r/versions.jsondoesn'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,
addnames the installed items it would move to another version, and the edits it would overwrite, and stops unless--yesis given ("This would move locale, render-prop and status from 2.1.0 to 2.6.1…npx candor-ui updateis the way to move them on purpose. Nothing was installed."). With--yesthe same line is a notice. The last line says what was installed and at which version. - Unchanged, on purpose:
initstill installsthemeand the font from the newest release.
2.6.0 - 2026-11-09
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'sdata-densityon<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 theh-(--cd-control-h-sm)form so a consumer'sh-10still wins throughcn().- 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 itsthemeitem still draws the default sizes. npm run check:densityfails 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 inrelease:checkand CI.
The docs MCP and CLI 0.11.0
theme_checkin the docs MCP server (read-only, keyless, fetches nothing): send the contents ofcandor-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 yourpublic/. 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 checkand the MCP'stheme_checkrun 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.
2.5.1 - 2026-11-09
No package of the kit changed. The registry’s items and @candor-ui/react are as in the release before, and the package wasn’t published again, so it keeps the earlier version number.
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
@importlines andtheme check), in the brand FAQ, and inllms.txt, the design reference and the theme docs, so a coding agent can find it./themespoints at the builder's checks andnpx 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/motionrenders 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".
2.5.0 - 2026-11-08
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
/appdemo 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
@motiontags. - A worktree's dev server serves fonts through its linked
node_modules.
2.4.0 - 2026-11-08
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.Alertcounts "first draw" from the page's load, so the first alert an app shows can rise in.Composerchips are flex children of the chip row again;EntityChipandAttachmentChipgainstyle. -useLeaving's fallback is 600 ms;useMotionMode(ref)is new inlib/motion.ts; families with one drawing are marked fixed in the design reference;check:motionrequires literal defaults. - Pro - A decision lands:
ApprovalRequestandEntityDisambiguationopen the outcome line and draw its tick or cross only after the service confirms;Planopens 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,SessionListandRunLogrows rise in when added after first draw (never on a tab, filter, pin or scroll);ApprovalQueueandInboxrows 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,RunReceiptandBadgecrossfade a figure that changes and pop a count that rises; nothing counts through numbers that were never measured. - Validation:InputandTextareagainattend: one attention ring on the invalid field after a failed submit, never a shake, and never on first draw.AccountCreateandSignInfocus and ring the field the error concerns once the service has answered, and fade their messages in;InviteMembersfades in its "won't be sent" note. -TypeToConfirmpops each time the text comes to match exactly and shakes (expressive only) when it stops matching.EnvironmentBandrings once, in the environment's colour, when the environment in scope changes. - Measured fills:BulletBarandUsageMetersmove between measured values;DataImportgainsprogress(0–1, a bar only while reading). - Checks draw as they return:ShipReview,TestResultsandRestoreResultdraw each check's mark when its result arrives;RestoreResultgainsfresh.SteerComposerdraws the read tick onpicked-up, never on send. -Drawer'sdata-sideis nowdata-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;ComboboxandCarouseluse 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:
useAttentionplays the brand's sound for each signal (sound.srcis now optional;sound.when"away" | "always", "always" when left out;sound.events; per-signalsound; kinds mapapproval→needs-you,finished→finished,failed→failed); coalescing now also applies to an explicitsrc. NewuseArrivals(ids, onNew), which calls back only for ids not present at its first render. Newsound-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. Newsounds: five short CC0 sounds from Kenney (0.18–0.57 s, under 5 KB each); the registry carries text, so it installsscripts/candor-sounds.mjsandpublic/sounds/LICENCE.txt, andnode scripts/candor-sounds.mjswrites the five MP3s topublic/sounds/.
The motion manifest and `data-slot`
src/docs/motion.json, written bynpm run docs: every family's settings and, per item, its moments with family, defaults, utilities and the sentence from its@motiontag. 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.jsonand/r/v/<version>/motion-manifest.json, no key needed.- Every component's root carries
data-slot="<item>"(npm run check:slotskeeps 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.mdgains the nativeAttentionKindmapping, thewhen: "away"default and the drawer rename. tw-animate-cssis 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 withswitchandcheckbox.
CLI 0.10.0
theme checkreads motion and sound against the motion manifest of the kit you have installed (amotion.jsonbesidecandor.css, else the registry's copy for the version incandor-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-themenewer than 2. A sound length it can't read is "not measured", never a pass.--jsonaddsmotionAndSound.- New
theme apply <file | url>: checks the file in memory, writescandor-brand.cssnext tocandor.css(asks before replacing one;--overwrite), adds the import aftercandor.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 runpasses.
2.3.0 - 2026-11-08
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,liveandclock. 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 hooksuseSettled,useArrived,useLeavinganduseMotionAllowed. 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-animateclass is left in the registry, blocks or templates, andnpm run check:motionkeeps it that way. Updatethemetogether with your components, because they use its newcd-*utilities. 2.2'sanimate-*utilities and a brand's--cd-pop-fromor--cd-motion-shakestill work. Small visible differences atsubtle: 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;
livegoes still beside its word,attentionis one ring that fades,clocksteps,revealsnaps to its measured size.data-motion="calm"offers the same as a choice in the app;nonestays the hard off and outranks everything, andsubtleandexpressiveare 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,
lastHeardAtandstaleAfter: a running dot pulses only while the run has been heard from withinstaleAfter, 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 withdata-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;lockedkeeps it focusable and says why, andthumbLabelsnames the thumbs),progress(moves only between the values it is given; with no value it is indeterminate rather than a guessed fraction),label,alert(destructiveisrole="alert", the restrole="status") andaccordion. - Pro:
toggleandtoggle-group(the highlight slides to the chosen item),alert-dialog(focus starts on Cancel; theirreversibleprop prints what can't be undone and ties it to the action),drawer(follows the pointer one to one when dragged, novaul;onDismissAttemptruns before Escape, an outside click or a drag closes it and can keep it open),menubar,context-menuandnavigation-menu(submenus open from their trigger; items takelockedwith the reason beside them),breadcrumb,pagination(PaginationRangesays nothing about a total it wasn't given;pageWindowpicks the page numbers to draw),table(the plain table besidedata-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),calendaranddate-picker(months, weekdays and digits from the locale, viaIntl, noreact-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) andcarousel(scroll-snap, "3 of 8", no auto-advance unless you setinterval, and it pauses on hover, focus, reduced motion anddata-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.mdopens the ledger of agreed breaking changes for a future 3.0, each with its migration.
CLI 0.9.1
auditreads the page as someone who asked for reduced motion:infinite-animationnames what still loops, and the newcalm-motionnames transform, translate, scale, rotate and height animations and transitions that still run.lintwarns (motion-hardcoded) about raw durations,tw-animateclasses andtransition-allin files that use Candor components, and points at the motion families.doctor's clash check knows the new primitives.
2.2.0 - 2026-11-08
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 inscripts/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 itemstheme-slate,theme-paper,theme-console,theme-signal: an override file imported aftercandor.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 waycandor.cssdoes, 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 shadcnglobals.css, a Tailwind config, or a Figma variables export) into acandor-brand.cssoverride 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 ofsrc/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, runslint; 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). WritesAUDIT.mdgrouped 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 --installedsays "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.mjsrenders the templates and gallery pages in light, dark and high contrast at desktop and phone widths with Playwright, and/examplesshows them with alt text. Not run in CI. - Skills publishing:
scripts/skills-publish.mjsvalidates both skills' frontmatter for the skills.sh registry and prints the publish commands;docs/RELEASING.mdstep 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-labelon a span. - Honest vs. typical: the estimate example's Start runs a scripted run to a measured result.
- Theme builder:
applyuses 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.mdhas the evidence); the adapter waits for stable shapes.
2.1.0 - 2026-11-08
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 witharia-expanded, folds away, and can show asummarywhile folded ("3 checks, 2 with time limits");collapsibleanddefaultOpensay which. Acommandvalue is monospace, wraps, and has a copy control that says "Copied" only after the clipboard took it;codeis the same without the control; alinkis followed only inside the app; an unknown value shows as "Not known".AttributesRailstays the flat sibling. Install withnpx 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,onPinoronDelete, 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.
RelativeTimewithbarestill 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'stextContentnow holds it as well as the short form ("2 days2 days ago"); a test that readstextContentshould match on the short form or query the element it means. Update withnpx candor-ui update session-list relative-time. - CLI 0.8.1:
candor-ui lintknowsDetailsListas a Candor component, so a file that uses only it counts as using Candor.
2.0.0 - 2026-11-08
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 thatnpm run themechecks, now insrc/lib/contrast.tsand shared by the script and the site. Nothing is fixed for you silently; failing pairings are named with a passing lightness you can apply. Downloadcandor-brand.css(overrides after thecandor.cssimport, with the result in its header) or copy aDESIGN.mdaddendum. 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, inllms.txt, and in the docs MCP asget_screenandlist_screens;suggest_componentsnames 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) andstarters/tanstack-start-claude(TanStack Start + the Claude Agent SDK adapter, the same to-do agent as the Next starter).scripts/sync-starter.mjsrefreshes all three; the public repo publishes them asstarter-vite-ag-ui/andstarter-tanstack-start-claude/besidestarter/.
CLI 0.8.0
candor-ui list [--tier] [--group] [--installed] [--json],search <words…>andinfo <item>read the site's docs index, so a person or an agent can find an item from the terminal;--installedmarks whatcandor-lock.jsonhas 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.csslikefont-inter. - theme: a
spaciousdensity preset,data-density="spacious", the other way fromcompact.
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); acaptionsays 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
TermsProviderpreset where its words differ; likesalesforce-kinds.
Repo
docs/RELEASING.mdpublishes the MCP registry entry (com.themethodic/candor) with each version.
1.9.1 - 2026-11-08
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,Attentionpluscounts(the number waiting perkind); theAttentiontype 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'sestimate-as-measuredalso 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 ascall={{ 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, andsettledCountandretryCountare checked. Candor's own source still has no finding.
1.9.0 - 2026-11-07
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 andllms.txt. - Plugins. Claude Code:
claude plugin marketplace add MethodicDev/candor, thenclaude plugin install candor-ui@candorinstalls the skill and the docs MCP server together (.claude-plugin/). Cursor, Codex and VS Code / Copilot packages underplugins/, with.cursor-plugin/marketplace.jsonand.github/plugin/marketplace.json(copilot plugin install candor-ui@candor)..mcp/server.jsondescribes 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.mdtells 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.mdand/design.md, generated from the shipped CSS byscripts/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. Thecandor-uiskill gains an "After each screen" section pointing at the checklist and design.md. - Docs MCP: new tools
get_design,get_review_checklistandget_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>andinit --mcp <tool>add the docs MCP server (https://candor.themethodic.com/mcp, read-only, no key) as a server namedcandorto 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, anddoctorsays 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/.jsfiles against the honesty rules:model-html(error: HTML rendered from a string in a file that shows a chat),disabled-without-reason,preselected-decisionandestimate-as-measured(warnings). Printspath:line:col rule message, exits 1 on an error;--strictfails on warnings,--jsonfor 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, likedata-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 asduration-(--cd-dur-base)), and keyframescollapse-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,FoldedTurnsand 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.StatusDotpops 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-copycarries 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, forholdMs(1200 unless the app says otherwise) beforeonConfirmfires. The bar fills from the clock; letting go early cancels and says so. The requiredreason(what it does, whether it can be undone) is read with the button;lockedsays 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 (untilorseconds; no default, so without either the app'scannotUndotext shows and there is no Undo). Time left is read from the clock, so a slept tab catches up. Pending untilonUndosettles, 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 byclear(). System notifications only withnotifyon and permission already granted (the hook never asks;requestPermission()is for the app's own button); sound only with asrcthe app passed andenabled: 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.mdis the release runbook,CLAUDE.mdthe repo's standing instructions, andnpm run release:checkruns CI's checks locally with a preflight on the version, the CHANGELOG and the package versions.
1.8.1 - 2026-11-06
Three accessibility and theming fixes a customer found in 1.8. No new props.
CommandPalette: the search box also carriesaria-label(thesearchstring). In 1.8 it was named only by cmdk's label, hidden withdisplay: none; Chromium follows that througharia-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 withvirtualizetoo, 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 ownsm:max-w-sm(384px) had won at every width the panel is a sheet.
1.8.0 - 2026-11-06
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 withhref(new onSession) 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 throughonOpenfor your router; other clicks are the browser's. Withouthref, rows are buttons as before.AppLayout:navOpenandonNavOpenChangecontrol 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 carriesdata-nav("rail" or "sheet") andgroup/app-layout, so your own button can show only while the sidebar is a sheet (group-data-[nav=rail]/app-layout:hidden).CommandPaletteis named once: the dialog by its title, the search box "Search" and the list "Results" (new stringssearchandresults). 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 withmentions, "/ command" (new stringhintCommand) only withcommands.hints={false}hides them.
Plan drift and autonomy (Pro)
Plan: drift. A step can say how the run left the approved plan, withdriftonPlanStep({ 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. Withautonomy(a list ofPlanAutonomyOption), accepting says what it allows. The person picks one before Accept is available; none is picked for them.onAcceptgets the choice as its second argument. - Two options have built-in words:"askBeforeEdits"("Ask before each edit") and"runWithoutAsking"("Run without asking"). Your own takelabelanddetail;lockedsays 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 MCPinput_requiredresult as Candor data, and the person's answers back as the retry. -mcpInputView(result, { server })turns each of the server'sinputRequestsinto an item, in the server's order. A form (elicitation/create) becomes questions inClarifyingQuestions' 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-answerDecisionforApprovalDecision. - A link the server wants opened (URL mode: a sign-in, a payment) is aDecisiontoo, 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 asown. -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 theinputResponsesto send. Declined and dismissed requests are sent as such, and what wasn't sent is listed innotSent. -mcpRetryParams(original, view, inputResponses)is the original call's params with the answers and the server'srequestStateexactly 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 fitClarifyingQuestionandDecisionas they are. The words are inmcpInputWords; 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. PasttoolLimit(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.onConnectgets 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,busyanderror. - Connect and Cancel are the same size and style, so neither is the easy way out. - Its words are undermcpConnectinLocaleProvider'sstrings.
New items only: nothing existing changes.
Usage that isn't metered yet (Pro)
UsageMeters:pendingis 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.mayExceedBysays 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…Textversions for server-formatted money. The meter never works either out.
React 19.3 and the React Compiler
SidePanel:keepTabskeeps 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/clearand similar) gets a line too: the agent doesn't see the messages above. eventTextgives these lines your own words, for other languages.recalledon 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 aMemoryUsedline in that message'sfooter.
CLI (candor-ui 0.6.0) and finding components
update <item> --moved a=brecords 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--movednaming a file no item here installed is refused, with the paths the lockfile does know.addwith 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.txtand the docs MCP'slist_componentsandsearch_docsname an item's other components:approval-requestexportsApprovalRequestandApprovalDecision.get_component_docsalready 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.
1.7.0 - 2026-11-06
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. - WithlastHeardAt, a running run heard from recently says "Running · heard 1 minute ago". Silent for longer thanstaleAfter(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", orneeds) 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. - WithoutlastHeardAt, the app isn't tracking freshness, and the status is shown as given, as before. -compactis 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. -onWithdrawtakes 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. lastHeardAtandhostOfflineonBackgroundTask,AgentActivityEntryandSession, with astaleAfterprop onTaskTray,AgentActivityandSessionList. A silent or offline run stops showing as running in each: -TaskTraycounts 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. -AgentActivityshows the same line instead of the agent's status. -SessionListshows it instead of the status withshowStatus; without it, the dot stops pulsing and its label says why.status(free) gainsrunLiveness(run, now, staleAfter), theRunLivenessandHostOfflinetypes, andSTALE_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. WithonApproveEditedand the request's newinput(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 viewPermissionPromptshows for an edited tool call, and the edited change's own hash once it's worked out. "Approve as edited" callsonApproveEdited(hash, input)with that hash; an edit that changes nothing approves throughonApproveas 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.hashOfworks the hash out (by defaultchangeHash: 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'supdatedInput.- 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.inputanddecision.editedFrom(both optional).
Blocks (Premium)
- Approve from anywhere (new,
approve-from-anywhereandapprove-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 compactApprovalRequest, 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, throughmayDecide) 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'sApprovalStore; 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'sresume). 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 theanywhere_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.onOpenmakes each one a button (to open it inMemoryManager, say) andonManageadds "Manage memory".fromHistorysays 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).forgottencounts memories it used that have since been forgotten, without words it no longer has. With no memory used it renders nothing. Put it inMessage's newfooter.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,errorandlockedwork as inPermissionMode.MemoryManager:history(withchatswhen 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."modesays 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 likeMemoryUsed.MessageFootertakes it too. Without it, nothing changes.know: theMemoryModeValuetype ("on", "paused", "off").
New strings: memoryUsed and memoryMode tables; memoryManager gains emptyWithHistory, history, historyCount, paused and off.
Thread, messages and composer (free)
Thread:anchoropens 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;scrollerRefhands over the scrolling element;onDroptakes files dropped on the thread;fade={false}turns off the soft fade at the bottom.MessageandMessageHeader:density="compact"draws a 12px name in a 24px row.MessageandMessageContent:bareCodeshows 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'stimeFormat="time"for a clock time.FoldedTurns:headerreplaces 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").lockedstill disables the box. -textareaRefto focus the box from outside. -sendShape="round"for a round send button.
CLI (candor-ui 0.5.0)
add --overwritestops before shadcn replaces an installed item you've changed: it names the files, installs nothing, and says to bring them up to date withupdate(which merges) first.--replace-editsreplaces 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),
addsays so, names that file, records nothing for those items and exits 1. Before, it said the items were "already installed".
1.6.0 - 2026-11-06
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
exactOptionalPropertyTypeson. 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 incard-registryanda2ui-surfacemarkstateandrenderasoverride.
Messages and times
Message,MessageHeader,MessageFooterandThreadEventtaketimeFormat:"relative"(the default), or an absolute"time","date"or"datetime"in the locale, for every time the message shows.Messagetakesmeta:falsehides the "You · time" line under a person's message, a node replaces it.message-contentinstallssafe-markdown, and the docs nameplainBlocksandmarkdownBlocksas the way to build a message's blocks. Import them fromsafe-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 througharia-valuetext),RunReceipt(totalText, and a model'scostText),RunEstimate(costText),SpendBreakdown(totalText) andStatCard(valueText). The numbers still place bars and markers.
Toasts
Toastertakesoffset(or the--cd-toast-offsettoken) 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-…"onToasterstill 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-fontfalls back to the system's sans-serif. candor-ui initadds and imports it unless you pass--no-font. If you update the theme and want Inter, runnpx candor-ui initagain (it adds the font and changes nothing else), ornpx candor-ui add font-interand importstyles/candor-font-inter.cssaftercandor.css.updatesays so when it takes Inter away, anddoctornotes when text uses the system font.
CLI (candor-ui 0.4.0)
updatefollows 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>, andcandor-lock.jsonremembers 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
updatecan't find is now left alone: nothing of it is written, it stays at its old version, andupdateexits 1. Before, it moved on without that file. verify, for CI: checkscandor-lock.jsonagainst 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, anddoctorflags 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,--movedandverify;/docs/cliand/docs/updatinglead there.
Accessibility (WCAG 2.2 AA)
- A public accessibility statement at /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 themenow 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.
AppSidebartakeshelp, 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).
1.5.1 - 2026-11-06
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.
capToastsis exported for tests.
CLI (candor-ui 0.3.1)
initandkey(includingkey --remove) move@candoroff 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-urlstill sets any address you choose.- On the old address,
addandupdatestop and say to runinit, rather than sending your licence key to GitHub.doctorflags it (in a monorepo's shared package too) instead of saying "All good", and skips checking the key.
1.5.0 - 2026-11-05
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 anApprovalStoreinstead of only in process memory.memoryApprovalStore()is the default; pass your own (a table, a queue) asapprovals, so any instance can take the answer.waitByPollinghelps 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 outsidestreamClaudeAgent, 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.4answerClaudeAgentApprovalstill works, synchronously, on the default store. - AClaudeRunStore(memoryRunStore()) keeps a run's events. Withdetach, a run carries on when the browser goes away, andattachClaudeAgentRunstreams it again from any point, then live.stopClaudeAgentRunstops it. Responses carry the run's id inx-candor-run-id.onEventhands you every event to keep for replay, andpromptrecords what the person sent as the run's first event. A run store creates a run only onstart, andmemoryRunStoreforgets only finished runs (oldest first, pastmaxRuns), so a live run keeps its owner. It keeps up tomaxEvents(5,000) per run, after which partial-text events are dropped. -approvalTimeoutMscloses a request nobody answered as expired: the tool is denied, never allowed. Set one withdetach, 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_closedcarries 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'ssetPermissionMode, streaming input only) and tells the browser. The route enforces policy: modes outsideallowed, or the run'smodes, are refused, so a modePermissionModeshows 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):initialEventsreplays a stored conversation;attachUrlandrunIdre-attach to a run after a reload (attach()does it on demand);onRespondanswers through your own route instead ofapproveApi, which is now optional;stopApistops a detached run;modeApi,permissionModeandsetPermissionMode.respondtakes a fourth argument withupdatedInput,answersandalwaysAllow. Requests now send apromptIdtoo: pass it to the server'sprompt, and re-attaching withinitialEventsreplaces the run's events instead of adding them again. - Vercel AI SDK 7 (
ai-sdk,use-candor-chat): runs onWorkflowAgentstream 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 ownWorkflowChatTransport.
The Claude Agent SDK's permission model (free)
AskUserQuestionbecomes questions:ClaudeApproval.questions, shaped forClarifyingQuestions(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.ClaudeApprovalalso carriessuggestions(the SDK's "always allow" rules, offered and never kept unless the person picks one),noAlwaysAllow,mode,displayName,agentIdandmcpServer.claudeSuggestionsturns the rules into plain parts to show.claudePermissionResult(request, answer)turns an answer into the SDK'sPermissionResult, wherever the answer lands.fromClaudeAgentEventsreportspermissionModefrom the SDK'sinitandstatusmessages and the newcandor_modeevent.- 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. ToolCalltakesapproval: { 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,withProvenancefor copied text,provenanceMetadata(ai:involvement,ai:by,ai:at) for downloads and sidecar files, anduseCopyWithProvenance. - 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,RestoreResultshows 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: -targetandvalues: a change to one thing shows each value before and after (from: nullreads "Not set"; afromleft 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;onOpenopens the full request.- New:
TypeToConfirm(type-to-confirm): a step that can't be undone, confirmed by typing a name exactly. Pasting is allowed.DataControlsnow 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 offerother(the person's own words, sent astext), atagabove the question, andduringdrops "Before I plan" from the heading when the agent asks mid-run.- Changed type:
AuditActionis now open: Candor's known actions (KnownAuditAction) or any string.AuditLogtakesactionsto 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 everyAuditActionshould add adefaultbranch, and aRecord<AuditAction, …>map in your code no longer type-checks: key it byKnownAuditAction, with a fallback for other actions.
AG-UI 1.0 (free)
STATE_SNAPSHOTandSTATE_DELTAfold intostate(onfromAgUiEventsanduseAgUi). Deltas apply all or nothing; a patch that fails keeps the last good state and setsstateOutOfDatewith the reason until the next snapshot.ACTIVITY_SNAPSHOTandACTIVITY_DELTAbecomeactivities, in arrival order. Steps map toplan(shaped likePlanStep) and status content toagentActivity(shaped likeAgentActivityEntry), only when every status is a known word.- New
applyJsonPatch, a small RFC 6902 patcher that never changes its input.fromAgUiEventsanduseAgUitakeagentsandinitialState.
Citations from tool output (free)
- The Claude adapter fills
Message.sourcesfrom 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. TheToolSourcetype is inlib/chat.
Docs MCP server
/mcpspeaks MCP 2026-07-28: no handshake,server/discover, the version checked on every request (MCP-Protocol-Versionmust match_meta, else 400HeaderMismatch-32020), and an unsupported version answered with -32022 listing the supported ones. A 2026-07-28 request must sendMcp-Method, andMcp-Namefor the methods that name something (400HeaderMismatchwithout 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,pingand 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/uiplusapps/web) now work: -initfrom 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 bothcomponents.jsonfiles. - The licence key reaches shadcn when it runs in or writes to the shared package. - Run at the repository root,init,add,updateandkeystop, name the workspaces and say which--cwdto use;doctorchecks every workspace with acomponents.json. - A root.gitignorethat already covers.env*.localcounts; React given ascatalog:and Tailwind in the shared package are found; install commands use the project's package manager (pnpm --filter … add …). -candor-lock.jsonstays beside the app'scomponents.json;updaterun from the shared package says where it is. doctorsays 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 thatcnresolves, including after shadcn'smigrate cnto thecnpackage, and gives the line and the install command when it doesn't.
1.4.0 - 2026-11-05
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)
ProseDifftakesreadOnly: the changes between two texts with no accept or reject, headed "Changes" with a count ("3 changes"), andonResolveis never called. Use it to show what changed between two published versions.RetrievalInspectortakesverb, the word before each passage's date, for what itsreadAtrecords: "Reviewed", "Published", "Synced". The default is still "Read". The knowledge-base blocks pass "Reviewed".FailureClusters: - A cluster'sdeltacan benullwhen there's nothing to compare with, shown as a dash and read as "change unknown". The newFailureClusterInputtype (aFailureClusterwhosedeltamay be null) is what it takes;FailureClusteritself 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. -sincesays 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,fewerandnoChangenow take{since}. - The eval-dashboard blocks passnullbefore there's a production run to compare with, andsince="production's run". Before, they showed no change. If your own code passed 0 to mean "nothing to compare with", passnullnow. -FailureClusterInputlives inops, so updateopswith it:npx candor-ui update failure-clusters ops(a plainnpx candor-ui updateupdates everything). candor-ui 0.2.3 says so when you leave one behind.
Docs MCP server
/mcpallows 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.createDocsMcpHandlertakesrateLimit.
CLI (candor-ui 0.2.3)
updatenow 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.
1.3.0 - 2026-11-05
Docs for coding agents
- Every docs page is also Markdown at its address plus
.md:/docs/<name>.mdfor every item,/patterns/<slug>.mdand/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 theLocaleProviderstring keys.llms.txtlists 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, andsuggest_componentsfor 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)
toolsputs your own controls in the composer's toolbar, after the attach button.
Dictation (Pro)
DictationButtonanduseDictation(new,dictation) let a person speak into the composer. It's opt-in: put<DictationButton value={value} onChange={setValue} />in the composer'stools. 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.allowBrowserServiceopts 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 aftermaxSeconds(120, counted from when it starts listening) and whendisabled, 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 indictationStrings, underdictationinLocaleProvider. - 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
toolsslot.
Blocks (Premium)
- Knowledge base (new,
knowledge-baseandknowledge-base-claude): - An agent answers only from published help-article versions and cites the article and version. The code checks each citation against whatsearch_articlesactually 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 thekb_tables. - Eval dashboard (new,
eval-dashboardandeval-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 theevdash_tables.
1.2.1 - 2026-11-05
A patch: no component changes.
CLI (candor-ui 0.2.2)
- Behind a proxy,
key,doctorandupdatenow send their own requests throughHTTPS_PROXY(honouringNO_PROXY) on Node 24.14 or later. On Node 22.21+ and 24.0+, candor-ui says to setNODE_USE_ENV_PROXY=1; on older Node, to upgrade. shadcn already used the proxy. updateand 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 asapp/page.tsx, andnext build, against that change's registry and CLI. It also checks thataddrecorded the items incandor-lock.json.
Docs
- The agent skill explains theme nesting:
darkandhcwork on an inner element,lightdoesn't switch back inside a dark one.
1.2.0 - 2026-11-05
App shell (Pro)
CommandPalettetakesfilter, passed to cmdk as(value, search, keywords) => score. The newmatchEveryWordis 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 readskeywordsonly, never cmdk'svalue, which holds ids.- Fixed: closing
CommandPalettenow puts focus back on what had it when the palette opened. Before, a palette opened by a shortcut (noDialogTrigger) 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.onCloseAutoFocuslets you steer focus yourself. AppLayouttakesresizable(default true). Withresizable={false}the panel stays atdefaultPanel's width and the divider is a plain border with no handle.SidePanel: a tab can carry acount(hidden at 0), read by screen readers ascountLabel("2 need you") or thesidePanel.countstring (joined to the name bysidePanel.countAfterName), withcountTone="attention"for things waiting on the person.actionsputs buttons at the end of the tab row (hide the panel, open full width), outside the tab list.SessionListtakesgroupBy(your own headings instead of pinned and days) withgroupOrder, andshowStatusto print each session's status in words with its dot.Sessiongainsdetail(a second line, such as what it is doing now) andstatusLabel(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 aSidePaneltab or full width. A document'stextis read into safe blocks withmarkdownBlocks(text, { headings: true }), or you passblocks. 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.onDownloadgets the artifact's id and the chosen format (formats: Word, PDF…), andonFullWidthChangeadds Open full width / Back to the panel.headingLevel(default 2) fits the title into your page's outline. New types inwork:ArtifactandFileFormat.
Variants (Pro)
Plantakesdensity="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).actionsputs buttons under the steps (Pause, Stop) in any mode, beside Accept when proposed.UsageMeters: a usage'sestimate(your own figure, such as a quote) is a tick on the bar, printed under it as "Estimate: 2.6 USD", or with yourestimateLabel("My guess"). Without a limit it is printed with no tick. The meter never projects an estimate itself.ApprovalDecision(new export ofapproval-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, andlockedgives a reason. New types inwork:DecisionandDecisionChoice.- A setup gate from
AccountState:stepslists what's left as a checklist in the card,childrenholds your own controls, and an action can belockedwith its reason until the steps are done.emailandonSignOutare now optional (the signed-in line shows when both are set).SetupChecklisttakesbareto 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 (yourstatusLabel, 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 inwork: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 atheadingLevel(default 3). Nothing is a link: open and download go through your handlers. New type inwork: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 inwork:ReceiptLine.
Long histories
Threadtakesvirtualize(free): only the messages in or near view are rendered, each child being one item keyed by itskey. The column stays alog, 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.SessionListtakesvirtualize(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. Withoutvirtualize, nothing changes.
Project workspace template (Premium)
project-workspace(Vercel AI SDK) andproject-workspace-claude(Claude Agent SDK) install underapp/project-workspace/. Each project is a conversation with an agent team. The rail lists projects grouped into Needs you, Projects and Finished (SessionListgroupBy, 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, withArtifactPanelas the reader and Open full width) and History. The ⌘K palette usesmatchEveryWordand 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_URLis set (tables start withworkspace_, with migrations and a seed). It is tested on both, including two answers racing and two questions asked at once.
1.1.1 - 2026-11-05
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
.darkvariant thatshadcn initwrites came after thecandor.cssimport and replaced Candor's theme (only system dark mode survived).candor-ui init --yesnow comments out shadcn's default:rootand.darkcolour blocks and its dark variant;doctorflags them. Overrides you wrote yourself, and a dark variant of your own, are left alone, and overriding Candor's tokens aftercandor.cssworks as before. candor-ui addrecords what it installs. Most fresh installs were reported as "already installed, with changes" and left out ofcandor-lock.json, soupdatecouldn't merge them. The CLI is 0.2.1.candor-ui keychecks the key with the registry (10-second timeout) and says whether it's valid and for which tier;doctordoes 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 amessageso shadcn no longer prints "undefined". - One install story: docs pages, llms.txt and the skill use the
candor-uiCLI, 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.
1.1.0 - 2026-11-05
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.TermsProviderstill 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'ssidestays the physical edge you name.dirfollows the locale (Arabic, Hebrew, Persian, Urdu…) or is set on the provider; set it on<html>as well. RelativeTimetakesformat="date" | "datetime" | "time"for an absolute time, and its words and units follow the locale.
Messages
Messagetakesactions:falsehides 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) andMessageFooter(stopped and failed states, sources, who checked it, actions), to rebuild a message your way. App content still goes in acardblock, so messages stay plain data. - Thread pieces (free):
ThreadDividermarks a day ("Today", "Yesterday", a date) or a chapter;ThreadEventis a quiet centred line for something that happened ("Sam joined"), with anattentiontone and a time, and system messages are now drawn with it;FoldedTurnsfolds a run of turns into one line with your summary and opens them in place. - Attachments (free,
attachment-preview): a newattachmentsmessage block shows sent files as tiles, with an image preview when your app supplies apreviewUrl, an icon by type otherwise, and the size in the locale. A file is never a link:onOpenAttachmentonMessagemakes each tile a button.AttachmentChipis the composer's chip,AttachmentLista row of tiles.Attachmentgains optionalmediaTypeandpreviewUrl. Composerattaches files that are pasted or dropped on it (with a drop target while dragging), and takesacceptfor the picker.- New block kind.
MessageBlockhas a new kind,attachments. If youswitchover block kinds in your own code, thedefaultbranch 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>ordata-syntax="highlight"on<html>. Its colours are in the theme's contrast checks. Payloadtakesbare: 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, Tailwindtext-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 aftercandor.cssto fit your brand. - A compact preset:
data-density="compact"on<html>or any container gives 14px conversation text, 13px body and label text (text-baseand 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;addnow writescandor-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. SetlocaleandtimeZoneon 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.
MetadataDiffis nowChangeDiff, labelled "Changes"; the old name still works and is deprecated until 2.0 (the item is still installed asmetadata-diff). Doc comments in the work and chat types no longer use Salesforce examples.AccessRequestshows the environment a request was sent for by its name (and Production or its detail), not the idonSendreturned.BulletBarbands now shade from the end whenhigherIsBetter={false}, so the darkest end is always the worst.EmailPreviewshows an email inline, without a whole<html>document, with its title at your page's heading level.renderEmailandEmailLayouttake the email's language and words.ChartFrameandAppLayouttakedefaultWidth, used until they can measure themselves (on the server, and in jsdom tests, which measure everything as 0).ChartSizeProvidersets it for every chart inside.SsoSetupandSubscriptionStatustake alabelfor 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.EmailLayoutstays server-safe: it takesstringsandlangas props, and so doesrenderEmail. - 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.
1.0.1 - 2026-11-05
Fixed
npx candor-ui init --yessets up shadcn in a new project without stopping for questions; at a terminal,initruns 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.
1.0.0 - 2026-11-05
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
asChildand Base UI'srender.
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
plainblock: line breaks kept, nothing parsed); only an agent's text is read as safe markdown.markdownBlocks(text, { headings: true })turns#lines intoheadingblocks. If youswitchoverMessageBlockkinds in your own code, give it adefaultbranch: new kinds can arrive in a minor release. - The inline node for a value read from the user's system is
measured(it wasorgData, 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.