Kalahari Coding Standards

1. Icons

ALWAYS

cpp

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

NEVER

cpp

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

Available icons

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

2. Icon Colors

ALWAYS

cpp

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

cpp

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

3. Configuration

ALWAYS

cpp

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

NEVER

cpp

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

4. UI Strings

ALWAYS

cpp

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

NEVER

cpp

"Hardcoded string"  // not translatable

5. Themes

ALWAYS

cpp

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):

bash

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

With Settings UI integration (9 files modified):

bash

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:

bash

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

cpp

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

cpp

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)

cpp

#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

bash

scripts/build_windows.bat Debug

Linux

bash

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:

code

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:

code

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