If you are an AI agent generating memax UI code, these are the hard rules. Each rule maps to a section. Violating any rule produces non-memax output.

MEMAX DESIGN SYSTEM — HARD RULES FOR CODE GENERATION
═══════════════════════════════════════════════════════

COLORS (§13)
  text:       text-fg-1 (titles, body) | text-fg-2 (secondary) | text-fg-3 (meta) | text-fg-4 (decorative)
  surfaces:   bg-surface-1 (subtle) | bg-surface-2 (hover) | bg-surface-3 (active)
  accent:     var(--signature) — ONLY for AI indicators (✦) AND Intelligence tab controls, never decorative
  NEVER:      text-gray-*, bg-gray-*, hardcoded colors, text-foreground/XX

CONTROL COLOR SEMANTICS (§19)
  rule:       purple = Intelligence tab ONLY. Everywhere else uses NEUTRAL_INK.
  NEUTRAL_INK:       var(--fg-1) — active toggles, radio rings, radio dots
  NEUTRAL_INK_INVERSE: var(--background) — toggle thumb when filled
  off states:        NEUTRAL_TRACK_OFF / NEUTRAL_BORDER_OFF / NEUTRAL_THUMB_OFF
  import from:       @memaxlabs/ui/tokens/controls
  toggle:     iOS-solid. Track fills with active color, thumb inverts.
  radio:      border-2 ring + NEUTRAL_INK dot. NEVER fill the outer ring.
  pills vs radio rows: pills = self-explanatory labels (roles, tiers). radio rows = needs descriptions (Plain/Signature/Time).
  See §19 "Control color semantics" card for the canonical rule block.

TYPOGRAPHY (§12)
  H1:         text-[21px] font-bold                    (one per view, memory detail title)
  H2:         text-[16px] font-bold                    (section headers)
  H3:         text-[14px] font-semibold                (card titles)
  body:       text-[14px] text-fg-1                    (default)
  secondary:  text-[13px] text-fg-2 or text-fg-3       (descriptions, meta)
  caption:    text-[12px] text-fg-3                    (timestamps, kind)
  micro:      text-[10px] text-fg-4 uppercase tracking-wider font-semibold (group headers)
  weights:    400-700 only. NEVER font-light (300) or font-black (900)
  prose:      leading-[1.65] for AI answers and readable paragraphs

SURFACES (§14)
  card grid:  <Surface variant="default">     (bar-border + bar-shadow)
  detail:     <Surface variant="subtle">      (border only)
  mobile:     <Surface variant="borderless">  (full bleed)
  minimal:    <Surface variant="clean">       (bg only)
  note:       Surface's 'rounded' prop ("xl"|"2xl"|"lg") is a component API
              that resolves to the unified tokens — "xl"/"2xl" resolve to
              rounded-surface (20px); "lg" is legacy — don't use it. Surface
              defaults to rounded-surface when the prop is omitted.
  radius:     TWO tiers only — rounded-surface (20px) | rounded-chrome (14px)
              surface: cards, dialogs, popovers, bar, form sub-cards, containers
              chrome:  buttons, inputs, chips, role tags, code pills, any interactive
                       element ≤40px tall (even role tags become pill-ish at that size)
              source:  packages/ui/src/surface-radius.css (root-scoped, theme-safe)
              NEVER use rounded-lg/md/xl/2xl/3xl on product UI — those are stale.
              Exceptions:
                rounded-full  — true circles (avatars, status dots) OR status pills
                                ≤24px tall where the half-height clamps to the same
                                curve as rounded-chrome anyway
                rounded-sm    — 2px focus outlines on inline text links only

LAYOUT (§20)
  page:       max-w-4xl mx-auto px-5 sm:px-8 pb-36 md:pb-32
  top:        paddingTop: CONTENT_TOP (80px desktop)
  entrance:   animate-content-ready (on every page load)
  bar:        fixed bottom center, z-bar, max-w-[640px]
  modal:      z-modal (backdrop + content — DOM order stacks)

Z-INDEX SCALE — semantic tokens only (§20)
  NEVER use hardcoded z-50, z-[60], etc. Pick from this scale:
  z-page         (0)   regular page content
  z-bar-notif    (30)  bar notification (below bar)
  z-bar          (40)  command bar, mobile dock, top-right chrome row
  z-topic-tree   (50)  Topic Explorer floating panel + mobile fullscreen
  z-modal        (60)  Settings panel, Settings dialog, memory modal,
                       admin drawer, batch-toolbar backdrop
  z-popover      (70)  ALL popovers/dropdowns/menus/InfoPopover (above
                       modal so popovers triggered inside a dialog work)
  z-takeover     (80)  full-screen immersive: lightbox, hub-create,
                       mobile compose, surface-transition-overlay
  z-toast        (90)  top-most ephemeral feedback, impersonation-bar

  Invariant: popover > modal > topic-tree > bar > bar-notif > page.
  Invariant: takeover > popover (full-screen covers dropdowns).
  Tokens are defined as CSS vars (--z-*) in :root + @utility blocks
  in globals.css. Do NOT invent new tiers unless the token scale
  genuinely can't express the layer — add a tier with a rationale.

