echoes-of-the-ash/docs/visual_style_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) or tight radii (2px-4px) 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

: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).

// Usage Example
<GameTooltip content={<ItemStats item={sword} />}>
  <button className="game-slot">
    <img src="sword.png" />
  </button>
</GameTooltip>

4. Reusable Component Classes

Panels & Containers

.game-panel

• Look: Industrial, solid.
• CSS:

  background: var(--game-bg-panel);
  border: 1px solid var(--game-border-color);
  box-shadow: var(--game-shadow-panel);
  backdrop-filter: blur(8px);
  border-radius: var(--game-radius-sm);
  

Buttons

.game-btn

• Look: Rectangular, tactile.
• States:
  • Normal: Dark grey background, light border.
  • Hover: Glow effect, border brightens.
  • Active: Presses down (transform).
• CSS:

  text-transform: uppercase;
  font-family: var(--game-font-main);
  letter-spacing: 0.5px;
  clip-path: polygon(10px 0, 100% 0, 100% calc(100% - 10px), calc(100% - 10px) 100%, 0 100%, 0 10px); /* Mecha-cut corners */
  /* OR simple tight radius */
  border-radius: 2px;
  

Items & Slots

.game-slot

• Background: var(--game-bg-slot) (Darker than panel).
• Border: 1px solid var(--game-border-color).
• Interaction: On hover, background lightens slightly, border acts as highlight.

5. Implementation Plan

Phase 1: Tooltip System (Priority)

1. Create src/components/common/GameTooltip.tsx.
2. Implement global tooltip context/store if needed for performance, or use a lightweight library like generic CSS hover + React portal.
3. Audit: Grep for title= in all files and replace with <GameTooltip>.

Phase 2: Design Token Migration

1. Define all variables in index.css.
2. Update src/styles/components.css (or new file) with utility classes.

Phase 3: Component Reskinning

1. InventoryModal: Apply .game-panel and standard slots.
2. PlayerSidebar: Update bars and equipment slots.
3. HUD/Sidebar: Ensure borders are strict and consistent.