Family Tree Builder UX/UI Plan

This document defines a user-centered redesign of the family tree builder that keeps the database schema unchanged while making creation and connection flows intuitive.

Goals

• Reduce cognitive load; make add person + connect a single, fluid action
• Keep database unchanged; orchestrate in UI/services only
• Provide inline validation to prevent invalid graphs before commit
• Support keyboard and mobile interactions

Principles

• One intent, one flow: adding a person typically implies a connection
• Context-first: actions start from the node the user is focused on
• Draft then apply: stage multiple changes, then commit together
• Low-friction defaults with clear, optional advanced paths

Current Status (2025-10-25)

• Implemented

  • Canvas-level “Add Person” and standalone “Connect People” workflows integrated into D3 RadialLayout
    • Files: src/components/family-trees/layouts/RadialLayout.tsx, src/components/family-trees/FamilyTreeVisualization.tsx
  • Quick add flow: Step 1 “Add Person” (details inlined); “Continue” advances to connect
    • File: src/components/family-trees/QuickAddPersonDialog.tsx
    • Details absorbed into Step 1; previous AddDetailsDialog removed
    • Step header uses numbered circles with shorter connectors; labels exclude “Step X:”
    • Supports add new or add existing
  • Standalone connect flow: source/target/type selection, existing connections table (edit/delete), multi-add, “Done”
    • File: src/components/family-trees/ConnectPeopleDialog.tsx
  • Person card enhancements: Edit Connections dialog, Remove from tree, Delete person (with confirmations)
    • File: src/components/people/PersonCard.tsx
  • Removed the experimental new radial layout and references
    • Deleted: src/components/family-trees/layouts/RadialNewLayout.tsx
    • src/components/family-trees/FamilyTreeVisualization.tsx and src/components/family-trees/layouts/LayoutSwitcher.tsx updated to remove it
  • D3 stability: prevented simulation “jumping” by isolating UI state from the main D3 render effect
    • Kept UI state out of the simulation’s critical useEffect dependencies
  • Modal sizing/overflow: standardized responsive sizes and vertical scrolling

• Not implemented (deferred)

  • On-node quick actions/inline menus (replaced for now by canvas-level actions)
  • Drag-to-connect handles + relationship picker
  • Pending changes drawer (staging)
  • Feature flag treeBuilder.unifiedAddConnect (planned but not wired)
  • Keyboard/long-press touch affordances

Key UX Patterns

1. Add & Connect (two-step chained modals)

• Step 1: Add Person (new or existing), with details inlined
• Step 2: Connect People (multi-add supported; existing connections table with edit/delete)
• Driven by QuickAddPersonDialog → ConnectPeopleDialog
• Step header: numbered circles, dashed connectors, no “Step X:” prefix

2. Canvas-first affordances (current)

• Primary actions on the canvas toolbar: Add Person, Connect People
• Node-level quick actions are deferred to a future iteration to reduce visual noise and avoid D3 reflows

3. Existing connections management

• In Connect modal: existing connections for the selected person shown in a table (edit/delete)
• Multi-add flow with summary and Done

4. Validation posture (initial)

• Basic prevention of duplicates and obvious conflicts via ConnectionService
• Deeper pre-commit validation remains future work

UI Details

• Step header: numbered bullets, short dashed connectors, compact layout
  • File: src/components/family-trees/StepHeader.tsx
• Dialogs:
  • QuickAddPersonDialog: title adapts, details inline, “Continue” CTA
  • ConnectPeopleDialog: includes table of existing connections with actions and “Add New Connection”
• Person card actions (when permitted): Edit Connections, Remove from this tree, Delete
  • Non-blocking confirmations via alert dialogs

Technical Approach (No DB changes)

• Service orchestration only; no schema/RLS changes
• Use existing services:
  • src/services/personService.ts for create/update
  • src/services/connectionService.ts for create/delete with reciprocal handling
• D3 integration:
  • Separate UI state effects from D3 simulation effect to avoid reinitialization on UI interactions

Components & Integration

• Updated/new components
  • QuickAddPersonDialog.tsx (Step 1: Add)
  • ConnectPeopleDialog.tsx (Step 2: Connect, standalone)
  • StepHeader.tsx (reusable step header)
  • PersonCard.tsx (dialog wrapper with actions and connections editor)
• Touch points
  • FamilyTreeVisualization.tsx: removed RadialNewLayout, wired PersonCardDialog
  • layouts/RadialLayout.tsx: canvas actions and dialog orchestration
  • layouts/LayoutSwitcher.tsx: removed “Radial (New)”

Rollout & Flagging

• Planned feature flag: treeBuilder.unifiedAddConnect (not yet wired)
• Suggested phases
  • Phase 1 (MVP, in progress): Canvas actions, Add & Connect dialogs, basic validation
  • Phase 2 (Batch/draft): Pending changes drawer, optimistic UI with temp→real mapping
  • Phase 3 (Polish): Drag-to-connect + relationship picker, overlays, command palette, keyboard/touch

Validation & A11y

• Clear, actionable validation messages (progressively enhanced)
• Focus management across dialogs and tables
• Icon-only controls include labels/ARIA where applicable

Success Metrics

• Median time-to-add-child from a person node
• Steps per completed connect action
• Error rate on connection creation (pre vs post)
• Cancellation rate of the Add & Connect dialog

Out of Scope

• Database schema or RLS changes
• Bulk import tooling
• New layout algorithms

Notes & Decisions

• The “Radial (New)” layout and on-node inline quick-action menus were removed for stability and simplicity; can be revisited with better D3 isolation and a smaller affordance footprint.
• Details were absorbed into Step 1 to reduce modal chaining and confusion.
• The connect workflow is a true standalone modal that can be invoked independently from Add.