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 (✦), never decorative
  NEVER:      text-gray-*, bg-gray-*, hardcoded colors, text-foreground/XX

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, category)
  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" rounded="2xl"> (border only)
  mobile:     <Surface variant="borderless">           (full bleed)
  minimal:    <Surface variant="clean">                (bg only)
  radius:     bar/modal 16px → card 12px → button 8px → nested 6px

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-50, max-w-[640px]
  modal:      z-65 content, z-60 backdrop

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)

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. On=signature, Off=transparent+border

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

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.

Source: lib/category.ts. Colors are frontend-only — backend classifies, frontend renders the dot. Dot size: 6px (w-1.5 h-1.5) in memory rows, 8px (w-2 h-2) in detail view.

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: outer container always has larger radius than inner. Bar/modal 16px → card 12px → button 8px → nested 6px.

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

Rule: bar is z-50, modal is z-60+. Content lives at z-[1-3]. Never use arbitrary z values — pick from this list.

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

<Tag onRemove={fn}>label</Tag>
Source: ui/tag.tsx — bg-surface-1, border-border, rounded-lg, × on hover

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

Off: transparent track, foreground/15 border. On: signature fill, white knob.
Track: w-10 h-6 rounded-full. Knob: w-4.5 h-4.5 rounded-full.

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

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

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

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.

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.

Card appears immediately with content. ✦ replaces category dot 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.

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>

Every memory row: title (bold) + optional summary (muted). No tags at row level. Indicator + meta area adapt by surface/attribution. Hub label in right meta for team memories. Edge-to-edge within card (px-4), no rounded rows, flat dividers.

If category 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 category).

The indicator slot answers “who pushed this?” — not “which category.” Three tiers in priority order. Category dots remain as fallback for personal default only.

Two layout options for team hub memories in the personal “all” view. Compact: inline context, hub in right meta. Clean: attribution line above, title always left-aligned, verbs describe the action.

When no agent/team attribution, the indicator shows content type. Color comes from category (may be deprecated — dot color is the only remaining category signal).

Text → colored dot · PDF → FileText icon · Image → ImageIcon · Link → LinkIcon. All colored by category dot color.

Same memory rendered on each surface. Surface controls which lines appear, which meta is shown, and whether copy is available.

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, “Copy N for AI”) → topic cards grid → inbox (Inbox icon, count). Gap-3 consistent spacing.

