Admin Portal v2 theme tokens, plus two fixes to existing portal docs

[Wictorgirardi]

Summary

Companion to p2-inc/phasetwo-admin-portal#199, which replaces the portal's runtime CSS-class rewriting with a pared-down set of 13 CSS-variable theme tokens stored as _providerConfig.assets.portal.v2.<token> realm attributes. This documents the new tokens and, along the way, fixes two defects in the existing portal docs.

Fixes to existing docs

1. Published attribute keys that do not work. getting-started/customizing-ui.md listed the portal colors as _providerConfig.assets.portal.primary100, …primary200, and so on. The server reads primaryColor100, primaryColor200, … — the Color infix was missing from all nine keys, so every one of them was dead. Anyone who followed that table got no styling at all. Corrected against PortalResourceProvider.java.

2. A table that never rendered. The visibility-flag table in admin-portal/access-control.md had data rows but no header or delimiter row, so GFM rendered it as literal pipe-separated text rather than a table. Given a proper header.

New content

admin-portal/configuration.md

• Replaced "you can override three colors used in the portal" with the theme token documentation: how branding is applied at runtime, a 13-token table (token → CSS variable → default → notes), the precedence rule, and the accepted value formats.
• Documented the two dark-mode gotchas that are easy to trip over: the muted and border tokens have no effect in dark mode (those surfaces are mixed from darkBackground), and the foreground tokens fall back in two different ways — primaryForeground/ctaForeground/darkCtaForeground always auto-contrast, while foreground/darkForeground keep their defaults unless you set their background explicitly.
• Legacy colors section: the old attributes are still read, but only primaryColor700 (fallback for primary) and secondaryColor900 (fallback for cta) still affect rendering.
• Custom CSS section with an example, plus a :::caution breaking-change callout: CSS targeting the old generated utility classes (.bg-primary-700, .bg-primary-gradient, …) no longer applies, and realms that customized primaryColor100/primaryColor900 will see neutral surfaces until they set the matching v2 tokens.

admin-portal/access-control.md

• Added the org.attributes.enabled flag (new in add logos #199) and the profile.passwordless.enabled flag, which the server has always honored but was never documented anywhere.
• Added the Attributes RBAC line: view-organization to view, manage-organization to edit.
• Documented that the flag comparison is exact and case-sensitive — only the literal true enables a section; TRUE, 1 and yes disable it ("true".equals(v)).

getting-started/customizing-ui.md

• Rewrote the Admin Portal subsection with a v2 token table matching the neighbouring Login tables, the precedence rule, and a legacy table with the corrected key spellings.

[cloudflare-workers-and-pages]

Deploying phasetwo-docs with    Cloudflare Pages

Latest commit:	c709765
Status:	✅  Deploy successful!
Preview URL:	https://d33ee7c2.phasetwo-docs.pages.dev
Branch Preview URL:	https://feature-update-tokens-docs.phasetwo-docs.pages.dev

View logs

[pnzrr]

Marking as draft — the theme-token contract is still being finalized (shared _providerConfig.assets.theme.v2.* namespace, shadcn vocab, cta→primary). The token tables here will need updating to match before merge.

[pnzrr]

Pushed c709765, retargeting this to the contract that actually shipped. Rebased onto main first (it was 4 behind).

Why it changed

This PR documented assets.portal.v2.* as a portal-private namespace with a cta token. What shipped is the shared assets.theme.v2.*, consumed by the login theme, the Admin Portal and the email templates alike, with cta folded into primary. See keycloak-themes #100/#102/#103 (released 0.73–0.75) and phasetwo-admin-portal #199 (v0.60).

Documented once instead of twice

Both pages carried their own copy of the token table — which is exactly how the two had already drifted. The canonical list now lives in customizing-ui.md as the realm-attribute reference; admin-portal/configuration.md keeps the portal-specific parts (runtime injection, the sidebar derivation, the legacy portal keys) and links to it.

Corrections beyond the rename

• Missing tokens. secondary/secondaryForeground, mutedForeground, and the derived card, cardForeground, accent, accentForeground, input, ring weren't documented at all. Derived tokens follow a base token until set — that's what makes a lone custom primary also move the focus ring.
• Dark overrides. Every colour token takes a dark<Token>. The docs listed only four dark attributes.
• Two claims that are no longer true, both artefacts of the color-mix() implementation that per-mode tokens replaced: "No effect in dark mode" on muted/border, and "the other dark surfaces are mixed from it" on darkBackground.
• secondaryColor900 no longer affects rendering — it fed cta. Called out explicitly, since a realm that only ever customised it has to move to theme.v2.primary.
• login.primaryForegroundColor was listed as a working attribute with a #ffffff default. The legacy stylesheet never emitted a variable for it — AssetsResourceProvider emits exactly three --p2-login-* colours. It only takes effect through the token path, as the fallback for theme.v2.primaryForeground.
• "If omitted, the light-mode values are used as fallbacks" was only true of the brand colours. backgroundColor falls back to the dark default instead, or dark mode would stop being dark.
• The admin UI does now expose these fields — under Styles → Login, not Styles → Portal, because the tokens are shared rather than portal-specific.

Also notes the per-surface default divergence (portal primary #1570c2 and radius 0.5rem against the login palette) rather than implying one set of defaults, and that email alone doesn't fall back to resolved defaults — only explicitly-set tokens reach it, so unbranded email is unchanged.

Your two fixes from dc28ea6 are untouched: the missing Color infix in the nine portal keys, and the visibility table's absent header row.

Checks

Both cross-page anchors verified to resolve, and all tables verified column-consistent.

⚠️ pnpm build currently fails on this repo with Cannot mix different versions of joi schemas. This is pre-existing — I confirmed the unmodified branch fails identically — so it's a dependency/toolchain issue rather than anything in these changes, but it does mean Docusaurus' broken-link checking couldn't run. Worth a separate look.