echoes-of-the-ash/VISUALS_GUIDE.md

# 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*