# 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):**
```css
: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:**
```css
/* 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:**
```html
<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** |