Color Palette

# Brok UI: Color Palette (`color-palette`)

A grid or scale strip of colour swatches with name + value labels and per-swatch copy-to-clipboard, for design-system documentation. Supports an optional heading label and a vertical scale orientation.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add color-palette
```

## Usage

```blade
<div class="flex w-full flex-col gap-6">
    <x-ui.color-palette
        label="Brand"
        :columns="3"
        :colors="[
            ['name' => 'Primary', 'value' => '#6366f1'],
            ['name' => 'Secondary', 'value' => '#a78bfa'],
            ['name' => 'Success', 'value' => '#22c55e'],
            ['name' => 'Warning', 'value' => '#f59e0b'],
            ['name' => 'Destructive', 'value' => '#ef4444'],
            ['name' => 'Info', 'value' => '#0ea5e9'],
        ]"
    />

    <x-ui.color-palette
        layout="scale"
        label="Blue ramp"
        :colors="[
            ['name' => '50', 'value' => '#eff6ff'],
            ['name' => '200', 'value' => '#bfdbfe'],
            ['name' => '400', 'value' => '#60a5fa'],
            ['name' => '600', 'value' => '#2563eb'],
            ['name' => '800', 'value' => '#1e40af'],
            ['name' => '950', 'value' => '#172554'],
        ]"
    />

    <div class="max-w-xs">
        <x-ui.color-palette
            layout="scale"
            orientation="vertical"
            label="Slate ramp (vertical)"
            :colors="[
                ['name' => '100', 'value' => '#f1f5f9'],
                ['name' => '300', 'value' => '#cbd5e1'],
                ['name' => '500', 'value' => '#64748b'],
                ['name' => '700', 'value' => '#334155'],
                ['name' => '900', 'value' => '#0f172a'],
            ]"
        />
    </div>
</div>
```

## Props

- `colors` (array, default `[]`)
- `layout` (string, default `grid`)
- `columns` (int, default `3`)
- `showName` (bool, default `true`)
- `showValue` (bool, default `true`)
- `label` (mixed|null, default `null`)
- `orientation` (string, default `horizontal`)

## Use when

- Use to document, inspect, and apply design-system decisions consistently across teams and AI tooling.
- Documenting a design system's colours with their token names and values.
- Showing one hue's scale as a strip, where the steps must read in order.

## Avoid when

- Do not present token-level controls to end users who only need product functionality.
- Letting someone pick a colour; color-swatch and color-dropdown are the input controls.
- Showing a single colour, where color-token states the name and value on its own.

## Anti-patterns

- Exposing implementation tokens as product settings

## Rules

- Use the `<brok:color-palette>` tag (or `<x-ui.color-palette>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/color-palette
- Registry JSON (files, props, contract): https://brokui.dev/r/open/color-palette.json

@props([
    'colors' => [],
    'layout' => 'grid',
    'columns' => 3,
    'showName' => true,
    'showValue' => true,
    'label' => null,
    'orientation' => 'horizontal',
])

@php
    $layout = in_array($layout, ['grid', 'scale'], true) ? $layout : 'grid';
    $orientation = in_array($orientation, ['horizontal', 'vertical'], true) ? $orientation : 'horizontal';
    $showName = filter_var($showName, FILTER_VALIDATE_BOOLEAN);
    $showValue = filter_var($showValue, FILTER_VALIDATE_BOOLEAN);

    // The swatch background is the one allowed inline colour: it is arbitrary
    // user data (any CSS colour string), never a hardcoded palette utility —
    // exactly like the color-swatch primitive.
    $columns = max(1, min(6, (int) $columns));
    $colMap = [
        1 => 'grid-cols-1',
        2 => 'grid-cols-2',
        3 => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
        4 => 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-4',
        5 => 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-5',
        6 => 'grid-cols-3 sm:grid-cols-4 lg:grid-cols-6',
    ];

    $entries = array_values(array_filter(array_map(function ($c) {
        $value = (string) ($c['value'] ?? '');

        return $value === '' ? null : ['name' => (string) ($c['name'] ?? $value), 'value' => $value];
    }, $colors)));

    $label = $label !== null ? (string) $label : null;
@endphp

