@vadimcomanescu/nadicode-design-system 4.0.10 → 5.0.0

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

@@ -3,8 +3,8 @@ 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-kits, and Next.js App Router integration.
-tags: [seed, design-system, arctic-glow, react, tailwind, radix, glassmorphism, page-kits]
+  dual-axis theming, and Next.js App Router integration.
+tags: [seed, design-system, arctic-glow, react, tailwind, radix, glassmorphism, json-render]
 ---
 
 # Seed Design System -- Agent Skill
@@ -20,7 +20,7 @@ Consumer scaffold contract: brand customization stays palette-only unless the ta
 
 ## Component Discovery
 
-The catalog (`./catalog` and `./catalog/components` subpath exports) is the single surface for discovering and consuming Seed blocks and page-kits.
+The catalog (`./catalog` and `./catalog/components` subpath exports) is the single surface for discovering and consuming Seed catalog blocks.
 
 **Discovery** (server-safe, read this to learn what's available):
 ```ts
@@ -36,13 +36,17 @@ import { seedComponents } from "@vadimcomanescu/nadicode-design-system/catalog/c
 
 Usage:
 ```tsx
-const { LoginBlock, DashboardPageKit } = seedComponents
-<LoginBlock onSubmit={handleLogin} />
+const { LoginBlock, HeroBlock } = seedComponents
+// All catalog components use BaseComponentProps — pass props object and emit callback
+<LoginBlock
+  props={{ type: "login", showSocial: true }}
+  emit={(event) => { if (event === 'submit') handleLogin() }}
+/>
 ```
 
-**Blocks and page-kits** are imported exclusively from `seedComponents`. Do not import them via individual subpath exports (ADR 0009). The ESLint rule `nadicode/require-catalog-import` enforces this at lint time.
+**Catalog blocks** are imported exclusively from `seedComponents`. Do not import them via individual subpath exports (ADR 0009). The ESLint rule `nadicode/require-catalog-import` enforces this at lint time.
 
-**UI primitives** (Button, Heading, Input, etc.), icons, charts, and effects are imported via individual subpath exports. They are not registered in the catalog.
+**Cataloged UI primitives** (Button, Heading, Input, etc.) are consumed through `seedComponents` via the catalog, same as blocks. Icons retain individual subpath exports. Charts are cataloged and consumed through `seedComponents`.
 
 ## Catalog-First Rule (MANDATORY)
 
@@ -50,10 +54,10 @@ const { LoginBlock, DashboardPageKit } = seedComponents
 
 ### The workflow
 
-1. **Check the catalog.** Read `seedComponentDefinitions` keys, descriptions, and props. If a catalog block or page-kit covers >= 70% of the required functionality, USE IT. Pass props, compose with primitives around it, or request missing props upstream.
+1. **Check the catalog.** Read `seedComponentDefinitions` keys, descriptions, and props. If a catalog block covers >= 70% of the required functionality, USE IT. Pass props, compose with primitives around it, or request missing props upstream.
 2. **If the catalog block doesn't fit**, document WHY in a code comment at the top of your new component: `// Catalog: <BlockName> exists but doesn't fit because <reason>`. This makes the gap visible for future DS improvement.
 3. **If no catalog match exists**, build from primitives, but flag the gap: open an issue on the DS repo or leave a `// TODO(catalog-gap): this should be a catalog block` comment.
-4. **Never silently reimplement** a catalog block. The catalog ships 60+ blocks and 20+ page-kits. Reimplementing from primitives what the catalog already offers is wasted work and creates drift.
+4. **Never silently reimplement** a catalog block. The catalog covers all standard block patterns. Reimplementing from primitives what the catalog already offers is wasted work and creates drift.
 
 ### What counts as "block-level"
 
@@ -88,12 +92,13 @@ The catalog is machine-readable, tested, accessible, and themed. Hand-built bloc
 | `#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 |
+| Block with flat `interface *Props` | `BaseComponentProps<SeedProps<'Name'>>` | Flat props removed in v5.0.0 |
+| Required content props | Optional via `props.x ?? default` | Blocks render standalone |
+| `<LoginBlock onSubmit={fn} />` (flat props on catalog blocks) | `<LoginBlock props={{...}} emit={(e) => ...} />` | All catalog blocks use `BaseComponentProps`; flat props removed in v5.0.0 |
 | Inline/floating labels | `Label` above control (stacked) | Form convention |
 | `text-[10px]`, `text-[11px]` | `text-xs`, `text-sm`, `Heading`, `Typography` | No arbitrary text sizes |
 | Ad-hoc `chat-*` classes | Compose Seed primitives + motion tokens | No custom chat classes |
-| `import { BarChart } from "recharts"` | `import { BarChart } from "@vadimcomanescu/nadicode-design-system/charts"` | No direct recharts |
+| `import { BarChart } from "recharts"` | `import { seedComponents } from "@vadimcomanescu/nadicode-design-system/catalog/components"` then `seedComponents.BarChart` | No direct recharts; charts are in the catalog |
 | Ad-hoc Card + value for KPIs | `MetricCard` | Use the DS component |
 | Hex/rgb in chart config | `var(--color-chart-N)` tokens | Chart colors are tokenized |
 | Generic English defaults | Override ALL default copy per brand | No shipping placeholder text |
@@ -109,7 +114,7 @@ Override all default copy. Map brand colors to semantic tokens. Verify contrast
 
 ## Dashboard Rules
 
-KPI cards: `MetricCard`. Charts: empty-data guard required (`data.length > 0`). Chart colors: `var(--color-chart-N)` tokens. Import from `./charts`, never `recharts` directly. Sidebar navigation must include IA grouping with `SidebarGroupLabel`.
+KPI cards: `MetricCard`. Charts: empty-data guard required (`data.length > 0`). Chart colors: `var(--color-chart-N)` tokens. Import charts from `seedComponents`, never `recharts` directly. Sidebar navigation must include IA grouping with `SidebarGroupLabel`.
 
 ## Admin Chat
 
@@ -142,8 +147,8 @@ Token source of truth: `src/lib/tokens.config.js` (authored), `src/index.css` (g
 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"
+import { seedComponents } from "@vadimcomanescu/nadicode-design-system/catalog/components"
+const { Heading, Typography } = seedComponents
 
 <Heading level={1}>Page title</Heading>
 <Heading level={2} size="section">Section title</Heading>
@@ -255,12 +260,12 @@ import { SettingsIcon, BellIcon } from "@vadimcomanescu/nadicode-design-system/i
 
 ### 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` |
+| Tier | Animation | Source |
+|------|-----------|--------|
+| **Hand-crafted** | `motion.path` stroke animations (premium, per-icon) | [lucide-animated.com](https://lucide-animated.com); `sun.tsx` as template |
+| **Factory-wrapped** | 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.
+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.
 
 If an icon is missing, add it to `lucide-wrapped.tsx` via `createAnimatedIcon`. Do not hand-craft local copies to bypass the package contract.
 
@@ -311,7 +316,7 @@ Every page = **Shell > Sections > Components**.
 - 2-8 sections (vertical bands, no nesting)
 - 1-6 components per section via CSS grid/flex
 
-**Page-kits are the default.** Before assembling a page from sections and primitives, check if a `*PageKit` exists in the catalog (ProfileSettingsPageKit, DashboardPageKit, AnalyticsPageKit, etc.). Page-kits are pre-composed, tested, accessible, and themed. Only build a page by hand if no page-kit covers your layout. See the Catalog-First Rule above.
+**Catalog blocks are the building material.** Before assembling a page from primitives, check `seedComponentDefinitions` for existing blocks that cover your need. Pages are composed as json-render `NextAppSpec` JSON specs referencing catalog blocks by name. See the Catalog-First Rule above.
 
 ### Shell Selection
 
@@ -327,7 +332,7 @@ Content widths, vertical rhythm, responsive contracts: `references/composition.m
 
 ### Kanban Board
 
-Compound component via `seedComponents`. Uses `@dnd-kit` internally (no dnd-kit types leak). Card content is consumer-owned. See catalog entry for full props and sub-components. Types: `@vadimcomanescu/nadicode-design-system/kanban-board`.
+Compound component via `seedComponents`. Uses `@dnd-kit` internally (no dnd-kit types leak). Card content is consumer-owned. See catalog entry for full props and sub-components. Types: `@vadimcomanescu/nadicode-design-system/kanban.types`.
 
 ---
 

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

@@ -90,7 +90,7 @@ What is the element?
 
 ## Storyboard Format
 
-Animation storyboard format (use when documenting page-kit entrance sequences):
+Animation storyboard format (use when documenting page entrance sequences):
 
 ```
 ANIMATION STORYBOARD

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

@@ -251,7 +251,7 @@ Mobile (stacked):    Tablet (2 col):         Desktop (3 col):
 - **Agency Home**: Hero -> Logo cloud -> Services grid -> ProcessFlowBlock -> Outcome stats -> Testimonials -> FAQ -> CTA
 - **Digital Workers**: Hero -> AgentProfileGridBlock -> Per-agent deep dives -> WorkflowGraph -> Integrations -> FAQ -> CTA
 - **Service Detail**: Hero -> SolutionShowcaseBlock -> Features -> ProcessFlowBlock -> Stats -> Testimonials -> CTA
-- **About/Team**: Mission hero -> Values (FeatureGridBlock) -> Team (TeamBlock) -> Company stats -> Partners -> CTA
+- **About/Team**: Mission hero -> Values (FeatureBlock variant="grid") -> Team (TeamBlock) -> Company stats -> Partners -> CTA
 - **Contact**: Heading -> ContactBlock -> Company info cards -> FAQ
 - **Settings**: Settings nav -> Profile -> Preferences -> Notifications -> Integrations -> Danger zone
 - **CRUD List**: Header + search -> Filter bar -> Data table -> Pagination

package/.agents/skills/seed/references/glass-and-effects.md

@@ -104,47 +104,38 @@ import { AmbientGrid } from "@vadimcomanescu/nadicode-design-system/ambient-grid
 <AmbientGrid size={32} />  // Custom cell size
 ```
 
-### AuroraEffect
-
-Slow-moving gradient aurora background. Three layered animations at 12-18s cycles.
-
-```tsx
-import { AuroraEffect } from "@vadimcomanescu/nadicode-design-system/aurora-effect"
-<AuroraEffect className="absolute inset-0 -z-10" />
-```
-
 ### MeteorShower
 
-Animated diagonal streak particles.
+Animated diagonal streak particles. Cataloged — use via `seedComponents`.
 
 ```tsx
-import { MeteorShower } from "@vadimcomanescu/nadicode-design-system/meteor-shower"
-<MeteorShower count={20} />
+import { seedComponents } from "@vadimcomanescu/nadicode-design-system/catalog/components"
+<seedComponents.MeteorShower props={{ count: 20 }} emit={() => {}} on={{}} />
 ```
 
 ### MouseSpotlight
 
-Mouse-following spotlight radial gradient.
+Mouse-following spotlight radial gradient. Cataloged — use via `seedComponents`.
 
 ```tsx
-import { MouseSpotlight } from "@vadimcomanescu/nadicode-design-system/mouse-effect"
-<MouseSpotlight className="...">Content</MouseSpotlight>
+import { seedComponents } from "@vadimcomanescu/nadicode-design-system/catalog/components"
+<seedComponents.MouseSpotlight props={{ color: "teal", size: 300 }} emit={() => {}} on={{}}>Content</seedComponents.MouseSpotlight>
 ```
 
 ### AnimatedBackground
 
-CSS animated gradient background.
+CSS animated gradient background. Cataloged — use via `seedComponents`.
 
 ```tsx
-import { AnimatedBackground } from "@vadimcomanescu/nadicode-design-system/animated-background"
-<AnimatedBackground />
+import { seedComponents } from "@vadimcomanescu/nadicode-design-system/catalog/components"
+<seedComponents.AnimatedBackground props={{}} emit={() => {}} on={{}} />
 ```
 
 ### Other Effect Components
 
 | Component | Purpose |
 |-----------|---------|
-| MouseEffect | Mouse-tracking visual feedback |
+| MouseGlow | Mouse-tracking dot-grid overlay (cataloged) |
 | MovingBorder | Animated border rotation |
 | ProgressiveBlur | Gradient blur transition |
 | TiltCard | 3D perspective tilt on hover |
@@ -155,7 +146,12 @@ import { AnimatedBackground } from "@vadimcomanescu/nadicode-design-system/anima
 
 ## Text Effect Components
 
-All in `@vadimcomanescu/nadicode-design-system/text-effects/`.
+All 9 text effect components are catalog primitives. Import via `seedComponents`:
+
+```tsx
+import { seedComponents } from "@vadimcomanescu/nadicode-design-system/catalog/components"
+// Use: <seedComponents.TextReveal props={{ text: "..." }} emit={() => {}} on={{}} />
+```
 
 | Component | Effect | Key Props |
 |-----------|--------|-----------|
@@ -190,7 +186,6 @@ All in `@vadimcomanescu/nadicode-design-system/text-effects/`.
 | Avatar3D | 3D avatar using Three.js | `state`, custom 3D options |
 | AgentStatus | Connection status indicator | `status: "connected" \| "disconnected" \| "connecting"` |
 | AudioWaveform | Real-time audio level visualization | `audioData`, `isActive` |
-| ConversationThread | Chat message list with roles | `messages`, `isStreaming` |
 
 Agent animations use `--color-primary` (not accent) for glow effects:
 

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

@@ -291,47 +291,42 @@ Key points:
 
 ## Pattern 4: Block Composition (LoginBlock)
 
-Blocks compose UI primitives into page-ready sections.
+Blocks compose UI primitives into page-ready sections. All catalog blocks use `BaseComponentProps<SeedProps<'BlockName'>>` from `@json-render/react`.
 
 ```tsx
-import React from "react"
+'use client'
+
+import { type BaseComponentProps } from '@json-render/react'
+import { type SeedProps } from '@/catalog/catalog'
 import { Button } from "../ui/Button"
-import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "../ui/Card"
+import { Card, CardContent, CardDescription, CardHeader } from "../ui/Card"
 import { Input } from "../ui/Input"
-import { Label } from "../ui/Label"
-import { GoogleIcon } from "../ui/BrandIcons"
-import { cn } from "../../lib/utils"
-
-interface LoginBlockProps {
-  className?: string
-  type?: "login" | "signup"
-  showSocial?: boolean
-  title?: string
-  description?: string
-  onLogin?: (e: React.FormEvent) => void
-}
+import { Field, FieldLabel } from "../ui/Field"
+import { GoogleIcon, MicrosoftIcon } from "../ui/BrandIcons"
+import { StaggerChildren } from "../ui/StaggerChildren"
+import { Heading } from "../ui/Heading"
+import { cn } from '@/lib/utils'
+
+const FIELD_STAGGER_MS = 50
+
+export function LoginBlock({ props, emit }: BaseComponentProps<SeedProps<'LoginBlock'>>) {
+  const type = props.type ?? "login"
+  const showSocial = props.showSocial ?? true
+  const error = props.error ?? null
 
-export function LoginBlock({
-  className,
-  type = "login",
-  showSocial = true,
-  title,
-  description,
-  onLogin,
-}: LoginBlockProps) {
-  const defaultTitle = type === "login" ? "Welcome back" : "Create an account"
+  const resolvedTitle = type === "login" ? "Welcome back" : "Create an account"
   const buttonText = type === "login" ? "Sign In" : "Sign Up"
 
   return (
-    <Card className={cn("w-full max-w-[400px] border-border/50", className)}>
+    <Card className={cn("w-full max-w-[400px] border-border/50")}>
       <CardHeader className="space-y-1">
-        <CardTitle className="text-2xl text-center">{title || defaultTitle}</CardTitle>
+        <Heading level={2} size="section" className="text-center">{resolvedTitle}</Heading>
         <CardDescription className="text-center">...</CardDescription>
       </CardHeader>
       <CardContent className="grid gap-4">
-        {showSocial && (
+        {!!showSocial && (
           <>
-            <Button variant="outline" className="w-full ...">
+            <Button type="button" variant="outline" className="w-full" onClick={() => emit('socialLogin')}>
               <GoogleIcon className="h-5 w-5" />
               <span>Continue with Google</span>
             </Button>
@@ -342,32 +337,37 @@ export function LoginBlock({
             </div>
           </>
         )}
-        <form onSubmit={onLogin} className="grid gap-4">
-          <div className="grid gap-2">
-            <Label htmlFor="email">Email address</Label>
-            <Input id="email" type="email" placeholder="name@example.com" />
+        {!!error && (
+          <div id="login-error" role="alert" className="rounded-md border border-destructive/50 bg-destructive/10 px-4 py-3 text-sm text-destructive">
+            {error}
           </div>
-          <div className="grid gap-2">
-            <Label htmlFor="password">Password</Label>
-            <Input id="password" type="password" />
-          </div>
-          <Button className="w-full bg-accent hover:bg-accent/90">{buttonText}</Button>
+        )}
+        <form onSubmit={(e) => { e.preventDefault(); emit('submit') }} className="grid gap-4">
+          <StaggerChildren staggerMs={FIELD_STAGGER_MS} className="grid gap-4">
+            <Field>
+              <FieldLabel htmlFor="email">Email address</FieldLabel>
+              <Input id="email" type="email" required placeholder="name@example.com" />
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="password">Password</FieldLabel>
+              <Input id="password" type="password" required />
+            </Field>
+            <Button type="submit" className="w-full bg-accent hover:bg-accent/90">{buttonText}</Button>
+          </StaggerChildren>
         </form>
       </CardContent>
-      <CardFooter>
-        <p className="text-center text-sm text-text-tertiary">
-          Don't have an account? <a href="#" className="text-accent">Create account</a>
-        </p>
-      </CardFooter>
     </Card>
   )
 }
 ```
 
 Key points:
-- Blocks don't need a `ref` prop (not primitives)
-- Always accept `className` for placement flexibility
-- Compose multiple UI primitives (Card, Button, Input, Label)
-- Props control behavior variants (type, showSocial), not visual variants
-- Naming convention: `*Block.tsx` suffix
+- `'use client'` directive required (blocks use browser APIs and event handlers)
+- Blocks use `BaseComponentProps<SeedProps<'BlockName'>>`, no flat props interface
+- Access data as `props.x ?? default`, never top-level destructuring
+- Fire callbacks with `emit('eventName')` where event name matches catalog `events` array
+- Use `Field` + `FieldLabel` (not bare `Label`), `Heading` (not `CardTitle`)
+- `StaggerChildren` for entrance animation on form fields
+- No `ref` prop (blocks are not primitives)
 - Semantic tokens only (`text-text-tertiary`, `bg-border/50`, `bg-accent`)
+- Naming convention: `*Block.tsx` suffix

package/.agents/skills/seed/references/state-machines.md

@@ -42,7 +42,7 @@ Expected wait time?
   < 1 second -> Skeleton (matches content shape)
   1-3 seconds -> Spinner with optional message
   3+ seconds -> Progress bar (determinate or indeterminate)
-  Unknown/streaming -> StreamingText or ThinkingIndicator
+  Unknown/streaming -> StreamingText or ChatThinkingMessage
 ```
 
 | Tier | Component | When |
@@ -205,29 +205,30 @@ function MyForm() {
 |-------|-----------|--------|
 | `idle` | Empty conversation | `Empty` with "Start a conversation" |
 | `connected` | Ready for input | Active composer with send button |
-| `streaming` | Receiving tokens | `StreamingText` in `AgentMessageBubble` |
-| `thinking` | Agent processing | `ThinkingIndicator` (pulsing dots) |
-| `tool-calling` | Tool execution | `ToolCallCard` with status (running/complete/error) |
+| `streaming` | Receiving tokens | `StreamingText` in `ChatMessage` + `ChatMessageContent isStreaming` |
+| `thinking` | Agent processing | `ChatThinkingMessage variant="pill"` (pulsing dots) |
+| `tool-calling` | Tool execution | `ChatToolCall` with state (input-available/output-available/output-error) |
 | `approval-needed` | Awaiting user | `ApprovalCard` with approve/reject buttons |
 | `error` | Agent/connection error | Error alert with retry |
 
 ### Streaming Implementation
 
 ```tsx
-<AgentMessageBubble
-  role="assistant"
-  content={streamingContent}  // Updates as tokens arrive
-  isStreaming={isStreaming}     // Shows cursor when true
-/>
-
-<ToolCallCard
-  name="search_files"
-  args={{ query: "utils.ts" }}
-  status="running"  // "running" | "complete" | "error"
-  result={toolResult}
-/>
-
-<ThinkingIndicator />  // Animated dots
+<ChatMessage role="assistant">
+  <ChatMessageContent isStreaming={isStreaming}>
+    {streamingContent}  {/* Updates as tokens arrive; shows cursor when isStreaming */}
+  </ChatMessageContent>
+</ChatMessage>
+
+<ChatToolCall state="input-available">  {/* input-available | output-available | output-error */}
+  <ChatToolCallHeader name="search_files" />
+  <ChatToolCallContent>
+    <ChatToolCallInput>{JSON.stringify({ query: "utils.ts" }, null, 2)}</ChatToolCallInput>
+    {toolResult && <ChatToolCallOutput>{toolResult}</ChatToolCallOutput>}
+  </ChatToolCallContent>
+</ChatToolCall>
+
+<ChatThinkingMessage variant="pill" />  {/* Animated dots; variant="dots" for inline */}
 ```
 
 ---

package/README.md

@@ -15,7 +15,9 @@ The dev server runs on `http://localhost:5001` and serves the showcase routes un
 
 Consumer apps install Seed through an exact released package version. For unpublished local work, stage a tarball under `.nadicode/packages/` and install that committed relative artifact instead. Do not point apps at a live DS repo directory.
 
-Component discovery and consumption go through the catalog. Blocks and page-kits have no individual subpath exports.
+Component discovery and consumption go through the catalog. Catalog blocks have no individual subpath exports.
+
+All catalog components implement `BaseComponentProps<SeedProps<'Name'>>` from `@json-render/react`. Consumer apps wire `defineCatalog()` (from `@json-render/core`) and `defineRegistry()` (from `@json-render/react`) to render pages from JSON specs. See `JSON_RENDER_MIGRATION.md` for the full consumer wiring pattern.
 
 Canonical consumer docs: