Merge pull request #2771 from w3c/css-sections-review-(issue-2762)

Made the changes on CSS management discussed in the issue 2762

Author: mattgarrish

epub34/authoring/index.html

@@ -6198,25 +6198,16 @@ <h4>Introduction</h4>
 							provided prefixed versions of numerous other properties. Although the CSS Working Group no
 							longer recommends the use of prefixed properties, this specification maintains some prefixed
 							properties to avoid breaking existing content. But with the minor exceptions defined in this
-							section, EPUB defers to the W3C to define CSS.</p>
-
-						<div class="note">
-							<p>Keep in mind that some [=reading systems=] will not support all desired features of CSS.
-								The following are known to be particularly problematic:</p>
-
-							<ul>
-								<li>
-									<p>Reading system-induced pagination can interact poorly with style sheets as
-										reading systems sometimes paginate using columns. This may result in incorrect
-										values for viewport sizes. Fixed and absolute positioning are particularly
-										problematic.</p>
-								</li>
-								<li>
-									<p>Some types of screens will render animations and transitions poorly (e.g., those
-										with high latency).</p>
-								</li>
-							</ul>
-						</div>
+							section, EPUB defers to the W3C to define CSS and expects [=reading systems=] to support it
+							at the level of major browsers.</p>
+
+						<p>Although reading systems are expected to support <a
+								data-cite="epub-rs-34#confreq-css-rs-support">CSS as defined in the CSS snapshot</a>
+							[[epub-rs-34]], the reality is that most reading systems currently do not support all
+							desired features of CSS, and often will modify, and allow users to change, the default
+							presentation defined by the [=EPUB creator=]. As a result, EPUB creators will need to adapt
+							their styling to these realities. For more information, refer to <a href="#sec-css-rs"
+							></a>.</p>
 					</section>
 
 					<section id="sec-css-req" data-epubcheck="true"
@@ -6274,6 +6265,40 @@ <h4>CSS requirements</h4>
 						</div>
 					</section>
 
+					<section id="sec-css-rs" class="informative">
+						<h4>Reading system support considerations</h4>
+
+						<p>Support for the following CSS features are known to be particularly problematic in [=EPUB
+							reading systems=]:</p>
+
+						<ul>
+							<li>
+								<p>Reading system-induced pagination can interact poorly with style sheets as reading
+									systems sometimes paginate using columns. This may result in incorrect values for
+									viewport sizes. Fixed and absolute positioning are particularly problematic.</p>
+							</li>
+							<li>
+								<p>Some types of screens will render animations and transitions poorly (e.g., those with
+									high latency).</p>
+							</li>
+						</ul>
+
+						<p>Reading systems will typically set some aspects of an [=EPUB publication | EPUB
+							publication's=] style (e.g., setting margins appropriate to the application), potentially
+							overriding the [=EPUB creator | EPUB creator's=] instructions. To mitigate conflicts, and
+							any potential rendering problems, EPUB creators are advised to consult reading systems' user
+							agent style sheets, when made publicly available, and adapt their styling choices for
+							optimal display.</p>
+
+						<p>Furthermore, reading systems that allow users to change the appearance (e.g., choice of
+							fonts, text justification, or foreground and background colors) will also modify some CSS
+							rendering directions in an EPUB publication. Due to CSS precedence rules, it is advisable to
+							limit the use of [[html]] [^html-global/style^] attributes in EPUB content documents so that
+							the user experience is not negatively impacted (i.e., the users' style choices not being
+							universally applied). Although some reading systems will override inline styles, such
+							behavior is not guaranteed.</p>
+					</section>
+
 					<section id="sec-css-prefixed">
 						<h4>Prefixed properties</h4>
 

epub34/rs/index.html

@@ -1038,14 +1038,14 @@ <h5>RDFa</h5>
 						<p>Reading system support for the <a data-cite="rdfa-core#s_model">attribute processing
 								model</a> [[rdfa-core]] is OPTIONAL.</p>
 					</section>
-					
+
 					<section id="sec-xhtml-its">
 						<h5>Internationalization Tag Set (ITS)</h5>
-						
+
 						<p>Reading system support for <a data-cite="its20#conformance-product-html5-its">processing ITS
 								markup</a> [[its20]] is OPTIONAL.</p>
 					</section>
-					
+
 					<section id="sec-xhtml-custom-attributes">
 						<h5>Custom attributes</h5>
 
@@ -1205,22 +1205,30 @@ <h3>Cascading Style Sheets (CSS)</h3>
 							[=EPUB content documents=].</p>
 					</li>
 					<li>
-						<p id="confreq-css-overrides">SHOULD NOT override the EPUB creator's style sheets, but SHOULD do
-							so in a way that preserves the Cascade when necessary: through a user agent style sheet, or
-							[[html]] [^html-global/style^] attributes.</p>
-					</li>
-					<li>
-						<p id="confreq-css-user-styles">It MAY override parts of the EPUB creator's style sheet because
-							of user interaction.</p>
+						<p id="confreq-css-rs-html-default">SHOULD support the [[html]] <a data-cite="html#rendering"
+								>suggested default rendering</a> in their user agent style sheet(s).</p>
 					</li>
 				</ul>
 
-				<p id="confreq-css-rs-html-default">In addition to supporting CSS properties as defined above, a reading
-					system's user agent style sheet SHOULD support the [[html]] <a data-cite="html#rendering">suggested
-						default rendering</a>.</p>
+				<div class="note">
+					<p>Reading system developers are expected to publicly document their user agent style sheet(s) and
+						how they interact with EPUB creator's style settings. </p>
+				</div>
+
+				<section id="sec-css-overrides">
+					<h4>Author styling overrides</h4>
 
-				<p>Reading system developers should implement CSS support at the level of major browsers and publicly
-					document their user agent style sheets and how they interact with EPUB creator's style sheets.</p>
+					<p id="confreq-css-overrides">A reading system MAY override parts of an [=EPUB publication|EPUB
+						publication's] styling (e.g., for ergonomic or user interface reasons). Morevoer, they MAY allow
+						users to set default themes and style preferences (e.g., for more accessible reading) that
+						further alter the original design of a publication.</p>
+
+					<!-- <p id="confreq-css-user-styles">These changes often make it impractical to render an EPUB
+						publication exactly as designed by an author, even if that is what the user wants. To assist
+						users in viewing an EPUB publication as closely as possible to the author intent, however,
+						reading systems MAY provide an affordance that reverts as much reading system-applied styling as
+						feasible.</p> -->
+				</section>
 			</section>
 
 			<section id="sec-scripted-content">
@@ -2710,6 +2718,10 @@ <h2>Change log</h2>
 				<summary>Substantive changes since <a href="https://www.w3.org/TR/epub-rs-33/">EPUB Reading Systems
 						3.3</a></summary>
 				<ul>
+					<li>06-August-2025: Updated the <a href="#sec-css">section on handling CSS</a>, in particular the
+						relationships between the user agent's and the creators' style sheets. See discussion in <a
+							href="https://github.com/w3c/epub-specs/issues/2762">issue 2762</a> and <a
+							href="https://github.com/w3c/epub-specs/pull/2771">pull request 2771</a>. </li>
 					<li>05-June-2025: Consolidated all deprecated features under the unsupported features section. See
 						the comments in <a href="https://github.com/w3c/epub-specs/pull/2735#issuecomment-2944066035"
 							>pull request 2735</a>.</li>