@cubis/foundry 0.3.70 → 0.3.72

package/workflows/powers/frontend-code-review/POWER.md

@@ -0,0 +1,137 @@
+````markdown
+---
+inclusion: manual
+name: frontend-code-review
+description: Review frontend code for accessibility, performance, state management, rendering efficiency, and design system compliance.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
+---
+
+# Frontend Code Review
+
+## Purpose
+
+Perform structured code reviews of frontend code, evaluating accessibility, performance, state management, rendering cost, and design system compliance. Produces actionable findings ranked by severity.
+
+## When to Use
+
+- Reviewing a pull request that touches frontend components, styles, or layout
+- Auditing an existing page or component for quality issues
+- Checking that new code follows team conventions and standards
+- Pre-launch review of a feature or page
+- When asked to "review", "audit", or "check" frontend code
+
+## Instructions
+
+### Step 1 — Scope the Review
+
+Identify what's being reviewed:
+
+- **Single component**: focus on API, accessibility, and rendering
+- **Page/feature**: focus on layout, loading states, and user flow
+- **Styles/CSS**: focus on token usage, responsiveness, and specificity
+- **Full audit**: run all checks below
+
+### Step 2 — Accessibility Review
+
+Check each item. Mark as pass (✓), fail (✗), or not-applicable (—):
+
+| Check               | Details                                                                         |
+| ------------------- | ------------------------------------------------------------------------------- |
+| Semantic HTML       | Correct elements (button, nav, main — not div for everything)                   |
+| Heading hierarchy   | h1 → h2 → h3, no skipped levels                                                 |
+| Keyboard navigation | All interactive elements reachable via Tab, operable via Enter/Space            |
+| Focus management    | Visible focus indicator, focus trapped in modals, restored after close          |
+| ARIA attributes     | Used only when native semantics insufficient, correct roles/states              |
+| Color contrast      | Text ≥ 4.5:1 (normal), ≥ 3:1 (large), UI components ≥ 3:1                       |
+| Alt text            | Images have meaningful alt (or empty alt for decorative)                        |
+| Form labels         | Every input has visible label or aria-label, errors linked via aria-describedby |
+| Motion              | Animations respect prefers-reduced-motion                                       |
+
+### Step 3 — Performance Review
+
+| Check              | Details                                                                           |
+| ------------------ | --------------------------------------------------------------------------------- |
+| Bundle impact      | New dependencies justified? Tree-shakeable? Could use native API instead?         |
+| Render cost        | Unnecessary re-renders? Missing memoization on expensive computations?            |
+| Layout shifts      | Images/embeds have dimensions? Dynamic content reserves space?                    |
+| Loading strategy   | Lazy-loaded below fold? Code-split at route level?                                |
+| Animation cost     | Compositor-only properties (transform, opacity)? No layout-triggering animations? |
+| Asset optimization | Images in modern format (WebP/AVIF)? Fonts preloaded? CSS critical path?          |
+
+### Step 4 — State Management Review
+
+| Check                | Details                                                              |
+| -------------------- | -------------------------------------------------------------------- |
+| State location       | State lives at the right level? Not lifted too high or duplicated?   |
+| Derived state        | Computed from source state, not stored separately?                   |
+| Side effects         | Cleanup on unmount? Race conditions handled? Abort controllers used? |
+| Loading/error states | All async operations handle loading, success, and error?             |
+| Form state           | Controlled vs uncontrolled appropriate? Validation on blur/submit?   |
+
+### Step 5 — Design System Compliance
+
+| Check               | Details                                                         |
+| ------------------- | --------------------------------------------------------------- |
+| Token usage         | Colors, spacing, typography, radius, shadows use design tokens? |
+| Component usage     | Using system components vs. custom implementations?             |
+| Naming conventions  | Class names, component names follow team patterns?              |
+| Responsive behavior | Mobile-first? Breakpoints consistent with system?               |
+| Consistency         | Visual style matches existing pages/components?                 |
+
+### Step 6 — Code Quality
+
+| Check               | Details                                                     |
+| ------------------- | ----------------------------------------------------------- |
+| TypeScript          | Proper types (no `any`), discriminated unions for variants? |
+| Component structure | Single responsibility? Reasonable size (< 200 lines)?       |
+| Error boundaries    | Errors caught at appropriate levels? Fallback UI provided?  |
+| Testing             | Key interactions tested? Visual regression coverage?        |
+| Documentation       | Complex logic commented? Props documented?                  |
+
+## Output Format
+
+Structure every review as:
+
+```
+## Review Summary
+[1-2 sentence overview of overall quality]
+
+## Critical (must fix before merge)
+- **[Category]**: [issue] → [fix]
+
+## Important (should fix)
+- **[Category]**: [issue] → [fix]
+
+## Suggestions (nice to have)
+- **[Category]**: [suggestion]
+
+## Passing
+- ✓ [what's done well — always include positives]
+```
+
+Severity definitions:
+
+- **Critical**: Accessibility violations, security issues, data loss risks, broken functionality
+- **Important**: Performance problems, missing error handling, design system violations
+- **Suggestion**: Code style, minor optimizations, documentation gaps
+
+## References
+
+- [references/review-checklists.md](references/review-checklists.md) — quick-reference checklists for common review scenarios
+- [references/common-antipatterns.md](references/common-antipatterns.md) — frequently seen frontend antipatterns with fixes
+- [references/performance-budgets.md](references/performance-budgets.md) — performance targets and measurement guidance
+
+## Examples
+
+**User**: "Review this React component" (pastes a Card component)
+
+**Response approach**: Run all 5 review steps. Check semantic HTML (is it using button/a vs div for interactive cards?), token usage (are colors hardcoded?), component API (boolean flags vs variants?), rendering (is it re-rendering unnecessarily?). Output findings in severity-ranked format.
+
+**User**: "Check this PR for accessibility issues"
+
+**Response approach**: Focus on Step 2 (Accessibility Review). Run through the full accessibility checklist. Report findings with WCAG criterion references and specific code fixes.
+````

