FollowQue component system

1 · Icon library

Family

lucide-react — the only approved icon source. No second library, ever.

Style

Outline only. No filled, duotone, brand-colour, or 3D variants.

Stroke width

1.9px default · 2.4px for the active tab and other selected chrome

Geometry

24px source grid, 2px rounded caps and joins, ~2px corner radius

• One glyph carries one meaning across the whole product; never reuse a glyph for a second concept.
• Silhouette does the work. Every icon must stay readable at 13px in greyscale.
• Icons support the label, they do not replace it — except in dense chrome where the control is already familiar (back, more, close).
• No robot, brain, chip, or spark-burst imagery. AI is one small sparkle, nothing else.
• Weight, not fill, signals emphasis: an active tab thickens its stroke instead of switching to a solid variant.

2 · Size matrix

3 · Placement & spacing

Buttons

16px leading icon, 6px gap to the label, optical -1px left nudge. Icon-only buttons are 20px inside a 32×32 (or 40×40 primary) target.

Navigation

20px, stacked above the tab label with a 3px gap. Active state thickens the stroke to 2.4 and switches colour to the primary token; the glyph never changes shape.

Cards

16px in the meta row, 6px gap, vertically centred to the cap height of the 12.5px meta text. Maximum two glyphs per card so a list of eight cards stays quiet.

Badges

13px, stroke 1.9, -2px left nudge inside the pill, 6px gap to the status word. Always aria-hidden; the word is the label.

Inputs

16px adornment inset 10px from the field edge, muted-foreground. Never place icons on both sides of one field.

Empty states

24px centred in a 44px rounded tile at 12% accent tint, 12px above the headline. Exactly one glyph per empty state.

Toasts

16px leading, aligned to the first text line (not centred vertically), 8px gap. Loading uses the spinner; success, warning, and error use their semantic glyph.

Menus

16px leading, 10px gap, one column of glyphs so labels align. Trailing chevrons only where the item opens a submenu.

Tabs

Icons in tabs are mandatory or absent per group — never mixed inside one tab bar.

5 · Colour rules

Icons inherit currentColor. Never pass a color prop or a hex value — colour comes from the parent's text token so light and dark both resolve for free.

6 · Accessibility checklist

• ✓Decorative icons — Any glyph paired with visible text is decorative: aria-hidden="true" and focusable="false". A status badge announces "Hot", never "Flame, Hot".
• ✓Informative icons — An icon that is the only carrier of meaning needs a text alternative on the nearest interactive or semantic element — aria-label on a button, or a visually hidden span.
• ✓Required labels — Every icon-only control carries an aria-label written as the action ("Snooze follow-up"), not the glyph ("clock").
• ✓Screen readers — Never announce state through a glyph alone. Loading uses aria-busy plus a live region; success uses the toast text, not the check.
• ✓Touch targets — Minimum 32×32px, 40×40px for primary and nav targets, with ≥8px between adjacent targets — the glyph stays 16–20px inside that box.
• ✓Contrast — Icons are non-text UI: ≥3:1 against their background, and ≥4.5:1 when they act as text (a glyph replacing a word). Verified by the dev Contrast Audit in both themes.

7 · Chrome side-panel guidelines

• 400px wide: one glyph per row of chrome. If a row needs three, the row is doing too much.
• Density budget — at most six icons visible in a single viewport of the scroll region, excluding the fixed nav.
• Recognition beats novelty: reuse the glyph the user already learned elsewhere in the panel rather than a more literal one.
• Never use an icon purely for decoration inside a card; empty states are the only illustrative surface.
• Consistent spacing: 6px icon↔label inline, 8px in toasts, 10px in menus. These three numbers cover every case.
• At narrow widths, labels truncate before icons shrink — a 16px glyph next to a truncated label still reads faster than a 12px one next to full text.
• Icons never wrap to their own line; a glyph and its label are one flex row with shrink-0 on the glyph.

8 · Usage examples

<Btn><CloudUpload size={16} aria-hidden /> Sync to GoHighLevel</Btn>

<Btn><CloudUpload size={20} color="#2F6F6A" /> <span>Save</span> <ChevronRight /></Btn>

<MenuItem icon={<Clock size={16} aria-hidden />}>Snooze 3 days</MenuItem>

<MenuItem>⏰ Snooze 3 days</MenuItem>  // emoji, no token colour, no size control

<span className="flex items-center gap-1.5 text-muted-foreground">
  <CalendarClock size={16} aria-hidden /> Due tomorrow
</span>

<CalendarClock size={16} className="text-warning" /> // colour reserved for real warnings

<Toast tone="success" icon={<CheckCircle2 size={16} aria-hidden />}>Lead captured</Toast>

<Toast tone="success" icon={<PartyPopper size={24} />}>Lead captured 🎉</Toast>

<StatusBadge status="Hot" /> // glyph aria-hidden, word is the accessible name

<span className="text-danger"><Flame aria-label="Hot" /></span> // colour-only + doubled name

<Empty spec={emptyStates.inboxZero} /> // one 24px glyph in a tinted tile

<img src="/illustration-robot.png" /> // no mascots, no raster art, no second library

<Tab icon={<Home size={20} strokeWidth={active ? 2.4 : 1.9} aria-hidden />} label="Today" />

<Tab icon={active ? <HomeFilled /> : <Home />} /> // fill switch = second vocabulary

9 · Common mistakes to avoid

• Introducing a second icon library (Heroicons, Font Awesome, Material) for one missing glyph — compose from Lucide or use a word.
• Emoji as an icon. They render differently on every OS and defeat token colour.
• Colouring a glyph outside the five feedback tones, or tinting an icon to make a card look livelier.
• aria-label on a glyph that already sits next to its word — screen readers then read it twice.
• Filled variants for active states instead of the 2.4 stroke.
• Two glyphs for one meaning (CalendarDays and CalendarClock both used for follow-up).
• Shrinking a glyph below 12px to fit a tight row; remove the glyph instead.
• Vendor logos for Facebook or GoHighLevel inside the panel — the neutral ScanLine and PlugZap glyphs are the approved stand-ins.
• Spinners in place of skeletons for content loading; spinners belong inside a control only.

Props

TypeScript interface

type BtnVariant = "primary" | "secondary" | "ghost" | "soft" | "danger";
type BtnSize = "sm" | "md" | "lg" | "icon";

export interface BtnProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: BtnVariant; // default "secondary"
  size?: BtnSize;       // default "md"
  full?: boolean;       // default false
}

Example usage

<Btn variant="primary" size="lg" full onClick={generate}>
  <Sparkles size={15} /> Generate replies
</Btn>
<Btn variant="ghost" size="sm" onClick={snooze}>
  <Moon size={13} /> Snooze
</Btn>

Chrome side-panel constraints

• At 400px, two side-by-side buttons max; three only at size="sm" with icon + one word.
• Commit actions sit at the end of the scroll flow, not fixed — the bottom nav already owns that edge.

Props

TypeScript interface

export type LeadStatus = "Hot" | "Warm" | "Cold" | "Waiting" | "Won";

export interface StatusBadgeProps {
  status: LeadStatus;
  muted?: boolean;
  className?: string;
}

