nxdns/specs/milestone-23.md

Milestone 23: StyleX and React Aria replace Tailwind

Goal: every styled element in web/src renders through StyleX (@stylexjs/unplugin at build time); Dialog, AlertDialog, Tabs and Select come from react-aria-components; Tailwind is removed. TanStack Router and TanStack Query stay (decided 2026-08-12 after review; the router swap is out of scope permanently, not deferred).

Design written 2026-08-12 against HEAD 91a0aa9. Needs milestone 22 landed (the StyleX and RAC .d.ts surfaces are checked by the TS7 tsc -b).

Inventory this spec rests on: 522 className= occurrences across 31 web/src files; 17 shared class constants in web/src/ui/classes.ts; web/src/styles.css is the single line @import "tailwindcss" (so dark mode is Tailwind 4's default prefers-color-scheme media strategy — no class toggle exists); the Tailwind plugin sits at web/vite.config.ts:3,8; tailwindcss and @tailwindcss/vite are devDependencies (web/package.json:34,44) and appear in neither the runtime closure nor the bundled set of licenses/dependency-identity.txt.

Implementation contract (read first)

• Read AGENTS.md, then this spec whole, before session work starts.
• web/src/lib/contractSamples.gen.ts and web/src/lib/types.ts are API contract surfaces; this milestone is styling-only and touches neither.
• Every session leaves all gates green: npm run format:check, npm run lint, npm run typecheck, npm test, npm run build, npm run assert-bundled (from web/), and zig build test. The release gate (zig build dist + verify-dist, .gitea/workflows/gates.yml) keeps its byte budgets; they are not tight — web/dist is 440,924 bytes raw against the 15 MiB binary budget — but verify-dist remains the arbiter.
• assert-bundled fails whenever the bundled npm package set changes. That failure is the license workflow trigger, not an obstacle: review each new package into licenses/inventory.zon, then record the new set in licenses/dependency-identity.txt (procedure in that file's header). Never update the recorded list without the inventory review.

Rulings (binding)

1. Build integration is @stylexjs/unplugin, proven before any page moves

stylex.vite() from @stylexjs/unplugin goes into web/vite.config.ts alongside the existing plugins (Tailwind stays until S3). Configuration per the official Vite guide (stylexjs.com/docs/learn/installation/vite): useCSSLayers: true, runtimeInjection: false, dev keyed off the Vite mode. The generated CSS injects into an existing CSS asset, so web/src/styles.css (imported by main.tsx:8) remains the CSS entry for the whole milestone; the dev/HMR virtual-module wiring from that guide is part of S1. The unmaintained community vite-plugin-stylex is forbidden. S1's acceptance proves dev server, vitest run and vite build all handle a StyleX component before S2 or S3 convert anything — this is a gate, not an assumption.

2. Tokens live in web/src/ui/tokens.stylex.ts

stylex.defineVars with role names, not raw shades: surface, surface-raised, border, border-strong, text, text-muted (the zinc ramp today), primary and primary-text (blue-600/white), danger, danger-surface, danger-border (the red ramp), focus (blue-600). Each var carries its dark value under @media (prefers-color-scheme: dark) inside defineVars — same media strategy the app has now. No theme toggle, no data-theme attribute.

3. web/src/ui/styles.ts replaces ui/classes.ts

The 17 exports of web/src/ui/classes.ts (focusRing, insetFocusRing, input, smallInput, button, smallButton, largeButton, primaryButton, largePrimaryButton, rowButton, linkButton, dangerLinkButton, retryButton, th, td, tableWrap, formCard) become stylex.create style objects in web/src/ui/styles.ts, composed at call sites via {...stylex.props(styles.button, extra)}. The milestone-9 accessibility floor restated by milestone-18 ruling 10 carries over verbatim: every interactive element renders the focus ring (:focus-visible outline, 2px, offset 2, focus token; the inset variant for controls flush against panel edges). ui/classes.ts is deleted in S3 when its last importer converts.

4. React Aria scope is exactly four components — end state, not a phase

From react-aria-components: Dialog + Modal (replacing the hand-rolled role="dialog" overlay in web/src/features/clients/ClientEditDialog.tsx:27-28), AlertDialog composition (ruling 5), Tabs (replacing the button-pair tab switcher in web/src/features/local/LocalDnsPage.tsx), Select (replacing the 7 files carrying native <select>: LookupPage, QueryLogPage, RecordsTab, RulesPage, SettingsPage, PrefixesEditor, ClientEditDialog). Everything else — buttons, text inputs, tables, links, banners — stays native HTML styled with StyleX. A native styled <button> is the finished design, not an interim one. S2 wraps the four as shared components: web/src/ui/Dialog.tsx, web/src/ui/ConfirmDialog.tsx, web/src/ui/Tabs.tsx, web/src/ui/Select.tsx, each styled with StyleX through RAC's render-prop state booleans (stylex.props(isSelected && styles.selected)) — never data-attribute selectors, which StyleX cannot express.

5. window.confirm dies with the conversion

All call sites become ConfirmDialog (RAC AlertDialog: role="alertdialog", focus trapped, danger-styled confirm button): web/src/features/blocklists/BlocklistsPage.tsx:61, web/src/features/upstreams/UpstreamsPage.tsx:43, web/src/features/rules/RulesPage.tsx:34, and web/src/ui/useCrudForm.ts:49 (which carries the confirm for ZonesTab and RecordsTab). useCrudForm's CrudFormSpec.confirmDelete keeps its signature; the hook returns the dialog state instead of calling window.confirm. The tests that stub confirm today (web/src/features/upstreams/UpstreamsPage.test.tsx:140,144,188, web/src/ui/useCrudForm.test.tsx:102) are rewritten to drive the real dialog: open, assert role="alertdialog" and the entity name in the message, confirm and cancel paths both asserted. BlocklistsPage and RulesPage gain the same coverage for their delete paths.

6. Styling mechanics

stylex.create/stylex.props only. Conditions are boolean-guarded style objects; variants are separate named styles; responsive behavior (the md: sidebar grid in web/src/shell/AppShell.tsx:90-98, the mobile drawer) becomes @media conditions inside style values. No dynamic class-name strings, no clsx-style helpers, no className literals left anywhere in web/src after S3 — className/style attributes appear only as the spread of stylex.props(...) (RAC render-prop className functions included). TanStack Link activeProps/inactiveProps (AppShell.tsx:35-42) pass stylex.props(...).className outputs.

7. Visual contract: drift accepted, structure pinned

No pixel parity requirement and no visual-regression harness. Pinned instead, checkable by reading the converted file against the original: same layout structure (grid/flex relationships, table columns, heading levels), token roles per ruling 2 (zinc surfaces, blue primary actions, red danger), the focus floor of ruling 3 on every interactive element, dark mode via media query, overflow-x-auto table wrappers preserved.

8. License inventory, named per step

• S1 adds @stylexjs/stylex (runtime dependency; stylex.props ships in the bundle) to the runtime closure and the bundled set. @stylexjs/unplugin is a devDependency — runtime closure and bundled set untouched by it.
• S2 adds react-aria-components and its transitive closure (@react-aria/*, @react-stately/*, @react-types/*, @internationalized/*, @swc/helpers — the exact bundled subset is whatever npm run assert-bundled reports after S2's conversions; every reported name gets a reviewed licenses/inventory.zon entry before the recorded list moves). This is the milestone's largest review surface.
• S3 removes nothing from the license files: Tailwind was dev-only and never recorded. The @tanstack/* entries stay untouched.

9. PLAN.md wording moves in S3

PLAN.md:138 "Vite + React + TypeScript + Tailwind; TanStack Router + TanStack Query" → "Vite + React + TypeScript + StyleX + React Aria; TanStack Router + TanStack Query". PLAN.md:235 directory comment updates the same way. Line 562 names loaders and Query only — untouched. No other PLAN amendment.

10. Conversion order is ascending className count, one commit per file

So a regression bisects to one page. Counts at spec time:

file	count
lib/InlineError.tsx	2
features/settings/ReadOnlyConfigBanner.tsx	2
features/dashboard/HealthBanners.tsx	2
features/local/LocalDnsPage.tsx	3
features/settings/RestartBanner.tsx	3
features/dashboard/StatCards.tsx	5
routes.tsx	6
auth/LoginPage.tsx	9
features/dashboard/DashboardPage.tsx	9
features/groups/GroupSourcesEditor.tsx	9
features/pause/PauseWidget.tsx	9
features/blocklists/BlocklistForm.tsx	11
features/clients/ClientEditDialog.tsx	11
features/dashboard/DiskCard.tsx	13
features/upstreams/UpstreamForm.tsx	14
features/clients/PrefixesEditor.tsx	15
shell/AppShell.tsx	17
features/live/LiveLogPage.tsx	18
features/dashboard/TimeseriesChart.tsx	21
features/dashboard/UpstreamHealthTable.tsx	21
features/upstreams/UpstreamsPage.tsx	21
features/groups/GroupsPage.tsx	22
features/lookup/LookupPage.tsx	25
features/local/ZonesTab.tsx	26
features/blocklists/SourceStatusSection.tsx	27
features/clients/ClientsPage.tsx	28
features/rules/RulesPage.tsx	31
features/blocklists/BlocklistsPage.tsx	31
features/settings/SettingsPage.tsx	31
features/local/RecordsTab.tsx	34
features/queries/QueryLogPage.tsx	46

S2 takes its owned cluster out of this order (converted together because the RAC wrappers land there); S3 walks the remainder smallest-first.

11. Tests that must change, known in advance

RAC changes DOM and focus behavior; these edits are expected work, not regressions to paper over:

• Dialog: ClientsPage.test.tsx (ClientEditDialog now portals into an RAC Modal; queries move to within(screen.getByRole("dialog"))).
• Tabs: LocalDnsPage.test.tsx (tab switcher becomes role="tablist"/ role="tab"; getByRole("button", { name: ... }) queries move to getByRole("tab", ...)).
• AlertDialog: UpstreamsPage.test.tsx, useCrudForm.test.tsx per ruling 5.
• Select: RAC Select renders a button + listbox, not <select>, so getByLabelText(...) + fireEvent.change patterns break in the tests for the 7 Select files (LookupPage, QueryLogPage, LocalDnsPage/RecordsTab, RulesPage, SettingsPage, ClientsPage). They move to userEvent-style open-then-select interactions. All other tests query by role/text and are expected to survive; a test that asserted a Tailwind class is rewritten against role or accessible name.

Sessions

Three sessions, strictly sequential: S1 → S2 → S3. (S2 and S3 both write web/package.json and the license files; the RAC wrappers S3 consumes are built in S2.)

Session S1: StyleX foundation, proven end to end

Owns: web/package.json, web/package-lock.json, web/vite.config.ts, web/src/styles.css, web/src/ui/tokens.stylex.ts (new), web/src/ui/styles.ts (new), web/src/ui/styles.test.tsx (new), licenses/inventory.zon, licenses/dependency-identity.txt.

• S1.1 add @stylexjs/stylex (dependency) and @stylexjs/unplugin (devDependency), exact pins; wire stylex.vite() per ruling 1. Tailwind plugin stays.
• S1.2 tokens per ruling 2; shared styles per ruling 3. ui/classes.ts is not deleted yet — both vocabularies coexist until S3.
• S1.3 styles.test.tsx: render a probe component using stylex.props(styles.button) under vitest; assert a non-empty className lands on the element (proves the transform runs in the test pipeline, since runtimeInjection is off).
• S1.4 license entries per ruling 8.

Acceptance (S1):

• npm run dev serves a probe page where a StyleX rule visibly applies and edits hot-reload (checked by hand, result recorded).
• npm test passes including styles.test.tsx.
• npm run build emits StyleX CSS into the web/dist assets; the built index.html page renders with the probe styled.
• npm run assert-bundled passes with @stylexjs/stylex in the recorded set; zig build test passes (drift guard agrees).
• All remaining gates green.

Session S2: React Aria primitives and their cluster

Owns: web/package.json, web/package-lock.json, web/src/ui/Dialog.tsx (new), web/src/ui/ConfirmDialog.tsx (new), web/src/ui/Tabs.tsx (new), web/src/ui/Select.tsx (new), web/src/ui/useCrudForm.ts, web/src/ui/useCrudForm.test.tsx, web/src/features/clients/*, web/src/features/local/*, web/src/features/upstreams/*, web/src/features/blocklists/BlocklistsPage.tsx and its test, web/src/features/rules/RulesPage.tsx and its test, licenses/inventory.zon, licenses/dependency-identity.txt.

• S2.1 add react-aria-components, exact pin; build the four wrappers per ruling 4, styled with tokens and ui/styles.ts.
• S2.2 convert the owned cluster fully to StyleX while adopting the wrappers: ClientEditDialog + PrefixesEditor + ClientsPage (Dialog, Select); LocalDnsPage + ZonesTab + RecordsTab (Tabs, Select, ConfirmDialog via useCrudForm); UpstreamsPage + UpstreamForm, BlocklistsPage, RulesPage (ConfirmDialog, Select). No className literal survives in an owned file.
• S2.3 window.confirm removal and test rewrites per rulings 5 and 11.
• S2.4 license review per ruling 8 — every package assert-bundled names.

Acceptance (S2):

• grep -rn 'window.confirm' web/src → only hits, if any, are in files S3 owns (expected: none; ruling 5 call sites all live in S2 files).
• Delete flows on upstreams, blocklists, rules, zones and records drive a role="alertdialog" element; confirm and cancel both covered by tests.
• Tabs on /local-dns expose role="tablist"; keyboard arrow keys move between tabs (asserted in LocalDnsPage.test.tsx).
• No className= literal in S2-owned files (grep -c 'className="' <file> = 0; stylex.props spreads excepted).
• assert-bundled passes with the RAC closure recorded; zig build test passes.
• All remaining gates green.

Session S3: the sweep and the removal

Owns: every web/src file not owned by S1/S2 that carries className= (the ruling-10 remainder: InlineError, ReadOnlyConfigBanner, HealthBanners, RestartBanner, StatCards, routes.tsx, LoginPage, DashboardPage, GroupSourcesEditor, GroupsPage, PauseWidget, BlocklistForm, SourceStatusSection, DiskCard, AppShell, LiveLogPage, TimeseriesChart, UpstreamHealthTable, LookupPage, QueryLogPage, SettingsPage) plus their tests, web/src/ui/classes.ts (delete), web/package.json, web/package-lock.json, web/vite.config.ts, web/src/styles.css, PLAN.md.

• S3.1 convert the remainder smallest-first per ruling 10, one commit per file, gates green at every commit.
• S3.2 delete ui/classes.ts when its import count reaches zero.
• S3.3 remove Tailwind: drop tailwindcss and @tailwindcss/vite from package.json, the plugin from vite.config.ts:3,8, and the @import "tailwindcss" line from styles.css (the file itself stays as the StyleX CSS entry per ruling 1).
• S3.4 PLAN.md per ruling 9.

Acceptance (S3):

• grep -rn 'className="' web/src returns zero matches; grep -rn 'tailwind' web matches nothing outside package-lock.json history (i.e. no source, config or dependency reference).
• ui/classes.ts is gone; nothing imports it.
• Dark scheme still follows prefers-color-scheme (vitest: token var resolves differently under a mocked dark media query, or a recorded manual check in both schemes).
• PLAN.md:138 and :235 name StyleX + React Aria; git diff PLAN.md touches nothing else.
• All gates green, including zig build dist + zig build verify-dist with -Dweb-dist=web/dist (run once at milestone end).

Orchestrator

Verify S1 acceptance (the ruling-1 gate) before S2 starts; S2 before S3. After S3: full gate set, then a live smoke — zig build a server with the fresh web/dist, click through every page in light and dark scheme, exercise one delete confirm and the local-dns tabs. Record deviations in ## Recorded (implementation).

Module layout

New files:

• web/src/ui/tokens.stylex.ts — the design tokens (ruling 2).
• web/src/ui/styles.ts — the shared style vocabulary (ruling 3).
• web/src/ui/styles.test.tsx — the transform-pipeline probe (S1.3).
• web/src/ui/Dialog.tsx, web/src/ui/ConfirmDialog.tsx, web/src/ui/Tabs.tsx, web/src/ui/Select.tsx — the RAC wrappers (ruling 4).

Deleted surface: web/src/ui/classes.ts; the window.confirm calls; the Tailwind dependency pair and its vite plugin line and CSS import.

Acceptance (milestone complete)

• All session boxes above.
• Zero Tailwind: no dependency, no plugin, no @import, no utility className literal in web/src.
• RAC appears in exactly four wrapper files plus their consumers; no other react-aria-components import (grep -rln 'react-aria-components' web/src ⊆ the four wrappers).
• Focus ring visible via keyboard on every interactive element of every page (spot-checked live, recorded).
• licenses/dependency-identity.txt, licenses/inventory.zon and the bundled reality agree (assert-bundled and zig build test both green).
• web/src/lib/types.ts and web/src/lib/contractSamples.gen.ts are byte-identical to HEAD.

Anti-requirements

• No router or query changes: TanStack Router and TanStack Query stay, untouched. That decision is closed.
• No RAC beyond Dialog, AlertDialog, Tabs, Select — no RAC Button, TextField, Table, Menu, Popover, DatePicker. Native elements styled with StyleX are the end state.
• No runtime style injection (runtimeInjection: false stays), no CSS-in-JS at runtime, no styled-components-like patterns.
• No dynamic class-name assembly, no clsx/classnames dependency, no Tailwind-compatibility shim.
• No theme toggle, no data-theme, no stored preference — media-query dark mode only, as today.
• No redesign: layout structure is pinned by ruling 7. Drift in shades and spacing is accepted; new page structures are not.
• No visual-regression harness, no screenshot tooling.
• No edits to web/src/lib/types.ts, web/src/lib/contractSamples.gen.ts, web/src/lib/api.ts, or anything under src/ (the Zig tree).
• No vite-plugin-stylex (unmaintained community plugin).