advanced-calculator/AGENTS.md

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.