Update CSS Best Practices #408

dmtrmrv · 2025-08-21T19:07:29Z

Description of the Change

This PR completely restructures and modernizes the CSS best practices documentation (_includes/markdown/CSS.md and css.md) to provide more comprehensive, actionable, and modern guidance for writing maintainable CSS.

Benefits:

More actionable guidance for developers at all levels
Better alignment with modern CSS development practices
Improved maintainability and scalability guidance
Enhanced accessibility considerations throughout
Clear migration path for adopting new CSS features

Verification steps:

Review the updated table of contents in css.md matches the new section structure
Verify all internal anchor links work correctly
Check that code examples are syntactically correct and follow established formatting
Ensure the mobile-first and accessibility principles are consistently applied throughout

How to test the Change

Build and serve the Jekyll site locally:
```
bundle install
bundle exec jekyll serve
```
Navigate to the CSS section (/css/) and verify:
- All navigation links in the sidebar work correctly
- Internal anchor links jump to the correct sections
- Code examples are properly formatted and highlighted
- Content flows logically from general principles to specific implementation details
Cross-reference with the main index page (/) to ensure:
- CSS section links are updated and functional
- The updated navigation structure is reflected in the homepage listing
Validate content accuracy:
- Review code examples for correctness
- Ensure all external links are functional
- Verify that the guidance aligns with current CSS best practices

Changelog Entry

Changed - Completely restructured and modernized CSS best practices documentation with updated methodologies, modern CSS features guidance, and enhanced practical examples

Credits

Props @dmtrmrv @joesnellpdx @dainelmawer @Antonio-Laguna

Checklist:

I agree to follow this project's Code of Conduct.
I have updated the documentation accordingly.
I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
All new and existing tests pass.

dainemawer

@dmtrmrv - really great job, I fully support your guidance here, I left quite a few comments - feel free to accept or ignore the suggestions. I would like to see some more concrete examples of using modern (supported) css to achieve cleaner outcomes, perhaps that can be a phase 2 thing.

_includes/markdown/CSS.md

dainemawer · 2025-08-22T10:23:34Z

_includes/markdown/CSS.md

+When you start a new codebase, pause before writing components and choose a CSS methodology—such as ITCSS, BEM, or a utility-first approach—that fits the project’s size, maintenance horizon, and team expertise. Committing to a structured methodology early establishes clear naming rules, predictable specificity, and sensible file organization. These guardrails ease onboarding, minimize refactors, and save both time and budget over the life of the project.

-Let's be honest, CSS "speed" and performance is not as important as PHP or JavaScript performance. However, this doesn't mean we should ignore it. A sum of small improvements equals better experience for the user.
+If you opt to design a custom architecture, capture every key choice: folder layout, naming conventions, tooling, and any deviations from common patterns. A short explanation of why each decision was made helps future contributors understand the system quickly and avoids guesswork.


@dmtrmrv Im wondering if we should include something about AI here - certain AI prompts for specific frameworks that can help with context sharing or standardization. Even the use of AI to better understand the CSS implementation - where theres overlap / redundancy or bloated code.

dainemawer · 2025-08-22T10:45:07Z

_includes/markdown/CSS.md

-* If you need more complex animations, use a JavaScript animation framework or requestAnimationFrame.
+* **Reach for media queries last.** Instead of relying heavily on media queries to adjust styles, focus on building layouts and components that adapt naturally to different screen sizes. Media queries should be a fallback for cases where intrinsic solutions won’t work.  
+* **Leverage clamp().** Use the clamp() function to create fluid, responsive values for properties like font sizes, spacing, and widths. It allows you to define a minimum, preferred, and maximum value, so elements scale dynamically without needing media queries.  
+* **Use intrinsic layouts with CSS Grid.** Grid layouts are inherently responsive and let you define flexible areas that adjust automatically to available space. Pair grids with techniques like minmax() and auto-fit for dynamic behavior without extra breakpoints.


