@design.estate/dees-catalog

Theme Token Migration (bdTheme → --dees-* tokens)

Status: WS1 in progress — vocabulary approved 2026-06-12. Decisions: (1) the three text tokens below were added to 00theme.ts; (2) shadow tokens are theme-aware (themeDefaults.shadowsDark); (3) consolidation mapping approved as listed; (4) the post-consolidation unique tail uses :host([gobright]) (goBright reflects as an attribute since @design.estate/dees-element 2.3.0) instead of remaining on bdTheme.

Goal: zero cssManager.bdTheme() call sites in ts_web outside ts_web/elements/00theme.ts. 00theme.ts is the single sanctioned bridge — the --dees-* tokens are themselves implemented via bdTheme() there, so the runtime theme-switch mechanism does not change. Components only ever consume var(--dees-*).

Inventory (2026-06-12)

• 1,651 bdTheme() call sites across 129 files (demos included): 1,622 single-line literal (clustered below), 22 multi-line literal (handled like any literal during sweeps), 7 with dynamic arguments
• 546 distinct (light, dark) pairs after color normalization
• 91 pairs / 397 sites match an existing token exactly or within Δ≤6 per RGB channel (visual no-op)
• 7 pairs / 50 sites look like flipped arguments (light/dark swapped) — see "Suspected bugs"
• 432 pairs / 1,155 sites need consolidation (mostly zinc/gray/slate/ad-hoc palette generations expressing the same semantics) — see mapping table
• 16 pairs / 20 sites are non-color values (shadows, borders shorthand, gradients, filters)
• Dynamic-argument calls live in only 3 components: dees-progressbar (3), dees-spinner (2), dees-searchbar (2)

Analysis tooling: tsx .nogit/debug/analyze-bdtheme.ts regenerates .nogit/debug/bdtheme-analysis.json (full cluster → file data) and the ratchet baseline counts.

Approved vocabulary additions (in 00theme.ts since 2026-06-12)

New color tokens in IThemeColors / themeDefaultStyles — values taken from the dominant existing usage, so adopting them is a visual no-op at those sites:

Token	Light	Dark	Replaces (sites)
--dees-color-text-success	hsl(142.1 76.2% 36.3%)	hsl(142.1 70.6% 45.3%)	green-600/500 pairs (~13)
--dees-color-text-error	#dc2626	#f87171	red-600/400 pairs (~10)
--dees-color-text-warning	hsl(38 92% 45%)	hsl(38 92% 55%)	amber pairs (~4)

Shadow tokens become theme-aware (today they are static; found usage consistently wants stronger shadows in dark mode). Light values unchanged:

Token	Light (unchanged)	Dark (new)
--dees-shadow-xs	0 1px 2px 0 rgb(0 0 0 / 0.05)	0 1px 2px 0 rgb(0 0 0 / 0.2)
--dees-shadow-sm	0 1px 3px rgba(0, 0, 0, 0.1)	0 1px 3px rgba(0, 0, 0, 0.3)
--dees-shadow-md	0 2px 8px rgba(0, 0, 0, 0.15)	0 2px 8px rgba(0, 0, 0, 0.35)
--dees-shadow-lg	0 4px 12px rgba(0, 0, 0, 0.15)	0 4px 12px rgba(0, 0, 0, 0.4)

Mechanism for the post-consolidation tail (genuinely component-unique theme pairs, e.g. terminal/chart palettes): goBright reflects as the gobright attribute since @design.estate/dees-element 2.3.0, so such sites use plain :host([gobright]) { ... } CSS for component-local light/dark styling without bdTheme and without growing the global vocabulary (rule R6).

Migration rules (precedence order)

