What's New
Release notes and changelog for all packages.0.4.4
New Components
- Promote
BottomSheetandBottomSheetSwitcherfrom the canary-only Lab package to Core. The stable package now includes their existing native-dialog, drag-detent, transition, and mobile-keyboard behavior, plus Core documentation and examples (#5080).
New Features
astryx template --cdnwrites a working no-build-step CDN starter page (#5068). A CDN starter is a template, so it joins the template family beside--skeletonrather than claiming a top-level command. It is a flag and not the positionalastryx template cdnbecause the positional resolves against everythingdiscoverAll()finds, where acdnid would shadow a discovered template.cdn.template.htmlloads Astryx from jsDelivr and esm.sh with no bundler, no install and no build step, with every CDN URL pinned to the Astryx version you have installed — an unpinned CDN URL resolves to whatever is latest and is cached hard, so a page written today breaks tomorrow without being edited. An existing file is never clobbered;--overwritereplaces it, and--jsonreturns the receipt.The annotations are the things that are load-bearing and silent when missing:?external=react,react-dom(without it esm.sh bundles a second React and every hook throwsCannot read properties of null (reading 'useState')),react/jsx-runtimein the import map (the published bundle imports it; omitting it fails the page withFailed to resolve module specifier), and afont-familyonbody(nothing in the stylesheets sets a document font, soButton— which isfont: inherit— otherwise renders its label in the browser's default serif).Three more lessons came out of building a real app on it. The page now<link>s the theme's webfont from Google Fonts, because the theme names Figtree and never loads it, so every viewer silently got the fallback stack (#5015 again). It imports the theme OBJECT and wraps in<Theme theme={neutralTheme} mode="system">, so light and dark follow the OS — thedata-astryx-themeattribute alone scopes the stylesheet but cannot switch modes. And#root:emptycarries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup ishtm, with a comment saying it is optional andcreateElementis the dependency-free alternative.A recipe that is only read is a recipe that is only assumed to work, so CI renders it:.github/scripts/cdn-template-smoke-test.mjsscaffolds the page with the real CLI and opens it in headless Chromium, failing on any console error, page error or failed request, and on a page that loads without rendering.astryx theme buildtakes any number of theme files —astryx theme build themes/*.tscompiles them all in one process, so an app with several themes no longer hand-rolls a loop that re-enters the CLI once per theme. Outputs are byte-identical to the serial invocations; the run stops at the first failure and names the theme that failed. The CLI's Node floor (>=22.13) is now declared inengines, so a package manager can enforce it at install instead of the build failing later (#5121).defineTheme:color.accentaccepts a[light, dark]tuple (#2279)ColorScaleConfig.accentnow takes either a single hex or a[light, dark]tuple, matchingTokenValue. With a tuple,expandColorScalederives the light half of every generatedlight-dark()pair from the light seed's palettes and the dark half from the dark seed's, so each scheme gets a consistent derived palette (muted, on-accent, neutrals) instead of thetokens['--color-accent']workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence betweencolorandtokensfor accent-derived values:tokensentries win token by token, thevar(--color-accent)reference tokens follow a--color-accentoverride at runtime, and the baked--color-on-accentstays derived from thecolor.accentseed.
Fixes
- Bottom Sheet showcase block: the filter checkboxes are interactive again (#5157).
CheckboxInputis fully controlled —valueis required and the input only moves when the owner updates it. The showcase passed a literalvalue={false}with noonChange, so the three filters ("In stock", "On sale", "Free shipping") rendered but could never be toggled: on the docs site the first thing a reader tries in a Bottom Sheet does nothing, and anyone copying the block inherits three dead controls. Each filter now has its ownuseStateandonChange, matching the checkbox wiring already used in the Bottom Sheet Switcher showcase. - An integration whose manifest fails to load is no longer silent. A manifest that throws on import — the common case being one still calling a
create*authoring factory, removed in 0.3.0 — contributes nothing, and the CLI treated that as if the package had never been configured:astryx discoveransweredNo integrations configured.whileastryx.config.mjsplainly configured one, and no command said a word. The only way to find out was to already suspect it and runvalidate-integrationby name. A configured integration could remain invisible to CLI discovery, leading an app team to conclude that its components did not exist (#5119). The load error now counts as an integration issue, so the existing one-line stderr nudge fires oncomponent,templateandupgrade, anddiscover— the command whose whole job is listing integrations — nudges too, as doessearch.discoveralso stops reportingconfigured: falsefor a project that configured an integration that failed to load; the empty state now distinguishes "you configured nothing" from "what you configured contributed nothing", which is the distinctionmeta.configuredwas introduced to carry.Nothing becomes fatal: the warning is best-effort, stderr-only, suppressed under--json, and never changes an exit code. Broken contributions are still skipped exactly as before.
Contributors
Thanks to everyone who contributed to this release:
0.4.3
Fixes
- The unloaded-font advisory is a notice, not a warning. A theme file cannot load a font — Astryx sets
--font-family-*and loading is the app's job — so #5045's advisory fires on any theme naming a webfont, including a perfectly correct one. As a warning that made a clean build read as defective, and it put the shipped template permanently in violation of its own "compiles with no warnings" guard (#5079 had to allowlist the template's two font names in that assertion). Thetheme.buildreceipt now separates the two:warningsare defects the author should fix,noticesare advisories about a correct theme. The font advisory moves tonoticesand to stdout with the rest of the build's progress; stderr stays for defects. The template guard is back towarningsbeing empty, and no longer needs to know which fonts the template names.Programmatic callers readingdata.warningsfor font advisories should readdata.notices; the message text is unchanged. extendsnow reaches the CSS. A theme that extended another built a stylesheet holding only the declarations it stated itself: the base's tokens, component overrides and surface rules were all absent, and because each theme is@scoped to its owndata-astryx-themevalue, loading the base's stylesheet alongside could not fill the gap either. Every consumer of an inheritance chain silently got stock geometry, elevation and type with a new palette painted over it (#5067). Nothing warned; the loss only showed up by diffing two generated stylesheets token by token. The cause wastheme buildshadowing its own inputs. It writes<name>.jsnext to<name>.ts, and the loader resolved a plain./<name>specifier to that generated artifact before the source — so the second build of a family read the artifact, which carries nocomponentsand exports<name>Themerather than whatever the source exports. A named import that missed becameextends: undefined, anddefineThemetreated an absent base as no base at all. The loader now resolves source extensions first, which is also the resolution the author's TypeScript sees, so the CSS a build emits matches the theme that type-checked.Three things behind it are fixed too, so the failure cannot come back by another route.defineThemethrows whenextendsis present but is not a theme, naming the likely cause, instead of inheriting nothing — the one behavior change here, and it turns a silent stylesheet into a build error. A theme'sonDark/onLightsurfaces and its__inputTokensare now inherited like its tokens and components were, so a child no longer reverts its base's inverted-surface customizations to the defaults or loses its[light, dark]tuples. And a built theme module now carries the resolvedcomponentsand surfaces alongside its tokens, so extending one — the./builtsubpath every shipped theme exposes — is no longer lossy.theme buildalso stopped hand-picking fields when it re-resolves a plain object theme file, which droppedextends,colorandsyntaxon the way in.An extended theme is flat: everything it inherits is resolved into its own output, and its stylesheet stands alone. Measured on a 14-theme family (one base, 13 palettes extending it): each palette went from 25 custom properties and no component rules to the base's full 175 and 70, with its own colours still winning.
Contributors
Thanks to everyone who contributed to this release:
0.4.2
New Features
astryx theme buildwarns when a theme names fonts it does not load. The resolved--font-family-*tokens and component-overridefontFamilyvalues are checked against CSS generics and known system families; anything else gets one warning per family in the receipt and, after the install instructions, the<link>/@font-facesnippet to add.astryx docs typographygains a Loading Custom Fonts section (Google Fonts and self-hosted recipes,font-display: swap, real fallback stacks), and the theme docs' production-build section points at it (#5015).astryx theme templatewrites an annotated theme template into your project (#5048). New sibling oftheme add: whereaddstarts you from a theme we ship,templatestarts you from a blank annotated one.astryx init --features themecalls the same leaf, so project setup writes it too — it previously printed a one-line hint and wrote nothing, which is the weakest form of the help a theme author needs, since the first problem is not knowing the command but not knowing what the theme surface contains. The file istheme.template.ts: everydefineThemefield with a note on when to reach for it, the token families, the component override syntax, and the consumption steps (providing the theme, loading the fonts you name, building for SSR), each section naming the CLI command that prints its authoritative reference. An existing file is never clobbered.This came out of a vibe test (#5047): agents given an annotated template reached twice as far into the theme surface as agents given only the docs (17 component targets vs 8, and the only arm to use interaction states, custom variants andonDark), and shipped a third of the contrast defects.A template that lies is worse than no template, so its claims are machine-checked against live sources rather than trusted:scripts/check-theme-template.test.mjsfails when adefineThemefield is added and left undocumented, when a token family is missing from the inventory, when a CSS variable or component key it names does not exist, when it cites a docs topic that does not, or when a theme source drops its SYNC reference.theme buildcompiles it warning-free in CI, and the CLI typecheck now covers it.
Fixes
- Heading's
typeis a documented theming target, and the docs stop teaching a CSS variable that does not exist (#5016).Headingreflectstypeas a theme selector —typography.scalegeneratesheading: {'type:display-1' …}rules for it — buttheming.targetslisted onlylevelandcolor, soastryx theme buildwarnedUnknown prop "type" on component "heading"on every theme that sets a type scale, including the shippedneutralTheme. The drift guard missed it twice over: it read a conditional spread ({level, color, ...(type && {type})}) as an unknown bag, and it only checked a component against a doc file in its own directory, soHeading/— documented fromText/Text.doc.mjs— was never checked at all. Both are fixed, which brings three more previously unchecked directories under the guard.Separately, the theme docs' component-override example set--button-press-scale, which no component defines: copying it produces CSS that silently never applies. It now sets a real public var, and the example no longer declares the samebuttonkey twice. - Two guards left failing on
mainby their own landings, so every PR since has been red through no fault of its own. #4963 gave Thumbnail's remove button a coarse-pointer hit-area var and did not document it, which the derived-var guard reads as an undocumented private var; the var is aninseton a::afteroverlay, so it is documented as private and listed alongside the other vars no standard CSS property maps onto. #5026 movedborderDefaultsintoCoreTokenName— the landing the theme-template guard was explicitly waiting for (its comment says "when #5017 lands, this guard starts requiring the template to cover it") — so the template's token inventory now names--border-width.
Documentation
- MobileNavToggle preview simulates a mobile AppShell instead of an empty stage: new playground.appShellMobile for components that render nothing without AppShell mobile context (#4983)
Contributors
Thanks to everyone who contributed to this release:
0.4.1
Fixes
astryx theme buildno longer warnsUnknown propfor documented state override keys. Component docs declare state-driven selectors undertheming.targets[].states(radio→checked/disabled,calendar-day→today/selected, …), but override validation only loadedvisualProps, so the state syntax the Theming Infrastructure wiki documents —components: {radio: {checked: {...}}}— warned on every build. The CSS was always generated correctly; only the warning was wrong. 30 targets across core were affected (#4778).
Contributors
Thanks to everyone who contributed to this release:
0.4.0
Breaking Changes
- DropdownMenu's two item modes are peers again. Compound mode gains a
DropdownMenuDividercomponent (aliased asContextMenuDividerandBreadcrumbMenuDivider), which the data path also renders, so{type: 'divider'}and<DropdownMenuDivider />produce identical DOM, spacing, and theme target. Data mode gainsendContentanddescription, so anitemsrow can carry a shortcut hint or secondary text without dropping to compound mode. Itslabelwidens fromstringtoReactNode, matching compound mode: the narrowing existed only because rows were keyed by label, and they no longer are (#4953). The bare names now belong to those components, so the data-mode option types take theDatasuffix their siblingDropdownMenuItemDataalready carries:DropdownMenuDivider→DropdownMenuDividerData,ContextMenuDivider→ContextMenuDividerData,BreadcrumbMenuDivider→BreadcrumbMenuDividerData. TypeScript cannot re-export a value and a type under one name from a single barrel, so the rename is what makes the components exportable at all. Runastryx upgrade --applyto rewrite the type imports; a missed one fails at compile time rather than silently.
New Features
- Add the
migrate-table-rowexpansion-to-treecodemod (runs onastryx upgrade): rewrites the removeduseTableRowExpansionStatetree pattern touseTableTreeState+useTableTreeData. Detail-panel usage (renderExpanded) is left untouched. (#4884) - Add a self-documenting layer to the CLI: typed, colocated
.doc.mjsfor every command, every@astryxdesign/cli/apifunction, and every authored schema (config, integration, codemod, the response envelope, and the doc-types themselves). Adds theFunctionDoc,SchemaDoc,CommandDoc, andEnumDocauthoring types with sealed parsers. (#4714) Every command's--helpand itsastryx manifestentry are now built from that command's colocatedCommandDocvia adefineCommandconverter, so the docs and the CLI can no longer describe different things. The migration is behavior-preserving: help text, command output, error paths, and exit codes are byte-identical.The CLI README's command, error-code, and response-type tables are now generated from the manifest and theEnumDocs, correcting real drift — the error-code table listed two codes that do not exist and omitted several that do, and the command table was missingblog,build,layout, andvalidate-integration.Kept honest by a drift harness (docs vs the live CLI),check:cli-structure(each doc-type andapi/leaf ships its full file set), and lint rules for the CLI's layering. - Add themeable indicators — the componentized check, checkbox, and radio visuals.
defineTheme({indicators: {check: RadioIndicator}})replaces one by name, and every component drawing it follows. (#4712) Theme targets now follow the component-name convention:checkbox-indicator,radio-indicator,radio-indicator-dot. The old names (checkbox,radio,radio-dot) remain emitted on the same element so existing themes keep working. New themes should use the canonical names; deprecation does not set an automatic removal deadline.Migration: menu radios use those shared targets now.dropdown-menu-radio-dotis removed — targetradio-indicator-dot;astryx upgraderewrites it for you.
Fixes
- The generated agent cheat sheet hardcoded a shell recommendation ("Full page → AppShell; sidebar nav → SideNav", "pick the shell (AppShell / Layout+LayoutPanel)"), which answers a question that depends on the app archetype and duplicates guidance
astryx docs layoutalready maintains. The two layout rules now send agents to that doc instead, so shell choice, region budgets, and the responsive contract have one source of truth. (#4772) The rule cites the command rather than the docsite URL, in the block's establishedastryx <cmd>form that the header maps to the project's real invocation (pnpm exec astryx,npx @astryxdesign/cli, …).astryx docsreads the docs shipped inside the installed version, so an agent can't be shown an API that release doesn't have. - The
migrate-grid-minchildwidth-to-columnscodemod bailed without changes when a<Grid>had bothcolumnsandminChildWidth, leaving the now-invalidminChildWidthprop in place and failing type-checking on 0.3.0. (#4792) Whencolumnsis a numeric literal, it now migrates losslessly to the 0.3.0 object form. This mirrors the old (0.2.0) Grid runtime, whereminChildWidthdominated and the numericcolumnscapped the column count underauto-fit:<Grid columns={3} minChildWidth={280}>becomes<Grid columns={{minWidth: 280, max: 3, repeat: 'fit'}}>. Object or dynamiccolumnsvalues remain a deliberate bail. - The documented
hookexample referenceduseToggle, which is not a hook in the design system — running it failed withERR_UNKNOWN_HOOK. It now usesuseFocusTrap. (#4742) This shipped in two places a consumer sees:astryx manifest --json, which agents read to learn the CLI, and thehookCommandDoc that feeds--help. Replaced in both. - CLI internals: a true
foundation/bottom layer, and generated./authoringtypes (#4736).foundation/no longer importsapi/, and ESLint now enforces that direction alongside the existingauthoring/andapi/rules. Two things were reaching upward:Projectpulled template discovery out ofapi/template, whose adapter importedProjectstraight back, and bothProjectandintegration-warningsimportedvalidateLoadedIntegrationfrom thevalidate-integrationcommand. Neither was misplaced logic, just misplaced files — the adapter now lives atfoundation/discovery/template-adapter.mjsand the validators atfoundation/integrations/validate-contributions.mjs. To be precise:Projectand the template adapter still import each other, so that module cycle remains, contained within foundation instead of spanning two layers. Behavior-preserving — the CLI's observable surface is byte-identical across 84 invocations.The published./authoringtype declarations are now generated from their JSDoc instead of hand-written, the same way./apialready works. The 13 hand-maintained.d.mtsfiles are gone;scripts/sync-api-types.mjsemits both trees atprepack, stamped@generated. A hand-written declaration shadows the JSDoc in its.mjs, so it could disagree with the implementation and still compile — and both failure modes had shipped: a missing declaration made a strict consumer resolve that parser asany, and a staleparseDocreturn union silently droppedSchemaDoc,CommandDocandEnumDoc. Also fixesparseFunction, a bare re-export ofparseHookthat publishedHookDocinstead of the generalFunctionDoc. - Scaffolding a template that references demo video (e.g.
LightboxVideo) no longer replaces the video source with the image placeholder data URI, which the generated<video>element couldn't play.stripTemplateAssetRefs()treated every demo-media reference as an image regardless of extension; video extensions (.mp4,.webm,.mov,.ogv) are now stripped to an emptysrcinstead — there's no equivalent self-contained inline placeholder for video, so the scaffolded example is honest about needing the builder to supply their own file rather than pointing at something that can't play. (#4863) - Stepper templates: the scaffolded Stepper blocks gain the a11y, theming and responsive-label hardening from the component audit, and their doc blocks match what they render (#4917).
- cli: add
theme build --icons-specifierso the generated module's icon import can be fully specified (#4620) The generated theme module imports the icon registry rather than inlining it, because the registry holds React elements.astryx theme buildscraped that specifier out of the TypeScript source and emitted it verbatim, so./icons— valid TypeScript, invalid ESM — reached the generated.js. Every published theme's/builtentry therefore failed to load in Node, including under Vite SSR and Next.js Pages Router, while bundlers papered over it by guessing the extension.No single extension is correct: the same source compiled by tsup lands aticons.mjsin a package with no"type"field and aticons.jsin one with"type": "module", and the generator runs before the compile step that produces either. The caller knows; now it can say so. Without the flag the specifier is emitted unchanged, so the default no---outflow — where the neighbour is an uncompiledicons.tsxthat only a bundler can resolve — is unaffected.The seven theme packages now declare--icons-specifier ./icons.mjsin their build scripts.
Other Changes
- The scaffolded login pages use
Center'spaddingprop instead of a hand-writtenvar(--spacing-6)style object (#4764). - Self-host template demo imagery in the repo instead of streaming it (#3973)
from the internal
lookaside.facebook.comCDN. - Template demo images are now committed under
apps/docsite/public/template-assets/and referenced by root-relative/template-assets/*paths (previously Meta-internal CDN URLs invisible to external contributors). stripTemplateAssetRefsstill swaps these paths for the inlinedata:URI placeholder on scaffold, so generated projects render with zero setup and no network dependency — no image is ever copied into a scaffolded project.
Contributors
Thanks to everyone who contributed to this release: