SaaS UI Guideline for Laravel-Based CRUD Applications

This comprehensive guideline standardizes the visual and interaction design for our SaaS applications built in Laravel. These are primarily polished, complex CRUD interfaces aimed at enterprise users. The goal is to ensure consistency, efficiency, and user-friendliness across all modules. Designers should create high-fidelity mockups in Figma (using our shared component library), while developers implement using Tailwind CSS, Alpine.js for interactivity, and Livewire for dynamic components. All icons must come from Heroicons (outline for default, solid for active/hover states). Colors: Primary #2563EB (blue-600), Success #10B981 (emerald-500), Danger #EF4444 (red-500), Warning #F59E0B (amber-500). Typography: Inter font family, with headings in semibold and body in regular.

Below is the expanded list of rules, including the provided ones with detailed paragraphs, plus additional standard and highly user-friendly actions/practices. I've grouped them logically into sections for better organization.

Global Navigation & Layout

Universal Search Box Accessible via CMD+/ (or Ctrl+/ on Windows)
A prominent search input should be fixed in the top navigation bar (center or right-aligned next to the global menu trigger). It supports fuzzy searching across all entities, users, settings, and recent activities. Triggering CMD+/ focuses the input automatically. Results appear in a dropdown with categorized sections (e.g., Customers, Invoices, Settings) and keyboard navigation (arrow keys, Enter to select). This enhances discoverability in large apps, reducing clicks to find data.
Visual Suggestion: Use a magnifying glass icon on the left of a rounded input (bg-white, border-gray-300, focus:ring-2 ring-primary). Dropdown: max-height 80vh, shadow-lg, with dividers between categories. Mock in Figma with auto-layout for dynamic results.
Main Menu on Left Sidebar (Collapsible)
The primary navigation is a vertical sidebar on the left, defaulting to expanded (250px wide) on desktop and collapsed (icon-only, 60px) on mobile or via a toggle button. Collapse/expand persists per user session via localStorage. Icons are 20x20px, labels in 14px text. Active item: bg-primary/10, text-primary, with a left border indicator.
Visual Suggestion: Sidebar bg-gray-50, border-right gray-200. Toggle icon (chevron-left/right) in top-right of sidebar. Use Figma variants for expanded/collapsed states; animate slide in Alpine.js.
Avoid Second-Level Submenus Unless Necessary
Keep navigation flat to minimize cognitive load. If a module exceeds 8 items, group logically under collapsible sections (accordion-style) instead of submenus. Only use submenus for deeply hierarchical data (e.g., Reports > Financial > Taxes) with a clear back button.
Visual Suggestion: Accordion chevron icons rotate on click. Submenu: indented 16px, lighter text color. Prototype interactions in Figma to test one-click access.
Global Menu for Quick Module Access (Mega Menu Style)
A hamburger or grid icon in the top bar opens a mega menu dropdown/popup with all modules in a grid (3-4 columns), recent items, and pinned favorites. Supports keyboard shortcuts (e.g., CMD+1 for first module). This acts as a command palette alternative for power users.
Visual Suggestion: Mega menu: full-width dropdown below top bar, divided into columns with module icons (24x24px) and labels. Pinned section at top. Use Figma auto-layout grids; add hover effects (scale 1.05).
Top-Right User Avatar
Display a circular avatar (32x32px) with the user's profile image. If none, show initials (first + last name) in a colored circle (bg-primary, text-white, uppercase 12px bold). Dropdown on click: Profile, Settings, Logout, with dividers.
Visual Suggestion: Badge for notifications (red dot with count). Dropdown: shadow-md, min-width 200px. Figma component with variants for image/initials/notifications.
Breadcrumbs on All Pages
Every page (except dashboard) shows hierarchical breadcrumbs starting from Home > Module > Submodule > Current. Clickable links except the last. Truncate long paths with ellipsis.
Visual Suggestion: Text-gray-600, 13px, chevron separators (>). Home icon as house. Align left below top bar. Figma: use text auto-layout with slashes or icons.

Data Grids & Tables

