diff --git a/design/figma/figma-component-map.json b/design/figma/figma-component-map.json new file mode 100644 index 0000000..c956ad2 --- /dev/null +++ b/design/figma/figma-component-map.json @@ -0,0 +1,56 @@ +{ + "components": [ + { + "name": "AppShell", + "variants": ["Student", "Teacher", "Studio", "Organization", "Admin", "Lesson"], + "sourceSpec": "docs/ux-overhaul/component-specifications.md#application-shell" + }, + { + "name": "Navigation/Sidebar", + "variants": ["Expanded", "Collapsed", "MobileDrawer"], + "states": ["Default", "Active", "Focus", "Disabled", "Loading"] + }, + { + "name": "Navigation/MobileBottomNav", + "variants": ["Student", "TeacherCompact"], + "states": ["Default", "Active", "Focus"] + }, + { + "name": "Button", + "variants": ["Primary", "Secondary", "Tertiary", "Danger", "Ghost", "Link", "Icon"], + "sizes": ["Small", "Medium", "Large"], + "states": ["Default", "Hover", "Active", "Focus", "Disabled", "Loading"] + }, + { + "name": "Form/Input", + "variants": ["Text", "Password", "Search", "Email"], + "states": ["Default", "Focus", "Error", "Success", "Disabled"] + }, + { + "name": "Card/Course", + "variants": ["Assigned", "Available", "Completed", "StaffPreview"], + "states": ["Default", "Hover", "Focus", "Selected", "Unavailable"] + }, + { + "name": "Card/Assignment", + "variants": ["NotStarted", "InProgress", "Submitted", "Returned", "Overdue"] + }, + { + "name": "LessonPlayer", + "variants": ["Student", "TeacherPreview", "Blocked", "Completed", "Loading"] + }, + { + "name": "DataList", + "variants": ["Roster", "Users", "Assignments", "ReviewQueue"], + "breakpoints": ["DesktopTable", "MobileCards"] + }, + { + "name": "StatePanel", + "variants": ["Empty", "Loading", "Error", "PermissionDenied", "Success"] + }, + { + "name": "ConfirmationDialog", + "variants": ["Standard", "Destructive", "Publish", "RevokeAccess"] + } + ] +} diff --git a/design/figma/figma-file-structure.md b/design/figma/figma-file-structure.md new file mode 100644 index 0000000..74ef343 --- /dev/null +++ b/design/figma/figma-file-structure.md @@ -0,0 +1,55 @@ +# Figma File Structure + +No native Figma file was created in this environment. No Figma MCP/API integration was available through tool discovery. This package is prepared for manual Figma implementation or import through a future integration. + +## Pages + +1. `00 Cover` +2. `01 Foundations` +3. `02 Design Tokens` +4. `03 Components` +5. `04 Public` +6. `05 Student` +7. `06 Teacher` +8. `07 Admin` +9. `08 Responsive` +10. `09 User Flows` +11. `10 Prototype` +12. `11 Deprecated Current UI` + +## Frame Targets + +- Desktop: 1440px +- Small desktop: 1280px +- Tablet: 768px +- Mobile: 390px + +## Foundation Frames + +- Brand principles +- Color roles and semantic pairings +- Typography scale +- Spacing/radius/elevation +- Iconography +- Motion and reduced motion +- Accessibility examples + +## Component Frames + +- App shell variants +- Header variants +- Sidebar/mobile nav variants +- Page headers +- Controls and form fields +- Cards/lists/tables +- States +- Lesson and assessment controls +- Discussion and feedback components + +## Prototype Flow Frames + +- Public landing to login/register +- Student resume course and complete lesson +- Teacher class detail and assignment creation +- Admin user management and confirmation +- Content admin review and publish readiness diff --git a/design/figma/figma-import-readme.md b/design/figma/figma-import-readme.md new file mode 100644 index 0000000..319f01e --- /dev/null +++ b/design/figma/figma-import-readme.md @@ -0,0 +1,29 @@ +# Figma Import Readme + +This package is Figma-ready, not a native `.fig` file. + +## Import Order + +1. Create pages from `figma-file-structure.md`. +2. Add variables from `figma-variables.json`. +3. Build components from `figma-component-map.json`. +4. Create frames from `figma-screen-manifest.json`. +5. Wire prototype links from `figma-prototype-connections.json`. + +## Naming Rules + +- Use semantic variable names exactly as provided. +- Use frame names from `screen.name`. +- Prefix component sets by domain, for example `Navigation/Sidebar`, `Card/Course`, `StatePanel`. + +## Implementation Notes + +- Use 8px card radius unless a component spec says otherwise. +- Do not use generic purple SaaS gradients. +- Do not put cards inside cards. +- Keep learner screens less dense than teacher/admin screens. +- Use real EchoEd content from seed data, especially `Introduction to Africa`, not placeholder lorem ipsum. + +## Native Figma Status + +No native Figma file was created because no functioning Figma connector was available in this session. diff --git a/design/figma/figma-prototype-connections.json b/design/figma/figma-prototype-connections.json new file mode 100644 index 0000000..2e5c58b --- /dev/null +++ b/design/figma/figma-prototype-connections.json @@ -0,0 +1,59 @@ +{ + "connections": [ + { + "from": "public-landing.primaryCta", + "to": "auth-login", + "interaction": "click" + }, + { + "from": "auth-login.studentDemoSubmit", + "to": "student-home", + "interaction": "submit success" + }, + { + "from": "student-home.continueLearning", + "to": "student-lesson-player", + "interaction": "click" + }, + { + "from": "student-lesson-player.completeLesson", + "to": "student-home", + "interaction": "click success" + }, + { + "from": "auth-login.teacherDemoSubmit", + "to": "teacher-dashboard", + "interaction": "submit success" + }, + { + "from": "teacher-dashboard.openClass", + "to": "teacher-class-detail", + "interaction": "click" + }, + { + "from": "teacher-class-detail.createAssignment", + "to": "teacher-assignment-flow", + "interaction": "click" + }, + { + "from": "teacher-assignment-flow.confirm", + "to": "teacher-class-detail", + "interaction": "submit success" + }, + { + "from": "auth-login.adminDemoSubmit", + "to": "admin-dashboard", + "interaction": "submit success" + }, + { + "from": "admin-dashboard.manageUsers", + "to": "admin-user-management", + "interaction": "click" + }, + { + "from": "admin-user-management.cancelDelete", + "to": "admin-user-management", + "interaction": "click" + } + ] +} diff --git a/design/figma/figma-screen-manifest.json b/design/figma/figma-screen-manifest.json new file mode 100644 index 0000000..afa25cd --- /dev/null +++ b/design/figma/figma-screen-manifest.json @@ -0,0 +1,137 @@ +{ + "screens": [ + { + "id": "public-landing", + "name": "Landing", + "role": "Public", + "route": "/", + "frameSizes": [1440, 1280, 768, 390], + "layoutRegions": ["top navigation", "mission hero", "learning preview", "community contribution", "footer"], + "components": ["PublicHeader", "Button", "CoursePreview", "Footer"], + "states": ["default"], + "contentRequirements": ["community project language", "no investor language", "EchoEd mission"], + "apiDependencies": [], + "prototypeLinks": ["login", "public-products"], + "accessibilityNotes": ["first heading is EchoEd", "primary CTA visible without keyboard trap"] + }, + { + "id": "auth-login", + "name": "Login", + "role": "Public", + "route": "/login", + "frameSizes": [1440, 390], + "layoutRegions": ["brand panel", "login form", "demo access helper"], + "components": ["Input", "Button", "Alert"], + "states": ["default", "submitting", "invalid credentials", "bootstrap failed"], + "contentRequirements": ["demo account guidance where appropriate"], + "apiDependencies": ["/api/auth/token", "/api/orgs"], + "prototypeLinks": ["student-home", "teacher-dashboard", "admin-dashboard", "onboarding"], + "accessibilityNotes": ["error linked to form", "show password has accessible name"] + }, + { + "id": "student-home", + "name": "Student Learn Home", + "role": "Student", + "route": "/learn", + "frameSizes": [1440, 768, 390], + "layoutRegions": ["app shell", "next learning", "assigned work", "progress", "achievements"], + "components": ["AppShell.Student", "CourseCard.Assigned", "ProgressSummary", "AchievementDisplay", "MobileBottomNav"], + "states": ["loading", "empty", "error", "all complete"], + "contentRequirements": ["Introduction to Africa demo content", "student-safe support copy"], + "apiDependencies": ["/api/student-courses", "/api/analytics/student-progress", "/api/students/{id}/badges"], + "prototypeLinks": ["student-course-overview", "student-lesson-player"], + "accessibilityNotes": ["next action first in DOM", "status text not color-only"] + }, + { + "id": "student-course-overview", + "name": "Student Course Overview", + "role": "Student", + "route": "/learn/products/:id", + "frameSizes": [1440, 390], + "layoutRegions": ["course header", "unit list", "progress", "source context"], + "components": ["CourseHeader", "LessonCard", "ProgressIndicator"], + "states": ["not started", "in progress", "completed", "unavailable"], + "apiDependencies": ["/api/courses/{id}", "/api/start-course"], + "prototypeLinks": ["student-lesson-player"], + "accessibilityNotes": ["lesson availability explained in text"] + }, + { + "id": "student-lesson-player", + "name": "Student Lesson Player", + "role": "Student", + "route": "/learn/lesson/:id", + "frameSizes": [1440, 768, 390], + "layoutRegions": ["lesson content", "activity", "progress rail", "sticky actions"], + "components": ["LessonPlayer", "ActivityControls", "StatePanel"], + "states": ["loading", "available", "governed unavailable", "completed", "error"], + "apiDependencies": ["/api/progress/segment", "/api/lessons/{id}", "/api/progress/segment/complete"], + "prototypeLinks": ["student-completion"], + "accessibilityNotes": ["live region for save/advance", "safe exit button"] + }, + { + "id": "teacher-dashboard", + "name": "Teacher Today", + "role": "Teacher", + "route": "conceptual /teach using current /home teacher dashboard", + "frameSizes": [1440, 768, 390], + "layoutRegions": ["priorities", "classes", "learner support", "submissions", "curriculum"], + "components": ["AppShell.Teacher", "PriorityList", "ClassCard", "DataList", "StatusPill"], + "states": ["loading", "empty", "error"], + "apiDependencies": ["/api/courses", "/api/users/students", "/api/analytics/teacher-summary"], + "prototypeLinks": ["teacher-class-detail", "teacher-assignment-flow"], + "accessibilityNotes": ["data list fallback on mobile", "evidence basis exposed as text"] + }, + { + "id": "teacher-class-detail", + "name": "Teacher Class Detail", + "role": "Teacher", + "route": "/home/sections/:id", + "frameSizes": [1440, 390], + "layoutRegions": ["class header", "tabs", "roster", "assignments", "progress"], + "components": ["Tabs", "RosterList", "AssignmentCard", "ProgressChart"], + "states": ["loading", "no learners", "error"], + "apiDependencies": ["/api/sections/{id}/roster", "/api/sections/{id}/assignments"], + "prototypeLinks": ["teacher-assignment-flow"], + "accessibilityNotes": ["tabs keyboard navigation", "table/card parity"] + }, + { + "id": "teacher-assignment-flow", + "name": "Teacher Assignment Workflow", + "role": "Teacher", + "route": "conceptual over section assignment APIs", + "frameSizes": [1440, 390], + "layoutRegions": ["stepper", "content picker", "learner picker", "review"], + "components": ["Stepper", "Search", "CourseCard", "CheckboxGroup", "ConfirmationDialog"], + "states": ["draft", "validation error", "submitting", "success"], + "apiDependencies": ["/api/sections/{id}/assignments", "/api/assign-course"], + "prototypeLinks": ["teacher-class-detail"], + "accessibilityNotes": ["stepper announces current step", "review before submit"] + }, + { + "id": "admin-dashboard", + "name": "Admin Dashboard", + "role": "Admin", + "route": "conceptual /admin using current admin dashboard", + "frameSizes": [1440, 768, 390], + "layoutRegions": ["alerts", "metrics", "governance issues", "recent users", "recent courses"], + "components": ["AppShell.Admin", "MetricTile", "DataList", "StatusPill"], + "states": ["loading", "partial error", "empty"], + "apiDependencies": ["/api/analytics/overview", "/api/users", "/api/courses"], + "prototypeLinks": ["admin-user-management"], + "accessibilityNotes": ["alerts before metrics in DOM"] + }, + { + "id": "admin-user-management", + "name": "Admin User Management", + "role": "Admin", + "route": "/home/admin/users", + "frameSizes": [1440, 390], + "layoutRegions": ["filters", "user table", "user detail drawer", "confirmation"], + "components": ["Search", "FilterBar", "DataList", "Drawer", "ConfirmationDialog.Destructive"], + "states": ["loading", "no results", "delete confirm", "error"], + "apiDependencies": ["/api/users", "/api/users/{id}"], + "prototypeLinks": ["admin-dashboard"], + "accessibilityNotes": ["destructive confirmation names user and impact"] + } + ] +} diff --git a/design/figma/figma-variables.json b/design/figma/figma-variables.json new file mode 100644 index 0000000..0c61f8e --- /dev/null +++ b/design/figma/figma-variables.json @@ -0,0 +1,67 @@ +{ + "collections": [ + { + "name": "EchoEd Foundations", + "modes": ["Light"], + "variables": { + "color.surface.page": "#f8f2e8", + "color.surface.default": "#fffdf8", + "color.surface.raised": "#ffffff", + "color.text.default": "#102033", + "color.text.muted": "#40546b", + "color.text.link": "#1b5f85", + "color.action.primary.background": "#0f766e", + "color.action.primary.text": "#ffffff", + "color.action.secondary.background": "#fffdf8", + "color.action.secondary.text": "#102033", + "color.status.success.background": "#eaf7f2", + "color.status.success.text": "#0b5f59", + "color.status.warning.background": "#fff8df", + "color.status.warning.text": "#8a5b00", + "color.status.danger.background": "#fff1f3", + "color.status.danger.text": "#9f1239", + "space.layout.page": "32", + "space.layout.section": "64", + "space.1": "4", + "space.2": "8", + "space.3": "12", + "space.4": "16", + "space.6": "24", + "space.8": "32", + "radius.control.default": "8", + "radius.card.default": "8", + "radius.dialog": "12", + "elevation.raised": "0 12 28 rgba(16,32,51,0.12)", + "state.focus.ring": "#0f766e" + } + }, + { + "name": "EchoEd Typography", + "modes": ["Default"], + "variables": { + "font.family.body": "Inter", + "font.family.display": "Cal Sans", + "font.size.body": "16", + "font.size.small": "14", + "font.size.h1": "40", + "font.size.h2": "32", + "font.size.h3": "24", + "line.height.body": "26", + "line.height.heading": "1.25" + } + }, + { + "name": "EchoEd Responsive", + "modes": ["Desktop", "Small Desktop", "Tablet", "Mobile"], + "variables": { + "frame.width.desktop": "1440", + "frame.width.smallDesktop": "1280", + "frame.width.tablet": "768", + "frame.width.mobile": "390", + "nav.sidebar.width": "288", + "nav.sidebar.collapsedWidth": "80", + "control.touch.minHeight": "44" + } + } + ] +} diff --git a/docs/ux-overhaul/accessibility-audit.md b/docs/ux-overhaul/accessibility-audit.md new file mode 100644 index 0000000..2fb5af1 --- /dev/null +++ b/docs/ux-overhaul/accessibility-audit.md @@ -0,0 +1,49 @@ +# Accessibility Audit + +Evidence: `frontend/src/app/components/accessibility-focus.spec.ts`, `echo-header`, `echo-sidebar`, `echo-loading-state`, `echo-state-panel`, `lesson-view`, `assessment-detail`, global `styles.scss`. + +## What Works + +- Skip link exists in `HomeComponent` and targets `#echoed-main-content`. +- Main content is focusable with `tabindex="-1"`. +- Sidebar collapsed links set accessible labels and titles. +- Header profile menu uses `aria-haspopup`, `aria-expanded`, `role="menu"`, and `role="menuitem"`. +- Loading component specs verify status semantics. +- State panel specs verify alert semantics for errors. +- Global focus styles are tested to ensure focus is not suppressed. +- Lesson and assessment specs include accessible loading/error/unavailable states. + +## Risks by Area + +| Area | Risk | Severity | Evidence | Recommendation | +| --- | --- | --- | --- | --- | +| Navigation | Collapsed sidebar is icon-only and has no persistent visible text. | High | `echo-sidebar.component.html` | Add tooltips, 44px target minimum, mobile bottom navigation for learners, visible section title in expanded mode. | +| Shell semantics | Header says "Command center" and "Workspace OS" for all roles. | Medium | `echo-header.component.html`, `home.component.html` | Role-specific shell title and landmark labels. | +| Motion | Many page/card animations are globally applied. | Medium | `styles.scss` | Keep reduced-motion token and limit nonessential animation. | +| Contrast | Multiple legacy tokens and translucent backgrounds make contrast hard to guarantee. | High | `styles.scss`, page SCSS | Use semantic token contrast targets and document pairings. | +| Forms | Component APIs vary across native, reactive, and custom controls. | Medium | registration, onboarding, course wizard | Standardize label, hint, error, described-by behavior. | +| Tables | Teacher/admin dense tables may lack complete mobile/screen-reader alternatives. | High | teacher/admin specs and templates | Use responsive data list component with row summary and actions. | +| Confirmation | Deletions can happen without a shared confirmation dialog. | High | admin/teacher dashboard delete handlers | Require confirmation dialog with object name and irreversible-action copy. | +| Lesson runtime | Recovery states exist but screen-reader progression announcements need review. | Medium | `lesson-view.component.ts` | Announce segment completion and next lesson load through live region. | +| Discussion | Posts/threads API exists, but UI coverage is unclear. | Medium | backend `posts.py`, `threads.py` | Design moderated discussion component before exposing broadly. | + +## WCAG 2.2 AA Standards for Redesign + +- Text contrast at least 4.5:1, large text 3:1. +- Non-text contrast at least 3:1 for controls, focus indicators, icons, chart segments. +- Focus indicator minimum 2 CSS px outline or equivalent contrast area. +- Target size 24px minimum, 44px recommended for primary touch actions. +- Keyboard access for all menus, dialogs, tabs, drawers, comboboxes, lesson controls, quiz controls. +- Error messages programmatically associated with fields. +- Loading states use `role="status"` and do not trap focus. +- Error states use `role="alert"` only when immediate announcement is needed. +- Reduced motion honors `prefers-reduced-motion`. +- No information conveyed only by color. + +## Required Accessibility QA + +1. Keyboard-only pass for public, auth, student lesson, teacher class detail, admin user management. +2. Screen-reader pass for navigation landmarks, page titles, table/list summaries, lesson completion. +3. Contrast audit of tokens and real screens. +4. Mobile target-size audit at 390px width. +5. Form validation audit across login, registration, onboarding, invites, assignment creation, course wizard. diff --git a/docs/ux-overhaul/accessibility-standards.md b/docs/ux-overhaul/accessibility-standards.md new file mode 100644 index 0000000..d2645c8 --- /dev/null +++ b/docs/ux-overhaul/accessibility-standards.md @@ -0,0 +1,56 @@ +# Accessibility Standards + +Target: WCAG 2.2 AA. + +## Keyboard + +- All interactive controls reachable by Tab. +- Visible focus on every focusable element. +- Menus, tabs, comboboxes, dialogs, drawers, lesson controls, and quiz controls must support expected keyboard behavior. +- Escape closes menus/popovers/dialogs unless a critical confirmation requires explicit choice. + +## Screen Readers + +- One `h1` per page. +- Landmarks: banner, navigation, main, complementary where applicable. +- Loading: `role="status"` with concise text. +- Errors: `role="alert"` only for immediate feedback. +- Route changes should focus the page heading or main container. + +## Color and Contrast + +- Body text: 4.5:1 minimum. +- Large text: 3:1 minimum. +- Icons, borders, focus, charts: 3:1 minimum. +- Never use color alone for status. + +## Forms + +- Every control has a programmatic label. +- Hints and errors use `aria-describedby`. +- Required fields are indicated visually and programmatically. +- Submit buttons show pending state without losing focus. + +## Motion + +- Respect `prefers-reduced-motion`. +- No parallax, background orbs, or decorative motion on app screens. +- Loading skeletons should pause under reduced motion. + +## Responsive and Touch + +- Primary touch targets should be 44px minimum. +- Text must not overlap or clip at 390px width. +- Tables must have responsive data-list alternatives when columns exceed viewport. + +## Data Visualization + +- Include text summaries. +- Use patterns/labels in addition to color. +- Tooltip information must be accessible through keyboard or details panels. + +## Lesson and Assessment Safety + +- Progress-saving state must be visible. +- Leaving a lesson with unsaved work requires confirmation. +- Assessment submit must announce pending, success, and failure states. diff --git a/docs/ux-overhaul/api-ui-contract-map.md b/docs/ux-overhaul/api-ui-contract-map.md new file mode 100644 index 0000000..af00710 --- /dev/null +++ b/docs/ux-overhaul/api-ui-contract-map.md @@ -0,0 +1,96 @@ +# API to UI Contract Map + +Evidence: `frontend/src/app/services/*.ts`, `backend/app/api/routes/*.py`. + +## Auth and Session + +| UI/service | API | Method | Backend file | Roles | UX contract | +| --- | --- | --- | --- | --- | --- | +| `AuthService.login()` | `/api/auth/token` | POST | `routes/auth.py` | Public | Returns JWT, user, org context. Login must wait for permission bootstrap before navigation. | +| `AuthService.register()` | `/api/auth/register` | POST | `routes/auth.py` | Public | Creates account. Registration must not create parallel org flow. | +| `OrganizationService.refreshOrganizations()` | `/api/orgs` | GET | `routes/orgs.py` | Auth | Drives active org switcher and onboarding requirement. | +| `OrganizationService.createOrganization()` | `/api/orgs` | POST | `routes/orgs.py` | Auth | Creates org and org_admin membership. | +| `OrganizationService.switchOrganization()` | `/api/orgs/{id}/switch` | POST | `routes/orgs.py` | Member | Returns refreshed token/org context. UI must not optimistically switch. | +| `MetaService.getEnums()` | `/api/enums` | GET | `routes/meta.py` | Public | Drives registration role/org options. | + +## Learning Runtime + +| UI/service | API | Method | Backend file | Roles | UX contract | +| --- | --- | --- | --- | --- | --- | +| `CoursesService.getCourses()` | `/api/courses` | GET | `routes/courses.py` | admin, teacher, student | Course catalog. Student view must hide staff-only fields via backend serializer. | +| `CoursesService.getCourseById()` | `/api/courses/{id}` | GET | `routes/courses.py` | admin, teacher, student | Course overview and lesson preview. | +| `CoursesService.getStudentCourses()` | `/api/student-courses` | GET | `routes/courses.py` | student | Enrolled learning list and continuation guidance. | +| `CoursesService.enrollInCourse()` | `/api/enroll` | POST | `routes/enroll.py` | student | Self-enrollment; use success/error toast and avoid duplicate enrollment confusion. | +| `CoursesService.assignCourseToStudent()` | `/api/assign-course` | POST | `routes/enroll.py` | admin, teacher | Teacher assignment workflow. | +| `CoursesService.startCourse()` | `/api/start-course` | POST | `routes/start_course.py` | student | Returns governed segment state; UI must handle unavailable/pending/completed. | +| `CoursesService.getCurrentSegment()` | `/api/progress/segment` | GET | `routes/progress.py` | admin, teacher, student | Restores current governed lesson. | +| `CoursesService.markSegmentCompleted()` | `/api/progress/segment/complete` | POST | `routes/progress.py` | admin, teacher, student | Advances progress; UI must preserve recovery from stale segment IDs. | +| `CoursesService.getLessonById()` | `/api/lessons/{id}` | GET | `routes/lessons.py` | admin, teacher, student | Student receives governed learner lesson; staff receive teacher notes. | + +## Curriculum and Authoring + +| UI/service | API | Method | Backend file | Roles | UX contract | +| --- | --- | --- | --- | --- | --- | +| Course wizard | `/api/courses` | POST/PUT/DELETE | `routes/courses.py` | admin, teacher | Course create/edit/delete. Add confirmation and governance visibility. | +| Studio courses | `/api/courses/authoring` | POST | `routes/courses.py` | org content roles | Course authoring shell. | +| Course versions | `/api/courses/{id}/versions`, `/api/course-versions/{id}` | POST/PUT | `routes/courses.py` | content_admin, org_admin | Version workflow. | +| Publish version | `/api/course-versions/{id}/publish` | POST | `routes/courses.py` | content_admin, org_admin | Requires readiness/safe-publish context. | +| Units | `/api/units`, `/api/course-versions/{id}/units` | CRUD | `routes/units.py` | admin, teacher | Course structure editing. | +| Lessons | `/api/lessons` | CRUD | `routes/lessons.py` | admin, teacher | Lesson editing; staff fields visible only staff. | +| Uploads | `/api/upload/coloring`, `/api/upload/storybook`, `/api/upload/badge` | POST | `routes/uploads.py` | admin/teacher/admin badge | Asset upload. Storybook image URLs must use backend public URL in deployed environments. | + +## Assessment and Credentials + +| UI/service | API | Method | Backend file | Roles | UX contract | +| --- | --- | --- | --- | --- | --- | +| `ProgramsService.getPrograms()` | `/api/programs` | GET | `routes/programs.py` | Auth roles | Pathway list with student-specific progress. | +| Program enroll | `/api/programs/{id}/enroll` | POST | `routes/programs.py` | student | Adds pathway/courses. | +| Assessment detail | `/api/assessments/{id}` | GET | `routes/assessments.py` | Auth | Student form or staff preview. | +| Submit attempt | `/api/assessments/{id}/attempts` | POST | `routes/assessments.py` | student | Needs submit pending/failure and completion state. | +| Certifications | `/api/certifications`, `/api/students/me/certifications` | GET/POST | `routes/certifications.py` | staff/student | Separate learner credential display from staff management. | + +## Classroom and Organization + +| UI/service | API | Method | Backend file | Roles | UX contract | +| --- | --- | --- | --- | --- | --- | +| `SectionsService.getSections()` | `/api/sections` | GET | `routes/sections.py` | teacher, org_admin, instructor | Teacher class list. | +| Section roster | `/api/sections/{id}/roster` | GET | `routes/sections.py` | teacher, org_admin, instructor | Class detail roster. | +| Add enrollment | `/api/sections/{id}/enrollments` | POST | `routes/sections.py` | teacher, org_admin, instructor | Enroll learner. | +| Assignments | `/api/sections/{id}/assignments` | GET/POST | `routes/assignments.py` | teacher/org roles | Assignment workflow. | +| Submit assignment | `/api/assignments/{id}/submit` | POST | `routes/assignments.py` | student | Student work submission; no complete UI found. | +| Invites | `/api/orgs/{id}/invites`, `/api/invites/accept` | GET/POST | `routes/invites.py` | org_admin/content_admin for invites | Invite management and acceptance. | + +## Analytics and Governance + +| UI/service | API | Method | Backend file | Roles | UX contract | +| --- | --- | --- | --- | --- | --- | +| Admin overview | `/api/analytics/overview` | GET | `routes/analytics.py` | staff/admin | Admin dashboard metrics. | +| Teacher summary | `/api/analytics/teacher-summary` | GET | `routes/analytics.py` | teacher/admin | Classroom progress table/list. | +| Student progress | `/api/analytics/student-progress` | GET | `routes/analytics.py` | student | Learner dashboard metrics. | +| Educator support | `/api/analytics/...` runtime support | GET | `routes/analytics.py` | educator roles | Reteach/review/enrichment recommendation visibility. | +| Governance summary | `/api/courses/{id}/governance-summary` | GET | `routes/courses.py` | staff | Aggregates publish readiness, safe-publish, competency integrity, runtime interventions. | + +## V2 Workspace + +| UI/service | API | Method | Backend file | Roles | UX contract | +| --- | --- | --- | --- | --- | --- | +| Workspaces | `/api/workspaces` | GET | `routes/v2_platform.py` | creator roles | Workspace selection/status. | +| Projects | `/api/projects` | GET/POST | `routes/v2_platform.py` | creator roles | Project shell creation/list/detail. | +| Products | `/api/products` | GET/POST/PATCH | `routes/v2_platform.py` | creator roles | Product wrapper over course/content. | +| Public products | `/api/public/products` | GET | `routes/v2_platform.py` | Public | Public catalog/detail. | +| Learner portal products | `/api/learner-portal/products` | GET | `routes/v2_platform.py` | student/auth | Learner product catalog. | +| Knowledge sources | `/api/knowledge-sources` | GET/POST | `routes/v2_platform.py` | creator roles | Source metadata shell. | +| Artifacts | `/api/artifacts` | GET/POST | `routes/v2_platform.py` | creator roles | Artifact metadata shell. | +| Review center | `/api/review-center` | GET | `routes/v2_platform.py` | creator roles | Review queue. | +| Review status | `/api/artifacts/{id}/review-status`, `/api/products/{id}/review-status` | PATCH | `routes/v2_platform.py` | creator roles | Content review state changes. | +| Access grants | `/api/access-grants` | GET/POST/PATCH revoke | `routes/v2_platform.py` | creator roles | Access management. Avoid payment/commercial assumptions. | + +## Backend Change Classification + +Required for design implementation: none verified during design phase. + +Potential optional backend additions: + +- Context-aware current-user route to return resolved roles, active org, and default landing target in one call. Optional because current token + `/api/orgs` supports it. +- Parent/family child-progress endpoints if parent portal is implemented. Required only for future parent role. +- Search endpoints for public products/courses if client-side filtering becomes insufficient. Optional initially. diff --git a/docs/ux-overhaul/backend-change-assessment.md b/docs/ux-overhaul/backend-change-assessment.md new file mode 100644 index 0000000..4c101f7 --- /dev/null +++ b/docs/ux-overhaul/backend-change-assessment.md @@ -0,0 +1,40 @@ +# Backend Change Assessment + +## Required Backend Changes + +None verified during the design phase. + +The redesign can begin frontend-first using existing APIs for: + +- Auth and registration: `/api/auth/token`, `/api/auth/register`. +- Session/org context: `/api/orgs`, `/api/orgs/{id}/switch`. +- Curriculum: courses, units, lessons, activities. +- Learning runtime: start-course, progress segment, segment complete. +- Assessment and certifications. +- Sections, roster, assignments. +- Analytics and governance summary. +- V2 workspace: products, projects, sources, artifacts, review center, access grants. +- Uploads and storybook/coloring/badge media. +- Posts and threads. + +## Optional Backend Changes + +| Change | Classification | Reason | +| --- | --- | --- | +| Current-user/session summary endpoint | Optional | Could reduce token/org bootstrap complexity, but current services work. | +| Preferred landing space preference | Optional | Could persist multi-role default; current preferences may be extended later. | +| Parent/guardian child progress APIs | Required only for parent portal | Parent role is partial; do not expose full parent dashboard without backend relationship/access model. | +| Moderation/flagging endpoints | Required only for full moderation UI | Posts/threads exist, but moderation status was not verified. | +| Asset library list/delete APIs | Optional | Upload exists; admin asset management may need browse/delete later. | +| Server-side search/filter/pagination | Optional | Can begin client-side; may be needed for scale. | +| Non-destructive archive/deactivate endpoints | Optional/preferred | Safer than delete for users/courses if current API only deletes. | + +## Backend Changes Avoided + +- No duplicate authentication system. +- No duplicate organization onboarding. +- No new role/permission model. +- No parallel progress/session tracking. +- No duplicate course/lesson/assignment/section models. +- No database schema changes in design phase. +- No API shape changes hidden inside the UX redesign. diff --git a/docs/ux-overhaul/component-inventory.md b/docs/ux-overhaul/component-inventory.md new file mode 100644 index 0000000..a424e20 --- /dev/null +++ b/docs/ux-overhaul/component-inventory.md @@ -0,0 +1,58 @@ +# Component Inventory + +Evidence: `frontend/src/app/components`, `frontend/src/app/shared`, Storybook stories. + +## Shared Shell Components + +| Component | Path | Current purpose | Redesign decision | +| --- | --- | --- | --- | +| `HomeComponent` | `pages/home` | Authenticated shell, sidebar/header, lesson mode. | Keep as base shell but introduce role-aware shell metadata. | +| `SidebarComponent` | `components/echo-sidebar` | Workspace nav filtered by permissions. | Replace one-size nav with role-specific nav sections using same permission service. | +| `EchoHeaderComponent` | `components/echo-header` | Brand, breadcrumbs, org switcher, profile menu. | Keep org switch contract; redesign as role-aware app bar. | +| `EchoBreadcrumbsComponent` | `components/echo-breadcrumbs` | URL-derived breadcrumbs. | Keep, but add custom labels and hierarchy map. | +| `IconModule/AppIconComponent` | `shared/icon` | Inline SVG icon set. | Extend icon set and document size/label rules. | + +## Foundational UI Components + +| Component | Path | Storybook | Current maturity | Redesign decision | +| --- | --- | --- | --- | --- | +| Button | `components/echo-button` | Yes | Basic | Standardize variants, sizes, icon support, loading state. | +| Input | `components/echo-input` | Yes | Basic | Add label/hint/error API. | +| Select | `components/echo-select` | Yes | Basic | Add described-by and validation states. | +| Textarea | `components/echo-textarea` | Yes | Basic | Align with input. | +| Checkbox | `components/echo-checkbox` | Yes | Basic | Add group semantics guidance. | +| Radio | `components/echo-radio`, `echo-radio-group` | Yes | Basic | Ensure keyboard arrow behavior. | +| Toggle | `components/echo-toggle` | Yes | Basic | Use switch semantics. | +| Modal | `components/echo-modal` | Yes | Basic confirmation | Upgrade to accessible dialog with focus trap and destructive variant. | +| Tooltip | `components/echo-tooltip` | Yes | Basic | Use for icon-only nav/actions. | +| Toast | `components/echo-toast`, `echo-toast-container` | Yes | App feedback | Add severity and persistence rules. | +| Loading state | `components/echo-loading-state` | Yes | Strong | Keep; add skeleton variants. | +| State panel | `components/echo-state-panel` | Yes | Strong | Keep; expand empty/error/permission/success patterns. | +| Badge | `components/echo-badge` | Yes | Basic | Separate status pill vs achievement badge. | +| Stat card | `components/stat-card` | No | Dashboard metric | Replace with metric tile spec. | +| Timeline | `components/timeline` | No | Event timeline | Redesign for learner history/activity audit. | + +## Domain Components + +| Component | Path | Purpose | Redesign decision | +| --- | --- | --- | --- | +| `StudentCourseCardComponent` | `components/student-course-card` | Student course summary/action. | Promote to course card variants for assigned, available, complete. | +| `LessonViewerComponent` | `shared/lesson-viewer.component` | Renders lesson content and activities. | Keep runtime contract; redesign layout/controls. | +| `StorybookViewerComponent` | `components/storybook-viewer` | Storybook pages/media. | Add image loading/error/public URL guidance. | +| `ColoringCanvasComponent` | `components/coloring-canvas` | Interactive coloring activity. | Audit keyboard/touch accessibility before broad use. | +| `AfricaMapExplorerComponent` | `components/africa-map-explorer` | Map exploration. | Use historical-geographic visual guidance and keyboard fallback. | +| `AchievementItemComponent` | `components/achievement-item` | Learner achievement. | Align with achievement display spec. | +| `DemoTourOverlayComponent` | `components/demo-tour-overlay` | Guided demo overlay. | Keep demo-only; avoid required workflows hidden in tour. | +| `EE design system` | `components/ee-design-system` | Presentational components. | Existing V2 layer should be reconciled with new tokens, not expanded blindly. | + +## Page Components + +Major page components include public/auth (`landing`, `login`, `registration`, `public-products`), learner (`student-view`, `learner-portal`, `lesson-view`, `programs`, `assessment-detail`, `certifications`), teacher (`teacher-view`, `sections`, `section-detail`), admin (`admin-view`, `admin-users`, `admin-courses`, `admin-badges`), content/workspace (`workspace-dashboard`, `product-studio`, `project-detail`, `product-detail`, `review-center`, `access-grants`, `workspace-analytics`, `v2-collection-page`). + +## Component Debt + +- Several components use local styling instead of shared tokenized states. +- Storybook coverage is incomplete for domain components and page states. +- Data tables/lists are page-local and should become a shared responsive data component. +- Dialogs need focus management and destructive-action copy standards. +- Icon taxonomy is small and should be intentionally mapped to role navigation. diff --git a/docs/ux-overhaul/component-specifications.md b/docs/ux-overhaul/component-specifications.md new file mode 100644 index 0000000..a7a70d6 --- /dev/null +++ b/docs/ux-overhaul/component-specifications.md @@ -0,0 +1,128 @@ +# Component Specifications + +This file defines implementation targets. Production components should migrate incrementally. + +## Application Shell + +- Purpose: authenticated layout with role-aware navigation, org context, notifications, profile, skip link. +- Variants: student, teacher, studio, organization, admin, lesson. +- States: loading session, org load error, access denied, compact/mobile, multi-role. +- Accessibility: landmarks, skip link, keyboard nav, focus restoration after route changes. +- Responsive: desktop sidebar for staff; learner bottom nav on mobile; lesson hides global chrome. +- Anti-patterns: one generic "Workspace OS" shell for all users. + +## Header + +- Purpose: page context, org switcher, search, notifications, profile. +- Variants: standard, compact, lesson. +- States: org loading, switch pending/success/error, menu open. +- Keyboard: menu opens with Enter/Space, closes with Escape, arrow navigation optional. + +## Sidebar / Primary Navigation + +- Purpose: role-specific primary navigation. +- Variants: expanded, collapsed, mobile drawer. +- States: active, hover, focus, disabled/unavailable, loading permissions. +- Accessibility: text label always available; icon-only requires tooltip and `aria-label`. +- Anti-patterns: hiding essential workflows in overflow; unlabeled icons. + +## Mobile Navigation + +- Purpose: fast access to primary learner/staff tasks. +- Variants: learner bottom nav, staff drawer. +- Accessibility: 44px targets, active state text and icon. + +## Breadcrumbs + +- Purpose: show hierarchy on deep routes. +- Variants: text, compact back-link. +- Behavior: use route metadata/entity titles, not raw IDs. + +## Page Header + +- Purpose: title, description, primary action, status. +- Variants: standard, compact, data-heavy, lesson. +- Anti-patterns: hero-scale type in dashboards. + +## Tabs + +- Purpose: contextual secondary navigation. +- Variants: underline, segmented, scrollable mobile. +- Keyboard: arrow keys move focus; Home/End optional. + +## Buttons and Icon Buttons + +- Variants: primary, secondary, tertiary, danger, ghost, link; icon-only. +- Sizes: sm 36px, md 44px, lg 48px. +- States: default, hover, active, focus, disabled, loading. +- Accessibility: icon-only needs accessible name and tooltip. + +## Form Controls + +Controls: inputs, selects, comboboxes, search, checkboxes, radios, switches, textarea, date controls, file upload. + +- Required states: default, focus, error, success, disabled, loading. +- Validation: label, hint, error, described-by ID. +- Keyboard: native behavior where possible; combobox follows ARIA practices. +- Anti-patterns: placeholder as label; color-only errors. + +## Cards + +- Purpose: repeated items and genuinely framed tools. +- Variants: course, lesson, assignment, metric, achievement, empty/action. +- States: active, selected, completed, locked, unavailable. +- Anti-patterns: cards nested inside cards; page sections as floating cards. + +## Progress Indicators + +- Variants: linear, ring, stepper, status timeline. +- Accessibility: include text value and state. +- Usage: learning progress, assignment completion, publish readiness. + +## Badges and Achievements + +- Status pill: small operational state. +- Achievement badge: learner accomplishment with image/icon, criteria, date. +- Accessibility: do not rely on color/shape alone. + +## Tables and Responsive Data Lists + +- Purpose: rosters, users, assignments, reports. +- Desktop: sortable table where useful. +- Mobile: data cards with row title, key facts, actions. +- Accessibility: table headers, captions, filter descriptions, keyboard actions. + +## Pagination, Filters, Search + +- Filters: chips for common filters, drawer for advanced filters on mobile. +- Search: clear button, results count, empty state. +- Pagination: page size and total count where backend supports it; otherwise document client-side limits. + +## Empty, Loading, Error, Permission States + +- Empty: explain why empty and next action. +- Loading: skeleton for known layouts, status text for unknown. +- Error: what failed, impact, retry action. +- Permission denied: who can help, current role/org context. + +## Overlays + +Components: alerts, toasts, banners, tooltips, popovers, menus, dialogs, confirmation dialogs, drawers. + +- Dialogs require focus trap, Escape close unless destructive confirmation in progress, labelled title, described body. +- Destructive confirmation must name the object and impact. +- Toasts must not be the only record of critical state changes. + +## Domain Components + +| Component | Variants | Required behavior | +| --- | --- | --- | +| Course card | Assigned, available, completed, staff preview | Show status, next action, progress, age/grade metadata. | +| Lesson card | Ready, locked, completed, review, enrichment | Explain availability and action. | +| Assignment card | Not started, in progress, submitted, returned, overdue | Due date, target, status, feedback entry. | +| Activity timeline | Student progress, project review, admin audit | Chronological, accessible, filterable. | +| Discussion thread | Learner, teacher, moderator | Moderation state, reply, flag, source/context. | +| Rich content | Lesson body, historical source, source note | Captions, provenance, readable width. | +| Quiz controls | MCQ, short answer, reflection | Submit pending, validation, feedback. | +| Teacher feedback | Inline, rubric, summary | Student-safe feedback language. | +| Charts | Progress, mastery, access, review queue | Text summaries and no color-only legends. | diff --git a/docs/ux-overhaul/content-design-guide.md b/docs/ux-overhaul/content-design-guide.md new file mode 100644 index 0000000..2818de7 --- /dev/null +++ b/docs/ux-overhaul/content-design-guide.md @@ -0,0 +1,56 @@ +# Content Design Guide + +## Voice + +- Clear, warm, and specific. +- Use learner-safe language. +- Explain why something is blocked or unavailable without blaming the user. +- Prefer role language users recognize: class, learner, assignment, lesson, progress. + +## Naming + +| Current/internal | Preferred UI label | +| --- | --- | +| Section | Class | +| Cohort | Class or Group, depending context | +| Product | Learning product or Course package when learner-facing | +| Workspace OS | Workspace, Studio, Teach, Learn, Admin by role | +| Commercial | Community | +| Runtime intervention | Learner support recommendation | +| Safe publish | Learner safety check | + +## Error Copy Pattern + +Use: + +1. What happened. +2. What the user can do. +3. Whether data was changed. + +Example: "We could not save this assignment. No learners were assigned. Try again or check your connection." + +## Empty State Pattern + +- Title: plain reason. +- Body: what this means. +- Action: next useful step. + +Avoid implementation roadmap copy such as "This arrives in a later phase" in production user flows. + +## Cultural Content Rules + +- Historical materials need context and source treatment. +- Do not use decorative motifs as a substitute for accurate content. +- Avoid flattening Africa or African-American history into a single visual theme. +- Use respectful captions, dates, and geography when available. + +## Child-Safe Copy + +- Keep sentence length short on learner surfaces. +- Avoid shame language: not "failed"; use "try again", "review", "ready for support". +- Use encouragement sparingly and specifically. + +## Community Project Language + +- Avoid investor, revenue, commercial, marketplace, conversion, and sales copy. +- Use contributor, community, access, stewardship, review, learning, and shared resources where accurate. diff --git a/docs/ux-overhaul/cross-role-workflows.md b/docs/ux-overhaul/cross-role-workflows.md new file mode 100644 index 0000000..0554ca0 --- /dev/null +++ b/docs/ux-overhaul/cross-role-workflows.md @@ -0,0 +1,54 @@ +# Cross-Role Workflows + +## Course to Classroom + +```mermaid +flowchart LR + A[Content admin authors course] --> B[Review center approves] + B --> C[Product/course published] + C --> D[Teacher previews curriculum] + D --> E[Teacher assigns to class] + E --> F[Student completes lesson] + F --> G[Teacher monitors progress] + G --> H[Runtime support recommends reteach/review/enrichment] +``` + +Backend compatibility: supported by existing course/version/review/product, assignment, progress, and analytics APIs. + +## Organization Onboarding + +```mermaid +flowchart LR + A[User registers] --> B[Optional pending org setup] + B --> C[Login] + C --> D[Onboarding guard checks orgs] + D --> E[Create organization] + E --> F[Switch active org] + F --> G[Role-aware home] +``` + +Backend compatibility: supported by `auth`, `orgs`, `PermissionsService`, and onboarding helpers. + +## Discussion and Moderation + +```mermaid +flowchart LR + A[Student posts question] --> B[Thread API] + B --> C[Teacher monitors class discussion] + C --> D[Admin/content moderator reviews flagged content] + D --> E[Resolution and learner-safe feedback] +``` + +Gap: backend `posts.py` and `threads.py` exist, but full UI and moderation workflow are not clearly implemented. + +## Access Grants + +```mermaid +flowchart LR + A[Org admin/content admin grants access] --> B[Access grant API] + B --> C[Learner portal product visible] + C --> D[Student starts learning] + D --> E[Teacher/admin sees progress] +``` + +Design warning: avoid commercial/marketplace framing in community project UI. diff --git a/docs/ux-overhaul/current-experience-audit.md b/docs/ux-overhaul/current-experience-audit.md new file mode 100644 index 0000000..c24efd6 --- /dev/null +++ b/docs/ux-overhaul/current-experience-audit.md @@ -0,0 +1,98 @@ +# Current Experience Audit + +Date: 2026-07-10 + +Scope: static repository audit of the Angular frontend, FastAPI backend routes, seeded demo data, shared styles, and automated tests. A native browser walkthrough of every role was not completed in this phase; the findings below are grounded in file evidence. + +## Verified Stack + +| Area | Evidence | Finding | +| --- | --- | --- | +| Frontend | `frontend/package.json`, `frontend/src/app/app.routes.ts` | Angular 20 standalone components with Angular Router. | +| Styling | `frontend/tailwind.config.js`, `frontend/src/styles.scss`, page SCSS files | Tailwind plus global SCSS and page-local SCSS. There are overlapping token systems. | +| Backend | `backend/app/main.py`, `backend/app/api/routes/*.py` | FastAPI route modules for auth, orgs, users, courses, lessons, progress, analytics, V2 platform, sections, assignments, posts, threads, uploads. | +| Auth | `backend/app/auth.py`, `backend/app/api/routes/auth.py`, `frontend/src/app/services/auth.service.ts` | JWT token login at `/api/auth/token`, registration at `/api/auth/register`, token payload drives frontend session. | +| Guards | `frontend/src/app/guards/home-session.guard.ts`, `frontend/src/app/guards/role.guard.ts` | Authenticated shell requires `PermissionsService.bootstrapSession()`. Role-gated routes use canonical permissions. | +| Tests | `frontend/src/app/**/*.spec.ts`, `backend/tests` | Karma/Jasmine and pytest coverage exists for auth/org state, sidebar/header accessibility, learner/teacher/admin states, API services, progress, uploads, permissions. | +| Storybook | `frontend/.storybook`, `frontend/src/app/components/*.stories.ts` | Storybook exists for several components but is not a complete product design lab. | + +## Current Product Shape + +EchoEd currently contains three overlapping experiences: + +1. Public marketing and public product pages: `''`, `/products`, `/products/:slug`. +2. Legacy role dashboard shell under `/home`: student, teacher, admin, courses, programs, certifications, sections, preferences, org invites, studio courses. +3. V2 workspace shell under `/workspace`: projects, product studio, products, knowledge sources, artifacts, review center, access, learners, analytics, community, settings. +4. Learner portal under `/learn`: learner dashboard, products, paths, certificates, resources, lessons. + +The overlap creates cognitive load because the same domain appears under multiple route families with different labels: courses/products, sections/cohorts, admin course management/product management, `/home/lesson/:id` and `/learn/lesson/:id`. + +## Roles and Access + +Implemented roles and role concepts are verified in `backend/app/enum.py`, `backend/app/deps.py`, `frontend/src/app/services/permissions.service.ts`, and `frontend/src/app/app.routes.ts`. + +| Role | Current status | Evidence | +| --- | --- | --- | +| Student | Implemented | `require_roles("student")` on enroll/start/certification routes; `/learn`; student dashboard component. | +| Teacher | Implemented | `require_roles("admin", "teacher")` for course creation and assignments; section org role access. | +| Admin | Implemented | `/home/admin/users`, `/home/admin/courses`, `/home/admin/badges`; backend user CRUD requires admin. | +| Org admin | Implemented | `OrganizationRole.ORG_ADMIN`; org invites, sections, workspace, studio courses. | +| Content admin | Implemented | `OrganizationRole.CONTENT_ADMIN`; studio courses, review/content operations. | +| Instructor | Implemented/partial | `OrganizationRole.INSTRUCTOR`; section and workspace nav, but fewer dedicated screens. | +| Parent | Partial | registration exposes parent and organization type family; no dedicated parent dashboard route. | +| Viewer | Partial/backend only | enum value exists; no clear frontend route model. | +| Super admin | Partial/backend privileged | backend bypass in org checks and V2 creator role; frontend route constants omit super_admin in some places. | + +## Strengths + +- Auth/session behavior is more robust than the visible UI suggests. `PermissionsService` prevents raw token-only navigation and tests cover failure, onboarding, and active org state. +- The shell already has a skip link, focusable main landmark, labeled sidebar controls, loading states, and org switching state. +- Student, teacher, and admin dashboards contain real learning operations, not only static cards. +- Backend APIs include mature governance, publish-readiness, safe-publish, competency integrity, runtime intervention, and V2 review/access concepts. +- Seed data provides realistic demo accounts and course content: `EchoEd Demo School`, `Introduction to Africa`, student archetypes, content admin dogfooding workspace. + +## Highest Severity UX Problems + +1. Navigation architecture is product-internal rather than role-task oriented. `/home`, `/workspace`, and `/learn` expose overlapping concepts with different labels. +2. The application shell title and copy say "Workspace OS" and "Command center" even for learner-facing routes, creating role confusion. +3. Student routes are split between `/home` and `/learn`; the canonical learner destination is unclear after login. +4. Teacher and admin dashboards combine operational priorities, course governance, quick actions, and reporting in dense pages with weak hierarchy. +5. Destructive actions such as course/user deletion exist in dashboard components without a documented confirmation pattern. +6. Registration supports parent/instructor concepts but does not provide role-specific post-registration journeys. +7. Content/community language is still inconsistent from prior commercialization work; `/workspace/commercial` now labels "Community" but the route and component name remain commercial. +8. Global SCSS contains two visual systems and some mojibake comments, making brand consistency fragile. +9. Empty/loading/error states exist but are unevenly applied across all screens and do not yet define a shared decision model. +10. Mobile navigation collapses to a sidebar overlay pattern but lacks a dedicated bottom/tab model for learners and rapid teacher tasks. + +## Accessibility Concerns + +- Positive: focus styles are globally retained and tested in `frontend/src/app/components/accessibility-focus.spec.ts`. +- Positive: loading states use status semantics and error panels use alert semantics in component specs. +- Risk: icon-only collapsed sidebar relies on `aria-label`/`title`; needs tooltip and target-size standardization. +- Risk: page-local cards and tables may not all provide responsive data-list alternatives. +- Risk: role selector and dense governance tables need screen-reader order review. +- Risk: motion is extensive in `styles.scss`; reduced-motion support exists but should be centralized in tokens. + +## Responsive Concerns + +- The shell collapses sidebar below 1024px in `HomeComponent.syncShellViewport()`. +- Current layout depends heavily on desktop sidebar mental models. +- Several data-heavy screens should switch to responsive data lists and task-first summaries rather than horizontally dense tables. +- Lesson mode correctly hides sidebar/header, but recovery and exit controls need consistent mobile placement. + +## Brand and Assets + +- No explicit logo asset was found by repository search. Current mark is text-based "EE" in `echo-header` and `echo-sidebar`. +- Relevant visual assets include `frontend/src/assets/maps/africa-reference.svg`, `world-context.svg`, storybook/coloring media in `backend/storybook` and `backend/colorings`, and social screenshots under `docs/screenshots`. +- `/mnt/data/logo_concept.webp` was not evaluated in this Windows workspace. If supplied later, treat it as source input for token and mark refinement. + +## Product Design Implication + +The redesign should preserve backend behavior and routes initially, but introduce a role-aware IA that resolves overlaps: + +- Learners start in Learn. +- Educators start in Teach. +- Admins start in Admin. +- Content/community operators start in Studio. + +The first implementation should create a clearer shell and shared component system before restyling individual screens. diff --git a/docs/ux-overhaul/current-user-journeys.md b/docs/ux-overhaul/current-user-journeys.md new file mode 100644 index 0000000..a1ecdfa --- /dev/null +++ b/docs/ux-overhaul/current-user-journeys.md @@ -0,0 +1,92 @@ +# Current User Journeys + +## Student: Sign In to Lesson + +```mermaid +flowchart TD + A[Open /login] --> B[POST /api/auth/token] + B --> C[PermissionsService bootstrap] + C --> D{Ready or onboarding?} + D -->|ready| E[/home] + D -->|onboardingRequired| F[/onboarding/organization] + E --> G[UserDashboard student view] + G --> H[GET /api/student-courses] + H --> I[Start/resume course] + I --> J[POST /api/start-course or GET /api/progress/segment] + J --> K{governed_available?} + K -->|yes| L[/home/lesson/:unitProgressId] + K -->|no| M[Unavailable state] + L --> N[GET /api/lessons/:id] + N --> O[Complete lesson] + O --> P[POST /api/progress/segment/complete] +``` + +Problems: default route is `/home`, not canonical `/learn`; route is governed but labels do not explain why a lesson is paused. + +## Student: Interrupted Lesson Recovery + +```mermaid +flowchart TD + A[Open stale /home/lesson/:id] --> B[GET /api/progress/segment] + B -->|404| C[GET /api/student-courses] + C --> D{active course has unit_progress_id?} + D -->|yes| E[Navigate to recovered lesson id] + D -->|no| F[Retryable error state] +``` + +Strength: recovery exists and is covered by tests. + +## Teacher: Assign Learning + +```mermaid +flowchart TD + A[Sign in] --> B[/home teacher dashboard] + B --> C[GET /api/courses] + B --> D[GET /api/users/students] + B --> E[GET /api/analytics/teacher-summary] + C --> F[Select course] + D --> G[Select student] + F --> H[POST /api/assign-course] + G --> H + H --> I[Toast success/error] +``` + +Problems: assignment is embedded in a dense dashboard rather than a dedicated guided workflow. + +## Teacher: Manage Class + +```mermaid +flowchart TD + A[/home/sections] --> B[GET /api/sections] + B --> C[/home/sections/:id] + C --> D[GET /api/sections/:id/roster] + C --> E[GET /api/sections/:id/assignments] + C --> F[POST /api/sections/:id/enrollments] + C --> G[POST /api/sections/:id/assignments] +``` + +Problems: the user-facing label should be "Classes"; assignment creation needs better validation and preview. + +## Admin: Manage Users + +```mermaid +flowchart TD + A[/home/admin/users] --> B[GET /api/users] + B --> C[Filter/review users] + C --> D[PUT /api/users/:id] + C --> E[DELETE /api/users/:id] +``` + +Problems: confirmation/audit-sensitive states need standardization. + +## Content Admin: Review Content + +```mermaid +flowchart TD + A[/workspace/review-center] --> B[GET /api/review-center] + B --> C[Open product or artifact] + C --> D[PATCH review-status] + D --> E[Updated queue] +``` + +Problems: content/admin workflows share generic workspace nav with teachers and instructors. diff --git a/docs/ux-overhaul/current-vs-proposed-scorecard.md b/docs/ux-overhaul/current-vs-proposed-scorecard.md new file mode 100644 index 0000000..98f503c --- /dev/null +++ b/docs/ux-overhaul/current-vs-proposed-scorecard.md @@ -0,0 +1,31 @@ +# Current vs Proposed UX Scorecard + +Scale: 1 = poor, 5 = excellent. + +| Criterion | Current score | Current evidence | Proposed score | Proposed evidence | +| --- | ---: | --- | ---: | --- | +| Role clarity | 2 | `/home`, `/workspace`, `/learn` overlap; generic shell copy. | 4 | Role spaces in IA/navigation docs. | +| Task completion | 3 | Core workflows exist, but teacher/admin tasks are dense. | 4 | Task-first journeys and screen specs. | +| Navigation consistency | 2 | Courses/products and sections/cohorts duplicate. | 4 | Proposed sitemap and nav model. | +| Accessibility | 3 | Good focus/state tests; gaps in tables/dialogs/mobile nav. | 4 | WCAG standards and component specs. | +| Responsive behavior | 3 | Sidebar collapse exists; mobile role workflows weak. | 4 | Breakpoint strategy and mobile nav requirements. | +| Content readability | 3 | Real seed content; dense dashboards and implementation copy. | 4 | Content design guide and screen hierarchy. | +| Cognitive load | 2 | Many cards/metrics/actions compete. | 4 | Role dashboards prioritize next action/alerts. | +| Error prevention | 2 | Delete handlers exist without shared confirmation. | 4 | Confirmation dialog requirements. | +| Feedback/status | 3 | Loading/error states present in key screens. | 4 | Shared state standard across all screens. | +| Cross-role handoffs | 3 | APIs support assignment/progress/review; UI fragmented. | 4 | Cross-role workflow maps. | +| Backend compatibility | 4 | Existing domain contracts are mature. | 5 | Proposal explicitly preserves contracts. | +| Component reuse | 3 | Component library exists but inconsistent coverage. | 4 | Component spec and migration tasks. | +| Implementation complexity | 2 | Broad route/style overlap. | 3 | Incremental phased plan with rollback. | +| Cultural integrity | 3 | Mission content exists; visual system not coherent. | 4 | Warm archive direction and source guidance. | +| Educational suitability | 3 | Strong lesson/progress foundation. | 4 | K-5 learner guidance and teacher support flows. | +| Child safety/privacy | 3 | Governed delivery and safe publish concepts exist. | 4 | Learner-safe copy and moderation/confirmation requirements. | +| Demo usability | 4 | Seeded demo accounts and routes are strong. | 4 | Demo content reused in prototypes; route clarity improves. | + +## Summary + +Current overall average: 2.8. + +Proposed design-phase target average: 4.1. + +The proposed score reflects design readiness, not production completion. diff --git a/docs/ux-overhaul/design-debt-register.md b/docs/ux-overhaul/design-debt-register.md new file mode 100644 index 0000000..59188b2 --- /dev/null +++ b/docs/ux-overhaul/design-debt-register.md @@ -0,0 +1,19 @@ +# Design Debt Register + +| ID | Debt | Severity | Evidence | Impact | Recommended resolution | +| --- | --- | --- | --- | --- | --- | +| DD-01 | One shared sidebar for all creator roles. | High | `echo-sidebar.component.ts` navSections | Users see product/workspace labels unrelated to their task. | Role-specific nav model using same permissions. | +| DD-02 | `/home`, `/learn`, and `/workspace/learners` overlap. | High | `app.routes.ts` | Learner and staff journeys lack a canonical path. | Make `/learn` learner canonical; staff learner management under Teach/Admin. | +| DD-03 | Commercial route/component naming remains. | Medium | `/workspace/commercial`, `CommercialDashboardComponent` | Conflicts with community GitHub project direction. | Rename visible IA to Community; plan route alias/deprecation later. | +| DD-04 | Global styles define multiple visual systems. | High | `styles.scss` | Inconsistent color, radius, shadow, motion, contrast. | Introduce separate token files, then migrate incrementally. | +| DD-05 | Overuse of cards and oversized hero-like page headers in app surfaces. | Medium | `.ee-page-header`, dashboard views | Operational screens become harder to scan. | Adopt dense but warm learning-platform layouts. | +| DD-06 | Destructive actions lack shared confirmation standard. | High | `deleteCourse`, `deleteUser` handlers | Accidental deletion risk. | Shared confirmation dialog with named object and role copy. | +| DD-07 | Parent role is exposed before product support exists. | Medium | registration role options, backend enum | Parent users can register with no destination. | Mark parent as future/limited and route to family setup placeholder only if implemented. | +| DD-08 | Super admin inconsistently surfaced. | Medium | backend V2 creator roles include; frontend route constants omit | Privileged users may hit access-denied. | Align frontend route constants to backend role support after decision. | +| DD-09 | Breadcrumb labels are URL-derived. | Medium | `echo-breadcrumbs.component.ts` | Labels like product-studio and IDs are not user-friendly. | Add route metadata label map and entity title support. | +| DD-10 | Storybook assets use backend-hosted files and need deployed URL discipline. | Medium | `backend/storybook`, prior deployment issue | Broken images in Vercel if localhost leaks. | Asset URL helper contract and visual tests. | +| DD-11 | Dashboard data density is not role-prioritized. | High | student/teacher/admin dashboard components | Key actions compete with secondary metrics. | Dashboard hierarchy by daily tasks and alert priority. | +| DD-12 | Discussion/community UI is not clearly discoverable. | Medium | backend posts/threads APIs | Community mission is underrepresented. | Design moderated discussion hub before full exposure. | +| DD-13 | Form patterns vary across template-driven, reactive, and custom controls. | Medium | login, registration, course wizard, invites | Validation consistency suffers. | Component spec and phased migration. | +| DD-14 | Visual asset/brand source is unclear. | Medium | no logo asset found, only `EE` mark | Hard to preserve brand concept. | Locate/import brand asset before production visual replacement. | +| DD-15 | Implementation placeholder copy leaks into UX. | Medium | V2 collection route data says "Read-only", "later phase" | Users see roadmap instead of task guidance. | Convert to user-centered empty and unavailable states. | diff --git a/docs/ux-overhaul/design-principles.md b/docs/ux-overhaul/design-principles.md new file mode 100644 index 0000000..d716424 --- /dev/null +++ b/docs/ux-overhaul/design-principles.md @@ -0,0 +1,33 @@ +# Design Principles + +## 1. Learning First + +Every screen should answer: what can this user do next to support learning? Operational tools are valuable only when they clarify learner progress, content quality, or community support. + +## 2. Role Clarity + +Students, teachers, content admins, organization admins, and platform admins should not share the same navigation just because they share a shell. The product should name each space by the user's job. + +## 3. Cultural Grounding Without Decoration + +EchoEd's African and African-American history mission should show through content structure, source treatment, maps, historical imagery, language, and care for lineage. Avoid superficial motifs or generic SaaS decoration. + +## 4. Warm Scholarly Trust + +The interface should feel calm, credible, and welcoming: editorial but not academic bureaucracy, child-friendly but not juvenile. + +## 5. Evidence and Safety + +Content publishing, learner recommendations, and mastery claims should show evidence, caution flags, and safe next steps. + +## 6. Accessible by Default + +Readable contrast, keyboard access, explicit states, visible focus, touch target sizing, reduced-motion behavior, and screen-reader order are non-negotiable. + +## 7. Content Forward + +The course, lesson, source, discussion, and learner evidence are the product. Cards, shadows, gradients, and chrome must not compete with the educational material. + +## 8. Incremental Compatibility + +The design should wrap the existing auth, org, curriculum, progress, assignment, section, review, and analytics contracts. Any backend change must be separately justified. diff --git a/docs/ux-overhaul/design-qa-checklist.md b/docs/ux-overhaul/design-qa-checklist.md new file mode 100644 index 0000000..2f8c3e4 --- /dev/null +++ b/docs/ux-overhaul/design-qa-checklist.md @@ -0,0 +1,44 @@ +# Design QA Checklist + +## Before Implementation + +- [ ] Audit artifacts reviewed. +- [ ] Route inventory accepted. +- [ ] Role-capability matrix accepted. +- [ ] Backend change assessment accepted. +- [ ] Figma-ready package reviewed or imported. +- [ ] Design-lab prototype reviewed at 1440, 1280, 768, and 390 widths. + +## Per Screen + +- [ ] Role and user goal are clear. +- [ ] One primary action is obvious. +- [ ] Page title and description match route context. +- [ ] Loading, empty, error, permission, and success states exist. +- [ ] Forms have labels, hints, validation, and submit-pending state. +- [ ] Destructive actions require confirmation. +- [ ] Keyboard-only operation works. +- [ ] Screen-reader order is logical. +- [ ] Mobile layout has no overlap or clipped text. +- [ ] Status is not color-only. +- [ ] API dependencies are documented. +- [ ] Backend changes are explicitly classified as required, optional, or avoided. + +## Per Component + +- [ ] Uses semantic tokens. +- [ ] Has documented variants and states. +- [ ] Has accessible name/role/value. +- [ ] Has focus/hover/active/disabled/loading states. +- [ ] Has responsive behavior. +- [ ] Has component tests or Storybook coverage. + +## Release Readiness + +- [ ] `npm test -- --watch=false --browsers=ChromeHeadless` passes. +- [ ] `npm run build` passes. +- [ ] Playwright role-flow smoke tests pass for seeded demo. +- [ ] Visual regression screenshots reviewed. +- [ ] Contrast checks pass. +- [ ] No investor/commercial copy remains in visible UI. +- [ ] Deprecated routes/styles have a rollback plan. diff --git a/docs/ux-overhaul/design-tokens.md b/docs/ux-overhaul/design-tokens.md new file mode 100644 index 0000000..d8f5717 --- /dev/null +++ b/docs/ux-overhaul/design-tokens.md @@ -0,0 +1,44 @@ +# Design Tokens + +Machine-readable token files: + +- `frontend/src/styles/tokens/design-tokens.json` +- `frontend/src/styles/tokens/_design-tokens.scss` +- `frontend/src/styles/tokens/design-tokens.css` + +## Token Categories + +| Category | Examples | Purpose | +| --- | --- | --- | +| Primitive color | `color.primitive.palm.700` | Raw palette values. | +| Semantic color | `color.action.primary.background` | Component/system meaning. | +| Typography | `font.family.body`, `font.size.body.md` | Stable text hierarchy. | +| Spacing | `space.4`, `space.layout.page` | Layout rhythm. | +| Radius | `radius.control.default`, `radius.card.default` | Shape consistency. | +| Border | `border.width.default`, `color.border.subtle` | Surface distinction. | +| Elevation | `shadow.raised`, `shadow.overlay` | Depth without excess. | +| Motion | `motion.duration.fast`, `motion.easing.standard` | Predictable interaction. | +| Focus | `focus.ring.color`, `focus.ring.width` | Accessible focus. | + +## Color Roles + +| Role | Token | Usage | +| --- | --- | --- | +| Page background | `color.surface.page` | Main app background. | +| Surface | `color.surface.default` | Panels, cards, dialogs. | +| Raised surface | `color.surface.raised` | Headers, drawers, overlays. | +| Primary text | `color.text.default` | Body and headings. | +| Muted text | `color.text.muted` | Secondary metadata. | +| Primary action | `color.action.primary.*` | Main CTA and active nav. | +| Secondary action | `color.action.secondary.*` | Secondary buttons. | +| Success | `color.status.success.*` | Completed, published, active. | +| Warning | `color.status.warning.*` | Needs review, pending, caution. | +| Danger | `color.status.danger.*` | Errors/destructive. | +| Info | `color.status.info.*` | Neutral guidance, links. | + +## Accessibility Notes + +- Do not use token pairs unless documented as AA-compliant. +- Status badges must include text labels. +- Focus ring must be visible on dark and light surfaces. +- Minimum touch control height: 44px. diff --git a/docs/ux-overhaul/information-architecture.md b/docs/ux-overhaul/information-architecture.md new file mode 100644 index 0000000..96a58e7 --- /dev/null +++ b/docs/ux-overhaul/information-architecture.md @@ -0,0 +1,41 @@ +# Information Architecture + +## IA Principles + +- Start from role intent, not internal product modules. +- Keep learners in a simple Learn space. +- Keep educators in a Teach space focused on classes, assignments, learner support, and curriculum preview. +- Keep content operations in Studio. +- Keep org/user/platform administration in Admin. +- Preserve existing backend resources and introduce route aliases or frontend grouping incrementally. + +## Proposed Top-Level Spaces + +| Space | Primary users | Purpose | Existing routes reused | +| --- | --- | --- | --- | +| Learn | Student | Resume assigned learning, browse available learning, complete lessons, track achievements. | `/learn`, `/learn/products`, `/learn/paths`, `/learn/certificates`, `/learn/resources`, `/learn/lesson/:id`. | +| Teach | Teacher, instructor | Manage classes, assignments, learner support, curriculum preview. | `/home/sections`, `/home/sections/:id`, `/home/courses`, `/home/assessments/:id`, `/home/lesson/:id`, teacher dashboard logic. | +| Studio | Content admin, org admin, curriculum creator | Projects, sources, artifacts, product/course authoring, review center. | `/workspace/projects`, `/workspace/product-studio`, `/workspace/knowledge-sources`, `/workspace/artifacts`, `/workspace/review-center`, `/workspace/products`. | +| Organization | Org admin | Members, invites, access, org settings, classes overview. | `/workspace/settings/invites`, `/workspace/access`, `/home/org/invites`, `/home/sections`. | +| Admin | Admin, super admin | Users, courses, badges, reporting, moderation, platform settings. | `/home/admin/users`, `/home/admin/courses`, `/home/admin/badges`, `/workspace/analytics`. | +| Community | Authenticated roles | Discussions, shared resources, community contribution. | Existing posts/threads APIs, `/workspace/commercial` as temporary route alias. | + +## Contextual Navigation + +- Course/product detail: Overview, Content, Learners/Access, Review, Analytics, Settings. +- Class detail: Overview, Roster, Assignments, Progress, Discussion. +- Lesson player: Content, Activity, Notes, Progress; teacher preview adds Facilitation Notes. +- Admin user detail: Profile, Roles, Organizations, Activity, Danger Zone. + +## Default Landing Rule + +Suggested frontend-only default after bootstrap: + +1. Student-only users: `/learn`. +2. Teacher/instructor without content/admin role: `/teach` alias to current teacher dashboard/classes. +3. Content admin: `/studio`. +4. Org admin: `/organization`. +5. Admin/super admin: `/admin`. +6. Multi-role users: show role switcher with clear destinations and remember preferred mode using existing preferences. + +Initial implementation can preserve physical route paths while changing navigation labels and redirect decisions. diff --git a/docs/ux-overhaul/legacy-style-migration.md b/docs/ux-overhaul/legacy-style-migration.md new file mode 100644 index 0000000..d7e6db7 --- /dev/null +++ b/docs/ux-overhaul/legacy-style-migration.md @@ -0,0 +1,29 @@ +# Legacy Style Migration + +## Phase 1 Approach + +Production now imports `frontend/src/styles/tokens/design-tokens.css`. Global compatibility aliases in `frontend/src/styles.scss` map older `--echo-*`, `--echo-v2-*`, and draft `--ee-*` names to approved semantic token values where practical. + +This phase intentionally avoids rewriting every legacy page stylesheet. The new shell and shared primitives consume semantic `--ee-color-*`, `--ee-space-*`, `--ee-radius-*`, `--ee-shadow-*`, `--ee-motion-*`, and focus-ring tokens directly. + +## Temporary Aliases + +- `--echo-*`: retained for older dashboard and public page styles. +- `--echo-v2-*`: retained for existing workspace/V2 pages. +- `--ee-midnight`, `--ee-purple`, `--ee-azure`, and related draft aliases: retained for legacy V2 page styles, now backed by approved token values. +- `--ee-duration-*` and `--ee-easing-*`: retained for older pages, backed by approved motion tokens. + +## Remaining Legacy Patterns + +- Raw color values remain in older page-local SCSS and inline component styles outside the Phase 1 shell. +- Several older pages still use large rounded cards, gradients, and glass-like panels. +- Sass deprecation warnings remain in `frontend/src/styles/_typography.scss` for mixed declarations. +- Some V2 route labels remain in page internals; visible shell navigation has been renamed where safe. + +## Migration Rules + +1. Migrate page styles only when their screen enters the approved implementation phase. +2. Keep backend route names and model terminology unchanged. +3. Replace visible commercial/investor-facing labels only when the route can safely keep its technical path. +4. Prefer shared primitives before adding new page-local controls. +5. Remove compatibility aliases only after `rg` confirms no production consumers remain. diff --git a/docs/ux-overhaul/navigation-model.md b/docs/ux-overhaul/navigation-model.md new file mode 100644 index 0000000..3745714 --- /dev/null +++ b/docs/ux-overhaul/navigation-model.md @@ -0,0 +1,100 @@ +# Navigation Model + +## Global Shell + +- App mark and product name. +- Role/space switcher only when the user has multiple implemented spaces. +- Active organization selector. +- Search entry where supported. +- Notifications. +- Profile/settings menu. +- Skip link and landmark structure. + +## Student Navigation + +Primary: + +- Home +- Assignments +- Courses +- Progress +- Achievements +- Discussions +- Profile + +Mobile: + +- Bottom nav: Home, Assignments, Courses, Progress, Profile. +- Lesson player hides global nav and provides sticky Exit/Progress controls. + +## Teacher / Instructor Navigation + +Primary: + +- Today +- Classes +- Assignments +- Curriculum +- Learner Support +- Reports +- Discussions +- Settings + +Secondary examples: + +- Class detail tabs: Overview, Roster, Assignments, Progress, Discussion. +- Curriculum detail tabs: Overview, Lessons, Assessments, Teacher Notes. + +## Content Admin / Studio Navigation + +Primary: + +- Studio Home +- Projects +- Sources +- Artifacts +- Products +- Review +- Access +- Analytics + +Secondary examples: + +- Product detail tabs: Overview, Content, Review, Access, Analytics, History. +- Artifact detail tabs: Preview, Source, Review, Versions. + +## Organization Admin Navigation + +Primary: + +- Organization Home +- People +- Invites +- Classes +- Access +- Settings +- Reports + +## Admin Navigation + +Primary: + +- Admin Home +- Users +- Organizations +- Curriculum +- Badges +- Reports +- Moderation +- Assets +- Platform Settings + +Danger zones must be visually separated and require confirmation. + +## Navigation Anti-Patterns to Avoid + +- A single "Workspace OS" sidebar for all roles. +- Showing product-studio links to teachers whose immediate goal is class instruction. +- Putting essential workflows only under profile menus. +- Icon-only navigation without tooltip and visible active context. +- Duplicate route labels for the same domain. diff --git a/docs/ux-overhaul/personas-and-role-needs.md b/docs/ux-overhaul/personas-and-role-needs.md new file mode 100644 index 0000000..5a2a7c2 --- /dev/null +++ b/docs/ux-overhaul/personas-and-role-needs.md @@ -0,0 +1,95 @@ +# Personas and Role Needs + +## Student + +Status: implemented. + +- Responsibilities: sign in, find assigned learning, complete lessons/activities, track progress, view achievements, recover when interrupted. +- Top goals: know what to do next, feel safe and capable, complete a lesson without losing progress. +- Daily workflows: resume learning, finish a lesson, answer assessment questions, view progress and badges. +- Critical workflows: recover stale session, understand unavailable lesson, retry failed submit, ask for support through teacher/community channels when available. +- Technical comfort: mixed; K-5 learners may need low reading burden and clear visual hierarchy. +- Accessibility considerations: large targets, readable type, reduced cognitive load, audio/visual alternatives, clear focus. +- Information priorities: next lesson, why it matters, time/progress, support state, achievements. +- Dashboard priorities: primary "Continue learning", assigned work, progress, achievements, resources. +- Navigation: Learn, Assignments, Courses, Progress, Achievements, Discussions, Profile. +- Notifications: new assignment, feedback, badge earned, lesson unlocked/paused, teacher message. +- Dangerous/confusing actions: enrolling in duplicate courses, leaving lesson before save, assessment submit. +- Cross-role handoffs: teacher assigns/supports; admin/content controls availability; discussion moderation protects learners. + +## Teacher / Educator + +Status: implemented. + +- Responsibilities: orient to class priorities, manage classes/rosters, assign curriculum, monitor completion, provide support and feedback. +- Top goals: know which learners need help, assign the right lesson, see progress quickly. +- Daily workflows: check class dashboard, open class, review learners needing support, assign/resume lessons, review submissions. +- Critical workflows: create class, enroll learner, handle blocked lesson, interpret runtime recommendations, recover from failed assignment. +- Technical comfort: moderate; needs low-friction classroom operations. +- Accessibility considerations: keyboard table navigation, readable dense data, status not color-only. +- Information priorities: active classes, overdue/unstarted work, intervention recommendations, recent submissions. +- Dashboard priorities: today, learners needing support, upcoming lessons, assignment status. +- Navigation: Teach, Classes, Assignments, Curriculum, Progress, Discussions, Settings. +- Notifications: submitted work, learners needing reteach/review/enrichment, discussion flags, roster changes. +- Dangerous/confusing actions: deleting course, assigning wrong cohort, starting unavailable lesson. +- Cross-role handoffs: students complete work; content admins publish/approve curriculum; admins manage users/org. + +## Administrator + +Status: implemented. + +- Responsibilities: manage users, roles, courses, badges, organizations, reports, destructive actions. +- Top goals: maintain platform health, resolve access problems, preserve data integrity. +- Daily workflows: review metrics, manage users, inspect course readiness, resolve access/role issues. +- Critical workflows: delete/deactivate user, manage roles, review content governance, handle moderation. +- Technical comfort: moderate to high. +- Accessibility considerations: dense admin tables, confirmation clarity, keyboard filters/actions. +- Information priorities: system health, pending risks, user/course counts, governance issues. +- Dashboard priorities: alerts, recent activity, users, courses, governance checks. +- Navigation: Admin, Users, Organizations, Curriculum, Reports, Moderation, Assets, Settings. +- Notifications: failed org access, content blocked, user invite issue, flagged content, safe-publish failure. +- Dangerous/confusing actions: delete user/course, revoke access, publish unsafe content. +- Cross-role handoffs: supports teachers/content admins; manages org admins; protects learners. + +## Organization Administrator + +Status: implemented. + +- Responsibilities: invite members, manage organization context, oversee sections/classes, access grants. +- Top goals: keep the organization roster and permissions accurate. +- Daily workflows: manage invites, review sections/cohorts, handle access. +- Critical workflows: revoke/adjust membership, switch org, manage content admin access. +- Navigation: Organization, People, Classes, Access, Settings. + +## Content Admin / Curriculum Creator + +Status: implemented. + +- Responsibilities: author courses/products, manage sources/artifacts, review/publish content. +- Top goals: move content from source to reviewed learner-ready product. +- Daily workflows: open Studio, review queue, inspect products/artifacts, publish approved material. +- Critical workflows: safe publish, review status changes, source provenance, version management. +- Navigation: Studio, Projects, Sources, Artifacts, Review, Products, Analytics. + +## Instructor + +Status: partially implemented. + +- Responsibilities: manage sections/cohorts and support learners. +- Gap: no dedicated instructor-specific dashboard or route labels. + +## Parent / Guardian + +Status: partially implemented. + +- Evidence: backend `OrganizationRole.PARENT`; registration exposes `parent` and family org intent. +- Gap: no parent portal, child linking, progress visibility, or messaging. +- Recommendation: future Family Portal only after backend child relationship/access contracts are defined. + +## Super Administrator + +Status: partially implemented. + +- Evidence: backend super admin bypass and V2 creator role. +- Gap: frontend route constants omit super_admin from creator roles. +- Recommendation: align frontend route access after deciding if super admin should use Admin or internal Ops IA. diff --git a/docs/ux-overhaul/production-foundations-implementation.md b/docs/ux-overhaul/production-foundations-implementation.md new file mode 100644 index 0000000..4ff8271 --- /dev/null +++ b/docs/ux-overhaul/production-foundations-implementation.md @@ -0,0 +1,65 @@ +# Production Foundations Implementation + +Date: 2026-07-10 + +Scope: Phase 1 production foundations and application shell for `overhaul-role-based-ui-ux-experience`. This phase activates the approved tokens and shell patterns without redesigning the internal student, teacher, administrator, organization, Studio, or community pages. + +## Implemented + +- Imported `frontend/src/styles/tokens/design-tokens.css` from `frontend/src/styles.scss`. +- Reworked production compatibility aliases in `frontend/src/styles.scss` so legacy `--echo-*`, `--echo-v2-*`, and older `--ee-*` aliases resolve to approved semantic token values. +- Added `ShellNavigationService` for role-aware navigation and canonical role destinations. +- Migrated the authenticated shell frame through `HomeComponent`, `EchoHeaderComponent`, and `SidebarComponent`. +- Added mobile navigation with open/close control, Escape support, body scroll lock, overlay backdrop, and focus return to the trigger. +- Added shared primitives: + - `EchoConfirmationDialogComponent` + - `EchoSkeletonComponent` + - expanded `EchoStatePanelComponent` variants for `permission` and `success` +- Migrated the access-denied page to the shared permission state. +- Updated login ready-session routing to use the canonical destination returned by `ShellNavigationService`. + +## Role Navigation Mapping + +| Role | Primary space | Canonical route | Notes | +| --- | --- | --- | --- | +| `student` | Learn | `/learn` | Student login now lands on Learn. Existing `/home` links remain reachable. | +| `teacher` | Teach | `/home` | Uses existing courses, programs, sections, and learner-progress routes. | +| `instructor` | Teach | `/home` | Partial role mapped to teacher-compatible navigation only where current guards support it. | +| `content_admin` | Studio | `/workspace` | Commercial/product labels are replaced with education-oriented labels where route compatibility is preserved. | +| `org_admin` | Organization | `/workspace/learners` | Member-management link is not exposed because the current nested users route is admin-only. | +| `admin` | Admin | `/home` | Admin user/course/badge routes remain under existing guarded `/home/admin/**` paths. | +| `super_admin` | Admin | `/home` | Partial role receives only guard-compatible baseline admin overview until backend/frontend permissions explicitly support more routes. | +| `parent`, `viewer` | None | Existing fallback | No parent/viewer portal was added. | + +## Brand Asset + +`/mnt/data/logo_concept.webp` was not accessible from this environment (`Test-Path` returned false). No replacement logo was invented. The shell continues to use the existing neutral `EE` wordmark treatment, with brand usage documented as deferred until the asset is available in a repository-controlled path. + +## Accessibility Work + +- One skip link targets `#echoed-main-content`. +- Authenticated shell keeps one `main` landmark. +- Sidebar and header controls have explicit accessible names. +- Mobile menu state uses `aria-expanded` and Escape-to-close behavior. +- Confirmation dialog uses `role="dialog"`, `aria-modal`, labelled title/description, initial focus on Cancel, focus trap, Escape behavior, loading lockout, and focus restoration. +- Shared state panels use `status` or `alert` semantics depending on severity. +- New shell styles use visible tokenized focus rings and respect `prefers-reduced-motion`. + +## Verification + +- `cmd /c npm test -- --watch=false --browsers=ChromeHeadless`: 210 success. +- `cmd /c npm run build`: passed. Existing Sass mixed-declaration deprecation warnings remain in `frontend/src/styles/_typography.scss`. + +## Deviations + +- Native logo asset integration was skipped because `/mnt/data/logo_concept.webp` was not accessible. +- Organization Members navigation was not added because the only matching route, `/workspace/learners/users`, is guarded to `admin`. +- Internal dashboard/page content was intentionally not redesigned in this phase. + +## Deferred + +- Full control library migration for forms, data lists, tables, filters, and page-specific actions. +- Full role-specific dashboard and workflow redesigns. +- Connecting the shared confirmation dialog to every destructive action. +- Visual regression screenshot baselines for all role flows. +- Dedicated parent/viewer experiences. diff --git a/docs/ux-overhaul/production-route-migration.md b/docs/ux-overhaul/production-route-migration.md new file mode 100644 index 0000000..7cb8a89 --- /dev/null +++ b/docs/ux-overhaul/production-route-migration.md @@ -0,0 +1,34 @@ +# Production Route Migration + +Phase 1 preserves route compatibility and establishes canonical role destinations without deleting deep links. + +| Current route | Canonical route | Role | Redirect behavior | Guard behavior | Migration phase | Removal criteria | Deep-link risk | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `/home` | `/home` for teacher/admin, transitional for other roles | teacher, instructor, admin, super_admin-compatible | No redirect | `HomeSessionGuard`; child guards unchanged | Phase 1 | Only after all role dashboards have route-level replacements and analytics show low usage | High | +| `/learn` | `/learn` | student | Login routes students here after ready bootstrap | `HomeSessionGuard`; learner child routes unchanged | Phase 1 | None planned | Low | +| `/workspace` | `/workspace` | content_admin | No redirect | `HomeSessionGuard` plus existing role guards | Phase 1 | None planned | Medium | +| `/workspace/learners` | `/workspace/learners` | org_admin | No redirect | Existing creator-role guard | Phase 1 | Replace only if organization home becomes a dedicated route | Medium | +| `/workspace/commercial` | `/workspace/commercial` with visible label `Community` | admin/content_admin/org_admin/teacher/instructor via existing creator role set | No redirect | Existing creator-role guard | Phase 1 | Add alias and deprecation only after community surface is redesigned | Medium | +| `/home/admin/users` | `/home/admin/users` | admin | No redirect | Existing `RoleGuard` admin-only | Phase 1 | Dedicated Admin IA route exists and old path is aliased | High | +| `/home/admin/courses` | `/home/admin/courses` | admin | No redirect | Existing `RoleGuard` admin-only | Phase 1 | Dedicated Admin IA route exists and old path is aliased | High | +| `/home/admin/badges` | `/home/admin/badges` | admin | No redirect | Existing `RoleGuard` admin-only | Phase 1 | Dedicated Admin IA route exists and old path is aliased | High | +| `/home/sections` | `/home/sections` | teacher, instructor, org_admin | No redirect | Existing `RoleGuard` section roles | Phase 1 | Class/cohort IA aliases are implemented and smoke tested | High | +| `/home/courses` | `/home/courses` | teacher, instructor, student transitional | No redirect | Existing child route, no added guard | Phase 1 | Course library split is implemented and tested | Medium | +| `/home/programs` | `/home/programs` | teacher, instructor, student transitional | No redirect | Existing child route, no added guard | Phase 1 | Learning path route aliases are implemented and tested | Medium | +| `/home/me/preferences` | `/home/me/preferences` | all authenticated roles | No redirect | Existing authenticated shell | Phase 1 | Dedicated settings route aliases are implemented | Medium | + +## Canonical Login Destinations + +- `student`: `/learn` +- `teacher`: `/home` +- `instructor`: `/home` +- `content_admin`: `/workspace` +- `org_admin`: `/workspace/learners` +- `admin`: `/home` +- `super_admin`: `/home` + +## Route Compatibility Notes + +- Browser bookmarks are preserved; no broad route deletion was performed. +- Unauthorized routes remain protected by existing route guards. Hidden navigation is not treated as authorization. +- `/workspace/commercial` remains the technical path in this phase, but visible navigation now uses `Community`. diff --git a/docs/ux-overhaul/proposed-user-journeys.md b/docs/ux-overhaul/proposed-user-journeys.md new file mode 100644 index 0000000..854978f --- /dev/null +++ b/docs/ux-overhaul/proposed-user-journeys.md @@ -0,0 +1,96 @@ +# Proposed User Journeys + +## Student: Resume Learning + +```mermaid +flowchart TD + A[Sign in] --> B[Resolve role and active org] + B --> C[/learn] + C --> D[Next learning card] + D --> E{Assigned or self-selected?} + E -->|assigned| F[Open assignment context] + E -->|self-selected| G[Open course overview] + F --> H[Start/resume lesson] + G --> H + H --> I[Lesson player] + I --> J[Activity/assessment] + J --> K[Completion feedback] + K --> L[Progress and next recommendation] +``` + +Design requirements: next action first, lesson status visible, safe exit sticky on mobile, live progress feedback. + +## Student: Recover Interrupted Session + +```mermaid +flowchart TD + A[Open lesson route] --> B[Show restoring lesson status] + B --> C[Try segment restore] + C -->|success| D[Return to exact lesson] + C -->|stale| E[Find active learner course] + E -->|found| F[Explain recovery and continue] + E -->|not found| G[Return to Learn with retry] +``` + +Design requirements: do not show raw IDs, explain recovery in student-safe copy. + +## Teacher: Start Day + +```mermaid +flowchart TD + A[Sign in] --> B[/teach] + B --> C[Today's priorities] + C --> D[Learners needing support] + C --> E[Recent submissions] + C --> F[Upcoming assignments] + D --> G[Open class detail] + E --> H[Review work] + F --> I[Edit or assign learning] +``` + +Design requirements: class context visible; intervention recommendations linked to evidence and next teacher action. + +## Teacher: Assign Learning + +```mermaid +flowchart TD + A[Classes] --> B[Select class] + B --> C[Assignments tab] + C --> D[Create assignment] + D --> E[Choose curriculum item] + E --> F[Choose target learners] + F --> G[Set due/status] + G --> H[Review summary] + H --> I[Confirm assignment] +``` + +Design requirements: reuse existing sections/assignments APIs; no new backend contract required for initial guided UI. + +## Content Admin: Publish Content + +```mermaid +flowchart TD + A[Studio] --> B[Projects] + B --> C[Product detail] + C --> D[Review readiness] + D --> E{Safe to publish?} + E -->|yes| F[Publish confirmation] + E -->|no| G[Issue list with owners] + F --> H[Published product] +``` + +Design requirements: source provenance, review status, safe-publish issues, learner impact warnings. + +## Admin: Resolve Access Issue + +```mermaid +flowchart TD + A[Admin dashboard] --> B[Access alert] + B --> C[User detail] + C --> D[Org memberships] + D --> E[Adjust role or invite] + E --> F[Confirmation] + F --> G[Audit-friendly success] +``` + +Design requirements: destructive/privileged actions require confirmation and clear role definitions. diff --git a/docs/ux-overhaul/prototype-review-guide.md b/docs/ux-overhaul/prototype-review-guide.md new file mode 100644 index 0000000..22607df --- /dev/null +++ b/docs/ux-overhaul/prototype-review-guide.md @@ -0,0 +1,29 @@ +# Prototype Review Guide + +Prototype location: `frontend/design-lab/index.html`. + +## How to Review + +1. Open the static HTML file in a browser. +2. Review desktop around 1440px. +3. Review tablet around 768px. +4. Review mobile around 390px. +5. Navigate by the top prototype links and in-page role links. + +## Review Questions + +- Does each role have a clear starting point? +- Is the student next action obvious without reading a dashboard full of cards? +- Does the teacher view prioritize learner support and class work? +- Does the admin view separate risk from routine management? +- Does the visual direction feel warm, scholarly, culturally grounded, and not generic SaaS? +- Are there any investor/commercial terms left in visible prototype copy? +- Does mobile remain usable without overlapping content? +- Are focus indicators visible? + +## Known Prototype Limits + +- Static only; no Angular routing or backend calls. +- Does not prove production component implementation. +- Uses the current text "EE" mark because no standalone logo asset was found. +- Does not include every route; it demonstrates representative screens and shared states. diff --git a/docs/ux-overhaul/responsive-audit.md b/docs/ux-overhaul/responsive-audit.md new file mode 100644 index 0000000..d91bba8 --- /dev/null +++ b/docs/ux-overhaul/responsive-audit.md @@ -0,0 +1,41 @@ +# Responsive Audit + +Evidence: `HomeComponent.syncShellViewport()`, `home.component.scss`, `echo-sidebar`, page SCSS, tests in `home.component.spec.ts`, teacher/admin responsive specs. + +## Current Behavior + +- Sidebar collapses automatically below 1024px. +- Compact expanded sidebar acts as an overlay. +- Lesson mode hides header/sidebar and uses a dedicated content surface. +- Many `.ee-grid` patterns use `auto-fit` and `minmax`. +- Several specs verify compact shell width and responsive fallback markup. + +## Main Issues + +| Issue | Severity | Evidence | Recommended redesign | +| --- | --- | --- | --- | +| Desktop sidebar model dominates all roles. | High | Shared `HomeComponent` shell for `/home`, `/workspace`, `/learn`. | Role-specific desktop nav and learner mobile bottom nav. | +| Teacher/admin tables need consistent card/list fallbacks. | High | Teacher/admin specs mention responsive fallback markup, but no shared data-list spec. | Create responsive data list component. | +| Header org switcher hides on smaller widths. | Medium | `echo-header.component.html` uses `hidden lg:flex`. | Provide compact org/context switcher in profile drawer. | +| Deep routes need breadcrumbs/back behavior on mobile. | High | Breadcrumbs exist in header, hidden hierarchy in lesson mode. | Page header includes contextual back link and breadcrumb on non-lesson deep routes. | +| Touch targets vary by page-local styles. | Medium | Many custom SCSS files. | Tokenize control height: 40 desktop, 44 touch. | +| Dashboards overuse cards and grids. | Medium | Student/teacher/admin views. | Mobile task stack: next action, status, alerts, then secondary content. | + +## Breakpoint Strategy + +| Breakpoint | Width | Behavior | +| --- | --- | --- | +| Mobile | 390px target, 360px minimum | Single column, bottom nav for learners, top app bar, drawers for filters/secondary nav. | +| Tablet | 768px | Two-column where content allows, collapsible rail for staff, persistent page actions. | +| Small desktop | 1280px | Staff sidebar plus content max width, secondary nav tabs. | +| Desktop | 1440px | Full role nav, contextual panels, readable data density. | + +## Screen-Specific Responsive Priorities + +- Landing/login/registration: first viewport must show brand, action, and no clipped form fields. +- Student dashboard: next lesson remains first; achievements/progress below. +- Lesson player: content and activity controls remain in one column on mobile, with sticky safe exit. +- Teacher dashboard: class priorities and learner support before governance detail. +- Class detail: roster and assignments become tabs on mobile. +- Admin users: filters collapse into drawer; table becomes data list. +- Studio/review: queue filters become horizontal chips or drawer. diff --git a/docs/ux-overhaul/role-capability-matrix.md b/docs/ux-overhaul/role-capability-matrix.md new file mode 100644 index 0000000..6f047d5 --- /dev/null +++ b/docs/ux-overhaul/role-capability-matrix.md @@ -0,0 +1,61 @@ +# Role Capability Matrix + +Evidence: `backend/app/enum.py`, `backend/app/deps.py`, `backend/app/api/routes/*.py`, `frontend/src/app/services/permissions.service.ts`, `frontend/src/app/app.routes.ts`, `backend/app/seed_demo.py`. + +## Role Status + +| Role | Status | Current entry points | Primary capabilities | Gaps | +| --- | --- | --- | --- | --- | +| Student | Implemented | `/home`, `/learn` | Enroll, start course, continue governed lessons, submit assessments, view programs/certifications/badges/progress. | Two learner route families; no child-specific navigation model. | +| Teacher | Implemented | `/home`, `/workspace`, `/home/sections` | View courses/students, assign courses, manage sections, inspect classroom progress and runtime support. | Dashboard mixes course authoring, governance, reporting, and class management. | +| Admin | Implemented | `/home/admin/*`, `/workspace` | Manage users/courses/badges; view admin overview and governance states. | Needs confirmation flows and audit-sensitive UX. | +| Org admin | Implemented | `/workspace`, org invites, sections, studio courses | Manage org invites, sections, studio course authoring, workspace access. | No dedicated organization administration hub. | +| Content admin | Implemented | `/workspace`, studio courses, review center | Course/content authoring, review, artifacts, products, project pipeline. | Needs content-first IA; currently shares generic workspace nav. | +| Instructor | Partially implemented | `/workspace`, sections | Manage sections/cohorts and workspace access. | No distinct instructor dashboard or workflow copy. | +| Parent/guardian | Partially implemented | registration only; backend org role | Can register as parent and create family org intent. | No parent dashboard, learner visibility, or family workflows. | +| Viewer | Backend enum only | None verified | Enum exists. | No frontend routes or permissions. | +| Super admin | Partially implemented | backend privileged; inconsistent frontend | Backend org bypass and V2 creator role. | Frontend creator role constants omit `super_admin`; admin IA unclear. | + +## Capability Matrix + +| Capability | Student | Teacher | Instructor | Content admin | Org admin | Admin | Parent | Super admin | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Sign in / JWT session | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| Register account | Yes | Yes | Yes | No explicit option | No explicit option | No explicit option | Yes | No | +| Create organization | Family/personal intent | School intent | School intent | Via org admin routes if invited | Yes | Not primary | Family intent | Backend capable | +| Switch active org | If member | Yes | Yes | Yes | Yes | Yes | If member | Yes | +| Browse courses/products | Yes | Yes | Yes | Yes | Yes | Yes | Not dedicated | Yes | +| Enroll self | Yes | No | No | No | No | No | No | No | +| Start/continue governed lesson | Yes | Preview/demo | Preview/demo | Preview/demo | Preview/demo | Preview/demo | No | Preview/demo | +| Submit assessment | Yes | Preview only | Preview only | Preview only | Preview only | Preview only | No | Preview only | +| View own progress | Yes | No | No | No | No | No | Future | No | +| View class progress | No | Yes | Yes | Maybe via workspace | Yes | Yes | Future child visibility | Yes | +| Manage sections/classes | No | Yes | Yes | No | Yes | No unless admin route added | No | Yes | +| Assign courses | No | Yes | Likely | No | Possible via section context | Yes | No | Yes | +| Create/edit courses | No | Yes | No verified | Yes in studio | Yes in studio | Yes | No | Yes | +| Publish/review content | No | Readiness visible | No verified | Yes | Yes | Yes | No | Yes | +| Manage users | No | Student list only | Roster only | No | Invites only | Yes | No | Yes | +| Manage badges | No | No | No | No | No | Yes | No | Yes | +| Manage access grants | No | Yes | Yes | Yes | Yes | Yes | No | Yes | +| Discussion/community | API exists | API exists | API exists | API exists | API exists | API exists | Future | API exists | + +## Critical Permission Evidence + +- `PermissionsService.buildPermissions()` grants workspace navigation to admin, teacher, content_admin, org_admin, and instructor. +- `RoleGuard` checks `PermissionsService.hasAnyRole()`, combining JWT role and active organization role. +- Backend `require_roles()` checks global user role. +- Backend `require_org_roles()` checks active org membership and allows super admin bypass where implemented. +- `backend/app/api/routes/v2_platform.py` defines `CREATOR_ROLES = {"admin", "teacher", "content_admin", "org_admin", "instructor", "super_admin"}` while frontend `creatorRoles` excludes `super_admin`. + +## Design Recommendation + +Use role-aware entry surfaces, not one shared workspace: + +- Student: Learn. +- Teacher/instructor: Teach. +- Content admin: Studio. +- Org admin: Organization. +- Admin/super admin: Admin. +- Parent: Future Family Portal until implemented. + +Keep backend role strings unchanged. Add frontend IA grouping over existing routes first. diff --git a/docs/ux-overhaul/route-and-screen-inventory.md b/docs/ux-overhaul/route-and-screen-inventory.md new file mode 100644 index 0000000..4051eea --- /dev/null +++ b/docs/ux-overhaul/route-and-screen-inventory.md @@ -0,0 +1,103 @@ +# Route and Screen Inventory + +Evidence: `frontend/src/app/app.routes.ts`, guards in `frontend/src/app/guards`, services in `frontend/src/app/services`, backend route modules in `backend/app/api/routes`. + +## Public Routes + +| Route | Component | Role access | User goal | Main API dependencies | UX problems | +| --- | --- | --- | --- | --- | --- | +| `/` | `LandingComponent` | Public | Understand EchoEd and enter auth/product discovery | None direct | Must reflect community project, not investor positioning. | +| `/products` | `PublicProductsComponent` | Public | Browse published products | `V2PlatformService.getPublicProducts()` -> `/api/public/products` | Product/course terminology competes with course catalog. | +| `/products/:slug` | `PublicProductDetailComponent` | Public | Inspect public product | `/api/public/products/{slug}` | Needs clear conversion to login/register or learner access. | +| `/login` | `LoginComponent` | Public | Sign in | `/api/auth/token`, `/api/orgs` through bootstrap | Error handling exists; destination can be role-confusing. | +| `/registration` | `RegistrationComponent` | Public | Create account and optional org setup | `/api/auth/register`, `/api/meta/enums` | Supports parent/instructor but lacks role-specific expectations. | +| `/onboarding/organization` | `OnboardingOrganizationComponent` | Authenticated onboarding | Create org after registration | `/api/orgs`, `/api/orgs/{id}/switch` | Required when org context missing; needs clearer role-specific copy. | +| `/access-denied` | `AccessDeniedComponent` | Public/auth | Recover from permission failure | None direct | Needs useful next action by role. | +| `**` | Redirect | Public | Recover from unknown route | None | Redirects to landing instead of contextual 404. | + +## Authenticated Shell Routes + +| Route family | Component shell | Guard | Notes | +| --- | --- | --- | --- | +| `/home/**` | `HomeComponent` | `HomeSessionGuard`; child `RoleGuard` where needed | Legacy role dashboard and curriculum routes. | +| `/workspace/**` | `HomeComponent` | `HomeSessionGuard` + creator role guards | V2 content/product/community workspace. | +| `/learn/**` | `HomeComponent` | `HomeSessionGuard` | Learner portal route family. | + +## `/home` Routes + +| Route | Component | Role access | User goal | API dependencies | UX problems | +| --- | --- | --- | --- | --- | --- | +| `/home` | `UserDashboardComponent` + `EchoedRoleSelectorComponent` | Authenticated | Select/resolve role dashboard | Session/org bootstrap | Role selector can become an unnecessary landing step. | +| `/home/courses` | `AvailableCoursesComponent` | Authenticated | Browse courses | `/api/courses`, `/api/enroll` | Mixes learner catalog with staff course concepts. | +| `/home/courses/new` | `CourseWizardComponent` | admin, teacher | Create course | `/api/courses`, `/api/upload/*`, course version routes | Should move to Teach/Admin or Studio IA. | +| `/home/courses/:courseId/edit` | `CourseWizardComponent` | admin, teacher | Edit course | `/api/courses/{id}` | Needs safe-publish/version state in page header. | +| `/home/programs` | `ProgramsComponent` | Authenticated | View/enroll pathways | `/api/programs`, `/api/programs/{id}/enroll` | Role behavior varies but route is shared. | +| `/home/assessments/:id` | `AssessmentDetailComponent` | Authenticated, submit student | Complete assessment | `/api/assessments/{id}`, attempts | Needs role-aware preview vs student submission mode. | +| `/home/certifications` | `CertificationsComponent` | Authenticated | View certifications | `/api/certifications`, `/api/students/me/certifications` | Needs clear student vs staff distinction. | +| `/home/org/invites` | `OrgInvitesComponent` | org_admin, content_admin | Invite org members | `/api/orgs/{orgId}/invites`, `/api/invites/accept` | Needs role descriptions and invite status handling. | +| `/home/studio/courses` | `StudioCoursesComponent` | content_admin, org_admin | Manage course versions | `/api/courses/authoring`, versions | Overlaps `/workspace/product-studio/courses`. | +| `/home/sections` | `SectionsComponent` | teacher, org_admin, instructor | Manage classes | `/api/sections` | Label should be "Classes" for K-5 teachers, "Sections" as secondary. | +| `/home/sections/:id` | `SectionDetailComponent` | teacher, org_admin, instructor | Manage roster/assignments | `/api/sections/{id}/roster`, `/api/sections/{id}/assignments` | Needs clearer assignment workflow. | +| `/home/me/preferences` | `PreferencesComponent` | Authenticated | Manage profile/preferences | `/api/me/preferences` | Should be reachable from all shells with consistent route. | +| `/home/admin/courses` | `AdminCoursesComponent` | admin | Manage courses | `/api/courses` | Overlaps staff and Studio course surfaces. | +| `/home/admin/badges` | `AdminBadgesComponent` | admin | Manage badges | `/api/badges`, `/api/upload/badge` | Needs asset guidance and destructive confirmation. | +| `/home/admin/users` | `AdminUsersComponent` | admin | Manage users | `/api/users`, `/api/users/{id}` | Needs filters, role management, confirmation. | +| `/home/lesson/:id` | `LessonViewComponent` | Authenticated | View governed lesson | `/api/progress/segment`, `/api/lessons/{id}`, `/api/progress/segment/complete` | Shared with learner flow; exit destination should match entry shell. | + +## `/workspace` Routes + +| Route | Component | Role access | User goal | API dependencies | UX problems | +| --- | --- | --- | --- | --- | --- | +| `/workspace` | `WorkspaceDashboardComponent` | admin, teacher, content_admin, org_admin, instructor | Orient to workspace operations | V2 analytics and workspace APIs | Too broad for every creator role. | +| `/workspace/projects` | `V2CollectionPageComponent` | creator roles | View project shells | `/api/projects` | Empty/read-only language is implementation-first. | +| `/workspace/projects/:projectId` | `ProjectDetailComponent` | creator roles | Inspect project pipeline | `/api/projects/{id}`, project collections | Needs task tabs and breadcrumbs. | +| `/workspace/product-studio` | `ProductStudioComponent` | creator roles | Create project/product/source/artifact shells | `/api/projects`, `/api/products`, `/api/knowledge-sources`, `/api/artifacts` | Many operations in one large form surface. | +| `/workspace/product-studio/create` | `ProductStudioComponent` | creator roles | Create product | Same as above | Duplicate destination. | +| `/workspace/product-studio/generation-runs` | `V2CollectionPageComponent` | creator roles | View generation attempts | `/api/generation-runs` | Read-only placeholder needs clearer future-state framing. | +| `/workspace/product-studio/generation-runs/:generationRunId` | `GenerationRunDetailComponent` | creator roles | Inspect generation run | `/api/generation-runs/{id}` | Needs logs/status structure. | +| `/workspace/product-studio/courses` | `StudioCoursesComponent` | content_admin, org_admin | Author course versions | `/api/courses/authoring`, versions | Duplicates `/home/studio/courses`. | +| `/workspace/product-studio/courses/new` | `CourseWizardComponent` | admin, teacher | Create course | `/api/courses` | Role mismatch with studioRoles. | +| `/workspace/product-studio/courses/:courseId/edit` | `CourseWizardComponent` | admin, teacher | Edit course | `/api/courses/{id}` | Needs consistent course authoring role model. | +| `/workspace/products` | `V2CollectionPageComponent` | creator roles | Manage products | `/api/products` | Product vs course relationship needs explicit labels. | +| `/workspace/products/:productId` | `ProductDetailComponent` | creator roles | Inspect/publish product | `/api/products/{id}`, publish/review/status | Good candidate for contextual secondary nav. | +| `/workspace/products/manage` | `AdminCoursesComponent` | admin | Manage courses | `/api/courses` | Route order may conflict with `products/:productId`; should be reviewed. | +| `/workspace/knowledge-sources` | `V2CollectionPageComponent` | creator roles | Manage sources | `/api/knowledge-sources` | Source ingestion not fully implemented. | +| `/workspace/artifacts` | `V2CollectionPageComponent` | creator roles | Manage artifacts | `/api/artifacts` | Needs artifact type filters. | +| `/workspace/artifacts/:artifactId` | `ArtifactDetailComponent` | creator roles | Inspect artifact | `/api/artifacts/{id}` | Needs review and source provenance layout. | +| `/workspace/review-center` | `ReviewCenterComponent` | creator roles | Review products/artifacts | `/api/review-center`, review-status patches | Good domain but nav label should be visible to content roles first. | +| `/workspace/access` | `AccessGrantsComponent` | creator roles | Manage learner access | `/api/access-grants` | Must avoid marketplace/commercial framing. | +| `/workspace/learners` | `UserDashboardComponent` | creator roles | Open learner management hub | Mixed `/home` child components | Reuses learner dashboard shell inside workspace; IA drift. | +| `/workspace/learners/products` | `AvailableCoursesComponent` | creator roles | View products/courses | `/api/courses` | Learner label with staff permissions is confusing. | +| `/workspace/learners/paths` | `ProgramsComponent` | creator roles | View paths | `/api/programs` | Needs staff vs learner mode. | +| `/workspace/learners/certificates` | `CertificationsComponent` | creator roles | View certificates | `/api/certifications` | Needs reporting view. | +| `/workspace/learners/users` | `AdminUsersComponent` | admin | Manage users | `/api/users` | Duplicates admin users. | +| `/workspace/learners/cohorts` | `SectionsComponent` | teacher, org_admin, instructor | Manage cohorts/classes | `/api/sections` | Label mismatch with sections. | +| `/workspace/learners/cohorts/:id` | `SectionDetailComponent` | teacher, org_admin, instructor | Manage cohort detail | `/api/sections/{id}/roster`, assignments | Should be primary Teacher IA. | +| `/workspace/analytics` | `WorkspaceAnalyticsComponent` | creator roles | View workspace analytics | `/api/analytics/workspace`, products, learners, knowledge-pipeline | Needs role-specific summaries. | +| `/workspace/commercial` | `CommercialDashboardComponent` | creator roles | Community/operations | likely V2 platform data | Component/route retains commercial wording. | +| `/workspace/demo-readiness` | `DemoReadinessComponent` | creator roles | Demo guide | Demo data APIs | Internal readiness route should be dev/demo only. | +| `/workspace/settings` | `PreferencesComponent` | creator roles | Settings | `/api/me/preferences` | Needs org settings separation. | +| `/workspace/settings/invites` | `OrgInvitesComponent` | org_admin, content_admin | Invite members | invites APIs | Should be under Admin/Org. | +| `/workspace/settings/badges` | `AdminBadgesComponent` | admin | Manage badges | badge APIs | Admin only but nested in workspace settings. | +| `/workspace/lesson/:id` | `LessonViewComponent` | Authenticated | Staff lesson preview | lesson/progress APIs | Preview and governed learner delivery should be explicit modes. | + +## `/learn` Routes + +| Route | Component | Role access | User goal | API dependencies | UX problems | +| --- | --- | --- | --- | --- | --- | +| `/learn` | `LearnerPortalComponent` | Authenticated | Resume learner journey | `/api/learner-portal/products`, progress APIs | Best candidate for student default. | +| `/learn/products` | `LearnerProductsComponent` | Authenticated | Browse available learner products | `/api/learner-portal/products` | Needs assigned vs available split. | +| `/learn/paths` | `ProgramsComponent` | Authenticated | View learning paths | `/api/programs` | Shared component needs learner presentation. | +| `/learn/certificates` | `CertificationsComponent` | Authenticated | View certificates | certification APIs | Needs child-friendly achievements framing. | +| `/learn/resources` | `LearnerResourcesComponent` | Authenticated | Access supporting resources | V2 product/resource APIs | Needs search/filter and source safety guidance. | +| `/learn/lesson/:id` | `LessonViewComponent` | Authenticated | Complete lesson | progress + lesson APIs | Should be canonical student lesson route. | + +## Duplicate Pattern Register + +| Domain | Duplicate routes/components | Proposed resolution | +| --- | --- | --- | +| Student learning | `/home`, `/home/courses`, `/home/lesson/:id`, `/learn/**` | Make `/learn` canonical for students; keep `/home` as compatibility redirect during implementation. | +| Course authoring | `/home/courses/new`, `/home/admin/courses`, `/home/studio/courses`, `/workspace/product-studio/courses` | Place authoring under Studio for content roles and Teach for teachers; admin sees governance summaries. | +| Sections/classes | `/home/sections`, `/workspace/learners/cohorts` | Teacher IA label "Classes"; retain section API names. | +| User management | `/home/admin/users`, `/workspace/learners/users` | Admin IA primary route; staff roster views remain class-scoped. | +| Settings | `/home/me/preferences`, `/workspace/settings` | Global profile route plus role-specific org/admin settings. | diff --git a/docs/ux-overhaul/screen-specifications.md b/docs/ux-overhaul/screen-specifications.md new file mode 100644 index 0000000..74ca468 --- /dev/null +++ b/docs/ux-overhaul/screen-specifications.md @@ -0,0 +1,11 @@ +# Screen Specifications + +The detailed specifications are split by role: + +- `docs/ux-overhaul/screens/public.md` +- `docs/ux-overhaul/screens/student.md` +- `docs/ux-overhaul/screens/teacher.md` +- `docs/ux-overhaul/screens/admin.md` +- `docs/ux-overhaul/screens/shared.md` + +Each screen spec includes user goal, layout, state, accessibility, API, and backend-change notes. Production implementation must not start until these specs and the OpenSpec proposal are approved. diff --git a/docs/ux-overhaul/screens/admin.md b/docs/ux-overhaul/screens/admin.md new file mode 100644 index 0000000..34682c8 --- /dev/null +++ b/docs/ux-overhaul/screens/admin.md @@ -0,0 +1,73 @@ +# Administrator Screen Specifications + +## Admin Dashboard + +- Current: `AdminViewComponent`. +- Goal: understand platform health and risks. +- API: `/api/analytics/overview`, `/api/users`, `/api/courses`, governance summary, usage stats service. +- Layout: alerts, metrics, governance issues, recent users/courses, quick links. +- Backend changes: none. + +## User Management + +- Route/component: `/home/admin/users`, `AdminUsersComponent`. +- Goal: find, edit, deactivate/delete users. +- API: `/api/users`, `/api/users/{id}`. +- Desktop: searchable table with filters. +- Mobile: data list. +- Confirmation: required for delete/role changes. +- Backend changes: optional deactivate vs delete if not supported. + +## Role Management + +- Current: roles are user role and org membership role. +- Goal: safely adjust platform/org role. +- API: `/api/users/{id}`, org membership/invite APIs. +- Backend changes: optional dedicated role audit endpoint. + +## Organization Management + +- Current: `/api/orgs`, invites, active org switch. +- Goal: manage organizations and memberships. +- UI: organization list, detail, members, invites, settings. +- Backend changes: optional admin org list/detail if super admin needs all orgs. + +## Curriculum / Course Management + +- Route/component: `/home/admin/courses`, `AdminCoursesComponent`. +- API: `/api/courses`, governance endpoints. +- Goal: manage course lifecycle and safety. +- Confirmation: delete/archive/publish actions require dialog. +- Backend changes: none for current management; archive preferable if supported later. + +## Reporting + +- Current: analytics routes. +- Goal: inspect student, classroom, product, and platform reports. +- API: `/api/analytics/*`. +- Layout: filters, summary cards, accessible charts, export if supported. +- Backend changes: optional exports. + +## Moderation + +- Current: review center and posts/threads APIs. +- Goal: handle flagged content/discussions. +- Backend changes: likely required if flag/moderation states are not implemented. + +## Uploads / Assets + +- Current: badge/coloring/storybook upload endpoints and backend file folders. +- Goal: manage media safely. +- API: `/api/upload/*`. +- Backend changes: optional asset library/list/delete endpoints. + +## Platform Settings + +- Current: preferences and org settings only. +- Goal: configure app-level settings where supported. +- Backend changes: required only for new configurable settings. + +## Audit-Sensitive Confirmation Flows + +- Applies to: delete user, delete course, revoke access, publish product, change role. +- Requirements: object name, impact, irreversible/undo copy, typed confirmation for high-risk operations, success/failure record. diff --git a/docs/ux-overhaul/screens/public.md b/docs/ux-overhaul/screens/public.md new file mode 100644 index 0000000..5fef32e --- /dev/null +++ b/docs/ux-overhaul/screens/public.md @@ -0,0 +1,65 @@ +# Public Screen Specifications + +## Landing Page + +- Role: public, contributor, educator, family. +- Goal: understand EchoEd's mission and enter the right path. +- Route/component: `/`, `LandingComponent`. +- Main action: sign in or explore public learning products. +- Layout: first viewport shows EchoEd identity, mission, public product entry, community project signal; no investor language. +- Mobile: brand, mission, primary action, secondary product link. +- States: public product loading may be deferred to product pages. +- API: none required. +- Backend changes: none. +- Analytics: landing CTA click, public products click, login click. + +## Public Products + +- Route/component: `/products`, `PublicProductsComponent`. +- Goal: browse published learning products. +- Actions: filter/search, open product, sign in/register. +- API: `/api/public/products`. +- Empty: "No public learning products are available yet." +- Error: retry with nontechnical copy. +- Accessibility: product cards need headings and status labels. + +## Public Product Detail + +- Route/component: `/products/:slug`, `PublicProductDetailComponent`. +- Goal: inspect a public product/course package. +- API: `/api/public/products/{slug}`. +- Layout: title, audience, description, learning outcomes, source/provenance, access action. +- Backend changes: none unless source/provenance fields are missing for desired content depth. + +## Login + +- Route/component: `/login`, `LoginComponent`. +- Goal: sign in and route to correct role space. +- API: `/api/auth/token`, then session bootstrap `/api/orgs`. +- States: submitting, invalid credentials, bootstrap failure, onboarding required. +- Validation: username/password required. +- Accessibility: show/hide password button has accessible name; errors linked to form. +- Backend changes: none. + +## Registration + +- Route/component: `/registration`, `RegistrationComponent`. +- Goal: create account and optionally begin organization setup. +- API: `/api/meta/enums`, `/api/auth/register`. +- States: loading roles, enum fallback, password mismatch, registration failed. +- Role treatment: student, teacher, parent, instructor are exposed; parent/instructor support must set expectation. +- Backend changes: none for current registration; parent portal would require future backend contracts. + +## Organization Onboarding + +- Route/component: `/onboarding/organization`, `OnboardingOrganizationComponent`. +- Goal: create/switch organization after account creation. +- API: `/api/orgs`, `/api/orgs/{id}/switch`. +- States: prefilled pending setup, submit pending, failure preserves input. +- Accessibility: clear required fields, role-specific organization type explanation. + +## Error and Not Found + +- Current: `AccessDeniedComponent` and wildcard redirect. +- Proposed: add contextual not-found view later. +- Backend changes: none. diff --git a/docs/ux-overhaul/screens/shared.md b/docs/ux-overhaul/screens/shared.md new file mode 100644 index 0000000..a8e172d --- /dev/null +++ b/docs/ux-overhaul/screens/shared.md @@ -0,0 +1,47 @@ +# Shared Screen Specifications + +## Application Shell + +- Role: all authenticated roles. +- Goal: provide correct navigation and org/user context. +- API: session token, `/api/orgs`, preferences. +- States: session loading, org loading, org switch pending/error/success, permission denied. +- Accessibility: skip link, landmarks, visible focus, keyboard profile menu. +- Backend changes: none. + +## Empty State + +- Components: `EchoStatePanelComponent` target. +- Required fields: eyebrow optional, title, explanation, primary action, secondary action optional. +- Variants: learner no assignments, teacher no classes, admin no results, studio no artifacts. + +## Loading State + +- Components: `EchoLoadingStateComponent`, skeleton variants. +- Behavior: preserve page structure where known; use status semantics. + +## Error State + +- Required: what failed, impact, retry action, support path if persistent. +- No raw backend traces. + +## Permission Denied + +- Required: current role/org context, missing access explanation, profile/org switch action, back action. + +## Search and Filter + +- Shared across public product catalog, curriculum library, rosters, users, review queues. +- Mobile filters use drawer or stacked chips. + +## Notifications + +- Proposed, not currently fully implemented. +- Types: assignment, feedback, content review, access/invite, discussion moderation, system. +- Backend changes: required only when real persistent notifications are implemented. + +## Profile and Preferences + +- Route/component: `PreferencesComponent`. +- Requirements: display name, preferences, accessibility settings, preferred role/space if multi-role. +- Backend changes: optional preference fields for preferred landing space. diff --git a/docs/ux-overhaul/screens/student.md b/docs/ux-overhaul/screens/student.md new file mode 100644 index 0000000..fe2fbec --- /dev/null +++ b/docs/ux-overhaul/screens/student.md @@ -0,0 +1,81 @@ +# Student Screen Specifications + +## Student Dashboard / Learn Home + +- Route/component: proposed canonical `/learn`, current `LearnerPortalComponent` and `StudentViewComponent`. +- Goal: know what to do next. +- Main action: continue assigned/current lesson. +- Information order: next learning, assignments, progress, achievements, available courses, resources. +- Desktop: two-column with next action and progress side panel. +- Mobile: single-column; next action first; bottom nav. +- API: `/api/student-courses`, `/api/analytics/student-progress`, `/api/students/{id}/badges`, `/api/programs`, `/api/students/me/certifications`, `/api/learner-portal/products`. +- States: loading dashboard, no assigned learning, all complete, partial API failures, permission denied. +- Backend changes: none. + +## Course Library / Available Learning + +- Routes: `/learn/products`, `/home/courses`. +- Goal: browse available learning. +- Actions: search/filter, open course, enroll/start. +- API: `/api/courses`, `/api/learner-portal/products`, `/api/enroll`. +- Empty: explain no available courses. +- Error: retry. +- Accessibility: card headings, status text, no color-only progress. + +## Course Overview + +- Current: course details through `AvailableCoursesComponent` and course models. +- Goal: understand course structure before starting. +- Layout: overview, units, lessons, estimated time, progress, source/cultural context. +- API: `/api/courses/{id}`, `/api/start-course`. +- Backend changes: optional if estimated time/source context is not available. + +## Unit Overview + +- Current: implicit in course/lesson data. +- Goal: understand lesson sequence and unlock/progress. +- API: `/api/courses/{id}`, progress data. +- Backend changes: none for basic structure. + +## Lesson Player + +- Route/component: `/learn/lesson/:id` or `/home/lesson/:id`, `LessonViewComponent`. +- Goal: complete lesson safely. +- Main action: complete lesson segment. +- Secondary actions: exit, retry load, view activity, teacher feedback if returned. +- API: `/api/progress/segment`, `/api/lessons/{id}`, `/api/progress/segment/complete`. +- States: resolving segment, governed unavailable, pending review, completed, stale segment recovery, generic error. +- Desktop: content column, progress/lesson outline side panel. +- Mobile: single-column, sticky action bar, safe exit. +- Accessibility: live region for save/next segment, heading order, keyboard activity controls. +- Backend changes: none. + +## Activity and Assessment + +- Route/component: `/home/assessments/:id`, `AssessmentDetailComponent`; activities in `LessonViewerComponent`. +- Goal: answer and submit work. +- API: `/api/assessments/{id}`, `/api/assessments/{id}/attempts`. +- States: unavailable, loading, submit pending, submit failed, completed feedback. +- Accessibility: form labels, grouped options, error association. + +## Progress and Achievements + +- Current components: student dashboard, certifications, badges. +- Goal: see growth and earned recognition. +- API: `/api/analytics/student-progress`, `/api/students/{id}/badges`, `/api/students/me/certifications`. +- Layout: progress summary, course progress, badges, certificates, timeline. +- Backend changes: none. + +## Discussions + +- Current: backend posts/threads APIs; no clear student discussion screen verified. +- Proposed: moderated class/course discussion. +- API: `/api/threads`, `/api/posts`. +- Backend changes: optional moderation/flagging if not present. + +## Profile and Settings + +- Route/component: `/home/me/preferences`, `PreferencesComponent`. +- Goal: preferences and profile. +- API: `/api/me/preferences`. +- Backend changes: none. diff --git a/docs/ux-overhaul/screens/teacher.md b/docs/ux-overhaul/screens/teacher.md new file mode 100644 index 0000000..fcd92ce --- /dev/null +++ b/docs/ux-overhaul/screens/teacher.md @@ -0,0 +1,72 @@ +# Teacher Screen Specifications + +## Teacher Dashboard / Today + +- Current: `TeacherViewComponent`. +- Goal: orient to current class priorities. +- Main action: open learners needing support or recent submissions. +- API: `/api/courses`, `/api/users/students`, `/api/analytics/teacher-summary`, runtime support/governance endpoints. +- Layout: today priorities, class cards, learner support, recent submissions, curriculum quick links. +- Mobile: priorities first, tabs for support/classes/curriculum. +- Backend changes: none. + +## Sections / Classes + +- Routes/components: `/home/sections`, `/workspace/learners/cohorts`, `SectionsComponent`. +- Goal: create/manage class. +- API: `/api/sections`. +- Layout: class list with roster count, active assignments, mode, recent activity. +- Empty: create first class. +- Backend changes: none. + +## Class Detail + +- Route/component: `/home/sections/:id`, `SectionDetailComponent`. +- Goal: manage roster, assignments, progress. +- API: `/api/sections/{id}/roster`, `/api/sections/{id}/assignments`, `/api/sections/{id}/analytics/summary`. +- Tabs: Overview, Roster, Assignments, Progress, Discussion. +- Mobile: tabs become segmented control. +- Backend changes: none for existing roster/assignment; optional for richer learner detail. + +## Curriculum Library and Course Preview + +- Routes/components: `/home/courses`, course detail/wizard preview. +- Goal: find curriculum and preview before assigning. +- API: `/api/courses`, `/api/courses/{id}`, governance summary. +- Layout: filters by grade/topic/status, course cards, preview drawer. +- Backend changes: optional search/filter endpoints later. + +## Assignment Creation + +- Current: section assignments API; UI in section detail. +- Goal: assign learning to class or learners. +- API: `/api/sections/{id}/assignments`, `/api/assign-course`. +- Flow: choose content, choose learners, due date/status, review, confirm. +- Validation: required class/content/target. +- Backend changes: none for basic assignment. + +## Learner Progress and Student Detail + +- Current: teacher summary and runtime support. +- Goal: identify and support learners. +- API: `/api/analytics/teacher-summary`, educator runtime support, student course/progress endpoints where available. +- Layout: support states, evidence basis, recent activity, next action. +- Backend changes: optional student detail aggregation endpoint. + +## Review and Feedback + +- Current: assessment attempts exist; explicit review UI unclear. +- Proposed: submissions queue and feedback panel. +- API: assessments/assignments submission routes. +- Backend changes: optional if feedback persistence is incomplete. + +## Discussion Moderation + +- Current: posts/threads APIs. +- Proposed: class discussion tab with teacher moderation. +- Backend changes: optional moderation flags if not present. + +## Teacher Settings + +- Route/component: preferences. +- API: `/api/me/preferences`. diff --git a/docs/ux-overhaul/shared-component-status.md b/docs/ux-overhaul/shared-component-status.md new file mode 100644 index 0000000..91af75b --- /dev/null +++ b/docs/ux-overhaul/shared-component-status.md @@ -0,0 +1,35 @@ +# Shared Component Status + +## Added In Phase 1 + +| Component | Path | Status | Notes | +| --- | --- | --- | --- | +| Shell navigation service | `frontend/src/app/services/shell-navigation.service.ts` | Production active | Centralizes role-to-navigation and canonical route logic using existing permissions. | +| Confirmation dialog | `frontend/src/app/components/echo-confirmation-dialog/` | Available, not broadly connected | Supports default, destructive, and publish variants; focus trap and Escape behavior covered by unit tests. | +| Skeleton | `frontend/src/app/components/echo-skeleton/` | Available | Tokenized primitive for later page migrations. | + +## Migrated Or Extended + +| Component | Path | Status | Notes | +| --- | --- | --- | --- | +| Authenticated shell | `frontend/src/app/pages/home/` | Production active | Adds skip link, role-aware mobile navigation, overlay, scroll lock, and focus return. | +| Header | `frontend/src/app/components/echo-header/` | Production active | Uses role-aware shell titles and shared state panels for organization states. | +| Sidebar | `frontend/src/app/components/echo-sidebar/` | Production active | Uses role-aware navigation sections and tokenized active/focus states. | +| State panel | `frontend/src/app/components/echo-state-panel/` | Production active | Adds `permission` and `success` variants and real icon rendering. | +| Access denied | `frontend/src/app/pages/access-denied/` | Migrated | Uses shared permission state. | +| Icon registry | `frontend/src/app/shared/icon/icon.module.ts` | Extended | Adds `Lock` and `CheckCircle` paths. | + +## Still Legacy + +- Form controls, tables, filter controls, page-specific buttons, dashboard cards, and internal page layouts are still mixed Tailwind/SCSS implementations. +- Existing Storybook/design-lab artifacts remain references; production consumers were not migrated wholesale. +- Destructive actions still need page-by-page adoption of `EchoConfirmationDialogComponent`. + +## Required Future Adoption + +- Admin user deletes/role changes. +- Course archive/delete/publish actions. +- Badge create/update/delete flows. +- Organization invite revocation. +- Access grant revoke flows. +- Product publish/review transitions. diff --git a/docs/ux-overhaul/sitemap-current.md b/docs/ux-overhaul/sitemap-current.md new file mode 100644 index 0000000..331d4c3 --- /dev/null +++ b/docs/ux-overhaul/sitemap-current.md @@ -0,0 +1,69 @@ +# Current Sitemap + +```mermaid +flowchart TD + Public[Public] + Public --> Landing[/] + Public --> Products[/products] + Products --> ProductSlug[/products/:slug] + Public --> Login[/login] + Public --> Registration[/registration] + Public --> Onboarding[/onboarding/organization] + Public --> AccessDenied[/access-denied] + + Home[/home] + Home --> RoleSelector[/home] + Home --> Courses[/home/courses] + Home --> CourseNew[/home/courses/new] + Home --> CourseEdit[/home/courses/:courseId/edit] + Home --> Programs[/home/programs] + Home --> Assessment[/home/assessments/:id] + Home --> Certifications[/home/certifications] + Home --> Invites[/home/org/invites] + Home --> StudioCourses[/home/studio/courses] + Home --> Sections[/home/sections] + Sections --> SectionDetail[/home/sections/:id] + Home --> Preferences[/home/me/preferences] + Home --> AdminCourses[/home/admin/courses] + Home --> AdminBadges[/home/admin/badges] + Home --> AdminUsers[/home/admin/users] + Home --> HomeLesson[/home/lesson/:id] + + Workspace[/workspace] + Workspace --> Projects[/workspace/projects] + Projects --> ProjectDetail[/workspace/projects/:projectId] + Workspace --> ProductStudio[/workspace/product-studio] + ProductStudio --> GenerationRuns[/workspace/product-studio/generation-runs] + ProductStudio --> GenerationRunDetail[/workspace/product-studio/generation-runs/:generationRunId] + ProductStudio --> StudioCourseList[/workspace/product-studio/courses] + ProductStudio --> StudioCourseNew[/workspace/product-studio/courses/new] + ProductStudio --> StudioCourseEdit[/workspace/product-studio/courses/:courseId/edit] + Workspace --> WorkspaceProducts[/workspace/products] + WorkspaceProducts --> WorkspaceProductDetail[/workspace/products/:productId] + Workspace --> KnowledgeSources[/workspace/knowledge-sources] + Workspace --> Artifacts[/workspace/artifacts] + Artifacts --> ArtifactDetail[/workspace/artifacts/:artifactId] + Workspace --> ReviewCenter[/workspace/review-center] + Workspace --> Access[/workspace/access] + Workspace --> Learners[/workspace/learners] + Learners --> LearnerProducts[/workspace/learners/products] + Learners --> LearnerPaths[/workspace/learners/paths] + Learners --> LearnerCertificates[/workspace/learners/certificates] + Learners --> LearnerUsers[/workspace/learners/users] + Learners --> Cohorts[/workspace/learners/cohorts] + Cohorts --> CohortDetail[/workspace/learners/cohorts/:id] + Workspace --> Analytics[/workspace/analytics] + Workspace --> Commercial[/workspace/commercial] + Workspace --> DemoReadiness[/workspace/demo-readiness] + Workspace --> WorkspaceSettings[/workspace/settings] + WorkspaceSettings --> SettingsInvites[/workspace/settings/invites] + WorkspaceSettings --> SettingsBadges[/workspace/settings/badges] + Workspace --> WorkspaceLesson[/workspace/lesson/:id] + + Learn[/learn] + Learn --> LearnProducts[/learn/products] + Learn --> LearnPaths[/learn/paths] + Learn --> LearnCertificates[/learn/certificates] + Learn --> LearnResources[/learn/resources] + Learn --> LearnLesson[/learn/lesson/:id] +``` diff --git a/docs/ux-overhaul/sitemap-proposed.md b/docs/ux-overhaul/sitemap-proposed.md new file mode 100644 index 0000000..4705c77 --- /dev/null +++ b/docs/ux-overhaul/sitemap-proposed.md @@ -0,0 +1,76 @@ +# Proposed Sitemap + +## Preserve First, Restructure Gradually + +| Proposed area | Route strategy | Notes | +| --- | --- | --- | +| Learn | Preserve `/learn/**`; redirect student `/home` to `/learn` after preference migration. | Canonical student experience. | +| Teach | Add frontend route aliases later; initially relabel existing `/home/sections`, teacher dashboard, assignments. | Existing APIs support it. | +| Studio | Preserve `/workspace/**` for content operations; hide irrelevant nav per role. | Keep product/source/artifact routes. | +| Organization | Initially conceptual over `/workspace/settings/invites`, `/workspace/access`, `/home/sections`. | Dedicated routes optional later. | +| Admin | Initially conceptual over `/home/admin/*` and analytics. | Dedicated `/admin` route aliases optional. | +| Community | Relabel `/workspace/commercial`; later add `/community` alias and discussion UI. | Avoid backend change initially. | + +```mermaid +flowchart TD + App[EchoEd] + App --> Public[Public] + App --> Learn[Learn] + App --> Teach[Teach] + App --> Studio[Studio] + App --> Org[Organization] + App --> Admin[Admin] + App --> Community[Community] + + Public --> PLanding[Landing] + Public --> PCatalog[Public Products] + Public --> PLogin[Login] + Public --> PRegister[Registration] + Public --> POnboarding[Organization Setup] + + Learn --> LHome[Learner Home] + Learn --> LAssignments[Assignments] + Learn --> LCourses[Courses] + Learn --> LLesson[Lesson Player] + Learn --> LProgress[Progress] + Learn --> LAchievements[Achievements] + Learn --> LResources[Resources] + + Teach --> TToday[Today] + Teach --> TClasses[Classes] + Teach --> TAssignments[Assignments] + Teach --> TCurriculum[Curriculum] + Teach --> TSupport[Learner Support] + Teach --> TReports[Reports] + + Studio --> SHome[Studio Home] + Studio --> SProjects[Projects] + Studio --> SSources[Sources] + Studio --> SArtifacts[Artifacts] + Studio --> SProducts[Products] + Studio --> SReview[Review] + + Org --> OPeople[People] + Org --> OInvites[Invites] + Org --> OAccess[Access] + Org --> OSettings[Settings] + + Admin --> AHome[Admin Home] + Admin --> AUsers[Users] + Admin --> AOrgs[Organizations] + Admin --> ACurriculum[Curriculum] + Admin --> ABadges[Badges] + Admin --> AReports[Reports] + Admin --> AModeration[Moderation] + + Community --> CDiscuss[Discussions] + Community --> CContrib[Contributor Guide] + Community --> CResources[Shared Resources] +``` + +## Route Compatibility Notes + +- Preserved physical routes: `/learn/**`, `/workspace/**`, `/home/admin/*`, `/home/sections`, `/home/lesson/:id`. +- Frontend route aliases recommended later: `/teach`, `/admin`, `/organization`, `/community`. +- Conceptual views over existing routes: Teacher Today, Learner Support, Organization Home, Admin Reports, Moderation. +- Backend changes required: none for IA shell phase. diff --git a/docs/ux-overhaul/usability-test-plan.md b/docs/ux-overhaul/usability-test-plan.md new file mode 100644 index 0000000..fd36bff --- /dev/null +++ b/docs/ux-overhaul/usability-test-plan.md @@ -0,0 +1,67 @@ +# Usability Test Plan + +## Participants + +- Student or student proxy: 3-5. +- Teacher/educator: 3-5. +- Administrator/content operator: 3-5. + +## Method + +- Moderated remote or in-person sessions. +- Use seeded demo data where safe. +- Capture task success, time on task, confusion points, accessibility blockers, and role language comprehension. + +## Student Script + +1. Sign in as `student1`. +2. Find what you should do next. +3. Open Introduction to Africa. +4. Resume the next lesson. +5. Complete an activity. +6. Leave and return to the lesson. +7. Find your progress and badges. +8. Find where you would ask or read a discussion question if available. + +Success criteria: student can identify next action without help, recover from lesson interruption, and describe progress status. + +## Teacher Script + +1. Sign in as `teacher`. +2. Identify which learners need support today. +3. Open a class. +4. Review the roster. +5. Find curriculum for Introduction to Africa. +6. Assign a lesson to a class or learner. +7. Review learner progress. +8. Locate where to respond to discussion or flagged content if available. + +Success criteria: teacher can complete assignment flow and explain support recommendations. + +## Administrator Script + +1. Sign in as `orgadmin` or admin demo account where available. +2. Understand platform health. +3. Find user management. +4. Inspect a user's role/organization context. +5. Attempt a destructive action and explain the confirmation. +6. Review curriculum/course governance status. +7. Find organization invites/access. +8. Locate moderation or review queues. + +Success criteria: admin can distinguish risk alerts from routine metrics and avoids accidental destructive action. + +## Accessibility Tasks + +- Keyboard-only navigation from sign in to primary task. +- Screen-reader heading/landmark review. +- Mobile 390px task completion. +- Reduced-motion check. + +## Metrics + +- Task completion: pass/fail/assisted. +- Confidence rating: 1-5. +- Navigation clarity rating: 1-5. +- Error recovery success. +- Accessibility blockers count. diff --git a/docs/ux-overhaul/visual-acceptance-criteria.md b/docs/ux-overhaul/visual-acceptance-criteria.md new file mode 100644 index 0000000..022c6dd --- /dev/null +++ b/docs/ux-overhaul/visual-acceptance-criteria.md @@ -0,0 +1,39 @@ +# Visual Acceptance Criteria + +## Global + +- No investor, commercial, marketplace, revenue, or sales language in community-facing UI. +- UI uses warm archive palette, not generic purple SaaS styling. +- Text does not overlap or clip at 390px, 768px, 1280px, or 1440px widths. +- Cards are not nested inside cards. +- Primary actions have 44px touch targets. +- Focus indicator is visible on all interactive elements. +- Reduced motion disables nonessential animation. + +## Public + +- First viewport shows EchoEd identity, mission, and clear entry actions. +- Public product pages explain learning value and access path. + +## Student + +- Next learning action is first in visual and DOM order. +- Lesson player has clear exit and save/progress feedback. +- Unavailable/governed states explain what happened and how to continue. + +## Teacher + +- Dashboard starts with today's priorities, learner support, and class context. +- Assignment creation has a review step before submit. +- Class detail groups roster, assignments, progress, and discussion. + +## Admin + +- High-risk alerts appear before routine metrics. +- Destructive actions use confirmation with object name and impact. +- Users/courses are searchable and usable as mobile data lists. + +## Figma/Prototype + +- Frames exist for 1440, 1280, 768, and 390 widths for major flows. +- Components use semantic variables from the Figma package. diff --git a/docs/ux-overhaul/visual-direction.md b/docs/ux-overhaul/visual-direction.md new file mode 100644 index 0000000..74e677a --- /dev/null +++ b/docs/ux-overhaul/visual-direction.md @@ -0,0 +1,49 @@ +# Visual Direction + +## Direction: Warm Archive Learning Platform + +EchoEd should feel like a living learning archive: warm paper surfaces, deep ink text, grounded green action color, gold for earned/progress moments, clay/rose for caution, and restrained blue for links/information. + +## Brand Cues + +- Current repository mark: text "EE" in shell components. +- Existing mission assets: Africa/world maps and storybook images. +- No standalone logo file was found in the repository search; do not replace the mark until the real logo asset is supplied. + +## Palette Roles + +- Ink: primary reading text and page titles. +- Archive paper: page background and content surfaces. +- Palm green: primary action and active navigation. +- Gold: achievement, progress, highlights. +- Clay: warning and historical annotation. +- River blue: links, informational states, maps. +- Berry red: destructive/error states. + +## Typography + +- Use a readable sans family for app UI. Existing assets include `CalSans-Regular.ttf`; current CSS references Inter/Poppins/Playfair but repo font availability should be rationalized during implementation. +- Proposed: Cal Sans for display/brand headings where licensed locally; system sans for body unless Inter is bundled. +- Avoid viewport-scaled body text. Use stable scale tokens. + +## Imagery + +- Use real historical images, maps, storybook images, and learner artifacts when they directly support content. +- Historical images require captions, source/provenance, date/context where known, and respectful cropping. +- Avoid dark blurred generic background images when learners need inspection. + +## Layout + +- App surfaces should be full-width bands and constrained content, not cards nested inside cards. +- Use cards for repeated items, dialogs, and framed tools. +- Data-heavy staff surfaces should be calm and dense; student surfaces should be spacious and action-led. + +## Motion + +- Motion should orient, not entertain. +- Use short fades/slides for state changes. +- Disable nonessential animation under reduced motion. + +## Dark Mode + +Dark mode is feasible later, but not recommended for the first overhaul because historical imagery, maps, and K-5 reading benefit from a stable light-first contrast system. diff --git a/frontend/design-lab/README.md b/frontend/design-lab/README.md new file mode 100644 index 0000000..41cc2ca --- /dev/null +++ b/frontend/design-lab/README.md @@ -0,0 +1,21 @@ +# EchoEd UX Overhaul Design Lab + +This is an isolated static prototype for the role-based UX overhaul design phase. + +It does not affect Angular production routing, services, auth, or backend contracts. + +Open `frontend/design-lab/index.html` in a browser to review representative screens: + +- Public landing +- Login +- Student dashboard +- Student course overview +- Student lesson player +- Teacher dashboard +- Teacher class detail +- Teacher assignment workflow +- Admin dashboard +- Admin user management +- Shared states +- Desktop and mobile navigation concepts + diff --git a/frontend/design-lab/design-lab.css b/frontend/design-lab/design-lab.css new file mode 100644 index 0000000..72db121 --- /dev/null +++ b/frontend/design-lab/design-lab.css @@ -0,0 +1,483 @@ +:root { + --page: #f8f2e8; + --surface: #fffdf8; + --raised: #ffffff; + --ink: #102033; + --muted: #40546b; + --subtle: #64748b; + --palm: #0f766e; + --palm-dark: #0b5f59; + --gold: #d59b00; + --river: #1b5f85; + --danger: #be123c; + --border: #dccdb7; + --shadow: 0 12px 28px rgba(16, 32, 51, 0.12); +} + +* { + box-sizing: border-box; +} + +html { + scroll-behavior: smooth; +} + +body { + background: var(--page); + color: var(--ink); + font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; + line-height: 1.6; + margin: 0; +} + +a, +button, +input { + font: inherit; +} + +a:focus-visible, +button:focus-visible, +input:focus-visible { + outline: 2px solid var(--palm); + outline-offset: 3px; + box-shadow: 0 0 0 4px rgba(15, 118, 110, 0.18); +} + +.skip-link { + background: var(--ink); + color: #fff; + left: 1rem; + padding: .75rem 1rem; + position: absolute; + top: -4rem; + z-index: 10; +} + +.skip-link:focus { + top: 1rem; +} + +.lab-topbar { + align-items: center; + background: rgba(255, 253, 248, .96); + border-bottom: 1px solid var(--border); + display: grid; + gap: 1rem; + grid-template-columns: auto 1fr auto; + padding: 1rem clamp(1rem, 3vw, 2rem); + position: sticky; + top: 0; + z-index: 5; +} + +.lab-topbar h1, +.page-header h2, +.hero-copy h2, +.lesson-content h2 { + letter-spacing: 0; + line-height: 1.1; + margin: 0; +} + +.lab-topbar nav { + display: flex; + flex-wrap: wrap; + gap: .4rem; +} + +.lab-topbar a, +.side-nav a { + color: var(--ink); + text-decoration: none; +} + +.lab-topbar nav a, +.side-nav a { + border-radius: .5rem; + padding: .55rem .75rem; +} + +.lab-topbar nav a:hover, +.side-nav a.active, +.side-nav a:hover { + background: #eaf7f2; + color: var(--palm-dark); +} + +.brand-mark { + align-items: center; + background: var(--palm); + border-radius: .5rem; + color: #fff; + display: inline-flex; + font-weight: 800; + height: 2.75rem; + justify-content: center; + width: 2.75rem; +} + +.eyebrow { + color: var(--palm-dark); + font-size: .75rem; + font-weight: 800; + letter-spacing: .12em; + margin: 0 0 .35rem; + text-transform: uppercase; +} + +.screen, +.app-frame, +.lesson-frame { + margin: 2rem auto; + max-width: 1180px; + padding: clamp(1rem, 3vw, 2rem); +} + +.public-hero { + align-items: stretch; + display: grid; + gap: 1rem; + grid-template-columns: minmax(0, 1.2fr) minmax(20rem, .8fr); + min-height: 72vh; +} + +.hero-copy, +.archive-panel, +.context-panel, +.form-card, +.panel, +.next-card, +.lesson-content, +.state-card, +.lesson-list article { + background: var(--surface); + border: 1px solid var(--border); + border-radius: .75rem; + box-shadow: var(--shadow); + padding: clamp(1rem, 3vw, 2rem); +} + +.hero-copy { + align-content: center; + display: grid; +} + +.hero-copy h2 { + font-size: clamp(3rem, 10vw, 6rem); +} + +.archive-panel { + display: grid; +} + +.map-card { + align-self: end; + background: + linear-gradient(135deg, rgba(15, 118, 110, .22), rgba(213, 155, 0, .22)), + radial-gradient(circle at 45% 35%, #0f766e 0 14%, transparent 15%), + radial-gradient(circle at 55% 55%, #0b5f59 0 20%, transparent 21%), + #f4eadc; + border: 1px solid var(--border); + border-radius: .75rem; + min-height: 18rem; +} + +.actions, +.toolbar { + display: flex; + flex-wrap: wrap; + gap: .75rem; +} + +.button, +button { + align-items: center; + border: 1px solid var(--border); + border-radius: .5rem; + cursor: pointer; + display: inline-flex; + font-weight: 750; + min-height: 2.75rem; + padding: .7rem 1rem; + text-decoration: none; +} + +.button.primary { + background: var(--palm); + border-color: var(--palm); + color: #fff; +} + +.button.primary:hover { + background: var(--palm-dark); +} + +.button.secondary, +button { + background: var(--raised); + color: var(--ink); +} + +.two-col, +.priority-grid, +.dashboard-grid, +.state-grid { + display: grid; + gap: 1rem; +} + +.two-col { + grid-template-columns: .9fr 1.1fr; +} + +.form-card { + display: grid; + gap: 1rem; +} + +label { + color: var(--muted); + display: grid; + font-weight: 700; + gap: .35rem; +} + +input { + background: #fff; + border: 1px solid var(--border); + border-radius: .5rem; + color: var(--ink); + min-height: 2.75rem; + padding: .65rem .75rem; +} + +.hint { + color: var(--muted); + margin: 0; +} + +.app-frame { + background: var(--surface); + border: 1px solid var(--border); + border-radius: .75rem; + box-shadow: var(--shadow); + display: grid; + grid-template-columns: 15rem minmax(0, 1fr); + min-height: 42rem; + overflow: hidden; + padding: 0; +} + +.side-nav { + background: #fffaf1; + border-right: 1px solid var(--border); + display: flex; + flex-direction: column; + gap: .5rem; + padding: 1rem; +} + +.side-nav .brand-mark { + margin-bottom: .75rem; +} + +.app-content { + padding: clamp(1rem, 3vw, 2rem); +} + +.page-header { + margin-bottom: 1rem; +} + +.page-header h2 { + font-size: clamp(2rem, 5vw, 3rem); +} + +.priority-grid { + grid-template-columns: 1.4fr .8fr .8fr; +} + +.dashboard-grid { + grid-template-columns: repeat(3, minmax(0, 1fr)); +} + +.wide { + grid-column: span 2; +} + +.metric { + color: var(--palm-dark); + display: block; + font-size: 3rem; + line-height: 1; +} + +.progress { + background: #eadfce; + border-radius: 999px; + height: .65rem; + margin: 1rem 0; + overflow: hidden; +} + +.progress span { + background: var(--palm); + display: block; + height: 100%; +} + +.lesson-list, +.data-list, +.state-grid { + display: grid; + gap: .75rem; + list-style: none; + padding: 0; +} + +.lesson-list { + grid-template-columns: repeat(3, minmax(0, 1fr)); +} + +.status { + border-radius: 999px; + display: inline-flex; + font-size: .75rem; + font-weight: 800; + padding: .25rem .55rem; +} + +.done, +.active { + background: #eaf7f2; + color: var(--palm-dark); +} + +.locked { + background: #f4eadc; + color: var(--muted); +} + +.lesson-frame { + background: var(--ink); + border-radius: .75rem; + color: #fffdf8; + padding: 0; +} + +.lesson-bar { + align-items: center; + border-bottom: 1px solid rgba(255, 255, 255, .18); + display: flex; + gap: 1rem; + justify-content: space-between; + padding: 1rem; +} + +.lesson-content { + box-shadow: none; + color: var(--ink); + margin: 1rem; + max-width: 48rem; +} + +.activity-box { + background: #f4eadc; + border: 1px solid var(--border); + border-radius: .75rem; + display: grid; + gap: .5rem; + margin: 1rem 0; + padding: 1rem; +} + +.data-list li { + align-items: center; + background: var(--raised); + border: 1px solid var(--border); + border-radius: .5rem; + display: grid; + gap: .5rem; + grid-template-columns: minmax(0, 1fr) minmax(10rem, auto) auto; + padding: .9rem; +} + +.tabs, +.stepper { + display: flex; + flex-wrap: wrap; + gap: .5rem; + margin: 1rem 0; +} + +.tabs button, +.stepper span { + background: var(--raised); + border: 1px solid var(--border); + border-radius: 999px; + color: var(--ink); + padding: .55rem .85rem; +} + +.tabs .active, +.stepper .active { + background: #eaf7f2; + border-color: #ccebe0; + color: var(--palm-dark); +} + +.warning { + background: #fff8df; + border-color: #fdeba8; +} + +.danger-text { + color: var(--danger); +} + +.state-grid { + grid-template-columns: repeat(4, minmax(0, 1fr)); +} + +.state-card.error { + border-color: #ffd9df; +} + +@media (max-width: 900px) { + .lab-topbar, + .public-hero, + .two-col, + .priority-grid, + .dashboard-grid, + .lesson-list, + .state-grid { + grid-template-columns: 1fr; + } + + .app-frame { + grid-template-columns: 1fr; + } + + .side-nav { + border-bottom: 1px solid var(--border); + border-right: 0; + flex-direction: row; + overflow-x: auto; + } + + .wide { + grid-column: auto; + } + + .data-list li { + align-items: stretch; + grid-template-columns: 1fr; + } +} + +@media (prefers-reduced-motion: reduce) { + html { + scroll-behavior: auto; + } +} diff --git a/frontend/design-lab/index.html b/frontend/design-lab/index.html new file mode 100644 index 0000000..802ff65 --- /dev/null +++ b/frontend/design-lab/index.html @@ -0,0 +1,237 @@ + + + + + + EchoEd Design Lab + + + +
+ +
EE
+
+

