What

Ships the CADS (CodeAI Design System) color ramp behind data-brand='codeai-next' without changing what legacy-brand users see, so the rebrand can be QA'd ahead of the cutover and enabled via the default-brand DCDO key (no deploy, instant rollback).

The CADS exports change the token schema, not just values: --borders-* → --border-*, the aqua/teal/purple brand families collapse into one brand family, ramp steps extra-light/light → light/mid, and disabled/selected/alpha families are new. Several primitive names (--brand-purple-50, --neutral-base-black, all grays/sentiments) exist in both schemas with different values, so the canonical files cannot load at :root before cutover.

How

New files in frontend/packages/component-library-styles/:

Supporting changes:

• Cdo::Brand + apps/src/util/brand.ts: new codeai-audit brand code (?brand=codeai-audit persists via the existing router). DSCO-coverage auditing moves there; ?brand=codeai-next now shows real CADS colors.
• MUI: CodeaiTheme gets the real CADS purple palette (#4C42CF/#928CEF/#3228B7); the hot-pink placeholder palette becomes CodeaiAuditTheme.
• Logo-layout selectors in dashboard/app/assets/stylesheets/application.scss and shared/css/user-menu.scss include codeai-audit.

CSS mechanics worth knowing when reviewing:

• :root and [data-brand='x'] tie at specificity (0,1,0); brand-scoped blocks carry :root/[data-theme] compounds to reach (0,2,0) and win independent of import order.
• Custom properties substitute var() chains on the element that declares them and inherit as resolved values, so the aliases/shim re-declare on [data-theme]-carrying elements — otherwise Lab2's nested data-theme='Dark' subtrees would inherit light-resolved values.

Which schema is the base, and what gets deleted later

A common first read of this PR is "it converts the new tokens back to the old structure" — it's actually the opposite in the scope that matters, and both directions exist on purpose, one per brand scope:

• Under codeai-next (the future default), the CADS schema is the base. brandCodeAiNext.css defines the new tokens natively; brandCodeAiNextAliases.css maps the old names onto them (--borders-brand-teal-primary: var(--border-brand-primary)). Old names are compatibility pointers into the new system, kept alive so unmigrated call sites are still rebranded on day one.
• Under the legacy brands (until cutover), the old schema is the base. brandLegacyShim.css maps the new names onto old values, only so code migrated early (or written fresh against CADS names) renders sensibly pre-cutover. This is the temporary half.

Planned rework is deletion plus a mechanical rename, not a redesign:

1. Call-site migration (~2,800 usages of legacy names): required in every possible approach; the bridge just detaches it from the launch date. By then it is a dumb find-and-replace — brandCodeAiNextAliases.css doubles as the codemod table, with every design decision (teal→brand, extra-light/light→light/mid, strawberry→pink) already encoded one line per token.
2. Cleanup: promote the two canonical *_codeAi.css files to :root, delete colors.css, primitiveColors.css, the shim, the aliases, the aggregator, and the generator. Total disposable artifact: ~350 lines of alias/shim CSS plus a 70-line script. (The pink audit file overrides old names today; at cleanup it gets rewritten against CADS names.)

Why not the inverse now (CADS at :root as the global base, legacy values mapped on top for pre-cutover): old→new is many-to-one (teal/purple/aqua primaries all map to the one brand family), so the shipped mapping is well-defined. The reverse is one-to-many — once a call site says --background-brand-primary, whether it "used to be" teal or purple is unrecoverable, so a legacy override would have to pick one and some surfaces would visibly change color before launch. It would also force the ~370-file rename immediately (conflicting with everything in flight) and turn rollback into a deploy instead of a DCDO flip. Same destination either way; this ordering puts the risky step after the deadline instead of before it.

Mapping decisions needing design sign-off

• Legacy aqua/teal/purple brand tokens all collapse onto the CADS brand family (pre-cutover teal and purple surfaces converge on CADS purple).
• Legacy background extra-light/light → CADS light/mid; hover → mid; strawberry → pink; --background-neutral-lab → --background-neutral-primary (legacy dark lab value #121212 equals CADS dark primary exactly).
• Same-name tokens whose meaning shifted cannot be aliased and follow the CADS definition: legacy --background-{sentiment}-light call sites move from a 20-level fill to a 5-level wash (the heavier step is now -mid; ~30 usages to revisit during call-site migration). CADS also defines light-mode --background-neutral-true-base as black (1 usage).

Examples:

Rollout

1. Merge: no visible change for legacy brands. QA via ?brand=codeai-next, audit via ?brand=codeai-audit.
2. Cutover: flip DCDO default-brand to codeai-next.
3. Cleanup: see checklist below.

Cleanup checklist (post-cutover — so we don't forget)

The CADS token names already work everywhere (natively under codeai-next, via the shim under legacy brands), so call sites can migrate any time — every migrated call site shrinks this list. Once both preconditions hold:

• the cutover has happened (default brand is on the CADS ramp), and
• a grep for legacy token names (--borders-, --background-brand-{teal,aqua,purple}-, --text-brand-{teal,aqua,purple}-, --accent-strawberry-, --text-neutral-inverse, --*-neutral-disabled, --background-neutral-lab, …) returns zero call sites,

the teardown is a small deletion PR — no rewrites or re-mapping, since the mapping knowledge is baked into the migrated call sites by then:

• Migrate call sites legacy→CADS names. Mechanical 1:1 rename for everything in brandCodeAiNextAliases.css (that file is the codemod table) — except ~30 usages of --background-{error,info,success,warning}-light, where the token kept its name but moved from a 20-level fill to a 5-level wash: each needs a human to choose -light vs -mid by intent.
• Add a stylelint rule banning legacy token names so the count only goes down (this can and should land before cutover, as soon as teams start migrating).
• Point the four style entry points (createReactRoot.tsx, code-studio.js, studio __root.tsx, markdown demo) at colors_codeAi.css + primitiveColors_codeAi.css — they are already written in :root form; that is why they were committed verbatim and the scoped copy is generated rather than hand-edited.
• Delete colors.css, primitiveColors.css, brandLegacyShim.css, brandCodeAiNext.css, brandCodeAiNextAliases.css, brandOverrides.css, and scripts/generateBrandCodeAiNext.mjs.
• Rewrite brandCodeAiAudit.css to override the CADS token names (it pinks the legacy names today; the audit brand outlives the bridge).
• Consolidate brand codes in Cdo::Brand / brand.ts (fold the CADS ramp into codeai or make codeai-next the plain default; drop the MUI theme split if only one real brand remains).

Testing

• Scripted coverage checks: all 107 legacy semantic + 129 legacy primitive tokens resolve under codeai-next; all 141 CADS tokens resolve under legacy brands; every var() reference resolves within its scope; codeai-audit keeps full parity with the pink block it replaced.
• Cascade simulation (models html + nested dark div per brand): 17 spot checks pass, incl. dark-subtree re-resolution and the alpha flip to white-alpha in dark.
• apps typecheck clean; brandTest.ts 11/11 (new codeai-audit cases); eslint/stylelint/prettier/rubocop clean; brand_test.rb extended.
• Not covered locally: real-browser pass over ?brand=codeai-next/?brand=codeai-audit and eyes baselines (default brand unchanged by construction, but please confirm on drone).

🤖 Generated with Claude Code