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" to labelSpacing="hug" on Switch. (#2889)
  • New incident-console page 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 the Tools - Incident Console template category.
  • New messaging-shell page template: Slack-style column frame (rail | sidebar | stream | thread panel) built on the Chat component family — dense rows, zero cards. Adds the Shell - Messaging template category.
Fixes
  • Fill viewport height across CLI page templates so the background covers the full page (#3762)
  • astryx init --features agents now 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 root AGENTS.md, which Hermes loads from the project root — unlike the .claude/CLAUDE.md default. Additive only: existing claude/cursor/codex/all/auto-detect behavior is unchanged. (#2187)
  • cli: astryx doctor now detects @astryxdesign/theme-* packages in pnpm projects. pnpm installs packages as symlinks into node_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 with light-dark() tokens no longer defeat <Theme mode="light|dark"> forcing (#3660)
  • runCodemods now returns writtenFiles, so astryx upgrade's post-codemod hooks (prettier/eslint formatting) actually run on core-codemod changes. The runner built the writtenFiles list internally but omitted it from its return object, so upgrade.mjs read codemodResult.writtenFiles ?? [] as always-empty and the configured hooks.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, failing prettier-format lint on migrated apps. The sibling integration-runner already returned writtenFiles correctly, 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 breaks next/font, so an SWC-based transform is required), and astryx docs styling gains 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-existent XDS-prefixed one, so variant="accentOutline" type-checks. Props with no augmentation point (closed unions like Button size or Heading type) are skipped instead of emitting dead augmentations, and the generated .variants.d.ts is now referenced from the theme's .d.ts so 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 beat astryx-base regardless 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 correct defineTheme component-override key. The theming example stripped a stale xds- prefix (left over from the astryx rename) instead of astryx-, so it advertised keys like astryx-base-table / astryx-button. Those double-prefix to .astryx-astryx-* selectors at runtime and silently match nothing. Keys are now the stable class name minus astryx- (e.g. base-table, button), which is what generateThemeRules expects (#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/core import (e.g. XDSCodeBlock → CodeBlock) would collide with a same-named local binding in the file (such as a local export function CodeBlock wrapper), alias the import to Astryx<Name> and rewrite its usages instead of producing a duplicate declaration that breaks the build.
  • migrate-xds-css-surfaces: rewrite CSS @import of @xds/* package stylesheets (both '…'/"…" and url(…) forms), including the @xds/core/xds.css → @astryxdesign/core/astryx.css file rename and the theme-default/theme-daily → theme-neutral collapse.
  • migrate-xds-module-specifiers: when collapsing @xds/theme-default/@xds/theme-daily to @astryxdesign/theme-neutral, remap the defaultTheme export to neutralTheme, 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 blog command that reads the blog over the site's RSS feed and prints a post's plaintext (.txt) variant. The command is not shown in --help or 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 layout topic (shell choice, region budgets, app archetypes, cards-vs-rows policy, responsive contracts), layout rules in the generated agent cheat sheet, and layout anti-patterns in docs 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-theme CSS 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 doctor theme-wiring hint to reference the real astryx.theme config field (was xds.theme) and update the agent-docs check wording to say "Astryx".
  • Update the API/CLI parity harness for the package-qualified component --list shape, 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 Link trigger 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 icon and selectedIcon on 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, and Timestamp rename the color="active" value to color="accent", now mapping to the dedicated --color-text-accent token (legible accent text ink) instead of --color-accent. Run astryx upgrade to migrate call sites automatically. (#2863)
New Features
  • Let astryx.config.mjs integrations contribute package docs, gap-report hooks, template fetching hooks, upgrade codemods, and post-codemod hooks.
  • Add astryx theme add <slug> [path] (and astryx 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 init theme instructions with the runtime built-theme recommendation (#3080) astryx init now 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 build now 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 the variant prop on card
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
Contributors
Thanks to everyone who contributed to this release:

0.1.1

New Features
  • Add astryx build command 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. build with 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 init output. The generated CLAUDE.md now leads with the build workflow (search reframed as a neutral universal find), and includes a required-CSS setup note (reset.css + astryx.css) so components never render unstyled. init now points agents at astryx build/astryx search instead of dumping page-template names.
  • Improve astryx build output 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.md block from ~48 lines to ~26 (the per-topic docs dump collapsed to one line, build/search/component no longer duplicated between workflow and reference, run-prefix stated once, filler prose removed) — same information, far denser.
Fixes
  • npx astryx now 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 the node_modules/.bin/astryx symlink 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 of import.meta.url), working whether invoked via symlink, copy, or Windows shim. Also fixes the non-interactive init/theme error to say astryx <command> instead of the stale xds <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 legacy astryx.versionFile update-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 with Cannot find module for anyone who hasn't already installed the theme package. Prepend a one-line preamble + npm install code 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/className with var(--token) design tokens, plus an explicit note NOT to use xstyle/utilities (they would not compile)
Contributors
Thanks to everyone who contributed to this release: