From 98aa75b614e0d1052d552615c6f9fb682c61c4aa Mon Sep 17 00:00:00 2001
From: mohiit1502 <mohiit1502@gmail.com>
Date: Sun, 4 Jan 2026 20:37:41 +0530
Subject: [PATCH] chore: add comprehensive documentation

- Add docs/SPECS.md, DESIGN.md, DEBT.md, READINESS.md
- Update README.md with comprehensive documentation
---
 README.md         |  95 ++++++++++++++++++-
 docs/DEBT.md      | 234 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/DESIGN.md    | 175 ++++++++++++++++++++++++++++++++++
 docs/READINESS.md | 234 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/SPECS.md     | 174 ++++++++++++++++++++++++++++++++++
 5 files changed, 911 insertions(+), 1 deletion(-)
 create mode 100644 docs/DEBT.md
 create mode 100644 docs/DESIGN.md
 create mode 100644 docs/READINESS.md
 create mode 100644 docs/SPECS.md

diff --git a/README.md b/README.md
index b24d5e3..a560935 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,94 @@
-# Armco Template for the tech stack: React, TS, Dart Sass, Redux Tookkit, react-redux, react browser routing, TS based plop generator
\ No newline at end of file
+# @armco/font-spot
+
+> Font Browser UI for Armco Platform
+
+font-spot is a React-based font browser that provides browsing, searching, and previewing capabilities for fonts served by ArmoryStatic.
+
+## Features
+
+- **Font Grid**: Visual font browser with live preview
+- **Search**: Text search with debounce
+- **Pagination**: Page-based navigation
+- **Live Preview**: Fonts render in their own typeface
+
+## Installation
+
+```bash
+pnpm add @armco/font-spot
+```
+
+## Peer Dependencies
+
+```json
+{
+  "@armco/components": "^0.0.60",
+  "@armco/configs": "^0.0.11",
+  "@armco/types": "^0.0.18",
+  "@armco/utils": "^0.0.29",
+  "react": "^18.2.0",
+  "react-dom": "^18.2.0"
+}
+```
+
+## Usage
+
+```tsx
+import Fonts from "@armco/font-spot"
+
+function App() {
+  return (
+    <div className="h-100">
+      <Fonts />
+    </div>
+  )
+}
+```
+
+## Exported Components
+
+| Component | Description |
+|-----------|-------------|
+| `Fonts` | Main font browser container |
+| `FontsList` | Font grid with search and pagination |
+| `FontTile` | Individual font preview card |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Build library
+pnpm build
+```
+
+## Project Structure
+
+```
+src/
+├── Fonts.tsx          # Main container
+├── FontsList.tsx      # Font grid
+├── FontTile.tsx       # Font card
+└── types.ts           # TypeScript types
+```
+
+## How It Works
+
+1. On mount, fetches font list from ArmoryStatic `/font/page` endpoint
+2. Response includes font names and `@font-face` CSS rules
+3. CSS is injected into document head as `<style>` element
+4. Each font tile displays the font name in its own typeface
+
+## Documentation
+
+- [SPECS.md](docs/SPECS.md) - Feature specifications
+- [DESIGN.md](docs/DESIGN.md) - Architecture diagrams
+- [DEBT.md](docs/DEBT.md) - Technical debt register
+- [READINESS.md](docs/READINESS.md) - Production checklist
+
+## License
+
+ISC
diff --git a/docs/DEBT.md b/docs/DEBT.md
new file mode 100644
index 0000000..ce6e619
--- /dev/null
+++ b/docs/DEBT.md
@@ -0,0 +1,234 @@
+# font-spot - Technical Debt Register
+
+## 🔴 Critical (Must Fix Before Production)
+
+### 1. Console.error in Production Code
+**Location:** `src/FontsList.tsx` (Line ~50)
+**Issue:** Error logged to console
+```typescript
+.catch((error) => {
+  console.error(error)
+  setLoading(false)
+})
+```
+**Risk:** Pollutes browser console, exposes internal errors
+**Resolution:** Replace with proper error handling UI
+**Effort:** Low (1-2 hours)
+
+---
+
+### 2. No Error State or User Feedback
+**Location:** `src/FontsList.tsx`
+**Issue:** API errors silently swallowed, user sees no feedback
+**Current behavior:** Loading stops, empty grid shown
+**Risk:** Poor user experience, silent failures
+**Resolution:** Add error state and error message component
+**Effort:** Low (2-3 hours)
+
+---
+
+### 3. Memory Leak: Style Elements Not Cleaned Up
+**Location:** `src/FontsList.tsx` (Lines ~42-47)
+**Issue:** New `<style>` element appended on every fetch
+```typescript
+const styleElement = document.createElement("style")
+styleElement.type = "text/css"
+styleElement.appendChild(document.createTextNode(content.returnFontGroups))
+document.head.appendChild(styleElement)
+```
+**Risk:** Multiple style elements accumulate, causing memory leak
+**Resolution:** Track and replace previous style element or use ID
+**Effort:** Low (1-2 hours)
+
+---
+
+## 🟠 High Priority
+
+### 4. Compact Toggle Non-Functional
+**Location:** `src/FontsList.tsx` (Lines ~85-89)
+**Issue:** Toggle exists but does nothing
+```tsx
+<Toggle
+  onChange={() => { }}
+  toggleOnName="Compact"
+  toggleOffName="Compact"
+/>
+```
+**Risk:** Misleading UI, broken user expectation
+**Resolution:** Implement compact view or remove toggle
+**Effort:** Medium (4-6 hours)
+
+---
+
+### 5. Upload Button Non-Functional
+**Location:** `src/FontsList.tsx` (Lines ~80-84)
+**Issue:** Upload button has no handler
+```tsx
+<Button
+  content="Upload"
+  variant={ArButtonVariants.SUCCESS}
+  // No onClick
+/>
+```
+**Risk:** Broken user expectation
+**Resolution:** Implement upload or remove button
+**Effort:** High (16+ hours to implement fully)
+
+---
+
+### 6. Commented Code
+**Location:** `src/FontsList.tsx` (Lines ~100-110, 130-135)
+**Issue:** Dead commented code left in file
+```typescript
+// fonts
+//   ? fonts.map(
+//       (font): SearchItem => ({
+//         label: font.name,
+//         data: font,
+//       }),
+//     )
+//   : []
+
+// trigger={ArPageTriggers.SCROLL}
+// dataFetcher={(load, count) =>
+//   fetchIconsPage(load, count, {}, setIcons, setPage, setLoading)
+// }
+```
+**Risk:** Code confusion, references wrong function name (`fetchIconsPage`)
+**Resolution:** Remove or complete implementation
+**Effort:** Low (30 minutes)
+
+---
+
+### 7. Search Autocomplete Disabled
+**Location:** `src/FontsList.tsx` (Line ~100)
+**Issue:** Search items hardcoded to empty array
+```typescript
+items={[]}
+```
+**Risk:** Inconsistent UX compared to icon-spot
+**Resolution:** Enable font name suggestions
+**Effort:** Low (2-3 hours)
+
+---
+
+## 🟡 Medium Priority
+
+### 8. No Unit Tests
+**Issue:** 0% test coverage
+**Files needing tests:**
+- `FontsList.tsx` - Fetch logic, pagination
+- `FontTile.tsx` - Rendering
+
+**Resolution:** Add Vitest tests
+**Effort:** Medium (8-12 hours)
+
+---
+
+### 9. Inconsistent Initial Fetch Sizes
+**Location:** `src/FontsList.tsx`
+**Issue:** Different page sizes for initial vs search
+```typescript
+// Initial load
+fetchFontsPage(30, 0, filters, ...)
+
+// On search
+fetchFontsPage(200, 0, filters, ...)
+```
+**Risk:** Inconsistent behavior
+**Resolution:** Use consistent pagination logic
+**Effort:** Low (1-2 hours)
+
+---
+
+### 10. Missing TypeScript Strictness
+**Location:** `src/types.ts`
+**Issue:** Props interfaces too minimal
+```typescript
+export interface FontTileProps {
+  font: string  // Should include optional handlers
+}
+```
+**Resolution:** Add onClick, onFavorite, etc.
+**Effort:** Low (1-2 hours)
+
+---
+
+### 11. No Loading Skeleton
+**Issue:** Only spinner shown during load
+**Current:** Full-page loader
+**Resolution:** Add skeleton tiles matching grid layout
+**Effort:** Low (2-3 hours)
+
+---
+
+### 12. No Font Detail View
+**Issue:** Clicking font tile does nothing useful
+**Current:** Cursor pointer but no action
+**Resolution:** Navigate to detail page or open modal
+**Effort:** Medium (8-12 hours)
+
+---
+
+## 🟢 Low Priority
+
+### 13. Outdated README
+**Location:** `README.md`
+**Issue:** Single line, no documentation
+**Resolution:** Update with proper documentation
+**Effort:** Low (2-3 hours)
+
+---
+
+### 14. Duplicate Background-Color in SCSS
+**Location:** `src/FontsList.component.scss`
+**Issue:** Duplicate property
+```scss
+.ar-FontsList__header-search-upload {
+  background-color: var(--ar-bg);       // ← First
+  color: var(--ar-colora);
+  background-color: var(--ar-bg-base);  // ← Duplicate
+}
+```
+**Resolution:** Remove duplicate
+**Effort:** Low (5 minutes)
+
+---
+
+### 15. Missing key Prop
+**Location:** `src/FontsList.tsx` (Line ~120)
+**Issue:** React key warning
+```tsx
+{(page as Array<string>).map((font) => (
+  <FontTile font={font} />  // Missing key={font}
+))}
+```
+**Resolution:** Add key prop
+**Effort:** Low (5 minutes)
+
+---
+
+### 16. Fixed Tile Size
+**Location:** `src/FontTile.component.scss`
+**Issue:** Hardcoded 8rem × 8rem size
+**Resolution:** Make configurable via props
+**Effort:** Low (1-2 hours)
+
+---
+
+## Debt Resolution Priority Matrix
+
+| Priority | Items | Total Effort |
+|----------|-------|--------------|
+| 🔴 Critical | 3 items | 4-7 hours |
+| 🟠 High | 4 items | 23-28 hours |
+| 🟡 Medium | 5 items | 20-31 hours |
+| 🟢 Low | 4 items | 5-8 hours |
+
+**Recommended Sprint 1 Focus:**
+1. Fix style element memory leak
+2. Add error state and user feedback
+3. Remove console.error
+4. Add missing key prop
+5. Remove or implement compact toggle
+6. Remove commented code
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
new file mode 100644
index 0000000..8d1165a
--- /dev/null
+++ b/docs/DESIGN.md
@@ -0,0 +1,175 @@
+# font-spot - Design Documentation
+
+## Component Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                             font-spot Application                                │
+│                                                                                  │
+│  ┌────────────────────────────────────────────────────────────────────────────┐ │
+│  │                              Fonts.tsx                                      │ │
+│  │                        (Container Component)                                │ │
+│  │  ┌──────────────────────────────────────────────────────────────────────┐  │ │
+│  │  │                        Main (Layout)                                  │  │ │
+│  │  │                   from @armco/shared-components                       │  │ │
+│  │  └───────────────────────────────┬──────────────────────────────────────┘  │ │
+│  └──────────────────────────────────┼─────────────────────────────────────────┘ │
+│                                     │                                            │
+│                                     ▼                                            │
+│  ┌────────────────────────────────────────────────────────────────────────────┐ │
+│  │                           FontsList.tsx                                     │ │
+│  │                        (List Component)                                     │ │
+│  │                                                                             │ │
+│  │  ┌────────────────────────────────────────────────────────────────────┐    │ │
+│  │  │                        Header Section                               │    │ │
+│  │  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │    │ │
+│  │  │  │   Upload     │  │   Toggle     │  │ SearchField  │              │    │ │
+│  │  │  │   Button     │  │  (Compact)   │  │              │              │    │ │
+│  │  │  └──────────────┘  └──────────────┘  └──────────────┘              │    │ │
+│  │  └────────────────────────────────────────────────────────────────────┘    │ │
+│  │                                                                             │ │
+│  │  ┌────────────────────────────────────────────────────────────────────┐    │ │
+│  │  │                     Font Tile Container                             │    │ │
+│  │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │    │ │
+│  │  │  │ FontTile │ │ FontTile │ │ FontTile │ │ FontTile │ │ FontTile │  │    │ │
+│  │  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │    │ │
+│  │  └────────────────────────────────────────────────────────────────────┘    │ │
+│  │                                                                             │ │
+│  │  ┌────────────────────────────────────────────────────────────────────┐    │ │
+│  │  │                        Pagination                                   │    │ │
+│  │  └────────────────────────────────────────────────────────────────────┘    │ │
+│  └─────────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Data Flow: Font Loading
+
+```
+┌───────────────┐     ┌───────────────┐     ┌───────────────┐
+│  Component    │────▶│   API Call    │────▶│  ArmoryStatic │
+│   Mount       │     │    get()      │     │    Backend    │
+└───────────────┘     └───────────────┘     └───────┬───────┘
+                                                     │
+                      ┌──────────────────────────────┘
+                      ▼
+              ┌───────────────────────────────────────────────┐
+              │            Response Processing                 │
+              │  1. Parse JSON body                           │
+              │  2. Extract fontNames[]                       │
+              │  3. Extract returnFontGroups (CSS)            │
+              └───────────────────┬───────────────────────────┘
+                                  │
+              ┌───────────────────┴───────────────────┐
+              │                                       │
+              ▼                                       ▼
+      ┌───────────────┐                      ┌───────────────┐
+      │ Create <style>│                      │  setFonts()   │
+      │ element with  │                      │  setPage()    │
+      │ @font-face    │                      │               │
+      └───────┬───────┘                      └───────┬───────┘
+              │                                       │
+              ▼                                       ▼
+      ┌───────────────┐                      ┌───────────────┐
+      │ Append to     │                      │ Render        │
+      │ document.head │                      │ FontTile x N  │
+      └───────────────┘                      └───────────────┘
+```
+
+---
+
+## Data Flow: Search
+
+```
+User types in SearchField
+        │
+        ▼ (debounce 1000ms)
+┌─────────────────┐
+│ setSearchText() │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ useEffect       │────▶│ fetchFontsPage  │
+│ (searchText)    │     │ with filter     │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                                 ▼
+                        ┌─────────────────┐
+                        │ Update fonts    │
+                        │ Update page     │
+                        │ Inject CSS      │
+                        └─────────────────┘
+```
+
+---
+
+## Feature Completion Matrix
+
+| Feature | Status | What's Done | What's Pending | Potential Additions |
+|---------|--------|-------------|----------------|---------------------|
+| **Font Grid** | ✅ Complete | Display with live preview | - | Configurable tile size |
+| **Search** | ✅ Complete | Debounced text search | - | Fuzzy matching |
+| **Pagination** | ✅ Complete | Page controls | Scroll pagination | Infinite scroll |
+| **Compact View** | ❌ Stub | Toggle UI exists | Toggle logic | Grid layout change |
+| **Upload** | ❌ Stub | Button exists | Upload flow | Font validation |
+| **Font Preview** | ⚠️ Basic | Font name in font | Sample text | Full specimen |
+| **Font Details** | ❌ Missing | - | Detail page | Styles, weights, glyphs |
+| **Font Download** | ❌ Missing | - | Download link | Format selection |
+| **Favorites** | ❌ Missing | - | Everything | Persistence |
+| **Categories** | ❌ Missing | - | Category API | Sidebar filter |
+| **Font Styles** | ❌ Missing | - | Style variants | Weight/style selector |
+
+---
+
+## Directory Structure
+
+```
+font-spot/
+├── src/
+│   ├── Fonts.tsx                  # Main container
+│   ├── FontsList.tsx              # Font grid with pagination
+│   ├── FontsList.component.scss   # Grid styles
+│   ├── FontTile.tsx               # Font preview card
+│   ├── FontTile.component.scss    # Card styles
+│   ├── types.ts                   # TypeScript types
+│   ├── Test.tsx                   # Development test
+│   ├── react-app-env.d.ts         # React types
+│   └── vite-env.d.ts              # Vite types
+│
+├── build-tools/
+│   └── build.sh                   # Build script
+│
+├── vite.config.ts                 # Library build config
+├── vite-dev.config.ts             # Dev server config
+├── vite-run.config.ts             # Standalone run config
+├── tsconfig.json                  # TypeScript config
+└── package.json                   # Package definition
+```
+
+---
+
+## Component Props Summary
+
+| Component | Props |
+|-----------|-------|
+| `Fonts` | None (self-contained) |
+| `FontsList` | `classes?` |
+| `FontTile` | `font: string` |
+
+---
+
+## State Management
+
+Unlike icon-spot, font-spot uses **local component state only**:
+
+```typescript
+// FontsList.tsx state
+const [searchText, setSearchText] = useState<string>()
+const [fonts, setFonts] = useState<ArrayType>()      // All fonts
+const [page, setPage] = useState<ArrayType>()        // Current page
+const [loading, setLoading] = useState<boolean>()
+```
+
+No Redux store is required for font-spot.
diff --git a/docs/READINESS.md b/docs/READINESS.md
new file mode 100644
index 0000000..499cecb
--- /dev/null
+++ b/docs/READINESS.md
@@ -0,0 +1,234 @@
+# font-spot - Production Readiness Checklist
+
+## Overview
+
+This document tracks production readiness for font-spot as a standalone application and as an npm package consumed by other Armco applications.
+
+---
+
+## 1. Build & Packaging
+
+| Item | Status | Notes |
+|------|--------|-------|
+| ESM Build | ✅ | `build/es/` output |
+| CJS Build | ✅ | `build/cjs/` output |
+| Type Definitions | ✅ | `build/types/` output |
+| CSS Injection | ✅ | Using `vite-plugin-lib-inject-css` |
+| Tree Shaking | ✅ | Configured in rollup |
+| External Dependencies | ✅ | React, armco libs externalized |
+| Source Maps | ❌ | Not generated |
+| Bundle Size Analysis | ❌ | Not configured |
+
+### Actions Required:
+- [ ] Enable source maps for debugging
+- [ ] Add bundle size monitoring
+
+---
+
+## 2. Code Quality
+
+| Item | Status | Notes |
+|------|--------|-------|
+| TypeScript Strict Mode | ⚠️ | Minimal types |
+| ESLint Configured | ✅ | Via eslintConfig in package.json |
+| Prettier Configured | ✅ | Using prettier-config-nick |
+| No Console Statements | ❌ | console.error in code |
+| Error Boundaries | ❌ | No error boundaries |
+| PropTypes/Type Safety | ⚠️ | Basic types only |
+
+### Actions Required:
+- [ ] Remove console.error statements
+- [ ] Add error handling
+- [ ] Enhance TypeScript types
+
+---
+
+## 3. Testing
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Unit Tests | ❌ | 0% coverage |
+| Component Tests | ❌ | No tests |
+| Integration Tests | ❌ | No tests |
+| Visual Regression | ❌ | No Storybook |
+
+### Actions Required:
+- [ ] Add Vitest configuration
+- [ ] Write component tests
+- [ ] Consider Storybook setup
+
+---
+
+## 4. Accessibility
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Semantic HTML | ⚠️ | Basic div structure |
+| ARIA Labels | ❌ | Missing |
+| Keyboard Navigation | ❌ | Not implemented |
+| Screen Reader Testing | ❌ | Not tested |
+
+### Actions Required:
+- [ ] Add ARIA labels
+- [ ] Implement keyboard navigation for grid
+- [ ] Test with screen reader
+
+---
+
+## 5. Performance
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Lazy Loading | ❌ | Not implemented |
+| Virtual Scrolling | ❌ | All fonts rendered |
+| Memoization | ❌ | No useMemo/useCallback |
+| Memory Leaks | 🔴 | Style elements accumulate |
+
+### Actions Required:
+- [ ] Fix style element memory leak
+- [ ] Implement virtual scrolling
+- [ ] Add React.memo to FontTile
+
+---
+
+## 6. Error Handling
+
+| Item | Status | Notes |
+|------|--------|-------|
+| API Error Handling | ❌ | Errors swallowed |
+| User Error Messages | ❌ | No error UI |
+| Retry Logic | ❌ | No retry |
+| Loading States | ⚠️ | Basic spinner |
+
+### Actions Required:
+- [ ] Add error state to component
+- [ ] Display error messages to user
+- [ ] Add retry button
+
+---
+
+## 7. Features Completeness
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Font Grid | ✅ | Working |
+| Search | ✅ | Working |
+| Pagination | ✅ | Working |
+| Compact View | ❌ | UI only, not functional |
+| Upload | ❌ | Button only |
+| Font Details | ❌ | Not implemented |
+| Download | ❌ | Not implemented |
+
+### Actions Required:
+- [ ] Remove non-functional UI elements
+- [ ] Or implement missing features
+
+---
+
+## 8. Documentation
+
+| Item | Status | Notes |
+|------|--------|-------|
+| README | ✅ | Comprehensive docs added |
+| API Documentation | ❌ | None |
+| Usage Examples | ✅ | Provided in README |
+| Changelog | ❌ | Not maintained |
+
+### Actions Required:
+- [x] ~~Write comprehensive README~~ ✅ DONE
+- [ ] Add JSDoc comments
+- [ ] Maintain CHANGELOG.md
+
+---
+
+## 9. Security
+
+| Item | Status | Notes |
+|------|--------|-------|
+| XSS Prevention | ⚠️ | Dynamic CSS injection |
+| Dependency Audit | ⚠️ | Needs npm audit |
+| CORS Handling | ⚠️ | Backend configured |
+
+### Actions Required:
+- [ ] Validate CSS content before injection
+- [ ] Run npm audit fix
+
+---
+
+## Production Readiness Score
+
+| Category | Score | Max |
+|----------|-------|-----|
+| Build & Packaging | 5 | 8 |
+| Code Quality | 2 | 6 |
+| Testing | 0 | 4 |
+| Accessibility | 0.5 | 4 |
+| Performance | 0 | 4 |
+| Error Handling | 0.5 | 4 |
+| Features | 3 | 7 |
+| Documentation | 0 | 4 |
+| Security | 1 | 3 |
+| **Total** | **12** | **44** |
+
+**Readiness Level: 27% - NOT READY FOR PRODUCTION**
+
+---
+
+## Minimum Viable Production Checklist
+
+### Week 1: Critical Fixes
+- [ ] Fix style element memory leak
+- [ ] Add error state and user feedback
+- [ ] Remove console.error
+- [ ] Add missing React key prop
+
+### Week 2: UI Cleanup
+- [ ] Remove non-functional compact toggle
+- [ ] Remove non-functional upload button
+- [ ] Or implement them
+- [ ] Remove commented code
+
+### Week 3: UX Improvements
+- [ ] Add loading skeletons
+- [ ] Enable search autocomplete
+- [ ] Add font click action
+
+### Week 4: Documentation & Testing
+- [ ] Update README
+- [ ] Add basic component tests
+- [ ] Run npm audit
+
+---
+
+## Package Consumption Checklist
+
+For apps consuming `@armco/font-spot`:
+
+| Requirement | Provided |
+|-------------|----------|
+| Peer dependencies documented | ✅ |
+| Type definitions | ✅ |
+| CSS bundled | ✅ |
+| Tree-shakeable | ✅ |
+| No Redux required | ✅ |
+| No Router required | ✅ |
+
+### Integration Requirements:
+1. Configure ArmoryStatic API endpoint in environment
+2. Ensure `@armco/configs` has STATIC_HOST configured
+3. Include in React application tree
+
+---
+
+## Comparison with icon-spot
+
+| Aspect | font-spot | icon-spot |
+|--------|-----------|-----------|
+| Components | 3 | 12+ |
+| Redux | No | Yes |
+| Features | Basic | Extensive |
+| Test Coverage | 0% | 0% |
+| Readiness | 27% | 25% |
+| Complexity | Low | High |
+
+font-spot is simpler and requires less setup, but also has fewer features.
diff --git a/docs/SPECS.md b/docs/SPECS.md
new file mode 100644
index 0000000..19c5be2
--- /dev/null
+++ b/docs/SPECS.md
@@ -0,0 +1,174 @@
+# font-spot - Feature Specifications
+
+## Overview
+
+**font-spot** is a React-based font browser application for the Armco platform. It provides a visual interface for browsing, searching, and previewing fonts served by the ArmoryStatic backend.
+
+---
+
+## Technology Stack
+
+| Component | Technology | Version |
+|-----------|------------|---------|
+| UI Framework | React | 18/19 |
+| Build Tool | Vite | 7.x |
+| Styling | SCSS (Dart Sass) | 1.x |
+| Language | TypeScript | 5.x |
+| Package Format | ESM + CJS | - |
+
+---
+
+## Exported Components
+
+| Component | Description | Export Path |
+|-----------|-------------|-------------|
+| `Fonts` | Main font browser container | `@armco/font-spot` (default) |
+| `FontsList` | Font grid with search and pagination | `@armco/font-spot/FontsList` |
+| `FontTile` | Individual font preview card | `@armco/font-spot/FontTile` |
+
+---
+
+## Features
+
+### 1. Font Browser (`Fonts.tsx` → `FontsList.tsx`)
+
+**Description:** Grid view for browsing all available fonts with live preview
+
+**Capabilities:**
+- Paginated font grid (30 fonts initial, 200 on search)
+- Dynamic @font-face injection
+- Text search with debounce (1 second)
+- Compact view toggle (UI only)
+- Pagination controls
+
+**API Integration:**
+- `GET /font/page?pageSize=30&from=0` - Fetch fonts page
+
+**Response Processing:**
+1. Parse JSON response containing `fontNames` and `returnFontGroups`
+2. Inject `returnFontGroups` as `<style>` element into document head
+3. Display font names in grid with applied font-family
+
+---
+
+### 2. Font Tile (`FontTile.tsx`)
+
+**Description:** Individual font preview card
+
+**Display:**
+- 8rem × 8rem fixed size card
+- Font name displayed in that font's typeface
+- Border with hover cursor
+
+**Props:**
+```typescript
+interface FontTileProps {
+  font: string  // Font family name
+}
+```
+
+---
+
+### 3. Search Functionality
+
+**Description:** Real-time font search
+
+**Behavior:**
+- Debounced input (1000ms delay)
+- Triggers new API call with `search` parameter
+- Updates grid with filtered results
+
+---
+
+### 4. Pagination
+
+**Description:** Page-based navigation
+
+**Configuration:**
+- Max pills to show: 5
+- Initial page size: 30
+- Search page size: 200
+
+---
+
+## API Endpoints Used
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/font/page` | Paginated font list |
+
+**Query Parameters:**
+- `pageSize` - Number of fonts per page
+- `from` - Starting index
+- `search` - Text filter (optional)
+
+**Response Format:**
+```json
+{
+  "fontNames": ["Roboto", "Open Sans", ...],
+  "returnFontGroups": "@font-face { ... }"
+}
+```
+
+---
+
+## Peer Dependencies
+
+```json
+{
+  "@armco/components": "^0.0.60",
+  "@armco/configs": "^0.0.11",
+  "@armco/types": "^0.0.18",
+  "@armco/utils": "^0.0.29",
+  "react": "^18.2.0",
+  "react-dom": "^18.2.0",
+  "react-redux": "^8.0.1",
+  "react-router-dom": "^6.13.0"
+}
+```
+
+---
+
+## Build Output
+
+```
+build/
+├── cjs/          # CommonJS modules
+│   └── Fonts.js  # Main entry
+├── es/           # ES modules
+│   └── Fonts.js  # Main entry
+└── types/        # TypeScript declarations
+    └── Fonts.d.ts
+```
+
+---
+
+## Styling
+
+### CSS Variables Used
+
+| Variable | Purpose |
+|----------|---------|
+| `--ar-bg` | Background color |
+| `--ar-bg-base` | Base background |
+| `--ar-color` | Text color |
+| `--ar-colora` | Alternate text color |
+
+### BEM Naming
+
+- `.ar-Fonts` - Root container
+- `.ar-FontsList` - List container
+- `.ar-FontsList__header-search-upload` - Header section
+- `.ar-FontsList__font-tile-container` - Grid container
+- `.ar-FontTile` - Individual tile
+
+---
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `vite.config.ts` | Library build configuration |
+| `vite-dev.config.ts` | Development server |
+| `vite-run.config.ts` | Standalone run mode |
+| `tsconfig.json` | TypeScript configuration |