chore(web): introduce shadow-depth hierarchy across surfaces #242

Merged

code-lead merged 1 commit from dev/235 into main

2026-04-21 13:25:59 +00:00

dev commented

2026-04-21 12:53:51 +00:00

Collaborator

Summary

Defines a 4-level shadow scale (none / subtle / lifted / overlay) in design/tokens.json and mirrors it into apps/web/src/styles/tokens.css as --ch-shadow-* CSS vars
Exposes the three custom tiers as Tailwind utilities (shadow-subtle, shadow-lifted, shadow-overlay) via @theme in index.css
Migrates all 8 legacy shadow-lg / shadow-sm call sites onto the correct tier (4× modals → shadow-overlay, 2× panels/toasts → shadow-lifted, 1× transcript bubble → shadow-subtle, 1× specs dialog → shadow-overlay)
Documents the hierarchy in apps/web/CLAUDE.md alongside the existing radius convention

Closes #235

## Summary - Defines a 4-level shadow scale (`none` / `subtle` / `lifted` / `overlay`) in `design/tokens.json` and mirrors it into `apps/web/src/styles/tokens.css` as `--ch-shadow-*` CSS vars - Exposes the three custom tiers as Tailwind utilities (`shadow-subtle`, `shadow-lifted`, `shadow-overlay`) via `@theme` in `index.css` - Migrates all 8 legacy `shadow-lg` / `shadow-sm` call sites onto the correct tier (4× modals → `shadow-overlay`, 2× panels/toasts → `shadow-lifted`, 1× transcript bubble → `shadow-subtle`, 1× specs dialog → `shadow-overlay`) - Documents the hierarchy in `apps/web/CLAUDE.md` alongside the existing radius convention Closes #235

dev added 1 commit

2026-04-21 12:53:52 +00:00

chore(web): introduce shadow-depth hierarchy across surfaces

qa / qa (pull_request) Has been cancelled

Details

qa / dockerfile (pull_request) Has been cancelled

Details

ab553d8aad

Defines a 4-level shadow scale (none / subtle / lifted / overlay) in
design/tokens.json and tokens.css, exposes it via @theme in index.css,
and migrates all 8 legacy shadow-lg / shadow-sm call sites onto the
correct tier. Documents the hierarchy in apps/web/CLAUDE.md.

Closes #235

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dev force-pushed dev/235 from ab553d8aad

qa / qa (pull_request) Has been cancelled

Details

qa / dockerfile (pull_request) Has been cancelled

Details

to 137636d78f

qa / qa (pull_request) Successful in 4m9s

Details

qa / dockerfile (pull_request) Successful in 8s

Details

2026-04-21 13:06:31 +00:00

Compare

dev requested review from reviewer

2026-04-21 13:23:35 +00:00

reviewer approved these changes

2026-04-21 13:25:32 +00:00

reviewer left a comment

Review — round 1

CI: ✅ green (run #1884, 4m18s)

Acceptance criteria

Criterion	Status
4-level scale in `design/tokens.json` (`none` / `subtle` / `lifted` / `overlay`)	✅
CSS vars mirrored in `tokens.css`	✅
Tailwind utilities exposed via `@theme` in `index.css` (`shadow-subtle`, `shadow-lifted`, `shadow-overlay`)	✅
All 8 legacy `shadow-lg` / `shadow-sm` call sites migrated	✅
Hierarchy documented in `apps/web/CLAUDE.md`	✅
No legacy shadow utilities remaining in components	✅

Token values

JSON ↔ CSS mirror is exact (the 0.30→0.3 formatting difference is semantically identical). Token values are placed in core (not theme-scoped), which is correct — rgb(0 0 0 / X) black shadows render well on both the dark (#1A1B26) and light (#E9ECF2) palettes without needing overrides.

Tier assignments

All 8 call sites got the right tier:

shadow-overlay — sessions delete dialog, issue-card edit dialog, agents editor dialog, agents delete dialog, specs new-spec modal (5× modals/dialogs ✅)
shadow-lifted — board side panel, toasts (2× clearly-above-page surfaces ✅)
shadow-subtle — transcript chat bubble (1× hoverable card ✅)

Tailwind v4 registration

--shadow-subtle/lifted/overlay under @theme is the correct Tailwind v4 pattern for registering custom shadow utilities. shadow-none correctly relies on the built-in.

Sweep completeness

Zero remaining shadow-lg / shadow-sm in apps/web/src/ — the CLAUDE.md prohibition is now backed by an empty grep.

LGTM. Straightforward, well-scoped chore.

## Review — round 1 **CI:** ✅ green (run #1884, 4m18s) ### Acceptance criteria | Criterion | Status | |---|---| | 4-level scale in `design/tokens.json` (`none` / `subtle` / `lifted` / `overlay`) | ✅ | | CSS vars mirrored in `tokens.css` | ✅ | | Tailwind utilities exposed via `@theme` in `index.css` (`shadow-subtle`, `shadow-lifted`, `shadow-overlay`) | ✅ | | All 8 legacy `shadow-lg` / `shadow-sm` call sites migrated | ✅ | | Hierarchy documented in `apps/web/CLAUDE.md` | ✅ | | No legacy shadow utilities remaining in components | ✅ | ### Token values JSON ↔ CSS mirror is exact (the `0.30`→`0.3` formatting difference is semantically identical). Token values are placed in `core` (not theme-scoped), which is correct — `rgb(0 0 0 / X)` black shadows render well on both the dark (#1A1B26) and light (#E9ECF2) palettes without needing overrides. ### Tier assignments All 8 call sites got the right tier: - **`shadow-overlay`** — sessions delete dialog, issue-card edit dialog, agents editor dialog, agents delete dialog, specs new-spec modal (5× modals/dialogs ✅) - **`shadow-lifted`** — board side panel, toasts (2× clearly-above-page surfaces ✅) - **`shadow-subtle`** — transcript chat bubble (1× hoverable card ✅) ### Tailwind v4 registration `--shadow-subtle/lifted/overlay` under `@theme` is the correct Tailwind v4 pattern for registering custom shadow utilities. `shadow-none` correctly relies on the built-in. ### Sweep completeness Zero remaining `shadow-lg` / `shadow-sm` in `apps/web/src/` — the CLAUDE.md prohibition is now backed by an empty grep. LGTM. Straightforward, well-scoped chore.