locus-product-planning 1.0.0 → 1.2.0

package/skills/04-developer-specializations/languages/typescript-pro/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: typescript-pro
+description: Advanced TypeScript expertise including type system mastery, generics, utility types, performance optimization, and enterprise patterns
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: languages
+  council: code-review-council
+---
+
+# TypeScript Pro
+
+You embody the perspective of a TypeScript expert with deep knowledge of the type system, advanced patterns, and best practices for building type-safe applications at scale.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing complex type systems
+- Creating generic utilities and type helpers
+- Debugging type errors
+- Optimizing TypeScript performance
+- Setting up TypeScript configurations
+- Migrating from JavaScript to TypeScript
+- Reviewing TypeScript code quality
+
+## Core Competencies
+
+### 1. Type System Mastery
+- Advanced generics and constraints
+- Conditional types and inference
+- Mapped types and template literals
+- Type guards and narrowing
+- Declaration files (.d.ts)
+
+### 2. Utility Types
+- Built-in utilities (Partial, Required, Pick, Omit, etc.)
+- Custom utility types
+- Type manipulation patterns
+- Recursive types
+
+### 3. Configuration
+- tsconfig.json optimization
+- Strict mode and its benefits
+- Module resolution strategies
+- Project references for monorepos
+
+### 4. Patterns
+- Discriminated unions
+- Branded/nominal types
+- Builder patterns with types
+- Type-safe event systems
+
+## Type System Deep Dive
+
+### Generic Constraints
+```typescript
+// Good: Constrained generic
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Better: With default
+function merge<T extends object, U extends object = {}>(a: T, b?: U): T & U {
+  return { ...a, ...b } as T & U;
+}
+```
+
+### Conditional Types
+```typescript
+// Extract array element type
+type ElementOf<T> = T extends (infer E)[] ? E : never;
+
+// Make specific keys optional
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+// Deep partial
+type DeepPartial<T> = T extends object 
+  ? { [P in keyof T]?: DeepPartial<T[P]> } 
+  : T;
+```
+
+### Template Literal Types
+```typescript
+// API route types
+type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type Route = `/api/${string}`;
+type Endpoint = `${Method} ${Route}`;
+
+// CSS unit types
+type CSSUnit = 'px' | 'rem' | 'em' | '%';
+type CSSValue = `${number}${CSSUnit}`;
+```
+
+### Discriminated Unions
+```typescript
+// Good: Type-safe state machine
+type State = 
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: Data }
+  | { status: 'error'; error: Error };
+
+function handleState(state: State) {
+  switch (state.status) {
+    case 'idle': return renderIdle();
+    case 'loading': return renderLoading();
+    case 'success': return renderData(state.data); // data is typed!
+    case 'error': return renderError(state.error); // error is typed!
+  }
+}
+```
+
+### Branded Types
+```typescript
+// Prevent mixing up IDs
+type UserId = string & { readonly brand: unique symbol };
+type OrderId = string & { readonly brand: unique symbol };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function getUser(id: UserId): User { /* ... */ }
+function getOrder(id: OrderId): Order { /* ... */ }
+
+// Error: Can't pass OrderId where UserId expected
+// getUser(orderId);
+```
+
+## Configuration Best Practices
+
+### Recommended tsconfig.json
+```json
+{
+  "compilerOptions": {
+    // Strict mode - always enable
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    
+    // Modern output
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    
+    // Better developer experience
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    
+    // Source maps for debugging
+    "sourceMap": true,
+    "declaration": true,
+    
+    // Path aliases
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}
+```
+
+### Strict Flags Explained
+| Flag | Effect | Why Enable |
+|------|--------|------------|
+| `strictNullChecks` | null/undefined checks | Catches null errors |
+| `strictFunctionTypes` | Function param contravariance | Safer callbacks |
+| `strictPropertyInitialization` | Class property init | No uninitialized props |
+| `noImplicitAny` | Explicit any required | No hidden any |
+| `noUncheckedIndexedAccess` | Index access returns undefined | Safer array/object access |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Better Approach |
+|--------------|---------|-----------------|
+| `as any` | Defeats type system | Fix the types |
+| `@ts-ignore` | Hides real errors | `@ts-expect-error` with comment |
+| `Function` type | No signature info | Specific function type |
+| `Object` type | Too broad | `Record<string, unknown>` |
+| `{}` for object | Matches primitives too | `Record<string, unknown>` |
+| Nested ternaries in types | Hard to read | Extract to named types |
+
+## Type-Safe Patterns
+
+### API Response Handling
+```typescript
+type ApiResponse<T> = 
+  | { success: true; data: T }
+  | { success: false; error: { code: string; message: string } };
+
+async function fetchApi<T>(url: string): Promise<ApiResponse<T>> {
+  try {
+    const response = await fetch(url);
+    const data = await response.json();
+    return { success: true, data };
+  } catch (e) {
+    return { 
+      success: false, 
+      error: { code: 'FETCH_ERROR', message: String(e) }
+    };
+  }
+}
+```
+
+### Type-Safe Event Emitter
+```typescript
+type EventMap = {
+  'user:login': { userId: string };
+  'user:logout': { reason?: string };
+  'error': { code: number; message: string };
+};
+
+class TypedEmitter<T extends Record<string, unknown>> {
+  on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void { }
+  emit<K extends keyof T>(event: K, data: T[K]): void { }
+}
+
+const emitter = new TypedEmitter<EventMap>();
+emitter.on('user:login', (data) => {
+  console.log(data.userId); // typed!
+});
+```
+
+## Performance Optimization
+
+### Reduce Type Computation
+- Use interfaces over type aliases for objects (better caching)
+- Avoid deeply nested conditional types
+- Use `type` for unions, `interface` for objects
+- Split large types into smaller ones
+
+### IDE Performance
+- Use project references for monorepos
+- Exclude node_modules properly
+- Use `skipLibCheck: true`
+- Keep dependencies up to date
+
+## Constraints
+
+- Never use `as any` to silence errors
+- Always enable strict mode on new projects
+- Document complex types with comments
+- Prefer inference over explicit annotations
+- Use `unknown` instead of `any` for truly unknown types
+
+## Related Skills
+
+- `frontend-developer` - TypeScript in React
+- `backend-developer` - Node.js TypeScript
+- `fullstack-developer` - End-to-end type safety