package/workflows/powers/frontend-code-review/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: frontend-code-review
+description: Review frontend code for accessibility, performance, state management, rendering efficiency, and design system compliance.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
+---
+
+# Frontend Code Review
+
+## Purpose
+
+Perform structured code reviews of frontend code, evaluating accessibility, performance, state management, rendering cost, and design system compliance. Produces actionable findings ranked by severity.
+
+## When to Use
+
+- Reviewing a pull request that touches frontend components, styles, or layout
+- Auditing an existing page or component for quality issues
+- Checking that new code follows team conventions and standards
+- Pre-launch review of a feature or page
+- When asked to "review", "audit", or "check" frontend code
+
+## Instructions
+
+### Step 1 — Scope the Review
+
+Identify what's being reviewed:
+
+- **Single component**: focus on API, accessibility, and rendering
+- **Page/feature**: focus on layout, loading states, and user flow
+- **Styles/CSS**: focus on token usage, responsiveness, and specificity
+- **Full audit**: run all checks below
+
+### Step 2 — Accessibility Review
+
+Check each item. Mark as pass (✓), fail (✗), or not-applicable (—):
+
+| Check               | Details                                                                         |
+| ------------------- | ------------------------------------------------------------------------------- |
+| Semantic HTML       | Correct elements (button, nav, main — not div for everything)                   |
+| Heading hierarchy   | h1 → h2 → h3, no skipped levels                                                 |
+| Keyboard navigation | All interactive elements reachable via Tab, operable via Enter/Space            |
+| Focus management    | Visible focus indicator, focus trapped in modals, restored after close          |
+| ARIA attributes     | Used only when native semantics insufficient, correct roles/states              |
+| Color contrast      | Text ≥ 4.5:1 (normal), ≥ 3:1 (large), UI components ≥ 3:1                       |
+| Alt text            | Images have meaningful alt (or empty alt for decorative)                        |
+| Form labels         | Every input has visible label or aria-label, errors linked via aria-describedby |
+| Motion              | Animations respect prefers-reduced-motion                                       |
+
+### Step 3 — Performance Review
+
+| Check              | Details                                                                           |
+| ------------------ | --------------------------------------------------------------------------------- |
+| Bundle impact      | New dependencies justified? Tree-shakeable? Could use native API instead?         |
+| Render cost        | Unnecessary re-renders? Missing memoization on expensive computations?            |
+| Layout shifts      | Images/embeds have dimensions? Dynamic content reserves space?                    |
+| Loading strategy   | Lazy-loaded below fold? Code-split at route level?                                |
+| Animation cost     | Compositor-only properties (transform, opacity)? No layout-triggering animations? |
+| Asset optimization | Images in modern format (WebP/AVIF)? Fonts preloaded? CSS critical path?          |
+
+### Step 4 — State Management Review
+
+| Check                | Details                                                              |
+| -------------------- | -------------------------------------------------------------------- |
+| State location       | State lives at the right level? Not lifted too high or duplicated?   |
+| Derived state        | Computed from source state, not stored separately?                   |
+| Side effects         | Cleanup on unmount? Race conditions handled? Abort controllers used? |
+| Loading/error states | All async operations handle loading, success, and error?             |
+| Form state           | Controlled vs uncontrolled appropriate? Validation on blur/submit?   |
+
+### Step 5 — Design System Compliance
+
+| Check               | Details                                                         |
+| ------------------- | --------------------------------------------------------------- |
+| Token usage         | Colors, spacing, typography, radius, shadows use design tokens? |
+| Component usage     | Using system components vs. custom implementations?             |
+| Naming conventions  | Class names, component names follow team patterns?              |
+| Responsive behavior | Mobile-first? Breakpoints consistent with system?               |
+| Consistency         | Visual style matches existing pages/components?                 |
+
+### Step 6 — Code Quality
+
+| Check               | Details                                                     |
+| ------------------- | ----------------------------------------------------------- |
+| TypeScript          | Proper types (no `any`), discriminated unions for variants? |
+| Component structure | Single responsibility? Reasonable size (< 200 lines)?       |
+| Error boundaries    | Errors caught at appropriate levels? Fallback UI provided?  |
+| Testing             | Key interactions tested? Visual regression coverage?        |
+| Documentation       | Complex logic commented? Props documented?                  |
+
+## Output Format
+
+Structure every review as:
+
+```
+## Review Summary
+[1-2 sentence overview of overall quality]
+
+## Critical (must fix before merge)
+- **[Category]**: [issue] → [fix]
+
+## Important (should fix)
+- **[Category]**: [issue] → [fix]
+
+## Suggestions (nice to have)
+- **[Category]**: [suggestion]
+
+## Passing
+- ✓ [what's done well — always include positives]
+```
+
+Severity definitions:
+
+- **Critical**: Accessibility violations, security issues, data loss risks, broken functionality
+- **Important**: Performance problems, missing error handling, design system violations
+- **Suggestion**: Code style, minor optimizations, documentation gaps
+
+## References
+
+- [references/review-checklists.md](references/review-checklists.md) — quick-reference checklists for common review scenarios
+- [references/common-antipatterns.md](references/common-antipatterns.md) — frequently seen frontend antipatterns with fixes
+- [references/performance-budgets.md](references/performance-budgets.md) — performance targets and measurement guidance
+
+## Examples
+
+**User**: "Review this React component" (pastes a Card component)
+
+**Response approach**: Run all 5 review steps. Check semantic HTML (is it using button/a vs div for interactive cards?), token usage (are colors hardcoded?), component API (boolean flags vs variants?), rendering (is it re-rendering unnecessarily?). Output findings in severity-ranked format.
+
+**User**: "Check this PR for accessibility issues"
+
+**Response approach**: Focus on Step 2 (Accessibility Review). Run through the full accessibility checklist. Report findings with WCAG criterion references and specific code fixes.

