ahmido
3aeb0d04b8
Automated PR created by Copilot per user request. Branch pushed: 266-tenant-dashboard-productization-v1 Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #322
110 lines
5.0 KiB
Markdown
110 lines
5.0 KiB
Markdown
# 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. |