Establish coding conventions

[bradfrost]

We need to arrive at how HTML, CSS, and JavaScript would be authored, which would be followed by anyone contributing to this project.

Here is a strawman coding guidelines. which is not entirely comprehensive, nothing set in stone. But good for facilitating discussion: https://vanilla-full.netlify.app/?path=/docs/documentation-guidelines--docs

These conventions would be encoded into linting tools and become part of the review/PR process

[bradfrost]

The goal: agree upon the coding conventions to be used to author the library. All patterns and contributions will follow these code guidelines. It's important for these conventions to be consistent to ensure quality, understandability, linting/QA, and ease of contribution.

Of course, there are many, many, many ways to write HTML, CSS, and JavaScript (and we will need to decide how to handle JS in general). But the goal here is to pragmatically agree on code conventions in order to unlock all the exciting development work ahead. It will be important to agree on the code principles that will guide the specific implementation. You can see some principles here, but there will be some shared values like:

• Accessibility is paramount
  • People (and machines!) will copy-and-paste (as well as import through components) these patterns.
  • Therefore, any source code needs to embody accessibility best practices
  • Recognition that accessible patterns/components won't solve
    • Components can be misused by consumers. The library can provide guidance but ultimately can't prevent people from misusing them.
    • The design token architecture provides for a lot of flexibility, which can also be misused by consumers (e.g. defining colors that don't have sufficient contrast). Again, the library can provide guidance but ultimately can't prevent people from misusing them.
• Internationalization (writing modes, translation, logical properties, et al)
  • Content in attributes vs text nodes has gotchas
  • Generated content gotchas
• Privacy & security
• Clarity over succinctness
• Avoid clever code & hacks
• Pragmatism over idealism
  • W3C standards work vs "this is a solid component library that serves 80/20 rule"
• Rigor
  • While not as rigorous as W3C standards process, it still has wide/deep review by domain experts.
• Baseline Support
  • Technology choices (e.g. @layer) used by the pattern library should be
  • Sturdy, well-adopted, etc
  • Future-friendly (can enhance the experience with new(er) browser features, but provide sturdy foundations

And of course there are language-specific principles for HTML (e.g. use semantic markup), CSS (e.g. reduce specificity), and JS. Feel free to weigh in on this comment with principles you think are important to consider.

We're going to focus on a few components outlined in #2 as we put the code conventions together. I'll share some strawman code for conversation ahead of next week's session.

[sashafirsov]

There is no mention of tokens to be usedin theming. Those are the basic blocks on which css props and classes based on. I could propose some fro consumer semantic theming...

[bradfrost]

There is no mention of tokens to be usedin theming. Those are the basic blocks on which css props and classes based on. I could propose some fro consumer semantic theming...

@sashafirsov Right! That's handled separately in #14