Skip to content

Add UX context and development documentation system #734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ldstreet wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Add UX context and development documentation system #734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Maple Development Guide

This repository contains the Maple AI assistant frontend - a cross-platform desktop and mobile application built with Tauri, React, and TypeScript.

## Tech Stack
- **Frontend**: React 19, TypeScript, TanStack Router, TanStack Query
- **UI**: Tailwind CSS, shadcn/ui components
- **Desktop**: Tauri (Rust backend)
- **Build**: Bun for package management and bundling
- **Mobile**: iOS and Android via Tauri mobile

## Key Directories
- `frontend/src/components/` - React components
- `frontend/src/routes/` - TanStack Router routes
- `frontend/src/state/` - State management contexts
- `frontend/src-tauri/` - Rust Tauri backend
- `docs/` - Technical documentation

## Common Development Tasks

**Run development server**:
```bash
bun run dev # Web only
bun tauri dev # Desktop app
```

**Build**:
```bash
just desktop-build # Production desktop build
bun tauri build # Direct Tauri build
```

**Format & Test**:
```bash
just format # Format code
just test # Run tests
```

See `README.md` for complete development setup, build instructions, and platform-specific notes.

## Code Quality Standards
- TypeScript strict mode enabled
- Follow existing component patterns (see `frontend/src/components/`)
- Use TanStack Query for server state
- Use context for client state (see `frontend/src/state/`)
- Tailwind CSS for styling (custom Maple design tokens in `--maple-*` CSS variables)
- Accessibility: proper ARIA labels, keyboard navigation, semantic HTML

## Testing Changes
- For UI changes, run the dev server and manually test
- Test both light and dark modes
- Check mobile responsive layouts
- Verify keyboard navigation and screen reader support

## Git Workflow
- Work on feature branches (e.g., `agent/maple-<feature>`)
- Commit with clear, descriptive messages
- Open PRs for review (do not merge to master directly)
- Run pre-commit hooks (see `setup-hooks.sh`)

## State Management Patterns
- **Server state**: Use TanStack Query (`useQuery`, `useMutation`)
- **Local UI state**: Use React state (`useState`, `useReducer`)
- **Shared client state**: Use context (see `LocalStateContext`, `ChatRuntimeContext`)
- **Persistence**: localStorage for user preferences, IndexedDB for larger data

## Platform-Specific Code
Check platform with utilities from `frontend/src/utils/platform.ts`:
```typescript
import { isTauri, isMacOS, isLinux, isIOS, isAndroid } from "@/utils/platform";
```

## Security
- Never commit sensitive keys or credentials
- API URLs via environment variables (`VITE_OPEN_SECRET_API_URL`)
- User data encrypted via OpenSecret SDK
- Tauri security best practices (CSP, allowlist)

## Key Documentation
- `README.md` - Development setup, build instructions, releases
- `MAPLE_UX_CONTEXT.md` - UI feature reference for understanding the Maple app interface
- `docs/` - Technical specifications and architectural decisions
167 changes: 167 additions & 0 deletions DOCUMENTATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
# Maple Documentation Guide

This document explains the purpose of each documentation file in this repository and how they work together to provide context for both developers and the Maple AI assistant.

## Documentation Files

### For Developers

#### `README.md`
**Purpose**: Primary developer documentation
**Audience**: Engineers working on the Maple codebase
**Content**:
- Development setup and prerequisites
- Build instructions for all platforms
- Release process and versioning
- Testing and deployment

**When to read**: Starting development, building releases, troubleshooting setup

#### `AGENTS.md`
**Purpose**: Quick reference for AI agents working on the codebase
**Audience**: AI assistants (Claude, etc.) in development mode
**Content**:
- Tech stack overview
- Key directories and file structure
- Common development commands
- Code quality standards
- Git workflow

**When loaded**: Automatically by AI development tools (e.g., Claude Code) when working on this repository

### For Maple AI Assistant Context

