Skip to content

Commit 9c58fc9

Browse files
hperrinhperrin
committed
feat: new easy styling method
1 parent 18b49e4 commit 9c58fc9

13 files changed

+567
-276
lines changed

‎.gitignore

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
node_modules
2-
/packages/**/bare.css
2+
bare.css
33
/site/.svelte
44
/site/build

‎INSTALL.md

+113-190
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,124 @@ npm install --save-dev @smui/card
1414
npm install --save-dev svelte-material-ui
1515
```
1616

17-
(From here there are [different instructions](INSTALL.md#integration-for-sapper) for Sapper.)
17+
You can also [use SMUI in the Svelte REPL](REPL.md).
1818

19-
You also need [Dart Sass](https://www.npmjs.com/package/sass). (`node-sass` is deprecated, and SMUI uses features that it doesn't support.)
19+
## Importing Components
20+
21+
You will always import Svelte components from the individual packages.
22+
23+
This method will include Sass files as well. Use this for the Advanced Styling Method.
24+
25+
```svelte
26+
<script>
27+
import Button from '@smui/button';
28+
</script>
29+
```
30+
31+
And this method will only include the components. Use this for the Easy Styling Method.
32+
33+
```svelte
34+
<script>
35+
import Button from '@smui/button/bare';
36+
</script>
37+
```
38+
39+
Notice that adding "/bare" to your import path means no Sass files will be imported. Use this method if you use the Easy Styling Method or the Default Theme with "bare.css".
40+
41+
## Material Fonts
42+
43+
If you want the Material Icon, Roboto, and Roboto Mono fonts, be sure to include these stylesheets (or include them from a package).
44+
45+
```html
46+
<!-- Material Icons -->
47+
<link
48+
rel="stylesheet"
49+
href="https://fonts.googleapis.com/icon?family=Material+Icons"
50+
/>
51+
<!-- Roboto -->
52+
<link
53+
rel="stylesheet"
54+
href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700"
55+
/>
56+
<!-- Roboto Mono -->
57+
<link
58+
rel="stylesheet"
59+
href="https://fonts.googleapis.com/css?family=Roboto+Mono"
60+
/>
61+
```
62+
63+
# Using the Default Theme
64+
65+
If you don't care about theming, you can use the prebuilt "bare.css" file from the "svelte-material-ui" package. You can also use the "bare.css" files from the individual packages if you don't use many components and want smaller file sizes.
66+
67+
```sh
68+
npm install --save svelte-material-ui
69+
```
70+
71+
```html
72+
<link rel="stylesheet" href="node_modules/svelte-material-ui/bare.css" />
73+
```
74+
75+
Remember to import components with the "/bare" endpoint. If you want to theme SMUI, follow the next section instead.
76+
77+
# Using a Custom Theme
78+
79+
You will need [Dart Sass](https://www.npmjs.com/package/sass). (`node-sass` is deprecated, and SMUI uses features that it doesn't support.)
2080

2181
```sh
2282
npm install --save-dev sass
2383
```
2484

85+
You must have a `_smui-theme.scss` file in one of your Sass include paths to compile the Sass. That is where you [set the theme variables](THEMING.md). You can create a "theme" directory in your source directory, and create the file there.
86+
87+
```sh
88+
mkdir src/theme
89+
touch src/theme/_smui-theme.scss
90+
```
91+
92+
## Easy Styling Method
93+
94+
The Easy Styling Method builds styles for all of the SMUI components with your theme into CSS that you can include on your page easily.
95+
96+
Be sure to install the `svelte-material-ui` package.
97+
98+
```sh
99+
npm install --save-dev svelte-material-ui
100+
```
101+
102+
In your package.json file, add this script in the "scripts" section, adjusting the destination file as desired.
103+
104+
```json
105+
"prepare": "sass --no-source-map -I src/theme -I node_modules node_modules/svelte-material-ui/_index.scss build/smui.css",
106+
```
107+
108+
Now run `npm run prepare` to build the CSS file, and include it on your page. Remember to import components with the "/bare" endpoint.
109+
110+
### Dark Mode
111+
112+
For dark mode, you can make a new `_smui-theme.scss` file in a new "dark" directory under your "theme" directory.
113+
114+
```sh
115+
mkdir src/theme/dark
116+
touch src/theme/dark/_smui-theme.scss
117+
```
118+
119+
Replace the sript above with this.
120+
121+
```json
122+
"prepare": "npm run smui-theme-light && npm run smui-theme-dark",
123+
"smui-theme-light": "sass --no-source-map -I src/theme -I node_modules node_modules/svelte-material-ui/_index.scss build/smui.css",
124+
"smui-theme-dark": "sass --no-source-map -I src/theme/dark -I node_modules node_modules/svelte-material-ui/_index.scss build/smui-dark.css",
125+
```
126+
127+
Now run `npm run prepare` to build the CSS files, and include them on your page how you see fit.
128+
129+
## Advanced Styling Method
130+
131+
The advanced method will only build the styles for the SMUI components that you use in your app. The website uses the advanced styling method.
132+
133+
(From here there are [different instructions](SAPPER.md) for Sapper.)
134+
25135
For Rollup, you will need the PostCSS plugin. (Check out the [Rollup template](https://github.com/hperrin/smui-example-rollup).)
26136

27137
```sh
@@ -36,14 +146,7 @@ npm install --save-dev style-loader css-loader sass-loader
36146

