UX Design System for building Telegram bot interfaces with aiogram 3.x + aiogram-dialog. Defines how to structure navigation, pagination, data input flows, multi-select, feedback, and error handling in chat-based UI. Use this skill whenever building or extending a Telegram bot — whether the user mentions "telegram bot", "aiogram", "dialog", "bot screen", "bot menu", "inline keyboard", "pagination", "bot flow", or asks to "add a screen", "create a form", "build a list view". Also triggers on commands: /aiobot, /aiobot new, /aiobot rework, /aiobot partial-rework. This is a UX reference that teaches the agent how to think about chat-based interfaces so the output follows a consistent, production-tested design language.
This document defines a design system for building Telegram bot interfaces. It is the product of iterating on a production bot and describes how users interact with the bot — navigation, data display, input collection, feedback, and error recovery.
The technical foundation is aiogram 3.x (bot framework) + aiogram-dialog 2.x (stateful dialog windows), but the UX principles apply broadly to any chat-based UI.
When building any Telegram bot feature, consult the relevant section below. For widget-level API details, read references/widgets.md. For implementation patterns (middlewares, repos, config), read references/implementation.md.
This skill supports three commands. When invoked, follow the corresponding workflow.
/aiobot newGoal: scaffold a new bot project that follows this design system from the start.
.aiodesign/ folder structure (components/, , ).windows/flows/.aiodesign/windows/, reusable components in components/, and user journeys in flows/.references/implementation.md (dispatcher, routers, middlewares, config, repos).# UX: .aiodesign/windows/<file>.md comments. Add ## References sections to wireframes.setup_dialogs(), middleware chain, reply keyboard./aiobot reworkGoal: audit and fully rebuild the UX of an existing bot to match this design system.
_paginate() + dialog_data or something else?category:action:id?.aiodesign/ structure if it doesn't exist. Write wireframes for all existing screens./aiobot partial-reworkGoal: 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 на коллизии".aiodesign/ Project StructureEvery 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:
.aiodesign/.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.
A wireframe describes one screen (window) or one component using a minimal text notation.
| Syntax | Meaning | Example |
|---|---|---|
< text > | Dynamic text (rendered from data) | < You have {count} offers > |
[ Button ] | Tappable button | [ ← Back ] |
[ component.md ] | Reference to a reusable component | [ paging.md ] |
+++ | Separator between content and button area | +++ |
### | Screen boundary (separates multiple screens in a flow) | ### |
| Plain text | Static text, title, label | Select a currency: |
[ Help ] [ Profile ][ Help ]
[ Profile ]
[ ☑ USD ] [ ☐ EUR ] [ ☑ GBP ]
[ ☐ JPY ] [ ☑ CHF ] [ ☐ AUD ]
.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 ]
Components are reusable UI blocks that appear in multiple windows. A component file defines states — visual variations depending on context.
.aiodesign/components/paging.md# Paging
Paginated navigation for lists.