Designing with AI: How to Guide Large Language Models with Custom Agent Skills

# User Interface Design Skill

## Core Principles
- Follow Material Design 3 guidelines
- Maintain WCAG 2.1 AA accessibility standards
- Apply 8pt grid system for spacing
- Use consistent 4px border radius
- Ensure 3:1 color contrast ratio

## Brand Standards

### Color Palette
- Primary: #0066FF (Brand Blue)
- Secondary: #00CC88 (Success Green)
- Neutral: #F5F5F5 (Background)
- Text: #1A1A1A (Primary), #666666 (Secondary)

### Typography
- Headings: Inter, Bold, 24-48px
- Body: Inter, Regular, 16px
- Captions: Inter, Regular, 12px

### Visual Language
- Illustrations: Minimal line art style
- Icons: Lucide React icon set
- Images: High-quality photography with 20% overlay

# Component Templates

## Button Component

<button class="btn-primary">
  <icon name="plus" size="16px" />
  <span>Primary Action</span>
</button>

<style>
.btn-primary {
  padding: 12px 24px;
  background: #0066FF;
  color: white;
  border-radius: 4px;
  display: flex;
  align-items: center;
  gap: 8px;
}
</style>

# Landing Page Design Skill

## When to Use
Use this skill when designing or reviewing landing pages for:
- Product launches
- Marketing campaigns
- Lead generation
- Event registrations

## Required Elements
Every landing page must include:
1. Hero section with value proposition
2. Social proof (testimonials, stats, logos)
3. Features/benefits section
4. Clear call-to-action
5. Trust signals (security badges, guarantees)

## Component Library
Reference components: [components/hero.md](components/hero.md)
Color schemes: [reference/colors.md](reference/colors.md)
Typography: [reference/typography.md](reference/typography.md)

# Design Principles

## Hierarchy
- Use size, weight, and color to establish visual hierarchy
- Primary headlines: 48px Inter Bold
- Secondary headlines: 32px Inter Bold
- Body text: 16px Inter Regular
- Captions: 12px Inter Regular

## Spacing
- Follow 8pt grid system: 8, 16, 24, 32, 48, 64px
- Component padding: 16px (small), 24px (medium), 32px (large)
- Section margins: 48px (mobile), 64px (tablet), 96px (desktop)

## Color Usage
- Use brand colors purposefully
- Maximum 3 colors per component
- Maintain 3:1 contrast for accessibility
- Use color to guide user attention

# Button System

## Primary Button
Use for main actions (Submit, Download, Sign Up)
- Background: #0066FF
- Text: White
- Padding: 12px 24px
- Border radius: 4px
- Hover: Darken by 10%

## Secondary Button
Use for secondary actions (Learn More, Cancel)
- Background: Transparent
- Border: 2px solid #0066FF
- Text: #0066FF
- Same padding and border radius

## Tertiary Button
Use for subtle actions (Edit, View All)
- Background: Transparent
- Text: #666666
- No border
- Hover: #1A1A1A

#!/usr/bin/env python3
"""
Validates design system compliance for components.
"""

import re
import sys

def validate_component(file_path):
    """Check component against design system rules."""
    with open(file_path, 'r') as f:
        content = f.read()

    violations = []

    # Check spacing (8pt grid)
    spacing_pattern = r'padding:\s*(\d+)px'
    spacing_matches = re.findall(spacing_pattern, content)
    for match in spacing_matches:
        if int(match) % 8 != 0:
            violations.append(f"Padding {match}px not on 8pt grid")

    # Check color contrast (simplified check)
    if 'background:' in content and 'color:' not in content:
        violations.append("Background defined without text color")

    # Check border radius
    border_pattern = r'border-radius:\s*(\d+)px'
    border_matches = re.findall(border_pattern, content)
    for match in border_matches:
        if int(match) != 4:
            violations.append(f"Border radius {match}px not standard (4px)")

    if violations:
        print(f"VIOLATIONS in {file_path}:")
        for violation in violations:
            print(f"  - {violation}")
        return False
    else:
        print(f"✓ {file_path} complies with design system")
        return True

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python validate_design.py <component.html>")
        sys.exit(1)

    file_path = sys.argv[1]
    validate_component(file_path)

#!/usr/bin/env python3
"""
Generates visual style guide from design tokens.
"""

import json

