What's New
Release notes and changelog for all packages.0.1.5
New Features
- Add a v0.1.5 upgrade codemod that renames
labelSpacing="default"tolabelSpacing="hug"on Switch. (#2889) - New
incident-consolepage template: an on-call incident response console demonstrating the frame-first tracker archetype — grouped dense incident rows (StatusDot severity, Token state), PowerSearch filtering, status segmented control, and a resizable inspector panel with metadata and timeline. Adds theTools - Incident Consoletemplate category. - New
messaging-shellpage template: Slack-style column frame (rail | sidebar | stream | thread panel) built on the Chat component family — dense rows, zero cards. Adds theShell - Messagingtemplate category.
Fixes
- Fill viewport height across CLI page templates so the background covers the full page (#3762)
astryx init --features agentsnow supports--agent hermes. The preset injects the component index into an existing.hermes.md/HERMES.md(Hermes Agent's top-priority project-context files) and otherwise creates rootAGENTS.md, which Hermes loads from the project root — unlike the.claude/CLAUDE.mddefault. Additive only: existingclaude/cursor/codex/all/auto-detect behavior is unchanged. (#2187)- cli:
astryx doctornow detects@astryxdesign/theme-*packages in pnpm projects. pnpm installs packages as symlinks intonode_modules/.pnpm, and the theme scan only accepted real directories, so every symlinked theme package was skipped and doctor warned that none were installed (#3530). - Make
astryx theme build's color-scheme declaration mode-aware, so built themes withlight-dark()tokens no longer defeat<Theme mode="light|dark">forcing (#3660) runCodemodsnow returnswrittenFiles, soastryx upgrade's post-codemod hooks (prettier/eslint formatting) actually run on core-codemod changes. The runner built thewrittenFileslist internally but omitted it from its return object, soupgrade.mjsreadcodemodResult.writtenFiles ?? []as always-empty and the configuredhooks.postCodemod(e.g.prettier --write,eslint --fix) received no files and silently skipped. As a result, jscodeshift's default double-quote output ("@astryxdesign/core/Button") was never reformatted to the project's style, failingprettier-formatlint on migrated apps. The siblingintegration-runneralready returnedwrittenFilescorrectly, so integration-codemod changes were formatted while core-codemod changes were not.astryx swizzle: swizzled components ship raw StyleX source that needs a build-time StyleX compiler, and without one they render unstyled with no error. The command now prints a StyleX build-setup note after copying (including the Next.js caveat that the StyleX Babel plugin disables SWC and breaksnext/font, so an SWC-based transform is required), andastryx docs stylinggains a "StyleX Build Setup" section covering per-bundler setup. (#3373)astryx theme build: custom component variants declared in a theme (e.g.button['variant:accentOutline']) now generate a type augmentation against the component's real interface (ButtonVariantMap) instead of a non-existentXDS-prefixed one, sovariant="accentOutline"type-checks. Props with no augmentation point (closed unions like Buttonsizeor Headingtype) are skipped instead of emitting dead augmentations, and the generated.variants.d.tsis now referenced from the theme's.d.tsso the augmentation actually loads. (#3371)
Documentation
- CodeBlock: terminal-style dark block template (syntaxTheme preset)
- Add cascade-layer safety guidance to the migration guide (
astryx docs migration): a Cascade Layer Safety audit checklist (unlayered styles and later layers both beatastryx-baseregardless of specificity, classify every stylesheet into a layer deliberately, layer Tailwind preflight on both v3 and v4) and a Foundation Smoke Test section (one page with Button/TextInput/Card/Table plus a non-zero-padding assertion) so a broken layer order fails before feature work instead of after N migrated screens. The getting-started guide now points to it from the theme CSS step. - NavHeadingMenu: add a playground config and showcase block so the Overview tab has a working preview (#2698)
- NavHeadingMenu: constrain the showcase SideNav to a shorter height so the heading no longer appears to float at the top of the Overview preview (#2698)
Contributors
Thanks to everyone who contributed to this release:
0.1.4
Fixes
astryx component <Name>now prints the correctdefineThemecomponent-override key. The theming example stripped a stalexds-prefix (left over from the astryx rename) instead ofastryx-, so it advertised keys likeastryx-base-table/astryx-button. Those double-prefix to.astryx-astryx-*selectors at runtime and silently match nothing. Keys are now the stable class name minusastryx-(e.g.base-table,button), which is whatgenerateThemeRulesexpects (#3458).- Harden the v0.1.0 upgrade codemods against three cases surfaced while migrating consumer apps:
Documentation
- Add a browser-support guide (
astryx docs browser-support) documenting the support tiers, the modern platform features Astryx depends on (Popover API, CSS anchor positioning,light-dark()), which components are affected, and how consumers can support older browsers for their own audience.
Other Changes
- drop-xds-prefix-imports: when un-prefixing an
@xds/coreimport (e.g.XDSCodeBlock→CodeBlock) would collide with a same-named local binding in the file (such as a localexport function CodeBlockwrapper), alias the import toAstryx<Name>and rewrite its usages instead of producing a duplicate declaration that breaks the build. - migrate-xds-css-surfaces: rewrite CSS
@importof@xds/*package stylesheets (both'…'/"…"andurl(…)forms), including the@xds/core/xds.css→@astryxdesign/core/astryx.cssfile rename and thetheme-default/theme-daily→theme-neutralcollapse. - migrate-xds-module-specifiers: when collapsing
@xds/theme-default/@xds/theme-dailyto@astryxdesign/theme-neutral, remap thedefaultThemeexport toneutralTheme, aliasing back to the original local name (neutralTheme as defaultTheme) so downstream usages keep working.
Contributors
Thanks to everyone who contributed to this release:
0.1.3
New Features
- Add a hidden
astryx blogcommand that reads the blog over the site's RSS feed and prints a post's plaintext (.txt) variant. The command is not shown in--helpor the manifest and always reads from the canonical site origin. - Component discovery is now package-ownership aware: --package scoping, source resolution for integration components, and package-qualified JSON listings.
- Strict config + integration v1 schema (integrations, issuesUrl, hooks.postCodemod) and new @astryxdesign/cli/integration export.
- File-based codemod API (createCodemod/createConfigCodemod) with the @astryxdesign/cli/codemod export and integration codemod discovery in upgrade.
- component, template, and upgrade now print a one-line non-blocking warning when a configured integration has validation issues, pointing to validate-integration.
- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar. Based on a design by @cg-hub18.
- Add frame-first layout guidance: new
astryx docs layouttopic (shell choice, region budgets, app archetypes, cards-vs-rows policy, responsive contracts), layout rules in the generated agent cheat sheet, and layout anti-patterns indocs principles. - Add a v0.1.3 config codemod that migrates astryx.config layout.components to experimental.xle.components.
- Add v0.1.0 codemods for migrating
declare module "@xds/core/..."type augmentations and.xds-*/[data-xds-theme]/@layer xds-themeCSS surfaces to their@astryxdesign/astryx-*equivalents. - Introduce the Project configuration API as the single entry point for reading resolved project config, components, templates, codemods, and issue routing, replacing loadConfig. Misconfigured integrations are now skipped with a warning during upgrade instead of hard-failing, and a new --skip-codemod flag lets you re-run past a failed codemod.
- Add a Shell page-template category to the CLI: Top Nav, Side Nav, and Shell Nav app-shell scaffolds (#3245, #3246, #3247)
- Static template authoring API (createPageTemplate/createBlockTemplate) with the @astryxdesign/cli/template export and type-driven, package-scoped template discovery.
- Swizzle can now copy integration-owned components, rewrites escaping imports to the owning package, and routes maintainer feedback through config and integration issue URLs.
astryx theme build --watch: rebuild a theme automatically whenever the source file changes, until interrupted with Ctrl-C. Removes the manual re-run step (and the stale-CSS confusion that comes with forgetting it) from the theme-authoring loop. Each rebuild runs in a child process so a build error is contained and the watcher keeps running. Not supported with--json. (#3375)- Add the validate-integration command and integration issue model for checking an Astryx integration package's manifest and contributions.
- XLE app-component registration moved into validated config under experimental.xle.components (object form), replacing the unvalidated layout.components read.
Fixes
- Align the CLI error-code type declarations with the runtime error codes (add the missing ERR_AMBIGUOUS_TEMPLATE declaration).
- Correct the
doctortheme-wiring hint to reference the realastryx.themeconfig field (wasxds.theme) and update the agent-docs check wording to say "Astryx". - Update the API/CLI parity harness for the package-qualified
component --listshape, and make the component API reject a non-string name with a clean error instead of throwing. - The XDS-prefix drop codemod now runs as a mandatory v0.1.0 upgrade step, so upgrading from 0.0.x rewrites prefixed imports (useXDSTheme, XDSButton, XDSIconRegistry, ...) to their bare names alongside the @xds/_ → @astryxdesign/_ scope rename.
- upgrade now runs core codemods before loading config, so a config codemod can repair an otherwise-invalid config; dry-run reports a fixable config and suggests the command to apply it.
Documentation
- Blockquote: add "With Attribution" and "Testimonials" examples (#3385)
- DateTimeInput and DateRangeInput: add example blocks so their docs pages have populated Examples sections and playground links (#2724)
- Add copyable example blocks to 46 component docs pages that previously showed only a hero visual and an empty Examples section (#3481)
- HoverCard: give the "Link Preview" example an interactive
Linktrigger so there is something to hover over (#2728) - Lightbox: add Gallery, Video, and Zoom examples and fix the playground preview (#3301)
- Remove lingering references to the removed gap-report feature and swizzle gap flags; docs now reflect swizzle's maintainer feedback link.
- Tab: add an interactive example showing
iconandselectedIconon the Tab docs page (#2765) - ToggleButtonGroup: add a vertical example block showing orientation="vertical" with single- and multi-select groups (#2707)
Other Changes
- Integration codemod and template-doc loading now use the shared module-loader util instead of duplicating the jiti/import logic.
- Extract the shared module-loading + conventional-file-discovery helpers used by config and integration loading into one internal util (no behavior change).
- Remove the standalone gap-report command. Swizzle now prints a short maintainer feedback link instead of filing issues.
- Load and validate user-authored config, integration, codemod, and template modules through one shared module loader; create* factories are now type-only and validation happens at load.
- Remove the obsolete xds config-surface migration codemod and unify config codemod execution on the shared (file, api) runner used by integration codemods.
Contributors
Thanks to everyone who contributed to this release:
0.1.2
Breaking Changes
Text,Heading,Link, andTimestamprename thecolor="active"value tocolor="accent", now mapping to the dedicated--color-text-accenttoken (legible accent text ink) instead of--color-accent. Runastryx upgradeto migrate call sites automatically. (#2863)
New Features
- Let
astryx.config.mjsintegrations contribute package docs, gap-report hooks, template fetching hooks, upgrade codemods, and post-codemod hooks. - Add
astryx theme add <slug> [path](andastryx theme list) to scaffold a theme's source into your project as editable files you own, with theme sources bundled into the CLI
Fixes
- align
astryx inittheme instructions with the runtime built-theme recommendation (#3080)astryx initnow points users at the pre-built theme path (@astryxdesign/theme-neutral/built+theme.css) and the base CSS imports, matching the runtime<Theme>console guidance, instead of the slower runtime style-injection import that left apps unstyled. astryx theme buildnow derives every output file (.css/.js/.d.ts) from the theme name so they share one naming scheme, shows import paths as bare./<name>specifiers (instead of a cwd-rooted./src/...path that was wrong when your file already lives under src/), and no longer warns about thevariantprop oncard
Documentation
- Rename the ClickableCard and SelectableCard examples to follow the "Component — Variant" title convention (
Clickable Card — Nested Button,Selectable Card — Multi-select), and add playground defaults to both card docs so their docsite previews show realistic card content (#2877) - Declare playground scaffolds for the Chat sub-components so they preview at a realistic width (ChatComposer and ChatComposerDrawer wrap in a sized container, and the drawer seeds default content), and drop the redundant visible value label from the ChatComposerDrawer "With Progress" example while keeping the accessible label (#2877)
- Rename the DateInput "Date Range" example to "Min/Max Constraints" — it demos a single input constrained to a min/max window, not a date-range picker (#2692)
- Wire local state into more showcase examples that were frozen (static value + no-op onChange): TextInput, TextArea, NumberInput, SegmentedControl, RadioList, Tab, TabList, and TabMenu. Follows the same fix as the Slider/Selector/MultiSelector showcases so the docsite previews are actually interactive
- Wire local state into the Typeahead, Tokenizer, and FileInput showcase examples (static value + no-op onChange → frozen previews). Completes the interactive-showcase fixes started for Slider/Selector/MultiSelector (#3187-#3189) and the input/tab batch
- Wire local state into the Slider, Selector, and MultiSelector showcase examples so they are interactive — they were controlled components with a static value and a no-op/missing onChange, so the docsite previews appeared frozen (#3187, #3188, #3189)
- Add a LinkProvider example block showing how to swap in a framework router link (e.g. Next.js Link) for client-side routing (#2733)
- Add a showcase block for Outline so its docs page has a hero preview, alongside the existing example blocks (#2871)
- Remove the "MoreMenu — In Toolbar" example block — it rendered incorrectly and was redundant with the other MoreMenu examples (#2870)
- Add rendered example blocks for the two column-axis Table plugin hooks, shown on their own subcomponent pages:
- Move the "ToggleButton — Group" example to the ToggleButtonGroup page, where it belongs (it demonstrates grouped toggle behavior) (#2842)
- Make the Toolbar "Table Filter" example use real Selector controls for its Status and Priority filters instead of buttons styled to look like dropdowns, and add meaningful playground defaults plus richer slot options (buttons, icon buttons, tabs, segmented controls, selectors) to the Toolbar docs (#2877).
Other Changes
useTableStickyColumns — Pinned Columns(on /components/useTableStickyColumns)useTableColumnResize — Draggable Columns(on /components/useTableColumnResize)
Contributors
Thanks to everyone who contributed to this release:
0.1.1
New Features
- Add
astryx buildcommand for page composition, with natural-language search ranking.build "<idea>"returns a composition kit — the closest page template, the blocks that cover parts, and components to fill gaps, plus a Compose suggestion.buildwith no args prints the how-to-build playbook. The shared search ranking now handles oblique natural-language queries via tokenization + stopwords, a synonym/intent map, light stemming, and page-template keyword enrichment. - Make generated agent docs build-first and restructure
initoutput. The generatedCLAUDE.mdnow leads with thebuildworkflow (search reframed as a neutral universal find), and includes a required-CSS setup note (reset.css+astryx.css) so components never render unstyled.initnow points agents atastryx build/astryx searchinstead of dumping page-template names. - Improve
astryx buildoutput into a complete composition kit.build "<idea>"now returns an agent-ready kit grouped by role: a START line (scaffold vs compose), the closest PAGE template, an always-on FRAME (page shell) and FOUNDATION (layout/typography/action primitives), idea-specific BLOCKS and DOMAIN COMPONENTS (with a relevance floor to cut noise), and a SETUP reminder. The always-on FRAME/FOUNDATION groups fix low recall of the structural primitives every page needs but that never keyword-match an idea (measured: component recall 15% to 71% on an agent-grounded eval). - Densify agent docs + tailor styling guidance to the project's configured system
Tightened the generated
CLAUDE.md/AGENTS.mdblock from ~48 lines to ~26 (the per-topicdocsdump collapsed to one line,build/search/componentno longer duplicated between workflow and reference, run-prefix stated once, filler prose removed) — same information, far denser.
Fixes
npx astryxnow works when the CLI is installed as a real npm package. The bin imported its../src/*modules relative to the invoked path, so running through thenode_modules/.bin/astryxsymlink made them resolve outside the package (ERR_MODULE_NOT_FOUND: .../node_modules/src/...) on Node versions that don't realpath the bin entry. It now resolves siblings via the bin's real path (realpath ofimport.meta.url), working whether invoked via symlink, copy, or Windows shim. Also fixes the non-interactiveinit/themeerror to sayastryx <command>instead of the stalexds <command>.- Add a v0.1.0 upgrade codemod that migrates legacy
@xds/*module specifiers and config surfaces to the Astryx v0.1.0 names. [breaking] Remove legacyastryx.versionFileupdate-hint support from package.json.
Documentation
- Add npm install step to the Theme System guide
The Quick Start section jumped straight to
import {neutralTheme} from '@astryxdesign/theme-neutral', which fails withCannot find modulefor anyone who hasn't already installed the theme package. Prepend a one-line preamble +npm installcode block, and add a short prose note above the Available Themes table pointing at the install command pattern. Reported in #3082.
Other Changes
- StyleX compiler wired →
xstyle/ StyleX token imports - Tailwind → utility classes backed by
@astryxdesign/core/tailwind-theme.css - neither →
style/classNamewithvar(--token)design tokens, plus an explicit note NOT to usexstyle/utilities (they would not compile)
Contributors
Thanks to everyone who contributed to this release: