feat(skills): pin the Astryx design system on every web application

skills/AGENTS.md

@@ -32,7 +32,8 @@ An absent kind means `org`, which is a real decision, not a default to lean on:
   narration policy, and the coding run's own workflow skills (`aep`,
   `aep-validation`, `playwright-cli`).
 - **`org`** — the org-visible stack skills (`go`, `ballerina`, `react-webapp`,
-  `api-management`, `thunder-authentication`). Editable and deletable by an org.
+  `astryx-design-system`, `api-management`, `thunder-authentication`). Editable
+  and deletable by an org.
 
 Kind decides console visibility and who may edit a skill, and nothing else. It is
 `audience` that decides who may *read* one, and the two are independent — a skill
@@ -67,6 +68,58 @@ never loaded to author specs/", and `ballerina`'s says "Apply when a component's
 "Conventions for writing Go applications" names no trigger and is a defect — that
 one was `go`'s, and it was invisible for as long as `go` was preloaded regardless.
 
+## Swapping the UI design system
+
+A web app's UI toolkit is an **organization** decision, and nothing in this
+library hardcodes one. Two edits change it, both in places an org may edit:
+
+1. Add the new design-system skill — author `skills/<name>/SKILL.md`, or import
+   it through Settings → Skills. Delete `astryx-design-system` if the org does
+   not want it available.
+2. Point the **UI design system** section of `organization` at its name.
+
+`architecture` reads the name out of that section rather than holding one of its
+own. It can, because the `organization` body rides the design agent's system
+prompt on **every** turn (`buildOrgDefaultsBlock` in the agents service, not a
+per-flow eager skill), so the name is always in context when a component's
+`design.json` is written. It then pins that skill on every `web-application`, so
+the pin follows the org's choice with **no platform-skill edit** —
+`architecture` is `kind: platform` and read-only in the console, which is exactly
+why the name cannot live there. An empty section means web-app builds carry only
+the stack skills. `astryx-design-system` is the shipped default, nothing more.
+
+A design-system skill must declare four things to work in that slot:
+
+- **`metadata.aep.kind: org` and `metadata.aep.audience: [coding]`.** A design
+  system is built against, not designed with; `[coding]` is what puts it in the
+  project mirror, and `org` is what lets an org edit or delete it.
+- **A `## Verify` section** naming the one command `react-webapp`'s verify
+  sequence should run for it, or nothing if it has none.
+- **Which of its own defaults the platform overrides.** Every vendor's
+  quickstart assumes a project it scaffolded itself; `react-webapp`'s deployment
+  facts (no `base`, the platform's own nginx assets, `window._env_`, one
+  `tsconfig.json`) win, and
+  the skill should say so wherever its own docs would mislead.
+- **Its ownership boundary.** The design system owns UI under `src/`; the data
+  layer (`openapi-fetch` + the committed `src/generated/` client) stays
+  `react-webapp`'s.
+
+Only `organization` and the design-system skill itself may name a design system.
+A vendor name anywhere else in this library is a defect — it is the thing that
+would make a swap need more than the two edits above. That includes
+`references/*.md`: a mirror copies a skill's whole directory, so a vendor name in
+a reference reaches a coding session exactly as a body would. Check it before
+changing a web-app skill:
+
+```bash
+grep -rniE 'astryx|@astryxdesign' skills/ --include='*.md'
+```
+
+Only `skills/organization/SKILL.md`, `skills/astryx-design-system/**` and this
+file should match. A hit anywhere else — especially in `architecture`, which is
+`kind: platform` and read-only in the console — means an org can no longer swap
+its design system without a platform change.
+
 ## Who owns what
 
 - **`aep` is the umbrella**, and it is split by reader. `SKILL.md` is the **run**

skills/architecture/SKILL.md

@@ -41,7 +41,14 @@ component's build actually needs as a `skillsPinned` array **inside that
 component's `specs/design/components/<name>/design.json`** — use the exact
 catalog names, e.g. a Ballerina API service →
 `["openapi-conventions", "ballerina"]` (a Go one → `["openapi-conventions",
-"go"]`); a web-application → `["wireframes", "react-webapp"]`. Add
+"go"]`); a web-application → `["wireframes", "react-webapp", <design system>]`,
+where `<design system>` is the skill name in the **UI design system** section of
+the Organization defaults block in your instructions. A web app's UI toolkit is
+a settled organization decision, so pin it on **every** web-application rather
+than leaving it to a description to trigger — and read the name from that
+section every time instead of remembering one, because it differs per
+organization. If that section is absent or empty, pin only the two stack skills.
+Never substitute a design system the organization defaults do not name. Add
 `"api-management"` to any service that sits behind the gateway, and
 `"thunder-authentication"` to **both** sides of sign-in — the SPA *and* every
 protected backend it calls, since that skill owns how each resolves the caller's
@@ -121,12 +128,17 @@ violations:
   "exposure": "internet",             // "internet" (public) | "intranet" (internal only)
   "dependencies": [ /* see below — every arrow in Interactions appears here */ ],
   "description": "One paragraph: single responsibility, port/entrypoint expectations, and what it explicitly does NOT do.",
+  "stories": [1, 2, 4],               // PRD story numbers THIS component serves — the build gate refuses the tag while any story is claimed by nobody
+  "skillsPinned": ["openapi-conventions", "ballerina"], // the skills this component's build needs — see the field above
   "endpoint": { "name": "http" } // optional; see below
 }
 ```
 
 `name`, `type`, `version`, `language`, `buildpack`, `appPath`, `entrypoint`,
