@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/debugging.md

@@ -0,0 +1,281 @@
+---
+name: debugging
+description: Debug effectively with Chrome DevTools, Node inspector, console methods, memory leak detection, and performance profiling.
+---
+
+# Debugging Techniques
+
+## When to Use
+
+Use these techniques when something is broken and you don't know why, when
+performance degrades unexpectedly, or when you need to understand unfamiliar
+code. The best debuggers are systematic — they narrow down the problem space
+with each step instead of making random changes.
+
+## How It Works
+
+### 1. The Debugging Process
+
+Before touching tools, follow this sequence:
+
+1. **Reproduce** — Write down exact steps to trigger the bug
+2. **Isolate** — Find the smallest input or condition that causes it
+3. **Hypothesize** — Form a specific theory about what's wrong
+4. **Test** — Verify with a targeted check (breakpoint, log, test)
+5. **Fix** — Change one thing, confirm it resolves the issue
+6. **Verify** — Run the full reproduction to confirm, add a regression test
+
+### 2. Chrome DevTools — Sources Panel
+
+Set breakpoints directly in your code:
+
+```javascript
+// Conditional breakpoint — only breaks when condition is true
+// Right-click the line number → "Add conditional breakpoint"
+// Condition: user.id === 'usr_problem_account'
+
+// Logpoint — logs without pausing (no console.log commits needed)
+// Right-click → "Add logpoint"
+// Expression: 'Order total:', order.total, 'items:', order.items.length
+```
+
+Useful breakpoint types:
+| Type | How to set | When it breaks |
+|------|-----------|---------------|
+| Line | Click line number | Every time that line executes |
+| Conditional | Right-click → condition | Only when expression is truthy |
+| DOM | Elements → right-click node → Break on | When DOM node is modified |
+| XHR/Fetch | Sources → XHR breakpoints | When URL pattern matches |
+| Event listener | Sources → Event Listener Breakpoints | On click, keydown, etc. |
+| Exception | Sources → Pause on exceptions | On thrown error |
+
+### 3. Node.js Inspector
+
+Debug server-side code with Chrome DevTools.
+
+```bash
+# Start with inspector
+node --inspect dist/server.js
+
+# Break on first line (useful for startup issues)
+node --inspect-brk dist/server.js
+
+# Attach to a running process
+kill -USR1 <pid>  # enables inspector on the process
+```
+
+Open `chrome://inspect` in Chrome, click "inspect" on your process.
+
+For Vitest:
+
+```bash
+# Debug a specific test
+node --inspect-brk ./node_modules/.bin/vitest run --no-file-parallelism src/auth.test.ts
+```
+
+### 4. Console Methods Beyond console.log
+
+```typescript
+// Structured table output
+console.table(users.map(u => ({ id: u.id, name: u.name, role: u.role })));
+
+// Group related logs
+console.group('Order Processing');
+console.log('Validating items:', items.length);
+console.log('Calculating total:', total);
+console.warn('Discount code expired');
+console.groupEnd();
+
+// Measure execution time
+console.time('db-query');
+const result = await db.query(sql);
+console.timeEnd('db-query'); // db-query: 42.3ms
+
+// Count occurrences
+function processEvent(event: Event) {
+  console.count(event.type); // click: 1, click: 2, click: 3
+}
+
+// Assert — logs only when condition is false
+console.assert(user.age >= 0, 'Negative age:', user);
+
+// Trace — print call stack
+function unexpectedCall() {
+  console.trace('Who called this?');
+}
+
+// Dir — inspect object properties
+console.dir(complexObject, { depth: 4, colors: true });
+```
+
+### 5. Source Maps
+
+Ensure source maps work in development so stack traces point to original
+TypeScript, not compiled JavaScript.
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  build: {
+    sourcemap: true, // generates .map files
+  },
+});
+
+// tsconfig.json
+{
+  "compilerOptions": {
+    "sourceMap": true,
+    "declarationMap": true
+  }
+}
+```
+
+For production error tracking (Sentry, etc.), upload source maps during build
+but don't serve them publicly:
+
+```bash
+# Upload to Sentry, don't include in deployment
+sentry-cli sourcemaps upload --release=v1.2.3 ./dist
+```
+
+### 6. Memory Leak Detection
+
+Signs of a memory leak: increasing memory over time, page becoming sluggish,
+"out of memory" crashes.
+
+**Browser — DevTools Memory panel:**
+
+```
+1. Open Memory tab
+2. Take heap snapshot (baseline)
+3. Perform the suspected leaking action several times
+4. Take another snapshot
+5. Select "Comparison" view between snapshots
+6. Sort by "# New" to find objects that accumulate
+```
+
+**Common React memory leaks:**
+
+```typescript
+// Leak: effect cleanup missing
+useEffect(() => {
+  const interval = setInterval(fetchData, 5000);
+  // Missing: return () => clearInterval(interval);
+}, []);
+
+// Leak: event listener not removed
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize); // fix
+}, []);
+
+// Leak: updating state on unmounted component
+useEffect(() => {
+  let cancelled = false;
+  fetchData().then(data => {
+    if (!cancelled) setData(data); // guard against unmounted update
+  });
+  return () => { cancelled = true; };
+}, []);
+```
+
+**Node.js — heap snapshots:**
+
+```bash
+# Take a snapshot at runtime
+node --inspect dist/server.js
+# In DevTools: Memory → Take snapshot
+
+# Or programmatically
+node -e "
+  const v8 = require('v8');
+  const fs = require('fs');
+  const snapshot = v8.writeHeapSnapshot();
+  console.log('Snapshot written to:', snapshot);
+"
+```
+
+### 7. Performance Profiling
+
+**Browser — Performance panel:**
+
+```
+1. Open Performance tab
+2. Click Record
+3. Perform the slow action
+4. Stop recording
+5. Look for: long tasks (>50ms), layout thrashing, excessive re-renders
+```
+
+**React Profiler:**
+
+```tsx
+import { Profiler } from 'react';
+
+function onRender(id: string, phase: string, actualDuration: number) {
+  if (actualDuration > 16) { // longer than one frame
+    console.warn(`Slow render: ${id} took ${actualDuration.toFixed(1)}ms`);
+  }
+}
+
+<Profiler id="Dashboard" onRender={onRender}>
+  <Dashboard />
+</Profiler>
+```
+
+Install React DevTools browser extension for the dedicated Profiler tab with
+flame graphs and component render reasons.
+
+**Node.js — CPU profiling:**
+
+```bash
+# Profile for 10 seconds
+node --prof dist/server.js
+# Generate readable output
+node --prof-process isolate-*.log > profile.txt
+
+# Or use clinic.js for automated analysis
+npx clinic doctor -- node dist/server.js
+```
+
+### 8. Network Debugging
+
+```bash
+# Watch all requests/responses
+# Chrome DevTools → Network tab → Preserve log
+
+# cURL to reproduce API issues
+curl -v -X POST https://api.example.com/users \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "test"}'
+
+# DNS resolution issues
+nslookup api.example.com
+dig api.example.com
+
+# Test connectivity
+curl -o /dev/null -s -w "HTTP %{http_code}, Time: %{time_total}s\n" https://api.example.com/health
+```
+
+## Examples
+
+| Problem | Tool | What to look for |
+|---------|------|-----------------|
+| Function returns wrong value | Conditional breakpoint | Variable values at the branch point |
+| Slow page load | Network tab | Large responses, waterfall gaps |
+| Growing memory | Memory snapshots | Comparison view, increasing object counts |
+| Slow interaction | Performance panel | Long tasks, excessive layout recalc |
+| Can't reproduce locally | Logpoints | Non-intrusive data collection |
+| Regression in recent commits | `git bisect` | First commit that breaks the test |
+
+## Checklist
+
+- [ ] Bug report includes exact reproduction steps before debugging starts
+- [ ] Source maps are enabled in development for readable stack traces
+- [ ] `console.log` debugging is replaced with breakpoints or logpoints before committing
+- [ ] Memory-intensive pages are profiled with heap snapshots
+- [ ] Effects and event listeners always clean up in the return function
+- [ ] Performance profiling targets specific slow interactions, not the whole page
+- [ ] Production errors are tracked with Sentry or equivalent (with source maps uploaded)
+- [ ] No `console.log` or `debugger` statements are committed to the codebase

package/assets/skills/design-system.md

@@ -0,0 +1,289 @@
+---
+name: design-system
+description: Build design systems — tokens, component APIs, variants, compound components, Storybook, and theming.
+---
+
+# Design System Patterns
+
+## When to Use
+
+Build a design system when your application has more than a handful of shared
+UI components, or when multiple teams or projects share a visual language.
+This skill covers design tokens, component API design, variant patterns,
+compound components, Storybook documentation, and theming. Apply early —
+retrofitting consistency into an ad-hoc component library is expensive.
+
+## How It Works
+
+### 1. Design Tokens — The Foundation
+
+Tokens are named values that encode design decisions. Define once, use everywhere.
+
+```typescript
+// tokens.ts — single source of truth
+export const tokens = {
+  color: {
+    primary:    { 50: '#eff6ff', 100: '#dbeafe', 500: '#3b82f6', 600: '#2563eb', 700: '#1d4ed8', 900: '#1e3a5f' },
+    neutral:    { 50: '#fafafa', 100: '#f5f5f5', 200: '#e5e5e5', 500: '#737373', 700: '#404040', 900: '#171717' },
+    success:    { 500: '#22c55e', 700: '#15803d' },
+    warning:    { 500: '#f59e0b', 700: '#b45309' },
+    danger:     { 500: '#ef4444', 700: '#b91c1c' },
+  },
+  spacing: {
+    0: '0',      1: '0.25rem', 2: '0.5rem',  3: '0.75rem',
+    4: '1rem',   5: '1.25rem', 6: '1.5rem',  8: '2rem',
+    10: '2.5rem', 12: '3rem',  16: '4rem',   20: '5rem',
+  },
+  radius: {
+    none: '0',   sm: '0.25rem', md: '0.375rem',
+    lg: '0.5rem', xl: '0.75rem', full: '9999px',
+  },
+  font: {
+    family: { sans: 'Inter, system-ui, sans-serif', mono: 'JetBrains Mono, monospace' },
+    size:   { xs: '0.75rem', sm: '0.875rem', base: '1rem', lg: '1.125rem', xl: '1.25rem', '2xl': '1.5rem' },
+    weight: { normal: '400', medium: '500', semibold: '600', bold: '700' },
+  },
+  shadow: {
+    sm: '0 1px 2px rgba(0,0,0,0.05)',
+    md: '0 4px 6px -1px rgba(0,0,0,0.1)',
+    lg: '0 10px 15px -3px rgba(0,0,0,0.1)',
+  },
+} as const;
+```
+
+### 2. Component API Design — Props as Variants
+
+Use a constrained set of variants, not arbitrary style props.
+
+```typescript
+import { cva, type VariantProps } from 'class-variance-authority';
+
+const buttonVariants = cva(
+  // Base styles
+  'inline-flex items-center justify-center font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary:   'bg-primary-600 text-white hover:bg-primary-700',
+        secondary: 'bg-neutral-100 text-neutral-900 hover:bg-neutral-200',
+        ghost:     'hover:bg-neutral-100 text-neutral-700',
+        danger:    'bg-danger-500 text-white hover:bg-danger-700',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm rounded-md gap-1.5',
+        md: 'h-10 px-4 text-sm rounded-md gap-2',
+        lg: 'h-12 px-6 text-base rounded-lg gap-2',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+    },
+  }
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  loading?: boolean;
+}
+
+function Button({ variant, size, loading, children, className, ...props }: ButtonProps) {
+  return (
+    <button
+      className={buttonVariants({ variant, size, className })}
+      disabled={props.disabled || loading}
+      {...props}
+    >
+      {loading && <Spinner className="animate-spin h-4 w-4" />}
+      {children}
+    </button>
+  );
+}
+```
+
+### 3. Compound Components — Complex UI Composition
+
+```tsx
+// Card with slot-based composition
+interface CardProps { children: React.ReactNode; className?: string }
+
+function Card({ children, className }: CardProps) {
+  return <div className={cn('rounded-lg border bg-white shadow-sm', className)}>{children}</div>;
+}
+
+function CardHeader({ children, className }: CardProps) {
+  return <div className={cn('p-6 pb-0', className)}>{children}</div>;
+}
+
+function CardTitle({ children, className }: CardProps) {
+  return <h3 className={cn('text-lg font-semibold', className)}>{children}</h3>;
+}
+
+function CardContent({ children, className }: CardProps) {
+  return <div className={cn('p-6', className)}>{children}</div>;
+}
+
+function CardFooter({ children, className }: CardProps) {
+  return <div className={cn('p-6 pt-0 flex gap-2', className)}>{children}</div>;
+}
+
+// Usage — composable and explicit
+<Card>
+  <CardHeader>
+    <CardTitle>Order Summary</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <OrderDetails order={order} />
+  </CardContent>
+  <CardFooter>
+    <Button variant="primary">Confirm</Button>
+    <Button variant="ghost">Cancel</Button>
+  </CardFooter>
+</Card>
+```
+
+### 4. Theming — Light/Dark Mode
+
+```typescript
+// CSS custom properties for runtime theming
+const themes = {
+  light: {
+    '--color-bg': tokens.color.neutral[50],
+    '--color-surface': '#ffffff',
+    '--color-text': tokens.color.neutral[900],
+    '--color-text-muted': tokens.color.neutral[500],
+    '--color-border': tokens.color.neutral[200],
+    '--color-primary': tokens.color.primary[600],
+  },
+  dark: {
+    '--color-bg': tokens.color.neutral[900],
+    '--color-surface': '#262626',
+    '--color-text': tokens.color.neutral[50],
+    '--color-text-muted': tokens.color.neutral[500],
+    '--color-border': '#404040',
+    '--color-primary': tokens.color.primary[500],
+  },
+} as const;
+
+// ThemeProvider
+function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<'light' | 'dark'>(() => {
+    if (typeof window === 'undefined') return 'light';
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  });
+
+  useEffect(() => {
+    const root = document.documentElement;
+    const vars = themes[theme];
+    for (const [key, value] of Object.entries(vars)) {
+      root.style.setProperty(key, value);
+    }
+    root.setAttribute('data-theme', theme);
+  }, [theme]);
+
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+```
+
+### 5. Storybook — Living Documentation
+
+```typescript
+// Button.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  argTypes: {
+    variant: { control: 'select', options: ['primary', 'secondary', 'ghost', 'danger'] },
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    loading: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Primary: Story = {
+  args: { children: 'Button', variant: 'primary' },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Button variant="primary">Primary</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="danger">Danger</Button>
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  args: { children: 'Saving...', loading: true },
+};
+```
+
+### 6. Accessibility in Components
+
+```tsx
+// Always forward refs, support aria attributes, handle keyboard
+const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ label, error, id: providedId, ...props }, ref) => {
+    const id = providedId ?? useId();
+    const errorId = `${id}-error`;
+
+    return (
+      <div>
+        <label htmlFor={id} className="block text-sm font-medium">
+          {label}
+        </label>
+        <input
+          ref={ref}
+          id={id}
+          aria-invalid={!!error}
+          aria-describedby={error ? errorId : undefined}
+          className={cn('input-base', error && 'border-danger-500')}
+          {...props}
+        />
+        {error && (
+          <p id={errorId} role="alert" className="text-sm text-danger-500 mt-1">
+            {error}
+          </p>
+        )}
+      </div>
+    );
+  }
+);
+```
+
+## Examples
+
+| Pattern | Purpose | Benefit |
+|---------|---------|---------|
+| Design tokens | Centralized values | Change once, update everywhere |
+| CVA variants | Constrained component API | Type-safe, predictable styling |
+| Compound components | Flexible composition | Explicit slots, no prop drilling |
+| CSS custom properties | Runtime theming | Dark mode without rebuilding |
+| Storybook autodocs | Living documentation | Always in sync with code |
+
+## Checklist
+
+- [ ] Design tokens defined in a single file, not scattered in components
+- [ ] Components use variant props (not arbitrary `style` or `className` overrides)
+- [ ] Compound components used for multi-slot layouts (Card, Dialog, Dropdown)
+- [ ] All interactive components are keyboard accessible and have ARIA attributes
+- [ ] Theming uses CSS custom properties for runtime switching
+- [ ] Storybook stories cover all variants, states, and edge cases
+- [ ] Color contrast meets WCAG AA (4.5:1 for text, 3:1 for UI elements)
+- [ ] Components forward refs and spread native HTML attributes
+- [ ] Token naming is semantic (`color.primary`) not descriptive (`color.blue`)
+- [ ] Component API reviewed: no boolean explosion, sensible defaults