Astryx Design System

Astryx Design System

Astryx (@astryxdesign/core) is this organization's UI toolkit — components, layout, and styling (via StyleX) all come from it. Never raw HTML styling, never another component library, never an invented component prop.

You are here because the component you are building pinned this skill, so the whole of it is yours — theming included. The organization's colors are settled in Brand colors below; nobody is interviewed about them, at design time or any other time.

react-webapp owns the app: layout, config, verify sequence, Dockerfile, nginx. This skill owns what goes inside src/ — the UI. Where the two appear to disagree, react-webapp wins; the conflicts worth naming are listed under Platform constraints below.

Correctness through the CLI, not memory

Astryx ships @astryxdesign/cli because component APIs move faster than any model's training data. The CLI reads the installed version, so it is always right; a guessed prop is never right by comparison. The discipline: before writing JSX for a component you have not confirmed this session, run the CLI, then write the JSX — never the reverse.

Always invoke it as npx --no astryx …. --no restricts resolution to the @astryxdesign/cli in this app's node_modules — the version package-lock.json pins. Without it, an npx astryx in an app whose install has not run fetches and executes the unrelated astryx package that exists on the public registry. Do not drop the flag to shorten a command: if the CLI is missing, the right outcome is the loud could not determine executable to run, not a stranger's postinstall script running in the build pod.

Violating the letter of this rule is violating the spirit of it. "It's just a placeholder page," "the app doesn't have Astryx wired up yet," and "this screen is throwaway" are reasons to wire Astryx up faster, not reasons to skip it — a page built in raw <div>s is what deploys, because there is no human code-review gate between your PR and the dev environment.

Setup

react-webapp scaffolds the app. Add Astryx to it:

npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral @astryxdesign/build
npm install -D @astryxdesign/cli

@astryxdesign/core declares React 19+ as a hard peer dependency — set react / react-dom to ^19 in package.json, not an older major.

Wire the build (order matters — astryxStylex() before react(), and no base, per react-webapp):

// vite.config.ts
import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import {astryxStylex} from '@astryxdesign/build/vite';

export default defineConfig({plugins: [...astryxStylex(), react()]});

// main.tsx — reset + theme CSS load before anything renders
import '@astryxdesign/core/reset.css';
import '@astryxdesign/theme-neutral/theme.css';
import {Theme} from '@astryxdesign/core/theme';
import {neutralTheme} from '@astryxdesign/theme-neutral/built';
// wrap <App/> in <Theme theme={neutralTheme}> — swap the theme package to change
// the look, never hand-roll colors instead

That stock package is the default and the fallback. It is what a project gets when this organization has not set brand colors — see the next section.

Brand colors

A web app is themed at its FIRST build, and retrofitting a theme means revisiting every screen — so the colors cannot be a per-build decision. They are an organization decision, settled once in the section below and compiled at build time, exactly like the language a service is written in.

Never ask anyone for them. Not at design time, not at coding time, not once per project. The answer is either set below or it is the stock theme, and both are complete answers — a question about theming is a defect, not diligence.

The organization's colors

• Accent (buttons, links, focus): not set — use the stock theme
• Neutral (backgrounds, surfaces): not set — use the stock theme

To brand every web app this organization builds, an org edits those two lines to hex values (Settings → Skills), e.g.:

- Accent (buttons, links, focus): #f5c518
- Neutral (backgrounds, surfaces): #0a0a0a

HEX only, never color words: "black and yellow" does not say WHICH yellow, and this file is the whole of what a build sees. The edit reaches every subsequent build in the org with no conversation involved.

A per-project override still wins, per value, not per section: a hex under the ## Brand colors heading in the project's specs/requirements/prd.md overrides the same line here, and a line that heading omits still comes from this section. That heading is there for a project whose colors someone stated outright — it is not something to solicit, and a half-filled one is not a reason to drop the organization's other color.

At build time — compile the theme

Resolve each of the two colors before you wire the theme, independently: the project's ## Brand colors line in specs/requirements/prd.md if it has one, otherwise the line in The organization's colors above. A color neither one sets is not chosen — take it from the stock theme's own token and never invent one, whether that leaves you with two brand colors, one, or none. One brand color plus one stock color is a valid outcome; a guessed hex is not.

With colors, a brand theme is a compiled theme of your own — not hand-written colors sprinkled over a stock one. Editing component styles to paint them brand colors violates "colors are tokens" and leaves every unstyled surface off-brand. Scaffold a stock theme as editable source, retune its color tokens, compile it:

# 1. scaffold the closest stock theme as YOUR source (once)
npx --no astryx theme add neutral src/theme
# 2. copy it to src/theme/brandTheme.ts, rename the exported symbol +
#    `name:` + its defineSyntaxTheme `name:`, then edit the color tokens
# 3. compile — emits brand.css + brand.js + brand.d.ts beside the source
npx --no astryx theme build src/theme/brandTheme.ts -o src/theme/brand.css

Every color token is a [light, dark] pair. Retune this set and leave the rest of the scaffold alone — they are what carry a brand:

Then wire the compiled output exactly like a package theme — the import is the build's -o CSS plus the sibling JS, both from src/theme/, never the .ts:

