@sylix/coworker 2.0.10 → 2.0.12

package/dist/skills/defaults/frontend/typescript.md

@@ -0,0 +1,334 @@
+---
+name: typescript
+description: Write type-safe TypeScript code with advanced types, patterns, and best practices.
+---
+
+# TypeScript Advanced Patterns — CoWorker Edition
+
+Write robust, maintainable TypeScript with confidence.
+
+## When to Use This Skill
+
+- Building type-safe applications
+- Creating reusable libraries
+- Working with complex type transformations
+- Defining API contracts
+
+## Core Concepts
+
+### 1. Utility Types
+
+```typescript
+// Basic utilities
+type Partial<T> = { [P in keyof T]?: T[P] };
+type Required<T> = { [P in keyof T]-?: T[P] };
+type Readonly<T> = { readonly [P in keyof T]: T[P] };
+type Pick<T, K extends keyof T> = { [P in K]: T[P] };
+type Omit<T, K extends keyof T> = { [P in Exclude<keyof T, K>]: T[P] };
+
+// Practical usage
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  password: string;
+  createdAt: Date;
+}
+
+type PublicUser = Pick<User, 'id' | 'name'>;
+type UserCreateInput = Omit<User, 'id' | 'createdAt'>;
+type UserUpdateInput = Partial<Omit<User, 'id'>>;
+```
+
+### 2. Generics
+
+```typescript
+// Generic functions
+function first<T>(arr: T[]): T | undefined {
+  return arr[0];
+}
+
+function map<T, U>(arr: T[], fn: (item: T) => U): U[] {
+  return arr.map(fn);
+}
+
+// Generic constraints
+interface HasId {
+  id: string;
+}
+
+function findById<T extends HasId>(arr: T[], id: string): T | undefined {
+  return arr.find(item => item.id === id);
+}
+
+// Generic classes
+class Repository<T extends HasId> {
+  private items: T[] = [];
+  
+  find(id: string): T | undefined {
+    return this.items.find(item => item.id === id);
+  }
+  
+  save(item: T): void {
+    const idx = this.items.findIndex(i => i.id === item.id);
+    if (idx >= 0) {
+      this.items[idx] = item;
+    } else {
+      this.items.push(item);
+    }
+  }
+}
+```
+
+### 3. Discriminated Unions
+
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function handleResult<T>(result: Result<T>): T {
+  if (result.ok) {
+    return result.value;
+  }
+  throw result.error;
+}
+
+// Practical API response
+interface LoadingState {
+  status: 'loading';
+}
+
+interface SuccessState<T> {
+  status: 'success';
+  data: T;
+}
+
+interface ErrorState {
+  status: 'error';
+  error: Error;
+}
+
+type AsyncState<T> = LoadingState | SuccessState<T> | ErrorState;
+
+function render<T>(state: AsyncState<T>): string {
+  switch (state.status) {
+    case 'loading':
+      return 'Loading...';
+    case 'success':
+      return `Data: ${JSON.stringify(state.data)}`;
+    case 'error':
+      return `Error: ${state.error.message}`;
+  }
+}
+```
+
+### 4. Template Literal Types
+
+```typescript
+// Event system
+type EventName = `${string}:${'click' | 'focus' | 'blur'}`;
+
+interface Emitter<Events extends Record<string, unknown>> {
+  on<K extends keyof Events>(event: K, fn: (data: Events[K]) => void): void;
+  emit<K extends keyof Events>(event: K, data: Events[K]): void;
+}
+
+// API paths
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';
+type ApiEndpoint = `/api/${string}`;
+type Route = `${HttpMethod}:${ApiEndpoint}`;
+
+const routes: Route[] = [
+  'get:/api/users',
+  'post:/api/users',
+  'get:/api/users/:id',
+];
+```
+
+### 5. Mapped Types
+
+```typescript
+type Readonly<T> = {
+  readonly [P in keyof T]: T[P];
+};
+
+type Nullable<T> = {
+  [P in keyof T]: T[P] | null;
+};
+
+type RequiredKeys<T> = {
+  [K in keyof T]: T extends Record<K, T[K]> ? never : K;
+}[keyof T];
+
+type OptionalKeys<T> = {
+  [K in keyof T]: T extends Record<K, T[K]> ? K : never;
+}[keyof T];
+
+// Practical: Make all methods async
+type AsyncMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<R>
+    : T[K];
+};
+```
+
+### 6. Type Guards
+
+```typescript
+// Type predicate
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+function process(value: unknown) {
+  if (isString(value)) {
+    // value is narrowed to string
+    return value.toUpperCase();
+  }
+  return value;
+}
+
+// Discriminated union guard
+type Shape = { kind: 'circle'; radius: number } | { kind: 'square'; side: number };
+
+function area(shape: Shape): number {
+  if (shape.kind === 'circle') {
+    return Math.PI * shape.radius ** 2;
+  }
+  return shape.side ** 2;
+}
+
+// Instance guard
+class ApiError extends Error {
+  constructor(public statusCode: number, message: string) {
+    super(message);
+  }
+}
+
+function isApiError(error: unknown): error is ApiError {
+  return error instanceof ApiError && 'statusCode' in error;
+}
+```
+
+### 7. Zod Schema Validation
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(2).max(100),
+  email: z.string().email(),
+  age: z.number().int().positive().optional(),
+  role: z.enum(['admin', 'user', 'guest']),
+  metadata: z.record(z.string()).optional(),
+  createdAt: z.string().datetime(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+// Validation
+function validateUser(data: unknown): User {
+  return UserSchema.parse(data);
+}
+
+// With error handling
+function safeValidateUser(data: unknown) {
+  const result = UserSchema.safeParse(data);
+  if (!result.success) {
+    return { error: result.error.flatten() };
+  }
+  return { data: result.data };
+}
+
+// Refinement
+const AdminSchema = UserSchema.refine(
+  (user) => user.role === 'admin' || user.age >= 18,
+  { message: 'Must be admin or 18+' }
+);
+```
+
+### 8. React with TypeScript
+
+```typescript
+import { useState, useCallback } from 'react';
+
+// Component props
+interface ButtonProps {
+  children: React.ReactNode;
+  onClick?: () => void;
+  variant?: 'primary' | 'secondary';
+  disabled?: boolean;
+}
+
+function Button({ children, onClick, variant = 'primary', disabled }: ButtonProps) {
+  return (
+    <button
+      className={`btn btn-${variant}`}
+      onClick={onClick}
+      disabled={disabled}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Hooks with types
+function useFetch<T>(url: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  
+  const fetch = useCallback(async () => {
+    try {
+      setLoading(true);
+      const res = await fetch(url);
+      const json = await res.json();
+      setData(json);
+    } catch (e) {
+      setError(e as Error);
+    } finally {
+      setLoading(false);
+    }
+  }, [url]);
+  
+  return { data, loading, error, refetch: fetch };
+}
+
+// Context with types
+interface AuthState {
+  user: User | null;
+  login: (email: string, password: string) => Promise<void>;
+  logout: () => void;
+}
+
+const AuthContext = createContext<AuthState | null>(null);
+
+function useAuth() {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within AuthProvider');
+  }
+  return context;
+}
+```
+
+## Best Practices
+
+1. **Strict mode** - Always use strict TypeScript
+2. **Explicit types** - Don't overuse `any`
+3. **Discriminated unions** - For state machines
+4. **Utility types** - Leverage built-in utilities
+5. **Generics** - For reusable components
+6. **Type guards** - Narrow types explicitly
+7. **Schema validation** - Zod for runtime validation
+
+## Common Mistakes
+
+- Using `any` too liberally
+- Not enabling strict mode
+- Ignoring generic constraints
+- Missing null checks
+- Not using readonly appropriately
+- Over-engineering types

