Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit ce7b7ec

Browse files
Sam Altmanclaude
andauthored
docs(console-architecture): point Branding at the effective theme tokens (#7012)
The Branding section's closing sentence named only the `--brand-*` group, which is a backward-compat alias: `useAppShellBranding` writes it, nothing in this repo reads it, and no Tailwind utility is wired to it. The brand colour is actually carried by the Shadcn theme tokens the same hook writes (`--primary` / `--primary-foreground` / `--ring` / `--sidebar-primary` / `--sidebar-ring`, `--accent` / `--accent-foreground`), which reach rendered output through the Tailwind 4 `@theme` block in `packages/components/src/index.css`. The new copy states that mechanism and describes the `--brand-*` names as the alias they are, without promising removal or permanence. It also records that the alias does not follow the light/dark toggle while the theme tokens do. No properties removed and `AppShell.tsx` untouched: CSS custom properties are consumed by definition from outside this repo, so an in-repo grep cannot see the consumers that would make removal safe. Claude-Session: https://claude.ai/code/session_013hfmP9hoMd3dJwTh85J4yB Co-authored-by: Claude <noreply@anthropic.com>
1 parent b458300 commit ce7b7ec

2 files changed

Lines changed: 56 additions & 1 deletion

File tree

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
---
3+
4+
Documentation-only: `content/docs/guide/console-architecture.md`'s Branding section now points
5+
readers at the tokens branding actually acts through, instead of at the backward-compat alias.
6+
7+
The section's one closing sentence read "This sets CSS custom properties (`--brand-primary`,
8+
`--brand-primary-hsl`, etc.) on the document root" — naming only the `--brand-*` group. That
9+
group is an alias: `useAppShellBranding` writes it, nothing in this repository reads it, and no
10+
Tailwind utility is wired to it. The properties that make a brand colour visible are the Shadcn
11+
theme tokens the same hook writes — `--primary` / `--primary-foreground` / `--ring` /
12+
`--sidebar-primary` / `--sidebar-ring` from `primaryColor`, and `--accent` /
13+
`--accent-foreground` from `accentColor` — which reach rendered output through the Tailwind 4
14+
`@theme` block in `packages/components/src/index.css` (`--color-primary: hsl(var(--primary))`
15+
and siblings), and that is what generates the `bg-primary`, `text-primary-foreground`,
16+
`bg-accent` and `ring-ring` utilities the components already use. A reader following the old
17+
sentence would customize against a name nothing guarantees.
18+
19+
The new copy states the mechanism, then describes the `--brand-*` group as what it is: a
20+
backward-compatibility alias. It also records a difference the old sentence hid — `--brand-*`
21+
carries the authored hex and its light-mode HSL triple and does not follow the light/dark
22+
toggle, while `--primary` / `--accent` carry the mode-adjusted value — so the two are not
23+
interchangeable for anyone theming against them.
24+
25+
Deliberately **not** done here: the four alias properties are not removed and
26+
`packages/layout/src/AppShell.tsx` is not touched. CSS custom properties are consumed by
27+
definition from outside this repository — a customer stylesheet can write `var(--brand-primary)`
28+
directly — so the in-repo grep that found zero readers is structurally incapable of seeing the
29+
consumers that would make removal safe, and zero in-repo hits does not license deletion.
30+
Retiring them needs a measurement that reaches outside this repo (a release-surface
31+
announcement, a deprecation window, a survey of customer stylesheets); that is a separate card.
32+
The prose therefore neither promises removal nor promises permanence, matching the hedge the
33+
source comment already carries.
34+
35+
Every token name and the `@theme` consumption path were checked against
36+
`packages/layout/src/AppShell.tsx` and `packages/components/src/index.css`. No published
37+
behaviour changes and no package source was touched.

‎content/docs/guide/console-architecture.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,25 @@ Per-app branding is applied via `AppShell`'s `branding` prop:
197197
}}>
198198
```
199199

200-
This sets CSS custom properties (`--brand-primary`, `--brand-primary-hsl`, etc.) on the document root.
200+
This writes CSS custom properties on the document root (`html`), and re-applies them whenever
201+
the `.dark` class on that element changes, so the brand stays readable across the theme toggle.
202+
203+
**Branding acts through the Shadcn theme tokens.** `primaryColor` sets `--primary`,
204+
`--primary-foreground`, `--ring`, `--sidebar-primary` and `--sidebar-ring`; `accentColor` sets
205+
`--accent` and `--accent-foreground`. They reach rendered output through the Tailwind 4 `@theme`
206+
block in `packages/components/src/index.css`, which maps each one to a colour token
207+
(`--color-primary: hsl(var(--primary))`, `--color-accent: hsl(var(--accent))`, and so on) — and
208+
that is what generates the `bg-primary`, `text-primary-foreground`, `bg-accent` and `ring-ring`
209+
utilities the components already use. Overriding the token is therefore the whole mechanism:
210+
every existing consumer picks up the brand colour without a single component change.
211+
212+
`AppShell` also writes `--brand-primary`, `--brand-primary-hsl`, `--brand-accent` and
213+
`--brand-accent-hsl`. These are **backward-compatibility aliases, not the branding surface** —
214+
no utility is wired to them, and nothing in this repository reads them. They are not
215+
interchangeable with the tokens above either: `--brand-*` carries the authored hex and its
216+
light-mode HSL triple and does not follow the light/dark toggle, whereas `--primary` /
217+
`--accent` carry the mode-adjusted value. Theme against the Shadcn tokens; treat the
218+
`--brand-*` names as an alias kept for whatever already consumes it.
201219

202220
## Development Mode
203221

0 commit comments

Comments
 (0)