@vadimcomanescu/nadicode-design-system 2.0.0

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

@@ -0,0 +1,271 @@
+# Opinion Patterns: Machine-Readable Decision Tables
+
+Quick-lookup tables for enforcing `docs/OPINIONS.md` rules.
+Rules marked **[ENFORCED]** have automated tests in `src/test/opinion-*.test.ts`.
+Run `ls src/test/opinion-*.test.ts*` to discover all enforcement tests.
+
+## Navigation Pattern Selection [ENFORCED: opinion-navigation.test.ts]
+
+```
+IF context == "app shell" OR context == "dashboard":
+  USE Sidebar + SidebarProvider
+  MOBILE: Sheet (auto via Sidebar component)
+
+IF context == "content browsing" OR context == "settings":
+  USE Tabs + TabsList + TabsTrigger
+  MOBILE: horizontal scroll
+
+IF context == "marketing" OR context == "landing":
+  USE top-nav (<nav> in <header>)
+  MOBILE: hamburger -> Sheet
+
+IF context == "multi-step flow":
+  USE FormWizard
+```
+
+## Navigation Depth Check [ENFORCED: opinion-navigation.test.ts]
+
+```
+MAX_DEPTH = 3
+Level 1: SidebarGroup / SidebarGroupLabel
+Level 2: SidebarMenuItem / SidebarMenuButton
+Level 3: SidebarMenuSubItem / SidebarMenuSubButton
+Level 4+: VIOLATION -> flatten to Tabs, filters, or search
+```
+
+## Chart Type Selection
+
+```
+cumulative_time_series  -> AreaChart
+multi_series_trends     -> LineChart
+categorical_comparison  -> BarChart
+part_of_whole (n < 7)   -> PieChart
+part_of_whole (n >= 7)  -> BarChart
+multi_axis_profile      -> RadarChart
+dense_matrix            -> HeatmapChart
+```
+
+## Data Density Thresholds
+
+```
+data_points < 50        -> Chart component
+50 <= data_points < 500 -> DataTable
+data_points >= 500      -> DataTable + virtualization
+trend > precision       -> Sparkline + delta badge
+```
+
+## Typography Scale [ENFORCED: opinion-typography.test.ts]
+
+```
+h1: text-4xl/5xl, font-semibold, leading-tight (1 per page)
+h2: text-3xl, font-semibold, leading-tight
+h3: text-2xl, font-semibold, leading-tight
+h4: text-xl, font-semibold, leading-tight
+body: text-base, font-normal, leading-7
+small: text-sm, font-normal
+muted: text-sm, text-text-tertiary
+```
+
+## Font Weight Rules [ENFORCED: opinion-typography.test.ts]
+
+```
+FORBIDDEN: 300 (font-light) -- fails on glass backgrounds
+400 (font-normal)  = body text
+500 (font-medium)  = labels, UI text
+600 (font-semibold) = headings
+700 (font-bold)    = CTAs, buttons
+900 (font-black)   = brand display only
+```
+
+## Text Overflow Rules
+
+```
+TRUNCATE: nav items, table cells, tags, badges
+WRAP:     headings (text-balance), body (text-pretty)
+CLAMP:    card descriptions (line-clamp-2)
+NEVER:    truncate headings, wrap inside nav items
+```
+
+## Duration Tiers
+
+```
+hover/opacity   -> 100ms  (duration-micro)
+click/tab       -> 150ms  (duration-fast)
+modal/dropdown  -> 200ms  (duration-normal)
+page transition -> 250ms  (duration-moderate)
+hero entrance   -> 300ms  (duration-slow)
+NEVER           -> > 500ms
+```
+
+## Animation Type Selection
+
+```
+element_entering_viewport -> spring (motionSpring.snappy)
+color_change              -> CSS transition (duration-fast)
+opacity_change            -> CSS transition (duration-fast)
+border_state              -> CSS transition (duration-micro)
+progress_bar              -> linear
+FORBIDDEN                 -> parallax, scroll-jacking
+```
+
+## Hover Animation by Element Type
+
+```
+Button            -> lift (y: -2) + scale (1.02)
+Card (interactive) -> lift (y: -2) + glow border
+Link              -> underline (underline-offset-4)
+Icon button       -> scale (1.1)
+Static element    -> nothing
+```
+
+## Card Behavior Rules [ENFORCED: opinion-card-behavior.test.ts]
+
+```
+interactive_card  -> hover: lift (y: -2) + glow border, cursor-pointer
+static_card       -> no hover effect, no cursor-pointer
+card_click        -> entire card is clickable (not just nested link)
+card_actions      -> buttons inside card stop propagation
+```
+
+## Form Layout Rules
+
+```
+fields < 7   -> single page form
+7 <= fields <= 15 -> sectioned form (labeled sections)
+fields > 15  -> FormWizard (multi-step)
+
+Label placement: ALWAYS stacked (above input)
+FORBIDDEN: inline labels, floating labels
+```
+
+## Validation Timing
+
+```
+field_level   -> onBlur
+form_level    -> onSubmit
+on_keystroke  -> ONLY for password strength
+```
+
+## Error Display Channel
+
+```
+field_error          -> inline <p> below field
+network_error        -> toast (destructive variant)
+multi_field_error    -> Alert banner (top of form)
+```
+
+## Feedback Channel Selection
+
+```
+success_confirmation -> Toast (3-5s)
+form_field_error     -> inline text (persistent)
+form_multi_error     -> Alert banner (persistent)
+network_failure      -> Toast destructive (5s)
+destructive_action   -> AlertDialog (until action)
+system_announcement  -> Banner (until dismissed)
+```
+
+## Loading Indicator Selection
+
+```
+wait < 300ms    -> nothing
+300ms-3s        -> Spinner
+3s-10s          -> Skeleton
+wait > 10s      -> Progress + percentage
+```
+
+## Content Width by Context
+
+```
+marketing/landing -> max-w-7xl mx-auto
+dashboard         -> fluid (no max-width)
+reading/docs      -> max-w-2xl mx-auto
+settings/forms    -> max-w-md
+modals            -> max-w-lg
+```
+
+## Vertical Rhythm Scale
+
+```
+sections         -> space-y-12
+blocks           -> space-y-8
+components       -> space-y-4
+fields           -> space-y-2
+```
+
+## Grid Column Rules
+
+```
+forms/settings   -> 1 column
+features         -> 2 columns (md:grid-cols-2)
+pricing          -> 3 columns (md:grid-cols-3)
+stats            -> 4 columns (md:grid-cols-4)
+icons            -> exception (can exceed 4)
+NEVER            -> > 4 columns for content
+```
+
+## Responsive Breakpoints
+
+```
+default (< 640px)  -> 1 column, Sheet nav
+sm (640px)         -> 2 columns available
+md (768px)         -> Sidebar visible
+lg (1024px)        -> 3 columns available
+xl (1280px)        -> 4 columns, expanded spacing
+2xl (1536px)       -> containers center
+```
+
+## Mobile Control Rails
+
+```
+header_controls_mobile -> flex-wrap enabled, no forced single row
+tab_rail_mobile        -> overflow-x-auto on rail container, not page root
+tab_rail_alignment     -> justify-start mobile, can center at sm+
+viewport_375_check     -> documentElement.scrollWidth == documentElement.clientWidth
+```
+
+## Density Modes
+
+```
+comfortable (1x)    -> general app pages
+dense (0.75x)       -> dashboards, data tables
+spacious (1.5x)     -> marketing, landing, heroes
+```
+
+## Accessibility Minimums
+
+```
+body_text     -> 7:1 (AAA)
+headings      -> 7:1 (AAA)
+secondary     -> 4.5:1 (AA)
+error_text    -> 7:1 (AAA)
+placeholder   -> 4.5:1 (AA)
+borders       -> 3:1
+touch_target  -> 44x44px mobile, 40x40px desktop
+focus_ring    -> focus-visible:ring-1 ring-accent
+```
+
+## Status Color + Icon Pairing
+
+```
+success  -> bg-success  + CheckIcon
+error    -> bg-destructive + XIcon
+warning  -> bg-warning  + AlertTriangleIcon
+info     -> bg-info     + InfoIcon
+RULE: always triple-encode (color + icon + text)
+```
+
+## Card vs List vs Table
+
+```
+items < 20 + rich content   -> Card grid
+20 <= items <= 100          -> List
+items > 100 OR sort/filter  -> DataTable
+```
+
+## Sticky Element Rules
+
+```
+STICKY:     page header (always), table headers (when tall)
+NEVER:      footer, pagination, secondary nav, decorative elements
+```

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