// main.tsx
import '@astryxdesign/core/reset.css';
import './theme/brand.css';
import {Theme} from '@astryxdesign/core/theme';
import {brandTheme} from './theme/brand';
// wrap <App/> in <Theme theme={brandTheme}>

Commit the generated brand.css / brand.js / brand.d.ts alongside the source: the Docker build runs npm run build, not the theme compiler, so an uncommitted build output ships an unthemed app. Re-run theme build after every edit to brandTheme.ts — editing the source alone changes nothing.

Two colors is the common case, and it does not mean two tokens. Map the neutral across the background ramp and the accent across the accent trio; a pure #FFFF00-class hue almost always needs darkening for its light-mode slot and dark text for --color-on-accent. Contrast is not negotiable to match a brand: keep the hue, move the lightness.

Verify

This skill's step in react-webapp's verify sequence — after npm install, before npx tsc --noEmit:

npx --no astryx doctor

A non-zero exit fails verification like any other step in that sequence. It is there because a wiring fault (a missing astryxStylex() plugin, an unimported theme, a React peer-dependency mismatch) type-checks and builds perfectly clean, then renders an unstyled page in the cluster — cheap to fix here, expensive to debug after the Docker build.

Platform constraints that override this system's defaults

Four places where Astryx's own defaults do not fit this platform. Each is a runtime, build, or guidance failure, not a style preference:

1. Never install Astryx's agent docs. astryx init itself is fine — it initializes the design system in an existing project, and it is not required, because the Setup section above already states the wiring. What must not land is the agents feature: astryx init --features agents writes AGENTS.md into the repo root, and --all includes it. Guidance reaches you as skills, so a committed agent file is a second authority that nothing updates — it is stale the moment this skill changes. --features is an allow-list, so name only what you want (--features theme) and never --all; if agent docs already landed, astryx init --remove-agents deletes them.
2. Never set base in vite.config.ts, whatever an Astryx snippet shows. Each web app is served at its own gateway host root; a base 404s every asset and the page renders blank (react-webapp, Served at host root).
3. The CSS imports go in main.tsx, never in index.html. index.html's only <script> rules are react-webapp's: the synchronous env-config.js tag first, the module bundle second. Adding a stylesheet or script tag around them risks window._env_ being unset when the first module evaluates.
4. Theme tokens are not runtime config. Colors and spacing come from the theme package at build time. window._env_ carries only what the browser needs — OIDC config and flags — so do not plumb a theme value through it.

Astryx replaces hand-written UI, not the platform's data layer: openapi-fetch and the committed src/generated/ client stay exactly as react-webapp specifies. "Install no other library" below is about UI and styling.

Critical rules

1. Import everything from @astryxdesign/core/<Category> (per-category subpath entry points, e.g. @astryxdesign/core/Button, @astryxdesign/core/Layout) — never from Tailwind, MUI, Chakra, Ant Design, Bootstrap, or a hand-rolled component.
2. Run npx --no astryx component <Name> --dense before using ANY component, even one already used earlier in this session — confirm the prop exists before writing it, don't guess.
3. Search before building. Run npx --no astryx search "<thing>" when unsure what exists; Astryx ships more components than you would assume (tag inputs, command palettes, tree lists, chat UI) — check before reaching for a wrapper <div> or a new dependency.
4. Layout is VStack/HStack/Grid/Stack from @astryxdesign/core/Layout — never a raw <div>/<span> for spacing or arrangement.
5. Style overrides are stylex.create() + the component's xstyle prop — never style={{...}}, and never className/style alongside {...stylex.props()} (use mergeProps() if you must combine).
6. Colors and spacing are tokens, never literals. Run npx --no astryx docs tokens --dense; use the CSS-var color tokens and spaceN gap values it documents, not hex/rgb or raw px.
7. Page-level structure follows a template, not intuition. Run npx --no astryx template --list and npx --no astryx template <name> --skeleton to find and study a layout skeleton before hand-building a page (dashboard, settings, list, wizard, auth) from scratch.
8. Navigation uses useLinkComponent(), never a hardcoded <a>.
9. Dense data is rows, not cards. Use Table or List+Item for lists of records; Card is for widgets, galleries, or grouped settings — not one card per row.

Reach for these components (not raw HTML)

This table is a quick guide, not the catalog — run npx --no astryx component --list for every component grouped by category, or npx --no astryx search when nothing here fits.

Pitfalls

Red flags — stop and use Astryx

• About to write <div style={{...}}> or a raw className for layout, color, or spacing
• About to npm install any other component or styling library
• About to write JSX for a form, list, card, dialog, nav, or button from scratch
• Thinking "it's just a placeholder" or "Astryx isn't set up in this app yet"
• Using a prop without having confirmed it exists via astryx component <Name> --dense
• About to satisfy a brand-color requirement by styling components instead of compiling a theme — or about to ignore one because no stock theme matches
• About to ask which theme or colors to use — that is settled in Brand colors, and "not set" means the stock theme, not an open question

All of these mean: stop, run astryx search / astryx component <Name> --dense, and use what it returns.