[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M735HYGS0HARMX9620T7ECFR":3,"skill-same:01M735HYGS0HARMX9620T7ECFR":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":29,"commitSha":30,"skillDirectory":31,"forksCount":14,"repositoryHtmlUrl":32,"repositoryHomepageUrl":6,"ownerHtmlUrl":33,"ownerBlogUrl":34,"ownerDescription":35,"updatedAt":36,"install":37,"resources":50},"01M735HYGS0HARMX9620T7ECFR","astryx-design-system",null,"Astryx (`@astryxdesign\u002Fcore`) — a web-app design system this library keeps available, covering its Theme + StyleX wiring, the organization's settled brand colors, and the CLI you confirm every component's props against before writing JSX. Apply to all UI work in a `web-application` that pins it — pages, layouts, forms, tables, dialogs, nav, theming — even when the task never names Astryx.","wso2\u002Flabs-agentic-engineer","wso2","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F533043?v=4","01M6CDAFS40T9Y86DYXWE0NJES","WSO2","01M735EE4N2PP2ZR56AX7DNPNP",24,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Fastryx-design-system\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: astryx-design-system\ndescription: Astryx (`@astryxdesign\u002Fcore`) — a web-app design system this library keeps available, covering its Theme + StyleX wiring, the organization's settled brand colors, and the CLI you confirm every component's props against before writing JSX. Apply to all UI work in a `web-application` that pins it — pages, layouts, forms, tables, dialogs, nav, theming — even when the task never names Astryx.\nmetadata:\n  aep:\n    kind: org\n    audience: [coding]\n---\n\n# Astryx Design System\n\nAstryx (`@astryxdesign\u002Fcore`) is **this organization's** UI toolkit —\ncomponents, layout, and styling (via StyleX) all come from it. Never raw HTML\nstyling, never another component library, never an invented component prop.\n\nYou are here because the component you are building pinned this skill, so the\nwhole of it is yours — theming included. The organization's colors are settled\nin Brand colors below; nobody is interviewed about them, at design time or any\nother time.\n\n`react-webapp` owns the app: layout, config, verify sequence, Dockerfile, nginx.\nThis skill owns what goes **inside** `src\u002F` — the UI. Where the two appear to\ndisagree, `react-webapp` wins; the conflicts worth naming are listed under\nPlatform constraints below.\n\n## Correctness through the CLI, not memory\n\nAstryx ships `@astryxdesign\u002Fcli` because component APIs move faster than any\nmodel's training data. The CLI reads the *installed* version, so it is always\nright; a guessed prop is never right by comparison. The discipline: **before\nwriting JSX for a component you have not confirmed this session, run the CLI,\nthen write the JSX** — never the reverse.\n\n**Always invoke it as `npx --no astryx …`.** `--no` restricts resolution to the\n`@astryxdesign\u002Fcli` in this app's `node_modules` — the version `package-lock.json`\npins. Without it, an `npx astryx` in an app whose install has not run fetches and\nexecutes the unrelated `astryx` package that exists on the public registry. Do not\ndrop the flag to shorten a command: if the CLI is missing, the right outcome is the\nloud `could not determine executable to run`, not a stranger's postinstall script\nrunning in the build pod.\n\n**Violating the letter of this rule is violating the spirit of it.** \"It's just a\nplaceholder page,\" \"the app doesn't have Astryx wired up yet,\" and \"this screen\nis throwaway\" are reasons to wire Astryx up *faster*, not reasons to skip it — a\npage built in raw `\u003Cdiv>`s is what deploys, because there is no human code-review\ngate between your PR and the dev environment.\n\n## Setup\n\n`react-webapp` scaffolds the app. Add Astryx to it:\n\n```bash\nnpm install @astryxdesign\u002Fcore @stylexjs\u002Fstylex @astryxdesign\u002Ftheme-neutral @astryxdesign\u002Fbuild\nnpm install -D @astryxdesign\u002Fcli\n```\n\n`@astryxdesign\u002Fcore` declares React **19+** as a hard peer dependency — set\n`react` \u002F `react-dom` to `^19` in `package.json`, not an older major.\n\nWire the build (order matters — `astryxStylex()` before `react()`, and **no\n`base`**, per `react-webapp`):\n\n```ts\n\u002F\u002F vite.config.ts\nimport {defineConfig} from 'vite';\nimport react from '@vitejs\u002Fplugin-react';\nimport {astryxStylex} from '@astryxdesign\u002Fbuild\u002Fvite';\n\nexport default defineConfig({plugins: [...astryxStylex(), react()]});\n```\n\n```tsx\n\u002F\u002F main.tsx — reset + theme CSS load before anything renders\nimport '@astryxdesign\u002Fcore\u002Freset.css';\nimport '@astryxdesign\u002Ftheme-neutral\u002Ftheme.css';\nimport {Theme} from '@astryxdesign\u002Fcore\u002Ftheme';\nimport {neutralTheme} from '@astryxdesign\u002Ftheme-neutral\u002Fbuilt';\n\u002F\u002F wrap \u003CApp\u002F> in \u003CTheme theme={neutralTheme}> — swap the theme package to change\n\u002F\u002F the look, never hand-roll colors instead\n```\n\nThat stock package is the default and the fallback. It is what a project gets\nwhen this organization has not set brand colors — see the next section.\n\n## Brand colors\n\nA web app is themed at its FIRST build, and retrofitting a theme means revisiting\nevery screen — so the colors cannot be a per-build decision. They are an\n**organization** decision, settled once in the section below and compiled at\nbuild time, exactly like the language a service is written in.\n\n**Never ask anyone for them.** Not at design time, not at coding time, not once\nper project. The answer is either set below or it is the stock theme, and both\nare complete answers — a question about theming is a defect, not diligence.\n\n### The organization's colors\n\n- Accent (buttons, links, focus): _not set — use the stock theme_\n- Neutral (backgrounds, surfaces): _not set — use the stock theme_\n\nTo brand every web app this organization builds, an org edits those two lines to\nhex values (Settings → Skills), e.g.:\n\n```markdown\n- Accent (buttons, links, focus): #f5c518\n- Neutral (backgrounds, surfaces): #0a0a0a\n```\n\nHEX only, never color words: \"black and yellow\" does not say WHICH yellow, and\nthis file is the whole of what a build sees. The edit reaches every subsequent\nbuild in the org with no conversation involved.\n\nA per-project override still wins, **per value, not per section**: a hex under\nthe `## Brand colors` heading in the project's `specs\u002Frequirements\u002Fprd.md`\noverrides the same line here, and a line that heading omits still comes from\nthis section. That heading is there for a project whose colors someone stated\noutright — it is not something to solicit, and a half-filled one is not a\nreason to drop the organization's other color.\n\n### At build time — compile the theme\n\nResolve each of the two colors before you wire the theme, independently: the\nproject's `## Brand colors` line in `specs\u002Frequirements\u002Fprd.md` if it has one,\notherwise the line in The organization's colors above. **A color neither one\nsets is not chosen** — take it from the stock theme's own token and never\ninvent one, whether that leaves you with two brand colors, one, or none. One\nbrand color plus one stock color is a valid outcome; a guessed hex is not.\n\nWith colors, a brand theme is a **compiled theme of your own** — not hand-written\ncolors sprinkled over a stock one. Editing component styles to paint them brand\ncolors violates \"colors are tokens\" and leaves every unstyled surface off-brand.\nScaffold a stock theme as editable source, retune its color tokens, compile it:\n\n```bash\n# 1. scaffold the closest stock theme as YOUR source (once)\nnpx --no astryx theme add neutral src\u002Ftheme\n# 2. copy it to src\u002Ftheme\u002FbrandTheme.ts, rename the exported symbol +\n#    `name:` + its defineSyntaxTheme `name:`, then edit the color tokens\n# 3. compile — emits brand.css + brand.js + brand.d.ts beside the source\nnpx --no astryx theme build src\u002Ftheme\u002FbrandTheme.ts -o src\u002Ftheme\u002Fbrand.css\n```\n\nEvery color token is a `[light, dark]` pair. Retune this set and leave the rest\nof the scaffold alone — they are what carry a brand:\n\n| Token | Set it to |\n|---|---|\n| `--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 |\n| `--color-on-accent` | the text color that sits ON the accent — check contrast both ways |\n| `--color-accent-muted` | the accent at low alpha (e.g. `#RRGGBB33`) |\n| `--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\u002Fcard a step lighter, never all the same value |\n\nThen wire the compiled output exactly like a package theme — the import is the\nbuild's `-o` CSS plus the sibling JS, both from `src\u002Ftheme\u002F`, never the `.ts`:\n\n```tsx\n\u002F\u002F main.tsx\nimport '@astryxdesign\u002Fcore\u002Freset.css';\nimport '.\u002Ftheme\u002Fbrand.css';\nimport {Theme} from '@astryxdesign\u002Fcore\u002Ftheme';\nimport {brandTheme} from '.\u002Ftheme\u002Fbrand';\n\u002F\u002F wrap \u003CApp\u002F> in \u003CTheme theme={brandTheme}>\n```\n\nCommit the generated `brand.css` \u002F `brand.js` \u002F `brand.d.ts` alongside the\nsource: the Docker build runs `npm run build`, not the theme compiler, so an\nuncommitted build output ships an unthemed app. Re-run `theme build` after\nevery edit to `brandTheme.ts` — editing the source alone changes nothing.\n\nTwo colors is the common case, and it does not mean two tokens. Map the neutral\nacross the background ramp and the accent across the accent trio; a pure\n`#FFFF00`-class hue almost always needs darkening for its light-mode slot and\ndark text for `--color-on-accent`. Contrast is not negotiable to match a brand:\nkeep the hue, move the lightness.\n\n## Verify\n\nThis skill's step in `react-webapp`'s verify sequence — after `npm install`,\nbefore `npx tsc --noEmit`:\n\n```bash\nnpx --no astryx doctor\n```\n\nA non-zero exit fails verification like any other step in that sequence. It is\nthere because a wiring fault (a missing `astryxStylex()` plugin, an unimported\ntheme, a React peer-dependency mismatch) type-checks and builds perfectly clean,\nthen renders an unstyled page in the cluster — cheap to fix here, expensive to\ndebug after the Docker build.\n\n## Platform constraints that override this system's defaults\n\nFour places where Astryx's own defaults do not fit this platform. Each is a\nruntime, build, or guidance failure, not a style preference:\n\n1. **Never install Astryx's agent docs.** `astryx init` itself is fine — it\n   initializes the design system in an *existing* project, and it is not\n   required, because the Setup section above already states the wiring. What\n   must not land is the `agents` feature: `astryx init --features agents`\n   writes `AGENTS.md` into the repo root, and `--all` includes it. Guidance\n   reaches you as skills, so a committed agent file is a second authority that\n   nothing updates — it is stale the moment this skill changes. `--features` is\n   an allow-list, so name only what you want (`--features theme`) and never\n   `--all`; if agent docs already landed, `astryx init --remove-agents` deletes\n   them.\n2. **Never set `base` in `vite.config.ts`**, whatever an Astryx snippet shows.\n   Each web app is served at its own gateway host root; a `base` 404s every asset\n   and the page renders blank (`react-webapp`, Served at host root).\n3. **The CSS imports go in `main.tsx`, never in `index.html`.** `index.html`'s\n   only `\u003Cscript>` rules are `react-webapp`'s: the synchronous `env-config.js`\n   tag first, the module bundle second. Adding a stylesheet or script tag around\n   them risks `window._env_` being unset when the first module evaluates.\n4. **Theme tokens are not runtime config.** Colors and spacing come from the\n   theme package at build time. `window._env_` carries only what the **browser**\n   needs — OIDC config and flags — so do not plumb a theme value through it.\n\nAstryx replaces hand-written UI, not the platform's data layer: `openapi-fetch`\nand the committed `src\u002Fgenerated\u002F` client stay exactly as `react-webapp`\nspecifies. \"Install no other library\" below is about UI and styling.\n\n## Critical rules\n\n1. **Import everything from `@astryxdesign\u002Fcore\u002F\u003CCategory>`** (per-category\n   subpath entry points, e.g. `@astryxdesign\u002Fcore\u002FButton`,\n   `@astryxdesign\u002Fcore\u002FLayout`) — never from Tailwind, MUI, Chakra, Ant Design,\n   Bootstrap, or a hand-rolled component.\n2. **Run `npx --no astryx component \u003CName> --dense` before using ANY component**,\n   even one already used earlier in this session — confirm the prop exists before\n   writing it, don't guess.\n3. **Search before building.** Run `npx --no astryx search \"\u003Cthing>\"` when unsure\n   what exists; Astryx ships more components than you would assume (tag inputs,\n   command palettes, tree lists, chat UI) — check before reaching for a wrapper\n   `\u003Cdiv>` or a new dependency.\n4. **Layout is `VStack`\u002F`HStack`\u002F`Grid`\u002F`Stack` from `@astryxdesign\u002Fcore\u002FLayout`**\n   — never a raw `\u003Cdiv>`\u002F`\u003Cspan>` for spacing or arrangement.\n5. **Style overrides are `stylex.create()` + the component's `xstyle` prop** —\n   never `style={{...}}`, and never `className`\u002F`style` alongside\n   `{...stylex.props()}` (use `mergeProps()` if you must combine).\n6. **Colors and spacing are tokens, never literals.** Run\n   `npx --no astryx docs tokens --dense`; use the CSS-var color tokens and\n   `spaceN` gap values it documents, not hex\u002Frgb or raw px.\n7. **Page-level structure follows a template, not intuition.** Run\n   `npx --no astryx template --list` and `npx --no astryx template \u003Cname>\n   --skeleton` to find and study a layout skeleton before hand-building a page (dashboard,\n   settings, list, wizard, auth) from scratch.\n8. **Navigation uses `useLinkComponent()`**, never a hardcoded `\u003Ca>`.\n9. **Dense data is rows, not cards.** Use `Table` or `List`+`Item` for lists of\n   records; `Card` is for widgets, galleries, or grouped settings — not one card\n   per row.\n\n## Reach for these components (not raw HTML)\n\n| If you're about to build… | Use instead |\n|---|---|\n| Page shell with top bar + side nav | `AppShell`, `TopNav`, `SideNav`, `MobileNav` |\n| A data table \u002F list view | `Table`, `List` + `Item`, `MetadataList` |\n| A form with grouped fields | `FormLayout`, `Field`, `FieldStatus` |\n| A select \u002F combobox \u002F tag input | `Selector`, `MultiSelector`, `ComplexSelector`, `Typeahead`, `Tokenizer` |\n| A modal \u002F confirmation dialog | `Dialog`, `AlertDialog` |\n| A dropdown \u002F context \u002F command menu | `DropdownMenu`, `ContextMenu`, `MoreMenu`, `CommandPalette` |\n| Status \u002F count \u002F label chip | `Badge`, `StatusDot`, `Token`, `Indicator` |\n| Tooltip \u002F hover detail \u002F anchored popup | `Tooltip`, `HoverCard`, `Popover` |\n| Date\u002Ftime entry | `DateInput`, `DateRangeInput`, `DateTimeInput`, `TimeInput`, `Calendar` |\n| Loading \u002F empty state | `Skeleton`, `Spinner`, `ProgressBar`, `EmptyState` |\n| Breadcrumbs \u002F global search | `Breadcrumbs`, `PowerSearch` |\n| Toggle \u002F choice input | `Switch`, `CheckboxInput`, `CheckboxList`, `RadioList`, `SegmentedControl`, `ToggleButton` |\n\nThis table is a quick guide, not the catalog — run\n`npx --no astryx component --list` for every component grouped by category, or\n`npx --no astryx search` when nothing here fits.\n\n## Pitfalls\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| Astryx components render unstyled\u002Funthemed | `reset.css`\u002Ftheme CSS not imported, or imported after other global CSS without layer ordering | Import reset + theme first in `main.tsx`; if the app has other global CSS, assign every stylesheet an explicit `@layer` (`npx --no astryx docs migration`) |\n| `npm install` fails \u002F peer-dependency warnings on React | `package.json` is on React \u003C19 | Set `react`\u002F`react-dom` to `^19` before installing `@astryxdesign\u002Fcore` |\n| Build succeeds but StyleX classes\u002Fstyles don't apply | `astryxStylex()` missing from `vite.config.ts`, or ordered after `react()` | Add `...astryxStylex()` to `plugins`, listed before `react()` |\n| Page renders blank in dev, every asset 404s | `base` was set in `vite.config.ts` from an Astryx snippet | Remove it — served at host root (`react-webapp`) |\n| A prop doesn't exist, or is the old spelling | Answered from memory instead of the CLI | Run `npx --no astryx component \u003CName> --dense` — the CLI reflects the installed version, training data doesn't |\n| Every row in a list is wrapped in its own `Card` | Defaulted to a generic \"card grid\" instead of checking data density | `npx --no astryx docs principles --dense` — dense data is `Table`\u002F`List`+`Item`; `Card` is for widgets\u002Fgalleries\u002Fsettings groups |\n| Brand colors are set, deployed app is stock-themed | Colors were read but never compiled into a theme, or `brandTheme.ts` was edited without re-running `theme build` | Re-run `npx --no astryx theme build src\u002Ftheme\u002FbrandTheme.ts -o src\u002Ftheme\u002Fbrand.css` and confirm `brand.css`\u002F`brand.js` are COMMITTED — the image build never runs the compiler |\n| The user gave brand colors in chat, the build ignored them | A coding run never sees a conversation — colors reach it only from this skill or the project's `specs\u002Frequirements\u002Fprd.md` | Set them in The organization's colors (Settings → Skills) for the whole org, or under `## Brand colors` in the project's `specs\u002Frequirements\u002Fprd.md` for one project; an answer that is not in a file did not happen |\n| Brand accent is unreadable — pale text on a pale button | The brand hex was pasted into both `[light, dark]` slots of `--color-accent` | Darken the light-mode slot and set `--color-on-accent` to a color that contrasts with the accent in each mode |\n\n## Red flags — stop and use Astryx\n\n- About to write `\u003Cdiv style={{...}}>` or a raw `className` for layout, color, or\n  spacing\n- About to `npm install` any other component or styling library\n- About to write JSX for a form, list, card, dialog, nav, or button from scratch\n- Thinking \"it's just a placeholder\" or \"Astryx isn't set up in this app yet\"\n- Using a prop without having confirmed it exists via\n  `astryx component \u003CName> --dense`\n- About to satisfy a brand-color requirement by styling components instead of\n  compiling a theme — or about to ignore one because no stock theme matches\n- About to ask which theme or colors to use — that is settled in Brand colors,\n  and \"not set\" means the stock theme, not an open question\n\nAll of these mean: stop, run `astryx search` \u002F `astryx component \u003CName> --dense`,\nand use what it returns.\n","# Astryx Design System\n\nAstryx (`@astryxdesign\u002Fcore`) is **this organization's** UI toolkit —\ncomponents, layout, and styling (via StyleX) all come from it. Never raw HTML\nstyling, never another component library, never an invented component prop.\n\nYou are here because the component you are building pinned this skill, so the\nwhole of it is yours — theming included. The organization's colors are settled\nin Brand colors below; nobody is interviewed about them, at design time or any\nother time.\n\n`react-webapp` owns the app: layout, config, verify sequence, Dockerfile, nginx.\nThis skill owns what goes **inside** `src\u002F` — the UI. Where the two appear to\ndisagree, `react-webapp` wins; the conflicts worth naming are listed under\nPlatform constraints below.\n\n## Correctness through the CLI, not memory\n\nAstryx ships `@astryxdesign\u002Fcli` because component APIs move faster than any\nmodel's training data. The CLI reads the *installed* version, so it is always\nright; a guessed prop is never right by comparison. The discipline: **before\nwriting JSX for a component you have not confirmed this session, run the CLI,\nthen write the JSX** — never the reverse.\n\n**Always invoke it as `npx --no astryx …`.** `--no` restricts resolution to the\n`@astryxdesign\u002Fcli` in this app's `node_modules` — the version `package-lock.json`\npins. Without it, an `npx astryx` in an app whose install has not run fetches and\nexecutes the unrelated `astryx` package that exists on the public registry. Do not\ndrop the flag to shorten a command: if the CLI is missing, the right outcome is the\nloud `could not determine executable to run`, not a stranger's postinstall script\nrunning in the build pod.\n\n**Violating the letter of this rule is violating the spirit of it.** \"It's just a\nplaceholder page,\" \"the app doesn't have Astryx wired up yet,\" and \"this screen\nis throwaway\" are reasons to wire Astryx up *faster*, not reasons to skip it — a\npage built in raw `\u003Cdiv>`s is what deploys, because there is no human code-review\ngate between your PR and the dev environment.\n\n## Setup\n\n`react-webapp` scaffolds the app. Add Astryx to it:\n\n```bash\nnpm install @astryxdesign\u002Fcore @stylexjs\u002Fstylex @astryxdesign\u002Ftheme-neutral @astryxdesign\u002Fbuild\nnpm install -D @astryxdesign\u002Fcli\n```\n\n`@astryxdesign\u002Fcore` declares React **19+** as a hard peer dependency — set\n`react` \u002F `react-dom` to `^19` in `package.json`, not an older major.\n\nWire the build (order matters — `astryxStylex()` before `react()`, and **no\n`base`**, per `react-webapp`):\n\n```ts\n\u002F\u002F vite.config.ts\nimport {defineConfig} from 'vite';\nimport react from '@vitejs\u002Fplugin-react';\nimport {astryxStylex} from '@astryxdesign\u002Fbuild\u002Fvite';\n\nexport default defineConfig({plugins: [...astryxStylex(), react()]});\n```\n\n```tsx\n\u002F\u002F main.tsx — reset + theme CSS load before anything renders\nimport '@astryxdesign\u002Fcore\u002Freset.css';\nimport '@astryxdesign\u002Ftheme-neutral\u002Ftheme.css';\nimport {Theme} from '@astryxdesign\u002Fcore\u002Ftheme';\nimport {neutralTheme} from '@astryxdesign\u002Ftheme-neutral\u002Fbuilt';\n\u002F\u002F wrap \u003CApp\u002F> in \u003CTheme theme={neutralTheme}> — swap the theme package to change\n\u002F\u002F the look, never hand-roll colors instead\n```\n\nThat stock package is the default and the fallback. It is what a project gets\nwhen this organization has not set brand colors — see the next section.\n\n## Brand colors\n\nA web app is themed at its FIRST build, and retrofitting a theme means revisiting\nevery screen — so the colors cannot be a per-build decision. They are an\n**organization** decision, settled once in the section below and compiled at\nbuild time, exactly like the language a service is written in.\n\n**Never ask anyone for them.** Not at design time, not at coding time, not once\nper project. The answer is either set below or it is the stock theme, and both\nare complete answers — a question about theming is a defect, not diligence.\n\n### The organization's colors\n\n- Accent (buttons, links, focus): _not set — use the stock theme_\n- Neutral (backgrounds, surfaces): _not set — use the stock theme_\n\nTo brand every web app this organization builds, an org edits those two lines to\nhex values (Settings → Skills), e.g.:\n\n```markdown\n- Accent (buttons, links, focus): #f5c518\n- Neutral (backgrounds, surfaces): #0a0a0a\n```\n\nHEX only, never color words: \"black and yellow\" does not say WHICH yellow, and\nthis file is the whole of what a build sees. The edit reaches every subsequent\nbuild in the org with no conversation involved.\n\nA per-project override still wins, **per value, not per section**: a hex under\nthe `## Brand colors` heading in the project's `specs\u002Frequirements\u002Fprd.md`\noverrides the same line here, and a line that heading omits still comes from\nthis section. That heading is there for a project whose colors someone stated\noutright — it is not something to solicit, and a half-filled one is not a\nreason to drop the organization's other color.\n\n### At build time — compile the theme\n\nResolve each of the two colors before you wire the theme, independently: the\nproject's `## Brand colors` line in `specs\u002Frequirements\u002Fprd.md` if it has one,\notherwise the line in The organization's colors above. **A color neither one\nsets is not chosen** — take it from the stock theme's own token and never\ninvent one, whether that leaves you with two brand colors, one, or none. One\nbrand color plus one stock color is a valid outcome; a guessed hex is not.\n\nWith colors, a brand theme is a **compiled theme of your own** — not hand-written\ncolors sprinkled over a stock one. Editing component styles to paint them brand\ncolors violates \"colors are tokens\" and leaves every unstyled surface off-brand.\nScaffold a stock theme as editable source, retune its color tokens, compile it:\n\n```bash\n# 1. scaffold the closest stock theme as YOUR source (once)\nnpx --no astryx theme add neutral src\u002Ftheme\n# 2. copy it to src\u002Ftheme\u002FbrandTheme.ts, rename the exported symbol +\n#    `name:` + its defineSyntaxTheme `name:`, then edit the color tokens\n# 3. compile — emits brand.css + brand.js + brand.d.ts beside the source\nnpx --no astryx theme build src\u002Ftheme\u002FbrandTheme.ts -o src\u002Ftheme\u002Fbrand.css\n```\n\nEvery color token is a `[light, dark]` pair. Retune this set and leave the rest\nof the scaffold alone — they are what carry a brand:\n\n| Token | Set it to |\n|---|---|\n| `--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 |\n| `--color-on-accent` | the text color that sits ON the accent — check contrast both ways |\n| `--color-accent-muted` | the accent at low alpha (e.g. `#RRGGBB33`) |\n| `--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\u002Fcard a step lighter, never all the same value |\n\nThen wire the compiled output exactly like a package theme — the import is the\nbuild's `-o` CSS plus the sibling JS, both from `src\u002Ftheme\u002F`, never the `.ts`:\n\n```tsx\n\u002F\u002F main.tsx\nimport '@astryxdesign\u002Fcore\u002Freset.css';\nimport '.\u002Ftheme\u002Fbrand.css';\nimport {Theme} from '@astryxdesign\u002Fcore\u002Ftheme';\nimport {brandTheme} from '.\u002Ftheme\u002Fbrand';\n\u002F\u002F wrap \u003CApp\u002F> in \u003CTheme theme={brandTheme}>\n```\n\nCommit the generated `brand.css` \u002F `brand.js` \u002F `brand.d.ts` alongside the\nsource: the Docker build runs `npm run build`, not the theme compiler, so an\nuncommitted build output ships an unthemed app. Re-run `theme build` after\nevery edit to `brandTheme.ts` — editing the source alone changes nothing.\n\nTwo colors is the common case, and it does not mean two tokens. Map the neutral\nacross the background ramp and the accent across the accent trio; a pure\n`#FFFF00`-class hue almost always needs darkening for its light-mode slot and\ndark text for `--color-on-accent`. Contrast is not negotiable to match a brand:\nkeep the hue, move the lightness.\n\n## Verify\n\nThis skill's step in `react-webapp`'s verify sequence — after `npm install`,\nbefore `npx tsc --noEmit`:\n\n```bash\nnpx --no astryx doctor\n```\n\nA non-zero exit fails verification like any other step in that sequence. It is\nthere because a wiring fault (a missing `astryxStylex()` plugin, an unimported\ntheme, a React peer-dependency mismatch) type-checks and builds perfectly clean,\nthen renders an unstyled page in the cluster — cheap to fix here, expensive to\ndebug after the Docker build.\n\n## Platform constraints that override this system's defaults\n\nFour places where Astryx's own defaults do not fit this platform. Each is a\nruntime, build, or guidance failure, not a style preference:\n\n1. **Never install Astryx's agent docs.** `astryx init` itself is fine — it\n   initializes the design system in an *existing* project, and it is not\n   required, because the Setup section above already states the wiring. What\n   must not land is the `agents` feature: `astryx init --features agents`\n   writes `AGENTS.md` into the repo root, and `--all` includes it. Guidance\n   reaches you as skills, so a committed agent file is a second authority that\n   nothing updates — it is stale the moment this skill changes. `--features` is\n   an allow-list, so name only what you want (`--features theme`) and never\n   `--all`; if agent docs already landed, `astryx init --remove-agents` deletes\n   them.\n2. **Never set `base` in `vite.config.ts`**, whatever an Astryx snippet shows.\n   Each web app is served at its own gateway host root; a `base` 404s every asset\n   and the page renders blank (`react-webapp`, Served at host root).\n3. **The CSS imports go in `main.tsx`, never in `index.html`.** `index.html`'s\n   only `\u003Cscript>` rules are `react-webapp`'s: the synchronous `env-config.js`\n   tag first, the module bundle second. Adding a stylesheet or script tag around\n   them risks `window._env_` being unset when the first module evaluates.\n4. **Theme tokens are not runtime config.** Colors and spacing come from the\n   theme package at build time. `window._env_` carries only what the **browser**\n   needs — OIDC config and flags — so do not plumb a theme value through it.\n\nAstryx replaces hand-written UI, not the platform's data layer: `openapi-fetch`\nand the committed `src\u002Fgenerated\u002F` client stay exactly as `react-webapp`\nspecifies. \"Install no other library\" below is about UI and styling.\n\n## Critical rules\n\n1. **Import everything from `@astryxdesign\u002Fcore\u002F\u003CCategory>`** (per-category\n   subpath entry points, e.g. `@astryxdesign\u002Fcore\u002FButton`,\n   `@astryxdesign\u002Fcore\u002FLayout`) — never from Tailwind, MUI, Chakra, Ant Design,\n   Bootstrap, or a hand-rolled component.\n2. **Run `npx --no astryx component \u003CName> --dense` before using ANY component**,\n   even one already used earlier in this session — confirm the prop exists before\n   writing it, don't guess.\n3. **Search before building.** Run `npx --no astryx search \"\u003Cthing>\"` when unsure\n   what exists; Astryx ships more components than you would assume (tag inputs,\n   command palettes, tree lists, chat UI) — check before reaching for a wrapper\n   `\u003Cdiv>` or a new dependency.\n4. **Layout is `VStack`\u002F`HStack`\u002F`Grid`\u002F`Stack` from `@astryxdesign\u002Fcore\u002FLayout`**\n   — never a raw `\u003Cdiv>`\u002F`\u003Cspan>` for spacing or arrangement.\n5. **Style overrides are `stylex.create()` + the component's `xstyle` prop** —\n   never `style={{...}}`, and never `className`\u002F`style` alongside\n   `{...stylex.props()}` (use `mergeProps()` if you must combine).\n6. **Colors and spacing are tokens, never literals.** Run\n   `npx --no astryx docs tokens --dense`; use the CSS-var color tokens and\n   `spaceN` gap values it documents, not hex\u002Frgb or raw px.\n7. **Page-level structure follows a template, not intuition.** Run\n   `npx --no astryx template --list` and `npx --no astryx template \u003Cname>\n   --skeleton` to find and study a layout skeleton before hand-building a page (dashboard,\n   settings, list, wizard, auth) from scratch.\n8. **Navigation uses `useLinkComponent()`**, never a hardcoded `\u003Ca>`.\n9. **Dense data is rows, not cards.** Use `Table` or `List`+`Item` for lists of\n   records; `Card` is for widgets, galleries, or grouped settings — not one card\n   per row.\n\n## Reach for these components (not raw HTML)\n\n| If you're about to build… | Use instead |\n|---|---|\n| Page shell with top bar + side nav | `AppShell`, `TopNav`, `SideNav`, `MobileNav` |\n| A data table \u002F list view | `Table`, `List` + `Item`, `MetadataList` |\n| A form with grouped fields | `FormLayout`, `Field`, `FieldStatus` |\n| A select \u002F combobox \u002F tag input | `Selector`, `MultiSelector`, `ComplexSelector`, `Typeahead`, `Tokenizer` |\n| A modal \u002F confirmation dialog | `Dialog`, `AlertDialog` |\n| A dropdown \u002F context \u002F command menu | `DropdownMenu`, `ContextMenu`, `MoreMenu`, `CommandPalette` |\n| Status \u002F count \u002F label chip | `Badge`, `StatusDot`, `Token`, `Indicator` |\n| Tooltip \u002F hover detail \u002F anchored popup | `Tooltip`, `HoverCard`, `Popover` |\n| Date\u002Ftime entry | `DateInput`, `DateRangeInput`, `DateTimeInput`, `TimeInput`, `Calendar` |\n| Loading \u002F empty state | `Skeleton`, `Spinner`, `ProgressBar`, `EmptyState` |\n| Breadcrumbs \u002F global search | `Breadcrumbs`, `PowerSearch` |\n| Toggle \u002F choice input | `Switch`, `CheckboxInput`, `CheckboxList`, `RadioList`, `SegmentedControl`, `ToggleButton` |\n\nThis table is a quick guide, not the catalog — run\n`npx --no astryx component --list` for every component grouped by category, or\n`npx --no astryx search` when nothing here fits.\n\n## Pitfalls\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| Astryx components render unstyled\u002Funthemed | `reset.css`\u002Ftheme CSS not imported, or imported after other global CSS without layer ordering | Import reset + theme first in `main.tsx`; if the app has other global CSS, assign every stylesheet an explicit `@layer` (`npx --no astryx docs migration`) |\n| `npm install` fails \u002F peer-dependency warnings on React | `package.json` is on React \u003C19 | Set `react`\u002F`react-dom` to `^19` before installing `@astryxdesign\u002Fcore` |\n| Build succeeds but StyleX classes\u002Fstyles don't apply | `astryxStylex()` missing from `vite.config.ts`, or ordered after `react()` | Add `...astryxStylex()` to `plugins`, listed before `react()` |\n| Page renders blank in dev, every asset 404s | `base` was set in `vite.config.ts` from an Astryx snippet | Remove it — served at host root (`react-webapp`) |\n| A prop doesn't exist, or is the old spelling | Answered from memory instead of the CLI | Run `npx --no astryx component \u003CName> --dense` — the CLI reflects the installed version, training data doesn't |\n| Every row in a list is wrapped in its own `Card` | Defaulted to a generic \"card grid\" instead of checking data density | `npx --no astryx docs principles --dense` — dense data is `Table`\u002F`List`+`Item`; `Card` is for widgets\u002Fgalleries\u002Fsettings groups |\n| Brand colors are set, deployed app is stock-themed | Colors were read but never compiled into a theme, or `brandTheme.ts` was edited without re-running `theme build` | Re-run `npx --no astryx theme build src\u002Ftheme\u002FbrandTheme.ts -o src\u002Ftheme\u002Fbrand.css` and confirm `brand.css`\u002F`brand.js` are COMMITTED — the image build never runs the compiler |\n| The user gave brand colors in chat, the build ignored them | A coding run never sees a conversation — colors reach it only from this skill or the project's `specs\u002Frequirements\u002Fprd.md` | Set them in The organization's colors (Settings → Skills) for the whole org, or under `## Brand colors` in the project's `specs\u002Frequirements\u002Fprd.md` for one project; an answer that is not in a file did not happen |\n| Brand accent is unreadable — pale text on a pale button | The brand hex was pasted into both `[light, dark]` slots of `--color-accent` | Darken the light-mode slot and set `--color-on-accent` to a color that contrasts with the accent in each mode |\n\n## Red flags — stop and use Astryx\n\n- About to write `\u003Cdiv style={{...}}>` or a raw `className` for layout, color, or\n  spacing\n- About to `npm install` any other component or styling library\n- About to write JSX for a form, list, card, dialog, nav, or button from scratch\n- Thinking \"it's just a placeholder\" or \"Astryx isn't set up in this app yet\"\n- Using a prop without having confirmed it exists via\n  `astryx component \u003CName> --dense`\n- About to satisfy a brand-color requirement by styling components instead of\n  compiling a theme — or about to ignore one because no stock theme matches\n- About to ask which theme or colors to use — that is settled in Brand colors,\n  and \"not set\" means the stock theme, not an open question\n\nAll of these mean: stop, run `astryx search` \u002F `astryx component \u003CName> --dense`,\nand use what it returns.\n",{"name":5,"metadata":24,"description":7},{"aep":25},{"kind":26,"audience":27},"org",[28],"coding","main","e3b5fc8668f26761380b2d4965719f2d8f2eb246","skills\u002Fastryx-design-system","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer","https:\u002F\u002Fgithub.com\u002Fwso2","https:\u002F\u002Fwso2.com","Welcome to the WSO2 source code! For info on working with the WSO2 repositories and contributing code, click the link below.","2026-11-11 15:36:27",{"source":8,"skillName":5,"commands":38,"prompt":48,"zipAvailable":49},[39,42,45],{"tool":40,"command":41},"npx","npx skills add wso2\u002Flabs-agentic-engineer --skill astryx-design-system",{"tool":43,"command":44},"bunx","bunx skills add wso2\u002Flabs-agentic-engineer --skill astryx-design-system",{"tool":46,"command":47},"pnpm","pnpm dlx skills add wso2\u002Flabs-agentic-engineer --skill astryx-design-system","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Fastryx-design-system\u002FSKILL.md",true,[],[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M735MP9NFFRPS260G9D16JQX","validation-task","Load when working a VALIDATION task dispatched by WSO2 Labs Agentic Engineer — judging a deployed version against its acceptance criteria.","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Fvalidation-task\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M735MJ8ZMRZR20A57TMF7R9Q","thunder-authentication","Apply when a component sits on the project's sign-in — a SPA whose users authenticate through the auth platform-resource dependency, or a protected backend those signed-in users call.","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Fthunder-authentication\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M735MFQMY8DY1EM7JKS784D3","task-planning","Use when planning a version's build from a design — the plan turn that writes the build's checklist with planBuild, one item per feature the version carries in build order, after a Foundation item when the version needs one.","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Ftask-planning\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M735MCJQ4EVH7G4ZFMC682Y4","start","Use when kicking off a project from its idea — the product pass that agrees the feature list and writes the product page, the product-wide page and a stub per feature — or re-running \u002Fstart on a project that already has requirements.","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Fstart\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M735M9R050KT3H34PVXN2MKK","security-design","Write specs\u002Fdesign\u002Fsecurity.json when a design has sign-in, permissions, roles or test users — the permission catalog every API operation is gated on.","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Fsecurity-design\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M735M60CTW4S7XMS6XCX9A7Y","resolve-dependency","Use for taking one external dependency from open to resolved — `\u002Fresolve-dependency \u003Cname> [answer]` names it and may carry the provider the user chose; `\u002Fresolve-dependencies` walks every open one in turn. Ask which provider (their suggestions as options; never choose for them), get its interface on disk (found, uploaded from the card, or assumed under the authorization the card records), then derive the config keys.","https:\u002F\u002Fgithub.com\u002Fwso2\u002Flabs-agentic-engineer\u002Fblob\u002Fmain\u002Fskills\u002Fresolve-dependency\u002FSKILL.md",[],[]]