/CLAUDE.md

CLAUDE.md at /CLAUDE.md

Path: CLAUDE.md

zcss — zudo-css

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

Live site: https://zudo-css-wisdom.takazudomodular.com/

Commands

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

pnpm dev              # Dev server → http://localhost:8811/
pnpm build            # Production build → dist/
pnpm preview          # Preview built site
pnpm check            # Type checking (tsc + collections)
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: / (root, no sub-path prefix)

• Hosting: Cloudflare Workers static assets (config in wrangler.toml)

• Settings: src/config/settings.ts (siteUrl host MUST match the wrangler.toml custom-domain route)

• Build config: zfb.config.ts

CI/CD

Workflows live in .github/workflows/:

• pr-checks.yml — typecheck + build + a Cloudflare Workers preview URL posted as a PR comment

• main-deploy.yml — build + deploy to Cloudflare Workers static assets production, an automated cutover step (enables the workers.dev subdomain + attaches the zudo-css-wisdom.takazudomodular.com custom domain via the CF API), then an IFTTT notification

• Secrets: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN (needs Workers: Edit, plus Zone: Edit on takazudomodular.com for the custom-domain attach), IFTTT_PROD_NOTIFY

• See CUTOVER.md for the production cutover runbook and manual fallbacks

Safety Rules

• rm -rf: relative paths only (./path), never absolute

• No force push, no --amend unless explicitly permitted

• Temp files go to __inbox/ (gitignored)