# Agent Skill: Component Implementation

## Purpose
This skill guides AI agents in implementing new components that integrate seamlessly with the Vicinity Labs design system.

## Component Structure Template

### Astro Component Template
```astro
---
import FilmGrain from "./patterns/FilmGrain.astro";

interface Props {
  // Required props
  title: string;
  
  // Optional props with defaults
  variant?: "default" | "primary" | "outline";
  size?: "sm" | "md" | "lg";
  class?: string;
}

const { 
  title, 
  variant = "default", 
  size = "md",
  class: className = "" 
} = Astro.props;

// Variant-based classes
const variantClasses = {
  default: "border-border bg-bg-card",
  primary: "border-gold/50 bg-gold/5",
  outline: "border-border bg-transparent"
};

const sizeClasses = {
  sm: "p-4 gap-2",
  md: "p-6 gap-4", 
  lg: "p-8 gap-6"
};
---

<div class:list={[
  "relative flex flex-col rounded-none overflow-hidden",
  variantClasses[variant],
  sizeClasses[size],
  className
]}>
  <FilmGrain opacity={0.06} blend="overlay" />
  <h3 class="font-[family-name:var(--font-primary)] text-xl text-fg-primary">
    {title}
  </h3>
  <div class="text-fg-secondary text-sm">
    <slot />
  </div>
</div>
```

## Design System Integration Checklist

### Visual
- [ ] Uses design tokens (CSS custom properties)
- [ ] FilmGrain overlay for texture
- [ ] Proper contrast ratios (WCAG AA minimum)
- [ ] Consistent border treatment
- [ ] Proper spacing using 4px grid

### Typography
- [ ] Headlines: `font-[family-name:var(--font-primary)]`
- [ ] Body: default sans (Inter)
- [ ] Labels/Technical: `font-mono` (JetBrains Mono)
- [ ] Text colors: `text-fg-primary`, `text-fg-secondary`, `text-fg-tertiary`

### Interaction
- [ ] Hover states with `hover:` Tailwind classes
- [ ] Focus states for accessibility
- [ ] Transitions: `transition-colors` minimum
- [ ] Cursor states where appropriate

### Accessibility
- [ ] ARIA labels for interactive elements
- [ ] Semantic HTML structure
- [ ] Keyboard navigation support
- [ ] Screen reader considerations

## Common Component Patterns

### With Icon
```astro
---
interface Props {
  title: string;
  icon?: string;
}
const { title, icon } = Astro.props;
---

<div class="flex items-center gap-3">
  {icon && (
    <div class="w-10 h-10 rounded-full bg-gold/10 flex items-center justify-center">
      <svg class="w-5 h-5 text-gold">...</svg>
    </div>
  )}
  <span class="font-[family-name:var(--font-primary)] text-lg text-fg-primary">{title}</span>
</div>
```

### With Slot for Custom Content
```astro
<div class="card-content">
  <slot name="header" />
  <div class="card-body">
    <slot />
  </div>
  <slot name="footer" />
</div>
```

### Data Display
```astro
<div class="data-display">
  <span class="font-mono text-xs text-gold-text uppercase">{label}</span>
  <p class="font-[family-name:var(--font-primary)] text-3xl text-fg-primary mt-1">{value}</p>
  {subtitle && <p class="text-sm text-fg-tertiary">{subtitle}</p>}
</div>
```

## Color Usage Guide

### Backgrounds
- Page/Root: `--bg-root` (#0a0a0a)
- Canvas/Surfaces: `--bg-canvas` (#111111)
- Cards/Elevated: `--bg-card` (#141414)

### Accents
- Primary emphasis: `--gold` (#d4af37) - borders, icons, highlights
- Text emphasis: `--gold-text` (#e6c86e) - labels, accents
- Secondary: `--amber` (#f59e0b) - comparison, warm contrast

### Text
- Primary: `--fg-primary` (#f5f5f5) - headings, important text
- Secondary: `--fg-secondary` (#a1a1a1) - body text
- Tertiary: `--fg-tertiary` (#737373) - captions, metadata

### Borders
- Default: `--border` (#262626)
- Strong: `--border-strong` (#404040)
- Accent: `border-gold/30` or `border-gold/50`

## Spacing Scale

| Token | Value | Usage |
|-------|-------|-------|
| 1 | 4px | Minimal spacing |
| 2 | 8px | Tight spacing |
| 3 | 12px | Compact padding |
| 4 | 16px | Default gap |
| 6 | 24px | Card padding |
| 8 | 32px | Section gaps |
| 12 | 48px | Large sections |
| 16 | 64px | Page sections |

## File Naming Conventions

- PascalCase for component files: `MyComponent.astro`
- Descriptive names: `ProgressBar.astro`, `NetworkGraph.astro`
- Group related components in subdirectories: `components/charts/`, `components/patterns/`

## Testing New Components

1. **Visual test**: Add to `/components` page for review
2. **Dark mode only**: System is dark-first, verify on dark backgrounds
3. **Responsive**: Test at 375px, 768px, 1440px breakpoints
4. **Content stress**: Test with min/max content lengths
5. **Interaction**: Verify hover, focus, and active states

## How to Make It Real

When implementing new components:

1. **Copy the template**: Start with the Astro component template above
2. **Define Props interface**: All props must be typed
3. **Use existing patterns**: Reference similar components for consistency
4. **Add FilmGrain**: Texture is part of the brand
5. **Export from index**: Add to `src/components/` directory
6. **Document on Components page**: Import and showcase in `pages/components.astro`

## Resources
- Existing components: `src/components/`
- Design tokens: `src/styles/global.css`
- Example implementations: See Card, Badge, ProgressBar