npm package: @pitcher/css
Description: Pitcher UI Framework - A comprehensive CSS framework with components for building modern web applications
Author: Pitcher
Latest version: 2025.10.1-7.1760711293807

# Pitcher UI Framework (@pitcher/css)

A comprehensive CSS framework with components for building modern web applications, specifically designed for Pitcher embedded apps.

## Features

- **Zero Build Step** - Pure CSS framework, no compilation required
- **Comprehensive Components** - Buttons, forms, tables, modals, tabs, tooltips, and more
- **Font Awesome Integration** - Built-in icon support
- **Instance Color Theming** - Automatically adapts to your Pitcher instance color
- **Responsive Design** - Mobile-first approach with responsive utilities
- **Pitcher API Integration** - Works seamlessly with `@pitcher/js-api`

## Installation

### Via CDN (Recommended for Production)

```html
<link
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700&display=swap"
  rel="stylesheet"
/>
<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css"
/>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@pitcher/css" />
<script src="https://cdn.jsdelivr.net/npm/@pitcher/js-api"></script>
```

### Via NPM

```bash
npm install @pitcher/css
```

```html
<link rel="stylesheet" href="node_modules/@pitcher/css/pitcher-ui.css" />
```

## Development & Debugging

**To develop or debug the CSS locally**, change the import from CDN to a local file:

```html
<!-- Production (CDN) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@pitcher/css" />

<!-- Development (Local File) -->
<link rel="stylesheet" href="pitcher-ui.css" />
```

This allows you to make changes to `pitcher-ui.css` and see them reflected immediately without publishing to NPM.

## Quick Start

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link
      href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700&display=swap"
      rel="stylesheet"
    />
    <link
      rel="stylesheet"
      href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css"
    />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@pitcher/css" />
    <script src="https://cdn.jsdelivr.net/npm/@pitcher/js-api"></script>
  </head>
  <body>
    <div class="p-card">
      <div class="p-card-header">Hello Pitcher</div>
      <div class="p-card-body">
        <p>Your first Pitcher UI component!</p>
        <button class="p-btn p-btn-primary">Click Me</button>
      </div>
    </div>

    <script>
        // Initialize Pitcher API and apply instance color
        const api = window.pitcher?.useApi();
        if (api) {
          const env = await api.getEnv();
          const instanceColor = env.pitcher?.instance?.color;
          if (instanceColor) {
            document.documentElement.style.setProperty('--p-primary', instanceColor);
          }
        }
    </script>
  </body>
</html>
```

## Components

The framework includes the following components:

### Layout & Structure

- **Cards** - `.p-card`, `.p-card-header`, `.p-card-body`, `.p-card-footer`
- **Panels** - `.p-panel`
- **Breadcrumbs** - `.p-breadcrumb`

### Forms & Inputs

- **Text Inputs** - `.p-input`
- **Text Areas** - `.p-textarea`
- **Selects** - `.p-select`
- **Checkboxes** - `.p-checkbox`
- **Radio Buttons** - `.p-radio`
- **Toggles** - `.p-toggle`
- **Labels** - `.p-label`, `.p-label.required`
- **File Upload** - `.p-file-upload`

### Buttons & Actions

- **Buttons** - `.p-btn`, `.p-btn-primary`, `.p-btn-secondary`, `.p-btn-success`, `.p-btn-danger`, `.p-btn-warning`, `.p-btn-info`, `.p-btn-text`
- **Button Sizes** - `.p-btn-sm`, `.p-btn-lg`
- **Action Buttons** - `.action-button`

### Feedback & Status

- **Alerts** - `.p-alert`, `.p-alert-success`, `.p-alert-error`, `.p-alert-warning`, `.p-alert-info`
- **Badges** - `.p-badge`, `.p-badge-success`, `.p-badge-error`, `.p-badge-warning`, `.p-badge-info`
- **Tags** - `.p-tag`, `.p-tag-success`, `.p-tag-error`, `.p-tag-warning`, `.p-tag-info`
- **Toast Notifications** - `.p-toast`, `.p-toast-container`
- **Progress Bars** - `.p-progress`, `.p-progress-bar`
- **Spinners** - `.p-spinner`
- **Skeleton Loaders** - `.p-skeleton`, `.p-skeleton-text`, `.p-skeleton-title`, `.p-skeleton-circle`, `.p-skeleton-button`

### Navigation & Interactive

- **Tabs** - `.p-tabs`, `.p-tab`, `.p-tab-content`
- **Accordion** - `.p-accordion`, `.p-accordion-item`, `.p-accordion-header`, `.p-accordion-body`
- **Dropdown** - `.p-dropdown`, `.p-dropdown-menu`, `.p-dropdown-item`
- **Tooltips** - `.p-tooltip`, `.p-tooltip-text`
- **Pagination** - `.p-pagination`, `.p-pagination-item`

### Data Display

- **Tables** - `.p-table`, `.p-table-striped`
- **List Group** - `.p-list-group`, `.p-list-item`
- **Avatars** - `.p-avatar`, `.p-avatar-sm`, `.p-avatar-md`, `.p-avatar-lg`, `.p-avatar-xl`, `.p-avatar-group`

### Overlays

- **Modals** - `.p-modal`, `.p-modal-content`, `.p-modal-header`, `.p-modal-body`, `.p-modal-footer`

### Utilities

- **Spacing** - `.p-m-*`, `.p-p-*`, `.p-mt-*`, `.p-mb-*` (0-4)
- **Flexbox** - `.p-flex`, `.p-flex-col`, `.p-flex-wrap`, `.p-items-center`, `.p-justify-between`, `.p-gap-*`
- **Text** - `.p-text-xs`, `.p-text-sm`, `.p-text-md`, `.p-text-lg`, `.p-text-center`, `.p-text-uppercase`
- **Colors** - `.p-text-primary`, `.p-text-success`, `.p-text-error`, `.p-text-warning`, `.p-text-gray`, `.p-text-muted`
- **Fonts** - `.p-font-normal`, `.p-font-medium`, `.p-font-semibold`, `.p-font-bold`

## CSS Variables

The framework uses CSS variables for easy theming:

```css
:root {
  /* Primary Colors */
  --p-primary: #29335c;
  --p-primary2: #4e5983;
  --p-primary3: #7e88b1;
  --p-primary4: #bfc5df;
  --p-primary5: #e0e2ed;
  --p-primary6: #f7f8fb;

  /* Status Colors */
  --p-success: #57a40f;
  --p-error: #bc1637;
  --p-warning: #e5c302;
  --p-info: #5bbfe3;

  /* Spacing */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-3: 0.75rem;
  --spacing-4: 1rem;

  /* ... and more */
}
```

Override these variables to customize the theme:

```css
:root {
  --p-primary: #3b82f6; /* Custom blue */
}
```

## Instance Color Theming

The framework automatically applies your Pitcher instance color when embedded:

```javascript
async function applyInstanceColor() {
  const api = window.pitcher?.useApi();
  if (!api) return;

  const env = await api.getEnv();
  const instanceColor = env.pitcher?.instance?.color;

  if (instanceColor) {
    document.documentElement.style.setProperty("--p-primary", instanceColor);
  }
}
```

## Examples

See `index.html` for comprehensive component examples and usage patterns.

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Android)

## License

MIT

## Contributing

Issues and pull requests are welcome! This framework is specifically designed for Pitcher embedded apps but can be used in any web project.

## Links

- **NPM**: `@pitcher/css`
- **CDN**: `https://cdn.jsdelivr.net/npm/@pitcher/css`
- **Pitcher JS API**: `@pitcher/js-api`