docs: migration css info refinement

Author: cdransf

2nd-gen/packages/swc/components/badge/migration.md

@@ -69,8 +69,8 @@ Find and replace all instances of `sp-badge` with `swc-badge` in your templates
 
 ### CSS custom properties
 
-All `--mod-badge-*` custom properties have been renamed to `--swc-badge-*`. Update any
-overrides in your stylesheets:
+All `--mod-badge-*` custom properties have been removed. Replace them with the
+`--swc-badge-*` equivalents in your stylesheets:
 
 | Removed (1st-gen)                           | Replacement (2nd-gen)          |
 | ------------------------------------------- | ------------------------------ |
@@ -99,6 +99,30 @@ swc-badge {
 }
 ```
 
+> **Note on per-variant color overrides:** Semantic variants (`neutral`, `informative`,
+> `positive`, `negative`, `notice`, `accent`) use attribute-based selectors internally,
+> so consumer per-variant overrides work as expected:
+>
+> ```css
+> swc-badge[variant='positive'] {
+>   --swc-badge-background-color: darkgreen;
+> }
+> ```
+>
+> Non-semantic color variants (`gray`, `red`, `orange`, `yellow`, `chartreuse`, `celery`,
+> `green`, `seafoam`, `cyan`, `blue`, `indigo`, `purple`, `fuchsia`, `magenta`, `pink`,
+> `turquoise`, `brown`, `cinnamon`, `silver`) are applied via internal class selectors.
+> A consumer attribute selector targeting one of these variants will not reliably override
+> its color properties — use a global (unscoped) override instead, which will affect all
+> variants:
+>
+> ```css
+> /* Works — but applies to all badge instances */
+> swc-badge {
+>   --swc-badge-background-color: rebeccapurple;
+> }
+> ```
+
 ---
 
 ## New in 2nd-gen

2nd-gen/packages/swc/components/divider/migration.md

@@ -71,8 +71,8 @@ Find and replace all instances of `sp-divider` with `swc-divider` in your templa
 
 ### CSS custom properties
 
-All `--mod-divider-*` custom properties have been renamed to `--swc-divider-*`. Update
-any overrides in your stylesheets:
+All `--mod-divider-*` custom properties have been removed. Replace them with the
+`--swc-divider-*` equivalents in your stylesheets:
 
 | Removed (1st-gen)                | Replacement (2nd-gen)                                                                                                                  |
 | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -94,6 +94,11 @@ swc-divider {
 }
 ```
 
+> **Note on `static-color` overrides:** When `static-color="white"` or
+> `static-color="black"` is set, the component applies color values via internal class
+> selectors to ensure correct contrast on static backgrounds. Consumer overrides of
+> `--swc-divider-background-color` will not take effect when `static-color` is in use.
+
 ---
 
 ### Shadow DOM structure

2nd-gen/packages/swc/components/icon/migration.md

@@ -183,7 +183,8 @@ to the nearest available size:
 
 ### CSS custom properties
 
-All `--mod-icon-*` custom properties have been renamed to `--swc-icon-*`:
+All `--mod-icon-*` custom properties have been removed. Replace them with the
+`--swc-icon-*` equivalents:
 
 | Removed (1st-gen)        | Replacement (2nd-gen)                                |
 | ------------------------ | ---------------------------------------------------- |

2nd-gen/packages/swc/components/progress-circle/migration.md

@@ -72,8 +72,8 @@ your templates and HTML.
 
 ### CSS custom properties
 
-All `--mod-progress-circle-*` custom properties have been renamed to
-`--swc-progress-circle-*`. Update any overrides in your stylesheets:
+All `--mod-progress-circle-*` custom properties have been removed. Replace them with the
+`--swc-progress-circle-*` equivalents in your stylesheets:
 
 | Removed (1st-gen)                          | Replacement (2nd-gen)                      |
 | ------------------------------------------ | ------------------------------------------ |
@@ -135,6 +135,12 @@ The `static-color` attribute now accepts `"black"` in addition to `"white"`, mat
 the Spectrum 2 specification. Use `static-color="black"` when placing the component on
 a light static background that falls outside the normal theme.
 
+> **Note:** When `static-color` is set, the component applies track and fill colors via
+> internal class selectors to ensure correct contrast. Consumer overrides of
+> `--swc-progress-circle-track-border-color` and
+> `--swc-progress-circle-fill-border-color` will not take effect when `static-color` is
+> in use.
+
 ```html
 <!-- 1st-gen: white only -->
 <sp-progress-circle

2nd-gen/packages/swc/components/status-light/migration.md

@@ -112,8 +112,8 @@ that best represents your use case:
 
 ### CSS custom properties
 
-All `--mod-statuslight-*` custom properties have been renamed to `--swc-statuslight-*`.
-Update any overrides in your stylesheets:
+All `--mod-statuslight-*` custom properties have been removed. Replace them with the
+`--swc-statuslight-*` equivalents in your stylesheets:
 
 | Removed (1st-gen)                           | Replacement (2nd-gen)              |
 | ------------------------------------------- | ---------------------------------- |
@@ -144,6 +144,29 @@ swc-status-light {
 }
 ```
 
+> **Note on per-variant color overrides:** Semantic variants (`neutral`, `info`,
+> `positive`, `negative`, `notice`) use attribute-based selectors internally, so
+> consumer per-variant overrides work as expected:
+>
+> ```css
+> swc-status-light[variant='positive'] {
+>   --swc-statuslight-dot-color: darkgreen;
+> }
+> ```
+>
+> Color variants (`yellow`, `chartreuse`, `celery`, `seafoam`, `cyan`, `indigo`,
+> `purple`, `fuchsia`, `magenta`, `pink`, `turquoise`, `brown`, `cinnamon`, `silver`)
+> are applied via internal class selectors. A consumer attribute selector targeting one
+> of these variants will not reliably override `--swc-statuslight-dot-color` — use a
+> global (unscoped) override instead:
+>
+> ```css
+> /* Works — but applies to all status-light instances */
+> swc-status-light {
+>   --swc-statuslight-dot-color: rebeccapurple;
+> }
+> ```
+
 ---
 
 ## New in 2nd-gen