def generate_style_guide():
    """Create style guide documentation."""
    tokens = {
        "colors": {
            "primary": "#0066FF",
            "secondary": "#00CC88",
            "neutral": {
                "100": "#F5F5F5",
                "500": "#999999",
                "900": "#1A1A1A"
            }
        },
        "typography": {
            "fontFamily": "Inter",
            "sizes": {
                "xs": "12px",
                "sm": "14px",
                "md": "16px",
                "lg": "20px",
                "xl": "24px",
                "2xl": "32px",
                "3xl": "48px"
            }
        },
        "spacing": {
            "xs": "4px",
            "sm": "8px",
            "md": "16px",
            "lg": "24px",
            "xl": "32px",
            "2xl": "48px",
            "3xl": "64px"
        }
    }

    markdown = "# Design System Style Guide\n\n"

    # Colors section
    markdown += "## Colors\n\n"
    for name, value in tokens["colors"].items():
        if isinstance(value, dict):
            markdown += f"### {name.title()}\n\n"
            for shade, color in value.items():
                markdown += f"- **{shade}**: `{color}`\n"
        else:
            markdown += f"- **{name}**: `{value}`\n"
    markdown += "\n"

    # Typography section
    markdown += "## Typography\n\n"
    markdown += f"**Font Family**: {tokens['typography']['fontFamily']}\n\n"
    markdown += "**Sizes**:\n"
    for size, value in tokens["typography"]["sizes"].items():
        markdown += f"- {size}: {value}\n"
    markdown += "\n"

    # Spacing section
    markdown += "## Spacing\n\n"
    for name, value in tokens["spacing"].items():
        markdown += f"- {name}: {value}\n"

    with open('reference/style-guide.md', 'w') as f:
        f.write(markdown)

    print("✓ Style guide generated: reference/style-guide.md")

if __name__ == "__main__":
    generate_style_guide()

# UI/UX Design Skill

## Workflow
1. Understand user needs and business goals
2. Apply user-centered design principles
3. Create wireframes and prototypes
4. Conduct usability testing
5. Iterate based on feedback

## Key Principles
- Design for user needs, not business needs
- Follow Fitts's Law for interactive elements
- Apply Hick's Law for menu design
- Use progressive disclosure
- Provide clear feedback

## Accessibility Requirements
- All images have alt text
- Minimum 3:1 contrast ratio
- Keyboard navigation support
- Screen reader compatibility
- Focus indicators visible

## Documentation Structure
- User personas: [research/personas.md](research/personas.md)
- User journey maps: [research/journeys.md](research/journeys.md)
- Wireframe templates: [templates/wireframes.md](templates/wireframes.md)
- Prototype examples: [examples/prototypes.md](examples/prototypes.md)

# Brand Identity Design Skill

## Brand Components
- Logo variations (primary, secondary, icon)
- Color palette (primary, secondary, neutrals, accent)
- Typography system (headings, body, captions)
- Voice and tone guidelines
- Visual style (imagery, illustrations, icons)

## Logo Usage Rules
- Minimum size: 24px height (digital), 1 inch (print)
- Clear space: 0.5x logo height on all sides
- Backgrounds: White or brand colors only
- Don't: Stretch, rotate, drop shadow, outline

## Color Guidelines
- Primary colors: Maximum 3 colors
- Use neutrals for balance
- Color psychology considerations
- Accessibility compliance (WCAG 2.1 AA)

## Voice and Tone
- Professional yet approachable
- Confident without being arrogant
- Clear and jargon-free
- Consistent across all touchpoints

# Product Design Skill

## Product Design Process
1. Research: User interviews, market analysis
2. Define: Problem statements, success metrics
3. Ideate: Brainstorming, design studios
4. Prototype: Low-fi to high-fi iterations
5. Test: Usability testing, A/B testing
6. Launch: Monitor metrics, gather feedback

## Design Systems
- Component library with usage guidelines
- Design tokens (colors, spacing, typography)
- Interaction patterns and behaviors
- Accessibility guidelines
- Documentation and examples

## Metrics to Track
- User engagement (time on task, completion rate)
- Conversion rates (sign-ups, purchases)
- User satisfaction (NPS, CSAT)
- Task success rate
- Error rate and recovery

