# Implementation Guide for 561 Website Designs

## Overview

This document describes the workflow and standards for implementing the 561 website designs that have been created in the Design phase. Two reference implementations (`hangul.day` and `hil.st`) have been completed as templates.

## Quick Start

### File Structure for Each Site
```
/sites/{domain}-v1/
├── DESIGN.md          # Design specifications (already created)
├── index.html         # Generated HTML
├── style.css          # Generated CSS
└── script.js          # Generated JavaScript (if needed for interactivity)
```

### Minimum Viable Implementation

Each implementation requires:

1. **index.html** (semantic HTML, ~200-300 lines)
   - Document structure matching design layout
   - Semantic elements (section, article, header, footer)
   - Proper heading hierarchy (h1, h2, h3)
   - Responsive meta tags
   - Font preconnects

2. **style.css** (complete styling, ~400-600 lines)
   - CSS custom properties for colors
   - Grid/flex layout system
   - Typography scale
   - Animations and transitions
   - Responsive breakpoints (desktop, tablet, mobile)
   - Print and accessibility styles

3. **script.js** (if design requires interactivity)
   - Scroll effects
   - Animation triggers
   - User interactions
   - Performance optimization

## Design Pattern Categories

The 561 designs fall into these layout patterns (with approximate counts):

### High-Frequency Patterns (>50 sites each)
- **Stacked Sections** (95 sites) — Full-viewport sections, content stacks vertically
  - Examples: `hangul.day`, `historical.quest`, `diplomatic.bar`
  - Key features: Scroll-triggered animations, section transitions, viewport-height containers

- **Card Grid** (78 sites) — Responsive grid of cards with hover effects
  - Examples: `haskell.quest`, `bada.day`, `charter.quest`
  - Key features: CSS Grid, card elevation on hover, image/icon placeholders

- **Single Column** (65 sites) — Narrow column, full-bleed sections
  - Examples: `hanun.ai`, `graphers.dev`, `chloengine.com`
  - Key features: max-width container, generous margins, clear reading flow

- **Horizontal Scroll** (42 sites) — Sections scroll horizontally as user scrolls down
  - Examples: `diplomatic.club`, `paradox.dev`
  - Key features: Transform on scroll, overflow-x handling

### Medium-Frequency Patterns (20-50 sites)
- **Split Screen** (38 sites) — Left/right content layout
- **Bento Box** (32 sites) — Irregular grid layout
- **F-Pattern** (28 sites) — Left-focused with right decoration (like `hil.st`)
- **Centered Spotlight** (25 sites) — Content centered, decorative elements around

### Low-Frequency Patterns (<20 sites)
- **Masonry** (15 sites) — Pinterest-style layout
- **Interactive Map** (8 sites) — Geo/network visualization
- **Custom Unique** (5 sites) — One-off layouts

## Implementation Workflow

### Phase 1: Pattern Template Development
Create reusable CSS/JS template for each high-frequency pattern.

**For Stacked Sections pattern:**
```css
:root {
    --section-height: 100vh;
    --max-width: 800px;
    --gutter: 24px;
}

section {
    min-height: var(--section-height);
    display: grid;
    place-items: center;
    padding: 4rem var(--gutter);
}

section:nth-child(odd) {
    background-color: var(--light-bg);
    color: var(--dark-text);
}

section:nth-child(even) {
    background-color: var(--dark-bg);
    color: var(--light-text);
}
```

**For Card Grid pattern:**
```css
.grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 2rem;
    max-width: var(--max-width);
}

.card {
    aspect-ratio: 1;
    border-radius: 4px;
    overflow: hidden;
    transition: all 0.3s ease;
}

.card:hover {
    transform: translateY(-8px);
    box-shadow: 0 16px 32px rgba(0, 0, 0, 0.2);
}
```

### Phase 2: Content Generation
For each design:

1. **Extract key information from DESIGN.md:**
   ```
   - Aesthetics: [style name]
   - Layout: [pattern name]
   - Typography: [font choices + sizes]
   - Color Palette: [color variables]
   - Key Animations: [effects to implement]
   ```

2. **Select matching template** based on layout pattern

3. **Customize template with design-specific values:**
   - Color palette
   - Typography
   - Animations
   - Content structure

4. **Generate HTML structure** from template + content

### Phase 3: Enhancement
Add design-unique features:
- Custom animations
- Interactive elements
- Data visualizations
- Decorative SVG elements

## Color System Template

Every CSS file should use a color system following this pattern:

```css
:root {
    /* Primary colors */
    --color-bg-primary: #F5EDE0;
    --color-bg-secondary: #3B0A1A;
    --color-text-primary: #1C1216;
    --color-text-secondary: #8C7D75;

    /* Accent colors */
    --color-accent-1: #D4728C;
    --color-accent-2: #8B6BAE;
    --color-accent-3: #5AA4A0;

    /* Semantic colors */
    --color-success: #4CAF50;
    --color-warning: #FF9800;
    --color-error: #F44336;
}
```

## Typography System Template

Every site should have a consistent typography scale:

