@vadimcomanescu/nadicode-design-system 2.0.0

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

@@ -0,0 +1,292 @@
+# Animation
+
+Central animation infrastructure built on `motion/react` and custom tokens.
+
+## Core Files
+
+| File | Purpose |
+|------|---------|
+| `src/lib/animation.tokens.ts` | Easing curves, duration scale, spring configs, style presets |
+| `src/lib/motion.ts` | Motion variants, spring presets, stagger, useStyleMotion, reduced motion |
+| `tailwind.config.js` | Tailwind keyframes and animation utilities |
+| `src/index.css` | CSS keyframes and `prefers-reduced-motion` |
+
+---
+
+## Spring Presets
+
+### Arctic (precise, controlled)
+
+| Name | Stiffness | Damping | Mass | Use For |
+|------|-----------|---------|------|---------|
+| `snappy` | 400 | 28 | 0.8 | Micro-interactions, tooltips, badges |
+| `gentle` | 200 | 20 | 1.0 | Page transitions, slide-ins |
+| `bouncy` | 300 | 14 | 0.8 | Playful UI, celebratory moments |
+| `dramatic` | 500 | 24 | 1.2 | Hero entrances, major reveals |
+
+### Bloom (softer, bouncier, more playful)
+
+| Name | Stiffness | Damping | Mass | Use For |
+|------|-----------|---------|------|---------|
+| `snappy` | 300 | 16 | 0.6 | Micro-interactions |
+| `gentle` | 150 | 12 | 0.8 | Transitions |
+| `bouncy` | 200 | 8 | 0.5 | Playful UI |
+| `dramatic` | 250 | 8 | 0.6 | Hero entrances |
+| `wobbly` | 180 | 6 | 0.4 | Extra-playful (bloom-only) |
+
+```tsx
+import { motionSpring } from "@/lib/motion"
+<motion.div animate={{ opacity: 1 }} transition={motionSpring.snappy} />
+```
+
+### Spring Selection Guide
+
+```
+What is the element?
+  Micro-interaction (tooltip, badge, toggle)?  -> snappy
+  Page or panel transition?                    -> gentle
+  Celebration or success?                      -> bouncy
+  Major reveal or hero entrance?               -> dramatic
+  Bloom style, extra playful?                  -> wobbly (bloom only)
+```
+
+---
+
+## Duration Scale
+
+| Token | Value | Tailwind Class | Use For |
+|-------|-------|----------------|---------|
+| `micro` | 100ms | `duration-micro` | Micro-feedback (ripples) |
+| `fast` | 150ms | `duration-fast` | Hover states, toggles |
+| `normal` | 200ms | `duration-normal` | Standard transitions |
+| `moderate` | 250ms | `duration-moderate` | Medium elements |
+| `slow` | 300ms | `duration-slow` | Large/prominent elements |
+
+---
+
+## Easing Curves
+
+### Ease-Out (user-initiated: dropdowns, modals, tooltips)
+
+| Name | CSS | Tailwind |
+|------|-----|----------|
+| `out-quad` | `cubic-bezier(0.25, 0.46, 0.45, 0.94)` | `ease-out-quad` |
+| `out-cubic` | `cubic-bezier(0.215, 0.61, 0.355, 1)` | `ease-out-cubic` |
+| `out-quart` | `cubic-bezier(0.165, 0.84, 0.44, 1)` | `ease-out-quart` |
+| `out-quint` | `cubic-bezier(0.23, 1, 0.32, 1)` | `ease-out-quint` |
+| `out-expo` | `cubic-bezier(0.19, 1, 0.22, 1)` | (token only) |
+
+### Ease-In-Out (morphing, elements already on screen)
+
+| Name | CSS | Tailwind |
+|------|-----|----------|
+| `in-out-quad` | `cubic-bezier(0.455, 0.03, 0.515, 0.955)` | (token only) |
+| `in-out-cubic` | `cubic-bezier(0.645, 0.045, 0.355, 1)` | `ease-in-out-cubic` |
+| `in-out-quart` | `cubic-bezier(0.77, 0, 0.175, 1)` | `ease-in-out-quart` |
+
+**Default:** `ease-out-cubic` for enters/opens, `ease-in-out-cubic` for morphing.
+
+---
+
+## Storyboard Format
+
+Every recipe includes an animation storyboard:
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 600ms | SPRING: snappy (default) | REDUCED: opacity-only
+
+T+0ms     [shell]     Frame visible (instant, no animation)
+T+0ms     [ambient]   Background effects begin (if any)
+T+50ms    [header]    Page title fades in          {fadeInUp, snappy}
+T+130ms   [kpi-1]     First KPI card enters        {fadeInUp, snappy}
+T+210ms   [kpi-2]     Second KPI card enters       {fadeInUp, snappy}
+T+530ms   [activity]  Activity section enters      {fadeIn, gentle}
+
+SCROLL-TRIGGERED (below fold):
+[testimonials]  ScrollFadeIn when 20% visible     {fadeInUp, snappy}
+```
+
+- `T+Nms` -- time offset from page mount
+- `[label]` -- element identifier (matches recipe section names)
+- `{variant, spring}` -- motion variant and spring preset from `@/lib/motion`
+- `BUDGET` -- total entrance animation time
+- `REDUCED` -- behavior when `prefers-reduced-motion` is active
+
+---
+
+## Timing Budgets
+
+| Page Type | Above-fold Budget | Below-fold |
+|-----------|-------------------|------------|
+| App (dashboard, settings, CRUD) | 400-600ms | ScrollFadeIn |
+| Marketing (landing, pricing) | 800-1200ms | ScrollFadeIn |
+| Auth (login, signup) | 300-400ms | N/A |
+| Error (404, 500) | 200-300ms | N/A |
+
+---
+
+## Stagger Rules
+
+| Pattern | Delay | Max Items | Distance | Spring |
+|---------|-------|-----------|----------|--------|
+| `blockStagger` | 80ms | 8 | 24px up | snappy |
+| `heroStagger` | 100ms | 5 | 36px up | gentle |
+| KPI cards | 80ms | 4 | 24px up | snappy |
+| Feature cards | 100ms | 6 | 24px up | snappy |
+| Table rows | 40ms | 10 | 12px up | snappy |
+| Nav items | 50ms | 8 | 16px left | snappy |
+
+- **Max stagger chain**: 8 items. Beyond 8, group items and stagger groups.
+- **Min delay**: 50ms (below this, items blur together).
+- **Max delay**: 120ms (beyond this, sequence feels disconnected).
+
+---
+
+## Entrance Choreography Patterns
+
+### Header-First (App Pages)
+
+```
+T+0ms     Shell + nav (instant)
+T+50ms    Page title + breadcrumb
+T+130ms   Control bar (filters, actions)
+T+200ms   Primary content (stagger if grid)
+T+400ms   Secondary content
+```
+
+### Hero-Cascade (Marketing Pages)
+
+```
+T+0ms     Nav bar (instant)
+T+100ms   Hero headline (fadeInUp, dramatic)
+T+250ms   Hero subtitle
+T+400ms   Hero CTA buttons
+T+600ms   Hero visual/image (scaleIn, gentle)
+T+800ms   Trust logos (fadeIn, snappy)
+```
+
+### Center-Focus (Auth/Modals)
+
+```
+T+0ms     Background/split panel (instant)
+T+100ms   Card scales in (scaleIn, gentle)
+T+200ms   Form fields stagger (blockStagger, 60ms)
+T+350ms   CTA button (fadeIn, snappy)
+```
+
+### Streaming (Agent/Chat)
+
+```
+T+0ms     Shell + panels (instant)
+T+50ms    Message history fades in (fadeIn)
+T+0ms     New messages: slide up from bottom (slideInUp, snappy)
+T+0ms     Tool calls: expand in-place (accordion, gentle)
+T+0ms     Thinking: pulse animation (continuous)
+```
+
+---
+
+## `useStyleMotion()` Hook
+
+Style-aware animation values that adapt to arctic vs bloom:
+
+```tsx
+import { useStyleMotion } from "@/lib/motion"
+const { spring, distance, scale, blur, style } = useStyleMotion()
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `spring` | Arctic or Bloom spring configs | Style-specific spring presets |
+| `distance` | `{ sm, md, lg }` in px | Animation travel distances |
+| `scale` | `{ subtle, normal }` | Starting scales (animate to 1.0) |
+| `blur` | `{ subtle, normal }` in px | Blur amounts for reveal effects |
+| `style` | `'arctic' \| 'bloom'` | Current active style |
+
+### Style Comparison
+
+| Property | Arctic | Bloom |
+|----------|--------|-------|
+| `distance.sm` | 16px | 20px |
+| `distance.md` | 32px | 40px |
+| `distance.lg` | 56px | 72px |
+| `scale.subtle` | 0.90 | 0.85 |
+| `scale.normal` | 0.80 | 0.70 |
+| `blur.subtle` | 4px | 6px |
+| `blur.normal` | 8px | 12px |
+
+Components using `useStyleMotion()` or `useTheme()` require `ThemeProvider` in tests.
+
+---
+
+## Pre-Built Motion Variants
+
+Import from `@/lib/motion`:
+
+| Variant | Initial State | Spring |
+|---------|---------------|--------|
+| `fadeIn` | `opacity: 0` | snappy |
+| `fadeInUp` | `opacity: 0, y: 32, blur: 4px` | snappy |
+| `fadeInDown` | `opacity: 0, y: -32, blur: 4px` | snappy |
+| `scaleIn` | `opacity: 0, scale: 0.85, blur: 6px` | snappy |
+| `slideInLeft` | `opacity: 0, x: -30` | gentle |
+| `slideInRight` | `opacity: 0, x: 30` | gentle |
+
+```tsx
+<motion.div {...fadeInUp}>Content</motion.div>
+```
+
+---
+
+## Reduced Motion
+
+Three layers of protection:
+
+1. **Global CSS** (`index.css`): Forces `animation-duration: 0.01ms`, `transition-duration: 0.01ms`
+2. **`useMotionConfig()`**: Returns `{ duration: 0.01 }` when reduced motion preferred
+3. **`useReducedMotion()`** from `motion/react`: Boolean flag
+
+When `prefers-reduced-motion` is active:
+- Spring animations overridden to instant
+- Stagger delay set to 0 (all items appear simultaneously)
+- ScrollFadeIn elements visible immediately
+- Continuous animations (aurora, shimmer, meteor) paused via CSS
+
+Every recipe storyboard includes a `REDUCED` line specifying fallback behavior.
+
+---
+
+## Tailwind Animation Utilities
+
+| Tailwind Class | Animation | Duration/Timing |
+|----------------|-----------|-----------------|
+| `animate-fade-in` | Opacity 0 -> 1 | 200ms ease-out-cubic |
+| `animate-fade-in-up` | Opacity 0 + translateY(8px) | 200ms ease-out-cubic |
+| `animate-scale-in` | Opacity 0 + scale(0.95) | 200ms ease-out-cubic |
+| `animate-blur-reveal` | Opacity 0 + blur(8px) | 300ms ease-out-cubic |
+| `animate-accordion-down` | Height 0 -> auto | 200ms ease-out |
+| `animate-accordion-up` | Height auto -> 0 | 150ms ease-out |
+| `animate-cursor-blink` | Opacity blink | 1s step-end infinite |
+| `animate-gradient-sweep` | Background position sweep | 8s linear infinite |
+| `animate-border-spin` | Border rotation | 3s linear infinite |
+| `animate-meteor` | Diagonal streak | var(--meteor-duration, 2s) |
+| `animate-aurora-1/2/3` | Slow ambient drift | 12-18s ease-in-out infinite |
+| `animate-shimmer` | Horizontal shimmer | 2s linear infinite |
+| `animate-scroll-vertical` | Vertical scroll | var(--duration, 40s) linear |
+
+---
+
+## Z-Index Scale
+
+| Tailwind Class | Value | Use For |
+|----------------|-------|---------|
+| `z-base` | 0 | Default stacking |
+| `z-dropdown` | 50 | Dropdowns, selects |
+| `z-sticky` | 100 | Sticky headers, toolbars |
+| `z-overlay` | 200 | Modal backdrops, overlays |
+| `z-modal` | 300 | Modal/dialog content |
+| `z-popover` | 400 | Popovers, tooltips |
+| `z-toast` | 500 | Toast notifications |
+| `z-max` | 999 | Maximum z-index (rare) |

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

