js/webawesome
1
0
Fork 0
mirror of https://github.com/shoelace-style/webawesome.git synced 2026-01-12 12:09:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revise docs to clarify installation guidance (#638)

Browse Source 
* Revise docs to clarify installation guidance

* Fix broken link

* Clarify `:where(:root)`, add CSS part example
This commit is contained in:
Lindsay M
2025-01-30 14:40:08 -05:00
committed by GitHub
parent c5f91ec2f7
commit a64cc60ad5
8 changed files with 181 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/_layouts/component.njk
View File

@@ -255,7 +255,7 @@
{# Importing #}
<h2>Importing</h2>
<p>
The <a href="/docs/#autoloading">autoloader</a> is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.
The <a href="/docs/installation/#quick-start-autoloading-via-cdn">autoloader</a> is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.
</p>
<wa-tab-group label="How would you like to import this component?">

2
docs/_layouts/overview.njk
View File

@@ -20,6 +20,6 @@ tags: ["overview"]
<script type="module" src="/assets/scripts/filter.js"></script>
{% if content | trim %}
<br> {# Temp fix for spacing issue #}
<wa-divider style="--spacing: var(--wa-space-3xl)"></wa-divider> {# Temp fix for spacing issue #}
{{ content | safe }}
{% endif %}

100
docs/docs/customizing.md
View File

@@ -1,24 +1,28 @@
---
title: Customizing
description: Learn how to customize Web Awesome through parts and custom properties.
description: Learn how to customize Web Awesome through themes, parts, and custom properties.
layout: page-outline
---
Web Awesome components can be customized at a high level through a theming API. This gives you control over theme colors and general styling. For more advanced customizations, you can make use of CSS parts and custom properties to target individual components.
You can customize the look and feel of Web Awesome at a high level with themes. For more advanced customizations, you can make use of CSS parts and custom properties to target individual components.
## Themes
Web Awesome uses numerous CSS custom properties that make up a high-level theming API and provide a consistent look and feel across the entire library. You can customize them and use them in your own application just with CSS — no preprocessor required.
Web Awesome uses [themes](/docs/themes) to apply a cohesive look and feel across the entire library. Themes are built with a collection of predefined CSS custom properties, which we call [design tokens](/docs/tokens), and there are many premade themes you can choose from.
Because these custom properties live at the page level, they're prefixed with `--wa-` to avoid collisions with other libraries or your own custom properties.
To use a theme, simply add a link to the theme's stylesheet to the `<head>` of your page. For example, you can replace the link to `default.css` in the [installation code](/docs/installation/#quick-start-autoloading-via-cdn) with this snippet to use the *Awesome* theme:
To customize a theme, simply override any of these custom properties in your own stylesheet by scoping your styles to `:root`, `:host`, and, if needed, the class for the specific theme you want to override. Here's an example that changes the default brand color (blue) to violet in the light theme using existing [literal colors](/docs/tokens/color/#literal-colors).
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/awesome.css' %}" />
```
You can [customize any theme](/docs/themes/creating) just with CSS — no preprocessor required. All design tokens are prefixed with `--wa-` to avoid collisions with other libraries or your own custom properties. Simply override any design token in your own stylesheet by scoping your styles to `:where(:root)`, `:host`, the class for the specific theme you want to override (if needed), and the class for the relevant color scheme (if needed). Here's an example that changes the default brand color to violet in light mode:
```css
:where(:root),
:host,
.wa-theme-default {
/* Changes the brand color to violet across the library */
.wa-light,
.wa-dark .wa-invert {
--wa-color-brand-fill-quiet: var(--wa-color-violet-95);
--wa-color-brand-fill-normal: var(--wa-color-violet-90);
--wa-color-brand-fill-loud: var(--wa-color-violet-50);
@@ -31,11 +35,15 @@ To customize a theme, simply override any of these custom properties in your own
}
```
For more examples and further guidance, refer to [Themes](/docs/themes) and the Theming section of this documentation. For a complete list of all custom properties used for theming, refer to `src/styles/themes/default.css` in the project's source code.
:::info
Wrapping the `:root` selector in `:where()` gives this selector 0 specificity. This allows us to define our design tokens' default values while ensuring they can be cleanly overridden as needed.
:::
For a complete list of all custom properties used for theming, refer to `src/styles/themes/default.css` in the project's source code.
## Components
Whereas a theme offers a high-level way to customize the library, components offer different hooks as a low-level way to customize them individually.
While themes offer a high-level way to customize the library, components offer different hooks as a low-level way to customize them individually.
Web Awesome components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate their styles and behaviors. As a result, you can't simply target their internals with the usual CSS selectors. Instead, components expose a set of custom properties and CSS parts that can be targeted to customize their appearance.
@@ -122,3 +130,77 @@ CSS parts have a few important advantages:
- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.
## Native Elements
If you're using [native styles](/docs/native), any custom styles added for a component should also target the corresponding native element. In general, the same styles you declare for components will work just the same to style their native counterparts.
For example, we can give `<input type="checkbox">` the same custom styles as `<wa-checkbox>` by using the custom properties required to style the component:
```html {.example}
<wa-checkbox class="pinkify">Web Awesome checkbox</wa-checkbox>
<br />
<label>
<input type="checkbox" class="pinkify" />
HTML checkbox
</label>
<style>
wa-checkbox.pinkify,
input[type="checkbox"].pinkify {
--background-color-checked: hotpink;
--border-color-checked: hotpink;
--border-width: 3px;
--checked-icon-color: lavenderblush;
}
</style>
```
Or, if using CSS parts, we can give both checkboxes the same custom styles using standard CSS properties:
```html {.example}
<wa-checkbox class="purpleify">Web Awesome checkbox</wa-checkbox>
<br />
<label>
<input type="checkbox" class="purpleify" />
HTML checkbox
</label>
<style>
wa-checkbox.purpleify::part(control),
input[type="checkbox"].purpleify {
border-width: 3px;
}
wa-checkbox.purpleify:state(checked)::part(control),
input[type="checkbox"].purpleify:checked {
background-color: darkorchid;
border-color: darkorchid;
color: lavender;
}
</style>
```
## Style Utilities
Similarly, if you're using [style utilities](/docs/utilities), any custom styles added for a specific attribute variation of a component — such as `appearance`, `variant`, or `size` — should also target the corresponding style utility class. This ensures that the attribute and its utility class counterpart work interchangeably.
For example, we can give all outlined callouts a thick left border, regardless of whether they are styled with `appearance="outlined"` or `class="wa-outlined"`:
```html {.example}
<wa-callout appearance="outlined filled">
<wa-icon slot="icon" name="circle-star"></wa-icon>
Here's a callout with <code>appearance="outlined"</code>
</wa-callout>
<wa-callout class="wa-outlined wa-filled">
<wa-icon slot="icon" name="circle-star"></wa-icon>
Here's a callout with <code>class="wa-outlined"</code>
</wa-callout>
<style>
wa-callout:is(
[appearance~="outlined"],
.wa-outlined
) {
border-left-width: var(--wa-panel-border-radius);
}
</style>
```

107
docs/docs/installation.md
View File

@@ -6,7 +6,7 @@ layout: page-outline
Welcome to the Web Awesome alpha release for early backers! 👋
==This is a very early alpha release!== For this preview, we're only offering access to the free components through a temporary CDN. Please be aware: Things can change. Things can break. You probably shouldn't be using this software in production yet! But fear not, we're working hard to polish up the free stuff you see here _plus_ all the great stuff we have planned for Web Awesome Pro!
==This is a very early alpha release!== For this preview, we're offering access to Web Awesome through a temporary CDN. Please be aware: Things can change. Things can break. You probably shouldn't be using this software in production yet! But fear not, we're working hard to polish up everything you see here _plus_ all the great stuff we have planned for Web Awesome Pro!
Thank you so much for backing us!
@@ -20,22 +20,78 @@ As a Web Awesome backer, this early alpha release is _just for you_. Please refr
---
## Autoloading via CDN (Easiest)
## Quick Start (Autoloading via CDN)
The autoloader is the easiest way to use Web Awesome. A lightweight script watches the DOM for unregistered Web Awesome elements and lazy loads them for you — even if they're added dynamically.
To get everything included in Web Awesome, add the following code to the `<head>` of your site:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/default.css' %}" />
<link rel="stylesheet" href="{% cdnUrl 'styles/webawesome.css' %}" />
<script type="module" src="{% cdnUrl 'webawesome.loader.js' %}"></script>
```
This snippet includes three parts:
1. **The default theme**, a stylesheet that gives a cohesive look to Web Awesome components with both light and dark modes
2. **Web Awesome styles**, an optional stylesheet that [styles native HTML elements](/docs/native) and includes [utility classes](/docs/utilities) you can use in your project
3. **The autoloader**, a lightweight script watches the DOM for unregistered Web Awesome elements and lazy loads them for you — even if they're added dynamically
Now you can [start using Web Awesome!](/docs/usage)
:::info
While convenient, autoloading may lead to a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/). The linked article describes some ways to alleviate it.
:::
## Setting the Base Path
---
## Using Font Awesome Kit Codes
Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You can provide it by adding the `data-fa-kit-code` attribute to any element on the page, or by calling the `setKitCode()` method.
```html
<!-- Option 1: the data-fa-kit-code attribute -->
<script src="bundle.js" data-fa-kit-code="abc123"></script>
<!-- Option 2: the setKitCode() method -->
<script type="module">
import { setKitCode } from '{% cdnUrl 'webawesome.loader.js' %}';
setKitCode('YOUR_KIT_CODE_HERE');
</script>
```
---
## Advanced Setup
The autoloader is the easiest way to use Web Awesome, but different projects (or your own preferences!) may require different installation methods.
### Installing via npm
An npm package isn't available in the early backer alpha release, but we'll have one soon! For now, please enjoy [Web Awesome from the CDN](#quick-start-autoloading-via-cdn).
### Cherry Picking
Cherry picking will only load the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component on each page it's used. You'll still need to include the default theme (`styles/themes/default.css`) or another theme to style any imported components.
Here's an example that loads only the button component.
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/default.css' %}" />
<script type="module">
import '{% cdnUrl 'components/button/button.js' %}';
// <wa-button> is ready to use!
</script>
```
You can copy and paste the code to import a component from the "Importing" section of the component's documentation. Note that some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the "Dependencies" section of its docs.
:::warning
You will see files named `chunk.[hash].js` in the `chunks` directory. Never import these files directly, as they are generated and change from version to version.
:::
### Setting the Base Path
Some components rely on assets (icons, images, etc.) and Web Awesome needs to know where they're located. For convenience, Web Awesome will try to auto-detect the correct location based on the script you've loaded it from. This assumes assets are colocated with `webawesome.loader.js` and will "just work" for most users.
@@ -70,45 +126,4 @@ Most of the magic behind assets is handled internally by Web Awesome, but if you
// Get the path to an asset, e.g. /path/to/assets/file.ext
const assetPath = getBasePath('file.ext');
</script>
```
## Using Font Awesome Kit Codes
Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You can provide it by adding the `data-fa-kit-code` attribute to any element on the page, or by calling the `setKitCode()` method.
```html
<!-- Option 1: the data-fa-kit-code attribute -->
<script src="bundle.js" data-fa-kit-code="abc123"></script>
<!-- Option 2: the setKitCode() method -->
<script type="module">
import { setKitCode } from '/path/to/web-awesome/dist/webawesome.js';
setKitCode('YOUR_KIT_CODE_HERE');
</script>
```
## Cherry Picking
Cherry picking will only load the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component on each page it's used.
Here's an example that loads only the button component.
```html
<link rel="stylesheet" href="/path/to/web-awesome/dist/styles/themes/default.css" />
<script type="module" data-webawesome="/path/to/web-awesome/dist">
import '/path/to/web-awesome/dist/components/button/button.js';
// <wa-button> is ready to use!
</script>
```
You can copy and paste the code to import a component from the "Importing" section of the component's documentation. Note that some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the "Dependencies" section of its docs.
:::warning
You will see files named `chunk.[hash].js` in the `chunks` directory. Never import these files directly, as they are generated and change from version to version.
:::
## Using Web Awesome with npm
An npm package isn't available in the early backer alpha release, but we'll have one soon! For now, please enjoy Web Awesome from the CDN as shown above.
```

20
docs/docs/layout.njk
View File

@@ -1,7 +1,25 @@
---
title: Layout
description: Layout components and utility classes help you organize content that can adapt to any device or screen size. Browse the collection of responsive layout tools included in Web Awesome Pro.
description: Layout components and utility classes help you organize content that can adapt to any device or screen size. See the [installation instructions](#installation) to use Web Awesome's layout tools in your project.
layout: overview
categories: ["components", "utilities"]
override:tags: []
---
{% markdown %}
## Installation
Layout components are included in Web Awesome's [autoloader](/docs/installation/#quick-start-autoloading-via-cdn). You can also import them individually via [cherry picking](/docs/installation/#cherry-picking).
Layout utilities are bundled with all [style utilities](/docs/utilities). You can import all Web Awesome page styles (including [native styles](/docs/native/)) by including the following stylesheet in your project:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/webawesome.css' %}" />
```
Or, you can choose to import _only_ the utilities:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/utilities.css' %}" />
```
{% endmarkdown %}

5
docs/docs/native/index.njk
View File

@@ -1,6 +1,7 @@
---
title: Native Styles
description: Native Styles use your theme to style native HTML elements to match the look and feel of Web Awesome components.
description: Native styles apply your theme to native HTML elements so they match the look and feel of Web Awesome components.
See the [installation instructions](#installation) to use native styles in your project.
layout: overview
categories: ['forms', 'apps', 'content']
override:tags: []
@@ -19,7 +20,7 @@ To use all Web Awesome page styles (including [utilities](/docs/utilities/)), in
<link rel="stylesheet" href="{% cdnUrl 'styles/webawesome.css' %}" />
```
Or, to _only_ include styles for built-in elements:
Or, to _only_ include styles for native elements:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/native.css' %}" />

5
docs/docs/themes/index.njk vendored
View File

@@ -1,6 +1,7 @@
---
title: Themes
description: Themes are collections of predefined CSS custom properties that thread through every Web Awesome component and pattern.
description: Themes are collections of design tokens that thread through every Web Awesome component and pattern.
Themes play a crucial role in [customizing Web Awesome](/docs/customizing).
layout: overview
override:tags: []
forTag: theme
@@ -14,7 +15,7 @@ categories:
## What's a Theme?
A theme is a collection of standardized [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*), also called "design tokens," that cover a range of styles from colors to transitions. We use these tokens throughout Web Awesome components for a cohesive look and feel. Our [Design Tokens pages](/docs/tokens/) document these styles so that you can use them freely throughout your project and customize them as needed.
A theme is a collection of standardized [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*), also called "design tokens," that cover a range of styles from colors to transitions. We use these tokens throughout Web Awesome components for a cohesive look and feel. Our [Design Tokens section](/docs/tokens/) document these styles so that you can use them freely throughout your project and customize them as needed.
Themes are scoped to unique classes, such as `wa-theme-default` or `wa-theme-classic`.
Scoping to unique classes allows you to import multiple themes and use them interchangeably without collisions.

6
docs/docs/utilities/index.njk
View File

@@ -1,7 +1,7 @@
---
title: Style Utilities
description: Web Awesome provides a few style utilities to customize styles in ways that cannot necessarily be described by semantic HTML.
Some of these correspond to component attributes, but we also expose utility classes so you can apply these styles to native elements too.
description: Style utilities are preset rules that let you efficiently customize styles for components and native elements alike.
See the [installation instructions](#installation) to use style utilities in your project.
layout: overview
categories: ["layout"]
override:tags: []
@@ -21,6 +21,4 @@ Or, to _only_ include utilities:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/utilities.css' %}" />
```
You can also include individual utilities following the instructions in their pages.
{% endmarkdown %}