tenantsmith-design

name	tenantsmith-design
description	Use when building or modifying UI components, layouts, or pages for TenantSmith. Covers the brand color palette, dark/light theme conventions, component patterns, typography, spacing rules, and the login page design system. Do not use for backend logic, database migrations, or API endpoints.
metadata	{"author":"team"}

TenantSmith Design System

⚠️ READ FIRST: Before touching any Blade file, read Page Patterns. It contains the exact structure every page must follow. Tokens alone won't tell you how to build a page.

TenantSmith uses a dual-theme (light/dark) design system built on Tailwind CSS v3 with darkMode: 'class'. All components must support both themes.

Quick Reference

Brand Colors

The brand color scale (aliased indigo) is the primary accent:

Token	Hex	Usage
brand-50	#eef2ff	Subtle backgrounds, tints
brand-100	#e0e7ff	Light accent bg
brand-200	#c7d2fe	Borders, dividers
brand-400	#818cf8	Active indicators
brand-500	#6366f1	Primary accent — focus rings, active states
brand-600	#4f46e5	Primary buttons, links
brand-700	#4338ca	Hover on primary actions
brand-800	#3730a3	Active/pressed primary

Dark Theme Colors (Dark Mode)

The dark theme uses custom hex values, NOT standard Tailwind grays:

Surface	Hex	Tailwind Class	Usage
Page bg	#08080c	dark:bg-[#08080c]	Body, page background
Surface	#101016	dark:bg-[#101016]	Cards, sidebar, header, inputs
Elevated	#181820	dark:bg-[#181820]	Hover states, dropdowns, active items
Border	#262632	dark:border-[#262632]	All borders, input borders

IMPORTANT: Do NOT use dark:bg-gray-800, dark:bg-gray-900, etc. Always use the custom hex values above.

Dark Mode Rule

Every light-mode class MUST have a dark: counterpart. The pattern:

