# Table of Contents

- [Getting Started · Astryx](#getting-started-astryx)
- [Browser Support · Astryx](#browser-support-astryx)
- [CLI Integrations · Astryx](#cli-integrations-astryx)
- [Elevation · Astryx](#elevation-astryx)
- [Getting Started · Astryx](#getting-started-astryx)
- [Icons · Astryx](#icons-astryx)
- [Color · Astryx](#color-astryx)
- [Illustrations · Astryx](#illustrations-astryx)
- [Migration Guide · Astryx](#migration-guide-astryx)
- [Motion · Astryx](#motion-astryx)
- [Layout · Astryx](#layout-astryx)
- [Spacing · Astryx](#spacing-astryx)
- [Principles · Astryx](#principles-astryx)
- [Internationalization · Astryx](#internationalization-astryx)
- [Theme System · Astryx](#theme-system-astryx)
- [Shape · Astryx](#shape-astryx)
- [Styling Library Interop · Astryx](#styling-library-interop-astryx)
- [Typography · Astryx](#typography-astryx)
- [All Tokens · Astryx](#all-tokens-astryx)
- [Styling Components · Astryx](#styling-components-astryx)
- [Working with AI · Astryx](#working-with-ai-astryx)

---

# Getting Started · Astryx

[Skip to content](https://astryx.atmeta.com/docs#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Getting Started
===============

Add the design system to your project and start building.

Quick Start with AI
-------------------

Copy link

Paste this into your AI coding tool and let it handle the setup:

Paste this into your AI

text

``   Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.   ``

Install
-------

Copy link

Astryx requires React 19 or later: `react` and `react-dom` >= 19.0.0 are peer dependencies of `@astryxdesign/core`.

Add the core package, a theme, and the CLI to your existing project.

Terminal

bash

`   npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli   `

Then run `astryx init` to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive; no prompts; so it's safe for AI agents, CI, and scripts. Add `--all` for pointers to the theme and page-building workflows.

Terminal

bash

`   npx astryx init   `

Add the theme CSS
-----------------

Copy link

Import the reset stylesheet and a theme in your global CSS file. Themes provide all design tokens (colors, spacing, radius, typography) as CSS custom properties.

globals.css

css

`   @import '@astryxdesign/core/reset.css';  @import '@astryxdesign/core/astryx.css';  @import '@astryxdesign/theme-neutral/theme.css';   `

Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See [`astryx docs theme`](https://astryx.atmeta.com/docs/theme)
 for the full theming guide.

These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in [`astryx docs migration`](https://astryx.atmeta.com/docs/migration)
 before building screens.

Add your first component
------------------------

Copy link

Components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.

app/page.tsx

tsx

`   import {Button} from '@astryxdesign/core/Button';  import {VStack} from '@astryxdesign/core/Layout';  ​  export default function Page() {    return (      <VStack gap={2}>        <Button label="Hello Astryx" onClick={() => alert('Hi!')} />      </VStack>    );  }   `

Customize with StyleX
---------------------

Copy link

Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](https://astryx.atmeta.com/docs/styling)
 for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/)
, an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.

Style overrides

tsx

`   import * as stylex from '@stylexjs/stylex';  ​  const overrides = stylex.create({    save: { alignSelf: 'flex-end', marginTop: 16 },  });  ​  <Button label="Save" xstyle={overrides.save} />   `

Example Apps
------------

Copy link

For a full working project, clone one of the example apps from the repo. These are complete setups with routing, theming, and components wired together.

| Example | Stack | Path |
| --- | --- | --- |
| Next.js | Next.js + theme CSS | [apps/example-nextjs](https://github.com/facebook/astryx/tree/main/apps/example-nextjs) |
| Next.js + StyleX | Next.js + StyleX for custom styles | [apps/example-nextjs-stylex](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-stylex) |
| Next.js + Tailwind | Next.js + Tailwind bridge | [apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind) |
| Next.js Source | Next.js importing from source | [apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source) |
| Vite | Vite | [apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite) |

Clone and run an example

bash

`   git clone https://github.com/facebook/astryx.git  cd astryx/apps/example-nextjs  pnpm install  pnpm dev   `

Explore the CLI
---------------

Copy link

The CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:

package.json

json

`   "scripts": {    "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"  }   `

Then discover what's available:

Terminal

bash

`   astryx component          # list all components  astryx component Button   # props, usage, theming for Button  astryx docs               # list all doc topics  astryx template --list    # available page templates  astryx docs tokens        # spacing, color, radius reference   `

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/getting-started)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Browser Support · Astryx

[Skip to content](https://astryx.atmeta.com/docs/browser-support#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Browser Support
===============

What browsers Astryx targets, which modern platform features it depends on, and how to support older browsers for your own audience.

Overview
--------

Copy link

Astryx is built on modern web platform features: the Popover API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.

A design system does not own its traffic; the products built on it do. Their audiences range from evergreen-Chrome-only internal tools to public sites with meaningful older-Safari share. So Astryx does not declare a single hard browser floor the way an app would. Instead it defines tiers that describe what works at each level, and hands the final decision to you. Pick the tier that matches your audience.

Support Tiers
-------------

Copy link

Astryx officially supports Tier 1 and Tier 2. Tier 3 is best-effort: components will not crash, but positioning and theming may degrade.

| Tier | Baseline | Representative versions | What your users experience |
| --- | --- | --- | --- |
| Tier 1: Full fidelity | Current Baseline (2026) | Chrome 125+, Edge 125+, Safari 26+, Firefox 147+ | Everything works, including CSS anchor positioning. This is the reference target. |
| Tier 2: Functional | Baseline − 2 years (2024) | Chrome 114+, Edge 114+, Safari 17+, Firefox 125+ | Components open, dismiss, and are fully usable. Only anchor positioning is missing, so layered surfaces (tooltips, menus, popovers) may not be positioned next to their trigger. |
| Tier 3: Below Tier 2 | Older than Baseline − 2 | Anything older | Best-effort. The only guarantee is "does not crash." `light-dark()` is unavailable, so theme colors may fall back to defaults. |

Which Features Set the Floor
----------------------------

Copy link

Only three modern features carry a browser requirement. Everything else Astryx uses (`:has()`, `color-mix()`, container queries, the `<dialog>` element) has been widely available since 2023 or earlier and needs no special handling.

| Feature | Role in Astryx | Widely available |
| --- | --- | --- |
| CSS Anchor Positioning | Positions layered surfaces relative to their trigger (tooltips, menus, popovers, dropdowns). | Baseline 2026: the tightest requirement. |
| Popover API | Opens, stacks, and light-dismisses layered surfaces via the top layer. | Baseline 2025. |
| CSS light-dark() | Compiles every theme color tuple into a single value that responds to color scheme. Underpins the whole theming system. | Widely available since mid-2024. |

The gap that matters is between Tier 1 and Tier 2: the Popover API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.

Which Components Are Affected
-----------------------------

Copy link

The browser requirement is concentrated in the layered-surface components: anything that renders content in an overlay positioned against a trigger:

*   Tooltip
*   HoverCard
*   Popover
*   ContextMenu
*   Selector and MultiSelector (dropdown surfaces)
*   Tokenizer (suggestion menu)
*   Carousel (anchored controls)

If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.

What Astryx Guarantees
----------------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Components never throw on missing platform APIs. Where a browser lacks the Popover API, layers fall back to plain visibility instead of crashing. |
| Do  | Tier 1 and Tier 2 are officially supported and tested. |
| Do  | Non-layered components render correctly down to Tier 2. |
| Don't | Astryx does not guarantee correct layer positioning below Tier 1 (anchor positioning). Closing that gap for a Tier 2 audience is a consumer choice; see below. |
| Don't | Astryx does not ship a `light-dark()` fallback, so theme colors are not guaranteed below Tier 2. |

Supporting Older Browsers
-------------------------

Copy link

If your audience includes Tier 2 browsers and you need correct layer positioning, you have three options, cheapest first. All of them are decisions you make for your audience; Astryx does not impose one.

1.  Polyfill anchor positioning. Load a CSS anchor positioning polyfill conditionally behind an `@supports` check so it costs nothing on Tier 1. This is the lowest-effort way to get correct positioning; note that polyfills may not cover every position-fallback feature.
2.  Provide a JS positioning fallback. Detect missing support with `CSS.supports("anchor-name", "--x")` and position layers with a measurement-based library (e.g. a floating-element positioner) when it returns false. More code, full control.
3.  Accept degraded positioning. Document for your users that on Tier 2 browsers, layered surfaces open correctly but may not sit next to their trigger. Cheapest, and often fine for internal tools on evergreen browsers.

Feature-detect at runtime rather than sniffing user agents:

Feature detection

js

`   // Popover API (Tier 2 and up)  const hasPopover = typeof HTMLElement !== 'undefined'    && typeof HTMLElement.prototype.showPopover === 'function';  ​  // CSS anchor positioning (Tier 1)  const hasAnchorPositioning = CSS.supports('anchor-name', '--x');  ​  // CSS light-dark() (Tier 2 and up)  const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');   `

How These Tiers Move Over Time
------------------------------

Copy link

The tiers are rolling, not frozen to specific versions. They track the Web Baseline year:

*   Tier 1 tracks the current Baseline year.
*   Tier 2 tracks Baseline minus two years.
*   Tier 3 is everything older, and remains best-effort.

This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the Popover API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/browser-support)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# CLI Integrations · Astryx

[Skip to content](https://astryx.atmeta.com/docs/cli-integrations#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

CLI Integrations
================

Author an npm package that contributes components, templates, and upgrade codemods to Astryx.

Overview
--------

Copy link

An integration is an npm package that contributes components, templates, and/or upgrade codemods to a consumer's design-system workflow. Consumers install the package and add it to their `astryx.config`; from then on the integration's contributions show up alongside core's in the same CLI commands.

The system runs on two files. The consumer writes `astryx.config.{ts,mjs,js}` at their project root to list which packages to load. The author writes `astryx.integration.{ts,mjs,js}` at the package root to declare what the package contributes. This page is the author's guide. For the consumer side, run [`npx astryx docs getting-started`](https://astryx.atmeta.com/docs/getting-started)
.

On the consumer side, adding your package is one line:

typescript

`   // astryx.config.ts  export default {    integrations: ['@acme/astryx-widgets'],  };   `

Your components and templates then appear next to core's:

bash

`   astryx component --list --package @acme/astryx-widgets  astryx component AcmeCarousel --props   `

The Integration File
--------------------

Copy link

To register your package as an integration, add an `astryx.integration.{ts,mjs,js}` file as a sibling of your `package.json`. It tells the CLI where to find your components, templates, and codemods. Identity (name, version) comes from your `package.json`, not this file.

typescript

`   // astryx.integration.ts  export default {    components: './components',    templates: './templates',    codemods: './codemods',    issuesUrl: 'https://github.com/acme/widgets/issues',  };   `

Every field is optional. Declare only the contribution roots your package ships. There is no factory to call. Write a plain object, and for editor autocomplete and type-checking annotate it with the `AstryxIntegration` type exported from `@astryxdesign/cli/authoring`.

Components
----------

Copy link

Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`.

typescript

`   // AcmeCarousel.doc.ts  export default {    type: 'component',    name: 'AcmeCarousel',    description: 'A carousel that cycles through slides.',    // props, usage, examples, ...  };   `

Templates
---------

Copy link

Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object stamped with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`.

typescript

`   // AcmeLandingPage.template.ts  export default {    type: 'page',    // name, description, preview, ...  };   `

The CLI needs the template source at consume time, so make sure it is included in your published package. This is typically done via the `exports` key in `package.json`. It also lets the docsite render template previews in the future.

jsonc

`   {    "exports": {      // ...      "./templates/*.tsx": "./templates/*.tsx"    }  }   `

To verify it resolves, try importing the template component with its `.tsx` extension. An extensionless specifier will not resolve under `moduleResolution: bundler`, and the extensionful export above is what lets this type-check without consumers enabling `allowImportingTsExtensions`.

typescript

`   import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');   `

Codemods
--------

Copy link

Ship codemods so `astryx upgrade` can migrate consumers across breaking changes in your package. Point the integration file's `codemods` field at your codemods root, and author each one as a plain object stamped with `type: 'code'` (transforms source files) or `type: 'config'` (rewrites the consumer's `astryx.config`).

typescript

`   // codemods/v2-rename-prop.ts  export default {    type: 'code',    // title, description, transform, ...  };   `

All authoring types are exported from `@astryxdesign/cli/authoring`: `ComponentDoc`, `HookDoc`, and `ReferenceDoc` for docs, `TemplateDoc` for templates, and `AstryxConfig`, `AstryxIntegration`, and `AstryxCodemod` for the project files. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.

How It Works
------------

Copy link

Every CLI command loads the consumer's `astryx.config`, resolves each listed integration's manifest from `node_modules`, and discovers its contributions. Everything is validated against one strict schema at the load boundary: the CLI parses each file through `@astryxdesign/cli/authoring` when it loads it, not when you author it. There are no factories; you write a plain object and stamp its `type`.

Discovery is resilient. A broken or misconfigured integration is skipped with a single non-blocking warning on stderr instead of crashing the CLI, and it never corrupts a `--json` stdout envelope. Everyday commands keep working with the remaining valid contributions.

To inspect problems, run `astryx validate-integration <package>` for a detailed report on one package, or `astryx doctor` for an overall health check of the setup.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/cli-integrations)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Elevation · Astryx

[Skip to content](https://astryx.atmeta.com/docs/elevation#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Elevation
=========

Shadow tokens for visual elevation and inset state rings.

Overview
--------

Copy link

Elevation tokens create depth through box-shadow. Three levels (low, med, high) establish a visual hierarchy for floating elements. Inset shadows provide focus and selection rings for interactive components.

### Elevation Scale

Copy link

Each level adds stronger offset and spread. Shadow color adapts to dark mode automatically via light-dark().

| Token | Preview |
| --- | --- |
| \--shadow-low |     |
| \--shadow-med |     |
| \--shadow-high |     |
| \--shadow-inset-hover |     |
| \--shadow-inset-selected |     |
| \--shadow-inset-success |     |
| \--shadow-inset-warning |     |
| \--shadow-inset-error |     |

Choosing a level
----------------

Copy link

Pick the level by how far the surface sits from the page, not by how much shadow you want. Elevation encodes stacking order: a higher level means the surface is layered over more of the UI. Use exactly one level per surface, and only raise a surface above `none` when it actually sits above other content.

| Level | When to use | Examples |
| --- | --- | --- |
| none | The component is flat and embedded in the surface; it is part of the page, not layered above it. This is the default for every surface except ChatComposer. | A Card in a grid, an inline Banner, a standard Button |
| low | The component is in the normal page flow but should read as distinct from the background. Use for emphasis or to separate the component from the surface behind it; the component still sits on the page, it is not floating over other content. | A raised Card that needs emphasis, a ChatComposer |
| med | The component sits over other content on the same page; it floats above nearby elements but not the whole screen. | A Popover, a floating Banner, a floating action Button |
| high | The component is placed over the entire UI; it is the topmost layer and typically has a backdrop or takes focus from everything else. | A modal Dialog, a full-screen overlay surface |

If two surfaces overlap, the one on top takes the higher level. If a surface does not overlap anything, it is `none` or `low`; never `med` or `high`.

The elevation prop
------------------

Copy link

Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.

Prop defaults preserve current appearance: every surface defaults to `none` except ChatComposer, which defaults to `low` to keep its raised look. Set `elevation="none"` to flatten it; the flat composer draws a border with the same rest / hover / focus treatment as a text input.

Raising a surface with the elevation prop

tsx

`   // Flat by default; raise only when the surface needs to float.  <Card elevation="low">Raised card</Card>  ​  // A floating action button.  <IconButton icon={<Icon icon="add" />} label="New" variant="primary" elevation="med" />  ​  // Flatten the composer (defaults to 'low').  <ChatComposer elevation="none" onSubmit={handleSubmit} />   `

Always float; no prop: intrinsic overlays (Dialog, Popover, Tooltip, Toast, HoverCard, DropdownMenu, and the components that compose them) bake their elevation in and never expose the prop. Flow content (inputs, Text, layout) is never elevated; input fields use inset rings, which are a separate concept from elevation.

Usage
-----

Copy link

When building a custom surface, read elevation from the token scale rather than a hand-rolled shadow; the same tokens the elevation prop resolves to.

Applying elevation

tsx

`   import {shadowVars} from '@astryxdesign/core';  ​  const styles = stylex.create({    dropdown: {      boxShadow: shadowVars['--shadow-med'],    },    dialog: {      boxShadow: shadowVars['--shadow-high'],    },    inputFocused: {      boxShadow: shadowVars['--shadow-inset-selected'],    },  });   `

Best Practices
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Reach for the `elevation` prop on a configurable surface before writing any custom shadow. |
| Do  | Choose the level by how far the surface sits from the page: `none` when flat/embedded, `low` when in-flow but distinct, `med` when over page content, `high` when over the whole UI. See "Choosing a level". |
| Do  | Use inset shadows for input focus/selection states; they compose better than outlines. |
| Don't | Hand-write a `box-shadow` in app code; set the `elevation` prop or read `shadowVars` instead. |
| Don't | Raise a surface that does not sit above other content; a non-overlapping surface is `none` or `low`, never `med` or `high`. |
| Don't | Stack multiple elevation levels on the same element. |
| Don't | Use elevation shadows for decorative borders. Use --color-border tokens instead. |

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/elevation)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Getting Started · Astryx

[Skip to content](https://astryx.atmeta.com/docs/getting-started#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Getting Started
===============

Add the design system to your project and start building.

Quick Start with AI
-------------------

Copy link

Paste this into your AI coding tool and let it handle the setup:

Paste this into your AI

text

``   Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.   ``

Install
-------

Copy link

Astryx requires React 19 or later: `react` and `react-dom` >= 19.0.0 are peer dependencies of `@astryxdesign/core`.

Add the core package, a theme, and the CLI to your existing project.

Terminal

bash

`   npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli   `

Then run `astryx init` to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive; no prompts; so it's safe for AI agents, CI, and scripts. Add `--all` for pointers to the theme and page-building workflows.

Terminal

bash

`   npx astryx init   `

Add the theme CSS
-----------------

Copy link

Import the reset stylesheet and a theme in your global CSS file. Themes provide all design tokens (colors, spacing, radius, typography) as CSS custom properties.

globals.css

css

`   @import '@astryxdesign/core/reset.css';  @import '@astryxdesign/core/astryx.css';  @import '@astryxdesign/theme-neutral/theme.css';   `

Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See [`astryx docs theme`](https://astryx.atmeta.com/docs/theme)
 for the full theming guide.

These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in [`astryx docs migration`](https://astryx.atmeta.com/docs/migration)
 before building screens.

Add your first component
------------------------

Copy link

Components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.

app/page.tsx

tsx

`   import {Button} from '@astryxdesign/core/Button';  import {VStack} from '@astryxdesign/core/Layout';  ​  export default function Page() {    return (      <VStack gap={2}>        <Button label="Hello Astryx" onClick={() => alert('Hi!')} />      </VStack>    );  }   `

Customize with StyleX
---------------------

Copy link

Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](https://astryx.atmeta.com/docs/styling)
 for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/)
, an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.

Style overrides

tsx

`   import * as stylex from '@stylexjs/stylex';  ​  const overrides = stylex.create({    save: { alignSelf: 'flex-end', marginTop: 16 },  });  ​  <Button label="Save" xstyle={overrides.save} />   `

Example Apps
------------

Copy link

For a full working project, clone one of the example apps from the repo. These are complete setups with routing, theming, and components wired together.

| Example | Stack | Path |
| --- | --- | --- |
| Next.js | Next.js + theme CSS | [apps/example-nextjs](https://github.com/facebook/astryx/tree/main/apps/example-nextjs) |
| Next.js + StyleX | Next.js + StyleX for custom styles | [apps/example-nextjs-stylex](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-stylex) |
| Next.js + Tailwind | Next.js + Tailwind bridge | [apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind) |
| Next.js Source | Next.js importing from source | [apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source) |
| Vite | Vite | [apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite) |

Clone and run an example

bash

`   git clone https://github.com/facebook/astryx.git  cd astryx/apps/example-nextjs  pnpm install  pnpm dev   `

Explore the CLI
---------------

Copy link

The CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:

package.json

json

`   "scripts": {    "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"  }   `

Then discover what's available:

Terminal

bash

`   astryx component          # list all components  astryx component Button   # props, usage, theming for Button  astryx docs               # list all doc topics  astryx template --list    # available page templates  astryx docs tokens        # spacing, color, radius reference   `

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/getting-started)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Icons · Astryx

[Skip to content](https://astryx.atmeta.com/docs/icons#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Icons
=====

Semantic icon names available in the design system. These adapt to the active theme's icon registry.

Available Names
---------------

Copy link

Components that accept an icon prop use IconType: either a semantic name string or a direct SVG component. The semantic names below are resolved through the global icon registry.

| Name | Usage |
| --- | --- |
| close | Dismiss, close dialogs/panels |
| chevronDown | Dropdown triggers, expand/collapse |
| chevronLeft | Navigate back, previous |
| chevronRight | Navigate forward, next |
| chevronsLeft | Jump to first, skip to start |
| chevronsRight | Jump to last, skip to end |
| check | Checkbox checked, confirm |
| success | Success status indicator |
| error | Error status indicator |
| warning | Warning status indicator |
| info | Info status indicator, tooltips |
| calendar | Date pickers, scheduling |
| clock | Time pickers, timestamps |
| externalLink | Links opening in new tab |
| menu | Hamburger menu, navigation toggle |
| moreHorizontal | Overflow menu, additional actions |
| search | Search inputs, find |
| arrowUp | Sort ascending, move up |
| arrowDown | Sort descending, move down |
| arrowsUpDown | Sortable column indicator |
| funnel | Filter controls |
| eyeSlash | Hidden/visibility toggle |
| viewColumns | Column visibility settings |
| copy | Copy to clipboard |
| checkDouble | Copied confirmation |
| wrench | Settings, configuration |
| stop | Stop/cancel action |
| microphone | Voice input, audio recording |

Custom Icons
------------

Copy link

For icons not in the semantic list, pass an SVG component directly. Any ComponentType<SVGProps<SVGSVGElement>> works; Icon applies size and color styling automatically.

Using custom SVG components

tsx

`   import { PhotoIcon } from '@heroicons/react/24/outline';  import { HeartIcon } from 'lucide-react';  ​  <Icon icon={PhotoIcon} size="lg" />  <Icon icon={HeartIcon} color="negative" />   `

Theme Overrides
---------------

Copy link

Themes can replace the default SVGs for any semantic name with the `icons` field in `defineTheme()`. This lets you swap the icon set (e.g. heroicons → lucide) without touching component code, and keeps lookup scoped to the active theme instead of mutating global defaults.

Theme-scoped icons

tsx

`   import {defineTheme} from '@astryxdesign/core/theme';  import {XMarkIcon, ChevronDownIcon} from '@heroicons/react/24/outline';  ​  export const brandTheme = defineTheme({    name: 'brand',    icons: {      close: <XMarkIcon />,      chevronDown: <ChevronDownIcon />,    },  });   `

Adding New Icons
----------------

Copy link

To add a new semantic icon name to the design system:

1.  Add the name to IconName type in packages/core/src/Icon/globalIconRegistry.tsx
2.  Add the default SVG to packages/core/src/Icon/defaultIcons.tsx
3.  Add a row to the Available Names table in packages/cli/docs/icons.doc.mjs

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/icons)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Color · Astryx

[Skip to content](https://astryx.atmeta.com/docs/color#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Color
=====

Semantic color tokens for surfaces, text, icons, borders, and status indicators.

Overview
--------

Copy link

Colors are semantic: tokens describe purpose, not appearance. Every color adapts automatically between light and dark modes via CSS light-dark(). Themes override the resolved values, so your code never references raw hex colors.

### Surface Colors

Copy link

Layered surface hierarchy: body → surface → card → popover. Each level sits visually above the previous one.

| Token | Value |
| --- | --- |
| \--color-accent | #262626 / #ebebeb |
| \--color-accent-muted | #f1f1f1 / #262626 |
| \--color-on-accent | #ffffff / #171717 |
| \--color-neutral | #0000000F / #FFFFFF1A |
| \--color-background-surface | #ffffff / #262626 |
| \--color-background-body | #f1f1f1 / #1b1b1b |
| \--color-overlay | #00000080 / #000000CC |
| \--color-overlay-hover | #0000000D / #FFFFFF0D |
| \--color-overlay-pressed | #0000001A / #FFFFFF1A |
| \--color-background-muted | #f1f1f1 / #1b1b1b |
| \--color-text-primary | #171717 / #fafafa |
| \--color-text-secondary | #525252 / #a3a3a3 |
| \--color-text-disabled | #a3a3a3 / #525252 |
| \--color-text-accent | #262626 / #ebebeb |
| \--color-on-dark | #ffffff |
| \--color-on-light | #171717 |
| \--color-icon-accent | #262626 / #ebebeb |
| \--color-icon-primary | #171717 / #fafafa |
| \--color-icon-secondary | #737373 / #a3a3a3 |
| \--color-icon-disabled | #a3a3a3 / #525252 |
| \--color-background-card | #ffffff / #1b1b1b |
| \--color-background-popover | #ffffff / #1b1b1b |
| \--color-background-inverted | #0A1317 / #FFFFFF |
| \--color-background-error-inverted | #AA071E / #E3193B |
| \--color-success | #007004 / #9fe59b |
| \--color-success-muted | #c5e5c0 / #84c9803D |
| \--color-on-success | #ffffff / #171717 |
| \--color-error | #a50c25 / #ffc6c1 |
| \--color-error-muted | #facecb / #ff9e973D |
| \--color-on-error | #ffffff / #171717 |
| \--color-warning | #745b00 / #fdcf4f |
| \--color-warning-muted | #f8da9d / #deb4333D |
| \--color-on-warning | #171717 |
| \--color-border | #00000014 / #FFFFFF1A |
| \--color-border-emphasized | #d4d4d4 / #525252 |
| \--color-skeleton | #ebebeb / #525252 |
| \--color-track | #CCD3DB / #5A5E66 |
| \--color-shadow | #0000001A / #0000004D |
| \--color-tint-hover | black / white |
| \--color-background-blue | #c4ddfb / #9eb7ff3D |
| \--color-border-blue | #b1c9e7 / #6d9cfe |
| \--color-icon-blue | #00458c / #9eb7ff |
| \--color-text-blue | #00458c / #c7d3ff |
| \--color-background-cyan | #a3e0ef / #83c2d43D |
| \--color-border-cyan | #91d3e3 / #67a7b8 |
| \--color-icon-cyan | #00505f / #83c2d4 |
| \--color-text-cyan | #00505f / #9edef0 |
| \--color-background-gray | #e5e5e5 / var(--color-neutral) |
| \--color-border-gray | #d4d4d4 / #262626 |
| \--color-icon-gray | #525252 / #a3a3a3 |
| \--color-text-gray | #262626 / #e5e5e5 |
| \--color-background-green | #c5e5c0 / #84c9803D |
| \--color-border-green | #b2d1ac / #69ad67 |
| \--color-icon-green | #0c5700 / #84c980 |
| \--color-text-green | #0c5700 / #9fe59b |
| \--color-background-orange | #fad0b5 / #ffa2583D |
| \--color-border-orange | #e6bda2 / #e2883e |
| \--color-icon-orange | #6e3500 / #ffa258 |
| \--color-text-orange | #6e3500 / #ffc9a2 |
| \--color-background-pink | #fccadc / #ff99c33D |
| \--color-border-pink | #e7b7c8 / #f273aa |
| \--color-icon-pink | #83004b / #ff99c3 |
| \--color-text-pink | #83004b / #ffc3da |
| \--color-background-purple | #eccef3 / #f297ff3D |
| \--color-border-purple | #d8bbdf / #dd74f0 |
| \--color-icon-purple | #700084 / #f297ff |
| \--color-text-purple | #700084 / #fac1ff |
| \--color-background-red | #facecb / #ff9e973D |
| \--color-border-red | #e6bab8 / #ff6f6c |
| \--color-icon-red | #89001a / #ff9e97 |
| \--color-text-red | #89001a / #ffc6c1 |
| \--color-background-teal | #a5e3d6 / #7ec6b83D |
| \--color-border-teal | #94d6c8 / #63ab9d |
| \--color-icon-teal | #005348 / #7ec6b8 |
| \--color-text-teal | #005348 / #99e2d3 |
| \--color-background-yellow | #f8da9d / #deb4333D |
| \--color-border-yellow | #e4c279 / #c0990e |
| \--color-icon-yellow | #584400 / #deb433 |
| \--color-text-yellow | #584400 / #fdcf4f |
| \--color-syntax-keyword | #700084 / #efa8ff |
| \--color-syntax-string | #005600 / #a6d2a2 |
| \--color-syntax-comment | #737373 / #a3a3a3 |
| \--color-syntax-number | #6e3500 / #ffb37f |
| \--color-syntax-function | #00458c / #a0caff |
| \--color-syntax-type | #700084 / #efa8ff |
| \--color-syntax-variable | #171717 / #e5e5e5 |
| \--color-syntax-operator | #737373 / #a3a3a3 |
| \--color-syntax-constant | #6e3500 / #ffb37f |
| \--color-syntax-tag | #89001a / #ffaeaa |
| \--color-syntax-attribute | #584400 / #eec12f |
| \--color-syntax-property | #005348 / #83dac9 |
| \--color-syntax-punctuation | #a3a3a3 / #525252 |
| \--color-syntax-background | #fafafa / #0a0a0a |
| \--color-data-categorical-blue | #0171E3 |
| \--color-data-categorical-orange | #EB6E00 |
| \--color-data-categorical-purple | #6B1EFD |
| \--color-data-categorical-green | #0B991F |
| \--color-data-categorical-pink | #F351C0 |
| \--color-data-categorical-cyan | #0171A4 |
| \--color-data-categorical-red | #F5394F |
| \--color-data-categorical-teal | #08A3A3 |
| \--color-data-categorical-brown | #965E03 |
| \--color-data-categorical-indigo | #6F8AFF |
| \--color-data-neutral | #8494A3 / #8C939B |
| \--color-data-blue-5 | #02165E |
| \--color-data-blue-4 | #004CBC |
| \--color-data-blue-3 | #2694FE |
| \--color-data-blue-2 | #78BEFF |
| \--color-data-blue-1 | #DBECFF |
| \--color-data-shamrock-5 | #0B603D |
| \--color-data-shamrock-4 | #138546 |
| \--color-data-shamrock-3 | #24BB5E |
| \--color-data-shamrock-2 | #8EF7AA |
| \--color-data-shamrock-1 | #D6FEE4 |
| \--color-data-orange-5 | #A13F04 |
| \--color-data-orange-4 | #D66100 |
| \--color-data-orange-3 | #FD9537 |
| \--color-data-orange-2 | #FDB876 |
| \--color-data-orange-1 | #FFE6CF |
| \--color-data-pink-5 | #8E1073 |
| \--color-data-pink-4 | #D123A1 |
| \--color-data-pink-3 | #F989D3 |
| \--color-data-pink-2 | #FEADE3 |
| \--color-data-pink-1 | #FCE3F4 |
| \--color-data-purple-5 | #3E0697 |
| \--color-data-purple-4 | #6B1EFD |
| \--color-data-purple-3 | #9081FF |
| \--color-data-purple-2 | #B3B0FE |
| \--color-data-purple-1 | #E8E8FB |
| \--color-data-red-5 | #9D0519 |
| \--color-data-red-4 | #D31130 |
| \--color-data-red-3 | #FB7D87 |
| \--color-data-red-2 | #FFB2B8 |
| \--color-data-red-1 | #FEE4E6 |
| \--color-data-teal-5 | #08767D |
| \--color-data-teal-4 | #0C9293 |
| \--color-data-teal-3 | #0DB7AF |
| \--color-data-teal-2 | #6CE6D8 |
| \--color-data-teal-1 | #D7FCF8 |
| \--color-data-yellow-5 | #8A5001 |
| \--color-data-yellow-4 | #D69804 |
| \--color-data-yellow-3 | #FBCE03 |
| \--color-data-yellow-2 | #FCEC85 |
| \--color-data-yellow-1 | #FDF6BA |
| \--color-data-gray-5 | #25363F / #333338 |
| \--color-data-gray-4 | #5D6C7B / #666A72 |
| \--color-data-gray-3 | #AFB9C4 / #B2B8BE |
| \--color-data-gray-2 | #CCD3DB / #D0D3D6 |
| \--color-data-gray-1 | #F1F4F7 / #F2F4F6 |
| \--color-brand |     |

Usage
-----

Copy link

Applying color tokens

tsx

`   import * as stylex from '@stylexjs/stylex';  import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';  ​  const styles = stylex.create({    container: {      backgroundColor: colorVars['--color-background-surface'],      color: colorVars['--color-text-primary'],      borderColor: colorVars['--color-border'],    },    accent: {      color: colorVars['--color-text-accent'],    },  });   `

Best Practices
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Use semantic tokens (--color-text-primary) instead of raw hex values. |
| Do  | Rely on the surface hierarchy (body → surface → card → popover) for layering. |
| Do  | Use status colors (success, error, warning) only for their semantic meaning. |
| Don't | Hardcode hex values, since they won't adapt to dark mode or custom themes. |
| Don't | Mix accent colors with status colors in the same context. |
| Don't | Use --color-on-accent on non-accent backgrounds. |

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/color)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Illustrations · Astryx

[Skip to content](https://astryx.atmeta.com/docs/illustrations#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Illustrations
=============

Illustration guidelines for empty states, onboarding flows, and feature highlights.

When to Use
-----------

Copy link

Consistent illustration usage reinforces brand identity and helps users understand context at a glance. Use illustrations in these contexts:

| Context | Examples |
| --- | --- |
| Empty states | No data, first-time experience, search with no results |
| Onboarding | Welcome screens, feature introduction, setup wizards |
| Feature highlights | New feature announcements, upgrade prompts |
| Error states | Permission denied, not found, service unavailable |

Guidelines
----------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Keep illustrations consistent in style across the product. |
| Do  | Use simple, flat illustrations that work in both light and dark mode. |
| Do  | Size illustrations proportionally to the container, typically 120–240px. |
| Do  | Center illustrations with supporting text below. |
| Don't | Mix illustration styles from different sources. |
| Don't | Use illustrations as decoration without purpose. |

Placement
---------

Copy link

Center illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.

Empty state with illustration

tsx

`   <Center>    <Stack direction="vertical" gap={3} hAlign="center">      <img        src="/illustrations/empty-search.svg"        alt="No results"        style={{ width: 200, height: 200 }}      />      <Heading level={3}>No results found</Heading>      <Text type="body" color="secondary">        Try adjusting your search or filters to find what you’re        looking for.      </Text>    </Stack>  </Center>   `

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/illustrations)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Migration Guide · Astryx

[Skip to content](https://astryx.atmeta.com/docs/migration#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Migration Guide
===============

How to migrate an existing Tailwind, shadcn, or Radix application to the design system incrementally.

Overview
--------

Copy link

Treat migration as a product-shell and workflow migration, not a global class replacement. Start by putting the app inside Theme and AppShell, then move one route or surface at a time to design system primitives while keeping existing data, routing, and business logic intact.

Tailwind can coexist during migration. Use it for legacy wrappers and local layout while replacing interactive controls, navigation, command surfaces, forms, alerts, dialogs, and settings UI with components.

Recommended Order
-----------------

Copy link

1.  Install the design system and run init so the project has package scripts, theme CSS, and agent docs.
2.  Wrap the app root with Theme and choose the initial light, dark, or system mode behavior.
3.  Make Tailwind and design system CSS layer order explicit before replacing components.
4.  Render the foundation smoke test page and confirm primitives keep their padding before migrating any surface.
5.  Move the persistent frame first: AppShell, TopNav, SideNav, page content, and mobile navigation.
6.  Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, Tabs, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.
7.  Replace global workflows: command palette, settings popover, theme toggle, search, filters, create flows, and destructive confirmation dialogs.
8.  Remove legacy Tailwind classes from each completed surface, keeping only token-backed layout utilities or local wrappers that still need to be migrated.
9.  Verify both light and dark modes, keyboard navigation, responsive layout, and empty/error/loading states before moving to the next route.

CLI Workflow
------------

Copy link

Use the CLI as the migration checklist. Read the docs for the pattern you are about to touch, inspect a matching template skeleton, then read the exact component docs before editing.

Migration-oriented CLI pass

bash

`   astryx docs migration  astryx docs theme  astryx docs styling  astryx template --list --type block  astryx template AppShellTopNavWithSideNav --skeleton  astryx template PopoverSettingsPanel --skeleton  astryx component AppShell  astryx component SideNav  astryx component TopNav  astryx component CommandPalette  astryx component Button  astryx component TextInput   `

Use --dense when pasting output into an AI coding tool, and use --json when building automated migration reports.

Dense and JSON modes

bash

`   astryx docs migration --dense  astryx component Button --json   `

Theme and CSS Setup
-------------------

Copy link

Mount Theme at the app root so every migrated component reads the same token set. Keep the mode in application state if users can switch between light and dark themes.

Root provider with explicit mode

tsx

`   import {Theme} from '@astryxdesign/core/theme';  import {neutralTheme} from '@astryxdesign/theme-neutral/built';  import {useState} from 'react';  import '@astryxdesign/theme-neutral/theme.css';  ​  export function AppRoot({children}: {children: React.ReactNode}) {    const [mode, setMode] = useState<'system' | 'light' | 'dark'>('system');  ​    return (      <Theme theme={neutralTheme} mode={mode}>        <SettingsContext.Provider value={{mode, setMode}}>          {children}        </SettingsContext.Provider>      </Theme>    );  }   `

When Tailwind remains in the app, declare layer order once in the global CSS file. design system reset and theme CSS should load before Tailwind utilities so migrated components keep design system defaults while legacy utility classes still work.

Tailwind v4 coexistence

css

`   @layer reset, theme, base, astryx-base, astryx-theme, components, utilities;  ​  @import "tailwindcss/theme.css" layer(theme);  @import "tailwindcss/preflight.css" layer(base);  @import "@astryxdesign/core/reset.css";  @import "@astryxdesign/core/astryx.css";  @import "@astryxdesign/theme-neutral/theme.css";  @import "@astryxdesign/core/tailwind-theme.css";  @import "tailwindcss/utilities.css" layer(utilities);   `

On Tailwind v3 there is no preflight.css to import, so wrap the @tailwind base directive in a named layer instead. Keep utilities unlayered so existing app utility classes still win everywhere.

Tailwind v3 coexistence

css

`   @layer reset, tw-preflight, astryx-base, astryx-theme;  ​  @import "@astryxdesign/core/reset.css";  @import "@astryxdesign/core/astryx.css";  @import "@astryxdesign/theme-neutral/theme.css";  ​  @layer tw-preflight {    @tailwind base; /* layered: astryx-theme now wins over preflight */  }  @tailwind components;  @tailwind utilities; /* unlayered: legacy utility classes keep winning */   `

Cascade Layer Safety
--------------------

Copy link

In a stylesheet with no layers at all, a zero-specificity reset like `* { padding: 0 }` loses to any class selector, so most developers treat resets as harmless. Layers change the rules twice: unlayered styles beat every named layer, and a later layer beats an earlier one, both regardless of specificity. The same reset therefore wins against every component style either by staying unlayered or by landing in a layer declared after astryx-base. Same CSS, opposite outcome, and no error or warning when it happens.

This is the most common way an adoption breaks, through one of two @import mechanisms. A top-level @import without the layer() keyword keeps the legacy reset unlayered, where it overrides every design system layer. And an @import nested inside a file that was itself imported into a layer inherits that surrounding layer, so a reset can silently land in a consumer layer above astryx-base. Either way the fix is the same: import the legacy reset into the lowest layer explicitly.

Legacy reset, explicitly layered

css

`   /* was: @import "./legacy-reset.css";  (unlayered: beats every layer) */  @import "./legacy-reset.css" layer(reset);   `

Audit the layers around the design system with this checklist before building screens.

*   Declare the canonical @layer order once, before any @import. With webpack-based bundlers (including Next.js) the order declaration must live in its own CSS file imported first, such as layers.css, because webpack hoists @import content above the inline CSS that follows it.
*   Audit every pre-existing global or reset stylesheet and assign each one to a layer deliberately. Top-level imports without layer() stay unlayered and beat every layer; imports nested inside a layered file inherit that layer.
*   Remove or demote the app legacy reset. The design system ships its own :where() reset in the lowest layer, so any app reset belongs in that same reset layer and never in a layer above astryx-base.
*   Layer Tailwind preflight. On Tailwind v4, import preflight.css with layer(base). On Tailwind v3, wrap the @tailwind base directive in a named layer (see the snippet in Theme and CSS Setup). Unlayered preflight overrides theme CSS silently.
*   Set moduleResolution to bundler or node16 and newer so subpath imports like @astryxdesign/core/reset.css resolve.
*   Theme with defineTheme and the accent family API instead of hand-writing individual color tokens. Derived tokens like --color-on-accent are generated from the accent scale automatically; hand-writing only --color-accent leaves --color-on-accent at its stale white default with no contrast guarantee against the new accent.
*   Run the foundation smoke test below and view a few components in both light and dark mode before migrating any route.

One more mental model shift: a className or utility class you write on a component still reaches the DOM either way, but whether it overrides the component is a layer question, not a source order question. Keep app utilities in the utilities layer so they keep winning.

Foundation Smoke Test
---------------------

Copy link

A broken layer order fails silently and identically on every page, so catch it before feature work instead of after N migrated screens. Render one throwaway page with a few primitives as the first migration step.

Foundation check page

tsx

`   import {useState} from 'react';  import {Button} from '@astryxdesign/core/Button';  import {Card} from '@astryxdesign/core/Card';  import {Table} from '@astryxdesign/core/Table';  import {TextInput} from '@astryxdesign/core/TextInput';  import {VStack} from '@astryxdesign/core/VStack';  ​  export default function FoundationCheck() {    const [email, setEmail] = useState('');  ​    return (      <div data-foundation-check>        <VStack gap={4}>          <Button label="Primary action" variant="primary" />          <TextInput            label="Email"            placeholder="you@example.com"            value={email}            onChange={setEmail}          />          <Card>One card with default padding</Card>          <Table            data={[{name: 'Foundation', status: 'ok'}]}            columns={[              {key: 'name', header: 'Name'},              {key: 'status', header: 'Status'},            ]}          />        </VStack>      </div>    );  }   `

If the button renders with visible padding, a filled primary background, and the input and card have borders and internal spacing, the foundation is sound. For an assertion that can run in any test runner or a dev-only effect, check that a primitive keeps non-zero padding:

Foundation assertion

ts

`   const button = document.querySelector<HTMLButtonElement>(    '[data-foundation-check] button',  );  if (!button) {    throw new Error('Foundation check page did not render a button.');  }  if (getComputedStyle(button).paddingInline === '0px') {    throw new Error(      'Foundation broken: an unlayered reset or a later cascade layer is ' +        'overriding component styles. Check that no app reset sits outside ' +        'the reset layer.',    );  }   `

When this fails, the fix is almost always in the layer order: find the stylesheet that zeroes padding, and move it into the reset layer or delete it.

Move the App Frame First
------------------------

Copy link

Start with AppShell so page migration happens inside the final navigation, spacing, surface, and responsive frame. This also exposes theme and color issues early because every route shares the same shell.

| Legacy surface | Component | Notes |
| --- | --- | --- |
| Header | TopNav | Use for product identity, global actions, account entry, and command/search trigger. |
| Sidebar | SideNav | Use sections and nested nav items for route groups. Keep selection state driven by the router. |
| Main page wrapper | AppShell + Layout | Let the shell own persistent structure; let route components own page content. |
| Mobile drawer nav | MobileNav or AppShell mobile behavior | Verify focus, close behavior, and route changes on narrow viewports. |
| Settings menu | Popover + Layout + Switch | Use as the home for theme mode and app preferences. |

Map shadcn and Radix Primitives
-------------------------------

Copy link

Do not wrap old shadcn components in design system styles. Replace the primitive with the component that owns the behavior, accessibility, state classes, and token usage.

| Existing primitive | Component | Migration note |
| --- | --- | --- |
| button / shadcn Button | Button or IconButton | Use Button for labeled commands and IconButton for icon-only toolbar actions. |
| input | TextInput | Keep validation state in status props rather than ad hoc border classes. |
| textarea | TextArea | Use when multiline editing is the primary action. |
| switch | Switch | Use for persisted boolean settings, including theme mode when represented as a binary choice. |
| checkbox | CheckboxInput or CheckboxList | Use list variants for grouped selection. |
| radio group | RadioList | Use when one option must be selected from a visible set. |
| select / combobox | Selector or Typeahead | Use Selector for bounded options and Typeahead for searchable async options. |
| tabs used as page nav | TabList | Use route state or current page state as the source of truth. |
| command dialog | CommandPalette | Keep app-specific search sources outside the shell and feed searchable items. |
| dropdown action menu | DropdownMenu or MoreMenu | Use MoreMenu for compact overflow actions. |
| alert / callout | Banner or Toast | Use Banner for page or section messages and Toast for transient feedback. |
| dialog | Dialog or AlertDialog | Use AlertDialog for destructive confirmation and Dialog for task flows. |
| card-like list row | ListItem | Prefer ListItem for selectable rows instead of styling Button as a row. |

Command Palette, Settings, and Theme
------------------------------------

Copy link

Move global search to CommandPalette once the shell exists. Treat the palette as a view over app commands: routes, contextual actions, create actions, filters, recent items, and entity results. Keep data normalization in app code so search sources always return arrays of searchable items.

Put light and dark mode controls in the settings popover or account menu. The switch or selector should update the mode passed to Theme, not toggle isolated body classes.

Settings popover theme control

tsx

`   function ThemeModeSwitch() {    const {mode, setMode} = useSettings();    const isDark = mode === 'dark';  ​    return (      <Switch        label="Dark mode"        description="Use the dark color theme"        value={isDark}        onChange={next => setMode(next ? 'dark' : 'light')}      />    );  }   `

Verification Checklist
----------------------

Copy link

*   Run the app in light and dark mode and check that surfaces, borders, text, icons, hover states, focus rings, and status colors flow together.
*   Open the command palette from the shell, type into it, select items by keyboard, and confirm focus returns to the trigger.
*   Check the SideNav at collapsed, expanded, active, hover, nested, and mobile states.
*   Verify settings popovers and dialogs in jsdom and in a real browser because native dialog and Popover APIs may need test shims.
*   Search for leftover hardcoded Tailwind colors, arbitrary hex values, and one-off hover colors after each route migration.
*   Run component tests, build, and at least one browser screenshot pass for each migrated route.

AI Migration Prompt
-------------------

Copy link

When using an AI coding agent, give it an explicit migration loop instead of asking for a full-app rewrite.

Paste this into your AI

text

`   We are migrating this existing Tailwind/shadcn app to Astryx incrementally.  ​  First run:  - astryx docs migration --dense  - astryx docs theme --dense  - astryx docs styling --dense  - astryx template AppShellTopNavWithSideNav --skeleton  ​  Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.   `

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/migration)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Motion · Astryx

[Skip to content](https://astryx.atmeta.com/docs/motion#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Motion
======

Duration and easing tokens for animations and transitions.

Overview
--------

Copy link

Motion serves two purposes: it makes interfaces easier to understand, and it makes them more pleasant to use. A panel animating open helps the eye track what changed and where new content sits in the layout. These moments reduce cognitive load and make the interface feel responsive.

At the same time, well-tuned motion gives an application a sense of craft and polish that users notice, even if they can't name it.

The design system provides duration and easing tokens that keep these moments consistent across your application.

### Duration

Copy link

| Token | Value |
| --- | --- |
| \--duration-fast-min | 130ms |
| \--duration-fast | 175ms |
| \--duration-fast-max | 230ms |
| \--duration-medium-min | 310ms |
| \--duration-medium | 410ms |
| \--duration-medium-max | 550ms |
| \--duration-slow-min | 730ms |
| \--duration-slow | 975ms |
| \--duration-slow-max | 1300ms |

### Easing

Copy link

| Token | Value |
| --- | --- |
| \--ease-standard | cubic-bezier(0.24, 1, 0.4, 1) |

Where Motion Helps
------------------

Copy link

Some parts of the interface benefit from animation. Panels, dialogs, and collapsible sections are disorienting when they appear instantly, so animation gives the eye something to follow. Toasts and notifications need just enough entrance to be noticed without startling. State changes like a switch flipping or a selection highlighting feel more intentional with a brief transition.

The common thread is that these are moments where the user needs to understand what happened.

Where Motion Hurts
------------------

Copy link

Table row hovers. List item highlights. Anything the user does dozens of times per minute. Adding perceptible duration to these interactions makes the interface feel like it's catching up to the cursor. Keep these fast enough that the user never notices a delay.

Animations that block interaction are worse. If a user has to wait for a panel to finish sliding before they can click something inside it, the animation has become an obstacle. Motion should never stand between the user and their next action.

Movement Principles
-------------------

Copy link

*   Not everything needs an animated exit. Elements the user is moving away from, such as tooltips, hover cards, and dropdown menus, can disappear instantly. The user has already shifted their attention. Animate the exit only when it helps orient the user, like a panel closing or a dialog dismissing to reveal what's underneath.
*   When you do animate exit, match the entrance. A panel that slides in from the right should slide back out to the right.
*   Direction should match the action. Navigating deeper into content should feel like moving forward. Going back should feel like returning. This keeps the user oriented in the structure of the application.
*   Contextual UI should feel connected to its trigger. A dropdown should expand from the button that opened it. A popover should appear near the element it describes. This doesn't apply to global UI like command palettes or toasts, which have their own fixed positions.

Respecting User Preferences
---------------------------

Copy link

Some users experience motion sensitivity; animation that feels polished to one person can cause discomfort for another. Components should honor the operating system's reduced motion setting. When it's enabled, replace animations with instant state changes.

Usage
-----

Copy link

Applying motion tokens

tsx

`   import {durationVars, easeVars} from '@astryxdesign/core';  ​  const styles = stylex.create({    fadeIn: {      transitionProperty: 'opacity',      transitionDuration: durationVars['--duration-fast'],      transitionTimingFunction: easeVars['--ease-standard'],    },    slideUp: {      transitionProperty: 'transform, opacity',      transitionDuration: durationVars['--duration-medium'],      transitionTimingFunction: easeVars['--ease-standard'],    },  });   `

Best Practices
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Animate transitions that involve spatial change: panels opening, content expanding, elements entering the screen. |
| Do  | Use fast tokens for small, frequent interactions. Use medium tokens for larger transitions that rearrange the layout. |
| Do  | Honor reduced motion preferences at the OS level. |
| Don't | Let hover states or high-frequency interactions feel like they're lagging behind the user. |
| Don't | Let animation delay when a user can interact with new content. The transition should complete before (or not block) the next action. |
| Don't | Move elements in ways that contradict where they came from or where they're going. |

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/motion)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Layout · Astryx

[Skip to content](https://astryx.atmeta.com/docs/layout#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Layout
======

Frame-first app layout: choosing a shell, budgeting regions, and when to use cards vs rows.

Frame First
-----------

Copy link

Decide the frame before writing any content. Real applications are built top-down: pick the shell, name its regions, give each region an explicit size budget, then fill regions with content. Content-first layout (writing sections and wrapping each one in a Card) produces a padded scroll column that reads as a prototype, not a product.

1.  Pick the frame: AppShell (top nav and/or side nav apps), Layout + LayoutPanel + LayoutContent (multi-pane tools like explorers and consoles), or a plain content column (documents, marketing, forms)
2.  Budget regions in px before filling them: side nav 240–280, icon rail 64–72, detail/inspector panel 340–420, filter/facet rail 220–260
3.  Decide the container policy per region: dense data renders as rows; widget dashboards and galleries render as card grids (see Cards vs Rows)
4.  Write the responsive contract up front: which regions collapse, overlay, or drop at which breakpoints (see Responsive Contract)

A three-region tool frame

tsx

`   // Frame: nav 256 | content flex | inspector 380 (resizable)  <AppShell sideNav={<SideNav>{/* nav items */}</SideNav>} contentPadding={0}>    <Layout>      <LayoutContent>{/* dense list or table, edge-to-edge */}</LayoutContent>      <LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider>        {/* inspector for the selected row */}      </LayoutPanel>    </Layout>  </AppShell>   `

App Archetypes
--------------

Copy link

Match the frame and container policy to the kind of app you are building. These recipes are distilled from product-scale apps built with the design system; container choice tracks the archetype, not personal preference.

| Archetype | Frame | Container policy |
| --- | --- | --- |
| Tracker / work tool (issues, tickets, CRM) | AppShell + SideNav; inspector LayoutPanel on select | Rows only. Grouped edge-to-edge lists, zero cards |
| Console / observability (metrics, logs, deploys) | AppShell + SideNav or TopNav + TabList | Card grid for dashboard widgets; Table for everything else |
| Messaging / feed | Column frame: rail + sidebar + stream + panel | Rows and bubbles. No cards in the stream |
| Media library / gallery | AppShell + TopNav; grid content | Card grid (ClickableCard) with dense metadata rows in detail views |
| Settings / forms | AppShell + SideNav or settings template | Sections with FormLayout; Card only to group dangerous or billing actions |

Start from a template that matches the archetype (`npx astryx template --list`), then study its structure with `--skeleton` before customizing.

Cards vs Rows
-------------

Copy link

Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data (anything the user scans, filters, or selects) belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.

*   Table (with selection/sorting plugins) for columnar records: hosts, deployments, monitors, users
*   List/Item rows for scannable single-line records: issues, files, conversations
*   Card for self-contained widgets: KPI tiles, chart panels, gallery entries, settings groups
*   EmptyState inside the region when a filter matches nothing

*   Wrapping each list item in a Card (card soup)
*   Stacking full-width Cards as a substitute for page structure
*   Nesting Cards inside Cards
*   Using Badge as decoration: reserve it for counts and enumerated states; use StatusDot or Token for status and metadata

Panels and Inspectors
---------------------

Copy link

Master-detail is the backbone of tool UIs: selecting a row opens a fixed-width inspector panel rather than navigating away. Use LayoutPanel in the end slot with an explicit width budget; add resizable (useResizable) for user control, and let the panel overlay the content region below ~1024px instead of compressing it.

Inspector that overlays at narrow widths

tsx

`   <LayoutPanel    width={380}    hasDivider    isScrollable    label="Details"    resizable={{minSizePx: 320, maxSizePx: 480, autoSaveId: 'inspector'}}>    {selected ? <DetailFields item={selected} /> : <EmptyState title="Nothing selected" />}  </LayoutPanel>   `

Responsive Contract
-------------------

Copy link

Declare breakpoint behavior as a contract before building, and keep it in a comment at the frame root. A typical contract: full frame above 1024px; inspector panels overlay the content column at 1024px and below; the side nav collapses into MobileNav at 768px and below. Deciding this up front keeps every region change intentional instead of emergent.

Contract comment at the frame root

tsx

`   // Responsive contract:  //   > 1024px  nav 256 | content | inspector 380  //   <= 1024px inspector overlays content (position: absolute, end-aligned)  //   <= 768px  nav collapses into MobileNav drawer; toolbar actions wrap   `

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/layout)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Spacing · Astryx

[Skip to content](https://astryx.atmeta.com/docs/spacing#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Spacing
=======

Spacing scale tokens for padding, gap, and margin: the rhythmic foundation of design system layouts.

Overview
--------

Copy link

The design system uses a 4px base-unit spacing scale. Component gap props accept step values that map to these tokens. The scale provides fine-grained control at the small end (2px, 4px, 6px) and consistent rhythm at larger sizes (multiples of 4px).

### Scale

Copy link

| Token | Value |
| --- | --- |
| \--spacing-0 | 0px |
| \--spacing-0-5 | 2px |
| \--spacing-1 | 4px |
| \--spacing-1-5 | 6px |
| \--spacing-2 | 8px |
| \--spacing-3 | 12px |
| \--spacing-4 | 16px |
| \--spacing-5 | 20px |
| \--spacing-6 | 24px |
| \--spacing-7 | 28px |
| \--spacing-8 | 32px |
| \--spacing-9 | 36px |
| \--spacing-10 | 40px |
| \--spacing-11 | 44px |
| \--spacing-12 | 48px |

Usage
-----

Copy link

Most components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX.

Spacing via component props vs StyleX

tsx

`   // Via component props (preferred)  <Stack gap={4}>{/* 16px gap */}</Stack>  ​  // Via StyleX tokens (custom layouts)  import {spacingVars} from '@astryxdesign/core';  ​  const styles = stylex.create({    custom: {      padding: spacingVars['--spacing-4'],      gap: spacingVars['--spacing-3'],    },  });   `

Best Practices
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Use component gap props when available; they handle automatic spacing compensation. |
| Do  | Stick to the scale for consistency. If a value isn't on the scale, reconsider the design. |
| Do  | Use smaller steps (0.5–2) for tight internal spacing and larger steps (4–8) for section gaps. |
| Don't | Use arbitrary pixel values outside the scale. |
| Don't | Mix spacing tokens with raw px/rem values in the same component. |

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/spacing)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Principles · Astryx

[Skip to content](https://astryx.atmeta.com/docs/principles#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Principles
==========

Core design principles and rules for building with the design system.

Design Philosophy
-----------------

Copy link

A design system that prioritizes consistency, adaptability, and developer experience. Every decision flows from a few core ideas:

*   Components over primitives: use components for everything they cover before reaching for raw HTML
*   Semantic tokens over hardcoded values: colors, spacing, and radii are named by purpose, not appearance
*   Theme-agnostic code: your app code never references specific colors or measurements, so themes and dark mode work automatically
*   Open internals: every primitive is exported and composable, so you can build on top of it without fighting it

Rules
-----

Copy link

1.  Use components for everything they cover
2.  Layout is frame-first: pick the shell and budget regions before writing content (see [`astryx docs layout`](https://astryx.atmeta.com/docs/layout)
    )
3.  Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups
4.  StyleX or Tailwind for custom styling; both are first-class (see [`astryx docs styling`](https://astryx.atmeta.com/docs/styling)
    )
5.  Semantic tokens, not hardcoded values (see [`astryx docs tokens`](https://astryx.atmeta.com/docs/tokens)
    )
6.  CSS custom properties for colors, not hex values
7.  Form inputs are controlled (value + onChange)
8.  Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider

Styling Approach
----------------

Copy link

The design system supports multiple styling approaches. Every component accepts an `xstyle` prop for StyleX style overrides via `stylex.create()`. For layout and wrapper styling outside of components, use StyleX or Tailwind utilities; both resolve to the same design tokens.

See [`astryx docs styling`](https://astryx.atmeta.com/docs/styling)
 for the complete guide with examples.

Anti-Patterns
-------------

Copy link

| Guidance | Practices |
| --- | --- |
| Don't | Inline styles on raw elements. Use xstyle on components |
| Don't | Hardcoded colors (#fff). Use var(--color-\*) or Tailwind semantic classes (text-primary, bg-surface) |
| Don't | Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities |
| Don't | Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider |
| Don't | Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see [`astryx docs layout`](https://astryx.atmeta.com/docs/layout)<br>) |
| Don't | Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status |
| Don't | Inventing props. Read component docs first |

Design Tokens
-------------

Copy link

The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run [`astryx docs tokens`](https://astryx.atmeta.com/docs/tokens)
 for the full reference with all values.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/principles)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Internationalization · Astryx

[Skip to content](https://astryx.atmeta.com/docs/internationalization#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Internationalization
====================

Set the active locale for astryx components, load locale catalogs, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.

Quick Start
-----------

Copy link

Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.

Wrap your app

tsx

`   import {InternationalizationProvider} from '@astryxdesign/core/i18n';  ​  function App() {    return (      <InternationalizationProvider locale="en">        <YourApp />      </InternationalizationProvider>    );  }   `

The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.

Load an astryx locale catalog

tsx

`   import {InternationalizationProvider} from '@astryxdesign/core/i18n';  import fr from '@astryxdesign/core/locales/fr.json';  ​  <InternationalizationProvider locale="fr" messages={{fr}}>    <App />  </InternationalizationProvider>;   `

Astryx ships English today, with first-party translations for other locales on the roadmap. Until a locale is available from `@astryxdesign/core/locales/*`, apps can pass a local catalog with the same shape. See `@astryxdesign/core/locales/en.json` for the current key inventory. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).

Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.

Runtime language swap
---------------------

Copy link

Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.

Toggle between locales

tsx

`   const [locale, setLocale] = useState<'en' | 'fr'>('en');  ​  <InternationalizationProvider locale={locale} messages={{fr}}>    <Button      label={locale === 'en' ? 'Français' : 'English'}      onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}    />    <App />  </InternationalizationProvider>;   `

Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.

Text direction (RTL)
--------------------

Copy link

Astryx tracks text direction (`'ltr'` or `'rtl'`) alongside the locale. By default the direction is derived from the `locale` you pass to `<InternationalizationProvider>` via [\`Intl.Locale.getTextInfo()\`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo)
, so RTL locales such as Arabic (`ar`), Hebrew (`he`), Farsi (`fa`), and Urdu (`ur`) resolve to `'rtl'` automatically.

You don't wire anything per component. Once the direction is set, astryx components mirror on their own: layout and spacing flip via CSS logical properties, directional icons (chevrons, carets) flip in place, keyboard arrow keys swap left/right, and overlays position on the correct side. Set the direction once and the whole component tree follows.

Direction derived from locale

tsx

`   import {InternationalizationProvider} from '@astryxdesign/core/i18n';  ​  // direction resolves to 'rtl' automatically from the Arabic locale  <InternationalizationProvider locale="ar">    <App />  </InternationalizationProvider>;   `

Pass the optional `dir` prop to force a direction. This overrides the locale-derived default; useful for RTL layout testing under an English catalog, or to skip derivation when you already know the direction.

Explicit direction override

tsx

`   // force RTL layout while keeping English strings  <InternationalizationProvider locale="en" dir="rtl">    <App />  </InternationalizationProvider>;   `

There's one more step: tell the browser about the direction too. Add a `dir` attribute to your page; usually on the `<html>` tag. This is what makes text align to the correct side, punctuation and mixed-language text flow correctly, and layouts mirror. The provider handles astryx components; the `dir` attribute handles everything else on the page.

Astryx doesn't set `dir` for you; you set it, alongside the same direction you pass to the provider. If your app is server-rendered (like Next.js), the `getLocaleDirection()` helper computes the direction from a locale so you can set it while the page renders:

Set <html dir> in a Next.js root layout

tsx

`   import {getLocaleDirection} from '@astryxdesign/core/i18n';  ​  export default function RootLayout({children, params}) {    const {locale} = params;    return (      <html lang={locale} dir={getLocaleDirection(locale)}>        <body>{children}</body>      </html>    );  }   `

In a plain client app, set the same attribute on `<html>` whenever the locale changes. (`getLocaleDirection()` safely returns `'ltr'` for anything it doesn't recognize, so you can call it with any locale string.)

To make just one part of a left-to-right page right-to-left; say an Arabic quote or a comment thread; wrap that part in its own `<InternationalizationProvider dir="rtl">` and add `dir="rtl"` to the element around it. Pop-up overlays; menus, dialogs, popovers, tooltips; opened from inside that region mirror too: they position with logical CSS anchor placement, so they land on the correct side and inherit the region's direction automatically.

Overriding astryx's default text
--------------------------------

Copy link

Use `overrides` to change individual strings without shipping a full catalog. Overrides are keyed by locale and merged on top of the built-in and user-supplied catalogs.

Change one string in English

tsx

`   <InternationalizationProvider    locale="en"    overrides={{en: {'@astryx.pagination.next': 'Next →'}}}  >    <App />  </InternationalizationProvider>   `

Overrides win over both bundled English and any `messages` catalog for the same key. Use them for brand voice tweaks or one-off wording changes.

Using astryx with your own i18n library
---------------------------------------

Copy link

Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use: react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.

Astryx + react-intl side by side

tsx

`   import {InternationalizationProvider} from '@astryxdesign/core/i18n';  import {Selector} from '@astryxdesign/core/Selector';  import {Button} from '@astryxdesign/core/Button';  import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';  import astryxFr from './locales/astryx/fr.json'; // astryx's UI, in French  import appFr from './locales/app/fr.json';       // your app strings, in French  ​  function Pricing() {    // Consumer strings — resolved by react-intl.    const intl = useIntl();  ​    return (      <section>        <h1><FormattedMessage id="pricing.heading" /></h1>  ​        {/* Astryx Selector — trigger placeholder, search-box placeholder,            clear-button aria-label all resolved by            <InternationalizationProvider>. Options come from react-intl. */}        <Selector          label={intl.formatMessage({id: 'pricing.region.label'})}          options={[            {value: 'na', label: intl.formatMessage({id: 'pricing.region.na'})},            {value: 'eu', label: intl.formatMessage({id: 'pricing.region.eu'})},          ]}          hasSearch          hasClear        />  ​        <Button label={intl.formatMessage({id: 'pricing.cta.subscribe'})} />      </section>    );  }  ​  export default function App() {    return (      // Same locale, two providers reading their own catalogs.      <IntlProvider locale="fr" messages={appFr}>        <InternationalizationProvider locale="fr" messages={{fr: astryxFr}}>          <Pricing />        </InternationalizationProvider>      </IntlProvider>    );  }   `

Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way: re-render both providers with a new `locale` prop and the whole tree updates live.

Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029)
. For now, run the two providers side by side as shown above.

Using astryx as your i18n library
---------------------------------

Copy link

For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.

Translate app strings with astryx

tsx

`   import {Button} from '@astryxdesign/core/Button';  import {    InternationalizationProvider,    useTranslator,    type Catalog,    type MessagesByLocale,  } from '@astryxdesign/core/i18n';  ​  const en: Catalog = {    '@myapp.actions.save': {defaultMessage: 'Save'},  };  ​  const fr: Catalog = {    '@myapp.actions.save': {defaultMessage: 'Enregistrer'},  };  ​  const messages: MessagesByLocale = {en, fr};  ​  function SaveButton() {    const t = useTranslator();    return <Button label={t('@myapp.actions.save')} />;  }  ​  export default function App() {    return (      <InternationalizationProvider locale="fr" messages={messages}>        <SaveButton />      </InternationalizationProvider>    );  }   `

`Catalog` types a single locale file; `MessagesByLocale` types the map passed to `messages`. A catalog entry uses the same `{defaultMessage, description?}` shape as `@astryxdesign/core/locales/en.json`.

Testing your translations
-------------------------

Copy link

Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.

Turn on pseudo-localization

tsx

`   import {InternationalizationProvider} from '@astryxdesign/core/i18n';  import pseudo from '@astryxdesign/core/locales/pseudo.json';  ​  <InternationalizationProvider locale="pseudo" messages={{pseudo}}>    <App />  </InternationalizationProvider>;   `

For contributors
----------------

Copy link

### Developers

Copy link

Astryx component authors read strings with `useTranslator()` rather than hardcoding user-facing text.

Read an astryx string

tsx

`   import {useTranslator} from '@astryxdesign/core/i18n';  ​  function SaveButton() {    const t = useTranslator();    return <button>{t('@astryx.actions.save')}</button>;  }   `

Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator`; this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.

When you author a component that needs to respond to direction, resolve it from the DOM, not from a render-time JavaScript read, and reach for the lightest tool that works. In priority order:

#### 1\. CSS logical properties first

Copy link

Use `insetInlineStart`, `paddingInlineEnd`, `marginInline`, and friends instead of physical `left`/`right`. Most mirroring needs nothing more; the browser flips it from the ambient `dir`. The `@astryx/no-physical-properties` ESLint rule enforces this.

#### 2\. Directional icons — mirror with CSS, not a name-swap

Copy link

Render one fixed glyph and wrap it in the shared `rtlStyles.mirror` (a `scaleX(-1)` that only applies under `[dir="rtl"]`). It flips from the ancestor `dir` through the cascade, so it works on the server with no hydration flash. Do not pick `chevronLeft` vs `chevronRight` in JS. This is how Pagination, Calendar, and Carousel handle their chevrons.

Mirror a directional icon with CSS

tsx

`   import * as stylex from '@stylexjs/stylex';  import {rtlStyles} from '@astryxdesign/core';  ​  function NextButton() {    // One glyph; CSS flips it under RTL. No direction read.    return (      <span {...stylex.props(rtlStyles.mirror)}>        <Icon icon="chevronRight" />      </span>    );  }   `

#### 3\. Behavioral logic — read the DOM lazily, on the event

Copy link

For things CSS can't express; keyboard arrow-key mapping, drag/scroll math; read direction at interaction time with `isRtlElement(el)` (a `getComputedStyle().direction` check), never during render. The focus primitives (`useListFocus`, `useGridFocus`, `useTreeFocus`) already auto-detect direction from their container, so arrow keys flip for free; don't pass a direction flag to them. (`isRtl` on `useListFocus`/`useGridFocus` is deprecated in favor of auto-detection, and new hooks don't accept it.)

#### 4\. useDirection() context — the last resort

Copy link

Reach for it only when you genuinely need the direction value during render and none of the above fit. It's SSR-safe and returns `'ltr'` outside a provider (matching `useTranslator`'s silent fallback), but it's the one path that can mismatch on hydration if the provider's `direction` disagrees with `<html dir>`; so prefer the options above, which resolve purely from the DOM. As of the CSS-mirror migration, no astryx component reads direction from context at render time.

### Translators

Copy link

Crowdin is the preferred way to contribute; [join a language](https://crowdin.com/project/astryx)
, translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/internationalization)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Theme System · Astryx

[Skip to content](https://astryx.atmeta.com/docs/theme#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Theme System
============

Theme provider, custom themes, theme build for production/SSR, light/dark mode, and component style overrides.

Quick Start
-----------

Copy link

Install a theme package

bash

`   npm install @astryxdesign/theme-neutral   `

Basic theme setup (runtime injection)

tsx

`   import {Theme} from '@astryxdesign/core';  import {neutralTheme} from '@astryxdesign/theme-neutral';  ​  function App() {    return (      <Theme theme={neutralTheme}>        <YourApp />      </Theme>    );  }   `

Optimized setup (pre-built CSS)

tsx

`   import {Theme} from '@astryxdesign/core';  import {neutralTheme} from '@astryxdesign/theme-neutral/built';  import '@astryxdesign/theme-neutral/theme.css';  ​  function App() {    return (      <Theme theme={neutralTheme}>        <YourApp />      </Theme>    );  }   `

Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>`. The same pattern works for every theme; just swap the package and import name.

The default import uses runtime style injection, which works everywhere with no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.

Available Themes
----------------

Copy link

Install the theme package you want with `npm install @astryxdesign/theme-{name}`, then import its theme object as shown below.

| Theme | Import | Description |
| --- | --- | --- |
| Neutral | import {neutralTheme} from '@astryxdesign/theme-neutral' | Muted, minimal aesthetic with system fonts. A good starting point. |
| Butter | import {butterTheme} from '@astryxdesign/theme-butter' | Golden, buttery surfaces with blue accents; Sarina + Outfit type. |
| Chocolate | import {chocolateTheme} from '@astryxdesign/theme-chocolate' | Warm brown tones and cozy beige; Fraunces + Albert Sans type. |
| Gothic | import {gothicTheme} from '@astryxdesign/theme-gothic' | Dark-only atmospheric theme; deep blue-gray surfaces, distressed display type. |
| Matcha | import {matchaTheme} from '@astryxdesign/theme-matcha' | Earthy green theme with Figtree typography. |
| Stone | import {stoneTheme} from '@astryxdesign/theme-stone' | Warm stone and slate tones; Montserrat + Figtree type. |
| Y2K | import {y2kTheme} from '@astryxdesign/theme-y2k' | Playful Y2K pop; periwinkle body, holographic accents, Poppins + Crimson Text. |

All theme packages export from two subpaths: - `@astryxdesign/theme-{name}`: source theme (runtime injection) - `@astryxdesign/theme-{name}/built`: pre-built theme (pair with `theme.css`)

Theme Props
-----------

Copy link

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| theme | DefinedTheme | \-  | Theme object (required) |
| mode | 'system' \| 'light' \| 'dark' | 'system' | Color mode. system follows OS preference. |
| children | ReactNode | \-  | App content |

Creating a Custom Theme
-----------------------

Copy link

Use the CLI wizard (recommended) or create manually with defineTheme. Only override tokens that differ from defaults; omitted tokens use the design system defaults.

Scaffold with CLI

bash

`   astryx theme   `

defineTheme
-----------

Copy link

defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values.

defineTheme with scale configs

tsx

`   import {defineTheme} from '@astryxdesign/core/theme';  ​  const myTheme = defineTheme({    name: 'my-theme',    color: { accent: '#7B61FF', neutralStyle: 'cool' },    typography: {      scale: { base: 14, ratio: 1.2 },      body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' },    },    radius: { base: 4, multiplier: 1 },    motion: { fast: 175, medium: 410, ratio: 0.75 },    tokens: {      // Explicit overrides take precedence over scale-generated values      '--color-accent': ['#7B61FF', '#9B85FF'],    },    components: {      button: { 'variant:primary': { color: 'white' } },    },  });   `

| Config | Generates | Parameters |
| --- | --- | --- |
| color | \--color-accent, --color-background-\*, --color-text-\*, --color-border, etc. | accent? (hex; omit for neutral-only), neutralStyle? (warm\|cool\|neutral), contrast? (standard\|high) |
| typography.scale | \--text-heading-\*-size/weight/leading, --text-body-size/weight/leading | base (px), ratio |
| typography.body/heading/code | \--font-family-body, --font-family-heading, --font-family-code | family, fallbacks?, url?, weight? |
| radius | \--radius-inner, --radius-element, --radius-container, --radius-page, --radius-chat | base (px), multiplier (0–2) |
| motion | \--duration-fast-min/fast/fast-max, --duration-medium-min/medium/medium-max | fast (ms), medium (ms), ratio, easing? |

Extending a Theme
-----------------

Copy link

`extends` lets you derive a new theme from an existing one, inheriting its tokens, component overrides, icons, and fonts. Only specify what you want to change; everything else carries over from the base theme.

Extending the neutral theme

tsx

`   import {defineTheme} from '@astryxdesign/core/theme';  import {neutralTheme} from '@astryxdesign/theme-neutral';  import {myIcons} from './icons';  ​  const brandTheme = defineTheme({    name: 'brand',    extends: neutralTheme,    icons: myIcons,    tokens: {      '--color-accent': ['#7B61FF', '#9B85FF'],    },  });   `

| Field | Merge behavior |
| --- | --- |
| tokens | Base tokens are copied first, then child tokens override on top. |
| components | Deep-merged: child component rules override matching keys from the base. |
| icons | Shallow-merged: child icons override matching names from the base. |
| fonts | Base fonts included first, then child fonts appended. |
| typography, motion, radius, color | Child config replaces base entirely (these are scale inputs, not additive). |

Component Style Overrides
-------------------------

Copy link

The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in [`astryx docs styling`](https://astryx.atmeta.com/docs/styling)
.

Component overrides with standard CSS

tsx

`   components: {    // Standard CSS properties are expanded automatically.    // borderRadius also sets the internal radius var for concentric math.    // padding on container components (card, section, dialog) expands to layout tokens.    card: {      base: { borderRadius: '20px', padding: '24px' },    },    button: {      base: { borderRadius: '9999px', textTransform: 'uppercase' },      'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },    },    // Some components have public CSS vars for properties that don't map    // to standard CSS. Set these directly.    button: {      base: { '--button-press-scale': 'scale(0.95)' },    },  }   `

Run `astryx component <Name>` to see a component's theming targets, public CSS variables, and which standard CSS properties are supported.

*   Write standard CSS properties (borderRadius, padding); the pipeline expands them into internal vars.
*   Set public CSS vars directly when no standard property equivalent exists.

*   Set private CSS vars (prefixed --\_) directly. Use standard CSS properties instead. `astryx theme build` will error.

Custom Variants
---------------

Copy link

Themes can add new prop values to any component. Any `prop:value` key where the value isn't a built-in gets treated as a new variant. Use `astryx theme build` to generate TypeScript augmentations for type safety.

Adding custom variants

tsx

`   components: {    button: {      // Override an existing variant      'variant:secondary': { backgroundColor: 'rgba(0,0,0,0.06)' },      // Add a new variant — generates type augmentation on build      'variant:primary-muted': {        backgroundColor: 'light-dark(#F2F4F6, #28292C)',        color: 'var(--color-text-primary)',      },    },    banner: {      // Any extensible prop axis works — not just variant      'status:neutral': {        backgroundColor: 'var(--color-muted)',        color: 'var(--color-text-secondary)',      },    },  }   `

After building, the new values are type-safe in JSX:

Using custom variants

tsx

`   // TypeScript knows about 'primary-muted' after astryx theme build  <Button variant="primary-muted" label="Save draft" />  <Banner status="neutral" title="Note" />   `

Custom variants only work when the theme that defines them is active. The component's variant map is extended via module augmentation, with no changes to the component source needed.

Building Themes for Production
------------------------------

Copy link

`astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.

Build a theme

bash

`   astryx theme build ./src/themes/ocean.ts   `

This generates the following files alongside the source:

| File | Description |
| --- | --- |
| ocean.css | Pre-compiled CSS with token overrides, component overrides, and prose element styles in @scope rules |
| ocean.js | ES module exporting the theme object with `__built: true` and pre-resolved token values. Also re-exports the icon registry if the source theme declares one. |
| ocean.d.ts | TypeScript declarations for the theme and icon registry exports |
| ocean.variants.d.ts | (Optional) Module augmentations for custom component prop values found in the theme's component overrides |

The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it.

Using a custom built theme

tsx

`   import {oceanTheme} from './themes/ocean';  import './themes/ocean.css';  ​  <Theme theme={oceanTheme}>    <App />  </Theme>   `

Runtime vs Built Themes
-----------------------

Copy link

Themes work in two modes:

|     | Runtime (source) | Built |
| --- | --- | --- |
| Import (published theme) | @astryxdesign/theme-{name} | @astryxdesign/theme-{name}/built + theme.css |
| Import (custom theme) | defineTheme() directly | Built .js + .css from `astryx theme build` |
| How it works | useInsertionEffect injects <style> at hydration | Pre-compiled .css file loaded with the page |
| Component overrides | Injected client-only | In static CSS: present during SSR |
| SSR safe | Tokens yes, component overrides flash on hydration | Fully SSR safe: no flash |
| Best for | Dev, prototyping, client-only SPAs | Production, SSR apps (Next.js, Remix) |

*   Use the /built subpath + theme.css for production SSR apps.
*   Use runtime themes during development for fast iteration.
*   Run `astryx theme build` for custom themes to get the built artifacts.

*   Use runtime themes in production SSR apps; component overrides will flash on hydration.
*   Import /built without the CSS file; component overrides won't apply.

Light/Dark Mode
---------------

Copy link

Use \[light, dark\] tuples in token values for automatic mode switching. Use mode='system' (default) on Theme to follow OS preference.

Light/dark tuple

tsx

`   '--color-accent': ['#0064E0', '#2694FE'],  //                   ^light     ^dark   `

Toggle with a button

tsx

`   const [mode, setMode] = useState<'light' | 'dark'>('light');  ​  <Theme theme={myTheme} mode={mode}>    <Button      label={mode === 'light' ? 'Switch to Dark' : 'Switch to Light'}      onClick={() => setMode(m => (m === 'light' ? 'dark' : 'light'))}    />  </Theme>;   `

Nesting Themes
--------------

Copy link

Wrap different sections in separate <Theme> providers.

Dark sidebar with light content

tsx

`   <Theme theme={lightTheme} mode="light">    <Layout      header={<LayoutHeader>...</LayoutHeader>}      start={        <Theme theme={darkTheme} mode="dark">          <LayoutPanel>{/* Dark sidebar */}</LayoutPanel>        </Theme>      }      content={<LayoutContent>{/* Light content */}</LayoutContent>}    />  </Theme>   `

Token Utilities
---------------

Copy link

Use `tokenVar()` when a non-StyleX styling library wants a CSS variable reference, and `resolveThemeTokens()` when JavaScript needs token values for a specific theme and mode without React context. Themes are also registered by name when created with `defineTheme()`; call `registerTheme(theme)` for prebuilt or object-literal themes that need name-based SSR lookup.

CSS var references for styling-library configs

ts

`   import {tokenVar, tokenVars} from '@astryxdesign/core/theme/tokens';  ​  const pandaOrEmotionTheme = {    colors: {      text: tokenVar('--color-text-primary'),      surface: tokenVars['--color-background-surface'],    },    spacing: {      4: tokenVars['--spacing-4'],    },  };   `

Resolve token values without a hook

ts

`   import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';  import {neutralTheme} from '@astryxdesign/theme-neutral';  ​  const lightTokens = resolveThemeTokens(neutralTheme, {mode: 'light'});  const chartTheme = {    textColor: lightTokens['--color-text-primary'],    seriesColor: lightTokens['--color-data-categorical-blue'],  };   `

The `@astryxdesign/core/theme/tokens` subpath is server-safe and does not require React. The main `@astryxdesign/core/theme` barrel also re-exports these helpers for client code that already imports theme APIs.

useTheme Hook
-------------

Copy link

`useTheme()` uses the same token resolution as `resolveThemeTokens()`, but reads the nearest Theme and effective color mode from React context and media query state. Use it inside client components for SVG, canvas, charts, maps, and third-party configuration objects that need token values in JavaScript instead of `var(...)` references.

Access resolved token values in React

tsx

`   import {useMemo} from 'react';  import {useTheme} from '@astryxdesign/core/theme';  ​  function ChartConfig() {    const {mode, tokens} = useTheme();  ​    const options = useMemo(      () => ({        mode,        textColor: tokens['--color-text-primary'],        gridColor: tokens['--color-border'],        seriesColor: tokens['--color-data-categorical-blue'],      }),      [mode, tokens],    );  ​    return <Chart options={options} />;  }   `

Prefer CSS variables, StyleX token imports, xstyle, or className for ordinary styling. To change the theme or mode, manage state at the app level and pass it to <Theme>.

See [`astryx docs styling-libraries`](https://astryx.atmeta.com/docs/styling-libraries)
 for styling-library interop and [`astryx docs tokens`](https://astryx.atmeta.com/docs/tokens)
 for the full token reference.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/theme)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Shape · Astryx

[Skip to content](https://astryx.atmeta.com/docs/shape#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Shape
=====

Border radius tokens for consistent component rounding, from sharp corners to full pills.

Overview
--------

Copy link

The radius scale uses a semantic naming system: inner → element → container → page. Each level fits a specific context. Themes can multiply the entire scale via a radius multiplier, with --radius-none and --radius-full as fixed anchors.

### Radius Scale

Copy link

| Token | Value | Example |
| --- | --- | --- |
| \--radius-none | 0px |     |
| \--radius-inner | 8px |     |
| \--radius-element | 12px |     |
| \--radius-container | 16px |     |
| \--radius-page | 32px |     |
| \--radius-chat | 28px |     |
| \--radius-full | 9999px |     |

Concentric Radius
-----------------

Copy link

When a rounded container has padding, inner elements need a smaller radius to appear concentric. Components like Card handle this automatically; the inner radius is computed as max(0, outerRadius - padding).

Concentric radius formula

css

`   /* Automatic in Astryx Card */  --card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));   `

Best Practices
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Use --radius-element for interactive controls (buttons, inputs, selectors). |
| Do  | Use --radius-container for content containers (cards, panels, dialogs). |
| Do  | Use --radius-full for pill shapes (badges, tags, avatar status dots). |
| Don't | Use --radius-page for small elements; it's meant for page-level containers. |
| Don't | Hardcode radius values; they won't scale with theme radius multipliers. |

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/shape)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Styling Library Interop · Astryx

[Skip to content](https://astryx.atmeta.com/docs/styling-libraries#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Styling Library Interop
=======================

Integrate Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, and non-CSS renderers with system tokens.

Core Principle
--------------

Copy link

Keep the system as the source of truth for theme values. Components read design tokens from CSS custom properties such as `--color-text-primary`, `--color-background-surface`, `--spacing-4`, and `--radius-container`. Other styling libraries should map their own semantic tokens, utility names, or theme objects to those system CSS variables whenever possible.

Use CSS variables for ordinary DOM styling because they inherit through the tree, follow `data-theme` color mode, respect nested `data-astryx-theme` scopes, and update when themes switch. Use token resolver APIs only for non-CSS consumers such as SVG attribute values, canvas, chart configuration, color calculations, or static config generation.

For available token names and values, run [`astryx docs tokens`](https://astryx.atmeta.com/docs/tokens)
. Focused references are also available with [`astryx docs color`](https://astryx.atmeta.com/docs/color)
, [`astryx docs spacing`](https://astryx.atmeta.com/docs/spacing)
, [`astryx docs shape`](https://astryx.atmeta.com/docs/shape)
, [`astryx docs typography`](https://astryx.atmeta.com/docs/typography)
, [`astryx docs elevation`](https://astryx.atmeta.com/docs/elevation)
, and [`astryx docs motion`](https://astryx.atmeta.com/docs/motion)
.

Choose an Integration Path
--------------------------

Copy link

Choose the narrowest integration path that fits the styling library. Most DOM styling should stay on the CSS-variable path; JavaScript token resolution is for APIs that cannot consume CSS custom properties.

| Path | Use when | Value shape |
| --- | --- | --- |
| CSS variable aliases | The library ultimately writes CSS and accepts string values | `var(--color-text-primary)` |
| StyleX token imports | You are writing StyleX styles in application code | `colorVars['--color-text-primary']` |
| Tailwind bridge | You want utility classes backed by active system tokens | `@astryxdesign/core/tailwind-theme.css` |
| Token resolver APIs | JavaScript needs token values for charts, canvas, SVG, or config objects | `resolveThemeToken(theme, '--color-data-categorical-blue', {mode})` |

Best Practices
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Map by semantic intent: text, surface, border, accent, status, radius, spacing, typography. |
| Do  | Let the system own color mode. The root Theme syncs `data-theme="light\|dark"` and `data-astryx-theme` to `<html>` for portals and first-level theme scope. |
| Do  | Prefer CSS variables for runtime theme switching and nested themes. |
| Don't | Copy raw hex/px values into a second theme object when a `var(...)` reference would work. |
| Don't | Run a second unsynchronized dark-mode provider that disagrees with Theme. |
| Don't | Make another library's CSS variables the source of truth for the system. Some consumers need token values outside the DOM. |

Plain CSS and CSS Modules
-------------------------

Copy link

The simplest integration is direct CSS variable usage. CSS Modules scope class names, but system token variables are global/inherited values supplied by package CSS and the active theme.

Card.module.css

css

`   .card {    background: var(--color-background-surface);    color: var(--color-text-primary);    border: 1px solid var(--color-border);    border-radius: var(--radius-container);    padding: var(--spacing-4);  }   `

Sass variables are compile-time only. They are useful for generating static CSS, but they do not update when the system switches theme or color mode. Use native CSS custom properties for themeable values.

StyleX
------

Copy link

For StyleX styles, prefer the typed token exports from `@astryxdesign/core/theme/tokens.stylex`. They provide autocomplete and catch token-name typos while still resolving through the same system CSS variables at runtime.

Typed token imports

tsx

`   import * as stylex from '@stylexjs/stylex';  import {colorVars, spacingVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';  ​  const styles = stylex.create({    panel: {      backgroundColor: colorVars['--color-background-surface'],      color: colorVars['--color-text-primary'],      padding: spacingVars['--spacing-4'],      borderRadius: radiusVars['--radius-container'],    },  });   `

Use `xstyle` for component overrides and `stylex.props()` for your own DOM nodes. Use `className` when integrating a non-StyleX styling library.

Tailwind
--------

Copy link

The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme.

globals.css

css

`   @layer reset, theme, base, astryx-base, astryx-theme, components, utilities;  ​  @import "tailwindcss/theme.css" layer(theme);  @import "tailwindcss/preflight.css" layer(base);  @import "@astryxdesign/core/reset.css";  @import "@astryxdesign/core/astryx.css";  @import "@astryxdesign/theme-neutral/theme.css";  @import "@astryxdesign/core/tailwind-theme.css";  @import "tailwindcss/utilities.css" layer(utilities);   `

Pre-declare every layer before any imports. This keeps reset lowest, Tailwind preflight above reset, component/theme styles in the middle, and Tailwind utilities last so utility classes on `className` can intentionally override component defaults.

Tailwind classes backed by system tokens

tsx

`   <section className="rounded-lg border border-border bg-surface p-4 text-primary shadow-md">    <Button label="Save" variant="primary" />  </section>   `

The Tailwind bridge is the concrete example of the general interop pattern: expose another library's semantic API, but point the values at system token variables.

Panda, Chakra, and Other Semantic Token Systems
-----------------------------------------------

Copy link

Libraries like Panda CSS and Chakra UI have first-class semantic token objects. Put system CSS variables at the leaves of those objects so product code can use the library's semantic names while the system still owns the values.

Semantic token aliases

ts

`   semanticTokens: {    colors: {      text: {        primary: {value: 'var(--color-text-primary)'},        secondary: {value: 'var(--color-text-secondary)'},      },      background: {        surface: {value: 'var(--color-background-surface)'},        body: {value: 'var(--color-background-body)'},      },      border: {        default: {value: 'var(--color-border)'},      },    },  },  tokens: {    spacing: {      4: {value: 'var(--spacing-4)'},    },    radii: {      container: {value: 'var(--radius-container)'},    },  }   `

Panda-style usage

tsx

`   <section    className={css({      bg: 'background.surface',      color: 'text.primary',      borderColor: 'border.default',      p: '4',      rounded: 'container',    })}  />   `

If a semantic-token library needs to generate its own light/dark CSS from raw values, align its mode selector with Theme (`data-theme="light|dark"`) and generate that adapter from system theme data. Otherwise it can drift from nested or runtime themes.

MUI and Palette-Based Themes
----------------------------

Copy link

MUI expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.

MUI palette mapped to system vars

ts

`   const theme = createTheme({    cssVariables: true,    colorSchemes: {      light: {        palette: {          primary: {main: 'var(--color-accent)'},          background: {            default: 'var(--color-background-body)',            paper: 'var(--color-background-surface)',          },          text: {            primary: 'var(--color-text-primary)',            secondary: 'var(--color-text-secondary)',          },          divider: 'var(--color-border)',        },      },      dark: {        palette: {          primary: {main: 'var(--color-accent)'},          background: {            default: 'var(--color-background-body)',            paper: 'var(--color-background-surface)',          },          text: {            primary: 'var(--color-text-primary)',            secondary: 'var(--color-text-secondary)',          },          divider: 'var(--color-border)',        },      },    },  });   `

If MUI owns color mode in an app, generate the light and dark palette values from system theme data and keep Theme mode synchronized. If Theme owns color mode, keep both MUI schemes pointing at the same system CSS variables.

Emotion, styled-components, Theme UI, and Styled System
-------------------------------------------------------

Copy link

Runtime CSS-in-JS libraries usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.

Generic CSS-in-JS theme object

ts

`   const appTheme = {    colors: {      textPrimary: 'var(--color-text-primary)',      textSecondary: 'var(--color-text-secondary)',      surface: 'var(--color-background-surface)',      border: 'var(--color-border)',      accent: 'var(--color-accent)',    },    spacing: {      4: 'var(--spacing-4)',    },    radius: {      container: 'var(--radius-container)',    },  };   `

Avoid rebuilding CSS-in-JS theme objects with raw color values on every mode switch. CSS variables let the class names stay the same while the browser resolves the active values.

UnoCSS and Custom Utility Systems
---------------------------------

Copy link

Utility generators such as UnoCSS can put system variables in their theme config or shortcuts. Keep classes semantic (`bg-surface`, `text-primary`) and let the values point at system tokens.

UnoCSS-style config

ts

`   export default defineConfig({    theme: {      colors: {        surface: 'var(--color-background-surface)',        primary: 'var(--color-text-primary)',        border: 'var(--color-border)',        accent: 'var(--color-accent)',      },      spacing: {        4: 'var(--spacing-4)',      },    },    shortcuts: {      'xds-card': 'bg-surface text-primary border border-border rounded-lg p-4',    },  });   `

Static utility extractors cannot see dynamically constructed class names. Prefer explicit class strings or the library's safelist/source-registration mechanism.

Non-CSS Processing
------------------

Copy link

Use `resolveThemeTokens()` or `resolveThemeToken()` when code outside React needs token values for a known theme and mode. Use `useTheme()` inside client components when the values should come from the nearest Theme and active mode.

Resolve tokens without React context

ts

`   import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';  import {neutralTheme} from '@astryxdesign/theme-neutral';  ​  const tokens = resolveThemeTokens(neutralTheme, {mode: 'light'});  ​  const chartOptions = {    textColor: tokens['--color-text-primary'],    mutedTextColor: tokens['--color-text-secondary'],    gridColor: tokens['--color-border'],    seriesColors: [      tokens['--color-data-categorical-blue'],      tokens['--color-data-categorical-orange'],      tokens['--color-data-categorical-purple'],    ],  };   `

Resolve tokens from the nearest Theme

tsx

`   'use client';  ​  import {useMemo} from 'react';  import {useTheme} from '@astryxdesign/core/theme';  ​  function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {    const {mode, tokens} = useTheme();  ​    const chartOptions = useMemo(      () => ({        mode,        textColor: tokens['--color-text-primary'],        mutedTextColor: tokens['--color-text-secondary'],        gridColor: tokens['--color-border'],        seriesColors: [          tokens['--color-data-categorical-blue'],          tokens['--color-data-categorical-orange'],          tokens['--color-data-categorical-purple'],        ],      }),      [mode, tokens],    );  ​    return <ThirdPartyChart data={data} options={chartOptions} />;  }   `

Non-CSS Processing Best Practices
---------------------------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Use the returned `tokens` object as a memo dependency; it is stable until the active theme or mode changes. |
| Do  | Use data visualization tokens such as `--color-data-categorical-blue` for chart series instead of reusing arbitrary UI colors. |
| Do  | Prefer CSS variables for SVG elements when possible (`fill="var(--color-accent)"`); use token resolver APIs when an API requires a string value in JavaScript. |
| Don't | Use token resolver APIs for ordinary DOM styling. Use CSS variables, StyleX tokens, xstyle, or library aliases instead. |
| Don't | Assume the returned values reflect every CSS cascade override. They resolve tokens for the current theme and mode; local media-surface overrides and arbitrary CSS overrides may not be represented in the returned map. |

Interop Checklist
-----------------

Copy link

1.  Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `astryx theme build` or published `/built` theme imports plus `theme.css`.
2.  Choose one owner for color mode. Theme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.
3.  Map the external library's semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.
4.  Use [`astryx docs tokens`](https://astryx.atmeta.com/docs/tokens)
     and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.
5.  Use token resolver APIs only for non-CSS APIs that need resolved values.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/styling-libraries)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Typography · Astryx

[Skip to content](https://astryx.atmeta.com/docs/typography#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Typography
==========

Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.

Overview
--------

Copy link

Typography is built on a geometric type scale: base size × ratio^step, with 14px and 1.2 as defaults. Every text style is a semantic token that composes font size, weight, and line-height, so components express intent (heading, body, label) rather than raw values.

Two layers work together: raw size tokens (--font-size-xs ... --font-size-5xl) form the geometric scale, and semantic type scale tokens (--text-heading-1-size, --text-body-leading, etc.) reference them by var(). Themes override the entire scale by adjusting base and ratio in defineTheme; all semantic tokens recompute automatically.

### Font Families

Copy link

Three font roles: body (UI text), heading (titles and headings), and code (monospace). By default, body and heading share the same system font stack; code uses a monospace stack. Custom themes can assign different families per role; heading inherits from body when not explicitly set.

| Token | Value | Example |
| --- | --- | --- |
| \--font-family-body | Figtree | The quick brown fox jumps over the lazy dog |
| \--font-family-code | "SF Mono" | The quick brown fox jumps over the lazy dog |
| \--font-family-heading | Figtree | The quick brown fox jumps over the lazy dog |

### Font Sizes

Copy link

Geometric scale: round(base × ratio^step), expressed in rem. The default scale is 14px × 1.2, producing 12 steps from 4xs (6px) to 5xl (42px). Adjusting base and ratio in defineTheme regenerates every size token while preserving proportional relationships.

| Token | Value | Example |
| --- | --- | --- |
| \--font-size-4xs | 0.375rem | The quick brown fox jumps over the lazy dog |
| \--font-size-3xs | 0.4375rem | The quick brown fox jumps over the lazy dog |
| \--font-size-2xs | 0.5rem | The quick brown fox jumps over the lazy dog |
| \--font-size-xs | 0.625rem | The quick brown fox jumps over the lazy dog |
| \--font-size-sm | 0.75rem | The quick brown fox jumps over the lazy dog |
| \--font-size-base | 0.875rem | The quick brown fox jumps over the lazy dog |
| \--font-size-lg | 1.0625rem | The quick brown fox jumps over the lazy dog |
| \--font-size-xl | 1.25rem | The quick brown fox jumps over the lazy dog |
| \--font-size-2xl | 1.5rem | The quick brown fox jumps over the lazy dog |
| \--font-size-3xl | 1.8125rem | The quick brown fox jumps over the lazy dog |
| \--font-size-4xl | 2.1875rem | The quick brown fox jumps over the lazy dog |
| \--font-size-5xl | 2.625rem | The quick brown fox jumps over the lazy dog |

### Font Weights

Copy link

Four semantic weights: normal (400, body/code), medium (500, labels/data), semibold (600, headings/titles), bold (700, strong emphasis). Type scale tokens reference these by var() so themes can remap numeric values.

| Token | Value | Example |
| --- | --- | --- |
| \--font-weight-normal | 400 | The quick brown fox jumps over the lazy dog |
| \--font-weight-medium | 500 | The quick brown fox jumps over the lazy dog |
| \--font-weight-semibold | 600 | The quick brown fox jumps over the lazy dog |
| \--font-weight-bold | 700 | The quick brown fox jumps over the lazy dog |

Line Height
-----------

Copy link

Line heights are computed from a tiered target ratio and snapped to a 4px vertical grid. Small text (<20px) targets 1.5, medium text (20–31px) targets 1.4, and large text (≥32px) targets 1.25. A minimum gap of fontSize + 4px is enforced. The result is a unitless ratio stored in each --text-\*-leading token.

The 4px grid matters: every line box aligns to 4px increments, which keeps baselines, spacing, and component heights predictable. The expandTypeScale utility computes these automatically when you provide a base and ratio, so you should never need to set line-height manually.

### Type Scale

Copy link

Semantic tokens that combine size, weight, and line-height into a single type style. Each token triplet (--text-\*-size, --text-\*-weight, --text-\*-leading) is consumed by Text and Heading. Use the component props rather than composing raw font tokens.

| Sample | Tokens |
| --- | --- |
| H1  | 1.5rem · Figtree600 · 1.3333 (2px) |
| H2  | 1.25rem · Figtree600 · 1.4 (2px) |
| H3  | 1.0625rem · Figtree600 · 1.4118 (2px) |
| H4  | 0.875rem · Figtree600 · 1.4286 (1px) |
| H5  | 0.75rem · Figtree600 · 1.6667 (1px) |
| H6  | 0.625rem · Figtree600 · 1.6 (1px) |
| Display 1 | 2.625rem · Figtree600 · 1.2381 (3px) |
| Display 2 | 2.1875rem · Figtree600 · 1.2571 (3px) |
| Display 3 | 1.8125rem · Figtree600 · 1.2414 (2px) |
| Large | 1.0625rem · Figtree600 · 1.4118 (2px) |
| Body | 0.875rem · Figtree400 · 1.4286 (1px) |
| Label | 0.875rem · Figtree500 · 1.4286 (1px) |
| Code | 0.875rem · "SF Mono"400 · 1.4286 (1px) |
| Supporting | 0.75rem · Figtree400 · 1.6667 (1px) |

Display Text
------------

Copy link

Display variants (display-1, display-2, display-3) continue the geometric progression above heading-1, at steps +6, +5, and +4. They use normal weight (400) instead of semibold, and tighter line-heights (~1.2), since large text reads better with less leading. Use display types for hero banners, marketing headlines, and data callouts, not for document headings.

Display text often needs heading semantics for accessibility. Use the type prop on Heading to apply display styling while preserving the correct HTML element: <Heading level={1} type="display-1"> gives you display-1 styling with an <h1> tag, so screen readers see the correct document outline.

Usage
-----

Copy link

Heading for document structure

tsx

`   import {Heading} from '@astryxdesign/core';  ​  // Heading levels map to semantic tokens: level 1 → --text-heading-1-*  <Heading level={1}>Page Title</Heading>  <Heading level={2}>Section</Heading>  <Heading level={3}>Subsection</Heading>  ​  // Display type for hero/marketing headings — level sets the HTML element  <Heading level={1} type="display-1">Hero Title</Heading>  <Heading level={2} type="display-2">$1.2M Revenue</Heading>  ​  // Override the accessibility level when visual ≠ document hierarchy  <Heading level={2} accessibilityLevel={3}>    Sidebar Section  </Heading>   `

Text for body, label, and display text

tsx

`   import {Text} from '@astryxdesign/core';  ​  <Text type="body">Body text at the base scale.</Text>  <Text type="large">Emphasized body text.</Text>  <Text type="label">Form label</Text>  <Text type="supporting">Helper text, timestamps, metadata.</Text>  <Text type="code">{'const x = 1;'}</Text>  ​  // Display without heading semantics (data callouts, decorative)  <Text type="display-2">$1.2M Revenue</Text>   `

Customizing the type scale via defineTheme

tsx

`   import {defineTheme} from '@astryxdesign/core';  ​  // Adjust the entire ramp holistically with base and ratio  const editorialTheme = defineTheme({    name: 'editorial',    typography: {      scale: { base: 16, ratio: 1.25 },          // airy / article feel      body: { family: 'Geist', fallbacks: '-apple-system, sans-serif' },      heading: { weight: 'bold' },      code: { family: 'Geist Mono', fallbacks: '"SF Mono", monospace' },    },  });  ​  const denseTheme = defineTheme({    name: 'dense',    typography: {      scale: { base: 12, ratio: 1.125 },          // compact / data-dense UI    },  });   `

Best Practices
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Do  | Use Heading for document headings and Text for everything else; they apply the full type scale automatically. |
| Do  | Adjust typography holistically: change base and ratio in defineTheme to shift the entire ramp (e.g. { base: 16, ratio: 1.25 } for editorial, { base: 12, ratio: 1.125 } for dense UI). |
| Do  | Use display types with as="h1" (or h2/h3) when display text is a page heading; this preserves accessibility while giving you display-level sizing. Or better, use <Heading level={1} type="display-1"> which handles both semantics and styling. |
| Do  | Let line-height snap to the 4px grid via the type scale; expandTypeScale computes leading automatically from base and ratio. |
| Do  | Use the supporting type for secondary information: timestamps, helper text, metadata, captions. |
| Do  | Use accessibilityLevel on Heading when the visual hierarchy doesn't match the document outline (e.g. sidebar or card headings). |
| Don't | Set font-size or line-height manually; use the semantic type scale tokens so the full ramp stays consistent and 4px-grid-aligned. |
| Don't | Skip heading levels (e.g. h1 to h3); screen readers rely on an unbroken hierarchy. Use accessibilityLevel to decouple visual from semantic level. |
| Don't | Use display types for body content or in-page sections; they're designed for hero/marketing/data-callout contexts only. |
| Don't | Override individual size tokens (--font-size-lg) to "tweak" a heading; adjust base/ratio instead so proportions remain coherent across the entire scale. |
| Don't | Use raw numeric font-weight values (400, 600); reference the semantic weight tokens so themes can remap them. |

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/typography)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# All Tokens · Astryx

[Skip to content](https://astryx.atmeta.com/docs/tokens#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

All Tokens
==========

Complete reference for spacing, color, radius, typography, shadow, motion, and size tokens.

### Color Tokens

Copy link

Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching.

| Token | Value |
| --- | --- |
| \--color-accent | #262626 / #ebebeb |
| \--color-accent-muted | #f1f1f1 / #262626 |
| \--color-on-accent | #ffffff / #171717 |
| \--color-neutral | #0000000F / #FFFFFF1A |
| \--color-background-surface | #ffffff / #262626 |
| \--color-background-body | #f1f1f1 / #1b1b1b |
| \--color-overlay | #00000080 / #000000CC |
| \--color-overlay-hover | #0000000D / #FFFFFF0D |
| \--color-overlay-pressed | #0000001A / #FFFFFF1A |
| \--color-background-muted | #f1f1f1 / #1b1b1b |
| \--color-text-primary | #171717 / #fafafa |
| \--color-text-secondary | #525252 / #a3a3a3 |
| \--color-text-disabled | #a3a3a3 / #525252 |
| \--color-text-accent | #262626 / #ebebeb |
| \--color-on-dark | #ffffff |
| \--color-on-light | #171717 |
| \--color-icon-accent | #262626 / #ebebeb |
| \--color-icon-primary | #171717 / #fafafa |
| \--color-icon-secondary | #737373 / #a3a3a3 |
| \--color-icon-disabled | #a3a3a3 / #525252 |
| \--color-background-card | #ffffff / #1b1b1b |
| \--color-background-popover | #ffffff / #1b1b1b |
| \--color-background-inverted | #0A1317 / #FFFFFF |
| \--color-background-error-inverted | #AA071E / #E3193B |
| \--color-success | #007004 / #9fe59b |
| \--color-success-muted | #c5e5c0 / #84c9803D |
| \--color-on-success | #ffffff / #171717 |
| \--color-error | #a50c25 / #ffc6c1 |
| \--color-error-muted | #facecb / #ff9e973D |
| \--color-on-error | #ffffff / #171717 |
| \--color-warning | #745b00 / #fdcf4f |
| \--color-warning-muted | #f8da9d / #deb4333D |
| \--color-on-warning | #171717 |
| \--color-border | #00000014 / #FFFFFF1A |
| \--color-border-emphasized | #d4d4d4 / #525252 |
| \--color-skeleton | #ebebeb / #525252 |
| \--color-track | #CCD3DB / #5A5E66 |
| \--color-shadow | #0000001A / #0000004D |
| \--color-tint-hover | black / white |
| \--color-background-blue | #c4ddfb / #9eb7ff3D |
| \--color-border-blue | #b1c9e7 / #6d9cfe |
| \--color-icon-blue | #00458c / #9eb7ff |
| \--color-text-blue | #00458c / #c7d3ff |
| \--color-background-cyan | #a3e0ef / #83c2d43D |
| \--color-border-cyan | #91d3e3 / #67a7b8 |
| \--color-icon-cyan | #00505f / #83c2d4 |
| \--color-text-cyan | #00505f / #9edef0 |
| \--color-background-gray | #e5e5e5 / var(--color-neutral) |
| \--color-border-gray | #d4d4d4 / #262626 |
| \--color-icon-gray | #525252 / #a3a3a3 |
| \--color-text-gray | #262626 / #e5e5e5 |
| \--color-background-green | #c5e5c0 / #84c9803D |
| \--color-border-green | #b2d1ac / #69ad67 |
| \--color-icon-green | #0c5700 / #84c980 |
| \--color-text-green | #0c5700 / #9fe59b |
| \--color-background-orange | #fad0b5 / #ffa2583D |
| \--color-border-orange | #e6bda2 / #e2883e |
| \--color-icon-orange | #6e3500 / #ffa258 |
| \--color-text-orange | #6e3500 / #ffc9a2 |
| \--color-background-pink | #fccadc / #ff99c33D |
| \--color-border-pink | #e7b7c8 / #f273aa |
| \--color-icon-pink | #83004b / #ff99c3 |
| \--color-text-pink | #83004b / #ffc3da |
| \--color-background-purple | #eccef3 / #f297ff3D |
| \--color-border-purple | #d8bbdf / #dd74f0 |
| \--color-icon-purple | #700084 / #f297ff |
| \--color-text-purple | #700084 / #fac1ff |
| \--color-background-red | #facecb / #ff9e973D |
| \--color-border-red | #e6bab8 / #ff6f6c |
| \--color-icon-red | #89001a / #ff9e97 |
| \--color-text-red | #89001a / #ffc6c1 |
| \--color-background-teal | #a5e3d6 / #7ec6b83D |
| \--color-border-teal | #94d6c8 / #63ab9d |
| \--color-icon-teal | #005348 / #7ec6b8 |
| \--color-text-teal | #005348 / #99e2d3 |
| \--color-background-yellow | #f8da9d / #deb4333D |
| \--color-border-yellow | #e4c279 / #c0990e |
| \--color-icon-yellow | #584400 / #deb433 |
| \--color-text-yellow | #584400 / #fdcf4f |
| \--color-syntax-keyword | #700084 / #efa8ff |
| \--color-syntax-string | #005600 / #a6d2a2 |
| \--color-syntax-comment | #737373 / #a3a3a3 |
| \--color-syntax-number | #6e3500 / #ffb37f |
| \--color-syntax-function | #00458c / #a0caff |
| \--color-syntax-type | #700084 / #efa8ff |
| \--color-syntax-variable | #171717 / #e5e5e5 |
| \--color-syntax-operator | #737373 / #a3a3a3 |
| \--color-syntax-constant | #6e3500 / #ffb37f |
| \--color-syntax-tag | #89001a / #ffaeaa |
| \--color-syntax-attribute | #584400 / #eec12f |
| \--color-syntax-property | #005348 / #83dac9 |
| \--color-syntax-punctuation | #a3a3a3 / #525252 |
| \--color-syntax-background | #fafafa / #0a0a0a |
| \--color-data-categorical-blue | #0171E3 |
| \--color-data-categorical-orange | #EB6E00 |
| \--color-data-categorical-purple | #6B1EFD |
| \--color-data-categorical-green | #0B991F |
| \--color-data-categorical-pink | #F351C0 |
| \--color-data-categorical-cyan | #0171A4 |
| \--color-data-categorical-red | #F5394F |
| \--color-data-categorical-teal | #08A3A3 |
| \--color-data-categorical-brown | #965E03 |
| \--color-data-categorical-indigo | #6F8AFF |
| \--color-data-neutral | #8494A3 / #8C939B |
| \--color-data-blue-5 | #02165E |
| \--color-data-blue-4 | #004CBC |
| \--color-data-blue-3 | #2694FE |
| \--color-data-blue-2 | #78BEFF |
| \--color-data-blue-1 | #DBECFF |
| \--color-data-shamrock-5 | #0B603D |
| \--color-data-shamrock-4 | #138546 |
| \--color-data-shamrock-3 | #24BB5E |
| \--color-data-shamrock-2 | #8EF7AA |
| \--color-data-shamrock-1 | #D6FEE4 |
| \--color-data-orange-5 | #A13F04 |
| \--color-data-orange-4 | #D66100 |
| \--color-data-orange-3 | #FD9537 |
| \--color-data-orange-2 | #FDB876 |
| \--color-data-orange-1 | #FFE6CF |
| \--color-data-pink-5 | #8E1073 |
| \--color-data-pink-4 | #D123A1 |
| \--color-data-pink-3 | #F989D3 |
| \--color-data-pink-2 | #FEADE3 |
| \--color-data-pink-1 | #FCE3F4 |
| \--color-data-purple-5 | #3E0697 |
| \--color-data-purple-4 | #6B1EFD |
| \--color-data-purple-3 | #9081FF |
| \--color-data-purple-2 | #B3B0FE |
| \--color-data-purple-1 | #E8E8FB |
| \--color-data-red-5 | #9D0519 |
| \--color-data-red-4 | #D31130 |
| \--color-data-red-3 | #FB7D87 |
| \--color-data-red-2 | #FFB2B8 |
| \--color-data-red-1 | #FEE4E6 |
| \--color-data-teal-5 | #08767D |
| \--color-data-teal-4 | #0C9293 |
| \--color-data-teal-3 | #0DB7AF |
| \--color-data-teal-2 | #6CE6D8 |
| \--color-data-teal-1 | #D7FCF8 |
| \--color-data-yellow-5 | #8A5001 |
| \--color-data-yellow-4 | #D69804 |
| \--color-data-yellow-3 | #FBCE03 |
| \--color-data-yellow-2 | #FCEC85 |
| \--color-data-yellow-1 | #FDF6BA |
| \--color-data-gray-5 | #25363F / #333338 |
| \--color-data-gray-4 | #5D6C7B / #666A72 |
| \--color-data-gray-3 | #AFB9C4 / #B2B8BE |
| \--color-data-gray-2 | #CCD3DB / #D0D3D6 |
| \--color-data-gray-1 | #F1F4F7 / #F2F4F6 |
| \--color-brand |     |

### Spacing Tokens

Copy link

Spacing scale used for padding, gap, and margin. Component gap props map spacing steps to these tokens.

| Token | Value |
| --- | --- |
| \--spacing-0 | 0px |
| \--spacing-0-5 | 2px |
| \--spacing-1 | 4px |
| \--spacing-1-5 | 6px |
| \--spacing-2 | 8px |
| \--spacing-3 | 12px |
| \--spacing-4 | 16px |
| \--spacing-5 | 20px |
| \--spacing-6 | 24px |
| \--spacing-7 | 28px |
| \--spacing-8 | 32px |
| \--spacing-9 | 36px |
| \--spacing-10 | 40px |
| \--spacing-11 | 44px |
| \--spacing-12 | 48px |

### Size Tokens

Copy link

Control heights for consistent sizing across buttons, inputs, and selectors.

| Token | Value |
| --- | --- |
| \--size-element-sm | 28px |
| \--size-element-md | 32px |
| \--size-element-lg | 36px |

### Border Tokens

Copy link

Border width for card and input borders.

| Token | Value | Example |
| --- | --- | --- |
| \--border-width | 1px |     |

### Radius Tokens

Copy link

Numeric scale based on a 4dp base unit. Tokens scale with the theme's radius multiplier; --radius-none and --radius-full are fixed.

| Token | Value | Example |
| --- | --- | --- |
| \--radius-none | 0px |     |
| \--radius-inner | 8px |     |
| \--radius-element | 12px |     |
| \--radius-container | 16px |     |
| \--radius-page | 32px |     |
| \--radius-chat | 28px |     |
| \--radius-full | 9999px |     |

### Shadow Tokens

Copy link

Elevation shadows (low to med to high) and inset shadows for input state rings.

| Token | Preview |
| --- | --- |
| \--shadow-low |     |
| \--shadow-med |     |
| \--shadow-high |     |
| \--shadow-inset-hover |     |
| \--shadow-inset-selected |     |
| \--shadow-inset-success |     |
| \--shadow-inset-warning |     |
| \--shadow-inset-error |     |

### Duration Tokens

Copy link

Motion duration primitives. Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous). Min/max variants derive from base × ratio.

| Token | Value |
| --- | --- |
| \--duration-fast-min | 130ms |
| \--duration-fast | 175ms |
| \--duration-fast-max | 230ms |
| \--duration-medium-min | 310ms |
| \--duration-medium | 410ms |
| \--duration-medium-max | 550ms |
| \--duration-slow-min | 730ms |
| \--duration-slow | 975ms |
| \--duration-slow-max | 1300ms |

### Easing Tokens

Copy link

Easing curves for animations and transitions.

| Token | Value |
| --- | --- |
| \--ease-standard | cubic-bezier(0.24, 1, 0.4, 1) |

### Font Family Tokens

Copy link

Font family stacks for body, code, and heading text.

| Token | Value | Example |
| --- | --- | --- |
| \--font-family-body | Figtree | The quick brown fox jumps over the lazy dog |
| \--font-family-code | "SF Mono" | The quick brown fox jumps over the lazy dog |
| \--font-family-heading | Figtree | The quick brown fox jumps over the lazy dog |

### Font Size Tokens

Copy link

Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base).

| Token | Value | Example |
| --- | --- | --- |
| \--font-size-4xs | 0.375rem | The quick brown fox jumps over the lazy dog |
| \--font-size-3xs | 0.4375rem | The quick brown fox jumps over the lazy dog |
| \--font-size-2xs | 0.5rem | The quick brown fox jumps over the lazy dog |
| \--font-size-xs | 0.625rem | The quick brown fox jumps over the lazy dog |
| \--font-size-sm | 0.75rem | The quick brown fox jumps over the lazy dog |
| \--font-size-base | 0.875rem | The quick brown fox jumps over the lazy dog |
| \--font-size-lg | 1.0625rem | The quick brown fox jumps over the lazy dog |
| \--font-size-xl | 1.25rem | The quick brown fox jumps over the lazy dog |
| \--font-size-2xl | 1.5rem | The quick brown fox jumps over the lazy dog |
| \--font-size-3xl | 1.8125rem | The quick brown fox jumps over the lazy dog |
| \--font-size-4xl | 2.1875rem | The quick brown fox jumps over the lazy dog |
| \--font-size-5xl | 2.625rem | The quick brown fox jumps over the lazy dog |

### Font Weight Tokens

Copy link

Font weight values for body, emphasis, and headings.

| Token | Value | Example |
| --- | --- | --- |
| \--font-weight-normal | 400 | The quick brown fox jumps over the lazy dog |
| \--font-weight-medium | 500 | The quick brown fox jumps over the lazy dog |
| \--font-weight-semibold | 600 | The quick brown fox jumps over the lazy dog |
| \--font-weight-bold | 700 | The quick brown fox jumps over the lazy dog |

### Type Scale Tokens

Copy link

Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme.

| Sample | Tokens |
| --- | --- |
| H1  | 1.5rem · Figtree600 · 1.3333 (2px) |
| H2  | 1.25rem · Figtree600 · 1.4 (2px) |
| H3  | 1.0625rem · Figtree600 · 1.4118 (2px) |
| H4  | 0.875rem · Figtree600 · 1.4286 (1px) |
| H5  | 0.75rem · Figtree600 · 1.6667 (1px) |
| H6  | 0.625rem · Figtree600 · 1.6 (1px) |
| Display 1 | 2.625rem · Figtree600 · 1.2381 (3px) |
| Display 2 | 2.1875rem · Figtree600 · 1.2571 (3px) |
| Display 3 | 1.8125rem · Figtree600 · 1.2414 (2px) |
| Large | 1.0625rem · Figtree600 · 1.4118 (2px) |
| Body | 0.875rem · Figtree400 · 1.4286 (1px) |
| Label | 0.875rem · Figtree500 · 1.4286 (1px) |
| Code | 0.875rem · "SF Mono"400 · 1.4286 (1px) |
| Supporting | 0.75rem · Figtree400 · 1.6667 (1px) |

Usage in StyleX
---------------

Copy link

Using token imports

tsx

`   import * as stylex from '@stylexjs/stylex';  import {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core';  ​  const styles = stylex.create({    card: {      padding: spacingVars['--spacing-4'],      backgroundColor: colorVars['--color-background-surface'],      borderRadius: radiusVars['--radius-container'],    },    button: {      height: sizeVars['--size-element-md'],    },  });   `

See [`astryx docs styling`](https://astryx.atmeta.com/docs/styling)
 for how to apply tokens via xstyle, className, and compound component patterns. See [`astryx docs theme`](https://astryx.atmeta.com/docs/theme)
 for overriding tokens with defineTheme.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/tokens)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Styling Components · Astryx

[Skip to content](https://astryx.atmeta.com/docs/styling#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Styling Components
==================

How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, theming hooks, and styling-library interop.

Overview
--------

Copy link

There are several ways to style things. Here is when to use each:

| Approach | Use for | Example |
| --- | --- | --- |
| StyleX | Component-specific overrides, reusable styles, pseudo-classes, and typed tokens | const styles = stylex.create(...); <Button xstyle={styles.save} /> |
| Tailwind utilities | Layout, wrappers, and utility styling | className="flex gap-3 p-4" |
| className | Integrating with external CSS or Tailwind on components | className="my-card shadow-lg" |
| Styling-library token aliases | Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system | colors.surface = 'var(--color-background-surface)' |

All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run [`astryx docs styling-libraries`](https://astryx.atmeta.com/docs/styling-libraries)
; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.

xstyle Prop
-----------

Copy link

Every component accepts an xstyle prop for style customization. It accepts StyleX styles created via stylex.create(), not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.

Simple overrides

tsx

`   import * as stylex from '@stylexjs/stylex';  ​  const overrides = stylex.create({    card: { maxWidth: 400, marginBlock: 16 },    saveButton: { alignSelf: 'flex-end' },  });  ​  <Card xstyle={overrides.card} />  <Button label="Save" xstyle={overrides.saveButton} />   `

Pseudo-classes and conditional styles

tsx

`   import * as stylex from '@stylexjs/stylex';  ​  const overrides = stylex.create({    card: {      boxShadow: {        default: 'none',        ':hover': { '@media (hover: hover)': '0 4px 12px rgba(0,0,0,0.1)' },      },    },  });  ​  <Card xstyle={overrides.card}>...</Card>   `

*   All xstyle values must come from stylex.create()
*   Pseudo-classes (:hover, :focus-visible) are supported inside stylex.create
*   All :hover styles MUST use @media (hover: hover) guard
*   For non-StyleX styling (Tailwind, external CSS), use className instead

Tailwind Integration
--------------------

Copy link

The package ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.

globals.css: import the bridge

css

`   @layer reset, theme, base, astryx-base, astryx-theme, components, utilities;  ​  @import "tailwindcss/theme.css" layer(theme);  @import "tailwindcss/preflight.css" layer(base);  @import "@astryxdesign/core/reset.css";  @import "@astryxdesign/core/astryx.css";  @import "@astryxdesign/theme-neutral/theme.css";  @import "@astryxdesign/core/tailwind-theme.css";  @import "tailwindcss/utilities.css" layer(utilities);   `

Tailwind utilities alongside components

tsx

`   <div className="text-primary bg-surface rounded-container p-4 flex gap-3">    <Button label="Save" variant="primary" />    <Button label="Cancel" variant="secondary" />  </div>   `

The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run [`astryx docs styling-libraries`](https://astryx.atmeta.com/docs/styling-libraries)
.

className and style Props
-------------------------

Copy link

Every component also accepts standard className and style props. className is appended after the component's own classes. style is merged after StyleX inline styles, so consumer values win on conflict.

className with Tailwind utilities

tsx

`   <Card className="shadow-lg hover:shadow-xl transition-shadow">    ...  </Card>  <Button label="Save" className="my-app-save-btn" />   `

For layout and wrapper styling, Tailwind utilities on className work well. For component-specific overrides (padding, colors, borders), prefer xstyle; it integrates with StyleX deduplication and the component's internal style pipeline.

Rest Props (Prop Drilling)
--------------------------

Copy link

Components extend HTML attributes and spread rest props onto their root DOM element. This means data-\* attributes, aria-\* attributes, event handlers, and other HTML props pass through automatically.

Data attributes, event handlers, and ARIA

tsx

`   <Card    data-testid="user-card"    data-user-id={user.id}    onMouseEnter={handleHover}    aria-label="User profile card"  >    ...  </Card>   `

Ref forwarding

tsx

`   const cardRef = useRef<HTMLDivElement>(null);  <Card ref={cardRef}>...</Card>   `

A few HTML attributes are intentionally omitted from the base type (contentEditable, dangerouslySetInnerHTML). children is not in the base type either; components that accept children declare it explicitly, so slot-based components don't silently drop JSX children.

Compound Components
-------------------

Copy link

Complex components are composed from smaller components. Each sub-component accepts its own xstyle, className, and rest props. You style the parts individually; there's no single "drill into sub-part" prop.

Dialog with individually styled parts

tsx

`   import * as stylex from '@stylexjs/stylex';  ​  const overrides = stylex.create({    dialog: { maxWidth: 500 },    content: { gap: 'var(--spacing-4)' },  });  ​  <Dialog isOpen={isOpen} onClose={close} xstyle={overrides.dialog}>    <Layout      header={        <LayoutHeader hasDivider>          <Heading level={2}>Edit Profile</Heading>        </LayoutHeader>      }      content={        <LayoutContent xstyle={overrides.content}>          <TextInput label="Name" value={name} onChange={setName} />        </LayoutContent>      }      footer={        <LayoutFooter hasDivider>          <Button label="Cancel" variant="secondary" onClick={close} />          <Button label="Save" variant="primary" onClick={save} />        </LayoutFooter>      }    />  </Dialog>   `

The pattern: the parent component (Dialog) controls structure and behavior, child components (Layout, Header, Button) control their own appearance. Style each piece where it lives.

Preferred Selector Surface: Data Attributes
-------------------------------------------

Copy link

When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.

css

`   .my-app .astryx-button[data-variant="primary"] {    /* primary buttons in this app context */  }  ​  .my-app .astryx-button[data-variant="primary"][data-size="sm"] {    /* small primary buttons */  }  ​  .my-app .astryx-heading[data-level="2"] {    /* level 2 headings; numeric values stay literal in data attrs */  }   `

What components reflect

tsx

`   // <Button variant="primary" size="sm" />  // preferred selector attrs: data-variant="primary" data-size="sm"  ​  // <Card variant="elevated" />  // preferred selector attrs: data-variant="elevated"  ​  // <Heading level={2} />  // preferred selector attrs: data-level="2"   `

For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run [`astryx docs theme`](https://astryx.atmeta.com/docs/theme)
 for the full theming guide.

Deprecated: Bare Prop and State Classes
---------------------------------------

Copy link

Astryx still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.

css

`   /* Deprecated compatibility selector — avoid in new CSS */  .my-app .astryx-button.primary {    /* use .astryx-button[data-variant="primary"] instead */  }  ​  /* Deprecated compatibility selector — avoid in new CSS */  .my-app .astryx-heading.level-2 {    /* use .astryx-heading[data-level="2"] instead */  }   `

Design Tokens
-------------

Copy link

When writing custom styles, use design tokens instead of hardcoded values. Tokens are CSS custom properties that adapt to the active theme and color mode. The system provides tokens for spacing, color, radius, shadow, typography, and size.

Using tokens in stylex.create

tsx

`   import * as stylex from '@stylexjs/stylex';  ​  const styles = stylex.create({    surface: {      padding: 'var(--spacing-4)',      borderRadius: 'var(--radius-container)',      backgroundColor: 'var(--color-background-surface)',    },  });  ​  <Card xstyle={styles.surface} />   `

Using typed token imports in stylex.create

tsx

`   import {colorVars, spacingVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';  ​  const styles = stylex.create({    highlight: {      backgroundColor: colorVars['--color-accent-muted'],      padding: spacingVars['--spacing-3'],      borderRadius: radiusVars['--radius-element'],    },  });   `

Both approaches work: var() strings or typed imports from tokens.stylex. The typed imports give autocomplete and catch typos at build time.

See [`astryx docs tokens`](https://astryx.atmeta.com/docs/tokens)
 for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See [`astryx docs theme`](https://astryx.atmeta.com/docs/theme)
 for how to override tokens via defineTheme.

StyleX Build Setup (required for swizzled components)
-----------------------------------------------------

Copy link

Astryx components ship pre-compiled, so consuming the published package needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX \*source\* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.

| Bundler | StyleX plugin |
| --- | --- |
| Webpack | @stylexjs/webpack-plugin |
| Vite / Rollup | @stylexjs/rollup-plugin (or a community Vite plugin) |
| Babel (any bundler) | @stylexjs/babel-plugin + @stylexjs/postcss-plugin |
| Next.js (App Router, SWC) | An SWC-based transform; see the Next.js note below |

Next.js (App Router) is the sharp edge. StyleX's canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, which in turn breaks SWC-dependent features like `next/font`. So the "obvious" Babel setup is actively incompatible with a standard Next 15 App Router app.

The working path on Next.js is an SWC-based StyleX transform (e.g. the community `@stylexswc/nextjs-plugin`) wired into `next.config`, which keeps SWC and `next/font` intact. See the example app `apps/example-nextjs-stylex` in the repo for a complete, working Next.js + StyleX + SWC configuration.

next.config.mjs: SWC-based StyleX transform (keeps next/font working)

js

`   import stylexPlugin from '@stylexswc/nextjs-plugin';  ​  export default stylexPlugin({    rsOptions: {      // Resolve @astryxdesign/core's StyleX so swizzled component source compiles.      aliases: {'@/*': ['./src/*']},      unstable_moduleResolution: {type: 'commonJS'},    },  })({    // your existing Next.js config  });   `

*   Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.
*   Do NOT add @stylexjs/babel-plugin to a Next.js App Router app; it disables SWC and breaks next/font.
*   Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.

What NOT to Do
--------------

Copy link

| Guidance | Practices |
| --- | --- |
| Don't | style={{}} on raw <div> wrappers. Use xstyle on the component directly. |
| Don't | Hardcoded colors (#fff, rgb(...)). Use var(--color-\*) tokens or Tailwind semantic classes (text-primary, bg-surface). |
| Don't | Hardcoded spacing (16px, 1rem). Use var(--spacing-\*) tokens or Tailwind spacing utilities (p-4, gap-3). |
| Don't | Wrapping a component in a <div> just to add margin. Use xstyle with stylex.create on the component. |
| Don't | Using !important. If styles aren't applying, check specificity; xstyle is merged last. |

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/styling)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---

# Working with AI · Astryx

[Skip to content](https://astryx.atmeta.com/docs/working-with-ai#astryx-app-shell-main)

Type to search

↑↓Navigate↵SelectEscClose

Working with AI
===============

How to set up AI coding tools to generate correct component code.

Overview
--------

Copy link

The design system is built to be AI-friendly: consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props.

The CLI includes a built-in agent docs system that generates context files for your AI tool of choice. One command sets up everything your AI needs to write correct component code.

Quick Start
-----------

Copy link

Tell your AI to install the CLI and set itself up:

Paste this into your AI

text

``   Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.   ``

That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.

By default this creates `AGENTS.md` (the tool-agnostic standard most agents read). To target a specific tool's file instead:

Manual options

bash

`   npx @astryxdesign/cli init --features agents --agent claude    # .claude/CLAUDE.md  npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules  npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)   `

What Gets Generated
-------------------

Copy link

The generated context teaches your AI a 3-step workflow before writing any UI code:

1.  `astryx template --list`: find a related page pattern to use as reference
2.  `astryx template <name> --skeleton`: study the layout structure
3.  `astryx component <Name>`: read props and examples for every component used

It also includes rules that prevent common mistakes (no raw divs, no style={{}}, use tokens not magic values) and a CLI quick reference. After setup, you shouldn't need to manually correct your AI on these conventions; the agent docs handle it at the system level.

Cursor Setup
------------

Copy link

Cursor project rules aren't always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.

Install as a Cursor user rule

bash

`   mkdir -p ~/.cursor/rules  npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc   `

Checking Your Setup
-------------------

Copy link

Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can't answer them, it'll know to install the agent docs first.

Paste this into your AI

text

``   Before writing any Astryx code, check your knowledge:  ​  1. What is the correct import path for Button?  2. How do you make an Dialog non-dismissible?  3. What prop does Selector use for its items?  ​  If you don't know all three, run `npx @astryxdesign/cli init --features agents` to generate agent docs, then read the generated file.   ``

The astryx Pattern
------------------

Copy link

AI agents frequently invoke the CLI with incorrect paths (e.g. node\_modules/@astryxdesign/cli/bin/docs.mjs instead of astryx.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.

package.json

json

`   "scripts": {    "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"  }   `

With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.

Reliable CLI invocation

bash

`   astryx component --list  astryx component Dialog --dense  astryx docs styling --dense  astryx docs tokens --dense   `

The --dense Flag
----------------

Copy link

Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.

Dense output for pasting into AI conversations

bash

`   astryx component Dialog --dense  astryx docs styling --dense  astryx docs tokens --dense   `

MCP Server
----------

Copy link

Astryx ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the Astryx design system directly, searching for components, reading full documentation, and pulling code examples on demand.

The MCP server exposes two tools: search(query) for discovering components, doc topics, and templates; and get(name) for retrieving full documentation with props, usage, and examples.

Add the server to your MCP config file. This works with any MCP-compatible tool: Claude Desktop (claude\_desktop\_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.

MCP config (same for all tools)

json

`   {    "mcpServers": {      "xds": {        "type": "url",        "url": "https://astryx.atmeta.com/mcp"      }    }  }   `

Once connected, your AI tool can search for components by natural language (e.g. "dropdown menu", "success message") and retrieve full documentation without any manual CLI invocation. The server uses the same keyword index from component docs, so search quality improves automatically as component documentation is updated.

[](https://astryx.atmeta.com/)

[Docs](https://astryx.atmeta.com/docs/getting-started)
[Components](https://astryx.atmeta.com/components)
[Templates](https://astryx.atmeta.com/templates)
[Themes](https://astryx.atmeta.com/themes)
[Playground](https://astryx.atmeta.com/playground)
[Blog](https://astryx.atmeta.com/blog)
[Community](https://astryx.atmeta.com/community)
[Changelog](https://astryx.atmeta.com/changelog)
[Canary docs](https://astryx-canary.vercel.app/docs/working-with-ai)

[](https://github.com/facebook/astryx)

GitHub

[](https://discord.com/invite/XnsUcFykEP)

Discord

[](https://www.facebook.com/astryxdesign)

Facebook

[](https://www.instagram.com/astryxdesign)

Instagram

[](https://www.threads.com/@astryxdesign)

Threads

[](https://x.com/Astryxdesign)

X

[](https://opensource.fb.com/)

[Terms of use](https://opensource.fb.com/legal/terms)
[Privacy policy](https://opensource.fb.com/legal/privacy)

©2026 Meta Platforms, Inc.

---