GLASS + BACKDROP-BLUR — unified surface material (§14)
  ALL translucent floating surfaces use ONE of three sibling classes,
  each paired with backdrop-blur-sm (8px) so the standard
  backdrop-filter property emits (Lightning CSS strips the standard
  form from raw custom-CSS declarations in some cases).
  .glass-bar       command bar                           → paired in layout.tsx
  .glass-panel     Topic Explorer tree panel             → paired in topic-tree-panel.tsx
  .glass-dropdown  ALL popovers (via PopoverContent)     → paired in packages/ui/src/components/popover.tsx
  Recipe: 65% fill + saturate(180%) contrast(1.05) + rim inset + ambient shadow.
  NEVER hand-roll a fourth glass variant. If a new surface needs glass,
  reuse one of the three. The popover primitive OWNS the material for
  every dropdown — consumers pass NO variant/override.
  Popovers: PopoverContent is always glass — no variant prop.
  Menu rows: <MenuItem> from @memaxlabs/ui — never hand-roll a button
  with px/py/hover/radius classes for menu items.

MOTION (§18)
  easing:     var(--ease-spring) — cubic-bezier(0.16, 1, 0.3, 1)
  NEVER:      linear, ease-in-out, ease
  fast:       0.15s (hover, modal, dropdown)
  normal:     0.2s (content transitions)
  AI breathe: state-slow-breathe (2.5s loop)
  entrance:   animate-content-ready (0.15s opacity + translateY)

MOBILE MOTION — HARD RULES (§38e3 mobile lifecycle)
  ░░░ THE SINGLE-BLUR INVARIANT ░░░
  At most ONE backdrop-filter: blur() element composited at a time on mobile.
  Stacking (scrim + glass edge + bar) is the #1 frame-drop cause on mobile GPUs.
  Never blur over a solid background — if bg-card / bg-background is opaque,
  backdrop-filter is INVISIBLE but still costs a full compositing pass per
  frame. Check --card / --background opacity BEFORE adding blur.

  CROSS-TAB DOCK SWITCH (mobile)
  Instant. No fade, no surface-transition overlay, no color-interpolation
  on tab buttons. router.push() only. Desktop keeps subtle fade-in; mobile
  snaps. NEVER call requestSurfaceTransitionForNavigation on mobile tabs.

  MEMORY DETAIL NAVIGATION
  Entry:  opacity fade via template's animate-fade-in (150ms). No slide-in.
  Exit:   router.back() INSTANT. No setTimeout delay, no slide-out-right.
  NEVER:  animate-slide-in-right / animate-slide-out-right on mobile routes.

  TOPIC DRILL (kitchen 29n spec)
  Duration:  FAST (150ms) on mobile, NORMAL (200ms) on desktop.
  Translate: ±16px on x-axis.
  Easing:    var(--ease-spring).
  Parallel:  AnimatePresence WITHOUT mode="wait". Serial mode doubles
             perceived duration (exit 200ms + enter 200ms = 400ms).

  MOBILE COMPOSE SHEET (kitchen 38e3)
  Surface:   ONE solid var(--background) sheet. NEVER translucent + blur.
             The compose state TAKES OVER, it doesn't LAYER on top.
  Motion:    opacity fade only (FAST 150ms). NO y-slide, NO delayed content
             fade, NO framer layout animations.
  Gesture:   drag-to-dismiss is user-initiated — keep it. Rubber-band
             resist 0.55, dismiss >96px OR velocity >720px/s, settle 0.25s.

  BAR ON MOBILE
  - No 100ms setTimeout stagger before barVisible flips.
  - No CSS transition on outer positioning div (top / transform constants).
  - No framer opacity+y fade-in on mount/tab-switch.
  - Position: calc(100dvh - 96px - var(--safe-bottom, 0px)) above dock.
  - Rest dock has zero backdrop-filter (see single-blur invariant).

  CHROME ROW (logo + hub chip + avatar)
  - No transition-all on mobile — tab switches must not animate bg/border.
  - Always transparent on mobile; banner-mode tint transition is desktop-only.
  - BrandLogo: h-5 w-24 (mobile) / h-6 w-30 (desktop).

  MEMORY ROW COMPACT (mobile recent surface)
  - showSummary = false (no description preview).
  - useStackedRecent = false (single-line layout).
  - showCopy = false (saves horizontal space).
  - leadingIdentity = "none" (title leads the scan).
  - trailingActor = author avatar | agent icon | none.
  - showTrailingContentMeta = true for pdf/image/link (NOT for docs/notes).
  - Flag: isMobileCompactRecent in memory-row-presentation.ts.

  POPOVERS / DROPDOWNS
  - No backdrop-filter over solid bg-card. Remove it — the card is opaque.
  - data-open:duration-100 (not default 150) for snap-open feel.
  - For mobile SettingsPanel-style: plain conditional render, no framer
    AnimatePresence. Framer overhead eats the budget at sub-150ms durations.

  FRAMER MOTION BUDGET
  - Never nest motion.div with opacity fades 3 levels deep for one appearance.
  - duration < 0.15s → prefer CSS transition or plain render (framer tax).
  - AnimatePresence mode="wait" → NEVER on routes; use default parallel.

