@jhm1909/ag-kit 0.1.0

package/.agent/skills/designer/references/design-systems.md

@@ -0,0 +1,219 @@
+# Design Systems Guide
+
+Expert guide for creating and maintaining scalable design systems.
+
+## Design Tokens
+
+### Token Hierarchy
+
+```
+Global Tokens (primitives)
+    ↓
+Semantic Tokens (purpose)
+    ↓
+Component Tokens (specific)
+```
+
+### Token Categories
+
+| Category    | Examples                                  |
+| ----------- | ----------------------------------------- |
+| Color       | `color.blue.500`, `color.surface.primary` |
+| Typography  | `font.family.body`, `font.size.lg`        |
+| Spacing     | `space.4`, `space.8`                      |
+| Border      | `border.radius.md`, `border.width.thin`   |
+| Shadow      | `shadow.sm`, `shadow.lg`                  |
+| Motion      | `duration.fast`, `ease.out`               |
+| Breakpoints | `breakpoint.md`, `breakpoint.lg`          |
+| Z-index     | `z.modal`, `z.tooltip`                    |
+
+### Token Naming Convention
+
+```
+{category}.{property}.{variant}.{state}
+
+Examples:
+color.background.surface
+color.background.surface.hover
+font.size.heading.xl
+space.padding.component.md
+```
+
+### CSS Implementation
+
+```css
+:root {
+  /* Primitives */
+  --color-blue-500: #3b82f6;
+  --color-blue-600: #2563eb;
+
+  /* Semantic */
+  --color-primary: var(--color-blue-500);
+  --color-primary-hover: var(--color-blue-600);
+
+  /* Component-specific (optional) */
+  --button-bg: var(--color-primary);
+  --button-bg-hover: var(--color-primary-hover);
+}
+```
+
+## Component Architecture
+
+### Atomic Design Levels
+
+| Level     | Description         | Examples               |
+| --------- | ------------------- | ---------------------- |
+| Atoms     | Basic elements      | Button, Input, Icon    |
+| Molecules | Simple combinations | Search bar, Form field |
+| Organisms | Complex sections    | Header, Card, Modal    |
+| Templates | Page layouts        | Dashboard, Settings    |
+| Pages     | Specific instances  | Home, Profile          |
+
+### Component API Design
+
+```typescript
+interface ButtonProps {
+  // Variants (visual)
+  variant: "primary" | "secondary" | "ghost" | "danger";
+  size: "sm" | "md" | "lg";
+
+  // States
+  isLoading?: boolean;
+  isDisabled?: boolean;
+
+  // Content
+  children: ReactNode;
+  leftIcon?: ReactNode;
+  rightIcon?: ReactNode;
+
+  // Behavior
+  onClick?: () => void;
+  type?: "button" | "submit" | "reset";
+}
+```
+
+### Variant Strategy
+
+```
+Base styles (always applied)
+    + Variant styles (visual appearance)
+    + Size styles (dimensions)
+    + State styles (hover, focus, disabled)
+```
+
+## Documentation Standards
+
+### Component Doc Template
+
+```markdown
+# Button
+
+Primary action element for user interactions.
+
+## Usage Guidelines
+
+- Use primary for main CTAs (1 per view)
+- Use secondary for alternative actions
+- Use ghost for tertiary/toolbar actions
+
+## Variants
+
+[Visual examples of each variant]
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+
+## Accessibility
+
+- Uses native `<button>` element
+- Focus visible by default
+- Loading state announces via aria-busy
+
+## Examples
+
+[Code snippets for common use cases]
+```
+
+## Figma ↔ Code Sync
+
+### Token Export Format
+
+```json
+{
+  "color": {
+    "primary": {
+      "value": "#3b82f6",
+      "type": "color"
+    }
+  },
+  "spacing": {
+    "4": {
+      "value": "16px",
+      "type": "spacing"
+    }
+  }
+}
+```
+
+### Sync Workflow
+
+1. Designers update tokens in Figma
+2. Export via Tokens Studio / Style Dictionary
+3. Generate CSS/JS token files
+4. Review PR with visual diff
+5. Merge and deploy
+
+## Versioning & Changelog
+
+### Semantic Versioning
+
+```
+MAJOR.MINOR.PATCH
+
+1.0.0 → 1.0.1  (patch: bug fix)
+1.0.0 → 1.1.0  (minor: new component)
+1.0.0 → 2.0.0  (major: breaking change)
+```
+
+### Breaking Changes
+
+- Removed component/prop
+- Changed prop name/type
+- Visual changes affecting layout
+- Token name changes
+
+### Changelog Format
+
+```markdown
+## [1.2.0] - 2024-01-15
+
+### Added
+
+- New `Tooltip` component
+
+### Changed
+
+- Button hover states now use scale transform
+
+### Deprecated
+
+- `Button` `loading` prop → use `isLoading`
+
+### Fixed
+
+- Modal focus trap edge case
+```
+
+## Quality Checklist
+
+### For Each Component
+
+- [ ] Follows token system (no hard-coded values)
+- [ ] All variants documented
+- [ ] Accessibility tested
+- [ ] Dark mode compatible
+- [ ] RTL tested (if applicable)
+- [ ] Unit tests for logic
+- [ ] Visual regression tests

