Code_of_Conquest/docs/phases/Phase9-FrontendPolish.md

Phase 9: Frontend Polish

Goal: Improve UI/UX, add HTMX interactivity, create cohesive design system Priority: Medium Status: Not Started Last Updated: November 29, 2025

---

Overview

Polish the web frontend with a cohesive dark fantasy aesthetic, responsive design, and smooth HTMX-powered interactions. This phase focuses on user experience improvements without adding new features.

Key Goals:

• Dark fantasy visual theme
• Mobile-responsive design
• No full page reloads (HTMX everywhere)
• Reusable component library
• Loading states and error handling
• Subtle animations for feedback

---

Task Groups

Design System (4 tasks)

Task ID	Task	Status	Notes
9.1	Design CSS color palette	⬜	Dark fantasy: deep purples, golds, parchment tones
9.2	Create typography system	⬜	Fantasy-appropriate fonts, readable hierarchy
9.3	Design component library	⬜	Buttons, cards, modals, forms, alerts
9.4	Checkpoint: Review design system	⬜	Verify consistency across components

Color Palette (Example):

:root {
  /* Backgrounds */
  --bg-primary: #1a1a2e;      /* Deep navy */
  --bg-secondary: #16213e;    /* Darker blue */
  --bg-card: #0f3460;         /* Card background */

  /* Accents */
  --accent-gold: #c9a227;     /* Gold highlights */
  --accent-purple: #7b2cbf;   /* Magic purple */
  --accent-red: #9e2a2b;      /* Danger/combat */

  /* Text */
  --text-primary: #e8e8e8;    /* Main text */
  --text-secondary: #a0a0a0;  /* Muted text */
  --text-gold: #ffd700;       /* Important text */
}

Deliverable: Documented design system with CSS variables

---

Responsive Layout (3 tasks)

Task ID	Task	Status	Notes
9.5	Implement mobile navigation	⬜	Hamburger menu, slide-out nav
9.6	Create responsive grid system	⬜	Flexbox/Grid layouts that adapt
9.7	Test on multiple screen sizes	⬜	Mobile, tablet, desktop breakpoints

Breakpoints:

/* Mobile first */
@media (min-width: 640px) { /* Tablet */ }
@media (min-width: 1024px) { /* Desktop */ }
@media (min-width: 1280px) { /* Large desktop */ }

Deliverable: Mobile-friendly responsive layouts

---

HTMX Enhancements (4 tasks)

Task ID	Task	Status	Notes
9.8	Audit all pages for full page reloads	⬜	Identify and fix
9.9	Implement partial updates everywhere	⬜	Use hx-swap, hx-target correctly
9.10	Add hx-indicator loading states	⬜	Show spinners during requests
9.11	Implement hx-push-url for history	⬜	Browser back/forward works

HTMX Pattern:

<button hx-post="/api/action"
        hx-target="#result-area"
        hx-swap="innerHTML"
        hx-indicator="#loading-spinner">
  Take Action
</button>
<div id="loading-spinner" class="htmx-indicator">
  <span class="spinner"></span> Loading...
</div>

Deliverable: Seamless HTMX-powered interactions

---

Reusable Components (4 tasks)

Task ID	Task	Status	Notes
9.12	Create character card component	⬜	partials/character_card.html
9.13	Create item card component	⬜	partials/item_card.html - rarity colors
9.14	Create stat bar component	⬜	partials/stat_bar.html - HP, mana, XP
9.15	Create notification/toast component	⬜	partials/toast.html - success, error, info

Deliverable: Reusable Jinja2 partial templates

---

Feedback & Polish (4 tasks)

Task ID	Task	Status	Notes
9.16	Add loading states for AI calls	⬜	Typing indicator, "DM is thinking..."
9.17	Implement user-friendly error displays	⬜	Friendly messages, not stack traces
9.18	Add dice roll animations	⬜	static/js/dice-roller.js - visual d20 roll
9.19	Add combat action animations	⬜	Flash effects for damage, healing

Deliverable: Polished user feedback

---

Cross-Browser Testing (2 tasks)

Task ID	Task	Status	Notes
9.20	Test on Chrome, Firefox, Safari	⬜	Fix any browser-specific issues
9.21	Final Checkpoint: UI review	⬜	Complete visual audit

Deliverable: Cross-browser compatible UI

---

Files to Create/Modify

New Files:

• /public_web/static/css/design-system.css - CSS variables, base styles
• /public_web/static/css/components.css - Component styles
• /public_web/static/js/dice-roller.js - Dice animation
• /public_web/static/js/toast.js - Toast notifications
• /public_web/templates/partials/character_card.html
• /public_web/templates/partials/item_card.html
• /public_web/templates/partials/stat_bar.html
• /public_web/templates/partials/toast.html
• /public_web/templates/partials/loading.html

Modified Files:

• /public_web/templates/base.html - Include new CSS/JS, design tokens
• /public_web/templates/**/*.html - Apply design system, HTMX patterns

---

Testing Criteria

Visual Testing

• Design system applied consistently
• Colors and typography match spec
• Components look correct in all states

Responsive Testing

• Mobile layout works (320px - 640px)
• Tablet layout works (640px - 1024px)
• Desktop layout works (1024px+)
• Navigation works on all sizes

HTMX Testing

• No full page reloads during gameplay
• Loading indicators show during requests
• Browser back/forward works
• Errors display gracefully

Browser Testing

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Mobile Safari
• Chrome Mobile

---

Success Criteria

• Cohesive dark fantasy aesthetic
• Mobile-responsive on all pages
• No full page reloads in main flows
• Loading states for all async operations
• User-friendly error messages
• Reusable component library
• Works across major browsers

---

Dependencies

Requires (already implemented):

• All core gameplay features
• HTMX integration (basic)

---

Task Summary

Group	Tasks	Checkpoints
Design System	3	1
Responsive Layout	3	0
HTMX Enhancements	4	0
Reusable Components	4	0
Feedback & Polish	4	0
Cross-Browser Testing	1	1
Total	19	2