CONTROLS (§19)
  buttons:    <Button variant="default|outline|secondary|ghost|destructive">
  sizes:      xs (h-6) | sm (h-7) | default (h-8) | lg (h-9)
  icon:       icon-xs (24px) | icon-sm (28px) | icon (32px) | icon-lg (36px)
  send btn:   h-8 w-8 rounded-lg. Push=foreground fill, Recall=signature fill
  toggle:     w-10 h-6 rounded-full. See CONTROL COLOR SEMANTICS above for on/off colors.

ACCESSIBILITY (§27)
  fg-1:       12.2:1 — safe everywhere
  fg-2:       5.2:1  — safe everywhere
  fg-3:       2.5:1  — meta/labels only, FAILS AA normal text in light mode
  fg-4:       1.5:1  — decorative only, NEVER readable text
  focus:      focus-visible:ring-3 focus-visible:ring-ring/50
  touch:      44px primary, 32px secondary, 24px minimum

The wordmark is the stable brand anchor. Next to the right-side hub capsule it was reading like a watermark — too small, too muted, hard to notice. The fix is size + opacity, not color. The ink stays neutral var(--foreground) so signature (violet) can keep its job as accent for hub avatars / dreams / active states without the wordmark stealing that vocabulary.

// packages/web/src/app/(app)/layout.tsx
import { MemaxWordmark } from "@memaxlabs/ui";

function BrandLogo({ isMobile }: { isMobile: boolean }) {
  return (
    <div
      className="fixed z-50 flex h-12 items-center"   // was h-11
      style={{
        left: isMobile ? 16 : 32,
        top: isMobile
          ? "max(20px, calc(8px + var(--safe-top, 0px)))"
          : "32px",
      }}
    >
      <a
        href="/home"
        className="cursor-pointer text-foreground opacity-90 transition-opacity hover:opacity-100"
      >
        <MemaxWordmark height={24} />
      </a>
    </div>
  );
}

// Right-capsule container on line ~143 — lock height to match:
<div
  className="fixed right-4 md:right-8 z-50 flex h-12 items-center gap-2 ..."
  //                                             ^^^^^ add h-12
  ...
>

Hub headers drift through aurora gradients (time-of-day, signature, dreams). When an aura sits behind the wordmark, the fixed var(--foreground) ink can fall into the gradient and become hard to read. This card answers the question: should the wordmark auto-adapt to the aura behind it?

// packages/web/src/app/(app)/layout.tsx

function BrandLogo({
  isMobile,
  showBannerChrome,              // NEW — accept the same flag the right capsule uses
}: {
  isMobile: boolean;
  showBannerChrome: boolean;
}) {
  return (
    <div
      className={`fixed z-50 flex h-12 items-center rounded-2xl px-3 py-1.5 transition-all ${
        showBannerChrome
          ? "border border-white/10 bg-background/52 backdrop-blur-md ring-1 ring-black/5"
          : "border border-transparent bg-transparent backdrop-blur-0 ring-0"
      }`}
      style={{
        left: isMobile ? 16 : 32,
        top: isMobile
          ? "max(20px, calc(8px + var(--safe-top, 0px)))"
          : "32px",
      }}
    >
      <a
        href="/home"
        className="cursor-pointer text-foreground opacity-90 transition-opacity hover:opacity-100"
      >
        <MemaxWordmark height={24} />
      </a>
    </div>
  );
}

// Layout already computes showBannerChrome for the right capsule — pass the
// same value into <BrandLogo /> so both sides light up together.

3 dots in signature color, sequential pulse. Pure CSS — no requestAnimationFrame.

All semantic colors are computed from --foreground with opacity multipliers. Change one variable, entire palette adapts. No hardcoded color values in components.

Rule: one H1 per view. H2 for sections within a page. H3 for cards/list items. Never skip levels.

Rule: never use font-light (300) or font-black (900). Product uses 400–700 range only.

All computed from --foreground via oklch opacity. Adapts automatically to dark mode. Never use raw foreground/XX — always use text-fg-N classes.

