From 83fb761d414ffd100d59948a9e8b27943c83184c Mon Sep 17 00:00:00 2001
From: Lea Verou <lea@verou.me>
Date: Fri, 20 Dec 2024 14:01:01 -0500
Subject: [PATCH] Rename `applied.css` to docs and add some docs on usage

---
 docs/_includes/base-wide.njk         |   2 +-
 docs/_includes/base.njk              |   2 +-
 docs/_layouts/blank.njk              |   2 +-
 docs/assets/scripts/code-examples.js |   2 +-
 docs/docs/native/index.md            |  16 +++--
 docs/docs/utilities/index.md         |  20 +++++-
 src/styles/applied.css               | 101 ---------------------------
 src/styles/native.css                |  17 +++++
 src/styles/native/base.css           |  75 ++++++++++++++++++++
 src/styles/webawesome.css            |   9 +++
 10 files changed, 135 insertions(+), 111 deletions(-)
 delete mode 100644 src/styles/applied.css
 create mode 100644 src/styles/native.css
 create mode 100644 src/styles/native/base.css
 create mode 100644 src/styles/webawesome.css

diff --git a/docs/_includes/base-wide.njk b/docs/_includes/base-wide.njk
index 74b3af98a..8d0ce9237 100644
--- a/docs/_includes/base-wide.njk
+++ b/docs/_includes/base-wide.njk
@@ -23,7 +23,7 @@
     {# Web Awesome #}
     <script type="module" src="/dist/webawesome.loader.js"></script>
     <link rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/default.css" />
-    <link rel="stylesheet" href="/dist/styles/applied.css" />
+    <link rel="stylesheet" href="/dist/styles/webawesome.css" />
     <link id="color-stylesheet" rel="stylesheet" href="/dist/styles/color/standard.css" />
     <link rel="stylesheet" href="/dist/styles/forms.css" />
 
diff --git a/docs/_includes/base.njk b/docs/_includes/base.njk
index 1f5e21128..9ec84b4a0 100644
--- a/docs/_includes/base.njk
+++ b/docs/_includes/base.njk
@@ -32,7 +32,7 @@
     {# Web Awesome #}
     <script type="module" src="/dist/webawesome.ssr-loader.js"></script>
     <link rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/default.css" />
-    <link rel="stylesheet" href="/dist/styles/applied.css" />
+    <link rel="stylesheet" href="/dist/styles/webawesome.css" />
     <link id="color-stylesheet" rel="stylesheet" href="/dist/styles/utilities.css" />
     <link rel="stylesheet" href="/dist/styles/forms.css" />
 
diff --git a/docs/_layouts/blank.njk b/docs/_layouts/blank.njk
index 8807acc09..8dc25ef9a 100644
--- a/docs/_layouts/blank.njk
+++ b/docs/_layouts/blank.njk
@@ -21,7 +21,7 @@
     {# Web Awesome #}
     <script type="module" src="/dist/webawesome.ssr-loader.js"></script>
     <link rel="stylesheet" id="theme-stylesheet" />
-    <link rel="stylesheet" href="/dist/styles/applied.css" />
+    <link rel="stylesheet" href="/dist/styles/webawesome.css" />
     <link id="color-stylesheet" rel="stylesheet" href="/dist/styles/utilities.css" />
     <link rel="stylesheet" href="/dist/styles/forms.css" />
 
diff --git a/docs/assets/scripts/code-examples.js b/docs/assets/scripts/code-examples.js
index e7c55fa16..daa4d732c 100644
--- a/docs/assets/scripts/code-examples.js
+++ b/docs/assets/scripts/code-examples.js
@@ -19,7 +19,7 @@ document.addEventListener('click', event => {
     const html =
       `<script type="module" src="${cdnUrl}webawesome.loader.js"></script>\n` +
       `<link rel="stylesheet" href="${cdnUrl}styles/themes/default.css">\n` +
-      `<link rel="stylesheet" href="${cdnUrl}styles/applied.css">\n` +
+      `<link rel="stylesheet" href="${cdnUrl}styles/webawesome.css">\n` +
       `<link rel="stylesheet" href="${cdnUrl}styles/utilities.css">\n\n` +
       `${code.textContent}`;
     const css = 'html > body {\n  font: 16px sans-serif;\n  padding: 2rem;\n}';
diff --git a/docs/docs/native/index.md b/docs/docs/native/index.md
index 3bab34503..8082143ae 100644
--- a/docs/docs/native/index.md
+++ b/docs/docs/native/index.md
@@ -8,13 +8,21 @@ Web Awesome works _with_ the platform, rather than trying to reinvent it.
 If all you need is styles, you don’t need to use new `<wa-*>` elements!
 We also provide styles that make native HTML elements look good so you can continue using what you know and gradually adopt Web Awesome as you see fit.
 
-To use all Web Awesome Native Styles, include the following stylesheet in your project:
+## Usage
+
+To use all Web Awesome page styles (including [utilities](/docs/utilities/)), include the following stylesheet in your project:
 
 ```html
-<link rel="stylesheet" href="{% cdnUrl 'styles/applied.css' %}" />
+<link rel="stylesheet" href="{% cdnUrl 'styles/webawesome.css' %}" />
 ```
 
-Here’s what we have so far:
+Or, to _only_ include styles for built-in elements:
+
+```html
+<link rel="stylesheet" href="{% cdnUrl 'styles/native.css' %}" />
+```
+
+## Elements
 
 <div id="component-grid" class="index-grid">
   <!-- <h2 class="index-category">Actions</h2> -->
@@ -35,7 +43,7 @@ Instead of including Native Styles with a `<link>` element, you can include it l
 
 ```html
 <style>
-@import url('{% cdnUrl 'styles/applied.css' %}') layer(wa);
+@import url('{% cdnUrl 'styles/webawesome.css' %}') layer(wa);
 
 @layer wa {
   .wa-off,
diff --git a/docs/docs/utilities/index.md b/docs/docs/utilities/index.md
index bddb70408..355ae9bbb 100644
--- a/docs/docs/utilities/index.md
+++ b/docs/docs/utilities/index.md
@@ -5,8 +5,24 @@ description: Web Awesome provides a few style utilities to customize styles in w
 layout: page-outline
 ---
 
+## Usage
+
+To use all Web Awesome page styles (including [native styles](/docs/native/)), include the following stylesheet in your project:
+
+```html
+<link rel="stylesheet" href="{% cdnUrl 'styles/webawesome.css' %}" />
+```
+
+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.
+
 <div id="component-grid" class="index-grid">
-  <h2 class="index-category">Layout</h2>
+  <h2 class="index-category">Layout Utilities</h2>
 
   {%- for page in collections.utilities | sort -%}
   {%- if page.fileSlug != 'native' and 'layout' in page.data.tags -%}
@@ -16,7 +32,7 @@ layout: page-outline
 </div>
 
 <div id="component-grid" class="index-grid">
-  <h2 class="index-category">Other</h2>
+  <h2 class="index-category">Other Utilities</h2>
 
   {%- for page in collections.utilities | sort -%}
   {%- if page.fileSlug != 'native' and not ('layout' in page.data.tags) -%}
diff --git a/src/styles/applied.css b/src/styles/applied.css
deleted file mode 100644
index 574a3e328..000000000
--- a/src/styles/applied.css
+++ /dev/null
@@ -1,101 +0,0 @@
-/* Native styles */
-@import url('native/content.css');
-@import url('native/code.css');
-@import url('native/forms.css');
-@import url('native/button.css');
-@import url('native/checkbox.css');
-@import url('native/color-picker.css');
-@import url('native/input.css');
-@import url('native/details.css');
-@import url('native/tables.css');
-@import url('native/blockquote.css');
-@import url('native/dialog.css');
-@import url('native/progress.css');
-@import url('native/radio.css');
-@import url('native/select.css');
-@import url('native/slider.css');
-
-/* Web Awesome components */
-@import url('components/page.css');
-
-/* CSS Utilities */
-@import url('utilities.css');
-
-/**
- * Applied styles are used to "reset" a page and provide defaults for typography and native HTML elements based on
- * Web Awesome's design tokens.
- */
-html {
-  box-sizing: border-box;
-  background-color: var(--wa-color-surface-default);
-  padding: 0;
-  margin: 0;
-  tab-size: 4;
-}
-
-*,
-*::before,
-*::after {
-  box-sizing: inherit;
-}
-
-body {
-  min-height: 100vh;
-  font-family: var(--wa-font-family-body);
-  font-size: var(--wa-font-size-m);
-  font-weight: var(--wa-font-weight-body);
-  line-height: var(--wa-line-height-normal);
-  text-size-adjust: none;
-  color: var(--wa-color-text-normal);
-  padding: 0;
-  margin: 0;
-  -moz-osx-font-smoothing: grayscale;
-  -webkit-font-smoothing: antialiased;
-  -moz-text-size-adjust: none;
-  -webkit-text-size-adjust: none;
-}
-
-@keyframes wa-fade-in {
-  from {
-    opacity: 0;
-  }
-}
-
-/* Show custom elements only after they're registered */
-:where(:not(:defined, [did-ssr])) {
-  /*
-    * if an element gets defined earlier than 800ms, the animation stops applying so it just appears (no fade)
-    * If it takes somewhere between 800 and 1000 ms, then you may get an interrupted fade
-    * If an element takes longer than 1000ms to get defined, it fades in over 200ms
-    */
-  animation: 200ms 800ms wa-fade-in both;
-}
-
-/* Content flow */
-address,
-audio,
-blockquote,
-dd,
-details,
-dl,
-figure,
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-iframe,
-ol,
-p,
-pre,
-table,
-ul,
-video,
-wa-callout,
-wa-code-demo,
-wa-viewport-demo {
-  &:has(+ *) {
-    margin: 0 0 var(--wa-space-xl) 0;
-  }
-}
diff --git a/src/styles/native.css b/src/styles/native.css
new file mode 100644
index 000000000..0cbbf6e4d
--- /dev/null
+++ b/src/styles/native.css
@@ -0,0 +1,17 @@
+/* Web Awesome Native styles */
+@import url('native/base.css');
+@import url('native/content.css');
+@import url('native/code.css');
+@import url('native/forms.css');
+@import url('native/button.css');
+@import url('native/checkbox.css');
+@import url('native/color-picker.css');
+@import url('native/input.css');
+@import url('native/details.css');
+@import url('native/tables.css');
+@import url('native/blockquote.css');
+@import url('native/dialog.css');
+@import url('native/progress.css');
+@import url('native/radio.css');
+@import url('native/select.css');
+@import url('native/slider.css');
diff --git a/src/styles/native/base.css b/src/styles/native/base.css
new file mode 100644
index 000000000..50883518a
--- /dev/null
+++ b/src/styles/native/base.css
@@ -0,0 +1,75 @@
+/* Baseline styles for the root elements or multiple native elements at once */
+html {
+  box-sizing: border-box;
+  background-color: var(--wa-color-surface-default);
+  padding: 0;
+  margin: 0;
+  tab-size: 4;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  min-height: 100vh;
+  font-family: var(--wa-font-family-body);
+  font-size: var(--wa-font-size-m);
+  font-weight: var(--wa-font-weight-body);
+  line-height: var(--wa-line-height-normal);
+  text-size-adjust: none;
+  color: var(--wa-color-text-normal);
+  padding: 0;
+  margin: 0;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+  -moz-text-size-adjust: none;
+  -webkit-text-size-adjust: none;
+}
+
+@keyframes wa-fade-in {
+  from {
+    opacity: 0;
+  }
+}
+
+/* Show custom elements only after they're registered */
+:where(:not(:defined, [did-ssr])) {
+  /*
+	  * if an element gets defined earlier than 800ms, the animation stops applying so it just appears (no fade)
+	  * If it takes somewhere between 800 and 1000 ms, then you may get an interrupted fade
+	  * If an element takes longer than 1000ms to get defined, it fades in over 200ms
+	  */
+  animation: 200ms 800ms wa-fade-in both;
+}
+
+/* Content flow */
+address,
+audio,
+blockquote,
+dd,
+details,
+dl,
+figure,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+iframe,
+ol,
+p,
+pre,
+table,
+ul,
+video,
+wa-callout,
+wa-code-demo,
+wa-viewport-demo {
+  &:has(+ *) {
+    margin: 0 0 var(--wa-space-xl) 0;
+  }
+}
diff --git a/src/styles/webawesome.css b/src/styles/webawesome.css
new file mode 100644
index 000000000..8763aed04
--- /dev/null
+++ b/src/styles/webawesome.css
@@ -0,0 +1,9 @@
+/* Native styles */
+@import url('native/base.css'); /* for speed */
+@import url('native.css');
+
+/* Web Awesome components */
+@import url('components/page.css');
+
+/* CSS Utilities */
+@import url('utilities.css');