Skip to content

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

Open
Wictorgirardi wants to merge 1 commit into
mainfrom
feature/update-tokens-docs
Open

Admin Portal v2 theme tokens, plus two fixes to existing portal docs#344
Wictorgirardi wants to merge 1 commit into
mainfrom
feature/update-tokens-docs

Conversation

@Wictorgirardi

@Wictorgirardi Wictorgirardi commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

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.

@Wictorgirardi
Wictorgirardi requested a review from pnzrr July 24, 2026 20:47
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying phasetwo-docs with  Cloudflare Pages  Cloudflare Pages

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

View logs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant