# Styling and Tailwind

- Page: https://jiguang132.com/resources/astryx/docs/styling
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

Astryx 0.7.1: Styling and Tailwind.


## Styling overview

How to set up CSS — exact imports for three paths: plain, Tailwind, and StyleX for your own code — plus the stylesheet each Astryx package ships.

### Pick a path

| Path | Good for | Build step? |
| --- | --- | --- |
| Plain CSS | Most apps. Style with className, xstyle, or any CSS library. | None. |
| Tailwind | Apps on Tailwind v4. A CSS bridge maps utility classes to design tokens. | None beyond Tailwind's own. |
| StyleX for your own code | Your own `stylex.create()` styles and swizzled (ejected) components. Astryx itself stays prebuilt. | Yes — a StyleX plugin for your own code. |

All three load the same prebuilt Astryx stylesheets, resolve to the same design tokens, and support theming and dark mode. None of them compiles Astryx package source. You can mix them in one app.

### Plain CSS

```bash
npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral
```

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

Done. Components work out of the box — style them with `className`, `xstyle`, or `style`. Swap `theme-neutral` for any theme package (`astryx theme list` shows what's available).

### Tailwind

```bash
npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral
```

```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);
```

The `@layer` declaration is critical — without it, component styles outrank Tailwind utilities and `className` overrides stop working. The bridge (`tailwind-theme.css`) maps classes like `text-primary`, `bg-surface`, and `rounded-lg` to design tokens with no JS.

For Tailwind v3, see the layer workaround in `migration-setup`.

### StyleX for your own code

Only needed when you write your own StyleX (`stylex.create()`) or swizzle a component (`astryx swizzle <Component>`), which copies its StyleX source into your app. The plain path already supports `xstyle` overrides — this path is for your own StyleX code. Some built-in page templates also use StyleX for layout; if you scaffold one and see "Unexpected stylex.create call at runtime", add the compiler plugin for your bundler below.

```bash
npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral
```

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

Keep `astryx.css`: Astryx component styles always come from the prebuilt stylesheets. Point the StyleX compiler at your own source only, never at `node_modules/@astryxdesign`. Add the plugin for your bundler:

| Bundler | Plugin |
| --- | --- |
| Webpack | @stylexjs/webpack-plugin |
| Vite / Rollup | @stylexjs/rollup-plugin |
| Babel (any) | @stylexjs/babel-plugin + @stylexjs/postcss-plugin |
| Next.js (keep next/font) | @stylexswc/nextjs-plugin |

If a swizzled component renders with no styles and no error, a missing compiler is almost always why. See the StyleX Build Setup section of `tokens-and-setup` for bundler config examples.

### Other Astryx packages

Every Astryx package whose components carry styles ships its own prebuilt stylesheet. Import it after `astryx.css` for each package you use. All of them place their rules in the same `astryx-base` layer, so your theme overrides win over every package.

```css
@import "@astryxdesign/core/reset.css";
@import "@astryxdesign/core/astryx.css";
@import "@astryxdesign/richtext/richtext.css"; /* Rich Text */
@import "@astryxdesign/lab/lab.css"; /* Lab */
@import "@astryxdesign/charts/charts.css"; /* Charts */
@import "@astryxdesign/theme-neutral/theme.css";
```

| Package | Stylesheet |
| --- | --- |
| @astryxdesign/core | @astryxdesign/core/astryx.css |
| @astryxdesign/richtext | @astryxdesign/richtext/richtext.css |
| @astryxdesign/lab | @astryxdesign/lab/lab.css |
| @astryxdesign/charts | @astryxdesign/charts/charts.css |

### What each import does

| Import | Layer | Purpose |
| --- | --- | --- |
| reset.css | reset | Cross-browser reset (box-sizing, margins, color-scheme). Zero specificity via :where(). |
| astryx.css | astryx-base | Prebuilt component styles. Required on every path. |
| richtext.css, lab.css, charts.css | astryx-base | Prebuilt styles for each other Astryx package you use. Load after astryx.css. |
| theme.css | astryx-theme | Design tokens (colors, spacing, radius, typography) as CSS custom properties. Swap the package for a different theme. |
| tailwind-theme.css | — | Tailwind v4 bridge. Maps utility classes to design tokens. Pure CSS, no JS. Tailwind path only. |

### Further reading

- `styling` — xstyle, className, data-attribute selectors, design tokens in code.
- `styling-libraries` — Tailwind bridge details, Panda, Chakra, MUI, CSS Modules, and non-CSS token resolution.
- `use-a-theme` — applying themes, dark mode, nested themes. `author-a-theme` — defineTheme, overrides, production builds.
- `migration` — cascade layer audit, Tailwind v3 coexistence, and foundation smoke test.

Pinned install:

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt