diff --git a/art/hud/reputation/badge.png b/art/hud/reputation/badge.png new file mode 100644 index 0000000..e7c812f Binary files /dev/null and b/art/hud/reputation/badge.png differ diff --git a/art/hud/reputation/daemmerjaeger-badge.png b/art/hud/reputation/daemmerjaeger-badge.png new file mode 100644 index 0000000..155b944 Binary files /dev/null and b/art/hud/reputation/daemmerjaeger-badge.png differ diff --git a/art/hud/reputation/graufurt-badge.png b/art/hud/reputation/graufurt-badge.png new file mode 100644 index 0000000..3e29bbb Binary files /dev/null and b/art/hud/reputation/graufurt-badge.png differ diff --git a/art/hud/reputation/grenzwacht-badge.png b/art/hud/reputation/grenzwacht-badge.png new file mode 100644 index 0000000..cd41fd6 Binary files /dev/null and b/art/hud/reputation/grenzwacht-badge.png differ diff --git a/art/hud/reputation/letzte-wacht-badge.png b/art/hud/reputation/letzte-wacht-badge.png new file mode 100644 index 0000000..8011766 Binary files /dev/null and b/art/hud/reputation/letzte-wacht-badge.png differ diff --git a/docs/Ashen_Realms_Icon_Design_Guidelines.md b/docs/Ashen_Realms_Icon_Design_Guidelines.md new file mode 100644 index 0000000..522c8c0 --- /dev/null +++ b/docs/Ashen_Realms_Icon_Design_Guidelines.md @@ -0,0 +1,657 @@ +# Ashen Realms – Icon Design Guidelines + +## Purpose + +This document defines the visual design rules for **all future icons** in **Ashen Realms**. + +Its purpose is to ensure that every newly created icon: +- fits the existing Ashen Realms look and feel, +- remains readable in the UI, +- can be extended consistently over time, +- and does not drift into styles that break the game’s visual identity. + +These guidelines apply to: +- item icons, +- faction icons, +- NPC / role icons, +- enemy markers, +- status-effect icons, +- skill / ability icons, +- currency icons, +- UI utility icons, +- reputation / progression icons, +- and future icon categories. + +--- + +## 1. Core Visual Identity + +Ashen Realms uses a **dark fantasy browser RPG** aesthetic. + +All icons must visually belong to the same world as the existing: +- world map screens, +- combat screens, +- character screens, +- hunt cards, +- UI ornaments, +- creature art, +- and reputation / faction elements. + +### The intended overall feel is: +- dark, +- grounded, +- serious, +- atmospheric, +- medieval / gothic, +- realistic or painterly-realistic, +- non-cartoon, +- non-anime, +- non-mobile-game. + +### Every icon should feel like one of these: +- a real object from the world, +- a crafted emblem or sigil, +- a carved, forged, stitched, engraved, or painted artifact, +- a readable symbolic gameplay marker that still belongs to the world. + +--- + +## 2. Global Style Rules + +## 2.1 Required style qualities + +All icons should be: +- visually clean and readable, +- centered and balanced, +- strong in silhouette, +- detailed but not noisy, +- high contrast against dark UI backgrounds, +- rendered with believable materials, +- delivered on a **true transparent background** unless a specific exception is requested. + +## 2.2 Forbidden style directions + +Do **not** create icons in any of these styles: +- cartoon, +- anime, +- comic, +- pixel art, +- flat vector app icon style, +- modern esports logo style, +- bright casual mobile game style, +- toy-like style, +- exaggerated glossy fantasy-mobile style, +- sci-fi interface style, +- overly abstract minimalist symbol style. + +If an icon looks like it belongs to a mobile gacha game, a MOBA logo pack, or a modern productivity app, it is wrong. + +--- + +## 3. Material Language + +A central part of Ashen Realms’ identity is believable materiality. + +Icons should feel **forged, worn, scavenged, inherited, blessed, cursed, stitched, or weathered**. + +### Preferred materials +- blackened iron, +- aged steel, +- tarnished silver, +- bronze / brass, +- worn gold accents, +- leather, +- dark wood, +- bone, +- horn, +- parchment, +- rough cloth, +- stone, +- wax, +- ember-charred surfaces, +- ash-darkened surfaces. + +### Preferred surface detail +- scratches, +- dents, +- soot, +- wear, +- chipped edges, +- light corrosion / patina, +- dried blood if thematically appropriate, +- singed cloth, +- cracked runes, +- faint glow for magic or heat. + +### Avoid +- perfectly clean surfaces, +- smooth plastic look, +- airbrushed casual-game polish, +- chrome-like sterile rendering, +- excessive sparkle, +- excessive bloom. + +--- + +## 4. Shape Language + +Every icon should be based on a **clear primary shape**. + +This shape is what makes the icon readable at small sizes. + +### Strong base-shape examples +- sword, +- shield, +- skull, +- claw, +- fang, +- potion bottle, +- bag, +- helm, +- ring, +- moon, +- flame, +- tower, +- gate, +- coin, +- scroll, +- paw mark, +- eye, +- antlers, +- cross / X, +- gem, +- medallion. + +### Composition rule +An icon should usually have: +1. one dominant central object or symbol, +2. one supporting silhouette or frame, +3. only a few secondary detail elements. + +### Avoid +- too many unrelated elements in one icon, +- cluttered miniature scenes, +- thin unreadable details as the main structure, +- weak silhouette, +- symbols that only make sense at very large size. + +--- + +## 5. Color Rules + +Ashen Realms uses a restrained palette. + +### 5.1 General palette logic +The base is usually: +- charcoal, +- black, +- deep brown, +- grey steel, +- muted bronze, +- old gold, +- faded bone, +- dark desaturated reds, +- cold blue accents, +- muted green accents, +- ember orange highlights. + +### 5.2 Accent colors +Accent colors should communicate meaning, not decoration. + +Examples: +- **blue**: civilization, magic crystal, noble / city identity, +- **red**: danger, violence, blood, corruption, raiders, +- **green**: poison, wilderness, hunter / druidic influence, +- **orange / ember**: fire, ash, heat, aggression, +- **gold**: prestige, sacred, important, elite, +- **white / wax / pale bone**: sacred duty, relics, vigil, purity. + +### 5.3 Rules for color usage +- Keep the icon readable on dark UI backgrounds. +- Use color intentionally. +- Do not oversaturate the full icon. +- One main accent color is usually enough. +- A second accent is acceptable only if it improves meaning. +- Metal neutrals should remain dominant in many icon types. + +--- + +## 6. Glow and Magic Effects + +Glow effects are allowed, but must be controlled. + +### Appropriate glow usage +- ember cracks in charred weapons, +- faint runic light, +- potion liquid glow, +- moonlit eyes, +- sacred candlelight, +- rare arcane gem cores, +- faint curse energy. + +### Rules +- Glow should support the icon, not replace its structure. +- The shape must still read without the glow. +- Do not flood the whole icon with bloom. +- Avoid neon or sci-fi lighting. + +--- + +## 7. Transparency and Background Rules + +By default, future icons should be delivered as: +- **PNG** +- **transparent background** +- with the object cut out cleanly + +### Important requirement +The background must be **truly transparent**, not: +- dark-filled, +- fake transparent, +- soft black boxed, +- blurred backdrop, +- or baked into a UI panel. + +### Exceptions +A non-transparent icon background is only acceptable if explicitly requested for: +- a full card artwork, +- a framed UI tile, +- a world illustration, +- or a screenshot mockup. + +--- + +## 8. Readability by Size + +Every icon should remain functional at the sizes relevant to the game UI. + +### Reference sizes +- **1024×1024** – master asset / source icon +- **256×256** – large UI display / previews +- **128×128** – normal inventory or profile icon +- **64×64** – standard in-game icon size +- **32×32** – small lists, compact displays, status rows + +### Readability rules +- The primary shape must still be recognizable at **32–64 px**. +- Small icons should not depend on tiny textural detail. +- Major contrast zones should remain visible when scaled down. +- If necessary, simplify a future icon rather than packing in more detail. + +--- + +## 9. Category-Specific Guidelines + +## 9.1 Item icons + +Item icons should represent **physical objects from the world**. + +### Examples +- weapons, +- armor, +- trophies, +- bags, +- hides, +- insignias, +- bottles, +- crafting materials, +- relic fragments. + +### Rules +- show the item clearly, +- use a close-up icon composition, +- prefer one object or one bundle, +- avoid unnecessary scene context, +- preserve material realism, +- show damage / rarity / corruption through form and material, not only through glow. + +### Good item-icon motifs +- nicked blade, +- stitched pouch, +- scorched token, +- bloodied hide, +- cracked talisman, +- iron lantern, +- bone charm, +- fang bundle. + +--- + +## 9.2 Faction icons + +Faction icons should be **heraldic world emblems**, not abstract logos. + +### Rules +- strong central symbolic identity, +- distinct silhouette, +- ornamental but readable, +- suitable for reputation rows, map affiliations, and faction overview screens. + +Typical motifs: +- tower, +- gate, +- shield, +- skull, +- moon, +- candle, +- sword, +- wolf, +- antlers, +- banners, +- chains, +- medallions. + +--- + +## 9.3 Skill / ability icons + +Skill icons can be more symbolic than item icons, but must still feel grounded. + +### Rules +- focus on the action or effect, +- use a strong readable symbol, +- show the weapon, force, or defense style directly, +- keep silhouettes clear, +- allow slightly stronger dramatic lighting than regular items. + +### Examples +- crossed blades for attack, +- shield impact for shield bash, +- braced shield for defend, +- heavy axe arc for a strong strike, +- potion flask for consumable use. + +### Avoid +- abstract magical swirls without a readable core shape, +- MOBA-style visual clutter, +- generic “energy explosion” icons. + +--- + +## 9.4 Status-effect icons + +Status icons must be extremely readable and compact. + +### Rules +- one clear symbol, +- high clarity at 32 px, +- strong semantic color, +- minimal detail compared with larger icon types. + +### Examples +- drop + wound for bleeding, +- green fang or skull mist for poison, +- shield for block / defense, +- cracked armor for armor break, +- flame mark for burn, +- chain or slow-foot motif for slow, +- moon-eye or confusion symbol for fear or curse. + +--- + +## 9.5 Enemy markers / danger markers + +These are functional UI icons and should communicate threat quickly. + +### Rules +- clear symbolic meaning, +- simple silhouette, +- darker harsher visual language, +- aggressive accenting for danger levels. + +### Good motifs +- skull, +- claw mark, +- horned mark, +- blood X, +- burning eye, +- rank badge, +- elite crown or iron wreath. + +--- + +## 9.6 Currency icons + +Currency icons must look valuable and distinct. + +### Rules +- simple shape at first glance, +- physical token logic, +- strongly differentiated silhouettes and materials, +- enough contrast to separate currencies immediately. + +### Example differentiation +- silver coin, +- blue soul crystal, +- gold premium coin, +- regional token, +- seal fragment, +- hunter mark. + +--- + +## 9.7 UI utility icons + +These include interface-supporting icons such as: +- map, +- hunt, +- inventory, +- character, +- shop, +- mail, +- settings, +- group, +- logout, +- chat, +- notifications. + +### Rules +- slightly cleaner than item icons, +- still consistent with the fantasy setting, +- readable and restrained, +- should fit within framed navigation elements without looking too ornate. + +### These icons may be: +- simpler, +- more symbolic, +- less material-heavy than faction icons, +- but must still avoid generic flat-app icon style. + +--- + +## 10. Visual Hierarchy + +Not all icon categories should have the same complexity. + +### Recommended hierarchy + +#### Highest detail +- faction icons +- rare item icons +- prestige icons +- major currencies +- important sigils + +#### Medium detail +- regular item icons +- skill icons +- NPC role icons +- map affiliation icons + +#### Lower detail +- status icons +- small utility icons +- danger markers +- tiny inline symbols + +This prevents small UI icons from becoming unreadable. + +--- + +## 11. Consistency Rules + +When creating future icons, always compare against existing Ashen Realms assets. + +Every new icon should be checked for consistency in: +- palette, +- realism, +- shape weight, +- rendering quality, +- mood, +- material treatment, +- level of ornament, +- silhouette clarity. + +### Key rule +New icons should look like they were made by the **same art direction**, even if the motif differs. + +--- + +## 12. Prompting Guidance for Future Asset Generation + +When generating new icons with AI, prompts should be explicit. + +A good icon prompt should define: +- category, +- object / symbol, +- mood, +- materials, +- color accents, +- transparency, +- readability, +- style exclusions. + +### Prompt template + +```text +Create a dark fantasy icon for Ashen Realms. +Subject: [icon subject]. +Style: realistic, painterly-realistic dark fantasy, grounded medieval gothic RPG UI asset. +Materials: [materials]. +Colors: [base palette + accent]. +Composition: centered, strong silhouette, readable at small size. +Background: transparent. +Keep it ornate but clean, suitable for a dark fantasy browser RPG UI. +Do not make it cartoonish, anime, flat vector, pixel art, or mobile-game styled. +``` + +### Example + +```text +Create a dark fantasy item icon for Ashen Realms. +Subject: a scorched raider insignia token with warped iron and faint ember cracks. +Style: realistic, grounded dark fantasy, painterly-realistic RPG icon. +Materials: blackened iron, scorched bronze, ash residue. +Colors: dark iron, ember orange, muted red cloth accent. +Composition: centered close-up, strong silhouette, readable at small size. +Background: transparent. +Do not make it cartoonish, glossy mobile-game style, or flat vector. +``` + +--- + +## 13. Naming and File Rules + +### Master naming convention +Use clear asset names. + +Recommended pattern: + +`ashen-realms-[category]-[subject]-icon-v1.png` + +### Examples +- `ashen-realms-item-charred-raider-insignia-icon-v1.png` +- `ashen-realms-faction-graufurt-icon-v1.png` +- `ashen-realms-status-bleeding-icon-v1.png` +- `ashen-realms-skill-shield-bash-icon-v1.png` + +### Recommended master format +- PNG +- square +- transparent background +- 1024×1024 when possible + +--- + +## 14. Optional Variant System + +Some icon families may later need multiple states. + +### Example state variants +- normal, +- damaged, +- elite, +- cursed, +- blessed, +- locked, +- completed, +- defeated, +- active, +- disabled. + +### Variant rule +The **core silhouette and identity** must stay recognizable across variants. + +Example: +- a normal faction emblem, +- a hostile-stained version, +- a trusted / gilded version, +- a faded locked version. + +--- + +## 15. Review Checklist + +Before accepting any future icon, verify all of the following: + +### Style fit +- [ ] It looks like Ashen Realms. +- [ ] It matches the dark fantasy browser RPG direction. +- [ ] It does not look cartoonish, anime, or like a mobile game. + +### Readability +- [ ] The silhouette is strong. +- [ ] The icon is readable at 64 px. +- [ ] The main subject is still understandable at 32 px if needed. + +### Rendering +- [ ] Materials look believable. +- [ ] Detail is present but not noisy. +- [ ] Glow effects are controlled. + +### Color +- [ ] Accent colors are restrained and meaningful. +- [ ] The icon works against a dark UI background. + +### Delivery +- [ ] The background is truly transparent. +- [ ] The icon is centered and cleanly cut out. +- [ ] No unwanted frame or background plate is baked in unless explicitly requested. + +### Category fit +- [ ] The icon’s complexity suits its category. +- [ ] It is distinct from existing icons. +- [ ] It communicates the intended gameplay meaning clearly. + +--- + +## 16. Short Version for Fast Reference + +If only a short instruction is needed, use this: + +> All future Ashen Realms icons must use a grounded dark-fantasy style with realistic materials, strong silhouettes, restrained colors, and clean transparency. They must remain readable at small UI sizes, avoid cartoon/mobile/vector aesthetics, and always look like they belong to the same visual family as the existing Ashen Realms screens, items, factions, and UI assets. + +--- + +## 17. Final Principle + +When in doubt, prefer: +- darker over brighter, +- clearer over busier, +- grounded over flashy, +- material realism over abstract symbolism, +- strong silhouette over tiny detail, +- Ashen Realms consistency over novelty. + +A future icon should not merely look “good.” +It should look like it could only belong to **Ashen Realms**. diff --git a/docs/playable-slices/Ashen_Realms_Character_Page_Reputation_Implementation_Plan.md b/docs/playable-slices/Ashen_Realms_Character_Page_Reputation_Implementation_Plan.md new file mode 100644 index 0000000..3548352 --- /dev/null +++ b/docs/playable-slices/Ashen_Realms_Character_Page_Reputation_Implementation_Plan.md @@ -0,0 +1,1055 @@ +# Ashen Realms – Character Page & Reputation Progress Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Implement the Ashen Realms character page based on the approved character-page reference screenshot, with equipment, effective character stats, and a prominent Fame/Reputation progression section that gives the player the same continuous motivational feedback a classic XP bar would provide. + +**Architecture:** Reuse the existing Angular AppShell, TopBar, SideNavigation, Footer, panel components, UI assets, and existing reputation/fame backend/domain model. The character page is presentation-first: the server remains authoritative for character values and progression, while Angular composes the data into a dedicated character-page view model. Do not introduce a second reputation system or calculate authoritative progress values in the browser. + +**Tech Stack:** Angular 22.x, TypeScript, SCSS, NestJS 11.x, REST, TypeORM/PostgreSQL, existing Ashen Realms design tokens/assets/components. + +**Spec:** +- `docs/ui-visual-design-specification.md` +- `docs/design-manifest.md` +- the repository's current Fame/Reputation (`Ruhm` / `Ruf`) specification and implementation +- the approved character-page reference screenshot from the design discussion + +--- + +# 1. Non-negotiable visual requirement + +The approved screenshot and the existing Ashen Realms screens are **not inspiration only**. They are the visual target. + +The implementation must look as if it was built by the same UI team as the existing world, hunting, combat, inventory, and shell screens. + +## Mandatory rules + +- Reuse the existing `AppShell`, TopBar, SideNavigation, Footer, frame assets, panel assets, typography, colors, button styles, icon style, spacing tokens, and border treatments wherever they already exist. +- Before writing new SCSS, inspect the current components and `apps/web/public/assets/ui/` for reusable assets and styles. +- Do **not** replace the fantasy UI with generic Angular Material cards, Bootstrap-like panels, SaaS cards, glassmorphism, flat grey boxes, rounded mobile cards, or modern dashboard styling. +- Do **not** invent a new design system for this screen. +- Do **not** use a different gold, blue, green, border thickness, font hierarchy, or panel material when the project already defines one. +- The screen must preserve the dark metal / stone / leather material world and restrained gold trim used by the current Ashen Realms UI. +- Decorative elements must remain subordinate to information and interaction. +- Desktop is the primary target. Do not compromise the desktop composition to make it look like a mobile game. +- The final implementation must be visually compared side-by-side with the approved screenshot before the task is considered complete. + +## Visual acceptance target + +At a 16:9 desktop viewport, the screen must read as one coherent Ashen Realms screen: + +```text +TopBar +┌─────────────┬──────────────────────────────────────────────────────────────┐ +│ │ Character │ +│ │ │ +│ Side │ ┌──────────────────────────┐ ┌────────────────────────────┐ │ +│ Navigation │ │ Character + Equipment │ │ Effective Character Stats │ │ +│ │ │ │ ├────────────────────────────┤ │ +│ │ │ │ │ Fame / Reputation Progress │ │ +│ │ └──────────────────────────┘ └────────────────────────────┘ │ +│ │ │ +└─────────────┴──────────────────────────────────────────────────────────────┘ +Footer +``` + +The character artwork is the visual anchor. The statistics and progression panels support it; they must not turn the page into a spreadsheet/dashboard. + +--- + +# 2. Important progression semantics + +The current Ashen Realms progression model is authoritative. + +The project has moved away from a classic "kill monster → gain XP → level up" loop. The character page must therefore make **Fame / Renown (`Ruhm`) and regional Reputation (`Ruf`) visibly replace the motivational role of the XP bar**. + +Do not reintroduce XP as the primary progression display if the current repository has already migrated to the Fame/Reputation model. + +## Required distinction + +### Global Fame / Renown (`Ruhm`) + +This is the player's broad long-term progression track / world standing. + +It must be shown prominently and continuously, similar to a classic XP bar: + +```text +RUHM +Ruhmstufe 4 – Bewährt +[██████████████████░░░░░░░░░░] 1,250 / 2,000 +750 Ruhm bis Ruhmstufe 5 +``` + +The exact rank names, thresholds, current values, and unlocks must come from the existing game data. The example above is presentation only. + +### Regional Reputation (`Ruf`) + +Regional reputation is separate from global Fame and shows how trusted/respected the character is in individual regions or reputation domains. + +Example presentation: + +```text +Aschenfelder +Respektiert +[██████████████░░░░░░░░] 720 / 1,000 +Next: new Quartermaster offers +``` + +Again, the exact data and rank naming must come from the existing reputation system. + +## Motivation requirement + +The player must be able to answer these questions at a glance: + +1. What is my current Fame/Renown rank? +2. How far am I from the next Fame rank? +3. How much progress did I make since the last turn-in/session? +4. What regional reputation ranks do I currently have? +5. Which regional track is closest to the next rank? +6. What meaningful unlock comes next, if the current system exposes unlock information? + +The page must therefore show exact current/required values in addition to the graphical bars. A bar without numbers is insufficient. + +--- + +# 3. Screen layout + +## 3.1 Existing shell + +Do not create a special full-screen shell for the character page. + +Keep the existing persistent structure: + +- global TopBar +- left SideNavigation +- central main content +- Footer / status bar + +`Character` is the active navigation item and must use the project's existing active-state treatment. + +## 3.2 Main content proportions + +For desktop, use a two-column composition inside the content area: + +```text +Left: approximately 55–62 % +Right: approximately 38–45 % +``` + +The exact percentages may be adjusted to match existing shell dimensions, but the character must remain visually dominant. + +## 3.3 Left column – character and equipment + +The left panel contains: + +- page title: `Character` / current localized equivalent +- full-body character artwork +- equipment slots arranged around the character +- item rarity/quality borders using the existing item visual language +- equipped-item tooltips using the existing item tooltip component if present + +### V1 equipment slots + +The current V1 design defines these core slots: + +```text +Weapon +Helmet +Chest +Gloves +Legs +Boots +Amulet +``` + +Do not add Ring, Belt, Shoulder, Cape, or other slots only because they appeared in an early visual mockup. If the current repository's authoritative equipment model has changed since V1, use that model instead of duplicating slots. + +### Character artwork + +- Use the existing player artwork for the selected character/sex/model. +- Keep the figure large enough that it remains one of the strongest elements on the page. +- Do not crop the weapon, feet, head, or silhouette unnecessarily. +- The background may use a subtle world/stone/dark atmospheric treatment, but it must not compete with the character. + +## 3.4 Right column – effective stats + +The upper right panel shows actual effective character values returned by the server. + +Minimum values if present in the current model: + +```text +Health / Max Health +Attack +Weapon Damage +Armor +``` + +If the newer combat implementation already includes additional derived values such as Block Chance, Critical Chance, Dodge Chance, Counter effects, or similar set-derived combat stats, display them in a secondary `Details` group rather than hardcoding obsolete V1 assumptions. + +### Combat Power + +The older balancing documentation describes Combat Power as an internal balancing tool. Do **not** expose Combat Power or invent an "equipment score" on this page unless the current authoritative design explicitly decided to make such a value player-facing. + +## 3.5 Right column – Fame/Reputation panel + +This is a core feature, not a footer detail. + +Place it directly below the effective stats panel and keep at least the global Fame bar visible without scrolling at the primary desktop target. + +### Section A – Global Fame + +The global Fame block must contain: + +- progression icon / crest +- `Fame` / `Renown` / current localized term +- current Fame rank number +- current Fame rank title, if defined +- full-width progress bar +- exact `current / required` value +- exact remaining amount to next rank +- next rank title if available +- next unlock summary if the existing system provides one + +Recommended visual weight: + +- stronger than an individual regional reputation row +- gold / prestige accent from existing design tokens +- subtle highlight, no neon glow + +### Section B – Regional Reputation + +Below the global track, show the player's currently relevant regional tracks. + +Each row contains: + +- region/reputation icon +- region/reputation name +- current reputation rank/title +- progress bar +- exact `current / required` +- optional next-unlock line + +Order: + +1. current region first +2. then other known/unlocked regions +3. locked/unknown regions should not be presented as fake progress rows unless the existing reputation system explicitly exposes them + +### Long lists + +Do not allow 10+ reputation rows to destroy the screen composition. + +For more tracks than fit comfortably: + +- show the current region plus the next 2–4 most relevant tracks +- provide `View all reputation` / localized equivalent +- open a dedicated reputation view, drawer, or existing details screen if one exists + +Do not solve this by making the entire character page an endlessly scrolling dashboard. + +--- + +# 4. Progress bar visual specification + +The progress bars are intentionally reminiscent of classic RPG XP progression while remaining within Ashen Realms' material language. + +## Global Fame bar + +Target characteristics: + +- dark recessed metal/stone track +- thin aged-metal border +- subtle inner shadow +- filled portion uses muted prestige gold / warm amber from existing design tokens +- optional very subtle textured fill +- no bright mobile-game gradient +- no rounded pill shape unless the existing UI already uses it +- exact numbers remain readable at all fill percentages + +## Regional Reputation bars + +Use the same component and structure with lower visual emphasis. + +If the project already defines reputation-specific colors, use them. Otherwise: + +- positive/established reputation can use restrained green/gold accents +- neutral reputation can use muted bronze/grey +- hostile/negative reputation can use restrained red + +Colors must never be the only indication of reputation state; always show the text rank/title. + +## Progress calculation + +The client may calculate only the visual percentage from authoritative server values: + +```ts +percentage = max > min + ? Math.min(100, Math.max(0, ((current - min) / (max - min)) * 100)) + : 100; +``` + +Do not let the client decide rank thresholds, unlocks, or earned reputation. + +--- + +# 5. Data model for the character page UI + +Create a UI-facing view model so the template does not directly coordinate multiple raw API payloads. + +```ts +export interface CharacterPageVm { + character: CharacterSummaryVm; + stats: EffectiveCharacterStatsVm; + equipment: EquipmentSlotVm[]; + progression: CharacterProgressionVm; +} + +export interface CharacterSummaryVm { + id: string; + name: string; + portraitUrl: string; + artworkUrl: string; + currentHp: number; + maxHp: number; +} + +export interface EffectiveCharacterStatsVm { + currentHp: number; + maxHp: number; + attack: number; + weaponDamage: number; + armor: number; + details: CharacterDerivedStatVm[]; +} + +export interface CharacterDerivedStatVm { + key: string; + label: string; + formattedValue: string; +} + +export interface EquipmentSlotVm { + slot: string; + label: string; + item: EquippedItemVm | null; +} + +export interface EquippedItemVm { + itemId: string; + name: string; + iconUrl: string; + rarity: string; +} + +export interface CharacterProgressionVm { + fame: ProgressTrackVm; + regionalReputation: ProgressTrackVm[]; +} + +export interface ProgressTrackVm { + key: string; + name: string; + iconUrl?: string; + rank: number; + rankTitle: string; + currentValue: number; + rankStartValue: number; + nextRankValue: number; + nextRankTitle?: string; + nextUnlockLabel?: string; + state?: 'positive' | 'neutral' | 'negative'; +} +``` + +If the current reputation implementation already exposes equivalent DTOs, map those DTOs into the view model instead of changing the domain model to match this UI type. + +--- + +# 6. Data flow and server authority + +Preferred flow: + +```text +CharacterPageComponent + | + v +CharacterPageFacade + | | | + v v v +Character Equipment Reputation/Fame services + \ | / + \ | / + v v v + CharacterPageVm + | + v + Template +``` + +Rules: + +- The backend owns character values, equipped items, Fame, regional reputation, rank thresholds, and unlock conditions. +- Angular only displays them and derives presentation-only percentages/formatting. +- Never award Fame/Reputation from the character page. +- Never duplicate rank threshold tables in the frontend. +- Never infer reputation from inventory contents or killed monsters in the client. + +--- + +# 7. File structure + +Before implementation, inspect the repository and reuse equivalent files that already exist. Do not create duplicates with slightly different names. + +Target structure if the feature is not yet organized: + +```text +apps/web/src/app/features/character/ +├── character-page/ +│ ├── character-page.component.ts +│ ├── character-page.component.html +│ ├── character-page.component.scss +│ └── character-page.component.spec.ts +├── components/ +│ ├── character-equipment-panel/ +│ ├── character-stats-panel/ +│ ├── reputation-progress-panel/ +│ └── progress-track/ +├── data-access/ +│ ├── character-page.facade.ts +│ └── character-page.facade.spec.ts +└── models/ + └── character-page.vm.ts +``` + +Backend changes are only required if the current implemented Fame/Reputation system does not already expose the read data needed by this screen. + +If a read endpoint is missing, place it in the existing reputation/fame module rather than in the Angular-specific character module. + +Recommended read contract if no equivalent endpoint exists: + +```text +GET /api/reputation/me +``` + +Example response shape: + +```json +{ + "fame": { + "key": "world-fame", + "name": "Fame", + "rank": 4, + "rankTitle": "Proven", + "currentValue": 1250, + "rankStartValue": 1000, + "nextRankValue": 2000, + "nextRankTitle": "Known", + "nextUnlockLabel": "New world reputation tier" + }, + "regionalReputation": [ + { + "key": "ashen-fields", + "name": "Ashen Fields", + "rank": 2, + "rankTitle": "Respected", + "currentValue": 720, + "rankStartValue": 500, + "nextRankValue": 1000, + "nextRankTitle": "Trusted", + "nextUnlockLabel": "Quartermaster offers" + } + ] +} +``` + +The example values and labels are placeholders for shape only; production data must come from the existing Fame/Reputation definitions. + +--- + +# 8. Implementation tasks + +### Task 1: Audit existing character UI and design system + +**Files:** +- Inspect: `apps/web/src/app/layout/**` +- Inspect: `apps/web/src/app/shared/**` +- Inspect: `apps/web/src/app/features/character/**` +- Inspect: `apps/web/public/assets/ui/**` +- Inspect: current reputation/fame frontend and backend modules +- Inspect: existing world, hunt, combat, and inventory SCSS/components + +**Interfaces:** +- Consumes: existing AppShell/design system/reputation implementation +- Produces: a concrete reuse map before new UI code is added + +- [ ] **Step 1: Identify reusable shell components** + +Record the actual component selectors/classes for TopBar, SideNavigation, Footer, base Panel, button, tooltip, health bar, and item slot. + +- [ ] **Step 2: Identify design tokens and assets** + +Record the existing token names and file paths for panel backgrounds, borders, gold accents, text colors, active navigation treatment, and item rarity borders. + +- [ ] **Step 3: Identify existing Fame/Reputation APIs and DTOs** + +Search the repository for: + +```text +reputation +fame +renown +Ruhm +Ruf +world reputation +regional reputation +``` + +Use the existing implementation as source of truth. + +- [ ] **Step 4: Verify language strategy** + +Use the project's current localization/content language. Do not hardcode the German labels from the concept screenshot if the production UI has already moved to English. + +- [ ] **Step 5: Commit only if the audit required documentation changes** + +No production code should be changed just to complete the audit. + +--- + +### Task 2: Add character-page view model and facade + +**Files:** +- Create or modify: `apps/web/src/app/features/character/models/character-page.vm.ts` +- Create or modify: `apps/web/src/app/features/character/data-access/character-page.facade.ts` +- Test: `apps/web/src/app/features/character/data-access/character-page.facade.spec.ts` + +**Interfaces:** +- Consumes: current character/equipment/reputation data services +- Produces: `CharacterPageFacade.vm$` or equivalent signal returning `CharacterPageVm` + +- [ ] **Step 1: Write the failing facade test** + +The test must verify that character, equipment, effective stats, global Fame, and regional reputation are combined into one `CharacterPageVm`. + +- [ ] **Step 2: Run the test and verify failure** + +Run the project's established Angular unit-test command for the character facade. + +Expected: FAIL because the facade/view model does not yet exist or does not expose all required data. + +- [ ] **Step 3: Implement the minimal view-model mapping** + +Use the interfaces in section 5, adapted only where the existing domain model has authoritative names. + +- [ ] **Step 4: Keep authority on the server** + +Only format values and calculate visual percentages in the UI layer. Do not move reputation thresholds into the facade. + +- [ ] **Step 5: Run tests** + +Expected: PASS. + +- [ ] **Step 6: Commit** + +```bash +git add apps/web/src/app/features/character +git commit -m "feat: add character page view model" +``` + +--- + +### Task 3: Implement reusable progress-track component + +**Files:** +- Create or modify: `apps/web/src/app/features/character/components/progress-track/progress-track.component.ts` +- Create or modify: `apps/web/src/app/features/character/components/progress-track/progress-track.component.html` +- Create or modify: `apps/web/src/app/features/character/components/progress-track/progress-track.component.scss` +- Test: corresponding component spec + +**Interfaces:** +- Consumes: `ProgressTrackVm` +- Produces: reusable visual track for global Fame and regional Reputation + +- [ ] **Step 1: Write tests for progress percentage** + +Cover at least: + +```text +current below start -> 0 % +current midway -> correct percentage +current above next threshold -> 100 % +next threshold equal to start -> 100 % +``` + +- [ ] **Step 2: Implement clamped percentage calculation** + +```ts +const range = track.nextRankValue - track.rankStartValue; +const percentage = range <= 0 + ? 100 + : Math.min( + 100, + Math.max( + 0, + ((track.currentValue - track.rankStartValue) / range) * 100, + ), + ); +``` + +- [ ] **Step 3: Implement semantic template** + +The rendered component must expose: + +```text +track name +rank title +current / next threshold +remaining amount +visual bar +optional next unlock +``` + +- [ ] **Step 4: Style with existing Ashen Realms assets/tokens** + +Do not invent a new generic progress bar. Reuse existing frame/background assets and token values where possible. + +- [ ] **Step 5: Verify visual states** + +Check 0 %, 5 %, 50 %, 95 %, and 100 % fills; text must remain readable. + +- [ ] **Step 6: Commit** + +```bash +git add apps/web/src/app/features/character/components/progress-track +git commit -m "feat: add fame reputation progress track" +``` + +--- + +### Task 4: Implement Fame/Reputation panel + +**Files:** +- Create or modify: `apps/web/src/app/features/character/components/reputation-progress-panel/**` +- Test: corresponding component spec + +**Interfaces:** +- Consumes: `CharacterProgressionVm` +- Produces: prominent global Fame display plus regional reputation summary + +- [ ] **Step 1: Write rendering tests** + +Verify: + +```text +global Fame is rendered first +current Fame rank is visible +current/required values are visible +remaining amount is visible +current region reputation is first +more-than-limit case shows View all reputation action +``` + +- [ ] **Step 2: Implement global Fame hero row** + +The global track must be visually stronger than individual regional rows. + +- [ ] **Step 3: Implement regional reputation rows** + +Use the reusable `ProgressTrackComponent` in compact mode. + +- [ ] **Step 4: Implement ordering** + +Current region first; then remaining relevant unlocked tracks. + +- [ ] **Step 5: Implement overflow behavior** + +Do not render an unbounded list in the main page. Use the existing details navigation/drawer pattern if one exists. + +- [ ] **Step 6: Commit** + +```bash +git add apps/web/src/app/features/character/components/reputation-progress-panel +git commit -m "feat: add character reputation panel" +``` + +--- + +### Task 5: Implement character equipment composition + +**Files:** +- Create or modify: `apps/web/src/app/features/character/components/character-equipment-panel/**` +- Reuse: existing item slot / tooltip components +- Test: corresponding component spec + +**Interfaces:** +- Consumes: `CharacterSummaryVm`, `EquipmentSlotVm[]` +- Produces: character-artwork-centered equipment presentation + +- [ ] **Step 1: Write slot rendering tests** + +Verify that every authoritative equipment slot renders exactly once and empty slots render in the existing empty-slot style. + +- [ ] **Step 2: Render full-body character artwork** + +Preserve the visual prominence and silhouette from the approved screenshot. + +- [ ] **Step 3: Position equipment slots around the character** + +Use CSS Grid/absolute slot anchors only inside the equipment panel; do not disturb the global shell layout. + +- [ ] **Step 4: Reuse rarity borders and tooltips** + +No duplicate rarity styling. + +- [ ] **Step 5: Verify common viewport sizes** + +At the primary desktop viewport the artwork and all equipment slots must remain visible without overlap. + +- [ ] **Step 6: Commit** + +```bash +git add apps/web/src/app/features/character/components/character-equipment-panel +git commit -m "feat: add character equipment presentation" +``` + +--- + +### Task 6: Implement effective character stats panel + +**Files:** +- Create or modify: `apps/web/src/app/features/character/components/character-stats-panel/**` +- Test: corresponding component spec + +**Interfaces:** +- Consumes: `EffectiveCharacterStatsVm` +- Produces: server-authoritative stat summary + +- [ ] **Step 1: Write rendering test** + +Verify HP, Attack, Weapon Damage, and Armor are rendered from inputs. + +- [ ] **Step 2: Add secondary derived-stat section** + +Render only values delivered by the current effective-stat model; no fake zeros for systems that do not exist. + +- [ ] **Step 3: Ensure no client-side stat authority** + +The component formats values only. + +- [ ] **Step 4: Ensure Combat Power remains hidden by default** + +Do not add Combat Power unless the current design explicitly exposes it. + +- [ ] **Step 5: Commit** + +```bash +git add apps/web/src/app/features/character/components/character-stats-panel +git commit -m "feat: add character stats panel" +``` + +--- + +### Task 7: Compose the final character page + +**Files:** +- Create or modify: `apps/web/src/app/features/character/character-page/character-page.component.ts` +- Create or modify: `apps/web/src/app/features/character/character-page/character-page.component.html` +- Create or modify: `apps/web/src/app/features/character/character-page/character-page.component.scss` +- Modify: route configuration only if `/character` does not already exist +- Test: `character-page.component.spec.ts` + +**Interfaces:** +- Consumes: `CharacterPageFacade`, equipment panel, stats panel, reputation panel +- Produces: `/character` screen + +- [ ] **Step 1: Write page integration test** + +Verify the page contains all three major sections: + +```text +character/equipment +stats +Fame/Reputation +``` + +- [ ] **Step 2: Compose the two-column desktop layout** + +Do not create nested dashboard cards beyond the visual hierarchy in the approved reference. + +- [ ] **Step 3: Reuse the existing AppShell** + +The character feature must occupy only the shell's main content outlet. + +- [ ] **Step 4: Add loading state** + +Use the existing Ashen Realms loading treatment; avoid generic Material spinners if they are not part of the established UI. + +- [ ] **Step 5: Add error state** + +Use the existing panel/message treatment and provide a retry action if the page data fails to load. + +- [ ] **Step 6: Run component tests** + +Expected: PASS. + +- [ ] **Step 7: Commit** + +```bash +git add apps/web/src/app/features/character +git commit -m "feat: implement character page" +``` + +--- + +### Task 8: Add or adapt reputation read API only if required + +**Files:** +- Prefer modify: existing reputation/fame controller/service/DTO files +- Test: existing reputation integration test location + +**Interfaces:** +- Consumes: existing authoritative Fame/Reputation domain model +- Produces: read model required by `CharacterPageFacade` + +- [ ] **Step 1: Confirm whether existing API already provides all required fields** + +Required fields: + +```text +current Fame rank/title +current Fame value +current rank lower threshold +next Fame threshold/title +regional reputation current ranks +regional current values +regional thresholds +optional next unlock labels +``` + +- [ ] **Step 2: If complete, make no backend change** + +Map the existing response in the frontend. + +- [ ] **Step 3: If incomplete, write a failing API test for the missing read fields** + +Do not change progression rules; expose existing authoritative data only. + +- [ ] **Step 4: Extend the existing read DTO/service minimally** + +Avoid a second reputation calculation path. + +- [ ] **Step 5: Run backend tests** + +Expected: PASS. + +- [ ] **Step 6: Commit only if backend code changed** + +```bash +git add apps/api +git commit -m "feat: expose character reputation progress" +``` + +--- + +### Task 9: Visual fidelity pass + +**Files:** +- Modify only the character feature SCSS/templates and shared design tokens/assets when justified + +**Interfaces:** +- Consumes: approved reference screenshot and existing live Ashen Realms screens +- Produces: visually consistent final page + +- [ ] **Step 1: Open the implemented `/character` page at desktop resolution** + +Use the same browser zoom as the existing screenshots. + +- [ ] **Step 2: Compare side-by-side with the approved reference** + +Check: + +```text +shell proportions +panel materials +border style +font hierarchy +character scale +slot scale +right-column density +Fame bar prominence +regional reputation density +footer/topbar continuity +``` + +- [ ] **Step 3: Compare side-by-side with at least one existing world/hunt/combat screen** + +The question is not only "does it match the mockup?" but also "does it still look like the same application?" + +- [ ] **Step 4: Remove generic-web artifacts** + +Reject and replace any element that looks like: + +```text +Material card +SaaS dashboard panel +mobile-game pill +flat grey button +neon progress bar +default HTML progress element +``` + +- [ ] **Step 5: Verify information hierarchy** + +At first glance the eye should land on: + +```text +1. character +2. global Fame progress +3. equipment / core stats +4. regional reputation +``` + +- [ ] **Step 6: Commit** + +```bash +git add apps/web +git commit -m "style: align character page with ashen realms ui" +``` + +--- + +### Task 10: Final verification + +**Files:** +- No new production files expected + +**Interfaces:** +- Consumes: complete character page +- Produces: verified feature + +- [ ] **Step 1: Run frontend unit tests** + +Run the repository's complete web test suite. + +Expected: PASS. + +- [ ] **Step 2: Run backend tests if the reputation API changed** + +Expected: PASS. + +- [ ] **Step 3: Run production build** + +```bash +npm run build +``` + +Expected: PASS. + +- [ ] **Step 4: Verify `/character` manually** + +Check: + +```text +active Character navigation +character artwork renders +equipment matches server state +item tooltips work +stats match server values +Fame progress numbers are exact +Fame percentage is correct +regional reputation is ordered correctly +no XP bar is shown as primary progression if XP has been replaced +no horizontal overflow +no important content overlap +``` + +- [ ] **Step 5: Verify progression edge cases** + +Test with data representing: + +```text +0 % progress +nearly complete rank +exact rank threshold +newly entered rank +no regional reputation yet +one region +many regions +negative/hostile reputation if supported +``` + +- [ ] **Step 6: Final commit** + +```bash +git add . +git commit -m "feat: complete character fame reputation page" +``` + +--- + +# 9. Acceptance criteria + +The feature is complete only when all of the following are true: + +- `/character` uses the existing Ashen Realms AppShell. +- `Character` is visibly active in the existing left navigation. +- The page uses the same material, border, icon, typography, spacing, and accent language as the approved screenshots. +- The character remains the primary visual element of the left half of the page. +- Equipped items use the actual server equipment state. +- The page displays the authoritative effective combat values; it does not recalculate them independently. +- Global Fame/Renown has a prominent XP-like progress bar with exact numbers. +- The player can see current rank, current progress, next threshold, and remaining progress without opening another screen. +- Regional Reputation is shown separately from global Fame. +- Current-region reputation is prioritized. +- Large reputation lists do not turn the page into a scrolling dashboard. +- No obsolete XP progression is reintroduced if the current Fame/Reputation system replaced it. +- No player-facing Combat Power/gear score is added unless the current game design explicitly requires it. +- No duplicate reputation domain logic exists in Angular. +- The page looks like the same product as the world, hunting, combat, and inventory screens when compared side-by-side. +- Frontend tests pass. +- Backend tests pass if backend code changed. +- Production build passes. + +--- + +# 10. Explicit visual anti-goals + +The implementation is rejected if it drifts into any of these directions: + +```text +Generic Angular Material dashboard +Bootstrap card grid +SaaS admin UI +Mobile-game character sheet +Bright glossy fantasy UI +Neon cyberpunk UI +Flat minimal black-and-grey UI +Retro 2000s browsergame table layout +Independent new design system just for Character +``` + +The target remains: + +> **A modern premium dark-fantasy browser RPG, with classic MMORPG information density and a coherent Ashen Realms visual identity.** + +--- + +# 11. Implementation note for the coding agent + +Before changing code, inspect the existing application and treat the current implementation as authoritative for: + +```text +component names +API paths +reputation domain names +rank thresholds +equipment slots +localization +combat stats +design tokens +shared assets +``` + +This plan defines the required **behavior, information hierarchy, and visual result**. It does not authorize replacing existing working systems merely because an example type or filename in this document differs from the current repository. + +When the current repository and this document differ in naming but not in intent, adapt this plan to the existing architecture. When they differ in gameplay semantics, follow the current approved Fame/Reputation specification and preserve the visual/UX requirements defined here. diff --git a/docs/references/character-screenshot.png b/docs/references/character-screenshot.png index 53caf40..a7c5750 100644 Binary files a/docs/references/character-screenshot.png and b/docs/references/character-screenshot.png differ