Rule: never skip elevation levels. Page → Content → Elevated → Floating → Modal.

Same border/shadow as bar. Separator: border-t border-border/30. Hover: bg-surface-1.

Rule: two tiers only — rounded-surface (20px) wraps interactive rounded-chrome (14px). Source: packages/ui/src/surface-radius.css. Pick by element size — ≤40px is chrome, >40px is surface.

Glass communicates layer hierarchy: “this floats above that.” Never decorative.

Rule: semantic tokens only. NEVER use hardcoded z-50, z-[65], etc. Pick from this list. Invariants: popover > modal (popovers must work inside a Settings dialog) and takeover > popover (full-screen surfaces cover stray popovers). Tokens defined as CSS vars --z-* on :root plus @utility blocks in globals.css.

Content scrolls behind bar. Bar is fixed bottom center. No sidebar, no top bar. Bottom padding: safe-bottom + bar height + 16px clearance.

Red = forbidden easings. Notice how linear feels robotic and ease-in-out feels sluggish compared to spring.

slow-breathe: AI streaming/processing. fast-pulse: active card processing. static: complete/idle.

Crossfade cycle during AI loading. Source: RecallingText component. verb breathes in signature color.

Tab through to see focus rings. Ring is always 3px (buttons) or 2px (inputs) with --ring at 50%.

WCAG 2.5.8: minimum 24×24px target. Apple HIG: 44×44pt for primary actions. Memax follows Apple for primary, WCAG for minimum.

Use data-icon="inline-start|inline-end" for padding adjustment

<Badge variant="default|secondary|outline|destructive|ghost">
Source: ui/badge.tsx — h-5, rounded-4xl, text-xs

One pill to rule them all. Any chip-shaped element in the product — hub switcher, topic selector, memory tag, row metadata label — uses this primitive. Four variants cover every case; two sizes cover every density. If you find yourself writing rounded-full border bg-... inline, you're reinventing this. Stop and use <Pill> or pillClass() instead.

import { Pill, pillClass, Popover, PopoverTrigger } from "@memaxlabs/ui";

// Option 1 — <Pill> component (preferred for plain cases)
<Pill variant="select" icon={<Icon />} onClick={open}>Hub name</Pill>

// Option 2 — pillClass() helper (when another element owns the interaction,
// e.g. Base UI PopoverTrigger needs to BE the button itself)
<PopoverTrigger className={pillClass({ variant: "select" })}>
  <Icon />
  <span>Hub name</span>
  <ChevronDown className="size-3.5 shrink-0 text-fg-4" />
</PopoverTrigger>

Source: ui/pill.tsx — rounded-lg, bg-surface-1, border-border/60, text-[14px] (lg) / text-[12px] (md) / text-[11px] (sm). Variants: select | remove | add | static. 8px arc matches section 2a's TopicPill reference — crisp, not overly round.

<Pill variant="remove" onRemove={fn}>label</Pill> — Source: ui/pill.tsx. Use the same `Pill` primitive for removable tags instead of a separate tag component. This keeps chip semantics and tokens aligned across the product.

h-8 w-8 rounded-lg. Push: foreground fill. Recall: signature fill. Source: bar-right-portal.tsx

Neutral: NEUTRAL_INK (var(--fg-1)) track when on, NEUTRAL_TRACK_OFF when off. Intelligence: var(--signature) track when on. Both: same geometry — w-10 h-6 rounded-full track, w-4.5 h-4.5 thumb.

Optimistic: switch moves immediately. Pending: border pulses until server confirms (600ms simulated).

border-2 outer ring. Ring color = NEUTRAL_INK when selected, NEUTRAL_BORDER_OFF otherwise. Inner dot = NEUTRAL_INK. NO background fill on the ring — radios are border+dot, not filled pills. See real impl in SelectionOption (settings-dialog.tsx) and hub-permissions-section.tsx.

flex gap-1.5 flex-wrap. Selected: bg-foreground text-background font-medium. Unselected: bg-surface-1 text-fg-2 hover:bg-surface-2. Use when option labels are self-explanatory (role names, plan tiers, filter chips). Canonical impl: hub-invites-section.tsx:204-217. NOT for options that need descriptions — use RadioRow above for those.

h-8, rounded-lg, border-border, focus: border-ring + ring-2 ring-ring/50

Desktop: text "remember · recall" (dot separator). Mobile: pill chips with 44px min touch target. Source: layout.tsx mode toggle

One rule rules them all: purple is reserved for Intelligence, everything else uses neutral ink. This card is the single source of truth — if you're building a new control and wondering “what color does active use?”, the answer is here.

Pattern: label+description left, action button right. Separator: border-t border-border/20.

First consumer: packages/web/src/components/features/topic-card.tsx — "Your Topics" header.

