theunpartybrand

Location: /Users/UNPARTYLLC/theunpartybrand/
Status: Active Development
Primary Purpose: Brand color search and analysis tool for the UNPARTY ecosystem

Tech Stack

• Language: Bash (Shell Script)
• Platform: Unix/Linux/macOS (Cross-platform CLI)
• Dependencies: Standard Unix utilities (grep, find, tput)
• Configuration: .env file for environment-based settings
• Testing: Bash test suite with performance validation

Key Features

Core Functionality

• Hex Color Discovery: Automatically finds all hex color codes (#fff, #f9c22e) across project files
• Multi-format Support: Searches CSS, SCSS, JS, TS, Swift, HTML, JSON, Markdown, and more
• Interactive Menu System: User-friendly terminal interface with keyboard navigation
• Color Preview Mode: Visual swatches showing actual colors in the terminal
• Export Capabilities: Save discovered colors to timestamped files
• Smart Path Detection: Automatically restricts searches to UNPARTY project directories

Performance Optimizations

• Timeout Protection: 30-second safety timeouts prevent infinite hangs
• Directory Depth Limiting: Searches limited to 3 levels deep for speed
• Result Capping: Maximum 1000 results to prevent memory issues
• Exclude Patterns: Automatically skips node_modules, .git, build artifacts
• Signal Handling: Graceful Ctrl+C handling with branded cleanup messages

Accessibility Features

• Terminal Detection: Automatically adapts to terminal color capabilities
• No-Color Mode: Fully functional without ANSI color support
• Simple Text Mode: Clean output for screen readers and automation
• Keyboard Navigation: Tab, arrow keys, and letter shortcuts
• Timeout Feedback: Clear messaging when inputs time out

Brand Integration

• UNPARTY Yellow: Primary brand color (#f9c22e) with 24-bit/256-color/8-color fallbacks
• ASCII Art Branding: Large UNPARTY logo display with color safety
• Consistent Messaging: All prompts and errors maintain brand voice
• Visual Hierarchy: Color-coded menus (green=action, yellow=warning, red=error)

Architecture

Brand Tool (Bash)
├── Environment Configuration (.env)
│   ├── UNPARTY_BASE_PATH (base directory)
│   ├── PROJECT_DIRS (searchable projects)
│   ├── EXCLUDE_DIRS (ignored directories)
│   └── INCLUDE_EXTENSIONS (file types)
├── Core Script (colors.sh)
│   ├── Color Safety Functions
│   ├── Interactive Menu System
│   ├── Directory Navigation
│   ├── File Type Customization
│   ├── Color Search Engine
│   └── Export Functions
├── Test Suite (colors-test/)
│   ├── Performance Tests
│   ├── Unit Tests
│   ├── Integration Tests
│   └── Sample Files (CSS, JS, Swift, HTML)
└── Documentation
    ├── README.md (this file)
    └── colors-test/README.md (test documentation)

Data Flow

Installation & Usage

Setup

# Clone the repository
cd /Users/UNPARTYLLC
git clone https://github.com/unparty-app/theunpartybrand.git
cd theunpartybrand

# Make script executable
chmod +x colors.sh

# Configure your environment (optional)
# Edit .env to match your local paths
nano .env

Basic Usage

# Interactive mode (recommended)
./colors.sh

# Simple non-interactive mode
./colors.sh --simple

# Accessibility mode (no colors)
./colors.sh --no-color --simple

# Verbose mode
./colors.sh --verbose

Interactive Menu Options

1. Search for hex colors - Standard search with table output
2. Search with color preview - Shows actual color swatches in terminal
3. Export results to file - Saves to colors_YYYYMMDD_HHMMSS.txt
4. Change search directory - Navigate between UNPARTY projects
5. Customize file types - Modify which extensions to search
6. Help & accessibility - View keyboard shortcuts and options
7. Quit - Exit the tool

Configuration

Environment Variables (.env)

# Base directory for UNPARTY projects
UNPARTY_BASE_PATH="/Users/UNPARTYLLC"

# Comma-separated list of project directories (relative or absolute)
PROJECT_DIRS="theappweb,theunpartyapi,theunpartyapp,theunpartybrand,..."

# Directories to exclude from search
EXCLUDE_DIRS=".git,node_modules,build,dist,coverage,__pycache__,.build,DerivedData"

# File extensions to include in search
INCLUDE_EXTENSIONS="css,scss,js,ts,tsx,jsx,html,json,md,yml,yaml,env,swift,storyboard,xib"

# Regex pattern for hex colors
COLOR_REGEX='#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})'

Supported File Types

Testing

Test Suite Structure

colors-test/
├── run-all-tests.sh           # Master test runner
├── test-scripts/
│   ├── performance-test.sh    # Timeout and hang detection
│   ├── unit-tests.sh          # Function-level validation
│   └── integration-tests.sh   # End-to-end workflows
└── sample-files/
    ├── css/                   # CSS color definitions
    ├── js/                    # JavaScript theme files
    ├── swift/                 # Swift UIColor extensions
    └── html/                  # HTML with inline styles

Running Tests

# Run full test suite
cd colors-test
./run-all-tests.sh

# Run specific test category
./test-scripts/performance-test.sh
./test-scripts/unit-tests.sh
./test-scripts/integration-tests.sh

Test Coverage

• ✅ Timeout protection validation
• ✅ Directory navigation testing
• ✅ Color detection accuracy
• ✅ Memory usage monitoring
• ✅ Signal handling (Ctrl+C)
• ✅ File type filtering
• ✅ Export functionality
• ✅ Color preview mode
• ✅ Brand color detection
• ✅ Accessibility features

Integration Points

Internal UNPARTY Ecosystem

• theunpartyapp (Web): Validates web design system colors
• theunpartyunppp (iOS): Checks SwiftUI color consistency
• theunpartyapi: Reviews API documentation color codes
• theunpartycrawler: Analyzes conversation data with color metadata
• theunpartyrunway: Development workflow color audit automation

External Services

• Terminal Emulators: iTerm2, Alacritty, Kitty, VS Code terminal
• Color Standards: Hex color codes (3-digit and 6-digit formats)
• File Systems: Unix-compatible paths with symlink support

CI/CD Integration (Potential)

# Example GitHub Actions usage
- name: Audit Brand Colors
  run: |
    cd theunpartybrand
    ./colors.sh --simple --export
    # Verify brand colors are present
    grep "#f9c22e" colors_*.txt

Business Value

ABOUT: Understanding Brand Consistency

• Color Audit: Discover all color codes used across the entire UNPARTY ecosystem
• Brand Compliance: Verify UNPARTY yellow (#f9c22e) is consistently used
• Palette Analysis: Identify color palette drift between projects
• Documentation: Generate comprehensive color usage reports

BUILD: Enabling Design Systems

• Design System Validation: Ensure all projects use approved colors
• Refactoring Support: Find and replace deprecated color codes
• Cross-Platform Sync: Verify iOS and Web use matching color values
• Theme Development: Extract colors for new theme implementations

CONNECT: Facilitating Collaboration

• Designer-Developer Bridge: Shared color vocabulary across teams
• Onboarding: New developers can quickly understand color usage
• Documentation: Exportable color lists for design handoffs
• Quality Assurance: Automated color consistency checks

Relationship to Ecosystem

How theunpartybrand Connects

Cross-Repository Use Cases

1. Web → Brand: Extract colors.sh to validate Tailwind CSS configuration
2. iOS → Brand: Verify SwiftUI Color extensions match web design system
3. Runway → Brand: Automate brand compliance checks in CI/CD pipelines
4. Crawler → Brand: Include color analysis in conversation data exports

Security & Privacy

Security Features

• ✅ No remote connections or network access
• ✅ Read-only file operations (no modifications to source files)
• ✅ Safe environment variable handling (no eval or dynamic execution)
• ✅ Limited search scope (only UNPARTY project directories)
• ✅ Timeout protection prevents resource exhaustion
• ✅ Signal handling prevents zombie processes

Privacy Protection

• ✅ Local-only operation (no data transmission)
• ✅ Configurable paths via .env (no hardcoded credentials)
• ✅ No logging of file contents or paths to external services
• ✅ User-controlled export locations

Cost Sensitivity

• ✅ Zero external API costs (fully local)
• ✅ Minimal CPU usage with depth limiting
• ✅ No cloud services required
• ✅ One-time setup, unlimited searches

Development Guidelines

Adding New Features

# 1. Create feature branch
git checkout -b feature/new-search-mode

# 2. Modify colors.sh
nano colors.sh

# 3. Add test cases
cd colors-test/test-scripts
nano integration-tests.sh

# 4. Run tests
cd ..
./run-all-tests.sh

# 5. Commit changes
git add colors.sh colors-test/
git commit -m "Add new search mode with test coverage"

Code Style Guidelines

• Shell Script Best Practices: Use shellcheck for linting
• Error Handling: Always provide user-friendly error messages
• Brand Voice: Maintain UNPARTY friendly, professional tone
• Accessibility: Test all features with --no-color mode
• Performance: Add timeouts to all user input operations

Testing Requirements

• All new features must have test coverage
• Performance tests must pass (no hangs)
• Brand color detection must work in sample files
• Accessibility mode must remain functional

Troubleshooting

Common Issues

Problem: Script hangs waiting for input

# Solution: Use command-line arguments to skip interactive mode
./colors.sh --simple --export

Problem: Colors not displaying correctly

# Solution: Check terminal color support
echo $TERM
# Use accessibility mode if needed
./colors.sh --no-color

Problem: No projects found

# Solution: Verify .env configuration
cat .env
# Update UNPARTY_BASE_PATH to match your system

Problem: Permission denied

# Solution: Make script executable
chmod +x colors.sh

Roadmap

Planned Features

• GitHub Actions integration for automated color audits
• JSON export format for programmatic analysis
• Color contrast ratio calculations (WCAG compliance)
• RGB/HSL color format support
• Duplicate color detection and reporting
• Color usage frequency statistics
• Integration with Figma design tokens
• Web-based visualization dashboard

Maintenance Tasks

• Add shellcheck CI/CD validation
• Expand test coverage to 90%+
• Create Docker container for consistent environment
• Add man page documentation
• Publish to Homebrew for easy installation

Contributing

Contribution Checklist

When contributing to theunpartybrand:

• Test changes with ./colors-test/run-all-tests.sh
• Verify brand colors (#f9c22e) display correctly
• Test accessibility features (--no-color mode)
• Maintain performance (no hangs or excessive memory)
• Update documentation for new features
• Use consistent error messaging style
• Add test cases for new functionality

Related Documentation

• colors-test/README.md - Comprehensive test suite documentation
• [2025-07-27-colors-sh.md] - Historical refactoring notes (Issue #2)
• .env - Environment configuration with inline comments

UNPARTY Ecosystem Documentation

• theunpartyrunway/docs/architecture/ - Overall architecture evolution
• theunpartyapp/CLAUDE.md - Web app development guide
• theunpartyunppp/CLAUDE.md - Native app development guide
• theunpartycrawler/README.md - Analytics intelligence setup

Quick Reference

Command Line Arguments

Keyboard Shortcuts (Interactive Mode)

Exit Codes

Metrics & Analytics

Performance Benchmarks

Test Suite Results

License & Credits

Repository: theunpartybrand
Organization: UNPARTY LLC
License: Proprietary (Internal UNPARTY use)
Maintained By: UNPARTY Development Team
Created: 2025
Last Updated: 2025-10-29

Acknowledgments

• Bash shell scripting best practices from shellcheck
• Terminal color support inspired by modern terminal emulators
• Test methodology based on industry-standard CI/CD patterns
• UNPARTY brand guidelines enforced throughout

Status: ✅ Production Ready
Focus: Brand consistency through automated color discovery and validation across the UNPARTY ecosystem while protecting creator ownership, privacy, and cost-sensitivity.