1. R1 — exact/near token match (Δ≤6/channel on both light and dark): replace with the token. Visual no-op.
2. R2 — semantic consolidation: palette-generation duplicates (zinc/gray/slate/ad-hoc) map to the canonical token for their role (see table). Small intentional shifts: blue-tinted grays become neutral grays. Pick the token by role (text vs border vs surface), not by raw distance.
3. R3 — alpha tints of a semantic color: color-mix(in srgb, var(--dees-color-X) N%, transparent) instead of a dedicated pair.
4. R4 — flipped arguments: confirm against rendered output, then fix to the token (these are bugs — the light theme currently shows dark-theme values). Never "preserve" a flip by mapping it to swapped tokens, except intentional inverted-contrast UI (tooltips already have --dees-color-tooltip-*).
5. R5 — non-color values: shadows → --dees-shadow-*; spacing/radius/transition literals → their scales when the value matches; composite values (gradients, checkerboards) → compose from color tokens inside the gradient.
6. R6 — genuinely unique pairs (after R1–R5, expected rare): component-local :host([gobright]) CSS (dark value as default, bright override).

00colors.ts (legacy constants, 10 files) is retired during sweeps: blue/blueActive → accent/link tokens per role (note: #0050b9 → #3b82f6 is a visible shift, check each site), text → text tokens.

Consolidation mapping (clusters ≥7 sites; tail follows the same role rules)

Sites	Pair (light | dark)	→ Token	Shift
45	#09090b | #fafafa	--dees-color-text-primary	none
27	hsl(0 0% 89.8%) | hsl(0 0% 14.9%)	--dees-color-border-default	none
25	#71717a | #a1a1aa	--dees-color-text-muted	dark dims slightly
25	#e5e7eb | #27272a	--dees-color-border-default	none
24	hsl(215.3 25% 8.8%) | hsl(210 40% 98%)	--dees-color-text-primary	blue-gray → neutral
24	#e5e7eb | #374151	--dees-color-border-default	dark border darkens (wysiwyg blocks)
23	#3b82f6 | #60a5fa	--dees-color-link	none
22	hsl(215.4 16.3% 56.9%) | hsl(215 20.2% 55.1%)	--dees-color-text-muted	blue-gray → neutral
19	#3b82f6 | #3b82f6	--dees-color-accent-primary	none
19	#666 | #999	--dees-color-text-muted	minor
18	hsl(210 40% 96.1%) | hsl(215 20.2% 16.8%)	--dees-color-badge-default-bg	near none (secondary surface)
18	hsl(215.4 16.3% 46.9%) | hsl(215 20.2% 65.1%)	--dees-color-text-muted	dark dims
18	hsl(210 20% 98%) | hsl(215 27.9% 16.9%)	--dees-color-badge-default-bg	slate → neutral (datepicker family)
16	#71717a | #71717a	--dees-color-text-muted	becomes theme-aware (improvement)
16	#9ca3af | #6b7280	--dees-color-text-muted	light darkens (placeholders)
15	hsl(222.2 47.4% 51.2%) | hsl(217.2 91.2% 59.8%)	--dees-color-accent-primary	light brightens
15	hsl(0 0% 95.1%) | hsl(0 0% 14.9%)	--dees-color-badge-default-bg	near none
14	hsl(220 8.9% 46.1%) | hsl(215 20.2% 65.1%)	--dees-color-text-muted	dark dims
13	#18181b | #fff	--dees-color-tooltip-bg	near none
13	#000000 | #ffffff	per-site: usually text-primary	manual (R4 check: some intentional pure contrast)
13	hsl(0 0% 45.1%) | hsl(0 0% 63.9%)	--dees-color-text-muted	dark dims slightly
13	#374151 | #e5e7eb	per-site: text-secondary or text-primary	manual (emphasized text, dark value sits between tokens)
13	hsl(215 16% 45%) | hsl(215 16% 75%)	--dees-color-text-secondary	dark dims
12	#6b7280 | #9ca3af	--dees-color-text-muted	minor
11	#71717a | #888	--dees-color-text-muted	minor
11	#111827 | #f9fafb	--dees-color-text-primary	near none
10	#dc2626 | #f87171	--dees-color-text-error (new)	none
10	#ffffff | #000000	per-site (inverse surfaces)	manual
10	#a1a1aa | #666	per-site (storage-browser family)	manual, flip-suspect
10	#333 | #fff	--dees-color-text-primary	light deepens
10	hsl(214.3 31.8% 91.4%) | hsl(217.2 32.6% 17.5%)	--dees-color-border-default	slate → neutral
10	hsl(0 0% 50%) | hsl(0 0% 60%)	--dees-color-text-muted	minor
9	#e5e7eb | #3f3f46	--dees-color-border-default	dark darkens
9	hsl(0 0% 88%) | hsl(0 0% 20%)	--dees-color-border-default	minor
9	#d1d9e0 | #30363d	--dees-color-border-default	github palette → neutral (markdownoutlet)
8	hsl(142.1 76.2% 36.3%) | hsl(142.1 70.6% 45.3%)	--dees-color-text-success (new)	none
8	#e5e7eb | #333	--dees-color-border-default	minor
8	hsl(0 0% 20%) | hsl(0 0% 90%)	per-site: text-secondary/text-primary	manual
8	hsl(224 71.4% 4.1%) | hsl(210 20% 98%)	--dees-color-text-primary	near none
8	hsl(0 0% 95%) | hsl(0 0% 9%)	--dees-color-code-block-bg	near none
7	#999 | #666	--dees-color-text-muted	faint/disabled text, both shift
7	hsl(222.2 47.4% 51.2% / 0.1) | hsl(217.2 91.2% 59.8% / 0.1)	color-mix(accent-primary 10%) (R3)	near none
7	hsl(0 0% 100%) | hsl(224 71.4% 4.1%)	--dees-color-bg-primary	none
7	hsl(0 72.2% 50.6%) | hsl(0 62.8% 30.6%)	--dees-color-accent-error	dark brightens (destructive buttons) — review
7	hsl(215.3 25% 26.7%) | hsl(217.9 10.6% 74.9%)	--dees-color-text-secondary	dark dims
7	#d1d5db | #4b5563	--dees-color-border-strong	dark darkens

Suspected bugs (flipped light/dark arguments — fix via R4 during sweeps)

Sites	Pair (light | dark)	Looks like	Files
23	hsl(0 0% 9%) | hsl(0 0% 95%)	code-block-bg flipped	chart-log demo, table demo (terminal panels — verify: may be intentional always-dark panels; if so, use literal dark values, not a flip)
12	hsl(0 0% 15%) | hsl(0 0% 90%)	border-default flipped	dataview-statusobject, input-checkbox
9	hsl(0 0% 63.9%) | hsl(0 0% 45.1%)	text-secondary flipped	dropdown, statusobject
6	#333 | #ccc	border-strong flipped	profiledropdown, pagination
3	#a1a1aa | #404040	badge-default-fg flipped	storage-browser
3	hsl(0 0% 15%) | hsl(0 0% 93.9%)	badge-default-bg flipped	input-richtext, input-text
3	hsl(142.1 70.6% 45.3%) | hsl(142.1 76.2% 36.3%)	text-success flipped	(locate during sweep)
2	#262626 | #e5e5e5	border-default flipped	appui-mainmenu, simple-appdash

Sweep order (WS1, after vocabulary approval)

1. Add approved tokens to 00theme.ts (+ IThemeColors), release.
2. The 49 files currently using both systems (finish what's started; fastest surface reduction).
3. 00group-input + form infrastructure (incl. datepicker slate re-skin)
4. 00group-dataview (table styles.ts, storage-browser family incl. flip-suspects)
5. 00group-overlay, 00group-layout
6. 00group-appui, 00group-simple
7. 00group-chart, 00group-media, 00group-workspace, remaining groups + demos
8. Dynamic-call components (progressbar, spinner, searchbar) — restructure their color props to accept tokens/CSS values rather than light/dark pairs.

Per sweep: pnpm build, pnpm test, wcctools demo screenshots in both themes (before/after), node scripts/check-bdtheme-ratchet.cjs --update-baseline, focused commit per group.

Ratchet

scripts/check-bdtheme-ratchet.cjs (runs first in pnpm test):

• counts bdTheme( occurrences per file under ts_web/, excluding ts_web/elements/00theme.ts
• fails if any file exceeds its count in scripts/bdtheme-baseline.json, or if a file not in the baseline uses bdTheme at all
• --update-baseline rewrites the baseline after a sweep (counts may only shrink; the script refuses to raise them)