sojorn/sojorn_app/assets/reactions/README.md

# Custom Reaction Sets

This folder contains custom reaction image sets that users can choose from in the reaction picker.

## Folder Structure

```
assets/reactions/
├── reaction_config.json    # Configuration file for reaction sets
├── emoji/                  # Default emoji reactions (built-in)
├── green/                  # Green-themed reaction set
│   ├── credit.md          # Attribution information
│   └── *.png              # Reaction images
├── blue/                   # Blue-themed reaction set  
│   ├── credit.md          # Attribution information
│   └── *.png              # Reaction images
├── purple/                 # Purple-themed reaction set
│   ├── credit.md          # Attribution information
│   └── *.png              # Reaction images
├── dotto/                  # Dotto pixel art emoji set
│   ├── credit.md          # Attribution information
│   └── *.svg              # Reaction images (SVG format)
└── [custom]/               # Add your own themed sets here
    ├── credit.md          # Attribution information
    └── *.png/.svg         # Reaction images
```

## Adding Custom Reaction Sets

### 1. Create a New Folder
Create a new folder in `assets/reactions/` with your theme name:
```bash
mkdir assets/reactions/your_theme_name
```

### 2. Add Reaction Images
Place your reaction images in the folder. Recommended specifications:
- **Format**: PNG with transparency OR SVG for scalable graphics
- **Size**: 64x64px (32x32px artwork) for PNG
- **Naming**: Use descriptive names (system tries 200+ common names):
  - `heart.png/svg`, `thumbs_up.png/svg`, `laugh.png/svg`
  - `smiling_face.png/svg`, `winking_face.png/svg`
  - `skull.png/svg`, `ghost.png/svg`, `robot.png/svg`
  - `fire.png/svg`, `party.png/svg`, `clap.png/svg`
  - And many more! (see comprehensive list in code)

### 3. Add Credit Information (Optional)
Create a `credit.md` file in your folder with attribution information:

```markdown
# Your Theme Name

**Source:** [Link to source if applicable](URL)

**Author:** Your Name or Artist

**License:** License information

**Description:** Brief description of your reaction set

**Format:** PNG/SVG
```

### 4. Update Reaction Picker (Required!)

After adding files to folders, run the update script:

**Windows:**
```bash
tools\add_new_folder.bat
```

**Manual:**
```bash
dart tools/add_reaction_folder.dart
```

This script:
- **Scans all folders** in `assets/reactions/`
- **Checks for content** (PNG/SVG files)
- **Updates the code** to include folders with content
- **Ignores empty folders** automatically

**Example Output:**
```
🔍 Scanning for new reaction folders...
📁 Found folders: blue, dotto, green, purple
✅ dotto: Has content
⚠️  blue: Empty (will be ignored)
📝 Updated reaction_picker.dart with folders: dotto
🎉 Done! Restart your app to see the new reaction tabs
```

### 5. Restart App

Restart your Flutter app to see the new reaction tabs!

## Configuration Options

### Generated Configuration Format

The `generate_reaction_config.dart` script automatically creates a configuration like this:

```json
{
  "reaction_sets": {
    "emoji": {
      "type": "emoji",
      "reactions": ["❤️", "👍", "😂", ...]
    },
    "your_theme": {
      "type": "folder",
      "folder": "your_theme",
      "file_types": ["png", "svg"],
      "files": ["heart.png", "thumbs_up.png", ...]
    }
  },
  "generated_at": "2026-02-01T15:16:02.195009",
  "total_sets": 2
}
```

### Configuration Fields

- **type**: `"emoji"` or `"folder"`
- **folder**: Folder name (for folder type)
- **file_types**: Array of supported file extensions found
- **files**: Explicit list of all files found in the folder
- **generated_at**: When the config was last updated
- **total_sets**: Number of reaction sets

### Build-Time vs Runtime

**Important**: Flutter assets are bundled at build time, so:
- **File Discovery**: Happens when you run the generator script
- **Runtime Loading**: Uses the explicit file list from config
- **No Directory Scanning**: Cannot scan folders at runtime
- **Manual Updates**: Run script when adding/removing files

## Current Reaction Sets

### Emoji (Default)
Standard Unicode emoji reactions that work on all devices.

### Green
Green-themed custom reaction set with PNG images.

### Blue  
Blue-themed custom reaction set with PNG images.

### Purple
Purple-themed custom reaction set with PNG images.

### Dotto
16x16 pixel art emoji set with SVG graphics from the Dotto Emoji project.

## Image Guidelines

### Recommended Dimensions
- **PNG**: 64x64px canvas, 32-48px artwork (centered)
- **SVG**: Any size (scalable)
- **Format**: PNG with transparency OR SVG
- **Background**: Transparent

### Design Tips
- **Consistent Style**: All reactions in a set should have the same visual style
- **Clear Recognition**: Icons should be easily recognizable at small sizes
- **Good Contrast**: Work well on both light and dark backgrounds
- **Rounded Design**: Match the app's rounded aesthetic

### File Naming Convention
Use lowercase with underscores:
- `heart.png` (not `Heart.png`)
- `thumbs_up.png` (not `thumbsUp.png`)
- `thinking_face.png` (not `thinkingFace.png`)

## Credit System

Each reaction folder can include a `credit.md` file that:
- Displays at the bottom of the reaction tab
- Supports basic markdown formatting
- Provides attribution to content creators
- Shows automatically when users view the reaction set

### Markdown Support
- Headers: `# Title`
- Bold: `**text**`
- Italic: `*text*`
- Lists: `- item`

## Testing

The system includes robust error handling:
- If an image file is missing, it shows a placeholder icon
- If credit.md is missing, it shows default credit text
- If configuration is invalid, it falls back to emoji-only
- The reaction picker continues to function normally

## Asset Configuration

The `pubspec.yaml` only needs the parent folder:
```yaml
flutter:
  uses-material-design: true
  assets:
    - assets/reactions/
```

This automatically includes all subfolders and files.