feat(theme): adopt @aziontech/webkit and migrate to its design tokens

[isaque-bock-azion]

What

Sixth PR in the docs modernization stack (base: #2318). Installs @aziontech/webkit@4.3.0 + @aziontech/theme@4.3.0 and migrates every component off the legacy azion-theme design system, which is removed.

How the new design system works

Worth knowing before reviewing: the tokens are not in @aziontech/webkit — they live in the sibling @aziontech/theme (webkit depends on it). It publishes a single dist/v4/globals.css that registers the entire scale as native Tailwind v4 @theme tokens plus ready-made @utility classes (bg-surface, text-muted, border-default, …). There is no preset, plugin, or config step.

Consequence: tailwind.config.cjs is deleted. What it still carried moved into main.css as CSS-first equivalents — class-based dark mode became @custom-variant dark (&:where(.dark, .dark *)), and the mono font became a two-line @theme block. Its custom color scale and breakpoints are now the theme's own; the three max-w-xl xxxl:max-w-xxl layout sites moved to the theme scale (max-w-5xl 2xl:max-w-6xl, i.e. 1200→1192px and 1600→1536px — approximate by design).

Token mapping

Applied across 31 files (class usages) and every var() reference:

Legacy	New
--text-color / -secondary	--text-default / --text-muted
--text-color-link(-hover)	--text-link(-hover)
--surface-hover	--bg-hover
--surface-border	--border-default
--surface-section / --surface-0	--bg-surface
--surface-card / --surface-50	--bg-surface-raised
--surface-ground	--bg-canvas
--surface-200	--bg-selected
--primary-text-color	--primary-contrast
--secondary-button-*	--secondary / --secondary-contrast
--p-tag-*	--success / --warning / --danger (+ -contrast)

The @utility surface-* / text-color* block added during the primeflex removal (#2317) is gone — those are the theme's own utilities now.

All PrimeVue-era .p-* class names are also gone. They were styled by azion-theme's SCSS, so leaving them would have rendered those components unstyled; they were rebuilt with the theme's tokens/utilities following webkit's own styling rules. Zero hardcoded hex remains. Three orphaned vendored stylesheets are deleted and the survivor is renamed to src/styles/base.css, since it is now just base resets and font-family helpers.

Three real bugs found and fixed

• The site is now theme-aware through tokens alone. The dark: variants and the text-white/bg-header classes on the header, footer and body are gone. bg-header/border-header/bg-header-button-hover had been dead since the azion-webkit removal (they came from its v3 config and generate no CSS) — which left the header forcing white text on a light background in the light theme. Verified against the previous build's CSS that this predates the PR.
• Dark-theme sidebar was invisible. @aziontech/theme sets no color on body, so the document fell back to the browser default (black) and anything relying on inheritance — the entire left sidebar nav — disappeared in dark mode. base.css now sets color: var(--text-default).
• not-prose on LinkButton/HeroButton/CardBaseClickable. Their label color was being overridden by ReadableContent's prose-a:* utilities. This repo imports Tailwind in important mode, so those land as !important inside @layer utilities — and for !important declarations the cascade inverts layer order, meaning a layered !important beats an unlayered one regardless of specificity. The component's scoped style could never win. not-prose is the typography plugin's own opt-out and the only reliable fix. Note this also means the earlier specificity-based attempt at this same bug (in feat(components): remove azion-webkit, port all components locally with Tailwind #2316) never actually worked.

Also adds vue-demi: true to pnpm-workspace.yaml allowBuilds — it arrives via @aziontech/webkit → @vueuse/core, and pnpm 11 fails the install without an explicit decision (this would have broken CI).

Verification

• pnpm run build:local: 1494 pages, no errors. Confirmed the semantic utilities actually compile into the output CSS (worth checking, since the theme ships its own Tailwind entry point).
• Exercised in the browser against an astro preview production build, in both themes: theme switcher, left sidebar (#FAFAFA dark / #141414 light), TOC, breadcrumb, header buttons, content Tag badges, secondary LinkButtons, and the Algolia search dialog (panel/cards on the new surface tokens, real results, closes on Escape) — zero console errors.

Needs a design sign-off

severity="secondary" LinkButtons — the "Get Started" / "View details" buttons, 1179 usages in content — change from a subtle dark grey to a solid white button in the dark theme. That is the design system's intent (--secondary is an inverted high-contrast button, and @aziontech/webkit's own Button maps its secondary kind to exactly these tokens), but it is by far the most visible change in this PR.

Two smaller intentional deviations, both documented in code:

• Tag severity="info" keeps the neutral surface look rather than the theme's blue info status color — it is the severity used by ~390 content badges ("Preview", "Compute", "Static"), which read as labels, not alerts.
• SystemStatus's status-dot colors stay as literal hex: they mirror status.azion.com's severity palette, the theme's raw color primitives are pruned from the runtime output, and there is no semantic token for "maintenance".

Follow-up (not in this PR)

No @aziontech/webkit component is imported yet — this PR adopts the token layer only, keeping our own components as agreed. Swapping suitable local components (Button, Tag, Divider, Breadcrumb…) for webkit's own is the natural next step.

🤖 Generated with Claude Code