TenantAtlas/docs/product/standards/filament-native-enterprise-ui.md

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.