Paint

---
name: paint
version: "2.0.0"
author: BytesAgain
homepage: https://bytesagain.com
source: https://github.com/bytesagain/ai-skills
license: MIT-0
tags: [paint, tool, utility]
description: "Generate color palettes, gradients, and textures. Use when creating harmonized palettes, previewing schemes, converting color spaces, making patterns."
---

# Paint

A design toolkit for managing color palettes, gradients, swatches, and design assets. Each command category maintains its own timestamped log file, so you can organize design entries by purpose — palettes, previews, color conversions, harmonies, contrasts, gradients, swatches, and more. Includes built-in statistics, multi-format export, full-text search, and activity history.

All operations are logged with timestamps and stored locally in flat files for easy inspection and portability.

## Commands

| Command | Description |
|---------|-------------|
| `paint palette <text>` | Record a palette entry (or show recent palettes with no args) |
| `paint preview <text>` | Log a design preview note |
| `paint generate <text>` | Record a generated design asset or color scheme |
| `paint convert <text>` | Log a color space conversion (e.g., HEX to RGB) |
| `paint harmonize <text>` | Record a color harmony analysis |
| `paint contrast <text>` | Log a contrast check or accessibility evaluation |
| `paint export <text>` | Record an export operation or design asset output |
| `paint random <text>` | Log a randomly generated color or pattern |
| `paint browse <text>` | Record a browsed design reference or inspiration |
| `paint mix <text>` | Log a color mixing operation |
| `paint gradient <text>` | Record a gradient definition or transition |
| `paint swatch <text>` | Log a swatch entry or named color sample |
| `paint stats` | Show summary statistics across all categories |
| `paint search <term>` | Full-text search across all log files |
| `paint recent` | Show the 20 most recent activity entries |
| `paint status` | Health check — version, data dir, entry counts, disk usage |
| `paint help` | Show the built-in help message |
| `paint version` | Print the current version |

### How Entry Commands Work

Every entry command (`palette`, `preview`, `generate`, `convert`, `harmonize`, `contrast`, `export`, `random`, `browse`, `mix`, `gradient`, `swatch`) follows the same pattern:

- **With arguments:** Appends a timestamped entry (`YYYY-MM-DD HH:MM|<text>`) to the corresponding `.log` file and shows the new total count
- **Without arguments:** Shows the 20 most recent entries from that category's log file

## Data Storage

All data is stored in `~/.local/share/paint/` by default.

Files created in the data directory:

- **`palette.log`**, **`preview.log`**, **`generate.log`**, **`convert.log`**, **`harmonize.log`**, **`contrast.log`**, **`export.log`**, **`random.log`**, **`browse.log`**, **`mix.log`**, **`gradient.log`**, **`swatch.log`** — One log file per command category, each containing timestamped entries in `YYYY-MM-DD HH:MM|<text>` format
- **`history.log`** — Audit trail of every command executed with timestamps
- **`export.json`** / **`export.csv`** / **`export.txt`** — Generated by the stats/export functions

### Export Formats (via internal `_export` function)

- **json** — Array of objects with `type`, `time`, and `value` fields
- **csv** — Header row (`type,time,value`) followed by data rows
- **txt** — Human-readable sections grouped by category

## Requirements

- **bash** 4.0 or later (uses `set -euo pipefail`, `local` variables)
- **grep** — used by the `search` command for case-insensitive matching
- **Standard POSIX utilities** — `date`, `cat`, `echo`, `mkdir`, `wc`, `du`, `head`, `tail`, `basename`
- No external API keys or network access required
- No Python or Node.js dependencies

## When to Use

1. **Building a color palette library** — Use `palette` to log color combinations as you discover or create them, then `search` to find specific palettes later
2. **Tracking design iterations** — Use `preview` and `generate` to record design experiments, then `recent` to review your latest work
3. **Color space documentation** — Use `convert` to log color conversions (HEX → RGB → HSL) for reference in design systems or style guides
4. **Accessibility audits** — Use `contrast` to document contrast ratio checks between foreground and background colors for WCAG compliance
5. **Gradient and swatch management** — Use `gradient` and `swatch` to maintain a library of reusable color transitions and named color samples

## Examples

```bash
# Record a new palette
paint palette "Sunset: #FF6B35, #F7931E, #FCB040, #FDD835"
#=> [Paint] palette: Sunset: #FF6B35, #F7931E, #FCB040, #FDD835
#=> Saved. Total palette entries: 1

# Log a color conversion
paint convert "Brand blue: #2196F3 → rgb(33,150,243) → hsl(207,90%,54%)"
#=> [Paint] convert: Brand blue: #2196F3 → rgb(33,150,243) → hsl(207,90%,54%)
#=> Saved. Total convert entries: 1

# Record a gradient
paint gradient "Hero section: linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
#=> [Paint] gradient: Hero section: linear-gradient(135deg, #667eea 0%, #764ba2 100%)
#=> Saved. Total gradient entries: 1

# Check a contrast ratio
paint contrast "White #FFF on brand blue #2196F3: ratio 3.2:1 — fails AA for body text"
#=> [Paint] contrast: White #FFF on brand blue #2196F3: ratio 3.2:1 — fails AA for body text
#=> Saved. Total contrast entries: 1

# View statistics across all categories
paint stats
#=> === Paint Stats ===
#=>   palette: 1 entries
#=>   convert: 1 entries
#=>   gradient: 1 entries
#=>   contrast: 1 entries
#=>   ---
#=>   Total: 4 entries
#=>   Data size: 4.0K

# Search across all logs
paint search "blue"
#=> Searching for: blue
#=>   --- convert ---
#=>     2025-03-18 14:30|Brand blue: #2196F3 → rgb(33,150,243)
```

## Configuration

The data directory is hardcoded to `~/.local/share/paint/`. To use a custom location, modify the `DATA_DIR` variable in the script.

## How It Works

1. On every invocation, the tool ensures the data directory exists (`mkdir -p`)
2. The first argument selects the command via a `case` dispatch
3. Entry commands append a pipe-delimited line (`timestamp|text`) to their category-specific log file
4. Every command also appends to `history.log` for auditing
5. `stats` iterates over all `.log` files to produce aggregate counts
6. `search` uses `grep -i` across all log files for case-insensitive matching
7. All output goes to stdout for easy piping and redirection

---

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com