Internal docs: generate comprehensive documentation system

[sujaypawar]

Summary

Creates a comprehensive internal documentation system to help developers understand the codebase and assist AI agents in working effectively with Force UI.

Documentation Added (13 Files)

• README.md: Project overview, quick start, and navigation guide
• product-vision.md: Product goals, user personas, competitive landscape, roadmap
• architecture.md: High-level architecture, build system, component patterns
• codebase-map.md: Folder-by-folder guide with file purposes and navigation tips
• apis.md: Component APIs, hooks, utilities, type definitions, and usage examples
• coding-standards.md: TypeScript/React conventions, styling rules, best practices
• ui-and-copy.md: Design system principles, color tokens, microcopy guidelines
• onboarding.md: 1-hour, 1-day, 1-week developer learning paths
• ai-agent-guide.md: Instructions for AI coding agents (Claude, Copilot, etc.)
• troubleshooting.md: Common issues, error messages, and solutions
• faq.md: Frequently asked questions about Force UI
• glossary.md: Technical terms, acronyms, and component definitions
• maintenance.md: How to keep documentation updated

Target Audiences

1. New Developers - Fast onboarding with clear architecture and conventions
2. Existing Developers - Reference for patterns, APIs, and project structure
3. AI Coding Agents - Deep understanding of product intent, UX, and technical patterns

Build System Updates

• Added `internal-docs/` to `.distignore` for WordPress.org releases
• Verified internal docs excluded from release builds
• Documented in `codebase-map.md` that internal-docs are development-only

Content Highlights

Comprehensive Coverage:

• 40+ component API references with TypeScript examples
• Complete architecture diagrams and build flow
• TypeScript patterns, Tailwind usage, accessibility guidelines
• Troubleshooting guide with real error messages and solutions
• Glossary with 50+ technical terms

Developer-Friendly:

• Structured learning paths (1-hour to 1-week)
• Code examples tested against actual codebase
• Cross-referenced between docs for easy navigation
• Markdown formatted for readability

AI-Optimized:

• Dedicated AI agent guide with coding patterns
• Clear "do's and don'ts" for AI-generated code
• Component templates for consistent code generation
• Pattern matching examples

Verification

Documentation has been:

• ✅ Created in `internal-docs/` directory
• ✅ Content derived from actual codebase (no assumptions)
• ✅ Excluded from releases via `.distignore`
• ✅ No secrets or sensitive data included
• ✅ Cross-references verified
• ✅ Code examples tested

To verify exclusion from releases:

```bash

Build the library

npm run build

Create release package

npm run package

Verify internal-docs not in ZIP

unzip -l force-ui.zip | grep internal-docs

Should return nothing

```

Benefits

• Faster Onboarding: New developers productive in hours, not days
• Better Code Quality: Clear standards reduce inconsistencies
• AI Effectiveness: AI agents generate code matching project patterns
• Knowledge Preservation: Captures tribal knowledge in written form
• Self-Service: Developers find answers without asking teammates

Next Steps

After merge:

1. Share documentation with team
2. Gather feedback for improvements
3. Set up quarterly review schedule (per `maintenance.md`)
4. Update docs as codebase evolves

---

Generated with dev-docs skill

🤖 Co-Authored-By: Claude Sonnet 4.5

[github-actions]

Great job! ✅ The PR looks solid with no security or performance issues.

Please make sure to resolve any remaining comments if any. Approved 👍