This is huge and an often poorly considered point - would love to expand on this further

Agreed - at least maybe a link to a 3rd party article to start. This would be a great Learning & Knowledge session internally!

_includes/markdown/CSS.md

dainemawer · 2025-08-22T10:48:45Z

_includes/markdown/CSS.md

+### Animations (@keyframes)
+
+* Use clear action-based names (e.g., fade-in, slide-up).  
+* Maintain short, intuitive names indicating the animation’s behavior.


@dmtrmrv if using ITCSS, its worth noting where Animations should be placed within the triangle.

_includes/markdown/CSS.md

joesnellpdx

@dmtrmrv

Really awesome work! I'm sorry that some of this feedback should have been in the GDoc - but sometime swicthing context brings new perspective.

Please reach out to the team if you have any questions, thoughts, or would like some help moving anything forward!

Also, I 100% defer to you on any of my suggestions. Feel free to disregard/ignore as you see fit!

Otherwise - I approve!

_includes/markdown/CSS.md

joesnellpdx · 2025-08-22T15:42:42Z

_includes/markdown/CSS.md

-2. Regular styles (allows overriding extended styles)
-3. @include (to visually separate mixins and placeholders) and media queries
-4. Nested selectors
+By thoughtfully implementing and balancing resets, normalization, and custom global styles, you can establish a CSS foundation that fosters maintainability, consistency, and scalability for your project.


I like that suggestion, but also remember this best practices is to be somewhat agnostic - where we can be more prescriptive within our tooling or internal guides.

_includes/markdown/CSS.md

joesnellpdx · 2025-08-22T16:33:06Z

_includes/markdown/CSS.md

+
+### Example
+
+Let’s say you have a Card component. Avoid doing this:


@dmtrmrv

Now that I see this, I am wondering if we should add an example where we use relative values (i.e. em) to provide relative margin depending on context for vertical rhythm (i.e. headings)? I know you mention the lobotomized owl below, but this is an area I do see folks get hung up on - so a quick and easy example might be helpful. I 100% defer to you though! Simply a suggestion. If you feel this is an anti-pattern - please ignore.

joesnellpdx · 2025-08-22T16:35:17Z

_includes/markdown/CSS.md

-* If you need more complex animations, use a JavaScript animation framework or requestAnimationFrame.
+* **Reach for media queries last.** Instead of relying heavily on media queries to adjust styles, focus on building layouts and components that adapt naturally to different screen sizes. Media queries should be a fallback for cases where intrinsic solutions won’t work.  
+* **Leverage clamp().** Use the clamp() function to create fluid, responsive values for properties like font sizes, spacing, and widths. It allows you to define a minimum, preferred, and maximum value, so elements scale dynamically without needing media queries.  
+* **Use intrinsic layouts with CSS Grid.** Grid layouts are inherently responsive and let you define flexible areas that adjust automatically to available space. Pair grids with techniques like minmax() and auto-fit for dynamic behavior without extra breakpoints.


Agreed - at least maybe a link to a 3rd party article to start. This would be a great Learning & Knowledge session internally!

_includes/markdown/CSS.md

Co-authored-by: Joe Snell <[email protected]>

… choices in documentation

…ing-Best-Practices into feature/css-best-practices

Antonio-Laguna

Fantastic work!

This is a clear, thoughtful, and highly practical guide.

I like the emphasis on content-first thinking, mobile-first strategy, and accessibility throughout.
The guidance on keeping specificity low, avoiding overuse of shorthands, and managing margins/gaps at the container level is really great!

The stress-testing mindset, sensible use of logical properties, and progressive enhancement with @supports and clamp() make the recommendations both modern and pragmatic.

The structure is easy to follow, examples are actionable, and the tone encourages consistency and collaboration.

Overall, this reads like a playbook teams can adopt with confidence. Great job!

I left some minor comments regarding consistency and some minor checking on grammar/clarity. There are also some suggestions on Accessibility around motion, let me know what you think!

css.md

