✨ Overview

@usespaceui/gradients is the core color engine behind Space UI avatars and the others Space UI projects. It provides utilities to procedurally generate beautiful, deterministic color palettes and manipulate hex colors.

📦 Installation

pnpm add @usespaceui/gradients
# or
npm install @usespaceui/gradients
# or
yarn add @usespaceui/gradients

Zero dependencies.

🚀 Usage

Generating Deterministic Palettes

import { generatePalette } from '@usespaceui/gradients'

// Generates a deterministic harmonious 5-color palette for "Space UI"
const palette = generatePalette('Space UI')

console.log(palette.colors) // ['#bcd6ff', '#1f4fd8', '#0a1a4a', '#6073ff', '#59adef']

// Generate a random palette (auto-seeded)
const randomPalette = generatePalette()

// Force a specific generation mode
const presetOnly = generatePalette('seed')
const presetOnly = generatePalette('seed', { mode: 'presets' })
const randomOnly = generatePalette('seed', { mode: 'random' })
const niceOnly = generatePalette('seed', { mode: 'nice' })

// Provide your own custom colors
const customPalette = generatePalette('seed', { colors: ['#fff', '#000'] })

🧰 Utilities Included

• generatePalette(seed?: number | string, options?: PaletteOptions): GradientPalette Takes an optional seed string or number and returns a deterministic or random 5-color palette. Options allow you to specify the generation mode ('presets', 'random', or 'nice') or force colors.

• PRESET_PALETTES An array containing all the curated Space UI custom palettes used in the presets generation mode.

• NICE_PALETTES An array of 200 beautiful palettes named after stars, imported from nice-color-palettes and used in the nice generation mode.

• BASE_COLORS An array containing all the individual beautiful base colors used in the random generation mode.

📦 Related Packages

| Package | Description | | ---------------------------------------------------------------- | ---------------------------------------------- | | @usespaceui/avatars | Generative deterministic avatars | | @usespaceui/sounds | UI sound effects and audio interactions | | @usespaceui/squircle | Figma-style corner smoothing (Apple squircles) |

🪪 License

MIT — Free for commercial and personal use.

📚 Resources

• 🔍 Explore the palettes & Playground
• 🌍 Space UI Official Site

👏 Credits

• The NICE_PALETTES collection is powered by the amazing work from nice-color-palettes by the Experience-Monks team (and sourced from ColourLovers). We are grateful for their beautiful curations!

🛠 Maintenance

If you find a bug or have a feature request, please open an issue on GitHub. Engine internals are intentionally not part of the public API.