package/workflows/powers/frontend-code-review/references/common-antipatterns.md

@@ -0,0 +1,86 @@
+# Common Frontend Antipatterns
+
+## Accessibility
+
+### div-as-button
+
+**Problem**: `<div onClick={...}>Click me</div>`
+**Fix**: Use `<button>` — gets keyboard events, focus, and ARIA role for free.
+
+### Missing form labels
+
+**Problem**: `<input placeholder="Email" />` with no label
+**Fix**: `<label htmlFor="email">Email</label><input id="email" />` — placeholder is not a label.
+
+### Color-only state indication
+
+**Problem**: Error field only turns red, no text or icon
+**Fix**: Add error message text + icon alongside the color change.
+
+## Performance
+
+### Inline object/array props
+
+**Problem**: `<Component style={{ color: 'red' }} items={[1,2,3]} />`
+**Fix**: Move to module-level constants or useMemo — inline objects create new references every render.
+
+### Missing keys or index-as-key
+
+**Problem**: `list.map((item, i) => <Item key={i} />)`
+**Fix**: Use stable unique IDs as keys — index breaks when list is reordered/filtered.
+
+### Unoptimized images
+
+**Problem**: 2MB PNG for a 200px thumbnail
+**Fix**: Use WebP/AVIF, responsive `srcset`, and `loading="lazy"` for below-fold images.
+
+### useEffect for derived state
+
+**Problem**: `useEffect(() => setFullName(first + ' ' + last), [first, last])`
+**Fix**: `const fullName = first + ' ' + last` — compute during render, no effect needed.
+
+## State Management
+
+### Prop drilling through 4+ levels
+
+**Problem**: Passing props through intermediate components that don't use them
+**Fix**: Use context, composition (children), or state management library.
+
+### Storing server state in local state
+
+**Problem**: `const [users, setUsers] = useState([]); useEffect(() => fetch...)`
+**Fix**: Use a data-fetching library (SWR, TanStack Query) — handles caching, revalidation, race conditions.
+
+### Missing cleanup in effects
+
+**Problem**: `useEffect(() => { const id = setInterval(...) }, [])` with no return
+**Fix**: Return cleanup function: `return () => clearInterval(id)`
+
+## Design System
+
+### Hardcoded magic numbers
+
+**Problem**: `padding: 13px; margin-top: 7px; color: #3b82f6;`
+**Fix**: Use design tokens: `padding: var(--spacing-3); color: var(--color-interactive-primary)`
+
+### Boolean prop explosion
+
+**Problem**: `<Button primary large outlined rounded disabled />`
+**Fix**: `<Button variant="primary" size="lg" disabled />` — use constrained variant props.
+
+### CSS specificity wars
+
+**Problem**: `.container .card .header .title { ... }` or `!important` everywhere
+**Fix**: Use flat selectors, utility classes, or CSS Modules for scoping.
+
+## Component Design
+
+### God component
+
+**Problem**: Single component file > 500 lines handling multiple concerns
+**Fix**: Extract subcomponents, custom hooks, and utility functions.
+
+### Premature abstraction
+
+**Problem**: Creating a reusable component from a single use case
+**Fix**: Wait for 2+ real use cases before extracting — inline is fine for now.

