@jhm1909/ag-kit 0.1.0

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

@@ -0,0 +1,172 @@
+# Accessibility Guidelines
+
+Decision table and implementation checklist for inclusive design.
+
+## When to Apply Which Standard
+
+| Project Type          | Standard               | Contrast Ratio        | Target                |
+| --------------------- | ---------------------- | --------------------- | --------------------- |
+| Personal/Hobby        | No minimum             | -                     | -                     |
+| Commercial website    | WCAG 2.1 AA            | 4.5:1 text, 3:1 UI    | Most users            |
+| Government/Public     | WCAG 2.1 AA (required) | 4.5:1 text, 3:1 UI    | Legal compliance      |
+| Enterprise SaaS       | WCAG 2.1 AA+           | 4.5:1+                | Employee productivity |
+| Healthcare/Finance    | WCAG 2.1 AAA           | 7:1 text, 4.5:1 large | Critical info access  |
+| Kiosk/Public terminal | WCAG 2.1 AAA           | 7:1+                  | Diverse environments  |
+
+## Color & Contrast
+
+### Minimum Ratios
+
+| Element                      | AA    | AAA   |
+| ---------------------------- | ----- | ----- |
+| Body text                    | 4.5:1 | 7:1   |
+| Large text (18pt+/14pt bold) | 3:1   | 4.5:1 |
+| UI components                | 3:1   | -     |
+| Focus indicators             | 3:1   | -     |
+
+### Color Independence
+
+- ❌ Never use color alone to convey meaning
+- ✅ Add icons, patterns, or text labels
+- Example: Red error + error icon + error text
+
+## Keyboard Navigation
+
+### Focus Management
+
+```css
+/* Visible focus ring */
+:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+}
+
+/* Remove default only with replacement */
+:focus {
+  outline: none;
+  box-shadow: 0 0 0 3px var(--color-focus);
+}
+```
+
+### Tab Order
+
+- Logical, follows visual order
+- No tabindex > 0 (disrupts natural order)
+- Skip links for main content
+
+### Keyboard Patterns
+
+| Component       | Keys                            |
+| --------------- | ------------------------------- |
+| Button          | Enter, Space                    |
+| Link            | Enter                           |
+| Checkbox        | Space                           |
+| Radio           | Arrows                          |
+| Select/Dropdown | Arrows, Enter, Esc              |
+| Modal           | Esc to close, trap focus inside |
+| Tabs            | Arrows between, Tab to content  |
+
+## Screen Reader Optimization
+
+### Semantic HTML First
+
+```html
+<!-- Bad -->
+<div class="button" onclick="...">Click</div>
+
+<!-- Good -->
+<button type="button">Click</button>
+```
+
+### ARIA When Needed
+
+```html
+<!-- Icon-only button -->
+<button aria-label="Close dialog">
+  <svg>...</svg>
+</button>
+
+<!-- Live region for updates -->
+<div aria-live="polite" aria-atomic="true">3 items added to cart</div>
+
+<!-- Expandable sections -->
+<button aria-expanded="false" aria-controls="panel1">Show details</button>
+<div id="panel1" hidden>...</div>
+```
+
+### Content Order
+
+- Visual order = DOM order
+- Hidden decorative images: `aria-hidden="true"` or `alt=""`
+- Meaningful images: descriptive `alt`
+
+## Motion & Animation
+
+### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### Safe Animation Types
+
+- ✅ Opacity fades
+- ✅ Small scale changes
+- ⚠️ Limit parallax/vestibular motion
+- ❌ Flashing (3+ times/sec)
+
+## Forms
+
+### Required Labels
+
+```html
+<label for="email">Email address</label>
+<input
+  id="email"
+  type="email"
+  name="email"
+  autocomplete="email"
+  aria-required="true"
+  aria-describedby="email-hint email-error"
+/>
+<p id="email-hint">We'll never share your email</p>
+<p id="email-error" role="alert">Please enter valid email</p>
+```
+
+### Error Handling
+
+- Announce errors on submit (focus first error)
+- Inline errors near the field
+- Clear error states when corrected
+
+## Testing Checklist
+
+### Automated
+
+- [ ] axe DevTools browser extension
+- [ ] Lighthouse accessibility audit
+- [ ] eslint-plugin-jsx-a11y (React)
+
+### Manual
+
+- [ ] Tab through entire page
+- [ ] Use screen reader (VoiceOver/NVDA)
+- [ ] Zoom to 200%
+- [ ] Test with high contrast mode
+- [ ] Check without CSS loaded
+
+### Screen Readers to Test
+
+| Platform | Reader               |
+| -------- | -------------------- |
+| macOS    | VoiceOver (built-in) |
+| Windows  | NVDA (free), JAWS    |
+| iOS      | VoiceOver (built-in) |
+| Android  | TalkBack             |

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

