npm package: @syarahtech/plugin
Description: ## Introduction
Author: Ibrahim Banat
Latest version: 1.0.2

# Syarah Tailwind Plugin Documentation

## Introduction

The `syarah-plugin.js` is a custom Tailwind CSS plugin designed to extend the default Tailwind configuration with additional utilities, variants, and theme customizations. This plugin introduces new color palettes, font families, animations, and language-specific variants to meet the design requirements for Syarah projects.

## Installation

To use this plugin in your Tailwind CSS project, follow these steps:

1️⃣ **Install Tailwind CSS** in your project (if not already installed):
   ```bash
   npm install tailwindcss
   ```
2️⃣ **Place the `syarah-plugin.js` file** in your project directory.
3️⃣ **Import and register the plugin** in your `tailwind.config.js` file:
   ```javascript
   const { syarahPlugin } = require('./syarah-plugin');

   module.exports = {
       content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
       theme: {
           extend: {},
       },
       plugins: [syarahPlugin],
   };
   ```

## Features

### 1️⃣ Custom Variants

This plugin introduces language-specific variants for better internationalization:

- 🌐 **`ar`**: Applies styles when the HTML `lang` attribute contains `ar` (Arabic).
  ```html
  <html lang="ar">
  ```
- 🌐 **`en`**: Applies styles when the HTML `lang` attribute contains `en` (English).
  ```html
  <html lang="en">
  ```

Example usage:

```html
<div class="ar:bg-primary en:bg-secondary">
    This div has different background colors based on the language.
</div>
```

### 2️⃣ Theme Extensions

#### 🎨 Colors

The plugin extends Tailwind's color palette with new colors and shades for primary, secondary, success, warning, danger, neutral, and other UI-related elements. Each color includes several shades (e.g., `100`, `90`, `80`) for flexibility.

Example:

```html
<div class="bg-primary-100 text-primary-foreground">
    Primary button
</div>
```

**Color Tokens:**

- **Primary**: `#3C56D4` (Default), with shades from `120` to `50`.
- **Secondary**: `#FE561C` (Default), with shades from `120` to `60`.
- **Success**: `#00B362` (Default), with shades from `120` to `60`.
- **Warning**: `#FFB900` (Default), with shades from `120` to `60`.
- **Danger**: `#F11010` (Default), with shades from `120` to `60`.
- **Neutral**: Shades ranging from `0` to `100`.
- **Custom Tokens:** `border`, `input`, `ring`, `background`, `foreground`, `card`, `popover`, `muted`, and `accent`.

#### 🖋️ Font Family

Adds custom font families:

- **Default**: `"IBM Plex Sans Arabic", sans-serif`
- **plex-arabic**: `"IBM Plex Sans Arabic", sans-serif`
- **inter**: `"Inter", sans-serif`

Example:

```html
<div class="font-plex-arabic">
    Arabic text styled with IBM Plex Sans Arabic.
</div>
```

#### 🔄 Animations

Custom animations for accordion behavior:

- **Keyframes:**
    - `accordion-down`: Expands an accordion element.
    - `accordion-up`: Collapses an accordion element.
- **Animations:**
    - `accordion-down`: `accordion-down 0.2s ease-out`
    - `accordion-up`: `accordion-up 0.2s ease-out`

Example:

```html
<div class="animate-accordion-down">
    Expanding content
</div>
```

### 3️⃣ Utilities

The plugin enables the following utilities:

- 🌐 Variants `ar` and `en` for language-specific styling.
- 🎨 Customizable color tokens for theme coherence.

## Usage Examples

### 🖱️ Buttons with Custom Colors

```html
<button class="bg-primary-100 hover:bg-primary-90 text-white font-inter px-4 py-2">
    Primary Button
</button>

<button class="bg-secondary-100 hover:bg-secondary-90 text-white font-plex-arabic px-4 py-2">
    Secondary Button
</button>
```

### ⚠️ Alerts with Neutral Colors

```html
<div class="bg-neutral-10 border border-neutral-50 text-neutral-90 px-4 py-2">
    Neutral alert message
</div>
```

### 🔄 Accordion Animations

```html
<div class="overflow-hidden animate-accordion-down">
    Expanding content
</div>

<div class="overflow-hidden animate-accordion-up">
    Collapsing content
</div>
```

## Customization

You can further customize the plugin by modifying the `syarah-plugin.js` file. Adjust color values, font families, or animations to fit your project's design system.

## Conclusion

The Syarah Tailwind Plugin enhances your Tailwind CSS setup with powerful utilities, extended themes, and language-based variants, ensuring a **seamless** development experience for multilingual and design-rich projects.