docs: update content

Author: mrholek

packages/docs/.vuepress/config.ts

@@ -70,6 +70,29 @@ export default defineUserConfig<DefaultThemeOptions>({
             text: 'Introduction',
             link: `/getting-started/introduction.html`,
           },
+          {
+            text: 'Accessibility',
+            link: `/getting-started/accessibility.html`,
+          },
+        ],
+      },
+      {
+        text: 'Customize',
+        icon: '<path fill="var(--ci-primary-color, currentColor)" d="M425.514,82.055C380.778,39.458,320.673,16,256.271,16,196.248,16,136.415,36.073,92.115,71.071,43.032,109.85,16,164.161,16,224c0,60.1,15.531,98.87,48.876,122.019,28,19.438,68.412,27.731,135.124,27.731h29.75A26.28,26.28,0,0,1,256,400v47.984a32,32,0,0,0,32,32h.032l90.755-.088a32.094,32.094,0,0,0,19.686-6.8c9.725-7.622,34.727-29.4,56.8-66.9C482.3,360.262,496,307.037,496,248,496,184.268,470.968,125.334,425.514,82.055Zm2.173,307.915c-19.3,32.792-40.663,51.447-48.932,57.926L288,447.984V400a58.316,58.316,0,0,0-58.25-58.25H200c-59.69,0-94.644-6.585-116.876-22.019C58.833,302.869,48,273.344,48,224,48,113.833,153.9,48,256.271,48,372.755,48,464,135.851,464,248,464,301.253,451.782,349.019,427.687,389.97Z" class="ci-primary"/><path fill="var(--ci-primary-color, currentColor)" d="M128,144a56,56,0,1,0,56,56A56.064,56.064,0,0,0,128,144Zm0,80a24,24,0,1,1,24-24A24.027,24.027,0,0,1,128,224Z" class="ci-primary"/><path fill="var(--ci-primary-color, currentColor)" d="M240,72a56,56,0,1,0,56,56A56.064,56.064,0,0,0,240,72Zm0,80a24,24,0,1,1,24-24A24.027,24.027,0,0,1,240,152Z" class="ci-primary"/><path fill="var(--ci-primary-color, currentColor)" d="M360,128a56,56,0,1,0,56,56A56.064,56.064,0,0,0,360,128Zm0,80a24,24,0,1,1,24-24A24.027,24.027,0,0,1,360,208Z" class="ci-primary"/><path fill="var(--ci-primary-color, currentColor)" d="M376,264a56,56,0,1,0,56,56A56.064,56.064,0,0,0,376,264Zm0,80a24,24,0,1,1,24-24A24.027,24.027,0,0,1,376,344Z" class="ci-primary"/>',
+        link: '/customize/',
+        children: [
+          {
+            text: 'Sass',
+            link: '/customize/sass.html',
+          },
+          {
+            text: 'Options',
+            link: '/customize/options.html',
+          },
+          {
+            text: 'CSS Variables',
+            link: '/customize/css-variables.html',
+          },
         ],
       },
       {

packages/docs/components/accordion.md

@@ -10,7 +10,7 @@ Click the accordions below to expand/collapse the accordion content.
 
 ::: demo
 <CAccordion>
-  <CAccordionItem :item-key="1">
+  <CAccordionItem :item-key="1" :style="{ '--cui-accordion-bg': 'red' }">
     <CAccordionHeader>
       Accordion Item #1
     </CAccordionHeader>
@@ -277,6 +277,83 @@ Add `always-open` property to make accordion items stay open when another item i
 </CAccordion>
 ```
 
+## Customizing
+
+### CSS variables
+
+Vue accordions use local CSS variables on `.accordion` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+```sass
+--cui-accordion-color: #{color-contrast($accordion-bg)};
+--cui-accordion-bg: #{$accordion-bg};
+--cui-accordion-transition: #{$accordion-transition};
+--cui-accordion-border-color: #{$accordion-border-color};
+--cui-accordion-border-width: #{$accordion-border-width};
+--cui-accordion-border-radius: #{$accordion-border-radius};
+--cui-accordion-inner-border-radius: #{$accordion-inner-border-radius};
+--cui-accordion-btn-padding-x: #{$accordion-button-padding-x};
+--cui-accordion-btn-padding-y: #{$accordion-button-padding-y};
+--cui-accordion-btn-color: #{$accordion-color};
+--cui-accordion-btn-bg: #{$accordion-button-bg};
+--cui-accordion-btn-icon: #{escape-svg($accordion-button-icon)};
+--cui-accordion-btn-icon-width: #{$accordion-icon-width};
+--cui-accordion-btn-icon-transform: #{$accordion-icon-transform};
+--cui-accordion-btn-icon-transition: #{$accordion-icon-transition};
+--cui-accordion-btn-active-icon: #{escape-svg($accordion-button-active-icon)};
+--cui-accordion-btn-focus-border-color: #{$accordion-button-focus-border-color};
+--cui-accordion-btn-focus-box-shadow: #{$accordion-button-focus-box-shadow};
+--cui-accordion-body-padding-x: #{$accordion-body-padding-x};
+--cui-accordion-body-padding-y: #{$accordion-body-padding-y};
+--cui-accordion-active-color: #{$accordion-button-active-color};
+--cui-accordion-active-bg: #{$accordion-button-active-bg};
+```
+
+#### How to use CSS variables
+
+```js
+const vars = { 
+  '--my-css-var': 10,
+  '--my-another-css-var': "red" 
+}
+return <CAccordion :style="vars">...</CAccordion>
+```
+
+### SASS variables
+
+```sass
+$accordion-padding-y:                     1rem;
+$accordion-padding-x:                     1.25rem;
+$accordion-color:                         var(--cui-body-color);
+$accordion-bg:                            $body-bg;
+$accordion-border-width:                  $border-width;
+$accordion-border-color:                  var(--cui-border-color);
+$accordion-border-radius:                 $border-radius;
+$accordion-inner-border-radius:           subtract($accordion-border-radius, $accordion-border-width);
+
+$accordion-body-padding-y:                $accordion-padding-y;
+$accordion-body-padding-x:                $accordion-padding-x;
+
+$accordion-button-padding-y:              $accordion-padding-y;
+$accordion-button-padding-x:              $accordion-padding-x;
+$accordion-button-color:                  $accordion-color;
+$accordion-button-bg:                     var(--cui-accordion-bg);
+$accordion-transition:                    $btn-transition, border-radius .15s ease;
+$accordion-button-active-bg:              tint-color($component-active-bg, 90%);
+$accordion-button-active-color:           shade-color($primary, 10%);
+
+$accordion-button-focus-border-color:     $input-focus-border-color;
+$accordion-button-focus-box-shadow:       $btn-focus-box-shadow;
+
+$accordion-icon-width:                    1.25rem;
+$accordion-icon-color:                    $accordion-button-color;
+$accordion-icon-active-color:             $accordion-button-active-color;
+$accordion-icon-transition:               transform .2s ease-in-out;
+$accordion-icon-transform:                rotate(-180deg);
+
+$accordion-button-icon:         url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$accordion-icon-color}'><path fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/></svg>");
+$accordion-button-active-icon:  url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$accordion-icon-active-color}'><path fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/></svg>");
+```
+
 ## API
 
 !!!include(./api/accordion/CAccordion.api.md)!!!

packages/docs/components/alert.md

@@ -266,6 +266,48 @@ Alerts can also be easily dismissed. Just add the `dismissible` prop.
     }
   }
 </script>
+
+## Customizing
+
+### CSS variables
+
+Vue alerts use local CSS variables on `.alert` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+```sass
+--cui-alert-bg: transparent;
+--cui-alert-padding-x: #{$alert-padding-x};
+--cui-alert-padding-y: #{$alert-padding-y};
+--cui-alert-margin-bottom: #{$alert-margin-bottom};
+--cui-alert-color: inherit;
+--cui-alert-border-color: transparent;
+--cui-alert-border: #{$alert-border-width} solid var(--cui-alert-border-color);
+--cui-alert-border-radius: #{$alert-border-radius};
+```
+
+#### How to use CSS variables
+
+```js
+const vars = { 
+  '--my-css-var': 10,
+  '--my-another-css-var': "red" 
+}
+return <CAlert :style="vars">...</CAlert>
+```
+
+### SASS variables
+
+```sass
+$alert-padding-y:               $spacer;
+$alert-padding-x:               $spacer;
+$alert-margin-bottom:           1rem;
+$alert-border-radius:           $border-radius;
+$alert-link-font-weight:        $font-weight-bold;
+$alert-border-width:            $border-width;
+$alert-bg-scale:                -80%;
+$alert-border-scale:            -70%;
+$alert-color-scale:             40%;
+$alert-dismissible-padding-r:   $alert-padding-x * 3; // 3x covers width of x plus default padding on either side
+```
 ## API
 
 !!!include(./api/alert/CAlert.api.md)!!!

packages/docs/components/badge.md

@@ -180,6 +180,46 @@ Apply the `shape="rounded-pill"` prop to make badges rounded.
 <CBadge color="dark" shape="rounded-pill">dark</CBadge>
 ```
 
