统一交互组件 (#7)

Reviewed-on: #7

AGENTS.md

@@ -3,9 +3,11 @@
 ## Commands
 
 - `npm run dev` — Vite dev server with HMR
+- `npm run check:styles` — validates shared style contracts and blocks deprecated palettes/classes
 - `npm run build` — `vue-tsc -b && vite build` (typecheck must pass or build aborts)
 - `npx vue-tsc -b` — standalone typecheck (no script in package.json)
-- No linter, formatter, or test runner exists
+- `npm run preview` — previews the production build on strict port `5173`
+- No general linter, formatter, or test runner exists; `check:styles` is the project-specific visual-system check
 
 ## Architecture
 
@@ -26,9 +28,13 @@
 | `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/style.css` | Global stylesheet assembly point; imports Tailwind, tokens, base rules, and shared components |
+| `src/styles/` | Visual system source: semantic tokens, global square-corner baseline, shared `oc-*` component contracts |
+| `src/lib/theme.ts` | Naive UI theme overrides aligned with the semantic tokens |
 | `src/views/` | Route-level page components (see Routes below) |
 | `src/types/` | TypeScript types: domain models (`database.ts`), API DTOs (`api.ts`), AMap declarations (`amap.d.ts`), router meta (`router.d.ts`) |
+| `docs/style-system.md` | Concise implementation and naming guide for the visual system |
+| `scripts/check-style-system.mjs` | Automated guard against deprecated palettes and malformed shared classes |
 
 ## Routes
 
@@ -126,12 +132,33 @@ Optional:
 
 Backend-only variables such as database credentials, JWT secrets, SMTP settings, cookie policy, CORS origins, and upload paths belong in `../opencloud-backend/.env`, never in the Vite environment.
 
+## Visual System
+
+- The design language is a clean sky atlas: airy sky-blue surfaces, fresh eucalyptus green, square editorial panels, pixel-cloud identity, and hard offset shadows.
+- Read `.agents/skills/opencloud-style/SKILL.md` before material visual changes. Treat `src/styles/tokens.css`, `src/styles/base.css`, `src/styles/components.css`, and `src/lib/theme.ts` as the implementation sources of truth.
+- Shared/stable decisions belong in layers:
+  - tokens and palette remapping → `src/styles/tokens.css`
+  - global baseline and square-corner policy → `src/styles/base.css`
+  - cross-page semantic classes → `src/styles/components.css`
+  - feature-specific map/slider/media details → the component's scoped style
+  - one-off layout and responsive composition → Tailwind in the template
+- The global interface is square by default. Ordinary cards, inputs, dropdowns, buttons, modals, and map controls use `0px` radius. Circular marker dots, media overlay controls, AMap-generated bubbles/cards, and the media-focused image-detail shell are explicit exceptions.
+- Use hard zero-blur offset shadows (`--oc-shadow-xs` through `--oc-shadow-xl`) for ordinary UI depth. Interactive controls may lift by `translate(-1px, -1px)` on hover.
+- Brand/interaction green is fresh eucalyptus: main `#34745d`, dark `#274c40`, light surface `#f2faf6`.
+- Success green is a distinct leaf green: main `#4d7f3b`, dark `#35522c`, light surface `#f4faef`.
+- Existing `teal-*` and `emerald-*` Tailwind class names are compatibility aliases remapped in `tokens.css`; do not assume Tailwind's default values.
+- Do not introduce Tailwind `green-*`/`lime-*`, vivid default teal, purple, indigo, or generic gray palettes. Use slate, sky, remapped teal/emerald, amber, and rose according to semantic purpose.
+- The header brand mark is the pixel cloud/sun SVG inside a square `40px` `sky-100` surface with a `sky-200` border and neutral `4px` hard shadow. Do not replace it with emoji or give it a green background.
+- Map floating buttons use `oc-map-button`: square `40px × 40px`, white background, slate border, `0px` radius, and a hard shadow even when disabled.
+- For material visual changes, inspect representative desktop and real `375px` mobile screenshots and verify there is no horizontal overflow.
+
 ## Naive UI
 
 - 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.
+- Global overrides are defined in `src/lib/theme.ts` and mounted by `App.vue`; keep brand/success colors aligned with `src/styles/tokens.css`.
+- **Do not rely on default Naive UI primary/secondary colors for page CTAs or panel actions.** Use the shared classes in `src/styles/components.css`.
 - 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
@@ -146,12 +173,15 @@ Backend-only variables such as database credentials, JWT secrets, SMTP settings,
   - `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.
+- Primary and panel actions use dark text on light semantic surfaces; do not assume primary buttons should use white text.
 
 ## 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.
+- The site icon and header brand mark are a matching pixel-style cloud motif on a light sky-blue square; avoid 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.
+- Reuse existing `oc-*` classes before duplicating Tailwind bundles. New shared modifiers must always appear with their base class.
+- Validate style work with `npm run check:styles`, `git diff --check`, and `npm run build`.
 
 ## MVP Constraints