Update CSS Best Practices

[dmtrmrv]

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:

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

How to test the Change

1. Build and serve the Jekyll site locally:

   bundle install
   bundle exec jekyll serve

2. 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

3. 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

4. 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.

[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!

[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!

[kdo]

@dmtrmrv great job working on this!! I left 2 tiny comments, and I have a more general question, I wonder if logical properties should be promoted as the default now? It makes more sense to me to always use those 🤔
Thanks!

[asvinb]

Nice work @dmtrmrv . I notice that CSS logical properties is mentioned only once in an example. With excellent browser support and the significant benefits for maintainability and RTL support, maybe we should expand a little bit more on that?