docs: Update GEMINI and Visuals Guide
This commit is contained in:
Joan
53
GEMINI.md
Normal file
53
GEMINI.md
Normal file
@@ -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.
|
||||||
164
VISUALS_GUIDE.md
Normal file
164
VISUALS_GUIDE.md
Normal file
@@ -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: `<GameTooltip />`
|
||||||
|
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
|
||||||
|
<GameTooltip content={<ItemStats item={sword} />}>
|
||||||
|
<button className="game-slot">
|
||||||
|
<img src="sword.png" />
|
||||||
|
</button>
|
||||||
|
</GameTooltip>
|
||||||
|
|
||||||
|
## 4. Reusable Components
|
||||||
|
Use these React components located in `pwa/src/components/common/` to ensure visual consistency.
|
||||||
|
|
||||||
|
### Buttons: `<GameButton />`
|
||||||
|
**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
|
||||||
|
<GameButton variant="success" size="md" onClick={handleSave}>
|
||||||
|
Save Game
|
||||||
|
</GameButton>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tooltips: `<GameTooltip />`
|
||||||
|
**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
|
||||||
|
<GameTooltip content="Drains 10 Stamina">
|
||||||
|
<button className="ability-slot">Dash</button>
|
||||||
|
</GameTooltip>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Item Content: `<ItemTooltipContent />`
|
||||||
|
Specialized sub-component for rich item data (stats, weight, durability bars).
|
||||||
|
- **Props**: `item`, `showValue` (for trading), `showDurability`.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<GameTooltip content={<ItemTooltipContent item={sword} />}>
|
||||||
|
<div className="inventory-slot">...</div>
|
||||||
|
</GameTooltip>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Progress Bars: `<GameProgressBar />`
|
||||||
|
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
|
||||||
|
<GameProgressBar
|
||||||
|
value={80}
|
||||||
|
max={100}
|
||||||
|
type="health"
|
||||||
|
showText
|
||||||
|
label="Health"
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dropdowns: `<GameDropdown />`
|
||||||
|
Contextual menus that render outside the DOM hierarchy.
|
||||||
|
- **Features**: Auto-positioning (flips up if near bottom), click-outside to close.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<GameDropdown isOpen={menuOpen} onClose={() => setMenuOpen(false)}>
|
||||||
|
<div className="menu-item">Inspect</div>
|
||||||
|
<div className="menu-item">Discard</div>
|
||||||
|
</GameDropdown>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Notifications: `<NotificationContainer />`
|
||||||
|
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*
|
||||||
Reference in New Issue
Block a user