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

```typescript
// 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

```jsx
<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

```jsx
<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](https://www.w3.org/WAI/WCAG21/quickref/) for complete accessibility guidelines.

## Resources

- Original inspiration: `jarvis-brain/docs/DESIGN-PRINCIPLES.md`
- Color palette: [Tailwind CSS Colors](https://tailwindcss.com/docs/customizing-colors)
- Icon set: Unicode emojis (universal support)

## Examples from Codebase

### Good Example: Task List

```tsx
// 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.