From 4fff12648fb3e19938407ea30269461aa514d2c1 Mon Sep 17 00:00:00 2001
From: idevakk <219866223+idevakk@users.noreply.github.com>
Date: Fri, 6 Mar 2026 10:59:51 +0530
Subject: [PATCH] docs: implement comprehensive design system and auto-update
 protocol

---
 .ai/guidelines/design-system.md |  25 +
 .junie/guidelines.md            |  34 ++
 CLAUDE.md                       |  34 ++
 DESIGN.md                       | 902 ++++++++++++++++++++++++++++++++
 GEMINI.md                       |  34 ++
 5 files changed, 1029 insertions(+)
 create mode 100644 .ai/guidelines/design-system.md
 create mode 100644 DESIGN.md

diff --git a/.ai/guidelines/design-system.md b/.ai/guidelines/design-system.md
new file mode 100644
index 0000000..1dc959f
--- /dev/null
+++ b/.ai/guidelines/design-system.md
@@ -0,0 +1,25 @@
+# Design System (CRITICAL — Auto-Read Required)
+
+This project has a comprehensive Design System documented in `DESIGN.md` at the project root.
+
+## Before Any UI/UX Work
+
+**BEFORE** making ANY frontend, UI, UX, styling, component, animation, Blade template, or Tailwind-related change, you MUST read `DESIGN.md` using your file reading tool to understand the established:
+- Design tokens and color system
+- Typography scale and font conventions
+- Component patterns (toasts, modals, buttons, indicators)
+- Spacing constants and layout architecture
+- Animation and transition conventions
+- Responsive breakpoint rules
+
+This applies to: Blade views, CSS files, Alpine.js interactions, GSAP animations, Livewire component UI, toast notifications, modals, buttons, indicators, and any other visual element.
+
+## After Completing UI/UX Work
+
+**AFTER** completing any UI/UX change, you MUST update `DESIGN.md` per its Section 15 (Maintenance Protocol):
+- Add a new entry to Section 14 (Iteration History) using the provided template.
+- Update Section 9 (Component Library) if a component was created or modified.
+- Update Sections 5/6/7 if design tokens, fonts, or colors were added/changed.
+- Bump the version number and "Last updated" date at the top of the file.
+
+Failure to read and follow `DESIGN.md` will result in inconsistent UI, visual regressions, and wasted iteration cycles.
diff --git a/.junie/guidelines.md b/.junie/guidelines.md
index ea68f0f..e8aef0e 100644
--- a/.junie/guidelines.md
+++ b/.junie/guidelines.md
@@ -1,4 +1,37 @@
 <laravel-boost-guidelines>
+=== .ai/design-system rules ===
+
+# Design System (CRITICAL — Auto-Read Required)
+
+
+This project has a comprehensive Design System documented in `DESIGN.md` at the project root.
+
+
+## Before Any UI/UX Work
+
+
+**BEFORE** making ANY frontend, UI, UX, styling, component, animation, Blade template, or Tailwind-related change, you MUST read `DESIGN.md` using your file reading tool to understand the established:
+- Design tokens and color system
+- Typography scale and font conventions
+- Component patterns (toasts, modals, buttons, indicators)
+- Spacing constants and layout architecture
+- Animation and transition conventions
+- Responsive breakpoint rules
+
+This applies to: Blade views, CSS files, Alpine.js interactions, GSAP animations, Livewire component UI, toast notifications, modals, buttons, indicators, and any other visual element.
+
+
+## After Completing UI/UX Work
+
+
+**AFTER** completing any UI/UX change, you MUST update `DESIGN.md` per its Section 15 (Maintenance Protocol):
+- Add a new entry to Section 14 (Iteration History) using the provided template.
+- Update Section 9 (Component Library) if a component was created or modified.
+- Update Sections 5/6/7 if design tokens, fonts, or colors were added/changed.
+- Bump the version number and "Last updated" date at the top of the file.
+
+Failure to read and follow `DESIGN.md` will result in inconsistent UI, visual regressions, and wasted iteration cycles.
+
 === foundation rules ===
 
 # Laravel Boost Guidelines
@@ -27,6 +60,7 @@ This application is a Laravel application and its main Laravel ecosystems packag
 - phpunit/phpunit (PHPUNIT) - v11
 - rector/rector (RECTOR) - v2
 - tailwindcss (TAILWINDCSS) - v4
+- laravel-echo (ECHO) - v2
 
 ## Skills Activation
 
diff --git a/CLAUDE.md b/CLAUDE.md
index ea68f0f..e8aef0e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,4 +1,37 @@
 <laravel-boost-guidelines>
+=== .ai/design-system rules ===
+
+# Design System (CRITICAL — Auto-Read Required)
+
+
+This project has a comprehensive Design System documented in `DESIGN.md` at the project root.
+
+
+## Before Any UI/UX Work
+
+
+**BEFORE** making ANY frontend, UI, UX, styling, component, animation, Blade template, or Tailwind-related change, you MUST read `DESIGN.md` using your file reading tool to understand the established:
+- Design tokens and color system
+- Typography scale and font conventions
+- Component patterns (toasts, modals, buttons, indicators)
+- Spacing constants and layout architecture
+- Animation and transition conventions
+- Responsive breakpoint rules
+
+This applies to: Blade views, CSS files, Alpine.js interactions, GSAP animations, Livewire component UI, toast notifications, modals, buttons, indicators, and any other visual element.
+
+
+## After Completing UI/UX Work
+
+
+**AFTER** completing any UI/UX change, you MUST update `DESIGN.md` per its Section 15 (Maintenance Protocol):
+- Add a new entry to Section 14 (Iteration History) using the provided template.
+- Update Section 9 (Component Library) if a component was created or modified.
+- Update Sections 5/6/7 if design tokens, fonts, or colors were added/changed.
+- Bump the version number and "Last updated" date at the top of the file.
+
+Failure to read and follow `DESIGN.md` will result in inconsistent UI, visual regressions, and wasted iteration cycles.
+
 === foundation rules ===
 
 # Laravel Boost Guidelines
@@ -27,6 +60,7 @@ This application is a Laravel application and its main Laravel ecosystems packag
 - phpunit/phpunit (PHPUNIT) - v11
 - rector/rector (RECTOR) - v2
 - tailwindcss (TAILWINDCSS) - v4
