From 03756b6adc076ecca4577ebf1a5dbf8e5fb06bb8 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Wed, 5 Jun 2024 21:45:50 -0400 Subject: [PATCH] docs/issue 7 document latest contributing guidelines for styling strategy (#50) --- CONTRIBUTING.md | 114 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 103 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 210e8d55..98cbcda0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ The layout of the project is as follows: - _/styles/_ - Global theme and styles > [!NOTE] -> _Please review the documentation contained in this project's Storybook by running `npm run story:dev` and going through the content in the **Overview** section_ +> Please review the documentation contained in this project's Storybook by running `npm run story:dev` and going through the content in the **Overview** section. ## Documentation Changes @@ -41,39 +41,131 @@ General changes to the website can be made by submitting a PR directly to the ma All global theming and general styles should go in _src/styles/theme.css_, like font family and CSS custom properties to be used throughout the site. -[Open Props](https://open-props.style/) are used in this project to provide a set of consistent and re-usable design system tokens. Please review these first before creating any new custom values or variables. +For anything that may not be easily "componentized" or is very general like for markdown based content, it should go in _src/styles/main.css_. + +> [!NOTE] +> [Open Props](https://open-props.style/) are used in this project to provide a set of consistent and re-usable design system tokens. Please review these first before creating any new custom values or variables. ### Components -As this project is a static site, all Web Components will generally be authored as content rendering into the light dom, which will then be pre-rendered at build time to static HTML. +This project leverage Web Components (custom elements) as the mechanism for all templating and / or interactivity, with pre-rendering of the content occurring during the build (SSG). + +```js +export default class Greeting extends HTMLElement { + connectedCallback() { + // ... + } +} + +// we use app- as the tag name prefix +customElements.define("app-greeting", Greeting); +``` + +#### Static Components (Light DOM) + +Since most of the content for this project is static content, Light DOM based HTML is preferred, rendering directly into `innerHTML`. For styling these components, a [Greenwood based implementation of CSS Modules](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-css-modules) is used, that will link the class names at build time yet still emit static CSS in the `` of the page. + +```css +/* greeting.module.css */ +.wrapper { + color: var(--color-primary); + box-shadow: var(--shadow-3); +} +``` ```js -export default class MyComponent extends HTMLElement { +import styles from "./greeting.module.css"; + +export default class Greeting extends HTMLElement { connectedCallback() { this.innerHTML = ` -

Hello from my component!

+

Hello from the greeting component!

`; } } + +customElements.define("app-greeting", Greeting); ``` +This would emit the following generated HTML + ```html - -