From a82a2e622e36793f03b7b05bd96e5280961fb070 Mon Sep 17 00:00:00 2001 From: Brad Frost Date: Tue, 16 Sep 2025 12:56:29 -0400 Subject: [PATCH 1/3] Work-in-progress code styles for discussion --- docs/style-guide.md | 255 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 221 insertions(+), 34 deletions(-) diff --git a/docs/style-guide.md b/docs/style-guide.md index 84c3d21..a60f23e 100644 --- a/docs/style-guide.md +++ b/docs/style-guide.md @@ -1,33 +1,62 @@ -# Open UI Global Design System Component Code Style Guidelines +# Open UI Global Design System Code Style Guidelines -This document outlines the Code Style guidelines for the components that are -part of the Open UI Global Design System (OUI). Additional guidelines will be -needed for the tooling and apps that support the components, as well as for any -framework-specific implementations of OUI. +This document outlines the Code Style guidelines for the components that are part of the Open UI Global Design System (OUI). + +- This is a living document and meant to reflect reality. When a question arises that is not covered, the guidelines should be updated with the new guidance. +- Code guidelines should make it *easier* to contribute, by reducing the number of arbitrary decisions a developer needs to make, while not being onerous to follow. This document tries to find that balance. +- When possible, these guidelines should be enforced through tooling. Otherwise, they are enforced through the PR approval process. -- This is a living document and meant to reflect reality. When a question arises - that is not covered, the guidelines should be updated with the new guidance. -- Code guidelines should make it *easier* to contribute, by reducing the number - of arbitrary decisions a developer needs to make, while not being onerous to - follow. This document tries to find that balance. -- When possible, these guidelines should be enforced through tooling. Otherwise, - they are enforced through the PR approval process. +Additional guidelines will be needed for the tooling and apps that support the components, as well as for any +framework-specific implementations of OUI. -In addition to the criteria for inclusion outlined elsewhere, OUI follows these -coding principles and conventions. +In addition to the criteria for inclusion outlined elsewhere, OUI follows these coding principles and conventions. ## OUI Implementations -The primary implementation of the global design system will be copyable -HTML/CSS/JS snippets that show a variety of states +### OUI Patterns +The primary implementation of the global design system will be HTML, CSS, and JavaScript code patterns that can be referenced (by humans and AI models), copied-and-pasted, and included in projects. + +- **HTML** is surfaced as code snippets on an easy-to-browse website +- **CSS** are available as a consumable asset (akin to `https://cdn/bootstrap.min.css`) as well as surfaced on the website +- **Design tokens** are available as a customizable starter file, and the website showcases different themes (akin to CSS Zen Garden) + +### Web Components implementations +An accompanying Web Component library is also in the works, which delivers the OUI pattern code as a consumable package that can be directly imported and used by web applications and libraries. -In the future, there will also be web component implementations, as well as -framework-specific implementations that either wrap or emulate a component, with -adjustments needed to make the component usable in React, Svelte, Vue, etc. -These implementations are expected to have an API and output that aligns with -the primary implementations. +### Framework-specific implementations +OUI patterns can also be implemented in any other web-based framework. Framework-specific implementations can: +- **Reference/re-implement** the OUI pattern HTML, CSS, JS and marry that code with framework-specific conventions +- **Wrap Web Components** with adjustments needed to make the component usable in the specific framework. + +These implementations are expected to have an API, naming, and output that aligns with the primary implementations. + +## Design Principles +- **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 + - There is a recognition that accessible patterns/components won't solve all problems + - 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** - + - This is a global initiative + - Accommodating different writing modes, translations, number/date/time formats, is critical + - The library embodies best practices (e.g. using logical properties) to accommodate internationalized experiences + - The library will consider various quirks (such as attributes, text nodes, and generated-content) +- **Privacy & security** - It is critical that any code associated with the OUI Global Design System to be private and secure. +- Pragmatism over idealism + W3C standards work vs "this is a solid component library that serves 80/20 rule" +- **Rigor** - While this effort as rigorous as the full-blown 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 +- **A living source** - The library can provide sturdy foundations for today’s technology, and enhance the experience over time when emerging browser features become available +- **Curate, not invent** - This library curates and normalizes _existing_ best practices established in existing design systems rather than inventing new solutions +- **Quality and Durability** - OUI code should be well-architected, intuitive, legible, readable, understandable, maintainable, and extensible. + - **Legibility over succinctness** - + - **Avoid clever code & hacks** - + - **Extensibility** - ## Code style guidelines +The ambition of this effort in addition to the multi-dimensional delivery means that getting names ### Namespace @@ -56,25 +85,183 @@ the primary implementations. ### CSS principles -- **Portable** - The CSS architecture uses CSS classes for styling in order to - ensure the CSS is portable across frameworks and web technologies. -- **Clarity over brevity** - CSS class naming conventions are verbose, but they - deliver clarity, legibility, and resilience in exchange. -- **Modular** - Component styles are fully modular in order to keep things +- **Modular** - Modular CSS architecture is a best practice, is great for DX, is more matinainable, and helps avoid style collisions tightly scoped and to avoid unintended style bleeding. -- **Limit chaining and multiple selectors** - Chaining and descendant selectors - should be avoided wherever possible in order to keep CSS as DOM-independent - and modular as possible. +- **Clarity over brevity** - CSS class naming conventions prioritize clarity, legibility, and resilience over succinctness and saving bytes +- **Limit specificity** - Overly-specific styles should be avoided for manageability, maintainability, and DX. + + + + + + + + +------ + + +## HTML Naming Conventions +- Using appropriate HTML tags is a given. +- TODO: populate HTML-specific naming conventions + +## CSS Naming Conventions + +### 1. Determine CSS selectors + +Options: classes, data attributes, IDs (#yolo), other +Propose: CSS classes +Rationale: Standard convention + +### 2. Determine CSS style/methodology + +Options: BEM, BEMIT, OOCSS, SMACSS, ITCSS, SUIT CSS, CUBE CSS, RSCSS, Utility-first (Tailwind, Atomic) +Propose: Some BEM-style syntax +Rationale: Clarity over brevity. Hierarchical. At-a-glance. +Example: + +``` +.alert + +.alert--success + +.alert--error + +.alert__icon + +.alert__body + +``` + + +### 3. Determine a global namespace + +Options: `oui-` `www-` `web-` `w3c-` + +Propose: +Rationale: + +(note: It would be amazing to have something that hints at its global nature! `www`, `web` or `w3c` would be badass, but I also acknowledge those might be a more challenging sell) + +###4. Determine component naming standard + +Options: `oui-alert`, `oui-button-group`, `oui-c-alert`, +Propose: `oui-[component-name]` +Rationale: Feels generally clean + +### 5. Determine variant names + +#### 5a. Determine component state-based names +Code will use native pseudoselectors (e.g. `:hover`, `:focus-visible`, etc). However, there are other states to account for, in addition to artificially triggering a specific state of a component + +Options: +- Modifier class: `button--hover`, `focus`, `active`, `disabled` +- Modifier class with `is-`: `is-hovered`, `is-active`, `is-disabled` +- Use attributes: `[disabled]`, `[aria-expanded="true"]` + +Propose: +Rationale: + +#### 5b. Determine status variant names + +Options: +- BAD: `error`, `danger`, `critical`, `destructive`, `blocked`, `negative` +- GOOD: `success`, `valid`, `positive`, `complete` +- CAUTION: `caution`, `warning`, ` +- INFO: `info`, `neutral`, `default` + +Propose: `error`, `success`, `warning`, `info` +Rationale: Common convention across many design systems + + +5c: Sizing names + +Options: +- `small`, `medium`, `large`, `extra-large` +- `sm`, `md`, `lg`, `xl` +- more + +Propose: +Rationale: + +5d: Spacing names + +Options: +- `small`, `medium`, `large`, `extra-large` +- `sm`, `md`, `lg`, `xl` +- `4`, `8`, `12`, `16`, etc + +Propose: +Rationale: + +### 6. Component states +Options: +- Pseudo-class names: hover, focus, active, disabled +- Boolean prefix: is-hovered, is-active +- ARIA/data attributes: [data-state="open"], [aria-invalid="true"] + + +### 6: Media query names/units + +Note: this is weird as media queries don't support CSS custom properties. But it's probably good to have them as quasi-variables or potentially think about how to use Sass with them. + +Options: +- raw values `30rem`, `56rem` +- `desktop`, `tablet`, `mobile` +- `small`, `medium`, `large`, `extra-large` +- `sm`, `md`, `lg`, `xl` +- `bp-1`, `bp-2`, `bp-3` + +Propose: +Rationale: + + + +### 7. Determine CSS declaration structure + +Options: + +Structural + +``` +.oui-alert { + /* Structural (hard-coded) styles */ + [positioning] + [box model] + [other] + + /* Themeable styles */ + [color] + [typography] + [border] + [shadow] + [animation] + [other] +} +``` + +Alphabetical + +``` +.oui-alert { + align-content: + ... + z-index +} +``` + +Proposal: +Rationale: + + + + + + -### CSS conventions -*TODO: Add class naming rules* -*TODO: Add property usage rules, for instance preference for logical properties* -## JavaScript -*TODO: Add JavaScript principles and conventions* ## Credits From 72c20de3c170c7d4df9419881d7321bb159c3ed5 Mon Sep 17 00:00:00 2001 From: Brad Frost Date: Tue, 16 Sep 2025 13:30:46 -0400 Subject: [PATCH 2/3] Update CSS style options in style guide Added 'Parent class + raw elements inside' to CSS options. --- docs/style-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/style-guide.md b/docs/style-guide.md index a60f23e..570c930 100644 --- a/docs/style-guide.md +++ b/docs/style-guide.md @@ -114,7 +114,7 @@ Rationale: Standard convention ### 2. Determine CSS style/methodology -Options: BEM, BEMIT, OOCSS, SMACSS, ITCSS, SUIT CSS, CUBE CSS, RSCSS, Utility-first (Tailwind, Atomic) +Options: BEM, BEMIT, OOCSS, SMACSS, ITCSS, SUIT CSS, CUBE CSS, RSCSS, Utility-first (Tailwind, Atomic), Parent class + raw elements inside. Propose: Some BEM-style syntax Rationale: Clarity over brevity. Hierarchical. At-a-glance. Example: @@ -265,4 +265,4 @@ Rationale: ## Credits -- https://vanilla-full.netlify.app/?path=/docs/documentation-guidelines--docs \ No newline at end of file +- https://vanilla-full.netlify.app/?path=/docs/documentation-guidelines--docs From fa073d5db20c3bb99add8a70f435f8640ff08209 Mon Sep 17 00:00:00 2001 From: Brad Frost Date: Fri, 14 Nov 2025 11:05:19 -0500 Subject: [PATCH 3/3] Refine style guide by removing TODOs and adding comments Removed TODO sections for namespace and variants in the style guide. Updated CSS principles for clarity and added a section on commenting conventions. --- docs/style-guide.md | 182 +++++--------------------------------------- 1 file changed, 17 insertions(+), 165 deletions(-) diff --git a/docs/style-guide.md b/docs/style-guide.md index 570c930..bb73899 100644 --- a/docs/style-guide.md +++ b/docs/style-guide.md @@ -58,14 +58,6 @@ Sturdy, well-adopted, etc ## Code style guidelines The ambition of this effort in addition to the multi-dimensional delivery means that getting names -### Namespace - -*TODO: Document namespace* - -### Variants - -*TODO: Add guidelines for color, size and other variants* - ## HTML ### HTML principles @@ -85,184 +77,44 @@ The ambition of this effort in addition to the multi-dimensional delivery means ### CSS principles +- **Separation of structural and aesthetic styles** - Structural styles (e.g. `display`, `position`, etc) are critical to the structure and behavior of a component, while aesthetic styles (e.g. `background-color`, `font-family`, `border-radius`, `box-shadow`) are cosmetic in nature. Structural styles are included alongside component HTML and JS, while aesethic styles are handled through the design token system. - **Modular** - Modular CSS architecture is a best practice, is great for DX, is more matinainable, and helps avoid style collisions tightly scoped and to avoid unintended style bleeding. - **Clarity over brevity** - CSS class naming conventions prioritize clarity, legibility, and resilience over succinctness and saving bytes -- **Limit specificity** - Overly-specific styles should be avoided for manageability, maintainability, and DX. - - - - - - - +- **Limit specificity** - Overly-specific styles should be avoided for manageability, maintainability, and DX. ------ - ## HTML Naming Conventions -- Using appropriate HTML tags is a given. +- Use appropriate HTML tags and attributes +- HTML commenting - TODO: populate HTML-specific naming conventions ## CSS Naming Conventions -### 1. Determine CSS selectors - -Options: classes, data attributes, IDs (#yolo), other -Propose: CSS classes -Rationale: Standard convention - -### 2. Determine CSS style/methodology - -Options: BEM, BEMIT, OOCSS, SMACSS, ITCSS, SUIT CSS, CUBE CSS, RSCSS, Utility-first (Tailwind, Atomic), Parent class + raw elements inside. -Propose: Some BEM-style syntax -Rationale: Clarity over brevity. Hierarchical. At-a-glance. -Example: - -``` -.alert - -.alert--success - -.alert--error - -.alert__icon - -.alert__body - -``` - - -### 3. Determine a global namespace - -Options: `oui-` `www-` `web-` `w3c-` - -Propose: -Rationale: - -(note: It would be amazing to have something that hints at its global nature! `www`, `web` or `w3c` would be badass, but I also acknowledge those might be a more challenging sell) - -###4. Determine component naming standard - -Options: `oui-alert`, `oui-button-group`, `oui-c-alert`, -Propose: `oui-[component-name]` -Rationale: Feels generally clean - -### 5. Determine variant names - -#### 5a. Determine component state-based names -Code will use native pseudoselectors (e.g. `:hover`, `:focus-visible`, etc). However, there are other states to account for, in addition to artificially triggering a specific state of a component - -Options: -- Modifier class: `button--hover`, `focus`, `active`, `disabled` -- Modifier class with `is-`: `is-hovered`, `is-active`, `is-disabled` -- Use attributes: `[disabled]`, `[aria-expanded="true"]` - -Propose: -Rationale: - -#### 5b. Determine status variant names - -Options: -- BAD: `error`, `danger`, `critical`, `destructive`, `blocked`, `negative` -- GOOD: `success`, `valid`, `positive`, `complete` -- CAUTION: `caution`, `warning`, ` -- INFO: `info`, `neutral`, `default` - -Propose: `error`, `success`, `warning`, `info` -Rationale: Common convention across many design systems - - -5c: Sizing names - -Options: -- `small`, `medium`, `large`, `extra-large` -- `sm`, `md`, `lg`, `xl` -- more - -Propose: -Rationale: - -5d: Spacing names - -Options: -- `small`, `medium`, `large`, `extra-large` -- `sm`, `md`, `lg`, `xl` -- `4`, `8`, `12`, `16`, etc - -Propose: -Rationale: - -### 6. Component states -Options: -- Pseudo-class names: hover, focus, active, disabled -- Boolean prefix: is-hovered, is-active -- ARIA/data attributes: [data-state="open"], [aria-invalid="true"] - - -### 6: Media query names/units - -Note: this is weird as media queries don't support CSS custom properties. But it's probably good to have them as quasi-variables or potentially think about how to use Sass with them. - -Options: -- raw values `30rem`, `56rem` -- `desktop`, `tablet`, `mobile` -- `small`, `medium`, `large`, `extra-large` -- `sm`, `md`, `lg`, `xl` -- `bp-1`, `bp-2`, `bp-3` - -Propose: -Rationale: - - - -### 7. Determine CSS declaration structure - -Options: - -Structural - -``` -.oui-alert { - /* Structural (hard-coded) styles */ - [positioning] - [box model] - [other] - - /* Themeable styles */ - [color] - [typography] - [border] - [shadow] - [animation] - [other] -} -``` - -Alphabetical - -``` -.oui-alert { - align-content: - ... - z-index -} -``` - -Proposal: -Rationale: +It's important to establish well-considered CSS conventions that the global design system will follow. Of course, there are _many_ ways to author CSS, and there are many facets to authoring CSS. The goal is to consider all sensible options, vote on the implementation, and get to work implementing them. Here are the syntax-specific topics to decide on: +### [1. Determine CSS selectors](https://github.com/openui/design-system/discussions/27) +### [2. Determine CSS style/methodology](https://github.com/openui/design-system/discussions/28) +### 3. [Determine a global namespace](https://github.com/openui/design-system/discussions/29) +### [4. Determine component naming standard](https://github.com/openui/design-system/discussions/31) +### [5. Determine variant names](https://github.com/openui/design-system/discussions/33) +#### [5a. Determine component state-based names](https://github.com/openui/design-system/discussions/32) +#### [5b. Determine status variant names](https://github.com/openui/design-system/discussions/33) +#### [5c: Sizing names](https://github.com/openui/design-system/discussions/34) +#### [5d: Spacing names](https://github.com/openui/design-system/discussions/35) +### [6: Media query names/units](https://github.com/openui/design-system/discussions/37) -## Credits +### [7. Determine CSS declaration structure](https://github.com/openui/design-system/discussions/36) -- https://vanilla-full.netlify.app/?path=/docs/documentation-guidelines--docs +### [8. Determine commenting conventions](https://github.com/openui/design-system/discussions/38)