From 5298986506f10f5cc44943dac0c157ed446893cb Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 19 May 2026 17:40:18 +0000 Subject: [PATCH] feat(frontend): initialize structured documentation for UI Animation style(ui): enforce deterministic Best-Practise standard in Design UI docs chore(nav): optimize internal connectivity between structured modules Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com> --- _sidebar.md | 6 +- frontend/design-ui/accessibility.md | 18 +++- frontend/design-ui/animation-performance.md | 99 ++++++++++++++++++++ frontend/design-ui/component-architecture.md | 7 +- frontend/design-ui/readme.md | 1 + frontend/design-ui/responsive-design.md | 20 +++- frontend/design-ui/styling.md | 25 ++++- 7 files changed, 171 insertions(+), 5 deletions(-) create mode 100644 frontend/design-ui/animation-performance.md diff --git a/_sidebar.md b/_sidebar.md index 17acc05..592db99 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -160,7 +160,11 @@ * [Testing](frontend/angular/testing.md) * **Design ui** * [Overview](frontend/design-ui/readme.md) - * [Styling](frontend/design-ui/styling.md) + * [Accessibility (a11y) standards](frontend/design-ui/accessibility.md) + * [Animation & performance optimization](frontend/design-ui/animation-performance.md) + * [Responsive & adaptive design principles](frontend/design-ui/responsive-design.md) + * [Ui component architecture](frontend/design-ui/component-architecture.md) + * [Ui/ux styling & design tokens rules](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..a2f9bac 100644 --- a/frontend/design-ui/accessibility.md +++ b/frontend/design-ui/accessibility.md @@ -53,4 +53,20 @@ 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. + +```mermaid +graph LR + A([Semantic HTML]) --> B([DOM Tree]) + B --> C([Accessibility Tree]) + C --> D([Assistive Tech]) + E([Non-Semantic HTML]) -.->|Manual ARIA/JS| C + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + class A,B,C,D,E default; +``` + +### ⚙️ Under the Hood: Edge Cases & Mechanics +- **Dynamic Content:** For Single Page Applications (SPAs), dynamically injected content must be announced to screen readers. Elements containing such content MUST utilize `aria-live` attributes (`polite` or `assertive`) to trigger deterministic re-evaluation of the accessibility tree. +- **Focus Trapping:** When implementing complex interactive components like modals, focus MUST be strictly trapped within the component bounds until it is explicitly dismissed. This prevents keyboard users from interacting with occluded background elements. +- **Contrast Ratios:** Text must maintain a minimum contrast ratio of `4.5:1` against its background (WCAG AA). Agents should verify this ratio analytically during generation rather than relying on visual approximations. \ No newline at end of file diff --git a/frontend/design-ui/animation-performance.md b/frontend/design-ui/animation-performance.md new file mode 100644 index 0000000..cbd5614 --- /dev/null +++ b/frontend/design-ui/animation-performance.md @@ -0,0 +1,99 @@ +--- +technology: Animation & Performance +domain: frontend +level: Senior/Architect +version: Agnostic +tags: [vibe-coding, performance, animations, css, best-practices] +ai_role: Frontend UI/UX Enforcer +last_updated: 2026-03-29 +--- + +# 🎥 Animation & Performance Optimization + +[⬆️ Back to Frontend Architecture](../readme.md) + +[⬆️ Back to UI/UX Design Index](./readme.md) + +This document enforces the structural principles for constructing 60fps, performant UI animations while avoiding browser rendering bottlenecks. + +## 📖 Context & Scope +- **Primary Goal:** Ensure all UI animations are performant and do not trigger layout thrashing or main-thread blocking. +- **Target Tooling:** AI Assistants (UI Generation & Performance Audits). +- **Tech Stack Version:** Agnostic (CSS, JS Animations). + +--- + +## ⚖️ Structural Comparison: Animation Paradigms + +| Paradigm | Animated Properties | Rendering Thread | AI Agent Preference | Risk | +|:---|:---|:---|:---:|:---| +| **Layout Thrashing (Anti-Pattern)** | `width`, `height`, `margin`, `top` | Main Thread | ❌ Avoid | Triggers `O(n)` layout recalcs per frame; jank. | +| **Hardware Accelerated (Best Practice)** | `transform`, `opacity` | Compositor Thread (GPU) | ✅ Optimal | `O(1)` performance overhead; guaranteed 60fps. | + +> [!CAUTION] +> **Animation Constraint:** AI Agents MUST strictly forbid animating layout-affecting properties (like `width`, `top`, `left`). AI Agents MUST exclusively use CSS `transform` and `opacity` properties for animations to leverage GPU hardware acceleration. + +### ❌ Bad Practice +```css +/* Animating layout-affecting properties */ +.slide-in { + left: -100px; + transition: left 0.3s ease-in-out; +} + +.slide-in.active { + left: 0; +} +``` + +### ⚠️ Problem +Animating properties like `left`, `margin`, or `width` forces the browser to recalculate the layout and repaint the screen on every frame (Layout Thrashing). This occurs entirely on the main CPU thread, competing with JavaScript execution, and results in choppy, janky animations that drop below 60fps, severely degrading the user experience. + +### ✅ Best Practice +```css +/* Animating strictly compositor-only properties */ +.slide-in { + transform: translateX(-100px); + transition: transform 0.3s ease-in-out; + /* Optional optimization for complex layouts: */ + will-change: transform; +} + +.slide-in.active { + transform: translateX(0); +} +``` + +> [!NOTE] +> **Internal Routing:** For more context, refer back to the [🎨 UI/UX Design Index](./readme.md). + + +### 🚀 Solution +Strictly animating `transform` and `opacity` is MANDATORY. These properties do not affect the document flow. The browser offloads their execution directly to the GPU (Compositor Thread). This decoupling ensures animations run independently of main-thread JavaScript execution, resulting in perfectly smooth, deterministic 60fps rendering without blocking application logic. + +```mermaid +graph TD + A[Animation Trigger] --> B{Property Type} + B -->|Layout: width, top| C[Main Thread] + B -->|Compositor: transform, opacity| D[GPU Thread] + + C --> E[Layout Recalc] + E --> F[Paint] + F --> G[Jank / Dropped Frames] + + D --> H[Hardware Acceleration] + H --> I[60fps Smooth Animation] + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef danger fill:#ffebee,stroke:#f44336,stroke-width:2px,color:#000; + classDef success fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + + class A,B default; + class C,E,F,G danger; + class D,H,I success; +``` + +### ⚙️ Under the Hood: Edge Cases & Mechanics +- **`will-change` Abuse:** While `will-change: transform` hints to the browser to pre-allocate GPU memory for an element, applying it globally or unnecessarily wastes memory resources and can crash lower-end devices. Agents MUST only apply it dynamically immediately before an animation triggers, or strictly on highly persistent, constantly animating elements. +- **Accessibility (prefers-reduced-motion):** Animations MUST respect user accessibility settings. Agents must wrap non-essential UI animations in `@media (prefers-reduced-motion: reduce)` queries to enforce static fallbacks or simplified fades, adhering to WCAG guidelines. +- **Z-Index Stacking Contexts:** Utilizing `transform`, `opacity`, or `will-change` implicitly creates a new CSS stacking context. Agents must be aware that child elements with `z-index` will now be constrained by this new local context, potentially causing visual layering bugs. diff --git a/frontend/design-ui/component-architecture.md b/frontend/design-ui/component-architecture.md index d693efc..c3c7189 100644 --- a/frontend/design-ui/component-architecture.md +++ b/frontend/design-ui/component-architecture.md @@ -115,4 +115,9 @@ 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:** While atomic components isolate rendering, passing data through deeply nested hierarchies (prop drilling) degrades performance and DX. Agents MUST utilize established state architectures (e.g., Context API, Zustand, NgRx) for cross-cutting concerns, rather than relying on structural prop chains. +- **Render Reconciliation:** Frameworks like React and Angular optimize re-renders at component boundaries. "God components" force the engine to diff the entire UI tree. Atomic isolation ensures `O(1)` diffing operations, targeting only mutated nodes. +- **Circular Dependencies:** When composing complex layouts, agents must be vigilant against circular imports between components, which breaks module loaders and runtime initialization. Enforce unidirectional architectural boundaries (e.g., FSD or strict Atomic groupings). \ No newline at end of file diff --git a/frontend/design-ui/readme.md b/frontend/design-ui/readme.md index df0b2ad..4814543 100644 --- a/frontend/design-ui/readme.md +++ b/frontend/design-ui/readme.md @@ -84,6 +84,7 @@ The UI/UX architecture is decomposed into the following specialized modules. AI * [📱 Responsive Design](./responsive-design.md) - Mobile-First Approach, Relative Units, and fluid layouts. * [♿ Accessibility (A11y)](./accessibility.md) - Semantic HTML, ARIA attributes, Focus visibility, and WCAG standards. * [🏗️ Component Architecture](./component-architecture.md) - Atomic Design principles and structural UI diagrams. +* [🎥 Animation & Performance](./animation-performance.md) - GPU Hardware acceleration, Layout thrashing, and 60fps animations. --- ## ✅ Checklist for Agents diff --git a/frontend/design-ui/responsive-design.md b/frontend/design-ui/responsive-design.md index e318949..e8a4da3 100644 --- a/frontend/design-ui/responsive-design.md +++ b/frontend/design-ui/responsive-design.md @@ -70,4 +70,22 @@ 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. + +```mermaid +stateDiagram-v2 + [*] --> MobileBase + MobileBase --> Tablet : >= 768px + Tablet --> Desktop : >= 1024px + Desktop --> LargeDesktop : >= 1440px + + state MobileBase { + direction LR + FluidWidth --> BaseTypography + } +``` + +### ⚙️ Under the Hood: Edge Cases & Mechanics +- **Sub-pixel Rendering:** Avoid relying on exact pixel boundaries for breakpoint transitions. When devices perform sub-pixel rendering, layouts using strict fractional values can shift. Utilizing standard progressive `min-width` breakpoints with relative internal units prevents edge fractures. +- **Viewport Height Units (vh):** On mobile browsers, UI toolbars (address bars) dynamically hide and show, causing `100vh` to jump and recalculate. Agents MUST prefer `100dvh` (dynamic viewport height) or rely on `flex`/`grid` stretch mechanics for full-height container calculations to ensure a deterministic paint lifecycle. +- **Orientation Changes:** Rapid device rotation can trigger unexpected layout recalibrations. Implementing debounce mechanisms on JS-driven layout adjustments or relying entirely on CSS Grid fractionals (`fr`) mitigates reflow penalties. \ No newline at end of file diff --git a/frontend/design-ui/styling.md b/frontend/design-ui/styling.md index 7e266cc..5eaf004 100644 --- a/frontend/design-ui/styling.md +++ b/frontend/design-ui/styling.md @@ -60,4 +60,27 @@ 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. + +```mermaid +classDiagram + class GlobalTokens { + --color-brand-500: #3b82f6 + --spacing-4: 1rem + } + class SemanticTokens { + --color-primary: var(--color-brand-500) + --padding-container: var(--spacing-4) + } + class ComponentTokens { + --btn-bg: var(--color-primary) + } + + GlobalTokens *-- SemanticTokens : Composition + SemanticTokens *-- ComponentTokens : Composition +``` + +### ⚙️ Under the Hood: Edge Cases & Mechanics +- **Token Specificity:** CSS variable overrides can unintentionally cascade if scoped incorrectly. Agents MUST enforce that global tokens are declared at the `:root` level, while semantic/component tokens can be scoped locally if necessary to isolate thematic variations. +- **Dynamic Theming Contexts:** When injecting dynamic themes (e.g., user-selected colors), agents must avoid injecting `