package/dist/skills/defaults/frontend/visual-design-foundations.md

@@ -0,0 +1,326 @@
+---
+name: visual-design-foundations
+description: Apply typography, color theory, spacing systems, and iconography principles to create cohesive visual designs. Use when establishing design tokens, building style guides, or improving visual hierarchy and consistency.
+---
+
+# Visual Design Foundations
+
+Build cohesive, accessible visual systems using typography, color, spacing, and iconography fundamentals.
+
+## When to Use This Skill
+
+- Establishing design tokens for a new project
+- Creating or refining a spacing and sizing system
+- Selecting and pairing typefaces
+- Building accessible color palettes
+- Designing icon systems and visual assets
+- Improving visual hierarchy and readability
+- Auditing designs for visual consistency
+- Implementing dark mode or theming
+
+## Core Systems
+
+### 1. Typography Scale
+
+**Modular Scale** (ratio-based sizing):
+
+```css
+:root {
+  --font-size-xs: 0.75rem; /* 12px */
+  --font-size-sm: 0.875rem; /* 14px */
+  --font-size-base: 1rem; /* 16px */
+  --font-size-lg: 1.125rem; /* 18px */
+  --font-size-xl: 1.25rem; /* 20px */
+  --font-size-2xl: 1.5rem; /* 24px */
+  --font-size-3xl: 1.875rem; /* 30px */
+  --font-size-4xl: 2.25rem; /* 36px */
+  --font-size-5xl: 3rem; /* 48px */
+}
+```
+
+**Line Height Guidelines**:
+| Text Type | Line Height |
+|-----------|-------------|
+| Headings | 1.1 - 1.3 |
+| Body text | 1.5 - 1.7 |
+| UI labels | 1.2 - 1.4 |
+
+### 2. Spacing System
+
+**8-point grid** (industry standard):
+
+```css
+:root {
+  --space-1: 0.25rem; /* 4px */
+  --space-2: 0.5rem; /* 8px */
+  --space-3: 0.75rem; /* 12px */
+  --space-4: 1rem; /* 16px */
+  --space-5: 1.25rem; /* 20px */
+  --space-6: 1.5rem; /* 24px */
+  --space-8: 2rem; /* 32px */
+  --space-10: 2.5rem; /* 40px */
+  --space-12: 3rem; /* 48px */
+  --space-16: 4rem; /* 64px */
+}
+```
+
+### 3. Color System
+
+**Semantic color tokens**:
+
+```css
+:root {
+  /* Brand */
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --color-primary-active: #1e40af;
+
+  /* Semantic */
+  --color-success: #16a34a;
+  --color-warning: #ca8a04;
+  --color-error: #dc2626;
+  --color-info: #0891b2;
+
+  /* Neutral */
+  --color-gray-50: #f9fafb;
+  --color-gray-100: #f3f4f6;
+  --color-gray-200: #e5e7eb;
+  --color-gray-300: #d1d5db;
+  --color-gray-400: #9ca3af;
+  --color-gray-500: #6b7280;
+  --color-gray-600: #4b5563;
+  --color-gray-700: #374151;
+  --color-gray-800: #1f2937;
+  --color-gray-900: #111827;
+}
+```
+
+## Quick Start: Design Tokens in Tailwind
+
+```js
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ["Inter", "system-ui", "sans-serif"],
+        mono: ["JetBrains Mono", "monospace"],
+      },
+      fontSize: {
+        xs: ["0.75rem", { lineHeight: "1rem" }],
+        sm: ["0.875rem", { lineHeight: "1.25rem" }],
+        base: ["1rem", { lineHeight: "1.5rem" }],
+        lg: ["1.125rem", { lineHeight: "1.75rem" }],
+        xl: ["1.25rem", { lineHeight: "1.75rem" }],
+        "2xl": ["1.5rem", { lineHeight: "2rem" }],
+      },
+      colors: {
+        brand: {
+          50: "#eff6ff",
+          500: "#3b82f6",
+          600: "#2563eb",
+          700: "#1d4ed8",
+        },
+      },
+      spacing: {
+        // Extends default with custom values
+        18: "4.5rem",
+        88: "22rem",
+      },
+    },
+  },
+};
+```
+
+## Typography Best Practices
+
+### Font Pairing
+
+**Safe combinations**:
+
+- Heading: **Inter** / Body: **Inter** (single family)
+- Heading: **Playfair Display** / Body: **Source Sans Pro** (contrast)
+- Heading: **Space Grotesk** / Body: **IBM Plex Sans** (geometric)
+
+### Responsive Typography
+
+```css
+/* Fluid typography using clamp() */
+h1 {
+  font-size: clamp(2rem, 5vw + 1rem, 3.5rem);
+  line-height: 1.1;
+}
+
+p {
+  font-size: clamp(1rem, 2vw + 0.5rem, 1.125rem);
+  line-height: 1.6;
+  max-width: 65ch; /* Optimal reading width */
+}
+```
+
+### Font Loading
+
+```css
+/* Prevent layout shift */
+@font-face {
+  font-family: "Inter";
+  src: url("/fonts/Inter.woff2") format("woff2");
+  font-display: swap;
+  font-weight: 400 700;
+}
+```
+
+## Color Theory
+
+### Contrast Requirements (WCAG)
+
+| Element            | Minimum Ratio |
+| ------------------ | ------------- |
+| Body text          | 4.5:1 (AA)    |
+| Large text (18px+) | 3:1 (AA)      |
+| UI components      | 3:1 (AA)      |
+| Enhanced           | 7:1 (AAA)     |
+
+### Dark Mode Strategy
+
+```css
+:root {
+  --bg-primary: #ffffff;
+  --bg-secondary: #f9fafb;
+  --text-primary: #111827;
+  --text-secondary: #6b7280;
+  --border: #e5e7eb;
+}
+
+[data-theme="dark"] {
+  --bg-primary: #111827;
+  --bg-secondary: #1f2937;
+  --text-primary: #f9fafb;
+  --text-secondary: #9ca3af;
+  --border: #374151;
+}
+```
+
+### Color Accessibility
+
+```tsx
+// Check contrast programmatically
+function getContrastRatio(foreground: string, background: string): number {
+  const getLuminance = (hex: string) => {
+    const rgb = hexToRgb(hex);
+    const [r, g, b] = rgb.map((c) => {
+      c = c / 255;
+      return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  };
+
+  const l1 = getLuminance(foreground);
+  const l2 = getLuminance(background);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+
+  return (lighter + 0.05) / (darker + 0.05);
+}
+```
+
+## Spacing Guidelines
+
+### Component Spacing
+
+```
+Card padding:      16-24px (--space-4 to --space-6)
+Section gap:       32-64px (--space-8 to --space-16)
+Form field gap:    16-24px (--space-4 to --space-6)
+Button padding:    8-16px vertical, 16-24px horizontal
+Icon-text gap:     8px (--space-2)
+```
+
+### Visual Rhythm
+
+```css
+/* Consistent vertical rhythm */
+.prose > * + * {
+  margin-top: var(--space-4);
+}
+
+.prose > h2 + * {
+  margin-top: var(--space-2);
+}
+
+.prose > * + h2 {
+  margin-top: var(--space-8);
+}
+```
+
+## Iconography
+
+### Icon Sizing System
+
+```css
+:root {
+  --icon-xs: 12px;
+  --icon-sm: 16px;
+  --icon-md: 20px;
+  --icon-lg: 24px;
+  --icon-xl: 32px;
+}
+```
+
+### Icon Component
+
+```tsx
+interface IconProps {
+  name: string;
+  size?: "xs" | "sm" | "md" | "lg" | "xl";
+  className?: string;
+}
+
+const sizeMap = {
+  xs: 12,
+  sm: 16,
+  md: 20,
+  lg: 24,
+  xl: 32,
+};
+
+export function Icon({ name, size = "md", className }: IconProps) {
+  return (
+    <svg
+      width={sizeMap[size]}
+      height={sizeMap[size]}
+      className={cn("inline-block flex-shrink-0", className)}
+      aria-hidden="true"
+    >
+      <use href={`/icons.svg#${name}`} />
+    </svg>
+  );
+}
+```
+
+## Best Practices
+
+1. **Establish Constraints**: Limit choices to maintain consistency
+2. **Document Decisions**: Create a living style guide
+3. **Test Accessibility**: Verify contrast, sizing, touch targets
+4. **Use Semantic Tokens**: Name by purpose, not appearance
+5. **Design Mobile-First**: Start with constraints, add complexity
+6. **Maintain Vertical Rhythm**: Consistent spacing creates harmony
+7. **Limit Font Weights**: 2-3 weights per family is sufficient
+
+## Common Issues
+
+- **Inconsistent Spacing**: Not using a defined scale
+- **Poor Contrast**: Failing WCAG requirements
+- **Font Overload**: Too many families or weights
+- **Magic Numbers**: Arbitrary values instead of tokens
+- **Missing States**: Forgetting hover, focus, disabled
+- **No Dark Mode Plan**: Retrofitting is harder than planning
+
+## Resources
+
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [Type Scale Calculator](https://typescale.com/)
+- [Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [Material Design Color System](https://m3.material.io/styles/color/overview)
+- [Radix Colors](https://www.radix-ui.com/colors)