# ConquerHub Design Context

> Read this file first. It is the compact source of truth for future design work.

## Goal

Static HTML frontend for ConquerHub server websites, designed for later integration into the existing PHP/CMS. There is no server-selector page in this delivery and the frontend must not become a PWA or SPA.

## Architecture

- One standalone HTML file per screen.
- Shared layout/components: `assets/css/theme.css`.
- Shared interactions: `assets/js/theme.js`.
- Server appearance is intended to be isolated in one server-theme CSS file per server (`umbra`, `eclipse`, `nova`).
- PHP/CMS/game/session values are represented by static fixtures and marked with `<!-- Dynamic: ... -->` comments.
- `programmer-reference/` contains integration references only; never include these files in static HTML.
- `playground.html` is the component compatibility reference and has no filters.

## Screens

`index.html`, `rankings.html`, `events.html`, `store.html`, `cart.html`, `player-profile.html`, `guild-profile.html`, `login.html`, `register.html`, `content-category.html`, `content-article.html`, `404.html`, `playground.html`.

Do not create standalone Market or Guides pages unless explicitly requested. Their navigation entries may point to CMS-owned routes.

## Approved shell

Header order:

`ConquerHub logo + server logo | Home | Game | Community | Rankings | Market | Store | language | HUB | Discord | Download | User panel`

Rules:

- No old top status bar (server online/local time/player count).
- ConquerHub logo returns to the server selector in production.
- Game submenu: Events, Statistics, Features, Guild War, Socket Logs. No Downloads, Top Guilds or Server Feeds.
- Community submenu includes Guides plus media/community links.
- Language selector supports ES/EN and sits between Store and the action buttons.
- No Download/Discord CTA buttons centered over the hero.
- Mobile: one disclosure menu at `<= 820px`.

## Visual direction

Dark fantasy MMO shell with server-specific art and accents. Large artwork-led hero, compact dark navigation, restrained borders, high contrast content cards, and themed accent color. Content remains readable and visually secondary to server branding.

Server identities:

- **Umbra:** purple / void / arcane / dark.
- **Eclipse:** black / red / ember / eclipse.
- **Nova:** white / gold / blue / celestial.

Hero artwork should use the final server banner as a cover background, preserve the important focal area, and avoid excessive zoom/cropping. Do not add duplicate hero text or CTA overlays when that content already exists inside the artwork.

## Compatibility boundary

The outer shell can be redesigned. CMS/page-content output cannot be casually renamed or restructured.

Preserve playground/component classes and hierarchy, especially:

- `.page-title`
- `.panel`, `.panel-body`, `.panel-title`
- `.btn.btn-default`, `.btn.btn-primary`
- `.accordion > .accordion__box-title + .accordion__box-content`
- `.row.fake-table > .fake-table__row > .row > .label + .value`
- `.form-horizontal.needs-validation`, `.form-group.row`, `.control-label`, `.form-control`
- `.table`, `.ranking-table`
- product/cart/profile/content classes represented in `playground.html`

`playground.html` is the fastest visual regression page. Keep its component order and `data-playground-category` / `data-playground-component` attributes intact.

## Shared CSS contract

`theme.css` owns structure and reusable component styling. Important variables:

```css
--bg
--surface
--surface-2
--text
--muted
--line
--accent
--accent-rgb
--accent-2
--hero-image
--server-logo
--gameplay-image
--theme-soft
--content-width
--font-ui
--font-display
```

Server-specific CSS should primarily override these variables. Do not duplicate shared component CSS into each server theme unless a server genuinely needs a visual exception.

## Shared JS contract

`theme.js` only handles presentation behavior:

- mobile navigation
- dropdown navigation
- accordion toggles
- static-preview ES/EN shell labels
- optional `?theme=umbra|eclipse|nova` preview switch
- prevention of static preview form submission

Do not add CMS rendering, authentication, payments, API calls, routing, service workers, or PWA behavior here.

## Assets

Keep image paths relative to `assets/`. Never delete or replace accumulated artwork unless explicitly requested. Server theme CSS should reference the correct server logo/banner rather than altering HTML per server.

## Editing rules

1. Change shared layout/component behavior in `theme.css` / `theme.js`.
2. Change only server palette/artwork in the relevant server-theme CSS.
3. Change HTML only when structure/content requirements change.
4. Preserve `<!-- Dynamic: ... -->` comments when editing CMS-owned areas.
5. Keep forms in static previews non-destructive.
6. Validate desktop plus `1180px`, `820px`, and `520px` breakpoints.
7. After component CSS changes, inspect `playground.html` before individual pages.

## References

- `THEME-GUIDE.md` — how to modify/create a server theme.
- `INTEGRATION.md` — PHP/CMS handoff rules.
- `programmer-reference/components-base.template.php` — template component output.
- `programmer-reference/components-form-base.template.php` — form component output.
- `programmer-reference/playground-html-ref.html` — original component snapshot.