# Agent Skill: Vicinity Design System

## Purpose
This skill provides comprehensive guidance for AI agents working with the Vicinity Labs design system. Use this when creating, modifying, or reviewing UI components, layouts, or visual designs.

## Design Principles

### Core Tenets
- **Dark First**: All designs use dark backgrounds (#0a0a0a) as the foundation
- **Gold Accent**: Gold (#d4af37) is the primary accent for emphasis and interactive elements
- **Amber Secondary**: Amber (#f59e0b) for secondary highlights and warm contrast
- **Premium Feel**: Velvet, blueprint, and technical precision aesthetics

### Color Tokens
| Token | Value | Usage |
|-------|-------|-------|
| `--bg-root` | #0a0a0a | Page background |
| `--bg-canvas` | #111111 | Card surfaces |
| `--bg-card` | #141414 | Elevated elements |
| `--gold` | #d4af37 | Primary accent |
| `--gold-text` | #e6c86e | Gold text (higher contrast) |
| `--amber` | #f59e0b | Secondary accent |
| `--fg-primary` | #f5f5f5 | Primary text |
| `--fg-secondary` | #a1a1a1 | Secondary text |
| `--fg-tertiary` | #737373 | Muted text |
| `--border` | #262626 | Default borders |
| `--border-strong` | #404040 | Emphasized borders |

### Typography
- **Primary Font**: Inter (weights 300, 400, 500, 600)
- **Monospace**: JetBrains Mono (for code, labels, technical text)
- **Headings**: Use `font-[family-name:var(--font-primary)]` 
- **Body**: Default sans (Inter)
- **Labels/Badges**: `font-mono` (JetBrains Mono)

### Spacing & Layout
- Base unit: 4px
- Cards: padding 24px (p-6)
- Sections: gap 32px (gap-8)
- Page padding: 32px horizontal (px-8), 64px vertical (py-16)
- Max-width containers: max-w-7xl (1280px)

### Border & Elevation
- Border radius: 0 (sharp corners) for cards, `rounded-lg` (8px) for buttons
- Border color: `border-border` (#262626) default
- Hover borders: `hover:border-gold/50`
- Shadows: `shadow-gold/5` for subtle gold glow

## Component Usage Guide

### Cards
```astro
<Card class="p-6 border-l-4 border-l-gold">
  <h3 class="font-mono text-sm text-gold-text uppercase tracking-wider mb-3">Title</h3>
  <p class="text-fg-secondary">Content</p>
</Card>
```

### Buttons (Primary)
```astro
<button class="font-mono text-sm text-gold-text border border-gold px-4 py-2 hover:bg-gold/10 transition-colors">
  Action
</button>
```

### Badges
- `variant="solid"`: Gold background, dark text (for active status)
- `variant="outline"`: Gold border, gold text (for labels)
- `variant="pill"`: Rounded, minimal (for tags)

### Charts
Always use the chart components with:
- Gold (#d4af37) for primary/highlighted data
- Amber (#f59e0b) for comparison/baseline data
- Dark grey for muted series
- Always include axis labels and legends

## How to Make It Real

When implementing designs from this system:

1. **Use existing components first**: Check `src/components/` for available Astro components
2. **Follow the token system**: Always use CSS custom properties, never hardcoded colors
3. **Maintain contrast ratios**: Gold on dark passes WCAG AA; amber text at 16px+ minimum
4. **Add film grain**: Use `<FilmGrain />` component for texture on key surfaces
5. **Animate subtly**: Use `transition-colors` for hovers, `animate-pulse` for indicators
6. **Test responsive**: All layouts should work down to 375px width

## Common Patterns

### Section Header
```astro
<SectionHeader text="Section Title" variant="primary" />
```

### Navigation Cards Grid
```astro
<div class="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
  <Card>...</Card>
  <Card>...</Card>
</div>
```

### Data Display
```astro
<div class="font-[family-name:var(--font-primary)] text-3xl text-fg-primary">248%</div>
<p class="text-sm text-fg-tertiary">metric label</p>
```

## Resources
- Full component library: `/components`
- Charts documentation: `/charts`
- Design tokens: `src/styles/global.css`