[thetaPC]

Issue URL: N/A

What is the current behavior?

Global styles live in src/styles, in partials named after internal concepts (_doc-item, _markdown, _navbar-sidebar) rather than the Docusaurus components they override. Ejected components import their styles from node_modules, some styles for swizzled components live in the global partials, and many rules target hashed class names, are nested up to 8 levels deep, or no longer match anything.

What is the new behavior?

The site looks the same; this reorganizes where styles live and removes dead code.

• Moves src/styles to src/css, with one partial per overridden component in src/css/theme, named after its path in @docusaurus/theme-classic (for example theme/Navbar/MobileSidebar.scss)
• Removes dead code, found by collecting CSS coverage on all 618 built pages: rules no page matches, styles only used by the archived v5 and v6 docs (served from frozen deployments, so unaffected), and the unused size prop on DocsCard
• Gives ejected components a local copy of upstream's styles.module.css with our rules between CUSTOM CODE markers, the same way the TSX marks changes
• Moves styles for markup our wrapped components render into modules next to them (TOC, DocSidebar, DocRoot/Layout/Main, MDXComponents/Table)
• Converts BestPracticeFigure, Tooltip, DocDemo and IconDots from global CSS to CSS modules
• Cuts hashed selectors from 23 to 11, using theme- classes or our own module classes where they exist. The rest have no stable alternative
• Flattens nesting to at most 5 levels; the compiled CSS is identical
• Documents the structure and when to use #__docusaurus in src/css/README.md and src/theme/README.md

Shipped CSS drops from 202.6 KB to 194.1 KB (40.9 KB gzipped).

Does this introduce a breaking change?

• Yes
• No

Other information

Compared computed styles of every element plus screenshots against main on 23 pages at 1440, 1100 and 390px in light and dark. The only differences are a redundant display: none on the demo wrapper (its column is already hidden) and the demo iframe mask written as the standard mask-image; both render identically.

Worth a quick look at the phone demo on /docs/ in Safari, which the comparison did not cover.

.install-button and .docs-button stay global because the VS Code Extension page and its translation set them as plain class names in markdown. Moving them into a component is a follow-up.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
ionic-docs	Ready	Preview	Nov 11, 2026 7:39pm UTC

[ShaneK]

Generally looking really good! Just one real issue, the encapsulation pill change breaks the markdown twins for the API pages. The rest are small README and comment fixes.

[ShaneK]

Looks good, awesome work!