## Common Patterns
- Navigation: Primary, secondary, breadcrumbs
- Forms: Clear labels, validation, error handling
- Search: Filters, sorting, relevance
- Dashboards: Metrics, trends, actions
- Settings:分组，defaults, reset options

# Comprehensive Design Skill

## Capabilities
- UI/UX design for web and mobile
- Brand identity and visual systems
- Product design and prototyping
- Design system development
- User research and testing

## Tools Integration
- Reference: Figma component libraries
- Design tokens: JSON format
- Style guides: Automated generation
- Usability testing: Scripts and frameworks

## Collaboration Workflow
1. Discovery: Research and requirements gathering
2. Strategy: Define design approach and goals
3. Design: Create wireframes, mockups, prototypes
4. Test: Validate with users and stakeholders
5. Iterate: Refine based on feedback
6. Handoff: Developer handoff with specifications

---
name: responsive-design-assistant
description: "Provides responsive design expertise. Activates when user mentions: responsive, mobile-first, breakpoint, viewport, cross-device, or design for mobile/tablet/desktop."
---

## Test Case 1: Landing Page Design

**Input**: "Create a landing page for a new SaaS product"
**Expected Output**:
- Hero section with clear value prop
- Social proof elements
- Feature benefits section
- Strong call-to-action
- Responsive design considerations
- Accessibility features

## Test Case 2: Design System Component

**Input**: "Design a button component for our design system"
**Expected Output**:
- Primary, secondary, tertiary variants
- Accessibility-compliant colors
- Proper sizing and spacing
- Hover and focus states
- Usage guidelines
- Code examples

# Design Skill Development Workflow

1. Document current design process
2. Identify repetitive tasks and patterns
3. Extract design principles and standards
4. Create templates and examples
5. Build validation scripts
6. Test with real projects
7. Iterate based on feedback

# Good: Clear guidelines with flexibility

## Color Usage
Use brand colors purposefully:
- Primary: #0066FF for main actions and links
- Secondary: #00CC88 for success states and positive feedback
- Neutral: #F5F5F5 for backgrounds and #1A1A1A for text

Note: You may adjust shades for accessibility or visual balance, maintaining WCAG 2.1 AA standards.

## Button Component Examples

✓ **Good Example**: Clean, accessible primary button
```html
<button class="btn-primary">
  <span>Get Started</span>
</button>

<a href="#" style="background: #999; color: #ccc;">Click</a>

User: "Design a login form for my app"
Claude: Creates generic form with basic styling

User: "Make it match my brand colors"
Claude: "What are your brand colors?"
User: "Blue (#0066FF) and white"
Claude: Updates colors, but spacing and typography still off

User: "Fix the spacing and add proper labels"
Claude: Makes adjustments, but accessibility may be missed

User: "Design a login form for my app"
Claude: Uses Design Skill to create accessible, on-brand form with proper:
- Brand colors (already configured)
- Typography system (Inter, appropriate sizes)
- Spacing (8pt grid system)
- Accessibility (labels, focus states, contrast)
- Validation patterns

Always use 24px padding on all components.
Never use custom colors outside the brand palette.
All buttons must be exactly 48px tall.

Use 8pt grid system for consistent spacing (typically 16px, 24px, 32px).
Prefer brand colors; custom colors require approval and must maintain 3:1 contrast.
Standard button height is 48px; adjust for context while maintaining accessibility.

Design Skill: "Use the blue button for all primary actions"

Design Skill: "Use primary buttons for main actions (Submit, Download, Sign Up). Consider the user's state (first-time vs. returning) and adjust action priority accordingly."

# Design Skill generates component
# No checking if it meets standards

# Design Skill generates component
# Runs validate_design_system.py
# Flags issues: color contrast, spacing, accessibility
# Provides specific fixes

## Review Checklist

### Usage Patterns
- What design tasks is the Skill most used for?
- Where do users struggle or request clarification?
- Which components/templates are most/least used?

### Quality Assessment
- What % of outputs pass design review without changes?
- Are there consistent issues or gaps?
- How do stakeholders rate the output quality?

### Evolution Opportunities
- New design patterns to add?
- Components that should be split or merged?
- Feedback from team members?

design-system-skill-v1.0/  # Initial release
design-system-skill-v1.1/  # Added dark mode support
design-system-skill-v2.0/  # Major: New brand guidelines
design-system-skill-v2.1/  # Added mobile-specific components