#CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

#Project Overview

Realm is the visual exploration portal for cytrogen.icu. It replaces the root domain's previous blog with a Castlevania-inspired territory map. The blog lives at blog.cytrogen.icu.

Design language: Deep cold tones (oklch blues), high-saturation orange as the sole accent, flat geometry, no strokes, no gradients, large color blocks.

Tech stack: Pure HTML + CSS. Zero JavaScript. All SVG is inline. No build tools, no bundler, no framework.

#Deployment

Push-to-deploy via bare repo on VPS (accessible as ssh vps-user):

git push origin main

The post-receive hook at ~/repos/realm.git/hooks/post-receive performs:

1. Checkout to temp dir
2. rsync to /var/www/realm (excludes .git, caddy/, CLAUDE.md)
3. Push to local Sourcehut instance (ssh://git@localhost:22222/~cytrogen/realm)

Caddy config lives at /etc/caddy/Caddyfile on the VPS (backup at ~/vps-deploy/Caddyfile). Editing requires sudo. The caddy/ directory in this repo contains reference snippets only.

#VPS Infrastructure

Blog deploys via ~/repos/blog.git → builds Hexo → /var/www/blog.cytrogen.icu → pushes to Sourcehut (blog-local + blog-public).

#Architecture

#CSS (css/realm.css)

Single stylesheet using @layer for cascade control:

@layer reset, tokens, base, layout, components, utilities;

• tokens: oklch color variables, spacing, typography scales, motion durations on :root
• components: SVG fill classes (.svg-icon, .svg-interactive), navigation, panels
• Typed @property declarations at file top enable smooth color transitions on SVG fills
• prefers-reduced-motion kills all transition durations globally

Colors use oklch with relative color syntax (oklch(from var(--accent) ...)) for derived variants.

#SVG Conventions

All SVG assets are inline in the HTML DOM — never <img> or <object>.

• Reusable shapes: <symbol> in a hidden sprite block, referenced via <use href="#id">
• Decorative SVG: aria-hidden="true" focusable="false"
• Informative SVG: role="img" aria-labelledby="title-id" with <title> as first child
• Paths use CSS classes for fills — no inline fill attributes
• No stroke attributes anywhere. No gradients. Fill-only flat geometry.
• Use viewBox only — omit explicit width/height on <symbol> for responsive scaling

#Page Structure

• index.html — Realm entry, contains the SVG sprite <defs> block and navigation
• pages/contact.html — 领地联络处 (Contact)
• caddy/ — Reference Caddyfile snippets (not deployed)

#Migration Phases

1. Phase 1 (done): 301 redirect cytrogen.icu → blog.cytrogen.icu, blog files at /var/www/blog.cytrogen.icu
2. Phase 2 (current): CSS/SVG design system established in css/realm.css
3. Phase 3 (planned): Full scene layout — Castlevania-style layered environment or game-map navigation. CSS classes .realm-scene, .realm-layer--far/mid/near are pre-defined in the layout layer.
4. Phase 4 (planned): Realm goes live at cytrogen.icu root (serve from /var/www/realm), remove 301 redirects

#Design Constraints

• No JavaScript unless absolutely unavoidable
• All interactivity via CSS (:hover, :focus-visible, transitions, @property animations)
• SVG complexity must degrade gracefully — use container queries or media queries to hide detail at small sizes
• Text-only fallback for terminals/Gemini-style access (planned: separate gopher/gemini protocol support)
• Accessibility: skip decorative SVG via aria-hidden, label informative SVG, respect prefers-reduced-motion