// One glyph per status, used by every surface. Never import an icon
// for a status directly — always read it from this registry.
export const statusIcons: Record<LeadStatus, { icon: LucideIcon; meaning: string }> = {
  Hot:     { icon: Flame,       meaning: "active buying intent" },
  Warm:    { icon: TrendingUp,  meaning: "engaged, moving forward" },
  Cold:    { icon: Snowflake,   meaning: "gone quiet" },
  Waiting: { icon: Clock,       meaning: "ball in their court" },
  Won:     { icon: CheckCircle2,meaning: "closed" },
};

export const STATUS_ICON_SIZE = 13;
export const STATUS_ICON_STROKE = 1.9;

Status mappings

Hot

Flame · bg-hot-soft / text-hot / border-hot/25 — buying signal, deserves emphasis

Warm

TrendingUp · bg-warm-soft / text-warm — engaged, no urgency

Cold

Snowflake · bg-cold-soft / text-cold — dormant, quiet by design

Waiting

Clock · bg-waiting-soft / text-waiting — ball in their court

Won

CheckCircle2 · bg-won-soft / text-won — closed, also the success tint

Example usage

<StatusBadge status={lead.status} />

Chrome side-panel constraints

• Right-aligned in a flex row with `min-w-0` on the name so long names truncate, badge never wraps.
• Icon adds ~19px to the pill. Verified at 320px, 400px and 480px panel widths — the name truncates first, the badge never wraps or clips.
• Surfaces audited for one consistent glyph: Today (hot list, overdue, lead rows), Queue, conversation detail and its status picker, Capture picker, search results, AI summary header and the GoHighLevel sync preview Status row.
• Do not add a status glyph to semantic feedback (alerts, toasts, sync success/failure) — those keep their own icons so a badge is never confused with a system message.

Props

TypeScript interface

export interface FieldProps {
  label: string;
  hint?: string;
  detected?: boolean;
  children: ReactNode;
}

export type TextInputProps = InputHTMLAttributes<HTMLInputElement>;
export type TextAreaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;

Example usage

<Field label="Phone" detected hint="Read from her Messenger profile">
  <TextInput value={phone} onChange={(e) => setPhone(e.target.value)} inputMode="tel" />
</Field>

<Field label="Context note">
  <TextArea rows={4} value={note} onChange={(e) => setNote(e.target.value)} />
</Field>

Chrome side-panel constraints

• One column always — never place two fields side by side at 400px.
• Keyboard overlay is not a concern in a side panel, but keep forms under ~7 fields per screen.

Props

TypeScript interface

export type SelectProps = SelectHTMLAttributes<HTMLSelectElement>;

Example usage

<Field label="Reply tone">
  <Select value={tone} onChange={(e) => setTone(e.target.value)}>
    <option value="direct">Direct</option>
    <option value="consultative">Consultative</option>
  </Select>
</Field>

Chrome side-panel constraints

• Prefer Select over a custom popover: a custom listbox inside a 400px panel clips or needs a portal.
• Above ~8 options, use SearchInput + ListRow instead.

Props

TypeScript interface

export interface CheckboxProps {
  checked: boolean;
  onChange: (v: boolean) => void;
  label: string;
}

export interface ToggleProps extends CheckboxProps {
  description?: string;
}

export interface RadioGroupProps<T extends string> {
  value: T;
  onChange: (v: T) => void;
  options: { value: T; label: string; description?: string }[];
}

Example usage

<Toggle
  checked={overdueAlerts}
  onChange={setOverdueAlerts}
  label="Overdue follow-ups"
  description="Premium white label"
/>

<RadioGroup
  value={style}
  onChange={setStyle}
  options={[{ value: "direct", label: "Direct", description: "Answers, then asks." }]}
/>

Chrome side-panel constraints

• Full-width rows with the control on the right read best at 400px; never inline-wrap a control mid-sentence.

Props

TypeScript interface

export type SearchInputProps = InputHTMLAttributes<HTMLInputElement>;

export interface ChipProps {
  children: ReactNode;
  onClick?: () => void;
  className?: string;
}

export interface AvatarProps {
  initials: string;
  size?: "sm" | "md" | "lg"; // default "md"
  status?: LeadStatus;
}

Example usage

<SearchInput placeholder="Search leads" value={q} onChange={(e) => setQ(e.target.value)} />
<Avatar initials={lead.initials} size="sm" status={lead.status} />
<Chip>{tag}</Chip>

Chrome side-panel constraints

• Avatars stay initials-only — no remote Facebook avatars, which avoids CSP and privacy issues in MV3.

Props

TypeScript interface

export interface TabsProps<T extends string> {
  value: T;
  onChange: (v: T) => void;
  items: readonly { id: T; label: string }[];
  variant?: "segmented" | "rail"; // default "segmented"
}

Status mappings

Queue rail

All · Overdue · Today · Upcoming · Waiting for Reply · Completed

Replies segmented

Direct · Consultative · Friendly

Example usage

const styles = [
  { id: "Direct", label: "Direct" },
  { id: "Consultative", label: "Consultative" },
  { id: "Friendly", label: "Friendly" },
] as const;

<Tabs value={style} onChange={setStyle} items={styles} />

Chrome side-panel constraints

• Never exceed three segments at 400px — a fourth truncates the label.
• Rails must bleed to the panel edge (-mx-4 px-4) so the last chip reads as scrollable.

Props

TypeScript interface

function StatusBadge(props: {
  status: LeadStatus;
  muted?: boolean;
  className?: string;
}): JSX.Element;

const STATUS_ICON_SIZE = 13;   // px, all five statuses
const STATUS_ICON_STROKE = 1.9; // consistent visual weight

Status mappings

Minimum badge size

20px tall × 53.5px wide (Hot / Won), 73.8px wide (Waiting) at 320px

Height

20px fixed (h-5) — identical for all five statuses at 320, 400 and 480px

Icon size

13 × 13px, shrink-0 — never scales between statuses

Stroke width

1.9

Icon-to-label gap

6px (gap-1.5), plus a -2px optical inset on the icon

Padding

8px horizontal; vertical padding replaced by the fixed 20px height for exact baseline parity

Radius

Full pill

Typography

11px / 600 weight / leading-none

Alignment

Icon centre is 0.0px from badge centre in every status at every tested width

Supported widths

320px (minimum), 400px (default), 480px

Example usage

<StatusBadge status="Waiting" />

// Compact row pattern — text yields, badge does not
<div className="flex min-w-0 items-center gap-2">
  <p className="truncate text-[13.5px] font-semibold">{lead.name}</p>
  <StatusBadge status={lead.status} />
</div>

Chrome side-panel constraints

• Verified at 320 / 400 / 480px in light and dark: badge height 20px, icon 13px, gap 6px, padding 8px and 0.0px icon-centre offset in every instance — zero variance across statuses, widths, themes and views.
• Covered surfaces: lead-card headers (Today), Follow-Up queue rows, conversation rows, search results, lead-detail metadata, AI summary cards, GoHighLevel sync previews and the /components and /design-system compact examples.
• No wrapping, clipping or badge-driven overflow found. The only horizontal scroll at 320px is the intentional filter-chip rail.
• Clutter reduced instead of badges: the queue row action bar (Complete · Snooze · Reschedule) became an even three-column grid with tighter icon gaps, so its labels fit at 320px without touching badge geometry.
• Greyscale and colour-blind simulation confirm all five statuses stay distinguishable by glyph and word alone.
• Visual-regression snapshots for the 320px compact layouts live in tests/a11y/status-badge-320.spec.ts.

