docs: improvements for the readmes and the site structure and demos

Author: hperrin

SVELTEKIT.md

@@ -1,7 +1,5 @@
 # SvelteKit Installation
 
-(You can also check out the [SvelteKit example repo](https://github.com/hperrin/smui-example-sveltekit).)
-
 You will need to install the packages you use individually as well as the theme package.
 
 ```sh
@@ -18,73 +16,72 @@ Create your theme files with `smui-theme`.
 npx smui-theme template src/theme
 ```
 
-You can [modify your theme variables](/THEMING.md#theme-variables) in the files now in `src/theme`.
+You can [modify your theme variables](/THEMING.md#theme-variables) in the files now in `src/theme` and `src/theme/dark`. You can also add the [Material typography styles](/TYPOGRAPHY.md).
 
 ## Theme Build Scripts
 
-You'll need one of these sets of prepare scripts in your `package.json` file. Note that SvelteKit already provides a "prepare" script, so you'll need to modify it to look like below.
+You'll need one of these sets of prepare scripts in your `package.json` file.
 
-- Without Dark Mode support.
+With Dark Mode support.
 
-  ```
-  "prepare": "npm run smui-theme",
-  "smui-theme": "smui-theme compile static/smui.css -i src/theme"
-  ```
+```
+"prepare": "npm run smui-theme-light && npm run smui-theme-dark",
+"smui-theme-light": "smui-theme compile static/smui.css -i src/theme",
+"smui-theme-dark": "smui-theme compile static/smui-dark.css -i src/theme/dark"
+```
 
-- With Dark Mode support.
+Or, without Dark Mode support.
 
-  ```
-  "prepare": "npm run smui-theme-light && npm run smui-theme-dark",
-  "smui-theme-light": "smui-theme compile static/smui.css -i src/theme",
-  "smui-theme-dark": "smui-theme compile static/smui-dark.css -i src/theme/dark"
-  ```
+```
+"prepare": "npm run smui-theme",
+"smui-theme": "smui-theme compile static/smui.css -i src/theme"
+```
 
 ## Stylesheets
 
 Now in your `src/app.html` file, add the following to the `head` section:
 
+With Dark Mode support.
+
 ```html
-<!-- Material Icons -->
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/icon?family=Material+Icons"
-/>
-<!-- Roboto -->
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700"
-/>
-<!-- Roboto Mono -->
+<!-- SMUI Styles -->
+<link rel="stylesheet" href="/smui.css" media="(prefers-color-scheme: light)" />
 <link
   rel="stylesheet"
-  href="https://fonts.googleapis.com/css?family=Roboto+Mono"
+  href="/smui-dark.css"
+  media="screen and (prefers-color-scheme: dark)"
 />
 ```
 
-And this for without Dark Mode support.
+Or, without Dark Mode support.
 
 ```html
 <!-- SMUI Styles -->
 <link rel="stylesheet" href="/smui.css" />
 ```
 
-Or this for with Dark Mode support.
+### Fonts
+
+Material uses the Roboto fonts, so include those as well. If you'd like to use the Material Icons font, include that as well.
 
 ```html
-<!-- SMUI Styles -->
-<link rel="stylesheet" href="/smui.css" media="(prefers-color-scheme: light)" />
+<!-- Material Icons -->
 <link
   rel="stylesheet"
-  href="/smui-dark.css"
-  media="screen and (prefers-color-scheme: dark)"
+  href="https://fonts.googleapis.com/icon?family=Material+Icons"
+/>
+<!-- Roboto -->
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700"
+/>
+<!-- Roboto Mono -->
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css?family=Roboto+Mono"
 />
 ```
 
-<small>
-  <i style="font-size: 1em;" class="material-icons">info</i>
-  Note: There used to be a Vite config step at this point, because SMUI was packaged incorrectly. It is now packaged correctly, so that's no longer required.
-</small>
-
 ## Finishing Up
 
 After that, run `npm run prepare` to build your CSS file, then you can run `npm run dev` to start developing. Happy coding!

THEMING.md

@@ -2,6 +2,8 @@
 
 ## Theming with Sass
 
+If you're going to theme with Sass, reading an [introduction to Sass](https://sass-lang.com/guide) would be helpful. Hoever, you don't need to know much about Sass to make basic themes for SMUI.
+
 To create a custom Sass theme, install the SMUI Theme Builder.
 
 ```sh
@@ -14,32 +16,25 @@ You can use it to create your theme directory from a template. Adjust to your so
 npx smui-theme template src/theme
 ```
 
-This creates `_smui-theme.scss` files in `src/theme`. That is where you set the theme variables.
+This creates a `_smui-theme.scss` file in `src/theme` for light mode and an alternative `_smui-theme.scss` file in `src/theme/dark` for dark mode. That is where you set the theme variables.
 
 ### Building Your Theme
 
 In your package.json file, add this script in the "scripts" section, adjusting the source/destination files as needed.
 
-```
-"prepare": "smui-theme compile build/smui.css -i src/theme",
-```
-
-Or for dark mode support.
-
 ```
 "prepare": "npm run smui-theme-light && npm run smui-theme-dark",
 "smui-theme-light": "smui-theme compile build/smui.css -i src/theme",
 "smui-theme-dark": "smui-theme compile build/smui-dark.css -i src/theme/dark",
 ```
 
-Now run `npm run prepare` to build the CSS file(s), then add it/them on your page. Something like this, adjusting the paths as needed.
+Or if you don't need dark mode support.
 
-```html
-<!-- SMUI Styles -->
-<link rel="stylesheet" href="/smui.css" />
+```
+"prepare": "smui-theme compile build/smui.css -i src/theme",
 ```
 
-Or for dark mode support.
+Now run `npm run prepare` to build the CSS file(s), then add them on your page. Something like this, adjusting the paths as needed.
 
 ```html
 <!-- SMUI Styles -->
@@ -51,11 +46,20 @@ Or for dark mode support.
 />
 ```
 
-Note: The smui-theme compiler will only include the Sass for the packages installed when it is run. If you install a new SMUI package, you should run `npm run prepare` to rebuild the CSS.
+Or if you don't need dark mode support.
+
+```html
+<!-- SMUI Styles -->
+<link rel="stylesheet" href="/smui.css" />
+```
+
+Important: The smui-theme compiler will only include the Sass for the packages installed when it is run. If you install a new SMUI package, you should run `npm run prepare` to rebuild the CSS.
 
 ### Theme Variables
 
-You can check out the READMEs of [the MDC-Web components](https://github.com/material-components/material-components-web/tree/v14.0.0/packages) to learn how to deeply style the components. The most important part (and probably the only one you want) is setting the [theme colors](https://github.com/material-components/material-components-web/tree/v14.0.0/packages/mdc-theme#color-scheme). For the Material color palette, you can @use ["@material/theme/color-palette"](https://github.com/material-components/material-components-web/blob/v14.0.0/packages/mdc-theme/_color-palette.scss). You might also want to style the [border radius variables](https://github.com/material-components/material-components-web/tree/v14.0.0/packages/mdc-shape#sass-variables).
+The most important part of theming (and probably the only one you want) is setting the [theme colors](https://github.com/material-components/material-components-web/tree/v14.0.0/packages/mdc-theme#color-scheme). For the Material color palette, you can @use ["@material/theme/color-palette"](https://github.com/material-components/material-components-web/blob/v14.0.0/packages/mdc-theme/_color-palette.scss). You might also want to style the [border radius variables](https://github.com/material-components/material-components-web/tree/v14.0.0/packages/mdc-shape#sass-variables).
+
+To learn how to deeply style the individual components, you can check out the READMEs of [the MDC-Web components](https://github.com/material-components/material-components-web/tree/v14.0.0/packages). If you need more help, check out the [theming guide](https://m2.material.io/develop/web/theming/theming-guide) on the MDC-Web website. SMUI uses all the styles from MDC-Web, so everything regarding Sass and CSS from that guide should work with SMUI.
 
 Here is an example `_smui-theme.scss` file you can use as a starting point.
 
@@ -102,12 +106,16 @@ Just make sure that you put that directly after the `@use '@material/theme/index
 
 ### Adding Classes and Variables
 
-If you want to use MDC's classes and variables (like `var(--mdc-theme-primary)` and `class="mdc-theme--primary-bg"`), you can add the following line somewhere in your Sass files. A great place to add it is in your `_smui-theme.scss` file.
+If you want to use MDC's classes and variables (like `var(--mdc-theme-primary)` and `class="mdc-theme--primary-bg"`), you can add the following line somewhere in your Sass files. A great place to add it is in your `_smui-theme.scss` files.
 
 ```scss
 @use '@material/theme/styles';
 ```
 
+## Adding Material Typography
+
+You can [add Material typography](/TYPOGRAPHY.md) as the default for your app.
+
 ## Theming the Bare CSS
 
 If you use the bare CSS, you can set a subset of the theme options with CSS variables. Note that not all of the colors in SMUI read from CSS variables, so some parts will still use the colors defined in the original Sass compile. Below is a copy of the variables from the CSS on the SMUI website. You can use this as a starting point for your own theme.

TYPOGRAPHY.md

@@ -0,0 +1,58 @@
+# Material Typoography
+
+If you'd like to style your entire app using Material's typography, you can add Sass like this to your `_smui-theme.scss` files.
+
+```scss
+// Import the mixins.
+@use '@material/typography/index' as typography;
+
+html {
+  @include typography.typography('body1');
+}
+
+h1 {
+  @include typography.typography('headline1');
+}
+
+h2 {
+  @include typography.typography('headline2');
+}
+
+h3 {
+  @include typography.typography('headline3');
+}
+
+h4 {
+  @include typography.typography('headline4');
+}
+
+h5 {
+  @include typography.typography('headline5');
+}
+
+h6 {
+  @include typography.typography('headline6');
+}
+
+caption {
+  @include typography.typography('caption');
+}
+
+code,
+pre {
+  font-family: 'Roboto Mono', monospace;
+}
+
+small {
+  font-size: 0.9em;
+}
+
+big {
+  font-size: 1.1em;
+}
+
+b,
+strong {
+  font-weight: bold;
+}
+```

packages/site/src/routes/+layout.svelte

@@ -241,35 +241,20 @@
       separator: true,
     },
     {
-      name: 'Accordion',
-      route: '/demo/accordion/',
-      indent: 0,
-      repos: [
-        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/accordion',
-      ],
-    },
-    {
-      name: 'Badge',
-      route: '/demo/badge/',
+      name: 'Introduction',
+      route: '/demo/introduction/',
       indent: 0,
-      repos: [
-        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/badge',
-      ],
     },
     {
-      name: 'Banner',
-      route: '/demo/banner/',
-      indent: 0,
-      repos: [
-        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/banner',
-      ],
+      name: 'sep2',
+      separator: true,
     },
     {
-      name: 'Bottom App Bar',
-      route: '/demo/bottom-app-bar/',
+      name: 'Accordion',
+      route: '/demo/accordion/',
       indent: 0,
       repos: [
-        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/bottom-app-bar',
+        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/accordion',
       ],
     },
     {
@@ -300,6 +285,42 @@
         'https://github.com/hperrin/svelte-material-ui/tree/master/packages/icon-button',
       ],
     },
+    {
+      name: 'App Bars',
+      indent: 0,
+    },
+    {
+      name: 'Bottom App Bar',
+      route: '/demo/bottom-app-bar/',
+      indent: 1,
+      repos: [
+        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/bottom-app-bar',
+      ],
+    },
+    {
+      name: 'Top App Bar',
+      route: '/demo/top-app-bar/',
+      indent: 1,
+      repos: [
+        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/top-app-bar',
+      ],
+    },
+    {
+      name: 'Badge',
+      route: '/demo/badge/',
+      indent: 0,
+      repos: [
+        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/badge',
+      ],
+    },
+    {
+      name: 'Banner',
+      route: '/demo/banner/',
+      indent: 0,
+      repos: [
+        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/banner',
+      ],
+    },
     {
       name: 'Cards',
       route: '/demo/card/',
@@ -531,14 +552,6 @@
         'https://github.com/hperrin/svelte-material-ui/tree/master/packages/tooltip',
       ],
     },
-    {
-      name: 'Top App Bar',
-      route: '/demo/top-app-bar/',
-      indent: 0,
-      repos: [
-        'https://github.com/hperrin/svelte-material-ui/tree/master/packages/top-app-bar',
-      ],
-    },
     {
       name: 'Touch Target',
       route: '/demo/touch-target/',

packages/site/src/routes/+page.svelte

@@ -47,7 +47,7 @@
         <Content>
           Many SMUI components are based on <a
             style="color: #fff;"
-            href="https://material.io/develop/web"
+            href="https://github.com/material-components/material-components-web"
             target="_blank">Material Design Components for Web</a
           >, by Google. It integrates these components using the
           <a
@@ -223,7 +223,7 @@
             <SecondaryText style="white-space: normal;">
               With over <a
                 href="https://github.com/hperrin/svelte-material-ui/network/dependents?package_id=UGFja2FnZS01NTM5MDg5MDQ"
-                target="_blank">1700 projects</a
+                target="_blank">2200 projects</a
               > using SMUI components, it is the most popular Svelte UI library.
               For good reason, too. It is the most versatile and adaptable Svelte
               UI library, guaranteed.
@@ -285,7 +285,7 @@
       <a href="https://github.com/hperrin/svelte-material-ui/issues"
         >Issue Tracker</a
       >
-      | &copy; 2022 Hunter Perrin ]
+      | &copy; 2019-2023 Hunter Perrin ]
     </p>
   </div>
 </section>