@vpxa/aikit 0.1.74 → 0.1.75

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

@@ -1,237 +0,0 @@
----
-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/_preview/skills/lesson-learned/SKILL.md

@@ -1,113 +0,0 @@
----
-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]
----
-
-# Lesson Learned
-
-Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.
-
-## Before You Begin
-
-**Load the principles reference first.**
-
-1. Read `references/se-principles.md` to have the principle catalog available
-2. Optionally read `references/anti-patterns.md` if you suspect the changes include areas for improvement
-3. Determine the scope of analysis (see Phase 1)
-
-**Do not proceed until you've loaded at least `se-principles.md`.**
-
-## Phase 1: Determine Scope
-
-Ask the user or infer from context what to analyze.
-
-| Scope | Git Commands | When to Use |
-|-------|-------------|-------------|
-| Feature branch | `git log main..HEAD --oneline` + `git diff main...HEAD` | User is on a non-main branch (default) |
-| Last N commits | `git log --oneline -N` + `git diff HEAD~N..HEAD` | User specifies a range, or on main (default N=5) |
-| Specific commit | `git show <sha>` | User references a specific commit |
-| Working changes | `git diff` + `git diff --cached` | User says "what about these changes?" before committing |
-
-**Default behavior:**
-- If on a feature branch: analyze branch commits vs main
-- If on main: analyze the last 5 commits
-- If the user provides a different scope, use that
-
-## Phase 2: Gather Changes
-
-1. Run `git log` with the determined scope to get the commit list and messages
-2. Run `git diff` for the full diff of the scope
-3. If the diff is large (>500 lines), use `git diff --stat` first, then selectively read the top 3-5 most-changed files
-4. **Read commit messages carefully** -- they contain intent that raw diffs miss
-5. Only read changed files. Do not read the entire repo.
-
-## Phase 3: Analyze
-
-Identify the **dominant pattern** -- the single most instructive thing about these changes.
-
-Look for:
-- **Structural decisions** -- How was the code organized? Why those boundaries?
-- **Trade-offs made** -- What was gained vs. sacrificed? (readability vs. performance, DRY vs. clarity, speed vs. correctness)
-- **Problems solved** -- What was the before/after? What made the "after" better?
-- **Missed opportunities** -- Where could the code improve? (present gently as "next time, consider...")
-
-Map findings to specific principles from `references/se-principles.md`. Be specific -- quote actual code, reference actual file names and line changes.
-
-## Phase 4: Present the Lesson
-
-Use this template:
-
-```markdown
-## Lesson: [Principle Name]
-
-**What happened in the code:**
-[2-3 sentences describing the specific change, referencing files and commits]
-
-**The principle at work:**
-[1-2 sentences explaining the SE principle]
-
-**Why it matters:**
-[1-2 sentences on the practical consequence -- what would go wrong without this, or what goes right because of it]
-
-**Takeaway for next time:**
-[One concrete, actionable sentence the user can apply to future work]
-```
-
-If there is a second lesson worth noting (maximum 2 additional):
-
-```markdown
----
-
-### Also worth noting: [Principle Name]
-
-**In the code:** [1 sentence]
-**The principle:** [1 sentence]
-**Takeaway:** [1 sentence]
-```
-
-## What NOT to Do
-
-| Avoid | Why | Instead |
-|-------|-----|---------|
-| Listing every principle that vaguely applies | Overwhelming and generic | Pick the 1-2 most relevant |
-| Analyzing files that were not changed | Scope creep | Stick to the diff |
-| Ignoring commit messages | They contain intent that diffs miss | Read them as primary context |
-| Abstract advice disconnected from the code | Not actionable | Always reference specific files/lines |
-| Negative-only feedback | Demoralizing | Lead with what works, then suggest improvements |
-| More than 3 lessons | Dilutes the insight | One well-grounded lesson beats seven vague ones |
-
-## Conversation Style
-
-- **Reflective, not prescriptive.** Use the user's own code as primary evidence.
-- **Never say "you should have..."** -- instead use "the approach here shows..." or "next time you face this, consider..."
-- **If the code is good, say so.** Not every lesson is about what went wrong. Recognizing good patterns reinforces them.
-- **If the changes are trivial** (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. "These changes are straightforward -- no deep lesson here, just good housekeeping."
-- **Be specific.** Generic advice is worthless. Every claim must point to a concrete code change.

package/scaffold/_preview/skills/lesson-learned/references/anti-patterns.md

@@ -1,55 +0,0 @@
----
-description: Common anti-patterns to detect in code diffs. Use alongside se-principles.md for balanced analysis -- principles show what's good, anti-patterns show what to watch for.
----
-
-# Anti-Patterns
-
-When analyzing a diff, check for these signals. Present findings gently -- as opportunities, not failures.
-
-## God Object / God Class
-
-One module doing too much.
-**Diff signals:** A single file with many unrelated changes. One class/module imported everywhere. A file over 500 lines that keeps growing.
-**Suggest:** Extract responsibilities into focused modules (SRP).
-
-## Shotgun Surgery
-
-One logical change scattered across many files.
-**Diff signals:** 10+ files changed for a single feature or fix. The same type of edit repeated in many places. A rename or config change touching dozens of files.
-**Suggest:** Consolidate the scattered logic. If one change requires editing many files, the abstraction boundaries may be wrong.
-
-## Feature Envy
-
-A function that uses another module's data more than its own.
-**Diff signals:** Heavy cross-module imports. A function reaching deep into another object's properties. Utility functions that only serve one caller in a different module.
-**Suggest:** Move the function closer to the data it uses.
-
-## Premature Abstraction
-
-Abstracting before there are multiple concrete cases.
-**Diff signals:** An interface with exactly one implementation. A factory that creates only one type. A generic solution for a problem that exists only once.
-**Suggest:** Wait for the second or third use case before abstracting (Rule of Three).
-
-## Copy-Paste Programming
-
-Duplicated code blocks with minor variations.
-**Diff signals:** Similar code appearing in multiple places in the diff. Functions that differ by only a parameter or two. Repeated patterns that could be parameterized.
-**Suggest:** Extract shared logic, parameterize the differences.
-
-## Magic Numbers / Strings
-
-Literal values without explanation.
-**Diff signals:** Hardcoded numbers in conditions (`if (retries > 3)`). String literals used as keys or identifiers. Timeouts, limits, or thresholds without named constants.
-**Suggest:** Extract to named constants that explain the "why."
-
-## Long Method
-
-Functions that do too much.
-**Diff signals:** New functions over 40-50 lines. Functions with multiple levels of nesting. Functions that require scrolling to read.
-**Suggest:** Extract sub-steps into named functions. Each function should do one thing.
-
-## Excessive Comments
-
-Comments explaining "what" instead of "why."
-**Diff signals:** Comments restating the code (`// increment counter`). Large comment blocks before straightforward code. Commented-out code left in place.
-**Suggest:** Make the code self-documenting through better naming. Use comments only for "why" -- intent, trade-offs, non-obvious constraints.

package/scaffold/_preview/skills/lesson-learned/references/se-principles.md

@@ -1,109 +0,0 @@
----
-description: Curated catalog of software engineering principles. Load this before analyzing code changes so you can map observations to named principles.
----
-
-# Software Engineering Principles
-
-Use this as a lookup table. When you spot a pattern in a diff, find the matching principle here. Each entry includes **code signals** -- what to look for in actual changes.
-
-## Design Principles (SOLID)
-
-**Single Responsibility Principle (SRP)**
-A module should have one reason to change.
-Code signals: A class/file was split into two. A function was extracted. A component stopped handling both UI and data fetching.
-
-**Open/Closed Principle (OCP)**
-Open for extension, closed for modification.
-Code signals: New behavior added without changing existing code. A plugin/hook/callback system introduced. Strategy pattern or configuration used instead of conditionals.
-
-**Liskov Substitution Principle (LSP)**
-Subtypes must be substitutable for their base types.
-Code signals: An interface was introduced to unify implementations. A subclass override changed behavior in a way that broke callers (violation). Type narrowing or guards added.
-
-**Interface Segregation Principle (ISP)**
-No client should depend on methods it doesn't use.
-Code signals: A large interface was split into smaller ones. Optional methods removed from an interface. A "fat" props object was broken into focused ones.
-
-**Dependency Inversion Principle (DIP)**
-Depend on abstractions, not concretions.
-Code signals: A concrete dependency replaced with an interface/injection. A factory or provider pattern introduced. Import paths changed from specific implementations to abstract layers.
-
-**Composition over Inheritance**
-Favor object composition over class inheritance.
-Code signals: Inheritance hierarchy replaced with delegation. Mixins or HOCs replaced with hooks or composition. A "base class" was removed.
-
-## Simplicity Principles
-
-**DRY (Don't Repeat Yourself)**
-Every piece of knowledge should have a single representation.
-Code signals: Duplicate code extracted into a shared function. A constant replaced repeated literals. A template/generator replaced copy-pasted boilerplate.
-
-**KISS (Keep It Simple, Stupid)**
-The simplest solution that works is the best.
-Code signals: A complex abstraction replaced with a straightforward implementation. Unnecessary indirection removed. A clever one-liner replaced with readable code.
-
-**YAGNI (You Aren't Gonna Need It)**
-Don't build it until you actually need it.
-Code signals: Speculative features removed. Unused configuration options deleted. An over-engineered solution simplified to match actual requirements.
-
-**Rule of Three**
-Wait until the third duplication before abstracting.
-Code signals: Similar code exists in 2 places and was left alone (good). A premature abstraction was introduced after only one use (violation). Third occurrence triggered extraction (textbook application).
-
-**Principle of Least Surprise**
-Code should behave the way most users would expect.
-Code signals: A function renamed to better describe what it does. Return types made consistent. Side effects made explicit or removed.
-
-## Structural Principles
-
-**Separation of Concerns**
-Different responsibilities should live in different modules.
-Code signals: Business logic extracted from UI components. Data access separated from domain logic. Configuration separated from behavior. A "god file" split into focused modules.
-
-**High Cohesion**
-Related functionality should live together.
-Code signals: Scattered related functions gathered into one module. A utility file broken up so each piece lives near its consumers. A feature folder created.
-
-**Loose Coupling**
-Modules should depend on each other as little as possible.
-Code signals: Direct imports replaced with events/callbacks. A shared dependency removed. Modules communicate through well-defined interfaces instead of reaching into internals.
-
-**Encapsulation**
-Hide internal details, expose only what's necessary.
-Code signals: Public methods reduced. Internal helpers made private. A module's API surface shrunk. Implementation details hidden behind a facade.
-
-**Information Hiding**
-Modules should not expose their internal data structures.
-Code signals: Raw data structures wrapped in accessor methods. Internal state made private. A data transformation moved inside the module that owns the data.
-
-## Pragmatic Principles
-
-**Boy Scout Rule**
-Leave the code better than you found it.
-Code signals: Small cleanups alongside a feature change. A renamed variable for clarity. A dead code path removed. An outdated comment updated.
-
-**Fail Fast**
-Detect and report errors as early as possible.
-Code signals: Input validation added at entry points. Assertions added for invariants. Early returns replacing deep nesting. Error handling moved closer to the source.
-
-**Defensive Programming**
-Anticipate and handle unexpected inputs gracefully.
-Code signals: Null checks added. Default values provided. Edge cases handled. Error boundaries introduced.
-
-**Premature Optimization (avoiding it)**
-Don't optimize until you've measured.
-Code signals: A simple implementation chosen over a "faster" complex one. Readability prioritized over micro-performance. A profiling step added before optimization work.
-
-## Refactoring Patterns
-
-**Extract Method/Function**
-Code signals: A long function split into named sub-functions. Inline logic replaced with a well-named call.
-
-**Extract Class/Module**
-Code signals: A file split into multiple files. A class split into two with distinct responsibilities.
-
-**Replace Conditional with Polymorphism**
-Code signals: A switch/if-else chain replaced with a strategy pattern or subclass dispatch. A type map introduced.
-
-**Introduce Parameter Object**
-Code signals: Multiple related parameters grouped into a single options/config object. Function signatures simplified.