/CLAUDE.md

CLAUDE.md at /CLAUDE.md

Path: CLAUDE.md

zcss — zudo-css

CSS best practices documentation site, built with zudo-doc (Astro 5, MDX, Tailwind CSS v4).

Commands

Package manager: pnpm (Node.js >= 20).

pnpm dev              # Dev server → http://css-bp.localhost:8811
pnpm build            # Production build → dist/
pnpm preview          # Preview built site
pnpm check            # Astro type checking
pnpm b4push           # Pre-push validation (typecheck + build + link check)

Content Structure

• English (default): src/content/docs/ -> /docs/...
• Japanese: src/content/docs-ja/ -> /ja/docs/...
• Japanese docs should mirror the English directory structure

Bilingual rule: When creating or updating any doc page, ALWAYS update both the English (docs/) and Japanese (docs-ja/) versions in the same PR. Keep code blocks and <CssPreview> blocks identical between languages — only translate surrounding prose. If a Japanese version does not yet exist, create it.

Content Categories

Top-level directories under src/content/docs/. Directories with header nav entries are mapped via categoryMatch in src/config/settings.ts:

• overview/ - What is zudo-css, css-wisdom skill docs
• layout/ - Flexbox, Grid, positioning, centering, sizing, specialized layouts
• typography/ - Font sizing, fonts, text control
• styling/ - Color, effects, shadows and borders
• responsive/ - Container queries, fluid design, media queries, responsive patterns
• interactive/ - Forms, scroll, selectors, states and transitions
• methodology/ - Architecture (BEM, cascade layers, CSS modules), design systems

Auto-generated directories (no header nav entry):

• inbox/ - Draft/work-in-progress articles (skipped by css-wisdom skill)

Writing Docs

All documentation files use .mdx format with YAML frontmatter.

Frontmatter Fields

Schema defined in src/content.config.ts:

Content Rules

• No h1 in content: The frontmatter title is automatically rendered as the page h1. Start your content with ## h2 headings. Do not write # h1 in the MDX body.
• Always set sidebar_position: Without it, pages sort alphabetically which is unpredictable. Use integers starting from 1.
• Kebab-case file names: Use my-article.mdx, not myArticle.mdx or my_article.mdx.

Article Structure

Follow this pattern for all articles:

1. ## The Problem — what goes wrong, common mistakes
2. ## The Solution — recommended approach with CssPreview demos
3. More sections with demos as needed
4. ## When to Use — summary of when this technique applies

Linking Between Docs

Use relative file paths with the .mdx extension:

[Link text](./sibling-page.mdx)
[Link text](../other-category/page.mdx)
[Link text](../other-category/page.mdx#anchor)

The remark plugin resolves these during build. External links use standard URLs.

MDX Components

Available globally in MDX without imports:

• <Note>, <Tip>, <Info>, <Warning>, <Danger> — Admonitions (each accepts optional title prop)
• <CssPreview> — Interactive CSS preview with code display (renders in iframe)

CssPreview Demos

Always include CssPreview demos — they are the most valuable part of each article.

Key details:

• Renders inside an iframe — all CSS is fully isolated
• Viewport buttons: Mobile (320px), Tablet (768px), Full (~900-1100px)
• No JavaScript — interactions must be CSS-only (:hover, :focus, :checked, etc.)

CSS Conventions in Demos

• Use hsl() colors, not hex
• Use descriptive BEM-ish class names (e.g., .card-demo__header)
• Use font-family: system-ui, sans-serif for body text
• Minimum font size: 0.75rem / 12px for labels
• Template literal indentation: Always indent css={} and html={} content by at least 2 spaces. The dedent() utility strips common leading whitespace before displaying code in the panel. Content at column 0 produces unindented code display.

Navigation Structure

Navigation is filesystem-driven. Directory structure directly becomes sidebar navigation.

Sidebar Ordering

• Pages are ordered by sidebar_position (ascending). Without it, alphabetical order is used.
• Category index pages (index.mdx) control category position via their own sidebar_position.

Header Navigation

Defined in src/config/settings.ts via headerNav. Each item maps to a top-level content directory via categoryMatch:

{ label: "Layout", path: "/docs/layout", categoryMatch: "layout" }

Adding a new header nav item requires editing settings.ts.

Content Creation Workflow

Adding a New Article

1. Create the English .mdx file in the appropriate category under src/content/docs/
2. Add frontmatter with at least title and sidebar_position
3. Write content starting with ## h2 headings (not # h1)
4. Include CssPreview demos to illustrate techniques
5. Create the matching Japanese file under src/content/docs-ja/ with the same path
6. Keep code blocks and <CssPreview> blocks identical — only translate prose
7. Run pnpm build to verify the site builds correctly

Adding a New Category

1. Create the directory under src/content/docs/ (kebab-case)
2. Create index.mdx with title, description, and sidebar_position
3. Add a headerNav entry in src/config/settings.ts with categoryMatch pointing to the directory name
4. Mirror the directory structure under src/content/docs-ja/
5. Run pnpm build to verify

Design Token System

Uses a 16-color palette with OKLCH orange accent (oklch(55.5% 0.163 48.998)).

Color Rules

• NEVER use Tailwind default colors (bg-gray-500, text-blue-600)
• ALWAYS use project tokens: text-fg, bg-surface, border-muted, text-accent, etc.
• Use palette tokens (p0–p15) only when no semantic token fits

Color Schemes

• Default: ZCSS Dark (warm dark theme with orange accents)
• Light: ZCSS Light (warm light theme with orange accents)
• Configured in src/config/settings.ts and src/config/color-schemes.ts

Doc Skill (css-wisdom)

The css-wisdom skill (.claude/skills/css-wisdom/SKILL.md) is generated by pnpm generate:css-wisdom (runs scripts/generate-css-wisdom.js). It is gitignored — do NOT track it in git or edit it directly. To update the skill content, edit the generator script and re-run pnpm generate:css-wisdom. Add descriptions for new articles to .claude/skills/css-wisdom/descriptions.json.

Claude Code Skills

This repo manages zcss-specific Claude Code skills in .claude/skills/:

• css-wisdom — Generated topic index of all CSS articles. Symlinked to ~/.claude/skills/css-wisdom so it’s available globally. Supports -u/--update mode.
• l-writing — Writing and formatting rules for MDX articles. Before writing or editing docs, invoke /l-writing.
• l-handle-deep-article — Guide for converting flat articles into deep articles with sub-pages. Local to this repo.
• l-demo-component — Guide for CssPreview component usage and defaultOpen prop conventions. Local to this repo.
• l-translate — Translate English docs to Japanese using the ja-translator subagent. Invoke /l-translate <path-or-category>.
• b4push — Before-push quality checks (type check, build, link check). Invoke /b4push.

Agents

• ja-translator — Subagent for translating MDX docs from English to Japanese.

Translation Workflow

After editing or creating an English doc, translate the Japanese counterpart using /l-translate. After editing a Japanese doc, update the English counterpart similarly.

Site Config

• Base path: /pj/zcss/
• Settings: src/config/settings.ts

CI/CD

• PR checks: typecheck + build + link check + Cloudflare Pages preview
• Main deploy: build + Cloudflare Pages production + IFTTT notification
• Preview deploy: branch-based Cloudflare Pages preview
• Secrets: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, IFTTT_PROD_NOTIFY

Safety Rules

• rm -rf: relative paths only (./path), never absolute
• No force push, no --amend unless explicitly permitted
• Temp files go to __inbox/ (gitignored)