Cozy-Den/CLAUDE.MD

CLAUDE.MD - AI Assistant Guide

This file provides guidance for Claude Code and other AI assistants when working with the Cozy Den project.

Project Quick Reference

Project: Cozy Den - Personal landing page for hiddenden.cafe Owner: Mats (gay furry developer, values self-hosting and privacy) Tech Stack: Astro 4.x, TypeScript, Vanilla CSS, Docker + Nginx Aesthetic: Warm coffee/cappuccino theme, cozy hidden den vibes Deployment: Docker containers pushed to Gitea registry at git.hiddenden.cafe

Core Design Principles

1. Cozy Aesthetic - Warm colors, coffee/cappuccino theme, hidden den vibes
2. Self-Hosted - Everything runs on personal infrastructure (homelab/VPS)
3. Privacy First - No tracking, no external dependencies
4. Lightweight - Static HTML/CSS, minimal JavaScript
5. Docker-Ready - Easy deployment via containers

File Structure

src/
├── layouts/
│   └── BaseLayout.astro      # Base HTML layout + global styles + CSS variables
├── pages/
│   └── index.astro            # Main landing page (all sections here)
└── components/                # Empty - ready for future components
public/
└── favicon.svg                # Coffee emoji favicon

Key Files:

• src/layouts/BaseLayout.astro - CSS variables, global styles, base HTML structure
• src/pages/index.astro - All page content and section-specific styles
• astro.config.mjs - Astro configuration
• Dockerfile - Multi-stage build (Node builder + Nginx server)
• docker-compose.yml - Local Docker Compose setup
• nginx.conf - Production Nginx configuration

Color System

All colors use CSS custom properties in src/layouts/BaseLayout.astro:

--color-bg: #1a1410           /* Dark background (deep coffee) */
--color-bg-light: #2a1f18     /* Lighter background for cards */
--color-text: #f4e9d8          /* Cream text */
--color-text-dim: #c4b5a0      /* Dimmed text */
--color-accent: #d4a574        /* Warm accent (coffee with cream) */
--color-accent-bright: #e8bf8e /* Brighter accent for highlights */
--color-warm: #8b6f47          /* Warm brown for borders/accents */

To change theme: Edit these variables. All components update automatically.

Common Modification Patterns

Adding a Section

<section class="section new-section">
  <div class="container">
    <div class="card fade-in">
      <h2>Section Title</h2>
      <p>Content</p>
    </div>
  </div>
</section>

Adding a Service

<div class="service-item">
  <h3><a href="https://service.hiddenden.cafe">🔧 Service Name</a></h3>
  <p>Description of the service</p>
</div>

Adding a New Page

Create src/pages/newpage.astro:

---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="New Page">
  <div class="container">
    <h1>New Page</h1>
  </div>
</BaseLayout>

Development Workflow

npm install          # Install dependencies
npm run dev          # Start dev server (http://localhost:4321)
npm run build        # Build for production (output to dist/)
npm run preview      # Preview production build

Docker Workflow

# Build image
docker build -t cozy-den .

# Run locally
docker run -d -p 3000:80 --name cozy-den cozy-den

# Or use Docker Compose
docker-compose up -d

# Tag for Gitea registry
docker tag cozy-den git.hiddenden.cafe/mats/cozy-den:latest

# Push to Gitea
docker login git.hiddenden.cafe
docker push git.hiddenden.cafe/mats/cozy-den:latest

Important Implementation Guidelines

DO:

• Maintain the cozy, warm aesthetic (coffee theme)
• Keep the site lightweight and fast (static HTML/CSS)
• Use CSS custom properties for all colors
• Add .fade-in class for animations
• Test both dev and production builds
• Verify Docker build works after changes
• Use semantic HTML with consistent .card class styling
• Ensure responsive design works on mobile
• Be warm and friendly in communication (matches site vibe)
• Focus on practical implementation
• Respect the furry community context

DON'T:

• Add tracking or external dependencies
• Make the site heavy or complex
• Use JavaScript unless absolutely necessary (site is pure HTML/CSS)
• Create sterile or corporate design elements
• Add features not explicitly requested
• Break the coffee/warm color theme
• Ignore accessibility considerations

Astro-Specific Notes

• File Extensions: .astro for components, .mjs for config
• Frontmatter: Code between --- runs at build time
• Styling: <style> tags are scoped by default, use <style is:global> for global styles
• Static Generation: Astro generates static HTML at build time
• No Runtime: This site outputs pure HTML/CSS with no JavaScript runtime needed

Current Project Status

Completed:

• Landing page with hero section
• About Hidden Den section
• About Me section (Mats)
• Services section (Gitea linked)
• Support section
• Docker deployment setup
• Responsive design

Future Possibilities:

• Blog section using Astro Content Collections
• More self-hosted services
• Payment/donation links
• Project showcase pulling from Gitea API
• Custom 404 page
• Theme toggle
• Contact form
• RSS feed

Owner Preferences

Mats typically:

• Works in bursts of creative energy
• Uses Docker for all deployments
• Pushes to personal Gitea at git.hiddenden.cafe
• Values complete control over hosting
• Prefers warm, personal styling over corporate design
• Is learning Astro (normally uses Python/Flask)

Testing Checklist

Before deploying changes:

• npm run dev - Check locally
• npm run build - Ensure build succeeds
• docker build -t cozy-den . - Verify Docker build
• Test on mobile viewport
• Check all links work
• Verify color contrast for accessibility

Success Criteria

The site should:

• Load fast (static HTML)
• Feel warm and welcoming
• Accurately represent Mats and Hidden Den
• Work on all screen sizes
• Be easy to deploy via Docker
• Require minimal maintenance

Troubleshooting Quick Reference

Build fails: Check TypeScript config, ensure Node 18+ Styles not applying: Check if you need is:global, verify CSS variables are in BaseLayout Docker build fails: Ensure package.json and package-lock.json are present Changes not showing: Hard refresh (Ctrl+Shift+R), restart dev server, or clear .astro cache

Documentation Files

• CLAUDE.MD (this file) - AI assistant guide
• PROJECT_CONTEXT.md - Project context and design principles
• DEVELOPMENT.md - Developer documentation and architecture
• TODO.md - Current tasks and future features
• README.md - User-facing documentation

Communication Style

When working with this project:

• Be warm and friendly (matches the site vibe)
• Use clear, direct language
• Respect the furry community context
• Focus on practical implementation
• Acknowledge this is a learning project with Astro
• Personal and authentic over polished and corporate

---

Last Updated: 2025-12-23 Project Version: Initial release Astro Version: 4.x Node Version: 18+