zpaper-draft

Type to search...

to open search from anywhere

/blog/CLAUDE.md

CLAUDE.md at /blog/CLAUDE.md

Path: blog/CLAUDE.md

Blog CLAUDE.md

Astro 6 blog with Tailwind CSS v4, MDX content collections, and React islands.

Structure

  • src/pages/ - Astro file-based routing
  • src/articles/ - MDX article files (draft writing)
  • src/s/ - Standalone MDX pages
  • src/components/ - Astro components + React islands
  • src/styles/global.css - Design system tokens and theme
  • src/lib/ - Data layer (article reader, types, utils)
  • src/layouts/ - Astro layouts (base-layout.astro)
  • src/plugins/ - Remark/Rehype plugins
  • src/content.config.ts - Content collections schema (articles + standalone)

Design System

Tight Token Strategy

Tailwind v4 is configured via @tailwindcss/vite (not PostCSS). global.css imports only tailwindcss/preflight + tailwindcss/utilities — no default theme. Only project-specific tokens defined in @theme are available.

NEVER use Tailwind default values (bg-gray-500, p-4, text-blue-600). Only use project tokens.

Color Tokens

Semantic color tokens — use these in classes:

  • Base: bg, fg → bg-bg, text-fg
  • UI: muted, surface, accent, accent-hover, link, active
  • Status: success, danger, warning
  • Special: sold, price
  • Absolute: black, white

Spacing Tokens (Vertical Rhythm)

Spacing is split into two semantic axes:

  • Horizontal (hsp-): hsp-2xs (5px) → hsp-2xl (250px), 7 steps
  • Vertical (vsp-): vsp-2xs (4px) → vsp-2xl (80px), 7 steps

Use: px-hsp-sm, mt-vsp-md, gap-x-hsp-xs, py-vsp-lg, etc.

Typography Tokens

Font sizes with paired line-heights: text-xs through text-5xl Font families: font-noto (body), font-futura (display), font-sans, font-mono Font weights: font-light, font-normal, font-medium, font-bold

Component-First Strategy

Always use Tailwind utility classes directly in component markup. Never create CSS module files or custom CSS class names. The component itself is the abstraction. Article typography is handled by the .zp-content class in global.css using :where() zero-specificity selectors.

Article Writing Rules

Before editing or creating article content in src/articles/, read and follow:

  • ../doc/src/content/docs/overview/writing-style.md
  • ../doc/src/content/docs/overview/markdown-writing-rule.md
  • ../doc/src/content/docs/overview/vocabulary-rule.md

Key vocabulary rule: Use kanji “言う” only for actual speech/dialogue. Use hiragana “いう” for explanatory expressions like “〜ということ”, “〜というわけ”, “〜という形”.

Image Guidelines

  • Store article images in public/img/articles/YYYYMMDD-slug/
  • In markdown, reference with the base path prefix: /pj/zpaper/img/articles/YYYYMMDD-slug/filename.png
  • Do NOT use /img/articles/... without the prefix — the blog is served under /pj/zpaper/

URL Reference Guidelines

When the user provides URLs starting with http://zpaper-blog.localhost:15567/pj/zpaper/ in the conversation:

  • DO NOT fetch the URL - These are local blog URLs served by Astro
  • Instead, find and read the corresponding source file in this directory
  • Map URLs to file paths following Astro file-based routing:
    • http://zpaper-blog.localhost:15567/pj/zpaper/ → src/pages/index.astro
    • http://zpaper-blog.localhost:15567/pj/zpaper/articles/ → src/pages/articles/index.astro
    • http://zpaper-blog.localhost:15567/pj/zpaper/articles/some-slug/ → src/articles/some-slug.mdx