Reusable liveness indicator for agents, services, connections. Derived from timestamps (last_used, last_seen) — no polling, no websocket. Green pulses to draw attention; others are static.

A page with N queries has N independent error zones. Collapsing them into a single page-level error throws away intact data from successful queries and makes retry ambiguous (“retry what?”). Every query renders into its own card; each card owns its own error UI via <DataSectionCard>.

if (topicsError || memoriesError) {
  return <ContentError retry={refetchAll} />
}
// → good topics data is thrown away
// → user sees red page instead of
//   3 loaded sections + 1 failed card

A mutation's isPending is not the same signal as a query's isFetching. Showing both a successMessage toast and an inline visual confirmation is redundant — pick one. Production example: useDreamTriggershows a success toast AND the inbox morphs to a breathing “organizing…” state (use-dreams.ts:37, section 28).

Mutation state  →  Query state  →  Visual
───────────────────────────────────────────────
isPending       →  —              →  button dim + spinner
                                      (per-row, not global)

(settled)       →  isFetching     →  NOTHING (silent refetch,
                                      see section 35c)

isSuccess       →  data updates   →  ONE of:
                                      a) row animates in
                                         via state-memory-arrive
                                         (see section 35e)
                                      b) toast
                                         (irreversible / batch only)

isError         →  data unchanged →  surface-specific error
                                      + retry that names action

Single signature dot that breathes — scale 0.85→1.0, opacity 0.4→1.0, soft glow halo (2.4s ease-in-out). Replaces the three-dot pulse.

Orb breathes → data arrives → dot flares outward (scale 2.8×, glow burst, 0.5s spring) → fades → content enters. Strong sense of "arriving."

MemaxLoader (signature-colored sequential pulse dots) is the brand. Centered on background, not card. Text at /40. Used on brain view during initial load.

Brief transition. Compact loader, no text — user already knows where they're going.

AI answer uses summary callout pattern (bg-surface-1 rounded-xl). Entry: animate-content-ready. ✦ breathes (state-slow-breathe) while streaming, static when complete. Text at /75.

Skeleton mirrors loaded card: dot+title, body, meta. Shimmer uses foreground opacity, not gray — adapts to dark mode.

Recall loading: send button shows spinner (no notification banner). AI synthesis loading: ✦ breathing + RecallingText variant="ai" crossfade below results ("memax is thinking" → "reading your memories" → "connecting the dots"...).

0.15s ease-out, opacity 0→1 + translateY 6px→0. Applied globally to all loading→loaded transitions. Click to replay.

When a mounted data card refetches (stale-while-revalidate, post-mutation invalidation, focus refetch), memax shows no visual signal at all. The rows the user sees are already accurate, and a pulsing indicator would only distract. This is a deliberate rule. For the full composed state machine and the cache pivot / memory arrival cases see section 35.

Card appears immediately with content. ✦ replaces the neutral indicator during processing. "organizing..." breathes in signature color.

i18n: recall.noResults, recall.noResultsHint. Shown inside bar expand slot when recall returns 0 results. No icon — text only.

Tier 2 above is the centered “No memories in code” variant — that's correct for a full-page filter (like the brain view's kind filter). But most filters live insidea SectionCard (Recent, Inbox, Topic detail) and the empty state must render inside the card's body — the header and filter chip stay visible so the user can clear the narrow filter without losing context.

i18n: copy MUST echo the active filter values (“in the past 12 hours”, “from Claude”) — not a generic “No results.” Clear-filter action uses the exact filter label so the user knows what they're undoing. Chinese translations must not repeat the card title (anti-pattern: card labeled 最近 showing “最近 12h 没有结果” — “最近” × 2).

The single most common empty-state bug in memax: a component does if (!data.length) return nulland the entire surface disappears. The result: layout jumps, users can't see where the section was, and they can't tell whether content was deleted or is just loading. Every such callsite should render a minimum viable shell instead.

Historical audit note: keep this list current. Mounted detail sections like topic-siblings.tsx and related-memories.tsxshould use section 35's <DataSectionCard>. Headless providers such as dream-notification.tsx and processing-notification.tsx are not card targets.

The single biggest production risk in the audit: bar recall currently has zero error UI (expand-search-results.tsx:269-292) — a network failure falls through to “No matching memories found.” Users think their memories are gone. Recall is memax's core value prop. Fix: use <ContentError compact> inside the bar expand slot — red pulsing dot + specific message + named retry link. No RotateCw icon, no SIGNATURE color — both are reserved for memax AI working, not user retry (design law 4).

i18n (NEW): recall.errorTitle, recall.retry. Must differ from zero-results copy. Retry label is specific (“Retry recall,” not “Try again”). Error state must never fall through to the zero-results branch.

