Responsive UI

Feature: Global UI, Design Tokens, & Responsive Standards
Feature Owner: Jethro Magdaleno Lagmay
Module: Player
Priority: High (Prerequisite for all UI development)
Sprint: #12
Date: July 2, 2026

EXECUTIVE SUMMARY

What is this feature? A centralized standardization of WyzQuests' frontend visual architecture. It enforces a strict reliance on the semantic variables defined in globals.css, standardizes how Shadcn UI components are extended, and establishes a mobile-first layout strategy. A design token guide is also given to serve as a guide.

Why does it matter? As the platform grows (particularly across complex modules like the reviewer queue and visual canvas), maintaining consistency becomes difficult. Hardcoded CSS creates tech debt, visual fragmentation, and brittle layouts that break on mobile devices. This standard ensures a unified design language and significantly speeds up frontend development.

What’s the MVP scope?

• Mapping all brand colors, typography, and spacing to globals.css variables and standard Tailwind classes.

• Establishing the cn() utility as the only acceptable method for customizing Shadcn components.

• Setting baseline mobile responsive rules (e.g., standard viewport scaling, flexible grids).

1. USER PAIN POINT & SOLUTION

Current State (Without Feature) Developers are manually writing custom hex codes and arbitrary pixel values for padding/margins. Mobile layouts frequently break or require horizontal scrolling due to rigid container widths.

Pain Point

• Emotional: Frustration from users struggling to navigate broken mobile interfaces and developers dealing with CSS conflicts.

• Functional: Unpredictable UI behavior across different screen sizes; dark mode toggle doesn't apply consistently.

• Business Impact: Increased development time for new features due to debugging legacy CSS; poor mobile user retention.

Future State (With Feature) A predictable, scalable, and responsive UI out-of-the-box. Any developer can drop a Shadcn component onto a page, apply a Tailwind utility mapped to a globals.css token, and trust it will look perfectly on-brand across all devices.

Marketing Hook A seamless, accessible, and unified WyzQuests experience—whether you are creating a course on a desktop or reviewing content on your phone.

2. 4D FRAMEWORK MAPPING

Diagnose Identify isolated UI components utilizing hardcoded styling, improper HTML semantics, and fixed widths that violate responsive behavior.

Design Define the single source of truth in globals.css. Ensure Shadcn base components are correctly mapped to these global tokens (e.g., mapping --primary to the platform's core brand color).

Develop Refactor existing elements to use Tailwind token utilities. Implement Flexbox and CSS Grid for structural layout shifts based on standard screen breakpoints (sm, md, lg).

Deliver A fully fluid frontend foundation where all interactive elements, text blocks, and containers gracefully adapt from 320px mobile screens up to 1440px desktop displays.

3. USER FLOWS

Entry Point Global application load; applies to every route and view within the Next.js application.

Success Criteria

• Zero horizontal overflow on viewports down to 320px.

• 100% adherence to the globals.css color scheme.

• Seamless toggling between light and dark modes.

Main Flow (Happy Path) User accesses the site on a mobile device -> Layout utilizes default standard utility classes -> User rotates device or switches to desktop -> Breakpoints (md:, lg:) trigger CSS Grid/Flexbox restructuring for larger displays.

Edge Cases Extremely narrow legacy mobile screens (under 320px); deeply nested data tables that cannot physically compress further.

Decision Points When a layout cannot compress without losing readability, the decision point is to introduce a controlled horizontal scroll container (e.g., for large data tables) rather than breaking the page wrapper.

4. INFORMATION ARCHITECTURE

Primary Information (Always visible) Core content rendering, utilizing standard global typography tokens.

Secondary Information Responsive navigation elements (e.g., sidebar condensing to a hamburger menu on mobile).

Tertiary Information (Hidden until needed) Hover states, popovers, and tooltips (which must adapt to touch-events on mobile).

Actions

• Primary CTA: Rendered via Shadcn <Button> using the default variant tied to the primary CSS variable.

• Secondary Actions: Rendered via <Button variant="outline"> or variant="ghost", scaling appropriately to maintain minimum touch-target sizes on mobile.

5. WIREFRAMES

N/A (Foundational styling update; applies to existing wireframes).

6. WIREFLOWS

N/A

7. PROTOTYPE

Already synced in the development server.

8. BACKEND SCHEMA

N/A - This feature is strictly scoped to the frontend CSS architecture and component structure.

Database Tables: N/A Indexes: N/A Constraints: N/A RLS Policies: N/A

9. API ENDPOINTS

N/A - No backend API modifications required for this UI standardization.

10. DATA REQUIREMENTS

Frontend Needs Consistent loading of globals.css at the root layout level in Next.js to ensure all CSS variables are injected into the DOM before page paint.

API Calls Frontend Will Make N/A

Caching Strategy Standard static asset caching for the compiled CSS stylesheet.

11. PERFORMANCE CONSIDERATIONS

Database Optimization: N/A Caching Strategy: CSS stylesheet should be minified and cached at the CDN level. API Response Time: N/A

Note on Frontend Performance: Consolidating custom CSS into Tailwind utility classes will reduce the overall CSS bundle size, improving First Contentful Paint (FCP) metrics.

12. SECURITY & AUTHORIZATION

N/A - UI styling does not interact with authentication or authorization logic.

Who can access this feature? All users. Authorization Logic: N/A Data Validation: N/A

13. ERROR HANDLING

• CSS Variable Failure: If a Tailwind class references a missing variable, it fails silently. Development builds will utilize the Tailwind PostCSS plugin to flag unresolved utility classes in the console.

14. TESTING CHECKLIST

Happy Path

• [ ] Verify the cn() utility correctly merges classes when passing custom margins/paddings to a Shadcn component.

• [ ] Resize the browser down to 320px wide; confirm the horizontal scrollbar does not appear on the main <body>.

• [ ] Verify touch targets on mobile (buttons, inputs) are at least 44px in height.

Edge Cases & Specific Implementation Checks

• [ ] Check the "Beyond Coding" module components: Verify that descriptive text blocks are using standard paragraph tags (<p>) and not <label> tags, ensuring they inherit the correct typography tokens without interfering with Shadcn form behaviors.

• [ ] Validate complex UI states (e.g., active, disabled, focus-visible) on form elements for sufficient color contrast.

15. OPEN QUESTIONS

• Are there any legacy pages in the codebase that still rely on standard CSS modules or styled-components that need to be scoped for refactoring?

16. OUT OF SCOPE

• Creating brand new component designs from scratch.

• Modifying backend database logic.

• Ejecting or heavily modifying the internal source code of standard Shadcn components.

17. SUCCESS METRICS

• Codebase Metric: 0 hardcoded color hex codes found in React component files.

• UX Metric: 100% pass rate on Lighthouse Mobile Accessibility and Best Practices scores.

18. DEPENDENCIES

This feature depends on:

• globals.css containing the finalized design tokens.

• Tailwind CSS configuration correctly mapping to those tokens.

• Shadcn UI library installation.

These features depend on this:

• All future frontend modules (Course Builders, Canvas interactions, Reviewer Queue UI).

• Future theming expansions (e.g., introducing a high-contrast mode).

19. TIMELINE & OWNERSHIP

Implemented: Implemented as development continues, to be maintained.
Owner: Jethro Magdaleno Lagmay