Aether/CLAUDE.md

Aether Project Rules for Claude Code

You are working on Project Aether — a beautiful, fast, native open-source Qt 6 client for the self-hosted Stoat backend.

Non-negotiable rules (always follow):

• Every source file (.cpp, .qml, CMakeLists.txt) must start with the exact AGPL-3.0 SPDX header:

  // SPDX-License-Identifier: AGPL-3.0-or-later
  // Copyright (C) 2026 Aether Contributors
  //
  // This file is part of Aether.
  //
  // Aether is free software: you can redistribute it and/or modify it
  // under the terms of the GNU Affero General Public License as published
  // by the Free Software Foundation, either version 3 of the License, or
  // (at your option) any later version.
  
  

Keep the modular QML structure: separate files in src/qml/components/, src/qml/styles/, src/qml/utils/. Every QML file must import:qmlimport QtQuick 2.15 import QtQuick.Controls 2.15 import QtQuick.Controls.Material 2.15 import QtQuick.Layouts 1.15 import Aether 1.0

Theme and Constants are singletons — always use Theme.xxx and Constants.xxx. Never hard-code colors, sizes, or fonts. Never use letterSpacing: — always use font.letterSpacing:. In Repeater delegates, always use named model roles (model.channelId, model.name, etc.) — never modelData. When fixing errors, change only the necessary lines. Do not rewrite whole files unless explicitly asked.

QML Best Practices

Use component for inline reusable items inside a file. Prefer ListModel + named roles over JS arrays for Repeaters. Always wrap Repeater delegates in an Item if you need to pass model properties to custom components. Use Loader or StackView for dynamic content. Keep QML files small and focused (one component per file when possible).

Qt 6 / CMake Rules

Always use qt_add_qml_module with proper URI Aether. Singletons must have pragma Singleton + set_source_files_properties(..., QT_QML_SINGLETON_TYPE TRUE). Use Qt 6.8+ minimum in CMake. Never hard-code paths.

Resources & Assets

All icons, images, fonts go in resources/. Use Qt Resource System (qrc) for everything. Prefix resource paths with qrc:/qt/qml/Aether/.

C++ Integration (future)

C++ code only in src/cpp/. Expose to QML via QML_ELEMENT, QML_SINGLETON, or context properties. Keep C++ minimal — most logic should stay in QML until performance requires otherwise.

UI/UX Style Guide

Dark Material theme with DeepPurple accent. Use Theme singleton for all colors, spacing, radii, fonts, animations. Use Constants singleton for layout dimensions. Subtle hover animations (100–180 ms). Clean, modern Discord-like aesthetic.

This is the permanent rule set for Aether. Follow it strictly in every response.