Props

TypeScript interface

// src/lib/follow-up-date.ts
export function formatFollowUpDate(iso: string): string;  // "Tuesday, August 11"
export function formatFollowUpFull(iso: string): string;  // "Tuesday, August 11, 2026"
export function formatFollowUpLine(iso: string): string;  // "Today · Monday, August 3"
export function followUpRelative(iso: string): string | null;
export function followUpAria(iso: string, prefix?: string): string;

Status mappings

Lead card / queue row

formatFollowUpLine(lead.followUpDate)

Date-picker trigger & presets

formatFollowUpDate(iso) + followUpAria(iso)

Toast / undo confirmation

`Follow-up moved to ${formatFollowUpDate(iso)}`

Sync summary & checklist

formatFollowUpDate(iso); spoken details use formatFollowUpFull(iso)

Screen-reader label

followUpAria(iso) — always the full date with year

Example usage

import { formatFollowUpDate, formatFollowUpLine, followUpAria } from "@/lib/snooze";

<p className="truncate">
  <span aria-hidden>{formatFollowUpLine(lead.followUpDate)}</span>
  <span className="sr-only">{followUpAria(lead.followUpDate)}</span>
</p>

updateUndoable(lead.id, { followUpDate: iso, due: formatFollowUpLine(iso) },
  `Follow-up moved to ${formatFollowUpDate(iso)}`);

Chrome side-panel constraints

• Banned in product copy and mock data: 'Tue', '8/11', 'Aug 11th', bare 'Tomorrow', and any time-of-day. FollowQue schedules days, not appointments.
• Locale-aware: toLocaleDateString(undefined, { weekday: 'long', month: 'long', day: 'numeric' }) keeps weekday–month–day clarity wherever the user is.
• The longest realistic string, 'Wednesday, September 24', fits the 400px panel at every documented size; do not add time or year suffixes by hand.

Props

TypeScript interface

export interface CardProps {
  children: ReactNode;
  tone?: "default" | "alert" | "success"; // default "default"
  interactive?: boolean;                  // default false
  onClick?: () => void;
  className?: string;
}

Example usage

<Card interactive onClick={() => openLead(lead.id)}>…</Card>
<Card tone="alert">…</Card>

Chrome side-panel constraints

• Cards are edge-to-edge inside px-4 gutters; vertical rhythm is space-y-2 in lists, space-y-5 between sections.

Props

TypeScript interface

export interface LeadCardProps {
  lead: Lead;
  note?: string;
  onOpen: (id: string) => void;
}

Status mappings

lead.status

→ StatusBadge + Avatar dot

lead.bucket === 'Overdue'

→ Card tone="alert"

lead.due

→ mono meta line, verbatim from the record

Example usage

<Card interactive onClick={() => onOpen(lead.id)} className="mb-2">
  <div className="flex items-start gap-3">
    <Avatar initials={lead.initials} status={lead.status} />
    <div className="min-w-0 flex-1">
      <div className="flex items-center justify-between gap-2">
        <p className="truncate text-[14px] font-semibold">{lead.name}</p>
        <StatusBadge status={lead.status} />
      </div>
      <p className="mt-0.5 truncate text-[12px] text-muted-foreground">{lead.business}</p>
      <p className="mt-2 line-clamp-2 text-[12px] text-foreground/80">{note ?? lead.dueNote}</p>
      <p className="mt-2 font-mono text-[10px] uppercase tracking-[0.12em] text-muted-foreground">{lead.due}</p>
    </div>
  </div>
</Card>

Chrome side-panel constraints

• Max four visible lines of text — anything longer belongs in the conversation view.
• No horizontal swipe actions: the panel shares gestures with the Facebook page beneath it.

Props

TypeScript interface

export interface ConversationCardProps {
  lead: Lead;
  onStatusChange: (status: LeadStatus) => void;
}

Status mappings

lead.status

→ selected pill, Avatar dot, and downstream queue emphasis

Example usage

<Card>
  <div className="flex items-start gap-3">
    <Avatar initials={lead.initials} size="lg" status={lead.status} />
    <div className="min-w-0">
      <h2 className="text-[18px] font-bold">{lead.name}</h2>
      <p className="text-[12px] text-muted-foreground">{lead.business}</p>
    </div>
  </div>
</Card>

Chrome side-panel constraints

• The five status pills wrap to two rows at 400px — that is the accepted layout, do not shrink the labels.

Props

TypeScript interface

export type QueueBucket =
  | "Overdue" | "Today" | "Upcoming" | "Waiting for Reply" | "Completed";

export interface FollowUpCardProps {
  lead: Lead;
  bucket: QueueBucket;
  onOpen: (id: string) => void;
  onComplete: (id: string) => void;
  onReschedule: (id: string) => void;
}

Status mappings

Overdue

hot emphasis — the loudest bucket in the product

Today

neutral, primary-tinted count

Upcoming

quiet, mono date

Waiting for Reply

waiting colour, no actions encouraged

Completed

won colour, muted, read-only

Example usage

<Card className="p-3">
  <button onClick={() => onOpen(lead.id)} className="flex w-full items-start gap-3 text-left">…</button>
  {bucket !== "Completed" && (
    <div className="mt-2.5 flex gap-1.5 border-t border-border pt-2.5">
      <Btn variant="ghost" size="sm" full onClick={() => onComplete(lead.id)}><Check size={13} /> Complete</Btn>
      <Btn variant="ghost" size="sm" full onClick={() => setSnoozeFor(lead.id)}><Moon size={13} /> Snooze</Btn>
      <Btn variant="ghost" size="sm" full onClick={() => onReschedule(lead.id)}><Clock3 size={13} /> Today</Btn>
    </div>
  )}
</Card>

Chrome side-panel constraints

• Three sm ghost buttons is the hard limit for a 400px action row.
• Buckets render as sections with SectionHeader + count, so a single scroll shows the whole day.

Props

TypeScript interface

export interface AISummaryCardProps {
  summary: string;
  facts: string[];
  objection?: string;
  nextAction: string;
  loading?: boolean; // default false
}

Example usage

<Card>
  <Eyebrow>AI summary</Eyebrow>
  {loading ? (
    <div className="mt-2 space-y-2">
      <Skeleton /><Skeleton className="w-[90%]" /><Skeleton className="w-[65%]" />
    </div>
  ) : (
    <p className="mt-2 text-[12.5px] leading-relaxed">{summary}</p>
  )}
</Card>

Chrome side-panel constraints

• Cap facts at five; at 400px a sixth pushes the recommended action below the fold.
• Generation is one of the five moments allowed strong emphasis — but only through the primary button and the loading line, never a glow.

Props

TypeScript interface

export type ReplyStyle = "Direct" | "Consultative" | "Friendly";

export interface ReplySuggestionCardProps {
  style: ReplyStyle;
  text: string;
  onChange: (v: string) => void;
  onCopy: () => void;
  editing?: boolean; // default false
  loading?: boolean; // default false
}

Status mappings

Direct

Short, answers the question, asks for the next step.

Consultative

Leads with their context, then proposes a next step.

Friendly

Warm and casual, low pressure.