@@ -0,0 +1,88 @@
+# Branding & Identity Development
+
+Expert guidelines for creating distinctive, memorable brand identities.
+
+## Brand Discovery Process
+
+### 1. Brand Essence Questions
+
+Before any visual work, answer:
+
+- **Purpose**: Why does this brand exist? What problem does it solve?
+- **Personality**: If this brand were a person, how would they speak/act?
+- **Positioning**: What makes this brand different from competitors?
+- **Promise**: What can users always expect from this brand?
+
+### 2. Target Audience Mapping
+
+| Dimension      | Primary | Secondary |
+| -------------- | ------- | --------- |
+| Demographics   |         |           |
+| Psychographics |         |           |
+| Pain points    |         |           |
+| Aspirations    |         |           |
+
+## Visual Identity System
+
+### Logo Design Principles
+
+1. **Simplicity**: Must work at 16px favicon and billboard sizes
+2. **Memorability**: One unique element that sticks
+3. **Timelessness**: Avoid trendy elements that date quickly
+4. **Versatility**: Works in mono, color, dark/light backgrounds
+5. **Appropriateness**: Matches brand personality
+
+### Logo Variations Required
+
+- Primary (full logo)
+- Secondary (simplified)
+- Icon/favicon (minimal)
+- Wordmark only
+- Mono versions (black, white)
+
+### Brand Color Strategy
+
+| Type      | Count | Purpose                       |
+| --------- | ----- | ----------------------------- |
+| Primary   | 1-2   | Main brand recognition        |
+| Secondary | 2-3   | Support & variety             |
+| Accent    | 1     | CTAs & highlights             |
+| Neutral   | 3-5   | Text, backgrounds             |
+| Semantic  | 4     | Success, error, warning, info |
+
+## Brand Voice & Tone
+
+### Voice Attributes Matrix
+
+| Attribute | We Are | We Are Not |
+| --------- | ------ | ---------- |
+| Tone 1    |        |            |
+| Tone 2    |        |            |
+| Tone 3    |        |            |
+
+### Messaging Hierarchy
+
+1. **Tagline**: 3-7 words, core promise
+2. **Value propositions**: 3 key benefits
+3. **Elevator pitch**: 30-second explanation
+4. **Full story**: Origin, mission, vision
+
+## Brand Consistency Checklist
+
+- [ ] Logo usage rules documented
+- [ ] Color palette with hex/RGB/HSL codes
+- [ ] Typography system defined
+- [ ] Photography/illustration style guide
+- [ ] Voice & tone guidelines
+- [ ] Do's and Don'ts examples
+- [ ] Application templates (social, email, etc.)
+
+## Integration with UI
+
+When applying brand to UI:
+
+1. **Primary color**: Headers, primary CTAs
+2. **Secondary colors**: Supporting elements
+3. **Accent**: Interactive highlights, notifications
+4. **Typography**: Match brand fonts or select complementary web-safe alternatives
+5. **Imagery**: Consistent with brand photography style

package/.agent/skills/designer/references/color-theory.md

