devflow-kit 0.9.0 → 1.1.0

package/plugins/devflow-core-skills/skills/accessibility/references/violations.md

@@ -0,0 +1,419 @@
+# Accessibility Violations
+
+Extended violation patterns for accessibility reviews. Reference from main SKILL.md.
+
+## Keyboard Navigation Violations
+
+### No Keyboard Access
+
+```tsx
+// VIOLATION: onClick without keyboard equivalent
+<div onClick={handleClick} className="card">
+  Click me
+</div>
+
+// VIOLATION: Custom element not focusable
+<span className="link" onClick={() => navigate('/page')}>
+  Go to page
+</span>
+
+// VIOLATION: Drag-only interaction
+<div
+  draggable
+  onDragStart={handleDrag}
+  onDragEnd={handleDrop}
+>
+  Drag me (no keyboard alternative)
+</div>
+```
+
+### Missing Focus Management
+
+```tsx
+// VIOLATION: Modal doesn't trap focus
+function Modal({ isOpen, children }) {
+  return isOpen ? (
+    <div className="modal-overlay">
+      <div className="modal-content">
+        {children}
+        <button onClick={onClose}>Close</button>
+      </div>
+    </div>
+  ) : null;
+}
+
+// VIOLATION: Dropdown doesn't return focus on close
+function Dropdown() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setIsOpen(true)}>Open</button>
+      {isOpen && (
+        <ul>
+          <li onClick={() => setIsOpen(false)}>Option 1</li>
+          {/* Focus lost when dropdown closes */}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### Poor Focus Visibility
+
+```css
+/* VIOLATION: Focus removed entirely */
+*:focus {
+  outline: none;
+}
+
+/* VIOLATION: Focus invisible on dark backgrounds */
+button:focus {
+  outline: 1px solid #333;
+}
+
+/* VIOLATION: Focus style same as hover */
+button:hover,
+button:focus {
+  background: #eee;
+}
+```
+
+### Illogical Tab Order
+
+```tsx
+// VIOLATION: tabIndex breaks natural order
+<div>
+  <input tabIndex={3} placeholder="Third" />
+  <input tabIndex={1} placeholder="First" />
+  <input tabIndex={2} placeholder="Second" />
+</div>
+
+// VIOLATION: Positive tabIndex on many elements
+<nav>
+  <a href="/" tabIndex={1}>Home</a>
+  <a href="/about" tabIndex={2}>About</a>
+  <a href="/contact" tabIndex={3}>Contact</a>
+</nav>
+```
+
+---
+
+## ARIA Violations
+
+### Missing Labels
+
+```tsx
+// VIOLATION: Icon button without accessible name
+<button onClick={handleClose}>
+  <CloseIcon />
+</button>
+
+// VIOLATION: Input without label
+<input type="text" placeholder="Search" />
+
+// VIOLATION: Image without alt
+<img src="/logo.png" />
+
+// VIOLATION: Link without text
+<a href="/profile">
+  <Avatar src={user.avatar} />
+</a>
+```
+
+### Incorrect ARIA Usage
+
+```tsx
+// VIOLATION: role="button" on already-button element
+<button role="button" onClick={handleClick}>Submit</button>
+
+// VIOLATION: aria-hidden on focusable element
+<button aria-hidden="true" onClick={handleClick}>
+  Hidden but focusable
+</button>
+
+// VIOLATION: Missing required ARIA attributes
+<div role="slider">
+  {/* Missing aria-valuenow, aria-valuemin, aria-valuemax */}
+</div>
+
+// VIOLATION: aria-label duplicating visible text
+<button aria-label="Submit form">Submit form</button>
+```
+
+### Overuse of ARIA
+
+```tsx
+// VIOLATION: ARIA where semantic HTML suffices
+<div role="navigation" aria-label="Main navigation">
+  <div role="list">
+    <div role="listitem">
+      <div role="link" onClick={() => navigate('/')}>Home</div>
+    </div>
+  </div>
+</div>
+
+// Should be:
+<nav aria-label="Main">
+  <ul>
+    <li><a href="/">Home</a></li>
+  </ul>
+</nav>
+```
+
+---
+
+## Color and Contrast Violations
+
+### Insufficient Contrast
+
+```css
+/* VIOLATION: Light gray on white (1.5:1 ratio) */
+.muted-text {
+  color: #aaa;
+  background: #fff;
+}
+
+/* VIOLATION: Placeholder text too light */
+input::placeholder {
+  color: #ccc;
+}
+
+/* VIOLATION: Disabled state invisible */
+button:disabled {
+  color: #eee;
+  background: #f5f5f5;
+}
+```
+
+### Color-Only Information
+
+```tsx
+// VIOLATION: Status only indicated by color
+<span style={{ color: status === 'error' ? 'red' : 'green' }}>
+  {status}
+</span>
+
+// VIOLATION: Required fields only marked red
+<label style={{ color: required ? 'red' : 'inherit' }}>
+  {label}
+</label>
+
+// VIOLATION: Chart using only color to differentiate data
+<LineChart>
+  <Line stroke="red" data={series1} />
+  <Line stroke="blue" data={series2} />
+  {/* No pattern, icon, or label differentiation */}
+</LineChart>
+```
+
+---
+
+## Form Violations
+
+### Missing Error Association
+
+```tsx
+// VIOLATION: Error not associated with input
+<div>
+  <input id="email" type="email" />
+  {error && <span className="error">{error}</span>}
+</div>
+
+// VIOLATION: Error not announced to screen readers
+<div>
+  <input aria-invalid={!!error} />
+  {error && <div className="error-message">{error}</div>}
+</div>
+```
+
+### Placeholder as Label
+
+```tsx
+// VIOLATION: Placeholder disappears, no persistent label
+<input placeholder="Email address" />
+
+// VIOLATION: Floating label without visible label initially
+function FloatingInput({ label }) {
+  const [value, setValue] = useState('');
+  return (
+    <div>
+      <input
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <label className={value ? 'floating' : 'hidden'}>{label}</label>
+    </div>
+  );
+}
+```
+
+### Form Not Keyboard Navigable
+
+```tsx
+// VIOLATION: Custom select not keyboard accessible
+function CustomSelect({ options, value, onChange }) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div className="select" onClick={() => setIsOpen(!isOpen)}>
+      <span>{value}</span>
+      {isOpen && (
+        <ul className="options">
+          {options.map(opt => (
+            <li onClick={() => onChange(opt)}>{opt}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Motion and Animation Violations
+
+### No Reduced Motion Support
+
+```css
+/* VIOLATION: Animation ignores user preference */
+.hero {
+  animation: slideIn 1s ease-in-out;
+}
+
+@keyframes slideIn {
+  from { transform: translateY(100%); }
+  to { transform: translateY(0); }
+}
+```
+
+### Autoplay Without Pause
+
+```tsx
+// VIOLATION: Video autoplays without pause control
+<video autoPlay loop muted>
+  <source src="/background.mp4" />
+</video>
+
+// VIOLATION: Carousel auto-advances without pause
+function Carousel({ slides }) {
+  useEffect(() => {
+    const interval = setInterval(nextSlide, 3000);
+    return () => clearInterval(interval);
+  }, []);
+  // No pause on hover or focus
+}
+```
+
+### Flashing Content
+
+```css
+/* VIOLATION: Flash rate > 3 per second */
+@keyframes flash {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
+}
+.alert {
+  animation: flash 0.2s infinite;
+}
+```
+
+---
+
+## Touch Target Violations
+
+### Small Touch Targets
+
+```css
+/* VIOLATION: Icon buttons too small */
+.icon-btn {
+  width: 24px;
+  height: 24px;
+  padding: 4px;
+}
+
+/* VIOLATION: Inline links with no padding */
+.inline-link {
+  /* Natural text height only */
+}
+
+/* VIOLATION: Close button in corner */
+.modal-close {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  width: 16px;
+  height: 16px;
+}
+```
+
+### Targets Too Close Together
+
+```tsx
+// VIOLATION: Adjacent small targets
+<div className="button-group">
+  <button className="icon-btn">A</button>
+  <button className="icon-btn">B</button>
+  <button className="icon-btn">C</button>
+  {/* No spacing between 24px buttons */}
+</div>
+```
+
+---
+
+## Screen Reader Violations
+
+### Hidden Important Content
+
+```tsx
+// VIOLATION: Visually hidden but important content
+<span className="sr-only">
+  Loading... {/* Never announced because sr-only wrong implementation */}
+</span>
+
+// VIOLATION: aria-hidden on important element
+<main aria-hidden="true">
+  {/* Page content hidden from AT */}
+</main>
+```
+
+### Meaningless Link Text
+
+```tsx
+// VIOLATION: Generic link text
+<p>
+  To learn more about our services, <a href="/services">click here</a>.
+</p>
+
+// VIOLATION: Repeated "Read more" links
+{posts.map(post => (
+  <article>
+    <h2>{post.title}</h2>
+    <p>{post.excerpt}</p>
+    <a href={post.url}>Read more</a>
+  </article>
+))}
+```
+
+### Missing Page Structure
+
+```tsx
+// VIOLATION: No landmark regions
+function App() {
+  return (
+    <div>
+      <div className="header">...</div>
+      <div className="sidebar">...</div>
+      <div className="content">...</div>
+      <div className="footer">...</div>
+    </div>
+  );
+}
+
+// VIOLATION: Skipped heading levels
+<h1>Page Title</h1>
+<h3>Section</h3>  {/* h2 skipped */}
+<h5>Subsection</h5>  {/* h4 skipped */}
+```

package/plugins/devflow-core-skills/skills/core-patterns/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: core-patterns
+description: This skill should be used when the user asks to "handle errors", "inject dependencies", "return Result", "make it immutable", "compose with pipes", or implements business logic, error handling, or service composition. Provides Result type patterns, dependency injection, immutability by default, pipe composition, and structured logging for robust application architecture.
+user-invocable: false
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+---
+
+# Core Engineering Patterns
+
+The canonical source of architectural patterns and principles for consistent, high-quality code.
+
+## Iron Law
+
+> **NEVER THROW IN BUSINESS LOGIC**
+>
+> All operations that can fail MUST return Result types. Exceptions are allowed
+> ONLY at system boundaries (API handlers, database adapters). Any `throw` statement
+> in business logic is a violation. No exceptions.
+
+## Philosophy
+
+1. **Type Safety First** - Strict type checking, avoid dynamic types
+2. **Functional Core, Imperative Shell** - Business logic pure, side effects isolated
+3. **Explicit Error Handling** - Result types instead of exceptions
+4. **Immutability by Default** - Return new objects, don't mutate
+5. **Dependency Injection** - Inject dependencies for testability
+6. **Test Behaviors** - Simple tests that validate behavior, not implementation
+7. **No Fake Solutions** - Be honest about limitations and workarounds
+8. **Fix Root Causes** - Never work around bad architecture
+
+---
+
+## Pattern 1: Result Types
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function createUser(data: unknown): Result<User, ValidationError> {
+  if (!valid(data)) return Err({ type: 'ValidationFailed', details: validate(data).errors });
+  return Ok(buildUser(data));
+}
+```
+
+## Pattern 2: Dependency Injection
+
+```typescript
+class UserService {
+  constructor(private db: Database, private emailer: EmailService) {}
+}
+// Easy to test: new UserService(mockDb, mockEmailer)
+```
+
+Never: `private db = new Database()` - can't mock.
+
+## Pattern 3: Immutability
+
+```typescript
+function updateUser(user: User, changes: Partial<User>): User {
+  return { ...user, ...changes };  // New object, no mutation
+}
+```
+
+Never mutate inputs. Copy before `.sort()`.
+
+## Pattern 4: Pure Functions
+
+```typescript
+function calculateTotal(items: Item[], taxRate: number): number {
+  return items.reduce((sum, i) => sum + i.price, 0) * (1 + taxRate);
+}
+```
+
+No side effects in pure functions.
+
+## Pattern 5: Type Safety
+
+```typescript
+type Status = 'pending' | 'completed' | 'failed';
+function handleStatus(status: Status): string {
+  switch (status) {
+    case 'pending': return 'Waiting';
+    case 'completed': return 'Done';
+    case 'failed': return 'Error';
+  }  // Exhaustive - no default needed
+}
+```
+
+## Pattern 6: Error Type Design
+
+```typescript
+type UserError =
+  | { type: 'NotFound'; userId: string }
+  | { type: 'ValidationFailed'; field: string; message: string };
+```
+
+## Pattern 7: Resource Cleanup
+
+```typescript
+const handle = await fs.open(path);
+try {
+  return Ok(parse(await handle.readFile()));
+} finally {
+  await handle.close();
+}
+```
+
+## Pattern 8: Architecture Documentation
+
+```typescript
+// ARCHITECTURE: Repository returns domain objects only
+// ARCHITECTURE EXCEPTION: Direct DB for health check - must work if service layer down
+```
+
+## Pattern 9: Naming Conventions
+
+- **Types/Classes**: PascalCase (`UserProfile`)
+- **Functions/Variables**: camelCase (`calculateTotal`)
+- **Constants**: SCREAMING_SNAKE_CASE (`MAX_RETRY`)
+
+## Pattern 10: Performance Awareness
+
+```typescript
+const customerMap = new Map(customers.map(c => [c.id, c]));  // O(1) vs O(n)
+```
+
+---
+
+## Consistency Rules
+
+- Result types: if one method returns Result, ALL must
+- DI: apply consistently throughout
+- Async: single pattern (don't mix callbacks/promises)
+
+## Anti-Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| Fake Solutions | Hardcoded responses simulating functionality |
+| Silent Failures | Catch blocks that swallow errors |
+| Magic Values | Unlabeled constants with special meaning |
+| Deceptive Code | Functions that pretend to work (e.g., `return true` with no logic) |
+
+### Workaround Labeling (Required)
+
+All workarounds, hacks, and temporary solutions MUST be labeled:
+
+| Label | Use When |
+|-------|----------|
+| `HACK:` | Workaround for specific problem |
+| `MOCK:` | Fake data for testing/development |
+| `TODO:` | Work that needs to be done |
+| `TEMPORARY:` | Short-term solution with deadline |
+| `NOT-PRODUCTION:` | Code that should never ship |
+| `ARCHITECTURE EXCEPTION:` | Violates pattern with justification |
+
+Unlabeled workarounds, empty catch blocks, and early returns without rationale are violations. See `references/code-smell-violations.md` for extended examples.
+
+---
+
+## Extended References
+
+See `references/` for: violations.md, patterns.md, detection.md, checklist.md