Unparty Logo

CHARETTE

the ios app for color

UNCOLOR (uncolor-ios)

Location: https://github.com/unparty-app/uncolor-ios
Status: Active Development
Primary Purpose: Native iOS color palette management application for brand designers and creative professionals

Overview

UNCOLOR is a sophisticated color palette management app for iOS that empowers designers, brand managers, and creative professionals to organize, visualize, and export their brand color systems. Built with SwiftUI and featuring a local-first architecture, UNCOLOR provides a privacy-focused, offline-capable solution for managing brand identity colors, typography settings, and design guidelines.

Tech Stack

  • Framework: SwiftUI (iOS 14+)
  • Language: Swift
  • Storage: Local JSON files (Application Support directory)
    • Primary: Atomic JSON file operations with thread safety
    • Legacy: CloudKit integration (deprecated/sunset)
  • Platform: iOS (iPhone and iPad)
  • Build Tool: Xcode with standard iOS development workflows
  • Testing: Swift Testing framework (not XCTest)
  • Architecture Pattern: MVVM (Model-View-ViewModel)

Key Technologies

  • Vision Framework: For color extraction from images
  • PDFKit: For PDF export of brand palettes
  • File Sharing: iOS Files app integration for import/export
  • Custom Typography: Brandon Grotesque font family
  • SwiftUI Animations: Smooth transitions and interactive UI elements

Key Features

šŸŽØ Color Management

  • Custom Color Palettes: Create and organize unlimited brand color collections
  • Color Groups: Categorize colors within palettes (Primary, Secondary, Accent, Neutral, etc.)
  • Hex Color Support: Standard hex color codes for cross-platform compatibility
  • Visual Color Picker: Custom SwiftUI color picker with real-time preview
  • Image Color Extraction: Use Vision framework to extract colors from photos
  • Color Export: Share colors as CSS files or PDF brand guides

šŸŽÆ Brand Identity Management

  • Brand Profiles: Store brand name, tagline, and description with each palette
  • Typography Settings: Configure font families and sizes for brand elements
    • Brand name font and size
    • Tagline font and size
    • Description font and size
  • Custom Fonts: Brandon Grotesque family with multiple weights (Black, Thin, Light, Medium, Regular)
  • Brand Categories: Organize palettes by type or client

šŸ“¦ Local-First Storage

  • JSON-Based Persistence: Human-readable, inspectable data format
  • Atomic Operations: Thread-safe file operations with file locking
  • Configurable Storage Limits: User-defined limits from 5MB to 500MB
  • Storage Usage Monitoring: Real-time tracking with color-coded progress indicators
  • Proactive Warnings: Alerts at 80% storage capacity
  • Automatic Migration: Seamless migration from legacy UserDefaults storage

šŸ”„ Import/Export

  • Files App Integration: Native iOS file picker and sharing
  • PDF Export: Generate professional brand style guides
  • CSS Export: Export color palettes as CSS custom properties
  • AirDrop Support: Quick sharing to other devices
  • Data Portability: Full export/import of palette data

šŸŽ­ User Experience

  • Grid/List Toggle: Switch between grid and list views for palette display
  • Search & Filter: Real-time search across palette names
  • Sort Options: By date created, last modified, or alphabetical
  • Welcome/Onboarding: Guided experience for first-time users
  • Dark Mode Ready: Adaptive color system with neon accents
  • Smooth Animations: Polished transitions and interactions

šŸ”’ Privacy & Control

  • No Cloud Sync Required: All data stored locally on device
  • Optional Telemetry: Opt-in analytics (privacy-first approach)
  • Transparent Data Format: JSON files users can inspect and backup
  • No Account Required: Fully functional without sign-in

Architecture

Code

