feat(examples): add Next.js 16 + Turbopack example (fixes silent unstyled-CSS trap)

[josephfarina]

Problem

On Next.js 16 with Turbopack (the default bundler), the documented CSS setup
silently produces unstyled components. Importing the component stylesheet
via a CSS @import:

/* globals.css */
@import '@astryxdesign/core/astryx.css';

compiles the stylesheet into a chunk in .next/static/chunks, but Turbopack
never links that chunk onto the route — no <link> is emitted, so none of
the component atomic rules reach the browser. There is no build error and no
console warning; components just render unstyled.

Every existing Next.js example in this repo (example-nextjs,
example-nextjs-tailwind, example-nextjs-stylex, example-nextjs-source) is
webpack-based (next dev / next build), so this path was never covered.

Fix

Add a validated Next.js 16 + Turbopack example app that imports the Astryx
stylesheets as JS side-effects in the root layout — the path Turbopack
reliably links:

// src/app/layout.tsx
import '@astryxdesign/core/reset.css';
import '@astryxdesign/core/astryx.css';
import '@astryxdesign/theme-neutral/theme.css';
import './globals.css';

Turbopack builds its CSS graph from the JS module graph, so CSS imported by a
module is bundled and linked; a bare @import of a package CSS subpath from a
CSS file is not. This is a bundler behavior, not an Astryx bug — but it means
the supported adoption path on Turbopack is the module-import form.

The example mirrors example-nextjs (same showcase page, same Theme/Link
provider) and differs only in:

• next on 16.x with --turbopack for both dev and build
• CSS imported from layout.tsx instead of @import in globals.css
• a README documenting the rule and the silent-failure it avoids

Verification

• Built with next build --turbopack (Next.js 16.2.11): compiles successfully;
  the component stylesheet is emitted as a chunk containing the full atomic rule
  set (~1,500 rules).
• On the equivalent server-rendered setup, the emitted HTML contains a
  <link rel="stylesheet"> for that chunk and components render styled — the
  @import-from-CSS form emits the same chunk with no <link>.

Follow-ups (not in this PR)

• An astryx doctor check that flags when astryx.css is only reachable via a
  CSS @import on a Turbopack project.
• A short "Adopting Astryx into Next.js 16 / Turbopack" doc pointing at this
  example.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 23, 2026 8:50pm

[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.7KB	0B

Accessibility Audit

Status: No accessibility violations detected.

---

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