@@ -0,0 +1,122 @@
+# Blocks Catalog
+
+All blocks live in `src/components/blocks/`. Import via `@vadimcomanescu/nadicode-design-system/block-name`.
+Blocks are pre-composed page sections built from Seed UI primitives.
+Run `npm run docs:inventory` for the current filesystem-backed list.
+
+## Auth Flow
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| LoginBlock | Email/password login with social OAuth | `type`, `variant`, `showSocial`, `title`, `description`, `onLogin`, `googleAction`, `forgotPasswordHref`, `signUpHref`, `signInHref` |
+| SignUpBlock | Registration form | `onSubmit`, `showSocial` |
+| PasswordRecoveryBlock | Password reset request | `onSubmit` |
+| ResetPasswordBlock | New password entry (from email link) | `onSubmit` |
+| TwoFactorChallengeBlock | 2FA code entry challenge | `onVerify` |
+| TwoFactorSetupBlock | 2FA setup with QR code | `qrCodeUrl`, `secret` |
+| AccountLockedBlock | Account locked notification | `onContact`, `reason` |
+| AuthSuccessBlock | Generic auth success state | `title`, `description`, `onContinue` |
+| AuthLayout | Split-screen auth layout wrapper | `children` |
+
+## Marketing
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| HeroBlock | Full hero with gradient text | `title`, `subtitle`, `cta` |
+| HeroSectionBlock | Alternate hero layout | `title`, `description`, `actions` |
+| FeatureBlock | Single feature showcase | `title`, `description`, `icon` |
+| FeatureGridBlock | Multi-feature grid layout | `features: Array<{title, description, icon}>` |
+| PricingBlock | Pricing cards comparison | `plans: Array<Plan>` |
+| TestimonialsBlock | Customer testimonial carousel/grid | `testimonials: Array<Testimonial>` |
+| CallToActionBlock | Call-to-action section | `title`, `description`, `action` |
+| FAQBlock | FAQ accordion | `items: Array<{question, answer}>` |
+| ComparisonBlock | Side-by-side feature comparison | `items` |
+| SocialProofBlock | Social proof metrics/logos | `metrics`, `logos` |
+| StatsMarketingBlock | Marketing statistics display | `stats: Array<{label, value}>` |
+| LogoCloud | Partner/client logo grid | `logos: Array<{src, alt}>` |
+| ProcessFlowBlock | "How it works" numbered step sequence | `steps: Array<{title, description, icon?}>`, `badge?` |
+| AgentProfileGridBlock | Agent/worker profile card grid ("Meet your AI team") | `agents: Array<{name, role, description, avatar, capabilities?, status?}>`, `columns?` |
+| SolutionShowcaseBlock | Problem → Solution → Output narrative with color-coded arc | `sections: Array<{label, title, description, bullets}>`, `badge?` |
+
+## Navigation
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| HeaderBlock | Site header with nav links | `logo`, `links`, `actions` |
+| FooterBlock | Site footer with link columns | `columns`, `social`, `legal` |
+| BannerBlock | Top-of-page promotional banner | `message`, `action`, `dismissible` |
+| NotFoundBlock | 404 page content | `title`, `description`, `action` |
+| NavUser | Sidebar user menu with dropdown | `user: {name, email, avatar?}`, `items?`, `footer?` |
+
+## Dashboard & Data
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| StatsBlock | KPI statistics cards | `stats: Array<{label, value, change}>` |
+| ChartBlock | Single chart container | `title`, `chart`, `description` |
+| ChartCollectionBlock | Multiple chart grid | `charts: Array<ChartConfig>` |
+| BarChartBlock | Pre-configured bar chart | `data`, `title` |
+| InteractiveAreaChartBlock | Zoomable/interactive area chart | `data`, `title` |
+| HeatmapChartBlock | Heatmap visualization | `data`, `title` |
+| UsageDonutBlock | Usage/quota donut chart | `used`, `total`, `label` |
+| DataGridBlock | Data grid/table block | `columns`, `data` |
+| ActivityFeedBlock | Activity/event timeline | `activities: Array<Activity>` |
+| CodeBlock | Syntax-highlighted code display | `code`, `language`, `title` |
+
+## Application
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| SettingsLayout | Settings page with nav sidebar | `sections`, `children` |
+| ChatLayout | Chat application layout | `messages`, `onSend` |
+| OnboardingBlock | Multi-step onboarding wizard | `steps: Array<Step>` |
+| WizardBlock | Generic step-by-step wizard | `steps`, `onComplete` |
+| CreateBlock | Entity creation form | `fields`, `onSubmit` |
+| DirectoryBlock | User/item directory with search | `items`, `onSearch` |
+| ChangelogBlock | Version changelog display | `entries: Array<ChangelogEntry>` |
+| IntegrationsBlock | Integration marketplace grid | `integrations: Array<Integration>` |
+| ContactBlock | Contact form | `onSubmit` |
+
+## Content & Media
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| GalleryBlock | Image/media gallery grid | `items: Array<GalleryItem>` |
+| AudioVisualizerBlock | Audio visualization display | `audioSrc` |
+| NewsletterBlock | Email newsletter signup | `onSubscribe` |
+
+## User
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| TeamBlock | Team members grid with roles/avatars | `members: Array<Member>` |
+| InviteUserModal | Invite user flow modal | `onInvite?`, `onInvited?` |
+
+## AI/Voice
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| VoiceAgentCard | AI voice agent interface card | `agent`, `state`, `selected?`, `onSelect?` |
+
+## Agentic
+
+| Block | Purpose | Key Props |
+| --- | --- | --- |
+| AgentConversationBlock | Agent conversation UI (messages, tool calls, thinking) | `messages: ConversationMessage[]` |
+
+## Usage Pattern
+
+Blocks accept `className` for placement and compose Seed UI primitives:
+
+```tsx
+import { LoginBlock } from "@vadimcomanescu/nadicode-design-system/login-block"
+import { HeroBlock } from "@vadimcomanescu/nadicode-design-system/hero-block"
+
+<div className="flex items-center justify-center min-h-dvh">
+  <LoginBlock type="login" showSocial />
+</div>
+
+<HeroBlock title="Ship faster with Seed" subtitle="Production-ready components" />
+```
+
+Blocks are `"use client"` in Next.js (they contain event handlers, state, or Radix primitives).