@@ -0,0 +1,373 @@
+# Component Patterns
+
+Four real patterns from the Seed codebase, simplest to most complex.
+
+## Golden Template
+
+Every Seed component follows this structure:
+
+```
+1. Imports (React, Radix, CVA, cn, motion)
+2. CVA variants definition
+3. Props interface (extends HTML attrs + VariantProps, ref as prop)
+4. Function component (destructure props, cn() for classes)
+5. Named exports (component + variants)
+```
+
+Rules:
+- `cn()` for all class merging, never string concatenation
+- CVA for any component with variants
+- `ref` as a regular prop (React 19), no `forwardRef`, no `displayName`
+- `asChild` + `Slot` for polymorphic components
+- Export both the component and its variants function
+- `useReducedMotion()` guards all motion props
+
+---
+
+## Pattern 1: Simple CVA + Slot (Button)
+
+The canonical Seed pattern. CVA for variants, Slot for polymorphism.
+
+```tsx
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { motion, useReducedMotion } from "motion/react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+import { motionSpring } from "@/lib/animation"
+
+const MotionSlot = motion.create(Slot)
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium " +
+  "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-accent " +
+  "disabled:pointer-events-none disabled:opacity-50 transition-colors duration-fast",
+  {
+    variants: {
+      variant: {
+        primary: "bg-primary text-primary-foreground hover:bg-primary/90 shadow-glow",
+        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        outline: "border border-border bg-transparent hover:bg-surface-hover text-text-primary",
+        ghost: "hover:bg-surface-hover text-text-primary",
+        link: "text-text-primary underline-offset-4 hover:underline",
+        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        accent: "bg-accent text-accent-foreground hover:bg-accent/90 shadow-glow-accent",
+        glass: "glass-panel hover:bg-surface/40 text-text-primary",
+      },
+      size: {
+        sm: "h-8 px-3 text-xs",
+        default: "h-9 px-4 py-2",
+        lg: "h-10 px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: { variant: "primary", size: "default" },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+  ref?: React.Ref<HTMLButtonElement>
+}
+
+function Button({ className, variant, size, asChild = false, ref, ...props }: ButtonProps) {
+  const prefersReduced = useReducedMotion()
+  const isLink = variant === "link"
+  const shouldAnimate = !prefersReduced && !isLink
+
+  const motionProps = shouldAnimate
+    ? {
+        whileHover: { scale: 1.02, y: -2 },
+        whileTap: { scale: 0.97 },
+        transition: motionSpring.snappy,
+      }
+    : {}
+
+  if (asChild) {
+    return (
+      <MotionSlot
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref as React.Ref<HTMLElement>}
+        {...motionProps}
+        {...props}
+      />
+    )
+  }
+
+  return (
+    <motion.button
+      className={cn(buttonVariants({ variant, size, className }))}
+      ref={ref}
+      {...motionProps}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }
+```
+
+Key points:
+- `MotionSlot = motion.create(Slot)` for animated polymorphism
+- `useReducedMotion()` guards all motion; `link` variant also skips animation
+- Export both component and variants
+
+---
+
+## Pattern 2: Form Input with Label/Error/Icons (Input)
+
+```tsx
+import * as React from 'react'
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from '@/lib/utils'
+import { Label } from './Label'
+
+const inputVariants = cva(
+  "flex w-full rounded-md border border-border bg-surface shadow-sm " +
+  "transition-[border-color,box-shadow] duration-fast ease-out-cubic " +
+  "placeholder:text-text-tertiary hover:border-primary/40 " +
+  "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-accent " +
+  "disabled:cursor-not-allowed disabled:opacity-50 text-text-primary",
+  {
+    variants: {
+      size: {
+        sm: "h-8 px-2.5 py-0.5 text-xs",
+        default: "h-9 px-3 py-1 text-sm",
+        lg: "h-11 px-4 py-2 text-base",
+      },
+    },
+    defaultVariants: { size: "default" },
+  }
+)
+
+export interface InputProps
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">,
+    VariantProps<typeof inputVariants> {
+  label?: React.ReactNode
+  error?: string | boolean
+  startIcon?: React.ReactNode
+  endIcon?: React.ReactNode
+  ref?: React.Ref<HTMLInputElement>
+}
+
+export function Input({ className, type, label, error, startIcon, endIcon, id, size, ref, ...props }: InputProps) {
+  const generatedId = React.useId()
+  const inputId = id || generatedId
+
+  return (
+    <div className="w-full space-y-2">
+      {label && <Label htmlFor={inputId}>{label}</Label>}
+      <div className="relative">
+        {startIcon && (
+          <div className="absolute left-3 top-1/2 -translate-y-1/2 text-text-tertiary pointer-events-none">
+            {startIcon}
+          </div>
+        )}
+        <input
+          type={type}
+          id={inputId}
+          className={cn(
+            inputVariants({ size }),
+            startIcon && "pl-10",
+            endIcon && "pr-10",
+            error && "border-destructive focus-visible:ring-destructive",
+            className
+          )}
+          ref={ref}
+          {...props}
+        />
+        {endIcon && (
+          <div className="absolute right-3 top-1/2 -translate-y-1/2 text-text-tertiary pointer-events-none">
+            {endIcon}
+          </div>
+        )}
+      </div>
+      {typeof error === 'string' && (
+        <p className="text-xs font-medium text-destructive">{error}</p>
+      )}
+    </div>
+  )
+}
+```
+
+Key points:
+- `React.useId()` for accessible label association
+- `Omit<..., "size">` avoids conflict with CVA's `size` variant
+- Icons positioned absolutely with `pointer-events-none`
+- Error state via `cn()` conditional
+
+---
+
+## Pattern 3: Compound Radix Wrapper (Dialog)
+
+Wraps Radix primitives into styled sub-components.
+
+```tsx
+import * as React from "react"
+import * as DialogPrimitive from "@radix-ui/react-dialog"
+import { XIcon } from "@vadimcomanescu/nadicode-design-system/icons"
+import { cn } from "@/lib/utils"
+
+// Pass-through re-exports (no styling needed)
+const Dialog = DialogPrimitive.Root
+const DialogTrigger = DialogPrimitive.Trigger
+const DialogPortal = DialogPrimitive.Portal
+const DialogClose = DialogPrimitive.Close
+
+function DialogOverlay({ className, ref, ...props }: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay> & { ref?: React.Ref<React.ElementRef<typeof DialogPrimitive.Overlay>> }) {
+  return (
+    <DialogPrimitive.Overlay
+      ref={ref}
+      className={cn(
+        "fixed inset-0 z-50 bg-overlay/80 backdrop-blur-sm " +
+        "data-[state=open]:animate-in data-[state=closed]:animate-out " +
+        "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogContent({ className, children, ref, ...props }: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & { ref?: React.Ref<React.ElementRef<typeof DialogPrimitive.Content>> }) {
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        ref={ref}
+        className={cn(
+          "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg " +
+          "translate-x-[-50%] translate-y-[-50%] gap-4 glass-panel p-6 " +
+          "duration-normal ease-out-cubic " +
+          "data-[state=open]:animate-in data-[state=closed]:animate-out " +
+          "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 " +
+          "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 " +
+          "sm:rounded-lg",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ...">
+          <XIcon size={16} />
+          <span className="sr-only">Close</span>
+        </DialogPrimitive.Close>
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  )
+}
+
+// Layout sub-components (styled divs, no Radix)
+function DialogHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex flex-col space-y-1.5 text-center sm:text-left", className)} {...props} />
+}
+
+function DialogTitle({ className, ref, ...props }: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title> & { ref?: React.Ref<React.ElementRef<typeof DialogPrimitive.Title>> }) {
+  return (
+    <DialogPrimitive.Title
+      ref={ref}
+      className={cn("text-lg font-semibold leading-none tracking-tight text-text-primary", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger,
+  DialogContent, DialogHeader, DialogTitle,
+}
+```
+
+Key points:
+- Re-export Radix primitives directly when no styling needed
+- Content uses `glass-panel` for glassmorphism
+- Overlay uses `bg-overlay/80 backdrop-blur-sm`
+- `data-[state=open/closed]` drives enter/exit animations
+- Use `React.ElementRef<typeof Primitive>` and `React.ComponentPropsWithoutRef<typeof Primitive>` for types
+
+---
+
+## Pattern 4: Block Composition (LoginBlock)
+
+Blocks compose UI primitives into page-ready sections.
+
+```tsx
+import React from "react"
+import { Button } from "../ui/Button"
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } 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
+}
+
+export function LoginBlock({
+  className,
+  type = "login",
+  showSocial = true,
+  title,
+  description,
+  onLogin,
+}: LoginBlockProps) {
+  const defaultTitle = 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)}>
+      <CardHeader className="space-y-1">
+        <CardTitle className="text-2xl text-center">{title || defaultTitle}</CardTitle>
+        <CardDescription className="text-center">...</CardDescription>
+      </CardHeader>
+      <CardContent className="grid gap-4">
+        {showSocial && (
+          <>
+            <Button variant="outline" className="w-full ...">
+              <GoogleIcon className="h-5 w-5" />
+              <span>Continue with Google</span>
+            </Button>
+            <div className="flex items-center gap-3 text-xs uppercase text-text-tertiary">
+              <div className="h-px flex-1 bg-border/50" />
+              <span>Or continue with</span>
+              <div className="h-px flex-1 bg-border/50" />
+            </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" />
+          </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>
+      </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
+- Semantic tokens only (`text-text-tertiary`, `bg-border/50`, `bg-accent`)