@vadimcomanescu/nadicode-design-system 2.0.0

package/.agents/skills/seed/SKILL.md

@@ -0,0 +1,433 @@
+---
+name: Seed Design System
+description: >
+  Use when building UI with the Seed Design System or composing full pages from
+  Seed components. Covers tokens, components, glass effects, animations,
+  dual-axis theming, page recipes, and Next.js App Router integration.
+tags: [seed, design-system, arctic-glow, react, tailwind, radix, glassmorphism, recipes]
+---
+
+# Seed Design System -- Agent Skill
+
+React 19 + TypeScript + Tailwind CSS 4 + Radix UI + CVA.
+Dual-axis theming: `theme` (light/dark/system) + `style` (arctic/bloom).
+Arctic: cool teal glassmorphism. Bloom: warm light-only organic aesthetic.
+Next.js App Router. Dev server: `localhost:5001`.
+
+In consumer apps, Seed runtime normally comes from an exact released `@vadimcomanescu/nadicode-design-system` version. For unpublished local work, use a packed tarball such as `file:.nadicode/packages/vadimcomanescu-nadicode-design-system-<version>.tgz`. Do not point consumer apps at a live DS repo directory.
+
+Consumer scaffold contract: brand customization stays palette-only unless the task is explicitly DS development. In seeded apps, edit seed-palette.css in the app src/ root for brand colors. Do not tell consumers to edit the package tokens stylesheet, `src/lib/tokens.config.js`, or font/layout wiring as part of normal branding.
+
+## Read Order
+
+1. **This file** -- router, quick references, forbidden patterns
+2. **`contract.md`** -- binary rules, package integration contract
+3. **`intent-map.md`** -- intent decision tree + recipe index
+4. **`recipes/<page-type>.md`** -- matching recipe for your page
+5. **`references/`** -- deep dives as needed
+6. **`references/brand-override.md`** -- palette-only brand customization guide for seeded apps
+
+---
+
+## Intent Decision Tree
+
+What are you building? Follow the tree to find your recipe.
+
+```
+Does user have a session?
+  YES --> app-shell intents:
+         dashboard .......... recipes/dashboard.md
+         CRUD list/detail ... recipes/crud-list-detail.md
+         CRUD form .......... recipes/crud-form.md
+         settings ........... recipes/settings.md
+         analytics .......... recipes/analytics.md
+         agents/chat ........ recipes/agents-chat.md
+         navigation shell ... recipes/navigation-shell.md
+  NO  --> auth?
+            YES --> recipes/auth.md (auth-shell)
+          onboarding?
+            YES --> recipes/onboarding.md (onboarding-shell)
+          marketing intents (marketing-shell):
+            agency home ...... recipes/agency-home.md
+            landing .......... recipes/marketing-landing.md
+            digital workers .. recipes/digital-workers.md
+            service detail ... recipes/service-detail.md
+            pricing .......... recipes/pricing.md
+            blog/content ..... recipes/blog-content.md
+            about/team ....... recipes/company-about.md
+            contact .......... recipes/company-contact.md
+            checkout ......... recipes/checkout.md
+            marketing shell .. recipes/marketing-shell.md
+          error pages --> recipes/error-pages.md (fallback-shell)
+```
+
+Full intent-to-recipe mapping with shell selection: see `intent-map.md`.
+
+---
+
+## Forbidden Patterns
+
+| WRONG | CORRECT | Why |
+|-------|---------|-----|
+| `text-foreground` | `text-text-primary` | `foreground` undefined |
+| `text-muted-foreground` | `text-text-secondary` / `text-text-tertiary` | Semantic text tokens |
+| `border-error` | `border-destructive` | `error` undefined |
+| `bg-black/80` (overlays) | `bg-overlay/80` | Semantic overlay token |
+| `bg-zinc-950`, `bg-slate-*` | `bg-background` / `bg-surface` | No Tailwind default colors |
+| `h-screen` / `min-h-screen` | `h-dvh` / `min-h-dvh` | Mobile viewport bug |
+| `glass-card` | `glass-panel` | `glass-card` deleted |
+| `glass-atmospheric` | `glass-overlay` | Renamed |
+| `import { X } from "lucide-react"` | `import { XIcon } from "@vadimcomanescu/nadicode-design-system/icons"` | Integrity test enforces |
+| `import { motion } from "framer-motion"` | `import { motion } from "motion/react"` | Package renamed |
+| `#6366f1` / Electric Indigo | `#38BDB8` (dark) / `#1A8F88` (light) teal | Arctic Glow replaced Indigo |
+| `import { MeshGradient } from "@paper-design/shaders-react"` | `import { ShaderBackground } from "@vadimcomanescu/nadicode-design-system/shader-background"` | Use themed wrapper |
+| CSS hex in vars: `--color-bg: #0F1114` | `--color-background: 15 17 20` | CSS vars use space-separated RGB |
+| Block without `interface *Props` | `interface MyBlockProps { title?: string }` | Integrity test enforces |
+| Required content props | Optional with defaults in destructuring | Blocks render standalone |
+
+---
+
+## Token Quick Reference
+
+**Backgrounds:** `bg-background` (page), `bg-surface` (cards), `bg-surface-hover`, `bg-surface-active`, `bg-surface-raised`, `bg-muted`, `bg-overlay/80` (modals)
+
+**Text:** `text-text-primary` (headings/body), `text-text-secondary` (meta), `text-text-tertiary` (disabled), `text-link`
+
+**Status:** `bg-destructive`/`text-destructive`, `bg-success`/`text-success`, `bg-warning`, `bg-info`
+
+**Borders:** `border-border`, `border-border-hover`, `border-border-subtle`, `border-destructive`
+
+**Interactive:** `bg-primary` (gray.12), `bg-secondary`, `bg-accent` (teal), `ring-accent` (focus)
+
+**Charts:** `chart-1` (teal), `chart-2` (blue), `chart-3` (amber), `chart-4` (green), `chart-5` (violet), `chart-6` (red)
+
+**Sidebar:** `sidebar`, `sidebar-foreground`, `sidebar-primary`, `sidebar-accent`, `sidebar-border`, `sidebar-ring`
+
+Full token tables with CSS variables and Radix scales: `references/tokens.md`
+
+---
+
+## Heading And Text
+
+Use `Heading` for semantic headings. Use `Typography` for non-heading copy only.
+
+```tsx
+import { Heading } from "@vadimcomanescu/nadicode-design-system/heading"
+import { Typography } from "@vadimcomanescu/nadicode-design-system/typography"
+
+<Heading level={1}>Page title</Heading>
+<Heading level={2} size="section">Section title</Heading>
+<Heading level={3} size="label">Card title</Heading>
+
+<Typography>Body copy</Typography>
+<Typography variant="small">Meta text</Typography>
+<Typography variant="muted">Muted text</Typography>
+```
+
+**Heading props**
+
+| Prop | Type | Default | Purpose |
+|------|------|---------|---------|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Semantic HTML heading level |
+| `size` | `display \| section \| subsection \| title \| label \| eyebrow` | from `level` | Visual size preset |
+| `className` | `string` | - | Spacing, color, and contextual overrides |
+
+**Typography variants**
+
+| Variant | Use |
+|---------|-----|
+| `body` | Default paragraph copy |
+| `small` | Meta text, captions, compact labels |
+| `muted` | Secondary/de-emphasized text |
+
+---
+
+## Golden Component Pattern
+
+```tsx
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const variants = cva("base-classes", {
+  variants: { variant: { primary: "...", secondary: "..." }, size: { sm: "...", md: "..." } },
+  defaultVariants: { variant: "primary", size: "md" },
+})
+
+export interface Props extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+  VariantProps<typeof variants> { asChild?: boolean; ref?: React.Ref<HTMLButtonElement> }
+
+function MyComponent({ className, variant, size, asChild = false, ref, ...props }: Props) {
+  const Comp = asChild ? Slot : "button"
+  return <Comp className={cn(variants({ variant, size, className }))} ref={ref} {...props} />
+}
+
+export { MyComponent, variants }
+```
+
+**5 rules:** (1) `ref` as prop (React 19, no forwardRef) (2) `cn()` for class merging (3) CVA for variants (4) `asChild` + `Slot` for polymorphism (5) Export component + variants
+
+Full patterns with Button, Input, Dialog, Block examples: `references/patterns.md`
+
+---
+
+## Glass Tiers
+
+| Class | Use For | Key Properties |
+|-------|---------|----------------|
+| `glass-panel` | Dashboards, cards, data containers | `bg-surface/30 backdrop-blur-xl` |
+| `glass-floating` | Elevated elements, hero cards | `bg-surface/40 backdrop-blur-[40px]` + heavy shadows |
+| `glass-overlay` | Popovers, toasts, transient UI | `bg-surface/30 backdrop-blur-md` |
+
+Light/bloom overrides are automatic. Bloom uses warm cream tints + brown shadows.
+Deep dive: `references/glass-and-effects.md`
+
+---
+
+## Animation Essentials
+
+```tsx
+import { motion } from "motion/react"
+import { motionSpring, fadeInUp, blockStagger } from "@/lib/motion"
+```
+
+### Spring Presets
+
+| Name | Stiffness | Damping | Mass | Use For |
+|------|-----------|---------|------|---------|
+| `snappy` | 400 | 28 | 0.8 | Micro-interactions, tooltips |
+| `gentle` | 200 | 20 | 1.0 | Page transitions, drawers |
+| `bouncy` | 300 | 14 | 0.8 | Celebration, completion |
+| `dramatic` | 500 | 24 | 1.2 | Hero entrances |
+| `wobbly` | bloom only | | | Extra bounce |
+
+### Duration Tokens
+
+`duration-micro` (100ms), `duration-fast` (150ms), `duration-normal` (200ms), `duration-moderate` (250ms), `duration-slow` (300ms)
+
+### Easing
+
+`ease-out-cubic` (enters), `ease-in-out-cubic` (morphing). CSS transitions for hover/border/bg changes, springs for entrances/mounts.
+
+### Animation Budgets
+
+App pages: 400-600ms total. Marketing: 800-1200ms. Max stagger chain: 8 items, 50-120ms apart.
+Below-fold items: use `ScrollFadeIn`.
+
+Reduced motion: `useReducedMotion()` or `motion-reduce:` classes. Non-negotiable.
+Style-aware motion: `useStyleMotion()` hook. Deep dive: `references/animation.md`
+
+---
+
+## Icon Rules
+
+All icons export from `@vadimcomanescu/nadicode-design-system/icons` -- same import path, same API. Never import `lucide-react` directly (integrity test enforces).
+
+```tsx
+import { SettingsIcon, BellIcon } from "@vadimcomanescu/nadicode-design-system/icons"
+<SettingsIcon size={16} />  // size in px, default 28
+```
+
+### Two Tiers
+
+| Tier | Count | Animation | Source |
+|------|-------|-----------|--------|
+| **Hand-crafted** | 110 | `motion.path` stroke animations (premium, per-icon) | [lucide-animated.com](https://lucide-animated.com); `sun.tsx` as template |
+| **Factory-wrapped** | 289 | CSS stroke-draw via `createAnimatedIcon` (covers full Lucide catalog) | `lucide-wrapped.tsx` |
+
+**Total: 399 icons.** Before adding a new icon, check whether it already exports from `@vadimcomanescu/nadicode-design-system/icons` or a matching `@vadimcomanescu/nadicode-design-system/icons/<name>` subpath.
+
+### Adding a New Icon
+
+1. **Check if it exists** (399 total -- likely yes).
+2. **If missing:** add it to `lucide-wrapped.tsx` using `createAnimatedIcon`:
+   ```tsx
+   import { Home } from "lucide-react"
+   export const HomeIcon = createAnimatedIcon(Home, "HomeIcon")
+   ```
+3. **If the needed icon is missing**, stop and request an upstream DS export. Do not hand-craft a local scaffold copy just to bypass the package contract.
+
+`createAnimatedIcon` is also exported for consumers to wrap any Lucide icon ad-hoc without adding it to the catalog.
+
+Full catalog: `references/icons.md`
+
+---
+
+## Theming
+
+Dual-axis: `theme` (light/dark/system) + `style` (arctic/bloom). Bloom forces light.
+
+```tsx
+const { theme, style, setTheme, setStyle, resolvedTheme } = useTheme()
+```
+
+CSS selectors: `:root` (light), `:root.dark`, `:root.bloom`. Style-aware motion via `useStyleMotion()`.
+
+Arctic: teal accent `#38BDB8`/`#1A8F88`, cool grays. Bloom: coral accent `#E8573A`, warm cream, brown tints.
+
+In seeded consumer apps, palette overrides may fully replace Bloom colors. Bloom remains a style axis, not a protected palette.
+
+---
+
+## i18n Components
+
+**Ownership boundary**
+The scaffold app owns `next-intl` setup: `src/i18n/request.ts`, locale routing, `NextIntlClientProvider`, `timeZone`, `now`, and message loading. Seed owns DS message catalogs and merge helpers only.
+
+**Message merging**
+Use `mergeSeedMessages` from `@vadimcomanescu/nadicode-design-system/lib/merge-messages` in `src/i18n/request.ts` to combine DS-owned package exports like `@vadimcomanescu/nadicode-design-system/messages/<locale>` with app-owned `messages/<locale>.json`, then pass the merged result into the app's own `NextIntlClientProvider`.
+Do not copy DS catalog files into the app.
+
+**Test helpers**
+Consumer apps can import `SeedTestProvider` from `@vadimcomanescu/nadicode-design-system/test` when they need the package-owned test wrapper. The showcase app keeps its local `@/test/SeedTestProvider` wrapper for in-repo tests.
+
+**LanguageSwitcher** (`@vadimcomanescu/nadicode-design-system/language-switcher`)
+Props: `locales` (string[], default `['en','it']`), `value` (current locale), `onLocaleChange` (callback), `className`. Uses `useTranslations('components.languageSwitcher')` for labels. Without `onLocaleChange`, sets a `NEXT_LOCALE` cookie and calls `router.refresh()`.
+
+**SettingsModal** (`@vadimcomanescu/nadicode-design-system/settings-modal`)
+Exports: `defaultSettingsTabs`, `SettingsTabDef` (interface), `SettingsModal` (component).
+Props: `open`, `onOpenChange`, `defaultTab`, `tabs` (SettingsTabDef[]), `renderContent` (preferred: `(tab: string) => ReactNode`), `ContentComponent` (deprecated). Uses `useTranslations('pages.settings')` for tab labels and headings. The default language tab renders `LanguageSwitcher` automatically.
+
+---
+
+## Composition Algebra
+
+Every page = **Shell > Sections > Components**.
+
+- 1 shell (persistent frame: sidebar, header, footer)
+- 2-8 sections (vertical bands, no nesting)
+- 1-6 components per section via CSS grid/flex
+
+### Shell Selection
+
+| Intent | Shell | Components |
+|--------|-------|------------|
+| App (dashboard, settings, CRUD, analytics, agents) | `app-shell` | `Sidebar` + top bar + `SearchCommand` |
+| Marketing (landing, pricing, blog) | `marketing-shell` | `HeaderBlock` + `FooterBlock` |
+| Auth | `auth-shell` | `AuthLayout` (split/centered) |
+| Onboarding | `onboarding-shell` | Minimal header + progress bar |
+| Error | `fallback-shell` | Logo + nav back |
+
+Content widths, vertical rhythm, responsive contracts: `references/composition.md`
+
+### Kanban Board (Drag & Drop)
+
+Compound component for multi-column sortable boards (project boards, runs views, pipelines).
+
+```tsx
+import {
+  KanbanBoard, KanbanColumn, KanbanColumnHeader,
+  KanbanItem, KanbanHandle,
+} from '@vadimcomanescu/nadicode-design-system/kanban-board'
+import type { KanbanColumnState, KanbanMoveMeta } from '@vadimcomanescu/nadicode-design-system/kanban-board'
+```
+
+**Architecture:** `@dnd-kit/core` + `@dnd-kit/sortable` internally. Consumer API is Seed-owned (no dnd-kit types leak).
+
+**Usage:**
+
+```tsx
+type Task = { id: string; title: string }
+
+const [columns, setColumns] = useState<KanbanColumnState<Task>[]>([
+  { id: 'todo', items: [{ id: '1', title: 'Task A' }] },
+  { id: 'done', items: [] },
+])
+
+<KanbanBoard
+  value={columns}
+  onValueChange={(next, meta) => {
+    setColumns([...next])
+    // meta: { item, itemId, fromColumnId, toColumnId, fromIndex, toIndex }
+  }}
+  getItemId={(task) => task.id}
+  getItemLabel={(task) => task.title}
+  canMove={({ fromColumnId, toColumnId }) => isAllowed(fromColumnId, toColumnId)}
+  renderOverlay={(task) => <MyCard task={task} />}
+>
+  {columns.map((col) => (
+    <KanbanColumn key={col.id} id={col.id} items={col.items} aria-label={col.name}>
+      <KanbanColumnHeader>{col.name} <Badge variant="outline">{col.items.length}</Badge></KanbanColumnHeader>
+      {col.items.map((task) => (
+        <KanbanItem key={task.id} value={task}>
+          <KanbanHandle aria-label={`Move ${task.title}`} />
+          <MyCard task={task} />
+        </KanbanItem>
+      ))}
+    </KanbanColumn>
+  ))}
+</KanbanBoard>
+```
+
+**Key props:**
+
+| Prop | Required | Purpose |
+|------|----------|---------|
+| `value` | Yes | `KanbanColumnState<T>[]` -- controlled column state |
+| `onValueChange` | Yes | `(next, meta) => void` -- fires with new state + move metadata |
+| `getItemId` | Yes | Extract stable ID from item |
+| `getItemLabel` | No | Human label for screen reader announcements |
+| `canMove` | No | Constraint callback to reject moves |
+| `renderOverlay` | No | Custom drag ghost (renders inside `glass-floating`) |
+| `activationDistance` | No | Px before drag starts (default: 5) |
+| `items` on Column | Yes | Pass the column's items array for SortableContext |
+
+**Card content is consumer-owned.** The DS provides the board structure, drag mechanics, glass styling, and accessibility. Compose card interiors from existing DS primitives: `Badge`, `StatusDot`, `Typography`, `Button`, `Avatar`.
+
+---
+
+## Page States
+
+Every page handles: `loading` (Skeleton), `empty` (Empty + CTA), `error` (Alert + retry), `has-data`, `submitting` (disabled + spinner), `success` (Toast / SuccessCheck).
+
+Loading tiers: Skeleton (< 1s), Spinner (1-3s), Progress (3s+).
+Patterns: `references/state-machines.md`
+
+---
+
+## Recipe Index
+
+| Intent | Recipe | Shell |
+|--------|--------|-------|
+| Dashboard | `recipes/dashboard.md` | app-shell |
+| Marketing Landing | `recipes/marketing-landing.md` | marketing-shell |
+| Agency Home | `recipes/agency-home.md` | marketing-shell |
+| Digital Workers | `recipes/digital-workers.md` | marketing-shell |
+| Service Detail | `recipes/service-detail.md` | marketing-shell |
+| CRUD List + Detail | `recipes/crud-list-detail.md` | app-shell |
+| CRUD Form | `recipes/crud-form.md` | app-shell |
+| Settings | `recipes/settings.md` | app-shell |
+| Auth | `recipes/auth.md` | auth-shell |
+| Onboarding | `recipes/onboarding.md` | onboarding-shell |
+| Pricing | `recipes/pricing.md` | marketing-shell |
+| Analytics | `recipes/analytics.md` | app-shell |
+| Agent Chat | `recipes/agents-chat.md` | app-shell |
+| Error Pages | `recipes/error-pages.md` | fallback-shell |
+| Navigation Shell | `recipes/navigation-shell.md` | app-shell |
+| Blog / Content | `recipes/blog-content.md` | marketing-shell |
+| Company About | `recipes/company-about.md` | marketing-shell |
+| Company Contact | `recipes/company-contact.md` | marketing-shell |
+| Marketing Shell | `recipes/marketing-shell.md` | marketing-shell |
+| Checkout | `recipes/checkout.md` | marketing-shell |
+
+---
+
+## Reference Index
+
+| File | Contents |
+|------|----------|
+| `references/tokens.md` | Radix scales, semantic token map, CSS variables, bloom palette |
+| `references/components.md` | All UI components with tiers inline, Radix primitives, agentic UI |
+| `references/patterns.md` | Golden pattern + 4 code examples: Button, Input, Dialog, LoginBlock |
+| `references/animation.md` | Springs, easings, durations, stagger, choreography, reduced motion |
+| `references/glass-and-effects.md` | Glass tier CSS, decorative components, text effects, shaders |
+| `references/blocks.md` | Blocks by domain with import paths |
+| `references/icons.md` | Animated icon usage patterns |
+| `references/opinions.md` | Decision tables from Opinions Bible |
+| `references/nextjs.md` | App Router setup, providers, SSR boundaries, showcase |
+| `references/composition.md` | Layout algebra, spacing, grid patterns, content widths |
+| `references/responsive.md` | Breakpoint contracts, mobile-first, touch targets |
+| `references/state-machines.md` | State machines, loading tiers, streaming, error handling |
+| `references/dashboard-patterns.md` | Glass budgets, typography, chart colors, animation, anti-patterns for dashboards |
+| `references/brand-override.md` | Brand customization (colors, glass, typography, motion, copy, assets) |

package/.agents/skills/seed/contract.md

@@ -0,0 +1,92 @@
+# Seed Contract
+
+Binary rules for consumer apps using the Seed Design System. Every rule is non-negotiable.
+
+## Scope
+
+- Apply only to the explicit migration scope you were given.
+- Do not edit files outside scope unless the build is blocked by a required wiring step.
+
+## Import Rules
+
+1. Import Seed primitives, blocks, charts, icons, and text effects from `@vadimcomanescu/nadicode-design-system/*` subpaths. Do not vendor or recreate DS runtime files inside the scaffold.
+2. Never import icons from `lucide-react` directly. Import from `@vadimcomanescu/nadicode-design-system/icons` or the matching `@vadimcomanescu/nadicode-design-system/icons/<name>` subpath.
+3. If a needed primitive is missing, stop and report it. Do not invent ad-hoc replacements.
+
+## Token Rules
+
+4. Semantic tokens only (`bg-background`, `bg-surface`, `text-text-primary`, `border-border`, etc.).
+5. Never use raw Tailwind palette classes (`bg-zinc-900`, `text-gray-500`).
+6. Never use `text-foreground`, `text-muted-foreground`, or `border-error`.
+7. Never use `bg-black/80` for overlays. Use `bg-overlay/80`.
+
+## Container Rules
+
+8. Use glass tiers for containers: `.glass-panel`, `.glass-floating`, or `.glass-overlay`.
+
+## Form Rules
+
+9. Stacked labels only (`Label` above control). Never inline or floating labels.
+
+## Admin UI Rules
+
+10. No arbitrary text sizes (`text-[10px]`, `text-[11px]`). Use `Heading`, `Typography`, or the standard Tailwind scale (`text-xs`, `text-sm`).
+11. No ad-hoc `chat-*` classes. Conversation UIs must compose existing Seed primitives and motion tokens.
+12. Admin chat features must include all three agentic layers:
+    - Conversation: `ConversationThread` or `AgentMessageBubble`
+    - Tooling: `ToolCallCard` or `ThinkingIndicator`
+    - Traceability: `SourceCitation`, `AgentTimeline`, `WorkflowGraph`, or `HandoffIndicator`
+13. Admin sidebar navigation must include IA grouping with `SidebarGroupLabel`. No flat unlabeled menus.
+14. Admin analytics must use Seed chart primitives (`AreaChart`, `BarChart`, `LineChart`, `PieChart`, `ChartContainer`). No pseudo-charts from raw `<div>` bars.
+## Page Composition
+
+16. Page architecture MUST match a `page_intent` from `intent-map.md`.
+17. If an intent is missing from the catalog, stop and report it. Do not improvise.
+18. Routes without a mapped intent + recipe are invalid.
+
+## Brand Customization Rules
+
+19. Always override ALL default copy. Never ship generic English defaults from block components.
+20. Always map brand colors to semantic tokens. Never hardcode hex values in components.
+21. Always verify contrast ratios after color override (WCAG AA: 4.5:1 body, 3:1 large text).
+22. Glass intensity must match brand personality. See `references/brand-override.md` for presets.
+23. Always update `src/site.config.ts` (name, description, tagline, nav) before building pages.
+
+## Dashboard Rules
+
+24. Dashboard KPI cards must use `MetricCard`, not ad-hoc Card + value compositions.
+25. Chart components must not be rendered without an empty-data guard (`data.length > 0` or `ChartCard`).
+26. Chart color configs must use `var(--color-chart-N)` tokens, never hex/rgb/hsl literals.
+27. Import chart primitives from `@vadimcomanescu/nadicode-design-system/charts` or the matching `@vadimcomanescu/nadicode-design-system/charts/<chart-name>` subpath. Do not import `recharts` directly into scaffold app code.
+
+## ESLint Rule Reference
+
+These rules are enforced at lint time (Layer 1):
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `nadicode/no-raw-recharts-import` | error | Direct `recharts` imports outside chart wrappers |
+| `nadicode/require-chart-empty-handler` | error | Chart rendered without data-length guard |
+| `nadicode/no-arbitrary-chart-color` | error | Hex/rgb/hsl in chart config instead of tokens |
+| `nadicode/require-dashboard-loading-skeleton` | warn | Dashboard routes missing Skeleton import |
+| `nadicode/require-stagger-on-metric-grid` | warn | 3+ MetricCard grid without StaggerChildren |
+
+## i18n Test Mocking
+
+The consumer app owns `next-intl` setup, including `src/i18n/request.ts`, locale routing, `NextIntlClientProvider`, `timeZone`, and `now`. Seed only supplies DS message catalogs plus merge helpers.
+
+Consumer tests that render Seed components using `useTranslations` must provide merged messages. Use `mergeSeedMessages()` from `@vadimcomanescu/nadicode-design-system/lib/merge-messages` in `src/i18n/request.ts` to combine package-backed DS catalogs such as `@vadimcomanescu/nadicode-design-system/messages/<locale>` with `messages/<locale>.json` (consumer keys) and pass the result to your test's `NextIntlClientProvider`.
+When a test only needs the Seed theme/provider wrapper, import `SeedTestProvider` from `@vadimcomanescu/nadicode-design-system/test`. The showcase app may keep using `@/test/SeedTestProvider` for in-repo tests.
+Do not copy DS catalog files into the app.
+
+## Done Criteria
+
+All of these must pass before a task is complete:
+
+```bash
+npx tsc --noEmit
+npm run build
+npm run lint
+npm run test
+npm run ds:check
+```