From 18f0ea4b35ed3f1b34baa45f600d2ade6d93e836 Mon Sep 17 00:00:00 2001 From: Eric Liu Date: Sun, 13 Sep 2020 13:39:36 -0700 Subject: [PATCH] docs: update guidance on examples, usage --- README.md | 106 +++++++++++++++++++++++---- examples/rollup-typescript/README.md | 10 +++ examples/rollup/README.md | 10 +++ examples/routify/README.md | 10 +++ examples/sapper/README.md | 10 +++ examples/svite/README.md | 10 +++ examples/webpack/README.md | 10 +++ 7 files changed, 151 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 279a4487..493b0f1b 100644 --- a/README.md +++ b/README.md @@ -5,38 +5,114 @@ > Svelte implementation of the [Carbon Design System](https://github.com/carbon-design-system) -## Getting Started +## Getting started `carbon-components-svelte` can be installed as a development dependency. ```bash yarn add -D carbon-components-svelte +# OR +npm -i -D carbon-components-svelte ``` ## Usage +The quickest way to start is to use a template from the [examples](examples/) folder. + +Example set-ups demonstrate usage with popular application bundlers and frameworks. They feature a mix of Singe-page Applications (SPA), Server-side rendering (SSR) and statically exported approaches. + +- **[rollup](examples/rollup/)**: SPA bundled using [Rollup](https://github.com/rollup/rollup) +- **[rollup-typescript](examples/rollup-typescript/)**: SPA bundled using Rollup with TypeScript support +- **[routify](examples/routify/)**: SPA + static export using [Routify](https://github.com/roxiness/routify) +- **[sapper](examples/sapper/)**: SSR + static export using [Sapper](https://github.com/sveltejs/sapper) +- **[svite](examples/svite/)**: SPA developed with Svite, bundled with [Rollup](https://github.com/rollup/rollup) +- **[webpack](examples/webpack/)**: SPA bundled with [webpack](https://github.com/webpack/webpack) + +### Scaffolding + +Each example is published in a dedicated branch of the same name. + +Use [degit](https://github.com/Rich-Harris/degit) to scaffold a new project: + +For example, to use the `svite` template, run the following commands: + +```sh +npx degit ibm/carbon-components-svelte#svite svelte-app +cd svelte-app +yarn install +``` + +### Importing components + +Import components from `carbon-components-svelte` in the `script` tag of your Svelte file. + ```html + - - - - - + + Content 1 + Content 2 + Content 3 + ``` +Refer to [COMPONENT_INDEX.md](COMPONENT_INDEX.md) for component documentation. + +### Precompiled CSS StyleSheets + +`carbon-components-svelte` includes precompiled CSS StyleSheets for each Carbon theme: + +- **white.css**: Default Carbon theme (light) +- **g10.css**: Gray 10 theme (light) +- **g90.css**: Gray 90 theme (dark) +- **g100.css**: Gray 100 theme (dark) +- **all.css**: All themes (White, Gray 10, Gray 90, Gray 100) using CSS variables + +Each StyleSheet is [generated](scripts/build-css.js) from the flagship [carbon-components](https://github.com/carbon-design-system/carbon/tree/master/packages/components) library. + +The [examples](examples/) use `all.css` for dynamic theming through CSS variables. + +#### Usage + +##### `svelte-preprocess` + +The easiest way to import a StyleSheet is with [svelte-preprocess](https://github.com/sveltejs/svelte-preprocess). + +```js +const svelteOptions = { + preprocess: require("svelte-preprocess")(), +}; +``` + +```html + + +``` + +##### JavaScript import + +Importing a CSS file in a JavaScript file will require the appropriate file loader(s). + +```js +import "carbon-components-svelte/css/all.css"; +import App from "./App.svelte"; + +const app = new App({ target: document.body }); + +export default app; +``` + +See [webpack.config.js](examples/webpack/webpack.config.js) in [examples/webpack](examples/webpack). + ### TypeScript support -This library ships with TypeScript definitions ([types/index.d.ts](types/index.d.ts)). - -## Components - -Refer to [COMPONENT_INDEX.md](COMPONENT_INDEX.md) for component documentation. +The component library ships with TypeScript definitions ([types/index.d.ts](types/index.d.ts)). ## Contributing diff --git a/examples/rollup-typescript/README.md b/examples/rollup-typescript/README.md index 42aa6e6a..770cbb4d 100644 --- a/examples/rollup-typescript/README.md +++ b/examples/rollup-typescript/README.md @@ -2,6 +2,16 @@ > Example Rollup/TypeScript set-up scaffolded from the official [Svelte template](https://github.com/sveltejs/template). +## Getting started + +Scaffold a new project using [degit](https://github.com/Rich-Harris/degit): + +```sh +npx degit ibm/carbon-components-svelte#rollup-typescript svelte-app +cd svelte-app +yarn install +``` + ## Available scripts ### `yarn dev` diff --git a/examples/rollup/README.md b/examples/rollup/README.md index 058acf2f..a7ff6dd8 100644 --- a/examples/rollup/README.md +++ b/examples/rollup/README.md @@ -2,6 +2,16 @@ > Example set-up using [Rollup](https://github.com/rollup/rollup). +## Getting started + +Scaffold a new project using [degit](https://github.com/Rich-Harris/degit): + +```sh +npx degit ibm/carbon-components-svelte#rollup svelte-app +cd svelte-app +yarn install +``` + ## Available scripts ### `yarn dev` diff --git a/examples/routify/README.md b/examples/routify/README.md index aa891404..21a44e98 100644 --- a/examples/routify/README.md +++ b/examples/routify/README.md @@ -2,6 +2,16 @@ > Example set-up using [Routify](https://github.com/roxiness/routify). +## Getting started + +Scaffold a new project using [degit](https://github.com/Rich-Harris/degit): + +```sh +npx degit ibm/carbon-components-svelte#routify svelte-app +cd svelte-app +yarn install +``` + ## Available scripts ### `yarn dev` diff --git a/examples/sapper/README.md b/examples/sapper/README.md index 5a28fe62..9df1635a 100644 --- a/examples/sapper/README.md +++ b/examples/sapper/README.md @@ -2,6 +2,16 @@ > Example set-up using [Sapper](https://github.com/sveltejs/sapper). +## Getting started + +Scaffold a new project using [degit](https://github.com/Rich-Harris/degit): + +```sh +npx degit ibm/carbon-components-svelte#sapper svelte-app +cd svelte-app +yarn install +``` + ## Available scripts ### `yarn dev` diff --git a/examples/svite/README.md b/examples/svite/README.md index cea6b03a..d8be3e93 100644 --- a/examples/svite/README.md +++ b/examples/svite/README.md @@ -2,6 +2,16 @@ > Example set-up using [svite](https://github.com/dominikg/svite). +## Getting started + +Scaffold a new project using [degit](https://github.com/Rich-Harris/degit): + +```sh +npx degit ibm/carbon-components-svelte#svite svelte-app +cd svelte-app +yarn install +``` + ## Available scripts ### `yarn dev` diff --git a/examples/webpack/README.md b/examples/webpack/README.md index 71bed67e..6c3a2619 100644 --- a/examples/webpack/README.md +++ b/examples/webpack/README.md @@ -2,6 +2,16 @@ > Example set-up using [webpack](https://github.com/webpack/webpack). +## Getting started + +Scaffold a new project using [degit](https://github.com/Rich-Harris/degit): + +```sh +npx degit ibm/carbon-components-svelte#webpack svelte-app +cd svelte-app +yarn install +``` + ## Available scripts ### `yarn dev`