https://github.com/arceus-7/chroma16
Go package that turns any hex color or string into a ready-to-use 16-color terminal palette.
https://github.com/arceus-7/chroma16
Last synced: 29 days ago
JSON representation
Go package that turns any hex color or string into a ready-to-use 16-color terminal palette.
- Host: GitHub
- URL: https://github.com/arceus-7/chroma16
- Owner: Arceus-7
- License: mit
- Created: 2026-03-24T14:38:40.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-25T18:05:54.000Z (about 1 month ago)
- Last Synced: 2026-03-26T17:16:36.259Z (about 1 month ago)
- Language: Go
- Homepage: https://pkg.go.dev/github.com/arceus-7/chroma16
- Size: 52.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- fucking-awesome-go - chroma16 - Generate a harmonious 16-color terminal palette from a single seed color or string. (Command Line / Advanced Console UIs)
- awesome-go-with-stars - chroma16 - color terminal palette from a single seed color or string. | 2026-03-25 | (Build Automation / Advanced Console UIs)
- awesome-go - chroma16 - Generate a harmonious 16-color terminal palette from a single seed color or string. (Command Line / Advanced Console UIs)
README
# chroma16
[](https://app.codecov.io/github/Arceus-7/chroma16)
[](https://pkg.go.dev/github.com/arceus-7/chroma16)
[](https://go.dev/dl)
[](LICENSE)
[](https://goreportcard.com/report/github.com/arceus-7/chroma16)
Generate a complete, harmonious 16-color terminal palette from a single seed value — a hex color or any string.
---
## Install
```bash
go get github.com/arceus-7/chroma16
```
---
## Quick Start
```go
import "github.com/arceus-7/chroma16"
palette, err := chroma16.From("#FF6B35")
if err != nil {
log.Fatal(err)
}
palette.Preview() // prints a color swatch to your terminal
```
---
## Builder API
```go
palette, err := chroma16.New().
Seed("#2E86AB").
Mood(chroma16.Cool).
Contrast(chroma16.High).
Build()
if err != nil {
log.Fatal(err)
}
// Get all 16 hex colors
hexColors := palette.Hex()
// Apply to terminal session with ANSI OSC 4 sequences
for _, seq := range palette.ANSI() {
fmt.Print(seq)
}
```
---
## Examples
Three runnable examples live in the `examples/` directory:
| Program | Run | What it shows |
|---------|-----|---------------|
| `examples/basic` | `go run ./examples/basic` | `From()` with hex and string seeds |
| `examples/builder` | `go run ./examples/builder` | Every `Mood` × `Contrast` combo via the Builder |
| `examples/outputs` | `go run ./examples/outputs` | All output formats: Hex, RGB, ANSI, At(), Preview() |
| `examples/named` | `go run ./examples/named` | Using standard CSS named colors |
| `examples/export` | `go run ./examples/export` | Generate configs for Alacritty, Kitty, Windows Terminal, and Xresources |
| `examples/json` | `go run ./examples/json` | Marshalling and unmarshalling palettes to/from JSON |
| `examples/lipgloss` | `go run -tags lipgloss ./examples/lipgloss` | Deep integration with `charmbracelet/lipgloss` styles |
---
## The 16 Slots
Colors are indexed to match the standard 16-color terminal palette:
| Index | Name | Index | Name |
|-------|--------------|-------|---------------|
| 0 | Black | 8 | Bright Black |
| 1 | Red | 9 | Bright Red |
| 2 | Green | 10 | Bright Green |
| 3 | Yellow | 11 | Bright Yellow |
| 4 | Blue | 12 | Bright Blue |
| 5 | Magenta | 13 | Bright Magenta|
| 6 | Cyan | 14 | Bright Cyan |
| 7 | White | 15 | Bright White |
---
## Seed Input
| Seed type | Behaviour |
|-----------------|--------------------------------------------------|
| `"#FF6B35"` | Parsed as a hex color |
| `"FF6B35"` | Same — leading `#` is optional |
| `"ocean"` | Deterministically hashed via FNV-1a |
| `""` | Hashed (FNV-1a of empty string) — valid, stable |
| `"#GGGGGG"` | Returns an error (invalid hex characters) |
> **Note:** Named colors like `"red"` are hashed, not looked up by name.
> Named color lookup is planned for v0.2.
---
## Moods
| Constant | Effect |
|------------------|-----------------------------------------|
| `chroma16.Neutral` | Default — balanced hues |
| `chroma16.Warm` | Shift toward reds and oranges |
| `chroma16.Cool` | Shift toward blues and cyans |
| `chroma16.Dark` | Lower brightness throughout |
| `chroma16.Pastel` | Desaturated, soft, muted tones |
| `chroma16.Neon` | High saturation, vivid and energetic |
---
## Contrast
| Constant | Effect |
|-------------------|-------------------------------------|
| `chroma16.Medium` | Default — balanced luminance range |
| `chroma16.High` | Wider luminance spread |
| `chroma16.Low` | Narrower, softer luminance range |
---
## API Reference
### Functions
| Function | Returns | Description |
|----------------------|------------------|------------------------------------------------|
| `From(seed string)` | `Palette, error` | One-liner palette from a seed |
| `New()` | `*Builder` | Create a Builder for a customized palette |
| `Blend(p1, p2, t)` | `Palette` | Interpolate two palettes (t is 0 to 1) |
| `FromJSON(data)` | `Palette, error` | Restore a palette from JSON bytes |
### Palette Methods
| Method | Returns | Description |
|--------------|----------------|--------------------------------------------------------|
| `Hex()` | `[]string` | 16 hex strings in `#RRGGBB` format |
| `ANSI()` | `[]string` | 16 XTerm OSC 4 escape sequences |
| `RGB()` | `[][3]uint8` | 16 raw `[R, G, B]` triples |
| `At(i int)` | `string, error`| Hex string for slot `i`; error if `i` outside [0,15] |
| `Preview()` | — | Prints a color swatch to stdout |
| `Complement()`| `Palette` | Returns a new palette with opposite hues |
| `Analogous(d)`| `Palette` | Returns a new palette with hues shifted by `d` degrees |
| `ToAlacritty()`| `string` | Returns an Alacritty TOML colors block |
| `ToKitty()` | `string` | Returns a Kitty `.conf` text block |
| `ToWindowsTerminal(n)`| `string` | Returns a JSON block for Windows Terminal |
| `ToXresources()`| `string` | Returns an Xresources colors block |
| `MarshalJSON()`| `[]byte, err`| Serializes palette to JSON |
| `ToLipglossTheme()`| `LipglossTheme` | Available when built with `-tags lipgloss` |
### Builder Methods
| Method | Returns | Description |
|-------------------------|--------------|-------------------------------------|
| `Seed(seed string)` | `*Builder` | Set the seed value |
| `Mood(m Mood)` | `*Builder` | Set the palette mood |
| `Contrast(c Contrast)` | `*Builder` | Set the contrast level |
| `Build()` | `Palette, error` | Generate the final palette |
---
## Color Generation Algorithm
`chroma16` converts the seed to HSL, then places 8 hue relationships
(complement, primary, triadic, analogous) across the 16 slots. Normal colors
(0–7) use lower lightness; bright colors (8–15) use higher lightness. Mood
adjusts the hue shift, saturation multiplier, and lightness offset. Contrast
widens or narrows the lightness spread between the two groups.
All math is pure Go standard library — zero transitive dependencies.
---
## License
MIT © 2026 Arceus-7