# thesvg.org - The Open SVG Brand Library

## Vision

The definitive open-source SVG brand library. No gatekeeping. Every brand deserves a place.

## Domain

thesvg.org (standalone OSS project)

## Tech Stack

- Next.js 15 (App Router, SSG where possible)
- Tailwind CSS v4 + shadcn/ui
- Fuse.js (client-side search)
- Lucide React (UI icons only)
- Vercel (hosting)

## Repo

github.com/thegdsks/thesvg

## Data Sources (internal, not user-facing)

| Source | Count | License | What we extract |
|--------|-------|---------|-----------------|
| simple-icons | 3,411 mono SVGs | CC0 | Mono variants, hex colors, aliases |
| svgl | 967 SVGs (595 entries) | MIT | Color/light/dark variants, wordmarks, categories |
| lobe-icons | 286 icon sets | MIT | Color variants from JSX, gradients |

All legally redistributable. We merge, deduplicate, and present as our own curated collection.

## Unified Icon Schema

```typescript
interface IconEntry {
  slug: string;              // primary key, kebab-case
  title: string;             // display name
  aliases: string[];         // alt names
  hex: string;               // brand color (no #)
  categories: string[];      // tags
  variants: {
    default: string;         // always present
    light?: string;
    dark?: string;
    mono?: string;
    wordmark?: string;
    wordmarkLight?: string;
    wordmarkDark?: string;
  };
  license: string;           // CC0-1.0 or MIT
  url?: string;              // brand website
  guidelines?: string;       // brand guidelines URL
}
```

## Project Structure

```
thesvg/
  public/icons/{slug}/       -- SVG files
  src/
    app/
      page.tsx               -- Homepage (hero + search + grid)
      icon/[slug]/page.tsx   -- Icon detail (SSG)
      submit/page.tsx        -- Submission guide
      api/icons/route.ts     -- REST API
      api/icons/[slug]/route.ts
    components/
      icons/                 -- Grid, card, detail, copy
      search/                -- Command-K search
      filters/               -- Category pills
    lib/
      icons.ts               -- Load/query icons.json
      search.ts              -- Fuse.js setup
      copy-formats.ts        -- SVG/JSX/Vue/CDN formatters
    data/
      icons.json             -- Generated by migration
  scripts/
    migrate.ts               -- Merge repos into unified format
    validate-icon.ts         -- Validate submissions
  docs-local/                -- Internal planning (not shipped)
  CONTRIBUTING.md
```

## Implementation Sessions

### Session 1: Foundation + Data Migration
- Scaffold Next.js app
- Write migration script (merge 3 repos)
- Run migration, populate data

### Session 2: Core UI
- Layout, header, dark theme
- Homepage hero with stats
- Category pills, icon grid
- Fuse.js search with Cmd+K

### Session 3: Detail + Copy
- Icon detail dialog (variant tabs, preview)
- Copy buttons (SVG, JSX, Vue, CDN)
- Detail page /icon/[slug] (SSG, SEO)

### Session 4: API + Polish
- REST API routes
- Submit page
- Footer, final polish

### Session 5: Ship
- CONTRIBUTING.md + CI
- Deploy to Vercel
- README with badges
- Push to GitHub

## Community Submissions

No gatekeeping. Fork, add SVGs + JSON entry, run validate, open PR.
CI auto-validates: valid XML, no scripts, under 10KB.

## Performance

- Use <img> tags (not inline SVG) for 4,600+ icons
- content-visibility: auto, lazy loading
- icons.json loaded at build time for SSG
- Fuse.js client-side index
- Vercel CDN with immutable cache headers