@vadimcomanescu/nadicode-design-system 2.0.0

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

@@ -0,0 +1,209 @@
+# Responsive Strategy
+
+Breakpoint contracts, mobile-first patterns, touch targets, and responsive rules by page type.
+
+---
+
+## Breakpoint System
+
+| Token | Width | Target |
+|-------|-------|--------|
+| (default) | < 640px | Mobile phones (portrait) |
+| `sm:` | >= 640px | Large phones (landscape), small tablets |
+| `md:` | >= 768px | Tablets (portrait) |
+| `lg:` | >= 1024px | Tablets (landscape), small laptops |
+| `xl:` | >= 1280px | Laptops, desktops |
+| `2xl:` | >= 1536px | Wide desktops |
+
+**Design priority**: Mobile-first. Default styles target mobile, add complexity at breakpoints.
+
+**Primary breakpoints** (used in recipes): default, `sm:`, `lg:`, `xl:`. Use `md:` and `2xl:` sparingly.
+
+---
+
+## Layout Contracts by Page Type
+
+### Dashboard
+
+| Breakpoint | KPI Grid | Chart Grid | Activity |
+|------------|----------|------------|----------|
+| Mobile | 1 col | 1 col | Full width |
+| `sm:` | 2 col | 1 col | Full width |
+| `lg:` | 4 col | 2 col | Full width |
+| `xl:` | 4 col | 2 col + 1 full | Side panel option |
+
+### Settings
+
+| Breakpoint | Navigation | Content |
+|------------|------------|---------|
+| Mobile | Horizontal scrollable tabs | Full width below tabs |
+| `lg:` | Sidebar nav (200px fixed) | Content fills remaining |
+
+### Agent Chat (3-panel)
+
+| Breakpoint | Layout |
+|------------|--------|
+| Mobile | Single column: conversation + composer (team/work hidden in drawers) |
+| `lg:` | 2-panel: sidebar (280px) + conversation |
+| `xl:` | 3-panel: sidebar (280px) + conversation + work panel (320px) |
+
+### CRUD List
+
+| Breakpoint | Table | Filters | Actions |
+|------------|-------|---------|---------|
+| Mobile | Card list or horizontal-scroll table | Dropdown filter button | Floating action button |
+| `sm:` | Table with key columns | Inline filter row | Inline buttons |
+| `lg:` | Full table all columns | Persistent filter bar | Row actions + bulk actions |
+
+### Marketing Landing
+
+| Breakpoint | Hero | Features | Content Width |
+|------------|------|----------|---------------|
+| Mobile | Stacked: text then image | 1 col | Full width w/ px-4 |
+| `sm:` | Stacked: text then image | 2 col | max-w-7xl px-6 |
+| `lg:` | Split 50/50 or centered | 3 col | max-w-7xl px-8 |
+
+### Auth
+
+| Breakpoint | Layout |
+|------------|--------|
+| Mobile | Centered card, full width with px-4 |
+| `lg:` | Split screen: illustration (50%) + form (50%) |
+
+### Pricing
+
+| Breakpoint | Plan Cards |
+|------------|------------|
+| Mobile | Stacked vertically, 1 col |
+| `sm:` | 2 col (if 2 plans) or scrollable |
+| `lg:` | 3 col side-by-side |
+
+---
+
+## Touch Target Requirements
+
+| Element | Minimum Size | Implementation |
+|---------|-------------|----------------|
+| Buttons | 44px height (mobile), 40px (desktop) | `min-h-[44px] sm:min-h-[40px]` or size="lg" on mobile |
+| Icon buttons | 44x44px (mobile), 36x36px (desktop) | `size-11 sm:size-9` click area |
+| Links in body text | 44px touch target | `py-2 -my-2` for invisible padding |
+| Table rows (clickable) | 44px min height | `h-11` minimum |
+| Nav items | 44px height | Sidebar items default to this |
+| Form inputs | 44px height (mobile) | Input size="default" is 40px, add `min-h-[44px]` on mobile |
+
+**Rule**: Any interactive element must have a minimum 44x44px touch target on mobile. Use invisible padding if the visual element is smaller.
+
+---
+
+## Mobile-First Patterns
+
+### Navigation Collapse
+
+```tsx
+// Desktop: full sidebar visible
+// Mobile: sheet-based sidebar triggered by hamburger
+<SidebarProvider>
+  <Sidebar className="hidden lg:flex">
+    {/* Full sidebar */}
+  </Sidebar>
+  <main className="flex-1">
+    <header className="lg:hidden flex items-center p-4">
+      <SidebarTrigger />
+      <span className="ml-3 font-medium">Page Title</span>
+    </header>
+    {children}
+  </main>
+</SidebarProvider>
+```
+
+### Table to Card List
+
+```tsx
+// Desktop: DataTable. Mobile: Card list.
+<div className="hidden sm:block">
+  <DataTable columns={columns} data={data} />
+</div>
+<div className="sm:hidden space-y-3">
+  {data.map((item) => (
+    <Card key={item.id} className="p-4">
+      {/* Card representation of row */}
+    </Card>
+  ))}
+</div>
+```
+
+### Tab Navigation Scroll
+
+```tsx
+// Horizontal scrollable tabs on mobile
+<div className="overflow-x-auto -mx-4 px-4">
+  <TabsList className="inline-flex w-auto min-w-full sm:w-full">
+    <TabsTrigger value="general">General</TabsTrigger>
+    <TabsTrigger value="security">Security</TabsTrigger>
+    <TabsTrigger value="billing">Billing</TabsTrigger>
+  </TabsList>
+</div>
+```
+
+### Multi-Panel to Drawers
+
+```tsx
+// Desktop: visible panels. Mobile: main content + drawer-triggered panels.
+<div className="flex h-dvh">
+  <aside className="hidden xl:block w-[280px] border-r border-border">
+    <TeamPanel />
+  </aside>
+  <main className="flex-1 flex flex-col">
+    <header className="xl:hidden flex items-center gap-2 p-3 border-b border-border">
+      <Sheet>
+        <SheetTrigger asChild>
+          <Button variant="ghost" size="icon"><UsersIcon size={16} /></Button>
+        </SheetTrigger>
+        <SheetContent side="left"><TeamPanel /></SheetContent>
+      </Sheet>
+      <span className="flex-1 text-center font-medium">Agent Chat</span>
+    </header>
+    <ConversationArea />
+    <Composer />
+  </main>
+  <aside className="hidden xl:block w-[320px] border-l border-border">
+    <WorkPanel />
+  </aside>
+</div>
+```
+
+---
+
+## Column Rules
+
+| Content Type | Mobile | sm | lg | xl |
+|-------------|--------|-----|-----|-----|
+| KPI cards | 1 col | 2 col | 4 col | 4 col |
+| Feature cards | 1 col | 2 col | 3 col | 3 col |
+| Charts | 1 col | 1 col | 2 col | 2 col |
+| Pricing tiers | 1 col | 2 col | 3 col | 3 col |
+| Settings sections | 1 col | 1 col | sidebar + content | sidebar + content |
+
+---
+
+## Responsive Testing Checklist
+
+Before shipping any page:
+
+1. 375px (iPhone SE): no horizontal overflow, all text readable, touch targets 44px
+2. 640px (sm): 2-column grids activate where expected
+3. 1024px (lg): full layout with sidebar/multi-panel visible
+4. 1280px (xl): max-width containers kick in, no over-stretching
+5. Landscape orientation: no layout breakage
+6. Tab order matches visual order at every breakpoint
+
+---
+
+## Forbidden Responsive Patterns
+
+| Pattern | Why | Instead |
+|---------|-----|---------|
+| `h-screen` / `min-h-screen` | Mobile viewport bug (address bar) | `h-dvh` / `min-h-dvh` |
+| Horizontal scroll on page body | Breaks mobile | Scroll only within contained tables |
+| Fixed pixel widths on containers | Breaks at smaller screens | Use responsive max-w + percentage |
+| Hiding critical content at mobile | Information loss | Restructure or use drawers/sheets |

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

