docs: add AGENTS.md repository guidelines and official color scheme

This commit is contained in:
Codex CLI 2025-08-29 01:11:15 -05:00
commit 72e0e47cd3

46
AGENTS.md Normal file
View file

@ -0,0 +1,46 @@
# 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; 4space 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)
- `--c-primary-1`: `#5AC3D6`; `--c-primary-2`: `#223544`; `--c-primary-3`: `#4E6D84`.
- `--c-emph-1`: `#F5A623`; `--c-emph-2`: `#D94E87`; `--c-emph-3`: `#49C46D`.
- `--bg`: `var(--c-primary-3)`; `--surface`: `var(--c-primary-2)`; `--text`: `#EAF2F7`.
- `--muted`: `rgba(255,255,255,0.75)`; `--border`: `rgba(255,255,255,0.18)`.
- `--input-bg`: `rgba(255,255,255,0.06)`; `--input-border`: `rgba(255,255,255,0.22)`.
- `--link`: `var(--c-primary-1)`; `--focus`: `var(--c-primary-1)`.
- Avalonia mapping: define colors/brushes in `Styles/Colors.axaml` (e.g., `CPrimary1/2/3`, `CEmph1/2/3`; `ThemeAccentBrush` from primary1; background/surfaces from `--bg/--surface`; text from `--text`). Keep all UI colors derived from these tokens.
## 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 viewmodel 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 nontrivial 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`.