You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/_layouts/component.njk
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -255,7 +255,7 @@
255
255
{# Importing #}
256
256
<h2>Importing</h2>
257
257
<p>
258
-
The <ahref="/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.
258
+
The <ahref="/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.
259
259
</p>
260
260
261
261
<wa-tab-grouplabel="How would you like to import this component?">
Copy file name to clipboardExpand all lines: docs/docs/customizing.md
+91-9Lines changed: 91 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,24 +1,28 @@
1
1
---
2
2
title: Customizing
3
-
description: Learn how to customize Web Awesome through parts and custom properties.
3
+
description: Learn how to customize Web Awesome through themes, parts, and custom properties.
4
4
layout: page-outline
5
5
---
6
6
7
-
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.
7
+
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.
8
8
9
9
## Themes
10
10
11
-
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.
11
+
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.
12
12
13
-
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.
13
+
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:
14
14
15
-
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).
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:
16
20
17
21
```css
18
22
:where(:root),
19
23
:host,
20
-
.wa-theme-default {
21
-
/* Changes the brand color to violet across the library */
@@ -31,11 +35,15 @@ To customize a theme, simply override any of these custom properties in your own
31
35
}
32
36
```
33
37
34
-
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.
38
+
:::info
39
+
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.
40
+
:::
41
+
42
+
For a complete list of all custom properties used for theming, refer to `src/styles/themes/default.css` in the project's source code.
35
43
36
44
## Components
37
45
38
-
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.
46
+
While themes offer a high-level way to customize the library, components offer different hooks as a low-level way to customize them individually.
39
47
40
48
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.
41
49
@@ -122,3 +130,77 @@ CSS parts have a few important advantages:
122
130
- 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.
123
131
124
132
Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.
133
+
134
+
## Native Elements
135
+
136
+
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.
137
+
138
+
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:
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.
186
+
187
+
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"`:
188
+
```html {.example}
189
+
<wa-calloutappearance="outlined filled">
190
+
<wa-iconslot="icon"name="circle-star"></wa-icon>
191
+
Here's a callout with <code>appearance="outlined"</code>
192
+
</wa-callout>
193
+
<wa-calloutclass="wa-outlined wa-filled">
194
+
<wa-iconslot="icon"name="circle-star"></wa-icon>
195
+
Here's a callout with <code>class="wa-outlined"</code>
Copy file name to clipboardExpand all lines: docs/docs/installation.md
+61-46Lines changed: 61 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ layout: page-outline
6
6
7
7
Welcome to the Web Awesome alpha release for early backers! 👋
8
8
9
-
==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!
9
+
==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!
10
10
11
11
Thank you so much for backing us!
12
12
@@ -20,95 +20,110 @@ As a Web Awesome backer, this early alpha release is _just for you_. Please refr
20
20
21
21
---
22
22
23
-
## Autoloading via CDN (Easiest)
23
+
## Quick Start (Autoloading via CDN)
24
24
25
-
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.
25
+
To get everything included in Web Awesome, add the following code to the `<head>` of your site:
1.**The default theme**, a stylesheet that gives a cohesive look to Web Awesome components with both light and dark modes
35
+
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
36
+
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
37
+
32
38
Now you can [start using Web Awesome!](/docs/usage)
33
39
34
40
:::info
35
41
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.
36
42
:::
37
43
38
-
## Setting the Base Path
44
+
---
39
45
40
-
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.
46
+
## Using Font Awesome Kit Codes
41
47
42
-
==If you're using the CDN, you can skip this section.== However, if you're [cherry picking](#cherry-picking) or bundling Web Awesome, you'll need to set the base path. You can do this one of two ways.
48
+
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.
Most of the magic behind assets is handled internally by Web Awesome, but if you need to reference the base path for any reason, the same module exports a function called `getBasePath()`. An optional string argument can be passed, allowing you to get the full path to any asset.
The autoloader is the easiest way to use Web Awesome, but different projects (or your own preferences!) may require different installation methods.
62
66
63
-
setBasePath('/path/to/assets');
67
+
### Installing via npm
64
68
65
-
// ...
69
+
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).
66
70
67
-
// Get the base path, e.g. /path/to/assets
68
-
constbasePath=getBasePath();
71
+
### Cherry Picking
69
72
70
-
// Get the path to an asset, e.g. /path/to/assets/file.ext
71
-
constassetPath=getBasePath('file.ext');
72
-
</script>
73
-
```
73
+
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.
74
74
75
-
## Using Font Awesome Kit Codes
76
-
77
-
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.
75
+
Here's an example that loads only the button component.
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.
91
88
92
-
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.
89
+
:::warning
90
+
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.
91
+
:::
93
92
94
-
Here's an example that loads only the button component.
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.
101
97
102
-
// <wa-button> is ready to use!
98
+
==If you're using the CDN, you can skip this section.== However, if you're [cherry picking](#cherry-picking) or bundling Web Awesome, you'll need to set the base path. You can do this one of two ways.
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.
111
+
### Referencing Assets
107
112
108
-
:::warning
109
-
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.
110
-
:::
113
+
Most of the magic behind assets is handled internally by Web Awesome, but if you need to reference the base path for any reason, the same module exports a function called `getBasePath()`. An optional string argument can be passed, allowing you to get the full path to any asset.
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.
119
+
setBasePath('/path/to/assets');
120
+
121
+
// ...
122
+
123
+
// Get the base path, e.g. /path/to/assets
124
+
constbasePath=getBasePath();
125
+
126
+
// Get the path to an asset, e.g. /path/to/assets/file.ext
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.
3
+
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.
4
4
layout: overview
5
5
categories: ["components", "utilities"]
6
6
override:tags: []
7
7
---
8
+
9
+
{%markdown%}
10
+
## Installation
11
+
12
+
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).
13
+
14
+
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:
0 commit comments