@vpxa/aikit 0.1.55 → 0.1.57

package/scaffold/general/skills/frontend-design/SKILL.md

@@ -1,237 +1,237 @@
----
-name: frontend-design
-description: "Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection."
-metadata:
-	category: domain
-	domain: frontend
-	applicability: on-demand
-	inputs: [ui-requirements, codebase]
-	outputs: [design-guidance, patterns]
-	relatedSkills: [react]
----
-
-# Frontend Design
-
-> Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection. Synthesized from Anthropic's frontend-design skill, Vercel Web Interface Guidelines, and Impeccable design patterns.
-
-## When to Use
-
-**MANDATORY** for the Frontend agent on every task. Also use when:
-- Building any UI component, page, or layout
-- Styling, theming, or visual design work
-- Reviewing UI for quality, accessibility, or design consistency
-- User says "make it look good", "design", "UI", "styling", "responsive", "dark mode", "animation"
-
-## Context Gathering Protocol
-
-Before any design work, gather answers to these questions (infer from codebase if user doesn't specify):
-
-1. **Design System** — Does one exist? Tokens, variables, component library?
-2. **Brand Guidelines** — Colors, fonts, logo usage, tone?
-3. **Accessibility Requirements** — WCAG level (AA default), assistive tech?
-4. **Responsive Breakpoints** — Mobile-first? Specific breakpoints?
-5. **Motion Preferences** — Animation budget, reduced-motion support?
-6. **Content Model** — CMS, static, dynamic, i18n?
-7. **Dark Mode** — Required? System preference detection?
-8. **Target Platforms** — Desktop, mobile web, tablet, native?
-
-## Design Thinking Process
-
-Follow this cycle: **Understand → Explore → Evaluate → Refine**
-
-1. **Understand** — What is the user trying to accomplish? What are the constraints?
-2. **Explore** — Generate at minimum 2-3 distinct design directions. Name each direction. Describe the aesthetic and rationale.
-3. **Evaluate** — Compare against requirements, accessibility, performance, and the AI Slop Test.
-4. **Refine** — Iterate on the chosen direction. Polish details.
-
-## Typography
-
-### Hierarchy
-- Use a **clear scale**: display → h1 → h2 → h3 → body → caption → overline
-- Maximum **3 font sizes** per viewport visible at once
-- Use `font-weight` to create hierarchy within same size
-- Line height: 1.5 for body text, 1.2-1.3 for headings
-- **Fluid typography**: use `clamp()` for responsive sizing — e.g., `clamp(1rem, 2.5vw, 1.5rem)`
-
-### Rules
-- Never use more than 2 typeface families
-- Ensure minimum **16px** body text on mobile
-- Use `rem` for font sizes, `em` for component-relative spacing
-- Monospace only for code: use a dedicated code font family
-- Set `max-width: 65ch` on text blocks for readability
-- Use `text-wrap: balance` on headings, `text-wrap: pretty` on body
-- Provide room for **text expansion** (50%+) for i18n
-
-## Color
-
-### 60-30-10 Rule
-- **60%** — Background/surface (neutral)
-- **30%** — Secondary/container (brand subtle)
-- **10%** — Accent/CTA (brand strong)
-
-### Systematic Color
-- Define colors as design tokens with semantic names: `--color-surface`, `--color-text-primary`, `--color-accent`
-- Every color needs **4.5:1 contrast ratio** minimum (WCAG AA) for text
-- Non-text elements need **3:1** minimum
-- Never rely on color alone to convey information — pair with icons, text, or patterns
-- Test with color blindness simulators
-
-### Dark Mode
-- Detect system preference with `prefers-color-scheme`
-- Don't just invert — re-design surfaces: dark surfaces get lighter elevation, reduce saturation
-- Smooth transition between modes (CSS transitions on `background-color`, `color`)
-- Diagrams/images: consider `filter: invert(1)` or provide alternate assets
-- Store user preference and sync with system default
-
-## Layout & Spacing
-
-### Grid System
-- Use an **8px base grid** — all spacing is a multiple of 8 (4px for tight spaces)
-- CSS Grid for 2D layouts, Flexbox for 1D alignment
-- Consistent spacing tokens: `--space-xs: 4px`, `--space-sm: 8px`, `--space-md: 16px`, `--space-lg: 24px`, `--space-xl: 32px`, `--space-2xl: 48px`, `--space-3xl: 64px`
-
-### Responsive Design
-- **Mobile-first**: design for 320px, scale up
-- Breakpoints: only add when the layout breaks, not at device widths
-- Use `container queries` for component-level responsiveness
-- Fluid layouts with `minmax()`, `auto-fill`, `auto-fit`
-- Every interactive target: minimum **44×44px** touch area (WCAG 2.5.5)
-
-### Rules
-- Use consistent gutters — don't mix random padding values
-- Stacking: define a z-index scale (e.g., base: 0, dropdown: 100, modal: 200, toast: 300)
-- Avoid magic numbers — extract to named tokens
-
-## Motion & Animation
-
-### Principles
-- **Purpose before polish** — every animation must serve a purpose: orientation, feedback, continuity, or delight
-- **Spring physics** over linear easing — use `cubic-bezier(0.175, 0.885, 0.32, 1.275)` or spring-based libraries
-- Duration budget: micro-interactions **100-200ms**, transitions **200-400ms**, page transitions **300-500ms**
-- Never exceed **500ms** unless it's a storytelling/onboarding animation
-
-### Performance
-- Animate only `transform` and `opacity` — these run on the compositor thread
-- Never animate `width`, `height`, `top`, `left`, `margin`, `padding` (trigger layout)
-- Use `will-change` sparingly and only before the animation starts
-- `requestAnimationFrame` for JS animations
-
-### Accessibility
-- **Always respect `prefers-reduced-motion`**: reduce or remove animations when set
-- Layout animations: use `layout` prop (Framer Motion) or FLIP technique
-- Skeleton screens during loading — never an empty blank page
-- Skeleton loading → content: smooth fade transition, not a hard swap
-
-### Patterns
-- Enter/exit transitions with stagger for lists
-- Shared element transitions between route changes
-- Micro-interactions on hover/focus: subtle scale, bg-color shift, shadow change
-- Pull-to-refresh, swipe gestures (mobile) with physics-based feel
-
-## Accessibility (WCAG AA Mandatory)
-
-### Structure
-- Use **semantic HTML**: `header`, `nav`, `main`, `section`, `article`, `aside`, `footer`
-- Every `<img>` has a meaningful `alt` (or `alt=""` for decorative)
-- Every form field has a visible `<label>` (not just placeholder)
-- Headings form a logical hierarchy (`h1` → `h2` → `h3`, no skipping)
-
-### Keyboard Navigation
-- All interactive elements reachable via **Tab** key
-- Logical tab order (follows visual reading order)
-- Focus indicators: visible, high-contrast, never `outline: none` without replacement
-- Escape to close modals/dropdowns, Enter/Space to activate
-- Skip-to-content link for screen readers
-
-### Screen Readers
-- ARIA labels on icons-only buttons: `aria-label="Close"`
-- Live regions for dynamic content: `aria-live="polite"` for updates, `"assertive"` for errors
-- Landmark roles if semantic HTML is insufficient
-- Don't use ARIA when a native HTML element works (`<button>` not `<div role="button">`)
-
-### Testing
-- Tab through entire flow without mouse
-- Test with screen reader (NVDA, VoiceOver)
-- Run Lighthouse accessibility audit
-- Test at 200% zoom — nothing should break or overflow
-
-## Forms
-
-- **Instant inline validation** — validate on blur, not on every keystroke
-- Show error messages below the field, not in an alert
-- Preserve user input on error — never clear a form on submit failure
-- **Auto-save** drafts for long forms (debounced)
-- Use `inputmode` for mobile: `numeric`, `email`, `tel`, `url`
-- Multi-step forms: show progress indicator and allow back-navigation
-- File uploads: drag-and-drop zone, progress indicator, file type restrictions, preview
-- **Optimistic UI**: show success immediately, revert on error
-
-## Navigation & State
-
-- URL should always reflect application state (`/settings/profile` not `/settings#profile`)
-- Support deep linking — any URL should be shareable and land on the right view
-- Breadcrumbs for hierarchical navigation (3+ levels deep)
-- Keyboard shortcuts for power users (document them)
-- Browser back/forward must work correctly — don't break history
-
-## Performance
-
-- **Virtual scroll** for lists > 100 items — don't render 10,000 DOM nodes
-- **Lazy load** images: use `loading="lazy"`, provide dimensions to prevent layout shift
-- **Prefetch** next-likely routes on hover/viewport intersection
-- **Code split** by route — each page only loads its own JavaScript
-- **Edge rendering** — render at the CDN edge when possible (SSR, RSC)
-- Optimize images: use `<picture>` with WebP/AVIF + fallback
-- Font loading: `font-display: swap`, preload critical fonts
-- Target LCP < 2.5s, INP < 200ms, CLS < 0.1
-
-## Error Handling
-
-- **Graceful degradation** — partial failures shouldn't crash the entire page
-- Show retry buttons on transient errors
-- Offline indicator when network is lost
-- Clear error messages: what happened, what the user can do about it
-- Error boundaries in React: catch rendering errors, show fallback UI
-- Never show raw error messages, stack traces, or error codes to users
-
-## SSR & Hydration
-
-- Prevent hydration mismatches: no `Date.now()`, `Math.random()`, `window` in server render
-- Use streaming SSR for faster TTFB
-- Optimistic mutations: update UI before server confirms
-- Handle loading states with Suspense boundaries
-
-## Internationalization (i18n)
-
-- **RTL support**: use logical properties (`margin-inline-start` not `margin-left`)
-- Format dates/numbers/currencies locale-aware — never hardcode formats
-- Text expansion room: German/French can be 50%+ longer than English
-- Unicode support: test with CJK, Arabic, emoji
-- Externalize all user-visible strings
-
-## AI Slop Test — MANDATORY CHECK
-
-Before shipping ANY design, verify it does NOT have these AI-generated tells:
-
-| AI Slop Pattern | What to check |
-|-----------------|---------------|
-| Centered hero + gradient blob | Does it look like every AI demo landing page? ADD ASYMMETRY |
-| Lowercase geometric sans headings | Add personality: case choices, weight variation, size contrast |
-| Purple-to-blue gradient | If using gradients, use brand-specific or creative color stops |
-| Uniform card grid with icon + heading + text | Vary card sizes, add imagery, break the grid |
-| Stock illustration style | Use real photos, custom illustrations, or no imagery |
-| "Modern SaaS template" look | Add something unexpected: editorial layout, bold typography, color blocking |
-| Generic placeholder copy | Real content or clearly marked FPO (For Placement Only) |
-| Identical padding everywhere | Vary rhythm — tight grouping inside sections, generous between |
-| No texture or depth | Add subtle noise, shadows, borders, layering |
-| Perfectly symmetrical everything | Break symmetry deliberately — offset grids, varied alignments |
-
-If 3+ items match → **STOP and redesign**. The goal is distinctive, not generic.
-
-## Implementation Principles
-
-1. **Design tokens before code** — define variables/tokens first, then use them everywhere
-2. **Component boundaries** — each component owns its internal layout, parent owns its placement
-3. **Progressive enhancement** — works without JS, enhanced with JS
-4. **Content-first** — design with real content, not lorem ipsum
-5. **Test in context** — view components inside the actual page, not just in isolation
+---
+name: frontend-design
+description: "Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection."
+metadata:
+  category: domain
+  domain: frontend
+  applicability: on-demand
+  inputs: [ui-requirements, codebase]
+  outputs: [design-guidance, patterns]
+  relatedSkills: [react]
+---
+
+# Frontend Design
+
+> Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection. Synthesized from Anthropic's frontend-design skill, Vercel Web Interface Guidelines, and Impeccable design patterns.
+
+## When to Use
+
+**MANDATORY** for the Frontend agent on every task. Also use when:
+- Building any UI component, page, or layout
+- Styling, theming, or visual design work
+- Reviewing UI for quality, accessibility, or design consistency
+- User says "make it look good", "design", "UI", "styling", "responsive", "dark mode", "animation"
+
+## Context Gathering Protocol
+
+Before any design work, gather answers to these questions (infer from codebase if user doesn't specify):
+
+1. **Design System** — Does one exist? Tokens, variables, component library?
+2. **Brand Guidelines** — Colors, fonts, logo usage, tone?
+3. **Accessibility Requirements** — WCAG level (AA default), assistive tech?
+4. **Responsive Breakpoints** — Mobile-first? Specific breakpoints?
+5. **Motion Preferences** — Animation budget, reduced-motion support?
+6. **Content Model** — CMS, static, dynamic, i18n?
+7. **Dark Mode** — Required? System preference detection?
+8. **Target Platforms** — Desktop, mobile web, tablet, native?
+
+## Design Thinking Process
+
+Follow this cycle: **Understand → Explore → Evaluate → Refine**
+
+1. **Understand** — What is the user trying to accomplish? What are the constraints?
+2. **Explore** — Generate at minimum 2-3 distinct design directions. Name each direction. Describe the aesthetic and rationale.
+3. **Evaluate** — Compare against requirements, accessibility, performance, and the AI Slop Test.
+4. **Refine** — Iterate on the chosen direction. Polish details.
+
+## Typography
+
+### Hierarchy
+- Use a **clear scale**: display → h1 → h2 → h3 → body → caption → overline
+- Maximum **3 font sizes** per viewport visible at once
+- Use `font-weight` to create hierarchy within same size
+- Line height: 1.5 for body text, 1.2-1.3 for headings
+- **Fluid typography**: use `clamp()` for responsive sizing — e.g., `clamp(1rem, 2.5vw, 1.5rem)`
+
+### Rules
+- Never use more than 2 typeface families
+- Ensure minimum **16px** body text on mobile
+- Use `rem` for font sizes, `em` for component-relative spacing
+- Monospace only for code: use a dedicated code font family
+- Set `max-width: 65ch` on text blocks for readability
+- Use `text-wrap: balance` on headings, `text-wrap: pretty` on body
+- Provide room for **text expansion** (50%+) for i18n
+
+## Color
+
+### 60-30-10 Rule
+- **60%** — Background/surface (neutral)
+- **30%** — Secondary/container (brand subtle)
+- **10%** — Accent/CTA (brand strong)
+
+### Systematic Color
+- Define colors as design tokens with semantic names: `--color-surface`, `--color-text-primary`, `--color-accent`
+- Every color needs **4.5:1 contrast ratio** minimum (WCAG AA) for text
+- Non-text elements need **3:1** minimum
+- Never rely on color alone to convey information — pair with icons, text, or patterns
+- Test with color blindness simulators
+
+### Dark Mode
+- Detect system preference with `prefers-color-scheme`
+- Don't just invert — re-design surfaces: dark surfaces get lighter elevation, reduce saturation
+- Smooth transition between modes (CSS transitions on `background-color`, `color`)
+- Diagrams/images: consider `filter: invert(1)` or provide alternate assets
+- Store user preference and sync with system default
+
+## Layout & Spacing
+
+### Grid System
+- Use an **8px base grid** — all spacing is a multiple of 8 (4px for tight spaces)
+- CSS Grid for 2D layouts, Flexbox for 1D alignment
+- Consistent spacing tokens: `--space-xs: 4px`, `--space-sm: 8px`, `--space-md: 16px`, `--space-lg: 24px`, `--space-xl: 32px`, `--space-2xl: 48px`, `--space-3xl: 64px`
+
+### Responsive Design
+- **Mobile-first**: design for 320px, scale up
+- Breakpoints: only add when the layout breaks, not at device widths
+- Use `container queries` for component-level responsiveness
+- Fluid layouts with `minmax()`, `auto-fill`, `auto-fit`
+- Every interactive target: minimum **44×44px** touch area (WCAG 2.5.5)
+
+### Rules
+- Use consistent gutters — don't mix random padding values
+- Stacking: define a z-index scale (e.g., base: 0, dropdown: 100, modal: 200, toast: 300)
+- Avoid magic numbers — extract to named tokens
+
+## Motion & Animation
+
+### Principles
+- **Purpose before polish** — every animation must serve a purpose: orientation, feedback, continuity, or delight
+- **Spring physics** over linear easing — use `cubic-bezier(0.175, 0.885, 0.32, 1.275)` or spring-based libraries
+- Duration budget: micro-interactions **100-200ms**, transitions **200-400ms**, page transitions **300-500ms**
+- Never exceed **500ms** unless it's a storytelling/onboarding animation
+
+### Performance
+- Animate only `transform` and `opacity` — these run on the compositor thread
+- Never animate `width`, `height`, `top`, `left`, `margin`, `padding` (trigger layout)
+- Use `will-change` sparingly and only before the animation starts
+- `requestAnimationFrame` for JS animations
+
+### Accessibility
+- **Always respect `prefers-reduced-motion`**: reduce or remove animations when set
+- Layout animations: use `layout` prop (Framer Motion) or FLIP technique
+- Skeleton screens during loading — never an empty blank page
+- Skeleton loading → content: smooth fade transition, not a hard swap
+
+### Patterns
+- Enter/exit transitions with stagger for lists
+- Shared element transitions between route changes
+- Micro-interactions on hover/focus: subtle scale, bg-color shift, shadow change
+- Pull-to-refresh, swipe gestures (mobile) with physics-based feel
+
+## Accessibility (WCAG AA Mandatory)
+
+### Structure
+- Use **semantic HTML**: `header`, `nav`, `main`, `section`, `article`, `aside`, `footer`
+- Every `<img>` has a meaningful `alt` (or `alt=""` for decorative)
+- Every form field has a visible `<label>` (not just placeholder)
+- Headings form a logical hierarchy (`h1` → `h2` → `h3`, no skipping)
+
+### Keyboard Navigation
+- All interactive elements reachable via **Tab** key
+- Logical tab order (follows visual reading order)
+- Focus indicators: visible, high-contrast, never `outline: none` without replacement
+- Escape to close modals/dropdowns, Enter/Space to activate
+- Skip-to-content link for screen readers
+
+### Screen Readers
+- ARIA labels on icons-only buttons: `aria-label="Close"`
+- Live regions for dynamic content: `aria-live="polite"` for updates, `"assertive"` for errors
+- Landmark roles if semantic HTML is insufficient
+- Don't use ARIA when a native HTML element works (`<button>` not `<div role="button">`)
+
+### Testing
+- Tab through entire flow without mouse
+- Test with screen reader (NVDA, VoiceOver)
+- Run Lighthouse accessibility audit
+- Test at 200% zoom — nothing should break or overflow
+
+## Forms
+
+- **Instant inline validation** — validate on blur, not on every keystroke
+- Show error messages below the field, not in an alert
+- Preserve user input on error — never clear a form on submit failure
+- **Auto-save** drafts for long forms (debounced)
+- Use `inputmode` for mobile: `numeric`, `email`, `tel`, `url`
+- Multi-step forms: show progress indicator and allow back-navigation
+- File uploads: drag-and-drop zone, progress indicator, file type restrictions, preview
+- **Optimistic UI**: show success immediately, revert on error
+
+## Navigation & State
+
+- URL should always reflect application state (`/settings/profile` not `/settings#profile`)
+- Support deep linking — any URL should be shareable and land on the right view
+- Breadcrumbs for hierarchical navigation (3+ levels deep)
+- Keyboard shortcuts for power users (document them)
+- Browser back/forward must work correctly — don't break history
+
+## Performance
+
+- **Virtual scroll** for lists > 100 items — don't render 10,000 DOM nodes
+- **Lazy load** images: use `loading="lazy"`, provide dimensions to prevent layout shift
+- **Prefetch** next-likely routes on hover/viewport intersection
+- **Code split** by route — each page only loads its own JavaScript
+- **Edge rendering** — render at the CDN edge when possible (SSR, RSC)
+- Optimize images: use `<picture>` with WebP/AVIF + fallback
+- Font loading: `font-display: swap`, preload critical fonts
+- Target LCP < 2.5s, INP < 200ms, CLS < 0.1
+
+## Error Handling
+
+- **Graceful degradation** — partial failures shouldn't crash the entire page
+- Show retry buttons on transient errors
+- Offline indicator when network is lost
+- Clear error messages: what happened, what the user can do about it
+- Error boundaries in React: catch rendering errors, show fallback UI
+- Never show raw error messages, stack traces, or error codes to users
+
+## SSR & Hydration
+
+- Prevent hydration mismatches: no `Date.now()`, `Math.random()`, `window` in server render
+- Use streaming SSR for faster TTFB
+- Optimistic mutations: update UI before server confirms
+- Handle loading states with Suspense boundaries
+
+## Internationalization (i18n)
+
+- **RTL support**: use logical properties (`margin-inline-start` not `margin-left`)
+- Format dates/numbers/currencies locale-aware — never hardcode formats
+- Text expansion room: German/French can be 50%+ longer than English
+- Unicode support: test with CJK, Arabic, emoji
+- Externalize all user-visible strings
+
+## AI Slop Test — MANDATORY CHECK
+
+Before shipping ANY design, verify it does NOT have these AI-generated tells:
+
+| AI Slop Pattern | What to check |
+|-----------------|---------------|
+| Centered hero + gradient blob | Does it look like every AI demo landing page? ADD ASYMMETRY |
+| Lowercase geometric sans headings | Add personality: case choices, weight variation, size contrast |
+| Purple-to-blue gradient | If using gradients, use brand-specific or creative color stops |
+| Uniform card grid with icon + heading + text | Vary card sizes, add imagery, break the grid |
+| Stock illustration style | Use real photos, custom illustrations, or no imagery |
+| "Modern SaaS template" look | Add something unexpected: editorial layout, bold typography, color blocking |
+| Generic placeholder copy | Real content or clearly marked FPO (For Placement Only) |
+| Identical padding everywhere | Vary rhythm — tight grouping inside sections, generous between |
+| No texture or depth | Add subtle noise, shadows, borders, layering |
+| Perfectly symmetrical everything | Break symmetry deliberately — offset grids, varied alignments |
+
+If 3+ items match → **STOP and redesign**. The goal is distinctive, not generic.
+
+## Implementation Principles
+
+1. **Design tokens before code** — define variables/tokens first, then use them everywhere
+2. **Component boundaries** — each component owns its internal layout, parent owns its placement
+3. **Progressive enhancement** — works without JS, enhanced with JS
+4. **Content-first** — design with real content, not lorem ipsum
+5. **Test in context** — view components inside the actual page, not just in isolation

package/scaffold/general/skills/lesson-learned/SKILL.md

@@ -2,13 +2,13 @@
 name: lesson-learned
 description: "Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work."
 metadata:
-	category: cross-cutting
-	domain: general
-	applicability: on-demand
-	inputs: [git-history, code-changes]
-	outputs: [engineering-lessons]
-	requires: [aikit]
-	relatedSkills: [session-handoff]
+  category: cross-cutting
+  domain: general
+  applicability: on-demand
+  inputs: [git-history, code-changes]
+  outputs: [engineering-lessons]
+  requires: [aikit]
+  relatedSkills: [session-handoff]
 ---
 
 # Lesson Learned