Section

# Brok UI: Section (`section`)

A semantic page-section primitive with density-aware vertical rhythm and tokenized surface tones.

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

## Install

```bash
php artisan ui:add section
```

## Usage

```blade
<x-ui.section space="8" surface="muted" class="w-full rounded-lg text-center">
    <h3 class="text-lg font-semibold">{{ __('Section rhythm') }}</h3>
</x-ui.section>
```

## Props

- `space` (none|sm|md|lg|xl, default `md`) — Vertical padding tier. `sm` 32px, `md` 48px, `lg` 48→64px (responsive from `sm:`), `xl` 64→96px (responsive from `sm:`) — the dominant marketing-block rhythm (`py-16 sm:py-24`). Numeric aliases `8`/`12`/`16` map to `sm`/`md`/`lg` for backward compatibility.
- `surface` (default|card|muted|primary|transparent, default `default`) — Background/foreground token pairing for the section.
- `as` (section|div|main|aside|header|footer, default `section`) — Rendered element tag.

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Wrapping a page or landing-page section that needs consistent vertical padding.
- A marketing block needs the py-16 sm:py-24 rhythm (`space="xl"`).

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- The region is a control or card, not a page-level section; use `surface` or `card` instead.
- You need a bounded content width — pair with `<x-ui.container>` inside the section.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

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

@props([
    'space' => 'md',
    'surface' => 'default',
    'as' => 'section',
])

@php
    $allowedTags = ['section', 'div', 'main', 'aside', 'header', 'footer'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'section';
    $spaces = [
        'none' => '',
        'sm' => 'py-section-sm',
        'md' => 'py-section-md',
        'lg' => 'py-section-md sm:py-section-lg',
        'xl' => 'py-section-lg sm:py-section-xl',
        '8' => 'py-section-sm',
        '12' => 'py-section-md',
        '16' => 'py-section-md sm:py-section-lg',
    ];
    $surfaces = [
        'default' => 'bg-background text-foreground',
        'card' => 'bg-card text-card-foreground',
        'muted' => 'bg-muted text-foreground',
        'primary' => 'bg-primary text-primary-foreground',
        'transparent' => 'text-foreground',
    ];
    $spaceKey = array_key_exists((string) $space, $spaces) ? (string) $space : 'md';
    $surfaceKey = array_key_exists($surface, $surfaces) ? $surface : 'default';
    // A block that composes this section may pass 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') ?: 'section');
@endphp

<{{ $tag }}
    data-slot="{{ $slotName }}"
    data-space="{{ $spaceKey }}"
    data-surface-tone="{{ $surfaceKey }}"
    {{ $attributes->except('data-slot')->merge(['class' => trim('min-w-0 max-w-full '.$spaces[$spaceKey].' '.$surfaces[$surfaceKey])]) }}
>{{ $slot }}</{{ $tag }}>