Skip to content

docs: add css layer names adr #6030

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+84 −0
Open

docs: add css layer names adr #6030

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5cb4d27
docs: add css layer names adr
joshblack May 9, 2025
99c7663
docs: include view_components in impact
joshblack May 15, 2025
e88745a
docs: add note on library in namespace
joshblack May 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions contributor-docs/adrs/adr-022-css-layer-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# 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
Comment on lines +33 to +38
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


All layers should exist within the `primer` namespace. For example:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we differentiate PVC css, PCSS css, and PRC css?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooo good point, Maybe primer.components.<library>.<component>? Or primer.<library>.components.<component>?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like primer.<library>.components.<component> cause then we can order layers @layer primer.css, primer.react


```css
@layer primer.base {
/* ... */
}

@layer primer.components.Button {
/* ... */
}
```

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you thinking this would be directly in our dist CSS files?

- 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

## Unresolved questions

- Where should the order of CSS layers be defined?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feel like we should include a recommended order, but leave it up to the consumer.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where should the order of CSS layers be defined?

Just to confirm, is the ask here where we should have the suggestions documented?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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;


## 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)
Loading