164 lines
6.2 KiB
Markdown
164 lines
6.2 KiB
Markdown
# TypoGenie - AI Coding Agent Guide
|
||
|
||
## Project Overview
|
||
|
||
TypoGenie is a web application that transforms Markdown content into professionally formatted Microsoft Word documents. Users upload `.md` or `.txt` files, select from 40+ typography styles across multiple categories (Minimalist, Corporate, Editorial, Tech, Creative, etc.), and download a formatted `.docx` file.
|
||
|
||
The application uses a local Markdown parser (marked) rather than AI for document conversion, though it was originally designed with AI integration in mind.
|
||
|
||
## Technology Stack
|
||
|
||
- **Framework**: React 19.2.4 with TypeScript 5.8.2
|
||
- **Build Tool**: Vite 6.2.0
|
||
- **Styling**: Tailwind CSS (loaded via CDN in `index.html`)
|
||
- **Icons**: Lucide React
|
||
- **Document Generation**: docx library (client-side DOCX creation)
|
||
- **Markdown Parsing**: marked library (local conversion, no API calls)
|
||
- **Fonts**: Google Fonts loaded dynamically
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
├── App.tsx # Main application component with state machine
|
||
├── index.tsx # React root mount
|
||
├── index.html # HTML entry, Tailwind CDN, import maps
|
||
├── types.ts # TypeScript interfaces (StyleOption, DocxStyleConfig, etc.)
|
||
├── constants.ts # System prompts and style exports
|
||
├── components/
|
||
│ ├── FileUpload.tsx # Drag-and-drop file upload (.md, .txt)
|
||
│ ├── StyleSelector.tsx # Style grid with preview iframe
|
||
│ ├── Preview.tsx # Final preview and DOCX export
|
||
│ └── StylePreviewModal.tsx # (Unused) Modal style preview component
|
||
|
||
├── styles/ # Typography style definitions
|
||
│ ├── index.ts # Aggregates all style categories
|
||
│ ├── minimalist.ts # 11 minimalist styles
|
||
│ ├── corporate.ts # 13 corporate/professional styles
|
||
│ ├── editorial.ts # Editorial/magazine styles
|
||
│ ├── tech.ts # Tech/startup styles
|
||
│ ├── creative.ts # Creative/artistic styles
|
||
│ ├── vintage.ts # Retro/vintage styles
|
||
│ ├── lifestyle.ts # Lifestyle/blog styles
|
||
│ ├── academic.ts # Academic/research styles
|
||
│ └── industrial.ts # Industrial/technical styles
|
||
```
|
||
|
||
## Application State Flow
|
||
|
||
The app uses a 4-state machine defined in `types.ts`:
|
||
|
||
1. **UPLOAD** - Initial screen with file upload dropzone
|
||
2. **CONFIG** - Style selection interface with live preview
|
||
3. **GENERATING** - Processing animation (800ms artificial delay for UX)
|
||
4. **PREVIEW** - Final preview with DOCX download option
|
||
|
||
State transitions:
|
||
- UPLOAD → CONFIG: After file loaded successfully
|
||
- CONFIG → GENERATING: When user clicks "Apply Style & Convert"
|
||
- GENERATING → PREVIEW: After HTML generation completes
|
||
- PREVIEW → CONFIG: Via "Back to Editor" button
|
||
- Any → UPLOAD: Via header logo click (reset)
|
||
|
||
## Style System Architecture
|
||
|
||
Each style is a `StyleOption` object containing:
|
||
|
||
```typescript
|
||
{
|
||
id: string, // Unique identifier
|
||
name: string, // Display name
|
||
category: string, // For filtering (Minimalist, Corporate, etc.)
|
||
description: string, // Short description
|
||
vibe: string, // Mood/aesthetic descriptor
|
||
googleFontsImport: string, // Google Fonts URL
|
||
wordConfig: {
|
||
heading1: DocxStyleConfig, // H1 formatting for Word
|
||
heading2: DocxStyleConfig, // H2 formatting for Word
|
||
body: DocxStyleConfig, // Body text formatting for Word
|
||
accentColor: string // Brand accent color
|
||
},
|
||
previewCss: string // CSS string for web preview (must manually match wordConfig)
|
||
}
|
||
```
|
||
|
||
**Important**: `wordConfig` and `previewCss` must be kept in sync manually for visual fidelity between preview and exported document.
|
||
|
||
## Build Commands
|
||
|
||
```bash
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Development server (runs on port 3000)
|
||
npm run dev
|
||
|
||
# Production build (outputs to dist/)
|
||
npm run build
|
||
|
||
# Preview production build
|
||
npm run preview
|
||
```
|
||
|
||
## Environment Configuration
|
||
|
||
No environment variables required. The app uses local Markdown parsing only.
|
||
|
||
## Key Implementation Details
|
||
|
||
### DOCX Generation (components/Preview.tsx)
|
||
|
||
The DOCX export uses the `docx` library to create Word-compatible documents:
|
||
|
||
- Converts HTML to docx Paragraph elements
|
||
- Supports headings (h1-h6), paragraphs, blockquotes, lists
|
||
- Applies style-specific fonts, colors, spacing, borders, and shading
|
||
- Paper sizes: A4 (210mm × 297mm) and Letter (8.5in × 11in)
|
||
- Margins: 1in top/bottom, 1.2in left/right
|
||
|
||
### Preview System
|
||
|
||
Previews render in an iframe with dynamically injected:
|
||
- Google Fonts link from style config
|
||
- Style-specific CSS from `previewCss`
|
||
- Sample content for style selection view
|
||
- Actual converted content for final preview
|
||
|
||
### File Upload
|
||
|
||
Accepts: `.md`, `.txt`, `.markdown`
|
||
Uses FileReader API for client-side text extraction
|
||
Validates file extension before processing
|
||
|
||
## Code Style Guidelines
|
||
|
||
- **TypeScript**: Strict mode enabled; all components typed with React.FC
|
||
- **Imports**: Use `@/` path alias for project root imports
|
||
- **Styling**: Tailwind utility classes; custom CSS only in `previewCss` fields
|
||
- **Naming**: PascalCase for components, camelCase for functions/variables
|
||
- **Comments**: Explain business logic and non-obvious decisions
|
||
|
||
## Adding New Typography Styles
|
||
|
||
1. Choose appropriate category file in `/styles/` (or create new category)
|
||
2. Add StyleOption object to the array with:
|
||
- Unique `id`
|
||
- Google Fonts URL
|
||
- Complete `wordConfig` for DOCX export
|
||
- Matching `previewCss` for web preview
|
||
3. Export from `/styles/index.ts` if new category
|
||
4. Test both preview and DOCX export
|
||
|
||
## Security Considerations
|
||
|
||
- No server-side processing; all conversion happens client-side
|
||
- No API keys required; all processing is done locally
|
||
- File upload limited to text files by extension check
|
||
- iframe sandboxing for style previews (same-origin content only)
|
||
|
||
## Known Limitations
|
||
|
||
- `wordConfig` and `previewCss` require manual synchronization
|
||
- DOCX export has limited table support
|
||
- Complex Markdown (nested lists, code blocks) may not format perfectly
|
||
- Style categories are loosely organized and may overlap
|