+- laravel-echo (ECHO) - v2
 
 ## Skills Activation
 
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..2faad21
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,902 @@
+# Zemail (iMail) — Design System & UI/UX Guidelines
+
+> **Version:** 1.1.0 — Last updated: 2026-03-06
+>
+> This document is the single source of truth for every visual, interactive, and architectural decision in the Zemail project. Any developer or AI agent working on this codebase **must** read this document before making any frontend changes, and **must** update it after completing any UI/UX-related work.
+
+---
+
+## Table of Contents
+
+1. [Activated Skills & References](#1-activated-skills--references)
+2. [Design Philosophy](#2-design-philosophy)
+3. [Tech Stack](#3-tech-stack)
+4. [Aesthetic Preset: "DevTool Dark"](#4-aesthetic-preset-devtool-dark)
+5. [Design Tokens (CSS Custom Properties)](#5-design-tokens-css-custom-properties)
+6. [Typography](#6-typography)
+7. [Color System](#7-color-system)
+8. [Spacing & Layout](#8-spacing--layout)
+9. [Component Library](#9-component-library)
+10. [Animation & Micro-Interactions](#10-animation--micro-interactions)
+11. [Real-Time UI Patterns](#11-real-time-ui-patterns)
+12. [Responsive Design Rules](#12-responsive-design-rules)
+13. [Accessibility](#13-accessibility)
+14. [Iteration History & Design Decisions](#14-iteration-history--design-decisions)
+15. [Maintenance Protocol (MANDATORY)](#15-maintenance-protocol-mandatory)
+
+---
+
+## 1. Activated Skills & References
+
+The following `.agents/skills` were activated during the initial design and development of this project. **Any future developer or AI agent must activate the relevant skill before working in that domain.**
+
+| Skill | Path | When to Activate |
+|-------|------|------------------|
+| **`bento-landing-page-generator`** | `.agents/skills/bento-landing-page-generator/SKILL.md` | Building or modifying Bento-style landing pages, hero sections, feature grids. This was the **primary skill** used to establish the entire visual language of this project. |
+| **`tailwindcss-development`** | `.agents/skills/tailwindcss-development/SKILL.md` | Any styling work. Uses Tailwind CSS **v4** with CSS-first `@theme` configuration. Never use deprecated v3 utilities. |
+| **`fluxui-development`** | `.agents/skills/fluxui-development/SKILL.md` | Building forms, modals, inputs, or interactive UI components. Uses the **Flux UI Free** edition. |
+| **`volt-development`** | `.agents/skills/volt-development/SKILL.md` | Creating single-file Livewire components. Check existing Volt components for functional vs. class-based style before creating new ones. |
+| **`cinematic-landing-page-builder`** | `.agents/skills/cinematic-landing-page-builder/SKILL.md` | Building cinematic, pixel-perfect landing pages with strict design system enforcement, micro-interactions, and GSAP animations. |
+| **`pest-testing`** | `.agents/skills/pest-testing/SKILL.md` | Writing or modifying tests. Uses Pest 3. |
+
+### External References Used
+
+- **Appwrite Dashboard** — Dark UI inspiration for surface colors, card borders, and glow effects.
+- **Vercel** — Minimal dark theme, clean typography hierarchy, terminal-style code blocks.
+- **Stripe / BentoNow** — Asymmetric Bento Grid layout patterns, card span ratios.
+- **Heroicons** — Default icon set. Search at [heroicons.com](https://heroicons.com/). Never guess icon names.
+
+---
+
+## 2. Design Philosophy
+
+### Core Principles
+
+1. **Premium-First**: Every element must feel premium and state-of-the-art. No basic MVPs, no generic layouts. The user should be "wowed" at first glance.
+2. **Dark Mode Native**: The application is dark-mode-only (`class="dark"` on `<html>`). All design tokens, colors, and contrasts are optimized for dark backgrounds.
+3. **Cinematic Motion**: Interfaces should feel alive. Use GSAP for scroll-driven reveals, Alpine.js for instant state transitions, and CSS `transition-all` for micro-interactions.
+4. **Information Density**: Mailbox UIs are information-dense by nature. Use compact typography (`text-[10px]`, `text-[11px]`), uppercase tracking (`tracking-widest`, `tracking-[0.2em]`), and monospace fonts for data.
+5. **No Placeholders**: Never use placeholder images or `lorem ipsum`. Build all visuals with HTML/CSS/SVG. Use `generate_image` tool if real images are needed.
+6. **Glassmorphism & Glow**: Frosted glass effects (`backdrop-blur-xl`, `bg-white/5`) and colored glows (`shadow-[0_0_30px_rgba(236,72,153,0.3)]`) are signature visual elements.
+
+### The "Bento Box" Layout Rules
+
+- Use **asymmetric CSS Grids** (e.g., `grid-cols-1 md:grid-cols-3` or `md:grid-cols-4`).
+- Cards must have **distinct spans** (`col-span-2`, `row-span-2`) to create a mosaic effect.
+- All cards use `rounded-2xl` or `rounded-3xl` border radii.
+- Cards use `bg-zinc-900` surface color with `border border-white/5` borders.
+- Background glows inside cards use `blur-2xl` with accent color at very low opacity (`bg-pink-500/5`).
+
+---
+
+## 3. Tech Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Backend | Laravel | v12 |
+| Real-Time | Livewire | v3 |
+| Client-Side Reactivity | Alpine.js | (bundled with Livewire) |
+| Styling | Tailwind CSS | v4 |
+| Animations | GSAP | 3.12.5 |
+| Component Library | Flux UI Free | v2 |
+| WebSocket | Laravel Reverb | v1 |
+| Fonts | Google Fonts (via Bunny) | Inter, JetBrains Mono |
+| Icons | Heroicons (via Flux) | — |
+| QR Generator | QRious | 4.0.2 |
+| Build Tool | Vite | v7 |
+
+### Asset Pipeline
+
+```
+resources/css/app.css    → Tailwind v4 with @theme design tokens
+resources/js/app.js      → Laravel Echo + Pusher + WebSocket status dispatching
+resources/views/          → Blade templates, Livewire components, anonymous components
+```
+
+All frontend changes require `npm run build` (or `npm run dev` during development) to take effect.
+
+---
+
+## 4. Aesthetic Preset: "DevTool Dark"
+
+This project uses **Preset A — "DevTool Dark"**, inspired by Appwrite and Vercel.
+
+| Property | Value |
+|----------|-------|
+| Background | `#09090B` (`bg-app-bg`) |
+| Surface | `#18181B` (`bg-app-surface` / `bg-zinc-900`) |
+| Borders | `#27272A` (`border-app-border` / `border-white/5`) |
+| Primary Accent | `#EC4899` (Pink) |
+| Secondary Accent | `#10B981` (Emerald) |
+| Text Primary | `#FAFAFA` |
+| Text Secondary | `#737373` (`text-zinc-500`) |
+| Text Muted | `#525252` (`text-zinc-600`) |
+| Selection Highlight | `rgba(236, 72, 153, 0.3)` (`selection:bg-[#EC4899]/30`) |
+
+---
+
+## 5. Design Tokens (CSS Custom Properties)
+
+All design tokens are defined in `resources/css/app.css` using Tailwind v4's CSS-first `@theme` directive.
+
+```css
+@theme {
+  /* Core Application Colors */
+  --color-app-bg: #09090B;
+  --color-app-surface: #18181B;
+  --color-app-border: #27272A;
+  --color-app-red: #EC6A5F;     /* macOS-style traffic light red */
+  --color-app-yellow: #F4BF4F;  /* macOS-style traffic light yellow */
+  --color-app-green: #61C554;   /* macOS-style traffic light green */
+
+  /* Zinc Scale (Dark Mode Neutrals) */
+  --color-zinc-50: #fafafa;
+  --color-zinc-500: #737373;
+  --color-zinc-600: #525252;
+  --color-zinc-800: #262626;
+  --color-zinc-900: #171717;
+  --color-zinc-950: #0a0a0a;
+
+  /* Primary (Purple/Indigo Scale — used for accents) */
+  --color-primary-500: #787ddc;
+  --color-primary-600: #615dce;
+
+  /* App Primary (oklch scale — for gradients and advanced color) */
+  --color-app-primary-500: oklch(0.589 0.137 290.02);
+  --color-app-primary-600: oklch(0.506 0.16 288.92);
+
+  /* Typography */
+  --font-sans: 'Instrument Sans', ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+### Important Token Rules
+
+- **Never hardcode colors** that already exist as tokens. Use `bg-app-bg`, `text-zinc-500`, etc.
+- **Opacity modifiers** use the Tailwind v4 slash syntax: `bg-pink-500/10`, not the deprecated `bg-opacity-*`.
+- **New tokens** must be added to `@theme {}` in `app.css`, not in a `tailwind.config.js` file (Tailwind v4 is CSS-first).
+
+---
+
+## 6. Typography
+
+### Font Stack
+
+| Usage | Font | Weight | Loaded Via |
+|-------|------|--------|------------|
+| Body & UI | **Inter** | 400, 500, 600, 700 | Bunny Fonts CDN |
+| Code, Data, Addresses | **JetBrains Mono** | 400, 500 | Bunny Fonts CDN |
+
+### Font Loading
+
+```html
+<link rel="preconnect" href="https://fonts.bunny.net">
+<link href="https://fonts.bunny.net/css?family=inter:400,500,600,700|jetbrains-mono:400,500" rel="stylesheet" />
+```
+
+### Typography Scale
+
+| Element | Classes | Example Usage |
+|---------|---------|---------------|
+| Page Heading | `text-2xl font-black tracking-tight uppercase italic` | Confirm modal title |
+| Section Label | `text-[10px] font-bold text-zinc-500 uppercase tracking-widest` | "Active Mailbox", "Your Sessions" |
+| Category Label | `text-[10px] font-bold text-zinc-600 uppercase tracking-[0.2em]` | Sidebar section headers |
+| Data Display (email) | `text-[11px] font-mono text-white break-all` | Email address display |
+| Toast Type Label | `text-[10px] font-black uppercase tracking-[0.2em] opacity-40` | Toast "SUCCESS", "INFO" label |
+| Toast Message | `text-[11px] font-bold tracking-wide whitespace-pre-wrap` | Toast notification body |
+| Button Text | `text-xs font-bold` | Primary action buttons |
+| Compact Button Text | `text-[10px] font-black uppercase tracking-[0.2em]` | Modal confirm/cancel buttons |
+| Timer Display | `text-[10px] font-mono text-pink-500` | Expiration countdown |
+| Badge/Count | `text-[10px] font-bold px-1.5 py-0.5` | Unread count badge |
+
+### Typography Rules
+
+- **No comments in code** unless logic is exceptionally complex. Use PHPDoc blocks instead.
+- **Uppercase + Wide Tracking** is the signature style for labels and metadata text.
+- **Monospace (`font-mono`)** is used for any machine-readable data: email addresses, timers, code blocks.
+- **`break-all`** must be applied to email addresses to prevent overflow on small screens.
+
+---
+
+## 7. Color System
+
+### Semantic Color Mapping
+
+These semantic colors are used consistently across all components (toasts, modals, buttons, indicators):
+
+| Semantic | Background | Border | Text | Icon BG | Glow |
+|----------|-----------|--------|------|---------|------|
+| **Success** | `bg-emerald-500/10` | `border-emerald-500/20` | `text-emerald-100` | `bg-emerald-500/20 text-emerald-400` | `bg-emerald-500/10` |
+| **Info** | `bg-blue-500/10` | `border-blue-500/20` | `text-blue-100` | `bg-blue-500/20 text-blue-400` | `bg-blue-400/10` |
+| **Warning** | `bg-amber-500/10` | `border-amber-500/20` | `text-amber-100` | `bg-amber-500/20 text-amber-400` | `bg-amber-400/10` |
+| **Danger** | `bg-rose-500/10` | `border-rose-500/20` | `text-rose-100` | `bg-rose-500/20 text-rose-400` | `bg-rose-400/10` |
+
+### Important Color Rules
+
+- **Never use generic red/blue/green**. Always use the curated semantic mapping above.
+- **Pink (`#EC4899` / `pink-500`)** is the project's primary accent. Used for highlights, CTAs, gradients, and the expiration progress bar.
+- **Emerald (`emerald-500`)** is the secondary accent. Used for success states and the WebSocket connection indicator.
+- **Rose (`rose-500`)** is used for destructive actions, errors, and the disconnected WebSocket indicator.
+- The **expiration progress bar** uses a gradient from pink to emerald: `bg-gradient-to-r from-pink-500 to-emerald-500`.
+- **Toast notification types**: `success`, `info`, `warning`, `danger`. **Never** use `error` — use `danger` instead.
+
+---
+
+## 8. Spacing & Layout
+
+### Global Spacing Constants
+
+| Context | Value | Tailwind Class |
+|---------|-------|----------------|
+| Card Padding | 16px | `p-4` |
+| Card Border Radius | 16px | `rounded-2xl` |
+| Modal Border Radius | 32px | `rounded-[32px]` |
+| Button Border Radius | 16px | `rounded-2xl` |
+| Icon Container Radius | 12px | `rounded-xl` |
+| Section Gap | 24px | `space-y-6` |
+| Inner Element Gap | 8px | `space-y-2` / `gap-2` |
+| Toast Container Spacing | 12px | `gap-3` |
+| Screen Edge Margin | 24px | `bottom-6 left-6 right-6` (responsive) |
+
+### Layout Architecture
+
+The main mailbox view (`mailbox.blade.php`) uses a **three-panel layout**:
+
+```
+┌──────────┬──────────────┬──────────────────────┐
+│ Sidebar  │  Email List   │   Email Detail       │
+│ (280px)  │  (flex-1)     │   (flex-1, lg only)  │
+│          │               │                      │
+│ - Active │  - Search     │   - Header           │
+│   Mailbox│  - Email rows │   - Body (iframe)    │
+│ - Create │  - Pagination │   - Attachments      │
+│ - Sessions               │                      │
+└──────────┴──────────────┴──────────────────────┘
+```
+
+- Sidebar uses `w-[280px]` when open, collapses on smaller screens.
+- `overflow-hidden` on `<body>` prevents page-level scrolling. Each panel scrolls independently.
+- Use `scrollbar-hide` utility class (custom CSS) to hide scrollbars in compact panels.
+
+### Body-Level Styling
+
+```html
+<body class="bg-app-bg text-[#FAFAFA] antialiased selection:bg-[#EC4899]/30 h-full overflow-hidden">
+```
+
+---
+
+## 9. Component Library
+
+### 9.1 Global Toast Notification System
+
+**Location:** `resources/views/components/layouts/app.blade.php`
+**Trigger:** `$this->dispatch('notify', message: '...', type: 'success')` from Livewire, or `addToast('...', 'success')` from Alpine.js.
+**Event:** `@notify.window` on `<body>`.
+
+#### Architecture
+
+```
+<body x-data="{ toasts: [], wsConnected: true, addToast(msg, type) {...} }">
+  └── @notify.window="addToast($event.detail.message, $event.detail.type)"
+  └── @ws-status.window="wsConnected = $event.detail.connected"
+  └── <div class="fixed bottom-6 left-6 right-6 sm:left-auto sm:right-6 z-[100]">
+        └── <template x-for="toast in toasts">
+              └── Toast card with icon, type label, message, close button
+```
+
+#### Allowed Types
+
+| Type | Visual | Use Case |
+|------|--------|----------|
+| `success` | Emerald green | Copy to clipboard, successful actions |
+| `info` | Blue | New email received, informational alerts |
+| `warning` | Amber/Orange | Cooldown period active, soft warnings |
+| `danger` | Rose red | Address already in use, destructive errors |
+
+#### Design Specifications
+
+- **Container:** `fixed bottom-6 left-6 right-6 sm:left-auto sm:right-6 z-[100]`
+  - Mobile: Full-width with 24px margins on both sides.
+  - Desktop: Anchored to bottom-right.
+- **Toast Card:** `w-full sm:min-w-[320px] p-4 rounded-2xl border backdrop-blur-xl shadow-2xl`
+- **Auto-dismiss:** 4000ms timeout.
+- **Enter Animation:** `transition ease-out duration-500` — slides in from right with scale.
+- **Leave Animation:** `transition ease-in duration-300` — fades out with scale.
+- **Multiline Support:** `whitespace-pre-wrap` on message div. Use `\n` in PHP strings for line breaks.
+- **Icon:** 40×40px container (`w-10 h-10 rounded-xl`) with SVG stroke icon.
+- **Close Button:** `p-1.5 rounded-lg hover:bg-white/5` with X icon.
+
+#### Toast Message Formatting Examples
+
+```php
+// Single-line (copy confirmation)
+$this->dispatch('notify', message: 'Address copied to clipboard', type: 'success');
+
+// Multi-line (new email notification)
+$this->dispatch('notify',
+    message: "Sender: {$sender}\nSubject: {$subject}",
+    type: 'info'
+);
+
+// Cooldown warning with precise timer
+$this->dispatch('notify',
+    message: "Address is in cooldown. Try again in {$remaining}.",
+    type: 'warning'
+);
+
+// Error (address conflict)
+$this->dispatch('notify', message: 'Address already in use.', type: 'danger');
+```
+
+### 9.2 Confirm Modal
+
+**Location:** `resources/views/components/bento/confirm-modal.blade.php`
+**Trigger:** `$dispatch('open-confirm-modal', { title, message, confirmLabel, type, action })`
+
+#### Design Specifications
+
+- **Backdrop:** `bg-zinc-950/80 backdrop-blur-xl` — heavy frosted glass overlay.
+- **Card:** `max-w-[400px] bg-zinc-900 border border-white/10 rounded-[32px] p-8` — super-rounded.
+- **Glow:** `w-64 h-64 rounded-full blur-[80px] opacity-20` — type-colored radial glow behind the card.
+- **Icon:** `w-16 h-16 rounded-2xl` — large, prominent, type-colored icon container.
+- **Title:** `text-2xl font-black text-white tracking-tight uppercase italic` — bold, dramatic.
+- **Message:** `text-xs font-bold text-zinc-500 uppercase tracking-widest leading-relaxed` — subdued.
+- **Buttons:** `grid grid-cols-2 gap-4` — two equal-width buttons with `py-4 rounded-2xl`.
+- **Cancel:** `bg-white/5 border border-white/10 text-zinc-400` — ghost style.
+- **Confirm:** Solid type-colored background (e.g., `bg-rose-600 text-white` for danger).
+
+#### Supported Types
+
+Same four types as the toast system: `danger`, `info`, `warning`, `success`.
+
+### 9.3 WebSocket Connection Indicator
+
+**Location:** `resources/views/livewire/mailbox.blade.php` (Active Mailbox card)
+**State Source:** Global `wsConnected` from `<body x-data>`.
+
+```html
+<div class="w-1.5 h-1.5 rounded-full animate-pulse transition-colors duration-500"
+     :class="wsConnected ? 'bg-emerald-500' : 'bg-rose-500'"></div>
+```
+
+- **Connected:** Emerald green pulsing dot.
+- **Disconnected:** Rose red pulsing dot.
+- **Transition:** `duration-500` smooth color transition between states.
+- The dot sits next to the "ACTIVE MAILBOX" label in the sidebar card.
+
+### 9.4 Expiration Progress Bar
+
+**Location:** `resources/views/livewire/mailbox.blade.php`
+
+#### Design Specifications
+
+- **Track:** `h-1 bg-white/5 rounded-full overflow-hidden`
+- **Fill:** `bg-gradient-to-r from-pink-500 to-emerald-500 transition-all duration-1000 ease-linear`
+- **Timer Text:** `text-[10px] font-mono text-pink-500`
+- **Label:** `text-[10px] text-zinc-500 uppercase font-black tracking-tighter` — "EXPIRES IN"
+
+#### Time Display Rules (User Iteration)
+
+The expiration timer processes remaining time **in seconds** and displays with adaptive precision:
+
+```javascript
+// Display hierarchy (most precise possible):
+if (days > 0)  → "14d 23h 59m 59s"
+if (hours > 0) → "23h 59m 59s"
+if (mins > 0)  → "59m 59s"
+else           → "59s"
+```
+
+> **User Iteration Note:** Originally showed "0 minutes" when only seconds remained. Fixed to always show seconds-level precision and cascade upward to days.
+
+#### Auto-Expiration Behavior
+
+When the timer reaches zero:
+1. Alpine.js sets `isExpired = true` and fires `$wire.deleteMailbox(id)`.
+2. This triggers a soft delete on the Mailbox model.
+3. The `deleted` Eloquent event fires cleanup (MongoDB email bodies, MariaDB email metadata).
+4. UI refreshes to show a new auto-generated mailbox.
+
+### 9.5 Cinematic Creation Overlay
+
+**Location:** `resources/views/livewire/mailbox.blade.php`
+
+Shown when a first-time visitor arrives or all mailboxes are deleted:
+
+- **Backdrop:** `fixed inset-0 z-[200] bg-zinc-950/90` — full-screen dark overlay.
+- **Logo:** `animate-pulse` with scale transition (`scale-110 opacity-100` → `scale-90 opacity-0`).
+- **Spinner:** Custom CSS spinner using `border-4 border-pink-500 border-t-transparent animate-[spin_1.5s_cubic-bezier(0.4,0,0.2,1)_infinite]` with pink glow shadow.
+- **Auto-dismiss:** `setTimeout(() => $wire.finishAutoCreation(), 1000)` — 1 second cinematic delay.
+
+### 9.6 Action Button Patterns
+
+#### Icon Buttons (Toolbar Style)
+
+```html
+<!-- Standard action button -->
+<button class="p-1.5 rounded-lg bg-white/5 text-zinc-500 hover:text-white hover:bg-white/10 transition-all cursor-pointer">
+    <svg class="w-3.5 h-3.5" ...></svg>
+</button>
+
+<!-- Destructive action button -->
+<button class="p-1.5 rounded-lg bg-rose-500/10 text-rose-500/60 hover:text-rose-500 hover:bg-rose-500/20 transition-all cursor-pointer">
+    <svg class="w-3.5 h-3.5" ...></svg>
+</button>
+```
+
+#### Full-Width CTA Button
+
+```html
+<button class="w-full py-3 px-4 rounded-2xl bg-white/5 border border-white/10 text-white text-xs font-bold flex items-center justify-center gap-2 hover:bg-white/10 hover:border-pink-500/30 transition-all group cursor-pointer">
+    <div class="w-5 h-5 rounded-lg bg-pink-500/20 text-pink-500 flex items-center justify-center group-hover:scale-110 transition-transform">
+        <svg class="w-3.5 h-3.5" ...></svg>
+    </div>
+    Create New Mailbox
+</button>
+```
+
+#### Key Button Rules
+
+- All buttons must have `cursor-pointer`.
+- Icon containers inside buttons use `group-hover:scale-110 transition-transform` for a micro-interaction.
+- Destructive buttons use the rose color scale at reduced opacity (`rose-500/10`, `rose-500/60`).
+- Ghost buttons use `bg-white/5 border border-white/10`.
+
+---
+
+## 10. Animation & Micro-Interactions
+
+### GSAP (Heavy Scroll Animations)
+
+Loaded via CDN in the layout:
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js"></script>
+```
+
+- Used primarily on the **landing page** for cinematic scroll reveals.
+- Initialize inside Alpine's `x-init` hook: `x-init="gsap.from($el, { opacity: 0, y: 50, scrollTrigger: $el })"`.
+- GSAP is **not used** in the mailbox application UI — Alpine.js handles all reactive transitions there.
+
+### Alpine.js (Instant UI State)
+
+All immediate user interactions must be handled client-side with Alpine.js:
+
+| Pattern | Usage |
+|---------|-------|
+| `x-show` + `x-transition` | Modals, overlays, conditional panels |
+| `x-data` + `$watch` | Reactive state management (timers, mobile view switching) |
+| `@click` + `$wire` | Livewire method calls from the client |
+| `@click` + `$dispatch` | Triggering global events (toasts, modals) |
+| `@resize.window` | Responsive sidebar behavior |
+| `:class` bindings | Dynamic styling (WebSocket indicator, toast types) |
+
+### CSS Transitions
+
+| Property | Duration | Easing | Usage |
+|----------|----------|--------|-------|
+| `transition-all` | default (150ms) | default | Button hover states |
+| `transition-colors duration-500` | 500ms | default | WebSocket indicator color change |
+| `transition-all duration-1000 ease-linear` | 1000ms | linear | Progress bar width |
+| `transition ease-out duration-500` | 500ms | ease-out | Toast enter |
+| `transition ease-in duration-300` | 300ms | ease-in | Toast leave |
+| `transition ease-out duration-700` | 700ms | ease-out | Full-screen overlay enter |
+| `transition ease-in duration-500` | 500ms | ease-in | Full-screen overlay leave |
+| `transition ease-out duration-500` | 500ms | ease-out | Modal card enter (with scale + translateY) |
+
+### Custom Keyframes
+
+```css
+@keyframes slide-right {
+    from { opacity: 0; transform: translateX(-10px); }
+    to   { opacity: 1; transform: translateX(0); }
+}
+
+@keyframes slide-up {
+    from { opacity: 0; transform: translateY(20px); }
+    to   { opacity: 1; transform: translateY(0); }
+}
+
+.animate-slide-up {
+    animation: slide-up 0.8s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+```
+
+---
+
+## 11. Real-Time UI Patterns
+
+### WebSocket Architecture
+
+```
+app.js → Laravel Echo (Reverb broadcaster)
+       → Pusher connection state listeners
+       → Dispatches window events: 'ws-status'
+
+app.blade.php → Listens for @ws-status.window
+              → Updates global Alpine 'wsConnected' state
+
+mailbox.blade.php → Reads 'wsConnected' for indicator color
+```
+
+### Connection Status Lifecycle
+
+```javascript
+// resources/js/app.js
+window.Echo.connector.pusher.connection.bind('connected',    () => dispatchStatus(true));
+window.Echo.connector.pusher.connection.bind('unavailable',  () => dispatchStatus(false));
+window.Echo.connector.pusher.connection.bind('disconnected', () => dispatchStatus(false));
+window.Echo.connector.pusher.connection.bind('failed',       () => dispatchStatus(false));
+```
+
+### Conditional Echo Initialization
+
+Echo is only initialized on pages that need it, controlled by a data attribute:
+
+```html
+<div data-requires-reverb="true"> ... </div>
+```
+
+```javascript
+if (document.querySelector('[data-requires-reverb]')) {
+    window.Echo = new Echo({ ... });
+}
+```
+
+### New Email Real-Time Flow
+
+1. `ProcessIncomingEmail` job saves email to MariaDB + MongoDB.
+2. `NewEmailReceived` event broadcasts on `mailbox.{domain}` channel.
+3. Livewire listener `echo:mailbox.{domain},.new.email` fires `onNewEmail()`.
+4. `onNewEmail()` dispatches a toast notification with sender + subject.
+5. `onNewEmail()` dispatches `$refresh` to reload the email list.
+
+---
+
+## 12. Responsive Design Rules
+
+### Breakpoint Strategy
+
+| Breakpoint | Prefix | Behavior |
+|-----------|--------|----------|
+| < 640px | (none) | Mobile: full-width toast, collapsed sidebar, single-panel view |
+| ≥ 640px | `sm:` | Toast anchors to bottom-right, min-width restored |
+| ≥ 1024px | `lg:` | Email detail panel becomes visible. Mobile view switcher deactivated |
+| ≥ 1280px | `xl:` | Sidebar always open |
+
+### Mobile View Switching
+
+On mobile (`< 1024px`), the mailbox uses an Alpine-driven view switcher:
+
+```javascript
+$watch('selectedId', value => { if (value && window.innerWidth < 1024) mobileView = 'detail' });
+$watch('mobileView', value  => { if (value === 'list' && window.innerWidth < 1024) selectedId = null });
+```
+
+### Toast Responsiveness (User Iteration)
+
+> **User Iteration Note:** The toast container originally used `fixed bottom-6 right-6` with a hard `min-w-[320px]`, causing it to overflow and touch the left screen edge on small devices. This was fixed by:
+> - Container: `left-6 right-6 sm:left-auto sm:right-6` — full-width with margins on mobile, bottom-right anchor on desktop.
+> - Toast card: `w-full sm:min-w-[320px]` — fluid on mobile, minimum width on desktop.
+
+---
+
+## 13. Accessibility
+
+### Required Patterns
+
+- All interactive elements must have `cursor-pointer`.
+- Icon-only buttons must have a `title` attribute for tooltip/screen-reader context.
+- `antialiased` is applied globally on `<body>` for smoother font rendering.
+- `selection:bg-[#EC4899]/30` provides a branded text selection color.
+- Use semantic HTML elements wherever possible (`<nav>`, `<button>`, `<main>`).
+- All interactive elements should have unique, descriptive IDs for browser testing.
+
+### Scrollbar Handling
+
+```css
+.scrollbar-hide::-webkit-scrollbar { display: none; }
+.scrollbar-hide { -ms-overflow-style: none; scrollbar-width: none; }
+```
+
+---
+
+## 14. Iteration History & Design Decisions
+
+This section documents every significant design iteration from the conversation thread, in chronological order. Each entry includes the rationale so future developers understand **why** a decision was made.
+
+### Iteration 1: Expiration Timer Precision
+
+**Problem:** When a mailbox had only seconds remaining, the timer displayed "0 minutes" instead of showing seconds.
+
+**Solution:** Rewrote the Alpine.js timer to process time in seconds and display with cascading precision: `days → hours → minutes → seconds`. The timer now always shows the most granular unit available.
+
+**Files Changed:** `resources/views/livewire/mailbox.blade.php`
+
+---
+
+### Iteration 2: Soft Deletes Instead of Hard Deletes
+
+**Problem:** Clicking the delete button permanently removed the mailbox record from the database, losing all audit trail.
+
+**Solution:** Added `SoftDeletes` trait to the `Mailbox` model. Created a migration to add `deleted_at` timestamps. All delete operations now soft-delete, preserving records for analytics and potential reclamation.
+
+**Files Changed:** `app/Models/Mailbox.php`, `database/migrations/2026_03_05_202748_add_soft_deletes_to_mailboxes_table.php`
+
+---
+
+### Iteration 3: Mailbox Duplication Prevention & Cooldown System
+
+**Problem:** Random address generation could produce duplicates. Users could snipe deleted addresses instantly.
+
+**Solution:**
+- **Random addresses:** `do-while` loop checks `withTrashed()` to ensure uniqueness.
+- **Same user reclaiming:** Automatically restores soft-deleted mailbox and updates expiration.
+- **Different user claiming:** Tier-based cooldown enforced (Guest: 24h, Free: 12h, Pro: 6h, Enterprise: instant).
+- **Cooldown toast:** Shows precise remaining time down to seconds (e.g., "11h 42m 18s").
+
+**Files Changed:** `app/Livewire/Mailbox.php`
+
+---
+
+### Iteration 4: Toast Notification Type Fix
+
+**Problem:** Cooldown and error notifications were dispatched with `type: 'error'`, which didn't match the global toast's four supported types (`success`, `info`, `warning`, `danger`). The toast would render without proper styling.
+
+**Solution:** Changed "address already in use" to `type: 'danger'` (rose red) and cooldown warnings to `type: 'warning'` (amber). **Rule: Never use `'error'` as a toast type.**
+
+**Files Changed:** `app/Livewire/Mailbox.php`
+
+---
+
+### Iteration 5: Session Linking on Login
+
+**Problem:** Guest users creating mailboxes via session would lose access when they registered or logged in.
+
+**Solution:** Added an `Event::listen(Login::class)` in `AppServiceProvider` to automatically transfer mailboxes from `session_id` to `user_id` when a guest authenticates.
+
+**Files Changed:** `app/Providers/AppServiceProvider.php`
+
+---
+
+### Iteration 6: Automatic Expiration Cleanup
+
+**Problem:** If a user closed their browser, expired mailboxes would never be cleaned up.
+
+**Solution:** Dual approach:
+1. **Live UI Hook:** Alpine.js timer triggers `$wire.deleteMailbox()` when countdown reaches zero.
+2. **Background Worker:** `CleanupExpiredMailboxes` Artisan command runs every minute via Laravel Scheduler.
+3. **Data Cleanup:** Eloquent `deleted` event on `Mailbox` model wipes associated `EmailBody` (MongoDB) and `Email` (MariaDB) records.
+
+**Files Changed:** `app/Console/Commands/CleanupExpiredMailboxes.php`, `routes/console.php`, `app/Models/Mailbox.php`, `resources/views/livewire/mailbox.blade.php`
+
+---
+
+### Iteration 7: WebSocket Status Indicator
+
+**Problem:** The "Active Mailbox" pulse indicator was always green, regardless of connection state.
+
+**Solution:**
+1. Added `connected/disconnected/unavailable/failed` listeners to Echo in `app.js`.
+2. Stored `wsConnected` in global Alpine state on `<body>`.
+3. Bound indicator color dynamically: emerald for connected, rose for disconnected.
+
+**Files Changed:** `resources/js/app.js`, `resources/views/components/layouts/app.blade.php`, `resources/views/livewire/mailbox.blade.php`
+
+---
+
+### Iteration 8: New Email Toast Notification
+
+**Problem:** Users had no visual cue when a new email arrived while reading another email.
+
+**Solution:** Updated `onNewEmail()` to dispatch a toast with sender and subject before refreshing the list. Used `type: 'info'` (blue) for the notification.
+
+**Files Changed:** `app/Livewire/Mailbox.php`
+
+---
+
+### Iteration 9: Multiline Toast Formatting
+
+**Problem:** Toast notification for new emails displayed sender and subject on a single line, making it hard to scan.
+
+**Solution:**
+1. Changed message format to `"Sender: {$sender}\nSubject: {$subject}"` using `\n`.
+2. Added `whitespace-pre-wrap` to the toast message div to render line breaks.
+
+**Files Changed:** `app/Livewire/Mailbox.php`, `resources/views/components/layouts/app.blade.php`
+
+---
+
+### Iteration 10: Mobile Toast Overflow Fix
+
+**Problem:** On small screens (< 320px viewport), the toast's `min-w-[320px]` caused it to overflow beyond the left edge of the screen.
+
+**Solution:**
+- Container: Changed from `fixed bottom-6 right-6` to `fixed bottom-6 left-6 right-6 sm:left-auto sm:right-6`.
+- Toast card: Changed from `min-w-[320px]` to `w-full sm:min-w-[320px]`.
+
+**Files Changed:** `resources/views/components/layouts/app.blade.php`
+
+---
+
+### Iteration 11: Random Address Format
+
+**Problem:** Random mailbox addresses included an underscore before the number suffix (e.g., `john_doe_42@imail.app`).
+
+**Solution:** User manually removed the underscore from the format string. Addresses now generate as `johndoe42@imail.app`.
+
+**Files Changed:** `app/Livewire/Mailbox.php` (user edit)
+
+---
+
+## Appendix: File Reference Map
+
+| File | Purpose |
+|------|---------|
+| `resources/css/app.css` | Tailwind v4 theme tokens, Flux UI imports, dark mode config |
+| `resources/js/app.js` | Laravel Echo init, WebSocket status dispatching |
+| `resources/views/components/layouts/app.blade.php` | Global layout: fonts, GSAP, global Alpine state, toast system |
+| `resources/views/livewire/mailbox.blade.php` | Main mailbox UI: sidebar, email list, detail view, modals |
+| `resources/views/components/bento/confirm-modal.blade.php` | Reusable confirm modal with type-based theming |
+| `resources/views/livewire/landing-page.blade.php` | Bento-style SaaS landing page |
+| `app/Livewire/Mailbox.php` | Mailbox Livewire component: CRUD, WebSocket, analytics |
+| `app/Models/Mailbox.php` | Mailbox Eloquent model: soft deletes, cleanup events |
+| `app/Events/NewEmailReceived.php` | WebSocket broadcast event for incoming emails |
+| `app/Console/Commands/CleanupExpiredMailboxes.php` | Scheduled cleanup of expired mailboxes |
+
+---
+
+> **For AI Agents:** Before making any UI change, re-read the relevant sections of this document. Match existing patterns exactly. When in doubt, check sibling components for conventions. Always activate the appropriate skill from `.agents/skills/` before starting work. **After completing any UI/UX change, update this document per Section 15.**
+
+---
+
+## 15. Maintenance Protocol (MANDATORY)
+
+This document is a **living document**. Every developer or AI agent who makes a UI/UX-related change **must** update it before considering their work complete. This ensures no knowledge is lost and prevents future confusion or hallucination.
+
+### 15.1 When to Update
+
+| Scenario | What to Update | Priority |
+|----------|---------------|----------|
+| New component created | Add to **§9 Component Library** with full spec | 🔴 Required |
+| Existing component modified | Update the relevant subsection in **§9** | 🔴 Required |
+| New design token added | Add to **§5 Design Tokens** | 🔴 Required |
+| Color or typography changed | Update **§6 Typography** or **§7 Color System** | 🔴 Required |
+| New animation or transition | Add to **§10 Animation** table | 🟡 Recommended |
+| New real-time event or flow | Add to **§11 Real-Time UI Patterns** | 🔴 Required |
+| Responsive behavior changed | Update **§12 Responsive Design Rules** | 🔴 Required |
+| Any iterative design refinement | Add to **§14 Iteration History** | 🔴 Required |
+| New file created that affects UI | Add to **Appendix: File Reference Map** | 🟡 Recommended |
+| New external dependency added | Add to **§3 Tech Stack** table | 🔴 Required |
+| New skill activated | Add to **§1 Activated Skills** table | 🟡 Recommended |
+
+### 15.2 Iteration Entry Template
+
+Every design change must be logged in **§14 Iteration History** using this exact format:
+
+```markdown
+### Iteration N: [Short Descriptive Title]
+
+**Date:** YYYY-MM-DD
+**Conversation/PR:** [Link or ID if available]
+
+**Problem:** One sentence describing what was wrong or what the user requested.
+
+**Why:** One sentence explaining *why* this matters (UX impact, visual regression, accessibility, etc.).
+
+**Solution:** Bullet points detailing what was changed. Include:
+- Exact Tailwind classes added/removed/changed.
+- Any new Alpine.js state or events introduced.
+- Any new Livewire methods or events.
+
+**Files Changed:** Comma-separated list of relative file paths.
+
+**Design Rules Established:** (Optional) Any new rules that emerged from this change.
+```
+
+#### Example — Well-Written Entry
+
+```markdown
+### Iteration 12: Attachment Preview Thumbnails
+
+**Date:** 2026-03-10
+**Conversation:** c1ba6ccd-8bd9-4670-94e4-50b936242f39
+
+**Problem:** Attachments in the email detail view showed only filenames with no visual preview.
+
+**Why:** Users couldn't quickly assess whether an attachment was an image, document, or archive without downloading it.
+
+**Solution:**
+- Added thumbnail preview for image attachments using `<img>` with `w-16 h-16 rounded-lg object-cover`.
+- Non-image attachments show a colored icon badge: `bg-blue-500/10 text-blue-400` for documents, `bg-amber-500/10 text-amber-400` for archives.
+- Thumbnails are lazy-loaded with `loading="lazy"` to avoid blocking the main render.
+
+**Files Changed:** `resources/views/livewire/mailbox.blade.php`
+
+**Design Rules Established:** All file-type indicators must use the semantic color mapping from §7. Image previews always use `rounded-lg object-cover`.
+```
+
+#### Example — Poorly-Written Entry (DO NOT DO THIS)
+
+```markdown
+### Iteration 12: Fixed attachments
+
+**Problem:** Attachments looked bad.
+
+**Solution:** Made them look better.
+
+**Files Changed:** mailbox.blade.php
+```
+
+> ⚠️ **This lacks specificity.** It doesn't explain *why* it mattered, *what* CSS classes were used, or *what rules* emerged. A future developer reading this would learn nothing and likely re-implement differently.
+
+### 15.3 Component Documentation Template
+
+When adding a new component to **§9 Component Library**, use this structure:
+
+```markdown
+### 9.N [Component Name]
+
+**Location:** `path/to/file.blade.php`
+**Trigger:** How to invoke (dispatch event, Livewire property, Alpine method, etc.)
+**State Source:** Where the component gets its data.
+
+#### Design Specifications
+
+- **Container:** Exact Tailwind classes for the outermost wrapper.
+- **Card/Body:** Exact Tailwind classes for the main content area.
+- **[Other visual elements]:** One bullet per distinct visual element.
+
+#### Behavior
+
+- How it appears (animation/transition).
+- How it dismisses.
+- How it responds to different screen sizes.
+
+#### Supported Variants
+
+Table of variants (types, sizes, states) if applicable.
+
+#### Code Example
+
+```php
+// Minimal working example showing how to trigger/use the component.
+```
+```
+
+### 15.4 Update Checklist for AI Agents
+
+Before marking any UI/UX task as complete, run through this checklist:
+
+- [ ] **Read** relevant sections of `DESIGN.md` before starting work.
+- [ ] **Match** existing patterns from this document (colors, spacing, typography, animations).
+- [ ] **Update §14** with a new Iteration entry if any visual or behavioral change was made.
+- [ ] **Update §9** if a component was created or modified.
+- [ ] **Update §5/§6/§7** if design tokens, fonts, or colors were added/changed.
+- [ ] **Update §3** if a new dependency was added.
+- [ ] **Update Appendix** if a new file was created.
+- [ ] **Bump the version** at the top of the file (patch for fixes, minor for features).
+- [ ] **Update the "Last updated" date** at the top of the file.
+
+### 15.5 Versioning Convention
+
+The version number at the top of this file follows **Major.Minor.Patch**:
+
+| Change Type | Bump | Example |
+|------------|------|--------|
+| New section or major restructure | Major | 1.0.0 → 2.0.0 |
+| New component, new iteration, new design token | Minor | 1.0.0 → 1.1.0 |
+| Typo fix, clarification, minor class update | Patch | 1.0.0 → 1.0.1 |
+
+### 15.6 Context Preservation Rules
+
+To keep entries **light but sufficient** (no confusion, no hallucination):
+
+1. **Always include exact Tailwind classes.** Don't write "made it rounded" — write `rounded-2xl`.
+2. **Always include the file path.** Don't write "the modal" — write `resources/views/components/bento/confirm-modal.blade.php`.
+3. **Always state the user's intent.** Don't write "changed the color" — write "User requested rose for destructive actions instead of generic red."
+4. **Always state the technical reason.** Don't write "it was broken" — write "The toast type `'error'` had no matching `:class` binding in the Alpine template."
+5. **Keep it to 3-5 sentences max per entry.** More detail goes in the component spec (§9), not the iteration log (§14).
+6. **Reference existing sections.** Instead of re-explaining the color system, write "Uses semantic Danger mapping from §7."
diff --git a/GEMINI.md b/GEMINI.md
index ea68f0f..e8aef0e 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -1,4 +1,37 @@
 <laravel-boost-guidelines>
+=== .ai/design-system rules ===
+
+# Design System (CRITICAL — Auto-Read Required)
+
+
+This project has a comprehensive Design System documented in `DESIGN.md` at the project root.
+
+
+## Before Any UI/UX Work
+
+
+**BEFORE** making ANY frontend, UI, UX, styling, component, animation, Blade template, or Tailwind-related change, you MUST read `DESIGN.md` using your file reading tool to understand the established:
+- Design tokens and color system
+- Typography scale and font conventions
+- Component patterns (toasts, modals, buttons, indicators)
+- Spacing constants and layout architecture
+- Animation and transition conventions
+- Responsive breakpoint rules
+
+This applies to: Blade views, CSS files, Alpine.js interactions, GSAP animations, Livewire component UI, toast notifications, modals, buttons, indicators, and any other visual element.
+
+
+## After Completing UI/UX Work
+
+
+**AFTER** completing any UI/UX change, you MUST update `DESIGN.md` per its Section 15 (Maintenance Protocol):
+- Add a new entry to Section 14 (Iteration History) using the provided template.
+- Update Section 9 (Component Library) if a component was created or modified.
+- Update Sections 5/6/7 if design tokens, fonts, or colors were added/changed.
+- Bump the version number and "Last updated" date at the top of the file.
+
+Failure to read and follow `DESIGN.md` will result in inconsistent UI, visual regressions, and wasted iteration cycles.
+
 === foundation rules ===
 
 # Laravel Boost Guidelines
@@ -27,6 +60,7 @@ This application is a Laravel application and its main Laravel ecosystems packag
 - phpunit/phpunit (PHPUNIT) - v11
 - rector/rector (RECTOR) - v2
 - tailwindcss (TAILWINDCSS) - v4
+- laravel-echo (ECHO) - v2
 
 ## Skills Activation