package/.agents/skills/seed/references/brand-override.md

@@ -0,0 +1,140 @@
+# Brand Override Guide
+
+This guide is for **seeded consumer apps that want to stay on the Seed update path**.
+
+The contract is intentionally narrow:
+
+- brand customization is **palette-only**
+- the only normal consumer-owned branding file is `seed-palette.css` in the app `src/` root
+- everything else stays package-owned unless you are doing explicit DS development
+
+If a team wants to change typography, motion, component shape, asset pipelines, or register a new style axis, that is no longer “brand override.” That is design-system extension work and should be handled deliberately in the DS itself.
+
+## Allowed Surface
+
+Edit only:
+
+- `seed-palette.css` in the app `src/` root
+
+Do not edit for normal brand customization:
+
+- `@vadimcomanescu/nadicode-design-system/tokens.css` (package baseline)
+- `src/lib/tokens.config.js`
+- `tailwind.config.js`
+- `src/app/layout.tsx`
+- `src/app/fonts/**`
+- `src/lib/motion.ts`
+- `src/lib/animation.tokens.ts`
+
+Why this boundary exists:
+
+- updates stay deterministic
+- app branding stays isolated
+- consumers do not drift into DS-owned token families
+- `ds:update` can keep updating the package instead of diffing arbitrary brand edits
+
+## Canonical Selector Model
+
+Use class-based selectors only:
+
+```css
+:root {
+  /* light / base palette */
+}
+
+:root.dark {
+  /* dark palette */
+}
+
+:root.bloom {
+  /* optional bloom-specific light palette overrides */
+}
+```
+
+Do not use:
+
+- `[data-theme=...]`
+- `.dark` without `:root`
+- `.bloom` without `:root`
+
+`npm run ds:check` rejects the `data-theme` pattern because Seed theme switching is class-based.
+
+## What Counts As A Brand Token
+
+In the current scaffold contract, brand tokens are **color tokens only**.
+
+Typical brand-facing variables include:
+
+| Role | Example variables |
+|------|-------------------|
+| Core page colors | `--color-background`, `--color-surface`, `--color-surface-hover`, `--color-surface-active`, `--color-surface-raised` |
+| Text colors | `--color-text-primary`, `--color-text-secondary`, `--color-text-tertiary` |
+| Border colors | `--color-border`, `--color-border-hover`, `--color-border-subtle` |
+| Action colors | `--color-primary`, `--color-primary-foreground`, `--color-secondary`, `--color-accent`, `--color-accent-foreground` |
+| Status colors | `--color-success`, `--color-warning`, `--color-info`, `--color-destructive` |
+| Optional data viz colors | `--chart-1` through `--chart-6`, sidebar color vars if the app uses them |
+
+If a token is not a color token, treat it as upstream-managed unless the DS explicitly broadens the contract.
+
+## Example
+
+```css
+/* src/seed-palette.css */
+:root {
+  --color-background: 248 250 252;
+  --color-surface: 255 255 255;
+  --color-surface-hover: 241 245 249;
+  --color-border: 203 213 225;
+  --color-text-primary: 15 23 42;
+  --color-text-secondary: 71 85 105;
+  --color-primary: 79 70 229;
+  --color-primary-foreground: 255 255 255;
+  --color-accent: 14 165 233;
+  --color-accent-foreground: 255 255 255;
+}
+
+:root.dark {
+  --color-background: 15 17 20;
+  --color-surface: 21 23 25;
+  --color-surface-hover: 28 31 34;
+  --color-border: 58 63 69;
+  --color-text-primary: 248 250 252;
+  --color-text-secondary: 203 213 225;
+  --color-primary: 99 102 241;
+  --color-primary-foreground: 255 255 255;
+  --color-accent: 56 189 248;
+  --color-accent-foreground: 15 17 20;
+}
+
+:root.bloom {
+  --color-primary: 225 29 72;
+  --color-accent: 249 115 22;
+}
+```
+
+Palette overrides are allowed to replace Bloom colors completely. Bloom remains a style axis, not a protected color pack.
+
+## Verification
+
+Run the full gate after changing palette tokens:
+
+```bash
+npm run ds:check
+npm run lint
+npx tsc --noEmit
+npm run build
+```
+
+After color work, also do a visual pass in light, dark, and bloom where applicable.
+
+## If The Brand Needs More Than Palette
+
+Treat these as explicit DS tasks, not normal consumer branding:
+
+- swapping away from Satoshi
+- changing spacing/radius/shadow systems
+- changing motion presets or timing tokens
+- introducing a new style axis beyond `arctic` / `bloom`
+- changing component structure or visual effects globally
+
+That work belongs in `nadicode-design-system`, with matching updates to the package contract, `scripts/ds-check.mjs`, tests, and docs.