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`:

```css
--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
```astro
<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
```astro
<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`:
```astro
---
import BaseLayout from '../layouts/BaseLayout.astro';
---

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

## Development Workflow

```bash
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

```bash
# 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+