UNCOLOR (SwiftUI iOS App)
ā”œā”€ā”€ Views (SwiftUI)
ā”‚   ā”œā”€ā”€ ContentView.swift (Main interface with grid/list toggle)
ā”‚   ā”œā”€ā”€ WelcomeView.swift (Onboarding/empty state)
ā”‚   ā”œā”€ā”€ AddColorView.swift (Color creation with Vision integration)
ā”‚   ā”œā”€ā”€ TypographyView.swift (Font management)
ā”‚   ā””ā”€ā”€ Settings/
ā”‚       ā”œā”€ā”€ SettingsView.swift
ā”‚       ā””ā”€ā”€ StorageSettingsView.swift (Storage management UI)
ā”œā”€ā”€ Models (Data)
ā”‚   ā”œā”€ā”€ ColorPalette.swift (Main entity: brand + colors + typography)
ā”‚   ā”œā”€ā”€ CustomColor.swift (Individual color with metadata)
ā”‚   ā”œā”€ā”€ StorageSettings.swift (User preferences)
ā”‚   ā””ā”€ā”€ StorageSettingsData.swift (Codable bridge for JSON)
ā”œā”€ā”€ Storage (Persistence)
ā”‚   ā”œā”€ā”€ LocalJSONStorageManager.swift (Primary storage system)
ā”‚   ā”‚   - Atomic JSON operations with file locking
ā”‚   ā”‚   - Thread-safe DispatchQueue
ā”‚   ā”‚   - Auto-migration from UserDefaults
ā”‚   ā”‚   - Files: colors.json, palettes.json, settings.json
ā”‚   ā”‚   - Location: ~/Library/Application Support/UNCOLOR/
ā”‚   ā””ā”€ā”€ StorageSettings.swift (Singleton for preferences)
ā”œā”€ā”€ BrandInfo (Export & Visualization)
ā”‚   ā”œā”€ā”€ ExportManager.swift (PDF/CSS generation)
ā”‚   ā”œā”€ā”€ PDFContent.swift (PDF layout)
ā”‚   ā”œā”€ā”€ BrandCircle.swift (Visual components)
ā”‚   ā”œā”€ā”€ BrandCategory.swift
ā”‚   ā”œā”€ā”€ BrandScroll.swift
ā”‚   ā”œā”€ā”€ FullScreenPanel.swift
ā”‚   ā””ā”€ā”€ FullScreenPanelScroll.swift
ā”œā”€ā”€ Typography
ā”‚   ā””ā”€ā”€ TypographyFonts.swift (Centralized font management)
ā”œā”€ā”€ Color Utilities
ā”‚   ā”œā”€ā”€ Color.swift (Extensions)
ā”‚   ā”œā”€ā”€ CustomColors.swift
ā”‚   ā”œā”€ā”€ WelcomeColors.swift
ā”‚   ā””ā”€ā”€ ColorPalette.swift (Color groups and organization)
ā”œā”€ā”€ Design Components
ā”‚   ā”œā”€ā”€ NeonText.swift (Neon UI effects)
ā”‚   ā””ā”€ā”€ AppTitle.swift (Branded header)
ā”œā”€ā”€ UI Components & Utilities
ā”‚   ā””ā”€ā”€ UnpartyColorPicker.swift (Custom picker)
ā””ā”€ā”€ CloudKit (Legacy - Deprecated)
    ā””ā”€ā”€ [Sunset code to be removed]

Storage Architecture

Local-First Design:

  1. Primary Storage: Local JSON files with atomic write operations
  2. Storage Location: ~/Library/Application Support/UNCOLOR/
  3. Data Files:
    • colors.json - Individual color definitions
    • palettes.json - Brand palette collections
    • settings.json - User preferences and limits
  4. Thread Safety: Dedicated fileAccessQueue for serialized access
  5. Atomic Writes: Temporary files + FileManager.replaceItem() for consistency
  6. Migration: Automatic UserDefaults ā†’ JSON on first launch

Data Model

Code