Example usage

<Card>
  <p className="text-[11.5px] text-muted-foreground">{styleBlurb[style]}</p>
  {editing
    ? <TextArea rows={6} value={text} onChange={(e) => onChange(e.target.value)} className="mt-2" />
    : <p className="mt-2 whitespace-pre-line text-[13px] leading-relaxed">{text}</p>}
  <div className="mt-3 flex gap-1.5 border-t border-border pt-3">
    <Btn variant="ghost" size="sm" full onClick={() => setEditing(!editing)}><Pencil size={13} /> Edit</Btn>
    <Btn variant="secondary" size="sm" full onClick={onCopy}><Copy size={13} /> Copy</Btn>
  </div>
</Card>

Chrome side-panel constraints

• Never auto-focus the TextArea: focus stealing inside a side panel interrupts typing in the Facebook composer.
• Clipboard write must be triggered by the user gesture — MV3 blocks deferred clipboard access.

Props

TypeScript interface

export type SyncMatch =
  | { kind: "new" }
  | { kind: "existing"; name: string; company?: string; hint?: string };

export interface SyncPreviewProps {
  match: SyncMatch;
  actions: string[];
  className?: string;
}

Status mappings

kind: 'new'

primary tile + create sentence

kind: 'existing'

neutral tile + matched identity

actions[]

success check per line — what will change, in the user's words

Example usage

<SyncPreview
  match={{ kind: "existing", name: "Maya Okafor", company: "Okafor Creative" }}
  actions={["Update phone", "Update notes", "Add Facebook profile", "Create follow-up task"]}
/>

Chrome side-panel constraints

• Sits directly above the Sync button so the decision and the commit are on one screen at 400px.
• Keep actions to four lines; more suggests configuration, which this component deliberately refuses.

Props

TypeScript interface

export interface SyncFailureSpec {
  id: "connection" | "timeout" | "permission" | "signedOut" | "unknown";
  label: string;      // mono chip: "Didn't complete"
  title: string;      // what happened
  body: string;       // what is safe / what did not change
  notDone: string[];  // the steps that did not complete
  next: string;       // what to do now
  details?: string[]; // ONLY when real diagnostics exist
  retryable: boolean; // false => retry can't help yet
}

export interface SyncFailureProps {
  spec: SyncFailureSpec;
  attempt: number;
  retrying: boolean;
  onRetry: () => void;
  onClose: () => void;
  onGetHelp: () => void;
  diagnostics: SyncDiagnostics | null;   // null => no drawer offered
}

Status mappings

connection

First failure — 'We couldn't finish saving to GoHighLevel'. Retryable. Drawer available (temporary).

timeout

Repeat failure — 'GoHighLevel is taking longer than usual'. Retryable. Drawer available (temporary).

permission

Account can't add contacts. Not retryable → primary becomes 'Fix this in Settings'. Drawer available (needs you).

signedOut

Sign-in expired. Not retryable → reconnect in Settings. Drawer available (needs you).

unknown

Fallback. Retryable, and buildSyncDiagnostics returns null — no drawer, because we would have nothing honest to put in it.

Example usage

const [state, setState] = useState<"ready" | "syncing" | "synced" | "failed">("ready");
const [attempt, setAttempt] = useState(0);
const [retrying, setRetrying] = useState(false);
const saveRef = useRef<HTMLButtonElement>(null);

{state === "failed" && (
  <SyncFailure
    spec={failureForAttempt(attempt)}
    attempt={attempt}
    retrying={retrying}
    onRetry={() => {
      if (retrying) return;              // no duplicate submissions
      setAttempt((a) => a + 1);
      setRetrying(true);                 // loading state, card stays put
    }}
    onClose={() => {
      returnFocus.current = true;        // focus back to the save button
      setState("ready");
    }}
    onGetHelp={() => go("settings")}
    diagnostics={buildSyncDiagnostics({
      spec: failureForAttempt(attempt),
      contactName: name,
      companyName: company,
      attemptedAt: attemptedAt.current,
      attempt,
    })}                                  // null => no "Review sync details"
  />
)}

Chrome side-panel constraints

• Copy standard: one calm sentence for what happened, one for what is safe, a short list for what didn't complete, one sentence for the next move. No status codes, no 'error', no 'failed request', no blame.
• Every failure ends with 'Prototype simulation — no live GoHighLevel data was modified.' Success never claims a live change either.
• 'Review sync details' is conditional. If buildSyncDiagnostics can't name the failed step and what did or didn't complete, the button does not exist — an empty diagnostics panel erodes trust faster than no panel.
• When the drawer does open, it always describes the simulation in the negative and ends with the prototype notice, so it can never be misread as a record of live CRM changes.
• Recovery flow: ready → saving → failure (announce + focus heading) → Retry (loading, same card) → success card, or → next failure spec in the same card. Close returns to ready with focus restored.
• Failure is outside the emphasis budget's celebration rules but inside its attention rules: it may use danger tint once, at one card, at one moment.

Props

TypeScript interface

export const saveFocusKey = (leadId: string) => `save-crm:${leadId}`;

export function restoreFocus(
  key: string,
  opts?: {
    onFallback?: (message: string) => void;
    label?: string;
    scope?: HTMLElement | null;
    waitFor?: number;   // default 600ms
  },
): () => void;   // cancel

Status mappings

Exact control found

focus moves silently — nothing is announced

Control present but disabled

polled for up to 600ms, then focused — still silent

Control gone

nearest action focused + one role="status" sentence

Error text after close

never re-announced; the role="alert" card is unmounted

Example usage

const saveKey = saveFocusKey(lead.id);

useEffect(() => {
  if (state !== "ready" || !returnFocus.current) return;
  returnFocus.current = false;
  return restoreFocus(saveKey, {
    label: "Sync to GoHighLevel",
    scope: screenRef.current,
    onFallback: setFocusFallback,   // rendered in a role="status" region
  });
}, [state, saveKey]);

<Btn data-focus-key={saveKey} …>Sync to GoHighLevel</Btn>
<BackLink focusFallback={`the back link for ${lead.name}`} … />

Chrome side-panel constraints

• Verified with keyboard only, in light, dark and reduced-motion: trigger the failure from a lead's Save button, dismiss with the Close control and again with Escape — focus returns to data-focus-key="save-crm:tomas" both times, with a visible 2px ring, no leftover alert, no duplicate Save control, and an unchanged scroll offset.
• Fallback verified by removing the Save control during the close: focus lands on the back link and the status region reads the single fallback sentence.
• Duplicate-dismissal verified: two Escape presses in a row produce one focus move and no announcement.

Props

TypeScript interface

export interface SyncSuccessProps {
  headline: string;
  subline?: string;
  checklist: string[];
  details?: string[];
  onDone: () => void;
  onOpenCrm: () => void;
}

Status mappings

role="status" aria-live="polite"

Success. Polite: it waits for the current utterance to finish and never interrupts typing.

role="alert" (SyncFailure)

Failure only. Assertive interruption is reserved for outcomes that need an immediate decision.

aria-busy on the save button

In-flight. The button stays mounted with aria-disabled instead of disabled, so focus is never stolen by the browser.

Example usage