package/workflows/powers/frontend-code-review/references/performance-budgets.md

@@ -0,0 +1,56 @@
+# Performance Budgets
+
+## Core Web Vitals Targets
+
+| Metric                          | Good    | Needs Improvement | Poor    |
+| ------------------------------- | ------- | ----------------- | ------- |
+| LCP (Largest Contentful Paint)  | < 2.5s  | 2.5–4.0s          | > 4.0s  |
+| INP (Interaction to Next Paint) | < 200ms | 200–500ms         | > 500ms |
+| CLS (Cumulative Layout Shift)   | < 0.1   | 0.1–0.25          | > 0.25  |
+
+## Bundle Size Budgets
+
+| Resource                 | Budget         | Measurement                           |
+| ------------------------ | -------------- | ------------------------------------- |
+| Initial JS (compressed)  | < 150 KB       | gzip/brotli size of critical-path JS  |
+| Initial CSS (compressed) | < 50 KB        | gzip/brotli size of critical-path CSS |
+| Per-route JS chunk       | < 50 KB        | code-split chunk per route            |
+| Single component         | < 10 KB        | component + its direct dependencies   |
+| New dependency           | Justify > 5 KB | check bundlephobia before adding      |
+
+## Rendering Budgets
+
+| Check                | Target                            |
+| -------------------- | --------------------------------- |
+| Component re-renders | ≤ 1 per user interaction          |
+| DOM nodes per page   | < 1500 total                      |
+| DOM depth            | < 15 levels                       |
+| Event listeners      | No duplicates, cleanup on unmount |
+| Third-party scripts  | ≤ 3 per page, all async/defer     |
+
+## Image Budgets
+
+| Image Type    | Format       | Max Size |
+| ------------- | ------------ | -------- |
+| Hero/banner   | WebP/AVIF    | < 200 KB |
+| Content image | WebP/AVIF    | < 100 KB |
+| Thumbnail     | WebP         | < 30 KB  |
+| Icon          | SVG (inline) | < 3 KB   |
+| Avatar        | WebP         | < 15 KB  |
+
+## Font Budgets
+
+| Check               | Target                                           |
+| ------------------- | ------------------------------------------------ |
+| Total web fonts     | ≤ 2 families                                     |
+| Font file size      | < 50 KB per weight (WOFF2)                       |
+| Font weights loaded | ≤ 3 per family                                   |
+| Font display        | `font-display: swap` with size-adjusted fallback |
+
+## How to Measure
+
+- **Lighthouse**: Overall performance score, CWV metrics
+- **WebPageTest**: Real connection testing, filmstrip
+- **Bundle analyzer**: webpack-bundle-analyzer, source-map-explorer
+- **React DevTools Profiler**: Component render counts and timing
+- **Performance API**: `performance.mark()` / `performance.measure()` for custom timings

