docs: add css layer names adr #6030
Conversation
|
There was a problem hiding this comment.
Pull Request Overview
This PR introduces an ADR to define the named CSS layers and their application order within Primer.
- Specifies five core layers (
base,theme,icons,components,utilities) and their ordering - Establishes naming conventions (camelCase for layers, PascalCase for component layers) and namespace usage
- Details the impact on Primer libraries and poses an unresolved question about where ordering should be defined
Comments suppressed due to low confidence (1)
contributor-docs/adrs/adr-022-css-layer-names.md:8
- [nitpick] The status table shows 'Approved' with 🚧 and comments out 'Adopted'. Update the table to reflect the current stage or uncomment the Adopted status when appropriate, and use consistent labels to avoid confusion.
| Adopted | <!-- ✅ --> |
joshblack
requested review from
jonrohan,
lukasoppermann,
langermank,
hectahertz and
TylerJDev
size-limit report 📦
|
| - `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. For example: |
There was a problem hiding this comment.
Should we differentiate PVC css, PCSS css, and PRC css?
There was a problem hiding this comment.
Ooo good point, Maybe primer.components.<library>.<component>? Or primer.<library>.components.<component>?
There was a problem hiding this comment.
I like primer.<library>.components.<component> cause then we can order layers @layer primer.css, primer.react
|
|
||
| ## Unresolved questions | ||
|
|
||
| - Where should the order of CSS layers be defined? |
There was a problem hiding this comment.
Feel like we should include a recommended order, but leave it up to the consumer.
|
|
||
| ## Unresolved questions | ||
|
|
||
| - Where should the order of CSS layers be defined? |
There was a problem hiding this comment.
Where should the order of CSS layers be defined?
Just to confirm, is the ask here where we should have the suggestions documented?
There was a problem hiding this comment.
Yeah! Exactly, either documented or could be a file that we author the order in like:
/* base.css */
@layer primer.base, primer.reset, primer.components, primer.utilities;
|
|
||
| - 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 |
There was a problem hiding this comment.
Are you thinking this would be directly in our dist CSS files?
| - `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 |
There was a problem hiding this comment.
Non-blocking nitpick: I see the library mentioned (and used) below, but not in this list. Might be helpful to add it here after base or theme.
View Rendered ADR
Adds an ADR in order to define our CSS Layers and the order that they should be applied in. I wanted to take a stab at defining this for us as we start moving more into CSS Layers world. Defining the layers and their order should help address issues like: https://github.com/github/primer/issues/5181 since we will have a deterministic order in which styles are applied.
This was a quick draft so let me know if you have any questions or feedback! In particular, would love to see any resources you all might have that talk about this in other systems 👀 I linked a couple but I'm sure there are more out there.