ai-playbook 1.0.0

package/roles/software-developer/frontend/accessibility/best-practices.md

@@ -0,0 +1,368 @@
+# Accessibility: Best Practices
+
+Accessible applications work for everyone. This includes users with disabilities, users on slow networks, and users in challenging environments. Accessibility is not optional—it's a core part of quality.
+
+## Semantic HTML
+
+Use the right HTML elements. Semantic elements communicate meaning to assistive technologies.
+
+```javascript
+// BAD: Non-semantic
+function Navigation() {
+  return (
+    <div class="nav">
+      <div class="nav-item" onClick={goHome}>Home</div>
+      <div class="nav-item" onClick={goAbout}>About</div>
+      <div class="nav-item" onClick={goContact}>Contact</div>
+    </div>
+  );
+}
+
+// Screen readers don't understand that these are navigation links
+// Keyboard navigation doesn't work
+
+// GOOD: Semantic elements
+function Navigation() {
+  return (
+    <nav>
+      <a href="/">Home</a>
+      <a href="/about">About</a>
+      <a href="/contact">Contact</a>
+    </nav>
+  );
+}
+
+// Key semantic elements:
+// <header>, <nav>, <main>, <article>, <section>, <aside>, <footer>
+// <h1>, <h2>, <h3> for headings (not divs)
+// <button> for actions (not div onclick)
+// <a> for navigation (not div with click handler)
+// <form>, <label>, <input> for forms
+// <table>, <thead>, <tbody>, <th>, <td> for data tables
+```
+
+## Keyboard Navigation
+
+All functionality must work with keyboard alone.
+
+```javascript
+// BAD: Mouse-only (keyboard users are stuck)
+function Modal({ onClose }) {
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal-content">
+        <h2>Delete Item?</h2>
+        <p>This action cannot be undone.</p>
+        <div className="modal-actions">
+          <button onClick={onClose}>Cancel</button>
+          <button onClick={handleDelete}>Delete</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Clicking outside closes modal
+// But no way to know you can click outside without mouse
+// Tab focus might go to elements outside modal
+
+// GOOD: Keyboard support
+function Modal({ onClose }) {
+  const modalRef = useRef();
+  
+  useEffect(() => {
+    function handleEscape(e) {
+      if (e.key === 'Escape') onClose();
+    }
+    
+    window.addEventListener('keydown', handleEscape);
+    return () => window.removeEventListener('keydown', handleEscape);
+  }, [onClose]);
+  
+  return (
+    <div 
+      className="modal-overlay" 
+      onClick={onClose}
+      role="presentation"
+    >
+      <div 
+        className="modal-content"
+        role="alertdialog"
+        ref={modalRef}
+      >
+        <h2>Delete Item?</h2>
+        <p>This action cannot be undone.</p>
+        <p className="accessibility-hint">Press Escape to cancel</p>
+        <div className="modal-actions">
+          <button onClick={onClose}>Cancel</button>
+          <button onClick={handleDelete} autoFocus>Delete</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Test with keyboard alone:
+// - Tab through all interactive elements in logical order
+// - Ensure focus is visible
+// - All actions available via keyboard
+```
+
+## Color Contrast
+
+Text must have sufficient contrast against its background. Minimum 4.5:1 for normal text.
+
+```javascript
+// BAD: Low contrast (light gray on white)
+<p style={{ color: '#cccccc', background: '#ffffff' }}>
+  Hard to read
+</p>
+
+// BAD: Failing WCAG AA
+<p style={{ color: '#999999', background: '#ffffff' }}>
+  Text fails contrast check
+</p>
+
+// GOOD: 4.5:1 contrast ratio
+<p style={{ color: '#333333', background: '#ffffff' }}>
+  Clear and readable
+</p>
+
+// GOOD: Sufficient contrast for larger text (3:1 minimum)
+<h2 style={{ color: '#555555', background: '#ffffff' }}>
+  Heading with 3:1 contrast
+</h2>
+
+// Use WebAIM Contrast Checker to verify
+// Chrome DevTools has built-in contrast check
+// Many color picker tools show contrast ratio
+```
+
+## Alt Text for Images
+
+Every image needs descriptive alt text (except decorative images).
+
+```javascript
+// BAD: No alt text
+<img src="/user-avatar.jpg" />
+
+// BAD: Unhelpful alt text
+<img src="/user-avatar.jpg" alt="image" />
+<img src="/chart.png" alt="chart.png" />
+
+// GOOD: Descriptive alt text
+<img 
+  src="/user-avatar.jpg" 
+  alt="Sarah Johnson, Product Designer" 
+/>
+
+// GOOD: Alt text describes content, not the image itself
+<img 
+  src="/sales-chart.png" 
+  alt="Sales increased 25% year-over-year, from $2M to $2.5M" 
+/>
+
+// GOOD: Decorative images marked explicitly
+<img 
+  src="/decorative-line.png" 
+  alt=""
+  aria-hidden="true"
+/>
+
+// Alt text guidelines:
+// - Be specific and descriptive
+// - Describe content, not "image of" or "picture of"
+// - Keep it concise (< 125 characters)
+// - Include important text that appears in image
+```
+
+## Form Accessibility
+
+Forms must be usable by everyone.
+
+```javascript
+// BAD: Not accessible
+<div>
+  <input type="email" placeholder="Email" />
+  <input type="password" placeholder="Password" />
+  <button>Sign In</button>
+</div>
+
+// Screen readers can't associate labels with inputs
+// No semantic structure
+// Placeholder disappears when typing
+
+// GOOD: Accessible form
+<form>
+  <div className="form-group">
+    <label htmlFor="email">Email Address</label>
+    <input 
+      id="email"
+      type="email" 
+      required
+      aria-describedby="email-hint"
+    />
+    <small id="email-hint">We'll never share your email</small>
+  </div>
+  
+  <div className="form-group">
+    <label htmlFor="password">Password</label>
+    <input 
+      id="password"
+      type="password" 
+      required
+    />
+  </div>
+  
+  <button type="submit">Sign In</button>
+</form>
+
+// For validation errors:
+<div 
+  className="form-group"
+  role="alert"
+  aria-live="polite"
+>
+  <label htmlFor="email">Email Address</label>
+  <input 
+    id="email"
+    type="email"
+    aria-invalid="true"
+    aria-describedby="email-error"
+  />
+  <span id="email-error" className="error">
+    Please enter a valid email
+  </span>
+</div>
+```
+
+## ARIA Usage
+
+ARIA (Accessible Rich Internet Applications) enhances semantic HTML, but should not replace it.
+
+```javascript
+// BAD: ARIA doesn't help if HTML is wrong
+<div role="button" onClick={handleClick}>
+  Click me
+</div>
+
+// Doesn't work with keyboard, confuses screen readers
+
+// GOOD: Use semantic HTML first
+<button onClick={handleClick}>
+  Click me
+</button>
+
+// ARIA only when semantic HTML insufficient
+function Tabs({ activeTab, onTabChange, children }) {
+  return (
+    <div role="tablist">
+      {children.map((child, i) => (
+        <button
+          key={i}
+          role="tab"
+          aria-selected={activeTab === i}
+          aria-controls={`panel-${i}`}
+          onClick={() => onTabChange(i)}
+        >
+          {child.props.label}
+        </button>
+      ))}
+      {children.map((child, i) => (
+        <div
+          key={i}
+          id={`panel-${i}`}
+          role="tabpanel"
+          aria-labelledby={`tab-${i}`}
+          hidden={activeTab !== i}
+        >
+          {child}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Focus Management
+
+Focus should move logically and be visible.
+
+```javascript
+// GOOD: Focus management
+function Dialog({ onClose }) {
+  const firstButtonRef = useRef();
+  
+  useEffect(() => {
+    // Move focus to first button when dialog opens
+    firstButtonRef.current?.focus();
+    
+    // Trap focus within dialog (optional but good practice)
+    function handleTab(e) {
+      if (e.key === 'Tab') {
+        // Keep focus within dialog
+      }
+    }
+    
+    window.addEventListener('keydown', handleTab);
+    return () => window.removeEventListener('keydown', handleTab);
+  }, []);
+  
+  return (
+    <div role="dialog" aria-modal="true">
+      <h2>Confirm Delete</h2>
+      <button ref={firstButtonRef} onClick={onClose}>
+        Cancel
+      </button>
+      <button onClick={handleDelete}>Delete</button>
+    </div>
+  );
+}
+
+// Focus styles must be visible
+button:focus {
+  outline: 2px solid blue;
+  outline-offset: 2px;
+}
+```
+
+## Testing Accessibility
+
+Test with real tools and assistive technologies.
+
+```javascript
+// Automated testing (catches ~30% of issues)
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+test('Modal is accessible', async () => {
+  const { container } = render(<Modal />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+
+// Manual testing (catches remaining 70%)
+// - Use keyboard only (no mouse)
+// - Use screen reader (NVDA, JAWS, VoiceOver)
+// - Test with real users with disabilities
+// - Zoom to 200% and check responsive design
+```
+
+## Accessibility Best Practices Checklist
+
+- [ ] Semantic HTML elements used (nav, main, article, button, label)
+- [ ] All interactive elements keyboard accessible
+- [ ] Focus order logical (typically top to bottom, left to right)
+- [ ] Focus visible (not removed with CSS)
+- [ ] Text has 4.5:1 contrast ratio (normal) or 3:1 (large)
+- [ ] All images have appropriate alt text
+- [ ] Form labels associated with inputs
+- [ ] Form errors announced to screen readers
+- [ ] ARIA used only to enhance semantic HTML
+- [ ] Tested with actual assistive technologies
+
+## Related Guidance
+
+- `/components` — semantic component design  
+- `/testing` — accessibility testing approaches  
+- `/tools-setup` — accessibility testing tools  
+- `/code-quality` — semantic HTML standards

package/roles/software-developer/frontend/code-quality/README.md

@@ -0,0 +1,136 @@
+# Code Quality
+
+Senior frontend developers write clean, formatted, linted code. Automated tools catch issues.
+
+## Code Formatting
+
+### Tools
+- **Prettier** — automatic code formatting
+- **ESLint** — code quality and style rules
+
+### Setup
+```json
+// .prettierrc
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2
+}
+```
+
+### Pre-commit Hooks
+- Run linter before commit
+- Run formatter on staged files
+- Use Husky + lint-staged
+
+### Why Automate
+- Removes style debates
+- Consistent codebase
+- CI catches violations early
+- No manual formatting required
+
+## Code Standards
+
+### Naming Conventions
+- Components: PascalCase (`MyButton.jsx`)
+- Functions/variables: camelCase (`handleClick`, `userData`)
+- Constants: UPPER_SNAKE_CASE (`MAX_RETRIES`)
+- Private/internal: `_leadingUnderscore`
+- Boolean functions: `is*`, `has*`, `should*` (`isLoading`, `hasError`)
+
+### File Organization
+- One component per file (unless tightly coupled)
+- Group by feature, not file type
+- Colocate tests with implementation
+
+### Import Organization
+- External packages first
+- Internal imports second
+- Relative imports last
+- Sort alphabetically within groups
+
+### Function Length
+- Keep functions small (<30 lines)
+- Longer functions suggest decomposition
+- One purpose per function
+
+### Complexity
+- Avoid deep nesting (3+ levels)
+- Early returns reduce nesting
+- Extract complex logic to helpers
+- Use guards to fail fast
+
+## Comments & Documentation
+
+### When to Comment
+- Why, not what (code shows what)
+- Non-obvious decisions
+- Complex algorithms
+- Edge cases and gotchas
+
+### When NOT to Comment
+- Self-explanatory code
+- Redundant explanations
+- Outdated comments (worse than none)
+
+### JSDoc for Public APIs
+```javascript
+/**
+ * Format date for display
+ * @param {Date} date - the date to format
+ * @returns {string} formatted date (YYYY-MM-DD)
+ */
+export function formatDate(date) { ... }
+```
+
+## TypeScript Standards
+
+- Use strict mode (`"strict": true`)
+- No `any` types (use `unknown` if needed)
+- Export types explicitly
+- Type function arguments and returns
+- Use interfaces for objects, types for unions
+
+## Linting Rules to Enable
+
+```javascript
+// ESLint config
+{
+  "extends": ["eslint:recommended"],
+  "rules": {
+    "no-unused-vars": "error",
+    "no-console": "warn",
+    "prefer-const": "error",
+    "no-var": "error",
+    "eqeqeq": "error"
+  }
+}
+```
+
+## Pre-commit Checklist
+
+Before pushing:
+- [ ] Code formatted (Prettier)
+- [ ] Linter passes (ESLint)
+- [ ] Tests pass
+- [ ] No console.log or debugging code
+- [ ] No dead/commented code
+- [ ] No secrets in code
+
+## Anti-Patterns
+
+- Mixing concerns in one component
+- No type safety (missing types)
+- Ignoring linter warnings
+- Inconsistent naming
+- Functions doing too much
+- Dead code left commented out
+- Magic strings/numbers (use constants)
+
+## Related Guidance
+
+- `/testing` — testing code quality
+- `/debugging` — debugging code issues
+- `/logging-observability` — logging standards