typogenie/AGENTS.md

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:

{
  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

# 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