[presentation] Add StyleX/Astryx as the default generated UI profile

[kang-heewon]

Problem

Croco currently has a strong backend and presentation-runtime story, but generated applications still need a more opinionated, framework-owned UI default. Tailwind/shadcn-style scaffolding is flexible, but it pushes a lot of local component ownership, styling convention, upgrade behavior, and generated-template consistency onto the application.

For Croco's product direction, the default UI path should be more aligned with the framework's existing principles:

• generated, not hand-wired;
• LLM-readable architecture;
• stable contracts and smoke evidence;
• clear package boundaries between core/runtime/presentation layers;
• production-oriented generated app profiles.

StyleX + Astryx is a promising fit because Astryx provides a React component system, theming, CLI/templates, and StyleX-based styling while allowing generated apps to consume a coherent UI system instead of accumulating ad hoc Tailwind/shadcn fragments.

Desired outcome

Croco supports StyleX/Astryx as the first-class generated UI profile for React/Vite/meta-vite applications, without coupling @croco/frontend-react core primitives to a specific design system.

The preferred architecture is:

• keep @croco/frontend-react provider-neutral;
• introduce a separate Astryx-backed package/profile such as @croco/ui-astryx or @croco/presentation-astryx;
• add --ui astryx to create-croco-app, eventually making it the default UI profile once evidence is strong enough;
• keep --ui none and any Tailwind/shadcn path as explicit alternatives;
• verify the generated output through package tests and generated-app smoke before claiming beta/production readiness.

Proposed scope

1. Package boundary

Add a dedicated Astryx integration surface instead of importing Astryx into @croco/frontend-react directly.

Candidate package names:

• @croco/ui-astryx
• @croco/presentation-astryx

This package may provide Astryx-backed versions of Croco UI primitives such as:

• Problem display components;
• auth/session/permission/entitlement states;
• dashboard shell primitives;
• SaaS onboarding/billing/metering starter screens;
• default layout, theme provider, and app chrome.

@croco/frontend-react should remain the provider-neutral bridge for SSR data, auth bridge state, and Problem UI primitives.

2. Generated app support

Extend create-croco-app with a UI selection option:

npx create-croco-app my-app --frontend vite --ui astryx
npx create-croco-app my-app --frontend meta-vite --ui astryx
npx create-croco-app my-app --frontend meta-vite --ui none

Generated Astryx apps should include:

• required Astryx packages;
• required StyleX/Vite configuration only when the app needs local StyleX compilation;
• Astryx pre-built CSS import path when that is sufficient;
• generated theme setup;
• layout shell;
• route-level examples using Croco auth/tenant/entitlement state;
• docs explaining when consumers need direct StyleX authoring versus plain Astryx component usage.

3. Runtime/profile integration

Update the presentation profile metadata so the UI system is an explicit generated profile dimension, not an implicit template detail.

Consider adding UI metadata to presentation/runtime profiles:

{
  "ui": {
    "name": "astryx",
    "styleEngine": "stylex",
    "requiresStylexCompile": true,
    "generatedSmokeCase": "meta-vite-astryx-web"
  }
}

This should stay compatible with existing runtime profiles such as browser Vite SPA, Node SSR, Lambda, and Cloudflare Workers.

4. Evidence gates

Add tests and generated smoke so this does not become another decorative template path.

Minimum evidence:

• package tests for the Astryx integration package;
• generated app snapshot tests for package manifests and config files;
• generated app smoke for vite + astryx;
• generated app smoke for meta-vite + astryx;
• SSR/hydration smoke proving the layout renders and hydration mismatch is visible rather than silently accepted;
• StyleX config validation for Vite/plugin ordering where direct StyleX compilation is used;
• docs/catalog checks that mark the integration as alpha/beta only when evidence exists.

5. Documentation

Document the decision clearly:

• Astryx is the default Croco UI profile candidate;
• StyleX is the preferred styling engine for first-class Croco UI profiles;
• Tailwind/shadcn remains an optional ecosystem path, not the core contract;
• @croco/frontend-react is intentionally design-system-neutral;
• generated UI profiles are promoted based on runtime smoke evidence, not package presence alone.

Acceptance criteria

• A dedicated Astryx integration package or presentation profile is added without making @croco/frontend-react depend on Astryx.
• create-croco-app supports --ui astryx for at least one React/Vite generated profile.
• The generated app has a working Astryx theme/layout shell and at least one Croco-aware screen/state example.
• StyleX/Vite configuration is generated only where required and is validated by tests.
• Generated package manifests do not leak unnecessary UI dependencies into non-UI profiles.
• Generated smoke covers install, typecheck, build, and a minimal runtime render path.
• SSR/hydration behavior is tested for the meta-vite Astryx profile if meta-vite is in scope.
• Package catalog and presentation-runtime docs describe the maturity level and evidence commands.
• Tailwind/shadcn, if retained, is represented as an explicit alternative rather than an implicit default.

Non-goals

• Do not replace all existing UI/template paths in the first PR.
• Do not move Astryx into Croco core packages.
• Do not claim production-ready status until generated runtime evidence exists.
• Do not create a large bespoke design system that duplicates Astryx internals.

References

• Astryx: https://github.com/facebook/astryx
• StyleX Vite docs: https://stylexjs.com/docs/learn/installation/vite/vite-react
• StyleX Vite RSC docs: https://stylexjs.com/docs/learn/installation/vite/vite-rsc