chore(repo): phase-7 structural cleanup

[mmorerasanchez]

Summary

• Flatten 6 reference docs (design-system, architecture, principles, theming, tokens, migration) into docs/reference/
• Fix scripts/generate-tokens.mjs: write to tokens/design-tokens.json (not root), drop src/index.css fallback, fix $description string
• Fix scripts/generate-counts.mjs: drop src/ fallbacks, use registry/ + tokens/ directly
• Delete root design-tokens.json (now generated into tokens/)
• Delete USAGE.md; fold content into README.md License & Usage section
• Update all stale reference links across README, CLAUDE.md, docs/**/*.md to new docs/reference/ paths
• Fix both tests/tokens.test.ts and tests/tokens.contract.test.ts to read from tokens/design-tokens.json
• Verify internal-file gitignore guard (PHASE-*.md, audits/, prompts); no internal files tracked

Test plan

• npm run build green — counts: atoms:11 molecules:18 organisms:19 templates:7 ui:48
• tokens/design-tokens.json generated; root design-tokens.json absent
• npm test — 125 tests passing (4 suites)
• grep -rn "src/components\|src/index.css" scripts/ tests/ → only intentional shadcn consumer-path docs (lines 50-51 of build-registry.mjs)
• git ls-files | grep -iE "PHASE-|audit|testing-session|prompt" → empty

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Reorganized documentation structure by consolidating guides into a new docs/reference/ section with updated links across all documentation files.
  • Updated "License & Usage" section in README with clarified MIT licensing terms and contact information.
  • Removed outdated USAGE.md content.

• Chores

  • Relocated design tokens file to organized directory structure.
  • Updated build and generation scripts to reference new token paths.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2d51cff6-de9c-44c9-891b-55da9395b105

📥 Commits

Reviewing files that changed from the base of the PR and between 915b2df and ae5c75c.

📒 Files selected for processing (24)

• CLAUDE.md
• DESIGN.md
• README.md
• USAGE.md
• design-tokens.json
• docs/README.md
• docs/ai/ai-context.md
• docs/ai/ai-usage.md
• docs/ai/claude-design.md
• docs/ai/stitch.md
• docs/guides/customization-guides.md
• docs/guides/getting-started.md
• docs/reference/architecture.md
• docs/reference/design-system.md
• docs/reference/migration.md
• docs/reference/principles.md
• docs/reference/theming.md
• docs/reference/tokens.md
• scripts/build-registry.mjs
• scripts/generate-counts.mjs
• scripts/generate-tokens.mjs
• tests/tokens.contract.test.ts
• tests/tokens.test.ts
• tokens/design-tokens.json

---

📝 Walkthrough

Walkthrough

design-tokens.json is removed from the repo root and relocated to tokens/design-tokens.json. Generation scripts (generate-tokens.mjs, generate-counts.mjs) drop filesystem fallbacks and hardcode tokens/index.css as the source and tokens/design-tokens.json as the output. Tests update their fixture paths accordingly. Separately, all documentation cross-links pointing to docs/*.md are updated to docs/reference/*.md across root docs, guides, and AI context files. USAGE.md has its usage section removed, with equivalent content absorbed into README.md.

Changes

Token file relocation

Layer / File(s)	Summary
Token generation and counting scripts scripts/generate-tokens.mjs, scripts/generate-counts.mjs, scripts/build-registry.mjs	generate-tokens.mjs drops existsSync, hardcodes tokens/index.css as source, and writes output to tokens/design-tokens.json. generate-counts.mjs removes the existsSync import and conditional fallbacks, fixing tierDir and cssPath to registry/tokens paths. build-registry.mjs updates an inline comment only.
Token artifact move and test fixture updates design-tokens.json, tokens/design-tokens.json, tests/tokens.test.ts, tests/tokens.contract.test.ts	design-tokens.json is removed from the repo root. tokens/design-tokens.json has its $description date updated to 2026-06-18. Both test files update readFileSync paths to ../tokens/design-tokens.json.

Documentation link migration to docs/reference/*

Layer / File(s)	Summary
Root-level doc link and license updates README.md, USAGE.md, CLAUDE.md, DESIGN.md	README.md updates theming/resource links to docs/reference/* and tokens/design-tokens.json, and rewrites the License & Usage section with explicit MIT text, a paid-kit redistribution restriction, and a contact email. USAGE.md removes its entire Usage section. CLAUDE.md updates three doc links. DESIGN.md bumps its date.
docs/README.md index and guide link updates docs/README.md, docs/guides/getting-started.md, docs/guides/customization-guides.md, docs/reference/architecture.md	Guides table in docs/README.md is rewritten to use ./reference/* paths. Getting-started and customization-guides update Further Reading and See Also links. docs/reference/architecture.md updates its Further Reading links.
AI context and tool docs link updates docs/ai/ai-context.md, docs/ai/ai-usage.md, docs/ai/claude-design.md, docs/ai/stitch.md	All four AI docs update token, theming, design-system, and architecture links from docs/* to docs/reference/*.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop, hop, the tokens found a home,
No more root-level fields to roam.
tokens/ folder, neat and bright,
Reference paths now set aright.
The rabbit tidied every link—
Docs and scripts all in sync! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/phase-7-structure

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}