{{-- Backgrounds — use custom hex, not Tailwind grays --}}
bg-white dark:bg-[#101016]           {{-- cards, sidebar, header --}}
bg-gray-100 dark:bg-[#08080c]        {{-- page background --}}
bg-gray-50 dark:bg-[#181820]         {{-- hover, elevated --}}

{{-- Text — Tailwind grays are fine for text --}}
text-gray-900 dark:text-gray-100    {{-- primary text --}}
text-gray-700 dark:text-gray-300    {{-- secondary text --}}
text-gray-500 dark:text-gray-400    {{-- muted text --}}
text-gray-400 dark:text-gray-500    {{-- icons, bullets --}}

{{-- Borders — use custom hex --}}
border-gray-200 dark:border-[#262632]

{{-- Interactive --}}
hover:bg-gray-100 dark:hover:bg-[#181820]
hover:text-gray-900 dark:hover:text-gray-100
focus:ring-brand-500 focus:ring-offset-2 dark:focus:ring-offset-[#08080c]

Buttons

Three button components. Always use the Blade component, never inline button classes:

Component	File	When to use
<x-primary-button>	components/primary-button.blade.php	CTA, submit, create, approve
<x-secondary-button>	components/secondary-button.blade.php	Cancel, back, secondary actions
<x-danger-button>	components/danger-button.blade.php	Delete, reject, remove

Button text: ALL UPPERCASE + tracking-widest. Keep text short: "NEW TENANT", "CREATE MODULE", "APPROVE", "REJECT", "CANCEL".

CTA links (non-button): For link-based CTAs (e.g. header "New Tenant"), use an <a> tag with the exact same classes as <x-primary-button> plus ease-in-out:

<a href="{{ route('...') }}"
   class="inline-flex items-center justify-center gap-2 px-4 py-2 bg-gradient-to-b from-brand-500 to-brand-600 border border-brand-400/20 rounded-lg font-semibold text-xs text-white uppercase tracking-widest shadow-card hover:shadow-glow-brand-strong hover:from-brand-500 hover:to-brand-700 active:from-brand-600 active:to-brand-800 transition-all duration-200 ease-in-out">
    <x-heroicon-o-plus class="w-4 h-4" />
    New Tenant
</a>

Focus ring: focus:ring-2 focus:ring-brand-500 focus:ring-offset-2 dark:focus:ring-offset-[#08080c]

Input Fields (Floating Label)

The auth-input component uses a floating-label pattern with Alpine.js. Inputs use a refined border with subtle depth.

{{-- Structure --}}
<div x-data="{ focused: false, value: '{{ old($name) }}', showPassword: false }" class="relative">
    <label ... :class="{ 'top-2 !translate-y-0 text-xs font-medium': focused || value }">
    <input ... class="block w-full pt-5 pb-2 px-3 text-sm rounded-lg
        border border-gray-200 dark:border-[#262632]
        bg-white dark:bg-[#101016]
        text-gray-900 dark:text-gray-100
        shadow-card focus:shadow-glow-brand
        focus:border-brand-500 focus:ring-2 focus:ring-brand-500/30 dark:focus:ring-brand-400/20" />
</div>

Input tokens:

• Border: border border-gray-200 dark:border-[#262632]
• Border radius: rounded-lg
• Padding: pt-5 pb-2 px-3 (floating label needs top padding)
• Font size: text-sm
• Shadow: shadow-card default, shadow-glow-brand on focus
• Background: bg-white dark:bg-[#101016]
• Focus: focus:border-brand-500 focus:ring-2 focus:ring-brand-500/30 dark:focus:ring-brand-400/20
• Error state: border-red-400 dark:border-red-500 + animate-shake on error message

Alerts / Flash Messages

Always use <x-alert> for feedback messages. Never write inline alert divs.

{{-- Simple message --}}
<x-alert variant="success">{{ session('success') }}</x-alert>
<x-alert variant="error">{{ session('error') }}</x-alert>

{{-- With title + dismiss --}}
<x-alert variant="warning" title="Domain expiring" dismissible>Your domain expires in 7 days.</x-alert>

{{-- Info --}}
<x-alert variant="info">A new update is available.</x-alert>

Component: components/alert.blade.php. Props: variant (success/error/warning/info), title (optional), dismissible (bool).

Typography

• Font: Figtree (400, 500, 600 weights)
• Page headings: text-2xl font-bold
• Subtitles: text-sm text-gray-500 dark:text-gray-400
• Sidebar section labels: text-[10px] font-semibold uppercase tracking-[0.08em] text-gray-400 dark:text-gray-500
• Nav items: text-sm
• Form labels (floating): text-sm, shrinks to text-xs font-medium when focused

Sidebar

Structure: Labeled sections → nav items. Each section has an uppercase label and one or more items.

Section label: text-[10px] font-semibold uppercase tracking-[0.08em] text-gray-400 dark:text-gray-500 — hidden when collapsed via x-show="!$store.sidebar.collapsed" x-cloak.

Icons: Heroicons via blade-heroicons package. Outline style (<x-heroicon-o-*>).

Nav item (single link):

<a href="..." class="flex items-center gap-2.5 rounded-lg px-3 py-1.5 text-sm transition-colors
    hover:bg-gray-100 dark:hover:bg-[#181820]
    {{ $active ? 'bg-gray-100 dark:bg-[#181820] text-gray-900 dark:text-gray-100 font-medium' : 'text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100' }}"
    :title="$store.sidebar.collapsed ? 'Label' : ''">
    <x-heroicon-o-xxx class="w-5 h-5 shrink-0 {{ $active ? 'text-brand-500 dark:text-brand-400' : 'text-gray-400 dark:text-gray-500' }}" />
    <span x-show="!$store.sidebar.collapsed" x-cloak class="whitespace-nowrap">Label</span>
</a>

Active state rule: Active items get background + brand icon. All nav icons must turn text-brand-500 dark:text-brand-400 when their section is active — no exceptions.

Accordion (parent with sub-items): Same active state as single links. Two sub-displays:

• Expanded: x-show="open && !$store.sidebar.collapsed" — sub-links indented with ps-4, active sub-link uses bg-brand-50 dark:bg-brand-500/10 text-brand-700 dark:text-brand-300 font-medium.
• Collapsed flyout: x-show="$store.sidebar.collapsed && open" — absolute-positioned dropdown with shadow-lg, z-50.

Sections (central): Overview (Dashboard) · Central (Tenants accordion) · Platform (Modules accordion) Sections (tenant): Overview (Dashboard) · Platform (Modules) · Access (Users, Roles) · Network (Domains accordion)

Bottom bar: Profile link + Logout button, separated by border-t. Both use flex items-center gap-2 in dropdown menus.

Dashboard

Page structure: Page header (title + subtitle) → stat cards grid → activity feed card (full width).

Stat cards: grid-cols-1 sm:grid-cols-2 lg:grid-cols-4. Each uses <x-stat-card> with icon, value, label, description. Central and tenant get different stat sets via DashboardController.

Activity feed: <x-card> with header. Lists recent module requests with status dots (bg-green-500 / bg-red-500 / bg-amber-500) and <x-badge> status labels.

Layout

• Sidebar width: w-56 (expanded) / w-16 (collapsed), persisted in localStorage
• Header height: h-16 (sticky, z-30, backdrop-blur)
• Content padding: px-4 py-4 sm:px-6 lg:px-8
• Theme toggle: placed in header, left of user dropdown

Login Page (Split Screen)

Layout structure:

• Left panel (55% on lg, 50% on xl): brand gradient with illustration
• Right panel: form area, bg-white dark:bg-[#08080c]
• Mobile: left panel hidden, compact brand header above form

Left panel gradient: bg-gradient-to-br from-brand-600 via-brand-700 to-brand-950

Tenant-aware content:

@php $isTenant = (bool) tenant(); @endphp

@if ($isTenant)
    {{-- Tenant: "Your workspace is ready" --}}
    {{-- Features: Team management, Available modules, Custom domains --}}
@else
    {{-- Central: "Manage your tenants with confidence" --}}
    {{-- Features: Multi-tenant ready, Custom domains, Module management --}}
@endif

Illustration: Inline SVG with floating cards, connected nodes, and stacked layers. Uses animate-float for subtle bobbing.

Animations

Defined in resources/css/app.css:

Class	Animation	Duration	Usage
animate-fade-up	Fade in + slide up 16px	0.4s	Page entrance
animate-fade-up-delay-1	Same, 0.1s delay	0.4s + 0.1s	Staggered entrance
animate-fade-up-delay-2	Same, 0.2s delay	0.4s + 0.2s	Staggered entrance
animate-fade-up-delay-3	Same, 0.3s delay	0.4s + 0.3s	Staggered entrance
animate-shake	Horizontal shake 4px	0.4s	Error validation
animate-float	Vertical bob 8px	6s infinite	Illustration elements
animate-float-delayed	Same, 2s delay	6s infinite	Secondary illustration

Usage pattern: Wrap content in a div with the animation class. Use [x-cloak] to prevent flash of unstyled content.

Logo

• SVG: stacked-layers (3 overlapping rounded rectangles in brand-300/400/500)
• File: resources/views/components/application-logo.blade.php
• Favicon: public/favicon.svg
• Brand name: TenantSmith (hardcoded in layouts)

Before Adding a New Component

1. Check if an existing component covers the use case
2. Use button components — <x-primary-button>, <x-secondary-button>, <x-danger-button>. Never write inline button classes.
3. Use <x-alert> for flash/status messages — never inline alert divs.
4. Add dark: variants for every color utility using the custom hex values (#08080c, #101016, #181820, #262632)
5. Use brand-* for accent/focus, gray-* for text, custom hex for dark surfaces
6. Use rounded-lg for buttons and inputs (not rounded-md)
7. Use shadow-card (not shadow-sm) for cards and inputs. Use shadow-glow-brand on focus. Primary buttons use shadow-card hover:shadow-glow-brand-strong.
8. Test in both themes before finalizing

Common Pitfalls

• Using dark:bg-gray-800 instead of dark:bg-[#101016] — the dark theme uses custom hex values, not standard Tailwind grays.
• Missing dark: variant — the most common mistake. Every bg-white needs dark:bg-[#101016].
• Using raw indigo-* instead of brand-* — the palette is aliased so it can be swapped later.
• Forgetting dark:focus:ring-offset-[#08080c] on buttons — the focus ring offset must match the dark page background.
• Using shadow-sm on inputs/buttons — use shadow-card for default, shadow-glow-brand on focus/hover. The design uses CSS-variable-driven shadows, not Tailwind's built-in shadow-sm.
• Using rounded-md on buttons/inputs — use rounded-lg for the TenantSmith design.
• Hardcoded hex colors in SVGs — use brand tokens where possible; the logo uses brand-300/400/500.
• Isolated Alpine scope on buttons — put x-data on the <form>, not on the <button>, to avoid submit issues.
• :class on Blade components (<x-*>) is parsed as PHP, not Alpine.js — Blade's component tag compiler treats :class as a PHP prop binding. On <x-heroicon-o-chevron-down :class="open ? 'rotate-180' : ''" />, open is evaluated as a PHP constant and throws "Undefined constant". Fix: use x-bind:class instead of :class on any <x-*> component. On plain HTML elements (<div>, <span>, <a>), :class works fine for Alpine.js.

References

• Page Patterns — READ THIS FIRST. Exact page structure skeletons for list and form pages. Copy these patterns for every new page.
• Design Tokens — full token table, component inventory, and dark mode checklist