devflow-kit 1.8.3 → 2.0.1

package/src/assets/skills/typescript/references/violations.md

@@ -0,0 +1,285 @@
+# TypeScript — Violations
+
+Extended violation patterns with literature citations.
+See `sources.md` for full bibliography.
+
+---
+
+## Type Safety Violations
+
+### Using `any` Type [1, Item 43][4][17]
+
+"`any` is not just a hole in the type system — it's a hole that spreads."
+— Effective TypeScript [1, Item 43]. Every `any` disables checking for all
+values flowing through it.
+
+**Direct any usage**
+```typescript
+// VIOLATION: any disables type checking [1, Item 43]
+function parse(json: string): any { return JSON.parse(json); }
+
+// VIOLATION: any parameter — no safety downstream [4]
+function process(data: any) { console.log(data.name); }
+
+// VIOLATION: any default in generic [17]
+function wrap<T = any>(value: T) { return { value }; }
+```
+
+**Implicit any**
+```typescript
+// VIOLATION: Implicit any on parameter (fails with noImplicitAny) [16]
+function greet(name) { return `Hello, ${name}`; }
+
+// VIOLATION: Implicit any in catch [1, Item 47]
+try { riskyOperation(); } catch (e) { console.log(e.message); }
+```
+
+### Type Assertions Without Validation [1, Item 9]
+
+```typescript
+// VIOLATION: Casting without narrowing [1, Item 9]
+const user = data as User;  // data could be anything
+
+// VIOLATION: Double-assertion bypass — opts out of entire type system
+const value = data as unknown as SpecificType;
+
+// VIOLATION: Non-null assertion on nullable [4]
+function getName(user: User | null): string { return user!.name; }
+```
+
+### Non-Exhaustive Pattern Matching [1, Item 33]
+
+```typescript
+type Status = 'pending' | 'active' | 'completed' | 'failed';
+
+// VIOLATION: Missing cases hidden by default [1, Item 33]
+function handleStatus(status: Status): string {
+  switch (status) {
+    case 'pending': return 'Waiting';
+    case 'active':  return 'Running';
+    // Missing: 'completed' and 'failed'
+  }
+  return 'Unknown'; // hides compile error when union grows
+}
+
+// VIOLATION: Only handling success branch [1, Item 28]
+function process<T>(result: Result<T>): T {
+  if (result.ok) return result.value;
+  // error branch silently falls off — TypeScript won't error without strictNullChecks
+}
+```
+
+---
+
+## Type Guard Violations [2][6]
+
+### Missing or Incorrect Narrowing
+
+```typescript
+// VIOLATION: Trusting unvalidated input [1, Item 43][25]
+function processUser(data: unknown) {
+  const user = data as User; // assumes shape, no check
+  console.log(user.name);    // runtime error if wrong
+}
+
+// VIOLATION: Incomplete predicate — checks presence but not type [2]
+function isUser(obj: unknown): obj is User {
+  return typeof obj === 'object' && obj !== null && 'name' in obj;
+  // Missing: typeof obj.name === 'string', other required properties
+}
+
+// VIOLATION: Predicate doesn't match its check [6]
+function isString(value: unknown): value is string {
+  return value !== null; // wrong — null passes, non-strings pass
+}
+```
+
+### Unsafe `instanceof` Usage [7]
+
+```typescript
+// VIOLATION: instanceof fails for primitive types [7]
+function isNumber(value: unknown): value is number {
+  return value instanceof Number; // fails for primitive 42
+}
+
+// VIOLATION: instanceof fails across iframes/realms [7]
+function isArray(value: unknown): value is unknown[] {
+  return value instanceof Array; // use Array.isArray instead
+}
+```
+
+### Missing Null Checks [4][16]
+
+```typescript
+// VIOLATION: Optional property accessed without check [4]
+function getTimeout(config: { timeout?: number }): number {
+  return config.timeout * 1000; // Error: possibly undefined
+}
+
+// VIOLATION: Chained access without null safety
+function getCity(user: User): string {
+  return user.address.city; // runtime error if address is undefined
+}
+```
+
+---
+
+## Utility Type Violations [1, Items 14–16]
+
+### Manual Reimplementation of Built-ins [1, Item 15]
+
+```typescript
+// VIOLATION: Reinventing Partial<T> [1, Item 15]
+type MyPartial<T> = { [P in keyof T]?: T[P] };
+
+// VIOLATION: Duplicating types instead of using Partial [1, Item 14]
+interface CreateUserInput { name: string; email: string; }
+interface UpdateUserInput { name?: string; email?: string; }
+// Should be: type UpdateUserInput = Partial<CreateUserInput>
+```
+
+### Incorrect Generic Constraints [1, Item 50][6]
+
+```typescript
+// VIOLATION: No constraint — property access is unsafe [1, Item 50]
+function getProperty<T, K>(obj: T, key: K) { return obj[key]; }
+
+// VIOLATION: Over-constrained — prevents legitimate callers [1, Item 29]
+function merge<T extends { id: string }>(a: T, b: T): T {
+  return { ...a, ...b }; // can't merge objects without 'id' even when not needed
+}
+```
+
+### Improper Mapped Types [6][19]
+
+```typescript
+// VIOLATION: Silently drops optional modifiers [6]
+type Transformed<T> = { [P in keyof T]: string };
+// All properties become required strings — original optionality lost
+
+// VIOLATION: Doesn't remove readonly — looks like Mutable but isn't [6]
+type Mutable<T> = { [P in keyof T]: T[P] };
+// Must use { -readonly [P in keyof T]: T[P] }
+```
+
+---
+
+## Branded Type Omission [1, Item 37][22]
+
+Structural typing means two `string` aliases are interchangeable by default. Without
+branding, incorrect ID substitution compiles silently.
+
+```typescript
+// VIOLATION: Structural collision — UserId and OrderId both string [1, Item 37]
+type UserId  = string;
+type OrderId = string;
+
+function getUser(id: UserId): User { ... }
+
+declare const orderId: OrderId;
+getUser(orderId); // compiles! No protection against wrong-ID bugs
+
+// CORRECT: Branded types prevent silent substitution [1, Item 37][22]
+type UserId  = Brand<string, 'UserId'>;
+type OrderId = Brand<string, 'OrderId'>;
+getUser(orderId); // Error: OrderId not assignable to UserId
+```
+
+---
+
+## Async Pattern Violations [1, Item 25][2]
+
+### Unhandled Promises
+
+```typescript
+// VIOLATION: Fire-and-forget — error silently lost [1, Item 25]
+async function processData() {
+  saveToDatabase(data); // no await, no .catch()
+  console.log('Saved!'); // lie — may not be saved
+}
+
+// VIOLATION: forEach with async — outer loop doesn't wait [6]
+ids.forEach(async (id) => { await processItem(id); });
+```
+
+### Missing Error Handling
+
+```typescript
+// VIOLATION: No catch on fetch — network errors unhandled [2]
+async function loadUser(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  return response.json(); // throws on network failure, no type guard on JSON
+}
+
+// VIOLATION: Catch swallows error details [1, Item 47]
+try {
+  await riskyOperation();
+} catch (e) {
+  console.log('Error'); // e is unknown, message lost
+}
+```
+
+### Improper Async Patterns
+
+```typescript
+// VIOLATION: Sequential when parallel is possible [6]
+async function processAll(items: Item[]) {
+  const results = [];
+  for (const item of items) {
+    results.push(await process(item)); // one at a time unnecessarily
+  }
+  return results;
+}
+
+// VIOLATION: Unbounded Promise.all — overwhelms server [6]
+async function processAll(items: Item[]) {
+  return Promise.all(items.map(item => fetchData(item)));
+  // 1000 items → 1000 concurrent requests
+}
+
+// VIOLATION: Promise constructor anti-pattern [6]
+function fetchData(): Promise<Data> {
+  return new Promise(async (resolve, reject) => {
+    // async executor — errors in the async body don't reject the promise
+    const data = await fetch('/api/data');
+    resolve(data);
+  });
+}
+
+// VIOLATION: Callback inside async — inner return does nothing [6]
+async function getData() {
+  fs.readFile('data.json', (err, data) => {
+    return JSON.parse(data); // this return is discarded
+  });
+}
+```
+
+---
+
+## Module Violations [4][2]
+
+### Circular Dependencies
+
+```typescript
+// a.ts
+import { B } from './b';
+export class A { b = new B(); }
+
+// b.ts
+import { A } from './a'; // circular — loading order undefined
+export class B { a = new A(); }
+```
+
+### Import Anti-patterns [4]
+
+```typescript
+// VIOLATION: Importing entire module — no tree-shaking [4]
+import * as utils from './utils';
+utils.formatDate(date);
+
+// VIOLATION: Side effects at module level — untestable [4]
+export const db = new Database(connectionString); // runs on every import
+
+// VIOLATION: Value import for type-only usage — increases bundle [4]
+import { User } from './user'; // use: import type { User }
+```

