# Filament Native Enterprise UI Standard

> Canonical rules for custom Blade, Livewire widget, page, dashboard, and detail surfaces that need layout composition beyond stock Filament CRUD.
> This standard operationalizes UI-FIL-001 and BADGE-001 for TenantPilot product surfaces.
> The detailed canonical source for custom Filament UI is [../../ui/tenantpilot-enterprise-ui-standards.md](../../ui/tenantpilot-enterprise-ui-standards.md); if wording differs, that document wins.

**Last reviewed**: 2026-05-03

---

## Governing Principle

Custom product surfaces MUST preserve Filament-native interaction semantics.
Use custom Blade or Tailwind to compose product-specific layout, decision hierarchy, and progressive disclosure.
Do not create a parallel local design system.

---

## Scope

This standard applies to:

- custom Blade views embedded in Filament surfaces
- Livewire widgets and dashboard/detail surfaces
- productized pages that combine native Filament building blocks with local layout composition

This standard does not apply to:

- marketing or website pages outside the admin/operator panel
- purely cosmetic copy-only edits with no interaction or semantic effect

---

## Native-First Rules

- Use Filament Actions, Buttons, Badges, Sections, Infolists, Tables, Tabs, Widgets, and shared project primitives whenever they can express the required meaning.
- If Filament already supplies the semantic element, do not replace it with locally assembled markup.
- Custom Blade/Tailwind is for layout composition and progressive disclosure only. It is not a license to redefine action, status, or container semantics locally.
- Do not introduce ad-hoc styling for cards, buttons, hovers, badges, icons, progress bars, empty states, or interactive rows.

---

## Actions And Buttons

- Each page, card cluster, or other focused action area gets at most one dominant primary action.
- Secondary actions stay visually neutral unless the action is destructive or the semantic state change is the point of the action.
- Do not use status-colored buttons when the action itself is not semantically success, warning, or danger.
- Do not create per-card custom button styles unless they are promoted into a reusable shared primitive.
- Card actions must keep Filament-consistent sizing, radius, hover, focus, and disabled behavior.

## Affordance And Interactivity

- Hover, pointer, focus, shadow, or similar interactive affordance is allowed only when a repo-real route/action exists and the current actor has the permitted capability.
- When no route/action or capability exists, render a visibly static non-interactive surface instead of a fake clickable row.
- Interactive navigation uses real links or Filament actions, not decorative hover-only containers.

---

## Status And State Semantics

- Show status, health, readiness, risk, completeness, and similar state through BADGE-001 badges, labels, chips, and supporting text.
- Buttons are for actions, not for carrying most status meaning.
- Avoid arbitrary page-local status color systems. Semantic colors must stay aligned with Filament or shared project conventions.
- If a surface needs multiple status dimensions, keep them separate instead of collapsing them into one overloaded visual treatment.

Reference meanings:

- Success: healthy, completed, ready
- Warning: stale, needs review, due soon
- Danger: failed, blocked, critical
- Info: running, in progress
- Neutral: unknown, unavailable, not configured

---

## Cards, Containers, And Layout

- Prefer Filament Section/Card-like surfaces or approved shared primitives.
- Keep borders, shadows, spacing, and emphasis aligned with the surrounding Filament panel.
- Do not introduce oversized custom borders, hard outlines, or dramatic spacing systems that make one surface read like a separate product.
- Use custom composition to support decision hierarchy and progressive disclosure, not to create a new card language per page.

---

## Progressive Disclosure

- First viewport content should answer the operator's next decision, not dump raw technical detail.
- Technical diagnostics are secondary.
- Raw or support-focused evidence stays collapsed, lower-priority, or capability-gated by default when applicable.
- Repeated cards must not restate the same blocker, status, or next action at equal visual weight.

---

## Exception Rule

- A local custom pattern is allowed only when Filament and existing shared primitives cannot express the required product behavior.
- The governing spec or PR must record why the exception is necessary, what remains standardized, and how spread is contained.
- Historical accident or local convenience is not a valid exception reason.

---

## Review Gate

Reviewers must confirm:

- Filament-native interaction semantics remain intact.
- No independent button, status-color, spacing, or card system was introduced.
- One dominant primary action remains obvious.
- Status is conveyed through badges, labels, or supporting text instead of arbitrary action coloring.
- Any exception is explicit, bounded, and reusable-pressure is controlled.