All View Actions Open in Off-Canvas Sidebar (Closable via Escape Key)
Clicking "View" on any row slides in a right-side off-canvas panel (400-600px wide) with details, without leaving the grid. Close via X button, overlay click, or Esc key. Edit can upgrade in-place within the same panel.
Visual Suggestion: Panel: bg-white, shadow-xl, slide from right (transition 300ms). Overlay: bg-black/50. Include a "Edit" button to switch modes. Figma prototype with push transition.
Links on the Grid Should Be Underlined
Any clickable text in table cells (e.g., names, emails) must be underlined on hover (default: no underline, hover: underline + text-primary). This distinguishes links from plain text clearly.
Visual Suggestion: Base text-gray-900, hover text-primary with transition. Use Tailwind's hover:underline.
Sorted Column Highlighted by Colors
Clicking a column header toggles sort (asc/desc/none). Highlight header: bg-primary/5, text-primary. Add sort icons (up/down arrows) that fade in.
Visual Suggestion: Arrows: text-gray-400, active text-primary. Multiple sorts: numbered badges. Figma: variants for sort states.
Column Selection with User Preferences Saved in DB
Each grid has a "Columns" dropdown (gear icon) to toggle visibility, reorder via drag-drop. Save JSON of {visible: [], order: []} per user/grid in database. Default: all essential columns visible.
Visual Suggestion: Modal or dropdown with checkboxes and draggable list (use Sortable.js). Persist on refresh. Figma: interactive prototype for drag.
Search Box per Grid (Searches Entire Table)
A dedicated input above the grid filters rows client-side (debounced 300ms) or server-side for large datasets. Supports multi-column if specified. Clear button inside input.
Visual Suggestion: Position top-left, icon left, placeholder "Search [entity]...". Highlight matching text in rows. Tailwind debounce with Livewire.
Pagination on Bottom Right; Search Top Left; Rows per Page & Downloads Top Right
Pagination: "<< Prev 1 2 ... 10 Next >>" with current page highlighted (bg-primary text-white). Rows per page: dropdown [10, 25, 50, 100, All]. Downloads: CSV/Excel/PDF icons if enabled, with toast on completion.
Visual Suggestion: Compact layout: search full-width on mobile. Downloads: tooltip on hover. Figma: responsive variants.
Freeze First/Last Columns if >10 Columns; Horizontal Scroll for Rest
For wide tables, pin ID/first column and Actions/last column. Middle scrolls horizontally with fade edges. Indicate scroll with shadow.
Visual Suggestion: Use CSS sticky positioning. Shadow on scroll: gradient. Test in browser for performance.

Actions & Buttons

Action Button Accommodates Max 3 Icon Buttons; Excess in Dropdown
Primary actions (e.g., Add, Import, Export) in a button group. Limit to 3 icons (24x24px); fourth+ go into "More" kebab dropdown. Prioritize: most used leftmost.
Visual Suggestion: Buttons: bg-primary text-white, hover bg-primary/90. Icons only, tooltips. Dropdown: same style. Figma: component library for button groups.
View/Edit Pages Have "Back to [Entity]" Button
Top-left fixed button (or in header) returns to the grid with preserved filters/pagination. Label: "Back to Customers".
Visual Suggestion: Outline button with left arrow icon. Sticky on scroll.

Feedback & Operations

All Write Operations Show Toast Messages (Non-Blocking)
Success: green toast top-right, auto-dismiss 5s. Error: red with details. Warning: yellow. Use HotToast or custom with Alpine. No modals/alerts that block UI.
Visual Suggestion: Slide in from top-right, progress bar for timer. Stack multiple. Figma: animation prototypes.

User Settings & Preferences

Per-User Settings
A dedicated Settings module (gear icon in user dropdown) with tabs: General, Notifications, Appearance, API Keys. All preferences (e.g., theme, density) saved in users table JSON column.
Visual Suggestion: Form sections with dividers. Dark mode toggle. Figma: multi-page for tabs.
Left Menu Order Customization
Users drag-reorder sidebar items (except pinned/system ones). Save order in DB. Reset to default button.
Visual Suggestion: Edit mode: drag handles appear. Livewire for real-time save.
Days to Remember Cookies (Super Admin Only)
Super admins set global cookie expiration (e.g., 1-365 days) in Admin > Security. Affects "Remember Me" login.
Visual Suggestion: Slider input with label. Restricted via role check.
Settings Download
Export all user/grid preferences as JSON/CSV via button in Settings. Include audit log if applicable.
Visual Suggestion: Button with download icon, toast on success.

Additional Standard & User-Friendly Practices

