claw_blog/TODO.md

Koko Blog - TODO List

Detailed implementation plan for a React + TypeScript blog with a strict lightweight/performance focus.

---

Lightweight Rules (Global)

These rules apply to every phase.

• Keep initial JS under 50KB gzipped (or document why not)
• Prefer static/build-time work over runtime work
• Use route-level code splitting for all non-home routes
• Avoid heavy UI kits and unnecessary runtime libraries
• Avoid client-side state libraries unless a real scaling need appears
• Keep CSS lean and token-driven (no unused style systems)
• Run pnpm build + pnpm typecheck at each major milestone

---

Phase 0: Foundation (Critical)

0. Initialize React Baseline

Priority: Critical | Status: Pending

• Set up Vite + React + TypeScript project structure
• Configure strict TypeScript settings
• Define path aliases (@/*, @components/*, @pages/*, @styles/*, @lib/*)
• Add linting and formatting rules focused on consistency + small bundles
• Confirm baseline build passes

1. Performance Budget Guardrails

Priority: Critical | Status: Pending

• Add bundle-size budget checks to CI (or local verification script)
• Track core web vitals targets in docs:
  • LCP < 1.0s
  • CLS < 0.1
  • Lighthouse Performance > 90
• Document acceptable dependency categories (rendering, routing, content, build tooling)

---

Phase 1: Core UI Infrastructure (Critical)

2. Synthwave Theme System (src/styles/)

Priority: Critical | Status: Pending

• Build theme token layer in synthwave.css
  • Primary: #6a1b9a
  • Primary dark: #510ca9
  • Secondary: #000080
  • Background: #000
  • Paper: #121212
  • Text: #fff, #eee, #888
• Create gradient and glow utilities without large animation libraries
• Respect prefers-reduced-motion
• Keep total CSS size practical and audited

3. Layout Shell (Layout.tsx, Header.tsx, Sidebar.tsx, Footer.tsx)

Priority: Critical | Status: Pending

• Implement responsive app shell with collapsible sidebar
• Keep sidebar interactions lightweight (simple React state + CSS transitions)
• Ensure keyboard/focus accessibility for menu controls
• Add semantic landmarks (header, main, nav, footer)
• Validate no unnecessary re-renders in layout components

4. Hero Section (Hero.tsx)

Priority: High | Status: Pending

• Build hero component with optional carousel behavior
• Avoid external carousel libraries unless justified
• Use CSS transforms/opacity for transitions only
• Add pause-on-hover and reduced-motion fallback
• Ensure hero media does not block first paint

5. Post Card + Post Grid (PostCard.tsx, PostGrid.tsx)

Priority: High | Status: Pending

• Implement reusable PostCard with typed props
• Keep hover effects CSS-only
• Ensure responsive grid (1/2/3 column breakpoints)
• Add clear metadata rendering (date, category, tags)
• Use lazy-loaded images for below-the-fold cards

---

Phase 2: Content Pipeline & Routing (Critical)

6. Markdown Content Layer (src/content/, src/lib/content.ts)

Priority: Critical | Status: Pending

• Define Zod schema for frontmatter
  • title, slug, excerpt, publishedAt, category, tags, image, draft
• Load and validate markdown at build time
• Exclude drafts from production builds
• Generate strongly typed post objects for pages/components
• Keep markdown tooling minimal and audited

7. Routing (src/app/routes.tsx, src/pages/)

Priority: Critical | Status: Pending

• Configure React Router for:
  • / -> Home page
  • /posts/:slug -> Post page
  • * -> 404 page
• Add route-level lazy loading for post and 404 routes
• Prefetch only where useful (avoid wasteful eager loading)
• Verify navigation remains fast on low-end devices

8. Post Page (PostPage.tsx)

Priority: High | Status: Pending

• Render markdown content with lightweight renderer
• Add syntax highlighting strategy with minimal client cost
  • Prefer build-time highlighting
• Implement readable typography and code block styles
• Add previous/next and back-to-home links
• Ensure heading hierarchy and link accessibility are correct

9. 404 Page (NotFoundPage.tsx)

Priority: Medium | Status: Pending

• Design lightweight 404 page aligned with theme
• Keep effects minimal and accessible
• Add clear recovery action (Return Home)

---

Phase 3: Images, SEO, and Metadata (High)

10. Image Optimization (scripts/optimize-images.mjs)

Priority: High | Status: Pending

• Generate optimized WebP versions for post images
• Create multiple widths for responsive delivery
• Keep originals + generated assets organized
• Ensure hero images are prioritized and sized correctly
• Validate no layout shift from missing width/height

11. SEO + Social Metadata

Priority: High | Status: Pending

• Add per-page <title> and meta description handling
• Add Open Graph and Twitter meta tags
• Add canonical URL support
• Add sitemap generation step
• Add robots policy

12. Feed + Structured Data (Optional, Recommended)

Priority: Medium | Status: Pending

• Generate RSS feed from post metadata
• Add JSON-LD for blog posts
• Validate schema output with tooling

---

Phase 4: Quality Gates (Critical)

13. Testing Strategy

Priority: High | Status: Pending

• Unit tests for core utilities (content, date, slug)
• Component smoke tests for layout + post list
• Route-level render tests (/, /posts/:slug, 404)
• Accessibility checks for navigation and forms

14. Performance Verification

Priority: Critical | Status: Pending

• Run production build and inspect bundle output
• Verify route chunks are split as expected
• Run Lighthouse on preview build
• Record baseline metrics for future regressions
• Fail CI when bundle/perf budgets are exceeded

15. Cross-Browser + Device Checks

Priority: Medium | Status: Pending

• Chrome, Firefox, Safari, Edge basic coverage
• Mobile viewport checks (<768px)
• Tablet viewport checks (768-1024px)
• Desktop checks (>1024px)

16. Accessibility Audit (WCAG 2.1 AA)

Priority: High | Status: Pending

• Keyboard navigation across all interactive UI
• Visible focus states
• Sufficient contrast for text and controls
• Reduced-motion behavior verified
• Semantic headings and landmarks verified

---

Phase 5: Documentation & Maintenance (Medium)

17. Docs Update

Priority: Medium | Status: Pending

• Keep README aligned with actual scripts and folder layout
• Add architecture notes (why lightweight choices were made)
• Document content authoring workflow
• Document performance budget policy

18. Dependency Hygiene

Priority: Medium | Status: Pending

• Audit dependencies quarterly
• Remove unused packages quickly
• Avoid overlapping libraries solving the same problem
• Keep lockfile clean and reproducible

---

Quick Reference

Performance Budget

Metric	Target
Initial JS	< 50KB gzipped
LCP	< 1.0s
CLS	< 0.1
Lighthouse Performance	> 90

Breakpoints

Name	Width
Mobile	< 768px
Tablet	768px-1024px
Desktop	> 1024px

Core Commands

• pnpm dev
• pnpm build
• pnpm preview
• pnpm typecheck
• pnpm lint

---

Last Updated: 2026-03-03