@vadimcomanescu/nadicode-design-system 4.0.3 → 4.0.5

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

@@ -44,11 +44,30 @@ const { LoginBlock, DashboardPageKit } = seedComponents
 
 **UI primitives** (Button, Heading, Input, etc.), icons, charts, and effects are imported via individual subpath exports. They are not registered in the catalog.
 
+## Catalog-First Rule (MANDATORY)
+
+**Before creating any block-level or page-level component, you MUST query `seedComponentDefinitions` for an existing match.** This is non-negotiable.
+
+### 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.
+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.
+
+### What counts as "block-level"
+
+Any component that composes 3+ Seed primitives into a reusable unit (a form section, a settings card, a data display, a modal with form fields). If you're importing Button + Card + Input + Dialog into one component, you're building a block. Check the catalog first.
+
+### Why this matters
+
+The catalog is machine-readable, tested, accessible, and themed. Hand-built blocks skip all of that. Every reimplemented block is a maintenance burden that drifts from the DS over time.
+
 ## Read Order
 
 1. **This file** -- router, quick references, forbidden patterns, binary rules
-2. **catalog** (`@vadimcomanescu/nadicode-design-system/catalog`) -- machine-readable component metadata (variants, props, tiers)
-3. **`references/`** -- deep dives as needed
+2. **catalog** (`@vadimcomanescu/nadicode-design-system/catalog`) -- machine-readable component metadata; ALWAYS check before building
+3. **`references/`** -- deep dives for custom composition (only after confirming catalog doesn't cover your need)
 
 ---
 
@@ -79,6 +98,8 @@ const { LoginBlock, DashboardPageKit } = seedComponents
 | 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 |
 | Hardcoded hex in components | Map to semantic tokens | Brand colors via tokens only |
+| Building a block from 3+ primitives without checking catalog | Query `seedComponentDefinitions` first, use catalog block | Catalog-First Rule |
+| Reimplementing a catalog block locally | `const { BlockName } = seedComponents` | Prevents drift and wasted work |
 
 ---
 
@@ -290,7 +311,7 @@ Every page = **Shell > Sections > Components**.
 - 2-8 sections (vertical bands, no nesting)
 - 1-6 components per section via CSS grid/flex
 
-Page-kits in the catalog ARE the ready-made compositions. Use `seedComponents.<Name>PageKit` from `@vadimcomanescu/nadicode-design-system/catalog/components` rather than assembling pages by hand.
+**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.
 
 ### Shell Selection
 

package/dist/catalog/catalog.d.ts

@@ -39,6 +39,22 @@ export declare const seedComponentDefinitions: {
         events: string[];
         description: string;
     };
+    ApiKeysBlock: {
+        props: z.ZodObject<{
+            keys: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                prefix: z.ZodString;
+                createdAt: z.ZodString;
+                lastUsedAt: z.ZodNullable<z.ZodString>;
+                revokedAt: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>>;
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     ActivityFeedBlock: {
         props: z.ZodObject<{
             title: z.ZodNullable<z.ZodString>;
@@ -224,6 +240,24 @@ export declare const seedComponentDefinitions: {
         events: string[];
         description: string;
     };
+    BenchmarksBlock: {
+        props: z.ZodObject<{
+            badgeLabel: z.ZodNullable<z.ZodString>;
+            title: z.ZodNullable<z.ZodString>;
+            subtitle: z.ZodNullable<z.ZodString>;
+            datasets: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodString;
+                columns: z.ZodArray<z.ZodString>;
+                rows: z.ZodArray<z.ZodObject<{
+                    cells: z.ZodArray<z.ZodString>;
+                    highlight: z.ZodNullable<z.ZodBoolean>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+            staggerMs: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        description: string;
+    };
     BannerBlock: {
         props: z.ZodObject<{
             variant: z.ZodNullable<z.ZodEnum<{
@@ -297,6 +331,18 @@ export declare const seedComponentDefinitions: {
         }, z.core.$strip>;
         description: string;
     };
+    CheckEmailBlock: {
+        props: z.ZodObject<{
+            email: z.ZodNullable<z.ZodString>;
+            type: z.ZodNullable<z.ZodEnum<{
+                reset: "reset";
+                verification: "verification";
+                "magic-link": "magic-link";
+            }>>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     ChartBlock: {
         props: z.ZodObject<{
             data: z.ZodNullable<z.ZodArray<z.ZodObject<{
@@ -317,6 +363,18 @@ export declare const seedComponentDefinitions: {
         props: z.ZodObject<{}, z.core.$strip>;
         description: string;
     };
+    CommandPaletteBlock: {
+        props: z.ZodObject<{
+            items: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodString;
+                group: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>>;
+            placeholder: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     ComparisonBlock: {
         props: z.ZodObject<{
             title: z.ZodNullable<z.ZodString>;
@@ -387,6 +445,16 @@ export declare const seedComponentDefinitions: {
         }, z.core.$strip>;
         description: string;
     };
+    EmailVerifiedBlock: {
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            buttonText: z.ZodNullable<z.ZodString>;
+            autoRedirectSeconds: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     FAQBlock: {
         props: z.ZodObject<{
             title: z.ZodNullable<z.ZodString>;
@@ -432,6 +500,19 @@ export declare const seedComponentDefinitions: {
         }, z.core.$strip>;
         description: string;
     };
+    ForgotPasswordBlock: {
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            successTitle: z.ZodNullable<z.ZodString>;
+            submitLabel: z.ZodNullable<z.ZodString>;
+            loadingLabel: z.ZodNullable<z.ZodString>;
+            backLabel: z.ZodNullable<z.ZodString>;
+            emailPlaceholder: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     FooterBlock: {
         props: z.ZodObject<{
             brandDescription: z.ZodNullable<z.ZodString>;
@@ -605,6 +686,17 @@ export declare const seedComponentDefinitions: {
             forgotPasswordHref: string;
         };
     };
+    MagicLinkBlock: {
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            subtitle: z.ZodNullable<z.ZodString>;
+            successTitle: z.ZodNullable<z.ZodString>;
+            expiryMinutes: z.ZodNullable<z.ZodNumber>;
+            placeholder: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     NewsletterBlock: {
         props: z.ZodObject<{
             title: z.ZodNullable<z.ZodString>;
@@ -626,6 +718,26 @@ export declare const seedComponentDefinitions: {
         events: string[];
         description: string;
     };
+    OTPBlock: {
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            maxLength: z.ZodNullable<z.ZodNumber>;
+            buttonText: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
+    PasswordChangedBlock: {
+        props: z.ZodObject<{
+            autoRedirectSeconds: z.ZodNullable<z.ZodNumber>;
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            buttonLabel: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     PasswordRecoveryBlock: {
         props: z.ZodObject<{
             mode: z.ZodNullable<z.ZodEnum<{
@@ -662,6 +774,27 @@ export declare const seedComponentDefinitions: {
             showBillingToggle: boolean;
         };
     };
+    PricingTableBlock: {
+        props: z.ZodObject<{
+            heading: z.ZodNullable<z.ZodString>;
+            subheading: z.ZodNullable<z.ZodString>;
+            plans: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                price: z.ZodString;
+                period: z.ZodString;
+                description: z.ZodString;
+                features: z.ZodArray<z.ZodString>;
+                highlighted: z.ZodOptional<z.ZodBoolean>;
+                badge: z.ZodOptional<z.ZodString>;
+                buttonVariant: z.ZodOptional<z.ZodEnum<{
+                    outline: "outline";
+                    primary: "primary";
+                }>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     ProcessFlowBlock: {
         props: z.ZodObject<{
             title: z.ZodNullable<z.ZodString>;
@@ -696,6 +829,33 @@ export declare const seedComponentDefinitions: {
             showSocial: boolean;
         };
     };
+    SavingsCalculatorBlock: {
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            badgeLabel: z.ZodNullable<z.ZodString>;
+            billingTitle: z.ZodNullable<z.ZodString>;
+            billingDescription: z.ZodNullable<z.ZodString>;
+            billingModels: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                model: z.ZodString;
+                inputRate: z.ZodString;
+                savedPerRead: z.ZodString;
+            }, z.core.$strip>>>;
+            projectionTitle: z.ZodNullable<z.ZodString>;
+            projectionDescription: z.ZodNullable<z.ZodString>;
+            projections: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                amount: z.ZodNumber;
+                suffix: z.ZodString;
+                detail: z.ZodString;
+            }, z.core.$strip>>>;
+            summaryItems: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+        description: string;
+    };
     SocialProofBlock: {
         props: z.ZodObject<{
             variant: z.ZodNullable<z.ZodEnum<{
@@ -821,6 +981,24 @@ export declare const seedComponentDefinitions: {
         events: string[];
         description: string;
     };
+    TimezonePickerBlock: {
+        props: z.ZodObject<{
+            value: z.ZodNullable<z.ZodString>;
+            groups: z.ZodNullable<z.ZodArray<z.ZodObject<{
+                region: z.ZodString;
+                timezones: z.ZodArray<z.ZodObject<{
+                    value: z.ZodString;
+                    label: z.ZodString;
+                    region: z.ZodString;
+                    offset: z.ZodString;
+                    offsetMinutes: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+            name: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        events: string[];
+        description: string;
+    };
     UsageDonutBlock: {
         props: z.ZodObject<{
             data: z.ZodNullable<z.ZodArray<z.ZodObject<{
@@ -1026,6 +1204,14 @@ export declare const seedComponentDefinitions: {
         events: string[];
         description: string;
     };
+    WorkspaceSwitcherBlock: {
+        props: z.ZodObject<{
+            name: z.ZodNullable<z.ZodString>;
+            plan: z.ZodNullable<z.ZodString>;
+            href: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        description: string;
+    };
     AccountLockedPageKit: {
         props: z.ZodObject<{
             reason: z.ZodNullable<z.ZodEnum<{

package/dist/catalog/catalog.js

@@ -58,6 +58,24 @@ var seedComponentDefinitions = {
     events: ["contactSupport", "backToLogin"],
     description: "Account locked notification with reason, countdown timer, and support/login actions."
   },
+  ApiKeysBlock: {
+    props: z.object({
+      keys: z.array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          prefix: z.string(),
+          createdAt: z.string(),
+          lastUsedAt: z.string().nullable(),
+          revokedAt: z.string().nullable()
+        })
+      ).nullable(),
+      title: z.string().nullable(),
+      description: z.string().nullable()
+    }),
+    events: ["create", "revoke"],
+    description: "API key management block with table display, create dialog, copy-once flow, and revoke functionality."
+  },
   ActivityFeedBlock: {
     props: z.object({
       title: z.string().nullable(),
@@ -222,6 +240,28 @@ var seedComponentDefinitions = {
     events: ["composerChange", "composerSend"],
     description: "Agent workbench with conversation thread, code artifacts, diffs, terminal logs, and composer input."
   },
+  BenchmarksBlock: {
+    props: z.object({
+      badgeLabel: z.string().nullable(),
+      title: z.string().nullable(),
+      subtitle: z.string().nullable(),
+      datasets: z.array(
+        z.object({
+          name: z.string(),
+          description: z.string(),
+          columns: z.array(z.string()),
+          rows: z.array(
+            z.object({
+              cells: z.array(z.string()),
+              highlight: z.boolean().nullable()
+            })
+          )
+        })
+      ).nullable(),
+      staggerMs: z.number().nullable()
+    }),
+    description: "Benchmark results grid with tabular datasets, badge header, and staggered card animation."
+  },
   BannerBlock: {
     props: z.object({
       variant: z.enum(["info", "warning", "accent"]).nullable(),
@@ -269,6 +309,14 @@ var seedComponentDefinitions = {
     }),
     description: "Changelog display with versioned entries and categorized changes."
   },
+  CheckEmailBlock: {
+    props: z.object({
+      email: z.string().nullable(),
+      type: z.enum(["verification", "reset", "magic-link"]).nullable()
+    }),
+    events: ["resend", "backToLogin"],
+    description: "Post-submission email check prompt with resend action and step-by-step instructions."
+  },
   ChartBlock: {
     props: z.object({
       data: z.array(
@@ -288,6 +336,20 @@ var seedComponentDefinitions = {
     props: z.object({}),
     description: "Pre-composed collection of multiple chart types displayed in a dashboard grid."
   },
+  CommandPaletteBlock: {
+    props: z.object({
+      items: z.array(
+        z.object({
+          id: z.string(),
+          title: z.string(),
+          group: z.string().nullable()
+        })
+      ).nullable(),
+      placeholder: z.string().nullable()
+    }),
+    events: ["select"],
+    description: "Keyboard-driven command palette with fuzzy search, hotkey trigger (Cmd+K), and responsive trigger button."
+  },
   ComparisonBlock: {
     props: z.object({
       title: z.string().nullable(),
@@ -361,6 +423,16 @@ var seedComponentDefinitions = {
     }),
     description: "Navigation directory with sidebar items and project listings."
   },
+  EmailVerifiedBlock: {
+    props: z.object({
+      title: z.string().nullable(),
+      description: z.string().nullable(),
+      buttonText: z.string().nullable(),
+      autoRedirectSeconds: z.number().nullable()
+    }),
+    events: ["continue"],
+    description: "Email verification success card with check icon, continue button, and optional auto-redirect countdown."
+  },
   FAQBlock: {
     props: z.object({
       title: z.string().nullable(),
@@ -404,6 +476,19 @@ var seedComponentDefinitions = {
     }),
     description: "Simple feature grid with title and description per feature card."
   },
+  ForgotPasswordBlock: {
+    props: z.object({
+      title: z.string().nullable(),
+      description: z.string().nullable(),
+      successTitle: z.string().nullable(),
+      submitLabel: z.string().nullable(),
+      loadingLabel: z.string().nullable(),
+      backLabel: z.string().nullable(),
+      emailPlaceholder: z.string().nullable()
+    }),
+    events: ["submit", "backToLogin"],
+    description: "Forgot password form with email input, loading state, and success confirmation."
+  },
   FooterBlock: {
     props: z.object({
       brandDescription: z.string().nullable(),
@@ -545,6 +630,17 @@ var seedComponentDefinitions = {
     description: "Authentication login form with email/password fields and optional social login buttons.",
     example: { showSocial: true, forgotPasswordHref: "/reset-password" }
   },
+  MagicLinkBlock: {
+    props: z.object({
+      title: z.string().nullable(),
+      subtitle: z.string().nullable(),
+      successTitle: z.string().nullable(),
+      expiryMinutes: z.number().nullable(),
+      placeholder: z.string().nullable()
+    }),
+    events: ["submit", "backToLogin"],
+    description: "Magic link authentication form with email input, loading state, and success confirmation with expiry info."
+  },
   NewsletterBlock: {
     props: z.object({
       title: z.string().nullable(),
@@ -568,6 +664,26 @@ var seedComponentDefinitions = {
     events: ["toggle"],
     description: "Onboarding checklist with toggleable step completion tracking."
   },
+  OTPBlock: {
+    props: z.object({
+      title: z.string().nullable(),
+      description: z.string().nullable(),
+      maxLength: z.number().nullable(),
+      buttonText: z.string().nullable()
+    }),
+    events: ["verify"],
+    description: "OTP verification card with configurable code length, title, and verify callback."
+  },
+  PasswordChangedBlock: {
+    props: z.object({
+      autoRedirectSeconds: z.number().nullable(),
+      title: z.string().nullable(),
+      description: z.string().nullable(),
+      buttonLabel: z.string().nullable()
+    }),
+    events: ["continue"],
+    description: "Password change success confirmation with optional auto-redirect countdown and continue-to-login action."
+  },
   PasswordRecoveryBlock: {
     props: z.object({
       mode: z.enum(["reset", "magic-link"]).nullable(),
@@ -600,6 +716,26 @@ var seedComponentDefinitions = {
     description: "Pricing table with plan comparison, billing toggle, and feature lists.",
     example: { title: "Simple, transparent pricing", showBillingToggle: true }
   },
+  PricingTableBlock: {
+    props: z.object({
+      heading: z.string().nullable(),
+      subheading: z.string().nullable(),
+      plans: z.array(
+        z.object({
+          name: z.string(),
+          price: z.string(),
+          period: z.string(),
+          description: z.string(),
+          features: z.array(z.string()),
+          highlighted: z.boolean().optional(),
+          badge: z.string().optional(),
+          buttonVariant: z.enum(["primary", "outline"]).optional()
+        })
+      ).nullable()
+    }),
+    events: ["selectPlan"],
+    description: "Pricing comparison table with tiered plan cards, feature lists, and call-to-action buttons."
+  },
   ProcessFlowBlock: {
     props: z.object({
       title: z.string().nullable(),
@@ -633,6 +769,34 @@ var seedComponentDefinitions = {
     description: "Sign-up form with name, email, and password fields. Optional social login buttons.",
     example: { title: "Create an Account", showSocial: true }
   },
+  SavingsCalculatorBlock: {
+    props: z.object({
+      title: z.string().nullable(),
+      description: z.string().nullable(),
+      badgeLabel: z.string().nullable(),
+      billingTitle: z.string().nullable(),
+      billingDescription: z.string().nullable(),
+      billingModels: z.array(
+        z.object({
+          model: z.string(),
+          inputRate: z.string(),
+          savedPerRead: z.string()
+        })
+      ).nullable(),
+      projectionTitle: z.string().nullable(),
+      projectionDescription: z.string().nullable(),
+      projections: z.array(
+        z.object({
+          label: z.string(),
+          amount: z.number(),
+          suffix: z.string(),
+          detail: z.string()
+        })
+      ).nullable(),
+      summaryItems: z.array(z.object({ label: z.string(), value: z.string() })).nullable()
+    }),
+    description: "Savings calculator block with billing table and monthly projection cards featuring animated counting numbers."
+  },
   SocialProofBlock: {
     props: z.object({
       variant: z.enum(["logo-cloud", "testimonials"]).nullable(),
@@ -761,6 +925,28 @@ var seedComponentDefinitions = {
     events: ["verify", "complete"],
     description: "Two-factor setup wizard with QR code, secret key display, backup codes, and verification."
   },
+  TimezonePickerBlock: {
+    props: z.object({
+      value: z.string().nullable(),
+      groups: z.array(
+        z.object({
+          region: z.string(),
+          timezones: z.array(
+            z.object({
+              value: z.string(),
+              label: z.string(),
+              region: z.string(),
+              offset: z.string(),
+              offsetMinutes: z.number()
+            })
+          )
+        })
+      ).nullable(),
+      name: z.string().nullable()
+    }),
+    events: ["change"],
+    description: "Searchable timezone picker with grouped IANA timezones, offset display, and form integration."
+  },
   UsageDonutBlock: {
     props: z.object({
       data: z.array(
@@ -965,6 +1151,14 @@ var seedComponentDefinitions = {
     events: ["finish"],
     description: "Opinionated multi-step wizard card with Stepper progress indicator and built-in step content slots. Handles account, profile, plan, and launch steps by default. Use for onboarding and setup flows."
   },
+  WorkspaceSwitcherBlock: {
+    props: z.object({
+      name: z.string().nullable(),
+      plan: z.string().nullable(),
+      href: z.string().nullable()
+    }),
+    description: "Sidebar workspace switcher button with icon, workspace name, and plan label. Renders inside a SidebarMenu."
+  },
   // =========================================================================
   // Page Kits (28 entries, alphabetical)
   // =========================================================================