package/src/assets/skills/ui-design/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: ui-design
+description: This skill should be used when the user asks to "design a component", "pick colors", "improve typography", "fix spacing", "choose a layout", or discusses visual design, CSS, styling decisions, or responsive interfaces. Provides patterns for typography scales, color systems, spacing, and production-grade UI design.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.css"
+    - "**/*.scss"
+    - "**/tailwind.config.*"
+  exclude:
+    - "node_modules/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# UI Design Patterns
+
+Reference for intentional visual design. Every choice must be justified. Sources in `references/sources.md`.
+
+## Iron Law
+
+> **AESTHETICS MUST HAVE INTENT** [4][11]
+>
+> Every visual choice must be justified. Default styles, copied gradients, and
+> "looks modern" are not justifications. If you cannot explain why a specific
+> font, color, or animation exists, it's design debt. Good design is invisible
+> because it serves purpose — it satisfies mental models, not trends.
+> — Don Norman, *The Design of Everyday Things* [11]; Laws of UX [4]
+
+## When This Skill Activates
+
+- Creating/styling UI components; reviewing CSS, Tailwind, or styled-components
+- Discussing typography, color schemes, layouts, or design systems
+
+---
+
+## 1. Typography [6][7][10][19]
+
+Font choice must match product personality: developer tools → monospace (precision), documentation → serif (readability), marketing → distinctive display. [6][7][27]
+
+Use a **mathematical type scale** (1.25 major third ratio). All sizes relate harmonically. [10] Line length: 45–75 characters for body text; `line-height: 1.7` for prose, `1.2` for headings. [6][7]
+
+Heading levels must differ in weight, tracking, and size — not size alone. [7][15] See `references/patterns.md` for scale values, font pairs, and heading styles.
+
+---
+
+## 2. Color System [1][9][12][14]
+
+**Three-layer token architecture** (Material Design 3 [1] + W3C Design Tokens spec [9]):
+
+```css
+:root {
+  --blue-600: #2563eb;                      /* Layer 1: Primitive */
+  --color-primary: var(--blue-600);         /* Layer 2: Semantic  */
+  --button-primary-bg: var(--color-primary);/* Layer 3: Component */
+}
+```
+
+**Dark mode**: swap semantic tokens only — never invert or filter. [23]
+Elevation in dark mode is expressed via lightness, not shadows. [1][12]
+
+**Contrast**: 4.5:1 for normal text, 3:1 for large text and UI components. [14][26]
+
+See `references/patterns.md` for dark surface hierarchy and accessible contrast examples.
+
+---
+
+## 3. Spacing [1][13][15]
+
+4px/8px base grid — from Müller-Brockmann grid mathematics [13], adopted by Material Design [1].
+All padding/margin values must come from the scale: `--space-1` (4px) through `--space-24` (96px).
+
+Gestalt proximity: larger gaps between sections, smaller gaps within — whitespace creates grouping. [5]
+
+**Violation**: `padding: 18px 22px` — magic number, off-grid. [15]
+
+See `references/patterns.md` for full scale and component spacing hierarchy.
+
+---
+
+## 4. Motion [4][11][24]
+
+Animation must communicate state, not decorate. Fitts's Law: every interaction needs tactile feedback. [4][11]
+
+Define a timing system (`--duration-fast: 100ms`, `--duration-normal: 200ms`, `--duration-slow: 300ms`). [1]
+Never animate `all` — specify properties. Transitions over 500ms feel sluggish for UI. [4]
+
+**Required**: `@media (prefers-reduced-motion: reduce)` — WCAG 2.2 and vestibular accessibility. [24][26]
+
+---
+
+## 5. Component Hierarchy [1][3][5][15]
+
+Atomic Design [3]: atoms → molecules → organisms. Components reference tokens; organisms compose molecules.
+
+**Elevation table** — radius and shadow signal interactivity, not decoration: [1][11][15]
+
+| Element | Radius | Shadow |
+|---------|--------|--------|
+| Badge/tag | 4px (`--radius-sm`) | none |
+| Button/input | 6px (`--radius-md`) | none |
+| Card (static) | 8px (`--radius-lg`) | `shadow-sm` |
+| Dropdown | 8px | `shadow-lg` |
+| Modal | 12px (`--radius-xl`) | `shadow-xl` |
+
+---
+
+## AI Slop Detection [4][11][15]
+
+| Pattern | Problem |
+|---------|---------|
+| Purple-to-pink gradient | No brand justification; copied template [15] |
+| `font-family: Inter` without rationale | Default, not intentional [6] |
+| Everything centered | No reading flow; violates hierarchy [30] |
+| `rounded-xl` everywhere | Radius must vary by component scale [1][15] |
+| Shadows on everything | Elevation loses meaning when ubiquitous [11] |
+| `animate-pulse` on buttons | Hick's Law: noise slows decisions [4] |
+| Glassmorphism everywhere | Trend, not purpose [15] |
+
+---
+
+## Extended References
+
+- `references/sources.md` — Full bibliography (30 sources)
+- `references/patterns.md` — Extended correct patterns with citations
+- `references/violations.md` — Extended violation examples with citations
+- `references/detection.md` — Grep patterns for finding issues
+
+---
+
+## Checklist
+
+- [ ] Typography scale is mathematical; font choice has documented rationale [6][10]
+- [ ] Color system uses 3-layer tokens (primitives → semantic → component) [1][9]
+- [ ] All text meets WCAG contrast minimums (4.5:1 / 3:1) [14][26]
+- [ ] Dark mode designed intentionally — no invert filter [23]
+- [ ] Spacing follows 4px/8px base grid — no magic numbers [1][13]
+- [ ] Animations communicate state; `prefers-reduced-motion` respected [24]
+- [ ] Component elevation (shadow, radius) signals interactivity level [1][11]
+- [ ] No AI slop patterns present [4][15]
+- [ ] Visual hierarchy via whitespace and spacing — not lines or boxes [5][30]