#### `MAPLE_SYSTEM_INSTRUCTION.md`
**Purpose**: Concise system instruction for the Maple assistant
**Audience**: Maple AI when assisting end-users in conversations
**Content**:
- Interface detection rules (app vs API/proxy)
- Core UI features (web search, uploads, projects)
- When to reference UI vs capabilities
- Concise guidance for common scenarios

**How to use**:
1. Users can add this as a custom system prompt in Maple Settings → Preferences → "Default system prompt"
2. Copy the content into the system prompt field
3. Save preferences
4. The instruction will be included in all new conversations

**Format**: Designed to be copy-pasted directly into the preferences UI

#### `MAPLE_UX_CONTEXT.md`
**Purpose**: Comprehensive technical reference for Maple's UI
**Audience**: AI assistants, developers needing detailed UI implementation info
**Content**:
- Detailed feature descriptions with code references
- Implementation details and file locations
- Visual states and styling information
- Platform-specific differences
- Feature availability matrix

**When to read**:
- When assistant needs detailed UI information
- When updating UI features (to keep docs current)
- When debugging UI-related issues

**Not loaded automatically**: Too large for system prompt; used as reference documentation

#### `docs/` Directory
**Purpose**: Technical specifications and architectural decisions
**Content**: Detailed implementation docs for specific features
- `product-redesign-spec.md`
- `unified-chat-refactor.md`
- `pdf-ocr.md`
- `conversations-api-implementation.md`
- And more...

## How They Work Together

### Development Scenario
1. Developer opens the Maple repo
2. AI assistant reads `AGENTS.md` (lightweight, automatically loaded)
3. For detailed UI info, assistant references `MAPLE_UX_CONTEXT.md`
4. For specific features, assistant reads relevant `docs/*.md` files

### User Conversation Scenario

**Option 1: User adds system instruction manually**
1. User opens Maple Settings → Preferences
2. User copies content from `MAPLE_SYSTEM_INSTRUCTION.md`
3. User pastes into "Default system prompt" field
4. User saves preferences
5. All new conversations include this context

**Option 2: Default installation (future)**
- Maple could ship with `MAPLE_SYSTEM_INSTRUCTION.md` pre-loaded as a default instruction
- Would require backend changes to include it in system prompt automatically

### Agent Mode (Desktop App)
- Agent Mode uses Goose's skills system
- Automatically discovers `.claude/` directory in project roots
- `AGENTS.md` in a project root is loaded as development context
- No manual configuration needed

## File Size Considerations

| File | Size | Purpose | Loading |
|------|------|---------|---------|
| `AGENTS.md` | ~2KB | Quick dev reference | Auto (AI tools) |
| `MAPLE_SYSTEM_INSTRUCTION.md` | ~3KB | Concise user context | Manual copy-paste |
| `MAPLE_UX_CONTEXT.md` | ~15KB | Detailed UI reference | Reference only |
| `README.md` | ~12KB | Full dev guide | Manual read |

**System Prompt Budget**: Most LLM system prompts have ~8-16KB budget. `MAPLE_SYSTEM_INSTRUCTION.md` fits comfortably, while `MAPLE_UX_CONTEXT.md` is reference material consulted as needed.

## Maintaining These Files

### When to Update

**Update `MAPLE_SYSTEM_INSTRUCTION.md` when**:
- Core UI features are added/removed/moved
- Default behaviors change (e.g., web search default)
- New platform support added
- User-facing capabilities change

**Update `MAPLE_UX_CONTEXT.md` when**:
- Implementation details change
- Code references need updating (file paths, line numbers)
- Visual states or styling changes
- Platform-specific behavior changes
- New settings sections added

**Update `AGENTS.md` when**:
- Tech stack changes
- Build process changes
- New development patterns emerge
- Git workflow changes

### How to Update

1. **Test the actual UI** in a development build
2. **Verify code references** (file paths, line numbers, component names)
3. **Update the relevant file(s)**
4. **Check consistency** between MAPLE_SYSTEM_INSTRUCTION.md (concise) and MAPLE_UX_CONTEXT.md (detailed)
5. **Commit with clear description** of what changed and why

### Version Tracking