```css
:root {
    --font-display: 'Cormorant Garamond', serif;
    --font-body: 'Lora', serif;
    --font-code: 'JetBrains Mono', monospace;

    --font-size-h1: clamp(2rem, 6vw, 4rem);
    --font-size-h2: clamp(1.5rem, 4vw, 2.5rem);
    --font-size-body: clamp(1rem, 1.5vw, 1.2rem);

    --line-height-tight: 1.1;
    --line-height-normal: 1.6;
    --line-height-loose: 1.9;
}

h1 {
    font-family: var(--font-display);
    font-size: var(--font-size-h1);
    line-height: var(--line-height-tight);
}

body {
    font-family: var(--font-body);
    font-size: var(--font-size-body);
    line-height: var(--line-height-normal);
}
```

## Responsive Design Standards

All implementations must support:

- **Desktop** (1440px+) — Full design as specified
- **Tablet** (768px-1024px) — Adjusted layouts, single column where needed
- **Mobile** (320px-768px) — Optimized for small screens

```css
/* Mobile First Approach */
@media (min-width: 768px) {
    /* Tablet adjustments */
}

@media (min-width: 1440px) {
    /* Desktop optimizations */
}
```

## Performance Requirements

Every implementation must:

1. **Load in <3 seconds** on 4G (Core Web Vitals)
2. **Optimize fonts:**
   - Use `font-display: swap;`
   - Preconnect to Google Fonts
   - Limit to 2-3 font families max
3. **Minimize JavaScript:**
   - Use vanilla JS, avoid frameworks
   - Defer non-critical JS
   - Use `passive: true` on scroll listeners
4. **Optimize images:**
   - No raster images (use CSS/SVG)
   - If images needed, use WebP + fallback
   - Lazy load below the fold
5. **Use CSS custom properties** for dynamic values

## Accessibility Standards

Every implementation must:

1. **Meet WCAG 2.1 AA minimum:**
   - Color contrast >= 4.5:1 for text
   - Keyboard navigable
   - Screen reader friendly
   - Focus indicators visible

2. **Support prefers-reduced-motion:**
   ```css
   @media (prefers-reduced-motion: reduce) {
       * {
           animation-duration: 0.01ms !important;
           transition-duration: 0.01ms !important;
       }
   }
   ```

3. **Use semantic HTML:**
   - Proper heading hierarchy
   - ARIA labels where needed
   - Alternative text for decorative SVGs

4. **Focus management:**
   ```css
   :focus-visible {
       outline: 2px solid var(--color-accent);
       outline-offset: 2px;
   }
   ```

## Animation Guidelines

Animations should:

1. **Have purpose** — Support UX, not distract
2. **Be performant** — Use `transform` and `opacity` only
3. **Respect user preferences:**
   ```css
   @media (prefers-reduced-motion: reduce) {
       /* Disable animations */
   }
   ```
4. **Use CSS when possible** — Only JavaScript for complex interactions
5. **Duration guidelines:**
   - Entrance animations: 0.3s - 0.6s
   - Hover effects: 0.2s - 0.3s
   - Scroll triggered: 0.4s - 1s
   - Page transitions: 0.6s - 1.2s

## Testing Checklist

Before marking a site as complete:

- [ ] **Visual** — Design specs match implementation
- [ ] **Responsive** — Works on mobile, tablet, desktop
- [ ] **Performance** — Loads in <3s on 4G
- [ ] **Accessibility** — WCAG 2.1 AA compliant
- [ ] **Interactions** — All animations/clicks work
- [ ] **Cross-browser** — Chrome, Firefox, Safari, Edge
- [ ] **Print** — Prints reasonably without CSS

## Batch Implementation Workflow

For implementing multiple sites efficiently:

1. **Group sites by pattern** (using `design_pattern` field from Batch_001.md)
2. **Create pattern template** with variables
3. **For each site:**
   - Copy template
   - Extract colors from DESIGN.md
   - Add content/structure
   - Customize animations
   - Test responsive/performance
4. **Track progress** in REGISTRY.md (update status to 'I' for implemented)

## Reference Implementations

Two complete implementations are available as templates:

### hangul.day
- **Pattern:** Stacked Sections
- **Aesthetic:** Holographic calm
- **Key Techniques:** Gradient text, CSS texture, grid overlay, section animations
- **Interactivity:** Scroll progress indicator, underline animations
- **Files:**
  - `/sites/hangul.day-v1/index.html` (~280 lines)
  - `/sites/hangul.day-v1/style.css` (~650 lines)
  - `/sites/hangul.day-v1/script.js` (~200 lines)

### hil.st
- **Pattern:** F-Pattern with Signal/Noise Bands
- **Aesthetic:** Glitch digital art
- **Key Techniques:** CRT scan lines, chromatic aberration, circuit motifs, glitch animations
- **Interactivity:** Scroll-triggered tuning effect, frequency meters, energy indicators
- **Files:**
  - `/sites/hil.st-v1/index.html` (~200 lines)
  - `/sites/hil.st-v1/style.css` (~550 lines)
  - `/sites/hil.st-v1/script.js` (~250 lines)

## Next Steps

1. **Analyze design patterns** across 561 designs (Task #23)
2. **Create template CSS/JS** for 5 most common patterns
3. **Group sites** by pattern
4. **Batch implement** sites in groups of 10-20
5. **Automate generation** of structure where possible
6. **QA and refinement** for quality consistency

## Questions & Support

- Refer to `DESIGN.md` for each site's complete specification
- Check `Batch_001.md` for planned seeds/styles
- Review reference implementations for pattern examples
- Consult this guide for standards and templates