Keyboard Shortcuts Cheat Sheet
Accessible via ? key or help icon: lists all shortcuts (e.g., CMD+N for New, CMD+S for Save). Modal with searchable table. Improves efficiency for power users.
Visual Suggestion: Modal centered, grid layout. Use Mousetrap.js for implementation.
Density Options (Compact/Comfortable)
Per-user toggle for row height/padding in grids (compact: 40px rows, comfortable: 56px). Saves in DB, applies globally.
Visual Suggestion: Toggle in top bar or settings. Tailwind classes switch.
Inline Editing in Grids
For simple fields, double-click cell to edit (pencil icon on hover). Save on Enter/Blur, undo on Esc. Toast feedback. Reduces page navigations.
Visual Suggestion: Input appears in-cell, highlight row on focus.
Bulk Actions with Checkbox Selection
Select all checkbox in header. Selected rows: highlight bg-primary/5. Actions dropdown: Delete, Export, Tag, etc. Confirm modal for destructive.
Visual Suggestion: Counter: "X selected". Sticky header for long tables.
Dark Mode Support
System/user preference toggle. Use Tailwind dark: classes. Auto-detect OS preference on first load.
Visual Suggestion: Moon/sun icon in top bar. Smooth transition.
Responsive Design & Mobile Optimization
Grids stack vertically on <768px, off-canvas becomes bottom sheet. Sidebar auto-collapses. Touch-friendly (48px taps).
Visual Suggestion: Figma responsive artboards (desktop/tablet/mobile).
Loading States & Skeletons
All async actions show skeleton loaders (gray pulsing blocks) instead of spinners. Full-page overlay for initial loads.
Visual Suggestion: Tailwind animate-pulse. Match exact layout.
Accessibility Compliance (WCAG 2.1 AA)
All interactive elements: focus outlines, ARIA labels, color contrast >4.5:1. Screen reader tested. Alt text for icons/images.
Visual Suggestion: Use axe DevTools in browser; Figma contrast plugin.
Error Handling & Empty States
404/500 pages with friendly illustrations, "Back Home" button. Empty grids: illustration + "Create First [Entity]" button.
Visual Suggestion: SVG illustrations from unDraw. Centered layout.
Audit Logs for Sensitive Actions
Viewable in a dedicated grid (Super Admin): who, what, when, IP. Filterable.
Visual Suggestion: Separate module, exportable.

Authentication Pages – Core Principles

Single Layout for All Auth Pages
Use a shared Blade layout: resources/views/auth/layout.blade.php. Contains only: centered card, logo at top, minimal footer. No sidebar, no top bar, no breadcrumbs.
Why: Reduces duplication, ensures visual consistency, speeds up development.
Centered Card Layout (Responsive)
Max width: 420px (sm: full-width, md: max-w-md). Vertical padding: 8rem top/bottom on desktop, 4rem on mobile. Background: bg-gray-50. Card: bg-white shadow-sm rounded-xl p-8.
Why: Familiar SaaS pattern (like Stripe, Notion), focuses user on task.
Logo & Branding
Company logo centered at top of card (80px height, mx-auto). Below: tagline in text-sm text-gray-600 (e.g., “Secure access to your workspace”).
Why: Reinforces brand, builds trust.
Mobile-First & Touch-Friendly
Inputs: min-height 48px, font-size 16px. Buttons: full-width, h-12. No hover states on mobile.
Why: 60%+ logins happen on mobile; prevents zoom/fat-finger errors.
Dark Mode Auto-Detect
On first visit: use prefers-color-scheme. Add toggle in footer (moon/sun icon). Save preference in localStorage and sync to user settings on login.
Why: Respects OS setting, improves accessibility.
Accessibility (WCAG 2.1 AA)
- All inputs: visible focus rings (focus:ring-2 focus:ring-primary focus:border-primary)
- Labels: associated via for="" + id=""
- ARIA: aria-live for error messages, aria-describedby for hints
- Color contrast: ≥4.5:1
  Why: Legal compliance, inclusive design.

1. Login Page

Purpose: Secure entry with email/password, SSO, magic link, 2FA.

Form Structure
- Email → Password → Remember me (left) + Forgot password? (right) → Submit
- Submit: full-width primary button, disabled until valid
- Loading state: spinner inside button, text “Signing in…”
Remember Me
Checkbox with label. Default: unchecked. If checked, set cookie for 30 days (configurable by Super Admin).
Why: Balances convenience and security.
Forgot Password Link
Opens Password Reset Request in same card (slide transition).
Why: Keeps flow in context.
SSO Options (Divider + Buttons)
After submit: horizontal divider with “OR” in center. Below: “Continue with Google”, “Microsoft”, etc.
- Icons: 16x16px, brand colors
- Buttons: outline style, border-gray-300 hover:bg-gray-50
  Why: Enterprise users expect SSO.
Error Handling
- Inline errors below inputs (red text, icon)
- Global error banner at top of card if login fails (e.g., “Invalid credentials”)
- Auto-clear on input change
  Why: Non-blocking, clear feedback.
