docs: consolidate exploration & audit reports under docs/ (TEC-3094)

- Move 8 stray .md (+5 .txt) from ~/Desktop into docs/explorations/from-desktop/ - Reorganize 27 .md/.txt at workspace root: - audit reports -> docs/audits/ - exploration reports -> docs/explorations/ - design system -> docs/design-system/ - Keep only README/CHANGELOG/CONTRIBUTING/CLAUDE at repo root - Refresh docs/README.md as canonical index with links to all groups - Note: pre-existing docs/audits/AUDIT_INDEX.md and AUDIT_SUMMARY.md were overwritten by the newer root-level versions during the move Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-21 16:29:24 +07:00
parent 912121cf09
commit 08b96f9c2d
39 changed files with 15129 additions and 562 deletions
--- a/docs/audits/README_AUDIT_FILES.md
+++ b/docs/audits/README_AUDIT_FILES.md
@@ -0,0 +1,251 @@
+# 📋 Design System Audit — File Index
+
+**Generated:** April 21, 2026  
+**Scope:** Homepage refactor preparation  
+**Status:** ✅ Complete
+
+---
+
+## 📄 Three Audit Documents
+
+### 1. **DESIGN_SYSTEM_AUDIT_2026_04_21.md** (680 lines)
+**The Complete Reference**
+
+Comprehensive, detailed breakdown of every aspect of the design system:
+
+- **Section 1-7:** Component-by-component documentation (props, features, styling)
+- **Section 2:** Complete design token reference (colors, typography, spacing, animations)
+- **Section 3:** Full analytics API interface documentation
+- **Section 4:** React Query hooks and cache keys
+- **Section 5:** Chart components (Recharts implementations)
+- **Section 6:** Map components (Mapbox integrations)
+- **Section 7:** Map styling and theming
+- **Section 8:** Key patterns and best practices
+- **Section 9:** Export paths for integration
+- **Section 10:** Homepage refactor checklist
+
+**Use this for:** Deep dives, integration planning, architecture decisions
+
+---
+
+### 2. **DESIGN_SYSTEM_QUICK_REFERENCE.md** (241 lines)
+**The Developer's Cheat Sheet**
+
+Quick lookup and copy-paste code examples:
+
+- **Component Examples:** StatCard, PriceDelta, MarketIndex, DataTable, TickerStrip, DashboardLayout
+- **Design Tokens:** Colors, typography, spacing cheat sheet
+- **API Usage:** Raw calls and React Query hooks
+- **Charts:** Code snippets for each chart type
+- **Maps:** Examples of heatmap, listing map, location picker
+- **Best Practices:** Do's and don'ts
+- **Environment Setup:** Required ENV variables
+
+**Use this for:** Rapid prototyping, code copy-paste, quick lookups
+
+---
+
+### 3. **AUDIT_SUMMARY.md** (291 lines)
+**The Executive Summary**
+
+High-level overview for decision-makers and project leads:
+
+- **Quick Stats:** 7 components, 30+ tokens, 6+ API endpoints
+- **File Structure:** Directory tree showing organization
+- **Component Catalog:** High-level category overview
+- **Design Tokens:** Grouped by purpose (colors, typography, spacing, animations)
+- **Analytics API:** 6 main endpoints with quick reference table
+- **Key Patterns:** Design system philosophy and conventions
+- **What's Ready:** Production-ready checklist
+- **Considerations:** Important notes and gotchas
+- **Integration Checklist:** Testing and deployment steps
+- **Next Steps:** Recommended actions
+
+**Use this for:** Planning, reviews, stakeholder communication, status updates
+
+---
+
+## 🗂️ Component Organization
+
+```
+Design System (7 components)
+├── StatCard           — KPI metric display with delta
+├── PriceDelta         — % change with directional arrows
+├── MarketIndex        — Hero index value (large)
+├── DataTable          — Sortable, sticky-header table
+├── CompactHeader      — Terminal-style navbar (48px)
+├── DashboardLayout    — Full-page frame with sidebar + ticker
+└── TickerStrip        — Auto-scrolling ticker animation
+
+Charts (3 types)
+├── PriceTrendChart    — Dual Y-axis line chart
+├── DistrictBarChart   — Rotated-axis bar chart
+└── AgentPerformance   — Mixed KPI + funnel dashboard
+
+Maps (3 implementations)
+├── DistrictHeatmap    — Sized + colored district circles
+├── ListingMap         — Clickable price marker bubbles
+└── LocationPicker     — Interactive map selection + geocoding
+```
+
+---
+
+## 🎨 Design Token Snapshot
+
+| Category | Count | Reference |
+|----------|-------|-----------|
+| **Color Variables** | 30+ | Light/dark modes via CSS vars |
+| **Typography** | 2 fonts, 4 scales | Inter + JetBrains Mono |
+| **Spacing** | 3 custom | h-row, h-ticker-bar, h-header-compact |
+| **Shadows** | 2 levels | elevation-1, elevation-2 |
+| **Animations** | 3 types | ticker-scroll, signal-flash-up/down |
+
+---
+
+## 🔗 Quick Links Within Docs
+
+### In DESIGN_SYSTEM_AUDIT_2026_04_21.md
+- **[Jump to Design System Components](#1-design-system-components)** → Section 1
+- **[Jump to Design Tokens](#2-design-tokens--theme-system)** → Section 2
+- **[Jump to Analytics API](#3-analytics-api)** → Section 3
+- **[Jump to Charts](#5-chart-components-recharts)** → Section 5
+- **[Jump to Maps](#6-map-components-mapbox)** → Section 6
+
+### In DESIGN_SYSTEM_QUICK_REFERENCE.md
+- **[Component Examples](#quick-examples)** — Copy-paste code
+- **[Design Tokens](#design-tokens)** — CSS variable reference
+- **[Analytics API](#analytics-api)** — Hook usage
+- **[Best Practices](#best-practices)** — Don't-s
+
+### In AUDIT_SUMMARY.md
+- **[Component Catalog](#component-catalog)** — Overview table
+- **[Design Tokens Summary](#design-tokens)** — Grouped reference
+- **[Integration Checklist](#-integration-checklist)** — Testing steps
+- **[Export Reference](#export-reference)** — Import paths
+
+---
+
+## ✅ What You'll Find
+
+### For Product/Design
+- Color palettes (light + dark modes)
+- Component purposes and use cases
+- Design philosophy (explicit props, accessibility-first)
+- Token naming conventions
+- Spacing and sizing guidelines
+
+### For Frontend Developers
+- Full TypeScript interfaces
+- Component prop documentation
+- Copy-paste code examples
+- Query hooks with React Query
+- API endpoint signatures
+- Import paths
+
+### For Backend/Product Managers
+- Analytics API endpoints
+- Data structures and contracts
+- POI categories and filters
+- AI confidence levels
+- Cache hit tracking
+
+### For QA/Testing
+- Responsive breakpoints
+- Dark/light mode toggle points
+- Accessibility selectors (`[data-numeric]`, `aria-hidden`)
+- Chart data formats
+- Map fallback states
+
+---
+
+## 🚀 Getting Started
+
+1. **Start here:** Read **AUDIT_SUMMARY.md** (10 min) — gets you oriented
+2. **Deep dive:** Open **DESIGN_SYSTEM_AUDIT_2026_04_21.md** — reference as needed
+3. **Code time:** Use **DESIGN_SYSTEM_QUICK_REFERENCE.md** — copy-paste examples
+4. **Integrate:** Follow checklist in AUDIT_SUMMARY.md
+
+---
+
+## 📊 Statistics
+
+| Metric | Value |
+|--------|-------|
+| **Total Lines** | 1,212 |
+| **Components Documented** | 13 (7 design system + 3 charts + 3 maps) |
+| **API Endpoints** | 6+ |
+| **Design Tokens** | 30+ |
+| **Code Examples** | 25+ |
+| **Best Practices** | 10+ |
+| **Integration Notes** | Comprehensive |
+
+---
+
+## 🔍 Key Highlights
+
+### ✨ Design System Strengths
+1. **Fully typed TypeScript** — strong IDE support
+2. **Semantic HTML** — accessibility-first
+3. **Dark/light theme** — CSS variables, not hardcoded
+4. **Responsive by default** — mobile-first
+5. **Consistent patterns** — explicit props, no prop spreading
+6. **Theme-aware charts** — HSL variables for dynamic theming
+7. **Mapbox fallbacks** — graceful degradation
+
+### ⚙️ Integration Ready
+1. **All components exported** — central index.ts barrel export
+2. **Query keys cached** — React Query factory pattern
+3. **API fully documented** — TypeScript interfaces
+4. **No external deps** — uses only Recharts + Mapbox (already included)
+5. **CSS vars integrated** — Tailwind + globals.css
+
+### 📋 Missing Pieces (For Homepage Refactor)
+1. **TEC-3030 design spec** — check project management
+2. **Homepage layout** — design system is for dashboards
+3. **Marketing copy** — component docs only
+4. **Backend endpoints** — mock data shown in AgentPerformance
+
+---
+
+## 💡 Recommended Next Steps
+
+**Phase 1: Review** (1-2 hours)
+- [ ] Read AUDIT_SUMMARY.md
+- [ ] Skim DESIGN_SYSTEM_AUDIT sections 1-2
+- [ ] Review Quick Reference code examples
+
+**Phase 2: Plan** (2-4 hours)
+- [ ] Identify which components fit homepage
+- [ ] Map analytics endpoints to page sections
+- [ ] Create wireframe composition sketch
+- [ ] Document TEC-3030 requirements
+
+**Phase 3: Build** (1-2 days)
+- [ ] Create homepage layout wrapper
+- [ ] Compose components with real data
+- [ ] Test dark/light mode
+- [ ] Mobile responsive verification
+
+**Phase 4: Deploy** (depends on CI/CD)
+- [ ] Performance profile with real data
+- [ ] Accessibility audit (WCAG 2.1 AA)
+- [ ] Cross-browser testing
+- [ ] Mobile device testing
+
+---
+
+## 📞 Questions?
+
+Refer to the appropriate document:
+- **"How do I use X component?"** → QUICK_REFERENCE.md
+- **"What props does X component have?"** → AUDIT_2026_04_21.md (Section 1)
+- **"What colors are available?"** → AUDIT_2026_04_21.md (Section 2) or QUICK_REFERENCE.md
+- **"What API endpoints exist?"** → AUDIT_2026_04_21.md (Section 3) or QUICK_REFERENCE.md
+- **"Should I hardcode colors or use tokens?"** → AUDIT_2026_04_21.md (Section 8)
+- **"How do I set up Mapbox?"** → QUICK_REFERENCE.md or AUDIT_2026_04_21.md (Section 6)
+- **"What's the integration timeline?"** → AUDIT_SUMMARY.md (Integration Checklist)
+
+---
+
+**Last Updated:** April 21, 2026  
+**All components production-ready. Happy coding! 🚀**