stack/docs/3-architecture/3-design-principles/1-pda-friendly.md

PDA-Friendly Design Principles

Mosaic Stack is designed to be calm, supportive, and stress-free. These principles are non-negotiable.

Core Philosophy

"A personal assistant should reduce stress, not create it."

We design for pathological demand avoidance (PDA) patterns, creating interfaces that:

• Never pressure or demand
• Provide gentle suggestions instead of commands
• Use calm, neutral language
• Avoid aggressive visual design

Language Guidelines

Never Use Demanding Language

❌ NEVER	✅ ALWAYS
OVERDUE	Target passed
URGENT	Approaching target
MUST DO	Scheduled for
CRITICAL	High priority
YOU NEED TO	Consider / Option to
REQUIRED	Recommended
DUE	Target date
DEADLINE	Scheduled completion

Examples

❌ Bad:

URGENT: You have 3 overdue tasks!
You MUST complete these today!

✅ Good:

3 tasks have passed their target dates
Would you like to reschedule or review them?

❌ Bad:

CRITICAL ERROR: Database connection failed
IMMEDIATE ACTION REQUIRED

✅ Good:

Unable to connect to database
Check configuration or contact support

Visual Design Principles

1. 10-Second Scannability

Users should understand key information in 10 seconds or less.

Implementation:

• Most important info at top
• Clear visual hierarchy
• Minimal text per screen
• Progressive disclosure (details on click)

Example Dashboard:

┌─────────────────────────────────┐
│ Today                           │
│ ─────                           │
│ 🟢 Morning review — 9:00 AM     │
│ 🔵 Team sync — 2:00 PM          │
│                                 │
│ This Week                       │
│ ─────────                       │
│ 🔵 Project planning (3 days)    │
│ ⏸️ Research phase (on hold)     │
└─────────────────────────────────┘

2. Visual Chunking

Group related information with clear boundaries.

Use:

• Whitespace between sections
• Subtle borders or backgrounds
• Clear section headers
• Consistent spacing

Don't:

• Jam everything together
• Use wall-of-text layouts
• Mix unrelated information
• Create visual noise

3. Single-Line Items

Each list item should fit on one line for scanning.

❌ Bad:

Task: Complete the quarterly report including all financial data, team metrics, and project summaries. This is due next Friday and requires review from management before submission.

✅ Good:

Complete quarterly report — Target: Friday

(Details available on click)

4. Calm Colors

No aggressive colors for status indicators.

Status Colors:

• 🟢 On track / Active — Soft green (#10b981)
• 🔵 Upcoming / Scheduled — Soft blue (#3b82f6)
• ⏸️ Paused / On hold — Soft yellow (#f59e0b)
• 💤 Dormant / Inactive — Soft gray (#6b7280)
• ⚪ Not started — Light gray (#d1d5db)

Never use:

• ❌ Aggressive red for "overdue"
• ❌ Flashing or blinking elements
• ❌ All-caps text for emphasis

5. Progressive Disclosure

Show summary first, details on demand.

Example:

[Card View - Default]
─────────────────────────
Project Alpha
12 tasks · 3 approaching targets
🟢 Active
─────────────────────────
[Click to expand]

[Expanded View - On Click]
─────────────────────────
Project Alpha
Description: ...
Created: Jan 15, 2026
Owner: Jane Doe

Tasks (12):
- Setup environment ✓
- Design mockups ✓
- Implement API (target passed 2 days)
[Show all tasks]
─────────────────────────

Implementation Guidelines

Date Display

Relative dates for recent items:

Just now
5 minutes ago
2 hours ago
Yesterday at 3:00 PM
Monday at 10:00 AM
Jan 15 at 9:00 AM

Never:

2026-01-28T14:30:00.000Z  ❌ (ISO format in UI)

Task Status Indicators

// Don't say "overdue"
const getTaskStatus = (task: Task) => {
  if (isPastTarget(task)) {
    return {
      label: 'Target passed',
      icon: '⏸️',
      color: 'yellow',
    };
  }
  // ...
};

Notifications

❌ Aggressive:

⚠️ ATTENTION: 5 OVERDUE TASKS
You must complete these immediately!

✅ Calm:

💭 5 tasks have passed their targets
Would you like to review or reschedule?

Empty States

❌ Negative:

No tasks found!
You haven't created any tasks yet.

✅ Positive:

All caught up! 🎉
Ready to add your first task?

UI Component Examples

Task Card

<TaskCard>
  <TaskTitle>Review project proposal</TaskTitle>
  <TaskMeta>
    <Status icon="🟢">Active</Status>
    <Target>Target: Tomorrow at 2 PM</Target>
  </TaskMeta>
  <TaskActions>
    <Button variant="ghost">Reschedule</Button>
    <Button variant="ghost">Complete</Button>
  </TaskActions>
</TaskCard>

Notification Toast

<Toast variant="info">
  <ToastIcon>💭</ToastIcon>
  <ToastContent>
    <ToastTitle>Approaching target</ToastTitle>
    <ToastMessage>
      "Team sync" is scheduled in 30 minutes
    </ToastMessage>
  </ToastContent>
  <ToastAction>
    <Button>View</Button>
    <Button>Dismiss</Button>
  </ToastAction>
</Toast>

Testing for PDA-Friendliness

Checklist

• No words like "overdue", "urgent", "must", "required"
• Status indicators use calm colors (no aggressive red)
• All-caps text removed (except acronyms)
• Key info visible within 10 seconds
• List items fit on single line
• Details hidden behind "show more" or click
• Notifications are gentle suggestions, not demands
• Empty states are positive, not negative

Review Process

Every UI change must be reviewed for PDA-friendliness:

1. Self-review using checklist
2. Peer review for language and tone
3. User testing with PDA individuals (if possible)

Copy Guidelines

Microcopy

Buttons:

• "View details" not "Click here"
• "Reschedule" not "Change deadline"
• "Complete" not "Mark as done"

Headers:

• "Approaching targets" not "Overdue items"
• "High priority" not "Critical tasks"
• "On hold" not "Blocked"

Instructions:

• "Consider adding a note" not "You must add a note"
• "Optional: Set a reminder" not "Set a reminder"

Error Messages

❌ Blaming:

Error: You entered an invalid email address

✅ Helpful:

Email format not recognized
Try: user@example.com

Accessibility

PDA-friendly design overlaps with accessibility:

• High contrast (but not aggressive colors)
• Clear focus indicators
• Descriptive labels
• Keyboard navigation
• Screen reader friendly

See WCAG 2.1 Level AA for complete accessibility guidelines.

Resources

• Original inspiration: jarvis-brain/docs/DESIGN-PRINCIPLES.md
• Color palette: Tailwind CSS Colors
• Icon set: Unicode emojis (universal support)

Examples from Codebase

Good Example: Task List

// apps/web/components/TaskList.tsx
<div className="space-y-2">
  <h2 className="text-lg font-medium text-gray-900">
    Today
  </h2>
  {tasks.map(task => (
    <TaskCard key={task.id}>
      <div className="flex items-center gap-2">
        <StatusBadge status={task.status} />
        <span className="text-gray-900">{task.title}</span>
      </div>
      {task.targetDate && isPastTarget(task) && (
        <span className="text-sm text-yellow-600">
          Target passed {formatRelative(task.targetDate)}
        </span>
      )}
    </TaskCard>
  ))}
</div>

Enforcement

• Code reviews check for PDA violations
• Linting rules catch forbidden words
• Design review before major UI changes
• User feedback incorporated regularly

This is non-negotiable. If in doubt, make it calmer.