<div
    data-slot="color-palette"
    data-layout="{{ $layout }}"
    data-orientation="{{ $orientation }}"
    {{ $attributes->merge(['class' => 'flex w-full flex-col gap-2']) }}
>
    @if ($label !== null && $label !== '')
        <div data-slot="color-palette-label" class="text-xs font-medium text-muted-foreground">{{ $label }}</div>
    @endif

    @if ($layout === 'scale' && $orientation === 'vertical')
        {{-- A vertical ramp reads as a list: a continuous colour rail on the
             start side (each step one cell of it), the step name and value on
             one line, and a copy button that appears on hover. --}}
        <ul class="overflow-hidden rounded-lg border border-border bg-card" role="list">
            @foreach ($entries as $entry)
                <li class="group/step flex items-center gap-3 border-b border-border pe-2 last:border-b-0">
                    <span class="h-10 w-12 shrink-0" style="background-color: {{ $entry['value'] }}" aria-hidden="true"></span>
                    <span class="flex min-w-0 flex-1 items-baseline gap-2 py-2">
                        @if ($showName)<span class="shrink-0 text-sm font-medium tabular-nums text-foreground">{{ $entry['name'] }}</span>@endif
                        @if ($showValue)<span class="truncate font-mono text-xs text-muted-foreground">{{ $entry['value'] }}</span>@endif
                    </span>
                    <x-ui.copy-button
                        :value="$entry['value']"
                        :label="__('Copy :name', ['name' => $entry['name']])"
                        :copied-label="__('Copied')"
                        class="size-7 h-7 w-7 shrink-0 border-transparent bg-transparent text-muted-foreground opacity-0 transition-opacity hover:bg-muted hover:text-foreground focus-visible:opacity-100 group-hover/step:opacity-100 motion-reduce:transition-none"
                    />
                </li>
            @endforeach
        </ul>
    @elseif ($layout === 'scale')
        {{-- A continuous ramp: a horizontal strip of colour cells with the step
             name under each and the value on hover. --}}
        <div class="flex overflow-hidden rounded-lg border border-border">
            @foreach ($entries as $entry)
                <div class="group/step flex min-w-0 flex-1 flex-col">
                    <div class="h-14 w-full" style="background-color: {{ $entry['value'] }}"></div>
                    <div class="flex items-center justify-between gap-1 bg-card px-2 py-1">
                        <div class="min-w-0">
                            @if ($showName)<div class="truncate text-xs font-medium tabular-nums text-foreground">{{ $entry['name'] }}</div>@endif
                            @if ($showValue)<div class="truncate font-mono text-2xs text-muted-foreground">{{ $entry['value'] }}</div>@endif
                        </div>
                        <x-ui.copy-button
                            :value="$entry['value']"
                            :label="__('Copy :name', ['name' => $entry['name']])"
                            :copied-label="__('Copied')"
                            class="size-5 h-5 w-5 shrink-0 border-transparent bg-transparent text-muted-foreground opacity-0 transition-opacity hover:bg-muted hover:text-foreground focus-visible:opacity-100 group-hover/step:opacity-100 motion-reduce:transition-none"
                        />
                    </div>
                </div>
            @endforeach
        </div>
    @else
        <div class="grid gap-2 {{ $colMap[$columns] }}">
            @foreach ($entries as $entry)
                <div data-slot="color-palette-swatch" class="flex items-center gap-3 rounded-md border border-border bg-card p-2">
                    <span class="size-10 shrink-0 rounded-md border border-border" style="background-color: {{ $entry['value'] }}" aria-hidden="true"></span>
                    <div class="min-w-0 flex-1">
                        @if ($showName)<div class="truncate text-sm font-medium text-foreground">{{ $entry['name'] }}</div>@endif
                        @if ($showValue)<div class="truncate font-mono text-xs text-muted-foreground">{{ $entry['value'] }}</div>@endif
                    </div>
                    <x-ui.copy-button
                        :value="$entry['value']"
                        :label="__('Copy :name', ['name' => $entry['name']])"
                        :copied-label="__('Copied')"
                        class="size-7 h-7 w-7 shrink-0 border-transparent bg-transparent text-muted-foreground hover:bg-muted hover:text-foreground"
                    />
                </div>
            @endforeach
        </div>
    @endif
</div>