{state === "synced" && (
  <SyncSuccess
    headline="Synced to GoHighLevel"
    subline={`${lead.name} · ${company}`}
    checklist={syncedChecklist}          // same array feeds the announcement
    details={[`contact: matched by email`]}
    onDone={back}
    onOpenCrm={() => notify("This would open GoHighLevel")}
  />
)}

// Trigger stays mounted while saving so focus is never lost:
<Btn
  ref={saveRef}
  aria-disabled={state === "syncing"}
  aria-busy={state === "syncing"}
  onClick={() => { if (state !== "syncing") setState("syncing"); }}
/>

Chrome side-panel constraints

• Polite for success, assertive for failure. That split is the whole announcement policy — do not escalate a success to role="alert".
• Never announce a prototype simulation as a real CRM change. The simulation sentence is part of the announcement, not just the visuals.
• If this state ever becomes a modal or sheet rather than an inline card, the rule flips: move initial focus to the heading or the 'Done' action, trap focus inside, and return focus to the trigger on close.
• One announcement per outcome. Toasts fire separately and are polite too — success is never spoken twice by two regions saying the same thing.

Props

TypeScript interface

export interface AiFailureSpec {
  id: "failed" | "timeout" | "unavailable" | "rateLimit" | "emptyResponse";
  label: string;   // mono chip: "Took too long"
  shape: "clock" | "alert" | "cloud" | "pause" | "blank";
  title: string;   // what happened
  safe: string;    // what is still here
  next: string;    // what to do now
  details?: string[]; // ONLY when real diagnostics exist
  retryable: boolean;
}

export interface AiFailureProps {
  spec: AiFailureSpec;
  attempt: number;
  retrying: boolean;
  replacesView?: boolean;
  onRetry: () => void;
  onEditManually: () => void;
  onClose: () => void;
}

Status mappings

timeout

First simulated failure — 'Writing a reply is taking longer than expected'. Retryable, with diagnostics.

failed

'We couldn't write a reply just now'. Retryable, no diagnostics.

unavailable

'Reply drafting is unavailable for a moment' — explicitly our side, not theirs.

rateLimit

'You've asked for a lot of drafts in a short time'. retryable: false, so retry is disabled for about a minute.

emptyResponse

'We didn't get a usable reply back'. Retryable, no diagnostics.

Example usage

{phase === "failed" && (
  <AiFailure
    spec={aiFailures[failure]}
    attempt={attempt}
    retrying={retrying}
    onRetry={() => generate({ retry: true })}
    onEditManually={() => setPhase("manual")}
    onClose={back}
  />
)}

// Duplicate requests are impossible:
const generate = (opts = {}) => {
  if (inFlight.current) return;
  inFlight.current = true;
  ...
};

Chrome side-panel constraints

• Copy standard: what happened, then 'nothing has been lost', then what to do next. Never blame the person, never name a provider, never show an error code.
• 'View details' appears only where genuine diagnostics exist. No details, no disclosure.
• A manual draft is never overwritten. A successful regeneration replaces the text only when the person hasn't typed; otherwise their words stay and a toast confirms it.
• Prototype wording is explicit — 'these drafts are sample copy, so no live service is involved' — so nobody reads a simulated timeout as a real outage.
• The prototype scenario picker at the bottom of Reply suggestions is a simulation control and must not ship in the extension.

Props

TypeScript interface

export type StepOutcome = "completed" | "notCompleted" | "unknown";

export interface DetailStep {
  label: string;      // "Contact match"
  outcome: StepOutcome;
  meaning: string;    // one sentence, in the person's language
}

export interface DetailFact {
  label: string;      // "Saved"
  value: string;      // "Today at 4:12 PM"
  meaning: string;
}

export interface SyncDetailsModel {
  tone: "success" | "failure";
  statusLine: string;      // the heading, in words
  stoppedAt?: string;      // failure only
  facts: DetailFact[];
  steps: DetailStep[];
  natureLine?: string;
  nextAction?: string;
}

Status mappings

role="dialog" aria-modal="true"

Sheet semantics. The rest of the panel is inert to assistive tech while it is open.

aria-labelledby

The <h2> status line — the accessible name.

"completed"

Check glyph + the word 'Completed'. Never colour alone.

"notCompleted"

Minus glyph + “Didn’t complete”. Muted, not red — this is an explanation, not a second alarm.

"unknown"

Question glyph + 'Not known'. Used when we genuinely cannot say, e.g. contact match after a dropped connection.

nature: temporary

Waiting and retrying is the recommended move.

nature: needsYou

Retrying alone won't fix it; the recommended move is in Settings or with the account owner.

Example usage

const reviewRef = useRef<HTMLButtonElement>(null);
const [open, setOpen] = useState(false);

<Btn ref={reviewRef} variant="secondary" onClick={() => setOpen(true)}>
  Review sync details
</Btn>

<SyncDetails
  open={open}
  onClose={() => setOpen(false)}
  model={model}
  retryable={spec?.retryable}
  retrying={retrying}
  onRetry={() => { setOpen(false); setTimeout(onRetry, 0); }}
  triggerRef={reviewRef}
/>

Chrome side-panel constraints

• One implementation only. Success and failure must never grow separate details components again — they share this sheet and this model.
• Never show an empty or generic details panel. When no step can be named honestly, there is no model and the trigger disappears with it.
• Copy standard: a short label, then one sentence of meaning in the person's language. 'We couldn't determine whether this contact already exists.' — not 'contact lookup failed'.
• Forbidden in this surface: stack traces, request or response payloads, record IDs, HTTP status codes, internal error strings.
• No rollback. FollowQue never offers one-click undo for a CRM action; toast-level Undo covers local FollowQue state only.
• Tone stays calm. The failure card owns the one permitted danger tint; this sheet is neutral surface, muted glyphs and explanation.
• Layout is tuned for a 400px side panel: one column, wrapped values, sticky action row, sheet capped at 94% height.

Props

TypeScript interface

export type GuidanceMode = "full" | "low" | "off";

export type GuidanceWorkflow =
  | "captureLead" | "followUp" | "aiReply"
  | "snooze" | "ghlSync" | "none";

export const GUIDANCE_MODEL_VERSION = 1;

interface DiscoveryCtx {
  mode: GuidanceMode;
  setMode: (m: GuidanceMode) => void;
  completeWorkflow: (w: GuidanceWorkflow) => void;
  workflowDone: (w: GuidanceWorkflow) => boolean;
  reset: () => void;
}

Status mappings

captureLead

firstLeadSaved celebration · completed when a lead is saved

followUp

queueFilters coach mark, waitingHint, firstFollowUpSet · completed when a follow-up date is set

snooze

snoozeHint · completed when a follow-up is moved

aiReply

repliesFirstUse · completed when a draft is copied

ghlSync

syncFirstUse, firstSync · completed on a successful save

Example usage

const { mode, completeWorkflow } = useDiscovery();

// A view marks the workflow learned on the real action only
const setFollowUp = (id: string, iso: string) => {
  updateUndoable(id, { followUpDate: iso }, "Follow-up moved");
  completeWorkflow("followUp");
};

// Guidance surfaces stay declarative — the provider applies the mode
<Hint id="snoozeHint" when={!loading} />
<Celebration id="firstFollowUpSet" when={dateChanged} />

Chrome side-panel constraints

