From aa71a6be7c269ff0c293c4bb7ca673bbfcf06fc6 Mon Sep 17 00:00:00 2001 From: Joan Date: Wed, 25 Feb 2026 10:05:01 +0100 Subject: [PATCH] docs: Update GEMINI and Visuals Guide --- GEMINI.md | 53 +++++++++++++++ VISUALS_GUIDE.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 GEMINI.md create mode 100644 VISUALS_GUIDE.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..8e26264 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,53 @@ +# GEMINI.md - Echoes of the Ash + +## Project Overview +- **Type**: Dark Fantasy RPG Adventure +- **Stack**: Monorepo with Python/FastAPI backend and React/Vite/TypeScript frontend. +- **Infrastructure**: Docker Compose (Postgres, Redis, Traefik). +- **Primary Target**: Web (PWA + API). Electron is secondary. + +## Commands + +### Development & Deployment +- **Start (Dev)**: `docker compose up -d` +- **Apply Changes**: `docker compose build && docker compose up -d` (Required for both code and env changes) +- **Restart API**: `docker compose restart echoes_of_the_ashes_api` (This does not apply changes to the code) +- **View Logs**: `docker compose logs -f [service_name]` (e.g., `echoes_of_the_ashes_api`, `echoes_of_the_ashes_pwa`) + +### Frontend (PWA) +- **Directory**: `pwa/` +- **Build and run**: `docker compose build echoes_of_the_ashes_pwa && docker compose up -d` (Required for both code and env changes) + +### Backend (API) +- **Directory**: `api/` +- **Dependencies**: `requirements.txt` +- **Build and run**: `docker compose build echoes_of_the_ashes_api && docker compose up -d` (Required for both code and env changes) + +### Testing +- No automated testing +- Do not use the automated browser + +## Architecture & Code Structure + +### Backend (`api/`) +- **Entry**: `main.py` +- **Routers**: `routers/` (Modular endpoints: `game_routes.py`, `combat.py`, `auth.py`, etc.) +- **Core**: `core/` (Config, Security, WebSockets) +- **Services**: `services/` (Models, Helpers) +- **Pattern**: + - Use `routers` for new features. + - Register routers in `main.py` (auto-registration logic exists but explicit is clearer). + - Pydantic models in `services/models.py`. + +### Frontend (`pwa/`) +- **Entry**: `src/main.tsx` +- **Styling**: Standard CSS files per component (e.g., `components/Game.css`). No Tailwind/Modules. Read `VISUALS_GUIDE.md` for styling guidelines. +- **State**: Zustand stores (`src/stores/`). +- **Translation**: i18next (`src/i18n/`). +- **Reusable Components**: `src/components/common/` (e.g., `Button.tsx`, `Modal.tsx`, etc.) + +## Style Guidelines +- **Python**: PEP8 standard. No strict linter enforced. +- **TypeScript**: Standard ESLint rules from Vite template. +- **CSS**: Plain CSS. Keep component styles in dedicated files. Read `VISUALS_GUIDE.md` for styling guidelines. +- **Docs**: update `QUICK_REFERENCE.md` if simplified logic or architecture changes. diff --git a/VISUALS_GUIDE.md b/VISUALS_GUIDE.md new file mode 100644 index 0000000..26b6ce6 --- /dev/null +++ b/VISUALS_GUIDE.md @@ -0,0 +1,164 @@ +# Visual Style Guide - Echoes of the Ash + +This document defines the unified visual system for the application, ensuring a consistent, mature "videogame" aesthetic. + +## 1. Core Design Philosophy +- **Aesthetic**: **Mature Post-Apocalyptic**. Think "High-Tech Scavenger". + - **Dark & Gritty**: Deep blacks (`#0a0a0a`) mixed with industrial dark greys (`#1a1a20`). + - **Sharp & Distinct**: Avoid overly rounded "Web 2.0" corners. Use chamfered corners (clip-path) for a militaristic/industrial feel. + - **Glassmorphism**: Use semi-transparent backgrounds with blur (`backdrop-filter`) to keep the player connected to the world. + - **Cinematic**: High contrast text, subtle glows on active elements, and distinct borders. +- **Interaction**: **Instant Feedback**. + - **Custom Tooltips**: **MANDATORY**. Do NOT use the HTML `title` attribute. All information must appear instantly in a custom game-styled tooltip anchor. + - **Micro-animations**: Subtle pulses, border glows on hover. + +## 2. CSS Variables (Design Tokens) +Defined in `:root`. + +### Colors +```css +:root { + /* Backgrounds */ + --game-bg-app: #050505; /* Deepest black */ + --game-bg-panel: rgba(18, 18, 24, 0.96); /* Almost solid panels */ + --game-bg-glass: rgba(10, 10, 15, 0.85); /* Overlays */ + --game-bg-slot: rgba(0, 0, 0, 0.5); /* Item slots - darker than panels */ + --game-bg-slot-hover: rgba(255, 255, 255, 0.08); + + /* Borders / Separators */ + --game-border-color: rgba(255, 255, 255, 0.12); + --game-border-active: rgba(255, 255, 255, 0.4); + --game-border-highlight: #ff6b6b; /* Red accent border */ + + /* Corner Radius - Tighter for mature look */ + --game-radius-xs: 2px; + --game-radius-sm: 4px; + --game-radius-md: 6px; + + /* Typography */ + --game-font-main: 'Saira Condensed', system-ui, sans-serif; + --game-text-primary: #e0e0e0; /* Off-white is better for eyes than pure white */ + --game-text-secondary: #94a3b8; /* Cool grey */ + --game-text-highlight: #fbbf24; /* Amber/Gold */ + --game-text-danger: #ef4444; + + /* Semantic Colors (Desaturated/Industrial) */ + --game-color-primary: #e11d48; /* Blood Red - Action/Health */ + --game-color-stamina: #d97706; /* Amber - Stamina */ + --game-color-magic: #3b82f6; /* Blue - Mana/Tech */ + --game-color-success: #10b981; /* Emerald - Durability High */ + --game-color-warning: #f59e0b; /* Amber - Warning */ + + /* Rarity Colors */ + --rarity-common: #9ca3af; + --rarity-uncommon: #ffffff; + --rarity-rare: #34d399; + --rarity-epic: #60a5fa; + --rarity-legendary: #fbbf24; + + /* Effects */ + --game-shadow-panel: 0 8px 32px rgba(0, 0, 0, 0.8); + --game-shadow-glow: 0 0 15px rgba(225, 29, 72, 0.3); /* Subtle red glow */ +} +``` + +## 3. Tooltip System (CRITICAL) +**Goal**: Replicate a native game HUD tooltip. +**Rule**: NEVER use `title="Description"`. + +### The Component: `` +Every interactive element with info must be wrapped or associated with this component. +- **Behavior**: Appears instantly on hover (0ms delay). Follows cursor OR anchored to element. +- **Visuals**: + - Background: Solid dark (`#0f0f12`) with high opacity (98%). + - Border: Thin accent border (`1px solid --game-border-color`). + - Shadow: Strong drop shadow to separate from UI. + - Content: Supports HTML (rich text, stats, icons). + +```tsx +// Usage Example +}> + + + +## 4. Reusable Components +Use these React components located in `pwa/src/components/common/` to ensure visual consistency. + +### Buttons: `` +**Look**: Rectangular, tactile, with optional mecha-cut corners. +- **Variants**: `primary`, `secondary`, `success`, `danger`, `info`, `warning`. +- **Sizes**: `sm`, `md`, `lg`. +- **States**: Auto-handles hover glows and active transforms. + +```tsx + + Save Game + +``` + +### Tooltips: `` +**Rule**: NEVER use the HTML `title` attribute. +- **Behavior**: Appears instantly (0ms), follows cursor. Rendering via React Portal avoids z-index clipping. +- **Usage**: Wrap any interactive element. + +```tsx + + + +``` + +### Item Content: `` +Specialized sub-component for rich item data (stats, weight, durability bars). +- **Props**: `item`, `showValue` (for trading), `showDurability`. + +```tsx +}> +
...
+ +``` + +### Progress Bars: `` +For health, stamina, XP, weight, and volume. +- **Types**: `health`, `stamina`, `xp`, `weight`, `volume`, `durability`. +- **Modes**: Supports `showText`, custom `label`, and alignment. +- **Logic**: Auto-colors (e.g., weight turns red as it nears capacity). + +```tsx + +``` + +### Dropdowns: `` +Contextual menus that render outside the DOM hierarchy. +- **Features**: Auto-positioning (flips up if near bottom), click-outside to close. + +```tsx + setMenuOpen(false)}> +
Inspect
+
Discard
+ +``` + +### Notifications: `` +Global toast system. Used via `useNotification` hook. +- **Types**: `success`, `error`, `info`, `warning`. +- **Visuals**: Slide-in/out animations, industrial styling. + +## 5. UI Layout Patterns + +### Panels & Containers (`.game-panel`) +Use this class for modals and sidebars. +- **Visuals**: 96% opacity dark panels, 8px blur, 1px subtle border. + +### Grid Slots (`.game-slot`) +Consistent 1:1 ratio slots for items or abilities. Darker background than panels to create depth. + +--- +*Updated: Feb 16, 2026*