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; 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.

5.0 KiB Raw Blame History