What's New
Release notes and changelog for all packages.0.7.6
New Features
- When a template imports Astryx's docs-only demo content,
astryx template <name> <path>,astryx template <name>,astryx template <name> --skeleton, andastryx component <Name> --showcasereplace each demo-content element with a marked<Text>Card content</Text>placeholder and remove the demo-content import, so the code they hand out never imports a module that only Astryx's own previews have. The placeholder uses the file's own AstryxTextimport when that import is in scope, and otherwise importsText, under an alias when the file already uses that name.template.copyandtemplate.showgaindemoContentReplaced(0 when the template carried none), their text output says how many elements became placeholders, and thecomponentsthattemplate.showandtemplate.skeletonlist are the components of the returned source. No shipped template uses demo content yet, so every current template is copied, shown, and outlined exactly as before. The docsite's shadcn install of a block or page applies the same replacement and also replaces demo media, each with a marked placeholder: a placeholder image for an image and adata:,placeholder-video-add-your-ownsource for a video. The item's description says how many references and elements were replaced. The adjacent.astryx/<item>.jsonreceipt keeps its current shape, so every releasedastryx upgradestill reads it. (#9430) - A theme's
motiontakes two knobs beside the duration scale:tempo(0.75–1.5) scales every motion duration, andcharacter('crisp','standard'or'expressive') sets the new--ease-entranceand--ease-movetokens;--ease-exitstays the same at every character. Their types,ThemeMotionConfig,ThemeMotionKnobsandMotionCharacter, are exported. A theme without them renders exactly as before; a duration scale and explicit tokens win over the knobs, Spinner's and Skeleton's loops keep their timing under every tempo, and the press release fade follows tempo up to the 200 ms Reduce Motion cap under the person's setting. Springs don't read the knobs yet. The motion, token and theme-authoring docs and the theme template describe the knobs. (#8661)
Fixes
- BottomSheet checklist examples use CheckboxList so the whole row toggles, not just the label (#9533)
- The motion guide now says that under Reduce Motion, components cross-fade under a finger and change at once under a mouse, and that a value changing in place, such as a progress fill, takes its new value at once under any pointer (design:reduced-motion DR1–DR3). (#8615)
- Published packages no longer include repository test and benchmark files, reducing install size without changing exports. (#9153)
Performance
- Calling
integrationComponentConflicts()orintegrationCheck()from@astryxdesign/cli/apimore than once in one process now reads each TypeScript file a package'stsconfig.jsonincludes once while the file is unchanged, instead of on every call. A singleastryx doctor integration componentsorastryx integration checkrun is unchanged. (#9422) search()shares a catalog gather that is still running: searches that start together in one long-running process, such as a docs site's search right after it starts, now gather once instead of once each (#9460)
Documentation
- A new
useCollator — Locale-aware Name Sortexample block sorts a list of names with the compare function fromuseCollator: accented and lowercase names land where a reader expects, and switching the provider locale to Swedish moves Å and Ö after Z. Copy it withastryx template useCollatorHookUsage <path>. (#9510) - A new
usePressFeedback — Pressable Cardexample block shows the hook on an Astryx Card: the hook's marker and theinteractionOverlayStyles.backgroundImageoverlay go straight on the Card, so pressing the card darkens it the way every Astryx pressable does, under a finger or a mouse (Enter or Space flips it), andfocusOutlineStyles.focusVisiblegives keyboard users the shared Astryx focus ring on it. Copy it withastryx template usePressFeedbackHookUsage <path>; the docs-only playing card it shows becomes a<Text>placeholder for your own content. (#9431) - A new
useToast — Settings Savedexample block calls the function fromuseToaston a settings form: Save shows a "Settings saved" toast with an Undo action, itsuniqueIDmakes a second Save replace the toast instead of stacking another, and a failed save shows an error toast instead. Copy it withastryx template useToastHookUsage <path>. (#9512) - A new
useTranslator — Load More Footerexample block gets a list footer's "Load more" label and its "Showing 3 of 9" count from the functionuseTranslatorreturns. The app's own message keys are supplied per locale throughInternationalizationProvider, so switching the provider to French changes both strings. Copy it withastryx template useTranslatorHookUsage <path>. (#9573)
Other Changes
- Preserved the v0.7.5 upgrade codemod registry when the release outputs returned to main (#9086), so the v0.7.6 CLI continues to offer that migration.
Contributors
Thanks to everyone who contributed to this release:
0.7.5
Experimental APIs
- New command
astryx experimental render <page>turns a page built with your installed Astryx components into one self-contained HTML file. The file needs no network and no scripts, follows light and dark mode, and carries the page's source;astryx experimental render --reverse <file.html>writes that source back. Warnings point out anything that may not look as intended. Experimental commands may change or be removed in any patch release. Guide:astryx docs cli/experimental/render-pages. - Building an icon-set package from an icon library takes fewer steps and fewer guesses. Only the experimental icon commands, the icon-set guide, and
astryx templatein a project that setsexperimental.iconSetchange; without that opt-in, stable commands behave as before, and only theexperimentalgroup's summary inastryx helpandastryx manifestnow mentions icon sets.experimental icon new-set.--frommaps a definition only when an icon has its exact name and lists those for review; likely matches come back as at most three suggestions each, never written. It saves the library and version, copies the library's license notices, keeps your--excludelist across refreshes, and its receipt names the package entry, peer dependencies, andtypecheckscript to add.--variants,--default-variant,--display-name, and--descriptionfill in the set. A refresh changes only the icons that library supplies, keeps each icon's export name, and lists renamed icons. A 1,600-icon library is read in about two seconds.experimental icon addandmap.add --variant <name> --from <module> --alladds a variant for every icon at once, andmap --pairs a=b,c=dwrites many entries in one checked step.- Icon commands now refuse options that conflict instead of silently ignoring one (
ERR_INVALID_OPTION), leave every file as it was when they fail partway (ERR_WRITE_FAILED), and report a missing or withdrawn set the same way everywhere (ERR_NOT_FOUND). experimental icon --set <set> --all-iconslists every icon in a set, and--definitionslists every Astryx icon definition.- Templates drop a mapped icon library's sizing props (
size,strokeWidth,absoluteStrokeWidth) and keep comments on rewritten imports. - Thirteen new icon definitions:
rotate,flipHorizontal,flipVertical,alignStart,alignCenter,alignEnd,panelLeft,panelRight,gitBranch,gitFork,scale,cpu, andtextCase. Definitions gain common glyph names as search words; seven optional definitions lose a word that named a different thing:star(bookmark),database(table),raiseHand(stop),redo(forward),activity(monitor),archive(store),mobile(device). integration checksuggests icons by the same rule, describes each optional definition, and its version-drift warning gives the refresh command.
New Features
- Status colors are readable everywhere they appear, and Info is a status of its own. Each status (info, success, warning, error) now has a strong fill (
--color-<status>) with content on it (--color-on-<status>, at least 4.5:1), a pale fill (--color-<status>-muted) with its content (--color-on-<status>-muted), and readable text for the page and cards (--color-text-<status>). Status icons (--color-icon-<status>) and borders (--color-border-<status>) default to the readable text color. The Info roles (--color-info,--color-on-info,--color-info-muted, …) are new and no longer borrow your accent color.--color-success,--color-warning, and--color-errorandbg-<status>keep their meaning as the strong fills. In Tailwind,bg-info,bg-info-muted,text-on-<status>,text-on-<status>-muted, andtext-status-<status>are new;text-,decoration-,placeholder-, andcaret-<status>now use the readable text shade, andborder-,divide-,outline-, andring-<status>use the border shade, whilebg-,accent-,fill-,stroke-<status>, shadows, and gradients keep the strong fill. For example, Core's lighttext-warningis now[#753](https://github.com/meta/astryx/pull/753)F07instead of#E9AF08. To keep the fill color on text, writetext-[var(--color-warning)].What changes on screen:- Core's dark Error content (
--color-on-error) is now[#0](https://github.com/meta/astryx/pull/0)A1317instead of white, so text on dark-mode error fills reaches 4.5:1. Core's Info Badge uses[#0064](https://github.com/meta/astryx/pull/0064)E0instead of the accent ([#2694](https://github.com/meta/astryx/pull/2694)FEin dark mode). - Status icons (Icon
color="info|success|warning|error"), Stepper status glyphs, and Chat tool-call status icons use the readable shades. Core's light success icon is now[#09441](https://github.com/meta/astryx/pull/09441)Finstead of[#0](https://github.com/meta/astryx/pull/0)D8626. - Input and FileInput status borders use the border shades. Core's light warning border is now
[#753](https://github.com/meta/astryx/pull/753)F07instead of#E9AF08, and Butter's light success and warning input borders reach 3:1. - Banner draws its title, description, icon, and controls in the on-muted colors, and fills Info with
--color-info-muted. - Status fills keep a visible edge in forced-colors mode.
- Content on Chocolate and Matcha success and error fills, and on Stone success, warning, and error fills, now reaches 4.5:1.
- Every first-party theme sets a blue Info. Chocolate and Matcha Info Badges move from the accent to that blue; Butter keeps its own Info Badge colors.
- Neutral's
--color-success,--color-warning, and--color-errorare now the fills its Badges already showed, and its--color-infois[#0074](https://github.com/meta/astryx/pull/0074)E2([#6](https://github.com/meta/astryx/pull/6)D9CFEin dark mode). Its Badges, StatusDots, progress fills, and Stepper badges look the same; its accent ProgressBar, StatusDot, and Stepper now use Neutral's accent instead of blue. - Neutral no longer defines its undocumented local status tokens. Use the standard roles instead:
--astryx-theme-neutral-color-status-fill-success,-status-fill-warning, and-status-fill-error→--color-success,--color-warning,--color-error;-status-muted-accent→--color-info-muted;-on-tint-neutral→--color-neutral; the-on-tint-overlay-*and-destructive-overlay-*tokens →--color-overlay-hoverand--color-overlay-pressed.--astryx-theme-neutral-color-status-fill-accentkeeps its value but is deprecated.
Custom themes get the content and text roles they don't set: they are derived from the theme's status fills. To keep a component's previous color, set the matching role, for example--color-icon-successto your old--color-success. - Core's dark Error content (
- CodeBlock's
tokenizerprop is deprecated in favor of a custom language: passlanguage={createCodeLanguage({name, identifiers, tokenize})}with the same function. The prop still works.astryx upgraderewrites it when the block has a fixedlanguage, and leaves a TODO comment where it can't safely rewrite it. Icontakes an optionalvariantto ask the active theme for alternate artwork, for example<Icon icon="info" variant="filled" />. The theme's icon receives the variant only when the theme lists it iniconVariants; otherwise it draws its normal artwork. Icons you pass as components never receivevariant, and it is never written to the page. Icons withoutvariantrender as before.- A theme icon can now pick its artwork by size: an entry in
defineTheme({icons})orregisterIcons()can be a function of{size, variant}, andIconcalls it with the size it renders at. Returningnulldraws no icon.getIcon,getExtendedIcon,getIconRegistry,useIcon, and a theme'siconsfield still return nodes, reading a function at{size: 'md'}. Existing icon entries are unchanged. - A theme can list the icon variants it supports, such as
filled, withdefineTheme({iconVariants}), and read them back fromtheme.iconVariants. Child themes inherit the list unless they set their own.@astryxdesign/core/IconexportsIconVariantMapandIconVariantfor typing variants. Themes withouticonVariantsare unchanged. astryx theme buildkeeps function icons and icon variant lists, so a built theme draws each icon at the same size and variant as the live theme, including icons inherited from another theme. A theme that listsiconVariantsgets matching types in<theme>.variants.d.ts. Themes without these features build exactly as before.- Themes can set the real size of each Icon size:
widthandheightinpxorremoncomponents.icon['size:sm'](orxsm,md,lg) now resize the glyph itself, for named icons and SVG components, in live and built themes. Before, they sized only the box around the icon. Sizes a theme does not style still render at 12, 16, 20, or 24px at a 16px root.astryx docs themegains an Icon sizes section. - New
--ease-exitmotion token for things leaving the screen, beside--ease-standardfor things arriving. BottomSheet already closes on it, so nothing looks different, but a theme can now tune the exit.astryx docs motionand the theme template list it. astryx upgradefinishes instead of failing when it finds code it can't migrate safely: each spot is listed indeclinedCandidateswith its file, line, and a reason startingmanual migration needed (<codemod>):, and the run exits 0. Generated files that need rebuilding, such as stale theme CSS, are listed in a newregeneratefield with their rebuild command until they are rebuilt; ahooks.postCodemodthat rebuilds them clears the entry. Protected generated files still stop the run as before, now with the rebuild command listed.- The two Bottom Sheet flow templates (
BottomSheetSwitcherShowcase,BottomSheetSwitcherReviewFlow) now show the standalone-step pattern that replacesBottomSheetSwitcher, and are also listed underBottomSheet. Template names and ids are unchanged.
Fixes
- Projects that compile StyleX with
@stylexjs/unplugin(the standard Vite setup) are detected as StyleX projects. - The
Tokenizershowcase template's search returns matching tags again, so the live example on the Tokenizer docs page works. astryx integration verifyno longer fails with "npm pack failed" when anothernpmwrapper comes first on your PATH.astryx upgradeskips vendored, generated, or ignored files it can't parse, lists them indeclinedCandidates, and finishes the rest of the upgrade.astryx upgradeno longer spends minutes reading symlinkednode_modulesfolders or package stores.astryx upgrade --froma version before 0.7.0 no longer fails onvar(--color-data-*)without a fallback. Source builds that read raw data colors should importdataVarsfrom@astryxdesign/core/theme/dataTokens.stylex.- Tools that call the CLI API repeatedly, such as a docs site search, now see doc edits without restarting.
- Component families list the same members whether or not the package has been built, so Lab's
TourStepnow appears in the official package list. astryx upgradehandles anastryx.configwritten asconst config = {...}; export default config;.astryx component <name>suggests the right component when you type a wrapped or prefixed name.- When
astryx component,astryx template, orastryx docsfinds nothing, its suggestions stop where the matches get weak instead of listing unrelated entries. astryx upgradeto 0.7 no longer turns your own MetadataList class into adata-columnsselector that never matches.astryx discoverlists the experimental MobilePowerSearch component from@astryxdesign/lab.astryx theme buildreports a theme file that fails to load instead of guessing the theme from its text.astryx theme buildfails with a clear error when your project's@astryxdesign/corecan't load, instead of silently building with the CLI's own copy.astryx upgradeto 0.7 leaves other libraries' theme objects alone.- A failed
astryx upgradenow lists the files it already changed: its--jsonerror includes areceiptwithmodifiedFiles,errors,protectedFiles,complete: false, anderrorCode. The error code and exit code are unchanged.
Documentation
- The Tokenizer templates size their field to fit phone screens.
- The CodeBlock snippet example shows one-line commands with Copy beside them.
- Package links now point to the project's GitHub home,
meta/astryx. - TabList's description no longer promises a built-in "more" menu (a narrow tab strip scrolls), and the library page template describes
MobileNavas the slide-out drawer it is. - The theme guide and generated theme files explain that an extending theme's
motionsettings inherit field by field. - The disabled Thumbnail template now describes its buttons correctly: they stay focusable and are announced as disabled.
Contributors
Thanks to everyone who contributed to this release:
0.7.4
Experimental APIs
- Icon sets: an integration can ship an icon set, agents find icons by meaning and get the exact import line, and copied templates use the project's icons. Everything here is experimental and may change or be removed in a patch release; a project that does not set
experimental.iconSetsees no change in any stable command, apart from: the markedexperimentalgroup in help and inastryx manifest(its command, and itsresponseTypesandjsonSupportedentries); the marked experimental entries in theastryx docs clilistings; and a search for "experimental", which also finds the new stablestabilityfield of the field reference.astryx searchreturns no icon and no experimental doc. With a package that ships icon sets installed and no opt-in, the warnings an older CLI gives about the manifest keyexperimental(inastryx doctorandastryx doctor integration validate <package>, and the one-line nudge other commands print to stderr) are gone, anddoctor integrationchecks that package's icon sets only in a project that setsexperimental.iconSet; andastryx integration checkreports icon-set findings for a package that declaresexperimental.iconSets(below). (#7759)
New Features
- Keep Butter's released
butterPalettesobject byte-identical while moving the maintained Light/Dark theme to reviewed named palette stops. Signature Blue[#225](https://github.com/meta/astryx/pull/225)BFF, Butter Yellow#FDEE8C, and warm body surfaces remain exact; status fills move from success[#91](https://github.com/meta/astryx/pull/91)D143to[#7](https://github.com/meta/astryx/pull/7)BBF7A, warning#FFC502to#DFCF5B, error#FC473Bto#E56241, and info[#4883](https://github.com/meta/astryx/pull/4883)FDto[#4](https://github.com/meta/astryx/pull/4)D82FF. Info and error content changes from white to warm Neutral[#1](https://github.com/meta/astryx/pull/1)D1C11, the neutral Badge uses Blue[#194](https://github.com/meta/astryx/pull/194)CE8, and light TopNav items use Blue[#225](https://github.com/meta/astryx/pull/225)BFF/[#194](https://github.com/meta/astryx/pull/194)CE8; these palette-first pairs clear normal-text AA. Consumers that need the former appearance can extendbutterThemeand override the affected color, syntax, shadow, and component values with their previous values. The CLI template ships the same private palette request, receipt, and runtime-sized references. (#7672) - Docs can mark an experimental surface: every doc type except
ThemeDocandIconSetDoc, and every schema field and enum value, acceptsstability: 'experimental'. A marked command shows[experimental]in help, a marked schema field or enum value is left out of its stable table so its feature's own docs describe it, andastryx searchleaves out a marked doc, which is read on its own route. For the package being authored,doctor integration validate(and sointegration check) addsolderCliNotes, each{file, kind, field, message}: a template or namespace doc that setsstability, or a template that declaresicons, while the package's CLI peer range admits a release before 0.7.4, which drops that descriptor. A note is never an error or a warning and never fails a check, under--strictor--next; text output prints "Notes for older CLIs". Docs and findings that use none of these read exactly as before. (#7759) - Docs can write commands so every reader sees their own:
{@command docs theme}for an Astryx command,{@pm install @acme/widgets --dev}for a package-manager step, and{@pm-only npm "<reason>" pkg set name=x}for a step only one package manager can do. The CLI shows each one with the reader's runner and package manager (npm, pnpm, Yarn 1, Yarn 2 and newer, or Bun), and{@@…}shows a token as written.astryx docs authoring/building-blocks/docs/doc-syntaxdocuments them.doctor integration validatelists each command a topic writes for one package manager (package_manager_command), bare (plain_command) or with a runner (runner_command), and each token that does not parse (doc_token), each with the token to write. (#7868)integration check --nextcounts the findings the next minor release turns into warnings, the notes markednext, as warnings now, so--strict --nextfails on them. Every run says how many there are. Without--next,integration check --strictexits as before. - An integration's doc can now replace or extend one of the CLI's guides by its route, such as
replaces: 'authoring/quick-start'orextends: 'authoring/quick-start', so a package changes the guide agents already read for every app that installs it. An extension's section can setbeforeorafterto a section's key to go there instead of at the end; an older CLI rejects those fields, sointegration verifywarns when the package's@astryxdesign/clipeer range admits one. Every read names the replacing or extending package:packageon the guide and on each section, and a replaced topic or guide now also carriesreplacedPackagebesidereplaces(indocs,docs --index, the topic list, and a namespace's children), with areplaces <package>'s <topic>line in text. A name that holds no topic or guide (such as a namespace) changes nothing, and abeforeorafterkey that names no section adds the section at the end:integration validatelists each as a note (doc_target_not_found,doc_section_unplaced), and two docs of one package that replace one guide asduplicate_guide_replacement; none fails anything until the next minor release. (#7936) astryx doctor --built <path>checks a finished build before you deliver it: a project folder, a build output folder, or one built HTML file.built-astryx-usagefails when the path holds no import from an Astryx package (any@astryxdesign/*package, or an integration the project installs: a declared dependency whose installed copy has an integration manifest), no component imported from one, and no Astryx styles in built CSS or HTML, and names the template-first way to rebuild it.built-astryx-puritywarns with the source check ofastryx docs is-my-code-good: raw elements Astryx has a component for, raw SVG and icon-library icons, inline styles, classes,stylex.createand imported stylesheets, each with its file and line, or says the source was not inspected when the path holds no source with JSX, such as a bundle. The files under the path and that package.json are only read; nothing in them runs. Without--built,astryx doctorruns exactly as before. (#7886)- Keep Gothic's released flat
gothicPalettescompatibility export unchanged while moving the maintained dark theme to a reproducible generated palette and named stop mappings. The card changes from[#1](https://github.com/meta/astryx/pull/1)A1D20to[#191](https://github.com/meta/astryx/pull/191)D20; Gray background and border from[#3](https://github.com/meta/astryx/pull/3)D4248/[#5](https://github.com/meta/astryx/pull/5)D646Bto[#3](https://github.com/meta/astryx/pull/3)E454B/[#5](https://github.com/meta/astryx/pull/5)E676E; syntax comment and punctuation from[#6](https://github.com/meta/astryx/pull/6)B7079/[#7](https://github.com/meta/astryx/pull/7)A8290to[#7](https://github.com/meta/astryx/pull/7)E8791/[#7](https://github.com/meta/astryx/pull/7)E8791; and diff backgrounds from[#081408](https://github.com/meta/astryx/pull/081408)/[#1](https://github.com/meta/astryx/pull/1)E0A0Ato[#071607](https://github.com/meta/astryx/pull/071607)/[#220806](https://github.com/meta/astryx/pull/220806). Success, warning, and error inset rings move from[#87](https://github.com/meta/astryx/pull/87)B06A50/#D6B56A50/#D4485150to[#869](https://github.com/meta/astryx/pull/869)B7250/#D3C49050/#C6A6A250. Yellow text moves from[#6](https://github.com/meta/astryx/pull/6)C5010to[#573](https://github.com/meta/astryx/pull/573)F0B, and Pink text from[#71223](https://github.com/meta/astryx/pull/71223)Cto[#5](https://github.com/meta/astryx/pull/5)C182F; both darker named stops clear 4.5:1 on their categorical surfaces. Consumers that need the former appearance can extendgothicThemeand override these color, syntax, shadow, and component tokens with their previous values. The CLI template ships the same request, receipt, and runtime-sized references. (#7670) doctor integration validate, and sointegration check, lists what a package's examples need to work everywhere they are shown, as notes for the next minor release (integration check --strict --nextfails on them now): (#7891)- Move Matcha's existing color roles onto its reviewed light and dark ramps, including Tea Gold. Warning and Yellow move from
#FFB600/#FFC940to#F2C000/#F6D066; related syntax colors and warning inset rings follow the same palette. Consumers that need the former appearance can extendmatchaThemeand override the affected color, syntax, shadow, and component tokens with their previous values. The complete Matcha palette remains private authoring data, and the CLI template ships the same request, receipt, and runtime-sized references. (#7671) astryx theme palette generatereceipts now name the generator implementation (generatorVersion: 'palette-generator-v1') and the format of the candidate bytes they hash (candidateFormatVersion:'palette-typescript-v1'for a.tsoutput,'palette-json-v1'for a.jsonoutput or a printed candidate).candidateSha256and every other receipt field keep their meaning, values, and order, so existing readers keep working. (#7678)- Replace Stone's internal shared-ramp mapping with reviewed light and dark ramps while preserving the public numbered palette lookups and
hue/chromametadata. The light canvas moves from#F3F3F5to#F0F0F7, the dark popover from[#25252](https://github.com/meta/astryx/pull/25252)Ato[#302](https://github.com/meta/astryx/pull/302)F36, and Green, Yellow, Teal, and Cyan use re-seeded midtones (including Green[#667](https://github.com/meta/astryx/pull/667)D65to[#528](https://github.com/meta/astryx/pull/528)B49). Seven families' light stop-90 surfaces, syntax colors, and input status rims shift; the mapped success and warning rims use[#609757](https://github.com/meta/astryx/pull/609757)and#A08C36, and syntax attribute uses[#736419](https://github.com/meta/astryx/pull/736419), keeping the required contrast floors. Existing apps can keep the former appearance by extendingstoneThemeand overriding the affected color, syntax, shadow, and component tokens with their previous values. The CLI template ships the same reproducible request, receipt, and runtime-sized references. (#7669) - When the project's installed CLI (its own, or its workspace's) has
astryx doctor --built(0.7.4 and later), the agent docsastryx initwrites tell agents to run it before they deliver a build, and not to deliver a build that fails it. Before install, or on an older CLI, the line is left out; the nextinitorupgrade --applyadds it. (#7944) - Keep Y2K's released
y2kPalettesobject byte-identical while moving the maintained Light/Dark theme to reviewed named palette stops. Periwinkle#CCCFFAand Neon Green#C5E17Aremain exact; syntax becomes brighter, the dark code background moves from[#190](https://github.com/meta/astryx/pull/190)F00to[#0](https://github.com/meta/astryx/pull/0)E0F1A, and dark Gray background moves from#EDE0D4to#DFE2F3. The necessary dark input and unchecked-selection outline moves from the released[#3](https://github.com/meta/astryx/pull/3)A3F5Eto Neutral Dark 45[#636889](https://github.com/meta/astryx/pull/636889), raising contrast on the input surface from 1.71:1 to 3.23:1. Consumers that need the former appearance can extendy2kThemeand override the affected color, syntax, shadow, and component values with their previous values. The CLI template ships the same private palette request, receipt, and runtime-sized references. (#7675)
Fixes
astryx doctor --builtno longer counts a type-only Astryx import (import type,import {type X},export type … from) as Astryx use, since the build erases it. (#7945)- Discover results name their source package and tolerate typos. (#7147) Every
discoverJSON result now names its package per the provenance rule: single-artifact responses (discover.detail,discover.detail.doc,discover.item) carrypackagein the envelope, and list entries (discover.list, and each entry of itsmeta.available) carrypackage. Text output matches: an opened doc prints itspackage:line on stdout.discover <words>now has the same typo tolerance assearch: a near-miss name (edit distance 1–3, with minimum-length guards) returns results instead of "not found". Previouslydiscover Geodeticssaid "not found" whilesearch Geodeticsfoundgeodesic. astryx searchfinds a family member by its name spelled out, as its own description spells it ("vertical stack" is VStack), and lists a member named by its head word after single letters (VStack, HStack) for that word ("stack"). (#7927)astryx searchlists the first three members a family's doc names for a query that is the family's name ("table" lists three Table parts after Table; "chat" lists Chat parts though no Chat component exists), for Core and integration families alike. (#7955)astryx searchorders results the matcher scored the same by fit instead of by name: below the first result, a part of it leads (BadgeCountBadges after Badge), then the result matching the query's rarer words. Scores and the first result are unchanged. (#7959)astryx integration verifyworks on npm 8 for a scoped package: npm 8 names the tarball@scope/name-1.0.0.tgzin its pack output but writesscope-name-1.0.0.tgz, so verify reads the file npm wrote instead of failing to find it. (#7933)
Documentation
- Four block templates (
MetadataListItemBasic,SegmentedControlItemBasic,VisuallyHiddenSupplementaryContext,ItemWithMetadata) now describe what each one shows and when to use it, written from what the block renders. (#7963) - The
BottomSheetSwitchertemplate docs (BottomSheetSwitcherShowcase,BottomSheetSwitcherReviewFlow) describe each step as its own native dialog under one scrim, as the component now renders, instead of "one shared dialog". (#7720) - The
CommandPaletteItemshowcase block now describes what it renders, an inline command palette whose items pair each label with its keyboard shortcut, and lists only the components it uses. (#7967) - Discover data: list the Lab ListInput blocks (the Tag options showcase and the Mailing list, Budget allocation, and Family member declaration examples) as templates. (#7953)
- Six guide titles read more plainly and use the same sentence case as the rest: Theme System is now Theming, Styling Components is Styling components, Browser Support is Browser support, Migration Guide is Migration, Styling Library Interop is Other styling libraries, and Looking up components is Component lookups. Only the titles changed: every route still opens the same doc (
astryx docs theme,astryx docs styling-libraries,astryx docs cli/component-lookups), and searching by an old title still finds it. (#7934)
Other Changes
- Commands. The new
astryx experimentalgroup holds experimental commands; icon sets are its first.astryx experimental icon <words>ranks icons across the installed sets (icon.search),<set>/<id>reads one icon with every variant's import line (icon.detail), and--listlists each set with its definition coverage (icon.list). Authoring:experimental icon new-set <name>starts a set (--from <module>wraps every icon a library exports,--excludedrops exports that are not icons),experimental icon new-definition <name>adds a set's own icon definition,experimental icon add <Export> --from <module>verifies an export and lists the definitions that fit it or adds and maps it (--variant <name>adds it as a variant the set declares, a named look such as solid; size comes from CSS),experimental icon map <definition> <icon>edits one map entry, andexperimental icon use <set>picks the project's set. The API gainsicon,iconAdd,iconMap,iconUse,iconNewSet, andiconNewDefinition, all marked@experimental. - Configuration. The project's set is
experimental.iconSetin astryx.config; an integration declares its sets folder asexperimental.iconSetsin its manifest. Each set has a typed<name>.doc.mjs(IconSetDoc), a<name>.icons.jsondata file, and an optionaldefinitions/folder;@astryxdesign/cli/authoringexportsIconSetDoc,IconSetData,IconDefinitionDoc, and their parsers. An older CLI warns thatexperimentalis a manifest key it does not know, and a CLI before 0.7.4 refuses an astryx.config that setsexperimental.iconSet("Unrecognized key"), so commands that load the project configuration, such asdoctoranddiscover, fail in that project;astryx experimental icon usesays so in its receipt (warning) when the project's@astryxdesign/clirange admits such a release. - Where icon sets show up. Icon lookup by meaning is only
astryx experimental icon:astryx searchnever returns icons or experimental docs, with or without a set. A project that setsexperimental.iconSetalso getsastryx templatereplacing each icon a template declares in its newiconsfield (a named import by the name it imports, a default import by its local name) with that set's icon, every key reported as mapped or kept in aniconsreceipt field,astryx discoverreadingicon-setas a kind (--type icon-set, and catalog entries of that kind), and anicon-setscheck inastryx doctor. Without it, none of these change: templates are copied as they are,--type icon-setis an unknown type and catalogicon-setentries are ignored, and Doctor reports nothing about icon sets, even an invalid one.astryx integration checkreports icon-set findings for a package that declaresexperimental.iconSets, and lists, in the validate result's additiveiconSetsfield, the optional Astryx definitions each set leaves unmapped, with the icons that fit, and what it cannot judge (unchecked: an icon whose module is anexportstarget not built yet, an icon or adapter export it cannot prove either way, such as one behind a re-export it cannot follow or bound to a default import, and a theme map or entry it cannot read; only an export it proves absent fails), printed under "Not checked"; neither list is ever counted or fails a check, even under--strictor--next. It also notes each templateiconskey the template's source never imports (template_icon_not_imported), which fails nothing, under--nexttoo. - Docs. The guide and every icon definition live under
astryx docs cli/experimental, and every icon-set doc is markedstability: 'experimental'. The experimental icon-definitions namespace adopts definition docs from every package (source.packages: 'all', read only on a CLI namespace marked experimental). component_without_example: a published component that no block template shows withexampleFor: '<Name>'andisShowcase: true(oralsoShowcaseFor). A block named like a showcase that sets neither does not count. Hidden docs, family members, docs withisHiddenFromOverviewandUtilitycomponents are exempt. The note carries a template doc to paste.template_category: a templatecategorywritten as a path, such ascomponents/X, with a"<Group> - <Variant>"one to write.showcase_not_standalone: a showcase (a block withisShowcase: trueoralsoShowcaseFornames) that imports what a browser cannot load (server-only,next/headers,next/server,next/cache, a Node built-in) or readsprocess.envpastNODE_ENV. Type-only imports and comments don't count, and live data through the app is fine.template_asset_not_packed: a file or folder a template loads withnew URL(…, import.meta.url)that does not exist, sits outside the package, or that npm leaves out of the package: byfilesin package.json (the note names a!entry that excludes it), or by a.npmignoreor.gitignoreline (the note names the line). Whatnpm pack --dry-runpacks decides; when npm cannot answer, an asset it may pack is listed underdata.exampleAssetsas not checked.
Contributors
Thanks to everyone who contributed to this release:
0.7.3
New Features
astryx buildnames the right block first far more often. It ranks every block in the catalog by what the request means, read from each block's own name, description, and component, so a block that word matching missed can still come first, with its own score and reason; and the block picker's fixed values are refitted on a larger, more varied set of written example requests, which helps most with requests worded in a product's own terms. A block the request names by its exact name, and a block from an integration, keep their place. The kit never lists more blocks than before, and its fields, page call, start template, and alternatives are unchanged.astryx searchputs the entry you are after first more often: it orders the matches inside each score band, every result keeps its match score and reason, and a query that is an entry's exact name still answers with that entry first (#7752).astryx doctor integration validateandastryx integration checkcheck the component names a package's docs and blocks give, and list what they find as notes beside validate's issues, each with its fix. Nothing counts a note andintegration check --strictdoes not fail on them; they become failing warnings in the next minor release:doc_name_mismatchlists a component doc whosenameis not the name the component is listed under when the module its printed import names (the doc'simport, the published subpath, or the package root) provably does not export that name, soastryx componentwould print a broken import. TheFix:proposes the file name when that module exports it, otherwise the component it exports. A name that module's exports cannot prove or rule out (a re-export from another package,export =, a destructured binding, a namespace, an import that resolves to no file, or, when no import can be resolved, a source that only exports a default) is listed as not checked, with the reason, in validate's newdocNamesreport.unknown_block_componentlists a name a template'sexampleFororcomponentsUsedgives that neither the package nor Core has (every docastryx componentresolves in Core counts) and the template does not import it. Imports the template's local helpers make count too, including through a barrel such asparts/index.ts. A name is judged only where the template reaches components solely through named imports and re-exports from Core, React, StyleX, local helpers read in full, or the package's own name (followed through itsexportslike a helper). Anything else is listed as not checked in validate's newblockComponentsreport: an import from another package, which may render other components; anydefaultbinding other than React's or StyleX's; a namespace import; an alias of or member read off an imported binding; a component held in a variable;require(); a dynamicimport(); a file that does not parse cleanly; a local module this check cannot read; and, without Core installed, any name only Core could resolve.
integration check --strictdoes not fail on anything listed as not checked.- New
@astryxdesign/cli/hostentry for tools that carry the CLI:runHostedCliruns the CLI once per process, with the command name that tool's users type (printed commands start with it) and, when the tool skipped the project's own CLI, the reason, so that CLI is never run.jsimport {runHostedCli} from '@astryxdesign/cli/host';const result = await runHostedCli({argv: ['search', 'button'],cliCommand: 'acme astryx',}); astryx doctor integration validatenow notes, from source and without a build, what an integration package tells apps to import that they cannot import, the way it lists an ignoredcliCommand. Each note is indata.notesand names its fix, such as the exactexportsentry to add. Notes are listed only: neitherdoctor integration validatenorastryx integration check --strictcounts or fails on them in 0.7.3, and they become failing warnings in the next minor release, so fix them now. It notes:- a component's import (the doc's
import, or the one the CLI derives when the doc has none) or a template's public import whose subpath package.jsonexportsdoes not declare, or that names another package. A subpath is not declared by a missing key, a key whose only conditions an ES module import does not load (such asrequireortypes), anexportsthat is a single string, a wildcard that does not match, or an emptyexportsmap; - a component example that imports a subpath the package does not declare;
- a template that imports a relative path outside the templates root, or a path its own package or Core does not export.
A subpath is judged from itsexportsdeclaration alone, never by its target file, soexportsmay point at build output that does not exist yet; whether that module exports the names an import asks for is the next entry's check. Wildcards and condition objects withimportordefaultpass. An import of a subpath whoseexportsentry has onlytypestargets, or that an ES module import reaches only throughtypes(such astypesbesiderequire), is never judged as a run-time import: it passes when it isimport type, when every binding is an inlinetype, or when every name it imports is one thetypesfile declares as a type, and is listed underuncheckedotherwise. Atypestarget underrequiredoes not count, and a package with noexportskeeps its deep paths to files it ships. What it cannot judge (in a package with noexports, a deep path into build output not built yet, such asdist/; a template import of Core when@astryxdesign/coreis not installed beside the package; every import of the package's own name when package.json has noname) is listed underuncheckedin a newpublicImportsreport on the result ({status: 'checked', findings: [], unchecked: [{file, specifier, reason}]}), whichintegration checkcounts as not compared.- a component's import (the doc's
astryx doctor integration validatenow also notes, from source and without a build, an import that names something its module does not export (indata.notes, each with its fix). These notes are listed only in 0.7.3 too, and become failing warnings in the next minor release. It notes:- a component's import (the doc's
import, or the one the CLI derives) that leads to a module that does not export the component, naming the subpath that does or theexportsentry to add; - a component example or a template that imports a name the package does not export;
- a template source with no default export (
astryx templatestill copies it, but its public import and anything that renders it get nothing), suggesting an exported PascalCase function, class orconst, never a hook such asuseAccount, a helper such asformatBalance, an ALL-CAPS constant or a type; with none, the fix stays generic.
A name is judged only when a file theexportsentry names is there to read in full.export *is followed, cycles included; a built module's declaration file (x.d.tsbesidex.js, and the.d.tsfiles itsexport *names) is read for the types it exports;export import Alias = Inner.Valuecounts as an export; TypeScript source resolves a./x.jsspecifier to./x.ts; and a declaration file that is a module exports every top-level declaration unless it has an export list,export *,export =or a default export of an expression, as TypeScript does. Whatever the reader does not fully model is listed underuncheckedin thepublicImportsreport instead of as a note: a file theexportsentry names that does not exist yet; a module whose list cannot be read in full (CommonJS,export *from another package); a declaration file with no import or export (a global script); a name missing from a JavaScript module with no declaration file, which may be a type; and every name it would report, other than a component doc's own component, while a TypeScript file in the package (outsidenode_modules) has a parseddeclare moduleblock for a relative path, the package's own name or a subpath of it, since that can add names to the module. The reason names that file;declare global, a wildcard spec such as'*.css', another package's name and adeclare modulein a comment do not count, and a file withdeclare modulein its text that cannot be parsed counts.astryx docs authoring/ship/checksexplains each check.- a component's import (the doc's
- A failed
astryx component,templateordocslookup lists the entry you most likely meant first. Components that tie on match score are ordered by how early the name you typed appears in their keywords and by how close their names are, instead of alphabetically; among the suggestions offered, a component one of whose other names was typed (including another library's name for it, such asMUI TextField, with or without the library's name) comes first; a compound name that does not exist (a family part named with other words, or without one of its family's words) suggests the real part or its family. Templates are ordered by how closely their id or title matches the name you typed, and unknown docs routes by how closely the route matches. Suggestion lists never get longer, every suggestion is a real entry, and a name that resolved before still resolves to the same entry. - Integration docs that tell readers to run an Astryx command through a package runner now get a
runner_commandnote fromdoctor integration validate(and sointegration check) indata.notes, with its file, line and the bareastryx <command>to write instead. A note fails nothing, sointegration check --strictexits as before. The unscoped name after a download runner (npx astryx) always counts, because it fetches an unrelated package; the scopednpx @astryxdesign/cli, for install steps, does not.
Fixes
astryx buildstarts from a page template its word weights do not list (an integration's template, or one added since the weights were fit) only when the request names as many words of that template's own display name, category and keywords (search's stopwords aside) as of the best listed template, or names that template's family (the first part of its category) before the listed template's family and at most two fewer of its words; otherwise it starts from that listed template and offers the other as the first alternative.- The CLI finds the project's
@astryxdesign/corefrom any folder inside the project, socomponent,hook,build,search,swizzle,theme targetsanddoctornow work five or more folders deep, in workspace members whose Core the workspace installs at its root, and in Yarn Plug'n'Play projects. They still search the folders they searched before, and past them continue up to the workspace root of the nearest folder whose package.json declares an Astryx package.upgrade --fromrun from any folder in a project upgrades that project: the nearest folder whose package.json declares an Astryx package or that an Astryx workspace lists, found without passing a repository root or counting the home folder. It targets only the project's own Core (the one in itsnode_modules, or for a member its workspace lists, the one the workspace installs), scans the project'ssrcby default, reads a--pathyou type from the folder you ran in, names the files in its--jsonresult relative to that folder, refreshes the project's agent docs, and names the project root and the source folder it scans before it changes anything. With no such project,upgradereads only the current folder, as before.- An
upgraderun in a folder that installs Core but declares no Astryx package now upgrades the Astryx project above it instead of that folder alone, since such a folder was never a separate upgrade root. To keep a sub-folder that installs Core its own project, declare an Astryx package in that folder's package.json. - A
packages/corefolder that holds another package is no longer read as Core, and an integration named inastryx.confignow loads when the workspace installs it at its root, as an autolinked one already did.
- The CLI's install advice no longer adds a package to a
package.jsonthat is not an Astryx project's. This covers the daily hint, the setup reminder, the update notice,astryx doctor's version-alignment and integration fixes, andastryx discover's install command for an integration installed for the computer. The project is the nearest folder whosepackage.jsondeclares an Astryx package, or a member its workspace lists, never the home folder and never past a repository root.- From a folder inside such a project whose own
package.jsonis not the project's, such as a tool folder that installs its own@astryxdesign/core, the daily hint that matches a project's CLI to its Core, the setup reminder andastryx doctor's version-alignment fix used to name a command that added the CLI to that folder'spackage.json, making it a separate Astryx project. They still compare the CLI with the Core the run reads, and when the two differ they say to run from the project's folder, or to declare an Astryx package in that folder; the update notice upgrades the project from its folder, with the project's release. - For an integration installed for the computer,
astryx discovergives no install command from such a folder, andastryx doctor's fix says to run from the project's folder, where the command adds it for the project; in a folder that belongs to no project, neither names a command. - In a folder that belongs to no Astryx project, the hint, the setup reminder and the update notice no longer print, and
astryx doctor's fix says how to reach a project. - Unchanged: the official packages
astryx discoverlists and the theme packagesastryx doctorsuggests still use the folder the command runs in; a member its workspace lists keeps its own advice; in a folder whosepackage.jsondeclares an Astryx package, the advice is the same. No JSON shape or exit code changes.
- From a folder inside such a project whose own
astryx doctor integration validate,astryx integration checkandastryx integration verifycatch more package mistakes, and each new finding ends in aFix:that clears it. Findings that 0.7.2 did not fail on are listed as notes beside validate's issues, which nothing counts, until the next minor:- Two docs for one component (
AcmeWidget.doc.mjsandAcmeWidget.doc.js) are listed asduplicate_component_doc, naming the one read; discovery now always reads the same one. - A component doc whose file name differs from its source only in letter case is one finding that says which file to rename: an error where the pair fails (Linux), a listed
source_without_component_docwhere it still pairs (a case-insensitive disk); a hidden doc that does not pair keeps the source warning it had. - A root reached through a symlinked folder is listed as
symlinked_root: npm pack does not follow it. - An absolute root says roots are relative and gives the relative path; a root that is a file is reported by every check instead of crashing it.
- A package.json without
nameorversionis listed with a fix, instead of a crash;verifyfails on it. A package whosenameand manifestproviderIdgive no provider ID is listed asno_provider_id. - A contribution file Astryx cannot read is listed as
unreadable_file, before npm pack fails on it.
astryx integration check --strictdoes not fail on these pairing, root and package.json notes either; they become failures in the next minor.astryx integration verifystill fails on a package.json npm cannot pack.- Two docs for one component (
astryx doctor integration validate,astryx integration checkandastryx integration verifysay more plainly what is wrong in findings they already reported, and how to fix it:- An empty doc or manifest, or one with no default export, says so and names what it does export, instead of "(root): Invalid input".
- A manifest key one or two letters off a known key asks "did you mean
components?" before suggesting a newer CLI. - A theme descriptor named for the built file (
ocean.doc.mjsbeside a builtocean.jsthat lacks theoceanexport) says it must share its stem with thedefineThemesource, naming that source when the built module'sSource:line or the source'sdefineThemename confirms it. - A template doc with no source, a theme descriptor with no source, a theme source with no descriptor, and a component whose source is
.jsxget aFix:. - A theme source named for its theme (
brand.ts) beside the module the build writes (brand.js) is told to take thebrandThemestem. verifynames packed files by their path in the package, not the scratch copy's; says npm pack does not follow a symlinked root instead of asking for afilesentry; and, when a theme'sdefineThemename differs from the files its package exports, says a rebuild writes files under the new name.
- Integration authors now learn when the running CLI is outside their package's
@astryxdesign/clipeer range:astryx doctor integration validateandastryx integration checklist acli_peer_versionnote naming the package, the range and the running version. Below the range the note gives the project's commands to install a newer@astryxdesign/coreand@astryxdesign/clitogether (as dev dependencies in the package's own folder) and then runastryx upgrade --from <version> --apply. Above the range it asks for a release of an installed package that supports this CLI, or asks the author of the package in the current folder to test with this CLI and widen the range. A note fails nothing:--strict,integration verify,doctor, and exit codes are unchanged. astryx component <Member> --package @astryxdesign/corenow answers with that member, as the unscoped lookup does. A Core component documented in its family's doc (HStack and VStack in the Stack doc) used to come back as the family doc, named after the family and with no props.- The agent guide that global mode writes to the home folder now tells agents to deliver a page built with Astryx, not only how to find things. Before, agents that found the right template could still build the page with a tool that cannot install packages and deliver a page with no Astryx in it. The guide now tells agents to work in a project folder (creating one if there is none); add
@astryxdesign/coreand@astryxdesign/clito a new project or one without Core, or, in a project that already has@astryxdesign/core, the CLI at the same version; runastryx initthere; follow the same template-first workflow and self-check the project agent docs give; and end by building the project and delivering that build. The guide stays version-free and names only commands every release keeps. The project agent docs are unchanged, and so is what@astryxdesign/core's install script prints: its copy of the shared agent-docs file only gains the same workflow lines. - Agents that follow the guide global mode writes to the home folder now know what to do when
astryxis not found: run the command that installed the CLI for the computer first, with the same package manager and folder, such asnpm i -g @astryxdesign/cliorpnpm add -g @astryxdesign/cli. On machines that keep the home folder but reset system folders on restart, the guide outlived the CLI installed for the computer and told agents to run a command that was gone. Outside a project, when the guide namesastryxand noastryxcommand is on the search path, apart from a package runner's own copy,astryx doctornow says so and names the install step the guide records, or npm's when it records none. The global-mode guide for CI and containers explains how to keep the CLI across restarts. A guide written for a host's own command is unchanged. No JSON shape or exit code changes. - The butter, stone, and y2k themes no longer show the secondary hover fill on a disabled
ComplexSelectortrigger, whether the trigger is natively disabled or exposesaria-disabled="true", the focusable form every disabled control now uses. Before, the guard only recognized a natively disabled trigger. The themesastryx theme ejectcopies carry the same guard. - Apps that use Core's prebuilt CSS without a StyleX build step now get the default data colors: the prebuilt CSS defines the canonical
dataVarsdefaults, so compiled imports and raw CSS references paint correctly. astryx initwrites the agent docs at the project root, in files the project commits, so Codex, Gemini CLI, Copilot CLI and Claude Code all read the block from the project root or any folder below it (#7497). It no longer writes agent docs into a project's subfolder, the home folder, or a settings folder in it such as~/.gemini.AGENTS.mdholds the block, created when missing. Before, a project with onlyCLAUDE.mdgot the block only there, so Codex and Gemini CLI never saw it.- Claude Code skips
AGENTS.mdin a folder that has aCLAUDE.mdor.claude/CLAUDE.md, so the Claude Code file the project already has keeps a full copy: rootCLAUDE.md, else.claude/CLAUDE.md. It keeps the copy even when it importsAGENTS.md, because Claude Code does not follow that import in a session started in a subfolder; started at the root, Claude Code then reads two. When both exist, the copy goes in rootCLAUDE.md, which projects commit even when they ignore.claude/, and a block in.claude/CLAUDE.mdis removed. Init creates no Claude file.astryx upgraderefreshes every copy, except in a project at the top of a home settings folder (see the next entry). - Gemini CLI reads only
GEMINI.md: init adds a one-line import,@./AGENTS.md, creatingGEMINI.mdwhen it is missing. It adds none whenGEMINI.mdalready importsAGENTS.md, inline or on its own line. It adds the import even when the project's.gemini/settings.jsonhas Gemini readAGENTS.mdthroughcontext.fileName: Gemini loads those settings only when it starts at the project root, so a session started in a subfolder would otherwise get no copy. Started at the root, Gemini then reads two. - The project root is the nearest folder at or above where init runs whose
package.jsondeclares an@astryxdesignpackage, else the nearest with anypackage.json. The search stops at a repository root and never counts the home folder. With nopackage.jsonfound, init writes where it runs, as before.docsWrittenstill lists each file relative to where init ran, for example../../AGENTS.md. - A
GEMINI.mdthat resolves outside the project, for example a link to a shared file, is skipped and reported indocsErrorwith one note (not an error line), in the default layout and in a project's own layout; the rest is written and init exits 0. - The managed block belongs to Astryx: init and
astryx upgradewrite, refresh, and remove only the block, whatever ignore rules or generated markers say, as 0.7.1 did, and never change the text around it. Every write stays inside the project: run in the folder 0.7.1 wrote, an agent file 0.7.1 wrote there whose path leaves the project still refuses the run with exit 1. The project's Claude Code file (rootCLAUDE.md, or.claude/CLAUDE.mdwhen there is no root one) that resolves outside the project and is a block-less import of an existingAGENTS.md, which 0.7.1 left alone, is skipped and reported indocsErrorwith one note, and init exits 0. Run from a folder below the project root, where 0.7.1 wrote in that folder instead, a project-root file whose path leaves the project is skipped and reported indocsErrorwith one note, the rest is written, and init exits 0. - While root
CLAUDE.mdis untracked and ignored by the repository's ignore rules (any ignore file from the repository root down, such as a monorepo's root.gitignore, the local exclude file, or configured excludes; init asks git, Sapling or Mercurial), a.claude/CLAUDE.mdthe project commits gets the copy too, so a fresh clone still gives Claude Code a copy;--agent claudeand--agent allwrite it there as well. A file the repository tracks counts as committed whatever the ignore rules say, as git and Mercurial ignore only untracked files, and when the repository cannot answer, the copy is kept, on the first run as on later ones. Such a copy that resolves outside the project refuses the run with exit 1 where 0.7.1 wrote it too; one 0.7.1 did not write (the one--agent claudeadds, or a block-less import of an existingAGENTS.md) is skipped and reported indocsErrorwith one note, and init exits 0. So is a.claude/CLAUDE.mdwhose block--agent claudewould remove beside aCLAUDE.md, since 0.7.1'sclaudepreset wrote onlyCLAUDE.mdthere. Beside a committed rootCLAUDE.md, with.claudelinked outside the project, three cases that 0.7.1 refused now exit 0 with nothing written: the default with a.claude/CLAUDE.mdof plain text, and--agent allwith one of plain text or a block-less import ofAGENTS.md; rootCLAUDE.mdholds the copy, so no write leaves the project. In a project that keeps its own layout, aGEMINI.mdthat imports no agent file now gets a copy, as the other agent files do. - The copy in
.claude/CLAUDE.mdis removed only once rootCLAUDE.mdholds the same block, and only the managed block between its markers: the rest of the file stays, and the file is deleted only when nothing but whitespace is left.astryx init --remove-agentsdeletes a file it created only when nothing but whitespace or init's own heading is left; 0.7.0 also deleted a file whose remaining text had a heading and any line with the word "guidance". astryx init --remove-agentsremoves the block at the project root, whereinitwrites it, and in the folder it runs in. Run from a subfolder, it removes whatinitwrote at the root, and a block an earlier version left in that subfolder; a root agent file with a block that resolves outside the project is left as it is with a note, and the run exits 0, as 0.7.1 did when it touched only the subfolder. Exit codes and the JSON shape are unchanged.--agent claudeand--agent allnever leave a block in bothCLAUDE.mdand.claude/CLAUDE.md, unless the project ignoresCLAUDE.md: whenCLAUDE.mdgets the block, a block in.claude/CLAUDE.mdis removed.--agent allkeeps theGEMINI.mdimport. The--agenthelp and the working-with-AI guide say so.--agent-docs-pathwrites where init runs, as before.astryx doctorfails when theGEMINI.mdimport points at anAGENTS.mdwith no block. The setup check in the CLI and in@astryxdesign/coreno longer counts that import as set up, and looks atGEMINI.md. The reminder to runinitthat commands print looks at the project root too, so it stops onceinithas run in a nested package.
astryx initandastryx upgradeno longer write agent docs into your home folder, or into a settings folder in it such as~/.geminior~/.claudeoutside a project. Agents read the files in those folders in every project, so a block there reached unrelated work. This follows the CLI's existing rules that no command writes agent docs into those folders and that a write outside a command's own folder is refused before anything is written.- Refused by
init: the home folder itself, and the top of any folder in it whose name starts with a dot (every such folder is a settings folder), even when it holds apackage.json. A folder below it with its ownpackage.jsonis a project and is set up normally, such as an agent worktree in~/.codex/worktrees/or~/.cursor/worktrees/, andastryx upgraderefreshes it. With--agent-docs-path, each file's own folder is checked: from the home folder,notes/AI.mdis written as before, whileAI.mdor.claude/CLAUDE.mdis refused. - What
initdoes instead: it writes no agent docs, reportsdocsErrorasinstall-failedwith the reason, and exits 0, as before. - Refused by
upgrade: refreshing a block in a project whose root is the home folder or the top of a settings folder, such as~/.dotfileswith apackage.json, with or without--apply. It leaves the block as it is, setsagentDocs.actiontoerror(neverwould-refresh), and warns with the folder and why; its other steps and its exit status are as before. With no block there, it gives the same reason instead of suggestingastryx init.astryx doctor's agent-docs fix does the same, and the setup reminder after each command stays quiet. - Migration: run
astryx initfrom the project's own folder, or add the block to the file by hand. Move a project rooted at the home folder or a settings folder into a folder of its own, or update or remove its block by hand. To remove a block an earlier version wrote into~/.claude/CLAUDE.md, runastryx init --remove-agentsin the home folder.
- Refused by
- Repeated searches in one process answer faster:
astryx searchreuses its entry index while the catalog is unchanged, and ties that reuse to one list of the fields the index reads, so the index is never reused after any of them changes. Every answer is unchanged. - Tools that bundle the CLI into a server function no longer pack their whole project folder into it: one path in
integration check's import checks was built in a way file tracers cannot follow. The path and its results are unchanged. search()from@astryxdesign/cli/apianswers faster when one process searches again: it reuses the components, docs, templates and themes it gathered for the same folder andtypewhile no file it read, and no folder it listed, has changed since (a linked workspace package included). To see those reads, the first such search in a process wrapsnode:fs's read functions for that process; outside a search they behave exactly as before. Results are unchanged. Short-lived runs are unaffected: eachastryx searchcommand gathers once, as before (#7830).astryx searchandastryx buildfind a block by its authored display name when that name has two words or more and holds every word of the component the block shows: a query naming it, such as "rich text editor" for an integration's Rich Text Editor block, ranks it first. A display name that labels only the variant, such as "Inside a card", is not read.
Documentation
astryx docs cli/commands/postinstallnow documents the hiddenpostinstallhook,astryx docs cli/commandslists it, andastryx postinstall --helpshows its exit code and an example. The summary ofastryx docs cli/commands/manifest(text and--json) drops its final period, so it matches the description the manifest has always printed. What each command prints when it runs, its JSON and its exit codes are unchanged.- Everything an integration author reads now lives under one home,
astryx docs authoring: the integration guides' routes moved fromcli/integrations/…toauthoring/…(for example,cli/integrations/quick-startis nowauthoring/quick-start), beside the field reference atastryx docs authoring/field-reference.astryx docs authoring <name>still opens one field reference section, and an oldcli/integrations/…route's error names its new route. The loose topics now sit in Guides or Foundations instead of Unorganized, under the same names:astryx docs getting-startedstill opens, and its Up isastryx docs guides. - A new guide,
astryx docs is-my-code-good, checks component use, icons, custom styles, layout, assets, and code health from source and rendered evidence, in one page you can share. It includes an agent prompt and requires missing evidence to stay visible. The template grading rubric now links each category to these shared criteria instead of repeating them, and keeps its own weights, counting rules, and version 1.4. - Questions like "add an integration" or "install a package" now find a guide for app builders first.
Added a "Use integrations" guide (
use-integrations.doc.mjs) that covers discovering, installing, and using integration packages in an app; open it withastryx docs use-integrations. Search ranks it above authoring and API-function docs for those questions, while queries like "build an integration" still rank authoring content first.
Contributors
Thanks to everyone who contributed to this release:
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: