diff --git a/contributor-docs/adrs/adr-022-css-layer-names.md b/contributor-docs/adrs/adr-022-css-layer-names.md new file mode 100644 index 00000000000..cafede3f1d4 --- /dev/null +++ b/contributor-docs/adrs/adr-022-css-layer-names.md @@ -0,0 +1,84 @@ +# CSS Layer Names + +## Status + +| Stage | Status | +| -------- | ----------- | +| Approved | 🚧 | +| Adopted | | + +## Context + +As Primer begins making use of CSS Layers, we need to define the named groups +and order of the layers that we create. This will help to ensure a consistent +ordering of layers and make sure that our naming is consistent across libraries. + +We have several areas that may be helpful to define explicit layers for: + +- Primitives +- Octicons +- Components +- Resets +- Utilities +- Product + +This ADR will determine the naming convention for CSS Layers and the order in +which they should be applied. + +## Decision + +Below is the list of CSS layers that we will use in Primer. They appear in the +order in which they should be applied. + +- `base`: base styles that are applied to the document and the root element. This includes things like resets, typography, and + global styles. +- `theme`: styles that are applied for theming. This layer includes `@primer/primitives` +- `icons`: styles that are applied to octicons +- `components`: styles that are applied to components +- `utilities`: an optional layer for utility classes in order to take precedence over earlier styles + +All layers should exist within the `primer` namespace and include a library, +where applicable. For example: + +```css +@layer primer.react.base { + /* ... */ +} + +@layer primer.css.components.Button { + /* ... */ +} +``` + +Libraries should only be included in a layer name if the name may exist across multiple +libraries, such as a component. We would not need to include a library name for +primitives as those would belong already in `theme` or for utilities from +primer/css as they would already be in `utilities`. + +This will allow downstream consumers to order `primer` layers in a way that +makes sense to the application. + +Naming for these layers must use `camelCase`. The only exception would be for +the names of components which must use `PascalCase`. + +### Impact + +This change will impact the following libraries: + +- primer/css: styles in this library should be wrapped in either the utilities + or icons layer. +- primer/primitives: styles in this library should be wrapped in the theme layer +- primer/octicons: styles in this library should be wrapped in the icons + layer +- primer/react: styles in this library should be wrapped in the components layer +- primer/view_components: styles in this library should be wrapped in the components + layer + +## Unresolved questions + +- Where should the order of CSS layers be defined? + +## Links & Resources + +- [Tailwind CSS v4 Integration for Material UI](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4/) +- [Mantine CSS Layers](https://mantine.dev/styles/mantine-styles/#css-layers)