ObsidianDragon/.github/copilot-instructions.md

Copilot Instructions — DragonX ImGui Wallet

UI Layout: All values in ui.toml

Every UI layout constant must be defined in res/themes/ui.toml and read at runtime via the schema API. Never hardcode pixel sizes, ratios, rounding values, thicknesses, or spacing constants directly in C++ source files. This is critical for maintainability, theming support, and hot-reload.

Schema API reference

The singleton is accessed via schema::UI() (header: #include "../schema/ui_schema.h").

Method	Returns	Use for
drawElement(section, name)	DrawElementStyle	Custom DrawList layout values (.size, .height, .thickness, .radius, .opacity)
button(section, name)	ButtonStyle	Button width/height/font
input(section, name)	InputStyle	Input field dimensions
label(section, name)	LabelStyle	Label styling
table(section, name)	TableStyle	Table layout
window(section, name)	WindowStyle	Window/dialog dimensions
combo(section, name)	ComboStyle	Combo box styling
slider(section, name)	SliderStyle	Slider styling
checkbox(section, name)	CheckboxStyle	Checkbox styling
separator(section, name)	SeparatorStyle	Separator/divider styling

Section naming convention

Sections use dot-separated paths matching the file/feature:

• tabs.send, tabs.receive, tabs.transactions, tabs.mining, tabs.peers, tabs.market — tab-specific values
• tabs.balance — balance/home tab
• components.main-layout, components.settings-page — shared components
• dialogs.about, dialogs.backup, etc. — dialog-specific values
• sidebar — navigation sidebar

How to add a new layout value

1. Add the entry to res/themes/ui.toml under the appropriate section:

   [tabs.example]
   my-element = {size = 42.0}
   

2. Read it in C++ instead of using a literal:

   // WRONG — hardcoded
   float myValue = 42.0f;
   
   // CORRECT — schema-driven
   float myValue = schema::UI().drawElement("tabs.example", "my-element").size;
   

3. For values used as min/max pairs with scaling:

   // WRONG
   float h = std::max(18.0f, 24.0f * vScale);
   
   // CORRECT
   float h = std::max(
       schema::UI().drawElement("tabs.example", "row-min-height").size,
       schema::UI().drawElement("tabs.example", "row-height").size * vScale
   );
   

What belongs in ui.toml

• Pixel sizes (card heights, icon sizes, bar widths/heights)
• Ratios (column width ratios, max-width ratios)
• Rounding values (FrameRounding, corner radius)
• Thickness values (accent bars, chart lines, borders)
• Dot/circle radii
• Fade zones, padding constants
• Min/max dimension bounds
• Font selection (via schema font name strings, resolved with S.resolveFont())
• Colors (via schema::UI().resolveColor() or color variable references like "var(--primary)")
• Animation durations (transition times, fade durations, pulse speeds)
• Business logic values (fee amounts, ticker strings, buffer sizes, reward amounts)

What does NOT belong in ui.toml

• Spacing that already goes through Layout::spacing*() or spacing::dp()

Legacy system: UILayout

UILayout::instance() is the older layout system still used for fonts, typography, panels, and global spacing. New layout values should use schema::UI().drawElement() instead. Do not add new keys to UILayout.

Validation

After editing ui.toml, always validate:

python3 -c "import toml; toml.load('res/themes/ui.toml'); print('Valid TOML')"

Or with the C++ toml++ parser (which is what the app uses):

cd build && make -j$(nproc)

Build

# Linux
cd build && make -j$(nproc)

# Windows cross-compile
./build.sh --win-release

Plans

When asked to "create a plan", always create a new markdown document in the docs/ directory with the plan contents.

Icons: Use Material Design icon font, never Unicode symbols

Never use raw Unicode symbols or emoji characters (e.g. ↓, ↗, ⛏, 🔍, 📬, ⚠️, ℹ) for icons in C++ code. Always use the Material Design Icons font via the ICON_MD_* defines from #include "../../embedded/IconsMaterialDesign.h".

Icon font API

Method	Size	Fallback
Type().iconSmall()	14px	Body2
Type().iconMed()	18px	Body1
Type().iconLarge()	24px	H5
Type().iconXL()	40px	H3

Correct usage

#include "../../embedded/IconsMaterialDesign.h"

// WRONG — raw Unicode symbol
itemSpec.leadingIcon = "↙";

// CORRECT — Material Design icon codepoint
itemSpec.leadingIcon = ICON_MD_CALL_RECEIVED;

// WRONG — emoji for search
searchSpec.leadingIcon = "🔍";

// CORRECT — Material Design icon
searchSpec.leadingIcon = ICON_MD_SEARCH;

// For rendering with icon font directly:
ImGui::PushFont(Type().iconSmall());
ImGui::TextUnformatted(ICON_MD_ARROW_DOWNWARD);
ImGui::PopFont();

Why

Raw Unicode symbols and emoji render inconsistently across platforms and may not be present in the loaded text fonts. The Material Design icon font is always loaded and provides consistent, scalable glyphs on both Linux and Windows.

Audit for Unicode symbols

Before completing any task that touches UI code, search for and replace any raw Unicode symbols that may have been introduced. Common symbols to look for:

Unicode	Replacement
▶ ▷	ICON_MD_PLAY_ARROW
■ □ ◼ ◻	ICON_MD_STOP or ICON_MD_SQUARE
● ○ ◉ ◎	ICON_MD_FIBER_MANUAL_RECORD or ICON_MD_CIRCLE
↑ ↓ ← →	ICON_MD_ARROW_UPWARD, _DOWNWARD, _BACK, _FORWARD
↙ ↗ ↖ ↘	ICON_MD_CALL_RECEIVED, _MADE, etc.
✓ ✔	ICON_MD_CHECK
✗ ✕ ✖	ICON_MD_CLOSE
⚠ ⚠️	ICON_MD_WARNING
ℹ ℹ️	ICON_MD_INFO
🔍	ICON_MD_SEARCH
📋	ICON_MD_CONTENT_COPY or ICON_MD_DESCRIPTION
🛡 🛡️	ICON_MD_SHIELD
⏳	ICON_MD_HOURGLASS_EMPTY
🔄 ↻ ⟳	ICON_MD_SYNC or ICON_MD_REFRESH
⚙ ⚙️	ICON_MD_SETTINGS
🔒	ICON_MD_LOCK
★ ☆	ICON_MD_STAR or ICON_MD_STAR_BORDER