<commit_before># Upgrading your UI Theme or Package Stylesheets

In addition to changes in Atom's scripting API, we'll also be making some breaking changes to Atom's DOM structure, requiring stylesheets in both packages and themes to be updated. Deprecation cop will list usages of deprecated selector patterns to guide you.

## Custom Tags

Rather than adding classes to standard HTML elements to indicate their role, Atom now uses custom element names. For example, `<div class="workspace">` has now been replaced with `<atom-workspace>`. Selectors should be updated accordingly. Note that tag names have lower specificity than classes in CSS, so you'll need to take care in converting things.

Old Selector        | New Selector
--------------------|--------------------------------
`.editor`           | `atom-text-editor`
`.editor.mini`      | `atom-text-editor[mini]`
`.workspace`        | `atom-workspace`
`.horizontal`       | `atom-workspace-axis.horizontal`
`.vertical`         | `atom-workspace-axis.vertical`
`.pane-container`   | `atom-pane-conatiner`
`.pane`             | `atom-pane`
`.tool-panel`       | `atom-panel`
`.panel-top`        | `atom-panel[location="top"]`
`.panel-bottom`     | `atom-panel[location="bottom"]`
`.panel-left`       | `atom-panel[location="left"]`
`.panel-right`      | `atom-panel[location="right"]`

## Supporting the Shadow DOM

Text editor content is now rendered in the shadow DOM, which shields it from being styled by global style sheets to protect against accidental style pollution. For more background on the shadow DOM, check out the [Shadow DOM 101][shadow-dom-101] on HTML 5 Rocks. If you need to style text editor content in a UI theme, you'll need to circumvent this protection for any rules that target the text editor's content. Some examples of the kinds of UI theme styles needing to be updated:

* Highlight decorations
* Gutter decorations
* Line decorations
* Scrollbar styling

During a transition phase, it will be possible to enable or disable the text editor's shadow DOM in the settings, so themes will need to be compatible with both approaches.

### Shadow DOM Selectors

Chromium provides two tools for bypassing shadow boundaries, the `::shadow` pseudo-element and the `/deep/` combinator. For an in-depth explanation of styling the shadow DOM, see the [Shadow DOM 201][shadow-dom-201] article on HTML 5 Rocks.

#### ::shadow

The `::shadow` pseudo-element allows you to bypass a single shadow root. For example, say you want to update a highlight decoration for a linter package. Initially, the style looks as follows:

```css
// Without shadow DOM support
atom-text-editor .highlight.my-linter {
  background: hotpink;
}
```

In order for this style to apply with the shadow DOM enabled, you will need to add a second selector with the `::shadow` pseudo-element. You should leave the original selector in place so your theme continues to work with the shadow DOM disabled during the transition period.

```css
// With shadow DOM support
atom-text-editor .highlight.my-linter,
atom-text-editor::shadow .highlight.my-linter {
  background: hotpink;
}
```

Check out the [find-and-replace][find-and-replace] package for another example of using `::shadow` to pierce the shadow DOM.

#### /deep/<commit_msg>Add one more bullet point<commit_after># Upgrading your UI Theme or Package Stylesheets

In addition to changes in Atom's scripting API, we'll also be making some breaking changes to Atom's DOM structure, requiring stylesheets in both packages and themes to be updated. Deprecation cop will list usages of deprecated selector patterns to guide you.

## Custom Tags

Rather than adding classes to standard HTML elements to indicate their role, Atom now uses custom element names. For example, `<div class="workspace">` has now been replaced with `<atom-workspace>`. Selectors should be updated accordingly. Note that tag names have lower specificity than classes in CSS, so you'll need to take care in converting things.

Old Selector        | New Selector
--------------------|--------------------------------
`.editor`           | `atom-text-editor`
`.editor.mini`      | `atom-text-editor[mini]`
`.workspace`        | `atom-workspace`
`.horizontal`       | `atom-workspace-axis.horizontal`
`.vertical`         | `atom-workspace-axis.vertical`
`.pane-container`   | `atom-pane-conatiner`
`.pane`             | `atom-pane`
`.tool-panel`       | `atom-panel`
`.panel-top`        | `atom-panel[location="top"]`
`.panel-bottom`     | `atom-panel[location="bottom"]`
`.panel-left`       | `atom-panel[location="left"]`
`.panel-right`      | `atom-panel[location="right"]`

## Supporting the Shadow DOM

Text editor content is now rendered in the shadow DOM, which shields it from being styled by global style sheets to protect against accidental style pollution. For more background on the shadow DOM, check out the [Shadow DOM 101][shadow-dom-101] on HTML 5 Rocks. If you need to style text editor content in a UI theme, you'll need to circumvent this protection for any rules that target the text editor's content. Some examples of the kinds of UI theme styles needing to be updated:

* Highlight decorations
* Gutter decorations
* Line decorations
* Scrollbar styling
* Anything targeting a child selector of `.editor`

During a transition phase, it will be possible to enable or disable the text editor's shadow DOM in the settings, so themes will need to be compatible with both approaches.

### Shadow DOM Selectors

Chromium provides two tools for bypassing shadow boundaries, the `::shadow` pseudo-element and the `/deep/` combinator. For an in-depth explanation of styling the shadow DOM, see the [Shadow DOM 201][shadow-dom-201] article on HTML 5 Rocks.

#### ::shadow

The `::shadow` pseudo-element allows you to bypass a single shadow root. For example, say you want to update a highlight decoration for a linter package. Initially, the style looks as follows:

```css
// Without shadow DOM support
atom-text-editor .highlight.my-linter {
  background: hotpink;
}
```

In order for this style to apply with the shadow DOM enabled, you will need to add a second selector with the `::shadow` pseudo-element. You should leave the original selector in place so your theme continues to work with the shadow DOM disabled during the transition period.

```css
// With shadow DOM support
atom-text-editor .highlight.my-linter,
atom-text-editor::shadow .highlight.my-linter {
  background: hotpink;
}
```

Check out the [find-and-replace][find-and-replace] package for another example of using `::shadow` to pierce the shadow DOM.

#### /deep/
{'fraction_non_alphanumeric': 0.10330765745355687, 'fraction_numerical': 0.004228968433771334, 'mean_word_length': 3.757183908045977, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7647286', 'n_tokens_mistral': 1796, 'n_tokens_neox': 1688, 'n_words': 830}