`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: ```bash 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`): ```ts // 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()]}); ``` ```tsx // 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 in — 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.: ```markdown - 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: ```bash # 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: | Token | Set it to | |---|---| | `--color-accent`, `--color-text-accent`, `--color-icon-accent` | the accent brand color; the **light** slot usually needs a darkened variant to stay AA on a light background | | `--color-on-accent` | the text color that sits ON the accent — check contrast both ways | | `--color-accent-muted` | the accent at low alpha (e.g. `#RRGGBB33`) | | `--color-background-body`, `--color-background-surface`, `--color-background-card`, `--color-background-popover`, `--color-background-muted` | the neutral brand color, as a ramp — body darkest, surface/card a step lighter, never all the same value | 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`: ```tsx // main.tsx import '@astryxdesign/core/reset.css'; import './theme/brand.css'; import {Theme} from '@astryxdesign/core/theme'; import {brandTheme} from './theme/brand'; // wrap in ``` 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`: ```bash 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 `