In team hub, rows show WHO pushed WHAT. Same MemoryRow component, same surface="recent" — attribution tier auto-selects based on memory data.

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 category tabs (category 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 category tabs.

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

Cards show AI description for leaf topics, subtopic names for parents. No category dots. 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: category dot DNA, 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 — dots morph to rings, toolbar appears. “Done” exits. Same pattern on every surface.

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 dot IS the selection affordance.

End-to-end: “Select” enters mode → dots morph to rings → tap rows to select → toolbar appears → choose action → feedback → “Done” exits.

“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.

All states use 1px border. No border-width changes. Focus adds subtle ring + lift. Active states use notification banner, not border animation.

All barNotification types with their icon, accent color, background, and auto-dismiss behavior. One notification at a time — new replaces old.

Live background previews per type:

Default mode. User types, hits Enter (desktop) or send button (mobile). Textarea auto-expands for multi-line. Enter always newline on mobile.

One bar, two operations. How does the user choose Push vs Recall? Three approaches compared — Option C (floating mode toggle) was chosen and implemented. Desktop uses subtle text, mobile uses pill chips. All share the same visual language (bar tint + button icon change).

Results appear progressively: keyword (0ms) → server FTS (200ms) → semantic (1-3s) → AI synthesis (3-8s, Pro only). User sees results get better over time without waiting.

Push: dark fill (↑ ArrowUp). Recall: signature fill (✦ Sparkles). Loading: spinner replaces icon. Disabled: ghost, /40 opacity.

Mobile Enter always inserts newline — send button is the only way to submit. Textarea auto-expands via field-sizing: content (scrollbar hidden). Mode toggle uses tappable pill chips. Camera/file icon visible when input is empty.

Industry standard (ChatGPT, Claude, iMessage): auto-expand + scroll within bar. No fullscreen compose mode — keeps context visible. Scrollbar hidden via scrollbarWidth: none.

Files are staged above the input row as chips. Multiple files batch into one push. Images from clipboard auto-stage. Drag-drop onto bar. URL paste auto-detects and offers capture.

Notification is a separate fixed element (z-49) behind the bar (z-50). Slides up from behind. Own border-radius, own background. Zero seam line — completely independent DOM elements.

Notification transitions in-place behind bar. Each state replaces the previous — no stacking, no flicker.

Recall has a longer lifecycle. Notification shows during initial search, then dismisses when results take over. AI synthesis is inline in results — no separate notification.

Key rule: notification only during the “Searching” phase. Once results appear, notification dismisses — results are the feedback. AI synthesis uses inline ✦ cursor, not a notification.

Mode toggles float above bar. Desktop: subtle text toggle (“remember · recall”). Mobile: pill chips with icons. Smart detection from detectIntent() auto-suggests mode. User can always override by tapping toggle.

Full-height sticky sidebar. Logo stays fixed (same position always). Tree header aligns with CONTENT_TOP. ChevronsLeft collapses. Content push animated via motion.div width 0↔280. Hover left edge reveals overlay. Persisted.

No toggle button. Hover left edge (12px zone, 150ms delay) reveals overlay. Starts at HEADER_TOP (not full height). » pins to layout flow. Mouse-leave dismisses after 300ms. Backdrop at 8% opacity.

ListTree icon next to “Your Knowledge” page header (right side). Opens bottom sheet overlay with drag handle. Toggle is contextual, not in fixed header.

Tree IS the page content. Tap a topic → detail slides in from right. Back arrow returns. No separate toggle button. No overlay. This is the target pattern for mobile knowledge navigation.

Integrated into existing avatar dropdown (top-right). Single-hub users see no hub section. Multi-hub: hub list appears between user info and theme/lang toggles. Active hub shown with checkmark. Users icon for team hubs. “Create team hub” link at bottom. Current hub name shown in user subtitle.

Team memories show lucide Users + hub name (text-[12px] text-fg-4). Personal memories show no badge (default = no label). Only visible when user has 2+ hubs. Processing row unchanged. Flat dividers, icon containers match production.

Push toast: “Sent — memax will organize.” (personal) or “Sent → hub-name — memax will organize.” (team). Recall results show hub attribution in cross-hub mode. Bar clears immediately after submit (chat-style, no blocking confirmation).

Inline form in settings dialog Account tab, below existing hub list. Name input → auto-generated slug → Create. Hub appears in pill dropdown immediately. Also accessible via dropdown “Create team hub” link.

Click team hub in settings → expands to show members + invite link. Flat row dividers. Role badges. Copy invite link. Owner/admin only. Same Surface pattern as memory detail.

Centered card, same visual language as login. Shows hub name, memory count, member count, inviter. Single CTA. Expired tokens show error state.

Inbox is hub-scoped. Shows unassigned memories for active hub. Clean state uses DREAM_PURPLE ✦. All states match production patterns (Clock/Inbox icons, flat dividers, icon containers).

All states for hub creation: loading (breathing ✦), error (inline message), success (auto-switch + open management). Maps to teams-section.tsx HubCreateForm.

When hub has 1 member (owner) and 0 memories, replace member list with prominent invite CTA. This is the first thing an owner sees after creating a hub.

Four states: not generated (CTA button), generating (breathing ✦), generated (code + copy + expiry), error (inline message). Maps to hub-management.tsx InviteLinkSection.

Logged in: single CTA. Not logged in: “Sign in to join” → OAuth → return to page → auto-accept. Expired/used show error. Accepted shows redirect.

Two-step: button → destructive confirmation with memory count + member impact. “Personal memories are not affected.” After delete: return to list, auto-switch to personal.

Owner/Admin: full management (members + invite + delete). Contributor/Viewer: read-only member list + leave only. Roles affect ACTIONS not VIEWS — all roles see the same memories.

Hub switcher = scope filter. Selection controls BOTH what you see (read) AND where you push (write). “All” is read-only aggregation — push defaults to personal. Single-hub users see no filter UI.

Knowledge page title adapts to active scope. Personal = “Your Knowledge”, Team = “{name}'s Knowledge”, All = “All Knowledge”. Breadcrumb root also adapts.

Bar shows where push goes. Personal scope: no indicator (default). Team scope: hub name pill right of input. All scope: “→ Personal” default, user can tap to change. Push toast always confirms target.

Uses existing bar notification system. Success type, 2s auto-dismiss. Avatar subtitle updates immediately. No new component.

In settings Account tab. Click name → inline edit → save on blur/Enter. display_name is the single source of truth (seeded from OAuth, editable here). Used in attribution rows, settings panel, avatar dropdown.

Inline edit: no modal, no save button. Bottom border appears on hover, solidifies on focus. Save on blur or Enter. PATCH /v1/auth/me with display_name. Optimistic update in useAuth.

Each connected agent gets a unified card. Identity icon with accent color, status dot (active/idle/inactive), stats summary. Expand for API keys, config files, rename, revoke.

User can customize the display name shown in memory attribution and across the app. The agent slug (claude-code) is immutable — set during memax setup. Priority: user custom → AGENT_NAMES map → raw slug.

Three levels of removal: revoke single key, revoke all keys for an agent, or full disconnect (keys + configs). Memories are always preserved — they belong to the user, not the agent.

Status derived from last_usedon API keys. No MCP polling needed — every API call updates the timestamp.

Each agent type gets a unique icon + accent color. Consistent across attribution, settings, and management surfaces. Icon is mapped from agent_name slug, not user-configurable (keeps visual consistency).

Cards stacked visually. Resolve top card → it flies away, next card springs forward. Stack depth shows remaining count. Interactive demo below.

One component, three tiers based on memory count. Large spans 2 cols on desktop. "N new" uses typographic weight + Dream Violet left accent. Progress bar shows relative size.