37147
If you're not using a bunbler, you can import components from the `bare.js` files, which don't include any styling. Then you can use the `bare.css` files which are precompiled (with the default theme) and packaged with components. Then you can skip the next step, but your [theming options](THEMING.md#theming-the-bare-css) are limited.
38148

39-
## Setting up Sass
40-
41-
You must have a `_smui-theme.scss` file in one of your Sass include paths to compile the Sass. That is where you [set the theme variables](THEMING.md). If it's empty, it will use the default theme values from MDC-Web. You can create a "theme" directory in your source directory, and create the file there.
42-
43-
```sh
44-
mkdir src/theme
45-
touch src/theme/_smui-theme.scss
46-
```
149+
### Setting up Sass
47150

48151
In your bundler's config, you'll need to tell your bundler to compile Sass files.
49152

@@ -111,183 +214,3 @@ module.exports = {
111214
},
112215
};
113216
```
114-
115-
## Material Fonts
116-
117-
If you want the Material Icon, Roboto, and Roboto Mono fonts, be sure to include these stylesheets (or include them from a package).
118-
119-
```html
120-
<!-- Material Icons -->
121-
<link
122-
rel="stylesheet"
123-
href="https://fonts.googleapis.com/icon?family=Material+Icons"
124-
/>
125-
<!-- Roboto -->
126-
<link
127-
rel="stylesheet"
128-
href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700"
129-
/>
130-
<!-- Roboto Mono -->
131-
<link
132-
rel="stylesheet"
133-
href="https://fonts.googleapis.com/css?family=Roboto+Mono"
134-
/>
135-
```
136-
137-
## Using SMUI Components
138-
139-
You're now ready to use SMUI packages. Here's some example code.
140-
141-
```svelte
142-
<Button on:click={() => alert('Clicked!')}>Just a Button</Button>
143-
<Button variant="raised"><Label>Raised Button, Using a Label</Label></Button>
144-
<Button some-arbitrary-prop="placed on the actual button">Button</Button>
145-
146-
<Fab on:click={() => alert('Clicked!')} extended>
147-
<Icon class="material-icons" style="margin-right: 12px;">favorite</Icon>
148-
<Label>Extended FAB</Label>
149-
</Fab>
150-
151-
<Textfield bind:value={superText} label="Super Text">
152-
<HelperText slot="helper"
153-
>What you put in this box will become super!</HelperText
154-
>
155-
</Textfield>
156-
157-
<script>
158-
import Button from '@smui/button';
159-
import Fab from '@smui/fab';
160-
import Textfield from '@smui/textfield';
161-
import HelperText from '@smui/textfield/helper-text';
162-
import { Label, Icon } from '@smui/common';
163-
164-
let superText = '';
165-
</script>
166-
```
167-
168-
# Integration for Sapper
169-
170-
<sub>\* As of 2021-Apr-06, these instructions will now work without a flash of unstyled content!</sub>
171-
172-
Install the following packages as dev dependencies
173-
174-
```sh
175-
npm i -D rollup-plugin-postcss sass
176-
```
177-
178-
Create the `src/theme/_smui-theme.scss` file
179-
180-
```sh
181-
mkdir src/theme
182-
touch src/theme/_smui-theme.scss
183-
```
184-
185-
Update `rollup.config.js` with the following configuration
186-
187-
```js
188-
// ...
189-
// Put this along with the other imports.
190-
import postcss from "rollup-plugin-postcss";
191-
192-
// ...
193-
194-
// Insert the following right before the "export default {" line:
195-
const postcssOptions = (extract) => ({
196-
extensions: ['.scss'],
197-
extract: extract ? 'smui.css' : false,
198-
minimize: true,
199-
use: [
200-
[
201-
'sass',
202-
{
203-
includePaths: ['./src/theme', './node_modules'],
204-
},
205-
],
206-
],
207-
});
208-
209-
// Right after the "svelte" plugin in the "client:" section, paste the following plugin.
210-
postcss(postcssOptions(true)),
211-
212-
// Right after the "svelte" plugin in the "server:" section, paste the following plugin.
213-
postcss(postcssOptions(false)),
214-
215-
// Don't touch the "serviceworker:" section.
216-
// ...
217-
```
218-
219-
In the `template.html` file, in the `<head>` section right after `%sapper.base%`, paste the following
220-
221-
```html
222-
<!-- SMUI Styles -->
223-
<link rel="stylesheet" href="client/smui.css" />
224-
<!-- Material Icons -->
225-
<link
226-
rel="stylesheet"
227-
href="https://fonts.googleapis.com/icon?family=Material+Icons"
228-
/>
229-
<!-- Roboto -->
230-
<link
231-
rel="stylesheet"
232-
href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700"
233-
/>
234-
```
235-
236-
You're now ready to use SMUI packages. Here's some example code.
237-
238-
```svelte
239-
<Button on:click={() => alert('Clicked!')}>Click Me!</Button>
240-
241-
<script>
242-
import Button from '@smui/button';
243-
</script>
244-
```
245-
246-
You can also [set up a dark mode](THEMING.md#dark-mode) in your Sapper app.
247-
248-
# Using SMUI in the Svelte REPL
249-
250-
Check out an [example REPL](https://svelte.dev/repl/aa857c3bb5eb478cbe6b1fd6c6da522a?version=3.37.0).
251-
252-
SMUI components provide "bare.css" and "bare.js" files to use in the REPL. In a `<svelte:head>` section, load from a CDN like UNPKG the CSS files for the fonts, for Material typography, and for each SMUI component you are using:
253-
254-
```svelte
255-
<svelte:head>
256-
<!-- Fonts -->
257-
<link
258-
rel="stylesheet"
259-
href="https://fonts.googleapis.com/icon?family=Material+Icons"
260-
/>
261-
<link
262-
rel="stylesheet"
263-
href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700"
264-
/>
265-
266-
<!-- Material Typography -->
267-
<link
268-
rel="stylesheet"
269-
href="https://unpkg.com/@material/typography@10.0.0/dist/mdc.typography.css"
270-
/>
271-
272-
<!-- SMUI -->
273-
<link rel="stylesheet" href="https://unpkg.com/@smui/button/bare.css" />
274-
<link rel="stylesheet" href="https://unpkg.com/@smui/card/bare.css" />
275-
</svelte:head>
276-
```
277-
278-
Now load the Components, remembering to use the `/bare` script, from within a `<script>` section, and you can use them:
279-
280-
```svelte
281-
<Button on:click={() => alert('See, I told you.')}>This is a button!</Button>
282-
283-
<Card style="width: 360px; margin: 2em auto;">
284-
<Content class="mdc-typography--body2">This is a card!</Content>
285-
</Card>
286-
287-
<script>
288-
import Button from '@smui/button/bare';
289-
import Card, { Content } from '@smui/card/bare';
290-
</script>
291-
```
292-
293-
If you import from `@smui/common`, you don't need the `/bare` portion, since it doesn't have any Sass, so it can use the index file.

‎REPL.md

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Using SMUI in the Svelte REPL
2+
3+
Check out an [example REPL](https://svelte.dev/repl/aa857c3bb5eb478cbe6b1fd6c6da522a?version=3.37.0).
4+
5+
SMUI components provide "bare.css" and "bare.js" files to use in the REPL. In a `<svelte:head>` section, load from a CDN like UNPKG the CSS files for the fonts, for Material typography, and for SMUI:
6+
7+
```svelte
8+
<svelte:head>
9+
<!-- Fonts -->
10+
<link
11+
rel="stylesheet"
12+
href="https://fonts.googleapis.com/icon?family=Material+Icons"
13+
/>
14+
<link
15+
rel="stylesheet"
16+
href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700"
17+
/>
18+
19+
<!-- Material Typography -->
20+
<link
21+
rel="stylesheet"
22+
href="https://unpkg.com/@material/typography@10.0.0/dist/mdc.typography.css"
23+
/>
24+
25+
<!-- SMUI -->
26+
<link rel="stylesheet" href="https://unpkg.com/svelte-material-ui/bare.css" />
27+
</svelte:head>
28+
```
29+
30+
Now load the Components, remembering to use the `/bare` script, from within a `<script>` section, and you can use them:
31+
32+
```svelte
33+
<Button on:click={() => alert('See, I told you.')}>This is a button!</Button>
34+
35+
<Card style="width: 360px; margin: 2em auto;">
36+
<Content class="mdc-typography--body2">This is a card!</Content>
37+
</Card>
38+
39+
<script>
40+
import Button from '@smui/button/bare';
41+
import Card, { Content } from '@smui/card/bare';
42+
</script>
43+
```

0 commit comments

Comments
 (0)