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

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

# 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