kit-ui/GEMINI.md

GEMINI.md - Kit UI Context

This file provides foundational context and instructions for Gemini CLI when working in the kit-ui workspace.

🚀 Project Overview

Kit UI is a high-performance, aesthetically pleasing toolkit built with Next.js 16, React 19, and Tailwind CSS 4. It provides four core specialized applications:

1. Color: Advanced color theory, manipulation, and accessibility suite powered by @valknarthing/pastel-wasm.
2. Units: Smart unit converter supporting 187+ units across 23 categories, including a custom tempo measure.
3. ASCII: ASCII Art generator with 373 fonts and multi-format export.
4. Media: Browser-based file converter using FFmpeg and ImageMagick via WebAssembly (Zero server uploads).

🛠️ Tech Stack & Architecture

• Framework: Next.js 16 (App Router, Static Export).
• Library: React 19.
• Styling: Tailwind CSS 4 (CSS-first configuration in app/globals.css).
• Animations: Framer Motion 12.
• State Management: Zustand & React Query.
• Performance: Heavy logic (Color, Media) is offloaded to WebAssembly (WASM).
• UI Components: shadcn/ui (customized for a glassmorphic aesthetic).

📁 Project Structure

.
├── app/                  # Next.js App Router
│   ├── (app)/            # Core Tool Pages (color, units, ascii, media)
│   └── globals.css       # Tailwind 4 configuration & global styles
├── components/           # UI Components
│   ├── [tool]/           # Tool-specific components (e.g., components/color/)
│   ├── layout/           # AppShell, Sidebar, Header
│   └── ui/               # Base Atomic Components (shadcn)
├── lib/                  # Business Logic
│   ├── [tool]/           # Tool-specific logic & WASM wrappers
│   └── utils/            # General utilities (cn, format, etc.)
├── public/               # Static assets
│   ├── wasm/             # WASM binaries (ffmpeg, imagemagick)
│   └── fonts/            # ASCII fonts (.flf)
└── types/                # TypeScript definitions

⚙️ Development Workflows

Key Commands

• Development: pnpm dev (Uses Next.js Turbopack).
• Build: pnpm build (Generates a static export in /out).
• Lint: pnpm lint.
• WASM Setup: pnpm postinstall (Automatically copies WASM binaries to public/wasm/).

Coding Standards

1. Tailwind 4: Use the new CSS-first approach. Avoid tailwind.config.js. Define theme variables and utilities in app/globals.css.
2. Glassmorphism: Use the @utility glass for translucent components.
3. WASM Orchestration: Heavy processing should stay in lib/[tool]/ and utilize WASM where possible. Refer to lib/media/wasm/wasmLoader.ts for pattern-loading FFmpeg/ImageMagick.
4. Client-Side Only: Since this is a static export toolkit that relies on browser APIs (WASM, File API), ensure components using these are marked with 'use client'.
5. Icons: Exclusively use lucide-react.

🧠 Strategic Instructions for Gemini

• Surgical Updates: When modifying tools, ensure the logic remains in lib/ and the UI in components/.
• WASM Handling: Do not attempt to run WASM-dependent logic in the terminal/Node environment unless specifically configured. These tools are designed for the browser.
• Styling: Adhere to the glass and gradient utilities (gradient-purple-blue, etc.) defined in app/globals.css.
• Component Consistency: Use shadcn components from components/ui/ as the building blocks for new features.