• Persisted: fq-guidance-mode, fq-guidance-workflows (completed workflows), fq-discovery-seen (dismissed moments), fq-guidance-version.
• Never persisted: conversation content, message text, CRM credentials or API tokens. Guidance state is a handful of string ids.
• GUIDANCE_MODEL_VERSION is bumped only for a genuinely new guidance model. Cosmetic copy or styling changes must not reset a user's history.
• A genuinely new feature may add one new guided moment; it is a new id, so it is eligible even for users with history.
• Verification: Full shows approved hints; Low shows one per workflow and stops after completion; another unlearned workflow still teaches; warnings and errors persist in every mode; Off hides optional guidance only; returning to Low keeps history; reset makes first-use eligible again; keyboard-only and screen-reader operation, reload persistence, and light/dark/reduced-motion all verified.

Props

TypeScript interface

export interface KeyRow { keys: string[]; action: string }
export interface KeyGroup { id: string; title: string; rows: KeyRow[] }

export const keyboardGroups: KeyGroup[];
export function shouldOpenKeyboardHelp(e: KeyboardEvent): boolean;

Status mappings

Anywhere

Tab / Shift+Tab · Enter or Space · ?

Popovers, menus, dialogs

Esc closes · Tab stays inside a dialog · Enter or Space chooses

Follow-up dates and snooze

← → move · Home / End jump · Enter sets the date · Esc closes unchanged

After an action

Tab reaches Undo · Enter undoes before the toast fades

Moving around

Tab reaches the bottom navigation · Enter opens a tab

Example usage

// Panel shell (once)
<KeyboardHelpProvider>{children}</KeyboardHelpProvider>

// Settings › Help & hints
<KeyboardHelpButton />

// Contextual hint
<KeyHint keys="Esc" className="mt-2 justify-center">
  to close · arrow keys to choose a date
</KeyHint>

Chrome side-panel constraints

• Do not add a help icon to the header or any selling screen. One entry point only.
• Never open it automatically — not on first run, not after onboarding.
• Add a row only after the interaction is genuinely supported by a shipped component.
• No editable shortcut preferences, no shortcut chords, no single-letter global keys in V1.
• This panel is the customer-facing surface; the full engineering contract stays here in /components.

Props

TypeScript interface

export interface UndoOptions {
  undoMsg?: string;
  captureUi?: () => unknown;
  restoreUi?: (snapshot: unknown) => void;
  focusKey?: string;
}

Status mappings

Confirmation copy

`Follow-up moved to ${formatFollowUpDate(iso)}`

Restoration copy

`Follow-up restored to ${formatFollowUpDate(previousIso)}`

No previous date

'Follow-up restored'

Completed → queue

'<First name> moved back to the queue'

Example usage

updateUndoable(
  lead.id,
  { bucket: "Upcoming", due: formatFollowUpLine(iso), followUpDate: iso },
  `Follow-up moved to ${formatFollowUpDate(iso)}`,
  {
    undoMsg: `Follow-up restored to ${formatFollowUpDate(lead.followUpDate)}`,
    focusKey: `queue-date-${lead.id}`,
    captureUi: () => ({ expanded: snoozeFor, dateChanged }),
    restoreUi: (s) => { setSnoozeFor(s.expanded); setDateChanged(s.dateChanged); },
  },
);

Chrome side-panel constraints

• Verified with Playwright on leads at the beginning, middle and end of the queue: the row moves to the correct new position, and Undo returns the exact pre-action snapshot (record, order, expanded card, scroll offset, focus) with no duplicate cards.
• Verified in light, dark and reduced-motion modes, and keyboard-only, with the same result and no console errors.
• Covered by the automated axe suite as scenario 'queue-undo-restored' (npm run test:a11y).
• Scope is the immediate Undo window only — deliberately no action history and no multi-step undo.

Props

TypeScript interface

export type Orderable = { id: string; followUpDate?: string };

export function compareUpcoming(a: Orderable, b: Orderable): number;
export function sortUpcoming<T extends Orderable>(rows: readonly T[]): T[];
export function queuePosition(id: string): number;

Status mappings

1. Primary

followUpDate ascending (ISO string compare)

2. Tie-breaker

queuePosition(id) — original queue position

3. Fallback

id.localeCompare(id) — guarantees a total order

Example usage

const rows = bucket === "Upcoming" ? sortUpcoming(filtered) : filtered;

Chrome side-panel constraints

• Test cases: (1) three leads share Wednesday, August 12; (2) confirm the initial order Noor → Reuben → Clara; (3) move the middle lead (Reuben) to another date; (4) Noor and Clara keep their order; (5) Undo; (6) Reuben returns between Noor and Clara; (7) repeat with the first and last of the group; (8) rerender and switch filters — order unchanged; (9) repeat keyboard-only — same result; (10) reading order matches visual order.
• Verified in light and dark themes and with reduced motion; no console errors and no duplicate cards.
• Limitations: ordering is session-scoped like the rest of the prototype — a reload rebuilds it from the seed data. Only the Upcoming section is date-sorted; Overdue, Today, Waiting for Reply and Completed keep their authored order. No drag-and-drop or manual reordering exists, by design.

Props

TypeScript interface

interface OnboardingData {
  messengerConnected: boolean;
  ghl: "pending" | "connected" | "skipped";
  leadName: string;
  leadBusiness: string;
  leadSaved: boolean;
  followUp: string | null;
  reply: string;
  replyDrafted: boolean;
  replyEdited: boolean;
}

interface OnboardingState {
  step: number;
  completed: number[];
  skipped: number[];
  editReturn: number | null;
  data: OnboardingData;
}

Status mappings

Lead name changed

Updates the lead preview and the recap row. Follow-up, draft reply and progress untouched.

Follow-up changed

Updates the queue preview and the recap row. Lead and draft reply untouched.

Reply edited

Manual wording is kept verbatim; a new draft is only written after the user confirms 'Replace draft'.

GoHighLevel skipped then connected

Moves the step from skipped to completed and rewrites only that recap row.

Example usage

const goBack = () =>
  setState((s) =>
    s.editReturn !== null
      ? { ...s, step: s.editReturn, editReturn: null }
      : { ...s, step: Math.max(0, s.step - 1) },
  );

Chrome side-panel constraints

• Persistence: current step, completed steps, skipped steps, edited values and resume position are stored under fq-onboarding-progress-v1 and cleared when setup finishes. No secrets, tokens, passwords or live CRM data are stored — none exist in this flow.
• Verification: walked Back through every step; edited the lead, the follow-up day and the reply; skipped GoHighLevel and connected it later from the recap; confirmed only the affected recap row changed each time and no reset occurred. Repeated keyboard-only, with the screen reader order matching the visual order, in light mode, dark mode and reduced motion. Closing and reopening setup resumed on the same step with edited values intact.
• Limitations: the panel has no browser history of its own, so browser Back leaves the extension rather than stepping through setup — in-panel Back is the single navigation control, by design.

Props

TypeScript interface

// Approved naming strategy — visible text names the badge.
<span data-status-badge="Hot">
  <Flame aria-hidden focusable="false" />
  Hot
</span>

// Interactive exception — action + current value, spoken once.
<button aria-label="Lead status: Hot. Change status"> … </button>

Status mappings

Decorative icon

aria-hidden="true" and focusable="false" on every status glyph

SVG <title>

