# 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:
   ```toml
   [tabs.example]
   my-element = {size = 42.0}
   ```

2. **Read it in C++** instead of using a literal:
   ```cpp
   // 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:
   ```cpp
   // 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:
```bash
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):
```bash
cd build && make -j$(nproc)
```

### Build

```bash
# 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

```cpp
#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` |