package/.agent/skills/designer/references/frontend_design_aesthetics.md

@@ -0,0 +1,57 @@
+# Frontend Design Aesthetics — Anti-AI-Slop Guide
+
+> Source: [Anthropic Official Skills](https://github.com/anthropics/skills) (Apache 2.0)
+
+## Design Thinking
+
+Before coding, understand the context and commit to a **BOLD** aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme — brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian
+- **Constraints**: Technical requirements (framework, performance, accessibility)
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is **intentionality**, not intensity.
+
+## Anti-AI-Slop Aesthetics
+
+### Typography
+- Choose fonts that are **beautiful, unique, and interesting**
+- AVOID generic fonts: Arial, Inter, Roboto
+- Pair a distinctive display font with a refined body font
+- **NEVER** converge on common AI choices (e.g., Space Grotesk) across generations
+
+### Color & Theme
+- Commit to a cohesive aesthetic via CSS variables
+- Dominant colors with sharp accents > timid, evenly-distributed palettes
+- AVOID cliched color schemes (particularly purple gradients on white)
+
+### Motion
+- CSS-only solutions for HTML, Motion library for React
+- Focus on high-impact moments: **one well-orchestrated page load with staggered reveals** > scattered micro-interactions
+- Use scroll-triggering and hover states that surprise
+
+### Spatial Composition
+- Unexpected layouts. Asymmetry. Overlap. Diagonal flow.
+- Grid-breaking elements. Generous negative space OR controlled density.
+
+### Backgrounds & Visual Details
+- Create atmosphere and depth — never default to solid colors
+- Gradient meshes, noise textures, geometric patterns, layered transparencies
+- Dramatic shadows, decorative borders, custom cursors, grain overlays
+
+## The NEVER List
+
+❌ Overused font families (Inter, Roboto, Arial, system fonts)
+❌ Cliched color schemes (purple gradients on white backgrounds)
+❌ Predictable layouts and component patterns
+❌ Cookie-cutter design lacking context-specific character
+❌ Same design choices across different generations
+
+## The ALWAYS List
+
+✅ Match implementation complexity to the aesthetic vision
+✅ Maximalist designs → elaborate code, extensive animations
+✅ Minimalist designs → restraint, precision, subtle details
+✅ Every design should be contextually unique
+✅ Vary between light/dark themes, different fonts, different aesthetics

package/.agent/skills/designer/references/layout.md

@@ -0,0 +1,200 @@
+# Layout & Composition
+
+Expert spatial design principles for creating balanced, functional layouts.
+
+## Grid Systems
+
+### 8-Point Grid (Recommended)
+
+All spacing and sizing divisible by 8:
+
+```
+4px   - micro (border, small gaps)
+8px   - base unit
+16px  - component padding
+24px  - section gaps
+32px  - large gaps
+48px  - section spacing
+64px  - major sections
+```
+
+### Why 8-Point?
+
+- Scales cleanly (÷2, ×2)
+- Works with common screen densities (1x, 1.5x, 2x, 3x)
+- Aligns with most system fonts' baselines
+
+### Responsive Column Grids
+
+| Breakpoint            | Columns | Gutter | Margin          |
+| --------------------- | ------- | ------ | --------------- |
+| Mobile (<640px)       | 4       | 16px   | 16px            |
+| Tablet (640-1024px)   | 8       | 24px   | 32px            |
+| Desktop (1024-1440px) | 12      | 24px   | 64px            |
+| Large (>1440px)       | 12      | 32px   | auto (centered) |
+
+## Composition Principles
+
+### Visual Hierarchy
+
+1. **Size**: Larger = more important
+2. **Color**: Saturated/contrasting = attention
+3. **Position**: Top-left (LTR) = first seen
+4. **Whitespace**: Isolated = prominent
+5. **Typography**: Weight, style variations
+
+### The Rule of Thirds
+
+Divide canvas into 3×3 grid, place key elements at intersections.
+
+- Hero images: subject at intersection
+- CTAs: right-third for natural eye flow
+
+### Gestalt Principles
+
+| Principle     | Description                | Application              |
+| ------------- | -------------------------- | ------------------------ |
+| Proximity     | Close items seem related   | Group related controls   |
+| Similarity    | Similar items seem related | Consistent button styles |
+| Continuity    | Eye follows paths          | Align elements           |
+| Closure       | Mind completes shapes      | Icon design              |
+| Figure/Ground | Foreground vs background   | Cards, modals            |
+
+## Whitespace Strategy
+
+### Types of Space
+
+- **Micro**: Within components (padding, letter-spacing)
+- **Macro**: Between components/sections
+- **Negative**: Empty space that shapes perception
+
+### Breathing Room Guidelines
+
+```
+Component padding: 16-24px
+Section spacing: 48-96px
+Page margins: 16px (mobile) → 64px+ (desktop)
+```
+
+### Active vs Passive Space
+
+- **Active**: Intentionally empty, guides attention
+- **Passive**: Leftover, feels unfinished
+- Always design space, never leave leftovers
+
+## Layout Patterns
+
+### Common Page Layouts
+
+```
+┌──────────────────────────┐
+│         Header           │
+├──────────────────────────┤
+│                          │
+│          Hero            │
+│                          │
+├──────────────────────────┤
+│  Card  │  Card  │  Card  │
+├──────────────────────────┤
+│    Feature Section       │
+├──────────────────────────┤
+│         Footer           │
+└──────────────────────────┘
+```
+
+### Dashboard Layout
+
+```
+┌────────┬─────────────────┐
+│        │     Topbar      │
+│  Side  ├─────────────────┤
+│  bar   │                 │
+│        │  Main Content   │
+│        │                 │
+└────────┴─────────────────┘
+```
+
+## Responsive Strategies
+
+### Mobile-First Breakpoints
+
+```css
+/* Base: Mobile */
+.container {
+  padding: 16px;
+}
+
+/* Tablet */
+@media (min-width: 640px) {
+  .container {
+    padding: 32px;
+  }
+}
+
+/* Desktop */
+@media (min-width: 1024px) {
+  .container {
+    padding: 64px;
+    max-width: 1280px;
+  }
+}
+```
+
+### Container Queries (Modern)
+
+```css
+.card {
+  container-type: inline-size;
+}
+
+@container (min-width: 400px) {
+  .card-content {
+    flex-direction: row;
+  }
+}
+```
+
+## Advanced Techniques
+
+### CSS Grid for Complex Layouts
+
+```css
+.bento-grid {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  grid-auto-rows: 200px;
+  gap: 16px;
+}
+
+.featured {
+  grid-column: span 2;
+  grid-row: span 2;
+}
+```
+
+### Subgrid for Alignment
+
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 24px;
+}
+
+.card {
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-row: span 3; /* header, content, footer */
+}
+```
+
+## Safe Areas (Mobile)
+
+```css
+.full-bleed {
+  padding-top: env(safe-area-inset-top);
+  padding-right: env(safe-area-inset-right);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+}
+```

package/.agent/skills/designer/references/motion.md

@@ -0,0 +1,92 @@
+# Motion & Animation Design
+
+Expert guidelines for specifying purposeful, meaningful, and performant motion.
+
+**ROLE:** As a designer, your job is to **choreograph and specify** motion, not implement it. Use the provided templates to communicate your intent to the Frontend Developer.
+
+## I. Motion Design Strategy
+
+Before animating, define the **purpose** of the motion.
+
+### 1. Orientation (The "Where")
+
+Use motion to help users build a mental model of the interface.
+
+- **entering**: Elements should appear from where they were triggered.
+- **exiting**: Elements should return to their source or exit in the direction of intended flow.
+- **transitional**: Shared element transitions connect screens seamlessly.
+
+### 2. Feedback (The "What Happened")
+
+Use motion to acknowledge user interaction immediately.
+
+- **hover**: Subtle scale or lift (e.g., scale 1.0 -> 1.02).
+- **active/press**: Scale down (e.g., scale 1.0 -> 0.98).
+- **confetti/burst**: For high-value success states only.
+
+### 3. Focus (The "Look Here")
+
+Use motion to direct attention.
+
+- **shimmer**: Suggest loading or high-value content.
+- **pulse**: Gentle attention grab for notifications.
+
+## II. Functionality Specification
+
+To specify an animation, you must define **Trigger**, **Properties**, and **Timing**.
+
+**Template Location**: `../templates/design-motion-spec.md`
+**Output Location**: `docs/040-Design/Specs/`
+
+### 1. Triggers
+
+- **Load**: When the component mounts/appears.
+- **Hover**: Cursor interaction.
+- **Click/Tap**: Active interaction.
+- **Scroll**: Viewport entry or scroll-linked.
+- **State Change**: Success, Error, Loading.
+
+### 2. Properties (What changes?)
+
+Describe the specific visual change.
+
+- **Opacity**: 0% to 100%.
+- **Scale**: 0.9 to 1.0.
+- **Position**: Y+20px to Y-0px.
+- **Rotation**: 0deg to 180deg.
+
+### 3. Timing & Easing (The "Feel")
+
+Use standard easing names to communicate the feel.
+
+| Easing Name    | Description          | Use Case                                         |
+| :------------- | :------------------- | :----------------------------------------------- |
+| **Decelerate** | Start fast, end slow | **Entrances**. Natural feel for appearing items. |
+| **Accelerate** | Start slow, end fast | **Exits**. Items leaving the screen.             |
+| **Standard**   | Fast-Slow-Fast       | **Movement**. Moving from point A to B.          |
+| **Spring**     | Overshoot and settle | **Playful/High-Focus**. Attention grabbing.      |
+
+| Duration   | Scale                                     |
+| :--------- | :---------------------------------------- |
+| **Short**  | 100-200ms (Micro-interactions, Hover)     |
+| **Medium** | 250-350ms (Dialogs, Toasts, List Items)   |
+| **Long**   | 400-600ms (Page Transitions, Full Screen) |
+
+## III. Choreography Rules
+
+Specify how multiple elements move together.
+
+- **Stagger**: "Items should appear one after another with a 50ms delay."
+- **Sequence**: "Container expands FIRST (300ms), THEN content fades in (200ms)."
+- **Group**: "Avatar and Name move as a single unit."
+
+## IV. Design Handoff
+
+When a user asks for animation, **DO NOT write CSS**. Instead:
+
+1.  **Analyze** the interaction.
+2.  **Select** the appropriate parameters (Trigger, Easing, Duration).
+3.  **Generate a Motion Spec** using the template at `../templates/design-motion-spec.md`.
+4.  **Save** it to `docs/040-Design/Specs/Motion-[FeatureName].md`.
+
+This spec is the deliverable for the Frontend Developer.

package/.agent/skills/designer/references/review.md

@@ -0,0 +1,100 @@
+# UI Review & Auditing
+
+Expert guidelines for auditing UI code and ensuring production quality.
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use `read_url_content` to retrieve. The content contains full rules and output format.
+
+## Audit Decision Table
+
+Select which standards to apply:
+
+| Project Type  | Apply Standards             |
+| ------------- | --------------------------- |
+| Personal/demo | Basic review only           |
+| Commercial    | Full WIG + WCAG AA          |
+| Enterprise    | WIG + WCAG AA + performance |
+| Public/Gov    | WIG + WCAG AAA + security   |
+
+## Review Workflow
+
+1. **Determine scope**: Which files? Which standards?
+2. **Fetch guidelines**: Get latest from URL above
+3. **Load references**: `@references/accessibility.md` for a11y checks
+4. **Analyze code**: Apply all applicable rules
+5. **Report findings**: Use format below
+
+## Standard Audit Checklist
+
+These rules always apply:
+
+### Interactive States
+
+- [ ] All buttons/links have `:hover` state
+- [ ] All interactive elements have visible `:focus-visible`
+- [ ] No `outline: none` without replacement
+
+### Form Quality
+
+- [ ] Inputs have `autocomplete` attribute
+- [ ] Labels are clickable (`for` or wrapped)
+- [ ] Placeholders end with `…`
+- [ ] Errors announced to screen readers
+
+### Typography
+
+- [ ] Proper glyphs: `…` not `...`, curly quotes
+- [ ] `text-wrap: balance` on headings
+- [ ] `tabular-nums` on numeric tables
+
+### Performance
+
+- [ ] Images have explicit `width`/`height`
+- [ ] Large lists (>50) virtualized
+- [ ] No `transition: all`
+- [ ] Animations use transform/opacity only
+
+### Accessibility
+
+- [ ] Semantic HTML (buttons, links, sections)
+- [ ] Icon buttons have `aria-label`
+- [ ] Color not sole indicator
+- [ ] Contrast meets target level
+
+## Severity Levels
+
+| Level   | Symbol | When to Use                           |
+| ------- | ------ | ------------------------------------- |
+| Error   | 🔴     | Breaks functionality or accessibility |
+| Warning | 🟡     | Best practice violation               |
+| Info    | 🔵     | Suggestion for improvement            |
+
+## Output Format
+
+Group by file. Use clickable `file:line` format.
+
+```text
+## src/components/Button.tsx
+
+🔴 src/components/Button.tsx:42 - icon button missing aria-label
+🟡 src/components/Button.tsx:18 - transition: all → specify properties
+🔵 src/components/Button.tsx:25 - consider adding loading state
+
+## src/layout/Header.tsx
+
+✓ pass
+```
+
+**Rules:**
+
+- State issue + location only
+- Skip preamble
+- Explanations only if fix is non-obvious
+- End with pass/fail summary