The documentation at https://angular.io/guide/component-styles states this about :ng-deep:

The shadow-piercing descendant combinator is deprecated and support is being removed from major browsers and tools. As such we plan to drop support in Angular (for all 3 of /deep/, >>> and ::ng-deep).

As I understand, Angular was using the browser support for the piercing selectors /deep/ and >>>.

But :ng-deep is surely not supported by any browser.
And this is what I find confusing in the documentation. I don't understand what browser support has anything to do with :ng-deep.

The way I understand it, :ng-deep prevents Angular from appending the attribute selectors to all selector following it.

So, this CSS in a component:

:host ::ng-deep .my-button .ui-button-text {
    font-weight: bold;
}

will be transformed to:

[_nghost-c12]     .my-button .ui-button-text {
    font-weight: bold;
}

Without :ng-deep, this will be produced instead:

[_nghost-c12]     .my-button[_nghost-c12] .ui-button-text[_nghost-c12] {
    font-weight: bold;
}

(obviously breaking my intention).

I find 2 problems with the documentation, as it stands now:

• I don't see any relationship between lack of browser support for piercing selectors and deprecating :ng-deep
• I don't see any reason to deprecate :ng-deep (since it just tells Angular: "keep your attribute selectors away from my styles")

I propose the following:

• if I missed anything, and there is a valid reason why :ng-deep should be deprecated, the documentation should be changed to explain why
• if my reasoning above is correct, remove the section about deprecating :ng-deep, keeping the deprecation notice only for the piercing selectors /deep/ and >>>.