`, `

` | | **Live Regions** | Screen readers announce state transitions (upload/configure/generate/preview), search result counts, loading states, export success/failure | | **Semantic Markup** | Progress stepper uses `

/: `. Decorative elements marked `aria-hidden="true"` | | **Modal Accessibility** | All dialogs have `aria-labelledby` pointing to their heading. Export options use `
/` for radio groups | | **Dynamic Labels** | Favorite button announces "Add/Remove [style name] from favorites" with `aria-pressed` state. Category and paper size filters expose `aria-pressed` toggle state | | **Accessible Names** | Every icon-only button has an `aria-label`. All decorative icons carry `aria-hidden="true"` | | **Error Handling** | Errors use `role="alert"` (no conflicting `aria-live`). File upload errors linked to dropzone via `aria-describedby`. No auto-dismissing error messages | | **Error Boundary** | Application-level `ErrorBoundary` component catches crashes and renders an accessible `role="alert"` error screen with a reload option | ### Accessible Document Output The `.docx` files TypoGenie generates are also built with accessibility in mind: | Feature | Detail | |---------|--------| | **Document Metadata** | Every exported DOCX includes `title`, `description`, and `creator` properties for assistive technology | | **Heading Structure** | Semantic `HeadingLevel` preserved in both rendering modes (semantic and high-fidelity table layout) | | **Table Headers** | Rows containing `` elements are marked with `tableHeader: true` so screen readers can announce column/row headers | | **Image Placeholders** | `` elements in Markdown are converted to italic `[Image: alt text]` placeholders rather than silently dropped | | **Contrast-Safe Colors** | All template text colors are validated and auto-corrected against their backgrounds before being applied to the document | ### Runtime Contrast Validation Template colors are never trusted blindly. At CSS generation time, every text/background color pair passes through `ensureContrast()`: ``` Template says text color = #555555 on background #1a1a1a → contrastRatio("#555555", "#1a1a1a") = 2.8:1 (fails 7:1 AAA) → ensureContrast() lightens to #9a9a9a = 7.1:1 (passes) → Rendered color = #9a9a9a ``` This means all 165+ styles automatically meet WCAG AAA contrast requirements regardless of their original color definitions. The original aesthetic is preserved as closely as possible while guaranteeing readability.
--- ## 🎨 Demo
### The Transformation ``` ┌─────────────────────────────────────┐ ┌─────────────────────────────────────┐ │ YOUR INPUT │ │ TYPOGENIE OUTPUT │ │ ─────────── │ ⚡ │ ──────────────── │ │ │ → │ │ │ # My Document │ │ ┌─────────────────────────────┐ │ │ │ │ │ My Document │ │ │ Some **bold** text here. │ │ │ (Beautifully │ │ │ │ │ │ Formatted) │ │ │ - Point one │ │ └─────────────────────────────┘ │ │ - Point two │ │ │ │ │ │ Some bold text here. │ │ > A wise quote │ │ │ │ │ │ • Point one │ │ │ │ • Point two │ │ │ │ │ │ │ │ ┌─────────────────────────────┐ │ │ │ │ │ "A wise quote" │ │ │ │ │ └─────────────────────────────┘ │ └─────────────────────────────────────┘ └─────────────────────────────────────┘ ```

