# Repository Guidelines

## Project Structure & Modules
- `src/AdvancedCalculator`: Shared UI + logic (Avalonia, ViewModels, Services, Models, Converters, Styles, Views, Assets).
- `src/AdvancedCalculator.Desktop`: Desktop entry point (`net8.0`).
- `src/AdvancedCalculator.Browser`: WebAssembly host (`net8.0-browser`, `wwwroot` for static assets).
- `src/AdvancedCalculator.Android`: Android host (`net8.0-android`, `Resources`, `AndroidManifest.xml`).
- `src/AdvancedCalculator.sln`: Solution root; `src/Directory.Build.props` centralizes common settings (nullable, Avalonia version).

## Build, Run, and Development
- Restore + build all: `dotnet build src/AdvancedCalculator.sln -c Debug`
- Run Desktop: `dotnet run --project src/AdvancedCalculator.Desktop -c Debug`
- Run Browser: `dotnet run --project src/AdvancedCalculator.Browser -c Debug` (open the printed local URL)
- Build Android: `dotnet build src/AdvancedCalculator.Android -c Debug` (install APK via `adb install` from `bin/Debug/net8.0-android/`)
- Format code: `dotnet format` (run at repo root)

## Coding Style & Naming
- C# 8+/latest, nullable enabled; 4‑space indentation, no tabs.
- Names: PascalCase for types/properties; camelCase for locals/parameters; private fields `_camelCase`.
- Use `var` for obvious types; prefer expression-bodied members when clear.
- XAML: keep styles in `Styles/*.axaml`; avoid inline styling; prefer bindings and converters in `Converters/*`.

## Color Scheme (Official)
### Primary Colors
- Primary 1: `#5AC3D6` — Accent/brand; used for links, primary buttons, and focus highlights.
- Primary 2: `#223544` — Deep surface; used for app chrome, panels, and elevated containers.
- Primary 3: `#4E6D84` — Background shell; used for main window backgrounds and large surfaces.

### Emphasis Colors
- Emphasis 1: `#F5A623` — Warning/attention highlights and subtle callouts.
- Emphasis 2: `#D94E87` — Destructive/negative emphasis (e.g., remove/close actions).
- Emphasis 3: `#49C46D` — Success/positive emphasis (e.g., confirmations, success badges).

### Background & Surfaces
- Background: `#4E6D84` — Same as Primary 3; default app background.
- Surface: `#223544` — Same as Primary 2; cards, drawers, panels.

### Text & Links
- Text: `#EAF2F7` — Primary text on dark surfaces.
- Link: `#5AC3D6` — Matches Primary 1.
- Focus Ring: `#5AC3D6` — Matches Primary 1 for accessibility.

### Inputs & Borders
- Muted Text: `#FFFFFFBF` — 75% white over surfaces (semi‑transparent tint).
- Border: `#FFFFFF2E` — 18% white; subtle separators and dividers.
- Input Background: `#FFFFFF0F` — 6% white; faint fill for inputs.
- Input Border: `#FFFFFF38` — 22% white; input outlines on dark surfaces.

Note: 8‑digit hex values follow `#RRGGBBAA` (alpha last) and correspond to the previous RGBA tints.

### Avalonia Mapping
- Define brushes in `Styles/Colors.axaml`: `CPrimary1`, `CPrimary2`, `CPrimary3`, `CEmph1`, `CEmph2`, `CEmph3`.
- `ThemeAccentBrush`: derive from Primary 1.
- Background/Surface brushes: use Background and Surface above.
- Keep all UI colors derived from these tokens for consistency across Desktop, Browser, and Android.

## Testing Guidelines
- No test projects yet. If adding tests, create `tests/AdvancedCalculator.Tests` (xUnit or NUnit), name files `*.Tests.cs`, and target `net8.0`.
- Run tests with `dotnet test` at repo root or solution level.
- Aim for coverage of `Services` and view‑model logic; UI/XAML can be validated via snapshot or behavior tests.

## Commit & Pull Requests
- Messages: imperative mood, concise subject; optionally prefix type (e.g., `feat:`, `fix:`, `theme:`) as seen in history.
- Include a brief body for non‑trivial changes with bullet points.
- PRs: link related issues, describe scope and platform(s) affected (Desktop/Browser/Android), include screenshots/GIFs for UI changes, and note manual test steps.
- Keep changes scoped; avoid unrelated refactors.

## Configuration Tips
- Shared properties live in `src/Directory.Build.props`; prefer updating versions/nullable here, not per project.
- Browser host static assets are under `src/AdvancedCalculator.Browser/wwwroot`.
- Android package id is set in `AdvancedCalculator.Android.csproj` (`ApplicationId`). Update icons/splash in `Resources`.