Never rendered inside a decorative glyph — a <title> becomes part of the computed name

Hidden helper text

No visually hidden text may repeat the visible status word

aria-label

Not allowed on a badge whose visible text is already the correct name

aria-describedby

Never wired to text that duplicates the label

Local test command

bunx playwright test --config=playwright.config.ts status-badge-name

Automated coverage

24 scenarios: light + dark across Today, queue rows, search results, lead detail, GoHighLevel save preview, /design-system matrix and /components playground

Negative coverage

Injects an SVG <title>, a duplicating tooltip, a redundant aria-label, a duplicated aria-describedby, duplicate hidden text and a missing aria-hidden — each must fail the audit

Example usage

// Read what the browser would expose for every badge on screen
const { problems, names } = await auditStatusBadges(page, ctx);
expect(names).toEqual(["Hot", "Waiting", "Won"]);

Chrome side-panel constraints

• Applies at every supported side-panel width; compact layouts change geometry only, never naming.
• The same rules govern the /design-system state matrix and the /components props playground.

Props

TypeScript interface

type AuditKind = "normal-text" | "large-text" | "non-text";

runAudit(document.body, { kinds: ["non-text"] });

Status mappings

Normal text

4.5:1 — WCAG 1.4.3

Large text

3:1 — WCAG 1.4.3

Non-text UI

3:1 — WCAG 1.4.11: meaningful controls, icons, focus indicators, control boundaries and borderless control fills

Large-text definition

≥24px, or ≥18.66px at weight 700+ — applied only to text that genuinely qualifies

Classification

Unchanged by the selector: every element is graded against its own applicable threshold; the selector filters the view

Persistence

Session state only — never stored, never a customer preference

Design tokens

Untouched — switching threshold changes no styles, only which findings are shown

Availability

import.meta.env.DEV only — the control is dropped from production bundles

Production fallback

Audit sweeps every threshold, exactly as before

Verified

Light and dark modes, reduced motion, 320 / 400 / 480px side-panel widths

Example usage

// Headless sweep of one threshold
window.__fqContrastAudit();              // complete audit
window.__fqContrastAudit("large-text");  // focused QA view
runAudit(document.body, { kinds: ["large-text"] });

Chrome side-panel constraints

• Developer and QA tooling only — it is never a customer-facing setting.
• Threshold choice is per session; it does not persist into the product.

Props

TypeScript interface

export const VIEW_TRANSITION_MS = 160;

export function useScreenState<T>(key: string, initial: T): [T, (v: T) => void];
export function useReducedMotion(): boolean;
export function prefersReducedMotion(): boolean;

interface NavContinuity {
  navKey: string;                       // "conversation:maya"
  scrollMemory: Map<string, number>;
  uiMemory: Map<string, unknown>;
  pendingFocusKey: string | null;
  clearPendingFocus: () => void;
}

Status mappings

data-fq-focus="conversation-sync"

Sync button on the lead screen — focus target after Done.

data-fq-focus="conversation-manage-sync"

'Manage sync →' on the GoHighLevel card — focus target after Done when that was the entry point.

fq-view

Incoming screen: 160ms fade in.

fq-leaving

Outgoing success card: 160ms fade out before back().

Example usage

// Panel body: persistent scroller, keyed screen, restore before paint
<div ref={scroller} className="fq-scroll flex-1 overflow-y-auto">
  <div key={navKey} className="fq-view">{screen}</div>
</div>

useLayoutEffect(() => {
  if (lastKey.current === navKey) return;
  lastKey.current = navKey;
  scroller.current!.scrollTop = scrollMemory.get(navKey) ?? 0;
}, [navKey]);

// Done: fade, then return. Reduced motion returns immediately.
const handleDone = () => {
  if (prefersReducedMotion()) return back();
  setLeaving(true);
  window.setTimeout(back, VIEW_TRANSITION_MS);
};

// Trigger opts into focus restoration by naming itself
<Btn data-fq-focus="conversation-sync" onClick={() => go("sync")}>Sync</Btn>

Chrome side-panel constraints

• At 400px wide there is no room for spatial metaphor. Cross-fade is the only transition in the product — do not add slide or push for 'hierarchy'.
• Never remount the scroll container on navigation; keying the container is what caused the old jump-to-top on return.
• Restore what the person set (scroll, filters, selection). Do not restore what the person closed (menus, popovers, toasts).

Props

TypeScript interface

export interface ToastEntry {
  id: number;
  msg: string;
  tone: "status" | "error";
  duration: number; // 0 = stays until dismissed
  undo?: (() => void) | undefined;
  retry?: (() => void) | undefined;
  originKey?: string | null; // data-fq-focus key of the triggering control
}

export interface ToastApi {
  toast: ToastEntry | null;
  notify: (msg: string, undo?: () => void) => void;
  notifyError: (msg: string, opts?: { retry?: () => void }) => void;
  dismissToast: () => void;
  updateUndoable: (id: string, patch: Partial<Lead>, msg: string) => void;
}

Status mappings

Complete

'{First} marked complete' + undo

Snooze

'Follow-up moved to Tuesday, August 11' + undo — canonical date format

Reschedule

'Follow-up moved to Monday, August 3' + undo

Status change

'{First} set to {Status}' + undo

Capture / Sync

success confirmation, no undo (the sync screen owns its own state)

Example usage

updateUndoable(
  lead.id,
  { bucket: "Completed", due: "Completed today" },
  `${lead.name.split(" ")[0]} marked complete`,
);

Chrome side-panel constraints

• Positioned bottom-20 so it clears the bottom navigation, width calc(100% - 2rem).
• Toasts queue, oldest on top, capped at 3 — a pending Undo is never replaced.

Props

TypeScript interface

export interface SnoozeOption {
  id: string;    // "today" | "tomorrow" | "3d" | "1w"
  label: string; // "In 3 days"
  days: number;  // 0 | 1 | 3 | 7
}

export interface SnoozeMenuProps {
  open: boolean;
  onPick: (option: SnoozeOption) => void;
  onClose: () => void;
  options?: SnoozeOption[]; // default followUpPresets
}

Status mappings

Today

addDays(0) → bucket 'Today'

Tomorrow

addDays(1) → bucket 'Upcoming'

In 3 days

addDays(3) → bucket 'Upcoming'

Next week

addDays(7) → bucket 'Upcoming'

Example usage

{followUpPresets.map((o) => {
  const iso = addDays(o.days);
  return (
    <button key={o.id} onClick={() => updateUndoable(
      lead.id,
      { bucket: "Upcoming", followUpDate: iso, due: formatFollowUpLine(iso) },
      `Follow-up moved to ${formatFollowUpDate(iso)}`,
    )}>
      <span>{o.label}</span>
      <span className="text-[11.5px]">{formatFollowUpDate(iso)}</span>
    </button>
  );
})}

Chrome side-panel constraints

• Inline, not floating: a popover at 400px would clip against the panel edge or need a portal.
• Custom dates are intentionally absent — the queue is a rhythm, not a calendar.

Props

TypeScript interface

export interface AlertProps {
  tone?: "info" | "success" | "warning" | "danger"; // default "info"
  title: string;
  children?: ReactNode;
  action?: ReactNode;
}

Status mappings

Sync failed

danger + 'Retry sync'

Lead captured