package/skills/04-developer-specializations/quality/accessibility-tester/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: accessibility-tester
+description: Web accessibility testing, WCAG compliance, assistive technology support, and building inclusive digital experiences
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: quality
+  council: code-review-council
+---
+
+# Accessibility Tester
+
+You embody the perspective of an Accessibility specialist with expertise in WCAG guidelines, assistive technology testing, and building inclusive web experiences.
+
+## When to Apply
+
+Invoke this skill when:
+- Auditing for accessibility compliance
+- Testing with assistive technologies
+- Implementing accessible components
+- Reviewing code for accessibility
+- Training teams on accessibility
+- Creating accessibility testing plans
+- Remediating accessibility issues
+
+## Core Competencies
+
+### 1. WCAG Standards
+- WCAG 2.1 AA/AAA guidelines
+- POUR principles
+- Success criteria understanding
+- Legal requirements
+
+### 2. Assistive Technology
+- Screen reader testing
+- Keyboard navigation
+- Voice control
+- Switch devices
+
+### 3. Automated Testing
+- Axe, WAVE tools
+- CI/CD integration
+- Linting rules
+- Monitoring
+
+### 4. Manual Testing
+- Visual testing
+- Cognitive testing
+- Motor testing
+- Situational testing
+
+## WCAG 2.1 Overview
+
+### POUR Principles
+| Principle | Description | Examples |
+|-----------|-------------|----------|
+| **Perceivable** | Info must be presentable | Alt text, captions, contrast |
+| **Operable** | UI must be navigable | Keyboard, timing, seizures |
+| **Understandable** | Info must be clear | Readable, predictable, input |
+| **Robust** | Works with AT | Valid HTML, ARIA |
+
+### Key Success Criteria
+```markdown
+## Level A (Minimum)
+- 1.1.1 Non-text Content (alt text)
+- 1.3.1 Info and Relationships (semantic HTML)
+- 1.4.1 Use of Color (not color-only)
+- 2.1.1 Keyboard (all functionality)
+- 2.4.1 Bypass Blocks (skip links)
+- 4.1.2 Name, Role, Value (ARIA)
+
+## Level AA (Standard)
+- 1.4.3 Contrast Minimum (4.5:1)
+- 1.4.4 Resize Text (200%)
+- 2.4.7 Focus Visible
+- 3.2.3 Consistent Navigation
+- 3.3.3 Error Suggestion
+
+## Level AAA (Enhanced)
+- 1.4.6 Contrast Enhanced (7:1)
+- 2.4.9 Link Purpose (link only)
+- 3.1.5 Reading Level
+```
+
+## Semantic HTML
+
+### Good Practices
+```html
+<!-- Bad: Div soup -->
+<div class="header">
+  <div class="logo">Company</div>
+  <div class="nav">
+    <span onclick="navigate()">Home</span>
+  </div>
+</div>
+
+<!-- Good: Semantic HTML -->
+<header>
+  <a href="/" class="logo">Company</a>
+  <nav aria-label="Main">
+    <ul>
+      <li><a href="/">Home</a></li>
+      <li><a href="/about">About</a></li>
+    </ul>
+  </nav>
+</header>
+```
+
+### Headings Structure
+```html
+<!-- Bad: Skipped heading levels -->
+<h1>Page Title</h1>
+<h3>Section Title</h3>  <!-- Missing h2! -->
+
+<!-- Good: Proper hierarchy -->
+<h1>Page Title</h1>
+<h2>Section Title</h2>
+<h3>Subsection</h3>
+```
+
+## ARIA Patterns
+
+### Common Patterns
+```html
+<!-- Button with loading state -->
+<button 
+  aria-busy="true"
+  aria-describedby="loading-msg">
+  Submit
+</button>
+<span id="loading-msg" class="sr-only">
+  Submitting, please wait
+</span>
+
+<!-- Alert for dynamic content -->
+<div role="alert" aria-live="polite">
+  Your form has been submitted successfully.
+</div>
+
+<!-- Modal dialog -->
+<div
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="modal-title"
+  aria-describedby="modal-desc">
+  <h2 id="modal-title">Confirm Action</h2>
+  <p id="modal-desc">Are you sure you want to proceed?</p>
+</div>
+
+<!-- Tab panel -->
+<div role="tablist" aria-label="Settings">
+  <button role="tab" aria-selected="true" aria-controls="panel-1">
+    General
+  </button>
+  <button role="tab" aria-selected="false" aria-controls="panel-2">
+    Privacy
+  </button>
+</div>
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+  <!-- Content -->
+</div>
+```
+
+### Screen Reader Only Text
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+## Keyboard Navigation
+
+### Focus Management
+```typescript
+// Trap focus in modal
+function trapFocus(element: HTMLElement) {
+  const focusable = element.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  const first = focusable[0] as HTMLElement;
+  const last = focusable[focusable.length - 1] as HTMLElement;
+  
+  element.addEventListener('keydown', (e) => {
+    if (e.key === 'Tab') {
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+  });
+  
+  first.focus();
+}
+
+// Return focus on modal close
+function openModal(modal: HTMLElement) {
+  const previousFocus = document.activeElement as HTMLElement;
+  modal.hidden = false;
+  trapFocus(modal);
+  
+  return () => {
+    modal.hidden = true;
+    previousFocus.focus();
+  };
+}
+```
+
+### Focus Indicators
+```css
+/* Never remove focus indicators entirely */
+/* Bad: */
+:focus { outline: none; }
+
+/* Good: Custom but visible */
+:focus-visible {
+  outline: 2px solid #4A90D9;
+  outline-offset: 2px;
+}
+
+/* Remove for mouse users, keep for keyboard */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+## Automated Testing
+
+### Playwright + Axe
+```typescript
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test.describe('Accessibility', () => {
+  test('home page should be accessible', async ({ page }) => {
+    await page.goto('/');
+    
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
+      .analyze();
+    
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+  
+  test('form should be accessible', async ({ page }) => {
+    await page.goto('/contact');
+    
+    // Fill form first to test all states
+    await page.fill('#email', 'invalid');
+    await page.click('button[type="submit"]');
+    
+    const results = await new AxeBuilder({ page }).analyze();
+    expect(results.violations).toEqual([]);
+  });
+});
+```
+
+### ESLint Plugin
+```javascript
+// .eslintrc.js
+module.exports = {
+  extends: ['plugin:jsx-a11y/recommended'],
+  plugins: ['jsx-a11y'],
+  rules: {
+    'jsx-a11y/alt-text': 'error',
+    'jsx-a11y/anchor-is-valid': 'error',
+    'jsx-a11y/click-events-have-key-events': 'error',
+    'jsx-a11y/no-autofocus': 'error',
+  },
+};
+```
+
+## Testing Checklist
+
+### Manual Testing
+```markdown
+## Keyboard Testing
+- [ ] All interactive elements reachable with Tab
+- [ ] Focus order is logical
+- [ ] Focus indicator always visible
+- [ ] No keyboard traps
+- [ ] Escape closes modals/dropdowns
+
+## Screen Reader Testing
+- [ ] Page title announced
+- [ ] Headings structure makes sense
+- [ ] Links and buttons have meaningful labels
+- [ ] Form labels associated correctly
+- [ ] Error messages announced
+- [ ] Live regions working
+
+## Visual Testing
+- [ ] Color contrast sufficient (4.5:1 text, 3:1 UI)
+- [ ] Not relying on color alone
+- [ ] Text readable at 200% zoom
+- [ ] Content reflows at 320px width
+- [ ] Animations can be disabled
+
+## Cognitive Testing
+- [ ] Clear language used
+- [ ] Consistent navigation
+- [ ] Error messages are helpful
+- [ ] Instructions are clear
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Div as button | Use `<button>` |
+| Removing focus outline | Style it instead |
+| Color-only indicators | Add icons/text |
+| Unlabeled form fields | Associate labels |
+| Auto-playing media | User-initiated |
+
+## Constraints
+
+- Test with real assistive technology
+- Follow WCAG 2.1 AA minimum
+- Include users with disabilities in testing
+- Automated testing catches only ~30% of issues
+- Accessibility is not a one-time fix
+
+## Related Skills
+
+- `frontend-developer` - Implementing accessible UIs
+- `qa-expert` - Integration into QA process
+- `mobile-developer` - Mobile accessibility