@@ -0,0 +1,252 @@
+# State Machines
+
+Page state machines, loading tiers, form states, streaming UI states, and error handling patterns.
+
+---
+
+## Universal Page States
+
+Every page implements a subset of these states. Recipes specify which apply.
+
+```
+                   +----------+
+          fetch -> | loading  | -> data arrives -> has-data
+                   +----------+          |
+                        |            (zero records)
+                    (failure)             |
+                        v                 v
+                   +----------+    +----------+
+                   |  error   |    |  empty   |
+                   +----------+    +----------+
+                        |
+                    (retry) -> loading
+```
+
+### State to Visual Mapping
+
+| State | Component | Layout |
+|-------|-----------|--------|
+| `loading` | `Skeleton` matching content shape | Same grid as `has-data` |
+| `empty` | `Empty` with icon + title + desc + CTA | Centered in content area |
+| `error` | `Alert` variant="destructive" + retry `Button` | Top of content area |
+| `has-data` | Real components | Full layout |
+
+**Skeleton rule**: The skeleton must match the eventual content layout. If `has-data` shows a 4-column KPI grid, the skeleton shows 4 skeleton cards in the same grid.
+
+---
+
+## Loading Tiers
+
+```
+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
+```
+
+| Tier | Component | When |
+|------|-----------|------|
+| Skeleton | `Skeleton` shaped to match content | Default for data fetches (< 1s expected) |
+| Spinner | `Spinner` centered with optional label | Longer operations (1-3s) |
+| Progress | `Progress` bar with percentage or indeterminate | File uploads, batch operations (3s+) |
+
+---
+
+## Form States
+
+```
++----------+   input   +----------+   submit   +------------+
+| pristine | --------> |  dirty   | ---------> | submitting |
++----------+           +----------+            +------------+
+                            |                     |       |
+                        (validate)            (success) (failure)
+                            |                     |       |
+                            v                     v       v
+                   +------------------+    +--------+ +------------------+
+                   | validation-error |    |success | | submission-error |
+                   +------------------+    +--------+ +------------------+
+```
+
+| State | Visual |
+|-------|--------|
+| `pristine` | Form rendered, no changes, submit button may be disabled |
+| `dirty` | User has modified a field, unsaved changes indicator |
+| `submitting` | Submit button shows spinner, form disabled |
+| `validation-error` | Field-level error messages below invalid fields |
+| `submission-error` | `Alert` at top of form with server error |
+| `success` | Toast notification or redirect |
+
+### Form Implementation Pattern
+
+```tsx
+import { useForm } from "react-hook-form"
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@vadimcomanescu/nadicode-design-system/form"
+
+function MyForm() {
+  const form = useForm<FormValues>({ defaultValues: { name: "" } })
+  const { formState: { isDirty, isSubmitting } } = form
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>  {/* Always stacked, above */}
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormMessage />  {/* Validation error */}
+            </FormItem>
+          )}
+        />
+        <Button type="submit" disabled={!isDirty || isSubmitting}>
+          {isSubmitting ? <Spinner /> : "Save"}
+        </Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+---
+
+## CRUD List States
+
+```
++----------+   fetch   +----------+   filter   +------------+
+| loading  | --------> | has-data | ---------> | filtering  |
++----------+           +----------+            +------------+
+     |                      |                       |
+  (error)              (zero results)          (zero matches)
+     |                      |                       |
+     v                      v                       v
++----------+           +----------+          +--------------+
+|  error   |           |  empty   |          | empty-filter |
++----------+           +----------+          +--------------+
+```
+
+| State | Visual |
+|-------|--------|
+| `loading` | `Skeleton` table rows |
+| `has-data` | `DataTable` with rows |
+| `filtering` | Same table, possibly with loading indicator on filter |
+| `empty` | `Empty` with "No [entities] yet" + create CTA |
+| `empty-filter` | `Empty` with "No results match your filters" + clear filter CTA |
+| `error` | `Alert` with retry |
+
+---
+
+## Settings States
+
+```
++----------+   load   +----------+   change   +----------+
+| loading  | -------> | default  | ---------> |  dirty   |
++----------+          +----------+            +----------+
+                                                  |
+                                              (save)
+                                                  |
+                                                  v
+                                            +----------+
+                                            | saving   |
+                                            +----------+
+                                              |      |
+                                          (success) (error)
+                                              |      |
+                                              v      v
+                                         +------+ +-------+
+                                         |saved | |error  |
+                                         +------+ +-------+
+                                           |2s|
+                                           v
+                                        default
+```
+
+| State | Visual |
+|-------|--------|
+| `loading` | Skeleton cards matching settings layout |
+| `default` | Settings rendered with current values |
+| `dirty` | Unsaved changes indicator, save button enabled |
+| `saving` | Save button shows spinner |
+| `saved` | Toast "Settings saved" (auto-dismiss 2s) |
+| `error` | Toast variant="destructive" with error message |
+
+### Save Patterns
+
+| Pattern | When | Implementation |
+|---------|------|----------------|
+| Explicit save | Default for most settings | Save button at bottom of section/form |
+| Auto-save | Simple toggles (Switch) | Debounced save on change + optimistic UI |
+| Inline save | Per-field edit (rare) | Edit button -> input -> save/cancel |
+
+---
+
+## Streaming States (Agent/Chat)
+
+```
++----------+   connect   +-----------+   message   +-----------+
+|  idle    | ----------> | connected | ----------> | streaming |
++----------+             +-----------+             +-----------+
+                              |                         |
+                          (disconnect)              (complete)
+                              |                         |
+                              v                         v
+                        +-------------+           +-----------+
+                        | reconnecting|           | connected |
+                        +-------------+           +-----------+
+```
+
+### Agent-Specific States
+
+| State | Component | Visual |
+|-------|-----------|--------|
+| `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) |
+| `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
+```
+
+---
+
+## Error Handling
+
+### Error Hierarchy
+
+1. **Field-level**: `FormMessage` below the field (validation errors)
+2. **Section-level**: `Alert` at top of section (submission errors)
+3. **Page-level**: Next.js `error.tsx` boundary (unrecoverable errors)
+4. **Global**: Toast via `Sonner` (transient errors, API failures)
+
+### Error Recovery
+
+| Error Type | Recovery | Component |
+|------------|----------|-----------|
+| Validation | Fix field, resubmit | `FormMessage` |
+| Network (transient) | Retry button | `Alert` + `Button` |
+| Auth (401) | Redirect to login | `redirect("/login")` |
+| Not found (404) | Go home or search | `NotFoundBlock` |
+| Server error (500) | Retry or contact support | Error page |