/CLAUDE.md

CLAUDE.md at /CLAUDE.md

Path: CLAUDE.md

zudo-test-wisdom

Takazudo's frontend testing strategy guide, built with zudo-doc (zfb stack, MDX, Tailwind CSS v4).

Commands

pnpm dev              # Start zfb dev server (port 4321)
pnpm build            # Build static site via zfb build
pnpm preview          # Preview built site
pnpm check            # zfb type checking
pnpm format:md        # Format MDX files
pnpm b4push           # Pre-push validation (format + typecheck + build)
pnpm setup:doc-skill  # Generate test-wisdom skill + symlink all skills

Content Structure

English (default): src/content/docs/ -> /docs/...
Japanese: src/content/docs-ja/ -> /ja/docs/...
Japanese docs 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 identical between languages -- only translate surrounding prose.

Exception: Pages with generated: true in frontmatter (e.g., claude-resources auto-generated pages) do not require Japanese translations.

Content Categories

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

overview/ - Introduction and purpose of the testing guide
testing-levels/ - The 5 testing levels from unit to visual verification
decision-guide/ - Which level to use, common failure patterns, required behaviors
real-world-patterns/ - Vitest patterns, Playwright E2E, Tauri app testing
tools-reference/ - Quick reference of tools per testing level

Auto-generated directories (no header nav entry, managed by claude-resources integration):

claude-md/ - CLAUDE.md file documentation (noPage: true)
claude-skills/ - Claude Skills documentation (noPage: true)

Writing Docs

All documentation files use .mdx format with YAML frontmatter.

Frontmatter Fields

Schema defined in src/content.config.ts:

Field	Type	Required	Description
`title`	string	Yes	Page title, rendered as the page h1
`description`	string	No	Subtitle displayed below the title
`sidebar_position`	number	No	Sort order within category (lower = higher). Always set this for predictable ordering
`sidebar_label`	string	No	Custom text for sidebar display (overrides `title`)
`generated`	boolean	No	Build-time generated content (skip translation)

Content Rules

No h1 in content: The frontmatter title is automatically rendered as the page h1. Start your content with ## h2 headings.
Always set sidebar_position: Without it, pages sort alphabetically which is unpredictable.
Kebab-case file names: Use my-article.mdx, not myArticle.mdx.

Linking Between Docs

Use relative file paths with the .mdx extension:

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

Admonitions

Available globally without imports: <Note>, <Tip>, <Info>, <Warning>, <Danger>

Navigation is filesystem-driven. Directory structure directly becomes sidebar navigation. Pages ordered by sidebar_position (ascending). Category index pages (index.mdx) control category position.

Content Creation Workflow

Create English .mdx file under src/content/docs/ with title and sidebar_position
Write content starting with ## h2 headings (not # h1)
Create matching Japanese file under src/content/docs-ja/
Keep code blocks identical -- only translate prose
Run pnpm format:md then pnpm build to verify

Skills

This repo contains test-related Claude Code skills under .claude/skills/:

test-wisdom/ - Doc-lookup skill (generated by pnpm setup:doc-skill, gitignored -- do NOT track or edit directly)
verify-ui/ - Deterministic CSS/computed-style verification (tracked in git)
headless-browser/ - Headless browser screenshots and interaction (tracked in git, run npm install in its directory for playwright)

Run pnpm setup:doc-skill to generate the test-wisdom skill AND symlink all skills to ~/.claude/skills/. The script handles both the generated doc-lookup skill and the tracked skills in one step.

Typography

Futura for page h1 titles and header site name (font-futura class)
Noto Sans JP for body text
Headings use font-weight 400 (normal), not bold

Project Layout

pages/          # Host-app routing layer (zfb entry points)
src/
  components/   # Shared UI components
  config/       # settings.ts — site-wide config
  content/      # MDX doc pages (docs/ + docs-ja/)
  utils/        # Shared utilities
plugins/        # zfb integration plugins (.mjs)
zfb.config.ts   # Build config (framework, collections, plugins, adapter)

Site Config

Base path: / (root — no subpath prefix)
Live URL: https://zudo-test-wisdom.takazudomodular.com/
Settings: src/config/settings.ts
Build config: zfb.config.ts

CI/CD

PR checks: typecheck + build + Cloudflare Workers static assets preview
Main deploy: build → wrangler deploy → Cloudflare Workers + IFTTT notification
Hosting: Cloudflare Workers static assets (not Pages)
Secrets: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, IFTTT_PROD_NOTIFY