ColorPalette
ā”œā”€ā”€ id: String (UUID)
ā”œā”€ā”€ name: String
ā”œā”€ā”€ timestamp: Date
ā”œā”€ā”€ Brand Identity
ā”‚   ā”œā”€ā”€ brandName: String
ā”‚   ā”œā”€ā”€ brandTagline: String
ā”‚   ā”œā”€ā”€ brandDescription: String
ā”‚   ā””ā”€ā”€ brandCategory: String
ā”œā”€ā”€ Typography Settings
ā”‚   ā”œā”€ā”€ brandNameFont: String
ā”‚   ā”œā”€ā”€ brandNameSize: Int
ā”‚   ā”œā”€ā”€ brandTaglineFont: String
ā”‚   ā”œā”€ā”€ brandTaglineSize: Int
ā”‚   ā””ā”€ā”€ brandDescriptionSize: Int
ā””ā”€ā”€ colorGroups: [String: [CustomColor]]
    ā””ā”€ā”€ CustomColor
        ā”œā”€ā”€ id: String (UUID)
        ā”œā”€ā”€ name: String
        ā”œā”€ā”€ hexCode: String
        ā”œā”€ā”€ category: String
        ā””ā”€ā”€ timestamp: Date

Integration Points

External Services

  • Files App: Native iOS document picker and file sharing
  • Vision Framework: Apple's ML framework for image color extraction
  • PDFKit: Apple's framework for PDF generation
  • AirDrop: iOS native sharing protocol

File Format Support

  • Import: JSON palette files, images (for color extraction)
  • Export: PDF (brand guides), CSS (color variables), JSON (data backup)

Legacy Integration (Deprecated)

  • CloudKit: Previously used for iCloud sync (sunset in favor of local storage)
  • Note: CloudKit code remains in codebase but is no longer active

Business Value

ABOUT - Understanding Brand Identity

UNCOLOR helps users understand and organize their brand color systems:

  • Visual exploration of brand color relationships
  • Color palette templates and inspiration
  • Typography pairing with color schemes
  • Brand guideline documentation

User Insight: Designers and brand managers gain clarity on their brand's visual identity by seeing all colors organized in one place, with context and relationships clearly defined.

BUILD - Creating Brand Assets

UNCOLOR enables users to create professional brand resources:

  • Generate PDF brand style guides for client presentations
  • Export CSS files for web development handoff
  • Create multiple palette variations for A/B testing
  • Document brand evolution over time

Creator Control: Users maintain full ownership of their color data with local storage, no vendor lock-in, and complete export capabilities.

CONNECT - Sharing Brand Guidelines

UNCOLOR facilitates sharing brand assets with teams and clients:

  • AirDrop brand guides to colleagues instantly
  • Share CSS files directly with developers
  • Export palettes for use in other design tools
  • Document and communicate brand standards

Privacy & Cost-Sensitivity:

  • No subscription required - one-time purchase model
  • No cloud storage costs - everything stays on device
  • No data collection - optional telemetry only
  • Transparent pricing - no hidden fees

Relationship to UNPARTY Ecosystem

Position in Ecosystem

UNCOLOR is a user-facing creative tool within the UNPARTY ecosystem, focusing on empowering designers and brand managers with professional color management capabilities while maintaining privacy and local control.

Integration with Other Repositories

  • theunpartyapp: Could integrate color palettes for web design consistency
  • theunpartyunppp: Shares MVVM architecture patterns and SwiftUI best practices
  • theunpartyrunway: Subject to development velocity tracking and cost analysis
  • theunpartycrawler: Could analyze color usage patterns in design conversations

Data Flow

Code

Users ā†’ UNCOLOR (Color Management) ā†’ Export Files ā†’ Design Tools
                ā†“
        Local JSON Storage (Privacy-First)
                ā†“
        Export Formats:
        - PDF (Brand Guides)
        - CSS (Web Development)
        - JSON (Data Portability)

Alignment with UNPARTY Principles

Creator Ownership āœ…

  • Local-first storage: Users own their data, stored on their device
  • No cloud dependency: Full functionality without external services
  • Export capabilities: Complete data portability in standard formats

