# CLAUDE.md — SVGarden Platform
> **Project:** SVGarden — A massive, searchable bank of SVG + CSS animations with copy-ready code snippets.
> **Author:** Simon-Pierre Boucher — contact@spboucher.ai
> **Production URL:** https://www.svgarden.dev (served via ngrok from node `m3u96b`)
---
## 1. Mission
You (Claude Code) are building **SVGarden**, a static-first web platform that hosts a large, ever-growing library of SVG/CSS animations. Every animation is a self-contained snippet that visitors can preview live, customize, and copy in one click.
The platform must be:
1. **Scalable by design** — adding a new animation means adding ONE file. The gallery, search index, tags, and category pages regenerate automatically at build time.
2. **Zero-dependency for visitors** — every copied snippet must work when pasted into a blank `.html` file. No frameworks, no build step, no external assets required by the snippets themselves.
3. **Pedagogical** — every snippet ships with a short "How it works" explanation.
4. **Beautiful** — the site itself should demonstrate the craft it teaches.
---
## 2. Mandatory file header (NON-NEGOTIABLE)
**EVERY code file in this repository** — HTML, CSS, JS, config files, snippet files, build scripts, everything — MUST begin with an author header. No exceptions. If you create a file without this header, fix it immediately.
### HTML / Snippet files
```html
```
### CSS files
```css
/*
============================================================
SVGarden — https://www.svgarden.dev
Author : Simon-Pierre Boucher
Contact: contact@spboucher.ai
File : {relative/path/to/file}
Desc : {one-line description}
============================================================
*/
```
### JavaScript / Node files
```js
/**
* ============================================================
* SVGarden — https://www.svgarden.dev
* Author : Simon-Pierre Boucher
* Contact: contact@spboucher.ai
* File : {relative/path/to/file}
* Desc : {one-line description}
* ============================================================
*/
```
### Shell scripts / YAML / config
```bash
# ============================================================
# SVGarden — https://www.svgarden.dev
# Author : Simon-Pierre Boucher
# Contact: contact@spboucher.ai
# File : {relative/path/to/file}
# Desc : {one-line description}
# ============================================================
```
Additionally, the **copy-to-clipboard output** of every snippet must include the HTML-comment version of this header at the top, so attribution travels with the code.
---
## 3. Tech stack
| Layer | Choice | Rationale |
|---|---|---|
| Runtime | Node.js ≥ 20 (LTS) | Runs on node `m3u96b` |
| Framework | **Astro** (latest stable) | Static output, content collections, zero client JS by default |
| Styling | Vanilla CSS with custom properties | The site must eat its own dog food — no Tailwind for the public site |
| Syntax highlighting | **Shiki** (build-time) | Zero runtime cost |
| Search | **Fuse.js** (client-side, lazy-loaded) | Small, works on static hosting |
| Server | `astro preview` or a tiny Express static server on port **4321** | Fronted by ngrok |
| Tunnel | **ngrok** with reserved domain `www.svgarden.dev` | See §9 |
| Process manager | **pm2** | Keeps server + tunnel alive on `m3u96b` |
If Astro is unavailable or problematic on the node, fall back to a hand-rolled Node build script (`build.mjs`) that reads `snippets/**` and emits static HTML from templates. The architecture below must work either way.
---
## 4. Repository structure
```
svgarden/
├── CLAUDE.md ← this file
├── README.md
├── package.json
├── astro.config.mjs
├── ecosystem.config.cjs ← pm2 config (site + ngrok)
├── scripts/
│ ├── new-snippet.mjs ← scaffolds a new snippet file interactively
│ ├── validate-snippets.mjs ← CI check: headers, metadata, self-containment
│ └── deploy.sh ← build + pm2 restart + ngrok health check
├── src/
│ ├── layouts/Base.astro
│ ├── pages/
│ │ ├── index.astro ← gallery home (all snippets, filterable)
│ │ ├── category/[cat].astro
│ │ ├── snippet/[slug].astro ← detail page: preview + code + customizer
│ │ └── about.astro
│ ├── components/
│ │ ├── SnippetCard.astro
│ │ ├── LivePreview.astro ← sandboxed iframe preview
│ │ ├── CodeBlock.astro ← Shiki-highlighted, copy button
│ │ ├── Customizer.astro ← color/speed/size controls → live re-render
│ │ ├── SearchBar.astro
│ │ └── TagFilter.astro
│ └── styles/global.css
├── snippets/ ← THE BANK. One file = one animation.
│ ├── loaders/
│ ├── hover/
│ ├── stroke-draw/
│ ├── gauges/
│ ├── text/
│ ├── morph/
│ ├── backgrounds/
│ └── buttons/
└── public/
├── favicon.svg
└── og/ ← auto-generated OG images per snippet (stretch goal)
```
---
## 5. Snippet file format (the heart of the platform)
Every snippet is a single `.html` file inside `snippets/{category}/`. It contains a YAML-in-comment frontmatter block, followed by the raw self-contained snippet code.
```html