chore: establish StudyFlow project structure

Organize the standalone frontend for synchronized GitHub and Hugging Face Spaces publication, preserving the selected design reference and QA history.

Co-authored-by: Codex <codex@openai.com>

.gitattributes

@@ -0,0 +1,9 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.png !text !filter !merge !diff
+assets/hero/josephine-mainz-morning.png filter=lfs diff=lfs merge=lfs -text
+assets/materials/mq3zhq9n-clipboard.png filter=lfs diff=lfs merge=lfs -text
+assets/materials/mq3zhqat-clipboard.png filter=lfs diff=lfs merge=lfs -text
+assets/materials/mq3zhqbu-clipboard.png filter=lfs diff=lfs merge=lfs -text
+docs/design/reference/josephines-tagebuch.png filter=lfs diff=lfs merge=lfs -text
+docs/design/screenshots/josephine-design-comparison.png filter=lfs diff=lfs merge=lfs -text
+docs/design/screenshots/josephine-home-desktop.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,25 @@
+.env
+.env.*
+!.env.example
+
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+
+.uv-cache/
+.uv-python/
+.uv-tools/
+
+node_modules/
+dist/
+coverage/
+
+.DS_Store
+Thumbs.db
+*.log
+
+# Local design exploration archive and duplicated source renders.
+docs/design/local-archive/
+docs/design/open-design/references/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Soni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,78 @@
+---
+title: StudyFlow AI
+emoji: 📚
+colorFrom: green
+colorTo: purple
+sdk: static
+app_file: index.html
+pinned: false
+license: mit
+short_description: A private, personalized AI study copilot.
+---
+
+# StudyFlow AI
+
+StudyFlow AI is a private study copilot built around the materials students
+already use: handwritten notes, lecture slides, PDFs, calendars, flashcards,
+and reminders.
+
+The current release is an interactive frontend prototype centered on
+Josephine Wendland, a multilingual teaching student from Mainz. Backend,
+OCR, local model, and retrieval integrations will be added next.
+
+## Current Experience
+
+- Personal daily briefing and schedule
+- Material upload and OCR review interface
+- Connected slide, note, and AI study canvas
+- Calendar and personalized learning plan
+- Knowledge-gap review
+- Flashcard editing and export flows
+- Quiz simulation and reminders
+- Local-first privacy messaging
+
+## Run Locally
+
+No build step is required.
+
+```powershell
+node server.js
+```
+
+Then open [http://localhost:4173](http://localhost:4173).
+
+Python can also serve the static prototype:
+
+```powershell
+python -m http.server 4173
+```
+
+## Repository Layout
+
+```text
+assets/
+  hero/          Generated Josephine illustration
+  materials/     Sample note, slide, and calendar imagery
+docs/design/     Reference concepts, QA, reviews, and design history
+tools/           Local design and review utilities
+app.js           Application views and interactions
+index.html       Static Space entry point
+styles.css       Responsive visual system
+server.js        Tiny local development server
+```
+
+## Publication
+
+The same Git history is pushed to:
+
+- GitHub: source repository and development history
+- Hugging Face Spaces: live static prototype
+
+Commits created with Codex include an explicit Codex co-author trailer.
+
+## Next Phase
+
+The frontend will later be migrated to a Gradio/FastAPI-backed application
+with OCR, document linking, local retrieval, study-plan generation, and
+notification workflows.
+

docs/design/finalized.json

@@ -0,0 +1,12 @@
+{
+  "source_mockup": null,
+  "source_plan": "Pasted PRD attachment and current mockup iterations",
+  "mode": "evolve",
+  "html_file": "C:\\Users\\Lenovo\\Documents\\build-small-hackathon\\projects\\studyflow-ai\\index.html",
+  "pretext_tier": "card-grid-dashboard",
+  "framework": "vanilla",
+  "iterations": 1,
+  "date": "2026-06-06T00:00:00+02:00",
+  "screen": "studyflow-lehramt-arbeitszentrale",
+  "branch": "main"
+}

docs/design/legacy/script.js

@@ -0,0 +1,119 @@
+const toast = document.querySelector("#toast");
+const statusStrip = document.querySelector("#statusStrip");
+const flowCopy = document.querySelectorAll("[data-flow-copy]");
+
+function syncFlowCopyState() {
+  flowCopy.forEach((element) => {
+    element.classList.toggle(
+      "is-overflowing",
+      element.scrollWidth > element.clientWidth + 1
+    );
+  });
+}
+
+if (flowCopy.length) {
+  const resizeObserver = new ResizeObserver(syncFlowCopyState);
+  resizeObserver.observe(document.querySelector(".workspace"));
+  flowCopy.forEach((element) => {
+    new MutationObserver(syncFlowCopyState).observe(element, {
+      characterData: true,
+      childList: true,
+      subtree: true,
+    });
+  });
+  document.fonts?.ready.then(syncFlowCopyState);
+  syncFlowCopyState();
+}
+
+function showToast(message) {
+  toast.textContent = message;
+  toast.classList.add("show");
+  window.clearTimeout(showToast.timer);
+  showToast.timer = window.setTimeout(() => toast.classList.remove("show"), 2800);
+}
+
+document.querySelectorAll(".nav-item").forEach((item) => {
+  item.addEventListener("click", () => {
+    document.querySelectorAll(".nav-item").forEach((nav) => nav.classList.remove("active"));
+    item.classList.add("active");
+    const label = item.textContent.replace(/\s+/g, " ").trim();
+    showToast(`${label} geöffnet. Für den Demo-Mockup bleibt die Übersicht im Fokus.`);
+  });
+});
+
+document.querySelectorAll(".language-toggle button").forEach((button) => {
+  button.addEventListener("click", () => {
+    document.querySelectorAll(".language-toggle button").forEach((btn) => btn.classList.remove("selected"));
+    button.classList.add("selected");
+    const language = button.textContent.trim();
+    if (language === "DE") {
+      showToast("Deutsch bleibt die Hauptsprache der App.");
+    } else {
+      showToast(`${language} wird als Materialsprache erkannt. Die Oberfläche bleibt deutsch.`);
+    }
+  });
+});
+
+document.querySelectorAll(".action-row").forEach((button) => {
+  button.addEventListener("click", () => {
+    showToast(button.dataset.message);
+  });
+});
+
+document.querySelectorAll(".confirm-button").forEach((button) => {
+  button.addEventListener("click", () => {
+    const row = button.closest("tr");
+    row.classList.remove("pending-row");
+    row.querySelector("td:nth-child(7)").innerHTML = '<span class="chip green">Bestätigt</span>';
+    row.querySelector("td:nth-child(8)").innerHTML = '<button class="icon-button" type="button" aria-label="Termin bestätigt"><span class="material-symbols-rounded">check</span></button>';
+    showToast("Termin bestätigt und in Mayas Lernplan übernommen.");
+  });
+});
+
+document.querySelector("#linkCheckBtn").addEventListener("click", () => {
+  showToast("Verknüpfungen geprüft: Folien 10-15 passen zu Notizen 4-6.");
+});
+
+document.querySelector("#addEventBtn").addEventListener("click", () => {
+  const tbody = document.querySelector("#eventRows");
+  const row = document.createElement("tr");
+  row.innerHTML = `
+    <td>Fr, 30. Mai</td>
+    <td>11:30</td>
+    <td>Unterrichtsentwurf Abgabe</td>
+    <td><span class="chip red">Abgabe</span></td>
+    <td>Notizen_Seminar.pdf</td>
+    <td>84%</td>
+    <td><span class="chip amber">Ausstehend</span></td>
+    <td><button class="confirm-button" type="button" aria-label="Termin bestätigen">OK</button></td>
+  `;
+  row.querySelector(".confirm-button").addEventListener("click", () => {
+    row.querySelector("td:nth-child(7)").innerHTML = '<span class="chip green">Bestätigt</span>';
+    row.querySelector("td:nth-child(8)").innerHTML = '<button class="icon-button" type="button" aria-label="Termin bestätigt"><span class="material-symbols-rounded">check</span></button>';
+    showToast("Neuer Termin bestätigt.");
+  });
+  tbody.appendChild(row);
+  showToast("Neuer erkannter Termin wurde ergänzt.");
+});
+
+document.querySelector("#processBtn").addEventListener("click", () => {
+  const button = document.querySelector("#processBtn");
+  button.disabled = true;
+  button.innerHTML = '<span class="material-symbols-rounded">progress_activity</span> Prüfe...';
+  window.setTimeout(() => {
+    statusStrip.classList.remove("show");
+    button.disabled = false;
+    button.innerHTML = '<span class="material-symbols-rounded">task_alt</span> Jetzt prüfen';
+    showToast("Uploads geprüft: 2 Termine, 1 neue Wissenslücke und 12 Karteikarten gefunden.");
+  }, 650);
+});
+
+document.querySelectorAll(".focus-list input").forEach((checkbox) => {
+  checkbox.addEventListener("change", () => {
+    showToast(checkbox.checked ? "Lernblock als erledigt markiert." : "Lernblock wieder geöffnet.");
+  });
+});
+
+document.querySelector('[data-view="uploads"]').addEventListener("click", () => {
+  statusStrip.classList.add("show");
+});

docs/design/open-design/asset-inventory.md

@@ -0,0 +1,37 @@
+# StudyFlow AI Visual Asset Inventory
+
+The six reference screens are the canonical visual targets. Only source-material
+imagery should remain bitmap content; all interface elements must be rebuilt in
+HTML and CSS.
+
+## Extracted bitmap assets
+
+| Asset | Source | Used for |
+| --- | --- | --- |
+| `handwritten-calendar.png` | `02-uploads-ocr.png` | OCR review document canvas |
+| `lecture-slide-scaffolding.png` | `03-study-canvas.png` | Main linked lecture slide |
+| `handwritten-scaffolding-notes.png` | `03-study-canvas.png` | Main linked handwritten notes |
+| `flashcard-source-slide.png` | `05-flashcards.png` | Flashcard source evidence |
+| `flashcard-source-notes.png` | `05-flashcards.png` | Flashcard handwritten evidence |
+| `note-code-switching.png` | `01-overview.png` | Recent-note thumbnail |
+| `note-motivation.png` | `01-overview.png` | Recent-note thumbnail |
+| `note-past-progressive.png` | `01-overview.png` | Recent-note thumbnail |
+| `note-authentic-texts.png` | `01-overview.png` | Recent-note thumbnail |
+
+## Rebuild in code
+
+- StudyFlow logo and all sidebar/navigation icons
+- Maya avatar treatment
+- Buttons, inputs, tabs, badges, menus, checkboxes, and toolbars
+- Calendar grid and event blocks
+- Roadmap timeline and progress indicators
+- Charts, confidence bars, storage bars, and status dots
+- PDF/PPTX/JPG file badges and document containers
+- OCR bounding boxes and extraction overlays
+- Quiz answers, navigator, timer, feedback, and source cards
+- All typography, borders, shadows, spacing, and responsive layout
+
+## Replication constraint
+
+Use only the six canonical references and the extracted assets above. Do not add
+stock photography, illustrations, decorative gradients, or generated imagery.

docs/design/open-design/compare_josephine.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+
+root = Path(__file__).resolve().parents[1]
+reference = Image.open(
+    root / "docs" / "design" / "reference" / "josephines-tagebuch.png"
+).convert("RGB")
+prototype = Image.open(
+    root / "docs" / "design" / "screenshots" / "josephine-home-desktop.png"
+).convert("RGB")
+
+height = 1024
+reference.thumbnail((720, height))
+prototype.thumbnail((720, height))
+
+canvas = Image.new("RGB", (1440, height + 42), "#f4f1eb")
+canvas.paste(reference, (0, 42))
+canvas.paste(prototype, (720, 42))
+
+draw = ImageDraw.Draw(canvas)
+draw.text((18, 13), "REFERENCE", fill="#4b2140")
+draw.text((738, 13), "IMPLEMENTATION", fill="#0f5848")
+
+canvas.save(
+    root / "docs" / "design" / "screenshots" / "josephine-design-comparison.png",
+    optimize=True,
+)

docs/design/open-design/extract_assets.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from PIL import Image
+
+
+ROOT = Path(__file__).resolve().parent
+REFS = ROOT / "references"
+OUT = ROOT / "assets"
+OUT.mkdir(exist_ok=True)
+
+
+def crop(source: str, output: str, box: tuple[int, int, int, int]) -> None:
+    with Image.open(REFS / source) as image:
+        image.crop(box).save(OUT / output, optimize=True)
+
+
+crop("02-uploads-ocr.png", "handwritten-calendar.png", (652, 220, 1136, 742))
+crop("03-study-canvas.png", "lecture-slide-scaffolding.png", (355, 228, 653, 810))
+crop("03-study-canvas.png", "handwritten-scaffolding-notes.png", (677, 242, 1103, 811))
+crop("05-flashcards.png", "flashcard-source-slide.png", (1135, 216, 1299, 338))
+crop("05-flashcards.png", "flashcard-source-notes.png", (1135, 443, 1304, 566))
+
+crop("01-overview.png", "note-code-switching.png", (263, 883, 347, 974))
+crop("01-overview.png", "note-motivation.png", (512, 883, 600, 974))
+crop("01-overview.png", "note-past-progressive.png", (758, 883, 846, 974))
+crop("01-overview.png", "note-authentic-texts.png", (1042, 883, 1130, 974))

docs/design/reviews/design-html-review.md

@@ -0,0 +1,28 @@
+# Design HTML Finalization
+
+Date: 2026-06-06
+Mode: evolve existing standalone mockup
+Screen: StudyFlow AI Lehramt Arbeitszentrale
+Framework: vanilla HTML, CSS, JavaScript
+
+## Implementation Spec
+
+- Layout: responsive dashboard with fixed desktop sidebar, collapsed icon rail at tablet width, stacked mobile workspace.
+- Typography: Fraunces display headings, IBM Plex Sans interface text, Material Symbols Rounded icons.
+- Palette: warm paper background, green primary action/state, blue informational accents, amber/red priority states, dark-mode token overrides.
+- Components: navigation rail, local-processing trust panel, upload status strip, material-linking workspace, AI action list, extraction review table, daily focus, knowledge gaps, roadmap, subject progress.
+
+## Design HTML Pass
+
+- Added explicit theme metadata and dark-mode CSS token overrides.
+- Added named breakpoint refinements for 1440px, 1024px, 768px, and 375px.
+- Made the primary headline and subheading editable for demo iteration.
+- Added a small ResizeObserver and MutationObserver pass for editable copy overflow.
+- Kept the existing live app as the source of truth instead of generating a separate detached artifact.
+
+## Verification
+
+- UI checker: passed via `uv run python ui_ux_check.py`.
+- Desktop screenshot: `studyflow-design-html-desktop.png`
+- Mobile screenshot: `studyflow-design-html-mobile.png`
+- Narrow screenshot: `studyflow-design-html-375.png`

docs/design/reviews/design-qa.md

@@ -0,0 +1,37 @@
+# Product Design QA: Josephines Tagebuch
+
+Reference: `open-design/josephine-concepts/02-josephines-tagebuch.png`
+
+Implementation: `josephine-home-desktop.png`
+
+Comparison: `josephine-design-comparison.png`
+
+## Visual Match
+
+- Desktop shell, navigation width, hero proportion, editorial typography, and
+  two-column daily agenda closely match the selected 1440 x 1024 reference.
+- Josephine's generated Mainz morning scene preserves the intended story:
+  family, friends, horse, bread, cheese, aubergine accents, and teacher studies.
+- The hierarchy stays personal and spacious. Josephine's name is the dominant
+  first-viewport signal and the agenda reads as one continuous surface.
+- Colors, fine rules, restrained radii, and icon treatment are consistent with
+  the reference.
+- The mobile layout was separately checked and reflows the hero copy below the
+  illustration without overlap.
+
+## Functional Check
+
+- All nine navigation destinations load successfully.
+- Timeline and "Heute wichtig" rows navigate to their related tools.
+- Materials retains upload and OCR functionality.
+- Existing canvas, calendar, cards, and quiz interactions remain available.
+- Browser console: no warnings or errors.
+
+## Remaining P3 Polish
+
+- The generated hero is a fresh image in the selected art direction rather
+  than a pixel-identical crop of the concept image.
+- The small decorative horse sketch from the concept is intentionally omitted;
+  the horse is already represented prominently in the hero.
+
+final result: passed

docs/design/reviews/design-review.md

@@ -0,0 +1,73 @@
+# StudyFlow AI Design Review
+
+Review lenses: ui-ux-pro-max and gstack design-review.
+URL: http://localhost:4173
+Screenshots:
+- Desktop: studyflow-review-desktop.png
+- Mobile: studyflow-review-mobile.png
+
+## Result
+
+Design Score: B+ -> A-
+AI Slop Score: B -> A-
+Goodwill: 78/100 -> 86/100
+
+The dashboard now reads as a credible app UI rather than a generic generated dashboard. The strongest parts are the German-first Lehramt framing, clear privacy promise, tight study workflow, and visible links between documents, deadlines, gaps, and actions.
+
+## Fixes Applied
+
+0. Added a `uv`-run UI/UX checker.
+   - Why: gives the mockup a repeatable quality gate for accessibility, interaction, motion, mobile behavior, and token hygiene.
+
+1. Replaced the CSS-drawn brand mark with an icon-library mark.
+   - Why: avoids fake visual assets and improves consistency with the icon system.
+
+2. Tightened navigation labels and mobile navigation behavior.
+   - Why: German labels were wrapping/clipping awkwardly, especially on mobile.
+
+3. Improved accessibility and interaction states.
+   - Added visible focus styles, `aria-label`s for icon-only table actions, visited-link styling, and reduced-motion handling.
+
+4. Increased critical touch targets.
+   - Language buttons, profile, table action buttons, and primary action rows now have more reliable hit areas.
+
+5. Added mobile-specific table behavior.
+   - The linked-materials area now becomes compact row cards on small screens instead of forcing a desktop spreadsheet layout.
+
+6. Added a skip link and better action feedback.
+   - The upload review CTA now has a short loading state, and keyboard users can jump straight to the main dashboard.
+
+7. Reduced ad-hoc color usage.
+   - Repeated colors now route through semantic CSS tokens; the final `uv` checker reports only 26 raw hex values outside `:root`.
+
+## Remaining Tradeoffs
+
+- The desktop dashboard intentionally stays dense because it is meant to impress in a hackathon demo.
+- Mobile is now readable, but it is still a secondary presentation mode. A production app would likely need a dedicated mobile information architecture.
+- The mockup still uses realistic sample data rather than real uploaded notes/slides.
+
+## uv Check
+
+Command:
+
+```powershell
+$env:UV_CACHE_DIR='C:\Users\Lenovo\Documents\build-small-hackathon\.uv-cache'; $env:UV_PYTHON_INSTALL_DIR='C:\Users\Lenovo\Documents\build-small-hackathon\.uv-python'; uv run python ui_ux_check.py
+```
+
+Result: all checks passed.
+
+## Emil Design Engineering Pass
+
+Ran the Emil-style animation and interaction review after the UI/UX pass. See `emil-design-review.md` for the before/after table. The main changes were custom easing tokens, scale-based press feedback, pointer-gated hover states, and cleaner toast/status transitions.
+
+## Browser Annotation Fix
+
+Fixed the `Lernroadmap` section after review in the browser. The prior timeline placed detail text into the wrong implicit grid cells, which made short phrases wrap vertically and feel broken. The updated roadmap wraps each entry into a structured row with a timeline marker, date label, main task, and supporting detail, plus clearer active and exam states.
+
+## Frontend Design Pass
+
+Ran the `frontend-design` skill as a final aesthetic pass. See `frontend-design-review.md`. The main update was moving from generic dashboard polish toward a refined academic study-ledger identity with more distinctive typography, subtle paper-grid atmosphere, and clearer first-screen narrative labels.
+
+## Final Notes
+
+Quickest next polish would be adding one real-looking handwritten note thumbnail and one real-looking lecture slide thumbnail. That would make the demo feel less synthetic without adding much complexity.

docs/design/reviews/emil-design-review.md

@@ -0,0 +1,20 @@
+# Emil Design Engineering Review
+
+Skill lens: Emil Kowalski-style design engineering polish.
+URL: http://localhost:4173
+
+| Before | After | Why |
+| --- | --- | --- |
+| Press feedback used `translateY(1px)` | Press feedback uses `transform: scale(0.97)` | Scaling the whole control gives a more tactile "the UI heard me" response without nudging layout rhythm. |
+| Transitions used built-in `ease` / `.2s` shorthand | Transitions use explicit properties with `--ease-out: cubic-bezier(0.23, 1, 0.32, 1)` | Custom ease-out starts fast and feels more responsive for dashboard UI. |
+| Hover states applied globally | Hover states are gated behind `@media (hover: hover) and (pointer: fine)` | Touch devices should not get sticky hover behavior after tapping. |
+| Toast entered from a hardcoded `translateY(22px)` | Toast enters from `translateY(100%)` with transform/opacity only | Percentage translation adapts to the toast's own height and stays GPU-friendly. |
+| Status strip transition used generic `ease` | Status strip uses exact max-height, padding, and opacity timings | The reveal feels intentional without animating expensive layout properties broadly. |
+| Reduced-motion disabled all motion but left press transforms available | Reduced-motion now removes active transforms too | Users requesting reduced motion should not get unnecessary movement feedback. |
+
+## Verification
+
+- `uv run python ui_ux_check.py`: passed.
+- Desktop screenshot: `studyflow-emil-desktop.png`.
+- Mobile screenshot: `studyflow-emil-mobile.png`.
+- Local server health: `http://localhost:4173` returned `200`.

docs/design/reviews/frontend-design-review.md

@@ -0,0 +1,24 @@
+# Frontend Design Pass
+
+Skill lens: `frontend-design`.
+URL: http://localhost:4173
+
+## Direction
+
+Refined academic study ledger: a private, German-first learning workspace with a quiet paper-grid atmosphere, editorial title typography, and a stronger sense that StudyFlow connects real study artifacts rather than simply listing dashboard cards.
+
+## Changes
+
+- Replaced the generic Inter-only type system with `Fraunces` for display type and `IBM Plex Sans` for interface text.
+- Added a subtle paper-grid workspace texture so the app feels closer to study material and notebooks.
+- Gave the primary material-linking panel a stronger visual identity with a soft gradient surface and accent spine.
+- Added section kickers such as `01 / Materialabgleich` and `02 / Nächster Schritt` to make the first-screen story clearer.
+- Lifted document tables into contained study-document surfaces so the linked slide/note area feels more intentional.
+- Preserved the existing accessibility and interaction polish from the UI/UX and Emil passes.
+
+## Verification
+
+- `uv run python ui_ux_check.py`: passed.
+- Desktop screenshot: `studyflow-frontend-design-desktop.png`.
+- Mobile screenshot: `studyflow-frontend-design-mobile.png`.
+- Local server health: `http://localhost:4173` returned `200`.

server.js

@@ -0,0 +1,42 @@
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+
+const root = __dirname;
+const port = process.env.PORT || 4173;
+
+const types = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".svg": "image/svg+xml",
+};
+
+const server = http.createServer((req, res) => {
+  const urlPath = decodeURIComponent(req.url.split("?")[0]);
+  const filePath = path.join(root, urlPath === "/" ? "index.html" : urlPath);
+
+  if (!filePath.startsWith(root)) {
+    res.writeHead(403);
+    res.end("Forbidden");
+    return;
+  }
+
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(404);
+      res.end("Not found");
+      return;
+    }
+
+    res.writeHead(200, { "Content-Type": types[path.extname(filePath)] || "application/octet-stream" });
+    res.end(data);
+  });
+});
+
+server.listen(port, () => {
+  console.log(`StudyFlow mockup running at http://localhost:${port}`);
+});