_includes/markdown/CSS.md

Antonio-Laguna · 2025-08-25T11:03:34Z

_includes/markdown/CSS.md

+Style the project as if Desktop doesn’t exist first and then expand or override rules for the desktop.

-Avoid:
+With the capabilities of modern CSS it is usually best to reach for media queries last and use features like auto-rows in CSS Grid or functions like clamp() to create layouts that are mobile and desktop-friendly.


While I agree, I'm not sure this should live within a Best Practices doc?

_includes/markdown/CSS.md

Co-authored-by: Antonio Laguna <[email protected]>

…ing-Best-Practices into feature/css-best-practices

Co-authored-by: Joe Snell <[email protected]>

dmtrmrv added 2 commits August 21, 2025 14:53

Update CSS best practices documentation with new guidelines

569b28d

Update CSS documentation with new best practices and fix formatting

3116c51

dmtrmrv requested review from Antonio-Laguna, dainemawer, fabiankaegy and joesnellpdx August 21, 2025 19:07

dainemawer requested changes Aug 22, 2025

View reviewed changes

joesnellpdx reviewed Aug 22, 2025

View reviewed changes

dmtrmrv and others added 10 commits August 22, 2025 16:03

Update wording

d9d5cc8

Consolidate "Assume intent" and "Build on established patterns first"

e3cd3ed

Clarify wording in CSS documentation

cb01736

Add guideline for JavaScript-specific CSS naming conventions

019e19a

Add snippet highlighting

90d0a23

Co-authored-by: Joe Snell <[email protected]>

Add snippet highlighting

70a48e9

Co-authored-by: Joe Snell <[email protected]>

Add snippet highlighting

781a8c8

Co-authored-by: Joe Snell <[email protected]>

Add snippet highlighting

78b1561

Co-authored-by: Joe Snell <[email protected]>

Emphasize the importance of maintaining a record of key architectural…

b99435f

… choices in documentation

Merge branch 'feature/css-best-practices' of github.com:10up/Engineer…

ebe018d

…ing-Best-Practices into feature/css-best-practices

Antonio-Laguna reviewed Aug 25, 2025

View reviewed changes

dmtrmrv and others added 11 commits September 1, 2025 11:15

Add guideline to avoid excessive nesting of CSS variables

644ccf2

Clarify guidance on using automated tooling in CSS

9c680ae

Use 10up for the name

980f16f

Fix typo

7892e52

Co-authored-by: Antonio Laguna <[email protected]>

Fix typos in CSS documentation headings

21b1050

Update language

8159596

Co-authored-by: Antonio Laguna <[email protected]>

Update language

c279bed

Co-authored-by: Antonio Laguna <[email protected]>

Update language

1e5a20c

Co-authored-by: Antonio Laguna <[email protected]>

Update CSS documentation to replace max-inline-size with max-width

251ef23

Merge branch 'feature/css-best-practices' of github.com:10up/Engineer…

51ad057

…ing-Best-Practices into feature/css-best-practices

Fix typos in CSS documentation

0d635ad

dmtrmrv and others added 8 commits September 1, 2025 11:36

Update language for tone

eac77bd

Fix indentation in CSS documentation

90bb861

Fix formatting

24463d8

Co-authored-by: Joe Snell <[email protected]>

Add useful resources to CSS documentation

840de17

Add note on shorthand properties in CSS documentation

6547dff

Add guidance on naming design tokens in CSS documentation

971ae84

Add useful resources to CSS documentation

f7e62f9

Add ITCSS resource to CSS documentation

e9b274b


		### Example

		Let’s say you have a Card component. Avoid doing this:

Uh oh!

Update CSS Best Practices #408

Are you sure you want to change the base?

Update CSS Best Practices #408

Conversation

dmtrmrv commented Aug 21, 2025

Description of the Change

How to test the Change

Changelog Entry

Credits

Checklist:

Uh oh!

dainemawer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

joesnellpdx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Antonio-Laguna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants