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