Surface

# Brok UI: Surface (`surface`)

A constrained panel primitive combining semantic tone, density-aware padding, radius, and elevation tiers.

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

## Install

```bash
php artisan ui:add surface
```

## Usage

```blade
<x-ui.surface padding="md" class="w-full max-w-md">
    <h3 class="font-semibold">{{ __('A consistent surface') }}</h3>
    <p class="mt-2 text-sm text-muted-foreground">{{ __('Tone, padding, radius, and shadow use shared tiers.') }}</p>
</x-ui.surface>
```

## Props

- `tone` (string, default `card`) — Semantic background/border/foreground combination: surface, elevated, inverse, card, background, muted, popover, or transparent.
- `padding` (string, default `md`) — Inner padding tier: none, sm, md, or lg.
- `radius` (string, default `lg`) — Corner radius tier: none, sm, md, lg, or xl.
- `shadow` (string, default `sm`) — Elevation tier: none, xs, sm, md, or lg.
- `as` (string, default `div`) — HTML tag to render: div, section, main, aside, or article.

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Building a custom panel that needs a specific token-backed tone, padding, radius, and shadow combination not covered by card.
- Composing a bespoke container inside a block or page while staying on the semantic token system.

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- A standard bordered content card with header/footer parts is enough; use card directly.
- The container is purely structural with no visual tone, padding, or elevation; use stack or grid instead.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

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

@props([
    'tone' => 'card',
    'padding' => 'md',
    'radius' => 'lg',
    'shadow' => 'sm',
    'as' => 'div',
])

@php
    $allowedTags = ['div', 'section', 'main', 'aside', 'article'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'div';
    $tones = [
        'surface' => 'border border-default bg-surface text-foreground',
        'elevated' => 'border border-subtle bg-surface-elevated text-foreground',
        'inverse' => 'bg-inverse text-inverse-foreground',
        'card' => 'border border-border bg-card text-card-foreground',
        'background' => 'border border-border bg-background text-foreground',
        'muted' => 'bg-muted text-foreground',
        'popover' => 'border border-border bg-popover text-popover-foreground',
        'transparent' => 'text-foreground',
    ];
    $paddings = [
        'none' => '', 'sm' => 'p-surface-sm',
        'md' => 'p-surface-md', 'lg' => 'p-surface-lg',
    ];
    $radii = [
        'none' => 'rounded-none', 'sm' => 'rounded-sm',
        'md' => 'rounded-md', 'lg' => 'rounded-lg', 'xl' => 'rounded-lg',
    ];
    $shadows = [
        'none' => 'shadow-none', 'xs' => 'shadow-xs', 'sm' => 'shadow-sm',
        'md' => 'shadow-md', 'lg' => 'shadow-lg',
    ];
    $toneKey = array_key_exists($tone, $tones) ? $tone : 'card';
    $paddingKey = array_key_exists($padding, $paddings) ? $padding : 'md';
    $radiusKey = array_key_exists($radius, $radii) ? $radius : 'lg';
    $shadowKey = array_key_exists($shadow, $shadows) ? $shadow : 'sm';
@endphp

<{{ $tag }}
    data-slot="surface"
    data-tone="{{ $toneKey }}"
    data-padding="{{ $paddingKey }}"
    {{ $attributes->merge(['class' => implode(' ', ['min-w-0 max-w-full', $tones[$toneKey], $paddings[$paddingKey], $radii[$radiusKey], $shadows[$shadowKey]])]) }}
>{{ $slot }}</{{ $tag }}>