From dd93d5cd0c6036f4c407e3649d95c5fae3c1970b Mon Sep 17 00:00:00 2001
From: Mplan <mplan_@outlook.com>
Date: Sat, 30 May 2026 00:27:04 +0800
Subject: [PATCH] docs: update AGENTS.md with UI styling conventions

---
 AGENTS.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index be32fbe..3fb37a3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,6 +26,7 @@
 | `src/components/cloud/` | Cloud-related modals and widgets: ImageDetailModal, CloudEditModal, MapPickerModal, QuickUploadModal, MiniLocationMap |
 | `src/components/layout/` | AppHeader (top nav bar with auth state) |
 | `src/components/profile/` | ContributionHeatmap |
+| `src/style.css` | Global visual system hooks: shared button/card utility classes, base typography, body background |
 | `src/views/` | Route-level page components (see Routes below) |
 | `src/types/` | TypeScript types: database models (`database.ts`), AMap declarations (`amap.d.ts`), router meta (`router.d.ts`) |
 
@@ -121,6 +122,27 @@ Future (not in `.env`):
 - Used for modals, buttons, inputs, tags, progress bars, alerts, dropdowns, empty states, skeletons, and message toasts.
 - No SSR — pure client-side rendering.
 - Custom CSS overrides via scoped `<style>` blocks for slider styling, transitions, and component tweaks.
+- **Do not rely on default Naive UI primary/secondary colors for page CTAs or panel actions.** The project now uses shared global classes in `src/style.css` to keep buttons visually consistent with the sky-atlas theme.
+- Auth buttons use `oc-primary-button` with semantic variants:
+  - `oc-primary-button--teal` — login / account-access actions
+  - `oc-primary-button--sky` — register / create / forward actions
+- Panel and utility buttons use `oc-panel-button` with semantic variants:
+  - `oc-panel-button--neutral` — white card-style utility actions
+  - `oc-panel-button--sky` — primary panel actions
+  - `oc-panel-button--teal` — active toggles / confirm actions
+  - `oc-panel-button--danger` — destructive actions
+  - `oc-panel-button--amber` — admin/state-toggle actions where warning emphasis fits better than danger
+- Card-like containers should prefer shared shadow classes instead of ad-hoc shadows:
+  - `oc-panel-card`
+  - `oc-panel-card-soft`
+  - `oc-empty-card`
+- When styling `NButton`, prefer `type="default"` plus the shared class when a custom panel button variant is intended. Otherwise Naive UI theme variables may override white backgrounds or semantic colors.
+
+## Visual Notes
+
+- The site icon and header brand mark are a matching pixel-style cloud motif; avoid reintroducing emoji or unrelated icon styles for primary brand surfaces.
+- Header action buttons use slight hover lift (`translate(-1px, -1px)`) with hard-offset shadow growth; new header-like actions should follow that interaction pattern.
+- Heatmap view toggles in `ContributionHeatmap` intentionally use separate buttons with gap spacing instead of `NButtonGroup`, because grouped buttons visually collide once hard shadows and hover transforms are applied.
 
 ## MVP Constraints (from plan.md)