+## Customizing
+
+### CSS variables
+
+Vue badges use local CSS variables on `.badges` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+```sass
+--cui-badge-padding-x: #{$badge-padding-x};
+--cui-badge-padding-y: #{$badge-padding-y};
+--cui-badge-font-size: #{$badge-font-size};
+--cui-badge-font-weight: #{$badge-font-weight};
+--cui-badge-color: #{$badge-color};
+--cui-badge-border-radius: #{$badge-border-radius};
+```
+
+#### How to use CSS variables
+
+```js
+const vars = { 
+  '--my-css-var': 10,
+  '--my-another-css-var': "red" 
+}
+return <CBadge :style="vars">...</CBadge>
+```
+
+### SASS variables
+
+```sass
+$badge-font-size:                   .75em;
+$badge-font-weight:                 $font-weight-bold;
+$badge-color:                       $high-emphasis-inverse;
+$badge-padding-y:                   .35em;
+$badge-padding-x:                   .65em;
+$badge-border-radius:               $border-radius;
+
+$badge-font-size-sm:                .65em;
+$badge-padding-y-sm:                .3em;
+$badge-padding-x-sm:                .5em;
+```
+
 ## API
 
 !!!include(./api/badge/CBadge.api.md)!!!

packages/docs/components/breadcrumb.md

