@vadimcomanescu/nadicode-design-system 2.0.0

package/.agents/skills/seed/references/tokens.md

@@ -0,0 +1,279 @@
+# Tokens Reference
+
+## Architecture
+
+```
+tokens.config.js  -->  index.css  -->  tailwind.config.js
+   (master JS)       (CSS vars)       (Tailwind theme)
+```
+
+1. **`src/lib/tokens.config.js`** -- Pure JS, exports `colorScales`, `colorTokens`, `tokens`
+2. **`src/index.css`** -- Maps tokens to CSS custom properties on `:root` (light) and `:root.dark`
+3. **`tailwind.config.js`** -- Imports tokens, extends Tailwind with CSS variable references
+4. **`src/tokens.ts`** -- Re-exports with TypeScript types for component code
+
+In consumer apps, the package ships the baseline tokens stylesheet as `@vadimcomanescu/nadicode-design-system/tokens.css`. Consumers import `@vadimcomanescu/nadicode-design-system/tokens.css` plus `seed-palette.css` in their `globals.css`.
+
+Normal brand customization does **not** happen in the package token pipeline. Consumers should edit `seed-palette.css` instead of changing `tokens.config.js` or the package tokens stylesheet.
+
+**CSS Variable Format:** Space-separated RGB values (NOT hex).
+```css
+/* CORRECT */  --color-background: 15 17 20;
+/* WRONG */    --color-background: #0F1114;
+```
+This enables Tailwind opacity modifiers: `bg-background/50` -> `rgb(15 17 20 / 0.5)`
+
+---
+
+## 12-Step Radix Color Scales
+
+Steps usage: 1-2 backgrounds, 3-5 component bg/hover/active, 6-8 borders/separators, 9-10 solid fills, 11-12 high-contrast text.
+
+### Gray
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `#0F1114` | `#FBFCFD` |
+| 2 | `#151719` | `#F5F7F9` |
+| 3 | `#1C1F23` | `#EDF0F3` |
+| 4 | `#232730` | `#E4E8EC` |
+| 5 | `#2B2F37` | `#D9DFE5` |
+| 6 | `#33383F` | `#CDD4DC` |
+| 7 | `#3E4550` | `#B5BECA` |
+| 8 | `#505A68` | `#97A3B2` |
+| 9 | `#6B7A8A` | `#6B7A8A` |
+| 10 | `#8494A7` | `#566878` |
+| 11 | `#A0AEBB` | `#3E4F60` |
+| 12 | `#E1E7ED` | `#1A2230` |
+
+### Gray Alpha
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `rgba(200,220,240, 0.02)` | `rgba(0,30,60, 0.02)` |
+| 2 | `rgba(200,220,240, 0.04)` | `rgba(0,30,60, 0.04)` |
+| 3 | `rgba(200,220,240, 0.06)` | `rgba(0,30,60, 0.07)` |
+| 4 | `rgba(200,220,240, 0.09)` | `rgba(0,30,60, 0.11)` |
+| 5 | `rgba(200,220,240, 0.12)` | `rgba(0,30,60, 0.15)` |
+| 6 | `rgba(200,220,240, 0.16)` | `rgba(0,30,60, 0.20)` |
+| 7 | `rgba(200,220,240, 0.22)` | `rgba(0,30,60, 0.29)` |
+| 8 | `rgba(200,220,240, 0.32)` | `rgba(0,30,60, 0.41)` |
+| 9 | `rgba(200,220,240, 0.45)` | `rgba(0,30,60, 0.58)` |
+| 10 | `rgba(200,220,240, 0.58)` | `rgba(0,30,60, 0.66)` |
+| 11 | `rgba(200,220,240, 0.72)` | `rgba(0,30,60, 0.76)` |
+| 12 | `rgba(200,220,240, 0.93)` | `rgba(0,30,60, 0.90)` |
+
+### Teal (Accent)
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `#0B1615` | `#F0FDFC` |
+| 2 | `#0F1F1E` | `#E3FAF8` |
+| 3 | `#122B29` | `#C8F3EF` |
+| 4 | `#163834` | `#A8E9E2` |
+| 5 | `#1B4542` | `#85DBD4` |
+| 6 | `#21554F` | `#5DC9C0` |
+| 7 | `#2A6D66` | `#35B2A8` |
+| 8 | `#35917F` | `#22958D` |
+| 9 | `#38BDB8` | `#1A8F88` |
+| 10 | `#4ECEC8` | `#147A73` |
+| 11 | `#7EDCD6` | `#0F6660` |
+| 12 | `#C2F0ED` | `#08403D` |
+
+### Red (Destructive)
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `#191113` | `#FFF5F5` |
+| 2 | `#201316` | `#FFE8E8` |
+| 3 | `#3B1219` | `#FECDD4` |
+| 4 | `#50141D` | `#FDAFB7` |
+| 5 | `#661823` | `#FA8F9A` |
+| 6 | `#7E1F2D` | `#F16C78` |
+| 7 | `#9E2B3A` | `#E34D5B` |
+| 8 | `#C73A4B` | `#CE3644` |
+| 9 | `#E5484D` | `#CE2C3B` |
+| 10 | `#EB5E5E` | `#B82535` |
+| 11 | `#F39090` | `#9C1E2E` |
+| 12 | `#FAD1D4` | `#5C111A` |
+
+### Green (Success)
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `#0D1512` | `#F2FDF6` |
+| 2 | `#111C17` | `#E3FAEC` |
+| 3 | `#13291F` | `#C2F2D6` |
+| 4 | `#163727` | `#9DE8BC` |
+| 5 | `#1A4530` | `#76D9A0` |
+| 6 | `#1F563A` | `#4EC785` |
+| 7 | `#266E48` | `#30B26B` |
+| 8 | `#2F8E5A` | `#1D9B55` |
+| 9 | `#3DD68C` | `#1B9450` |
+| 10 | `#5CE4A0` | `#147C42` |
+| 11 | `#8CEDB8` | `#0F6636` |
+| 12 | `#C8F5DD` | `#08401F` |
+
+### Amber (Warning)
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `#16120B` | `#FEFCF0` |
+| 2 | `#1D1710` | `#FDF8E0` |
+| 3 | `#2C2011` | `#FCEFC0` |
+| 4 | `#3D2B10` | `#FAE39A` |
+| 5 | `#4F370F` | `#F5D46E` |
+| 6 | `#63440E` | `#E8C044` |
+| 7 | `#7E5711` | `#D4A825` |
+| 8 | `#A87318` | `#B88E15` |
+| 9 | `#F5C742` | `#D09E10` |
+| 10 | `#FFDB5C` | `#B08510` |
+| 11 | `#FFE588` | `#866510` |
+| 12 | `#FFF3CC` | `#4A380A` |
+
+### Blue (Info)
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `#0F1520` | `#F3F8FE` |
+| 2 | `#131B2E` | `#E6F0FD` |
+| 3 | `#15243B` | `#C8DFFB` |
+| 4 | `#192E4C` | `#A6CBF7` |
+| 5 | `#1D3A5E` | `#80B4F3` |
+| 6 | `#224973` | `#5999EC` |
+| 7 | `#2A5E92` | `#377FE2` |
+| 8 | `#347AB8` | `#2068D0` |
+| 9 | `#3E96F4` | `#2E78E5` |
+| 10 | `#5EAAF7` | `#2362C7` |
+| 11 | `#8EC3FA` | `#1B4FA5` |
+| 12 | `#CEE1FC` | `#0F3060` |
+
+### Violet
+
+| Step | Dark | Light |
+|------|------|-------|
+| 1 | `#14111F` | `#F9F6FE` |
+| 2 | `#1B1528` | `#F1EBFD` |
+| 3 | `#241C38` | `#E3D4FC` |
+| 4 | `#2E224A` | `#D2B9FA` |
+| 5 | `#38295E` | `#BF9CF7` |
+| 6 | `#443375` | `#A87CF2` |
+| 7 | `#553F94` | `#9060EA` |
+| 8 | `#6B54B5` | `#7A4ADD` |
+| 9 | `#8B5CF6` | `#7C3AED` |
+| 10 | `#9E77F8` | `#6A2ED2` |
+| 11 | `#BAA0FA` | `#5624B3` |
+| 12 | `#E2D5FD` | `#351468` |
+
+---
+
+## Semantic Token Map
+
+| CSS Variable | Tailwind Class | Dark | Light |
+|---|---|---|---|
+| `--color-background` | `bg-background` | gray.1 | gray.1 |
+| `--color-surface` | `bg-surface` | gray.2 | gray.2 |
+| `--color-surface-hover` | `bg-surface-hover` | gray.3 | gray.3 |
+| `--color-surface-active` | `bg-surface-active` | gray.4 | gray.4 |
+| `--color-surface-raised` | `bg-surface-raised` | gray.5 | gray.2 |
+| `--color-border` | `border-border` | gray.6 | gray.6 |
+| `--color-border-hover` | `border-border-hover` | gray.7 | gray.7 |
+| `--color-border-subtle` | `border-border-subtle` | grayA.3 | grayA.3 |
+| `--color-primary` | `bg-primary` | gray.12 | gray.12 |
+| `--color-primary-foreground` | `text-primary-foreground` | gray.1 | gray.1 |
+| `--color-secondary` | `bg-secondary` | gray.4 | gray.3 |
+| `--color-accent` | `bg-accent` | teal.9 | teal.9 |
+| `--color-destructive` | `bg-destructive` | red.9 | red.9 |
+| `--color-success` | `bg-success` | green.9 | green.9 |
+| `--color-warning` | `bg-warning` | amber.9 | amber.9 |
+| `--color-info` | `bg-info` | blue.9 | blue.9 |
+| `--color-muted` | `bg-muted` | gray.4 | gray.3 |
+| `--color-muted-foreground` | `text-muted-foreground` | gray.11 | gray.11 |
+| `--color-overlay` | `bg-overlay` | `#000` | `#000` |
+| `--color-text-primary` | `text-text-primary` | gray.12 | gray.12 |
+| `--color-text-secondary` | `text-text-secondary` | gray.11 | gray.11 |
+| `--color-text-tertiary` | `text-text-tertiary` | gray.10 | gray.9 |
+| `--color-focus-ring` | `ring-accent` | teal.9 | teal.9 |
+| `--color-link` | `text-link` | teal.10 | teal.11 |
+| `--color-input` | `bg-input` | gray.4 | gray.3 |
+| `--color-disabled` | `bg-disabled` | gray.7 | gray.6 |
+
+### Chart Variables (space-separated RGB)
+
+| Var | Dark | Light | Hue |
+|-----|------|-------|-----|
+| `--chart-1` | `56 189 184` | `26 143 136` | Teal |
+| `--chart-2` | `62 150 244` | `46 120 229` | Blue |
+| `--chart-3` | `245 199 66` | `208 158 16` | Amber |
+| `--chart-4` | `61 214 140` | `27 148 80` | Green |
+| `--chart-5` | `139 92 246` | `124 58 237` | Violet |
+| `--chart-6` | `229 72 77` | `206 44 59` | Red |
+
+---
+
+## Non-Color Tokens
+
+### Typography
+
+| Token | Value |
+|-------|-------|
+| `font-sans` | `Satoshi, sans-serif` |
+| `text-xs` | 12px |
+| `text-sm` | 14px |
+| `text-base` | 16px |
+| `text-lg` | 20px |
+| `text-xl` | 24px |
+| `text-2xl` | 32px |
+| `text-3xl` | 48px |
+| `text-4xl` | 64px |
+
+### Border Radius
+
+| Token | Value |
+|-------|-------|
+| `rounded-sm` | 4px |
+| `rounded-md` | 8px |
+| `rounded-lg` | 16px |
+| `rounded-full` | 9999px |
+
+### Shadows
+
+| Token | Value |
+|-------|-------|
+| `shadow-glow` | `0 0 20px -5px rgba(255,255,255,0.1)` |
+| `shadow-glow-accent` | `0 0 20px -5px rgba(56,189,184,0.15)` |
+
+### Spacing
+
+Base unit: 4px. Custom: `spacing-4.5` = `1.125rem`.
+
+---
+
+## Bloom Style Palette
+
+`:root.bloom` overrides the light theme with a warm, organic palette. Bloom is light-only (forces `resolvedTheme` to `'light'`).
+
+### Key Bloom Token Overrides
+
+| Token | Bloom | Arctic Light | Change |
+|-------|-------|-------------|--------|
+| `--color-background` | `254 253 251` (warm cream) | `251 252 253` (cool white) | Warmer base |
+| `--color-surface` | `251 249 246` | `245 247 249` | Cream tint |
+| `--color-accent` | `232 87 58` (coral) | `26 143 136` (teal) | Different hue |
+| `--color-border` | `217 209 199` (warm) | `205 212 220` (cool) | Brown vs blue-gray |
+| `--color-destructive` | `232 86 109` (rose) | `206 44 59` (red) | Softer |
+| `--color-success` | `61 214 160` (mint) | `27 148 80` (green) | Brighter |
+| `--color-warning` | `245 166 35` (peach) | `208 158 16` (amber) | Warmer |
+| `--color-overlay` | `45 35 24` (warm brown) | `0 0 0` (black) | Brown tint |
+| `--color-focus-ring` | `139 92 246` (violet) | `26 143 136` (teal) | Violet accent |
+| `--color-link` | `99 56 196` (violet) | `15 102 96` (teal) | Violet links |
+| `--color-info` | `90 180 245` (sky blue) | `46 120 229` (blue) | Sky blue |
+
+### Bloom Glass
+
+Bloom glass uses warm cream tints instead of cool white:
+- `glass-panel`: cream gradient with brown shadows (`rgba(45, 35, 24, 0.06)`)
+- `glass-floating`: warm hover rotation (`rotate(0.3deg)`)
+- `glass-overlay`: cream-tinted with brown shadows
+
+See `src/index.css` for the full Bloom glass overrides.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vadim Comanescu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# Seed Design System
+
+A premium, opinionated design system for AI-integrated web applications, with dual-axis theming (light/dark/bloom), glassmorphism effects, and a full agent skill for AI-assisted development.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev        # http://localhost:5001
+```
+
+The dev server runs a showcase app (`src/app/(showcase)/`) that exercises all components, blocks, charts, icons, and patterns.
+
+## Using in Next.js Projects
+
+Seed is consumed through installable package artifacts, not live repo-path links.
+
+| Situation | Command | Consumer guidance |
+|-----------|---------|-------------------|
+| Existing Next.js app | Install an exact released `@vadimcomanescu/nadicode-design-system` version | Read the synced Seed skill in the consumer app: `.agents/skills/seed/SKILL.md` |
+| Greenfield SaaS app | Use the scaffold repo for the app shell, then install the exact released `@vadimcomanescu/nadicode-design-system` version it pins | Read the synced Seed skill in the generated app: `.agents/skills/seed/SKILL.md` |
+
+DS-repo authoring notes and ownership rules still live under `docs/nadicode/`, but consumer apps keep only the synced Seed skill, not the `docs/nadicode/` tree.
+
+### Package-backed consumer contract
+
+1. `package.json` depends on `@vadimcomanescu/nadicode-design-system` through an exact released version such as `2.0.0`.
+2. Consumer apps must not depend on `@vadimcomanescu/nadicode-design-system` through a live repo directory such as `file:/absolute/path/to/nadicode-design-system`.
+3. `globals.css` imports `@vadimcomanescu/nadicode-design-system/tokens.css` before `seed-palette.css`.
+4. `tailwind.config.*` uses `@vadimcomanescu/nadicode-design-system/tailwind`.
+5. `eslint.config.*` imports `@vadimcomanescu/nadicode-design-system/eslint-config` and `@vadimcomanescu/nadicode-design-system/eslint-plugin`.
+6. `providers.tsx` imports `ThemeProvider` from `@vadimcomanescu/nadicode-design-system/theme-provider`.
+7. `@vadimcomanescu/nadicode-design-system/test` exports the package-owned `SeedTestProvider` wrapper for consumer tests, while repo-local tests can still use `@/test/SeedTestProvider`.
+8. `scripts/ds-check.mjs` delegates to `@vadimcomanescu/nadicode-design-system/ds-check`.
+9. `npm run ds:update` reinstalls from the `@vadimcomanescu/nadicode-design-system` spec already declared in `package.json` and syncs only the Seed usage skill.
+10. The app stays package-backed, with DS runtime imported from `@vadimcomanescu/nadicode-design-system`.
+11. DS scaffolding/distribution docs are not copied into the consumer app.
+
+### Package-backed i18n contract
+
+1. The app owns `src/i18n/request.ts`, locale routing, and `NextIntlClientProvider`.
+2. DS catalogs come from `@vadimcomanescu/nadicode-design-system/messages/<locale>`.
+3. App translations live in `messages/<locale>.json`.
+4. `src/i18n/request.ts` merges the two sources with `mergeSeedMessages()`.
+5. Generated apps do not copy DS catalogs into the app.
+
+### Minimal wiring
+
+```css
+/* src/app/globals.css */
+@import "@vadimcomanescu/nadicode-design-system/tokens.css";
+@import "../seed-palette.css";
+```
+
+```tsx
+// src/app/providers.tsx
+"use client"
+
+import { ThemeProvider } from "@vadimcomanescu/nadicode-design-system/theme-provider"
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>
+}
+```
+
+```js
+// tailwind.config.js
+import seedPreset from "@vadimcomanescu/nadicode-design-system/tailwind"
+
+export default seedPreset()
+```
+
+```js
+// eslint.config.mjs
+import seedConfig from "@vadimcomanescu/nadicode-design-system/eslint-config"
+import { nadicodePlugin } from "@vadimcomanescu/nadicode-design-system/eslint-plugin"
+
+export default [
+  ...seedConfig,
+  {
+    plugins: {
+      nadicode: nadicodePlugin,
+    },
+  },
+]
+```
+
+```js
+// scripts/ds-check.mjs
+#!/usr/bin/env node
+import "@vadimcomanescu/nadicode-design-system/ds-check"
+```
+
+### Distribution rule
+
+Seed must install into consumer `node_modules` as real package files. The canonical consumer contract is an exact released package version such as `@vadimcomanescu/nadicode-design-system@2.0.0`.
+
+For unpublished local work before a release exists, stage the tarball artifact into the consumer app and install from a committed relative path such as `file:.nadicode/packages/vadimcomanescu-nadicode-design-system-<version>.tgz`:
+
+```bash
+DS_REPO="/absolute/path/to/nadicode-design-system"
+mkdir -p .nadicode/packages
+npm --prefix "$DS_REPO" run pack:artifact -- "$PWD/.nadicode/packages"
+NADICODE_TARBALL="$(ls .nadicode/packages/vadimcomanescu-nadicode-design-system-*.tgz | head -n1)"
+npm install "@vadimcomanescu/nadicode-design-system@file:${NADICODE_TARBALL}"
+```
+
+Consumer apps must also satisfy Nadicode's peer dependencies, especially `next`, `react`, `react-dom`, `next-intl`, and `tailwindcss`.
+
+`npm run ds:update` in the consumer app must reinstall from the existing `@vadimcomanescu/nadicode-design-system` dependency spec in `package.json`. If the app is pinned to a local tarball, refresh that tarball first, then run `npm run ds:update`.
+
+### Verification
+
+```bash
+npm run ds:check
+npm run lint
+npx tsc --noEmit
+npm run build
+```
+
+## Maintainer Release Workflow
+
+Private releases are done locally from this repo, not through GitHub CI.
+
+Before publishing, make sure the npm account that owns the `@vadimcomanescu` scope is authenticated locally:
+
+```bash
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+If that fails, run `npm login` first. Publishing still requires either account 2FA or a granular access token that can publish under the scope.
+
+1. Bump the package version:
+
+```bash
+npm version patch --no-git-tag-version
+```
+
+Use `minor` or `major` instead of `patch` when appropriate.
+
+For the common cases, you can also run one of the release helpers:
+
+```bash
+npm run release:patch
+npm run release:minor
+npm run release:major
+```
+
+2. Run the full package release command:
+
+```bash
+npm run publish:package
+```
+
+That command does three things locally:
+
+- `npm run release:check`
+- `npm publish --access=public --registry=https://registry.npmjs.org/`
+- `npm run release:verify`
+
+Those checks are also wired into the npm publish lifecycle in this repo, so a plain `npm publish` still runs the same local release gate and post-publish verification.
+
+3. If you need to verify the published version again later:
+
+```bash
+npm run release:verify
+```
+
+4. If the scaffold needs unpublished DS changes before the next release, stage a fallback artifact under `.nadicode/packages/` with `npm run pack:artifact -- /absolute/path/to/consumer/.nadicode/packages`.
+
+Canonical DS-repo onboarding docs:
+
+- `docs/nadicode/ADOPTION_PLAYBOOK.md`
+- `docs/nadicode/SCAFFOLDING_PROCESS.md`
+- `docs/agents/recipes.md`
+- `AGENTS.md`
+- `docs/releasing-package.md`
+
+## Project Structure
+
+```
+src/
+  app/
+    (showcase)/        # Component showcase (dev server UI)
+  components/
+    ui/                # UI primitives and effect components
+    ui/icons/          # Animated icons (motion/react)
+    ui/charts/         # Chart primitives (recharts)
+    ui/stepper/        # Multi-step stepper
+    ui/text-effects/   # Streaming text, gradient text, etc.
+    blocks/            # Composed blocks (Hero, Pricing, Auth, etc.)
+    layout/            # Grid system
+    logos/             # Brand SVG logos
+    animate-ui/        # Animation primitives (fade, slide, zoom, etc.)
+  hooks/               # use-toast, use-mobile, use-token, etc.
+  lib/
+    tokens.config.js   # Master token definitions
+    ThemeProvider.tsx   # Dual-axis theme context (theme + style)
+    utils.ts           # cn() class merge helper
+    motion.ts          # Motion spring/transition presets
+  index.css            # CSS tokens, glass effects, keyframes
+bin/
+  dev-server.sh        # Local Next.js dev server wrapper
+  lighthouse.sh        # Local Lighthouse runner
+.agents/
+  skills/              # Bundled agent skills
+```
+
+## Commands
+
+```bash
+npm run dev            # Start dev server (port 5001)
+npm run build          # Build
+npm run test           # Run tests (Vitest)
+npm run lint           # Lint source
+npm run typecheck      # Type-check (tsc --noEmit)
+npm run test:all       # typecheck + lint + tests
+npm run pack:artifact  # Build and pack a consumer-installable .tgz artifact
+npm run ds:validate    # Repo validation gate (build round-trip still tracked in scaffolding backlog)
+npm run ds:check       # Nadicode contract enforcement
+npm run docs:check     # Validate docs and agent references
+npm run docs:inventory # List all components
+npm run docs:api       # Generate API docs
+npm run ds:task-pack   # Build task pack from scope-definition.json
+npm run test:visual    # Playwright visual regression tests
+```
+
+## Theming
+
+Dual-axis: `theme` (light / dark / system) + `style` (arctic / bloom).
+
+- **Arctic**: Cool teal accent, deep blacks in dark mode
+- **Bloom**: Warm coral accent, cream tones, light-only
+
+Tokens flow: `tokens.config.js` -> `index.css` (CSS vars) -> `tailwind.config.js` (Tailwind classes)
+
+## Key Conventions
+
+- Components use the **Radix + CVA + ref-as-prop** pattern (React 19, no forwardRef)
+- Icons: always import from `@/components/ui/icons/`, never from `lucide-react` directly
+- Colors: always use semantic tokens (`bg-background`, `text-text-primary`), never hardcoded
+- Glass effects: `glass-panel` (structural), `glass-floating` (elevated), `glass-overlay` (transient)
+- Class merging: always use `cn()` from `@/lib/utils`