From f9a7f874fe1d695ffc06d7a98c00677171da4d25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=87a=C4=9Fatay=20Onur=20=C5=9Eeng=C3=B6r?= Date: Mon, 23 Mar 2026 00:18:21 +0300 Subject: [PATCH 01/18] Add UI overhaul design document Co-Authored-By: Claude Opus 4.6 --- .design/ui-overhaul.md | 497 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 497 insertions(+) create mode 100644 .design/ui-overhaul.md diff --git a/.design/ui-overhaul.md b/.design/ui-overhaul.md new file mode 100644 index 0000000..d029679 --- /dev/null +++ b/.design/ui-overhaul.md @@ -0,0 +1,497 @@ +# Kaplan Cloud — UI Overhaul Design Document + +**Status:** Draft · Session 1 of ~6 +**Last updated:** 2026-03-22 +**Branch:** `claude/ui-overhaul-planning-ZlwnV` + +--- + +## Table of Contents + +1. [Background & Goals](#1-background--goals) +2. [Current State Audit](#2-current-state-audit) +3. [Competitive Analysis](#3-competitive-analysis) +4. [Design Direction](#4-design-direction) +5. [Design Tokens](#5-design-tokens) +6. [Component Inventory](#6-component-inventory) +7. [Recommended Tech Stack](#7-recommended-tech-stack) +8. [Accessibility Goals](#8-accessibility-goals) +9. [Session Roadmap](#9-session-roadmap) + +--- + +## 1. Background & Goals + +Kaplan Cloud is a functional Django-based translation management system. The UI was built with a "wireframe-first" approach: raw Django `form.as_table`, hand-rolled vanilla CSS Grid, no component system, and no coherent design language. It works, but feels unfinished. + +### Goals + +- Establish a consistent, polished visual identity across all screens +- Adopt a component system that reduces per-screen CSS authorship +- Support both **light and dark themes** with a user-controlled toggle +- Remain **tablet-friendly** (desktop-primary, usable on tablets ≥768px) +- Preserve all existing editor functionality (keyboard shortcuts, TM integration, contenteditable logic) +- Produce a design document before touching code, so future sessions are well-scoped + +### Non-goals (this overhaul) + +- Full mobile (phone) support +- Real-time collaboration features +- Redesigning data models or backend logic +- Replacing the editor's JavaScript behavior (only reskin it) + +--- + +## 2. Current State Audit + +### Template inventory + +| Template | Extends | Purpose | +|---|---|---| +| `base.html` | — | Root: DOCTYPE, CDN links, `{% block head %}`, `{% block body %}` | +| `index.html` | `base.html` | Dashboard shell: sidebar nav + main content area | +| `projects.html` | `index.html` | Projects list with searchable/filterable table | +| `project.html` | `index.html` | Project detail: file table, reference files, reports | +| `newproject.html` | `index.html` | Project creation form | +| `translation-memories.html` | `index.html` | TM list table | +| `tm.html` | `index.html` | TM detail: source/target entry table | +| `newtm.html` | `index.html` | TM creation form | +| `tm-import.html` | `index.html` | TM import form | +| `accounts/login.html` | `base.html` | Login form | +| `accounts/register.html` | `base.html` | Registration form | +| `accounts/change-password.html` | `base.html` | Password change form | +| `editor.html` | *(standalone)* | Full-page translation editor | +| `report.html` | *(standalone)* | Translation analysis report | + +`editor.html` and `report.html` do **not** extend `base.html` — they are self-contained pages with their own CSS links. + +### Static file inventory + +| File | Lines | Purpose | +|---|---|---| +| `main.css` | 236 | Global layout (CSS Grid shell, nav, buttons, modals, toasts, tables) | +| `editor.css` | 151 | Editor-specific styles (3-col grid, segment rows, sidebars, filter dropdown) | +| `main.js` | 5 | Search form toggle on Projects/TMs pages | +| `editor.js` | 681 | Full editor logic: contenteditable, TM/comment lookups, propagation, keyboard shortcuts, submission workflow | +| `project.js` | 242 | Project page: checkbox selection, context menus, file operations, linguist assignment | +| `newproject.js` | 33 | Dynamic TM dropdown population via Fetch | + +### Third-party dependencies (current) + +| Library | Delivery | Used for | +|---|---|---| +| Google Material Icons | CDN | Nav icons, button icons, editor controls | +| Ubuntu (Google Fonts) | CDN | Global typeface | + +No npm, no build step, no JS framework. + +### UI component patterns (current) + +- **Layout:** CSS Grid for sidebar + content shell; 3-column grid in editor +- **Navigation:** Vertical sidebar with `