What's New
Release notes and changelog for all packages.0.7.2
New Components
- Promote
DrawerandDrawerHeaderfrom the canary-only Lab package to Core, imported from@astryxdesign/core/Draweror the package root. The stable package now ships the full-height side panel with modal and non-modal presentation, the shared dismissal stack, Dialog'spurposedismissal policy, aDrawerHeaderwhose close button appears when givenonOpenChange, and Dialog-style container padding (--spacing-4by default,paddingprop, or a theme'sdrawerpadding), plus Core documentation and runnable examples. Canary users importing from@astryxdesign/labswitch to@astryxdesign/core/Drawer.
New Features
- An integration component doc can name a differently named export of the file beside it: when
Slides.tsxexportsAcmeCarouseland nothing namedSlides,Slides.doc.mjscan setname: 'AcmeCarousel', and a kebab-caseacme-widget.doc.mjscan nameAcmeWidget.component --list,component <Name>,search,swizzle, thedoctor integrationchecks andintegration verifyknow the component by that name, and its file name still opens it. A name that Core or another doc's file already has stays theirs on every surface unless--packagenames the integration. Docs and sources are read without running them; a doc named after its file, or beside a file that exports its own name, reads exactly as before. - Each full entry an integration's family doc lists in
components, such asAcmeSlidein anAcmeCarouseldoc, is a component under its own name when the module the doc'simportnames exports it. Its source is the.tsxfile in the family's folder that declares it; a member that only built output or a file outside that folder declares has no source to show or copy.component --list,component <Name>,search,swizzle, thedoctor integrationchecks,integration verifyandintegration addknow these members. A member's detail is scoped to its own entry, as a Core sub-component's is, and it never carries the family'sreplaces. A member named like a Core component or another doc's file opens with--package. - The CLI installed for the computer keeps one short Astryx skill for every agent on the computer:
~/.agents/skills/astryx/SKILL.md, which most coding agents read, linked into the skill folder of each agent that reads only its own (~/.claude/skillsalways; Kiro, Windsurf, Letta, Xcode's coding assistant, and~/.config/agents/skillswhen that folder exists) with a folder link and a relative target, a junction on Windows, or a copy where no link can be made. Continue, whose scanner skips links, gets a managed copy. The text tells agents that Astryx is on the computer, when it is relevant (building or changing UI), to start withastryx search, and to read docs withastryx docs; it names no version and only commands every release keeps. It is written on the global copy's first run and after each upgrade, in the background; package install scripts never write it.astryx init --userwrites it now, in any folder, andastryx init --user --remove-agentsremoves the file, every link Astryx made, and the copy, and turns it off. The setting and the links Astryx made are kept inastryx/settings.jsonin the per-user configuration folder. The file records a hash of its text, so a file a person edited is never overwritten or removed, and nothing Astryx did not create at a link folder is replaced.init --userwarns, while still writing, when noastryxcommand on the computer runs the Astryx CLI, and itsinit.userreceipt lists each path and what happened to it. Outside a project,astryx doctoradds acomputer-agent-textcheck (info only) that says whether the text is present, current, edited, or turned off, where it is linked, and any link folder it skipped or whose skill folder is missing. A cache or configuration folder set throughXDG_CACHE_HOME,XDG_CONFIG_HOME,LOCALAPPDATA, orAPPDATAis used only when it is an absolute path. - Integrations installed for the computer. An integration package installed in the same place as the CLI installed for the computer (
npm i -g,pnpm add -g,yarn global add, orbun add -gbeside@astryxdesign/cli), or installed with the CLI in one package set by a tool that runs it, is a computer-level integration. Outside a project, it loads the way a project's integrations do: its components, templates, docs, themes, discover source, andcliCommandapply, with the same validation, and one whose@astryxdesign/coreor@astryxdesign/clipeer range excludes the CLI's release is skipped. pnpm 11 and later, which give each global package a folder of its own, count every one of those folders. Inside a project, only the project's own integrations load: a computer-level one adds nothing there, andastryx discoverlists it undermeta.availablewith sourceinstalled for this computerand the project's install command ininstall, when its peer range admits the project's release and it loads. A project that installs the same integration uses only its own copy.astryx doctoradds acomputer-integrationscheck: outside a project, each one it uses, each the folder replaces with its own copy, and a warning for each it skips or cannot load; inside one, the ones the project could add. astryx gap-report --to <package>sends a report to the issues URL of the loaded integration the person chose, under the same--confirm-publicrule, instead of the default handlers. When loaded integrations name their own issues URLs,--list-categoriesand the receipt list every destination and tell the agent to ask the person where to file. The default route is unchanged.- Install the CLI once for your computer (
npm i -g @astryxdesign/cli) and runastryxin any folder. In a project, the project's own CLI answers, whatever its version, as before: a copy started anywhere else (the global install,npx, a typed version) hands the run to it. A project with no CLI of its own (only@astryxdesign/core, or a fresh clone) is answered by the copy you started, as before; when that copy is not the Core's release, one hint after the command, at most once a day per project, names the command that adds the CLI at Core's version, and JSON reportsmeta.answeredBy.copy: "starting". Only a project whose own CLI cannot start is answered by the CLI release equal to its Core, installed once into a per-user cache (from the installed Core, else the lockfile, else the declared range).astryx doctorwarns when a project's CLI and Core are different releases, or when a project has no CLI and the copy that answered differs from its Core, and prints the command that aligns them.astryx --helpand the manifest's newglobalModefield point toastryx docs global. The hand-off keeps the arguments, folder, standard streams, and exit status. Outside a project, the copy installed for your computer answers with its own release; commands that read Core use the Core of that release there: the global copy downloads it into the cache in a background step it starts as a run ends (never in CI, and not on Windows, where a background process would hold the caller's pipes and the first component command downloads it instead), so component reads work offline after one online run. Nothing that worked before breaks: when that release cannot be obtained (offline, a registry without it, an unwritable cache), the copy you started answers, as before global mode, with one warning line on standard error (astryx: could not get Astryx <version> to match this project's Core (<reason>); answering with CLI <version> instead) andmeta.answeredBy.copy: "fallback"in JSON. A copy counts as installed for the computer only in npm's global folder or in a global folder a package manager's own settings name (Bun'sBUN_INSTALLorglobalDir, Yarn'sglobal-folder, pnpm'sPNPM_HOMEorglobal-dir, or their defaults), never by a folder's layout alone, so an app made withyarn addis never mistaken for one; a moved Bun or Yarn global folder counts, and its notice reinstalls there. A failed install is remembered in the cache, so offline runs do not start npm again each time: it is retried after 2 minutes, then after 10 once it fails again, and a success forgets it. A stale install lock ends the process it records only when that process is exactly this CLI's install of that release (npm, or node running npm-cli.js, installing@astryxdesign/cli@<version>, started after the lock); otherwise the lock is simply taken over. The newERR_VERSIONS_UNAVAILABLEis kept for runs nothing can answer, such as a command that needs Core outside a project that cannot install it. The CLI starts npm from npm's own entry file with the running Node, never through a shell, and reads a project's declared Core range only when it is a plain version range. Every successful--jsonresult now carriesmeta.answeredBy(cli,core,copy:project,starting,matched,carried, orfallback), typed inCLIResponseand described in the output envelope docs. In text mode, a run answered by anything other than the project's own CLI prints oneastryx: answered by …line on standard error. Printed commands start with a name that reaches the same release: the project's runner when its own CLI answers,astryxoutside a project for the copy installed for the computer, and otherwise the CLI package pinned to the answering version (npx @astryxdesign/cli@0.7.2). The newERR_PROJECT_REQUIREDcode names a command that needs a project. Seeastryx docs global/install-once. astryx doctor integrationandastryx integration checkcatch more doc mistakes, and stop flagging one pattern Core itself uses.- An integration can set the command its users run the CLI with: a new
cliCommandfield inastryx.integration.*, such ascliCommand: 'acme astryx'. In a project that loads that integration, every command the CLI prints starts with it instead of the package-manager prefix (npx astryx,pnpm exec astryx): next-step hints, errors, suggestions, Doctor fixes,--help, the setup reminder, the agent-docs block, and doc text. If two loaded integrations set different commands, neither is used, and the newcli-commandcheck inastryx doctorwarns. An invalidcliCommandis ignored with aninvalid_cli_commandwarning; the rest of the manifest still loads. Docs, including an integration's, are now written with bareastryx ...commands, andastryx docsprefixes them for the project when it prints them. JSON output keeps every command bare, as before. The install-time setup reminder from@astryxdesign/coreand@astryxdesign/clinames the command the project's package manager runs, instead of alwaysnpx @astryxdesign/cli. - The integration manifest accepts an optional
docsiteUrl, a link to the integration's docs site, as a known field, so setting it no longer raises an unknown-key warning. - Update notices, the way
ghand the Vercel CLI do them. Once a day, never in the first day after its first run, the CLI installed for the computer checks the registry'slatestrelease in the background without delaying the command; it never installs a release by itself. When a newer release exists, a command that finishes successfully prints two lines on standard error, at most once a day:A new release of Astryx is available: <current> → <newest>andTo upgrade, run: <command>, with the command of the package manager that installed the CLI (npm i -g,pnpm add -g,yarn global add,bun add -g, orvolta install), after the Node the release needs when the computer runs an older one. Inside a project the notice names the project's install andupgradecommands instead, and anastryxfirst on the search path from before the hand-off gets a notice naming its upgrade. No notice prints with--json, after a failed command, or whenCIorNO_UPDATE_NOTIFIERis set, and neither variable lets the check run; unlikegh, a notice prints when standard error is not a terminal, because agents run the CLI without one. What the check found lives inastryx/state.jsonin the per-user configuration folder.astryx doctorreports the same: thenewest-releasecheck names the upgrade commands, and a newcli-on-pathcheck lists everyastryxcommand on the search path. - A
{@link <target>}in a component doc's text now reads as the command that opens its doc, inastryx component <Name>, its--propsview, and component lists, in text and JSON: the description, usage, best practices, anatomy and accessibility notes, and each prop's and example's description. A topic's description reads the same way inastryx docs, its list, and the docs tree. Code fields and code ticks show the link as written. A Core component's links resolve against the CLI's docs; an integration's against its own.astryx doctor integration componentswarns on a link in an integration's component docs that names no doc, anddoctor integration docsdoes the same for a topic's description. The written-pointer warning also reads component docs and topic descriptions, and each finding now names itskindandfield. - Component prop docs accept
stability: 'experimental', the machine-readable marker for a prop outside the stable compatibility promise, such as a component'sexperimentalprop object. doctor integration docs(and sointegration check) lists each pair of topics that repeat 10 or more words of prose word for word: two of the package's own topics, or one of them and a Core topic other than the one it replaces. Each entry names the topic that keeps the text (a Core topic, or of two package topics the one the passage fits), the line to change in the other, and the exact link to put there, and is in the newcopiedPassagesfield. A run with fewer than 4 distinct content words (words other than function words such as "the", "in" or "it"), or one that three or more topics share, is not listed. Each pair is also acopied_passagewarning, sointegration check --strict(new in this release) fails until it is fixed;doctor integration docsstill exits 0. The CLI's own guides no longer repeat 18 passages that another guide owns; each copy is now a link to the guide that owns the fact.astryx discoverlists the official Astryx packages, first, from a list each CLI release carries, so a project with no discover source sees the official themes, even offline. Each entry inmeta.availablecarries the command that adds it (install), so a project that loads no integration and has no discover source of its own, where every query still answers with the list, can add a package straight from it. An official entry'slatestis the newest release the CLI knows (its own version on a release CLI, or a newer Core release the project has), and itsversionsalso list the project's Core version, so both can be looked up. Its add command pins the project's Core version (installed, or declared exactly), else the Core range the project declares (quoted), else the latest release; on a canary CLI with no Core it pins none for packages released with Core, and canary-only packages are listed only beside a canary Core or no Core. Official entries nameAstryxas theirsource, andmeta.sourcesreports the list last. A project's or an integration's source keeps its entry for an official package, and for any package of the same integration. A theme package that the project's own package.json declares as a dependency, under an npm alias too, shows as installed from any folder of the project, and a theme's add text ends withastryx theme add <slug>. A version or item that the official list does not show still answersERR_UNKNOWN_PACKAGE, as before.doctor integration docs(and sointegration check) lists fluff in a package's prose, in the newflufffield: each padding phrase such as "in order to", "note that", or "it is worth noting", with its file line and what to write instead, and each topic of 80 or more prose words in which fewer than half the words carry content. Each is also adoc_fluffwarning, sointegration check --strict(new in this release) fails until it is cut;doctor integration docsstill exits 0. The phrase list and the floor are in the check-your-docs guide (astryx docs cli/integrations/building-blocks/docs/check-your-docs). Core'sbrowser-supportguide loses its one padding phrase, and three of Core's guides (debug-and-gap-reports,sections-and-placement,publishing) are tightened to meet the density floor.astryx doctor integration validatenow checks every doc an integration ships under its roots (components, templates, docs topics, themes, and their translations, served or not) against the published authoring type for its kind, with the project's own TypeScript, the waytscwould. Each unknown field, missing required field, or value outside its field's type is a warning that names the doc, the line, the field, and a fix; the exit code is unchanged. A doc it cannot fully check, or a themes root that does not load, is listed with the reason; test fixtures under__tests__in the components or docs root are counted, not checked. JSON addsdata.docTypes. Without TypeScript the check prints one[skip]line instead of passing silently; with a TypeScript it cannot read types with (one with no JavaScript compiler API, such as TypeScript 7), that line names the installed version. With no doc files, it says there is nothing to check.astryx doctor integration componentscompares each component doc's props with the component's TypeScript props, read with the project's owntypescript. It warns about a documented prop the code does not have, a prop the package declares that the doc leaves out, and a wrongrequired. Without TypeScript it prints one line saying the comparison was skipped; with a TypeScript it cannot read types with (one with no JavaScript compiler API, such as TypeScript 7), that line names the installed version. The findings are warnings, so the exit code does not change; the JSON response gainsdata.propDrift, and nothing else in it changes.astryx doctor integration componentsalso judges each documented prop's type against the code, for props the package declares, a documented field such asstatus.typeand a name the package's own index signature takes included, and warns when they differ (type_mismatch). A type is judged only where both sides read exactly, with the project's owntypescript: the same text once whitespace, quotes and union order are set aside, or primitives, literals, arrays and unions of those, and names for them. Every other type (a callback, an object, a generic with arguments, an intersection,keyof, a type that does not resolve, a name two index signatures take) is listed as not compared, never reported. The comparison needs TypeScript 4.8 or later: with an older one, no type is judged and the text says so in one[skip]line. JSON addstypesCompared,typesNotComparedand, when the types were not judged,typesSkippedtopropDrift. The findings are warnings, so the exit code does not change.- New
astryx integration check, the CI check for an integration package's own build. It takes no package argument and checks the integration package in the current folder. It runs the fourdoctor integrationchecks (validate,components,templates,docs), prints each result, then a summary, and exits 1 when any of them would.--strictalso exits 1 on any warning and on any check that did not run, such as a package with noastryx.integration.*: add"typecheck": "tsc --noEmit && astryx integration check --strict"to package.json so every build keeps the package's docs in sync. Its exit codes and JSON are a contract for the builds that run it: from this first release on, a new check, or a new failure code, joins only in a minor release named in the release notes. JSON: a newintegration.checkenvelope carries each check's own envelope unchanged. Its docs say to run it in CI, soastryx search cifinds it. Thedoctor integrationsubcommands keep their exit codes; their JSON gains only additions. - Three new published types describe an integration package's templates:
IntegrationPageTemplateDocandIntegrationBlockTemplateDoc, each with every field of itsTemplateDocmember butcategoryas the package's own string instead of aTemplateCategoryvalue, and their union,IntegrationTemplateDoc.@astryxdesign/cli/authoringexportsIntegrationTemplateDoc;@astryxdesign/cli/docand@astryxdesign/cli/templateexport all three.TemplateDocis unchanged. astryx upgraderenames a staticedgeCompensation="inline"onListtoedge="outset", and dropsedgeCompensationbeside anedgethat is a fixed string. It keepsedgeCompensationwith aTODO(astryx upgrade)comment where it can't prove the result: whereedgeis computed (it may be undefined, and thenedgeCompensationstill applies), on a dynamicedgeCompensationvalue, and where theListalso spreads props, which may setedge. The deprecated prop keeps working there.astryx doctor integration docslists each code span in an integration's prose that is exactlyastryx docs <name>for a doc that exists, and says which{@link}to write instead:{@link generic:<name>}for the package's own topic,{@link @astryxdesign/cli:generic:<name>}for Core's. The link prints the command that opens the doc, and doctor's link check fails it if the doc goes away. A command with more words, a route, or a code block is not listed. Each is astray_doc_pointerwarning, soastryx integration check --strictfails on it, and is in the newstrayPointersfield;doctor integration docskeeps exit 0. Core's own guides point with links, and a test keeps them that way.astryx doctor integration validateandastryx integration checknow warnsource_without_template_docwhen a.tsxdirectly in an integration's templates root has no same-stem template doc, soastryx templatewould never list it. The warning names the file and the doc to add. Files in subfolders, such as helpers a template imports, and test, spec or story files such asstray.test.tsxare not checked; a dotted template id such aslanding.page.tsxis, andintegration check --strictfails on the warning.- The doc-type and prop checks in
integration checkanddoctor integration validate|componentsread types with@typescript/typescript6, the TypeScript 6 API package TypeScript publishes for tools, when the project installs it and its owntypescriptis missing or has no JavaScript compiler API, as TypeScript 7 does. When no usable TypeScript is found, the skip reason now ends with the remedy: add@typescript/typescript6on TypeScript 7, or install TypeScript 5.0 through 6 (npm install -D typescript@6).
Fixes
extractComponentsreported phantom components from locally-declared helper functions in template files — e.g. "Timeline", derived from afunction TimelineSection() {...}helper declared directly in the detail-page template, which isn't a real component. It now excludes any name bound by a top-levelfunction,class,const,letorvardeclaration in the same file (read from the parsed source, so comments, strings and type annotations don't count), before suffix-stripping runs, so a locally-declared helper is never mistaken for an imported component. A component whose whole name is a stripped suffix, such as a bareSection, now stays in the list instead of emptying out.- Global and project copies of the CLI meet more predictably. A repository that builds the CLI itself, with
packages/clibesidepackages/core, answers with that CLI instead of failing withERR_VERSIONS_UNAVAILABLE. On a cache folder shared between computers, a release install renews its lock every 10 seconds, and a lock from another computer that goes a minute without renewal is taken over, instead of blocking runs for 20 minutes. Folder names are compared without letter case on macOS and Windows, a Yarn 1 global install on Windows is recognized as a global install, and the shims npm, pnpm (including pnpm 12's), and PowerShell write are read when doctor and the reminders look for theastryxcommands on the search path. - The setup reminder, the swizzle StyleX note, and one doctor line say only what is true
- A CLI installed with npm under a prefix of its own (
npm i -g --prefix ~/.local,NPM_CONFIG_PREFIX, orprefix=in an.npmrc) is now upgraded into that same prefix: the update notice andastryx doctorprintnpm i -g --prefix <prefix> @astryxdesign/cli@latest, with~for the home folder. npm's default prefixes (Node's own,/usr/local,/usr, and%APPDATA%\npmon Windows) keep the plain command. - The CLI now uses
postcss-selector-parser7.1.6, which parses flat selectors in linear time and closes a CPU-exhaustion vulnerability (#6985). integration verifyreads a package's exports with the same reader discovery uses, so the two agree: a component re-exported through a folder's index file passes, and a type-only re-export no longer counts as the component.astryx component --listandastryx searchfind VStack, HStack and Heading Each has its own import path, but its doc lives in its family's folder: Stack's doc documents HStack and VStack, and Heading's doc sits next to Text's. The list only counted a doc in the component's own folder, so the three were missing from the list and from search, andastryx component VStackfound its doc only through fuzzy matching. A component whose doc is elsewhere is now listed and searchable with its own import path, andastryx component VStackopens its doc directly.- A doc link to a component, page, or block (
{@link component:AcmeButton},{@link @astryxdesign/core:component:Button},{@link block:acme-card}) now resolves, and reads as the command that opens it:astryx component <Name>orastryx template <id> --type <page|block>, with--packagefor anything not from Core. Before, every such link printed as written, andastryx doctoranddoctor integration docswarned that it named no doc, for Core's components as for a package's own. A link that names no component or template still warns, and its hint now searches components or templates instead of topics. A resolved link'srouteis null for these kinds, which noastryx docsroute opens. astryx doctorno longer fails "Theme owners and built imports", andastryx componentno longer stops with "Could not load the recorded theme", when an added theme's built module imports a stylesheet, as inimport './ocean.css'. Node cannot load a stylesheet, so the CLI checks that each imported.cssfile exists, then treats it as empty. It looks for each stylesheet from the theme module's folder, also when a module that the theme imports from another folder names it. Doctor still fails when an imported stylesheet is missing, and when the module has any other problem, such as a missing dependency, a syntax error, or an error thrown while it loads.astryx searchfinds more of what a reader means when the words differ from the catalog's.astryx searchkeeps a guide first when the query is a phrase of two or more words that the guide declares as a keyword.font sizeandfont weightnow open the font setup guide before the Text component, anddark modeopens the theme guides before the theme hooks. A component whose name is the whole query still comes first, one-word queries are unchanged, and the code terms and table cells in a reference doc don't count as its keywords.astryx searchranks a match on more of your words above a shorter named entry.astryx integration check --strictprints each finding once. The checks' own output shows its message and fix, and the closing "Failing under --strict" list names each failure by check, code and place only, so a long report is no longer doubled.- The
table-filterpage template's phone-width view-options panel is now labelled by its selected tab (aria-labelledby) instead of a fixedaria-label, so screen readers get the panel's name from the tab that controls it and the tab–panel relationship resolves in both directions. astryx theme build --checkandthemeBuild({check: true})keep comparing outputs outside the working directory, as the latest release does, rather than refusing them withERR_PATH_TRAVERSALthe way a build does. Check mode writes nothing, so the write confinement ofarchitecture:cli-surface/INV10andINV10adoes not apply to it: an absolute--outpath outside the working directory, a theme file outside it whose outputs sit beside it, and--familywith its root theme file outside it are each checked read-only. A relative--outpath that escapes the working directory is still refused, as before. Builds keep refusing every one of these writes, so when such outputs are stale, the report no longer ends with aRebuild with:command the build refuses. It names the nearest directory that contains the theme files and the outputs, and the build and check commands to run from there: each output'sSource:header records the directory its build ran from, so the check passes only from that same directory. Stale outputs inside the working directory keep theRebuild with:line.astryx theme buildandthemeBuild()now write only inside the working directory (cwdfor the API), asarchitecture:cli-surface/INV10requires; underarchitecture:cli-surface/INV10athe refusal is a compatible fix. Each of these builds now fails withERR_PATH_TRAVERSALbefore anything is written: an absolute--outpath outside the working directory, a theme file outside it whose outputs would go beside it, and--familywith its root theme file outside it. Paths inside the working directory still build, including through a symlink. To migrate, run the build from a folder that holds the theme file and its outputs, or pass an--outpath inside that folder; API callers pass acwdthat holds them.astryx upgradeno longer reports your code as up to date when the CLI is older than the installed@astryxdesign/core. Core codemods ship inside the CLI, so an older CLI has none for the releases after its own version. It used to print "No changes needed" and "No codemods available for this version range" and exit 0 while the code still needed those releases' migrations. It now warns once that it cannot finish, prints the same upgrade pinned to the CLI release that matches your Core (such ascd <project> && npx @astryxdesign/cli@<core-version> upgrade --from <old-version> --path <source-dir> --apply), and ends with "Upgrade incomplete". That command changes to the folder the run used and names the directory it scanned as an absolute path, both with symbolic links resolved, so it upgrades the same code wherever you paste it. It is written for a POSIX shell, or for PowerShell on Windows.upgrade.status(no_codemodsandconfig_fixable) andupgrade.rungain an optionalcliBehindCorefield withcliVersionandcommand, present only in that case. The codemods the CLI has still run, and the exit status and every existing field are unchanged.astryx integration verifyaccepts a theme module that loads the theme's own styles. Such a module imports the theme's exported stylesheet and font stylesheet for their side effects, and re-exports from the moduleastryx theme buildwrites either everything or only its theme, under the theme's export name. Verify also finds that built module by the nametheme buildgives it, the theme's own name, so a theme whose name differs from its slug no longer fails to rebuild. Any other difference from the built module still fails withtheme_module_stale, and for a module that re-exports the theme, the message now says what is wrong.
Performance
- The CLI loads Core's runtime (
@astryxdesign/coreand@astryxdesign/core/theme) only when it builds or checks a theme (theme build, and thedoctorandintegration packtheme checks), not on every start. In a project with Core installed, every other command, and an import of@astryxdesign/cli/api, skips loading Core's components and React:astryx --versiondrops from about 1.3 s to 0.5 s. Output is unchanged.
Documentation
- Docs and CLI examples import each Core export from the path
astryx component <Name>prints. - Global mode docs:
astryx docs globalis a top-level docs section (and one docsite page, under Guide, which Getting Started introduces and links) explaining what global mode is, the one install command, what you get, and which version runs where. Its pages, each answering one question: project, global, or both (both is recommended;global/project-global-or-both), install (global/install-once, with what to do aboutEACCES), which version runs and why (global/who-answers), updates and notices (global/updates), the agent guide on your computer (global/computer-agent-guide), integrations installed globally (global/computer-integrations), monorepos and nested folders (global/monorepos), CI and containers (global/ci-and-containers), troubleshooting every line global mode prints (global/problems), uninstall and reset (global/uninstall), and a reference of paths, environment variables, JSON fields, and error codes (global/reference).astryx docs globaland its pages are answered by the copy you start, even inside a project whose version predates them. Integration authors get a checklist with the commands to try a package globally (cli/integrations/global-integrations). Every command that does something else outside a project says exactly what in its "In global mode" note, checked against the command run in an empty folder, and every terminal line the global-mode pages show is checked against the CLI's own strings. A project's update notice now installs the CLI beside Core, so a project that installed only Core gets its own CLI too. - The integration guides make
integration check --stricta required step in every integration's build: the quick start installstypescript@6(the checks need its JavaScript compiler API, which TypeScript 7 does not ship) and adds "Check it in every build (required)", the Build an integration overview says so, and the checks guide's section reads "Run every check in every build (required)". - The
astryx docs cli/integrationsguides andastryx docs authoringnow match the current CLI, and the guides point to the matchingastryx docs authoring <section>for every field instead of repeating its tables. - Fix the MCP setup snippet in working-with-ai — "type": "url" is not a transport type, and Claude Desktop adds remote servers through Connectors
Other Changes
VStackandHStackcome from@astryxdesign/core/VStackand@astryxdesign/core/HStack,Headingfrom@astryxdesign/core/Heading,Textfrom@astryxdesign/core/Text, andThemeanddefineThemefrom@astryxdesign/core/theme.- This covers the guides, the
Carddocs, the next stepsastryx initprints, the install exampleastryx theme buildprints, the wiring exampletheme addprints, the build rules, the theme-module fixastryx doctorprints, and the annotated theme template. - Every path was already exported. Nothing else changes.
- A
docsZhordocsDenseoverlay may setnameanddisplayName, as Core's own docs do; both are ignored when the doc renders, so--strictno longer fails on them. doctor integration componentsreports a documenteddefaultthat differs from the literal default the component writes in its props destructuring (size = 'md') asdefault_mismatch. Quotes and spacing are ignored; where either side's default is not a literal, the prop is listed as not compared.doctor integration validatewarns, each with a fix, on a prop documented twice (duplicate_prop), apropDescriptionskey that matches no prop entry's name as written (unknown_translated_prop), a section with no content (empty_section), two sections of one topic with the same key (duplicate_section_key, whose fix names the key the second one is already served at), and a.doc.zh.mjsor.doc.dense.mjsoverlay beside no topic file (orphan_doc_overlay).- A topic that takes the route of one of Astryx's own docs is named by its topic name, not an internal id, with the rename to make. A link written as a bare name (
{@link deploying}) gives the exact link to write, or says no topic has that name. - When a doc is missing several required fields, each finding's message names only its own field.
doctor integration validateprints each issue's fix and file in text output, as JSON already carries them.- The "run init to finish setup" reminder no longer prints where agents already have the Astryx prompt. In a git repository it looks for init's block in the agent docs from the project up to the repository root, because coding agents read every agent doc in between, so a package in a monorepo that ran
initat its root stays quiet. This holds for every command and for the reminder printed when@astryxdesign/coreor@astryxdesign/cliis installed. Running the CLI from its own source checkout, inside that checkout, prints no reminder. A project with no block in reach still gets it, and--jsonnever prints it. astryx swizzleno longer says StyleX components "render unstyled (no error)" without a StyleX compiler. Importing them throws StyleX's "Unexpected 'stylex.create' call at runtime" error and the page does not render, and the note now says so.- In an integration package, where the package's own manifest loads,
astryx doctor's implicit-integrations line no longer says that "every loaded integration is named in astryx.config". It names the package's own manifest: as the only loaded integration, or beside the integrations astryx.config names.Classification: contract-restoring. Only message text changes: JSON keys, check ids, statuses, and exit codes are unchanged. The doctor line's new text also appears in its--jsonmessage. - Internal groundwork for
astryx doctor integration components: a comparison of the props a component doc documents with the props its TypeScript source declares, read with the project's owntypescript. Nothing reaches it yet, so the CLI's behavior and output do not change; the command starts running it in a later change, which describes what users see. - Internal groundwork for
astryx doctor integration components: reading two written TypeScript types as one type when they differ only in how they are written (whitespace, comments, quotes, member order,Array<T>forT[], parameter names,React.qualifiers), and judging a documented prop type against the type the code declares where both read exactly. Nothing reaches either yet, so the CLI's behavior and output do not change. - Internal groundwork for
astryx doctor integration components: finding the project's owntypescript, and reading a package's TypeScript project the waytscreads it (its owntsconfig.jsonor a monorepo root's, a solution-style config's references, and the declaration files the config includes), and finding the references in that project the compiler cannot resolve. Nothing reaches it yet, so the CLI's behavior and output do not change. - Old-CLI notes name the published releases that behave that way: template
replaces, links, docs sections, sectionids and typed theme descriptors work from 0.6.4, and templatekeywordsfrom 0.6.6.integration verifystill names the CLI range to declare. - The quick start makes the package an ES module, so a theme it builds can be imported.
- Samples and output that had drifted are fixed, among them the subcomponent imports, a theme that extends another, and the upgrade output.
- The Authoring Reference corrects how an invalid
astryx.configis handled, theissuesUrlformat, where codemod files go, and which fields nothing reads yet. Its examples use theexport default {type: ...}form thatintegration addwrites. astryx docs cli/integrationslinks to the Authoring Reference, and the reference links back to the guides.astryx docs styling-overviewandtokens-and-setupgive the real symptom of a missing StyleX compiler: importing a swizzled component throws an error that startsUnexpected 'stylex.create' call at runtime.- Adjacent query words that join into a component, hook, or template name, or into a one-word keyword, match it:
table header cell with sort arrowfindsTableHeaderCell,tree view foldersthetreeviewkeyword, and a hook answers to its words withoutuse. Most of a name, a name's leading words, or a run of its words also count for components and hooks, a step below the full name. - A query that is one camelCase identifier and matches nothing as typed is read as the words it spells, so an unknown API name such as
useTablePaginationStatereachesuseTablePagination. In a query of several words each identifier stays one term. - When the whole query is an entry's name, these readings add no near siblings beside it. A match on a joined keyword never ranks above an entry the query names, and a match on part of another name does only when it spans more query words than that entry's name.
- A gerund matches its verb (
spacingandspace,dragginganddrag), and a plural can start a longer word through its singular (tokensandTokenizer). - Core component docs declare more keywords: other libraries' names (
scrollarea,togglegroup,pageheader,splitpane,circularprogress,linearprogress,commandmenu,relativetime,sidesheet,descriptionlist,inlinecode) and common glyph names onIcon, since any icon library's glyph renders through it. - The JSON shape is unchanged.
- A match on part of a longer name that reads more of the query than the entry the query names is no longer held below it:
dropdown menu radio optionsleads withDropdownMenuRadioItem, notDropdownMenu. useResizabledrops thesplitviewkeyword, which put it ahead of the side-panels guide.
Contributors
Thanks to everyone who contributed to this release:
0.7.1
Fixes
CommandPaletteInputnow exposes the semantics and name that its visible state promises. (#7321)- A standalone field with no popup attributes was
role="combobox"witharia-expanded="true"andaria-autocomplete="list"; it is nowrole="searchbox"with no popup state. Passrole="combobox", or your popup's own ARIA attributes, to keep the old semantics. A field that already passes popup attributes (aria-expanded,aria-controls,aria-owns,aria-haspopup, and the like) stays acomboboxand keeps them, and a field insideCommandPaletteis unchanged. - The field's default accessible name was its placeholder (
Search…, or the caller'splaceholder); it is nowSearch commands, translated. Passlabelto keep a specific name, for examplelabel="Search…"for the old default. A caller whose customplaceholderserved as the name keeps working code and hears the generic name until it passeslabel. - The CLI's async-search CommandPalette block names its field
Search files. endContent={true}no longer renders an empty trailing slot, andendContent={0}renders inside the trailing slot instead of after it.
- A standalone field with no popup attributes was
- Stone, Y2K, and Gothic set
CodeBlock's diff row slots in their own syntax palettes, so a reader of a diff on those themes gets added and removed rows whose code, line numbers, and+/-glyphs stay readable: every syntax token keeps at least 4.5:1 on the tinted rows in Stone (light and dark) and Y2K (light and dark), and in Gothic the rows take a deep green and a deep red at the background's own luminance, so every token keeps the contrast it has on the plain background. Line numbers and glyphs on changed rows use each theme's own green and red. The CLI's bundled copies of the three themes (astryx theme eject) carry the same palettes. (#7428) - A
secondarySelector, MultiSelector, or ComplexSelector now matches the theme's secondary Button: under butter, chocolate, gothic, stone, and y2k it takes that Button's border, fill, text color, and hover instead of the default borderless neutral fill, so a toolbar mixing secondary buttons and selectors reads as one set of controls. Disabled and read-only triggers keep a still fill on hover, as a disabled Button does, and a Selector or MultiSelector inside an InputGroup keeps the group's neutral fill and edges. The default theme is unchanged, the selector docs now saysecondaryfollows the theme's secondary Button, and themes added with the CLI get the same parity. (#7548) astryx theme build --watchstops as soon as it is interrupted (Ctrl-C or SIGTERM). A change saved while a rebuild was running no longer starts another rebuild after "Stopped watching.", and a rebuild in progress stops with the watcher instead of keeping the process alive. (#7508)
Performance
astryx searchandastryx build, and thesearchandbuildAPI functions, read each source directory once per call instead of once per candidate. Results are unchanged. A warmsearchdrops from about 1.9 s to 0.4 s on macOS. (#7421)
Documentation
- The generated token docs list the five diff row slots of the syntax vocabulary —
--color-syntax-added,--color-syntax-removed,--color-syntax-diff-header,--color-syntax-added-marker,--color-syntax-removed-marker— with their defaults, soastryx docs tokensdescribes nineteen syntax slots. (#7389) - The Tailwind and migration setup docs now say that
globals.css(or alayers.cssholding only the@layerline) must be the first import in the root layout or app entry, before theastryx-themesmodule or any component that imports theme CSS; otherwise Tailwind preflight overrides Astryx base styles and theme overrides lose. The Tailwind v3 coexistence snippet moves its@layerline into alayers.cssimported first, because Next.js (webpack or Turbopack) hoists CSS imports above an inline@layerline. (#7534) - Grid's
columnsdocs now lead with the shape that reflows: a numericcolumnsis exactly N columns at every width and never reflows, andcolumns={{minWidth, max}}is the form for columns that must survive a phone. Theastryx docs layout/responsivetopic gains a "Columns that reflow" section with a reflowing stat row beside a fixed week row. No behavior changes. (#7340) - The styling setup docs now load the prebuilt stylesheets on every path. The "StyleX from source" path becomes "StyleX for your own code": it keeps
astryx.cssand points the StyleX compiler at your own and swizzled source only. A new "Other Astryx packages" section lists each package's stylesheet (richtext.css,lab.css,charts.css) and where to import it. Getting started no longer lists the two example setups that compile Astryx source; the remaining examples all loadastryx.css. (#7587)
Contributors
Thanks to everyone who contributed to this release:
0.7.0
Breaking Changes
theme addnow imports built themes; usetheme ejectto copy theme source. (#7138) The old contract copied theme source withtheme add <slug> [path] [--overwrite] [--package <package>]and returnedtheme.addJSON. TheThemeAddResponsetype and thetheme.addresponse type are removed, with theirThemeAddResponse.type,ThemeAddResponse.data, andThemeAddResponse.metafields. The replacement imports the built theme withtheme add <slug> [--package <package>]and returnstheme.app;--importremains an accepted no-op. Plaintheme addnow returnstheme.appwith the ownerpackagedirectly aftertype. Local themes carry no package.A path aftertheme addnow exits 1 withERR_INVALID_ARGUMENT, and--overwriteexits 1 withERR_INVALID_OPTION; neither writes files. To migrate a script that copied source, runtheme ejectwith the same slug, path,--overwrite, and--packagearguments. A script that already runstheme add --importkeeps the same meaning and needs no change.init --remove-agentssays when there was nothing to remove. (#6623) Migration: a consumer readingdata.removedas a boolean keeps working; a consumer that narrowed on the literaltruemust accept the corrected value.- Four commands refuse silently ignored option pairs. (#7132) Migration: remove the option the command was ignoring.
- Refuse invalid input that used to silently succeed. (#7149)
Migration: pass a valid type or package, an integer limit, or the documented arguments, and catch
ERR_AMBIGUOUS_COMPONENTfor a multi-package name. - An empty-string argument no longer discards the rest of the command. (#6620) Migration: remove the empty string from the invocation; omit the argument to list.
doctor integration validateexits 1 when there is no package.json. (#7150) A missing package.json now produces ano_packageerror, so the existing error-severity exit rule applies. A directory with package.json but no integration manifest still exits 0.Migration: run the command in a directory that has apackage.json, or handle exit 1 for that case.- Move canonical data-color defaults from generated theme CSS to the public StyleX
dataVarsgroup. (#6834) ImportdataVarsfrom@astryxdesign/core/theme/dataTokens.stylexfor CSS-capable code. Canvas and other non-CSS APIs continue to useresolveThemeToken()oruseTheme().token(). Rebuild committed theme CSS withastryx theme build; concrete themes now emit only explicitly authored data-color overrides.Old usage: Generated theme CSS owned the canonical--color-data-*root defaults.Replacement: The public StyleXdataVarsgroup in@astryxdesign/core/theme/dataTokens.stylexowns the defaults; concrete themes emit only explicitly authored data-color overrides.Migration: ImportdataVarsfrom@astryxdesign/core/theme/dataTokens.stylexfor CSS-capable code. Canvas and other non-CSS APIs continue to useresolveThemeToken()oruseTheme().token(). Rebuild committed theme CSS withastryx theme build.Codemod:astryx upgraderunsvalidate-data-token-ownership, which rewrites nothing and reports fallback-lessvar(--color-data-*)uses (whole or embedded source strings, and stylesheets) and stale generated theme CSS for manual migration. - Doctor fails when the CLI cannot load what astryx.config asks for (#7130) A new
configured-integrationscheck fails when an integration named in astryx.config cannot be loaded: not installed, installed without a manifest, or a manifest that throws or fails its schema. Such an integration is withdrawn whole and contributes nothing. The config check fails, instead of warning, when astryx.config imports but the CLI cannot load the project from it.Unchanged: a problem inside one contribution kind (an invalid component doc, a missing or unreadable root, or an unresolved replacement) stays a warning underintegration-issues, and an autolinked dependency that cannot be loaded stays informational.No codemod applies: nothing in a project's source changes; install the integration, repair its manifest, or editintegrationsin astryx.config.What counts as configured is every name astryx.config lists, including a package set aside for a provider conflict and the package being authored when its own config names it. Migration: install the integration, fix its manifest, or remove it fromintegrations; fix the astryx.config field the message names. - Typeahead, Tokenizer, CheckboxList, RadioList, and Slider no longer accept root
xstyle,className, orstyle. Style the field withcontainerXstyle/containerClassName/containerStyle(the Field box; no effect inside InputGroup or ahorizontal-labelsFormLayout) and the visual control box withcontrolXstyle/controlClassName/controlStyle. Base props now reach the primary semantic control: the combobox input for Typeahead and Tokenizer, therole="group"/role="radiogroup"element for CheckboxList and RadioList, and therole="slider"thumb for Slider (therole="group"control in range mode). A calleraria-describedbyis kept alongside the field's own description and status, on these components and on TextInput, TextArea, and NumberInput, which previously dropped it. CLI templates use the new props. (#7339) Migration: rename rootxstyle/className/styleto the part they styled before:containerXstyle/containerClassName/containerStyleon all five components, except a Typeahead inside InputGroup, whose root styling painted the control surface and moves tocontrolXstyle/controlClassName/controlStyle. The release'sastryx upgradecodemod,migrate-field-input-styling, performs these renames on JSX usage.Not rewritten by the codemod, so update by hand:refandid, plusdata-*(except Typeahead and Tokenizerdata-testid, which marked the control surface),aria-*, and DOM event handlers such asonClick, previously landed on the outer Field (or were dropped by RadioList and Slider). They now land on the primary semantic control. Update code that measured, queried, or listened on the outer field, and wrap the component in your own element when you need an outer boundary.- Typeahead and Tokenizer refs are now
HTMLInputElement. - A consumer
onKeyDownon Typeahead or Tokenizer still runs after the built-in key handling, cannot cancel it, and still fires for keys on the clear button and tokens; for keys on the input it now runs on the combobox input itself. - RadioList and Slider used to drop DOM event handlers; they now run after the component's own handling, so a Slider
onPointerDown,onKeyDown,onFocus, oronBlurthat never fired before now fires (on the thumb, or on the group in range mode). - Tokenizer's
onFocus/onBlurkeep their meaning: focus entering or leaving the field. - Styling passed through a wrapper's own props or a spread is not rewritten and now fails type-checking at that callsite.
Untyped callers get a development warning and the value is ignored.From #5656 by @harjothkhara. - Selector, MultiSelector, and ComplexSelector no longer accept root
xstyle,className, orstyle. Style the field withcontainerXstyle/containerClassName/containerStyle(the Field box; no effect inside InputGroup, ahorizontal-labelsFormLayout, or withrenderTrigger) and the visual control box withcontrolXstyle/controlClassName/controlStyle. Base props such asref,id,data-*(includingdata-testid),aria-*, and DOM handlers reach the trigger button that carries the combobox role (or, withrenderTrigger, the caller's control), and a calleraria-describedbyis kept alongside the field's own description and status instead of being replaced. Handlers keep their existing order: a ComplexSelectoronClickon its own trigger can still cancel opening, and newly forwarded handlers (including those reaching arenderTriggercontrol) run after the built-in toggle and keyboard handling. CLI templates use the new props. (#7341) Migration: rename rootxstyle/className/styleon these components tocontrolXstyle/controlClassName/controlStyle, which style the same element as before. Not a rename: adata-testidor other base prop now lands on the trigger button rather than the bordered box around it (query the box with.closest()if a test measured it), and withrenderTriggerbase props andrefnow reach the caller's control. Rename JSX usage by hand, or runastryx upgrade; it runsmigrate-field-input-styling, which does not follow styling passed through a wrapper's own props or a spread, which now fails type-checking at that callsite, so rename it there. Untyped callers get a development warning and the value is ignored.From #5656 by @harjothkhara. - TextInput, TextArea, NumberInput, and FileInput no longer accept root
xstyle,className, orstyle. Style the field withcontainerXstyle/containerClassName/containerStyle(the Field box; no effect inside InputGroup or ahorizontal-labelsFormLayout) and the visual control box withcontrolXstyle/controlClassName/controlStyle. Base props such asref,id,data-*,aria-*, and DOM handlers reach the native control, and a calleridis now honored there. CLI templates use the new props. (#7336) Migration: rename rootxstyle/className/styleon these components tocontrolXstyle/controlClassName/controlStyle, which style the same element as before.astryx upgraderewrites JSX usage; styling passed through a wrapper's own props or a spread is not rewritten and now fails type-checking at that callsite, so rename it there. Untyped callers get a development warning and the value is ignored. Not rewritten by the codemod: a calleridused to be replaced by a generated one and now reaches the native control (the label stays associated), so remove anidyou passed but relied on being ignored. Other base props already reached the native control and are unchanged.From #5656 by @harjothkhara. - matcha's and y2k's spacing steps are rem (
--spacing-2: 0.75rem), so their gaps and padding follow the reader's root font size like the core scale. Every step is the same pixel value at the default 16px root; a reader with a larger root font size now sees proportionally larger spacing on these themes. The CLI's copies of both theme templates and the annotated theme template's spacing example change the same way. (#7374) Migration: nothing to change to take the new behaviour. To keep fixed pixel spacing on one of these themes, extend it and override the steps in px, which is honoured as written:defineTheme({name: 'app', extends: matchaTheme, tokens: {'--spacing-2': '12px'}}). - On touch devices narrower than the
lgbreakpoint ((width < 1024px) and (pointer: coarse)), the 14px-base first-party themes now floor their type base to 16px and re-derive the ratio so Display 1 keeps its desktop size: neutral and chocolate (base 14, ratio 1.2 → 1.1736) and butter and stone (base 14, ratio 1.25 → 1.2225). On phones, body, label and code text rise from 14px to 16px; supporting text, the headings and Display 2 and 3 grow by 1–2px; only Display 1 holds its desktop size. Desktop sizes are unchanged. gothic, matcha and y2k already use a 16px base and need no rule. The CLI's theme templates carry the same rule, so a newly scaffolded theme gets it too. (#6699) An app theme that extends one of these four themes and sets its owntypography.scaleor type-size tokens inherits this rule, and on touch + narrow screens the rule replaces those values (a base-18 child drops to a 16px body and a 42px Display 1). Append your own rule for the same condition with the values you want; a later rule for the same condition wins.Migration: nothing to change to take the new phone scale. To keep the previous 14px phone scale in an app, extend the theme and append a later rule for the same condition:defineTheme({name: 'app', extends: neutralTheme, adaptations: {rules: [{when: {pointer: 'coarse', width: {below: 'lg'}}, value: {typography: {scale: {base: 14, ratio: 1.2}}}}]}}). For butter and stone useratio: 1.25and also settokens: {'--text-supporting-size': '12px'}in that rule's value, because those themes pin supporting text at 12px rather than the 11px the scale alone gives. This cannot be rewritten by a codemod: whether an app wants the floor is a product choice. - Stop reading the Astryx-owned agent variables ASTRYX_AGENT_ID, ASTRYX_AGENT_SESSION_ID, and ASTRYX_AGENT_METADATA (#7127) The theme-import change already stopped reading
ASTRYX_THEME; these three were the last Astryx-owned agent variables. A test now fails on anyprocess.env.ASTRYX_*read in the CLI source.Migration: setAGENTandAGENT_SESSION_ID, which the CLI already reads, instead of the Astryx-prefixed variants.ASTRYX_AGENT_METADATAhas no replacement variable. - Remove the deprecated component-theming compatibility surface scheduled for 0.7.0. Components now emit only canonical target classes and reflected
data-*prop/state selectors. Theme discovery and build output no longer expose deprecated targets, andThemePropsOptionsplusComponentThemingTarget.deprecatedForare removed. Thetheme targets --jsonresponse drops theThemeTargetEntry.deprecatedForfield, because no target it lists is deprecated. (#7302) Migration: run the required codemodmigrate-deprecated-theme-surfacewithastryx upgrade --from <your 0.6 version> --apply --path .after upgrading.The codemod renames removed target keys inside themecomponentsmaps (an importeddefineTheme()call, an object typed as an Astryx theme, or a theme object with a staticname), renames target classes in CSS, and replaces target-qualified bare prop/value/state classes with reflecteddata-*selectors, using every bare class the final 0.6 release emitted. It leaves dynamic/computed theme keys, unqualified or unknown classes, and CSS embedded in JavaScript/TypeScript strings for manual review. It addsTODO(astryx upgrade)when old and canonical keys coexist, and when a bare class Astryx once emitted has no known meaning on the target it qualifies.The four per-component clear-icon aliases all become the sharedinput-clear-icon, which styles every input's clear icon. In CSS the codemod keeps each rule on its component with:where(.astryx-<component> *), which adds no specificity. Theme keys cannot carry that scope, so the codemod adds a TODO naming the CSS selector to use.Code that passed{legacyNames}tothemeProps()or setdeprecatedForin a component doc should delete that argument or field; the canonical target is unchanged.Rename theme keys and CSS target classes with this complete mapping:base-table→tablecheckbox→checkbox-indicatorcodeblock→code-blockcodeblock-copy-button→code-block-copy-buttoncodeblock-header→code-block-headercodeblock-title→code-block-titledate-input-clear-icon→input-clear-icondate-range-input-clear-icon→input-clear-iconhovercard→hover-cardmulti-selector-clear-icon→input-clear-iconnavicon→nav-iconpopover-surface→popoverprogressbar→progress-barprogressbar-fill→progress-bar-fillprogressbar-mark→progress-bar-markprogressbar-track→progress-bar-trackradio→radio-indicatorradio-dot→radio-indicator-dotselector-clear-icon→input-clear-iconstatusdot→status-dottextarea→text-area
For custom CSS, replace removed bare selectors with the corresponding reflected attribute on a canonical target—for example,.astryx-button.primary.smbecomes.astryx-button[data-variant="primary"][data-size="sm"], and.astryx-switch.checkedbecomes.astryx-switch[data-checked="checked"]. Review unqualified classes such as.primarymanually because they may be application-owned. - Remove the
astryx layoutcommand group. (#7137) Removes the deprecatedastryx layoutcommand group (expand,check,grammar), its three response types (layout.expand,layout.check,layout.grammar), and the programmatic API exports (layoutExpand,layoutCheck,layoutGrammar).Useastryx buildto choose the template to start from,astryx templateto scaffold it, andastryx docs layoutfor layout guidance. The layout guide is unaffected. The error codesERR_LAYOUT_PARSEandERR_LAYOUT_INVALIDare retained.Removed JSON ids:LayoutBlockReference.modeLayoutBlockReference.nameLayoutCheckOptions.cwdLayoutCheckOptions.formLayoutCheckOptions.looseLayoutCheckResponse.dataLayoutCheckResponse.data.compactLayoutCheckResponse.data.errorsLayoutCheckResponse.data.formLayoutCheckResponse.data.outlineLayoutCheckResponse.data.validLayoutCheckResponse.data.warningsLayoutCheckResponse.typeLayoutExpandOptions.cwdLayoutExpandOptions.formLayoutExpandOptions.looseLayoutExpandOptions.nameLayoutExpandOptions.targetPathLayoutExpandResponse.dataLayoutExpandResponse.data.blocksReferencedLayoutExpandResponse.data.codeLayoutExpandResponse.data.componentsUsedLayoutExpandResponse.data.demoMediaReplacedLayoutExpandResponse.data.formLayoutExpandResponse.data.statesLayoutExpandResponse.data.todosLayoutExpandResponse.data.warningsLayoutExpandResponse.data.writtenLayoutExpandResponse.typeLayoutGrammarOptions.cwdLayoutGrammarResponse.dataLayoutGrammarResponse.data.aliasesLayoutGrammarResponse.data.textLayoutGrammarResponse.typeLayoutIssue.colLayoutIssue.formattedLayoutIssue.lineLayoutIssue.messageLayoutIssue.suggestions - Spacing tokens are rem (
--spacing-2: 0.5rem), so gaps and padding follow the reader's root font size the way the type scale does. Every token value is unchanged at the default 16px root. (#7359) One change shows at the default root: theuseTableRowExpansionchevron now sits centered in its fixed 40px column instead of running past its edge (its button moves from 24–48px to 8–32px of the column). Under a theme with a larger spacing scale, such as matcha, the chevron is visible again and the detail panel lines up with the first column instead of starting 20px past it.Old usage: The--spacing-*defaults were fixed px (--spacing-2: 8px), souseTheme().token(),resolveThemeToken(),tokenDefaultsandspacingDefaultsreturned px strings, and spacing stayed the same size when a reader raised the browser font size.Replacement: The defaults are rem with the same value at a 16px root (--spacing-2: 0.5rem,--spacing-4: 1rem), and those readers return the rem string.Migration: CSS that readsvar(--spacing-*)needs no change. Code that parses a spacing token as a px number converts the rem value with the root font size, or reads the element's computed length. A theme that wants fixed px spacing sets the tokens back, for exampledefineTheme({tokens: {'--spacing-2': '8px'}}).Codemod: None. A token read and parsed at runtime cannot be found and rewritten statically, and CSS uses need no rewrite. theme buildexits 1 when it reports private--_*variables. (#6872) The old contract reported private-variable errors but exited 0. The corrected contract keeps the same warnings, receipts, generated files, and--checkoutput, but exits 1.To migrate, a CI step that relied on exit 0 must fix the theme's private--_*inputs.
New Features
astryx upgradeaddspadding={0}to BottomSheet elements that do not setpadding, keeping their unpadded content box now that BottomSheet pads like Dialog. Sheets whose only child is a Section or a Layout are left unchanged. A sheet with a Layout anywhere in its content also gets a TODO comment, becausepadding={0}removes the inset between that Layout's regions and the Layout's ownpaddingrestores only its outer edges. A shadowedBottomSheetbinding is left alone, and a second run changes nothing. (#6884)astryx upgraderunsmigrate-field-input-styling, which renames rootxstyle/className/styleon Field-composed inputs to the part they styled before:controlXstyle/controlClassName/controlStyleon TextInput, TextArea, NumberInput, FileInput, DateInput, DateRangeInput, DateTimeInput, TimeInput, Selector, MultiSelector, and ComplexSelector, andcontainerXstyle/containerClassName/containerStyleon Typeahead, Tokenizer, CheckboxList, RadioList, and Slider. It rewrites JSX written directly on an Astryx import (named, aliased, or namespace). Spreads and wrappers that forward their own styling props are left for manual migration, and a callsite that already sets the target prop gets a TODO instead of a rename. (#7342)astryx upgraderenamesemptySearchResultsTexttoemptySearchTextonTokenizer,Typeahead,BaseTypeahead, andChatComposerInputtrigger objects, for the release that removes the old name. (#7289)
Fixes
templateandbuildfollow the project's package manager. The nearest directory from the target up to the workspace root that has apackageManagerfield or a lockfile decides. With neither, the command uses npm, whatever package manager launched the CLI. When that directory's lockfiles disagree and nothing it commits picks one,installCommandisnulland the note names the missing packages, the directory, and the lockfiles that disagree, instead of guessing a command that would write a second lockfile. (#7343)- Teach generated palette references in the full custom-theme authoring guide. (#7268)
- Generate Neutral's runtime palette references from the stops its theme uses, and fail verification when the package or CLI template copy drifts. (#7255)
Documentation
- Clarify release-branch codemod promotion and version ownership. (#7293)
Contributors
Thanks to everyone who contributed to this release:
0.6.8
Fixes
- A template that sets
replacesneeds@astryxdesign/cli0.6.4, and one that setskeywordsneeds 0.6.6, not 0.7.0 (#7265). Published 0.6.4 applies a template'sreplaces, and published 0.6.6 reads itskeywords.integration verifyasked for">=0.7.0"for both, a range no released CLI satisfies, and npm leaves the CLI uninstalled in an app that installs a package with that optional peer.integration verifynow accepts">=0.6.4"forreplacesand">=0.6.6"forkeywords, and still refuses a range that admits an older CLI. Its messages now say what older CLIs do. Before 0.6.6 a template that setskeywordsis dropped, and before 0.6.4 the package's doc topics are hidden too.
Documentation
- Guide new theme authors to the palette generator and keep the broad color scale opt-in in generated theme templates (#6795).
Contributors
Thanks to everyone who contributed to this release:
0.6.7
New Features
- Apps can opt into package-managed themes with
astryx theme add <slug> --import. The command records the theme in one generated app module with its production CSS, optional font CSS, and default slug. Usetheme removeandtheme useto manage that record, and passthemes[defaultThemeSlug]to<Theme>. Plainastryx theme addkeeps its released source-copy behavior, options, stdout, exit status, and everytheme.adddata field. It now warns thattheme ejectis the explicit source-fork command andtheme add --importis the way to use the package-managed theme. Its machine result adds theDEP-0005deprecation entry; the cleanup isCLN-0005in a later scheduled minor.UsedefineTheme({extends: importedTheme, ...})for ordinary customization.theme ejectcreates an independent local fork with its descriptor. JSON callers receivetheme.appfrom import, remove, and use, ortheme.ejectfrom eject.Existing bundled source copies stay where they are and keep their bytes. Runastryx upgrade --from 0.6.4 --path . --applyto add the missing unmaintained descriptor beside each bundled copy insrc/themes. Until then, theme commands skip those copies andtheme listand doctor name them as unmigrated. Package integration themes keep their released complete-directory copy, including the authoring descriptor.ASTRYX_THEMEis no longer read. In a project with a generated app theme module, component metadata reads that record's default built theme. Without the module, the releasedpackage.json#astryx.themelookup keeps its meaning. Doctor loads every recorded built module through the same theme adapter, so a broken runtime import failstheme-ownersinstead of passing.theme buildalso writes<out>.css.d.tsso TypeScript accepts generated CSS imports. Check mode stays compatible with released output sets that do not have this new stub yet.Integration themes can export built modules and stylesheets.astryx integration add themecreates those exports, andintegration verifychecks the exported paths against the packed package and source. Missing partner exports alone do not block packing. Every declared export must resolve; staleness is a warning for an incomplete set and an error for the complete importable module and stylesheet pair. - Every result now names the package it comes from. A
--jsonresult about one artifact (a component and each of its projections, a doc topic, index, section, or docs-tree node, a template, a hook, andswizzle) carriespackagein its envelope, directly aftertype. A result that lists artifacts gives each item its ownpackage: everysearchhit,build's start, alternatives, blocks, and components, a doc's sections, a docs-tree node's children,--blocksentries, and thecomponent --listandupgrade --listentries. Text names the same package;--source,--showcase, and a template's source still print only the source on stdout and name the package on stderr. Existing fields are unchanged. - Deprecate the
astryx layoutcommand group Theastryx layoutcommand group (expand,check,grammar) is deprecated. Useastryx buildto choose the template to start from,astryx templateto scaffold it, andastryx docs layoutfor layout guidance.In human mode each invocation prints a stderr warning naming the replacement. In JSON mode the response envelope carries machine-readable deprecation metadata in itsmetafield. Canonical stdout, exit codes, and thelayout.expand/layout.check/layout.grammarresponse schemas are unchanged.Deprecation lifecycle (spec:AST-017FR28, FR31) — removal only in a later minor whose frozen manifest carries both ids of a pair: - An integration component can replace a Core component, once its package opts in An
@acme/navcomponent whose doc setsreplaces: 'SideNav'takes overSideNavfor unqualified component detail, batch selectors, everycomponent --listdetail level,search,swizzle, and gap-report routing, when@acme/navdeclares"@astryxdesign/cli": ">=0.6.7"inpeerDependencies(optional inpeerDependenciesMeta). Every result names its package,--package @astryxdesign/corestill selects the original Core component, and the replacement keeps answering to its own name.component SideNav --package @acme/navalso selects it.Any@astryxdesign/clirange that starts at 0.6.7 or later is the opt-in, including the>=0.7.0thatintegration add doc --parentwrote in 0.6.4 and 0.6.5, andintegration add themein 0.6.5. A package whose range admits an earlier CLI keeps its component under its own name and Core stays selected, and an app that loads it sees no new output; its author gets warnings naming the range to add, fromastryx doctor integration componentsandintegration verify. For a package that declares the range,astryx doctor integration componentsreports a missing Core target, an invalid value, a component named after a different Core component, or two replacements for one target in the package as errors and exits 1. When several packages replace one target, an explicitly configured package beats an autolinked one, the later configured package wins, and Doctor warns. - Add the model comparison page template with responsive sticky context and accessible interactions. (#6251)
- New
table-collapsiblepage template: several tables on one page, each in a collapsible card with its own columns, for groups that do not share a schema. Every table sorts on its own, one time range in the page header drives all of them, and rows expand in place into a full-width history chart. Below 720px each table folds to its name and headline figure. (#6065)
Fixes
- Printed commands name the scoped
@astryxdesign/clipackage whenever theastryxbin is not installed for the project - Compact the generated agent-docs block: fewer lines, same behavioral coverage
astryx doctorkeeps itsthemescheck, with the same id, label and fields, beside the new theme checks, so scripts that read it by id keep working. Without a generated theme module it reports what it did before: whether an@astryxdesign/theme-*package is installed, and whether the app's package.json names a theme inastryx.theme. Its fix now namestheme add --import. With a generated module it reports the overall result of the theme checks. In a workspace,themesreads the app's own package.json, the file the CLI reads when it resolves the theme, rather than the package.json beside the rootnode_modules. It no longer counts theASTRYX_THEMEvariable, which the CLI does not read, as a wired theme.- Doctor says why it skipped a check and what it checked, and
doctor integration validateno longer crashes on a folder it cannot read - upgrade: exclude node_modules from integration codemod discovery
When an integration declared its codemods root as the package root (
codemods: "./"), the version-folder scan treatednode_modules,.git,__tests__, and__fixtures__as version folders and loaded their files as codemods. The sameSKIP_DIRSfilter that the recursive file walk already used is now also applied to the top-level version-folder enumeration. - Align the layout deprecation (DEP-0006) with the documented envelope and precedent
The layout command's JSON envelope now emits
meta.deprecations: [{id, replacements}], matching the response schema doc and the DEP-0005 theme add precedent. ThedeprecatedCommandDoc field renders in--helpand the manifest. The programmatic API exports (layoutExpand,layoutCheck,layoutGrammar) carry@deprecatedin their declarations and generated types. Command and function reference pages name DEP-0006 and the replacement. The DEP-0006 record names its direct authority. All released data fields are unchanged. - swizzle: rewrite every .stylex import to a deep path
astryx swizzle Button(and any component that imports a.stylexmodule from outside its own directory) emitted an import that collapsed to the directory barrel — e.g.@astryxdesign/core/utilsinstead of@astryxdesign/core/utils/interactionOverlay.stylex. The barrel does not re-export those StyleX symbols, so the swizzled file could not compile.rewriteImportsnow gives every*.stylexmodule the deep subpath. The exports generator (scripts/sync-exports.js) adds 16 specific subpath exports for the.stylexmodules swizzled components actually reference across directories:DateInput/tokens.stylex,Icon/IconSize.stylex,Indicator/indicator.markers.stylex,Layer/layerAnimations.stylex,Layer/layerTextReset.stylex,Layer/layerViewportInset.stylex,Layout/container.stylex,Layout/edgeCompensation.stylex,Layout/padding.stylex,NavItem/navItemStyles.stylex,Selector/selectorPresentation.stylex,Stack/stack.stylex,Stack/stackItem.stylex,Text/text.stylex,utils/focusOutline.stylex,utils/interactionOverlay.stylexThese are public API additions. Each module already ships in the npm tarball (indist/); only the exports map entry is new. No wildcard — a future cross-directory.styleximport needs a deliberate entry inSTATIC_EXPORTS. Precedent:./theme/dataTokens.stylex(AST-066 FR2). - template: show a grouped summary by default instead of the full catalog Bare
astryx template(no name, no--list) now shows templates grouped by category with counts — about 21 KB instead of the full 149 KB catalog. The full catalog with descriptions is still reachable viaastryx template --list.JSON output is unchanged —--json templatestill returns the completetemplate.listresponse. This is a text-only rendering change under AST-017 FR11: the machine-readable response schema is the contract; text formatting is not.Trade-off: the grouped output still includes every template id (sotemplate <id>works from a copy-paste), at the cost of ~21 KB. An even shorter summary (type + count only, no ids) would be ~500 bytes but would require a second step to discover any id. The current shape serves both human scanning and agent copy-paste without a round-trip. - template: bare
template --typeno longer prints an empty group header - A section read on a docs-tree namespace answers from the guide that has the section again, so
astryx docs layout side-panelsand the other layout section reads released in 0.6.6 work after the layout split.docs(route, section)returns the samedocs.detail.sectionthe guide's own section read returns, found by key, then by title, in--denseand--zhtoo. When no guide or more than one has the section, the read fails withERR_UNKNOWN_SECTIONand names the guides to read it from. astryx searchranks a component, hook, or template that a query word names above a doc that matched only by keyword, heading, or text.font sizefinds Text first again instead of a typography guide. A doc the query names, such asfont setupormigration, or one whose title the query holds, such asresizable side panels, keeps its place. Result scores do not change; only the order between domains moves.astryx searchfinds a guide when the query is its route or title in the other number:side panelfinds the side panels guide first again, andheader and footerfinds headers and footers. A section's heading still doesn't count as its topic's name, sofont sizekeeps finding Text first.- Fix comparison table category from "Table - Frozen Column" to "Table - Comparison" The category described an implementation detail (the frozen label column) instead of what the template is for. Builders searching by layout type now find it under Comparison.
- Template and build tell you what a scaffolded template needs that your project lacks. When
astryx template <name> <path>scaffolds a file that imports packages your project does not have (e.g.@heroicons/react,recharts,lucide-react), the receipt now includes a ready-to-run install command with the project's package manager and version ranges from the CLI workspace.astryx buildshows the same note on its start template.When a scaffolded template uses StyleX and the project has no compiler plugin configured, the receipt warns and points toastryx docs styling-overview. The agent-docs block no longer says "don't use xstyle" flat-out — it acknowledges that some templates need it and links the setup doc.detectStylingSystemnow recognizes the official@stylexjs/rollup-plugin,@stylexjs/webpack-plugin, and@stylexjs/nextjs-pluginalongside the existing entries. astryx theme buildprints one line per built theme, plus one line naming fonts the themes do not load. Before, every theme printed the same install example and font recipe, so a build of many themes printed the same blocks again and again.--detail fullprints the install example and font recipe, once for a batch instead of once per theme; for one theme it prints what the default printed before. Only the text report changes:--jsonoutput,--check, exit codes and written files are unchanged.- Wherever the CLI shows the
<Theme>wrapper, it now also shows whereThemecomes from:import {Theme} from '@astryxdesign/core'. This covers theastryx initnext steps,theme addandtheme buildoutput, the doctor fix for an unimported theme module,buildhelp, and the theme guides. astryx theme add <slug> --importnames the npm package that owns the added theme, in its JSON envelope (package, directly aftertype) and in its text output, the same way other results about one artifact do. A local theme has no package, so its result has nopackage, andtheme removeandtheme useare unchanged.astryx theme add --listkeeps its JSON. Its text now namestheme add <slug> --importto use a theme andtheme eject <slug>to fork one, instead of the deprecated copy form.astryx doctoradds atheme-managementcheck, and focusedtheme-*checks once a project has a generated theme module.- One-off commands in a classic Yarn (1.x) project use
npx @astryxdesign/cli …instead ofyarn dlx, which classic Yarn does not have
Documentation
astryx docs migration,internationalization,styling,styling-libraries,typographyandtokensstill work and now list focused guides. Each section is also readable under its guide, for exampleastryx docs tokens/tokens-spacingorastryx docs styling/tokens-and-setup stylex-setup, andastryx docs <topic> <section>keeps working: every section key these topics had still opens the same section.astryx docs tokens --depth all --detail fullprints every token table, and atoken-reftotokenskeeps resolving through the guide that holds the table. Integrations: these six names are now docs-tree sections, not topics, so an integration doc that declaresextendsorreplaceswith one of them is reported as naming no topic, and its content no longer shows. To keep that content, ship it as your own topic under a new name, or as a guide in your package's own section (astryx integration add doc <name> --parent <your-section>). Topics that are still flat, such asthemeorcolor, can still be extended or replaced.(#7184)astryx docs layoutstill works and now lists the focused guides. Each section is also readable under its guide, for exampleastryx docs layout/side-panelsorastryx docs layout/scaffold shell, andastryx docs layout <section>keeps working. (#7125)astryx docs layoutopens with its overview again, andastryx docs author-a-themeanduse-a-themerestore guidance the theme split dropped: what a badextendsbase does, how adaptation rules are validated, what__builtmeans, the icon-registry specifier traps,registerTheme, and wiring built themes in development too. (#7204)- Add a choose-a-path styling overview and restore the import-based workflow across the theme guides. (#7134)
- Split the theme documentation into focused guides for using and authoring themes, with a concise overview that points to both workflows. (#7141)
Other Changes
- A hint uses
npx astryx …(orpnpm exec,yarn,bunx) only when theastryxbin is innode_modules/.bin, in the project or a folder above it. Otherwise it printsnpx @astryxdesign/cli …(pnpm dlx,yarn dlx,bunx), as it already did when the CLI ran from an npx or dlx cache. - A global install, or a workspace install used in a fresh package, used to print
npx astryx …. The npm package namedastryxis not this CLI, so following that hint fetched an unrelated package. astryx blogfollows the same rule, and the incident console template names the scoped package.Classification: contract-restoring. JSON shapes are unchanged; only hint text changes, and projects with the CLI installed keepnpx astryx ….- deprecation
DEP-0006/ cleanupCLN-0006—astryx layoutcommand group (expand,check,grammar) - A check that needs the loaded project quotes the reason the CLI could not load it, instead of only "Skipped".
- The config check warns when astryx.config imports but the CLI cannot load the project from it. Before, it said the config loaded cleanly.
- Integration contributions name the integrations they checked; with none loaded, the check reports info and says there is nothing to check.
- The agent-docs check reads every file init can write (Hermes included) and looks in the project root as well as the working directory, so running doctor from a subfolder no longer reports that there are no agent docs.
astryx doctor integration validatenames a folder it cannot read and keeps checking. A declared root that is a file or that cannot be read is reported asinvalid_rootorunreadable_rootinstead of a raw error or a crash.Classification: contract-restoring. No check becomes stricter: every new finding is a warning or info, and the only exit-code change is that an unreadable folder outside every root no longer crashes validation.- Whenever the CLI prints its scoped one-off form (it ran from an npx or dlx cache, or the
astryxbin is not installed for the project), a Yarn project gotyarn dlx @astryxdesign/cli …. On classic Yarn that command fails. - Classic Yarn is read from the declared
packageManagerversion, theyarn.lockheader (# yarn lockfile v1), a committed.yarnrc(without.yarnrc.yml), or the runner. Yarn 2 and later keepyarn dlx.Classification: contract-restoring. JSON shapes are unchanged; only hint text changes.
Contributors
Thanks to everyone who contributed to this release: