260 lines
17 KiB
Markdown
260 lines
17 KiB
Markdown
# Design System: iamcavalli Admin & Client Portal (v1.0)
|
||
|
||
> "Minimalist Premium / Quiet Luxury" — the aesthetic that replaces the old
|
||
> mixed token/hardcoded styling across ClientHub's admin area. First applied
|
||
> to the Lead Pipeline page (Phase: Pipeline redesign); the tokens and
|
||
> primitives documented here are the base for restyling every other section.
|
||
|
||
## Philosophy
|
||
|
||
- **Quiet, not loud.** Elevation is nearly invisible (shadow opacity ≤ 0.02),
|
||
borders are hairline, color is used sparingly and only to carry meaning
|
||
(status, semantics) — never for decoration.
|
||
- **Density with air.** Generous padding (`py-4 px-6` in tables, `p-4` in
|
||
kanban columns) paired with small type (`text-xs`, `text-[11px]`) reads as
|
||
premium rather than cramped.
|
||
- **Numbers are monospace.** Prices, phone numbers, dates, counts — anything
|
||
tabular/numeric — use `font-mono` and right-alignment so columns of digits
|
||
line up.
|
||
- **Dual-theme by construction.** Every surface is built from semantic
|
||
tokens (`bg-card`, `text-muted-foreground`, `border-border`, …), never raw
|
||
Tailwind palette classes (`bg-white`, `text-slate-900`, …) or hex literals.
|
||
This is what makes dark mode "just work" without a parallel dark stylesheet.
|
||
- **Motion is functional.** Transitions exist to explain state change (sidebar
|
||
collapse, hover, drag) — `duration-200`–`duration-350`,
|
||
`ease-[cubic-bezier(0.4,0,0.2,1)]` for the sidebar specifically. No
|
||
decorative animation.
|
||
|
||
## Typography
|
||
|
||
- **Sans**: Plus Jakarta Sans (weights 300–700), loaded via `next/font/google`
|
||
as `--font-plus-jakarta-sans`, mapped to Tailwind's `--font-sans` in
|
||
`@theme`. Used for all UI text.
|
||
- **Mono**: Geist Mono, `--font-geist-mono` → `--font-mono`. Used for numeric
|
||
data cells only (prices, phone numbers, counts, dates in tables).
|
||
- **Scale conventions**:
|
||
- Page title: `text-2xl font-semibold tracking-tight`
|
||
- Page subtitle: `text-xs text-muted-foreground`
|
||
- Table header cells: `text-[11px] font-semibold uppercase tracking-wider text-muted-foreground`
|
||
- Table body: `text-sm`
|
||
- Badge/pill label: `text-[10px]`–`text-xs font-semibold uppercase tracking-wide`
|
||
|
||
## Color Tokens
|
||
|
||
Raw values live in `:root` (light) / `.dark` (dark) in `src/app/globals.css`
|
||
and are mapped to Tailwind utilities via `@theme inline`. Components must
|
||
consume the mapped utility, never the raw hex or a Tailwind palette shade.
|
||
|
||
| Utility | Light | Dark | Usage |
|
||
|---|---|---|---|
|
||
| `bg-background` / `text-foreground` | `#ffffff` / `#1a1a1a` | `#0e1512` / `#f2f4f3` | Page canvas |
|
||
| `bg-card` / `text-card-foreground` | `#ffffff` | `#131a16` | Cards, table, kanban cards, header bar |
|
||
| `bg-muted` / `text-muted-foreground` | `#f9f9f9` / `#71717a` | `#171f1b` / `#9aa39e` | Subtle backgrounds, secondary text, kanban columns |
|
||
| `bg-primary` / `text-primary-foreground` | `#1A463C` | `#3FA88C` | Primary actions, sidebar, active nav state |
|
||
| `bg-accent` | `#DEF168` | `#DEF168` | Rare highlight accent (lime) |
|
||
| `border-border` / `border-input` | `#e5e7eb` | `#26302b` | All hairline borders |
|
||
| `ring-ring` | `#1A463C` | `#3FA88C` | Focus rings |
|
||
| `bg-destructive` | `#ef4444` | `#f87171` | Destructive actions |
|
||
|
||
**Sidebar exception**: the sidebar stays brand green `bg-[#1A463C]` in both
|
||
themes (it is not a themed surface — it's the constant brand anchor).
|
||
|
||
**Status/semantic colors** (lead stages, badges) use Tailwind's default
|
||
palette (blue/purple/amber/orange/emerald/red) directly, each paired with an
|
||
explicit `dark:` variant for legibility on dark surfaces — see `StatusBadge`.
|
||
|
||
## Elevation & Radius
|
||
|
||
- `--radius: 0.5rem` (base) is wired into `@theme` as `--radius-lg` (`=
|
||
--radius`) and `--radius-xl` (`= --radius + 0.25rem`), so `rounded-lg` /
|
||
`rounded-xl` utilities resolve consistently off one token.
|
||
- `--shadow-card: 0 4px 20px rgba(0,0,0,0.01)` → `shadow-card` utility.
|
||
Default resting elevation for cards, table containers, kanban cards.
|
||
- `--shadow-card-hover: 0 8px 30px rgba(0,0,0,0.02)` → `shadow-card-hover`
|
||
utility. Applied on hover for interactive cards.
|
||
|
||
## Layout Conventions
|
||
|
||
- **Table container**: `bg-card rounded-xl border border-border shadow-card
|
||
overflow-hidden`.
|
||
- **Table header row**: `bg-muted/50 border-b border-border text-[11px]
|
||
uppercase tracking-wider text-muted-foreground`.
|
||
- **Table body rows**: `py-4 px-6`, `divide-y divide-border`,
|
||
`hover:bg-muted/40 transition-colors`.
|
||
- **Kanban column**: `bg-muted/60 rounded-xl border border-border p-4`.
|
||
- **Kanban card**: `bg-card rounded-lg border border-border shadow-sm
|
||
hover:border-primary/30 hover:shadow-card-hover transition-all`.
|
||
- **Page header**: title `text-2xl font-semibold tracking-tight
|
||
text-foreground`, subtitle `text-xs text-muted-foreground mt-1`, primary
|
||
action button `bg-primary text-primary-foreground hover:bg-primary/90`.
|
||
|
||
## Color/Class Migration Map (dual-theme principle)
|
||
|
||
When restyling any surface, replace hardcoded classes with token utilities:
|
||
|
||
| Old (hardcoded) | New (token) |
|
||
|---|---|
|
||
| `bg-white` | `bg-card` |
|
||
| `bg-slate-50` / `bg-gray-50` | `bg-muted` |
|
||
| `border-slate-100` / `border-slate-200` | `border-border` |
|
||
| `text-slate-900` / `text-[#1a1a1a]` | `text-foreground` |
|
||
| `text-slate-500` / `text-slate-400` / `text-[#71717a]` | `text-muted-foreground` |
|
||
| `bg-brand-dark` / `text-[#1A463C]` (as action color) | `bg-primary` / `text-primary` |
|
||
|
||
## Motion
|
||
|
||
- **Sidebar collapse**: `transition-[width] duration-350
|
||
ease-[cubic-bezier(0.4,0,0.2,1)]` on the `<aside>`; label/logo text use
|
||
`whitespace-nowrap transition-opacity duration-200` and fade to
|
||
`opacity-0` immediately on collapse, but only fade back in ~150ms after
|
||
the width transition starts on expand (avoids text reflow/wrap during the
|
||
animation).
|
||
- **Hover states**: `transition-colors duration-150`–`duration-200` on rows,
|
||
buttons, nav links.
|
||
- **Kanban drag**: dragged card renders in a `DragOverlay` with
|
||
`rotate-1 shadow-xl`; drop target column highlights via `border-primary
|
||
bg-primary/5`.
|
||
|
||
## UX Rules
|
||
|
||
1. Numeric/tabular data is always monospace and right-aligned in tables.
|
||
2. Every interactive control has a visible focus state (`focus:ring-1
|
||
focus:ring-ring focus:border-primary` pattern) for keyboard accessibility.
|
||
3. Status is always communicated redundantly — color + text label — never
|
||
color alone.
|
||
4. Destructive actions use `destructive` tokens, never ad-hoc red.
|
||
5. Empty states are muted, centered, and brief ("Nessun lead trovato").
|
||
6. Sidebar collapse state persists across page loads via `localStorage`
|
||
(`iamcavalli:sidebar`) and is restored before paint where possible to
|
||
avoid layout jump.
|
||
|
||
---
|
||
|
||
## Component Inventory
|
||
|
||
Primitives extracted from the Lead Pipeline redesign, intended for reuse
|
||
across all future admin pages.
|
||
|
||
| Component | Path | Purpose |
|
||
|---|---|---|
|
||
| `AdminShell` | `src/components/admin/AdminShell.tsx` | Client shell holding sidebar-collapsed state (persisted to `localStorage`), renders sidebar + top header + `<main>`. Wraps all `/admin/*` pages. |
|
||
| `AdminSidebar` | `src/components/admin/AdminSidebar.tsx` | Collapsible brand sidebar (`w-64` ↔ `w-20`), controlled by `AdminShell`. Nav items, theme toggle, sign-out. |
|
||
| `StatusBadge` | `src/components/ui/StatusBadge.tsx` | Rounded-full status pill with a color map per lead stage, each with a `dark:` variant. Replaces the old scattered `STAGE_COLOR` maps. |
|
||
| `SearchInput` | `src/components/ui/SearchInput.tsx` | Search-icon input, `rounded-lg border-border focus:ring-primary`. |
|
||
| `SegmentedToggle` | `src/components/ui/SegmentedToggle.tsx` | Generic Lista/Kanban-style segmented control (`bg-muted p-1 rounded-lg`, active option `bg-card shadow-sm`). |
|
||
| `PageHeader` | `src/components/admin/PageHeader.tsx` | Page title (`text-2xl tracking-tight`) + subtitle + action slot, token-based. |
|
||
| `LeadTable` | `src/components/admin/leads/LeadTable.tsx` | Luxury table restyle: `bg-card rounded-xl shadow-card`, uppercase muted headers, `hover:bg-muted/40` rows, uses `StatusBadge`. |
|
||
| `LeadsKanbanBoard` | `src/components/admin/leads/LeadsKanbanBoard.tsx` | Kanban restyle: `bg-muted/60` columns with count pills, `bg-card` cards with `hover:border-primary/30`. Uses `@dnd-kit`, keeps all 6 lead stages. |
|
||
| `LeadsViewToggle` | `src/components/admin/leads/LeadsViewToggle.tsx` | Wires `SearchInput` + `SegmentedToggle` together with the table/kanban views. |
|
||
| `MilestoneStepper` | `src/components/client/MilestoneStepper.tsx` | Client-portal horizontal milestone stepper: one node per real phase, connecting line filled by `global_progress_pct`. Done = filled `bg-primary` ✓, active = `border-primary` outline, upcoming = `bg-muted`. |
|
||
| `LeadDetail` | `src/components/admin/leads/LeadDetail.tsx` | Lead detail page (`/admin/pipeline/[id]`): bespoke header (name + inline `StatusBadge` + action bar), asymmetric `lg:grid-cols-3` layout (1/3 profile card w/ icon-chip rows + tags, 2/3 Note/Follow-up + unified timeline). |
|
||
| `ClientProfitability` | `src/components/admin/dashboard/ClientProfitability.tsx` | Dashboard widget: valore orario reale per cliente (`getClientProfitability` → contrattualizzato ÷ ore tracciate) con badge margine (Ottimo `bg-primary/10 text-primary` / In Linea `bg-muted`). |
|
||
| `YearSelector` | `src/components/admin/YearSelector.tsx` | Selettore anno restilizzato a pill (`rounded-full border-border bg-card shadow-card`), frecce ←/→, valore `font-mono`. Guida i dati year-scoped della dashboard via `?year=`. |
|
||
| `ConversationsView` | `src/components/admin/conversazioni/ConversationsView.tsx` | Inbox messaggi clienti (`/admin/conversazioni`) a due pannelli: lista conversazioni filtrabile (search su nome/brand/ultimo messaggio, pallino unread) + thread attivo con bolle messaggio (admin a destra `bg-primary`, cliente a sinistra), badge entità per messaggio (Generale/Fase/Task/Deliverable) e form di risposta. Auto-mark-read all'apertura. |
|
||
| `MessagesWidget` | `src/components/admin/dashboard/MessagesWidget.tsx` | Widget dashboard "Messaggi Clienti": chat clienti in attesa di risposta (`getConversations()` filtrato su `unread`), pill emerald "N Nuovi" + pallino pulsante, righe con anteprima e link `Rispondi →` deep-link a `/admin/conversazioni?c=<clientId>`. Empty state "Nessun messaggio in attesa ✓". |
|
||
| `CopyLinkButton` | `src/components/admin/CopyLinkButton.tsx` | Icon button che copia un URL assoluto (`window.location.origin + path`) negli appunti; swap icona → check emerald per 1.5s con tooltip "Copiato!". Usato nella lista Clienti per il link profilo pubblico. |
|
||
| `ClientRow` | `src/components/admin/ClientRow.tsx` | Riga tabella Clienti restilizzata Quiet Luxury: nome link → dettaglio + sottotitolo brand/progetti, colonne numeriche `font-mono` right-aligned (LTV, incassato come pill emerald, da saldare), cella "Link profilo" con pill mono troncata (apre portale in new tab) + `CopyLinkButton`. |
|
||
|
||
**Unified timeline pattern**: activities + transcripts merged into one
|
||
reverse-chronological "Storico delle Interazioni". Vertical connector = absolute
|
||
`w-px bg-border` at `left-[19px]` behind `w-10 h-10 rounded-full` nodes.
|
||
Transcript node is highlighted (`bg-primary text-primary-foreground`) and
|
||
expandable (`line-clamp-2` → "Mostra tutto/meno"); activity nodes are muted
|
||
(`bg-muted border-border`). Dates are `font-mono` — activities relative
|
||
(`formatDistanceToNow`), transcripts absolute (`d MMMM yyyy`).
|
||
|
||
### Admin Dashboard restyle notes
|
||
|
||
The `/admin` dashboard was migrated to "Quiet Luxury" (applied 2026-07-11),
|
||
replicating `design-reference/pagina-dashboard`. It is a condensed single-screen
|
||
layout: no in-`<main>` `PageHeader` (sidebar + shell header carry the chrome).
|
||
|
||
- **KPI strip**: 4 `bg-card` metric cards (Clienti Attivi · Contrattualizzato ·
|
||
Incassato Reale · Ore Tracciate). Value `text-2xl font-bold font-mono`, label
|
||
`text-[10px] uppercase text-muted-foreground`. Positive delta uses
|
||
`text-emerald-600 dark:text-emerald-400`.
|
||
- **Griglia `lg:grid-cols-3`**: 2/3 col = `ForecastChart` (istogramma flussi 12
|
||
mesi, mese prossimo evidenziato `bg-primary`) + `ClientProfitability`; 1/3 col =
|
||
`FollowUpWidget` (count pill amber) + `MessagesWidget` ("Messaggi Clienti", pill
|
||
emerald "N Nuovi" + pallino pulsante, chat clienti in attesa di risposta) +
|
||
`OffersSoldChart` ("Offerte Più Richieste").
|
||
- **Year selector** interattivo (`YearSelector`) in una toolbar top-right; governa
|
||
i KPI year-scoped + redditività. Il forecast è rolling-12-mesi (non year-scoped).
|
||
- Widget rimossi dal legacy: chart incassi mensili, card "Da incassare"/"Clienti
|
||
acquisiti", barre "Ore per cliente" (sostituite dalla redditività oraria).
|
||
|
||
### Conversazioni (inbox) notes
|
||
|
||
`/admin/conversazioni` è l'inbox unificata dei messaggi clienti (replica
|
||
`design-reference/pagina-conversazioni`). Ogni conversazione è **per cliente**:
|
||
raccoglie tutti i suoi commenti — `general` + quelli su fasi/task/deliverable —
|
||
in un unico thread ordinato, con badge entità per messaggio.
|
||
|
||
- **Fonte unread**: `clients.admin_last_read_at` confrontato con l'ultimo
|
||
messaggio autore `client`. Una conversazione è non letta se esiste un messaggio
|
||
cliente dopo `admin_last_read_at` (o se è `NULL`). Query in
|
||
`src/lib/conversations-queries.ts` (`getConversations`, `getConversationThread`,
|
||
`getUnreadConversationsCount`).
|
||
- **Badge sidebar**: voce "Conversazioni" (`AdminSidebar`) con pill emerald del
|
||
numero di clienti con non letti (pallino verde se collapsed), alimentato da
|
||
`getUnreadConversationsCount()` in `src/app/admin/layout.tsx`. Stessa fonte di
|
||
verità del `MessagesWidget` in dashboard.
|
||
- **Reply**: salvata come commento `general` sul cliente e aggiorna
|
||
`admin_last_read_at` (mark-read). L'apertura di una conversazione fa
|
||
auto-mark-read. Deep-link a un thread specifico via `?c=<clientId>`.
|
||
|
||
### Clienti (lista) notes
|
||
|
||
`/admin/clients` migrata a "Quiet Luxury" (replica `design-reference/pagina-clienti`).
|
||
Tabella `bg-card rounded-xl border-border shadow-card` con header uppercase muted e
|
||
righe `py-4 px-6` / `divide-y divide-border` / `hover:bg-muted/40`.
|
||
|
||
- **Colonne**: Cliente (nome link → `/admin/clients/[id]` + sottotitolo
|
||
brand/progetti) a sinistra; LTV, Importo incassato, Importo da saldare, Link
|
||
profilo tutte right-aligned. Valori monetari `font-mono`; "incassato" reso come
|
||
pill emerald (`bg-emerald-50 text-emerald-700` + variante dark), zero → `—` muted.
|
||
- **Link profilo**: pill mono troncata (`/client/<slug|token>…`) che apre il portale
|
||
in new tab + `CopyLinkButton` (copia URL assoluto).
|
||
- **Header actions**: link testuale "Mostra/Nascondi archiviati" (`?archived=1`) +
|
||
Button primario "Nuovo cliente". Footer tabella "Mostrando N clienti attivi"
|
||
(singolare/plurale gestiti).
|
||
- Le righe archiviate restano `opacity-60` con pill "Archiviato".
|
||
|
||
### Offerte (lista) notes
|
||
|
||
`/admin/offers` migrata a "Quiet Luxury" (replica `design-reference/pagina-offerte`).
|
||
Griglia responsive di card `bg-card rounded-xl border-border p-6 shadow-card`
|
||
(`hover:shadow-card-hover`), `md:grid-cols-2 lg:grid-cols-3`.
|
||
|
||
- **Header**: `PageHeader` "Offerte" + sottotitolo, azione "+ Nuova Offerta"
|
||
(`Button` primario) che espande un form inline (`Input` nome + "Crea").
|
||
- **Filtri**: pill categoria rettangolari (`rounded-lg px-4 py-2`) — attiva
|
||
`bg-primary text-primary-foreground`, inattiva `border-border bg-card
|
||
text-muted-foreground hover:bg-muted`. "Tutti" + `categoryOptions` dinamiche.
|
||
A destra checkbox "Mostra offerte archiviate".
|
||
- **Card**: nome interno + descrizione muted + badge categoria colorato per tipo
|
||
(Retainer→blue, Entry→purple, Signature→amber, tutti con variante dark) via
|
||
helper `categoryBadgeClass`. Le archiviate sono `opacity-60` con pill "Archiviata".
|
||
- **Tabella tier**: `border-border rounded-lg`, header uppercase muted
|
||
(Tier · Servizi · Pubblico), righe `font-mono` `divide-y divide-border`; solo i
|
||
tier con `servicesTotal > 0` o `public_price` valorizzato; "Pubblico" assente → `—`.
|
||
|
||
### Client Portal restyle notes
|
||
|
||
The `/client/[token]` portal was migrated to the same "Quiet Luxury" tokens
|
||
(applied 2026-07-10). Key conventions specific to the client-facing surface:
|
||
|
||
- **Header**: `bg-card` sticky bar, three zones — `iamcavalli | Client Portal`
|
||
(left), brand name centered, "Area Riservata Protetta" emerald pill (right).
|
||
- **Status pills** (phases, payments) use soft tints, not solid fills:
|
||
emerald-50/700 (done/saldato), amber-50/700 (in corso/da saldare),
|
||
`bg-muted`/`text-muted-foreground` (upcoming) — each with a `dark:` variant.
|
||
- **Phase cards** (`PhaseCard`): `rounded-xl border-border-light bg-card
|
||
shadow-card`, progress bar colored per status (emerald/amber/`bg-border`).
|
||
- Sidebar cards (`OffersSection`, `PaymentStatus`, `DocumentsSection`,
|
||
`NotesSection`, `TranscriptsSection`) all follow `rounded-xl border-border-light
|
||
bg-card shadow-card`.
|
||
- `ClientDashboard` takes an `embedded` prop: when rendered inside the
|
||
multi-project tabs wrapper (`page.tsx`), it drops its own header/footer/canvas
|
||
so the page-level chrome isn't duplicated.
|