dogfooding fixes: adopting Astryx into an existing Next + Tailwind app (guide)

[josephfarina]

What this adds

An "Adopting Astryx in an existing Next.js + Tailwind app" guide — astryx docs adopting-existing-app — that collects the integration-boundary traps from the #3374 experience report so the next person doesn't rediscover them. Fixes #3374.

This is the umbrella issue's remaining work. Two of its items were broken out and are addressed by sibling PRs (linked below); this PR covers the rest and ties them together in one guide.

The guide covers

Trap 1 — Tailwind preflight silently defeats theme overrides (highest impact). Astryx emits component theme overrides in the astryx-theme cascade layer; Tailwind's preflight (@tailwind base) is emitted unlayered, and unlayered rules beat any @layer rule regardless of specificity — so every theme override loses to preflight, with zero errors. The guide gives the fix for both Tailwind versions:

• v4: declare the full @layer order up front and import Tailwind's theme/preflight/utilities into named layers (matches the working apps/example-nextjs-tailwind).
• v3: wrap @tailwind base in a named layer (@layer tw-preflight { @tailwind base; }).

Trap 2 — moduleResolution must be bundler/node16+. Astryx's subpath exports (@astryxdesign/core/Button, /theme, …) don't resolve under the common "moduleResolution": "node". The guide documents the switch and warns it's a project-wide change that can surface latent issues in unrelated deps.

Trap 3 — swizzled components need a StyleX compiler. Points at the new "StyleX Build Setup" section in astryx docs styling and the apps/example-nextjs-stylex reference (see #3373).

Trap 4 — custom variants are type-safe via defineTheme + theme build. Shows the variant: override pattern and notes the augmentation now loads automatically (see #3371).

Discoverability — a short "start with the CLI" section pointing at astryx component <Name>, docs tokens, docs styling, docs theme, since most "how do I theme X?" time is spent not knowing the answer already exists in the CLI.

Verification

• astryx docs lists the new adopting-existing-app topic; astryx docs adopting-existing-app renders all seven sections.
• The Tailwind v4 layer/import block in the guide matches the working apps/example-nextjs-tailwind/src/app/globals.css exactly.
• Getting Started now links to the guide from the Install section.
• Docs test suite passes (7 tests, including hyphenated-topic discovery/loading); ESLint clean.

Related PRs (sibling sub-issues of #3374)

• theme build custom-variant type augmentations (astryx theme build generates custom-variant augmentations against non-existent interface names (XDSButtonVariantMap ≠ ButtonVariantMap) #3371)
• Document StyleX build requirement for swizzled components (Swizzled components emit StyleX source, but no docs explain the required StyleX build/compiler setup (breaks silently; Next.js/SWC has no guidance) #3373)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 2, 2026 11:11pm

[cixzhang]

I see this adds a fairly specific guide for adopting Astryx in one specific condition. There's a few parts here just from cursory read through which I think could also be broken into specific jobs, for example:

Tailwind interop for v4 is documented in our docs but we are missing it for v3. There's a dedicated doc for styling library interop which sounds like it should keep information like this.

We may be missing per framework specific setup instructions. For NextJS there's additional setup like connecting the LinkProvider or setting up the build with stylex that could be useful for the LLM to know so I wonder if we should have a "Setting Up By Framework" article more generically. Were you able to make use of the example apps in resolving some of these?

Theming discovery is interesting but I wonder if that is best discovered via this new article. It seems more broadly useful.

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.6KB	0B

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}