@vadimcomanescu/nadicode-design-system 2.0.0

package/.agents/skills/seed/recipes/auth.md

@@ -0,0 +1,254 @@
+# Recipe: Auth
+
+Login, signup, password reset, and 2FA flows with split-screen or centered layout.
+
+## Route Patterns
+
+- `/login`
+- `/signup`
+- `/reset-password`
+- `/verify` (2FA challenge)
+
+## Shell
+
+`auth-shell` (AuthLayout: split-screen or centered, minimal chrome)
+
+---
+
+## Layout Blueprint (Desktop)
+
+```
++------------------------------------------------+
+|                                                 |
+|  +--------------------+  +-------------------+  |
+|  |                    |  |                   |  |
+|  |  Brand Panel       |  |  Auth Card        |  |
+|  |  (illustration,    |  |  (glass-floating) |  |
+|  |   testimonial,     |  |                   |  |
+|  |   or shader bg)    |  |  Logo             |  |
+|  |                    |  |  Title            |  |
+|  |                    |  |  Subtitle         |  |
+|  |                    |  |                   |  |
+|  |                    |  |  [Email input]    |  |
+|  |                    |  |  [Password input] |  |
+|  |                    |  |                   |  |
+|  |                    |  |  [Sign In]        |  |
+|  |                    |  |  Or continue with |  |
+|  |                    |  |  [Google] [GitHub] |  |
+|  |                    |  |                   |  |
+|  |                    |  |  Forgot password? |  |
+|  |                    |  |  Don't have acct? |  |
+|  +--------------------+  +-------------------+  |
+|                                                 |
++------------------------------------------------+
+
+Mobile: Brand panel hidden, auth card full-width centered
+```
+
+---
+
+## Section Sequence
+
+### 1. Auth Layout Wrapper
+
+```tsx
+<AuthLayout>
+  {/* AuthLayout provides split-screen on desktop, centered on mobile */}
+  <LoginBlock
+    type="login"
+    variant="glass-panel"
+    showSocial
+    title="Welcome back"
+    description="Sign in to your account"
+    onLogin={handleLogin}
+    forgotPasswordHref="/reset-password"
+    signUpHref="/signup"
+  />
+</AuthLayout>
+```
+
+### 2. Login Form (within LoginBlock or custom)
+
+```tsx
+<Card className="glass-floating p-8 w-full max-w-md">
+  <div className="flex flex-col items-center mb-6">
+    <Logo className="h-8 mb-4" />
+    <Heading level={3} size="subsection" >Welcome back</Heading>
+    <Typography variant="small" className="text-text-secondary mt-1">
+      Sign in to your account
+    </Typography>
+  </div>
+
+  {error && <Alert variant="destructive" className="mb-4">{error}</Alert>}
+
+  <form onSubmit={handleSubmit} className="space-y-4">
+    <div>
+      <Label htmlFor="email">Email</Label>
+      <Input id="email" type="email" placeholder="name@example.com" />
+    </div>
+    <div>
+      <Label htmlFor="password">Password</Label>
+      <PasswordInput id="password" />
+    </div>
+    <Button type="submit" className="w-full" disabled={isSubmitting}>
+      {isSubmitting ? <Spinner className="mr-2" /> : null}
+      Sign In
+    </Button>
+  </form>
+
+  <div className="relative my-6">
+    <Separator />
+    <span className="absolute left-1/2 -translate-x-1/2 -translate-y-1/2 bg-surface px-2 text-text-tertiary text-sm">
+      Or continue with
+    </span>
+  </div>
+
+  <div className="grid grid-cols-2 gap-3">
+    <Button variant="outline"><BrandIcons.Google className="mr-2 h-4 w-4" /> Google</Button>
+    <Button variant="outline"><BrandIcons.GitHub className="mr-2 h-4 w-4" /> GitHub</Button>
+  </div>
+
+  <div className="mt-6 text-center space-y-2">
+    <a href="/reset-password" className="text-sm text-link">Forgot password?</a>
+    <p className="text-sm text-text-secondary">
+      Don't have an account? <a href="/signup" className="text-link">Sign up</a>
+    </p>
+  </div>
+</Card>
+```
+
+### 3. 2FA Challenge (separate route)
+
+```tsx
+<Card className="glass-floating p-8 w-full max-w-md text-center">
+  <Heading level={3} size="subsection" >Two-factor authentication</Heading>
+  <Typography variant="small" className="text-text-secondary mt-2 mb-6">
+    Enter the 6-digit code from your authenticator app
+  </Typography>
+  <InputOTP maxLength={6} onComplete={handleVerify}>
+    <InputOTPGroup>
+      <InputOTPSlot index={0} />
+      <InputOTPSlot index={1} />
+      <InputOTPSlot index={2} />
+    </InputOTPGroup>
+    <InputOTPSeparator />
+    <InputOTPGroup>
+      <InputOTPSlot index={3} />
+      <InputOTPSlot index={4} />
+      <InputOTPSlot index={5} />
+    </InputOTPGroup>
+  </InputOTP>
+  <Button className="w-full mt-6" disabled={isSubmitting}>Verify</Button>
+</Card>
+```
+
+---
+
+## Animation Storyboard
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 350ms | SPRING: gentle | REDUCED: opacity-only
+
+T+0ms     [layout]    Split-screen panels visible   (instant)
+T+0ms     [brand]     Brand panel bg/shader          (instant)
+T+100ms   [card]      Auth card scales in            {scaleIn, gentle}
+T+200ms   [logo]      Logo fades in                  {fadeIn, snappy}
+T+250ms   [fields]    Form fields stagger            {blockStagger, 60ms, max 4}
+T+350ms   [cta]       Sign-in button fades in        {fadeIn, snappy}
+
+REDUCED MOTION: Card and all children visible immediately
+```
+
+---
+
+## Required Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `AuthLayout` | `@vadimcomanescu/nadicode-design-system/auth-layout` | Split-screen wrapper |
+| `LoginBlock` | `@vadimcomanescu/nadicode-design-system/login-block` | Pre-built login form |
+| `SignUpBlock` | `@vadimcomanescu/nadicode-design-system/sign-up-block` | Pre-built signup form |
+| `Card` | `@vadimcomanescu/nadicode-design-system/card` | Auth card container |
+| `Input` | `@vadimcomanescu/nadicode-design-system/input` | Email, name fields |
+| `PasswordInput` | `@vadimcomanescu/nadicode-design-system/password-input` | Password with toggle |
+| `Label` | `@vadimcomanescu/nadicode-design-system/label` | Stacked labels |
+| `Button` | `@vadimcomanescu/nadicode-design-system/button` | Submit, social login |
+| `Alert` | `@vadimcomanescu/nadicode-design-system/alert` | Error messages |
+| `Logo` | `@vadimcomanescu/nadicode-design-system/logo` | Brand mark |
+| `BrandIcons` | `@vadimcomanescu/nadicode-design-system/brand-icons` | Google, GitHub icons |
+| `Separator` | `@vadimcomanescu/nadicode-design-system/separator` | "Or" divider |
+| `InputOTP` | `@vadimcomanescu/nadicode-design-system/input-otp` | 2FA code entry |
+| `Spinner` | `@vadimcomanescu/nadicode-design-system/spinner` | Submit loading |
+| `Typography` | `@vadimcomanescu/nadicode-design-system/typography` | Headings, descriptions |
+
+### Allowed (optional)
+
+`PasswordRecoveryBlock`, `ResetPasswordBlock`, `TwoFactorChallengeBlock`, `TwoFactorSetupBlock`, `AccountLockedBlock`, `AuthSuccessBlock`, `Checkbox` (remember me), `ShaderBackground`
+
+### Forbidden
+
+`Sidebar`, `DataTable`, chart components, `NavigationMenu`, decorative effects (except on brand panel)
+
+---
+
+## Required States
+
+| State | Trigger | Visual |
+|-------|---------|--------|
+| `default` | Page loaded | Form ready for input |
+| `submitting` | Form submitted | Button shows Spinner, form disabled |
+| `error` | Auth failure | `Alert` variant="destructive" with message |
+| `success` | Auth succeeded | Redirect to dashboard (or `AuthSuccessBlock`) |
+| `2fa-challenge` | Server requests 2FA | Show 2FA code entry screen |
+
+---
+
+## Responsive Contract
+
+| Breakpoint | Layout | Card Width |
+|------------|--------|------------|
+| Mobile | Centered card, no brand panel | Full width, max-w-md, px-4 |
+| `lg:` | Split screen: brand (50%) + form (50%) | max-w-md centered in right half |
+
+---
+
+## Styling Rules
+
+- Auth card: `glass-floating p-8`
+- Brand panel: full-height, may use `ShaderBackground` or illustration
+- Labels: stacked above inputs (always)
+- Social buttons: `variant="outline"`, 2-column grid
+- Links: `text-link` token
+- Error: `Alert` at top of form, not inline per-field (for auth errors)
+
+---
+
+## Accessibility
+
+- Form inputs have associated labels
+- Error alert uses `role="alert"`
+- Social login buttons include brand name in text
+- OTP input is keyboard-navigable (auto-advance)
+- Focus moves to first field on mount
+- Escape key behavior is handled (no accidental navigation away)
+
+---
+
+## Reference Implementations
+
+- `src/components/blocks/LoginBlock.tsx`
+- `src/components/blocks/AuthLayout.tsx`
+- `src/app/login/vanta/*/page.tsx` (7 variants)
+
+---
+
+## Verification
+
+```bash
+npx tsc --noEmit
+npm run lint
+npm run test
+npx vitest run src/test/css-variable-usage.test.ts
+```

package/.agents/skills/seed/recipes/blog-content.md

@@ -0,0 +1,307 @@
+# Recipe: Blog / Content
+
+Blog index, article pages, and changelog display with reading-optimized layout.
+
+## Route Patterns
+
+- `/blog` (index with post cards)
+- `/blog/[slug]` (individual article)
+- `/changelog` (version changelog)
+
+## Shell
+
+`marketing-shell` (HeaderBlock + FooterBlock)
+
+---
+
+## Layout Blueprint: Blog Index (Desktop)
+
+```
++------------------------------------------------+
+| HeaderBlock                                     |
++------------------------------------------------+
+|                                                 |
+|    Blog           [Category filter]             |
+|    Latest thoughts and updates                  |
+|                                                 |
+|  +--------------------+  +-------------------+  |
+|  | Featured Post      |  | Post 2            |  |
+|  | (large card)       |  | (standard card)   |  |
+|  |                    |  +-------------------+  |
+|  |                    |  | Post 3            |  |
+|  |                    |  | (standard card)   |  |
+|  +--------------------+  +-------------------+  |
+|                                                 |
+|  +----------+  +----------+  +----------+       |
+|  | Post 4   |  | Post 5   |  | Post 6   |      |
+|  +----------+  +----------+  +----------+       |
+|                                                 |
+|  [Load More / Pagination]                       |
++------------------------------------------------+
+| FooterBlock                                     |
++------------------------------------------------+
+```
+
+## Layout Blueprint: Article Page (Desktop)
+
+```
++------------------------------------------------+
+| HeaderBlock                                     |
++------------------------------------------------+
+|                                                 |
+|         max-w-3xl centered                      |
+|                                                 |
+|    Category Badge        5 min read             |
+|    Article Title (h1)                           |
+|    Published Jan 1, 2025 by Author Name         |
+|                                                 |
+|    [Article hero image]                         |
+|                                                 |
+|    Article body content with prose styling...   |
+|    Headings, paragraphs, code blocks,           |
+|    images, blockquotes...                       |
+|                                                 |
+|    ---                                          |
+|    Author card                                  |
+|    Share buttons                                |
+|                                                 |
+|    Related Posts (3 cards)                       |
+|                                                 |
++------------------------------------------------+
+| FooterBlock                                     |
++------------------------------------------------+
+```
+
+---
+
+## Section Sequence: Blog Index
+
+### 1. Page Header
+
+```tsx
+<section className="py-12 md:py-16">
+  <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+    <div className="flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
+      <div>
+        <Heading level={1} size="display" >Blog</Heading>
+        <Typography variant="lead" className="text-text-secondary mt-2">
+          Latest thoughts and updates
+        </Typography>
+      </div>
+      <Select value={category} onValueChange={setCategory}>
+        <SelectTrigger className="w-48"><SelectValue placeholder="All categories" /></SelectTrigger>
+        <SelectContent>{/* Category options */}</SelectContent>
+      </Select>
+    </div>
+  </div>
+</section>
+```
+
+### 2. Featured + Recent Posts Grid
+
+```tsx
+<section className="pb-16">
+  <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+    {/* Featured row */}
+    <div className="grid grid-cols-1 lg:grid-cols-2 gap-6 mb-6">
+      <Card className="glass-panel overflow-hidden lg:row-span-2">
+        {/* Featured post with large image */}
+        <img src={featured.image} alt="" className="w-full h-48 lg:h-64 object-cover" />
+        <div className="p-6">
+          <Badge variant="outline">{featured.category}</Badge>
+          <Heading level={3} size="subsection"  className="mt-3">{featured.title}</Heading>
+          <Typography variant="p" className="text-text-secondary mt-2 line-clamp-3">
+            {featured.excerpt}
+          </Typography>
+          <div className="flex items-center gap-2 mt-4 text-text-tertiary text-sm">
+            <Avatar className="h-6 w-6"><AvatarImage src={featured.author.avatar} /></Avatar>
+            <span>{featured.author.name}</span>
+            <span>-</span>
+            <span>{featured.date}</span>
+          </div>
+        </div>
+      </Card>
+      <div className="space-y-6">
+        {recentPosts.slice(0, 2).map(post => (
+          <Card key={post.id} className="glass-panel p-6">
+            <Badge variant="outline">{post.category}</Badge>
+            <Heading level={4} size="title"  className="mt-2">{post.title}</Heading>
+            <Typography variant="small" className="text-text-secondary mt-1 line-clamp-2">
+              {post.excerpt}
+            </Typography>
+          </Card>
+        ))}
+      </div>
+    </div>
+
+    {/* Remaining posts grid */}
+    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
+      {remainingPosts.map(post => (
+        <Card key={post.id} className="glass-panel p-6">
+          <Badge variant="outline">{post.category}</Badge>
+          <Heading level={4} size="title"  className="mt-2">{post.title}</Heading>
+          <Typography variant="small" className="text-text-secondary mt-1 line-clamp-2">
+            {post.excerpt}
+          </Typography>
+        </Card>
+      ))}
+    </div>
+
+    {/* Pagination */}
+    <div className="mt-12 flex justify-center">
+      <Pagination current={page} total={totalPages} onPageChange={setPage} />
+    </div>
+  </div>
+</section>
+```
+
+### Article Page: Prose Content
+
+```tsx
+<article className="max-w-3xl mx-auto px-4 sm:px-6 py-12 md:py-16">
+  <header className="mb-8">
+    <div className="flex items-center gap-3 mb-4">
+      <Badge variant="outline">{post.category}</Badge>
+      <Typography variant="small" className="text-text-tertiary">
+        {post.readingTime} min read
+      </Typography>
+    </div>
+    <Heading level={1} size="display" >{post.title}</Heading>
+    <div className="flex items-center gap-3 mt-4 text-text-secondary">
+      <Avatar><AvatarImage src={post.author.avatar} /></Avatar>
+      <div>
+        <Typography variant="small" className="font-medium text-text-primary">
+          {post.author.name}
+        </Typography>
+        <Typography variant="small">{post.date}</Typography>
+      </div>
+    </div>
+  </header>
+
+  {/* Prose content */}
+  <div className="prose prose-neutral dark:prose-invert max-w-none">
+    {post.content}
+  </div>
+
+  {/* Author card + share */}
+  <Separator className="my-12" />
+  <Card className="glass-panel p-6 flex items-center gap-4">
+    <Avatar className="h-12 w-12"><AvatarImage src={post.author.avatar} /></Avatar>
+    <div>
+      <Heading level={4} size="title" >{post.author.name}</Heading>
+      <Typography variant="small" className="text-text-secondary">{post.author.bio}</Typography>
+    </div>
+  </Card>
+</article>
+```
+
+---
+
+## Animation Storyboard
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 600ms (index) / 300ms (article) | SPRING: snappy | REDUCED: opacity-only
+
+BLOG INDEX:
+T+0ms     [nav]       Header visible                (instant)
+T+50ms    [header]    Blog title + filter            {fadeInUp, snappy}
+T+130ms   [featured]  Featured post card             {fadeInUp, snappy}
+T+210ms   [recent]    Recent post cards stagger      {blockStagger, 80ms}
+T+450ms   [grid]      Remaining posts stagger        {blockStagger, 80ms, max 6}
+
+ARTICLE:
+T+0ms     [nav]       Header visible                (instant)
+T+50ms    [meta]      Category + reading time        {fadeIn, snappy}
+T+100ms   [title]     Article title                  {fadeInUp, snappy}
+T+200ms   [content]   Article body fades in          {fadeIn, gentle}
+
+REDUCED MOTION: All items visible immediately
+```
+
+---
+
+## Required Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `Card` | `@vadimcomanescu/nadicode-design-system/card` | Post cards |
+| `Badge` | `@vadimcomanescu/nadicode-design-system/badge` | Category tags |
+| `Avatar` | `@vadimcomanescu/nadicode-design-system/avatar` | Author avatars |
+| `Typography` | `@vadimcomanescu/nadicode-design-system/typography` | Headings, body |
+| `Pagination` | `@vadimcomanescu/nadicode-design-system/pagination` | Blog index pages |
+| `Separator` | `@vadimcomanescu/nadicode-design-system/separator` | Content dividers |
+| `Select` | `@vadimcomanescu/nadicode-design-system/select` | Category filter |
+| `HeaderBlock` | `@vadimcomanescu/nadicode-design-system/header-block` | Site navigation |
+| `FooterBlock` | `@vadimcomanescu/nadicode-design-system/footer-block` | Site footer |
+| `ScrollFadeIn` | `@vadimcomanescu/nadicode-design-system/scroll-fade-in` | Below-fold animations |
+| `Button` | `@vadimcomanescu/nadicode-design-system/button` | Share, read more |
+
+### Allowed (optional)
+
+`ChangelogBlock`, `NewsletterBlock`, `Tabs`, `Input` (search), `Breadcrumb`, `Tooltip`, `CodeBlock`
+
+### Forbidden
+
+`Sidebar`, `DataTable`, `FormWizard`, chart components, agentic components
+
+---
+
+## Required States
+
+| State | Trigger | Visual |
+|-------|---------|--------|
+| `loading` | Fetching posts | Skeleton post cards |
+| `empty` | No posts (unlikely for blog) | `Empty` with "No posts yet" |
+| `has-data` | Posts loaded | Full grid layout |
+| `category-filtered` | Category selected | Filtered post grid |
+
+---
+
+## Responsive Contract
+
+| Breakpoint | Blog Index Grid | Article Width |
+|------------|----------------|---------------|
+| Mobile | 1 col | Full width, px-4 |
+| `sm:` | 2 col | max-w-3xl, px-6 |
+| `lg:` | Featured 2-col + 3-col grid | max-w-3xl, px-6 |
+
+---
+
+## Styling Rules
+
+- Post cards: `glass-panel` with overflow-hidden for images
+- Article prose: Tailwind typography plugin (`prose prose-neutral dark:prose-invert`)
+- Reading width: `max-w-3xl` (768px) for article content
+- Category badges: `variant="outline"`
+- No raw palette colors
+
+---
+
+## Accessibility
+
+- Blog index is a `<main>` with article cards as `<article>` elements
+- Article page uses semantic `<article>`, `<header>`, heading hierarchy
+- Images have alt text
+- Pagination uses `<nav>` with `aria-label="Blog pagination"`
+
+---
+
+## Reference Implementations
+
+- `src/app/blog/page.tsx`
+- `src/app/changelog/page.tsx`
+- `src/components/blocks/ChangelogBlock.tsx`
+- `src/components/blocks/NewsletterBlock.tsx`
+
+---
+
+## Verification
+
+```bash
+npx tsc --noEmit
+npm run lint
+npm run test
+npx vitest run src/test/css-variable-usage.test.ts
+```