Desktop /home is intentionally zen: just the bar and a single floating badge under it. Not a section card, not a feed, not a summary — one line of status. Three states morph in place with a crossfade when data arrives. This is the only surface in the app that doesn't use DataSectionCard, because it isn't a section.

Every file in the web package that ships return null when its data list is empty. Each row should migrate to <DataSectionCard> from section 35 with an appropriate empty body. The anti-pattern is documented in 9f above; this table tracks the cleanup.

Every data-bound card in memax has exactly these 5 phases. Header chrome stays identical across all of them — only the body changes. isPlaceholderData is a modifier on loaded, not a separate phase. There is no isFetching prop — background refetch is silent (see 35c).

Recent-style cards do not auto-grow forever. Start with 5 rows, let users reveal 5 more at a time, and always allow the section to collapse back. This keeps the card bounded, preserves page hierarchy, and matches the product rule that data sections stay controllable instead of turning into infinite feeds. The footer only appears when there is more to reveal or when the section is already expanded.

Click a phase to switch the card below. Notice the header stays identical across every phase — only the body morphs. No layout shift.

When React Query re-fetches a card in the background (stale-while-revalidate, post-mutation invalidation, focus refetch), memax shows no visual signal. The rows on screen are already accurate — a pulsing indicator would only interrupt the user. This is a deliberate rule, not an omission.

This IS a moment where the user should see something change: the user just switched hubs or filters, and the rows on screen are about to be replaced. React Query's placeholderData: (prev) => prev keeps the previous data visible while the new query resolves, and the card dims its body to 0.72 to signal “outgoing.” Never drops to a skeleton. The dim is the ONLY visual cue — no pulse, no star, no spinner.

The other legitimate motion moment. When an agent pushes a new memory (SSE event) or the user just captured something, the new row lands with a soft upward settle and a fleeting signature trace on its left edge. Card chrome does nothing — the motion lives entirely on the new row. This is memax's “memory appearing” signature: quiet, expensive-feeling, and still legible during silent refetch.

Left side: patterns we currently ship in production. Right side: the DataSectionCardequivalent. Scan production for these anti-patterns — they're the biggest source of UI state bugs in the audit.

The caller is responsible for deriving phasefrom React Query flags (see 35h). The component is dumb — it just renders what it's told. Row-level states (updating / deleting / processing) live in the row component, NOT in the card phase — a card can hold rows in mixed mutation states simultaneously.

Drop this shape into topic-grid.tsx RecentSection. Delete the existing if (!recentPages) return null (L548) and the hand-rolled card wrapper. All state branches flow through the primitive.

// Recent section — production wiring target
const RECENT_PREVIEW_LIMIT = 5;
const {
  data, isPending, isError, isPlaceholderData, refetch, fetchNextPage,
  hasNextPage, isFetchingNextPage,
} = useRecentMemories({
  hubId,
  window,
  actor,
  expanded: visibleCount > RECENT_PREVIEW_LIMIT,
});

const memories = flattenRecentMemories(data);
const visible = memories.slice(0, visibleCount);
const expanded = visibleCount > RECENT_PREVIEW_LIMIT;
const hasMore = visible.length < memories.length || hasNextPage;
const canLoadMore = visible.length < memories.length || hasNextPage;
const nextIncrement = Math.min(5, Math.max(memories.length - visible.length, 5));
const isFilterActive = window !== "7d" || actor !== "all";

const phase: CardPhase =
  isPending && !data          ? "loading"
  : isError && !data          ? "error"
  : memories.length === 0 && isFilterActive ? "filtered-empty"
  : memories.length === 0     ? "empty"
  :                             "loaded";

// Note: we do NOT pass isFetching. Background refetch is silent by
// design — the rows on screen are already accurate (see 35c).
return (
  <DataSectionCard
    icon={Clock}
    label={t.memoryView.freshMemory.other}
    trailing={<RecentFilterTrigger window={window} actor={actor} />}
    phase={phase}
    isPlaceholderData={phase === "loaded" && isPlaceholderData}
    emptyCopy={{
      title: t.memoryView.recentEmptyTitle,
      hint:  t.memoryView.recentEmptyHint,
    }}
    filteredEmptyCopy={{
      title: t.memoryView.recentFilteredTitle,
      hint:  t.memoryView.recentFilteredHint,
      clearLabel: t.memoryView.clearFilters,
      onClear: resetFilters,
    }}
    errorCopy={{
      title:      t.memoryView.recentErrorTitle,
      detail:     t.memoryView.recentErrorDetail,
      retryLabel: t.memoryView.recentErrorRetry,
      onRetry:    () => refetch(),
    }}
  >
    {visible.map((m, i) => (
      <MemoryRow
        key={getRecentRenderKey(m.id)}
        memory={m}
        surface="recent"
        showDivider={i > 0}
        isNew={recentlyArrived.has(m.id)}
      />
    ))}
    {(hasMore || expanded) && (
      <footer className="border-t border-border/30 px-4 py-2.5 flex items-center justify-center gap-4">
        {expanded && (
          <button onClick={() => setVisibleCount(RECENT_PREVIEW_LIMIT)}>
            {t.memoryView.collapseRecent}
          </button>
        )}
        {canLoadMore && (
          <button
            disabled={isFetchingNextPage}
            onClick={async () => {
              const target = visibleCount + 5;
              if (target > memories.length && hasNextPage && !isFetchingNextPage) {
                await fetchNextPage();
              }
              setVisibleCount((n) => n + 5);
            }}
          >
            {isFetchingNextPage
              ? t.memoryView.loadingMore
              : interpolate(t.memoryView.loadMoreRecent, { n: String(nextIncrement) })}
          </button>
        )}
      </footer>
    )}
  </DataSectionCard>
);