@@ -105,6 +105,50 @@ Since breadcrumbs provide navigation, it's useful to add a significant label suc
 
 For more information, see the [WAI-ARIA Authoring Practices for the breadcrumb pattern](https://www.w3.org/TR/wai-aria-practices/#breadcrumb).
 
+## Customizing
+
+### CSS variables
+
+Vue breadcrumbs use local CSS variables on `.breadcrumb` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+```sass
+--cui-breadcrumb-padding-x: #{$breadcrumb-padding-x};
+--cui-breadcrumb-padding-y: #{$breadcrumb-padding-y};
+--cui-breadcrumb-margin-bottom: #{$breadcrumb-margin-bottom};
+--cui-breadcrumb-font-size: #{$breadcrumb-font-size};
+--cui-breadcrumb-bg: #{$breadcrumb-bg};
+--cui-breadcrumb-border-radius: #{$breadcrumb-border-radius};
+--cui-breadcrumb-divider-color: #{$breadcrumb-divider-color};
+--cui-breadcrumb-item-padding-x: #{$breadcrumb-item-padding-x};
+--cui-breadcrumb-item-active-color: #{$breadcrumb-active-color};
+```
+
+#### How to use CSS variables
+
+```js
+const vars = { 
+  '--my-css-var': 10,
+  '--my-another-css-var': "red" 
+}
+return <CBreadcrumb :style="vars">...</CBreadcrumb>
+```
+
+### SASS variables
+
+```sass
+$breadcrumb-font-size:              null;
+$breadcrumb-padding-y:              0;
+$breadcrumb-padding-x:              0;
+$breadcrumb-item-padding-x:         .5rem;
+$breadcrumb-margin-bottom:          1rem;
+$breadcrumb-bg:                     unset;
+$breadcrumb-divider-color:          $gray-600;
+$breadcrumb-active-color:           $gray-600;
+$breadcrumb-divider:                quote("/");
+$breadcrumb-divider-flipped:        $breadcrumb-divider;
+$breadcrumb-border-radius:          null;
+```
+
 ## API
 
 !!!include(./api/breadcrumb/CBreadcrumbItem.api.md)!!!

packages/docs/components/button.md

@@ -272,6 +272,111 @@ Additional utilities can be used to adjust the alignment of buttons when horizon
 </div>
 ```
 
+## Customizing
+
+### CSS variables
+
+Vue buttons use local CSS variables on `.btn` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+```sass
+--cui-btn-padding-x: #{$btn-padding-x};
+--cui-btn-padding-y: #{$btn-padding-y};
+--cui-btn-font-family: #{$btn-font-family};
+--cui-btn-font-size: #{$btn-font-size};
+--cui-btn-font-weight: #{$btn-font-weight};
+--cui-btn-line-height: #{$btn-line-height};
+--cui-btn-color: #{$body-color};
+--cui-btn-bg: transparent;
+--cui-btn-border-width: #{$btn-border-width};
+--cui-btn-border-color: transparent;
+--cui-btn-border-radius: #{$btn-border-radius};
+--cui-btn-box-shadow: #{$btn-box-shadow};
+--cui-btn-disabled-opacity: #{$btn-disabled-opacity};
+--cui-btn-focus-box-shadow: 0 0 0 #{$btn-focus-width} rgba(var(--cui-btn-focus-shadow-rgb), .5);
+```
+
+#### How to use CSS variables
+
+```js
+const vars = { 
+  '--my-css-var': 10,
+  '--my-another-css-var': "red" 
+}
+return <CButton :style="vars">...</CButton>
+```
+
+### SASS variables
+
+```sass
+$btn-padding-y:               $input-btn-padding-y;
+$btn-padding-x:               $input-btn-padding-x;
+$btn-font-family:             $input-btn-font-family;
+$btn-font-size:               $input-btn-font-size;
+$btn-line-height:             $input-btn-line-height;
+$btn-white-space:             null; // Set to `nowrap` to prevent text wrapping
+
+$btn-padding-y-sm:            $input-btn-padding-y-sm;
+$btn-padding-x-sm:            $input-btn-padding-x-sm;
+$btn-font-size-sm:            $input-btn-font-size-sm;
+
+$btn-padding-y-lg:            $input-btn-padding-y-lg;
+$btn-padding-x-lg:            $input-btn-padding-x-lg;
+$btn-font-size-lg:            $input-btn-font-size-lg;
+
+$btn-border-width:            $input-btn-border-width;
+
+$btn-font-weight:             $font-weight-normal;
+$btn-box-shadow:              inset 0 1px 0 rgba($white, .15), 0 1px 1px rgba($black, .075);
+$btn-focus-width:             $input-btn-focus-width;
+$btn-focus-box-shadow:        $input-btn-focus-box-shadow;
+$btn-disabled-opacity:        .65;
+$btn-active-box-shadow:       inset 0 3px 5px rgba($black, .125);
+
+$btn-link-color:              var(--cui-link-color);
+$btn-link-hover-color:        var(--cui-link-hover-color);
+$btn-link-disabled-color:     $gray-600;
+
+// Allows for customizing button radius independently from global border radius
+$btn-border-radius:           $border-radius;
+$btn-border-radius-sm:        $border-radius-sm;
+$btn-border-radius-lg:        $border-radius-lg;
+
+$btn-transition:              color .15s ease-in-out, background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out;
+
+$btn-hover-bg-shade-amount:       15%;
+$btn-hover-bg-tint-amount:        15%;
+$btn-hover-border-shade-amount:   20%;
+$btn-hover-border-tint-amount:    10%;
+$btn-active-bg-shade-amount:      20%;
+$btn-active-bg-tint-amount:       20%;
+$btn-active-border-shade-amount:  25%;
+$btn-active-border-tint-amount:   10%;
+
+// scss-docs-start button-variants
+$button-variants: (
+  "primary": btn-color-map($primary, $primary),
+  "secondary": btn-color-map($secondary, $secondary),
+  "success": btn-color-map($success, $success),
+  "danger": btn-color-map($danger, $danger),
+  "warning": btn-color-map($warning, $warning),
+  "info": btn-color-map($info, $info),
+  "light": btn-color-map($light, $light),
+  "dark": btn-color-map($dark, $dark)
+);
+
+$button-outline-ghost-variants: (
+  "primary": btn-outline-color-map($primary),
+  "secondary": btn-outline-color-map($secondary),
+  "success": btn-outline-color-map($success),
+  "danger": btn-outline-color-map($danger),
+  "warning": btn-outline-color-map($warning),
+  "info": btn-outline-color-map($info),
+  "light": btn-outline-color-map($light),
+  "dark": btn-outline-color-map($dark)
+);
+// scss-docs-end button-variants
+```
+
 ## API
 
 !!!include(./api/button/CButton.api.md)!!!