Token

# Brok UI: Token (`token`)

The base design-token documentation primitive: a name → value chip whose value is revealed in a tooltip on hover/focus, with click-to-copy. Specialised token variants compose it.

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

## Install

```bash
php artisan ui:add token
```

## Usage

```blade
<div class="flex flex-wrap items-center gap-3">
    <x-ui.token name="color.primary" value="hsl(222 47% 11%)" />
    <x-ui.token name="radius.lg" value="0.5rem" />
    <x-ui.token name="space.4" value="1rem" />
    <x-ui.token name="z.modal" value="1300" :copyable="false" />
</div>
```

## Props

- `name` (string, default ``) — Token name shown as the visible, focusable trigger.
- `value` (string, default ``) — Token value revealed in the tooltip and used as the copy-to-clipboard value.
- `copyable` (bool, default `true`) — Shows the trailing copy-to-clipboard button when true.
- `side` (string, default `top`) — Tooltip placement relative to the name.

## Use when

- Use to document, inspect, and apply design-system decisions consistently across teams and AI tooling.
- Documenting any raw design token, by name and value, on a style guide or token reference page.
- Building a new typed token chip (colour, spacing, radius, …) by composing this primitive and supplying an indicator.

## Avoid when

- Do not present token-level controls to end users who only need product functionality.
- Documenting a colour, typography, spacing, radius, elevation, duration, number or order token; use the matching typed *-token component instead so the indicator renders automatically from the value.
- Documenting a colour value specifically; use color-token instead.

## Anti-patterns

- Exposing implementation tokens as product settings

## Rules

- Use the `<brok:token>` tag (or `<x-ui.token>`) 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/token
- Registry JSON (files, props, contract): https://brokui.dev/r/open/token.json

@props([
    'name' => '',
    'value' => '',
    'copyable' => true,
    'side' => 'top',
])

{{--
    Token — the base design-token documentation primitive (tokenui.dev-inspired).

    Renders a name → value pair as an interactive chip: the token NAME is the
    visible trigger, the VALUE is revealed in a tooltip on hover/focus, and a
    copy-button copies the value to the clipboard. Specialised variants
    (color-token, spacing-token, radius-token, …) compose this and pass a leading
    visual through the `indicator` slot. Use the default `$slot` for fully custom
    composition.
--}}
@php
    $copyable = filter_var($copyable, FILTER_VALIDATE_BOOLEAN);
    $name = (string) $name;
    $value = (string) $value;
    $copyValue = $value !== '' ? $value : $name;
    // A typed chip built on this primitive (color-token, spacing-token, …)
    // passes its own data-slot; the browser keeps only the first of two
    // identical attributes, so read the override and print exactly one.
    $slotName = (string) ($attributes->get('data-slot') ?: 'token');
@endphp

<span
    data-slot="{{ $slotName }}"
    {{ $attributes->except('data-slot')->merge(['class' => 'group/token inline-flex items-center gap-1 rounded-md border border-border bg-card py-0.5 pe-0.5 ps-1 align-middle']) }}
>
    {{-- Optional leading visual (colour chip, radius box, type sample …) supplied by variants. --}}
    @isset($indicator)
        <span data-slot="token-indicator" class="inline-flex shrink-0 items-center justify-center" aria-hidden="true">{{ $indicator }}</span>
    @endisset

    @if ($value !== '')
        {{-- The name is the trigger; hovering / focusing it reveals the value. --}}
        <x-ui.tooltip :text="$value" :side="$side" class="align-middle">
            <span
                data-slot="token-name"
                tabindex="0"
                class="cursor-default rounded px-1 font-mono text-xs font-medium text-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring"
            >{{ $name }}</span>
        </x-ui.tooltip>
    @else
        <span data-slot="token-name" class="px-1 font-mono text-xs font-medium text-foreground">{{ $name }}</span>
    @endif

    @if ($copyable && $copyValue !== '')
        <x-ui.copy-button
            :value="$copyValue"
            :label="__('Copy :name', ['name' => $name !== '' ? $name : $value])"
            :copied-label="__('Copied')"
            class="size-6 h-6 w-6 shrink-0 border-transparent bg-transparent text-muted-foreground hover:bg-muted hover:text-foreground"
        />
    @endif

    {{ $slot }}
</span>