README.md

@@ -1,38 +1,120 @@
-# sv
+# GlyphDiff
 
-Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+A modern, high-performance font exploration tool for browsing and comparing fonts from Google Fonts and Fontshare.
 
-## Creating a project
+## ✨ Features
 
-If you're seeing this, you've probably already done this step. Congrats!
+- **Multi-Provider Support**: Access fonts from Google Fonts and Fontshare in one place
+- **Fast Virtual Scrolling**: Handles thousands of fonts smoothly with custom virtualization
+- **Advanced Filtering**: Filter by category, provider, and character subsets
+- **Responsive Design**: Beautiful UI built with shadcn components and Tailwind CSS
+- **Type-Safe**: Full TypeScript coverage with strict mode enabled
 
-```sh
-# create a new project in the current directory
-npx sv create
+## 🛠️ Tech Stack
 
-# create a new project in my-app
-npx sv create my-app
+- **Frontend**: Svelte 5 with runes (reactive primitives)
+- **Styling**: Tailwind CSS v4 + shadcn-svelte components
+- **Data Fetching**: TanStack Query for caching and state management
+- **Architecture**: Feature-Sliced Design (FSD) methodology
+- **Testing**: Playwright (E2E), Vitest (unit), Storybook (components)
+- **Quality**: Oxlint (linting), Dprint (formatting), Lefthook (git hooks)
+
+## 📁 Architecture
+
+```
+src/
+├── app/           # App shell, layout, providers
+├── widgets/       # Composed UI blocks
+├── features/      # Business features (filters, search)
+├── entities/      # Domain entities (Font models, stores)
+├── shared/        # Reusable utilities, UI components, helpers
+└── routes/        # Page-level components
 ```
 
-## Developing
+## 🚀 Quick Start
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+```bash
+# Install dependencies
+yarn install
 
-```sh
-npm run dev
+# Start development server
+yarn dev
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+# Open in browser
+yarn dev -- --open
 ```
 
-## Building
+## 📦 Available Scripts
 
-To create a production version of your app:
+| Command          | Description                |
+| ---------------- | -------------------------- |
+| `yarn dev`       | Start development server   |
+| `yarn build`     | Build for production       |
+| `yarn preview`   | Preview production build   |
+| `yarn check`     | Run Svelte type checking   |
+| `yarn lint`      | Run oxlint                 |
+| `yarn format`    | Format with dprint         |
+| `yarn test`      | Run all tests (E2E + unit) |
+| `yarn test:e2e`  | Run Playwright E2E tests   |
+| `yarn test:unit` | Run Vitest unit tests      |
+| `yarn storybook` | Start Storybook dev server |
 
-```sh
-npm run build
+## 🧪 Development
+
+### Type Checking
+
+```bash
+yarn check           # Single run
+yarn check:watch     # Watch mode
 ```
 
-You can preview the production build with `npm run preview`.
+### Testing
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+```bash
+yarn test:unit              # Unit tests
+yarn test:unit:watch        # Watch mode
+yarn test:unit:ui           # Vitest UI
+yarn test:e2e               # E2E tests with Playwright
+yarn test:e2e --ui          # Interactive test runner
+```
+
+### Code Quality
+
+```bash
+yarn lint          # Lint code
+yarn format        # Format code
+yarn format:check  # Check formatting
+```
+
+## 🎯 Key Components
+
+- **VirtualList**: Custom high-performance list virtualization using Svelte 5 runes
+- **FontList**: Displays fonts with loading, empty, and error states
+- **FilterControls**: Multi-filter system for category, provider, and subsets
+- **TypographyControl**: Dynamic typography adjustment controls
+
+## 📝 Code Style
+
+- **Path Aliases**: Use `$app/`, `$shared/`, `$features/`, `$entities/`, `$widgets/`, `$routes/`
+- **Components**: PascalCase (e.g., `CheckboxFilter.svelte`)
+- **Formatting**: 100 char line width, 4-space indent, single quotes
+- **Imports**: Auto-sorted by dprint, separated by blank line
+- **Type Safety**: Strict TypeScript, JSDoc comments for public APIs
+
+## 🏗️ Building for Production
+
+```bash
+yarn build
+yarn preview
+```
+
+## 📚 Learn More
+
+- [Svelte 5 Documentation](https://svelte-5-preview.vercel.app/docs)
+- [Feature-Sliced Design](https://feature-sliced.design)
+- [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4-alpha)
+- [shadcn-svelte](https://www.shadcn-svelte.com)
+
+## 📄 License
+
+MIT