Telegram Bot UX Design System

/aiobot rework

Goal: audit and fully rebuild the UX of an existing bot to match this design system.

1. Scan the entire project — find all handlers, dialogs, keyboards, state groups.
2. Compare each pattern against this design system. Build a gap report:
   • Navigation: is RESET_STACK used for top-level? Are detail views pushed?
   • Pagination: manual _paginate() + dialog_data or something else?
   • Input flows: step-per-screen? Validation without advancing? Message cleanup?
   • Multi-select: toggle component with emoji checkboxes?
   • Feedback: callback.answer() on every click? Correct hierarchy?
   • Callback data: namespaced category:action:id?
   • Error handling: stale buttons, empty states, missing context?
   • i18n: string constants or hardcoded text?
3. Present the gap report to the user. Do not change code yet.
4. After user confirms, create .aiodesign/ structure if it doesn't exist. Write wireframes for all existing screens.
5. Rewrite screen by screen, starting from navigation model and working inward. Update wireframes and add bidirectional references.
6. After each screen rewrite, verify against the Screen Composition Checklist.

/aiobot partial-rework

Goal: rework a specific part of an existing bot's UX.

The user specifies what to rework — a single dialog, a component type, or a pattern. Examples:

• /aiobot partial-rework "переделай пагинацию в catalog.py"
• /aiobot partial-rework "добавь multi-select фильтр в список товаров"
• /aiobot partial-rework "проверь callback data на коллизии"

1. Read the target file(s) or scan for the target pattern.
2. Compare current implementation against the relevant section of this design system.
3. Show the user what will change and why (brief diff summary).
4. After user confirms, apply the changes.
5. Verify the changed screens against the Screen Composition Checklist.

1. Wireframe Notation & .aiodesign/ Project Structure

Overview

Every project using this design system maintains a .aiodesign/ folder — a set of text wireframes that describe every screen, reusable component, and user flow. Wireframes are the source of truth for UX intent: they describe what the user sees and can do, not how the code implements it.

When the agent builds or modifies a dialog, the workflow is:

1. Write/update the wireframe in .aiodesign/
2. Implement the code that renders it
3. Add bidirectional references between wireframe and code

Folder Structure

.aiodesign/
├── components/          # Reusable UI blocks (paging, multi-select, etc.)
│   ├── paging.md
│   └── multi-select.md
├── windows/             # Individual screens (one file = one Window)
│   ├── main-menu.md
│   ├── market-list.md
│   └── offer-detail.md
└── flows/               # Multi-screen user journeys
    ├── create-offer.md
    └── onboarding.md

When /aiobot new is invoked, create this folder structure as part of project scaffolding. When /aiobot rework is invoked, generate .aiodesign/ from the existing codebase.

Wireframe Syntax

A wireframe describes one screen (window) or one component using a minimal text notation.

Elements

Layout rules

• Buttons on the same line render in a single row: [ Help ] [ Profile ]
• Buttons on separate lines render in separate rows:

  [ Help ]
  [ Profile ]
  

• Grid layout is indicated by multiple buttons per line:

  [ ☑ USD ]  [ ☐ EUR ]  [ ☑ GBP ]
  [ ☐ JPY ]  [ ☑ CHF ]  [ ☐ AUD ]
  

Example window wireframe (.aiodesign/windows/market-list.md)

Market

< {count} offers available >

< Offer: {give} → {receive}, rate {ratio} >
< Offer: {give} → {receive}, rate {ratio} >
< ... >

[ paging.md ]

+++

[ Filters ]  [ My Offers ]
[ ← Main Menu ]

Component Files

Components are reusable UI blocks that appear in multiple windows. A component file defines states — visual variations depending on context.

Example: .aiodesign/components/paging.md

# Paging

Paginated navigation for lists.