@@ -0,0 +1,139 @@
+# Color Theory for UI Design
+
+Expert guide to color selection, harmony, and application in digital interfaces.
+
+## Color Psychology
+
+### Emotional Associations by Hue
+
+| Color  | Positive                        | Negative             | Best For                        |
+| ------ | ------------------------------- | -------------------- | ------------------------------- |
+| Red    | Energy, passion, urgency        | Danger, aggression   | CTAs, sales, alerts             |
+| Orange | Creativity, warmth, fun         | Caution, cheap       | E-commerce, entertainment       |
+| Yellow | Optimism, clarity, warmth       | Anxiety, cowardice   | Highlights, warnings            |
+| Green  | Growth, health, success         | Envy, inexperience   | Finance, wellness, confirmation |
+| Blue   | Trust, calm, professional       | Cold, sadness        | Corporate, tech, healthcare     |
+| Purple | Luxury, creativity, wisdom      | Decadence, moodiness | Beauty, premium brands          |
+| Pink   | Playful, romantic, feminine     | Immature, weak       | Fashion, beauty, youth          |
+| Black  | Elegance, power, sophistication | Death, evil          | Luxury, fashion                 |
+| White  | Clean, simple, pure             | Sterile, empty       | Minimalist, healthcare          |
+| Gray   | Neutral, balanced, mature       | Dull, indecisive     | Professional, backgrounds       |
+
+### Cultural Considerations
+
+| Culture     | Red              | White    | Yellow    | Green             |
+| ----------- | ---------------- | -------- | --------- | ----------------- |
+| Western     | Love, danger     | Purity   | Happiness | Nature            |
+| Eastern     | Luck, prosperity | Mourning | Royalty   | Infidelity (some) |
+| Middle East | Danger           | Purity   | Joy       | Fertility         |
+
+## Color Harmony Schemes
+
+### 1. Monochromatic
+
+- **How**: Single hue, vary saturation/lightness
+- **Use**: Elegant, cohesive, easy to implement
+- **Tip**: Add one accent color for contrast
+
+### 2. Analogous
+
+- **How**: 3-5 adjacent colors on wheel
+- **Use**: Harmonious, natural feel
+- **Tip**: Pick one dominant, others as support
+
+### 3. Complementary
+
+- **How**: Opposite colors on wheel
+- **Use**: High contrast, vibrant
+- **Tip**: Use 70-30 ratio, never 50-50
+
+### 4. Split-Complementary
+
+- **How**: Base + two adjacents to its complement
+- **Use**: Contrast with less tension
+- **Tip**: Great for beginners
+
+### 5. Triadic
+
+- **How**: Three evenly spaced colors
+- **Use**: Vibrant, balanced
+- **Tip**: Let one dominate, two accent
+
+### 6. Tetradic (Rectangle)
+
+- **How**: Two complementary pairs
+- **Use**: Rich, varied palette
+- **Tip**: Most complex, requires careful balance
+
+## Palette Generation Workflow
+
+1. **Start with brand meaning** → Select primary hue
+2. **Choose harmony type** → Generate base palette
+3. **Add neutrals** → Gray scale from tinted primary
+4. **Define semantic colors** → Success, error, warning, info
+5. **Create shades** → 9-11 steps (50-900) per color
+6. **Test contrast** → WCAG AA minimum
+
+## Color Scale Generation
+
+```
+color-50:  lightest (backgrounds)
+color-100: very light
+color-200: light
+color-300: light-medium
+color-400: medium-light
+color-500: base (primary shade)
+color-600: medium-dark
+color-700: dark
+color-800: very dark
+color-900: darkest (text)
+color-950: near black
+```
+
+## Contrast Requirements (WCAG)
+
+| Level | Normal Text | Large Text | UI Components |
+| ----- | ----------- | ---------- | ------------- |
+| AA    | 4.5:1       | 3:1        | 3:1           |
+| AAA   | 7:1         | 4.5:1      | Not defined   |
+
+### Tools for Checking
+
+- WebAIM Contrast Checker
+- Stark (Figma plugin)
+- axe DevTools
+
+## Dark Mode Strategy
+
+### Approach 1: Invert Lightness
+
+- Swap 50↔900, 100↔800, etc.
+- Primary hue stays, lightness inverts
+
+### Approach 2: Semantic Tokens
+
+```css
+--color-surface: light → dark --color-on-surface: dark → light
+  --color-primary: adjust saturation + 10%;
+```
+
+### Dark Mode Do's & Don'ts
+
+- ✅ Reduce saturation slightly (colors feel brighter on dark)
+- ✅ Use elevation via subtle lightness increase
+- ✅ Test in actual dark environment
+- ❌ Pure black (#000) backgrounds (use #121212+)
+- ❌ Same colors as light mode (adjust for contrast)
+
+## CSS Implementation
+
+```css
+:root {
+  color-scheme: light dark;
+
+  /* Semantic color tokens */
+  --color-surface: light-dark(#fff, #1a1a1a);
+  --color-on-surface: light-dark(#1a1a1a, #f5f5f5);
+  --color-primary: light-dark(#2563eb, #60a5fa);
+}
+```

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

@@ -0,0 +1,118 @@
+# UI/UX Creation Guidelines
+
+Expert guide for creating distinctive, production-grade interfaces.
+
+## Design Thinking Process
+
+### Phase 1: Discovery
+
+Before any visual work:
+
+1. **Purpose**: What problem does this solve?
+2. **Audience**: Who uses this? What do they expect?
+3. **Context**: Where is it used? Device, environment, frequency?
+4. **Competition**: What exists? How to differentiate?
+
+### Phase 2: Aesthetic Direction
+
+Choose ONE strong direction:
+
+| Direction              | Characteristics                                | Best For                 |
+| ---------------------- | ---------------------------------------------- | ------------------------ |
+| Brutally Minimal       | White space, system fonts, zero decoration     | Tools, productivity      |
+| Maximalist             | Dense info, layered elements, rich color       | Dashboards, media        |
+| Retro-Futuristic       | Neon, scanlines, tech-noir                     | Gaming, creative         |
+| Organic Natural        | Earth tones, flowing shapes, textures          | Wellness, sustainability |
+| Luxury Refined         | Black/gold, thin type, generous space          | Premium products         |
+| Playful Toy-like       | Bright colors, rounded shapes, bouncy motion   | Kids, casual apps        |
+| Editorial Magazine     | Strong grid, bold headlines, photo-driven      | Content, portfolios      |
+| Brutalist Raw          | Mono fonts, harsh contrast, visible structure  | Art, experimental        |
+| Art Deco Geometric     | Gold accents, symmetric patterns, elegant type | Events, luxury           |
+| Soft Pastel            | Muted tones, gentle gradients, light feel      | Lifestyle, baby          |
+| Industrial Utilitarian | Gray, exposed grid, functional focus           | B2B, enterprise          |
+
+**Pick one. Commit. Execute with precision.**
+
+### Phase 3: Brainstorming
+
+#### Moodboard Elements
+
+- 5-10 reference images (from Dribbble, Awwwards, Behance)
+- 3 font candidates
+- Color palette draft
+- Key interaction moments
+
+#### "One Thing" Exercise
+
+Complete this sentence:
+
+> "When users see this, they will remember **\*\***\_\_\_**\*\***"
+
+Make that ONE thing unforgettable.
+
+## Implementation Excellence
+
+### Typography Execution
+
+```css
+/* Load reference: @references/typography.md */
+```
+
+- Display font for impact
+- Body font for readability
+- Proper text-wrap, font-features
+- Responsive sizing
+
+### Color Execution
+
+```css
+/* Load reference: @references/color-theory.md */
+```
+
+- Brand-aligned palette
+- Semantic colors defined
+- Dark mode prepared
+- Contrast verified
+
+### Motion Execution
+
+```css
+/* Load reference: @references/motion.md */
+```
+
+- **Define Intent**: Why is this moving? (Orientation/Feedback)
+- **Use Template**: Create a spec using `../templates/design-motion-spec.md`
+- **Spec Output**: Save to `docs/040-Design/Specs/`
+- **No Direct Code**: Leave implementation to `frontend-developer`
+
+### Layout Execution
+
+```css
+/* Load reference: @references/layout.md */
+```
+
+- Grid system applied
+- Spacing consistent (8pt)
+- Responsive breakpoints
+- Safe areas respected
+
+## Quality Checklist
+
+Before deliverySure:
+
+- [ ] Aesthetic direction is clear and committed
+- [ ] Typography pairs well and is readable
+- [ ] Color palette is harmonious and accessible
+- [ ] Motion is purposeful, not gratuitous
+- [ ] Layout is responsive and consistent
+- [ ] "One thing" is memorable
+- [ ] No generic patterns (default gradients, template cards)
+
+## Handoff to Development
+
+When integration with `frontend-developer`:
+
+1. Design tokens documented
+2. Component variants defined
+3. Interaction states specified
+4. Edge cases considered