Skip to content

Commit

Permalink
docs(website): Update Sass Documentation for @use
Browse files Browse the repository at this point in the history
  • Loading branch information
mlaursen committed Aug 13, 2021
1 parent 29b5d74 commit 68e8c6b
Show file tree
Hide file tree
Showing 12 changed files with 88 additions and 201 deletions.
2 changes: 1 addition & 1 deletion README.md
Expand Up @@ -75,7 +75,7 @@ Next, create a `src/App.scss` file to include all the `react-md` styles and
import the `App.scss` file in the `src/App.js`:

```scss
@import "react-md/dist/react-md";
@use "react-md" as *;

// this will include all the styles from react-md
@include react-md-utils;
Expand Down
Binary file not shown.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Expand Up @@ -30,55 +30,39 @@ want to override **before** you import any `react-md` styles other than the
color palette from the #theme package. So here's a quick example of changing a
few values.

> I recommend keeping a separate `_rmd-variable-overrides.scss` file so you can
> easily keep track of which default variables you have overridden. You can then
> import this in your "global" variables file so you have access to these values
> from any Sass file in your project.
First, create or update `src/_rmd-variable-overrides.scss`:

```scss
@import "@react-md/theme/dist/color-palette";

$rmd-theme-light: false;
// I am bad at colors and chose 2 random ones from https://flatuicolors.com/palette/defo
// probably looks terrible so wouldn't recommend copying this example
$rmd-theme-primary: #3498db;
$rmd-theme-secondary: #d35400;

// make buttons bigger
$rmd-button-text-horizontal-padding: 1.5rem;
$rmd-button-text-border-radius: 0.25rem;
$rmd-button-text-height: 3rem;

// add more padding to the base list
$rmd-list-vertical-padding: 1rem;
$rmd-list-dense-vertical-padding: 0.75rem;

// make each list item a bit more dense
$rmd-list-item-height: 2.5rem;
$rmd-list-item-dense-height: 2rem;
$rmd-list-item-medium-height: 3rem;
$rmd-list-item-dense-medium-height: 2.75rem;
```

Next, import the `rmd-variable-overrides` file into your global variables file
`src/_variables.scss`:
First, create or update `src/_everything.scss`:

```scss
@import "rmd-variable-overrides";
@use "@react-md/theme/dist/color-palette" as *;
@forward "react-md" with (
$rmd-theme-light: false,
// I am bad at colors and chose 2 random ones from https://flatuicolors.com/palette/defo
// probably looks terrible so wouldn't recommend copying this example
$rmd-theme-primary: #3498db,
$rmd-theme-secondary: #d35400,

// make buttons bigger
$rmd-button-text-horizontal-padding: 1.5rem,
$rmd-button-text-border-radius: 0.25rem,
$rmd-button-text-height: 3rem,

// add more padding to the base list
$rmd-list-vertical-padding: 1rem,
$rmd-list-dense-vertical-padding: 0.75rem,

// make each list item a bit more dense
$rmd-list-item-height: 2.5rem,
$rmd-list-item-dense-height: 2rem,
$rmd-list-item-medium-height: 3rem,
$rmd-list-item-dense-medium-height: 2.75rem,
);
```

Finally, update the root styles to import the react-md packages and generate the
base styles:

```scss
@import "variables";

@import "@react-md/button/dist/mixins";
@import "@react-md/theme/dist/mixins";
@import "@react-md/list/dist/mixins";
@import "@react-md/utils/dist/mixins";
@use "./everything" as *;

@include react-md-utils;
```
Expand Down
Expand Up @@ -16,9 +16,6 @@ export interface ThemeUsageProps {
theme: ThemeMode;
}

const DARK_OVERRIDE = `
$rmd-theme-light: false;`;

const toCSSName = (name: string): string => name.replace("-", "_");

export default function ThemeUsage({
Expand All @@ -36,13 +33,14 @@ export default function ThemeUsage({
{`##### SCSS Usage<!-- no-margin-bottom -->
\`\`\`scss
@import '@react-md/theme/dist/color-palette';
${theme === "light" ? "" : DARK_OVERRIDE}
$rmd-theme-primary: $rmd-${primary}-500;
$rmd-theme-secondary: $rmd-${secondary}-a-${accent};
// other variable overrides
@use '@react-md/theme/dist/color-palette' as *;
@use 'react-md' as * with (
$rmd-theme-light: ${theme === "light"},
$rmd-theme-primary: $rmd-${primary}-500,
$rmd-theme-secondary: $rmd-${secondary}-a-${accent},
// other variable overrides
);
@import '~react-md/dist/react-md';
@include react-md-utils;
\`\`\`
Expand Down
Expand Up @@ -9,8 +9,7 @@ My recommended way is using the media query approach along with the #utils
package:

```scss
@import "@react-md/tooltip/dist/mixins";
@import "@react-md/utils/dist/mixins";
@use "react-md" as *;

