Kalahari Coding Standards

1. Icons

ALWAYS

core::ArtProvider::getInstance().getIcon("cmd_id")
core::ArtProvider::getInstance().createAction("cmd_id", parent)  // for QAction with auto-refresh

NEVER

QIcon("path/to/icon.svg")  // hardcoded path

Available icons

• Location: resources/icons/
• Registered in: icon_registrar.cpp (gui::registerAllIcons())

2. Icon Colors

ALWAYS

QColor primary = core::ArtProvider::getInstance().getPrimaryColor();
QColor secondary = core::ArtProvider::getInstance().getSecondaryColor();
core::ArtProvider::getInstance().setPrimaryColor(QColor("#hex"));
core::ArtProvider::getInstance().setSecondaryColor(QColor("#hex"));

NEVER

QColor(255, 0, 0)  // hardcoded color
Theme::instance().getColor()  // DOES NOT EXIST!

3. Configuration

ALWAYS

auto& settings = core::SettingsManager::getInstance();
std::string value = settings.getValue("key", "default");
settings.setValue("key", "value");

NEVER

// hardcoded configuration values
const int MAX_SIZE = 100;  // should be in settings

4. UI Strings

ALWAYS

tr("User visible text")
tr("Format: %1").arg(value)

NEVER

"Hardcoded string"  // not translatable

5. Themes

ALWAYS

const core::Theme& theme = core::ThemeManager::getInstance().getCurrentTheme();
// Access theme colors:
theme.colors.primary
theme.colors.secondary
theme.palette.toQPalette()
theme.log.info  // log panel colors

Adding New Theme Colors

Use the automated script scripts/add_theme_color.py for adding colors to the theme system.

Basic usage (5 files modified):

python scripts/add_theme_color.py <color_name> <dark_value> <light_value> -d "description"

With Settings UI integration (9 files modified):

python scripts/add_theme_color.py <color_name> <dark_value> <light_value> -d "description" -l "Label" -s

Parameters:

• color_name: camelCase name (e.g., infoPrimary)
• dark_value: hex color for Dark theme (e.g., #6B9BD2)
• light_value: hex color for Light theme (e.g., #3D6A99)
• -d/--description: description for C++ comments
• -l/--label: display label in Settings UI
• -s/--add-to-settings: add to Settings dialog UI

Files modified by script:

• resources/themes/Dark.json - dark theme color value
• resources/themes/Light.json - light theme color value
• include/kalahari/core/theme.h - QColor member in Theme struct
• src/core/theme.cpp - fromJson/toJson serialization
• src/core/theme_manager.cpp - fallback, applyColorOverrides, setColorOverride
• (with -s): settings_data.h, settings_dialog.h, settings_dialog.cpp, main_window.cpp

Example:

python scripts/add_theme_color.py htmlHeading "#4A90D9" "#2E5C8A" -d "HTML heading color" -l "Heading" -s

NEVER add theme colors manually - always use the script to ensure consistency across all 5-9 files.

6. Logging

ALWAYS

core::Logger::getInstance().info("Message: {}", value);
core::Logger::getInstance().debug("Debug: {}", value);
core::Logger::getInstance().warn("Warning: {}", value);
core::Logger::getInstance().error("Error: {}", value);

Levels

• trace, debug, info, warn, error, critical

7. Layouts (Qt6)

Basic patterns

QVBoxLayout* mainLayout = new QVBoxLayout(this);
QHBoxLayout* rowLayout = new QHBoxLayout();
QGroupBox* group = new QGroupBox(tr("Title"));

Stretch factors

• 0 = fixed size
• 1+ = flexible, fills available space

Clearing layouts (ALWAYS use utility)

#include "kalahari/gui/utils/layout_utils.h"

// ALWAYS - properly handles nested layouts
kalahari::gui::utils::clearLayout(m_contentLayout);

// NEVER - leaks nested layouts
while (QLayoutItem* item = layout->takeAt(0)) {
    delete item->widget();
    delete item;
}

8. Build

Windows

scripts/build_windows.bat Debug

Linux

scripts/build_linux.sh

NEVER

• cmake directly
• WSL for Windows builds

9. Naming Conventions

Type	Convention	Example
Files	snake_case	character_card.cpp
Classes	PascalCase	CharacterCard
Methods	camelCase	getTitle()
Members	m_prefix	m_title
Constants	UPPER_SNAKE_CASE	MAX_CHAPTERS
Namespaces	lowercase	kalahari::core

10. Singletons Reference

Class	Access Method	Namespace
ArtProvider	getInstance()	kalahari::core
SettingsManager	getInstance()	kalahari::core
ThemeManager	getInstance()	kalahari::core
IconRegistry	getInstance()	kalahari::core
Logger	getInstance()	kalahari::core
CommandRegistry	getInstance()	kalahari::gui

11. MCP Tools for Code Intelligence

Use for understanding and navigating Kalahari codebase:

When to use:

• Before modifying any file → understand structure
• Before creating new class → find similar patterns
• Before refactoring → find all usages

Context7 (External Docs)

Use for Qt6 and other library documentation:

mcp__context7__resolve-library-id("Qt6")           # get library ID (once)
mcp__context7__get-library-docs("/qt/qtdoc", topic="QDockWidget")

When to use:

• Unsure about Qt6 API parameters
• Need to know available signals/slots
• Checking Qt6 best practices

Tool Selection Guide

Need	Tool
Qt6 API reference	Context7
Qt6 signals/slots	Context7
External library docs	Context7