ICANNWiki:Documentation/CLS: Difference between revisions

(3 intermediate revisions by 2 users not shown)

Line 1:

This is a subpage of [[ICANNWiki:Documentation]] describing a reusable pattern for preventing '''Cumulative Layout Shift (CLS)''' in client-rendered widgets. The guidance is written to help any MediaWiki site (and similar platforms) avoid layout jumps, with an ~~'''~~ICANNWiki case study~~'''~~ included for concrete examples. Maintained by [[Mark W. Datysgeld]].

This is a subpage of [[ICANNWiki:Documentation]] describing a reusable pattern for preventing '''Cumulative Layout Shift (CLS)''' in client-rendered widgets. The guidance is written to help any MediaWiki site (and similar platforms) avoid layout jumps, with an ICANNWiki case study included for concrete examples. Maintained by [[Mark W. Datysgeld]].

== MediaWiki Rendering Priority (General Reference) ==

When diagnosing layout or UI stability issues, think of a rendering priority stack. Earlier layers shape what the browser paints first; later layers should respect the space and structure already defined.

== MediaWiki Rendering Priority (General Reference) ==

When diagnosing layout or UI stability issues, treat the page as (1) server-side DOM construction, then (2) ResourceLoader-delivered CSS/JS behaviors, then (3) late/third-party content. The key operational goal is: layout anchors should exist in the delivered HTML and have CSS-reserved space before any JS enhances them.

== MediaWiki Rendering Priority (General Reference) ==

When diagnosing layout or UI stability issues, treat the page as a priority stack. Earlier layers define the DOM shell and layout anchors; later layers should enhance what already exists rather than inventing structure late.

{| class="wikitable"

! Layer (earliest → latest)

! Responsibility

! Reference

! Operational notes

|-

| Server-side HTML (Page chrome + Wrappers)

| MediaWiki + Skin core output: the outer page structure and content wrappers into which parsed content gets inserted

| Backend core + Skin

| This is the “wiki looks like a wiki” layer; Lua/templates can't normally replace this outer chrome.

|-

| Lua (#invoke)

| Emits arbitrary HTML/wikitext at parser-time, which become part of the delivered HTML inside content wrappers

| Scribunto

| Distinct authoring surface; an "upper layer" that still ships as part of the server HTML response.

|-

| CSS (skin + site + template-scoped)

| Layout/visibility/space reservation via stylesheets linked from the HTML (ResourceLoader); may include site CSS (e.g., Common.css) and other modules

| ResourceLoader styles + Common.css

| ResourceLoader explicitly treats stylesheets as a first-class, HTML-linked resource; this is where you must reserve space and define “anchors” before any JS runs.

|-

| ResourceLoader startup runtime

| The only script linked directly from the HTML; it bootstraps mw.loader and then batches/requests the rest of the JS modules (including gadgets and site scripts)

| ResourceLoader startup module

| Key reality check: anything not in startup (i.e., basically all custom JS) cannot influence first paint and will necessarily be “later”.

|-

| Gadget JS (ResourceLoader modules)

| Optional enhancement modules registered by Extension:Gadgets; can declare dependencies and can be configured for earlier loading when needed

| Extension:Gadgets (ResourceLoader)

| Gadgets are explicitly ResourceLoader modules (and can declare dependencies).

|-

| Site JS (Common.js, Skin.js)

| Site-wide and skin-specific scripts bundled by SiteModule (includes MediaWiki:Common.js)

| ResourceLoader SiteModule

| Common.js is delivered via ResourceLoader SiteModule.

|-

| Embedded content / third-party widgets

| External iframes or async components arriving late

| External HTML/JS

| Treat as content, not structure; reserve dimensions up front (width/height/aspect ratio/min-height) to avoid CLS.

|}

== What CLS Looks Like (Problem Statement) ==

@@ Line 1: / Line 1: @@
-This is a subpage of [[ICANNWiki:Documentation]] describing a reusable pattern for preventing '''Cumulative Layout Shift (CLS)''' in client-rendered widgets. The guidance is written to help any MediaWiki site (and similar platforms) avoid layout jumps, with an '''ICANNWiki case study''' included for concrete examples. Maintained by [[Mark W. Datysgeld]].
+This is a subpage of [[ICANNWiki:Documentation]] describing a reusable pattern for preventing '''Cumulative Layout Shift (CLS)''' in client-rendered widgets. The guidance is written to help any MediaWiki site (and similar platforms) avoid layout jumps, with an ICANNWiki case study included for concrete examples. Maintained by [[Mark W. Datysgeld]].
+== MediaWiki Rendering Priority (General Reference) ==
+When diagnosing layout or UI stability issues, think of a rendering priority stack. Earlier layers shape what the browser paints first; later layers should respect the space and structure already defined.
+== MediaWiki Rendering Priority (General Reference) ==
+When diagnosing layout or UI stability issues, treat the page as (1) server-side DOM construction, then (2) ResourceLoader-delivered CSS/JS behaviors, then (3) late/third-party content. The key operational goal is: layout anchors should exist in the delivered HTML and have CSS-reserved space before any JS enhances them.
+== MediaWiki Rendering Priority (General Reference) ==
+When diagnosing layout or UI stability issues, treat the page as a priority stack. Earlier layers define the DOM shell and layout anchors; later layers should enhance what already exists rather than inventing structure late.
+{| class="wikitable"
+! Layer (earliest → latest)
+! Responsibility
+! Reference
+! Operational notes
+|-
+| Server-side HTML (Page chrome + Wrappers)
+| MediaWiki + Skin core output: the outer page structure and content wrappers into which parsed content gets inserted
+| Backend core + Skin
+| This is the “wiki looks like a wiki” layer; Lua/templates can't normally replace this outer chrome.
+|-
+| Lua (#invoke)
+| Emits arbitrary HTML/wikitext at parser-time, which become part of the delivered HTML inside content wrappers
+| Scribunto
+| Distinct authoring surface; an "upper layer" that still ships as part of the server HTML response.
+|-
+| CSS (skin + site + template-scoped)
+| Layout/visibility/space reservation via stylesheets linked from the HTML (ResourceLoader); may include site CSS (e.g., Common.css) and other modules
+| ResourceLoader styles + Common.css
+| ResourceLoader explicitly treats stylesheets as a first-class, HTML-linked resource; this is where you must reserve space and define “anchors” before any JS runs.
+|-
+| ResourceLoader startup runtime
+| The only script linked directly from the HTML; it bootstraps mw.loader and then batches/requests the rest of the JS modules (including gadgets and site scripts)
+| ResourceLoader startup module
+| Key reality check: anything not in startup (i.e., basically all custom JS) cannot influence first paint and will necessarily be “later”.
+|-
+| Gadget JS (ResourceLoader modules)
+| Optional enhancement modules registered by Extension:Gadgets; can declare dependencies and can be configured for earlier loading when needed
+| Extension:Gadgets (ResourceLoader)
+| Gadgets are explicitly ResourceLoader modules (and can declare dependencies).
+|-
+| Site JS (Common.js, Skin.js)
+| Site-wide and skin-specific scripts bundled by SiteModule (includes MediaWiki:Common.js)
+| ResourceLoader SiteModule
+| Common.js is delivered via ResourceLoader SiteModule.
+|-
+| Embedded content / third-party widgets
+| External iframes or async components arriving late
+| External HTML/JS
+| Treat as content, not structure; reserve dimensions up front (width/height/aspect ratio/min-height) to avoid CLS.
+|}
 == What CLS Looks Like (Problem Statement) ==