@pihanga2/shadcn 0.2.7 → 0.2.8

package/AGENT.building-cards.md

@@ -703,3 +703,121 @@ Rules:
 - `src/cards/BUILDING_CARDS_HOWTO.md` — human-oriented narrative version of this guide
 - `scripts/gen-card-dependencies.mjs` — dependency scanner
 - `scripts/gen-registry.mjs` — registry builder
+
+---
+
+## Theme-aware cards — working with CSS variables
+
+shadcn/ui components (and therefore pihanga-shadcn cards built on top of them)
+use **CSS custom properties** for all semantic colours, radii, and shadows.
+Understanding the token system is essential for cards that carry their own
+visual chrome (borders, backgrounds, elevation).
+
+### How the token system works
+
+`src/theme.css` (shipped as `@pihanga2/shadcn/theme.css`) defines three layers:
+
+| Layer | Purpose | Example |
+|---|---|---|
+| `:root { --card: oklch(...) }` | **Palette** — raw colour values | `--card`, `--border`, `--radius` |
+| `@theme inline { --color-card: var(--card) }` | **Tailwind mapping** — wires vars to utility classes | `bg-card`, `border-border`, `rounded-xl` |
+| `.dark { --card: oklch(...) }` | **Dark-mode overrides** | Same tokens, different values |
+
+A consumer who overrides `:root { --card: oklch(0.9 0 0); }` in their own CSS
+automatically rethemes every card that uses `bg-card` — no card code changes
+needed.
+
+### Using theme tokens in a new card
+
+**Prefer shadcn semantic tokens over hardcoded colours.** This makes the card
+rethemable by the consumer:
+
+```tsx
+// ✅ Rethemable — uses CSS variable tokens
+<div className="bg-card text-card-foreground border border-border rounded-xl shadow-sm">
+
+// ❌ Hard-wired — ignores consumer theme
+<div className="bg-white text-gray-900 border border-gray-200 rounded-xl shadow-sm">
+```
+
+Standard shadcn tokens available as Tailwind utilities:
+
+| Tailwind class | CSS variable | Default (light) |
+|---|---|---|
+| `bg-card` | `--card` | white |
+| `text-card-foreground` | `--card-foreground` | near-black |
+| `bg-background` | `--background` | white |
+| `text-foreground` | `--foreground` | near-black |
+| `bg-muted` | `--muted` | light gray |
+| `text-muted-foreground` | `--muted-foreground` | medium gray |
+| `bg-primary` | `--primary` | dark |
+| `text-primary-foreground` | `--primary-foreground` | near-white |
+| `border-border` | `--border` | light gray |
+| `rounded-xl` | `--radius-xl` = `--radius + 4px` | ~14px |
+| `rounded-lg` | `--radius-lg` = `--radius` | 10px |
+| `shadow-sm` | Tailwind built-in | subtle shadow |
+
+### Adding a new theme token for a card
+
+When a card needs a design token consumers can override (e.g. a brand-specific
+colour or radius), add it to **`src/theme.css`** following the same pattern:
+
+```css
+/* In src/theme.css — @theme inline block */
+@theme inline {
+  /* … existing tokens … */
+  --color-my-card-accent: var(--my-card-accent);
+}
+
+/* default in :root */
+:root {
+  --my-card-accent: oklch(0.5 0.2 260);   /* a blue */
+}
+```
+
+Then use `bg-my-card-accent` / `text-my-card-accent` in your component.
+Consumers override by setting `--my-card-accent` in their own `:root`.
+
+> **Do not** add tokens that are only useful for a single card to the global
+> `theme.css`.  For card-local defaults, prefer explicit Tailwind colour classes
+> or a `className` prop.
+
+### The `@container` gotcha with shadcn composites
+
+shadcn's `<CardHeader>` applies `@container/card-header`
+(`container-type: inline-size`).  CSS containment makes the element's
+intrinsic inline size appear as **0** to its parent for `min-width` / `max-content`
+calculations — your card will collapse to a tiny width if it relies on `min-w-max`.
+
+**Fix:** replace `<CardHeader>` with a plain `<div data-slot="card-header">` that
+carries the same Tailwind classes but without the `@container` prefix:
+
+```tsx
+// ❌ @container breaks min-w-max on the parent Card
+<CardHeader className={headerClassName}>
+
+// ✅ Same visual styles, no CSS containment
+<div
+  data-slot="card-header"
+  className={cn(
+    "grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6",
+    "has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6",
+    headerClassName,
+  )}
+>
+```
+
+This is safe because the `has-data-[slot=card-action]` selector is a CSS `:has()`
+rule, not a container query — it doesn't require `@container` to function.
+
+### Consumer setup (reminder)
+
+Cards in this library render correctly only when the consuming app's CSS
+includes `@import "@pihanga2/shadcn/theme.css"`.  That single import:
+
+1. Defines the CSS custom property palette (`:root`, `.dark`)
+2. Maps them to Tailwind v4 utility tokens (`@theme inline`)
+3. Tells Tailwind to scan the library's compiled files (`@source "."`)
+
+Apps that already use shadcn/ui with their own theme setup do not need the
+import — their `:root` variables cascade over the defaults.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pihanga2/shadcn",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Pihanga core card components built on shadcn/ui and Radix UI — the npm distribution of pihanga-shadcn.",
   "type": "module",
   "exports": {
@@ -179,6 +179,9 @@
     "./lib/utils": {
       "import": "./lib/utils.js",
       "types": "./lib/utils.d.ts"
+    },
+    "./theme": {
+      "import": "./theme.css"
     }
   },
   "sideEffects": [

package/theme.css

@@ -0,0 +1,102 @@
+/*
+ * pihanga-shadcn — theme.css
+ *
+ * Add ONE line to your app's main CSS (processed by Tailwind v4):
+ *
+ *   @import "tailwindcss";
+ *   @import "@pihanga2/shadcn/theme.css";
+ *
+ * The @source directive below tells Tailwind to scan this package's
+ * compiled JS files for utility class names, so you don't need a
+ * separate @source line in your own CSS.
+ *
+ * Skip the import if your app already has a shadcn/ui theme — your
+ * :root variables will take precedence over the defaults below.
+ */
+
+/* Scan this package's compiled files for Tailwind utility classes */
+@source ".";
+
+/* Map shadcn CSS vars to Tailwind v4 utility tokens */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-btn-brand: var(--primary);
+  --color-btn-brand-foreground: var(--primary-foreground);
+  --radius-btn-brand: var(--radius-md);
+}
+
+/* Light theme (shadcn neutral / new-york) */
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --radius: 0.625rem;
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+}
+
+/* Dark theme */
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+}