docs: theming

docs: moved technical content to wiki controller page Co-Authored-By: Steven Spriggs <[email protected]> docs: fix import map location of color.js docs(context): improve demo docs: snippet grid docs: card grid spacing docs: card grid border docs: spacing docs: spacing docs: context examples docs: grid codeblocks docs: preliminary theming info chore: restore main's import map docs: theming page stubs
RedHat-UX · Nov 9, 2023 · fd50630 · fd50630
1 parent 71535ca
commit fd50630
Show file tree

Hide file tree

Showing 6 changed files with 313 additions and 0 deletions.
diff --git a/docs/_includes/component/header.njk b/docs/_includes/component/header.njk
@@ -92,6 +92,21 @@
           </details>
         </li>
 
+        <!-- Theming -->
+
+        <li class="item">
+          <details {{ 'open' if 'theming/' in page.url }}>
+            <summary class="heading">Theming</summary>
+            <ul class="sub-menu">
+              {%- for link in collections.theming -%}
+              <li class="item">
+                <a class="link {{ 'active' if page.url === link.url }}"
+                   href="{{ link.url | url }}">{{ link.data.title }}</a>
+              </li>
+              {%- endfor -%}
+            </ul>
+          </details>
+        </li>
         <!-- Tokens -->
 
         <li class="item">

