docs: remove old implementation docs and setup guides
This commit is contained in:
@@ -0,0 +1,483 @@
|
||||
|
||||
|
||||
# Prompt Windsurf — ObsiViewer Nimbus UI (Desktop + Mobile)
|
||||
|
||||
## 1. Project Overview and Core Philosophy
|
||||
|
||||
### 1.1. Product Philosophy
|
||||
|
||||
The redesign of the ObsiViewer application is guided by a set of core philosophical principles derived from a detailed analysis of the Nimbus Notes interface. These principles are not merely stylistic choices but foundational concepts that dictate the structure, flow, and user experience of the entire application. They ensure that the final product is not only visually similar to Nimbus Notes but also functionally and experientially aligned with its efficient, dense, and rapid workflow. The philosophy emphasizes a workspace-centric model, a dual-axis organizational system, a search-first approach to information retrieval, and a commitment to progressive disclosure to maintain a clean and focused user interface. Furthermore, it acknowledges the modern need for content to exist in multiple contexts, from private notes to public-facing portals, without friction. Adherence to these principles is paramount for achieving a successful and faithful reproduction of the target user experience.
|
||||
|
||||
#### 1.1.1. Workspace-First Architecture
|
||||
|
||||
The foundational principle of the interface is its **workspace-first** architecture. This concept dictates that all content—pages, folders, tags, and even team members—is contained within a strictly isolated and self-contained *workspace*. Switching between workspaces is not a simple global filter applied to a single, monolithic data set; rather, it is a complete context switch, transporting the user into an entirely new and distinct universe of content . This design choice has profound implications for the user experience. It allows for a high degree of organization and separation between different projects, teams, or personal and professional life, preventing the cognitive overload that can arise from a cluttered, undifferentiated information space. The interface must visually and functionally reinforce this separation, making it clear to the user which workspace they are currently operating in. The workspace selector, therefore, becomes a critical navigational element, and its implementation must be robust and easily accessible, as documented in the guides for navigating and managing workspaces . This architecture ensures that the user's mental model aligns perfectly with the application's data structure, leading to a more intuitive and less error-prone interaction.
|
||||
|
||||
#### 1.1.2. Bi-Axial Organization (Folders & Tags)
|
||||
|
||||
Complementing the workspace-first architecture is the **bi-axial organization** system, which employs two distinct but complementary methods for structuring content: **folders** and **tags**. Folders provide a traditional, hierarchical structure, allowing users to create a nested, tree-like organization that reflects a clear parent-child relationship between documents. This is ideal for creating a logical, top-down flow of information, such as organizing project documentation or a personal knowledge base. Tags, in contrast, offer a non-hierarchical, multi-categorical system for adding context and enabling rapid, cross-cutting discovery . A single page can be associated with multiple tags, allowing it to surface in various contexts regardless of its location within the folder hierarchy. For example, a project report could be tagged with `#quarterly-review`, `#marketing-strategy`, and `#client-xyz`, making it instantly discoverable through any of those lenses. The interface must support both systems seamlessly, providing clear visual distinctions and intuitive workflows for managing folders and tags. The guides on folders and tags provide a detailed look into how this dual system is intended to function, balancing rigid structure with flexible, associative context .
|
||||
|
||||
#### 1.1.3. Search-First, Navigate-Second
|
||||
|
||||
A core tenet of the user experience is the **"search first, navigate second"** philosophy. The interface is designed to prioritize rapid information retrieval through a powerful and always-visible search function, relegating manual navigation to a secondary role. The **top bar** is dominated by a large, centered search field, signaling its importance as the primary tool for interacting with the application's content. This is further enhanced by the use of **persistent filter chips**—"All folders," "All tags," and "All pages"—which provide immediate, at-a-glance feedback on the current search context . These chips are not static labels; they are interactive elements that allow users to refine their search scope on the fly without leaving their current workflow. The ability to see, edit, and reset these filters instantly makes the search process transparent and controllable. This approach caters to users who know what they are looking for and need to access it quickly, while still providing robust navigational tools for browsing and discovery. The design minimizes the cognitive load associated with finding information by making the most direct path—the search bar—the most prominent one.
|
||||
|
||||
#### 1.1.4. Progressive Disclosure
|
||||
|
||||
To maintain a clean and uncluttered interface despite the density of information and features, the design relies heavily on the principle of **progressive disclosure**. This strategy involves hiding advanced or less frequently used options until they are explicitly requested by the user. Instead of presenting a wall of controls, the interface reveals functionality contextually and on demand. Examples of this pattern include the **hover-reveal** of the subfolder creation button, which only appears when the user hovers over a parent folder, and the contextual panels like the **folder/tag picker** and the **document outline**, which are summoned via discrete triggers . This approach prevents the user from being overwhelmed by a complex interface, allowing them to focus on their primary task. It creates a sense of simplicity and elegance, even as it provides access to a powerful and feature-rich toolset. The goal is to make the application feel lightweight and approachable for new users while ensuring that power users can access advanced functionality without friction. This careful balance between simplicity and power is a hallmark of a well-designed user experience.
|
||||
|
||||
#### 1.1.5. Content with Multiple Facades (Portals)
|
||||
|
||||
The final philosophical pillar is the concept of **"one content, multiple facades,"** which is embodied by the **Portal** feature. This principle recognizes that a single piece of content, such as a project specification or a client report, often needs to be presented in different contexts with varying levels of access and branding. A page can be edited and managed within the private, internal environment of the ObsiViewer application, but it can also be seamlessly **published to an external, branded Portal** for sharing with clients, stakeholders, or the public . The commands for this action, such as **"Add to portal"** and **"Share,"** are consistently visible within the editor, making the transition from private creation to public dissemination a fluid and integrated part of the workflow . This eliminates the need for cumbersome export/import processes or separate content management systems for external-facing content. The interface must clearly communicate the publication status of a page and provide intuitive controls for managing its visibility and branding, effectively allowing a single source of truth to serve multiple audiences.
|
||||
|
||||
### 1.2. Core Principles for Redesign
|
||||
|
||||
To translate the high-level product philosophy into a concrete and actionable design, a set of eight core principles has been established. These principles serve as a checklist and a guide for every design and implementation decision, ensuring that the final ObsiViewer interface remains faithful to the spirit and functionality of the Nimbus Notes experience. They distill the complex interplay of layout, interaction, and workflow into a memorable and prescriptive set of rules. From the stability of the three-panel layout to the nuanced behavior of stateful filters and the seamless continuum between writing and publishing, these principles provide a clear roadmap for the development team. They are the "TL;DR" of the design specification, capturing the essence of what makes the Nimbus UI both powerful and intuitive.
|
||||
|
||||
#### 1.2.1. Three Stable Panels + Transient Overlays
|
||||
|
||||
The foundational layout of the application is built upon **three stable, persistent panels**: the left sidebar for primary navigation (folders and tags), the central column for the index or search results, and the right panel for the content reader/editor. This three-column structure provides a stable and predictable frame for the user's workflow, ensuring that primary navigational and contextual tools are always visible and accessible on a desktop screen. The stability of these panels creates a strong sense of place and orientation within the application. In contrast to these stable panels, more detailed or temporary interactions are handled through **transient overlays**, such as the floating pickers for folders and tags. These overlays appear on demand, provide a focused interface for a specific task (like filtering), and then disappear, returning the user to the stable three-panel view. This combination of a stable primary layout with transient secondary interactions is key to managing complexity without cluttering the main interface.
|
||||
|
||||
#### 1.2.2. Persistent Stateful Filters (Chips)
|
||||
|
||||
A key interaction pattern that must be meticulously reproduced is the use of **persistent, stateful filters**, visually represented as **chips**. Unlike simple, one-time-use dropdown menus, these chips are always visible in the central panel's header, providing continuous feedback on the current filtering state . They are "stateful" because they display the currently active filters (e.g., a specific folder or tag) and allow for immediate modification or removal. The presence of a **caret (▾)** and a **badge** (e.g., "+1") on these chips clearly communicates that they are interactive menus, not just static labels. This persistent visibility serves as a crucial piece of cognitive anchoring, reminding the user of their current context within the data and allowing them to refine their search without losing their place. The design must ensure these chips are not only visually distinct but also functionally robust, allowing for multi-selection and easy clearing of filters.
|
||||
|
||||
#### 1.2.3. Rich Pickers with Local Search
|
||||
|
||||
When a user interacts with one of the filter chips, they are presented with a **rich picker** interface. These are not standard browser dropdowns but sophisticated, custom-designed overlays that provide a powerful set of tools for selection. A critical feature of these pickers is the inclusion of a **local search bar**, which allows users to quickly find a specific folder or tag within a potentially long list, significantly reducing cognitive load. The pickers also support advanced interactions like multi-selection, with clear visual indicators such as **checkmarks** for tags and hierarchical displays with **chevrons** for nested folders. Furthermore, they include persistent **"Clear" and "Done"** actions at the bottom, giving the user explicit control over the filtering process. This level of richness and functionality in a seemingly simple UI element is a hallmark of the Nimbus design and is essential for creating a fluid and efficient filtering experience.
|
||||
|
||||
#### 1.2.4. Contextual Outline Panel
|
||||
|
||||
For users working with long-form documents, navigation within the page itself is just as important as navigating between pages. The design addresses this with a **contextual outline panel**. This feature is not a permanent fixture of the layout but is instead triggered by a small, round **hamburger button** that appears on the right side of the page content . Clicking this button slides out a docked panel that lists all the headings (H1–H6) in the document. This outline serves as an interactive table of contents, allowing users to click on a heading to instantly scroll to that section of the page. This is a prime example of **progressive disclosure**, where a powerful feature is made available on demand without permanently occupying screen real estate. The implementation must ensure this panel is synchronized with the document's content and provides a smooth, responsive scrolling experience.
|
||||
|
||||
#### 1.2.5. Single, Consistent Creation Action
|
||||
|
||||
To create a predictable and learnable interface, the design mandates a **single, consistent action for creating new content**. This action is embodied by the **"+ Page"** button, which is prominently displayed in the top bar. Regardless of where the user is in the application, this button always performs the same function: it creates a new page within the current context (i.e., the currently selected workspace and folder). This consistency eliminates ambiguity and reduces the cognitive load associated with creating new content. The user does not need to hunt for different "New" buttons in different parts of the interface; they know that the turquoise **"+ Page"** button is always their starting point for creation. This principle of a single, primary call-to-action is a cornerstone of intuitive UI design.
|
||||
|
||||
#### 1.2.6. Strictly Separated Workspaces
|
||||
|
||||
Reinforcing the **workspace-first** philosophy, this principle dictates that **workspaces must be strictly separated**. The UI must make it impossible for a user to accidentally interact with content from one workspace while believing they are in another. The workspace switcher, located in the sidebar footer and avatar menu, must be a deliberate and clear action . The visual design should also reflect this separation, perhaps by subtly changing the accent color or other visual elements when a different workspace is active. This strict separation is crucial for maintaining data integrity and user trust, especially in a multi-user or multi-project environment. It ensures that the isolated universe of each workspace remains truly isolated.
|
||||
|
||||
#### 1.2.7. Bi-Axial Folder/Tag System
|
||||
|
||||
This principle is the practical application of the **bi-axial organization** philosophy. The UI must provide clear, distinct, and equally powerful interfaces for managing both **folders** and **tags**. The left sidebar should present these two organizational systems as separate, top-level categories, allowing users to switch between a hierarchical view (folders) and a flat, categorical view (tags). The filtering system in the central panel must also respect this duality, with separate chips for filtering by folder and by tag. The design must avoid conflating the two systems and instead celebrate their complementary nature, giving users the flexibility to organize their information in the way that best suits their mental model and workflow .
|
||||
|
||||
#### 1.2.8. Omnipresent Share/Portal Actions
|
||||
|
||||
Finally, the design must treat the act of sharing and publishing as a natural extension of the writing process. The commands for **"Share"** and **"Add to portal"** should be **omnipresent** within the editor interface, ensuring that the user can move from creation to dissemination without friction . This creates a **continuum** between writing and publishing. The UI should make it clear what each action does—"Share" for direct link-based sharing, and "Add to portal" for publishing to a branded external space. By keeping these actions always visible, the design encourages a workflow where content is not just created and stored but is actively shared and collaborated upon, fulfilling the promise of "one content, multiple facades."
|
||||
|
||||
## 2. Responsive Design Strategy
|
||||
|
||||
The successful implementation of the Nimbus-like interface for ObsiViewer hinges on a robust and well-defined responsive design strategy. The application must provide an optimal user experience across a wide spectrum of devices, from large desktop monitors to small mobile phones. This requires a deliberate approach to layout, navigation, and component behavior that adapts intelligently to different screen sizes and input methods. The strategy outlined here employs a mobile-first methodology, a set of clearly defined breakpoints using Tailwind CSS, and distinct layout patterns for desktop, tablet, and mobile viewports. The goal is to ensure that the core functionality and user experience are not just preserved but are enhanced and tailored for each device category.
|
||||
|
||||
### 2.1. Breakpoints and Approach
|
||||
|
||||
The foundation of the responsive strategy is a combination of a mobile-first development philosophy and a granular set of breakpoints. This approach ensures that the application is built from the ground up with the constraints and capabilities of mobile devices in mind, and then progressively enhanced for larger screens. This is a departure from the traditional desktop-first approach, which often leads to mobile experiences that feel like a compromised afterthought. By starting with the most restrictive environment, the design is forced to prioritize essential content and functionality, resulting in a cleaner, more focused, and more performant application across all platforms.
|
||||
|
||||
#### 2.1.1. Tailwind Breakpoints (xs, sm, md, lg, xl, 2xl)
|
||||
|
||||
To manage the responsive behavior of the application, a set of standard Tailwind CSS breakpoints will be used. These breakpoints provide a consistent and predictable way to apply different styles and layouts at various screen widths. The chosen breakpoints are designed to cover a wide range of modern devices, from the smallest smartphones to large desktop monitors. The breakpoints are defined as follows:
|
||||
|
||||
| Breakpoint | Screen Width | Typical Device Category |
|
||||
| :--- | :--- | :--- |
|
||||
| `xs` | `320px` | Small phones (e.g., iPhone SE) |
|
||||
| `sm` | `640px` | Large phones, small tablets |
|
||||
| `md` | `768px` | Tablets (e.g., iPad) |
|
||||
| `lg` | `1024px` | Small laptops, desktop |
|
||||
| `xl` | `1280px` | Standard desktop |
|
||||
| `2xl` | `1536px` | Large desktop, wide screens |
|
||||
|
||||
These breakpoints will be used in conjunction with Tailwind's responsive prefixes (e.g., `md:flex`, `lg:hidden`) to create adaptive layouts and components. For example, a three-column layout might be applied at the `lg` breakpoint and above, while a single-column layout with a bottom navigation bar would be used for screens smaller than `lg`. This granular control allows for a highly optimized experience at every screen size.
|
||||
|
||||
#### 2.1.2. Mobile-First Development Approach
|
||||
|
||||
The project will adhere to a **mobile-first** development methodology. This means that the initial development and styling will target the smallest screen sizes (e.g., the `xs` and `sm` breakpoints). The base CSS will be written for the mobile layout, and then media queries will be used to add styles and modify the layout for progressively larger screens (`md`, `lg`, `xl`, etc.). This approach has several key advantages. First, it ensures that the mobile experience is a first-class citizen, not an afterthought. Second, it often leads to cleaner and more maintainable CSS, as the default styles are simple and focused, with complexity added only as needed for larger screens. Third, it can improve performance on mobile devices, as they will download and parse less CSS, avoiding the need to override complex desktop-first styles. This disciplined approach is crucial for delivering a truly responsive and user-friendly application.
|
||||
|
||||
### 2.2. Desktop Layout (≥1024px)
|
||||
|
||||
For desktop and large tablet devices in landscape mode (screen widths of 1024px and above), the application will display a **three-column layout**. This layout is designed to maximize productivity and information density by keeping all primary navigational and contextual elements visible on screen at all times. It provides a stable and powerful workspace for users who are creating, organizing, and consuming large amounts of information. The layout is reminiscent of classic email clients and file managers, providing a familiar and efficient paradigm for power users.
|
||||
|
||||
#### 2.2.1. Three-Column Structure
|
||||
|
||||
The desktop layout is composed of three distinct and persistent columns:
|
||||
|
||||
1. **Left Sidebar (Navigation):** This column, with a default width of 240-440px, contains the primary navigation elements, including Quick Links, the hierarchical folder tree, and the flat list of tags. It provides the main structural overview of the workspace.
|
||||
2. **Center Column (Index/Results):** This is the main content area, which displays the list of pages based on the current folder, tag, or search query. It is a scrollable list of page items, each showing a title, snippet, and metadata.
|
||||
3. **Right Panel (Reader/Editor):** This column displays the content of the currently selected page. It includes the page title, the rich text editor, and the document's action toolbar (e.g., Share, Add to Portal).
|
||||
|
||||
This three-column structure allows users to navigate through their content in the left sidebar, scan a list of relevant pages in the center, and read or edit a specific page on the right, all without having to switch views or lose context. This parallel workflow is highly efficient and is a core tenet of the desktop experience.
|
||||
|
||||
#### 2.2.2. Resizable Sidebar
|
||||
|
||||
To enhance user control and customization, the **left sidebar will be resizable**. Users will be able to click and drag a handle on the right edge of the sidebar to adjust its width within a predefined range (e.g., 240px to 440px). This allows users to tailor the interface to their specific needs and screen size. For example, a user with a very large monitor might want to expand the sidebar to see more of their folder hierarchy, while a user on a smaller laptop might prefer to keep it narrow to maximize the space for the content editor. The resizable functionality will be implemented using a dedicated `resizable-handle` component, which will manage the drag interactions and update the layout dynamically. The user's preferred sidebar width will be persisted in local storage, ensuring a consistent experience across sessions.
|
||||
|
||||
#### 2.2.3. Fixed Right Panel for ToC
|
||||
|
||||
The **Table of Contents (ToC)** for the currently open document will be displayed in a **fixed right panel** on desktop screens. This panel will be docked to the right edge of the viewport, providing a persistent and easily accessible outline of the document's structure. As the user scrolls through the document, the ToC will remain visible, allowing them to quickly jump between sections by clicking on the corresponding headings. This fixed positioning is a key feature for users working with long and complex documents, as it provides constant orientation and facilitates rapid navigation within the page. The ToC panel will be implemented as a separate component that can be shown or hidden based on the presence of headings in the document and user preference. This design choice reinforces the desktop paradigm of providing multiple, persistent views to support complex workflows.
|
||||
|
||||
### 2.3. Tablet Layout (768px ≤ width < 1024px)
|
||||
|
||||
For tablet devices and smaller desktop windows (screen widths between 768px and 1023px), the three-column desktop layout is no longer practical due to space constraints. To adapt to this intermediate screen size, the application will switch to a **tab-based navigation system**. This approach maintains access to all the core features of the application but organizes them into a series of full-screen panels that the user can switch between. This ensures that each view has enough space to be usable and readable, while the tab-based navigation provides a clear and intuitive way to move between different parts of the application.
|
||||
|
||||
#### 2.3.1. Tab-Based Navigation
|
||||
|
||||
Instead of displaying all three columns simultaneously, the tablet layout will use a system of tabs to switch between the main functional areas of the application. The primary tabs will be:
|
||||
|
||||
* **Sidebar:** This tab will display the full-width navigation panel, including folders and tags.
|
||||
* **List:** This tab will show the central index or search results list.
|
||||
* **Page:** This tab will display the full-width content reader/editor.
|
||||
* **ToC:** This tab will show the document's Table of Contents.
|
||||
|
||||
This tabbed interface allows the application to dedicate the entire screen to one task at a time, which is more appropriate for the smaller screen real estate of a tablet. The user can tap on a tab to instantly switch to that view, providing a fast and fluid navigation experience.
|
||||
|
||||
#### 2.3.2. Bottom Navigation Bar
|
||||
|
||||
To provide easy access to the primary tabs, a **fixed bottom navigation bar** will be displayed at all times. This bar will contain icons for the main tabs (e.g., Sidebar, List, Page, ToC), allowing the user to switch views with a single tap. The bottom navigation pattern is a standard and highly usable convention on mobile and tablet devices, as it places the primary navigation within easy reach of the user's thumbs. The active tab will be visually highlighted to provide clear feedback on the current view. This persistent navigation bar ensures that the user is never more than one tap away from the main sections of the application.
|
||||
|
||||
#### 2.3.3. Drawer for Sidebar
|
||||
|
||||
When the user is on the **List** or **Page** tab, the **Sidebar** will be accessible via a **drawer** that slides in from the left side of the screen. This drawer will overlay the current content and can be opened by tapping a menu icon in the top navigation bar. The drawer will contain the full folder and tag navigation, allowing the user to change their context without having to navigate to the dedicated Sidebar tab. This provides a quick and convenient way to switch folders or tags while remaining focused on their current task. The drawer can be dismissed by tapping outside of it or by swiping it away, returning the user to their previous view. This hybrid approach of using both tabs and a drawer provides a flexible and efficient navigation system for the tablet form factor.
|
||||
|
||||
### 2.4. Mobile Layout (<768px)
|
||||
|
||||
For mobile phones (screen widths below 768px), the design must be further simplified to accommodate the smallest screens and touch-based interactions. The application will adopt a **full-screen, single-tasking model**, where each functional area occupies the entire viewport. Navigation will be handled primarily through a **bottom navigation bar** with four distinct tabs, providing a clear and thumb-friendly way to switch between the main features of the app. The goal is to provide a focused and uncluttered experience that is optimized for on-the-go use.
|
||||
|
||||
#### 2.4.1. Bottom Navigation with 4 Tabs
|
||||
|
||||
The primary navigation on mobile will be a **bottom navigation bar with four tabs**. These tabs will provide direct access to the core functions of the application:
|
||||
|
||||
1. **☰ (Menu):** This tab will open the sidebar drawer, providing access to folders and tags.
|
||||
2. **🔍 (Search):** This tab will focus on the search bar and display search results.
|
||||
3. **📄 (Page):** This tab will display the content of the currently selected page.
|
||||
4. **📋 (ToC):** This tab will show the Table of Contents for the current page.
|
||||
|
||||
This four-tab layout provides a clear and logical grouping of features, ensuring that the most common tasks are always just one tap away. The use of standard icons makes the navigation immediately understandable to users familiar with mobile app conventions.
|
||||
|
||||
#### 2.4.2. Full-Width Content Panels
|
||||
|
||||
In the mobile layout, each of the main content areas will occupy the **full width of the screen**. This provides maximum readability and touch-target size for each element. The **sidebar** will be presented as a **drawer** that slides in from the left, covering most of the screen. The **search results list** will be a vertically scrollable list of full-width items. The **page viewer** will also be full-width, with the content optimized for mobile reading (e.g., appropriate font sizes, line heights, and image scaling). This single-tasking approach prevents the interface from feeling cramped and ensures that the user's attention is focused on one thing at a time.
|
||||
|
||||
#### 2.4.3. Inline/Collapsible ToC
|
||||
|
||||
On mobile, the **Table of Contents (ToC)** will not be a persistent panel due to space constraints. Instead, it will be implemented as an **inline, collapsible section** within the page content itself. A button, likely fixed to the bottom-right of the screen, will allow the user to toggle the visibility of the ToC. When opened, the ToC will appear as a list of links within the page, pushing the content down. Alternatively, it could be implemented as a modal or a bottom sheet that slides up from the bottom of the screen. This approach makes the ToC accessible on mobile without sacrificing valuable screen real estate, providing a practical solution for navigating long documents on a small screen.
|
||||
|
||||
## 3. Feature Flag and UI Toggle Implementation
|
||||
|
||||
To ensure a smooth transition and allow for user choice, the new Nimbus-like UI will be introduced behind a **feature flag**. This allows the legacy interface to remain fully functional while the new design is being developed and tested. A prominent toggle in the application's navbar will allow users to switch between the two UIs at any time, with their preference being persisted across sessions. This architecture is critical for managing risk, gathering user feedback, and ensuring a zero-regression deployment.
|
||||
|
||||
### 3.1. UI Mode Service
|
||||
|
||||
The core of the feature flag system is a dedicated Angular service, `UiModeService`, which will manage the application's UI state. This service will use Angular's new `signal` API for fine-grained reactivity, ensuring that components update instantly when the UI mode changes. It will also handle the persistence of the user's choice using the browser's `localStorage`.
|
||||
|
||||
#### 3.1.1. Signal-Based State Management
|
||||
|
||||
The `UiModeService` will utilize an Angular `signal` to hold the current UI mode. Signals are a new primitive in Angular that provide a simpler and more performant way to manage state compared to traditional RxJS observables for simple boolean flags. When the `toggleUIMode()` method is called, it will update the signal's value, which will automatically trigger re-rendering in any component that depends on it. This approach minimizes unnecessary change detection cycles and leads to a more responsive user interface.
|
||||
|
||||
#### 3.1.2. localStorage Persistence
|
||||
|
||||
To provide a seamless user experience, the selected UI mode must be remembered between sessions. The `UiModeService` will achieve this by saving the user's choice to `localStorage` whenever the mode is toggled. When the application is first loaded, the service will check `localStorage` for a saved preference. If one exists, it will initialize the signal with that value; otherwise, it will default to the new Nimbus mode. This ensures that users only have to make the choice once, and their preference will be respected every time they use the application.
|
||||
|
||||
### 3.2. Adaptive Layout Wrapper
|
||||
|
||||
A new top-level component, `AppShellAdaptiveComponent`, will act as a wrapper or router for the two different layout shells. This component will be responsible for conditionally rendering either the `AppShellNimbusLayoutComponent` (the new UI) or the `AppShellLegacyLayoutComponent` (the old UI) based on the current state of the `UiModeService`.
|
||||
|
||||
#### 3.2.1. Conditional Rendering of Layouts
|
||||
|
||||
The `AppShellAdaptiveComponent` will use Angular's `@if` block to render the appropriate layout component. It will inject the `UiModeService` and read the `isNimbusMode` signal. The template will be a simple conditional statement that displays one layout or the other. This clean separation ensures that the logic for choosing a UI is contained in a single place and that the two layout components remain decoupled and independent of each other.
|
||||
|
||||
#### 3.2.2. Integration with UiModeService
|
||||
|
||||
The `AppShellAdaptiveComponent` will be the primary consumer of the `UiModeService`. By injecting the service and reading its signal, it will react to any changes in the UI mode. When a user clicks the toggle button in the navbar, the `UiModeService` updates its signal, which in turn causes the `AppShellAdaptiveComponent` to re-render and switch the entire application layout. This reactive flow is efficient and easy to reason about, forming the backbone of the feature flag implementation.
|
||||
|
||||
### 3.3. Navbar Toggle Button
|
||||
|
||||
The user-facing control for the feature flag will be a button placed in the main application navbar. This button will be clearly labeled to indicate its function and will provide immediate visual feedback on the current UI mode.
|
||||
|
||||
#### 3.3.1. Visual Indication of Current Mode
|
||||
|
||||
The toggle button's label will change dynamically to reflect the current state. When the Nimbus UI is active, the button might display "🔧 Legacy" to indicate that clicking it will switch to the legacy UI. Conversely, when the legacy UI is active, the button might show "✨ Nimbus" to indicate the option to switch to the new design. This clear, contextual labeling removes any ambiguity about what the button will do.
|
||||
|
||||
#### 3.3.2. State-Switching Logic
|
||||
|
||||
The button's `(click)` event will be bound to a method in the navbar component that simply calls `uiModeService.toggleUIMode()`. This method will handle all the logic of flipping the signal and persisting the new state to `localStorage`. The navbar component itself does not need to contain any complex logic; it just acts as a trigger for the service, keeping the component's code clean and focused on its primary responsibility of navigation.
|
||||
|
||||
## 4. Component Architecture and Responsiveness
|
||||
|
||||
To manage the complexity of a fully responsive application, a clear and scalable component architecture is required. The strategy involves creating distinct component variants for desktop and mobile views, while sharing common logic. This is combined with a dynamic injection mechanism that loads the appropriate variant based on the current screen size, detected using Angular's CDK utilities.
|
||||
|
||||
### 4.1. Desktop/Mobile Component Variants
|
||||
|
||||
Instead of creating monolithic components with complex, inline responsive logic, the design promotes the creation of separate, specialized components for different screen sizes. This leads to cleaner, more maintainable code and allows each variant to be optimized for its specific context.
|
||||
|
||||
#### 4.1.1. Shared Logic Components
|
||||
|
||||
For each major feature (e.g., sidebar, search bar, note view), a base component will be created to encapsulate the shared logic and state. This component will not have a template of its own but will instead be responsible for managing data, handling business logic, and determining which of its child variants (desktop or mobile) should be displayed. This separation of concerns ensures that logic is not duplicated between the desktop and mobile versions of a component.
|
||||
|
||||
#### 4.1.2. Desktop-Specific Components (Fixed, Resizable)
|
||||
|
||||
For the desktop view (≥1024px), components will be designed to take advantage of the larger screen real estate. For example, the `app-left-sidebar.desktop.component.ts` will implement a fixed, resizable panel. These components will use CSS layouts like Flexbox or Grid to create the stable, multi-column structure. Their styling will be optimized for mouse and keyboard interaction, with hover states and precise click targets.
|
||||
|
||||
#### 4.1.3. Mobile-Specific Components (Drawer, Inline)
|
||||
|
||||
For the mobile view (<1024px), components will be designed for touch interaction and smaller screens. The `app-left-sidebar.mobile.component.ts`, for instance, will implement a drawer that slides in from the side. These components will use full-width layouts and larger touch targets. Animations and transitions will be used to provide feedback and create a fluid, app-like feel. The logic within these components will be tailored to the mobile interaction model, such as handling swipe gestures for dismissal.
|
||||
|
||||
### 4.2. Breakpoint Detection and Injection
|
||||
|
||||
The mechanism for switching between desktop and mobile variants will be handled by the shared logic component. It will use Angular's CDK to observe screen size changes and dynamically inject the correct variant into the view.
|
||||
|
||||
#### 4.2.1. Using Angular CDK BreakpointObserver
|
||||
|
||||
The `BreakpointObserver` from `@angular/cdk/layout` is the ideal tool for this task. The shared logic component will inject this service and use it to create an observable stream that emits a boolean value indicating whether the screen width is above or below a certain threshold (e.g., `Breakpoints.Large` for 1024px). This provides a clean, reactive way to respond to changes in viewport size.
|
||||
|
||||
#### 4.2.2. Dynamic Component Injection with `ngComponentOutlet`
|
||||
|
||||
Based on the boolean value from the `BreakpointObserver`, the shared logic component's template will use Angular's `ngComponentOutlet` directive to dynamically render the appropriate variant. The template will contain an `@if` block that checks the breakpoint state and then uses `*ngComponentOutlet` to inject either the desktop or mobile component. This powerful technique allows for a completely different component tree to be rendered for different screen sizes, providing the ultimate flexibility in responsive design.
|
||||
|
||||
## 5. Mobile Navigation and Gestures
|
||||
|
||||
The mobile experience is defined by its navigation patterns and touch-based interactions. To create an intuitive and efficient mobile app, the design incorporates a tab-based system, swipe navigation, and other touch-friendly gestures. These elements are managed by dedicated services and directives to keep the logic clean and reusable.
|
||||
|
||||
### 5.1. Tab/Drawer Navigation System
|
||||
|
||||
On mobile and tablet devices, the primary navigation will be handled by a system of tabs and drawers. This replaces the persistent three-column layout of the desktop with a more space-efficient, single-tasking model.
|
||||
|
||||
#### 5.1.1. MobileNavService for State Management
|
||||
|
||||
A `MobileNavService` will be created to manage the state of the mobile navigation. This service will use an Angular `signal` to track the currently active tab (e.g., 'sidebar', 'list', 'page', 'toc'). Other components, such as the `BottomNavComponent`, will inject this service to read the current state and to update it when the user interacts with the navigation. This centralized state management ensures that the navigation UI remains consistent and synchronized across the application.
|
||||
|
||||
#### 5.1.2. BottomNavComponent Implementation
|
||||
|
||||
The `BottomNavComponent` will be a sticky navigation bar fixed to the bottom of the screen on mobile devices. It will display icons for the four primary tabs. The component will read the active tab from the `MobileNavService` to highlight the correct icon. When a user taps an icon, the component will call a method on the service to update the active tab, which will in turn trigger a re-render of the main content area to show the corresponding view.
|
||||
|
||||
### 5.2. Swipe Navigation
|
||||
|
||||
To enhance the mobile experience and make navigation feel more fluid, horizontal swipe gestures will be supported for switching between tabs.
|
||||
|
||||
#### 5.2.1. SwipeNavDirective for Gesture Detection
|
||||
|
||||
A custom directive, `SwipeNavDirective`, will be created to encapsulate the logic for detecting swipe gestures. This directive will use `@HostListener` to listen for `touchstart` and `touchend` events on a host element. By comparing the start and end coordinates of the touch, it can determine the direction of the swipe.
|
||||
|
||||
#### 5.2.2. Horizontal Swipe for Tab Switching
|
||||
|
||||
The `SwipeNavDirective` will be applied to the main content area. When a swipe is detected, it will emit an event (e.g., `swipeLeft` or `swipeRight`). A parent component will listen for these events and use the `MobileNavService` to switch to the next or previous tab in the sequence. This provides a natural and intuitive way for users to navigate the application, mirroring the behavior of many native mobile apps.
|
||||
|
||||
### 5.3. Touch-Friendly Interactions
|
||||
|
||||
Beyond basic navigation, other touch-friendly interactions will be implemented to improve usability on mobile devices.
|
||||
|
||||
#### 5.3.1. Long-Press for Context Menus
|
||||
|
||||
A long-press gesture on items in a list (e.g., a page in the search results) will trigger a context menu. This menu will provide quick access to common actions like "Favorite," "Delete," or "Open in New Tab." This is a standard mobile pattern that provides power-user functionality without cluttering the main interface.
|
||||
|
||||
#### 5.3.2. Pull-to-Refresh (Optional)
|
||||
|
||||
As an optional enhancement, a pull-to-refresh gesture could be implemented on scrollable lists. This would allow users to manually trigger a refresh of the data, which is a common and expected behavior in mobile applications. This would likely be implemented using a third-party library or a custom directive that listens for scroll events and detects the "pull" gesture.
|
||||
|
||||
## 6. Mobile-First Component Specifications
|
||||
|
||||
To ensure a high-quality mobile experience, each component must be designed and built with a mobile-first mindset. This section provides detailed specifications for key mobile components, including their layout, styling, and behavior.
|
||||
|
||||
### 6.1. Bottom Navigation (Mobile)
|
||||
|
||||
The bottom navigation bar is the primary means of navigation on mobile and must be robust and user-friendly.
|
||||
|
||||
#### 6.1.1. Fixed Positioning and Styling
|
||||
|
||||
The `BottomNavComponent` will be fixed to the bottom of the viewport using `position: fixed`. It will have a solid background color to ensure it is always visible and legible, even when scrolling through content. It will use Flexbox to evenly distribute the tab buttons across its width. The styling will be simple and clean, with a top border to visually separate it from the content area.
|
||||
|
||||
#### 6.1.2. Active State Indication
|
||||
|
||||
The currently active tab must be clearly indicated. This will be achieved by changing the color of the icon and label for the active button. A subtle background color change on the active button could also be used to provide additional visual feedback. This state will be driven by the `activeTab` signal from the `MobileNavService`.
|
||||
|
||||
### 6.2. Drawer Sidebar (Mobile)
|
||||
|
||||
The sidebar drawer provides access to the main navigation (folders and tags) without leaving the current context.
|
||||
|
||||
#### 6.2.1. Animated Slide-In/Out
|
||||
|
||||
The drawer will be implemented as a `fixed` position element that is initially translated off-screen. When opened, a CSS transition will be used to animate its `transform` property, causing it to slide in smoothly from the left. The same animation will be used in reverse when the drawer is closed. This provides a clear and fluid visual cue to the user.
|
||||
|
||||
#### 6.2.2. Backdrop for Dismissal
|
||||
|
||||
When the drawer is open, a semi-transparent backdrop will be displayed over the main content. This backdrop serves two purposes: it visually de-emphasizes the background content, focusing the user's attention on the drawer, and it provides a large tap target to dismiss the drawer. Clicking on the backdrop will trigger the close animation and hide the drawer.
|
||||
|
||||
### 6.3. Compact Search Bar (Mobile)
|
||||
|
||||
The search bar on mobile needs to be compact yet powerful, providing access to search and filtering without taking up too much vertical space.
|
||||
|
||||
#### 6.3.1. Integrated Menu Toggle
|
||||
|
||||
The mobile search bar will be a single, integrated component that includes a button to toggle the sidebar drawer. This button will be placed on the left side of the search input field, providing a clear and consistent way to access the main navigation.
|
||||
|
||||
#### 6.3.2. Horizontally Scrollable Filter Badges
|
||||
|
||||
When filters are active, they will be displayed as small "chips" or badges below the search input. On mobile, where horizontal space is limited, this row of badges will be horizontally scrollable. This allows the user to see all active filters without the row wrapping and taking up too much vertical space. Each badge will also have a small "x" icon to allow for quick removal of individual filters.
|
||||
|
||||
### 6.4. Optimized Result List Item (Mobile)
|
||||
|
||||
Each item in the search results list must be designed for clarity and easy interaction on a small screen.
|
||||
|
||||
#### 6.4.1. Stacked Layout for Title, Date, and Tags
|
||||
|
||||
On mobile, the layout for each list item will be a stacked, vertical layout. The page title will be at the top, followed by a line containing the last modified date, and then a row of tags. This vertical stacking ensures that each piece of information is readable without horizontal scrolling.
|
||||
|
||||
#### 6.4.2. Truncated Excerpt with `line-clamp`
|
||||
|
||||
A short excerpt of the page's content will be displayed below the metadata. To prevent this excerpt from taking up too much space, its height will be limited using the CSS `line-clamp` property. This will truncate the text after a specified number of lines (e.g., 2 or 3) and add an ellipsis to indicate that the text has been cut off.
|
||||
|
||||
### 6.5. Responsive Markdown Viewer
|
||||
|
||||
The markdown content viewer must be responsive and provide a comfortable reading experience on any screen size.
|
||||
|
||||
#### 6.5.1. Mobile-First Prose Styling
|
||||
|
||||
The styling for the rendered markdown will be mobile-first. Base font sizes, line heights, and margins will be optimized for small screens. Tailwind's `prose` plugin will be used, with responsive variants like `prose-sm` for mobile and `prose-base` for larger screens, to ensure that the typography is always readable and well-proportioned.
|
||||
|
||||
#### 6.5.2. Inline ToC Toggle Button
|
||||
|
||||
As specified in the responsive strategy, the Table of Contents on mobile will not be a persistent panel. Instead, a floating action button (FAB) will be displayed in the bottom-right corner of the screen when the document has headings. Tapping this button will toggle the visibility of an inline ToC that appears within the document flow.
|
||||
|
||||
### 6.6. Adaptive ToC Drawer
|
||||
|
||||
The ToC component itself must adapt its behavior and appearance based on the screen size.
|
||||
|
||||
#### 6.6.1. Desktop: Fixed Right Panel
|
||||
|
||||
On desktop (≥1024px), the `app-toc-drawer` component will render a fixed panel on the right side of the screen. This panel will be styled with a distinct background color and a left border to separate it from the main content. It will be vertically scrollable if the list of headings is long.
|
||||
|
||||
#### 6.6.2. Mobile: Collapsible Inline Section with Animation
|
||||
|
||||
On mobile (<1024px), the same `app-toc-drawer` component will render a collapsible section that is inserted into the main content flow. The component will use an Angular animation trigger to smoothly animate the opening and closing of this section, animating its height from 0 to its full size. This provides a fluid and polished user experience.
|
||||
|
||||
## 7. Performance and Mobile Optimizations
|
||||
|
||||
A great user experience on mobile is heavily dependent on performance. The application must be fast to load, smooth to scroll, and responsive to user input. This section outlines key performance optimizations that will be implemented, with a focus on achieving high scores in tools like Google Lighthouse.
|
||||
|
||||
### 7.1. Critical Rendering Optimizations
|
||||
|
||||
Several techniques will be used to optimize the critical rendering path and improve perceived performance.
|
||||
|
||||
#### 7.1.1. Lazy-Loading Images
|
||||
|
||||
All images, including those in markdown content and bookmark cards, will be lazy-loaded. This is achieved by adding the `loading="lazy"` attribute to `<img>` tags. This tells the browser to defer loading the image until it is about to enter the viewport, significantly reducing the initial page load time and data usage.
|
||||
|
||||
#### 7.1.2. Virtual Scrolling for Long Lists
|
||||
|
||||
For lists that can contain a large number of items (e.g., the search results list), a virtual scrolling technique will be used. The Angular CDK's `VirtualScrollViewport` is an excellent tool for this. It works by only rendering the items that are currently visible in the viewport, plus a small buffer. As the user scrolls, it dynamically recycles and re-renders the items, keeping the DOM size small and ensuring smooth 60fps scrolling even with thousands of items.
|
||||
|
||||
#### 7.1.3. Debounced Search Input
|
||||
|
||||
To avoid firing a search request on every single keystroke, the search input field will be debounced. This means that the search function will only be executed after the user has stopped typing for a short period (e.g., 300ms on mobile, 150ms on desktop). This reduces the number of API calls and prevents the UI from becoming sluggish due to rapid, unnecessary re-rendering of search results.
|
||||
|
||||
### 7.2. Lighthouse Mobile Targets
|
||||
|
||||
Google Lighthouse provides a comprehensive audit of a web application's performance, accessibility, and best practices. The goal is to achieve high scores across the board, with a particular focus on the mobile audit.
|
||||
|
||||
#### 7.2.1. Performance Score ≥ 85
|
||||
|
||||
A performance score of 85 or higher on the mobile audit is the target. This will be achieved by implementing the optimizations listed above, as well as other best practices like minifying code, compressing assets, and using a content delivery network (CDN). The performance budget will be monitored throughout the development process.
|
||||
|
||||
#### 7.2.2. Accessibility Score ≥ 95
|
||||
|
||||
An accessibility score of 95 or higher is the target. This will be achieved by following the WCAG 2.1 AA guidelines, as detailed in the next section. This includes ensuring sufficient color contrast, providing alternative text for images, and making the application fully navigable with a keyboard.
|
||||
|
||||
#### 7.2.3. Best Practices Score ≥ 90
|
||||
|
||||
A best practices score of 90 or higher is the target. This audit checks for common web development pitfalls, such as using deprecated APIs, having security vulnerabilities, or not using HTTPS. Adhering to modern web standards and security best practices will ensure a high score in this category.
|
||||
|
||||
## 8. Accessibility and Usability
|
||||
|
||||
An accessible application is a usable application. The redesign will prioritize accessibility from the start, ensuring that the ObsiViewer is usable by as many people as possible, regardless of their abilities or the devices they use.
|
||||
|
||||
### 8.1. WCAG 2.1 AA Compliance
|
||||
|
||||
The Web Content Accessibility Guidelines (WCAG) 2.1 provide a comprehensive set of recommendations for making web content more accessible. The goal is to meet the **AA** level of conformance.
|
||||
|
||||
#### 8.1.1. Sufficient Color Contrast
|
||||
|
||||
All text and interactive elements must have a color contrast ratio of at least **4.5:1** against their background. For large text (18pt or 14pt bold), the ratio can be 3:1. This ensures that text is readable for users with low vision or color blindness. Tools will be used during development to check contrast ratios for all color combinations in both light and dark themes.
|
||||
|
||||
#### 8.1.2. Visible Focus Indicators
|
||||
|
||||
All interactive elements (links, buttons, form inputs) must have a visible focus indicator when they are navigated to using the keyboard (e.g., with the Tab key). This is typically a visible outline or border. This is crucial for keyboard-only users to know which element currently has focus.
|
||||
|
||||
#### 8.1.3. Zoom Compatibility (≤200%)
|
||||
|
||||
The application must remain fully functional and usable when the browser's zoom level is increased up to **200%**. This means that the layout should reflow appropriately, and horizontal scrolling should be avoided. This is a key requirement for users with low vision who rely on browser zoom to read content.
|
||||
|
||||
### 8.2. Keyboard Navigation
|
||||
|
||||
The application must be fully navigable and operable using only a keyboard.
|
||||
|
||||
#### 8.2.1. Complete Tab Navigation
|
||||
|
||||
All interactive elements must be reachable and operable using the Tab key to move forward and Shift+Tab to move backward through the interface. The tab order must be logical and follow the visual flow of the page.
|
||||
|
||||
#### 8.2.2. Keyboard Shortcuts for Common Actions
|
||||
|
||||
To improve efficiency for power users, keyboard shortcuts will be provided for common actions. For example, `Ctrl/Cmd + K` could open a command palette, and `Ctrl/Cmd + F` could focus the search bar. These shortcuts will be documented and discoverable.
|
||||
|
||||
### 8.3. Touch Accessibility
|
||||
|
||||
On mobile devices, touch targets must be large enough and well-spaced to be easily and accurately tapped.
|
||||
|
||||
#### 8.3.1. Minimum Touch Target Size (44x44px)
|
||||
|
||||
All interactive elements, such as buttons and links, should have a touch target size of at least **44x44 pixels**. This is the recommended minimum size by both Apple and Google to ensure that elements can be easily tapped without accidentally hitting adjacent targets.
|
||||
|
||||
#### 8.3.2. Descriptive ARIA Labels
|
||||
|
||||
For elements that are not clearly labeled with text (e.g., icon buttons), a descriptive `aria-label` attribute must be provided. This label is read by screen readers, providing context to users who cannot see the visual icon. This is essential for making the application's functionality understandable to users with visual impairments.
|
||||
|
||||
## 9. Implementation Plan and Deliverables
|
||||
|
||||
The project will be executed in a series of phases, with clear deliverables for each stage. This structured approach ensures that the project stays on track and that progress can be measured and reviewed.
|
||||
|
||||
### 9.1. Phased Implementation Schedule
|
||||
|
||||
The implementation will be broken down into three main phases, with an estimated timeline of 13-21 days for a single frontend engineer.
|
||||
|
||||
#### 9.1.1. Phase 1: Feature Flag and Responsive Shell (3-5 days)
|
||||
|
||||
This initial phase focuses on building the foundational architecture. It includes implementing the `UiModeService`, the `AppShellAdaptiveComponent`, and the navbar toggle button. It also involves setting up the Tailwind breakpoints and creating the basic three-column responsive shell for the desktop layout.
|
||||
|
||||
#### 9.1.2. Phase 2: Mobile Navigation and Components (7-10 days)
|
||||
|
||||
This phase is dedicated to building out the mobile experience. It includes creating the `MobileNavService`, the `BottomNavComponent`, and the swipe navigation directive. It also involves developing the mobile-specific variants of key components like the sidebar drawer, the compact search bar, and the optimized result list items.
|
||||
|
||||
#### 9.1.3. Phase 3: Gestures, Accessibility, and Testing (3-6 days)
|
||||
|
||||
The final phase focuses on polishing the user experience and ensuring quality. It includes implementing advanced gestures like long-press menus, conducting a full accessibility audit to meet WCAG 2.1 AA standards, and writing end-to-end and visual regression tests. It also includes creating the required documentation.
|
||||
|
||||
### 9.2. Code Deliverables
|
||||
|
||||
The primary output of the project will be the source code for the new features and components.
|
||||
|
||||
#### 9.2.1. UI Mode Service and Toggle
|
||||
|
||||
This includes the `UiModeService` for state management, the `AppShellAdaptiveComponent` for layout switching, and the toggle button integrated into the navbar.
|
||||
|
||||
#### 9.2.2. Responsive Component Wrappers
|
||||
|
||||
This includes the shared logic components for the sidebar, search bar, and note view, which are responsible for dynamically injecting their desktop or mobile variants.
|
||||
|
||||
#### 9.2.3. Mobile-Specific Components and Directives
|
||||
|
||||
This includes all the mobile-first components, such as the `BottomNavComponent`, the drawer sidebar, the compact search bar, and the `SwipeNavDirective`.
|
||||
|
||||
### 9.3. Documentation and Testing
|
||||
|
||||
High-quality documentation and a comprehensive test suite are essential for the long-term maintainability and success of the project.
|
||||
|
||||
#### 9.3.1. README_UI.md, MOBILE_GUIDE.md, RESPONSIVE_CHECKLIST.md
|
||||
|
||||
Three key documentation files will be created:
|
||||
* `README_UI.md`: An overview of the new UI architecture, including screenshots of the three main breakpoints.
|
||||
* `MOBILE_GUIDE.md`: A detailed guide to the mobile navigation patterns, gestures, and component behaviors.
|
||||
* `RESPONSIVE_CHECKLIST.md`: A checklist for testing the application's responsiveness and functionality across different devices and screen sizes.
|
||||
|
||||
#### 9.3.2. E2E and Visual Regression Tests
|
||||
|
||||
End-to-end tests will be written to cover critical user flows, such as toggling the UI, navigating on mobile, and performing searches. Visual regression tests will be implemented to automatically detect any unintended changes to the UI's appearance across the desktop, tablet, and mobile layouts.
|
||||
|
||||
#### 9.3.3. Accessibility Audit Checklist
|
||||
|
||||
A final checklist will be created to document the results of the accessibility audit, confirming that all WCAG 2.1 AA criteria have been met. This will serve as a record of compliance and a guide for future development.
|
||||
+1487
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user