success (Card tone="success" is the alternative for the full-screen moment)

AI drafts

info — 'Review before sending'

Missing data

warning — sync still allowed

Example usage

<Alert tone="danger" title="Sync failed" action={<Btn variant="secondary" size="sm" onClick={retry}>Retry</Btn>}>
  GoHighLevel didn't respond. Nothing was changed on the contact.
</Alert>

Chrome side-panel constraints

• Place the alert directly above the control it concerns; at 400px a top-of-screen banner loses its referent after scrolling.

Props

TypeScript interface

export interface SkeletonProps { className?: string }

export interface ProgressProps {
  value: number;   // 0–100
  label?: string;
}

// IndeterminateBar takes no props.

Status mappings

AI generating

card skeletons + 'Reading the last N messages…'

GHL syncing

IndeterminateBar under the Sync button

Bulk work

Progress with a real count

Example usage

<div aria-busy className="space-y-2">
  <Skeleton /><Skeleton className="w-[90%]" /><Skeleton className="w-[60%]" />
</div>

<IndeterminateBar />
<Progress value={62} label="Syncing contacts" />

Chrome side-panel constraints

• No spinners anywhere in the product — a rotating element in a narrow panel reads as instability.
• Skeleton counts should match the real content count so the panel height does not jump.

Props

TypeScript interface

export function useLoading(
  duration?: number, deps?: unknown[], delay?: number, min?: number,
): { loading: boolean; showSkeleton: boolean };

export interface LoadingSlotProps { show: boolean; children: ReactNode }
export interface LoadedStatusProps { loading: boolean; message: string }

Status mappings

Loading

skeleton only — no empty state, no error state, no announcement

Loaded with content

content + one polite outcome sentence

Loaded with nothing

empty state + one polite outcome sentence

Example usage

const { loading, showSkeleton } = useLoading(800);

<LoadedStatus loading={loading} message={rows.length ? `${rows.length} follow-ups in your queue.` : "Your follow-up queue is empty."} />

{loading ? (
  <LoadingSlot show={showSkeleton}><FollowUpsLoading rows={3} /></LoadingSlot>
) : rows.length ? (
  rows.map(...)
) : (
  <Empty spec={emptyStates.noUpcoming} />
)}

Chrome side-panel constraints

• Never render the empty state while loading is still true — the ternary always branches on `loading` first.
• Never render an error state before loading completes; failures replace the skeleton, they don't precede it.
• Skeleton row counts approximate the real content so the panel height barely moves on resolve.
• Audited surfaces: Today (context, overdue, hot, quiet threads), Follow-up queue, Search, Reply suggestions, CRM match lookup, Sync to GoHighLevel.

Props

TypeScript interface

export type SearchPhase = "idle" | "loading" | "results" | "empty" | "error";

export function useLeadSearch(leads: Lead[], query: string, delay?: number, min?: number): {
  phase: SearchPhase; showSkeleton: boolean; results: Lead[]; retry: () => void;
};

export interface SearchNoResultsProps { query: string; onClear: () => void }
export interface SearchConnectionErrorProps {
  onRetry: () => void; onClose: () => void; retrying?: boolean;
}

Status mappings

Loading

skeletons + role="status" (silent until resolved)

No results

neutral empty card — never role="alert", nothing failed

Connection error

role="alert", announced once, focus moves to the heading

Example usage

const search = useLeadSearch(leads, query);

{search.phase === "loading" ? (
  <LoadingSlot show={search.showSkeleton}><SearchLoading rows={3} /></LoadingSlot>
) : search.phase === "error" ? (
  <SearchConnectionError onRetry={search.retry} onClose={() => setQuery("")} />
) : search.phase === "empty" ? (
  <SearchNoResults query={query} onClear={() => setQuery("")} />
) : (
  <Results leads={search.results} />
)}

Chrome side-panel constraints

• Copy standard: no results states the fact then offers the way back ('No matching leads were found. Try a different search term, or clear your search to view all leads.'). The error states what happened, reassures that existing data is safe, and asks for one retry — no status codes, no jargon.
• Prototype simulation: search runs over mock data with no network call, so a real failure is impossible. Typing 'offline' triggers the simulated error, and the card says 'Simulated for this prototype' so it is never mistaken for a live incident. A retry always succeeds.
• Transitions are opacity-only (fq-fade) inside a height-reserving slot, and the global prefers-reduced-motion rule collapses them to an instant swap.

Props

TypeScript interface

export interface EmptyStateProps {
  icon: ReactNode;
  title: string;
  body: string;
  action?: ReactNode;
}

Status mappings

Overdue

'Nothing overdue' — praise, no action

Today

'No follow-ups today' + capture hint

Upcoming / Waiting / Completed

quiet factual copy, no action

No leads at all

primary 'Capture your first lead'

No AI context

'Not enough context yet' + back to conversation

Example usage

<EmptyState
  icon={<ListChecks size={18} />}
  title="No captured leads yet"
  body="Open a Facebook conversation and capture the prospect."
  action={<Btn variant="primary" size="sm" full onClick={() => go("capture")}>Capture your first lead</Btn>}
/>

Chrome side-panel constraints

• Vertically centred inside the scroll area, not the panel — the header and nav stay put.

Props

TypeScript interface

export interface ModalProps {
  open: boolean;
  onClose: () => void;
  title: string;
  description?: string;
  children?: ReactNode;
  footer?: ReactNode;
}

Example usage

<Modal
  open={open}
  onClose={() => setOpen(false)}
  title="Disconnect GoHighLevel?"
  description="Captured leads stay in FollowQue. Nothing is deleted."
  footer={<>
    <Btn variant="ghost" onClick={() => setOpen(false)}>Cancel</Btn>
    <Btn variant="danger" onClick={disconnect}>Disconnect</Btn>
  </>}
/>

Chrome side-panel constraints

• Positioned absolute inside the panel shell, so it never escapes the 400px frame or covers the Facebook page.
• One modal at a time; no nested dialogs.

Props

TypeScript interface

export interface HeaderProps {
  ghlConnected: boolean;
  dark: boolean;
  onToggleDark: () => void;
}

Example usage

<Header ghlConnected={ghlConnected} dark={dark} onToggleDark={toggle} />

Chrome side-panel constraints

• Header + nav must stay under ~110px total so the content area keeps ~740px at the 850px minimum panel height.
• The wordmark never wraps the header to two lines.

Props

TypeScript interface

export type View =
  | "today" | "conversation" | "replies"
  | "capture" | "queue" | "sync" | "settings";

export interface BottomNavProps {
  view: View;
  onNavigate: (v: View) => void;
  tabs?: { id: View; label: string; icon: LucideIcon }[];
}

Example usage

<nav className="sticky bottom-0 grid grid-cols-4 border-t border-border bg-background/90 px-2 py-1.5 backdrop-blur">
  {tabs.map((t) => (
    <button key={t.id} onClick={() => onNavigate(t.id)} aria-current={view === t.id ? "page" : undefined}>
      <t.icon size={17} strokeWidth={view === t.id ? 2.4 : 1.9} />
      {t.label}
    </button>
  ))}
</nav>

Chrome side-panel constraints

• Four is the maximum at 400px: five labels at 10.5px start truncating.
• Sticky, not fixed, so it stays inside the panel document in MV3.