EchoEd design lab

+

Role-based learning experience

+
+ +
+ +
+
+
+

Community learning platform

+

EchoEd

+

Explore African and African-American history through guided lessons, classroom support, source-aware content, and community stewardship.

+
+ Sign in + Preview learning +
+
+
+

Featured pathway

+

Introduction to Africa

+

Geography, kingdoms, knowledge traditions, community care, and creative expression for K-5 learners.

+
+
+
+ +
+ +
+ + + +

Demo examples: student1, teacher, orgadmin, contentadmin.

+
+
+ +
+ +
+
+

Learn

+

Welcome back, Sami.

+

Your next lesson in Introduction to Africa is ready.

+
+
+
+

Next learning

+

Introduction to Africa

+

Continue: Africa is a continent with many places, languages, and communities.

+
+ Resume lesson +
+
+

Progress

+ 42% +

3 lessons complete. One badge is close.

+
+
+

Achievement

+

Map Explorer

+

Earned for careful geography observations.

+
+
+
+
+ +
+
+

Course overview

+

Introduction to Africa

+

Follow a guided path through geography, routes, kingdoms, libraries, ecosystems, art, and community care.

+
+
+
Complete

What is Africa?

Build a map vocabulary and continent-scale context.

+
Ready

Rivers, routes, and communities