:root {
@rmd-utils-desktop-media {
Expand Down
4 changes: 0 additions & 4 deletions packages/documentation/src/constants/navItems.tsx
Expand Up @@ -111,10 +111,6 @@ const routes: NavItem[] = [
href: "/customizing-your-theme",
children: "Customizing Your Theme",
},
{
href: "/including-styles-without-webpack",
children: "Including Styles without Webpack",
},
{
href: "/using-the-sass-exports",
children: "Using the Sass Exports",
Expand Down
13 changes: 5 additions & 8 deletions packages/documentation/src/guides/advanced-installation.md
Expand Up @@ -136,7 +136,7 @@ Next, include the font with the weights by using the
`rmd-typography-host-google-font` mixin:

```scss
@import "@react-md/typography/dist/mixins";
@use "react-md" as *;

@include rmd-typography-host-google-font;
```
Expand Down Expand Up @@ -165,11 +165,11 @@ mv ~/Downloads/roboto src/fonts/roboto
```

```scss
@import "@react-md/typography/dist/mixins";
@use "react-md" as *;

@include rmd-typography-host-google-font(
@include .rmd-typography-host-google-font(
Roboto,
$rmd-typography-default-font-weights,
react-md.$rmd-typography-default-font-weights,
"~./fonts/roboto"
);
```
Expand All @@ -192,7 +192,7 @@ you'll use the `rmd-icon-host-material-icons` mixin from the #icon package
instead.

```scss
@import "@react-md/icon/dist/mixins";
@use "react-md" as *;

// if material icons are in `public/fonts/material-icons`
@include rmd-icon-host-material-icons;
Expand Down Expand Up @@ -224,7 +224,6 @@ import {
KeyboardArrowRightSVGIcon,
} from "@react-md/material-icons";


const overrides: ConfiguredIcons = {
// and/or any other configurable icons
back: <KeyboardArrowLeftSVGIcon />,
Expand Down Expand Up @@ -273,5 +272,3 @@ render(
[unpkg.com]: https://unpkg.com
[umd bundle]: https://github.com/umdjs/umd
[configuring externals]: https://webpack.js.org/configuration/externals/#object
[npm-run-all]: https://www.npmjs.com/package/npm-run-all
[including styles without webpack]: /guides/inlucding-styles-without-webpack
50 changes: 24 additions & 26 deletions packages/documentation/src/guides/creating-a-new-app.md
Expand Up @@ -27,18 +27,18 @@ yarn create react-app my-app
```

Once the command has completed, `cd` into the `my-app` directory and install
`react-md` and `node-sass`:
`react-md` and `sass`:

```sh
npm install --save react-md
npm install --save-dev node-sass
npm install --save-dev sass
```

Or with `yarn`:

```sh
yarn add react-md
yarn add --dev node-sass
yarn add --dev sass
```

Now that we've initialized our project, we can go ahead and start up the app
Expand Down Expand Up @@ -68,15 +68,17 @@ general `Configuration` and `Layout` to our app. Start by editing the main
+import { Configuration } from 'react-md';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

-ReactDOM.render(<App />, document.getElementById('root'));
+ReactDOM.render(
+ <Configuration>
+ <App />
+ </Configuration>,
+ document.getElementById('root')
+);
import reportWebVitals from './reportWebVitals';

ReactDOM.render(
<React.StrictMode>
- <App />
+ <Configuration>
+ <App />
+ </Configuration>
</React.StrictMode>,
document.getElementById('root')
);
```

Next, update the `src/App.js` to include the `Layout` component. Since the
Expand All @@ -85,22 +87,21 @@ Next, update the `src/App.js` to include the `Layout` component. Since the
behavior to start with.

```diff
import React from 'react';
import logo from './logo.svg';
+import { Layout, useLayoutNavigation } from 'react-md';
import './App.css';
+
+const navItems = {};
import logo from './logo.svg';
import './App.css';

+const navItems = {};
+
function App() {
return (
- <div className="App">
+ <Layout
+ appBarTitle="react-md App"
+ title="react-md App"
+ navHeaderTitle="My App"
+ treeProps={useLayoutNavigation(navItems, window.location.pathname)}
+ >
+ <div className="App">
<div className="App">
<header className="App-header">
<img src={logo} className="App-logo" alt="logo" />
<p>
Expand All @@ -115,13 +116,10 @@ behavior to start with.
Learn React
</a>
</header>
- </div>
+ </div>
</div>
+ </Layout>
);
}

export default App;
```

When you hit save, you'll be presented with this beauty:
Expand All @@ -133,7 +131,7 @@ Let's fix that by adding the base styles. Create a new file `src/App.scss` that
will import the `react-md` scss library as well as generate the default styles:

```scss
@import "react-md/dist/react-md";
@use "react-md" as *;

@include react-md-utils;
```
Expand All @@ -157,8 +155,8 @@ with the default color scheme.

> If you get an error like this:
>
> ![Missing node-sass error](/creating-a-new-app-node-sass-error.png) you can
> fix it by ensuring to install `node-sass` and restarting your dev server.
> ![Missing sass error](/creating-a-new-app-sass-error.png) you can fix it by
> ensuring to install `sass` and restarting your dev server.
We're getting close, but if you resize your browser, you'll notice something
weird in the layout:
Expand Down
39 changes: 19 additions & 20 deletions packages/documentation/src/guides/customizing-your-theme.md
Expand Up @@ -6,6 +6,7 @@ soon as possible since I'm terrible at colors and just chose two random ones.
The default theme is:

- `$rmd-theme-light: true`
- `$rmd-theme-dark-elevation: true`
- `$rmd-theme-primary: $rmd-purple-500`
- `$rmd-theme-secondary: $rmd-pink-a-400`
- `$rmd-theme-warning: $rmd-deep-orange-a-200`
Expand All @@ -16,25 +17,23 @@ The default theme is:
- `$rmd-theme-dark-background: #303030`
- `$rmd-theme-dark-surface: $rmd-grey-800`

To change your default theme, you'll want to define these variables before the
main `react-md` import in your base `.scss` file. My general recommendation is
to create a `_variables.scss` file that can be imported into any of your other
`.scss` files for your general theme and overrides:
My recommendation is to create a `src/_everything.scss` file that `@forward`s
everything from `react-md` with the overrides required for your app.

`src/_variables.scss`
`src/_everything.scss`

```scss
@import "@react-md/theme/dist/color-palette";

$rmd-theme-primary: $rmd-teal-500;
$rmd-theme-secondary: $rmd-deep-orange-a-400;
@use "@react-md/theme/dist/color-palette" as *;
@forward "react-md" with (
$rmd-theme-primary: $rmd-teal-500,
$rmd-theme-secondary: $rmd-deep-orange-a-400,
);
```

`src/index.scss`

```scss
@import "./variables";
@import "react-md/dist/react-md";
@use "./everything" as *;

@include react-md-utils;
```
Expand All @@ -50,21 +49,21 @@ Implementing a dark theme for your app is as simple as changing the
`$rmd-theme-light` variable to be `false` if it should be applied to your entire
app.

`src/_variables.scss`
`src/_everything.scss`

```scss
@import "@react-md/theme/dist/color-palette";

$rmd-theme-light: false;
$rmd-theme-primary: $rmd-teal-500;
$rmd-theme-secondary: $rmd-deep-orange-a-400;
@use "@react-md/theme/dist/color-palette" as *;
@forward "react-md" with (
$rmd-theme-light: false,
$rmd-theme-primary: $rmd-teal-500,
$rmd-theme-secondary: $rmd-deep-orange-a-400,
);
```

`src/index.scss`

```scss
@import "./variables";
@import "react-md/dist/everything";
@use "./everything";

@include react-md-utils;
```
Expand All @@ -86,7 +85,7 @@ theme in their OS? Luckily, `react-md` provides `rmd-theme-light` and
conditionally apply the dark theme.

```scss
@import "react-md/dist/everything";
@use "react-md" as *;

@media (prefers-color-scheme: dark) {
:root {
Expand Down

0 comments on commit 68e8c6b

Please sign in to comment.