package/workflows/powers/frontend-code-review/references/review-checklists.md

@@ -0,0 +1,47 @@
+# Review Checklists
+
+## Quick Component Review (5 min)
+
+- [ ] Correct semantic HTML element
+- [ ] Keyboard accessible (Tab, Enter, Escape)
+- [ ] Visible focus indicator
+- [ ] Design tokens used (no hardcoded colors/spacing)
+- [ ] Loading and error states handled
+- [ ] TypeScript types (no `any`)
+
+## PR Review (15 min)
+
+Everything in Quick Review, plus:
+
+- [ ] No accessibility regressions (heading hierarchy, ARIA)
+- [ ] Images have alt text and dimensions
+- [ ] New dependencies justified and tree-shakeable
+- [ ] No unnecessary re-renders
+- [ ] Responsive behavior works (mobile-first)
+- [ ] Error boundaries at appropriate levels
+- [ ] Tests cover key interactions
+
+## Full Audit (30+ min)
+
+Everything in PR Review, plus:
+
+- [ ] Color contrast passes WCAG AA (4.5:1 text, 3:1 UI)
+- [ ] Screen reader experience tested
+- [ ] Animation respects prefers-reduced-motion
+- [ ] Layout shifts measured (CLS target < 0.1)
+- [ ] Bundle size impact analyzed
+- [ ] Forms: labels, validation, error association
+- [ ] State management: correct level, cleanup, race conditions
+- [ ] Component API: consistent with design system patterns
+- [ ] Documentation: props, usage examples, a11y notes
+
+## CSS/Styles Review
+
+- [ ] Uses design tokens, not hardcoded values
+- [ ] Mobile-first media queries
+- [ ] No `!important` (except utility overrides)
+- [ ] No overly specific selectors (max 2-3 levels)
+- [ ] Dark mode tested
+- [ ] Container queries used where component-level responsiveness needed
+- [ ] Animations use transform/opacity only
+- [ ] No layout-triggering properties in animations