Structured code blocks for the most common patterns. Copy directly into new components.

<div className="w-full px-4 py-2.5 hover:bg-surface-1 transition-colors border-t border-border/30">
  <div className="flex items-center gap-2">
    <span className="h-1.5 w-1.5 rounded-full" style={{ background: dotColor }} />
    <span className="text-[14px] font-medium text-foreground truncate flex-1">{title}</span>
    <span className="text-[13px] text-fg-3 tabular-nums">{meta}</span>
  </div>
  <p className="text-[13px] text-fg-3 truncate mt-0.5 pl-5">{summary}</p>
</div>

<div>
  <div className="flex items-center gap-1.5 mb-3">
    <span className="text-[12px]" style={{ color: "var(--signature)" }}>✦</span>
    <span className="text-[13px] text-fg-3">memax summary</span>
  </div>
  <div className="text-[16px] text-fg-1 leading-[1.65]">{summary}</div>
</div>

<div className="flex items-center justify-between py-3">
  <div>
    <span className="text-[14px] text-fg-1">{label}</span>
    <p className="text-[12px] text-fg-3">{description}</p>
  </div>
  <Button variant="outline" size="sm">{action}</Button>
</div>

<div className="pb-36 md:pb-32 animate-content-ready" style={{ paddingTop: CONTENT_TOP }}>
  <div className="mx-auto max-w-4xl px-5 sm:px-8">
    {/* Page content */}
  </div>
</div>

<span className="text-[10px] text-fg-3 uppercase tracking-wider font-semibold">
  {groupLabel}
</span>

<div className="flex flex-col items-center justify-center text-center" style={{ minHeight: CENTERED_HEIGHT }}>
  <p className="text-[16px] text-fg-2 mb-2">{message}</p>
  <p className="text-[13px] text-fg-3">{hint}</p>
</div>

One scan anchor per row. In a feed or list, the title is the only thing the eye is allowed to latch onto. If the summary renders inline **bold** or `code`, every row sprouts a second anchor that fights the title, and scannability collapses. This is why Gmail, Linear, Notion, Apple Mail, and Readwise all render list previews as flat plain text and save rich markdown for the detail view.

Recent is attribution-rich. Desktop keeps the actor name and, when a tool captured on their behalf, shows the agent icon inline before the agent name. Mobile drops the name for team and agent rows. Plain personal rows collapse to the compact artifact layout instead of showing `saved` next to a file icon.

Topic rows answer “what is in this topic?” Explicit non-self actors move to the trailing edge, so the left side stays content-led and the title reads first.

Same primitive, four sizes. Decide at a glance before touching production.

Decide at feed length, not at single-row zoom. `md18` and `md20` rendered with the same 12-row dataset.

Baseline row anatomy for page-level topic layouts. The full attribution and responsive rules live in section 04. Use this section to validate page composition, spacing, and section hierarchy.