Explore how places connect people and ideas.

+
Later

Kingdoms and knowledge

Unlocks after the current lesson.

+
+
+ +
+
+ Exit lesson + Governed delivery + Introduction to Africa +
+
+

Lesson 2

+

Rivers, routes, and communities

+

People use rivers, roads, stories, and shared knowledge to stay connected. Today you will notice how geography can shape daily life.

+
+

Reflection

+

Choose one way a community can share knowledge across distance.

+ + + +
+ +
+
+ +
+ +
+
+

Teach

+

Today in EchoEd Demo School

+

Review learner support first, then manage classes and assignments.

+
+
+
+

Learners needing support

+
    +
  • Binta ReteachReteach recommended: map vocabulary
    • +
  • Chidi ReviewReview recommended: community routes
    • +
+
+

Active classes

3
+

Submissions

12
+
+
+
+ +
+
+

Class detail

+

Grade 4 History Circle

+

Roster, assignments, progress, and discussion are grouped in one class context.

+
+
+ +
+ +
+ +
+
+

Assignment workflow

+

Assign learning

+

Choose curriculum, select learners, review, then confirm.

+
+
1 Content2 Learners3 Review
+
+

Selected content

+

Introduction to Africa - Rivers, routes, and communities

+ +
+
+ +
+ +
+
+