diff --git a/docs/foundations/color.njk → docs/foundations/color/index.njk b/docs/foundations/color.njk → docs/foundations/color/index.njk
diff --git a/docs/theming/customizing.md b/docs/theming/customizing.md
@@ -0,0 +1,27 @@
+---
+title: Customizing
+order: 3
+---
+
+- "Applying a theme" means setting token values
+- prefer to customize 'semantic' (i.e. alias) tokens rather than 'base' (i.e. 
+crayon) tokens
+- set token values on `:root` for whole pages, or on a selector for a class 
+(e.g. 3-card promo band)
+- brag about your customizations! did other teams use it, or something similar? 
+  maybe it should be added upstream to the design system?
+
+```css
+.theme-pink {
+  --rh-color-surface-lightest: #feeded;
+  --rh-color-surface-darkest: var(--rh-color-brand-red-darkest, #5f0000);
+  --rh-color-text-primary-on-light: #131313;
+}
+
+.product-grid {
+  & rh-card {
+    --rh-border-radius-default: 10px;
+  }
+}
+```
+
diff --git a/docs/theming/index.md b/docs/theming/index.md
@@ -0,0 +1,58 @@
+---
+title: Overview
+order: 1
+---
+<style>
+  .card-grid {
+    display: grid;
+    gap: var(--rh-space-lg);
+    grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+    & rh-card {
+      &::part(header) {
+        padding: 0;
+        margin: 0;
+      }
+  }
+</style>
+
+<script type="module">
+  import '@rhds/elements/rh-card/rh-card.js'
+</script>
+
+Red Hat's Design System comes with a powerful, flexible, and easy-to-use
+theming system. Design system elements come with branded, accessible defaults 
+built-in, so that all you need to do to create quintessentially Red Hat 
+experiences is write some HTML. For those occasions when we want to flex our 
+design muscles, our elements come with powerful theming primitives in the form 
+of **slots**, **design tokens**, and **CSS shadow parts** to enable you to theme 
+a single element, a section, a page, or an entire app.
+
+<nav class="card-grid">
+  <rh-card>
+    <svg slot="header" viewBox="0 0 161 100">
+      <rect x="0" y="0" width="161" height="100" fill="var(--rh-color-brand-red-on-light)" />
+      <text fill="white" font="bold" x="10" y="60">Insert graphic</text>
+    </svg>
+    <rh-cta slot="footer">
+      <a href="palettes-and-themes/">Palettes and Themes</a>
+    </rh-cta>
+  </rh-card>
+  <rh-card>
+    <svg slot="header" viewBox="0 0 161 100">
+      <rect x="0" y="0" width="161" height="100" fill="var(--rh-color-brand-red-on-light)" />
+      <text fill="white" font="bold" x="10" y="60">Insert graphic</text>
+    </svg>
+    <rh-cta slot="footer">
+      <a href="customizing/">Customizing</a>
+    </rh-cta>
+  </rh-card>
+  <rh-card>
+    <svg slot="header" viewBox="0 0 161 100">
+      <rect x="0" y="0" width="161" height="100" fill="var(--rh-color-brand-red-on-light)" />
+      <text fill="white" font="bold" x="10" y="60">Insert graphic</text>
+    </svg>
+    <rh-cta slot="footer">
+      <a href="developers/">Developer Info</a>
+    </rh-cta>
+  </rh-card>
+</nav>
diff --git a/docs/theming/palettes-and-themes.md b/docs/theming/palettes-and-themes.md
@@ -0,0 +1,210 @@
+---
+title: Palettes and Themes
+order: 2
+---
+<script type="module">
+  import '@rhds/elements/rh-blockquote/rh-blockquote.js';
+  import '@rhds/elements/rh-cta/rh-cta.js';
+  import '@rhds/elements/rh-card/rh-card.js';
+  import '@rhds/elements/rh-tag/rh-tag.js';
+  import '@rhds/elements/lib/elements/rh-context-demo/rh-context-demo.js';
+</script>
+
+<style>
+  .card-snippet-grid {
+    display: grid;
+    grid-template: 1fr 1fr / 1fr 1fr;
+    gap: var(--rh-space-4xl)  var(--rh-space-lg);
+    padding: var(--rh-space-4xl);
+    border-radius: var(--rh-border-radius-default);
+    border: solid var(--rh-border-width-sm) var(--rh-color-border-subtle-on-light);
+    & pre[class^="language-"] {
+      margin: 0;
+    }
+  }
+</style>
+
+Red Hat Design System comes with a contextual color-theming feature called 
+"Color Context", designed to make page developers' and content authors' jobs
+easier and to improve customers' digital experiences. Authors and developers who
+adopt the color context system will produce accessible, branded experiences with 
+less effort and greater cross-property consistency.
+
+<rh-blockquote>
+  HTML design systems help teams ship better digital experiences, faster.
+</rh-blockquote>
+
+## How Color Context works
+<abbr title="red hat design system">RHDS</abbr>' color context system is an 
+*HTML* and *CSS* system with some supporting JavaScript[1].
+The color context system has two main parts: **providers** and **consumers**. 
+Providers actively define a color theme, while consumers passively accept their 
+theme from the nearest provider ancestor.
+
+### Color context providers
+Context **providers** define a **color palette** for themselves and their child 
+elements. There are currently six main color palettes:
+1. lightest
+1. lighter
+1. light
+1. dark
+1. darker
+1. darkest
+
+Context providers typically use the `lightest` color palette as the default. 
+Authors may define the color palette of a container using the `color-palette` HTML
+attribute. So for example, to create a card with the darkest color palette, use 
+this HTML:
+
+<div class="card-snippet-grid">
+
+```html
+<rh-card>
+  <p>
+    This card uses the default
+    color palette.
+  </p>
+</rh-card>
+```
+
+<rh-card>
+  <p>
+    This card uses the default
+    color palette.
+  </p>
+</rh-card>
+
+```html
+<rh-card color-palette="darkest">
+  <p>
+    This card uses the author-set
+    "darkest" color palette.
+  </p>
+</rh-card>
+```
+
+<rh-card color-palette="darkest">
+  <p>
+    This card uses the author-set
+    "darkest" color palette.
+  </p>
+</rh-card>
+
+</div>
+
+
+### Color context consumers
+Context **consumers**, which adopt a **color theme**. There are two main 
+color themes, corresponding to the above palettes:
+1. light
+1. dark
+
+Child elements which are providers will automatically adapt, applying their own 
+**color theme** as needed. Page authors *do not need to and should not customize*
+colors of consumer elements.
+
+Color context containers can be nested, such that child elements will always 
+adopt the color theme corresponding to the nearest container's palette.
+
+Extending our card example from above, if our page author then adds an `<rh-cta>` to the card, it will *automatically* adopt the dark color theme. The page author need not and should not customize the CTA.
+
+<div class="card-snippet-grid">
+
+```html
+<rh-card>
+  <p>
+    The card <em>and</em> 
+    CTA use the default colors.
+  </p>
+  <rh-cta slot="footer">Fine!</rh-cta>
+</rh-card>
+```
+
+<rh-card>
+  <p>
+    The card <em>and</em> 
+    CTA use the default colors.
+  </p>
+  <rh-cta slot="footer">Fine!</rh-cta>
+</rh-card>
+
+```html
+<rh-card color-palette="darkest">
+  <p>
+    The card uses the "darkest" palette.
+    The CTA is automatically themed
+    with the "dark" theme.
+  </p>
+  <rh-cta slot="footer">Nice!</rh-cta>
+</rh-card>
+```
+
+<rh-card color-palette="darkest">
+  <p>
+    The card uses the "darkest" palette.
+    The CTA is automatically themed
+    with the "dark" theme.
+  </p>
+  <rh-cta slot="footer">Nice!</rh-cta>
+</rh-card>
+
+</div>
+
+<rh-blockquote>
+  Color context lets authors write more HTML, and less CSS and JavaScript
+</rh-blockquote>
+
+### Combination elements
+Some elements are both providers and consumers. Card, for example is both a 
+provider and a consumer. It can accept the color theme of its context and it 
+can also set its own color palette.
+
+<rh-context-demo id="cards-demo">
+  <rh-card>
+    <h2 slot="header">Consumer</h2>
+    <rh-tag slot="header"
+            icon="info"
+            color="purple">passive</rh-tag>
+    <p>
+      This card acts as a consumer.
+      It will always receive its parent's <code>ColorTheme</code>.
+    </p>
+    <rh-cta slot="footer">
+      <a href="/elements/card/">Read card docs</a>
+    </rh-cta>
+  </rh-card>
+  <rh-card id="provider-card"
+           color-palette="lightest">
+    <h2 slot="header">Provider</h2>
+    <rh-tag slot="header"
+            icon="info"
+            color="green">active</rh-tag>
+    <p>
+      This card acts as a provider.
+      Try changing this card's 
+      <code>color-palette</code>
+      and see how it affects this card's children.
+    </p>
+    <label>
+      Set this card's color palette.
+      <rh-context-picker target="provider-card" value="lightest"></rh-context-picker>
+    </label>
+    <rh-cta slot="footer">
+      <a href="/elements/call-to-action/">Read CTA docs</a>
+    </rh-cta>
+  </rh-card>
+</rh-context-demo>
+
+<style>
+  #cards-demo::part(demo) {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: var(--rh-space-lg);
+  }
+  #cards-demo rh-card::part(header) {
+    flex-direction: row;
+  }
+  #cards-demo h2 {
+    margin-inline-end: auto;
+  }
+</style>
diff --git a/docs/theming/theming.11tydata.yaml b/docs/theming/theming.11tydata.yaml
@@ -0,0 +1,3 @@
+layout: layout-basic.njk
+tags:
+  - theming