BotUI Advisor

BotUI Advisor is a Visual Studio Code extension that analyzes chatbot user interfaces and identifies usability issues based on conversational interface design guidelines.

The extension helps developers improve the quality of chatbot interfaces by automatically detecting common design problems directly in the development environment.

BotUI Advisor was developed as part of the master's thesis:

“Usability Optimierung für das grafische Chatbot-Interface – Ein VS Code Plugin für Entwickler:innen”
Technische Universität Chemnitz.

Features

Chatbot UI Analysis

BotUI Advisor analyzes chatbot interfaces and detects usability issues using rule-based checks derived from findings in current conversational UI research.

The extension inspects the implementation of chatbot components and interaction patterns to identify common problems.

Examples include:

• missing typing indicators
• unclear bot identity
• weak repair messages
• missing clickable affordances
• poor message readability
• lack of interaction feedback

Interactive Rule Explorer (Webview)

BotUI Advisor includes an interactive Webview that provides detailed information about conversational UI rules, including implemented checks and rules planned for future versions.

The Webview provides:

• explanations of each usability rule
• examples of good implementations
• rule categories and severity levels
• additional context for developers

This allows developers to understand not only what problem occurred, but also why it matters and how to fix it.

Requirements

To use BotUI Advisor, the following requirements must be met:

Visual Studio Code

BotUI Advisor requires Visual Studio Code 1.108.0 or newer.

React + TSX Chatbot Project

BotUI Advisor currently focuses on chatbot interfaces implemented in React TSX projects.

Because the analysis relies on React component structures and TSX-based UI patterns, the extension may not work correctly for:

• non-React chatbot implementations
• plain JavaScript web applications
• other frontend frameworks such as Angular or Vue

Support for additional frameworks may be added in future versions.

Entry File Requirement

BotUI Advisor currently expects the analysis to be started from the main application entry file.

The command Run BotUI Advisor must be executed while one of the following files is open:

• main.tsx
• index.tsx

These files are typically the entry points of React applications and allow the extension to resolve the root chatbot component.

If the command is executed from another file, BotUI Advisor will display an error message and the analysis will not start.

Support for additional entry file detection may be added in future versions.

Running Chat Application (for Runtime Checks)

Some BotUI Advisor checks analyze the chatbot interface at runtime.

For these checks to work, your chat application must be running locally.

By default, the extension expects the application to be available at:

http://localhost:5173

If your application runs on a different port or URL, you can change the setting:

botui.runtimeUrl

in the VS Code settings.

Playwright Runtime Environment

BotUI Advisor uses Playwright for runtime-based checks.

In some environments, Playwright browser binaries may need to be installed manually:

npx playwright install

Usage

1. Open a chatbot UI project in VS Code
2. Run the BotUI Advisor analysis
3. Review diagnostics displayed in the editor
4. Open the rule explorer Webview for detailed explanations

Commands

Commands can be accessed through the Command Palette: Ctrl + Shift + P

Technologies

BotUI Advisor is built using:

• TypeScript
• VS Code Extension API
• ts-morph (AST analysis)
• PostCSS (CSS analysis)
• Playwright (runtime analysis)

License

This project is licensed under the MIT License.