Privacy Protection āœ…

  • No required accounts: App works fully without sign-in
  • Optional telemetry: Analytics are opt-in only
  • Transparent data: Human-readable JSON format users can inspect

Cost Sensitivity āœ…

  • No subscription model: One-time purchase (when applicable)
  • No cloud storage fees: All storage is local
  • Configurable limits: Users control storage usage (5MB-500MB)
  • Efficient storage: Proactive warnings at 80% capacity

Getting Started

Prerequisites

  • Xcode: Version 14+ (for iOS 14+ deployment target)
  • macOS: Big Sur (11.0) or later
  • iOS Device/Simulator: iOS 14+

Opening the Project

bash

# Clone the repository
git clone https://github.com/unparty-app/uncolor-ios.git
cd uncolor-ios

# Open in Xcode
open UNCOLOR.xcodeproj

Building

  1. Open UNCOLOR.xcodeproj in Xcode
  2. Select your target device or simulator
  3. Press āŒ˜+B to build or āŒ˜+R to run

Running Tests

  1. Open Xcode Test Navigator (āŒ˜+6)
  2. Press āŒ˜+U to run all tests
  3. Primary test suite: UNCOLORTests/LocalJSONStorageTests.swift

Project Structure

  • UNCOLOR/: Main app source code
  • UNCOLORTests/: Unit tests (Swift Testing framework)
  • UNCOLORUITests/: UI and integration tests
  • UNCOLOR.xcodeproj/: Xcode project file

Development

Architecture Pattern

MVVM (Model-View-ViewModel):

  • Models: ColorPalette, CustomColor, StorageSettings
  • Views: SwiftUI views in Views/ directory
  • ViewModels: ObservableObject classes (e.g., LocalJSONStorageManager)

Key Components

1. LocalJSONStorageManager

Primary storage system (UNCOLOR/Storage/LocalJSONStorageManager.swift):

  • Singleton pattern with @Published properties for SwiftUI reactivity
  • Thread-safe operations using dedicated DispatchQueue
  • Atomic file operations for data consistency
  • Automatic migration from legacy storage

Key Methods:

  • savePalettes(): Atomic write to palettes.json
  • loadPalettes(): Read from JSON with error handling
  • exportData(): Generate shareable data files
  • importData(): Parse and validate imported files

2. StorageSettings

User preferences manager (UNCOLOR/Storage/StorageSettings.swift):

  • Singleton pattern with ObservableObject
  • Configurable storage limits with real-time tracking
  • Privacy controls (telemetry opt-in)
  • Persistent settings in settings.json

3. ContentView

Main app interface (UNCOLOR/ContentView.swift):

  • Grid/list toggle for palette display
  • Search and sort functionality
  • Integration with storage manager
  • Navigation to add/edit views

Custom Fonts

Brandon Grotesque family loaded via Info.plist (UIAppFonts):

  • BrandonGrotesque-Black.otf
  • BrandonGrotesque-Thin.otf
  • BrandonGrotesque-Light.otf
  • BrandonGrotesque-Medium.otf
  • BrandonGrotesque-Regular.otf

Managed centrally through TypographyFonts.swift.

Storage Management

  • Default Limit: 50MB
  • Range: 5MB - 500MB (user-configurable)
  • Warning Threshold: 80% of limit
  • Real-time Tracking: Async size calculation to prevent UI blocking

Testing

Test Framework

Uses Swift Testing framework (not XCTest).

Primary Test Suite

UNCOLORTests/LocalJSONStorageTests.swift:

  • Atomic operation validation
  • Data consistency checks
  • Migration scenario testing
  • Thread safety verification
  • Performance benchmarks

Running Tests

bash

# In Xcode
āŒ˜+U (Run all tests)

# Or use Test Navigator (āŒ˜+6)

Test Coverage Areas

  • āœ… JSON serialization/deserialization
  • āœ… Atomic file operations
  • āœ… Storage limit enforcement
  • āœ… Migration from UserDefaults
  • āœ… Thread safety and race conditions
  • āœ… Error handling and recovery