Footer Links
Bottom of card: “Don’t have an account? Sign up” | “Need help?”
Why: Guides lost users.

2. Register / Sign-Up Page

Purpose: Onboarding new users (admin invite or self-signup).

Form Fields
- Full Name → Email → Password → Confirm Password → (Optional: Company) → Submit
- Password strength meter (weak/medium/strong) with rules tooltip
- Submit: “Create account”
Invite-Only Mode
If ALLOW_PUBLIC_REGISTRATION = false: show “Enter invite code” field first.
Why: Prevents spam, common in B2B SaaS.
Terms & Privacy
Checkbox: “I agree to the Terms and Privacy Policy”
Why: Legal requirement.
Success State
After submit: replace form with checkmark + “Check your email” message. Auto-redirect to login after 5s.
Why: Clear closure.

3. Password Reset Flow

Two Steps: Request → Reset

Request Page
- Single email field
- Submit: “Send reset link”
- Success: “If an account exists, you’ll receive an email.” (prevents enumeration)
  Why: Security best practice.
Reset Page
- Token validated server-side
- Fields: New Password → Confirm
- Submit: “Update password”
- Success: redirect to login with toast “Password updated”

4. Two-Factor Authentication (2FA)

Triggered after password if enabled

2FA Challenge Page
- Method: App (TOTP) or SMS
- Input: 6-digit code (auto-focus, paste support)
- “Resend code” link (disabled 30s)
- Backup codes: “Use backup code” link → modal with 10 codes (one-time use)
Recovery Flow
If user loses access: “Trouble signing in?” → email recovery link (rate-limited).

5. Magic Link (Passwordless)

Optional flow

Magic Link Request
- Email field → “Send magic link”
- Success: “Check your email” (link expires in 15 mins)
Magic Link Landing
- Auto-login on click
- Fallback: show code input if link expired

6. Session Management

Active Sessions Page (in User Settings)
- Grid: Device, Location, Last Active, IP
- “Log out” button per session
- “Log out all other sessions”
  Why: Security hygiene.
Auto-Logout
- Inactivity: 30 mins (configurable)
- Toast warning at 28 mins: “Session expiring soon”
- Extend: “Keep me signed in”

7. Security Best Practices (Dev Notes)

Rule	Implementation
Rate Limiting	5 attempts per email/IP per 15 mins
HTTPS Only	`Secure` flag on cookies
CSRF	Laravel built-in
Password Hashing	`bcrypt` or `argon2id`
Email Verification	Required on signup (unless SSO)
Audit Log	Log login, logout, failed attempts, 2FA events

Visual & UX Standards

Inputs: rounded-lg border-gray-300 focus:border-primary focus:ring-primary h-12 text-base
Buttons: Primary: bg-primary hover:bg-primary/90 text-white font-medium
Links: text-primary hover:underline
Errors: text-red-600 text-sm mt-1 flex items-center gap-1
Success: text-emerald-600
Typography: text-gray-900 for labels, text-gray-600 for hints
Spacing: space-y-6 between field groups

Implementation Checklist

// resources/views/auth/login.blade.php
@extends('auth.layout')

@section('title', 'Sign in')

@section('content')
  <form method="POST" action="{{ route('login') }}">
    @csrf
    <x-input label="Email" type="email" name="email" />
    <x-input label="Password" type="password" name="password" />
    <x-checkbox label="Remember me" name="remember" />
    <x-button type="submit">Sign in</x-button>
  </form>
@endsection

Enforce in Code Reviews:

No inline styles
All text translatable (__('Login'))
Form validation with Laravel + client-side hints
Tested on mobile (iOS/Android)

Figma Setup:
Create Auth Kit page in component library:
Login/, Register/, Reset/, 2FA/, Magic Link/ — all with states (default, focus, error, loading, success).

Implementation Notes

Figma Setup: Create a master file with pages for Components, Guidelines, Examples. Use styles for colors/typography, components for buttons/tables. Enable branching for module-specific designs.
Code Structure: Blade components for reusable parts (e.g., ). Enforce via PHP CS Fixer and Tailwind config.
Testing: Visual regression with Percy; usability tests with 5 users per new module.
Versioning: Update this doc in Confluence/Notion; tag releases (e.g., UI Guideline v1.2).

Follow this religiously for pixel-perfect, intuitive SaaS experiences. Questions? Ping design lead.

pappu687/saas-ui-design-guidelines.md

Select an option

No results found