From f2e1dfff264d73f652df180beddf2fc4950d73a7 Mon Sep 17 00:00:00 2001 From: Halil Ibrahim Ozturk Date: Thu, 6 Aug 2026 11:42:23 +0200 Subject: [PATCH 01/58] docs: specify cosmic black hole interface redesign --- .../2026-08-06-cosmic-black-hole-ui-design.md | 315 ++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-06-cosmic-black-hole-ui-design.md diff --git a/docs/superpowers/specs/2026-08-06-cosmic-black-hole-ui-design.md b/docs/superpowers/specs/2026-08-06-cosmic-black-hole-ui-design.md new file mode 100644 index 0000000..f406537 --- /dev/null +++ b/docs/superpowers/specs/2026-08-06-cosmic-black-hole-ui-design.md @@ -0,0 +1,315 @@ +# Inmerson Math-CS Cosmic Black Hole UI Design + +**Date:** 2026-08-06 +**Status:** Approved visual direction, pending written-spec review +**Repository:** `Inmerson/Math-CS` +**Reference:** The approved desktop mockup generated in this conversation, featuring a photorealistic black hole hero, dark glass panels, a persistent left sidebar, two course cards, and compact Math Lab / Formula Workspace cards. + +## 1. Goal + +Transform the existing Math-CS interface into a premium academic sci-fi product whose visual identity is built around a photorealistic three-dimensional black hole. The cosmic treatment must be strongest on the dashboard hero and subtle elsewhere so that lessons, exercises, formulas, and assessments remain calm, readable, and efficient. + +The redesign is visual and structural only. Existing curriculum data, navigation destinations, local progress storage, quiz grading, laboratories, examinations, formulas, and assistant behavior must remain functionally unchanged. + +## 2. Design Principles + +1. **Cinematic first impression:** The dashboard hero presents the black hole as the dominant visual anchor. +2. **Academic clarity:** Content hierarchy and reading contrast take priority over decorative effects. +3. **Controlled depth:** Glass layers, restrained glow, and starfield depth establish atmosphere without visual noise. +4. **Two-course distinction:** Math I uses cool blue accents; Math II uses soft violet accents. +5. **Consistent product system:** Dashboard, course hubs, lessons, laboratories, practice, exams, progress, formulas, and assistant share the same tokens and panel language. +6. **Accessible motion:** Animation remains subtle and respects `prefers-reduced-motion`. + +## 3. Visual System + +### 3.1 Palette + +- Page base: near-black `#030711` +- Deep navy surface: `#07111f` +- Raised surface: `#0b1726` +- Glass surface: translucent navy-black between 72% and 88% opacity +- Primary text: warm white `#f5f7fb` +- Secondary text: slate-blue `#9aa9bd` +- Math I accent: electric blue / cyan range +- Math II accent: violet / indigo range +- Black-hole accretion light: restrained warm white, pale gold, and soft copper +- Borders: low-opacity blue-white, with brighter active-state edges + +### 3.2 Typography + +- Use a clean sans-serif stack suitable for technical learning. +- Hero heading: large, confident, tight tracking. +- Section labels: small uppercase text with increased tracking. +- Body copy: comfortable line-height and muted contrast. +- Formula and code surfaces may retain monospace styling where already present. + +### 3.3 Surfaces + +Introduce reusable visual classes or components for: + +- `cosmic-shell`: page-level dark spatial background +- `cosmic-glass`: translucent panel with blur, fine border, and restrained shadow +- `cosmic-card`: interactive elevated card +- `cosmic-divider`: faint luminous horizontal divider +- `cosmic-glow-blue` and `cosmic-glow-violet`: course-specific accent treatments +- `cosmic-button`: dark-to-accent gradient button with a subtle focus-visible halo + +No panel should use excessive blur or glow. Text must remain legible against every image and gradient. + +## 4. Asset Strategy + +### 4.1 Black Hole Hero Asset + +Create and store one optimized photorealistic black-hole image under a stable path such as: + +`public/assets/cosmic/black-hole-hero.webp` + +Requirements: + +- Wide cinematic composition suitable for a desktop hero. +- Black-hole event horizon positioned toward the upper-right. +- Visible gravitational lensing and a realistic accretion disk. +- Darker negative space on the left for title and description. +- No embedded text, logo, watermark, interface, person, or device frame. +- Export WebP or AVIF with a practical balance between detail and transfer size. +- Provide a lower-resolution mobile variant only if responsive testing shows the desktop asset is too expensive. + +The generated dashboard mockup is a visual reference, not an image to place directly as the entire interface background. + +### 4.2 Supporting Visuals + +Course cards use lightweight SVG/CSS illustrations rather than additional large raster images: + +- Math I: luminous wireframe function surface or curve plot. +- Math II: luminous vector axes, matrix grid, or wireframe cube. +- Math Lab: compact orbital or nebula accent. +- Formula Workspace: faint integral, matrix, and eigenvalue notation texture. + +These visuals are decorative and must use `aria-hidden="true"`. + +## 5. Application Shell + +### 5.1 Desktop + +- Persistent left sidebar, approximately 272–288 px wide. +- Main content occupies the remaining viewport with a maximum readable width. +- Sidebar uses a nearly black translucent surface and a fine right border. +- Brand area includes a small black-hole-ring mark and the two-line name `Inmerson Math-CS`. +- Active navigation receives a blue-violet edge, subtle internal glow, and high-contrast text. +- Secondary tools remain visually integrated instead of appearing as an unrelated footer block. +- A compact overall-progress card sits near the bottom of the sidebar, using real progress derived from current state. + +### 5.2 Mobile and Tablet + +- Preserve the existing slide-out navigation and bottom navigation patterns. +- Hero becomes vertically stacked: text first, black-hole image second or behind a dark overlay. +- Course cards stack to one column. +- Utility cards stack or become horizontally scrollable only if width testing requires it. +- Decorative starfield and image layers reduce in complexity on small screens. + +## 6. Dashboard + +### 6.1 Hero + +Replace the plain header with a cinematic hero panel. + +Structure: + +- Large `Inmerson Math-CS` title. +- Tagline `Interactive Mathematics for Computer Science`. +- Existing brand description. +- Thin luminous divider with a small light point. +- Photorealistic black-hole image on the right, blended into the surface with overlays and edge gradients. +- Optional compact notification/avatar controls are excluded from the initial implementation because no account or notification system exists. + +The hero must remain readable when the image fails to load. A CSS gradient fallback is mandatory. + +### 6.2 Search + +- Place the existing learning search directly below or partially overlapping the hero’s lower edge. +- Use a dark glass field with a leading icon. +- Retain existing search behavior and result destinations. +- A visual keyboard-shortcut badge may be displayed, but it must not imply a shortcut unless the shortcut is actually implemented. The initial implementation should omit the badge unless keyboard handling is added and tested. + +### 6.3 Course Cards + +Both course cards share one component structure but use course-specific accents. + +Each card contains: + +- Course label and title. +- Official Polish title. +- Course description. +- Decorative course illustration. +- Horizontal progress bar. +- Compact circular percentage indicator. +- Completed-topic count. +- Recommended next topic. +- Latest checkpoint result. +- Strong course-specific call-to-action button. + +Math I uses blue/cyan. Math II uses violet/indigo. The cards must not become visually identical except for text. + +### 6.4 Utility Cards + +Math Lab and Formula Workspace become wide compact cards below the courses. + +- Large icon medallion on the left. +- Title and short description. +- Subtle domain-specific background visual. +- Compact action button on the right. +- Entire card remains keyboard accessible. + +## 7. Internal Views + +The strongest photorealistic black-hole image appears only on the dashboard. Other views inherit the cosmic system more quietly. + +### Course Hub + +- Course-specific blue or violet ambient gradient. +- A compact course header with progress and recommended next topic. +- Topic cards use glass surfaces and clear completion states. + +### Lesson Workspace + +- Reading-focused central column. +- Optional low-opacity starfield or grid only in page margins. +- Learn, Visualize, Practice, CS Connection, and Quiz stages have distinct but restrained panel accents. +- No large black-hole imagery behind lesson text. + +### Labs + +- Dark instrument-panel feel. +- Graphs, matrices, axes, inputs, and results remain the visual focus. +- Accent glow reflects the active lab rather than adding unrelated decorative imagery. + +### Practice and Exams + +- Calm, high-contrast assessment surfaces. +- Cosmic styling limited to headers, borders, buttons, and progress indicators. +- Correct/incorrect feedback colors remain semantically clear. + +### Progress + +- Use luminous rings, bars, and course-separated statistics. +- The sidebar overall-progress value and Progress view use the same derived percentage formula. + +### Formula Workspace and Assistant + +- Formula Workspace resembles a dark technical notebook with faint notation textures. +- Assistant uses a deep-space console tone without reducing chat readability. + +## 8. Component Architecture + +Create focused presentation components rather than placing the entire redesign in `DashboardView.tsx`. + +Expected components: + +- `components/cosmic/CosmicHero.tsx` +- `components/cosmic/CosmicLogoMark.tsx` +- `components/cosmic/CosmicProgressRing.tsx` +- `components/cosmic/CourseVisual.tsx` +- `components/cosmic/UtilityCard.tsx` +- Optional `components/cosmic/Starfield.tsx` if CSS-only background logic becomes too large for `AnimatedBackground.tsx` + +Modify existing boundaries: + +- `App.tsx`: shell spacing and mobile header styling only. +- `components/AnimatedBackground.tsx`: global subtle starfield and gradient layers. +- `components/Sidebar.tsx`: branded logo, active states, overall progress card; accept derived progress data through props rather than reading storage directly. +- `views/DashboardView.tsx`: compose hero, search, course grid, and utility cards. +- `components/course/CourseCard.tsx`: new premium card layout while retaining existing data and navigation props. +- `index.css`: design tokens, reusable surfaces, reduced-motion behavior, and safe image overlays. + +Business logic and storage functions must not be moved into presentation components. + +## 9. Data Flow + +- `App.tsx` continues to own `MathCsState`. +- Derived overall progress is calculated through a pure utility function. +- `Sidebar` receives the overall percentage as a prop. +- `DashboardView` continues to receive state and navigation callbacks. +- `CourseCard` receives already-derived course progress, completion count, recommendation, and latest quiz. +- No new remote API, login, notification, analytics, or cloud persistence is introduced. + +## 10. Motion + +Allowed motion: + +- Very slow background drift. +- Gentle hero-image scale or parallax limited to a few pixels. +- Card hover elevation and border glow. +- Progress animations when values change. +- Route-content fade/translate consistent with existing Framer Motion usage. + +Disallowed motion: + +- Fast star movement. +- Spinning black-hole animation that distracts from reading. +- Continuous large-scale parallax. +- Motion that hides initial content or causes layout shift. + +All nonessential motion is disabled or reduced under `prefers-reduced-motion`. + +## 11. Accessibility + +- Maintain one page-level `main` landmark and logical heading order. +- All controls preserve visible keyboard focus. +- Text overlays meet WCAG AA contrast against the hero image. +- Decorative imagery uses empty alt text or `aria-hidden`. +- The hero black-hole image is decorative; the educational meaning is communicated in text. +- Progress rings expose a text value and accessible label. +- Hover effects have equivalent focus-visible states. +- Mobile navigation remains operable without pointer input. + +## 12. Performance + +- Lazy-load noncritical visual assets where practical. +- Hero image must use explicit dimensions or aspect ratio to prevent layout shift. +- Use responsive `srcset` only when multiple image variants are actually generated. +- Avoid video, WebGL, or real-time 3D rendering in this redesign. +- The visual target is photorealistic, but implementation uses an optimized raster hero plus CSS/SVG effects rather than a heavy 3D runtime. +- Preserve the existing GitHub Pages deployment path and base URL. + +## 13. Testing and Acceptance Criteria + +### Automated + +- Existing behavior tests remain green. +- Add tests for overall-progress derivation. +- Add component tests for: + - sidebar progress and active navigation; + - dashboard hero title and accessible fallback structure; + - Math I and Math II distinct accents/visual variants; + - utility-card destinations; + - progress ring accessible labeling. +- Keep the Tailwind production-output regression test passing. +- Run `npm run verify` and `npm run build:pages`. + +### Visual and Responsive + +Verify at minimum: + +- 1440 px desktop. +- 1024 px tablet landscape. +- 768 px tablet portrait. +- 390 px mobile. + +Acceptance conditions: + +- Dashboard resembles the approved mockup in hierarchy, tone, spacing, and atmosphere. +- Black-hole visual is prominent on desktop but does not obscure title or search. +- Course cards are distinct and balanced. +- No horizontal overflow at target widths. +- Internal lesson and assessment views remain readable and calmer than the dashboard. +- Existing navigation, quizzes, laboratories, progress, formulas, and assistant remain functional. +- GitHub Pages deployment serves the redesigned assets correctly under `/Math-CS/`. + +## 14. Non-Goals + +- No account system, avatar profile, notifications, social features, or cloud sync. +- No WebGL black-hole simulation. +- No replacement of curriculum content. +- No new grading logic. +- No arbitrary animation library beyond existing dependencies. +- No redesign that sacrifices mobile usability or lesson readability for visual spectacle. From 2e60329811bd78af4204ad53c2fcd1ee8ed0b990 Mon Sep 17 00:00:00 2001 From: Halil Ibrahim Ozturk Date: Thu, 6 Aug 2026 11:54:04 +0200 Subject: [PATCH 02/58] docs: add cosmic black hole UI implementation plan --- .../plans/2026-08-06-cosmic-black-hole-ui.md | 899 ++++++++++++++++++ 1 file changed, 899 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-06-cosmic-black-hole-ui.md diff --git a/docs/superpowers/plans/2026-08-06-cosmic-black-hole-ui.md b/docs/superpowers/plans/2026-08-06-cosmic-black-hole-ui.md new file mode 100644 index 0000000..d38bb04 --- /dev/null +++ b/docs/superpowers/plans/2026-08-06-cosmic-black-hole-ui.md @@ -0,0 +1,899 @@ +# Cosmic Black Hole UI 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:** Transform Inmerson Math-CS into the approved premium academic sci-fi interface with a photorealistic black-hole dashboard hero, glass navigation shell, course-specific visual identities, and restrained cosmic styling throughout internal learning views. + +**Architecture:** Keep all curriculum, persistence, grading, lab, and navigation behavior unchanged. Add a small `components/cosmic` presentation layer, one pure overall-progress selector, a single optimized dashboard hero asset, and reusable CSS tokens/classes so the visual system is consistent without moving business logic into UI components. + +**Tech Stack:** React 19, TypeScript 5.8, Vite 6.4, Tailwind CSS 4, Framer Motion 12, Lucide React, Vitest 4, Testing Library, CSS/SVG presentation, WebP asset, GitHub Actions and GitHub Pages. + +## Global Constraints + +- The strongest photorealistic black-hole image appears only on the dashboard. +- Math I uses blue/cyan accents; Math II uses violet/indigo accents. +- Existing curriculum data, navigation destinations, local progress storage, quiz grading, laboratories, examinations, formulas, and assistant behavior remain functionally unchanged. +- Do not add authentication, notifications, analytics, cloud persistence, remote APIs, or WebGL dependencies. +- The black-hole image is decorative, has no embedded text or watermark, and must retain a CSS gradient fallback. +- All text overlays must remain readable at WCAG AA contrast. +- All interactive controls retain visible `:focus-visible` styling. +- Nonessential animation must respect `prefers-reduced-motion`. +- Desktop sidebar remains approximately 272–288 px; mobile keeps the slide-out sidebar and bottom navigation. +- Run `npm run verify` and `npm run build:pages` before merging or deploying. + +--- + +## File Map + +### Create + +- `public/assets/cosmic/black-hole-hero.webp` — optimized standalone hero artwork with negative space on the left and event horizon on the upper-right. +- `components/cosmic/CosmicHero.tsx` — dashboard title, tagline, description, luminous divider, and decorative image layer. +- `components/cosmic/CosmicHero.test.tsx` — hero semantics, fallback class, and decorative-image assertions. +- `components/cosmic/CosmicLogoMark.tsx` — CSS/SVG black-hole ring brand mark. +- `components/cosmic/CosmicProgressRing.tsx` — accessible percentage ring used by sidebar and course cards. +- `components/cosmic/CosmicProgressRing.test.tsx` — percentage clamping and accessible-label tests. +- `components/cosmic/CourseVisual.tsx` — lightweight SVG visual for Math I and Math II. +- `components/cosmic/UtilityCard.tsx` — reusable Math Lab / Formula Workspace card. +- `components/cosmic/CosmicPageHeader.tsx` — restrained internal-view header with optional course accent. +- `components/cosmic/CosmicPageHeader.test.tsx` — heading hierarchy and accent tests. +- `scripts/cosmic-assets.test.ts` — verifies required hero asset path and transfer-size budget. + +### Modify + +- `index.css` — cosmic tokens, glass surfaces, starfield, hero overlays, buttons, focus, responsive behavior, and reduced-motion rules. +- `components/AnimatedBackground.tsx` — subtle global starfield and ambient gradients only. +- `utils/progress.ts` — add pure `getOverallProgress` selector. +- `utils/progress.test.ts` — define overall-progress behavior. +- `App.tsx` — pass overall progress to sidebar and apply shell spacing/classes. +- `App.test.tsx` — verify shell landmark and real overall-progress propagation. +- `components/Sidebar.tsx` — logo mark, integrated navigation groups, active styling, and progress card. +- `components/Sidebar.test.tsx` — brand, progress card, active navigation, and existing navigation coverage. +- `views/DashboardView.tsx` — compose `CosmicHero`, search, course cards, and utility cards. +- `views/DashboardView.test.tsx` — hero/search/course/utility structure and navigation behavior. +- `components/course/CourseCard.tsx` — premium card composition and course-specific accent. +- `components/course/CourseCard.test.tsx` — visual variant, progress semantics, recommendation, and navigation. +- `views/CourseHubView.tsx` — quiet course-specific cosmic header and card hierarchy. +- `views/LessonWorkspaceView.tsx` — reading-focused glass stages and restrained margin atmosphere. +- `views/MathLabView.tsx` — instrument-panel shell without decorative hero imagery. +- `views/PracticeView.tsx` — calm assessment header and panels. +- `views/ExamsView.tsx` — calm assessment header and panels. +- `views/ProgressView.tsx` — shared progress rings/bars and course-separated summary. +- `views/FormulaWorkspaceView.tsx` — technical-notebook surface and faint notation texture. +- `views/AIChatView.tsx` — deep-space console styling while preserving chat readability. +- Existing tests for the views above — preserve behavior and add one visual-system assertion per view where useful. + +--- + +### Task 1: Add the Hero Asset Contract and Optimized Artwork + +**Files:** +- Create: `scripts/cosmic-assets.test.ts` +- Create: `public/assets/cosmic/black-hole-hero.webp` + +**Interfaces:** +- Consumes: no application code. +- Produces: stable browser path `/assets/cosmic/black-hole-hero.webp` with a maximum size of `900_000` bytes. + +- [ ] **Step 1: Write the failing asset test** + +```ts +import { describe, expect, it } from 'vitest'; +import { existsSync, statSync } from 'node:fs'; +import { resolve } from 'node:path'; + +describe('cosmic visual assets', () => { + it('ships an optimized dashboard black-hole hero', () => { + const assetPath = resolve(process.cwd(), 'public/assets/cosmic/black-hole-hero.webp'); + expect(existsSync(assetPath)).toBe(true); + expect(statSync(assetPath).size).toBeLessThanOrEqual(900_000); + }); +}); +``` + +- [ ] **Step 2: Run the test and verify RED** + +Run: + +```bash +npm test -- scripts/cosmic-assets.test.ts +``` + +Expected: FAIL because `public/assets/cosmic/black-hole-hero.webp` does not exist. + +- [ ] **Step 3: Generate the standalone artwork** + +Use image generation with this exact content direction: + +```text +Wide photorealistic 3D black hole in deep space for a premium academic mathematics web-app hero. Event horizon and realistic gravitational lensing in the upper-right, warm white and restrained pale-gold accretion disk, sparse starfield, deep black and navy space, darker negative space across the entire left half for white interface text, no text, no logo, no watermark, no UI, no person, cinematic but scientifically respectful, 16:7 composition. +``` + +Do not use the full generated dashboard mockup as the asset. + +- [ ] **Step 4: Convert and optimize** + +Use Pillow or an equivalent local encoder: + +```python +from pathlib import Path +from PIL import Image + +source = Path('/mnt/data/generated-black-hole.png') +target = Path('public/assets/cosmic/black-hole-hero.webp') +target.parent.mkdir(parents=True, exist_ok=True) + +with Image.open(source) as image: + image = image.convert('RGB') + image.thumbnail((1920, 900), Image.Resampling.LANCZOS) + image.save(target, 'WEBP', quality=82, method=6) +``` + +- [ ] **Step 5: Run the asset test and full verification** + +```bash +npm test -- scripts/cosmic-assets.test.ts +npm run verify +``` + +Expected: PASS; the asset exists and stays below 900 KB. + +- [ ] **Step 6: Commit** + +```bash +git add scripts/cosmic-assets.test.ts public/assets/cosmic/black-hole-hero.webp +git commit -m "feat: add optimized cosmic hero asset" +``` + +--- + +### Task 2: Establish the Cosmic Visual Tokens and Global Background + +**Files:** +- Modify: `index.css` +- Modify: `components/AnimatedBackground.tsx` +- Create: `components/AnimatedBackground.test.tsx` + +**Interfaces:** +- Consumes: existing Tailwind 4 import and `prefers-reduced-motion` rules. +- Produces: reusable classes `cosmic-shell`, `cosmic-glass`, `cosmic-card`, `cosmic-divider`, `cosmic-button`, `cosmic-glow-blue`, and `cosmic-glow-violet`. + +- [ ] **Step 1: Write the failing background test** + +```tsx +import { render, screen } from '@testing-library/react'; +import { describe, expect, it } from 'vitest'; +import { AnimatedBackground } from './AnimatedBackground'; + +describe('AnimatedBackground', () => { + it('renders decorative restrained cosmic layers', () => { + render(); + const background = screen.getByTestId('cosmic-background'); + expect(background).toHaveAttribute('aria-hidden', 'true'); + expect(background).toHaveClass('cosmic-shell'); + expect(background.querySelectorAll('[data-cosmic-layer]')).toHaveLength(3); + }); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +npm test -- components/AnimatedBackground.test.tsx +``` + +Expected: FAIL because the test id, shell class, and layer markers do not exist. + +- [ ] **Step 3: Add exact CSS tokens and reusable surfaces** + +Add these tokens at `:root` and retain the existing Tailwind 4 import: + +```css +:root { + color-scheme: dark; + --cosmic-void: #030711; + --cosmic-navy: #07111f; + --cosmic-surface: #0b1726; + --cosmic-raised: #101d30; + --cosmic-text: #f5f7fb; + --cosmic-muted: #9aa9bd; + --cosmic-blue: #62a8ff; + --cosmic-cyan: #67e8f9; + --cosmic-violet: #a78bfa; + --cosmic-indigo: #7c83ff; + --cosmic-gold: #f4d7aa; + --cosmic-border: rgba(165, 190, 225, 0.16); +} + +.cosmic-shell { background: var(--cosmic-void); } +.cosmic-glass { + border: 1px solid var(--cosmic-border); + background: linear-gradient(145deg, rgba(12, 25, 43, 0.86), rgba(5, 12, 24, 0.78)); + box-shadow: 0 24px 80px rgba(0, 0, 0, 0.32); + backdrop-filter: blur(18px); +} +.cosmic-card { transition: transform 180ms ease, border-color 180ms ease, box-shadow 180ms ease; } +.cosmic-card:hover { transform: translateY(-2px); } +.cosmic-divider { height: 1px; background: linear-gradient(90deg, transparent, rgba(98,168,255,.8), transparent); } +.cosmic-button { border: 1px solid rgba(255,255,255,.16); box-shadow: inset 0 1px rgba(255,255,255,.12), 0 8px 24px rgba(0,0,0,.22); } +.cosmic-glow-blue { box-shadow: 0 0 42px rgba(56, 139, 253, 0.12); } +.cosmic-glow-violet { box-shadow: 0 0 42px rgba(139, 92, 246, 0.12); } +``` + +Add restrained starfield pseudo-elements and ensure the reduced-motion media query disables drift. + +- [ ] **Step 4: Implement the three global decorative layers** + +```tsx +export const AnimatedBackground: React.FC = () => ( +