update stable selectors api

Author: francinelucca

…-docs/adrs/adr-023-data-component-api.md …ocs/adrs/adr-023-stable-selectors-api.mdcontributor-docs/adrs/adr-023-data-component-api.md renamed to contributor-docs/adrs/adr-023-stable-selectors-api.md contributor-docs/adrs/adr-023-data-component-api.md renamed to contributor-docs/adrs/adr-023-stable-selectors-api.md

@@ -1,4 +1,4 @@
-# Public `data-component` and `data-part` API for targeting component parts
+# Stable identifiers for Primer components
 
 📆 Date: 2026-02-20
 
@@ -7,23 +7,29 @@
 | Stage          | State       |
 | -------------- | ----------- |
 | Status         | Proposed ❓ |
-| Implementation |             |
+| Implementation | Pending ⚠️  |
 
 ## Context
 
-Primer React uses [CSS Modules](https://github.com/css-modules/css-modules) for
-styling. CSS Modules generate hashed class names (e.g.,
-`prc-ActionList-Item-cBBI`) that are not stable across versions. This makes it
-impossible for consumers to reliably target internal parts of a component for
-style overrides using class selectors.
-
-Consumers need the ability to target component parts for legitimate use cases:
-
-- Customizing the appearance of specific parts (e.g., hiding a trailing visual,
-  changing the font weight of a label)
-- Querying parts of a component in JavaScript (e.g., finding all selected items
-  in an action list)
-- Writing integration tests that target stable selectors
+Primer React components do not expose stable identifiers for their rendered DOM
+elements. Consumers who need to reference a specific component or slot in the
+DOM — for testing, tracking, monitoring, or querying — have no reliable way to
+do so.
+
+This creates problems across several areas:
+
+- **Testing.** Unit and end-to-end tests resort to brittle selectors like CSS
+  Module hashes (`prc-ActionList-Item-cBBI`), DOM structure assumptions, or
+  text content matching — all of which break silently when Primer is updated.
+- **Tracking and monitoring.** Consumers that want to measure how components are
+  used in production (e.g., counting how many ActionList items appear on a page)
+  have no stable hook to query against.
+- **JavaScript queries.** Finding all instances of a component or its parts in
+  the DOM (e.g., all selected items in an action list) requires knowledge of
+  internal implementation details.
+- **Style overrides.** When consumers do need to customize appearance, CSS
+  Module hashes are not stable across versions, leaving no reliable selector to
+  target.
 
 The `data-component` attribute is already used internally across multiple
 components (`Button`, `ActionList`, `PageHeader`, `UnderlineNav`, `Avatar`, and
@@ -43,14 +49,31 @@ without notice and coverage is incomplete — many component parts have no
 
 ## Decision
 
-Establish two **public, stable data attributes** for identifying components and
-their parts in the DOM:
+Establish two **public, stable data attributes** that act as reliable
+identifiers for Primer components and their parts in the DOM. Think of these as
+built-in test IDs — stable, predictable anchors that consumers can use for
+testing, tracking, monitoring, and querying without coupling to internal DOM
+structure.
 
 - **`data-component`** — identifies the root element of a component or
   sub-component.
 - **`data-part`** — identifies an inner structural part within a component.
 
-### Naming convention
+These attributes are primarily intended for:
+
+1. **Testing** — use them as locators in unit tests, integration tests, and
+   end-to-end tests instead of brittle class names or DOM paths.
+2. **Tracking and monitoring** — query the DOM for component usage metrics,
+   analytics, or observability.
+3. **JavaScript queries** — find specific components or parts
+   programmatically (e.g.,
+   `document.querySelectorAll('[data-component="ActionList.Item"]')`).
+4. **Simple CSS overrides** — as an added benefit, these selectors also
+   provide a stable target for style customizations when needed.
+
+### Implementation details
+
+#### Naming convention
 
 All values use PascalCase. The two attributes serve distinct roles:
 
@@ -59,7 +82,7 @@ data-component="ComponentName"     → root element of a component or sub-compon
 data-part="PartName"               → inner part within a component
 ```
 
-#### Rules
+##### Rules
 
 1. **Root components** get `data-component` with their React component name.
 
@@ -104,32 +127,46 @@ data-part="PartName"               → inner part within a component
    </li>
    ```
 
-### Relationship to CSS Modules and CSS Layers
+#### `data-component` and `data-part` on all components and slots
 
-`data-component` and `data-part` complement the existing styling architecture:
+All Primer components will receive a `data-component` attribute on their root
+element, and all meaningful slots will receive a `data-part` attribute. These
+attributes serve as the stable identifiers that consumers can use for targeting,
+ensuring full coverage across the library.
 
-- **CSS Modules** provide scoped class names for internal styling. Components
-  continue to use CSS Module classes for their own styles.
-- **CSS Layers** ([ADR-021](./adr-021-css-layers.md)) ensure that consumer
-  overrides take precedence over component styles regardless of specificity.
-- **`data-component` and `data-part`** provide the stable selectors that
-  consumers use to target components and their parts within those overrides.
+Every component must provide:
+
+- **`data-component`** on the root element of every component and public
+  sub-component
+- **`data-part`** on every internal structural element that a consumer might
+  reasonably need to target (labels, content wrappers, visual slots, action
+  slots)
 
-Together, these three mechanisms give consumers a complete override path:
+Elements that are purely for layout and have no semantic meaning (spacers,
+wrappers that exist only for CSS grid/flex layout) do not require either
+attribute.
 
-```css
-/* Target a component */
-[data-component='ActionList.Item'] {
-  border-radius: 8px;
-}
+#### ESLint rule in `eslint-plugin-primer-react`
 
-/* Target a slot within a component */
-[data-component='ActionList.Item'] [data-part='Label'] {
-  font-weight: 600;
-}
+A new ESLint rule will be added to `eslint-plugin-primer-react` that **warns**
+whenever a `data-component` or `data-part` selector is used in consumer code. The warning will
+inform consumers of the implications of relying on these selectors — namely that
+the surrounding DOM structure, attributes, parents, and children of the targeted
+element are not guaranteed to be stable.
+
+Consumers must **explicitly override** the
+rule on a per-usage basis to use a `data-component` selector. Overriding the
+rule acts as an acknowledgment that the consumer understands the risks and
+accepts responsibility for any breakage caused by structural changes to the
+component's DOM.
+
+```js
+/* eslint-disable primer-react/no-data-component-selector -- 
+   Intentionally targeting ActionList.Item for custom border radius. 
+   We accept that the surrounding DOM may change. */
 ```
 
-### Internal CSS usage
+#### Internal CSS usage
 
 Components may use `data-part` selectors in their own CSS Modules for targeting
 child parts. This replaces ad-hoc patterns like bare `[data-component='text']`
@@ -142,73 +179,100 @@ with the standardized naming:
 }
 ```
 
-### Coverage requirements
-
-Every component must provide:
-
-- **`data-component`** on the root element of every component and public
-  sub-component
-- **`data-part`** on every internal structural element that a consumer might
-  reasonably need to target (labels, content wrappers, visual slots, action
-  slots)
-
-Elements that are purely for layout and have no semantic meaning (spacers,
-wrappers that exist only for CSS grid/flex layout) do not require either
-attribute.
-
-### Testing requirements
+#### Testing requirements
 
 The presence and values of `data-component` and `data-part` attributes must be
 covered by tests. This can be achieved through:
 
 - Unit tests that assert the attributes are present on rendered elements
 - Snapshot tests that capture the attribute values
 
-Changing a `data-component` or `data-part` value is a **breaking change** and
-must follow the standard breaking change process.
+#### Documentation on Primer Docs
 
-### Versioning and breaking changes
+A dedicated section will be added to Primer Docs explaining what the stable
+selectors are intended for and what they are not intended for.
 
-Because `data-component` and `data-part` are **public API**, changes to them
-follow [Semantic Versioning](../versioning.md). The table below summarises what
-requires which kind of release:
+**Intended use cases:**
 
-| Change                                                             | semver bump |
-| ------------------------------------------------------------------ | ----------- |
-| A `data-component` or `data-part` attribute is added to an element | `minor`     |
-| A `data-component` or `data-part` value is renamed                 | `major`     |
-| A `data-component` or `data-part` attribute is removed             | `major`     |
-| An attribute is moved from one element to another                  | `major`     |
-| A `data-component` is changed to `data-part` or vice-versa         | `major`     |
+- **Unit tests** — targeting components and slots in test assertions
+  (e.g., `getByAttribute('data-component', 'ActionList.Item')`)
+- **End-to-end testing** — using stable selectors in Playwright or Cypress
+  locators instead of brittle class names or DOM structure
+- **Simple CSS selectors** — directly targeting a component or slot for style
+  overrides (e.g., `[data-component="Button"] { border-radius: 8px; }`)
 
-**Deprecation path.** Before removing or renaming a value in a major release,
-the old value should be deprecated in at least one prior minor release. During
-the deprecation window the component must emit a development-mode console
-warning (using the existing `warn` / `deprecate` helpers) so consumers have
-time to migrate.
+**Not intended for:**
 
-The [Migration](#migration) table below captures the full set of renames
-planned for the next major release.
+- **Complex CSS selector chaining** — sibling selectors (`~`, `+`), child
+  combinators (`>`), or parent selectors (`:has()`) that depend on DOM structure
+- **CSS hacks** — workarounds that rely on the internal layout, nesting, or
+  ordering of elements within a component
+- **Any code that assumes a specific DOM structure** — the DOM tree around a
+  `data-component` element (its parent, children, siblings, and attributes) is
+  not part of the public API and may change without notice
+
+The best solution is always to work alongside Primer for your use case. If you
+find yourself needing overly complex selectors or targeting `data-component`
+attributes for something bigger than their intended use, chances are there is a
+better approach. The Primer team is happy to help, guide, and assist with
+whatever your use case may be. The design system is always growing — if we are
+not covering your use case, we would love to hear from you, or even better,
+accept a contribution!
+
+### Relationship to CSS Modules and CSS Layers
+
+While the primary purpose of `data-component` and `data-part` is identification
+(testing, tracking, querying), they also serve as stable selectors for CSS
+overrides when consumers need to customize appearance.
+
+In that context, they complement the existing styling architecture:
+
+- **CSS Modules** provide scoped class names for internal styling. Components
+  continue to use CSS Module classes for their own styles.
+- **CSS Layers** ([ADR-021](./adr-021-css-layers.md)) ensure that consumer
+  overrides take precedence over component styles regardless of specificity.
+- **`data-component` and `data-part`** provide the stable selectors that
+  consumers can use to target components and their parts within those overrides.
+
+Example of a simple, supported override:
+
+> **Note:** This is an example for demo purposes only. In practice,
+> `ActionList.Item` accepts a `className` prop, which is better suited for this
+> type of override. You should always prefer the `className` prop over a stable
+> selector when possible.
+
+```css
+[data-component='ActionList.Item'] {
+  border-radius: 8px;
+}
+```
 
 ### Versioning and breaking changes
 
-Because `data-component` and `data-part` are **public API**, changes to them
-follow [Semantic Versioning](../versioning.md). The table below summarises what
-requires which kind of release:
+The **only** guarantee provided for `data-component` and `data-part` attributes is
+that they **exist** and are **tied to the most relevant DOM element** for each
+component and its slots.
 
-| Change                                                             | semver bump |
-| ------------------------------------------------------------------ | ----------- |
-| A `data-component` or `data-part` attribute is added to an element | `minor`     |
-| A `data-component` or `data-part` value is renamed                 | `major`     |
-| A `data-component` or `data-part` attribute is removed             | `major`     |
-| An attribute is moved from one element to another                  | `major`     |
-| A `data-component` is changed to `data-part` or vice-versa         | `major`     |
+The following aspects are **not** part of the public API and may change at any
+time without notice or a major semver bump:
 
-**Deprecation path.** Before removing or renaming a value in a major release,
-the old value should be deprecated in at least one prior minor release. During
-the deprecation window the component must emit a development-mode console
-warning (using the existing `warn` / `deprecate` helpers) so consumers have
-time to migrate.
+- The specific DOM element a `data-component` or `data-part` attribute is
+  applied to
+- The attributes, parent, or children of that element
+
+Because of this, consumers should only rely on the **direct targeting** of
+these selectors (e.g., `[data-component="ActionList.Item"]`). Chaining
+selectors that depend on DOM structure — such as parent, child, or sibling
+selectors — is **not supported** and may break without warning.
+
+| Change                                                             | semver bump   |
+| ------------------------------------------------------------------ | ------------- |
+| A `data-component` or `data-part` attribute is added to an element | `minor`       |
+| A `data-component` or `data-part` value is renamed                 | `major`       |
+| A `data-component` or `data-part` attribute is removed             | `major`       |
+| A `data-component` is changed to `data-part` or vice-versa         | `major`       |
+| The DOM element an attribute is applied to changes                 | `minor`       |
+| Attributes, parents, or children of the element change             | `patch/minor` |
 
 The [Migration](#migration) table below captures the full set of renames
 planned for the next major release.
@@ -253,9 +317,13 @@ Components that currently have no attributes on key parts must also be updated.
 
 ### Positive
 
-- **Stable selectors for consumers.** Consumers can target any component with
-  `[data-component="..."]` and any inner part with `[data-part="..."]` — both
-  are immune to CSS Module hash changes and version upgrades.
+- **Stable identifiers for testing.** Consumers can use `data-component` and
+  `data-part` as reliable locators in unit tests, integration tests, and
+  end-to-end tests — no more coupling to CSS Module hashes or DOM structure.
+- **Enables tracking and monitoring.** Consumers can query the DOM for component
+  usage metrics and observability without relying on implementation details.
+- **Enables JavaScript queries.** Consumers and tests can use
+  `querySelectorAll('[data-component="ActionList.Item"]')` reliably.
 - **Clear separation.** `data-component` answers "which component is this?"
   while `data-part` answers "which part of the component is this?" This makes
   the DOM self-documenting and avoids overloading a single attribute.
@@ -264,18 +332,16 @@ Components that currently have no attributes on key parts must also be updated.
 - **Scoped slot names.** Because `data-part` values are scoped to their parent
   `data-component`, names like `Label` or `LeadingVisual` can be reused across
   components without ambiguity.
-- **Enables JavaScript queries.** Consumers and tests can use
-  `querySelectorAll('[data-component="ActionList.Item"] [data-part="Label"]')`
-  reliably.
-- **Complements CSS Layers.** Together with ADR-021, this gives consumers a
-  complete, specificity-safe override mechanism.
+- **Supports CSS overrides.** Consumers who need to
+  customize styles have stable selectors to target, complementing CSS Layers
+  (ADR-021) for a complete override path.
 
 ### Negative
 
 - **Breaking change for existing consumers.** Anyone currently relying on the
-  undocumented `data-component` values (e.g., in CSS overrides or
-  `querySelector` calls) will need to update when values are renamed. This must
-  be coordinated in a major release.
+  undocumented `data-component` values (e.g., in tests, tracking code, CSS
+  overrides, or `querySelector` calls) will need to update when values are
+  renamed. This must be coordinated in a major release.
 
 ## Alternatives
 
@@ -302,7 +368,7 @@ applicable to our architecture.
 
 Continue using `data-component` informally without guaranteeing stability.
 
-**Why not chosen:** Consumers are already depending on these attributes for
-overrides (as seen in SelectPanel story CSS). Without a stability guarantee,
-any refactor can silently break consumer overrides. Formalizing the API
-acknowledges the reality and provides a proper contract.
+**Why not chosen:** Consumers are already depending on these attributes in
+tests, tracking code, and CSS overrides. Without a stability guarantee, any
+refactor can silently break consumer code. Formalizing the API acknowledges the
+reality and provides a proper contract.