If kind is fully removed, what anchors the left side? Comparing: title-only, content-type icon, and tags-inline. Agent/team attribution tiers are unaffected (they already don't use kind).

These examples are retained as visual references, but section 04 is the source of truth for the row system and attribution behavior.

The clean stacked attribution is the chosen direction for `recent`. Recall stays compact. Topic rows stay icon-only and quiet.

Topic rows are intentionally quiet: icon or avatar only, then title and summary. No name, no `via`, no `captured` copy.

Text → neutral dot · PDF → FileText icon · Image → ImageIcon · Link → LinkIcon. Personal indicators stay quiet and non-semantic.

Same memory rendered on each surface. The canonical rule matrix lives in section 04; this page-level demo keeps the topic layout grounded in those rules.

Universal across all surfaces. ✦ breathes with signature color. No summary, no tags, no meta — just title + status.

Full layout: page header → Recent section (Clock, dropdown time filter, Select) → topic cards grid → inbox (Inbox icon, count). Gap-3 consistent spacing.

Team-hub recent uses the same canonical `recent` row behavior from section 04: stacked attribution, human-first wording, and copy action in the row meta.

Recent, Inbox, Topic detail memory list, and Recall results are all task-oriented lists → progressive disclosure wins for all four. The current production infinite-scroll fallback in RecentSection is the exception to fix.

Inbox behavior differs by plan. Free users wait for nightly dream cycle. Pro users can trigger organization immediately. During organization, ✦ breathes and rows show progress.

Inside a topic. Breadcrumb → header with AI description → subtopic sections → “Other” section for ungrouped memories. No kind tabs (kind deprecated from UI). Rows use surface="topic": summary visible, edge-to-edge (px-4, no wrapper padding).

Blue-green deploys, rollback procedures, staging automation, and CI/CD pipeline configuration for Fly.io.

Leaf topic (no subtopics). Description shown under header. Memories in a single flat card. No kind tabs.

Error handling conventions, context propagation rules, interface design principles, and goroutine lifecycle patterns.

Cards show AI description for leaf topics and subtopic names for parents. No extra taxonomy indicators. Description comes from dream engine. h-full + flex-col pins age to bottom for consistent card height.

Cards are the right container. Problem: current cards look generic. Fix: AI description always visible, ✦ for dream signal, content preview for scent. Three options below.

No summary → content at text-fg-1 directly. No ✦, no disclosure. No topic → no siblings. recalled 0× → hidden. Cleanest possible page.

Processing: ✦ slow-breathe centered on --background. Provenance visible. No Surface card needed.

Skeleton mirrors the borderless layout exactly: back button area → provenance line → content lines → footer tags. All on --background. Uses bg-foreground/[0.07] + animate-pulse with staggered delays. Transitions to loaded via animate-content-ready.

Error: back button visible (escape route). Centered message + retry on --background. Red dot (destructive), text-fg-2 message, text-fg-3 hint, ghost retry button.

Skeleton → content uses animate-content-ready on the content wrapper. 0.15s opacity 0→1 + translateY 6px→0.

MANDATORY for every loading→loaded swap. No pop-in without animation. Skeleton shapes must match loaded layout exactly.

MemoryStickyHeader component. Fixed z-40, fades in on scroll via IntersectionObserver. mask-image dissolve at bottom. Shows recall count when ≥10 (activity signal in compact form). Extracted as reusable component.

Forget left (destructive, requires movement), Keep right (safe, cursor already there). Navigation cancels.

Mobile: identical design, not "narrower desktop." Back above title. No pl-8 (no back button inline). Provenance wraps. Same borderless surface as desktop now.

0=hidden, 1-9=fg-3, 10-49=fg-2 medium, 50+=fg-1 medium. Typographic weight only, no color.

Each section header has a trailing slot (right side, after spacer). “Select” lives there as subtle text. Tapping it enters selection mode — indicators morph to rings, toolbar appears. “Done” exits. Same pattern on every surface. In production, the current row indicator stays in the same slot and morphs there; it should never hard-swap to a disconnected checkbox.

Alternative entries: long-press (mobile, 500ms), shift+click (desktop range select). Both auto-enter selection mode.

The h-3 w-3 indicator container morphs with spring easing. No checkbox slides in. The row's own indicator slot becomes the selection affordance, then returns to its native icon on exit.

End-to-end: “Select” enters mode → indicators morph to rings → tap rows to select → checks appear → “Done” exits back to the native row indicator.

“Move” opens a glass picker above the toolbar. Topics with emoji icons. Tap topic → memories move → rows animate out → toast “3 → Deployment” → selection clears.

Picker anchored to Move button, opens upward. Click outside or Esc closes. Same glass treatment as bar expand slot.

Same toolbar container. Actions collapse, destructive confirmation appears. Glassmorphism destructive treatment (kitchen 03). Forget LEFT, Keep RIGHT (cursor safety — cursor was on Forget, Keep appears where cursor is).

Long-press (500ms, haptic feedback) enters selection on mobile. “Select” text still available in header. Compact toolbar: icons only, same glass treatment. Fixed above safe area.

Every batch action follows the same state machine. No dead states, no silent failures.

Glass container, five zones stacked top-to-bottom. Zones ②③ can be empty but never reorder. Zone ⑤ (hint bar) only appears when the result surface is open and on desktop.

The bar’s resting position is unchanged from production: 42vh centered on /home, 32px-from-bottom on /memories and overlay routes, above-dock on mobile. Same fade-in / fade-out animation as today. What changes is the engaged position — once real interaction exists, the bar animates to top 24vh (center-upper) with the existing 0.45s spring. Result surface caps at max-h-[60vh] with a “+ N more” affordance at the bottom of zone ④. On esc the bar returns to its rest position.