chore(agent): add phases 20-23 from TODO.md — four owner-confirmed bug fixes; clear TODO.md
This commit is contained in:
@@ -0,0 +1,114 @@
|
||||
# Phase 22 — Animated Background: Make It Actually Animate
|
||||
|
||||
**Source:** `TODO.md` L5 — *"Fix background animation not working, just
|
||||
blinking"*
|
||||
**Story:** `.agent/user_stories/background-animation.md` (created by task 02)
|
||||
**Context:** `frontend/assets/styles.css` — the phase-08 animated
|
||||
background block (~lines 60–100): `body::before` (44px drifting grid,
|
||||
1px lines at ~35% `--line` alpha, radial mask
|
||||
`radial-gradient(120% 90% at 50% 0%, black 25%, transparent 78%)`,
|
||||
`animation: bg-grid-drift 60s linear infinite`) and `body::after` (two
|
||||
soft radial glows, `animation: bg-glow-breathe 14s ease-in-out infinite
|
||||
alternate`, opacity 0.65↔1 + scale 1↔1.05). Both layers are
|
||||
`position: fixed; inset: 0; z-index: -1; pointer-events: none`. `html`
|
||||
owns the `var(--bg)` canvas and `body` is `background: transparent`
|
||||
(~lines 42–54) — if any later rule occludes that, the layers vanish.
|
||||
The **phase-08 design comments are the spec** for what "working" means.
|
||||
|
||||
## Objective
|
||||
Owner report 2026-08-24: the background "just blinks" — i.e. the motion
|
||||
the phase-08 design promised (a slow, seamless grid drift + a gentle
|
||||
glow breathe) is not perceived; at most a flicker/blink is visible.
|
||||
Diagnose which layer(s) actually fail in a real Chromium viewport, fix
|
||||
the CSS, and leave a background that visibly and smoothly animates as
|
||||
designed — no blink, no static frame, no jank.
|
||||
|
||||
## Owner-confirmed (2026-08-24, roadmap A3)
|
||||
1. **Intended effect = the phase-08 design comments:** seamless 60s grid
|
||||
drift (one cell per loop) + 14s ease glow breathing. The fix serves
|
||||
that design, not a redesign.
|
||||
2. **Pure CSS, zero JS** (phase-08 anchor) — no animation JS, no new
|
||||
assets, no `filter: blur` (perf note in the block).
|
||||
|
||||
## Design / diagnostic plan
|
||||
The fix is found, not guessed — work through this checklist in a real
|
||||
Chromium window (dev server, full page, ~15s of observation):
|
||||
1. **Per-layer visibility:** toggle each pseudo-element (DevTools
|
||||
generated-content / a temp outline) and screenshot — is the grid
|
||||
visible at all? Is only the glow (the "blink" the user perceives)
|
||||
alive?
|
||||
2. **Grid layer:** sample `background-position` on `body::before` at two
|
||||
timestamps — is it actually moving? Is the radial mask fading the
|
||||
visible region so small that the 44px/60s drift is imperceptible?
|
||||
(If the drift is real but too faint: raise the grid line alpha and/or
|
||||
the mask's visible radius — smallest change that reads as "smooth
|
||||
drift".)
|
||||
3. **Glow layer:** is the 14s breathe reading as a *blink*? (If the
|
||||
opacity swing 0.65↔1 is perceived as pulsing: lengthen the period
|
||||
and/or narrow the opacity delta so it reads as breathing.)
|
||||
4. **Occlusion check:** confirm nothing later in `styles.css` (or in
|
||||
`html`/`body` rules) paints an opaque background over the
|
||||
`z-index: -1` layers — the phase-08 comment at ~line 42 is the
|
||||
contract.
|
||||
5. **Apply the fix in `styles.css`** — document the found root cause in
|
||||
the phase report (screenshot before/after in
|
||||
`.agent/screenshots/22_background_animation/`).
|
||||
|
||||
## Dependencies
|
||||
- `08_story_dark_tech_theme` (complete) — owns the layers, the palette,
|
||||
and the "pure CSS, zero JS" anchor this phase must respect.
|
||||
- `07_story_responsive_polish` (complete) — no new overflow at 360px
|
||||
(both layers are `fixed; inset: 0` — keep it that way).
|
||||
|
||||
## Tasks
|
||||
1. `01_fix_background_animation.md` — diagnosis + the CSS fix +
|
||||
source-level unit pins.
|
||||
2. `02_e2e_story_suite_commit.md` — `tests/e2e/test_background_animation.py`
|
||||
(the story gate, isolated), regression suites, story file, final
|
||||
validation, the single atomic commit, phase move to `complete/`.
|
||||
|
||||
## Locked decisions
|
||||
- **Phase-08 anchor honored** — pure CSS, zero JS, no `filter: blur`,
|
||||
WCAG AA palette untouched (background layers carry no text).
|
||||
**A11 untouched** — no CDN, no new assets. **A16 honored** — one new
|
||||
story E2E suite + adapted regressions. No anchor changed.
|
||||
|
||||
## Testing & Quality
|
||||
- **Unit (source-level, new `tests/unit/test_background_animation.py`,
|
||||
repo source-pin pattern):** `styles.css` still defines
|
||||
`@keyframes bg-grid-drift` and `@keyframes bg-glow-breathe`;
|
||||
`body::before` animates `bg-grid-drift` with `linear infinite`;
|
||||
`body::after` animates `bg-glow-breathe`; both layers remain
|
||||
`position: fixed; z-index: -1; pointer-events: none`; `html` keeps
|
||||
`background: var(--bg)` and `body` keeps `background: transparent`
|
||||
(the no-occlusion contract). Pin the **final** values the fix lands
|
||||
on (durations/opacities may move per the design plan).
|
||||
- **Integration:** none (no `app/` changes).
|
||||
- **Coverage:** frontend-only; the >90% `app/` gate is unaffected.
|
||||
- **E2E:** `tests/e2e/test_background_animation.py` (task 02), green
|
||||
**in isolation** (prereq `podman compose up -d db`).
|
||||
- **Lint/types:** `uv run ruff check . && uv run pyright` clean.
|
||||
|
||||
## Completion Criteria
|
||||
- [ ] In a real Chromium viewport, the background visibly and smoothly
|
||||
animates (grid drift + glow breathe) — screenshot before/after in
|
||||
the phase report; owner's "just blinking" perception gone.
|
||||
- [ ] Root cause documented in `.agent/reports/22_background_animation/`.
|
||||
- [ ] `uv run pytest` green; `uv run pytest --cov=app
|
||||
--cov-report=term-missing` ≥ today's number.
|
||||
- [ ] `uv run pytest tests/e2e/test_background_animation.py -v --no-cov`
|
||||
green in isolation; regressions green in isolation:
|
||||
`test_dark_tech_theme.py`, `test_responsive_polish.py`.
|
||||
- [ ] `uv run ruff check . && uv run pyright` clean.
|
||||
- [ ] UI Structure Check (AGENTS.md rule 5): layers stay behind content
|
||||
(`z-index: -1`, `pointer-events: none`), no text/contrast impact,
|
||||
no 360px overflow.
|
||||
- [ ] `.agent/user_stories/background-animation.md` exists.
|
||||
- [ ] One `--no-gpg-sign` commit (below);
|
||||
`.agent/phases/todo/22_background_animation/` moved to
|
||||
`.agent/phases/complete/`.
|
||||
|
||||
## Commit
|
||||
```bash
|
||||
git add -A .agent/ frontend/ tests/ && git commit --no-gpg-sign -m "fix(ui): animated background actually animates — grid drift and glow breathe per the phase-08 design"
|
||||
```
|
||||
Reference in New Issue
Block a user