From dfabf0ba081de0fb456a62b022c6875d1d0044c0 Mon Sep 17 00:00:00 2001 From: Marionne Patel <95588923+marionnegp@users.noreply.github.com> Date: Thu, 18 Apr 2024 11:29:28 -0400 Subject: [PATCH] docs: add Get started: Developers (#1439) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add content and update template * feat: add script tags to some code blocks * feat: fix page order and headings * fix: add script tags * feat: updated installation content and code on Tokens subpage * feat: change layout-with-subnav template and frontmatter * fix: Change the link in the side nav from "Overview" to "Developers" * feat: link to Developers page from Get Started: Overview * feat: add usage content and update installation info * fix: add script tags to code blocks * docs: update docs/get-started/developers/tokens.md * docs: update docs/get-started/developers/usage.md * docs: react usage --------- Co-authored-by: Benny Powers - עם ישראל חי! Co-authored-by: Benny Powers --- docs/_includes/component/header.njk | 4 +- ...foundations.njk => layout-with-subnav.njk} | 14 +- docs/_plugins/rhds.cjs | 7 + docs/foundations/color/accessibility.md | 3 +- docs/foundations/color/index.md | 3 +- docs/foundations/color/usage.md | 3 +- docs/get-started.md | 16 +- docs/get-started/designers.md | 1 + docs/get-started/developers/index.md | 52 ++++++ docs/get-started/developers/installation.md | 107 ++++++++++++ docs/get-started/developers/tokens.md | 165 ++++++++++++++++++ docs/get-started/developers/usage.md | 114 ++++++++++++ 12 files changed, 472 insertions(+), 17 deletions(-) rename docs/_includes/{layout-foundations.njk => layout-with-subnav.njk} (64%) create mode 100644 docs/get-started/developers/index.md create mode 100644 docs/get-started/developers/installation.md create mode 100644 docs/get-started/developers/tokens.md create mode 100644 docs/get-started/developers/usage.md diff --git a/docs/_includes/component/header.njk b/docs/_includes/component/header.njk index 058ab9a7d4..e2ebda2107 100755 --- a/docs/_includes/component/header.njk +++ b/docs/_includes/component/header.njk @@ -48,7 +48,7 @@ - +
  • @@ -61,7 +61,7 @@ {%- for link in collections.getstarted -%}
  • {{ link.data.title }} + href="{{ link.url | url }}">{{ link.data.heading }}
    • {%- endfor -%} diff --git a/docs/_includes/layout-foundations.njk b/docs/_includes/layout-with-subnav.njk similarity index 64% rename from docs/_includes/layout-foundations.njk rename to docs/_includes/layout-with-subnav.njk index 553658ae12..81f792b66d 100644 --- a/docs/_includes/layout-foundations.njk +++ b/docs/_includes/layout-with-subnav.njk @@ -7,6 +7,7 @@ importElements: - rh-subnav - rh-tag - rh-badge + - rh-code-block --- {% include 'component/header.njk' %} @@ -14,13 +15,16 @@ importElements:
    -
    +

    {{ heading or title }}

    - {% for tab in collections.sortedColor %} - - {{ tab.data.title }} - {% endfor %} + {% if subNavCollection %} + + {% for tab in collections[subNavCollection] %} + + {{ tab.data.title }} + {% endfor %} + {% endif %}
    diff --git a/docs/_plugins/rhds.cjs b/docs/_plugins/rhds.cjs index f72c9154ca..07b24864cd 100644 --- a/docs/_plugins/rhds.cjs +++ b/docs/_plugins/rhds.cjs @@ -230,6 +230,13 @@ module.exports = function(eleventyConfig, { tagsToAlphabetize }) { }); }); + eleventyConfig.addCollection('sortedDevelopers', async function(collectionApi) { + const developersCollection = collectionApi.getFilteredByTags('developers'); + return developersCollection.sort((a, b) => { + if (a.data.order > b.data.order) { return 1; } else if (a.data.order < b.data.order) { return -1; } else { return 0; } + }); + }); + eleventyConfig.addCollection('elementDocs', async function(collectionApi) { const { pfeconfig } = eleventyConfig?.globalData ?? {}; /** diff --git a/docs/foundations/color/accessibility.md b/docs/foundations/color/accessibility.md index ad1dd89f86..0254f64758 100644 --- a/docs/foundations/color/accessibility.md +++ b/docs/foundations/color/accessibility.md @@ -1,10 +1,11 @@ --- -layout: layout-foundations.njk +layout: layout-with-subnav.njk title: Accessibility heading: Color tags: - color permalink: /foundations/color/accessibility/index.html +subNavCollection: sortedColor order: 20 bodyClasses: element-docs --- diff --git a/docs/foundations/color/index.md b/docs/foundations/color/index.md index be16e80aab..786ce2515c 100644 --- a/docs/foundations/color/index.md +++ b/docs/foundations/color/index.md @@ -1,11 +1,12 @@ --- -layout: layout-foundations.njk +layout: layout-with-subnav.njk title: Overview heading: Color tags: - foundations - color permalink: /foundations/color/index.html +subNavCollection: sortedColor order: 00 bodyClasses: element-docs --- diff --git a/docs/foundations/color/usage.md b/docs/foundations/color/usage.md index 7735d2b969..4a3dd66f29 100644 --- a/docs/foundations/color/usage.md +++ b/docs/foundations/color/usage.md @@ -1,10 +1,11 @@ --- -layout: layout-foundations.njk +layout: layout-with-subnav.njk title: Usage heading: Color tags: - color permalink: /foundations/color/usage/index.html +subNavCollection: sortedColor order: 10 bodyClasses: element-docs --- diff --git a/docs/get-started.md b/docs/get-started.md index 36ebc2c841..9eb0f0f817 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -37,13 +37,15 @@ The Red Hat Design System for digital experiences gives designers and developers
    Designers
    -
    - {% example - palette="descriptive", - alt="Card overlapping code editor user interface", - src="/assets/get-started/developers.png" %} -
    Developers (Coming soon)
    -
    + +
    + {% example + palette="descriptive", + alt="Card overlapping code editor user interface", + src="/assets/get-started/developers.png" %} +
    Developers
    +
    +     {% feedback %} diff --git a/docs/get-started/designers.md b/docs/get-started/designers.md index 3d3bad2cf8..5fa0e3fc87 100644 --- a/docs/get-started/designers.md +++ b/docs/get-started/designers.md @@ -1,6 +1,7 @@ --- layout: layout-basic.njk title: Designers +heading: Designers order: 2 tags: - getstarted diff --git a/docs/get-started/developers/index.md b/docs/get-started/developers/index.md new file mode 100644 index 0000000000..462f43a14b --- /dev/null +++ b/docs/get-started/developers/index.md @@ -0,0 +1,52 @@ +--- +layout: layout-with-subnav.njk +title: Overview +heading: Developers +tags: + - getstarted + - developers +permalink: /get-started/developers/index.html +subNavCollection: sortedDevelopers +order: 00 +bodyClasses: element-docs +--- + +## Introduction + +Welcome to the **Red Hat Design System** (RHDS) for digital experiences. If you need to develop something using our design system, you have come to the right place. + +Read this section to get started and e-mail [design-system@redhat.com](mailto:design-system@redhat.com) or connect with us on Slack if you have any questions along the way. + +## Learn about our design system + +Our design system libraries and the documentation website offer assets and guidance needed to create digital experiences. Please use these resources to have a better understanding of how to use our design system. + +
    +
    +

    Foundations

    +

    Foundations are how we express our brand through color, space, typography, etc.

    +
    +
    +

    Design tokens

    +

    Design tokens are how we translate our design language decisions into code.

    +
    +
    +

    Documentation

    +

    This website offers guidance about how to use our elements and patterns correctly.

    +
    +
    +

    GitHub repositories

    +

    Explore our code, roadmaps, and discussions in the Red Hat Design System repo and the Red Hat Design Tokens repo.

    +
    +
    + +## About web components + +Web components are based on a set of web platform APIs that help to create reusable and encapsulated UI elements. Those standards consist of custom elements, shadow DOM, and HTML Templates. + +Because they're able to work with any framework that supports HTML, web components can be used without having to rework all of your code and are less likely to be affected by changes in preferred web stacks. Encapsulation within the shadow DOM prevents a page's code from breaking a component's style and allows for a scalable design system. + +{% feedback %} +

    Designers

    +

    To get started using our design system as a designer, go to the Designers page.

    +{% endfeedback %} \ No newline at end of file diff --git a/docs/get-started/developers/installation.md b/docs/get-started/developers/installation.md new file mode 100644 index 0000000000..e4d6db4240 --- /dev/null +++ b/docs/get-started/developers/installation.md @@ -0,0 +1,107 @@ +--- +layout: layout-with-subnav.njk +title: Installation +heading: Developers +tags: + - developers +permalink: /get-started/developers/installation/index.html +subNavCollection: sortedDevelopers +order: 10 +bodyClasses: element-docs +--- + +## How to install + +There are three ways you can install the Red Hat Design System's web components: CDN, NPM, or JSPM. Each element's "Code" page includes the same installation information with code snippets that are specific to that element. + +### Red Hat CDN + +{% alert title="CDN Prerelease", + state="warning" %} +

    We are currently working on our CDN, which will be soon moving into beta. This will be the preferred method of installation in the near future. If you are a Red Hat associate and have questions or comments about the CDN or installation process please connect with us on Slack.

    +{% endalert %} + +The recommended way to load RHDS is via the Red Hat Digital Experience CDN, and using an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap). + +If you have full control over the page you are using, add an import map to the ``, pointing to the CDN, or update any existing import map. If you are not responsible for the page's ``, request that the page owner makes the change on your behalf. + + + + + +Once the import map is established, you can load the element with the following module, containing a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). The example below shows how you'd load in <`rh-button>`. + + + + + +Note that modules may be placed in the ``. Since they are deferred by default, they will not block rendering. + +### NPM + +Install RHDS using your team's preferred NPM package manager. + + + + + +Once that's been accomplished, you will need to use a bundler to resolve the bare module specifiers and optionally optimize the package for your site's particular use case and needs. Comprehensive guides to bundling are beyond the scope of this page; read more about bundlers on their websites: + +- [Rollup](https://rollupjs.org/) +- [esbuild](https://esbuild.github.io/) +- [Parcel](https://parceljs.org/) +- [Webpack](https://webpack.js.org/) + +### JSPM + +{% alert title="Public CDNs", + state="warning" %} +

    JSPM and other public CDNs should not be used on corporate domains. Use them for development purposes only!

    +{% endalert %} + +Add an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to the ``, pointing to the CDN, or update any existing import map. + + + + + +Once the import map is established, you can load the element with the following module, containing a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). The example below shows how you'd load in <`rh-button>`. + + + + + +Note that Modules may be placed in the ``. Since they are deferred by default, they will not block rendering. + +{% feedback %} +

    Designers

    +

    To get started using our design system as a designer, go to the Designers page.

    +{% endfeedback %} \ No newline at end of file diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md new file mode 100644 index 0000000000..9b0a9970c2 --- /dev/null +++ b/docs/get-started/developers/tokens.md @@ -0,0 +1,165 @@ +--- +layout: layout-with-subnav.njk +title: Tokens +heading: Developers +tags: + - developers +permalink: /get-started/developers/tokens/index.html +subNavCollection: sortedDevelopers +order: 30 +bodyClasses: element-docs +--- + +## How to install tokens + +Run the following git command to install RHDS tokens: + + + + + +## Usage + +We use [style-dictionary](https://amzn.github.io/style-dictionary/) to transform our tokens into multiple formats and helpers. + +### Import global CSS + +Apply defaults to the document root by importing the global stylesheet: + + + + + +### Reset the shadowroot + +Reset a component's styles (preventing inheritance) by adding resetStyles to its static Constructible Style Sheet list: + + + + + + + +### Import tokens as JavaScript objects + +{% alert title="Note", state="info" %} +We strongly recommend using CSS variables (and accompanying snippets), instead of importing tokens as JavaScript objects. +{% endalert %} + +Import tokens as JavaScript objects: + + + + + + + +or for tree-shakable imports: + + + + + + + +## Plugins + +### Using editor snippets + +Editor snippets complete prefixes like `--rh-color-brand` to their CSS custom properties, complete with fallback. + + + + + +They also provide reverse lookup. For example, if you want to choose between all the tokens with the value `#e00`, you can do so by completing the prefix `e00`. + +#### Load snippets in VSCode + +Download the VSIX bundle that’s linked at the bottom of our [“Release v1.0.0”](https://github.com/RedHat-UX/red-hat-design-tokens/releases/tag/v1.0.0) page. + +#### Load snippets in Neovim + +Use LuaSnip to load snippets in Neovim: + + + + + +### Stylelint plugin + +Install the stylelint plugin to automatically correct token values in your files. + +See the [Stylelint Plugin README](https://github.com/RedHat-UX/red-hat-design-tokens/blob/main/plugins/stylelint/README.md) for more info. + +### 11ty plugin + +The experimental 11ty plugin lets you display token values in an 11ty site. + +### vim-hexokinase + +Vim users can load the [vim-hexokinase](https://github.com/RRethy/vim-hexokinase) plugin to display color swatches next to their encoded values in their editor. + +Use the following config (lua syntax, for Neovim users) to configure hexokinase to display color values next to color aliases like `{color.brand.red}`. + + + + + + + + + +{% feedback %} +

    Designers

    +

    To get started using our design system as a designer, go to the Designers page.

    +{% endfeedback %} \ No newline at end of file diff --git a/docs/get-started/developers/usage.md b/docs/get-started/developers/usage.md new file mode 100644 index 0000000000..b571d486fc --- /dev/null +++ b/docs/get-started/developers/usage.md @@ -0,0 +1,114 @@ +--- +layout: layout-with-subnav.njk +title: Usage +heading: Developers +tags: + - developers +permalink: /get-started/developers/usage/index.html +subNavCollection: sortedDevelopers +order: 20 +bodyClasses: element-docs +--- + +## Usage + +Now that you've installed the Red Hat Design System, here's more information about how to use the web components. + +### Using react wrappers + +React wrappers make it possible to use web components within React JSX files. Follow the steps below to learn how. + +#### 1. Initial setup + +We'll bootstrap our React app using Vite. It's possible to use other tools for this, but that is out of the scope of this tutorial. + + + + + +This command will ask you to provide the project name, framework, and variant. + +#### 2. Install the `@lit/react` library + +Use the following command: + + + + + +#### 3. Import elements and patterns + +After installing the `@lit/react` library, you can import elements and patterns +to your file. Below is an example of importing `` and ``, and +managing app state between them using react. + + + + + +### Using RHDS elements with Vue + +To get web components to work with Vue, it’s pretty easy and straightforward. Follow the steps below to use web components in a Vue app. + +#### 1. Initial setup + +Add these two lines at the top of the `main.js` file in the `/src/` directory. + + + + + +#### 2. Import elements and patterns + +Add the import statements to the top of the ` + + +## Other resources + +- [Red Hat Design System Wiki](https://github.com/RedHat-UX/red-hat-design-system/wiki) +- [Red Hat Brand Standard](https://www.redhat.com/en/about/brand/standards) + +{% feedback %} +

    Designers

    +

    To get started using our design system as a designer, go to the Designers page.

    +{% endfeedback %}