@innovaccer/design-system 5.0.0-3 → 5.0.0-30

package/README.md

@@ -16,7 +16,7 @@
 
 <div align="center">
 
-[![codecov](https://codecov.io/gh/innovaccer/design-system/branch/master/graph/badge.svg?token=2LY7JLZGX0)](https://codecov.io/gh/innovaccer/design-system) ![GitHub](https://img.shields.io/github/license/innovaccer/design-system) ![GitHub top language](https://img.shields.io/github/languages/top/innovaccer/design-system) ![Snyk Vulnerabilities for GitHub Repo](https://img.shields.io/snyk/vulnerabilities/github/innovaccer/design-system)
+[![codecov](https://codecov.io/gh/innovaccer/design-system/branch/master/graph/badge.svg?token=2LY7JLZGX0)](https://codecov.io/gh/innovaccer/design-system) ![GitHub](https://img.shields.io/github/license/innovaccer/design-system) ![GitHub top language](https://img.shields.io/github/languages/top/innovaccer/design-system) [![Known Vulnerabilities](https://snyk.io/test/github/innovaccer/design-system/badge.svg)](https://snyk.io/test/github/innovaccer/design-system)
 
 </div>
 <br/>
@@ -155,33 +155,41 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->
 <table>
-  <tr>
-    <td align="center"><a href="https://github.com/aditya-kumawat"><img src="https://avatars.githubusercontent.com/u/12715487?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Aditya Kumawat</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=aditya-kumawat" title="Code">💻</a></td>
-    <td align="center"><a href="https://riyalohia.github.io/portfolio/"><img src="https://avatars.githubusercontent.com/u/31706090?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Riya Lohia</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=riyalohia" title="Code">💻</a></td>
-    <td align="center"><a href="http://satyamyadav.info/"><img src="https://avatars.githubusercontent.com/u/3583587?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Satyam Yadav</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=satyamyadav" title="Code">💻</a> <a href="https://github.com/innovaccer/design-system/commits?author=satyamyadav" title="Documentation">📖</a> <a href="https://github.com/innovaccer/design-system/pulls?q=is%3Apr+reviewed-by%3Asatyamyadav" title="Reviewed Pull Requests">👀</a></td>
-    <td align="center"><a href="https://github.com/sandeshchoudhary"><img src="https://avatars.githubusercontent.com/u/11272274?v=4?s=100" width="100px;" alt=""/><br /><sub><b>sandeshchoudhary</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=sandeshchoudhary" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/adityajhajharia"><img src="https://avatars.githubusercontent.com/u/42600089?v=4?s=100" width="100px;" alt=""/><br /><sub><b>adityajhajharia</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=adityajhajharia" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/anuradha9712"><img src="https://avatars.githubusercontent.com/u/46045493?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Anuradha Aggarwal</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=anuradha9712" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/xlreon"><img src="https://avatars.githubusercontent.com/u/26788670?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sidharth</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=xlreon" title="Code">💻</a></td>
-  </tr>
-  <tr>
-    <td align="center"><a href="https://github.com/stuti1090"><img src="https://avatars.githubusercontent.com/u/65341865?v=4?s=100" width="100px;" alt=""/><br /><sub><b>stuti1090</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=stuti1090" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/veekays"><img src="https://avatars.githubusercontent.com/u/6420348?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Vikas Singh</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=veekays" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/SaniyaGupta"><img src="https://avatars.githubusercontent.com/u/15903031?v=4?s=100" width="100px;" alt=""/><br /><sub><b>SaniyaGupta</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=SaniyaGupta" title="Code">💻</a></td>
-    <td align="center"><a href="https://www.linkedin.com/in/parth-chauhan-984624193/"><img src="https://avatars.githubusercontent.com/u/35137224?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Parth Chauhan</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=chauhanparth210" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/stutirao"><img src="https://avatars.githubusercontent.com/u/45294592?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Stuti Pandey</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=stutirao" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/Shib00"><img src="https://avatars.githubusercontent.com/u/33096446?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Shivam Dwivedi</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Shib00" title="Code">💻</a></td>
-    <td align="center"><a href="http://www.rahulgaur.info/"><img src="https://avatars.githubusercontent.com/u/760474?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rahul Gaur</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=aregee" title="Code">💻</a></td>
-  </tr>
-  <tr>
-    <td align="center"><a href="https://github.com/atifzaidi92"><img src="https://avatars.githubusercontent.com/u/54103064?v=4?s=100" width="100px;" alt=""/><br /><sub><b>atifzaidi92</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=atifzaidi92" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/Sumit2399"><img src="https://avatars.githubusercontent.com/u/66456021?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sumit Dhyani</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Sumit2399" title="Code">💻</a></td>
-    <td align="center"><a href="https://tanmay-portfolio.herokuapp.com/"><img src="https://avatars.githubusercontent.com/u/36269283?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tanmay Sharma</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=927tanmay" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/Rashi-Gupta-2000"><img src="https://avatars.githubusercontent.com/u/99866103?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rashi Gupta</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Rashi-Gupta-2000" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/varnikajain15"><img src="https://avatars.githubusercontent.com/u/55780559?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Varnika Jain</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=varnikajain15" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/aman2000verma"><img src="https://avatars.githubusercontent.com/u/45339091?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Aman Verma</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=aman2000verma" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/samyak3009"><img src="https://avatars.githubusercontent.com/u/56395892?v=4?s=100" width="100px;" alt=""/><br /><sub><b>SAMYAK JAIN</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=samyak3009" title="Code">💻</a></td>
-  </tr>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aditya-kumawat"><img src="https://avatars.githubusercontent.com/u/12715487?v=4?s=100" width="100px;" alt="Aditya Kumawat"/><br /><sub><b>Aditya Kumawat</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=aditya-kumawat" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://riyalohia.github.io/portfolio/"><img src="https://avatars.githubusercontent.com/u/31706090?v=4?s=100" width="100px;" alt="Riya Lohia"/><br /><sub><b>Riya Lohia</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=riyalohia" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://satyamyadav.info/"><img src="https://avatars.githubusercontent.com/u/3583587?v=4?s=100" width="100px;" alt="Satyam Yadav"/><br /><sub><b>Satyam Yadav</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=satyamyadav" title="Code">💻</a> <a href="https://github.com/innovaccer/design-system/commits?author=satyamyadav" title="Documentation">📖</a> <a href="https://github.com/innovaccer/design-system/pulls?q=is%3Apr+reviewed-by%3Asatyamyadav" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/anuradha9712"><img src="https://avatars.githubusercontent.com/u/46045493?v=4?s=100" width="100px;" alt="Anuradha Aggarwal"/><br /><sub><b>Anuradha Aggarwal</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=anuradha9712" title="Code">💻</a> <a href="https://github.com/innovaccer/design-system/commits?author=anuradha9712" title="Documentation">📖</a> <a href="https://github.com/innovaccer/design-system/pulls?q=is%3Apr+reviewed-by%3Aanuradha9712" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/sandeshchoudhary"><img src="https://avatars.githubusercontent.com/u/11272274?v=4?s=100" width="100px;" alt="sandeshchoudhary"/><br /><sub><b>sandeshchoudhary</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=sandeshchoudhary" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/adityajhajharia"><img src="https://avatars.githubusercontent.com/u/42600089?v=4?s=100" width="100px;" alt="adityajhajharia"/><br /><sub><b>adityajhajharia</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=adityajhajharia" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/xlreon"><img src="https://avatars.githubusercontent.com/u/26788670?v=4?s=100" width="100px;" alt="Sidharth"/><br /><sub><b>Sidharth</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=xlreon" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/stuti1090"><img src="https://avatars.githubusercontent.com/u/65341865?v=4?s=100" width="100px;" alt="stuti1090"/><br /><sub><b>stuti1090</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=stuti1090" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/veekays"><img src="https://avatars.githubusercontent.com/u/6420348?v=4?s=100" width="100px;" alt="Vikas Singh"/><br /><sub><b>Vikas Singh</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=veekays" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/SaniyaGupta"><img src="https://avatars.githubusercontent.com/u/15903031?v=4?s=100" width="100px;" alt="SaniyaGupta"/><br /><sub><b>SaniyaGupta</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=SaniyaGupta" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/parth-chauhan-984624193/"><img src="https://avatars.githubusercontent.com/u/35137224?v=4?s=100" width="100px;" alt="Parth Chauhan"/><br /><sub><b>Parth Chauhan</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=chauhanparth210" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/stutirao"><img src="https://avatars.githubusercontent.com/u/45294592?v=4?s=100" width="100px;" alt="Stuti Pandey"/><br /><sub><b>Stuti Pandey</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=stutirao" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Shib00"><img src="https://avatars.githubusercontent.com/u/33096446?v=4?s=100" width="100px;" alt="Shivam Dwivedi"/><br /><sub><b>Shivam Dwivedi</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Shib00" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.rahulgaur.info/"><img src="https://avatars.githubusercontent.com/u/760474?v=4?s=100" width="100px;" alt="Rahul Gaur"/><br /><sub><b>Rahul Gaur</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=aregee" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/atifzaidi92"><img src="https://avatars.githubusercontent.com/u/54103064?v=4?s=100" width="100px;" alt="atifzaidi92"/><br /><sub><b>atifzaidi92</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=atifzaidi92" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Sumit2399"><img src="https://avatars.githubusercontent.com/u/66456021?v=4?s=100" width="100px;" alt="Sumit Dhyani"/><br /><sub><b>Sumit Dhyani</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Sumit2399" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://tanmay-portfolio.herokuapp.com/"><img src="https://avatars.githubusercontent.com/u/36269283?v=4?s=100" width="100px;" alt="Tanmay Sharma"/><br /><sub><b>Tanmay Sharma</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=927tanmay" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Rashi-Gupta-2000"><img src="https://avatars.githubusercontent.com/u/99866103?v=4?s=100" width="100px;" alt="Rashi Gupta"/><br /><sub><b>Rashi Gupta</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Rashi-Gupta-2000" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/varnikajain15"><img src="https://avatars.githubusercontent.com/u/55780559?v=4?s=100" width="100px;" alt="Varnika Jain"/><br /><sub><b>Varnika Jain</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=varnikajain15" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aman2000verma"><img src="https://avatars.githubusercontent.com/u/45339091?v=4?s=100" width="100px;" alt="Aman Verma"/><br /><sub><b>Aman Verma</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=aman2000verma" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/samyak3009"><img src="https://avatars.githubusercontent.com/u/56395892?v=4?s=100" width="100px;" alt="SAMYAK JAIN"/><br /><sub><b>SAMYAK JAIN</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=samyak3009" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Atulya26"><img src="https://avatars.githubusercontent.com/u/85021422?v=4?s=100" width="100px;" alt="Atulya"/><br /><sub><b>Atulya</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Atulya26" title="Code">💻</a> <a href="#design-Atulya26" title="Design">🎨</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/abhiroopchaudhuri"><img src="https://avatars.githubusercontent.com/u/87370756?v=4?s=100" width="100px;" alt="Abhiroop Chaudhuri"/><br /><sub><b>Abhiroop Chaudhuri</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=abhiroopchaudhuri" title="Code">💻</a> <a href="#design-abhiroopchaudhuri" title="Design">🎨</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/grandhimanshu"><img src="https://avatars.githubusercontent.com/u/165885443?v=4?s=100" width="100px;" alt="Himanshu Jangir"/><br /><sub><b>Himanshu Jangir</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=grandhimanshu" title="Code">💻</a> <a href="#design-grandhimanshu" title="Design">🎨</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Shiv619"><img src="https://avatars.githubusercontent.com/u/83985838?v=4?s=100" width="100px;" alt="Shivaansh Sharma"/><br /><sub><b>Shivaansh Sharma</b></sub></a><br /><a href="https://github.com/innovaccer/design-system/commits?author=Shiv619" title="Code">💻</a> <a href="#design-Shiv619" title="Design">🎨</a></td>
+    </tr>
+  </tbody>
 </table>
 
 <!-- markdownlint-restore -->

package/css/SCOPED_CSS.md

@@ -0,0 +1,145 @@
+# Scoped stylesheet
+
+An additional consumer entry built alongside the default `dist/index.css`. Identical rules,
+wrapped in `@scope ([data-mds-root])`, so MDS styles only apply inside containers the host
+app opts in to — useful when MDS runs next to another stylesheet (Tailwind, a legacy global
+sheet, another design system) in the same document.
+
+- Output: `css/dist/mds-scoped.css`
+- Import: `@innovaccer/design-system/css/scoped` or `…/css/dist/mds-scoped.css`
+- Build: `npm run build-css` (gulp, builds both bundles) or `npm run build-css-scoped`
+
+The default `dist/index.css` bundle is unchanged — this is purely additive.
+
+## Usage
+
+```html
+<div data-mds-root>
+  <!-- MDS components -->
+</div>
+```
+
+Everything outside `[data-mds-root]` is untouched by MDS, and MDS components inside it are
+unaffected by the host app's global styles that would otherwise reach them.
+
+The scope root is yours to style — MDS declares nothing on it. If you put `data-mds-root` on a
+custom element, remember that custom elements default to `display: inline`, so give it a
+`display` of its own:
+
+```css
+ui-shell-app {
+  display: block;
+}
+```
+
+## How the build composes it
+
+`scripts/build-scoped.mjs` reads the same sources, in the same order, as the default build
+(both import the list from `scripts/css-sources.cjs`, so they cannot drift), then:
+
+1. **Hoists global-namespace at-rules** — `@keyframes`, `@font-face`, `@property` and
+   `@counter-style` above the `@scope` block. Their names are document-global and are not
+   scopable; leaving them inside would silently drop them. The build throws if one is nested
+   inside another at-rule, where the hoist cannot reach it.
+2. **Remaps `:root` / `html` / `body` / `:host` to `:scope`** so design tokens attach to the
+   scope root. Without this, every custom-property reference in the bundle resolves to nothing.
+3. **Adds a root-anchored variant of every selector** — `.Backdrop` becomes
+   `.Backdrop, :scope.Backdrop`. See *Overlays* below.
+4. **Wraps the result** in `@scope ([data-mds-root]) { … }`.
+
+Step 3 costs about +28% in raw bytes (~80 KB, considerably less gzipped).
+
+Nothing is declared on the scope root itself. A `[data-mds-root]` element is consumer
+markup, so any default MDS set there would compete with the consumer's own layout.
+
+## Overlays
+
+Modal, Sidesheet, FullscreenModal, Backdrop, Popover, Tooltip, Dropdown, Menu and the
+Listbox drag ghost all render through `ReactDOM.createPortal` into `document.body` — outside
+the consumer's `[data-mds-root]`. Without special handling they would receive neither
+component rules nor tokens, and render completely unstyled.
+
+Inside `@scope`, a rule like `.Backdrop` is implicitly `:scope .Backdrop`, so it matches
+**descendants of a scope root only**. Those portaled elements therefore have to be scope
+roots in their own right, and there is no MDS-owned ancestor to hang that on. So the build
+adds them to the prelude directly, targeting markup the components *already* render:
+
+```css
+@scope (
+  [data-mds-root],                              /* your opt-in container */
+  body > .Overlay-wrapper:has([data-layer]),    /* Modal, Sidesheet, FullscreenModal */
+  body > [data-test='DesignSystem-Popover'],    /* Popover, Tooltip, Dropdown, Menu, … */
+  body > [data-test='DesignSystem-Backdrop'],   /* Backdrop */
+  body > .Listbox-item--draggable               /* Listbox drag ghost */
+)
+```
+
+Every popper-based component shares one root — `Popover` renders the popup element itself and
+Tooltip/Dropdown/Menu all go through it — so a single selector covers them all.
+
+Each selector is qualified so it cannot collide with a host app's own class names:
+
+- **`body >`** — all of these land as direct children of `<body>`, so a colliding host class
+  would have to be at body level too.
+- **`:has([data-layer])`** — `data-layer` is an MDS-only attribute present on all five portal
+  roots. `.Overlay-wrapper` is a generic enough name that a host app could plausibly reuse it,
+  so the class alone is not enough. It matches a *descendant* rather than a child because Modal
+  wraps its container in `OutsideClick` when `backdropClose` is set.
+- **`data-test='DesignSystem-*'`** — already namespaced.
+
+The root-anchored selector variants from step 3 are what let those roots style *themselves*:
+`.Backdrop` alone would only match descendants. Because *every* rule gets a variant, all rules
+matching a given scope root are bumped by the same `:scope` (0,1,0), so relative specificity —
+and therefore the cascade between MDS rules — is preserved.
+
+`css/scripts/portal-roots.cjs` is the single source of truth for this list, shared with
+`core/utils/__tests__/scopedPortalRoots.test.tsx`. That test renders each overlay and asserts
+the selectors still match, so if a component ever stops rendering one of these hooks the build
+fails loudly instead of silently shipping unstyled overlays.
+
+### No component changes required
+
+This is the reason the prelude keys off existing markup rather than a dedicated attribute:
+nothing in `core/` changes, so **the scoped stylesheet can be updated independently of the
+library version**. Consumers swap the CSS file without rebuilding or upgrading, and it works
+against releases already in the wild.
+
+## Custom scope selectors
+
+`@scope`'s prelude is a forgiving selector list, so attribute and class patterns work:
+
+```bash
+MDS_SCOPE_SELECTOR='[data-mds-root], [class^="ui-"][class$="-app"]' npm run build-css-scoped
+MDS_SCOPE_OUTPUT='ui-apps.css' MDS_SCOPE_SELECTOR='ui-shell-app, ui-admin-app' npm run build-css-scoped
+```
+
+One selector list in a single `@scope` block covers many hosts — you do not need a stylesheet
+per app.
+
+`MDS_SCOPE_SELECTOR` replaces only the *consumer* part of the prelude. The portal-root
+selectors are always appended, so MDS's overlays stay scoped whatever you scope on. The build
+logs the final prelude it used.
+
+CSS has **no tag-name wildcard**, so a pattern like `ui-*-app` cannot be expressed as a
+selector: `^=` / `$=` / `*=` match attribute *values*, and a tag name is not an attribute.
+For custom elements following a naming convention, either enumerate the tags in
+`MDS_SCOPE_SELECTOR`, or have the host stamp `data-mds-root` onto matching elements at
+runtime (a `MutationObserver` plus `/^ui-.*-app$/.test(el.tagName.toLowerCase())`).
+
+## Caveats
+
+- **Browser support**: `@scope` requires Chrome/Edge 118+, Safari 17.4+, Firefox 128+. There
+  is no fallback — an older browser drops the whole stylesheet as an unknown at-rule and
+  renders MDS unstyled. Serve `dist/index.css` to browsers you still support.
+- **`@keyframes` names stay global.** They are hoisted out of `@scope`, so animation names
+  still collide with the host app's. `Spinner`'s were renamed to `mds-spin` / `mds-rotate`;
+  generic ones such as `fadeIn`, `fadeOut` and `shimmer` remain exposed.
+- **Portaled overlays get base tokens**, not per-root token overrides: a themed
+  `[data-mds-root]` does not affect overlays, which are scope roots of their own under
+  `<body>`. They are deliberately not re-parented into the app's scope root, because a
+  `transform` / `filter` / `contain` on an ancestor there would become the containing block
+  and break `position: fixed` overlays. Declare token overrides on `:root` so both the
+  in-tree components and the body-level overlays pick them up.
+- **The drag ghost has the weakest qualifier.** No `data-test` exists on it, so
+  `body > .Listbox-item--draggable` is all that is available. Worth tightening with a
+  `data-test` next time component changes ship.