Configuration

Bundle Identifier

  • App: UNPARTY.UNCOLOR (Xcode project)
  • Info.plist: com.unparty.uncolor

Capabilities

  • File Sharing: Enabled (UIFileSharingEnabled)
  • Documents in Place: Supported (LSSupportsOpeningDocumentsInPlace)
  • iCloud Containers: Configured (legacy from CloudKit era)
  • Background Modes: Remote notifications

Supported File Types

  • CSS Files: Viewer role
  • PDF Documents: Viewer role

Important Implementation Details

CloudKit Sunset āš ļø

  • Status: CloudKit integration is deprecated
  • Current State: Legacy code remains in codebase but is inactive
  • Future Work: CloudKit code should be removed/refactored out
  • Migration: Automatic migration from CloudKit data to local JSON (if applicable)

Thread Safety šŸ”’

  • All file operations use fileAccessQueue for serialization
  • Prevents race conditions and data corruption
  • Async updates to storage size to prevent UI blocking

Atomic Operations āš›ļø

  • Uses temporary files and FileManager.replaceItem() for consistency
  • Ensures data integrity even if app crashes during write
  • All-or-nothing write guarantees

Storage Strategy šŸ’¾

  • Primary: Local JSON files in Application Support
  • Format: Human-readable JSON for transparency
  • Backup: Users can manually backup/restore via Files app
  • Privacy: No data sent to external servers

Documentation

Key Documentation Files

  • CLAUDE.md: AI assistance guidance and architecture overview
  • README.md: This file - comprehensive project documentation
  • Info.plist: App configuration and capabilities
  • UNCOLOR.entitlements: App permissions and entitlements

Code Documentation

  • Inline comments for complex logic
  • MARK comments for code organization
  • SwiftDoc-style documentation for public APIs

Roadmap

Current Focus

  • āœ… Local-first storage implementation
  • āœ… Storage management UI
  • āœ… Export/import functionality
  • šŸš§ CloudKit code removal/refactoring

Future Enhancements

  • Color accessibility checker (WCAG compliance)
  • Gradient palette support
  • Color harmony suggestions (complementary, analogous, etc.)
  • Multi-device sync (iCloud Drive integration)
  • Collaboration features (shared palettes)
  • Integration with design tools (Figma, Sketch plugins)
  • Advanced export formats (Adobe Swatch, Procreate palette)

Contributing

Development Guidelines

  1. Follow existing MVVM architecture patterns
  2. Use SwiftUI best practices
  3. Ensure thread-safe operations for storage
  4. Write tests for new storage functionality
  5. Update CLAUDE.md for significant architecture changes
  6. Use Swift Testing framework (not XCTest)

Commit Standards

  • Use clear, descriptive commit messages
  • Reference issue numbers when applicable
  • Follow conventional commits format when possible

Code Quality

  • Linting: SwiftLint (if configured)
  • Type Safety: Leverage Swift's strong typing
  • Error Handling: Use Result types and proper error propagation
  • Performance: Profile storage operations for large datasets

License

[License information to be added]

Contact & Support

Repository: https://github.com/unparty-app/uncolor-ios
Organization: UNPARTY LLC
Ecosystem: Part of the UNPARTY creative tools ecosystem

For questions, issues, or contributions, please use GitHub Issues.

Acknowledgments

  • SwiftUI: Apple's declarative UI framework
  • Vision Framework: Apple's ML framework for image analysis
  • Brandon Grotesque: Custom typography
  • UNPARTY Ecosystem: Integration with broader creator tools platform

Status: āœ… Active Development
Documentation Version: 1.0.0
Last Updated: 2024-10-29
Maintained By: UNPARTY LLC Development Team

Focus: Empowering creators with professional color management while protecting ownership, privacy, and cost-sensitivity through local-first architecture. šŸŽØ