-`exposure`, `description`, and `dependencies` are required. To CHANGE a
+`exposure`, `description`, `dependencies`, `stories` and `skillsPinned` are
+required — `stories` and `skillsPinned` are as required as the rest, and a
+component missing either fails the build gate, so emit them in the SAME write
+rather than as a follow-up edit. To CHANGE a
 design.json, re-emit the whole corrected file (removeFile + addFile) — never
 patch JSON with anchored edits. On INVALID_JSON or SCHEMA_VIOLATION, fix what
 the message lists and re-emit.
@@ -142,12 +154,11 @@ into `workload.yaml` and the managed-API gateway binds to. The port lives in
 - **Preserved verbatim** where the platform has already written them:
   `exposesAPI`, `componentAgentInstructions`, and any dependency
   `status`/`reason`.
-- **Recomputed and overwritten** on every save: a dependency's `wiring` object,
-  and the component's `stories` array — the platform restamps it from the
-  design.cell citations, so cite stories in the CELL, never here.
+- **Recomputed and overwritten** on every save: a dependency's `wiring` object.
   The platform derives its `ref` and its env-var names from the dependency's name
   and its resource type's declared outputs, so anything you write there is
-  discarded.
+  discarded. `stories` is NOT in this class — it is yours to author, per the
+  **stories** field above.
 
 ### dependencies — one entry per Interactions arrow
 

skills/astryx-design-system/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: astryx-design-system
+description: Astryx (`@astryxdesign/core`) — the platform's default web-app design system, its Theme + StyleX wiring, and the CLI you confirm every component's props against before writing JSX. Apply to all UI work in a `web-application` component that pins this skill — pages, layouts, forms, tables, dialogs, nav, theming — even when the task never names Astryx.
+metadata:
+  aep:
+    kind: org
+    audience: [coding]
+---
+
+# Astryx Design System
+
+You are reading this because the component you are building pinned it, which
+means 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.
+
+`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:
+
+```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 <App/> in <Theme theme={neutralTheme}> — swap the theme package to change
+// the look, never hand-roll colors instead
+```
+
+## 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 `<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)
+
+| If you're about to build… | Use instead |
+|---|---|
+| Page shell with top bar + side nav | `AppShell`, `TopNav`, `SideNav`, `MobileNav` |
+| A data table / list view | `Table`, `List` + `Item`, `MetadataList` |
+| A form with grouped fields | `FormLayout`, `Field`, `FieldStatus` |
+| A select / combobox / tag input | `Selector`, `MultiSelector`, `ComplexSelector`, `Typeahead`, `Tokenizer` |
+| A modal / confirmation dialog | `Dialog`, `AlertDialog` |
+| A dropdown / context / command menu | `DropdownMenu`, `ContextMenu`, `MoreMenu`, `CommandPalette` |
+| Status / count / label chip | `Badge`, `StatusDot`, `Token`, `Indicator` |
+| Tooltip / hover detail / anchored popup | `Tooltip`, `HoverCard`, `Popover` |
+| Date/time entry | `DateInput`, `DateRangeInput`, `DateTimeInput`, `TimeInput`, `Calendar` |
+| Loading / empty state | `Skeleton`, `Spinner`, `ProgressBar`, `EmptyState` |
+| Breadcrumbs / global search | `Breadcrumbs`, `PowerSearch` |
+| Toggle / choice input | `Switch`, `CheckboxInput`, `CheckboxList`, `RadioList`, `SegmentedControl`, `ToggleButton` |
+
+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
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Astryx components render unstyled/unthemed | `reset.css`/theme 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`) |
+| `npm install` fails / peer-dependency warnings on React | `package.json` is on React <19 | Set `react`/`react-dom` to `^19` before installing `@astryxdesign/core` |
+| Build succeeds but StyleX classes/styles don't apply | `astryxStylex()` missing from `vite.config.ts`, or ordered after `react()` | Add `...astryxStylex()` to `plugins`, listed before `react()` |
+| 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`) |
+| A prop doesn't exist, or is the old spelling | Answered from memory instead of the CLI | Run `npx --no astryx component <Name> --dense` — the CLI reflects the installed version, training data doesn't |
+| 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`/`List`+`Item`; `Card` is for widgets/galleries/settings groups |
+
+## 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`
+
+All of these mean: stop, run `astryx search` / `astryx component <Name> --dense`,
+and use what it returns.

skills/organization/SKILL.md

@@ -25,3 +25,19 @@ Thunder is available as a dependency.
 
 - Web apps: TypeScript + React, single-page app.
 - Services and APIs: Ballerina.
+
+## UI design system
+
+`astryx-design-system`
+
+That is the name of a skill in this library, and it is the single authority for
+this organization's web-app UI — components, layout, styling, theming, and the
+verification step a web-app build owes it. **This section is a pointer, not a
+specification:** what the design system requires is stated in that skill and is
+never restated here, so the two can never disagree.
+
+To adopt a different design system, change the name above and make sure a skill
+by that name exists (see "Swapping the UI design system" in `skills/AGENTS.md`).
+Those are the only edits — nothing else in the library names a design system.
+Leave this section empty to run with no design system at all; web-app builds
+then carry only the stack skills.