zudo-doc-navigation-design

name	zudo-doc-navigation-design
description	Navigation design rules for the zudo-led-lamp doc site (zudo-doc). Consult before creating new pages, restructuring directories, or changing header navigation. Covers: 3-level hierarchy (header → sidebar → nested), file-structure-is-navigation principle, header nav conciseness, category index pages, sidebar_position discipline, the generated claude* categories, and common mistakes. Triggered by 'nav design', 'navigation structure', 'zudo-doc-navigation-design', 'structure nav', 'add category', 'add header nav', 'add a doc page'.
user-invocable	true

zudo-doc Navigation Design Rules

IMPORTANT: Consult these rules before creating new doc pages, adding categories, or changing this site's navigation. AI tools tend to pattern-match to personal preference and produce chaotic structures; this skill encodes the correct approach.

Ported from the upstream zudo-doc project skill of the same name and adapted to this site. Upstream reference (public): https://zudo-doc.takazudomodular.com/docs/claude-skills/zudo-doc-navigation-design/. This repo has no local copy of upstream's structuring-navigations.mdx guide — read the upstream page if you want the long-form walkthrough.

This skill is working-only, not published. doc/zfb.config.ts points claudeResources at the repo-root .claude/ (the component-audit skills), so nothing under doc/.claude/ renders on the site. That is deliberate: this is tooling for editing the site, not content about the project.

The 3-Level Hierarchy

zudo-doc has exactly three levels. Do not invent more:

1. Header nav — the biggest categories (3–6 items max)
2. Sidebar — all pages in the active category (generated from the filesystem)
3. Nested sidebar categories — subsections within a sidebar (2–3 levels of nesting max)

Each level narrows scope. Never jump levels — do not put a specific page directly in the header, and do not hide a whole category in a nested sidebar fold.

File Structure IS the Navigation

This is the single most important rule. The directory tree under doc/src/content/docs/ is the navigation. There is no separate config to keep in sync.

• A directory becomes a sidebar category. Its index.mdx is the category landing page.
• A file becomes a sidebar item.
• Subdirectories become nested collapsible categories.
• The headerNav setting in doc/zfb.config.ts maps top-level directories to header items via categoryMatch.

Consequence: design the filesystem with navigation in mind from the start. Do not reorganize the sidebar via config hacks — reorganize the files.

This Site's Current Structure

headerNav in doc/zfb.config.ts holds 6 items — the documented maximum. Adding a seventh is not a free action: merge or split an existing category instead.

Header item	categoryMatch	Directory	Content pages
Getting Started	getting-started	getting-started/	introduction, installation
Architecture	architecture	architecture/	overview, board-p, board-l, bom, decisions, next-steps
Power	power	power/	board-p-front-end, ratings-matrix, charger-compatibility, lessons-from-zudo-pd
Research	research	research/	led-candidates, driver-ics, thermal-budget, led-interconnect, control-logic-rail, mcu-candidates, control-knob, modulation-algorithms, control-safety
How-To	how-to	how-to/	ci-cloudflare-setup
Components	components / claude	components/, claude/, claude-md/, claude-skills/	catalog/records plus generated raw resources — see below

Known exception: how-to/ currently holds a single content page, below the "at least 3 pages" bar for a header category. It is kept because it is an operational-runbook bucket expected to grow. Do not cite it as precedent for a new thin category.

sidebar_position convention here

• Content categories with room to grow (architecture/, power/, research/) use gapped numbering in 10s — 10, 20, 30, … — so a page can be inserted between two others without renumbering the whole directory. Follow this when adding to these directories.
• Small, stable categories (getting-started/, how-to/) use plain 1, 2, 3.
• Every category index.mdx uses sidebar_position: 1.

The generated component and claude* categories — do not hand-edit

components/ is generated by doc/component-docs/; claude/, claude-md/, and claude-skills/ are generated at build time by zudo-doc's claudeResources plugin. The Components header dropdown intentionally groups the human component catalog with the raw agent resources it projects. Neither tree is a place for hand-authored pages.

• Editing them by hand is always wrong — the next generation discards it.
• To change components/, update the repo-root evidence or component-docs renderer, then run pnpm generate:components. To change claude*, update the repo-root .claude/skills/ and the repo's CLAUDE.md files, then run pnpm build.
• Footprint and model previews are committed generated assets under doc/public/assets/component-previews/; update their reviewed selection and run the corresponding generator, never link a hand-created preview from navigation.
• The claude* sidebar_position values (899–903) are assigned by the generator and sit deliberately high so they sort last. Do not give a hand-authored category a position in that range.
• The Components header entry uses components and claude child category matches; keep that paired dropdown when changing either generated tree. It has no hand-authored generated-tree index.

Header Navigation Rules

The header is the topmost level. It holds only the biggest categories.