--- ## 🚀 Quick Start ### Option 1: Portable Download (Recommended) 🎒 **TypoGenie is fully portable** - no installation, no registry entries, no files scattered across your system. Just download and run: - 🪟 **Windows**: `TypoGenie.exe` - Single executable, runs immediately **How it works:** ``` 📁 Your Folder/ ├── 🚀 TypoGenie.exe ← Run this ├── 📂 templates/ ← JSON templates (must be next to EXE) └── 📂 TypoGenie-Data/ ← Auto-created on first run (settings/cache) ``` ✅ **No installer** - Just double-click the EXE ✅ **No registry** - Windows registry untouched ✅ **No AppData** - Everything stays in the same folder ✅ **USB-friendly** - Run from a thumb drive anywhere ✅ **Easy backup** - Copy the whole folder, done ### Option 2: Build from Source #### Prerequisites - **Node.js** 18+ (we recommend the latest LTS) - **Rust** (for Tauri desktop builds) - Your favorite text editor #### Web Development ```bash # 1. Clone the collective's work git clone https://git.lashman.live/lashman/typogenie.git # 2. Enter the commons cd typogenie # 3. Gather dependencies (mutual aid from npm) npm install # 4. Start the local development server npm run dev ``` Your browser will open to `http://localhost:3000` - and you're ready to create! #### Desktop App Development ```bash # Run in desktop development mode npm run desktop # Build desktop app for production npm run desktop:build ``` **Build output:** | Platform | Output Location | Result | |----------|----------------|--------| | **Windows** | `src-tauri/target/release/TypoGenie.exe` | ⚡ **Portable EXE** - Run immediately, no install | **For the truly portable Windows experience:** 1. Build the release (`npm run tauri build`). 2. Copy `TypoGenie.exe` from `src-tauri/target/release/` to a new folder. 3. **CRITICAL**: Copy the `src-tauri/templates/` folder to that SAME folder. 4. Run `TypoGenie.exe`. ### Usage 1. **📤 Upload** - Drag and drop your Markdown file (or click to browse) 2. **🎨 Select Style** - Browse the gallery and click any style for live preview 3. **📐 Choose Paper Size** - A4 or Letter, depending on your needs 4. **✨ Generate** - Watch the magic happen (with a satisfying loading animation) 5. **📥 Download** - Grab your `.docx` file, ready for Word
--- ## 📚 Documentation ### Architecture Overview ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ TYPOGENIE ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ UPLOAD │───→│ CONFIG │───→│ PREVIEW │ │ │ │ (File) │ │ (Style) │ │ (Export) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ STATE MACHINE │ │ │ │ • UPLOAD → CONFIG → GENERATING → PREVIEW → (reset) │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ PROCESSING PIPELINE │ │ │ │ Markdown → marked parser → HTML → docx library → .docx │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### Style System Deep Dive Styles in TypoGenie are defined entirely in **JSON**, making them easy to edit and share. **Template Structure (`.json`):** ```json { "id": "my-custom-style", "name": "My Style", "category": "Creative", "description": "A brief description of the aesthetic", "vibe": "Keywords that capture the feeling", "googleFontsImport": "https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap", "typography": { "fonts": { "heading": "Roboto", "body": "Roboto" }, "colors": { "text": "1a1a1a", "background": "ffffff", "accent": "6366f1" } }, "elements": { "h1": { "font": "heading", "size": 24, "color": "text", "bold": true, "spacing": { "before": 24, "after": 12, "line": 1.2 } }, ... } } ``` **The Dual Rendering Architecture:** TypoGenie maintains two parallel rendering paths: 1. **Web Preview** - Dynamically generates CSS from your JSON config on the fly. 2. **DOCX Export** - Programmatically builds Word styles using the exact same JSON config. This ensures WYSIWYG fidelity: what you see in the preview is what you get in Word. ### Adding Custom Styles Want to contribute a new style? 1. **Create a JSON file** in a folder inside `templates/` (e.g., `templates/my-category/my-style.json`). 2. **Define your style** using the schema above. 3. **Restart the app** (or click refresh) - TypoGenie automatically discovers all `.json` files in the `templates/` directory. ### Configuration Options #### Paper Sizes | Size | Dimensions | Best For | |------|------------|----------| | **A4** | 210mm × 297mm | International use, academic papers | | **Letter** | 8.5in × 11in | US/Canada, business documents |
--- ## 🛠️ Development ### Available Scripts ```bash # Web Development npm run dev # Start Vite dev server npm run build # Production build (outputs to dist/) npm run preview # Preview production build locally # Desktop App Development (Tauri) npm run desktop # Run desktop app in dev mode npm run desktop:build # Build desktop app for production npm run tauri # Access Tauri CLI directly ``` ### Project Structure ``` typogenie/ ├── 📁 src/ # Frontend source code (React) │ ├── 📁 components/ # UI components │ │ ├── ErrorBoundary.tsx # Accessible crash recovery screen │ │ ├── ExportOptionsModal.tsx # DOCX export options (native dialog) │ │ ├── FileUpload.tsx # Drag-and-drop upload zone │ │ ├── Preview.tsx # Final preview & export │ │ ├── StylePreviewModal.tsx # Full-page style preview (native dialog) │ │ └── StyleSelector.tsx # Style gallery with listbox pattern │ ├── 📁 hooks/ # React hooks │ │ ├── useDialog.ts # Native management with focus restore │ │ └── ... │ ├── 📁 services/ # Logic │ │ ├── templateLoader.ts # Loads JSON templates via Rust │ │ └── templateRenderer.ts # Generates CSS/DOCX with contrast validation │ ├── 📁 utils/ # Utilities │ │ ├── contrastUtils.ts # WCAG contrast ratio validation │ │ └── docxConverter.ts # Accessible DOCX generation │ └── 📄 App.tsx # Main application component ├── 📁 src-tauri/ # Tauri desktop app │ ├── 📁 src/ # Rust backend code (filesystem access) │ ├── 📁 templates/ # DEFAULT TEMPLATES (bundled with app) │ │ ├── 📁 minimalist/ │ │ ├── 📁 tech/ │ │ └── ... │ ├── 📄 Cargo.toml # Rust dependencies │ └── 📄 tauri.conf.json # Tauri configuration └── 📄 vite.config.ts # Build configuration ``` ### Technology Stack | Layer | Technology | Purpose | |-------|------------|---------| | **Framework** | React 19.2.4 | UI components & state management | | **Language** | TypeScript 5.8.2 | Type safety & developer experience | | **Build Tool** | Vite 6.2.0 | Fast development & optimized builds | | **Styling** | Tailwind CSS 4 | Utility-first CSS | | **Animation** | Framer Motion (motion/react) | Transitions with reduced-motion support | | **Icons** | Lucide React | Beautiful, consistent iconography | | **Markdown** | marked 12.0.0 | Local Markdown parsing | | **Documents** | docx 8.5.0 | Client-side DOCX generation | | **Desktop** | Tauri 2.0 | Native desktop apps (Rust + WebView) | | **Backend** | Rust 1.77+ | Systems programming for desktop shell |
--- ## 🤝 Contributing TypoGenie is a **commons** - it belongs to everyone who uses it and improves it. We welcome contributions of all kinds: ### Ways to Contribute - 🎨 **New Styles** - Design and share new typography styles - 🐛 **Bug Reports** - Found something broken? Let us know! - 💡 **Feature Ideas** - Have a suggestion? Open a discussion - 📖 **Documentation** - Help us explain things better - 🔧 **Code Improvements** - Refactors, optimizations, fixes - 🌍 **Translations** - Help make TypoGenie accessible globally ### Contribution Guidelines 1. **Fork the repository** 2. **Create a feature branch**: `git checkout -b feature/amazing-thing` 3. **Make your changes** with clear, descriptive commits 4. **Test thoroughly** - preview AND Word export 5. **Submit a Pull Request** with a detailed description ### Code of Conduct - Be respectful and constructive - Assume good intentions - Help newcomers learn and grow - Focus on what's best for the community
--- ## 📜 Philosophy & License ### Why Free? Why Open? TypoGenie exists because we believe: > **Access to beautiful tools for self-expression should not depend on one's ability to pay.** In an era of increasingly proprietary, subscription-based software, TypoGenie is an offering to the digital commons - a tool that exists purely to serve those who need it, without extracting value, without surveillance, without artificial limitations. ### CC0 1.0 Universal - Public Domain Dedication [![CC0](https://licensebuttons.net/p/zero/1.0/88x31.png)](https://creativecommons.org/publicdomain/zero/1.0/) This project is released into the public domain under [CC0 1.0 Universal](LICENSE). To the extent possible under law, the authors have waived all copyright and related rights to this work. **tl;dr:** Do whatever you want with this code. No permission needed, no attribution required, no strings attached. Copy it, modify it, sell it, use it for whatever purpose serves your community. It belongs to everyone.
--- ## 🙏 Acknowledgments TypoGenie stands on the shoulders of giants - the countless open-source contributors who built the libraries, tools, and standards that make this project possible: - **The React Team** - For the component model that powers our UI - **The marked contributors** - For battle-tested Markdown parsing - **The docx maintainers** - For making client-side Word generation possible - **Google Fonts** - For democratizing access to beautiful typography - **Tailwind CSS** - For the utility-first approach that speeds development - **Vite** - For the build tooling that makes development a joy - **The broader open-source community** - For proving that collective, voluntary cooperation can create tools that rival (and exceed) proprietary alternatives **And to you, the user** - for choosing tools that respect your freedom.
---
## 💬 Connect

### ☕ Support the Commons If TypoGenie brings value to your life, consider: - ⭐ **Starring the repository** - Helps others discover it - 🗣️ **Spreading the word** - Tell friends and colleagues - 🔧 **Contributing code** - Improve it for everyone - 💝 **Supporting open-source** - Donate to the projects TypoGenie depends on
---
"The master's tools will never dismantle the master's house. But they might help you format a really nice document while we build something better together."

Made with ❤️ for the many, not the few.