Admin

+

Platform health

+

Resolve access, content, and safety issues before routine management.

+
+
+

Students

7
+

Teachers

1
+

Courses

2
+

2 publish checks need review

Open course governance before publishing new learner content.

+
+
+
+ +
+
+

User management

+

People and roles

+

Search users, review organization roles, and confirm high-risk changes.

+
+
+ +
+ +
+
+

Shared states

+

Loading, empty, error, permission

+
+
+

Loading

Restoring your lesson path.

+

No assignments yet

Your teacher has not assigned learning for this class.

+

Could not load roster

No changes were made. Try again.

+

Access needed

You are signed in as a student. Switch organization or ask an admin for access.

+
+
+
+ + diff --git a/frontend/src/app/components/echo-confirmation-dialog/echo-confirmation-dialog.component.spec.ts b/frontend/src/app/components/echo-confirmation-dialog/echo-confirmation-dialog.component.spec.ts new file mode 100644 index 0000000..33618ef --- /dev/null +++ b/frontend/src/app/components/echo-confirmation-dialog/echo-confirmation-dialog.component.spec.ts @@ -0,0 +1,84 @@ +import { SimpleChange } from '@angular/core'; +import { ComponentFixture, TestBed } from '@angular/core/testing'; + +import { EchoConfirmationDialogComponent } from './echo-confirmation-dialog.component'; + +describe('EchoConfirmationDialogComponent', () => { + let component: EchoConfirmationDialogComponent; + let fixture: ComponentFixture; + + beforeEach(async () => { + await TestBed.configureTestingModule({ + imports: [EchoConfirmationDialogComponent], + }).compileComponents(); + + fixture = TestBed.createComponent(EchoConfirmationDialogComponent); + component = fixture.componentInstance; + component.open = true; + component.title = 'Delete course'; + component.description = 'This removes the course from learners who can access it.'; + component.objectName = 'Introduction to Africa'; + component.confirmLabel = 'Delete course'; + component.variant = 'danger'; + fixture.detectChanges(); + }); + + it('renders destructive confirmation copy with dialog semantics', () => { + const dialog = fixture.nativeElement.querySelector('[role="dialog"]') as HTMLElement; + + expect(dialog.getAttribute('aria-modal')).toBe('true'); + expect(fixture.nativeElement.textContent).toContain('Destructive action'); + expect(fixture.nativeElement.textContent).toContain('Introduction to Africa'); + expect(fixture.nativeElement.textContent).toContain('Delete course'); + }); + + it('places initial focus on the safe cancel action', () => { + const cancelButton = fixture.nativeElement.querySelector('.echo-dialog__button--secondary') as HTMLButtonElement; + + expect(document.activeElement).toBe(cancelButton); + }); + + it('emits cancel on Escape when not loading', () => { + spyOn(component.cancel, 'emit'); + + document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' })); + + expect(component.cancel.emit).toHaveBeenCalled(); + }); + + it('does not close on Escape while loading', () => { + spyOn(component.cancel, 'emit'); + component.loading = true; + fixture.detectChanges(); + + document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' })); + + expect(component.cancel.emit).not.toHaveBeenCalled(); + }); + + it('traps Tab focus inside the dialog', () => { + const buttons = fixture.nativeElement.querySelectorAll('button') as NodeListOf; + const cancelButton = buttons[0]; + const confirmButton = buttons[1]; + confirmButton.focus(); + + document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab' })); + + expect(document.activeElement).toBe(cancelButton); + }); + + it('restores focus to the trigger after close', () => { + const trigger = document.createElement('button'); + document.body.appendChild(trigger); + trigger.focus(); + + component.open = false; + (component as any).previouslyFocused = trigger; + component.ngOnChanges({ + open: new SimpleChange(true, false, false), + }); + + expect(document.activeElement).toBe(trigger); + trigger.remove(); + }); +}); diff --git a/frontend/src/app/components/echo-confirmation-dialog/echo-confirmation-dialog.component.ts b/frontend/src/app/components/echo-confirmation-dialog/echo-confirmation-dialog.component.ts new file mode 100644 index 0000000..065b3ab --- /dev/null +++ b/frontend/src/app/components/echo-confirmation-dialog/echo-confirmation-dialog.component.ts @@ -0,0 +1,295 @@ +import { + AfterViewInit, + Component, + ElementRef, + EventEmitter, + HostListener, + Input, + OnChanges, + Output, + SimpleChanges, + ViewChild, +} from '@angular/core'; +import { CommonModule } from '@angular/common'; + +@Component({ + selector: 'app-echo-confirmation-dialog', + standalone: true, + imports: [CommonModule], + template: ` + + `, + styles: [` + .echo-dialog-backdrop { + align-items: center; + background: rgba(16, 32, 51, 0.48); + display: flex; + inset: 0; + justify-content: center; + padding: var(--ee-space-4, 1rem); + position: fixed; + z-index: 100; + } + + .echo-dialog { + background: var(--ee-color-surface-raised, #ffffff); + border: 1px solid var(--ee-color-border-subtle, #dccdb7); + border-radius: var(--ee-radius-dialog, 0.75rem); + box-shadow: var(--ee-shadow-overlay, 0 24px 64px rgba(16, 32, 51, 0.24)); + color: var(--ee-color-text-default, #102033); + display: grid; + gap: var(--ee-space-4, 1rem); + max-width: min(32rem, 100%); + padding: clamp(1rem, 3vw, 1.5rem); + width: 100%; + } + + .echo-dialog:focus { + outline: none; + } + + .echo-dialog__eyebrow, + .echo-dialog__object span { + color: var(--ee-color-action-primary-background, #0f766e); + font-size: var(--ee-font-size-xs, 0.75rem); + font-weight: 800; + letter-spacing: 0.12em; + margin: 0; + text-transform: uppercase; + } + + h2, + p { + margin: 0; + } + + h2 { + font-size: var(--ee-font-size-2xl, 1.5rem); + line-height: var(--ee-line-height-heading, 1.25); + } + + p { + color: var(--ee-color-text-muted, #40546b); + line-height: var(--ee-line-height-body, 1.6); + } + + .echo-dialog__object { + background: var(--ee-color-surface-subtle, #f4eadc); + border: 1px solid var(--ee-color-border-subtle, #dccdb7); + border-radius: var(--ee-radius-card-default, 0.5rem); + display: grid; + gap: 0.2rem; + padding: var(--ee-space-3, 0.75rem); + } + + .echo-dialog__object strong { + overflow-wrap: anywhere; + } + + .echo-dialog__error { + background: var(--ee-color-status-danger-background, #fff1f3); + border: 1px solid var(--ee-color-status-danger-border, #ffd9df); + border-radius: var(--ee-radius-card-default, 0.5rem); + color: var(--ee-color-status-danger-text, #9f1239); + padding: var(--ee-space-3, 0.75rem); + } + + .echo-dialog__actions { + display: flex; + flex-wrap: wrap; + gap: var(--ee-space-3, 0.75rem); + justify-content: flex-end; + } + + .echo-dialog__button { + border-radius: var(--ee-radius-control-default, 0.5rem); + border: 1px solid transparent; + cursor: pointer; + font: inherit; + font-weight: 800; + min-height: 2.75rem; + padding: 0.7rem 1rem; + } + + .echo-dialog__button:focus-visible { + outline: var(--ee-focus-ring-width, 2px) solid var(--ee-focus-ring-color, #0f766e); + outline-offset: var(--ee-focus-ring-offset, 3px); + box-shadow: var(--ee-focus-ring-shadow, 0 0 0 4px rgba(15, 118, 110, 0.18)); + } + + .echo-dialog__button--secondary { + background: var(--ee-color-action-secondary-background, #fffdf8); + border-color: var(--ee-color-action-secondary-border, #cdbda3); + color: var(--ee-color-action-secondary-text, #102033); + } + + .echo-dialog__button--primary { + background: var(--ee-color-action-primary-background, #0f766e); + border-color: var(--ee-color-action-primary-border, #0f766e); + color: var(--ee-color-action-primary-text, #ffffff); + } + + .echo-dialog__button--danger { + background: var(--ee-color-action-danger-background, #be123c); + border-color: var(--ee-color-action-danger-border, #be123c); + color: var(--ee-color-action-danger-text, #ffffff); + } + + .echo-dialog__button:disabled { + cursor: wait; + opacity: 0.68; + } + `], +}) +export class EchoConfirmationDialogComponent implements AfterViewInit, OnChanges { + @Input() open = false; + @Input() title = 'Confirm action'; + @Input() description = 'Review the consequences before continuing.'; + @Input() objectName = ''; + @Input() confirmLabel = 'Confirm'; + @Input() cancelLabel = 'Cancel'; + @Input() loadingLabel = 'Working...'; + @Input() loading = false; + @Input() errorMessage = ''; + @Input() variant: 'default' | 'danger' | 'publish' = 'default'; + @Output() confirm = new EventEmitter(); + @Output() cancel = new EventEmitter(); + + @ViewChild('dialogPanel') dialogPanel?: ElementRef; + @ViewChild('cancelButton') cancelButton?: ElementRef; + + readonly titleId = `echo-confirm-title-${Math.random().toString(36).slice(2)}`; + readonly descriptionId = `echo-confirm-description-${Math.random().toString(36).slice(2)}`; + private previouslyFocused: HTMLElement | null = null; + + get variantLabel(): string { + switch (this.variant) { + case 'danger': + return 'Destructive action'; + case 'publish': + return 'Publishing confirmation'; + default: + return 'Confirmation'; + } + } + + ngAfterViewInit(): void { + this.focusDialog(); + } + + ngOnChanges(changes: SimpleChanges): void { + if (changes['open']) { + if (this.open) { + this.previouslyFocused = document.activeElement as HTMLElement | null; + queueMicrotask(() => this.focusDialog()); + } else { + this.restoreFocus(); + } + } + } + + onBackdropClick(): void { + if (!this.loading) { + this.cancel.emit(); + } + } + + @HostListener('document:keydown', ['$event']) + onKeydown(event: KeyboardEvent): void { + if (!this.open) { + return; + } + + if (event.key === 'Escape' && !this.loading) { + event.preventDefault(); + this.cancel.emit(); + return; + } + + if (event.key === 'Tab') { + this.trapFocus(event); + } + } + + private focusDialog(): void { + if (this.open) { + this.cancelButton?.nativeElement.focus(); + } + } + + private restoreFocus(): void { + this.previouslyFocused?.focus?.(); + this.previouslyFocused = null; + } + + private trapFocus(event: KeyboardEvent): void { + const focusable = this.dialogPanel?.nativeElement.querySelectorAll( + 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])', + ); + + if (!focusable?.length) { + event.preventDefault(); + return; + } + + const first = focusable[0]; + const last = focusable[focusable.length - 1]; + + if (event.shiftKey && document.activeElement === first) { + event.preventDefault(); + last.focus(); + } else if (!event.shiftKey && document.activeElement === last) { + event.preventDefault(); + first.focus(); + } + } +} diff --git a/frontend/src/app/components/echo-header/echo-header.component.html b/frontend/src/app/components/echo-header/echo-header.component.html index a255724..920de6f 100644 --- a/frontend/src/app/components/echo-header/echo-header.component.html +++ b/frontend/src/app/components/echo-header/echo-header.component.html @@ -3,8 +3,9 @@
EE
-

EchoEd Dashboard

-

Command center

+

{{ shellSpace.eyebrow }}

+

{{ shellSpace.name }}

+

{{ shellSpace.description }}

@@ -101,6 +102,16 @@

Command center

{{ userinfo.role | titlecase }}