These docs reflect the Maple UX as of **August 2024**. Consider adding version markers when making significant updates:

```markdown
<!-- Last updated: September 2024 - Added new feature X -->
```

## Future Improvements

**Potential enhancements**:
1. **Auto-loading system instruction**: Backend support to include `MAPLE_SYSTEM_INSTRUCTION.md` automatically
2. **Versioned documentation**: Track docs against Maple version releases
3. **Interactive documentation**: In-app help that references these guides
4. **Automated updates**: Scripts to extract UI structure from codebase
5. **Documentation tests**: Verify code references are still accurate

## Questions?

- **For development**: See `README.md` or ask in the project repository
- **For UI features**: See `MAPLE_UX_CONTEXT.md` for detailed technical info
- **For user guidance**: See `MAPLE_SYSTEM_INSTRUCTION.md` for what to tell users
98 changes: 98 additions & 0 deletions MAPLE_SYSTEM_INSTRUCTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Maple Assistant Context

You are the Maple AI assistant. This instruction provides context about the Maple application interface when users interact with you through the Maple app.

## Interface Detection

**IMPORTANT**: Only reference Maple UI features when the user is clearly using the Maple desktop or mobile app. If the user mentions "API", "proxy", "CLI", or similar, they are NOT using the Maple app interface.

When uncertain, ask: "Are you using the Maple app, or accessing via API/proxy?"

## Maple App UI Features

When the user IS in the Maple app, you can reference these UI controls:

### Web Search Toggle
- **Icon**: Globe icon in the composer toolbar (bottom of chat)
- **Function**: Enable/disable web search for messages
- **Default**: Enabled for all users
- **States**:
- Active: Globe icon in primary color
- Inactive: Globe icon in secondary color
- **How to use**: "Click the globe icon to toggle web search"

### File Uploads
- **Icon**: Plus (+) icon in composer toolbar
- **Opens**: Attachment menu with two options

**Add Images**:
- Upload photos, screenshots, diagrams
- Requires vision-capable model
- Disabled during response generation
- Desktop, web, and mobile support

**Add Document**:
- Upload PDF files (with OCR on desktop)
- Desktop app: Full support
- Web version: Prompts to use desktop app
- Mobile: Platform-dependent

### Project Picker
- **Icon**: Folder icon in composer toolbar
- **Function**: Organize conversations by project
- **States**:
- No project: Gray folder icon
- Project selected: Colored folder icon with name
- **How to use**: "Click the folder icon to select or create a project"

### Model Selection
Available models:
- **Quick** (`auto:quick`): Fast, everyday responses
- **Powerful** (`auto:powerful`): Deeper thinking, vision-enabled

### Settings
**Location**: App menu → Settings

Available sections:
- **Preferences**: System prompt, chat appearance, text-to-speech
- **Account**: User account management
- **Security**: Security settings
- **Billing**: Subscription management
- **API**: API keys and proxy settings
- **History**: Conversation history

## When NOT in Maple App

If the user is accessing via API, proxy, or CLI, focus on **capabilities** not **UI elements**:

❌ Bad: "Click the globe icon to enable web search"
✅ Good: "I can search the web if web search is enabled in your request"

❌ Bad: "Use the + button to upload images"
✅ Good: "I can analyze images if you include them in your message"

## Response Guidelines

1. **Detect context first**: Understand if user is in Maple app or using API/proxy
2. **Match language to context**: UI references for app users, capability references for API users
3. **Be accurate**: Only reference features that actually exist in the current Maple version
4. **Stay concise**: Brief, helpful guidance without over-explaining

## Platform Differences

**Desktop App (Tauri)**:
- Full document upload with PDF OCR
- Native file system access
- All features available

**Web Version**:
- Limited document upload (redirects to desktop)
- Standard web capabilities
- All image features available

**Mobile (iOS/Android)**:
- Touch-optimized interface
- Camera integration for images
- Platform-specific layouts

Remember: Only reference these UI features when the user is in the Maple app. For API/proxy users, describe what's possible without specific UI instructions.
Loading
Loading