From c50f58dafce7325c1148364fd12ec36521d6a738 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Tue, 24 Feb 2026 16:10:36 -0500 Subject: [PATCH] docs: add wood paneling font color fix plan - Create comprehensive implementation plan for smart font colors on wood paneling backgrounds - Addresses readability issues where current theme colors don't contrast well with wood textures - Includes CSS strategy, TypeScript changes, texture replacements, and testing checklist - Ready to implement when needed --- WOOD_PANELING_FONT_FIX_PLAN.md | 231 +++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 WOOD_PANELING_FONT_FIX_PLAN.md diff --git a/WOOD_PANELING_FONT_FIX_PLAN.md b/WOOD_PANELING_FONT_FIX_PLAN.md new file mode 100644 index 0000000..adb252a --- /dev/null +++ b/WOOD_PANELING_FONT_FIX_PLAN.md @@ -0,0 +1,231 @@ +# Wood Paneling Smart Font Colors Fix Plan + +## Overview + +Add smart font colors for wood paneling backgrounds on the dashboard. When a wood texture is applied to `#collections-container`, the text color will automatically adjust to ensure readability. + +## Current State + +- Textures exist: `wood-light.png`, `wood-dark.png`, `wood-mahogany.png` +- **Issue**: Current `wood-mahogany.png` is too light (should be darkest) +- **Issue**: Current `wood-dark.png` may also need replacement (verify brightness) +- Wood paneling applies background to `#collections-container` +- Text colors currently use theme CSS variables (`var(--text-primary)`, `var(--text-secondary)`) +- Problem: Theme-based text colors may not contrast well with wood textures + +## Requirements + +1. **Keep existing naming**: `wood-light`, `wood-dark`, `wood-mahogany` (no renaming needed) +2. **Verify texture brightness**: Mahogany must be darkest, dark is medium, light is lightest (DO NOT change wood-light) +3. **Smart font colors**: Dark wood needs light text, light wood needs dark text +4. **Scope**: All text within `#collections-container` when wood is active +5. **Fallback**: When no wood is selected, use theme colors (current behavior) + +## Implementation Plan + +### Step 0: Verify and Replace Mahogany Texture + +The current `wood-mahogany.png` is too light and needs to be replaced with the darkest texture from the source pack. **DO NOT change `wood-light.png`.** + +**Download and extract texture pack:** +```bash +cd /tmp +curl -O https://opengameart.org/sites/default/files/wood_0.zip +unzip wood_0.zip +cd wood_0 +ls -la # Should show wood1.png, wood2.png, etc. +``` + +**Rename extracted textures:** +```bash +# From /tmp/wood_0, copy to bookhoard textures directory +cd web/static/textures +cp /tmp/wood_0/wood1.png wood-dark.png + +# wood2.png → wood-mahogany (darkest) +cp /tmp/wood_0/wood2.png wood-mahogany.png + +# wood-light.png remains unchanged (keep existing file) + +# Verify +ls -lh web/static/textures/ +``` + +**Brightness validation checklist:** +- [ ] `wood-dark` (was wood1.png) is medium-dark brown +- [ ] `wood-mahogany` (was wood2.png) is the darkest, deep reddish-brown +- [ ] `wood-light` remains unchanged (lightest) + +### Step 1: Update `woodPaneling.ts` + +Add `data-wood` attribute to the container when applying backgrounds. This allows CSS selectors to target wood-specific styling. + +**File**: `web/src/woodPaneling.ts` + +**Change 1** - In `applyWoodPaneling()` function, remove wood classes and data attribute: +```typescript +// Before: +container.classList.remove('bg-wood-light', 'bg-wood-dark', 'bg-wood-mahogany'); + +// After: +container.classList.remove('bg-wood-light', 'bg-wood-dark', 'bg-wood-mahogany'); +container.removeAttribute('data-wood'); +``` + +**Change 2** - In `applyWoodPaneling()` function, add wood class and data attribute: +```typescript +// Before: +if (paneling !== 'none') { + container.classList.add(`bg-${paneling}`); +} + +// After: +if (paneling !== 'none') { + container.classList.add(`bg-${paneling}`); + container.setAttribute('data-wood', paneling); +} +``` + +### Step 2: Update `woodPanelingInit.ts` + +Apply the same `data-wood` attribute during early initialization to prevent flash. + +**File**: `web/src/woodPanelingInit.ts` + +**Change** - In `applyPaneling()` function, add data-wood attribute: +```typescript +// Before: +const applyPaneling = () => { + const container = document.getElementById('collections-container'); + if (container) { + container.classList.add(`bg-${woodPaneling}`); + } +}; + +// After: +const applyPaneling = () => { + const container = document.getElementById('collections-container'); + if (container) { + container.classList.add(`bg-${woodPaneling}`); + container.setAttribute('data-wood', woodPaneling); + } +}; +``` + +### Step 3: Add Smart Font Color CSS + +Add CSS variables and selectors for each wood type in `input.css`. + +**File**: `web/static/input.css` + +**Add to `@layer components` section** - Add after the `.bg-wood-inactive` rule (around line 207-208), before the closing `}` of @layer components: + +```css +/* Smart text colors for wood paneling backgrounds */ +/* Wood Light - needs dark text for contrast */ +#collections-container[data-wood="wood-light"] { + --wood-text-primary: #1a1a1a; + --wood-text-secondary: #4a4a4a; + --wood-border: #2a2a2a; +} + +/* Wood Dark - needs medium text */ +#collections-container[data-wood="wood-dark"] { + --wood-text-primary: #d0d0d0; + --wood-text-secondary: #a0a0a0; + --wood-border: #5a4a3a; +} + +/* Wood Mahogany - needs light text (darkest background) */ +#collections-container[data-wood="wood-mahogany"] { + --wood-text-primary: #f5f5f5; + --wood-text-secondary: #c0c0c0; + --wood-border: #5c3317; +} + +/* Apply wood-specific text colors to all text within collections container */ +#collections-container[data-wood] h1, +#collections-container[data-wood] h2, +#collections-container[data-wood] h3, +#collections-container[data-wood] p, +#collections-container[data-wood] span, +#collections-container[data-wood] a, +#collections-container[data-wood] button { + color: var(--wood-text-primary) !important; +} + +#collections-container[data-wood] .text-sm, +#collections-container[data-wood] .text-secondary, +#collections-container[data-wood] p.text-sm { + color: var(--wood-text-secondary) !important; +} + +/* Preserve accent color for links */ +#collections-container[data-wood] a[style*="accent"] { + color: var(--accent) !important; +} + +/* Add subtle borders to book cards on wood backgrounds */ +#collections-container[data-wood] .book-card { + border: 1px solid var(--wood-border); +} +``` + +### Step 4: Build and Verify + +Run build commands to verify changes compile correctly. + +```bash +# Build CSS first (regenerates style.css with new utilities) +npm run build:css + +# Then build TypeScript +npm run build:ts + +# Verify Go templates compile +go build ./... +``` + +## Files Modified + +| File | Changes | +|------|---------| +| `web/static/textures/wood-dark.png` | Rename from extracted wood1.png | +| `web/static/textures/wood-mahogany.png` | Rename from extracted wood2.png | +| `web/static/textures/wood-light.png` | **DO NOT CHANGE** | +| `web/src/woodPaneling.ts` | Add/remove `data-wood` attribute | +| `web/src/woodPanelingInit.ts` | Add `data-wood` attribute | +| `web/static/input.css` | Add smart font color CSS | + +## Testing Checklist + +### Texture Verification +- [ ] Mahogany is visibly the darkest of all three textures +- [ ] Wood-dark is medium brightness +- [ ] Wood-light is lightest (unchanged) +- [ ] All textures are PNG format + +### Font Color Testing + +- [ ] `wood-light` shows dark text (#1a1a1a) +- [ ] `wood-dark` shows light text (#d0d0d0) +- [ ] `wood-mahogany` shows light text (#f5f5f5) +- [ ] "None" option uses theme colors (no `data-wood` attribute) +- [ ] Book cards have subtle borders on wood backgrounds +- [ ] "View All" links preserve accent color +- [ ] No console errors + +## Wood Brightness Reference + +| Source File | Target File | Brightness | Text Color | +|------------|-------------|------------|------------| +| `wood-light.png` | `wood-light.png` | Lightest | Dark (#1a1a1a) | **DO NOT CHANGE** | +| `wood1.png` | `wood-dark.png` | Medium | Medium (#d0d0d0) | +| `wood2.png` | `wood-mahogany.png` | **Darkest** | Light (#f5f5f5) | + +## Notes + +- The `data-wood` attribute is only present when a wood option is selected +- Absence of `data-wood` attribute means theme colors apply (no breaking change) +- CSS `!important` is used to override theme CSS variables within the selector scope +- Book card borders help separate content from wood texture