groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-nextjs-engineer/references/type-system.md

@@ -0,0 +1,368 @@
+# Type System & Schemas
+
+## Table of Contents
+- [Zod as the Contract](#zod-as-the-contract)
+- [Schema Organisation](#schema-organisation)
+- [Deriving Types](#deriving-types)
+- [Discriminated Unions](#discriminated-unions)
+- [Exhaustive Matching](#exhaustive-matching)
+- [The Result Pattern](#the-result-pattern)
+- [RSC Serialisation Boundary](#rsc-serialisation-boundary)
+- [Type Guards over any](#type-guards-over-any)
+
+---
+
+## Zod as the Contract
+
+Zod schemas are the single source of truth for all data shapes in the codebase. They serve as the type contract between the Go backend API and the React frontend. Every API response is validated against a Zod schema, and all TypeScript types for API data are derived from those schemas.
+
+Standalone TypeScript interfaces for API data are forbidden — they drift from reality. Zod schemas enforce runtime validation and compile-time types simultaneously.
+
+```tsx
+// lib/schemas/meeting.ts
+import { z } from 'zod';
+
+export const meetingSchema = z.object({
+  id: z.string().uuid(),
+  title: z.string().min(1),
+  status: z.enum(['scheduled', 'in_progress', 'completed', 'cancelled']),
+  host_id: z.string().uuid(),
+  starts_at: z.string().datetime(),
+  duration_minutes: z.number().int().positive(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+export type Meeting = z.infer<typeof meetingSchema>;
+
+export const meetingListSchema = z.object({
+  data: z.array(meetingSchema),
+  pagination: z.object({
+    next_cursor: z.string().nullable(),
+    has_more: z.boolean(),
+  }),
+});
+
+export type MeetingList = z.infer<typeof meetingListSchema>;
+```
+
+### Why Zod over Interfaces
+
+- **Runtime validation** — API responses are parsed, not assumed. If the backend changes a field name or type, the schema catches it immediately instead of producing silent runtime bugs.
+- **Single definition** — The schema defines shape, constraints, and TypeScript type in one place.
+- **Form integration** — Zod schemas plug directly into `react-hook-form` via `@hookform/resolvers/zod` for validation.
+
+---
+
+## Schema Organisation
+
+All schemas live in `lib/schemas/` with zero internal application dependencies. A schema file must never import from hooks, components, contexts, or the API client.
+
+```
+lib/schemas/
+├── meeting.ts                 # Meeting entity schemas
+├── meeting-synthesis.ts       # Synthesis-related schemas
+├── user.ts                    # User entity schemas
+├── common.ts                  # Shared schemas (pagination, error responses)
+└── index.ts                   # Barrel export
+```
+
+Each file exports:
+1. The Zod schema object (`meetingSchema`)
+2. The inferred TypeScript type (`Meeting`)
+3. Any sub-schemas needed for forms or partial updates
+
+```tsx
+// lib/schemas/index.ts
+export { meetingSchema, type Meeting, meetingListSchema, type MeetingList } from './meeting';
+export { userSchema, type User } from './user';
+export { paginationSchema, type Pagination } from './common';
+```
+
+---
+
+## Deriving Types
+
+Always derive types from schemas using `z.infer`. Never write parallel TypeScript interfaces.
+
+```tsx
+// Correct — type derived from schema
+export const meetingSchema = z.object({ /* ... */ });
+export type Meeting = z.infer<typeof meetingSchema>;
+
+// Incorrect — standalone interface duplicates the schema and will drift
+export interface Meeting {
+  id: string;
+  title: string;
+  // This will get out of sync with the schema
+}
+```
+
+### Partial and Pick Types
+
+Derive form-specific types from the base schema:
+
+```tsx
+// Schema for creating a meeting (subset of fields)
+export const createMeetingSchema = meetingSchema.pick({
+  title: true,
+  starts_at: true,
+  duration_minutes: true,
+});
+
+export type CreateMeetingInput = z.infer<typeof createMeetingSchema>;
+
+// Schema for updating a meeting (all fields optional)
+export const updateMeetingSchema = meetingSchema.partial().omit({
+  id: true,
+  created_at: true,
+  updated_at: true,
+});
+
+export type UpdateMeetingInput = z.infer<typeof updateMeetingSchema>;
+```
+
+---
+
+## Discriminated Unions
+
+Use discriminated unions to model states that are mutually exclusive. This prevents impossible states at the type level — the compiler enforces that only valid combinations of fields are accessed.
+
+```tsx
+// Correct — discriminated union makes invalid states impossible
+const meetingInputSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('recording'),
+    recording_url: z.string().url(),
+    device_id: z.string(),
+  }),
+  z.object({
+    type: z.literal('upload'),
+    file_path: z.string(),
+    file_size: z.number().positive(),
+  }),
+]);
+
+type MeetingInput = z.infer<typeof meetingInputSchema>;
+
+// Usage — the compiler knows which fields exist based on type
+function processMeetingInput(input: MeetingInput) {
+  switch (input.type) {
+    case 'recording':
+      // TypeScript knows recording_url and device_id exist here
+      startRecording(input.recording_url, input.device_id);
+      break;
+    case 'upload':
+      // TypeScript knows file_path and file_size exist here
+      uploadFile(input.file_path, input.file_size);
+      break;
+  }
+}
+```
+
+```tsx
+// Incorrect — loose optional fields allow impossible states
+const meetingInputSchema = z.object({
+  type: z.enum(['recording', 'upload']),
+  recording_url: z.string().url().optional(),      // When is this present?
+  device_id: z.string().optional(),                 // What if type is 'upload'?
+  file_path: z.string().optional(),                 // What if type is 'recording'?
+  file_size: z.number().positive().optional(),
+});
+// Nothing prevents { type: 'recording', file_path: '/foo' }
+```
+
+---
+
+## Exhaustive Matching
+
+Always enforce exhaustive matching on discriminated unions using `default: never`. This catches unhandled cases at compile time when new variants are added.
+
+```tsx
+type MeetingStatus = Meeting['status'];  // 'scheduled' | 'in_progress' | 'completed' | 'cancelled'
+
+function getStatusLabel(status: MeetingStatus): string {
+  switch (status) {
+    case 'scheduled':
+      return 'Upcoming';
+    case 'in_progress':
+      return 'Live';
+    case 'completed':
+      return 'Done';
+    case 'cancelled':
+      return 'Cancelled';
+    default: {
+      // If a new status is added to the enum, this line produces a compile error
+      const _exhaustive: never = status;
+      return _exhaustive;
+    }
+  }
+}
+```
+
+When a fifth status (e.g., `'archived'`) is added to the schema, the compiler flags every switch statement that doesn't handle it.
+
+---
+
+## The Result Pattern
+
+All Server Actions return a strictly typed `ActionResult<T>` to prevent unhandled client-side crashes from failed mutations. A Server Action must never throw — it always returns a result.
+
+### Type Definition
+
+```tsx
+// lib/schemas/common.ts
+type ActionResult<T> =
+  | { data: T; error: null }
+  | { data: null; error: string };
+```
+
+### Server Action Implementation
+
+```tsx
+// app/actions/meeting-actions.ts
+'use server';
+
+import { createMeetingSchema, type Meeting } from '@/lib/schemas';
+import { createMeeting } from '@/lib/api';
+import { revalidatePath } from 'next/cache';
+
+export async function createMeetingAction(
+  formData: FormData
+): Promise<ActionResult<Meeting>> {
+  const parsed = createMeetingSchema.safeParse({
+    title: formData.get('title'),
+    starts_at: formData.get('starts_at'),
+    duration_minutes: Number(formData.get('duration_minutes')),
+  });
+
+  if (!parsed.success) {
+    return { data: null, error: parsed.error.issues[0].message };
+  }
+
+  try {
+    const meeting = await createMeeting(parsed.data);
+    revalidatePath('/meetings');
+    return { data: meeting, error: null };
+  } catch {
+    return { data: null, error: 'Failed to create meeting. Please try again.' };
+  }
+}
+```
+
+### Client Consumption
+
+```tsx
+'use client';
+
+import { createMeetingAction } from '@/app/actions/meeting-actions';
+import { useTransition } from 'react';
+
+function CreateMeetingButton() {
+  const [isPending, startTransition] = useTransition();
+
+  async function handleSubmit(formData: FormData) {
+    startTransition(async () => {
+      const result = await createMeetingAction(formData);
+      if (result.error) {
+        // Show error in UI — never an unhandled throw
+        toast.error(result.error);
+        return;
+      }
+      // Successfully created
+      toast.success(`Created: ${result.data.title}`);
+    });
+  }
+
+  return (
+    <form action={handleSubmit}>
+      {/* form fields */}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating…' : 'Create Meeting'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## RSC Serialisation Boundary
+
+When a Server Component passes props to a Client Component, those props must be JSON-serialisable. React serialises them across the server-client boundary, and non-serialisable values either silently corrupt or crash.
+
+### What Can Cross the Boundary
+
+| Type | Serialisable? | Notes |
+|------|-------------|-------|
+| `string`, `number`, `boolean` | Yes | |
+| `null`, `undefined` | Yes | |
+| Plain objects and arrays | Yes | No class instances |
+| Server Actions (`'use server'`) | Yes | The only exception for functions |
+| `Date` | **No** | Silently becomes a string — `.getFullYear()` crashes on the client |
+| `Map`, `Set` | **No** | Silently stripped |
+| Functions (non-Server Action) | **No** | Cannot be serialised |
+| Class instances | **No** | Methods are stripped |
+| `Symbol` | **No** | Unless globally registered |
+
+### Fixing Non-Serialisable Props
+
+```tsx
+// Bad — Date object silently becomes string, then crashes
+export default async function Page() {
+  const meeting = await getMeeting(id);
+  return <MeetingCard createdAt={meeting.created_at} />;  // Date object
+}
+
+// Good — serialise to ISO string on the server
+export default async function Page() {
+  const meeting = await getMeeting(id);
+  return <MeetingCard createdAt={meeting.created_at.toISOString()} />;
+}
+
+// Bad — Map cannot be serialised
+<ClientComponent items={new Map([['a', 1]])} />
+
+// Good — convert to plain object
+<ClientComponent items={Object.fromEntries(map)} />
+
+// Bad — function prop (not a Server Action)
+export default function Page() {
+  const handleClick = () => console.log('clicked');
+  return <ClientButton onClick={handleClick} />;  // Cannot serialise
+}
+
+// Good — define the function inside the client component
+'use client';
+export function ClientButton() {
+  const handleClick = () => console.log('clicked');
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+
+---
+
+## Type Guards over any
+
+The `any` type is forbidden. When dealing with unknown data (external APIs, dynamic content, user input), use `unknown` and narrow the type using type guards or Zod parsing.
+
+```tsx
+// Bad — any bypasses all type checking
+function processResponse(data: any) {
+  return data.meetings[0].title;  // No type safety — runtime explosion
+}
+
+// Good — unknown + Zod parsing
+function processResponse(data: unknown) {
+  const parsed = meetingListSchema.safeParse(data);
+  if (!parsed.success) {
+    throw new Error(`Invalid API response: ${parsed.error.message}`);
+  }
+  return parsed.data.data[0].title;  // Fully typed
+}
+
+// Good — type guard for narrowing
+function isMeeting(value: unknown): value is Meeting {
+  return meetingSchema.safeParse(value).success;
+}
+```

package/src/engineer-skills/groundwork-nextjs-engineer/references/ux-principles.md

@@ -0,0 +1,278 @@
+# UX Principles
+
+## Table of Contents
+- [Speed & Interaction](#speed--interaction)
+- [Navigation & Control](#navigation--control)
+- [Information Architecture](#information-architecture)
+- [Feedback & Motion](#feedback--motion)
+- [Accessibility](#accessibility)
+- [Empty States & Onboarding](#empty-states--onboarding)
+- [Copy & Tone](#copy--tone)
+
+---
+
+## Speed & Interaction
+
+The UI must feel zero-latency for common actions. Speed is not a feature — it is the foundation of trust.
+
+### Principles
+
+- **Focus inputs immediately** — When a form or dialog opens, the primary input field must be focused without the user touching the mouse. Use `autoFocus` or `useRef` + `useEffect`.
+- **Inline editing** — Treat "viewing" and "editing" as the same action. Clicking a text element activates an in-place input. No separate "edit" screens, no confirmation dialogs for routine edits.
+- **Optimistic UI** — Update the interface immediately when the user acts. Show the intended result while the server confirms. Revert only on failure. See `references/data-fetching.md` for the SWR `mutate()` pattern.
+- **Instant resets** — After a successful form submission, clear all fields immediately so the user can submit the next entry without reaching for a mouse or navigating.
+
+### Anti-patterns
+
+| Don't | Why | Do Instead |
+|-------|-----|-----------|
+| Separate "view" and "edit" screens | Forces navigation for simple edits | Inline editing — click to edit in place |
+| Full-page loading spinner for submissions | Blocks the entire UI for a single operation | Optimistic update + subtle loading indicator on the action element |
+| "Are you sure?" confirmation dialogs for reversible actions | Interrupts flow unnecessarily | Allow immediate action; provide "Undo" for 5 seconds |
+| Unfocused form dialogs | User must click to start typing | `autoFocus` on the primary field |
+
+---
+
+## Navigation & Control
+
+### Command Palette
+
+The command palette is the central navigation hub. Users can search for anything — pages, actions, meetings, settings — from a single keyboard-activated overlay.
+
+- Launch with `⌘K` (macOS) / `Ctrl+K`
+- Results group by category (pages, actions, recent items)
+- Keyboard navigation with arrow keys + Enter
+- Uses `.surface-elevated` styling (see `references/visual-language.md`)
+
+### Keyboard Shortcuts
+
+Power users should never be forced to use the mouse. Provide shortcuts for frequent actions:
+
+| Action | Shortcut | Context |
+|--------|----------|---------|
+| Command palette | `⌘K` | Global |
+| Quick search | `/` | When no input is focused |
+| New meeting | `N` | Meeting list view |
+| Close modal/dialog | `Escape` | Any overlay |
+
+### Context Switching
+
+Switching between views should be instantaneous. Use layout-based navigation so the sidebar and header persist while only the content panel changes. Avoid full-page reloads.
+
+---
+
+## Information Architecture
+
+### Content-First Layout
+
+The most important content occupies the largest surface area and appears first in the visual hierarchy. Use the bento grid to establish importance through sizing (see `references/visual-language.md`).
+
+### Progressive Disclosure
+
+Show only what matters right now. Additional details reveal on interaction:
+- Expand/collapse sections for secondary information
+- Hover cards for quick previews
+- Drill-down for detailed views
+
+### Opacity-Based Depth
+
+Use text opacity to create visual hierarchy without additional colours:
+- Primary text: full opacity via `--color-text-primary`
+- Secondary text (metadata, timestamps): reduced opacity via `--color-text-secondary`
+- Disabled/inactive elements: further reduced opacity
+
+### Focal Points
+
+Create clear visual focal points using:
+- **Typography weight** — Bold headings draw the eye before body text
+- **Surface area** — Larger bento grid cells command more attention
+- **Colour contrast** — Accent colour on CTAs, muted tones for everything else
+- **Motion** — The first (and only) animated element on screen is the focal point
+
+---
+
+## Feedback & Motion
+
+### Liquid Transitions
+
+All transitions should feel organic and fluid — never mechanical or jarring.
+
+- **Entry:** Elements fade in and slide from their origin direction (bottom sheet from bottom, sidebar from left, tooltip from near the trigger)
+- **Duration:** 150-300ms for micro-interactions (button press, toggle); 300-500ms for layout transitions (panel open/close)
+- **Easing:** `ease-out` for elements appearing; `ease-in` for elements leaving. Never `linear`.
+
+### Tactile Scale Shifts
+
+Interactive elements respond to press with a subtle scale reduction:
+
+```css
+.interactive-element {
+  transition: transform 150ms ease-out;
+}
+
+.interactive-element:active {
+  transform: scale(0.97);  /* 3% reduction — barely perceptible, deeply satisfying */
+}
+```
+
+Never exceed 5% scale change — larger shifts feel cartoonish.
+
+### Calm Alerts
+
+Notifications and status indicators use the semantic role tokens from the design system — never a hand-picked hex. The specific hue for each role (often muted rather than a harsh stoplight) is the design system's decision; consume the role, not a colour.
+
+| State | Role token |
+|-------|------------|
+| Success | the `success` role |
+| Error | the `error` / `destructive` role |
+| Warning | the `warning` role |
+| Info | the `info` role |
+
+Toasts and banners should be dismissible, auto-fade after a reasonable duration (4-6 seconds for success, persistent for errors), and never stack vertically in a pile of doom.
+
+### Progressive Disclosure of Actions
+
+Actions should reveal contextually — on hover, on selection, or on focus. Don't show every possible action at all times.
+
+```tsx
+// Actions appear on hover/focus
+<div className="group relative">
+  <MeetingCard meeting={meeting} />
+  <div className="absolute top-2 right-2 opacity-0 group-hover:opacity-100 
+                  group-focus-within:opacity-100 transition-opacity">
+    <EditButton />
+    <DeleteButton />
+  </div>
+</div>
+```
+
+---
+
+## Accessibility
+
+Accessibility is not optional — it is a baseline requirement.
+
+### Contrast
+
+- Body text must meet **WCAG AA** (4.5:1 contrast ratio)
+- Large text (18px+ or 14px+ bold) must meet **3:1**
+- Interactive elements must meet **3:1** against their background
+- Test in both dark and light themes
+
+### Focus States
+
+- All interactive elements must have a visible focus indicator
+- Focus indicators must contrast with the background (not just browser default outline)
+- Tab order must follow visual layout order
+
+```css
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}
+```
+
+### Semantic HTML & ARIA
+
+- Use semantic elements: `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<header>`, `<footer>`
+- Icon-only buttons must have `aria-label`:
+  ```tsx
+  <button onClick={handleClose} aria-label="Close dialog">
+    <X size={20} />
+  </button>
+  ```
+- Use `role="alert"` for error messages that must be announced by screen readers
+- Never use `div` or `span` for clickable elements — use `button` or `a`
+
+### Colour Independence
+
+- Never communicate information through colour alone
+- Pair colour indicators with icons or text labels:
+  ```tsx
+  // Bad — colour-only status
+  <span className="text-success">●</span>
+  
+  // Good — colour + icon + text
+  <span className="text-success flex items-center gap-1">
+    <CheckCircle size={16} aria-hidden />
+    Completed
+  </span>
+  ```
+
+---
+
+## Empty States & Onboarding
+
+### Day-Zero Experience
+
+When a user first encounters a section with no data, the empty state should:
+1. Explain what this section is for
+2. Provide a single clear action to populate it
+3. Use a friendly illustration or icon (not a blank page)
+
+```tsx
+export function EmptyMeetingList() {
+  return (
+    <div className="surface-glass p-8 text-center">
+      <CalendarPlus size={48} className="mx-auto text-muted-foreground" aria-hidden />
+      <h3 className="text-title mt-4">No meetings yet</h3>
+      <p className="text-muted-foreground mt-2">
+        Schedule your first meeting to get started.
+      </p>
+      <Button className="mt-6">
+        <Plus size={16} aria-hidden />
+        Schedule Meeting
+      </Button>
+    </div>
+  );
+}
+```
+
+### Actionable Error States
+
+Error states must tell the user what went wrong and what they can do about it. Never show raw error codes or technical jargon.
+
+```tsx
+// Bad
+<p>Error 500: ECONNREFUSED</p>
+
+// Good
+<div className="surface-glass p-6 text-center" role="alert">
+  <AlertCircle size={32} className="mx-auto text-destructive" aria-hidden />
+  <h3 className="text-title mt-4">Couldn't load your meetings</h3>
+  <p className="text-muted-foreground mt-2">
+    We're having trouble connecting right now. Your data is safe.
+  </p>
+  <Button onClick={reset} className="mt-4">Try again</Button>
+</div>
+```
+
+### Input Preservation
+
+If a form submission fails, **never clear the user's input**. The react-hook-form + ActionResult pattern handles this automatically — `form.setError()` displays the server error without resetting field values.
+
+---
+
+## Copy & Tone
+
+### Voice Principles
+
+- **Concise** — Say it in fewer words. If a label can be one word, use one word.
+- **Active voice** — "Meeting created" not "A meeting has been created."
+- **Context-sensitive** — Error messages are empathetic. Success messages are brief. Help text is instructional.
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Success | Brief, confident | "Saved" / "Meeting created" |
+| Error | Empathetic, actionable | "Couldn't save. Check your connection and try again." |
+| Empty state | Encouraging, helpful | "No meetings yet. Schedule your first one." |
+| Destructive action | Clear, honest | "Delete this meeting? This can't be undone." |
+| Loading | Invisible preferred | Use skeleton UI, not "Loading..." text |
+
+### Punctuation
+
+- Button labels: no period ("Save", not "Save.")
+- Toast messages: no period ("Meeting created", not "Meeting created.")
+- Error messages: period at end if a full sentence ("Check your connection and try again.")
+- Labels: no period ("Duration", not "Duration:")