• 3–6 items max. More than 6 overwhelms users and wraps the header. This site is already at 6.
• Each item is a broad section, not a page. "Research" ✓, "LED candidates" ✗.
• categoryMatch must be a single top-level directory name. Multi-segment values (e.g. "architecture/board-p") break active-state highlighting. If you need nested grouping, use a header-level dropdown with children — not a path.
• Dropdowns are for closely related sections only. "Design > Architecture, Power" makes sense. "Everything > 7 miscellaneous items" does not — split into separate header items instead.

Sidebar Structure Rules

The sidebar is generated from the filesystem. The rules are about how you organize files:

• Every category directory MUST have an index.mdx. Without it, the category has no landing page and may not appear correctly. The index's sidebar_position sets the category's position.
• Every page MUST set sidebar_position. Without it, pages sort alphabetically — which is almost never what you want. This is the single most common AI mistake.
• Nesting depth: 2–3 levels max. Deep nesting hides content. If you need more, the header nav is probably missing a category — but see the 6-item ceiling above before adding one.
• Each sidebar section should cover one cohesive topic. Do not mix unrelated themes in the same sidebar. The research/ vs architecture/ split is the working example: research holds open options, architecture holds the locked picks. Keep that boundary.
• Use kebab-case directory and file names. board-p-front-end.mdx, not boardPFrontEnd.mdx.

Category Top Page (index.mdx)

Every category directory must have an index.mdx. This file is the landing page for that category — keep it short:

• A 1–2 sentence intro describing what the category covers.
• A <CategoryNav category="<dir>" /> component that auto-renders links to sibling pages.
• No full content or prose beyond the intro. Real documentation lives in sibling .mdx files under the same directory.

The category prop value is the top-level directory name (e.g. category="power" for doc/src/content/docs/power/). Do not include path separators or the full path.

Example index.mdx, matching this site's existing style:

---
title: Power
sidebar_position: 1
---

Board P — the USB-PD front end that negotiates a 15 V/3 A contract and hands a
switched rail downstream.

<CategoryNav category="power" />

The plural form <CategoryNav categories={["a","b"]} /> renders cards for several categories at once. It is used only by the generated claude/index.mdx; hand-authored category pages use the singular category prop.

Checklist for Adding a New Page

Before creating any new doc page, check this list:

• Which header category does it belong under? (If none fits, either rework an existing category or rethink whether this page is really needed — the header is full.)
• Which sidebar section inside that header category?
• Does the target directory exist? If yes, does it have an index.mdx?
• Have you set sidebar_position in the frontmatter, following the directory's convention (10s for architecture/power/research, 1-2-3 for the small ones)?
• Is the file name in kebab-case?
• Is the target directory one of the generated claude* ones? If so, stop — edit the source under the repo-root .claude/ instead.

This site is single-locale — there is no doc/src/content/docs-ja/, so no translation counterpart is needed. If a Japanese tree is ever added, every new page needs a matching file under docs-ja/ (or generated: true to skip it).

Checklist for Adding a New Category

Before creating any new category directory:

• Is this really a new category, or does it belong under an existing one? Default to "fewer categories."
• Does it need a header nav entry, or is it a nested sidebar category inside an existing header entry? The header is at its 6-item ceiling — prefer nesting.
• Have you created index.mdx with a short intro + <CategoryNav> (not full content) and sidebar_position: 1?
• If you added a header entry, does its categoryMatch value equal the new top-level directory name (single segment)?
• Does the new category have at least 3 pages? Fewer than 3 usually means the pages belong under a broader category instead.

Common Mistakes (Do Not Do)

• Hand-editing claude/, claude-md/, or claude-skills/. They are regenerated on every build. Edit the repo-root .claude/ or a CLAUDE.md instead.
• Putting specific pages in the header nav. The header is for categories, not pages.
• Adding a 7th header item without merging or splitting something first.
• Deep nesting (4+ levels). If you find yourself nesting deeply, the category boundaries are probably wrong.
• Mixing unrelated topics in one sidebar section — particularly blurring research/ (open options) into architecture/ (locked decisions).
• Missing sidebar_position on pages. Leads to unpredictable alphabetical order.
• Missing index.mdx in category directories. Category has no landing page.
• Ignoring the 10s gap convention in architecture/, power/, research/ — sequential 1,2,3 there forces a renumber on the next insertion.
• Multi-segment categoryMatch. Breaks active highlighting — use a single top-level directory name.
• Reorganizing via config instead of filesystem. If you are tempted to add a custom sidebar config override, the underlying filesystem is probably wrong. Fix the files instead.
• Stuffing a category index.mdx with full content/prose. The index is a landing page — keep it to a short intro + <CategoryNav>.

When in Doubt

If you are not sure whether a page belongs in header, sidebar, or nested sidebar: map the current tree first (find doc/src/content/docs -name '*.mdx' | sort), draw out where the new page fits, and place it deliberately. Never add pages to "whatever directory is closest" without considering the whole structure.

Verify

After any navigation change, run pnpm build from doc/ and confirm the sidebar and header render as intended — the filesystem-to-navigation mapping is only proven by the build.