docs: document removal of the 1.5.0 theme bridge workaround

[interacsean]

Closes tailor-inc/platform-planning#1646

Why

Apps that adopted the 1.5.0-era workaround — pasting the @theme inline block, @custom-variant dark (&:is(.dark *)), and a copy of the palette into their entry CSS while styles was missing the bridge — keep those definitions winning on 1.6+. AppShell imports its palette inside layer(theme.defaults) (theme.css:24) and consumer CSS is unlayered, so the stale copy beats it regardless of specificity or source order.

Nothing warns. The build succeeds, and dark mode breaks silently: surfaces added to AppShell since the copy was made have no dark value at all, so they render light-mode colours in dark mode — white text on white cards, unreadable disabled inputs. The reporter needed a full investigation to trace the symptoms back to their own 1.5.0-era CSS, and expects other projects that took the same workaround to be sitting on it.

There was no migration or upgrade documentation anywhere in docs/, so this had to be written rather than amended.

What changed

docs/concepts/styling-theming.md

• New Overriding tokens and cascade layers — AppShell's palette lives in a cascade layer, so consumer declarations win by design (that's what makes :root { --radius: … } work without !important). Documents the flip side: a partial palette copy silently pins whatever it defines while everything else tracks AppShell, and the two halves drift apart on upgrade. Two rules: override only the tokens you mean to, and mirror every :root override in .dark.
• New Upgrading from 1.5.x: remove the theme bridge workaround — the three failure modes (unlayered palette, missing dark values on newer surfaces, :is(.dark *) vs :where(.dark, .dark *)), a grep to detect it, an explicit delete list, before/after entry CSS, and the reporter's own measured values as a verification check (--card #fff → #171717, --input #e5e5e5 → rgba(255,255,255,.15), --destructive #dc2626 → #f87171).
• Warning and anchor link near the top so an upgrader hits it on the first screen.
• Drive-by: the palette example had @import "tailwindcss" last and a duplicated styles line, contradicting the example above it.

catalogue/src/fundamental/design-system.md (§1, §2 — source of the app-shell-patterns skill shipped in the npm package)

• Stops telling apps to import @tailor-platform/app-shell/theme.css, a deprecated no-op shim since 1.6.0.
• Dark mode documented as the .dark class, not [data-theme="dark"] — AppShell never sets that attribute.
• Override example uses tokens that actually exist (--primary, --background), set in both modes.

Plus a patch changeset, since the catalogue edit changes files distributed in the package (files: skills/**).

Notes for the reviewer

• examples/vite-app/src/index.css is already correct and is cited in the docs as the reference shape — no example app changes were needed.
• §4 of design-system.md is deliberately untouched. Its token table (--color-surface-1, --color-fg-default, --space-*, …) documents a token set app-shell has never shipped, so agents reading the bundled skill emit bg-surface-1 / text-fg-muted classes that silently resolve to nothing. That's already tracked as tailor-inc/platform-planning#1647, whose fix is mechanical generation of the table plus a CI drift check — out of scope here. This PR does incidentally close two of that ticket's four bullets (§1's theme.css import, the [data-theme="dark"] claim).
• The issue's "emit a build-time warning" ask is not implemented. It would mean scanning consumer CSS from @tailor-platform/app-shell-vite-plugin, which is opt-in, routing-focused, and reaches no Next.js consumer — poor coverage for real complexity, and it only fires on a rebuild when the people at risk have already upgraded. The reporter offered the documented-detection fallback themselves (「または検出手順をドキュメント化する」); that's the grep recipe above.

Verification

pnpm type-check (9 tasks), pnpm lint (0 warnings / 0 errors), pnpm test (76 files, 1430 tests), pnpm fmt — all pass. Regenerated the skill via catalogue/scripts/generate-skill.mjs and confirmed the output reflects the edits; check-generated-skills.mjs passes. No runtime code changed, so there's nothing to verify in a browser.

🤖 Generated with Claude Code

[interacsean]

/review

[github-actions]

✅ API Design Review completed successfully!

API Design Review: no in-scope files changed. All 3 changed files are documentation or changeset (.changeset/gentle-moons-repeat.md, catalogue/src/fundamental/design-system.md, docs/concepts/styling-theming.md). No packages/**/*.ts, packages/**/*.tsx, or packages/**/package.json files were modified — review scope does not apply to this PR.

[interacsean]

/review

[github-actions]

✅ API Design Review completed successfully!

PR #432 is documentation-only. No packages//*.ts, packages//*.tsx, or packages/**/package.json files were changed. API design review has nothing to evaluate — no issues found.