tools/open-design-proxy.js

@@ -0,0 +1,29 @@
+const http = require("node:http");
+
+const targetPort = Number(process.env.OD_TARGET_PORT || 49540);
+const listenPort = Number(process.env.OD_PROXY_PORT || 7456);
+
+const server = http.createServer((request, response) => {
+  const proxy = http.request(
+    {
+      hostname: "127.0.0.1",
+      port: targetPort,
+      path: request.url,
+      method: request.method,
+      headers: request.headers,
+    },
+    (upstream) => {
+      response.writeHead(upstream.statusCode || 502, upstream.headers);
+      upstream.pipe(response);
+    }
+  );
+
+  proxy.on("error", (error) => {
+    response.writeHead(502, { "content-type": "application/json" });
+    response.end(JSON.stringify({ error: error.message }));
+  });
+
+  request.pipe(proxy);
+});
+
+server.listen(listenPort, "127.0.0.1");

tools/ui_ux_check.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+import re
+
+root = Path(__file__).parent
+html = (root / "index.html").read_text(encoding="utf-8")
+css = (root / "styles.css").read_text(encoding="utf-8")
+
+checks = []
+
+def add(name, passed, detail):
+    checks.append((name, passed, detail))
+
+add("viewport", 'name="viewport"' in html and "initial-scale=1" in html, "viewport meta should allow responsive scaling")
+add("skip_link", "skip-link" in html, "keyboard users should be able to skip navigation")
+add("focus_visible", ":focus-visible" in css, "visible focus rings should be present")
+add("reduced_motion", "prefers-reduced-motion" in css, "motion should respect reduced motion")
+add("visited_links", "a:visited" in css, "visited links should remain distinguishable")
+add("no_horizontal_body", "overflow-x: hidden" in css, "body should avoid horizontal drift")
+add("touch_action", "touch-action: manipulation" in css, "tap delay should be minimized")
+add("aria_labels", html.count("aria-label") >= 6, "icon-only/profile controls need labels")
+add("mobile_breakpoint", "@media (max-width: 820px)" in css, "small-screen layout rules should exist")
+add("button_feedback", ":active" in css, "tap/press states should feel responsive")
+
+small_fonts = [float(x) for x in re.findall(r"font-size:\s*([0-9.]+)px", css) if float(x) < 11]
+add("tiny_text", not small_fonts, f"avoid unreadable text smaller than 11px; found {small_fonts}")
+
+css_without_root = re.sub(r":root\s*\{.*?\}\s*", "", css, flags=re.S)
+raw_hex_count = len(re.findall(r"#[0-9a-fA-F]{3,8}", css_without_root))
+add("semantic_color_bias", raw_hex_count <= 35, f"prefer semantic CSS tokens outside :root; raw hex count is {raw_hex_count}")
+
+failed = [item for item in checks if not item[1]]
+for name, passed, detail in checks:
+    print(f"{'PASS' if passed else 'FAIL'} {name}: {detail}")
+
+raise SystemExit(1 if failed else 0)