Card

# Brok UI: Card (`card`)

A content container with header, content and footer sections; renders as div, a, article, section, li, details, dl or figure, with a frameless ghost variant.

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

## Install

```bash
php artisan ui:add card
```

## Usage

```blade
{{-- card.title is an h3 by default; `as` sets the level that fits the page outline (h2-h6, p or div). --}}
<x-ui.card class="w-full max-w-sm text-start">
    <x-ui.card.header>
        <x-ui.card.title as="h2">{{ __('Billing') }}</x-ui.card.title>
        <x-ui.card.description>{{ __('Manage your subscription and invoices.') }}</x-ui.card.description>
    </x-ui.card.header>
    <x-ui.card.content>
        <p class="text-sm text-muted-foreground">{{ __('Your plan renews on the 1st of each month.') }}</p>
    </x-ui.card.content>
    <x-ui.card.footer>
        <x-ui.button class="w-full">{{ __('Update plan') }}</x-ui.button>
    </x-ui.card.footer>
</x-ui.card>
```

## Props

- `as` (string, default `div`) — Element the card renders as: div, article, section, li, details, dl, or figure; ignored (forced to a) when href is set.
- `href` (mixed|null, default `null`) — Renders the card as a link and adds a hover lift, while keeping the same surface recipe.
- `variant` (string, default `default`) — default is the bordered, filled surface; ghost has no frame, fill, or shadow, so only the layout parts sit on the page background.

## Use when

- Use to group related content into scannable units for browsing, prioritization, or rearrangement.
- Grouping related content (a title, description, body, and actions) into one bordered, elevated surface.
- Building a clickable card that links to a whole record or page via href.

## Avoid when

- Do not use card-like structures when dense row-by-row comparison would be clearer in a list or table.
- The content needs no visual framing, just spacing; use stack or a plain surface instead.
- The composition wants layout parts without a bordered surface at all; use variant="ghost" rather than reaching for a different primitive.

## Anti-patterns

- Turning every object into a card

## Rules

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

@props([
    // Element the card renders as: div (default), a (with href), article,
    // section, figure. A link card keeps the surface recipe and gains the
    // hover lift.
    'as' => 'div',
    'href' => null,
    // default: the bordered surface. ghost: no frame, no fill, no shadow —
    // the card's layout parts on the page background, for a composition
    // that sometimes wants the surface and sometimes does not.
    'variant' => 'default',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $allowedTags = ['div', 'a', 'article', 'section', 'li', 'details', 'dl', 'figure'];
    $tag = $href !== null ? 'a' : (in_array($as, $allowedTags, true) ? $as : 'div');
    $variant = $styles['normalizeVariant']($variant);
    $variant = $variant === 'ghost' ? 'ghost' : 'default';
    $baseClass = $variant === 'ghost' ? $styles['card']['ghost'] : $styles['card']['base'];
    // A max-width passed by the caller replaces the base `max-w-full` rather than
    // competing with it: Tailwind orders `max-w-2xl`, `max-w-7xl` and arbitrary
    // values before `max-w-full`, so the base would otherwise keep the card full width.
    if (preg_match('/(?<!\S)max-w-\S+/', (string) $attributes->get('class', ''))) {
        $baseClass = trim((string) preg_replace('/(?<!\S)max-w-full(?!\S)/', '', $baseClass));
    }
    $classes = $baseClass.($tag === 'a' ? ' '.$styles['card']['link'] : '');
    // A component built on this card (current-plan, approval-workflow, …)
    // 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') ?: 'card');
    // Same rule for data-variant: a composing component's own variant name
    // wins over the card's `ghost` marker.
    $variantName = (string) ($attributes->get('data-variant') ?: ($variant === 'ghost' ? 'ghost' : ''));
@endphp

<{{ $tag }}
    data-slot="{{ $slotName }}"
    @if ($variantName !== '') data-variant="{{ $variantName }}" @endif
    @if ($tag === 'a') href="{{ $href }}" @endif
    {{ $attributes->except(['data-slot', 'data-variant'])->merge(['class' => $classes]) }}
>
    {{ $slot }}
</{{ $tag }}>