docs: update CLAUDE.md with design system and casual style
- convert to casual markdown style (=== and ---) - add design system section (modern vs industrial patterns) - document latest blogs section on homepage - simplify and condense content for better readability - add clear guidance on when to use each design style
This commit is contained in:
parent
eaf536ae1f
commit
b52c8d67cf
222
CLAUDE.md
222
CLAUDE.md
@ -1,122 +1,160 @@
|
|||||||
# CLAUDE.md
|
nicholai.work - claude guide
|
||||||
|
===
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
this is an astro-based portfolio and blog site deployed on cloudflare pages. content-driven architecture with three main layers: content collections, components, and pages/layouts.
|
||||||
|
|
||||||
## Development Commands
|
development commands
|
||||||
|
---
|
||||||
|
|
||||||
### Core Development
|
core:
|
||||||
```bash
|
- pnpm dev - run dev server
|
||||||
pnpm dev # Run development server
|
- pnpm build - build the project
|
||||||
pnpm build # Build the project
|
- pnpm preview - build and preview with wrangler
|
||||||
pnpm preview # Build and preview with Wrangler
|
- pnpm deploy - build and deploy to cloudflare pages (then run `wrangler pages deploy --branch=main` for production)
|
||||||
pnpm deploy # Build and deploy to Cloudflare Pages
|
|
||||||
```
|
|
||||||
|
|
||||||
### Utilities
|
utilities:
|
||||||
```bash
|
- pnpm commit - interactive git commit with AI-generated messages
|
||||||
# Git commit message automation
|
- pnpm notepad - quick note-taking utility
|
||||||
pnpm commit # Interactive: review, accept/edit, optionally push
|
- pnpm run convert:avif:all - convert images to AVIF
|
||||||
pnpm commit --accept # Auto-accept message, prompt for push
|
- pnpm cf-typegen - generate cloudflare types
|
||||||
pnpm commit --accept --no-push # Auto-accept and commit without pushing
|
|
||||||
pnpm commit --accept --push # Fully automated: accept and push
|
|
||||||
|
|
||||||
pnpm notepad # Quick note-taking utility
|
architecture overview
|
||||||
|
---
|
||||||
|
|
||||||
# Image conversion to AVIF format
|
content layer (src/content/**)
|
||||||
pnpm run convert:avif:all # Convert all images
|
|
||||||
pnpm run convert:avif:jpeg # Convert JPEG only
|
|
||||||
pnpm run convert:avif:png # Convert PNG only
|
|
||||||
|
|
||||||
# Cloudflare types generation
|
content is managed via astro's content collections API with schema validation in src/content.config.ts:
|
||||||
pnpm cf-typegen # Generate Cloudflare types for TypeScript
|
|
||||||
```
|
|
||||||
|
|
||||||
## High-Level Architecture
|
blog/ - blog posts as MDX files
|
||||||
|
- schema: title, description, pubDate, updatedDate, heroImage, featured, category, tags
|
||||||
|
- sorted by pubDate (newest first)
|
||||||
|
- featured post displayed on homepage and blog index
|
||||||
|
|
||||||
This is an Astro-based portfolio and blog site deployed on Cloudflare Pages. The architecture follows a content-driven approach with three distinct layers:
|
sections/ - homepage section content
|
||||||
|
- hero, experience, skills, featured-project
|
||||||
|
- each has custom schema for its needs
|
||||||
|
- experience: systemId, status, dates, company, role, tags, description, achievements, link
|
||||||
|
- skills: id, domain, tools, proficiency
|
||||||
|
|
||||||
### 1. Content Layer (`src/content/**`)
|
pages/ - page-specific content
|
||||||
Content is managed via Astro's Content Collections API with schema validation defined in `src/content.config.ts`:
|
- contact form configuration, labels, social links, subject options
|
||||||
|
|
||||||
- **`blog/`** - Blog posts as MDX files
|
component layer
|
||||||
- Schema: title, description, pubDate, updatedDate (optional), heroImage (optional), featured (boolean), category, tags
|
|
||||||
- Posts are sorted by pubDate (newest first)
|
|
||||||
|
|
||||||
- **`sections/`** - Homepage section content (hero, experience, skills, featured-project)
|
organized by purpose:
|
||||||
- Each section has a custom schema for its specific data needs
|
- core UI: BlogCard, FormattedDate, Navigation, Footer, GridOverlay
|
||||||
- Experience entries include systemId, status, dates, company, role, tags, description, achievements, link
|
- blog: BlogFilters, ReadingProgress, TableOfContents, PostNavigation, RelatedPosts
|
||||||
- Skills entries include id, domain, tools, proficiency
|
- sections: Hero, Experience, Skills, FeaturedProject
|
||||||
|
|
||||||
- **`pages/`** - Page-specific content (contact form configuration)
|
page & layout layer
|
||||||
- Includes form labels, social links, subject options
|
|
||||||
|
|
||||||
### 2. Component Layer
|
- BaseLayout - shared structure for all pages
|
||||||
Components are organized by purpose:
|
- BlogPost - blog post template with sidebar, navigation, related posts
|
||||||
|
- src/pages/ - static routes + dynamic blog routes via [...slug].astro
|
||||||
|
|
||||||
- **Core UI**: `BlogCard`, `FormattedDate`, `Navigation`, `Footer`, `GridOverlay`
|
design system
|
||||||
- **Blog-specific**: `BlogFilters`, `ReadingProgress`, `TableOfContents`, `PostNavigation`, `RelatedPosts`
|
---
|
||||||
- **Section components**: `Hero`, `Experience`, `Skills`, `FeaturedProject`
|
|
||||||
|
|
||||||
### 3. Page & Layout Layer
|
design.json documents the evolution from industrial/technical to modern/clean design language.
|
||||||
- **Layouts**: `BaseLayout` (shared structure), `BlogPost` (blog template)
|
|
||||||
- **Routes**: Static routes in `src/pages/` with dynamic blog routes via `[...slug].astro`
|
|
||||||
|
|
||||||
## Data Flow Patterns
|
key principle: industrial styling reserved for hero, experience, and featured project sections only. everything else (blog, navigation, new sections) uses modern design.
|
||||||
|
|
||||||
### Blog Index (`src/pages/blog/index.astro`)
|
modern design (default for new work):
|
||||||
1. Fetches all posts via `getCollection('blog')`
|
- rounded corners (rounded-lg, rounded-full, rounded-xl)
|
||||||
2. Sorts by pubDate (newest first)
|
- clean typography (normal case, no excessive uppercase)
|
||||||
3. Identifies featured post (first with `featured: true` or fallback to latest)
|
- simple badges with bg-brand-accent/10
|
||||||
4. Renders featured hero + filterable grid of all posts
|
- clean metadata format: "date · read time"
|
||||||
5. Extracts unique categories for filter UI
|
- hashtag format for tags (#tag)
|
||||||
|
- no font-mono or tracking-widest on everything
|
||||||
|
- faster transitions (300ms)
|
||||||
|
|
||||||
### Individual Blog Posts (`src/pages/blog/[...slug].astro`)
|
industrial design (hero/experience/featured only):
|
||||||
1. Uses `getStaticPaths()` to generate all blog post routes
|
- sharp corners
|
||||||
2. For each post, calculates:
|
- uppercase tracking-tighter titles
|
||||||
- Previous/next posts (by date)
|
- font-mono system labels
|
||||||
- Related posts (matching category or shared tags, limited to 3)
|
- pulsing dots, accent strips
|
||||||
- Reading time (based on word count, 200 wpm)
|
- technical aesthetic
|
||||||
3. Passes everything to `BlogPost` layout which handles headings, navigation, related posts
|
|
||||||
|
|
||||||
### Content Collections
|
when building new features, default to modern design unless explicitly working on hero/experience/featured sections.
|
||||||
All content follows the schema validation pattern:
|
|
||||||
```
|
|
||||||
MDX file → src/content.config.ts schema → getCollection() → Component props
|
|
||||||
```
|
|
||||||
|
|
||||||
## Key Technical Patterns
|
data flow patterns
|
||||||
|
---
|
||||||
|
|
||||||
### Image Handling
|
homepage (src/pages/index.astro):
|
||||||
- Assets in `src/assets/` are processed by Astro (use relative paths in frontmatter)
|
- fetches hero, experience, skills, featured-project from content collections
|
||||||
- Static files in `public/media/` are served as-is (use absolute paths like `/media/file.mp4`)
|
- queries 3 most recent blog posts for latest blogs section
|
||||||
- AVIF conversion utility available for optimization
|
- displays in order: hero → experience → featured project → skills → latest blogs
|
||||||
|
|
||||||
### UI Development
|
blog index (src/pages/blog/index.astro):
|
||||||
- **Always review UI changes in the browser** - Check if the dev server is already running before starting it with `pnpm dev`, then visually verify components, animations, and layouts before considering work complete
|
- fetches all posts via getCollection('blog')
|
||||||
|
- sorts by pubDate newest first
|
||||||
|
- identifies featured post (first with featured: true or fallback to latest)
|
||||||
|
- renders featured hero + filterable grid of all posts
|
||||||
|
- extracts unique categories for filter UI
|
||||||
|
|
||||||
## Design Specification
|
individual blog posts (src/pages/blog/[...slug].astro):
|
||||||
|
- uses getStaticPaths() to generate routes
|
||||||
|
- calculates previous/next posts by date
|
||||||
|
- finds related posts (matching category or shared tags, limited to 3)
|
||||||
|
- calculates reading time (200 wpm)
|
||||||
|
- passes to BlogPost layout
|
||||||
|
|
||||||
`dev/design.json` contains V7 Industrial Dark Mode system specification (not yet implemented):
|
key technical patterns
|
||||||
- Dark mode native with `#0B0D11` primary background
|
---
|
||||||
- Orange/yellow accent `#FFB84C` for CTAs
|
|
||||||
- Brutalist/industrial aesthetic with visible grid structure
|
|
||||||
- Heavy typography emphasis
|
|
||||||
|
|
||||||
### Deployment
|
image handling:
|
||||||
- Cloudflare Pages adapter configured in `astro.config.mjs`
|
- assets in src/assets/ processed by astro (use relative paths in frontmatter)
|
||||||
- Image service set to "compile" mode
|
- static files in public/media/ served as-is (use absolute paths like /media/file.mp4)
|
||||||
- Platform proxy enabled for development
|
- AVIF conversion utility available
|
||||||
|
|
||||||
## Blog Post Creation Workflow
|
content collections pattern:
|
||||||
|
MDX file → src/content.config.ts schema → getCollection() → component props
|
||||||
|
|
||||||
1. Create `.mdx` file in `src/content/blog/` (filename becomes URL slug)
|
UI development:
|
||||||
2. Add required frontmatter: title, description, pubDate
|
- ALWAYS review UI changes in the browser
|
||||||
3. Optionally add: heroImage, featured, category, tags
|
- check if dev server is running before starting it
|
||||||
4. Write content using Markdown/MDX with embedded JSX/HTML
|
- visually verify components, animations, layouts before considering work complete
|
||||||
5. Images can reference `src/assets/` (relative) or `public/media/` (absolute)
|
|
||||||
|
|
||||||
## Utility Scripts
|
deployment:
|
||||||
|
- cloudflare pages adapter configured in astro.config.mjs
|
||||||
|
- image service set to "compile" mode
|
||||||
|
- platform proxy enabled for development
|
||||||
|
- production domain: nicholai.work
|
||||||
|
- hosted on cloudflare pages
|
||||||
|
|
||||||
- **`src/utils/convert-to-avif.js`** - Converts images to AVIF format with quality options
|
blog post creation workflow
|
||||||
- **`src/utils/git-commit.js`** - Auto-generates commit messages from staged changes
|
---
|
||||||
- **`src/utils/notepad.js`** - Quick note-taking utility
|
|
||||||
|
1. create .mdx file in src/content/blog/ (filename becomes URL slug)
|
||||||
|
2. add required frontmatter: title, description, pubDate
|
||||||
|
3. optionally add: heroImage, featured, category, tags
|
||||||
|
4. write content using markdown/MDX with embedded JSX/HTML
|
||||||
|
5. images can reference src/assets/ (relative) or public/media/ (absolute)
|
||||||
|
|
||||||
|
utility scripts
|
||||||
|
---
|
||||||
|
|
||||||
|
- src/utils/convert-to-avif.js - converts images to AVIF format
|
||||||
|
- src/utils/git-commit.js - auto-generates commit messages
|
||||||
|
- src/utils/notepad.js - quick note-taking
|
||||||
|
- src/utils/reading-time.ts - calculates reading time (200 wpm)
|
||||||
|
|
||||||
|
important files
|
||||||
|
---
|
||||||
|
|
||||||
|
- design.json - comprehensive design system documentation
|
||||||
|
- src/content.config.ts - content collection schemas
|
||||||
|
- astro.config.mjs - cloudflare pages adapter config
|
||||||
|
- wrangler.jsonc - cloudflare worker configuration
|
||||||
|
- src/consts.ts - site metadata (title, description, social links)
|
||||||
|
|
||||||
|
theme system
|
||||||
|
---
|
||||||
|
|
||||||
|
uses CSS custom properties for theming:
|
||||||
|
- --theme-bg-primary, --theme-bg-secondary
|
||||||
|
- --theme-text-primary, --theme-text-secondary, --theme-text-muted
|
||||||
|
- --theme-border-primary, --theme-hover-bg
|
||||||
|
- --brand-accent (primary accent color)
|
||||||
|
|
||||||
|
dark mode is default, light mode available via theme toggle.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user