wehub-resource-sync
2.7 KiB
Agent-First UI Design Philosophy
Guiding principle for all OpenClacky UI and feature design.
Core Principle
Conversation first, interactive cards when needed.
Users interact with the Agent through natural language to accomplish everything. When conversation is inconvenient for structured input (e.g. dropdowns, multi-select, precise time picking), the Agent triggers an interactive card via the request_user_feedback tool — rendered by the frontend as a structured UI component. Cards are a complement to conversation, not a replacement.
Two Interaction Modes
1. Conversation (default)
User expresses intent in natural language, Agent understands and executes.
User: Send me a daily standup summary every morning at 9
Agent: Done! Task created, runs Mon–Fri at 09:00 ✅
2. Interactive Cards (when conversation falls short)
When the Agent needs structured input that's hard to express in free text, it calls request_user_feedback. The frontend renders this as an interactive card (dropdowns, radio buttons, time pickers, etc.).
Agent calls request_user_feedback → frontend renders a card:
┌─────────────────────────────┐
│ 📋 Confirm task settings │
│ Frequency: [Daily ▼] │
│ Time: [09:00 ] │
│ [✅ Confirm] [Cancel] │
└─────────────────────────────┘
User fills card → structured data sent back to Agent → execution continues
When to Use Cards
| Situation | Reason |
|---|---|
| Choosing from a list of options | Easier than enumerating in chat |
| Date / time selection | Precise value, error-prone in free text |
| Sensitive input like API keys | Should not appear in conversation history |
| Collecting multiple fields at once | One card beats several back-and-forth questions |
Everything else: use conversation.
What Should NOT Exist
- ❌ Persistent configuration form pages
- ❌ Fields that require users to understand technical details (cron expressions, agent IDs, etc.)
- ❌ More than 3 action buttons per list row
- ❌ Standalone "Create" form modals
Role of UI Pages
UI pages are for displaying state, not for configuring things:
- ✅ Show task lists, run history, current status
- ✅ Minimal action set per row: ▶ Run / ✎ Edit (opens conversation) / ✕ Delete
- ❌ No inline create/edit forms inside list pages
Clicking "Edit" opens an Agent conversation with context pre-filled. The Agent drives the modification flow from there.
Applies to all OpenClacky Web UI and feature design.