From 83dfa9810c386c812aeae4e8af00b1452de4635d Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 22 May 2026 17:39:45 +0000 Subject: [PATCH] feat(docs): expand structured knowledge graph for UI/UX Design * Add "Under the Hood" sections to accessibility, component-architecture, responsive-design, and styling modules. * Add Mermaid diagrams to accessibility, responsive-design, and styling modules. * Ensure all files are alphabetically ordered in navigation index. * Update `_sidebar.md` and `frontend/readme.md` indexes. * Ensure visual scannability. Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com> --- README.md | 12 +++++++ _sidebar.md | 4 +++ frontend/design-ui/accessibility.md | 29 ++++++++++++++- frontend/design-ui/component-architecture.md | 8 ++++- frontend/design-ui/readme.md | 2 ++ frontend/design-ui/responsive-design.md | 29 ++++++++++++++- frontend/design-ui/styling.md | 37 +++++++++++++++++++- frontend/readme.md | 7 ++-- 8 files changed, 120 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 6149a20..c11819d 100644 --- a/README.md +++ b/README.md @@ -212,6 +212,12 @@ graph TD * ⚡ [performance.md](./frontend/angular/performance.md) * 📄 [readme.md](./frontend/angular/readme.md) * 📦 [state-management.md](./frontend/angular/state-management.md) + * 🎨 **[design-ui/](./frontend/design-ui/)** + * ♿ [accessibility.md](./frontend/design-ui/accessibility.md) + * 🏗️ [component-architecture.md](./frontend/design-ui/component-architecture.md) + * 📄 [readme.md](./frontend/design-ui/readme.md) + * 📱 [responsive-design.md](./frontend/design-ui/responsive-design.md) + * 🎨 [styling.md](./frontend/design-ui/styling.md) * 🟨 **[javascript/](./frontend/javascript/)** * 📄 [readme.md](./frontend/javascript/readme.md) * 🟦 **[typescript/](./frontend/typescript/)** @@ -436,6 +442,12 @@ graph TD * ⚡ [performance.md](./frontend/angular/performance.md) * 📄 [readme.md](./frontend/angular/readme.md) * 📦 [state-management.md](./frontend/angular/state-management.md) + * 🎨 **[design-ui/](./frontend/design-ui/)** + * ♿ [accessibility.md](./frontend/design-ui/accessibility.md) + * 🏗️ [component-architecture.md](./frontend/design-ui/component-architecture.md) + * 📄 [readme.md](./frontend/design-ui/readme.md) + * 📱 [responsive-design.md](./frontend/design-ui/responsive-design.md) + * 🎨 [styling.md](./frontend/design-ui/styling.md) * 🟨 **[javascript/](./frontend/javascript/)** * 📄 [readme.md](./frontend/javascript/readme.md) * 🟦 **[typescript/](./frontend/typescript/)** diff --git a/_sidebar.md b/_sidebar.md index 17acc05..34a3623 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -160,7 +160,11 @@ * [Testing](frontend/angular/testing.md) * **Design ui** * [Overview](frontend/design-ui/readme.md) + * [Accessibility](frontend/design-ui/accessibility.md) + * [Component architecture](frontend/design-ui/component-architecture.md) + * [Responsive design](frontend/design-ui/responsive-design.md) * [Styling](frontend/design-ui/styling.md) + * **Javascript** * [Overview](frontend/javascript/readme.md) * [Async logic](frontend/javascript/async-logic.md) diff --git a/frontend/design-ui/accessibility.md b/frontend/design-ui/accessibility.md index e03f550..c6b5333 100644 --- a/frontend/design-ui/accessibility.md +++ b/frontend/design-ui/accessibility.md @@ -25,6 +25,27 @@ This document enforces strict adherence to semantic HTML and accessibility guide --- +## ⚙️ Logic Routing + +```mermaid +flowchart TD + User([User Interaction: Space/Enter]) --> Element{Element Type} + Element -- Semantic HTML --> Browser[Native Browser Handling] + Element -- Generic Wrapper --> JS[Manual JS Event Listeners] + Browser --> Tree[Accessibility Tree] + JS --> Custom[Custom ARIA Logic] + Custom --> Tree + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + class User default; + class Element component; + class Browser component; + class JS component; + class Tree default; + class Custom component; +``` + ## ⚖️ Structural Comparison: Accessibility Paradigms | Paradigm | Interaction Handling | Semantic Clarity | AI Agent Preference | Risk | @@ -53,4 +74,10 @@ Using generic `
` wrappers and artificially attaching ARIA roles or keyboard ### 🚀 Solution -Enforcing **Semantic HTML** is MANDATORY to guarantee deterministic accessibility tree generation. Native elements inherently support keyboard navigation and screen reader parsing without custom JavaScript logic. This STRICTLY eliminates the performance overhead of manual event listener management and mitigates security risks associated with complex, logic-heavy DOM manipulation handlers. \ No newline at end of file +Enforcing **Semantic HTML** is MANDATORY to guarantee deterministic accessibility tree generation. Native elements inherently support keyboard navigation and screen reader parsing without custom JavaScript logic. This STRICTLY eliminates the performance overhead of manual event listener management and mitigates security risks associated with complex, logic-heavy DOM manipulation handlers. + +## ⚙️ Under the Hood + +### 🔍 Edge Cases & Mechanics +- **Shadow DOM Isolation:** When building Web Components, the Shadow DOM encapsulates the accessibility tree. Developers MUST use `delegatesFocus: true` and carefully map `aria-labelledby` across the Shadow boundary to ensure screen readers correctly interpret the isolated component's state. +- **Dynamic Content Injection:** SPA architectures frequently mutate the DOM post-load. Live regions (`aria-live="polite"` or `aria-live="assertive"`) MUST be implemented for dynamically injected content (e.g., toast notifications) to trigger deterministic screen reader announcements without stealing programmatic focus. diff --git a/frontend/design-ui/component-architecture.md b/frontend/design-ui/component-architecture.md index d693efc..47aa095 100644 --- a/frontend/design-ui/component-architecture.md +++ b/frontend/design-ui/component-architecture.md @@ -115,4 +115,10 @@ function UserDashboard() { ### 🚀 Solution -Strictly enforcing **Component Hierarchy** is MANDATORY to establish deterministic boundaries. Decoupled components map to independent rendering lifecycles, enabling focused isolation testing and STRICTLY reducing framework reconciliation overhead compared to monolithic structures. This predictable architecture minimizes the blast radius for performance regressions and mitigates Cross-Site Scripting (XSS) risks by isolating state and rendering contexts. \ No newline at end of file +Strictly enforcing **Component Hierarchy** is MANDATORY to establish deterministic boundaries. Decoupled components map to independent rendering lifecycles, enabling focused isolation testing and STRICTLY reducing framework reconciliation overhead compared to monolithic structures. This predictable architecture minimizes the blast radius for performance regressions and mitigates Cross-Site Scripting (XSS) risks by isolating state and rendering contexts. + +## ⚙️ Under the Hood + +### 🔍 Edge Cases & Mechanics +- **Prop Drilling vs Context Overhead:** While Atomic design encourages passing props down (Tokens -> Elements -> Components), deeply nested layouts suffer from "prop drilling". However, prematurely replacing props with Context API/Signals at the "Element" level triggers global re-renders. State injection MUST be restricted to the "Components" or "Layouts" level to preserve atomic isolation. +- **Hydration Mismatches:** In isomorphic applications, "God Components" that conditionally render based on window objects (e.g., `typeof window !== 'undefined'`) cause severe HTML hydration errors. By splitting layouts into strictly deterministic atomic elements, UI components can render statically, while browser-specific logic is deferred to higher-order wrappers. diff --git a/frontend/design-ui/readme.md b/frontend/design-ui/readme.md index df0b2ad..7c5a566 100644 --- a/frontend/design-ui/readme.md +++ b/frontend/design-ui/readme.md @@ -67,7 +67,9 @@ graph LR B --- C([♿ Accessibility]) C --- D([🏗️ Component Architecture]) + %% Added Design Token Styles for Mermaid Diagrams classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; class A default; class B default; class C default; diff --git a/frontend/design-ui/responsive-design.md b/frontend/design-ui/responsive-design.md index e318949..6951fdd 100644 --- a/frontend/design-ui/responsive-design.md +++ b/frontend/design-ui/responsive-design.md @@ -24,6 +24,27 @@ This document enforces the strict standards for building fluid, universally adap --- --- +## ⚙️ Logic Routing + +```mermaid +flowchart TD + Device{Device Viewport} -->|320px - 767px| Mobile[Base CSS / Mobile] + Device -->|768px - 1023px| Tablet[min-width: 768px] + Device -->|1024px+| Desktop[min-width: 1024px] + + Mobile --> Casc[Cascade Evaluation] + Tablet --> Casc + Desktop --> Casc + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + class Device default; + class Mobile component; + class Tablet component; + class Desktop component; + class Casc default; +``` + ## ⚖️ Structural Comparison: Responsive Paradigms | Paradigm | Default Viewport | Scaling Mechanism | AI Agent Preference | Risk | @@ -70,4 +91,10 @@ A desktop-first approach with absolute units (`px`) often leads to horizontal sc ### 🚀 Solution -Implementing a **Mobile-First Approach** using relative units is MANDATORY. Enforcing base constraints on mobile and dynamically scaling upward STRICTLY limits layout shift (CLS) and reduces the CSS parser's evaluation overhead. This unified cascading structure inherently standardizes deterministic scaling properties, ensuring robust layout performance and mitigating the risk of unpredictable rendering states. \ No newline at end of file +Implementing a **Mobile-First Approach** using relative units is MANDATORY. Enforcing base constraints on mobile and dynamically scaling upward STRICTLY limits layout shift (CLS) and reduces the CSS parser's evaluation overhead. This unified cascading structure inherently standardizes deterministic scaling properties, ensuring robust layout performance and mitigating the risk of unpredictable rendering states. + +## ⚙️ Under the Hood + +### 🔍 Edge Cases & Mechanics +- **Sub-Pixel Rendering Issues:** When using percentage-based widths or fractional `rem` values, browsers calculate sub-pixels. This can cause grid alignment errors or wrapping on certain devices. Using CSS Grid with `fr` units or `calc()` functions with explicit roundings mitigates layout breaking in flex containers. +- **Viewport Height Variations:** On mobile browsers, the URL bar dynamically hides/shows, changing the viewport height. Relying on `100vh` leads to hidden content. Developers MUST use `dvh` (dynamic viewport height) or implement JS workarounds for `vh` variables to ensure bottom-anchored UI components remain visible during scrolling. diff --git a/frontend/design-ui/styling.md b/frontend/design-ui/styling.md index 7e266cc..96c332e 100644 --- a/frontend/design-ui/styling.md +++ b/frontend/design-ui/styling.md @@ -24,6 +24,35 @@ This document enforces the strict styling rules and constraints regarding design --- --- +## ⚙️ Logic Routing + +```mermaid +classDiagram + class DesignTokens { + --color-primary + --spacing-md + --radius-sm + } + class ComponentStyle { + background-color: var(--color-primary) + padding: var(--spacing-md) + } + class ThemeProvider { + Dark Theme Overrides + Light Theme Base + } + + ThemeProvider *-- DesignTokens : Controls + DesignTokens *-- ComponentStyle : Injects + + %% Added Design Token Styles for Mermaid Diagrams + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + class DesignTokens:::component + class ComponentStyle:::default + class ThemeProvider:::component +``` + ## ⚖️ Structural Comparison: Styling Paradigms | Paradigm | Value Definition | Reusability | AI Agent Preference | Risk | @@ -60,4 +89,10 @@ Using hardcoded absolute values (`20px`, hex codes) creates inconsistencies acro ### 🚀 Solution -Strictly utilizing **Design Tokens** is MANDATORY to establish deterministic visual contracts. Constraining styles strictly to these centrally-managed tokens ensures a single source of truth, reducing CSS payload size and standardizing rendering performance. This pattern STRICTLY prevents arbitrary style manipulation, mitigating style-based injection vulnerabilities and enforcing uncompromised environmental immutability for safe AI Agent parsing. \ No newline at end of file +Strictly utilizing **Design Tokens** is MANDATORY to establish deterministic visual contracts. Constraining styles strictly to these centrally-managed tokens ensures a single source of truth, reducing CSS payload size and standardizing rendering performance. This pattern STRICTLY prevents arbitrary style manipulation, mitigating style-based injection vulnerabilities and enforcing uncompromised environmental immutability for safe AI Agent parsing. + +## ⚙️ Under the Hood + +### 🔍 Edge Cases & Mechanics +- **CSS Variable Specificity:** CSS variables inherit down the DOM tree. If a component defines a local token (e.g., `--btn-bg`) but fails to scope it properly, child components might inadvertently inherit and override their own default backgrounds. Strict block-level scoping via BEM or CSS Modules is required. +- **Flash of Unstyled Content (FOUC) in SSR:** When implementing Dark Mode using design tokens via JS-injected classes (e.g., `document.documentElement.classList.add('dark')`), Server-Side Rendered apps (Next.js, Angular Universal) will flash the default light theme before hydration. A blocking inline script MUST be placed in the `` to read local storage and inject the correct class before the body parses. diff --git a/frontend/readme.md b/frontend/readme.md index 991d0b1..a5d2be4 100644 --- a/frontend/readme.md +++ b/frontend/readme.md @@ -95,10 +95,9 @@ This folder acts as a container for documentation around the following technolog - [Qwik](./qwik/readme.md) ## 🎨 UI/UX Design & Styling -- [Styling Rules](./design-ui/styling.md) -- [Responsive Design](./design-ui/responsive-design.md) +- [UI/UX Design Index](./design-ui/readme.md) - [Accessibility](./design-ui/accessibility.md) - [Component Architecture](./design-ui/component-architecture.md) - -- [UI/UX Design Index](./design-ui/readme.md) +- [Responsive Design](./design-ui/responsive-design.md) +- [Styling Rules](./design-ui/styling.md)