From 848eab27dff16cc517ddaa851e4510460e4e44e4 Mon Sep 17 00:00:00 2001 From: Khalid Abdi Date: Wed, 3 Jun 2026 19:10:54 +0300 Subject: [PATCH] Docs: record COSS composition gotchas, theme toggle, token usage Update frontend/CLAUDE.md after the COSS migration: note the sidebar theme toggle and the always-use-semantic-tokens rule in Theming, add a 'COSS composition gotchas' section (MenuGroup requirement, DialogPanel padding, no Card/Avatar size prop, destructive variant, items-start Field, aliases, ai-elements drift), and dedupe the repeated lucide-react note. Co-Authored-By: Claude Opus 4.8 --- frontend/CLAUDE.md | 39 +++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md index 7c83076..dff7749 100644 --- a/frontend/CLAUDE.md +++ b/frontend/CLAUDE.md @@ -91,10 +91,16 @@ Tailwind v4 with `@theme inline` in `app/globals.css`, using **COSS's default ne (`@coss/colors-neutral`; values reference Tailwind palette vars like `--color-neutral-*` plus `--alpha()`/`color-mix()`). Both **light (`:root`) and dark (`.dark`)** palettes are defined; `next-themes` (`components/theme-provider.tsx`) toggles them with **`defaultTheme="dark"`** + -`enableSystem`, so the app still defaults to dark. Fonts follow the COSS variable contract -(`--font-sans`, `--font-heading` = Inter; `--font-mono` = Geist Mono). The radius scale -(`rounded-2xl` … `rounded-4xl`) is derived from `--radius`, so those utilities are larger than stock -Tailwind. +`enableSystem`, so the app still defaults to dark. The **theme toggle** is the _Theme_ item in the +sidebar-footer user menu (`components/sidebar-02/nav-user.tsx`, via `useTheme()`). Fonts follow the +COSS variable contract (`--font-sans`, `--font-heading` = Inter; `--font-mono` = Geist Mono). The +radius scale (`rounded-2xl` … `rounded-4xl`) is derived from `--radius`, so those utilities are +larger than stock Tailwind. + +**Always use semantic tokens** (`bg-muted`, `bg-input`, `border-border`, `text-muted-foreground`, +…), never hardcoded `oklch`/hex colors — the latter break the light theme. Dark surface tokens are +subtle alphas (`--muted`/`--secondary`/`--accent` ≈ white/4%, `--input` ≈ white/8%, `--border` ≈ +white/6%), so layered surfaces stay close in lightness. ## i18n @@ -117,8 +123,29 @@ converted as the reference pattern; other strings can be migrated incrementally. `next build`. There's a `Dockerfile` for the standalone build. - **`lucide-react@1.17` dropped brand glyphs** (e.g. `Github`, `Discord`) — import them and you get a build error. Use inline SVGs instead. -- **`lucide-react@1.17` dropped brand glyphs** (e.g. `Github`, `Discord`) — import them and you get - a build error. Use inline SVGs instead. - A sibling **`../landing-page/`** directory is a copy of this app with a marketing landing page (`components/landing/`); it is a separate project, not part of this git repo. - Multiple lockfiles in the tree produce a harmless Turbopack "inferred workspace root" warning. + +### COSS composition gotchas (hit during the shadcn→COSS migration) + +- **`MenuGroupLabel` must live inside `` (or ``)** — there is no standalone + `MenuLabel`. Using it bare throws `MenuGroupContext is missing` at runtime. +- **`DialogPopup`/`SheetPopup` have no inner padding** — padding comes from + `DialogHeader`/`DialogPanel`/`DialogFooter`. For a form dialog: keep the header outside the form, + wrap **panel + footer** in `
`, and put the body in `DialogPanel` + (see `components/chat/patient-form-dialog.tsx`). Content placed directly in the popup is flush. +- **`Card` has no `size` prop** and **`Avatar` has no `size` prop**. For compact cards, override the + section padding via data-slot selectors (`compactCard` in `patient-cards.tsx`); for avatars use a + `size-*` class. +- **Solid destructive buttons:** use `variant="destructive"`, not the default variant + a `bg-*` + override — the default variant keeps `border-primary`, which is near-white in dark mode. +- **COSS `Field` is `items-start`** (children don't stretch). Add `w-full` to buttons/rows meant to + fill the field. There is **no `FieldGroup`** (use a flex column) and **no `InputGroupButton`** + (use `Button`). +- COSS keeps back-compat aliases (`DialogContent`, `CardContent` → `CardPanel`, `SelectContent`, + `TooltipContent`, `PopoverContent`, `SheetContent`), so old imports still resolve — but prefer the + canonical `*Popup`/`*Panel` names in new/edited code. +- The vendored `ai-elements/*` were repointed to COSS (live `conversation`/`message` fully migrated; + dormant files via aliased imports). Their remaining `tsc` errors are **pre-existing Base UI drift**, + not regressions — they stay behind `ignoreBuildErrors`.