npm package: @firstbreath/typedoc-theme-firstbreath
Description: TypeDoc theme Firstbreath with React + Tailwind, integrating typedoc-plugin-coverage and typedoc-umlclass.
Latest version: 0.2.0

# TypeDoc Theme Firstbreath

A modern, beautiful TypeDoc theme with seamless integration of `typedoc-umlclass` and `typedoc-plugin-coverage`. Built with React, Tailwind CSS, and designed to match the Firstbreath brand colors from my-app.

## ✨ Features

- **🎨 Modern Design**: Beautiful, clean interface with gradient accents and smooth animations
- **📊 UML Diagrams**: Fully styled integration with `typedoc-umlclass` for visual class diagrams
- **📈 Coverage Reports**: Enhanced display for `typedoc-plugin-coverage` with beautiful metrics cards
- **🎯 Firstbreath Colors**: Matches the blue color scheme from your main application
- **📱 Responsive**: Mobile-first design that works on all screen sizes
- **🌗 Dark Mode**: Automatic dark mode support based on system preferences
- **⚡ Performance**: Optimized CSS with Tailwind for minimal file size
- **🖨️ Print-Friendly**: Special styles for printing documentation

## 📦 Installation

### For my-app project

```bash
cd /Users/nathandelenclos/Project/EIP/my-app
npm install --save-dev typedoc typedoc-plugin-coverage typedoc-umlclass
npm install --save-dev ../typedoc-theme-firstbreath
```

Or with a symlink for local development:

```bash
cd /Users/nathandelenclos/Project/EIP/my-app
npm link ../typedoc-theme-firstbreath
```

### For other projects

```bash
npm install --save-dev @firstbreath/typedoc-theme-firstbreath typedoc-plugin-coverage typedoc-umlclass
```

## 🚀 Usage

### Configuration

Create a `typedoc.json` file in your project root:

```json
{
  "entryPoints": ["./src/**/*.ts"],
  "out": "docs",
  "theme": "firstbreath",
  "plugin": [
    "typedoc-plugin-coverage",
    "typedoc-umlclass"
  ],
  "name": "My Project Documentation"
}
```

### Generate Documentation

Add to your `package.json`:

```json
{
  "scripts": {
    "docs": "typedoc",
    "docs:serve": "npx serve docs"
  }
}
```

Then run:

```bash
npm run docs
```

## 🎨 Theme Features

### Coverage Integration

The theme automatically styles coverage reports with:
- **Animated progress bars** with gradient fills
- **Color-coded metrics** (green for high, amber for medium, red for low)
- **Dashboard-style cards** for key metrics
- **Enhanced tables** with hover effects
- **Status indicators** for documentation coverage

### UML Class Diagrams

UML diagrams are displayed with:
- **Card-based layout** with shadows and hover effects
- **Gradient headers** in Firstbreath blue
- **Icon indicators** for methods (⚡) and properties (📦)
- **Hover animations** for better interactivity
- **Relation styling** with different line types for inheritance, composition, etc.

### Modern TypeDoc Elements

- **Gradient title headers** with text gradients
- **Enhanced navigation** with smooth transitions
- **Code blocks** with modern syntax highlighting
- **Signature blocks** with hover effects
- **Search box** with icon and focus states
- **Badge system** for different element types (Class, Interface, Function, etc.)

## 🎨 Color Scheme

The theme uses the Firstbreath blue palette, aligned with my-app:

- **Primary**: `#2563eb` (Blue 600)
- **Primary Dark**: `#1d4ed8` (Blue 700)
- **Primary Light**: `#60a5fa` (Blue 400)
- **Accent**: `#3b82f6` (Blue 500)

### CSS Variables

Available CSS custom properties:

```css
--fb-primary: #2563eb;
--fb-primary-dark: #1d4ed8;
--fb-primary-light: #60a5fa;
--fb-accent: #3b82f6;
--fb-coverage-high: #22c55e;
--fb-coverage-medium: #f59e0b;
--fb-coverage-low: #ef4444;
```

## 🛠️ Development

### Build the theme

```bash
# Build both web assets and TypeScript
npm run build

# Build only web assets (CSS/JS)
npm run build:web

# Build only TypeScript
npm run build:theme

# Development mode for web assets
npm run dev:web
```

### Project Structure

```
typedoc-theme-firstbreath/
├── src/
│   ├── theme/
│   │   └── FirstbreathTheme.ts    # Main theme class
│   └── index.ts                    # Plugin entry point
├── web/
│   └── src/
│       ├── index.css               # Tailwind CSS with custom styles
│       └── main.tsx                # React components (if needed)
├── web-dist/                       # Built CSS/JS assets
├── dist/                           # Compiled TypeScript
└── example/                        # Example configuration
```

## 📋 Requirements

- TypeDoc >= 0.28.0
- Node.js >= 18.0.0
- typedoc-plugin-coverage >= 4.0.0
- typedoc-umlclass >= 0.10.0

## 🎯 Best Practices

1. **Document your code**: The theme works best with well-documented TypeScript code
2. **Use JSDoc comments**: Add descriptions, examples, and parameter docs
3. **Enable coverage**: Set a coverage minimum in your config (e.g., 70%)
4. **Organize with categories**: Use `@category` tags to group related items
5. **Add UML diagrams**: The theme automatically styles class diagrams beautifully

## 📖 Example Documentation Structure

```typescript
/**
 * User authentication service
 * 
 * @category Services
 * @example
 * ```typescript
 * const auth = new AuthService();
 * await auth.login('user@example.com', 'password');
 * ```
 */
export class AuthService {
  /**
   * Authenticate a user with email and password
   * 
   * @param email - User's email address
   * @param password - User's password
   * @returns Authentication token
   * @throws {AuthError} If credentials are invalid
   */
  async login(email: string, password: string): Promise<string> {
    // Implementation
  }
}
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Make your changes
4. Build and test: `npm run build`
5. Submit a pull request

## 📄 License

MIT © Firstbreath

## 🔗 Links

- [TypeDoc Documentation](https://typedoc.org)
- [typedoc-plugin-coverage](https://github.com/codecov/typedoc-plugin-coverage)
- [typedoc-umlclass](https://github.com/krisztianb/typedoc-umlclass)
- [Tailwind CSS](https://tailwindcss.com)

---

**Made with ❤️ for the Firstbreath project**