docs: Restructure documentation with Bookstack-compatible hierarchy
- Organized docs into numbered shelf/book/chapter/page structure - Created comprehensive README.md with project overview - Added Getting Started book (quick start, installation, configuration) - Added Development book (workflow, testing, type sharing) - Added Architecture book (design principles, PDA-friendly patterns) - Added API Reference book (conventions, authentication) - Moved TYPE-SHARING.md to proper location - Updated all cross-references in main README - Created docs/README.md as master index - Removed old QA automation reports - Removed deprecated SETUP.md (content split into new structure) Documentation structure follows Bookstack best practices: - Numbered books: 1-getting-started, 2-development, 3-architecture, 4-api - Numbered chapters and pages for ordering - Clear hierarchy and navigation - Cross-referenced throughout Complete documentation available at: docs/README.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
361
docs/3-architecture/3-design-principles/1-pda-friendly.md
Normal file
361
docs/3-architecture/3-design-principles/1-pda-friendly.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# 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.
|
||||
29
docs/3-architecture/README.md
Normal file
29
docs/3-architecture/README.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Architecture
|
||||
|
||||
Technical architecture and design principles for Mosaic Stack.
|
||||
|
||||
## Chapters
|
||||
|
||||
1. **Overview** — System design and component architecture
|
||||
2. **Authentication** — BetterAuth integration and OIDC flow
|
||||
3. **Design Principles** — PDA-friendly patterns and UX guidelines
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
- **Type Safety First:** Shared types prevent frontend/backend drift
|
||||
- **Multi-Tenant Ready:** Row-level security with workspace isolation
|
||||
- **PDA-Friendly:** Calm, stress-free language and visual design
|
||||
- **Modular:** Plugin architecture for extensibility
|
||||
|
||||
## Technology Decisions
|
||||
|
||||
Key architectural choices and their rationale:
|
||||
- **BetterAuth** over Passport.js for modern authentication
|
||||
- **Prisma ORM** for type-safe database access
|
||||
- **Monorepo** with pnpm workspaces for code sharing
|
||||
- **PostgreSQL + pgvector** for AI-ready data storage
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Review **API** for implementation details
|
||||
- Check **Development** for workflow standards
|
||||
Reference in New Issue
Block a user