initial

README.md

@@ -0,0 +1,172 @@
+# Koko Blog
+
+A fast, beautiful personal blog built with Astro, TypeScript, and a synthwave purple theme.
+
+**Load time:** < 100ms | **Bundle size:** < 50KB | **Zero runtime JS by default**
+
+---
+
+## Stack
+
+- **Framework:** Astro 5 — static output, file-based routing, zero JS by default
+- **Language:** TypeScript strict
+- **Package manager:** pnpm
+- **Syntax highlighting:** Shiki / Dracula (built into Astro, zero runtime cost)
+- **Image optimization:** `node image-optimizer.js` (WebP via sharp, run before build)
+- **Content:** Astro Content Collections with Zod schema
+
+> **For AI agents:** All components are `.astro` files. No React, no Vue, no `.tsx`. Astro uses
+> `---` frontmatter fences, not `<template>` or `<script setup>`. File-based routing lives in
+> `src/pages/` — no router library needed. If existing files contradict this, ignore them and
+> follow this README.
+
+---
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm dev        # dev server at http://localhost:4321
+pnpm build      # production build → dist/
+pnpm preview    # preview production build
+pnpm check      # TypeScript check (astro check, not tsc)
+```
+
+---
+
+## Project Structure
+
+```
+koko-blog/
+├── public/
+│   ├── images/
+│   │   ├── posts/          # Blog post hero images
+│   │   └── previews/       # WebP-optimised thumbnails
+│   └── favicon.svg
+├── src/
+│   ├── components/         # .astro components only
+│   │   ├── Layout.astro    # Base page layout (head, header, footer)
+│   │   ├── Header.astro    # Navigation + mobile menu
+│   │   ├── Sidebar.astro   # Collapsible sidebar
+│   │   ├── Footer.astro
+│   │   ├── Hero.astro      # Homepage hero with carousel
+│   │   ├── PostCard.astro  # Blog post preview card
+│   │   └── PostGrid.astro  # Posts grid layout
+│   ├── pages/              # File-based routing (.astro files only)
+│   │   ├── index.astro     # Homepage
+│   │   ├── posts/
+│   │   │   └── [slug].astro  # Individual post page
+│   │   └── 404.astro
+│   ├── content/
+│   │   ├── config.ts       # Zod schema for blog collection
+│   │   └── blog/           # Markdown posts (.md files)
+│   ├── styles/
+│   │   ├── synthwave.css   # CSS custom properties (theme variables)
+│   │   └── global.css      # Resets and base styles
+│   └── env.d.ts            # /// <reference types="astro/client" />
+├── image-optimizer.js      # WebP conversion (run: node image-optimizer.js)
+├── astro.config.mjs        # Astro config (output: static, shiki/dracula)
+├── tsconfig.json           # extends astro/tsconfigs/strict + path aliases
+├── PLAN.md
+└── TODO.md
+```
+
+---
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `pnpm dev` | Start dev server (port 4321) |
+| `pnpm build` | Build for production |
+| `pnpm preview` | Preview production build |
+| `pnpm check` | Type-check with `astro check` |
+| `node image-optimizer.js` | Convert images to WebP (run before build) |
+
+---
+
+## Design System
+
+### Colors
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Primary | `#6a1b9a` | Buttons, accents, links |
+| Primary Dark | `#510ca9` | Hover states |
+| Secondary | `#000080` | Electronic sheen elements |
+| Background | `#000000` | Page background |
+| Paper | `#121212` | Card backgrounds |
+| Text Primary | `#ffffff` | Headings |
+| Text Secondary | `#eeeeee` | Body text |
+| Text Muted | `#888888` | Metadata |
+
+### Typography
+
+- **Headlines:** 2.5rem–4rem, weight 800
+- **Titles:** 1.8rem, weight 700
+- **Body:** 1rem, line-height 1.8
+- **Code:** Monospace, dark background (Shiki/Dracula)
+
+### Breakpoints
+
+- **Mobile:** < 768px
+- **Tablet:** 768px–1024px
+- **Desktop:** > 1024px
+
+---
+
+## Writing Content
+
+Posts live in `src/content/blog/` as `.md` files with YAML frontmatter:
+
+```markdown
+---
+title: "My Awesome Post"
+slug: "my-awesome-post"
+excerpt: "A brief description..."
+publishedAt: "2026-02-28"
+category: "Game Development"
+tags: ["unity", "csharp"]
+image: "/images/posts/hero.jpg"
+draft: false
+---
+
+Your content here with **markdown** support.
+
+```typescript
+// Syntax highlighting via Shiki/Dracula — zero runtime JS
+const hello = "world";
+```
+```
+
+---
+
+## TypeScript Path Aliases
+
+```typescript
+import Layout from '@components/Layout.astro';
+import '@styles/global.css';
+```
+
+Available aliases (defined in `tsconfig.json`):
+- `@/*` → `./src/*`
+- `@components/*` → `./src/components/*`
+- `@layouts/*` → `./src/layouts/*`
+- `@styles/*` → `./src/styles/*`
+- `@utils/*` → `./src/utils/*`
+
+---
+
+## Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| Load time | < 100ms |
+| Bundle size | < 50KB (gzipped) |
+| First Contentful Paint | < 50ms |
+| Largest Contentful Paint | < 1s |
+| Lighthouse score | > 90 |
+
+---
+
+**Built with:** Astro • TypeScript • pnpm