From 13bd64e5c9d5de84e578d947760b295177b8c54f Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Sun, 18 Jul 2021 05:39:35 -0700
Subject: [PATCH] Improve docs (#756)

* docs: remove Theme from new components

* docs: add styling instructions

* docs: add styling instructions

* docs: update copy
---
 README.md                                   |  19 ++-
 docs/src/components/Footer.svelte           |   2 +-
 docs/src/pages/_layout.svelte               |   2 +-
 docs/src/pages/components/Button.svx        |   8 +-
 docs/src/pages/components/OrderedList.svx   |   4 +-
 docs/src/pages/components/UnorderedList.svx |   2 +-
 docs/src/pages/index.svelte                 | 143 ++++++++++++++++++--
 7 files changed, 157 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 278dfde9..17967c57 100644
--- a/README.md
+++ b/README.md
@@ -13,27 +13,34 @@ The Carbon Svelte portfolio also includes:
 
 - **[Carbon Icons Svelte](https://github.com/IBM/carbon-icons-svelte)**: 6000+ Carbon icons as Svelte components
 - **[Carbon Pictograms Svelte](https://github.com/IBM/carbon-pictograms-svelte)**: 700+ Carbon pictograms as Svelte components
-- **[Carbon Charts Svelte](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte)**: 20 chart types, powered by d3
+- **[Carbon Charts Svelte](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte)**: 20+ charts, powered by d3
+- **[Carbon Preprocess Svelte](https://github.com/IBM/carbon-preprocess-svelte)**: Collection of Svelte preprocessors for Carbon
 
 ## [Documentation](http://ibm.biz/carbon-svelte)
 
-<a href="https://www.vercel.com?utm_source=carbon-components-svelte&utm_campaign=oss" target="_blank"><img height="34px" src="./docs/public/powered-by-vercel.svg" alt="Deploys by Vercel" /></a>
+<a href="https://www.vercel.com?utm_source=carbon-components-svelte&utm_campaign=oss" target="_blank"><img height="40px" src="./docs/public/powered-by-vercel.svg" alt="Deploys by Vercel" /></a>
 
 The [documentation website](http://ibm.biz/carbon-svelte) contains live demos and examples.
 
 Other forms of documentation are auto-generated:
 
 - **[TypeScript definitions](types)**: Component TypeScript definitions
-- **[Component Index](COMPONENT_INDEX.md)**: Markdown file documenting component props, slots, and events
-- **[Component API](docs/src/COMPONENT_API.json)**: Component API metadata in JSON format
+- **[Component Index](COMPONENT_INDEX.md)**: Component API in Markdown format
+- **[Component API](docs/src/COMPONENT_API.json)**: Component API in JSON format
 
-## Getting started
+## Installation
 
 Install `carbon-components-svelte` as a development dependency.
 
+**Yarn**
+
 ```sh
 yarn add -D carbon-components-svelte
-# OR
+```
+
+**NPM**
+
+```sh
 npm i -D carbon-components-svelte
 ```
 
diff --git a/docs/src/components/Footer.svelte b/docs/src/components/Footer.svelte
index b2b8e391..4acac22c 100644
--- a/docs/src/components/Footer.svelte
+++ b/docs/src/components/Footer.svelte
@@ -11,7 +11,7 @@
           target="_blank"
         >
           <img
-            height="36px"
+            height="40px"
             src="/powered-by-vercel.svg"
             alt="Deploys by Vercel"
           />
diff --git a/docs/src/pages/_layout.svelte b/docs/src/pages/_layout.svelte
index b5743fde..2324a182 100644
--- a/docs/src/pages/_layout.svelte
+++ b/docs/src/pages/_layout.svelte
@@ -20,7 +20,7 @@
   import Footer from "../components/Footer.svelte";
 
   const deprecated = ["ToggleSmall", "Icon"];
-  const new_components = ["Theme"];
+  const new_components = [];
 
   let isOpen = false;
   let isSideNavOpen = true;
diff --git a/docs/src/pages/components/Button.svx b/docs/src/pages/components/Button.svx
index 2b2f0f45..c0b06446 100644
--- a/docs/src/pages/components/Button.svx
+++ b/docs/src/pages/components/Button.svx
@@ -1,5 +1,5 @@
 <script>
-  import { Button } from "carbon-components-svelte";
+  import { InlineNotification, Button } from "carbon-components-svelte";
   import Add16 from "carbon-icons-svelte/lib/Add16";
   import TrashCan16 from "carbon-icons-svelte/lib/TrashCan16";
   import TextBold16 from "carbon-icons-svelte/lib/TextBold16";
@@ -118,7 +118,11 @@ If an `href` value is specified, the component will render an [anchor element](h
 
 Set `expressive` to `true` to use Carbon's expressive typesetting.
 
-Note: the expressive styles only apply to the default, `"lg"`, and `"xl"` button sizes.
+<InlineNotification svx-ignore title="Note:" kind="info" hideCloseButton>
+  <div class="body-short-01">
+    Expressive styles only work with the default, `"lg"`, and `"xl"` button sizes.
+  </div>
+</InlineNotification>
 
 <Button expressive size="xl">Primary</Button>
 <Button expressive size="xl" kind="secondary">Secondary</Button>
diff --git a/docs/src/pages/components/OrderedList.svx b/docs/src/pages/components/OrderedList.svx
index ef659907..9cc58175 100644
--- a/docs/src/pages/components/OrderedList.svx
+++ b/docs/src/pages/components/OrderedList.svx
@@ -9,8 +9,8 @@ components: ["OrderedList", "ListItem"]
 
 <InlineNotification svx-ignore title="Tip:" kind="info" hideCloseButton>
   <div class="body-short-01">
-    To render data formatted as a tree structure, use the <Link href="/components/RecursiveList#ordered">RecursiveList</Link> component.
-  </div>
+    Consider using the <Link href="/components/RecursiveList#ordered">RecursiveList</Link> component for rendering tree structured data.
+   </div>
 </InlineNotification>
 
 ### Default
diff --git a/docs/src/pages/components/UnorderedList.svx b/docs/src/pages/components/UnorderedList.svx
index 118f37da..2eea512e 100644
--- a/docs/src/pages/components/UnorderedList.svx
+++ b/docs/src/pages/components/UnorderedList.svx
@@ -9,7 +9,7 @@ components: ["UnorderedList", "ListItem"]
 
 <InlineNotification svx-ignore title="Tip:" kind="info" hideCloseButton>
   <div class="body-short-01">
-    To render data formatted as a tree structure, use the <Link href="/components/RecursiveList#unordered">RecursiveList</Link> component.
+   Consider using the <Link href="/components/RecursiveList#unordered">RecursiveList</Link> component for rendering tree structured data.
   </div>
 </InlineNotification>
 
diff --git a/docs/src/pages/index.svelte b/docs/src/pages/index.svelte
index 31365bbe..0ce0eaa3 100644
--- a/docs/src/pages/index.svelte
+++ b/docs/src/pages/index.svelte
@@ -6,8 +6,15 @@
     Column,
     CodeSnippet,
     Link,
+    Tabs,
+    Tab,
+    TabContent,
+    OutboundLink,
+    RadioButtonGroup,
+    RadioButton,
   } from "carbon-components-svelte";
   import TileCard from "../components/TileCard.svelte";
+  import { theme } from "../store";
   import { metatags } from "@sveltech/routify";
 
   metatags.title = "Carbon Components Svelte";
@@ -16,6 +23,23 @@
 
   const installYarn = "yarn add -D carbon-components-svelte";
   const installNpm = "npm i -D carbon-components-svelte";
+  const themes = {
+    white: "White",
+    g10: "Gray 10",
+    g80: "Gray 80",
+    g90: "Gray 90",
+    g100: "Gray 100",
+  };
+  $: cssImport = `import "carbon-components-svelte/css/${$theme}.css";`;
+  $: cssCdn = `<!DOCTYPE html>
+<html>
+  <head>
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/carbon-components-svelte/css/${$theme}.css"
+    />
+  </head>
+</html>`;
 </script>
 
 <Content>
@@ -32,15 +56,14 @@
           >
             Svelte
           </Link>
-          component library that implements the Carbon Design System, an
+          component library that implements the
           <Link
             inline
             class="big-link"
             href="https://www.carbondesignsystem.com/"
           >
-            open source design system
-          </Link>
-          by IBM.
+            Carbon Design System
+          </Link>, an open source design system by IBM.
         </p>
         <p>
           Design systems facilitate design and development through reuse,
@@ -50,23 +73,117 @@
     </Row>
     <Row style="margin-bottom: var(--cds-layout-02)">
       <Column>
-        <h3>Install</h3>
-        <h4>Installing with yarn:</h4>
+        <h3>Installation</h3>
+        <p>
+          Install
+          <code>carbon-components-svelte</code>
+          as a development dependency in your project.
+        </p>
+        <h4>Using Yarn:</h4>
         <Row noGutter>
           <CodeSnippet code="{installYarn}" />
         </Row>
-        <h4>Using npm:</h4>
+        <h4>Using NPM:</h4>
         <Row noGutter>
           <CodeSnippet code="{installNpm}" />
         </Row>
       </Column>
     </Row>
+    <Row style="margin-bottom: var(--cds-layout-05)">
+      <Column>
+        <h3>Styling</h3>
+        <p>
+          Before importing components, you will need to first apply Carbon
+          component styles. The Carbon Design System supports five themes (2
+          light, 3 dark).
+        </p>
+        <RadioButtonGroup
+          style="margin-top: var(--cds-spacing-08)"
+          legendText="Carbon themes"
+          bind:selected="{$theme}"
+        >
+          {#each ["white", "g10", "g80", "g90", "g100"] as value}
+            <RadioButton labelText="{themes[value]}" value="{value}" />
+          {/each}
+        </RadioButtonGroup>
+      </Column>
+    </Row>
+
+    <Row style="margin-bottom: var(--cds-layout-02)">
+      <Column xlg="{10}" noGutter>
+        <Tabs>
+          <Tab label="CSS StyleSheet" />
+          <Tab label="CDN" />
+          <Tab label="SCSS" />
+          <div slot="content">
+            <TabContent>
+              <p>
+                This library ships with six pre-compiled CSS StyleSheets built
+                from
+                <OutboundLink
+                  inline
+                  size="lg"
+                  href="https://github.com/carbon-design-system/carbon/tree/main/packages/components"
+                >
+                  carbon-components
+                </OutboundLink>.
+              </p>
+              <Row padding noGutter>
+                <Column>
+                  <p>
+                    <CodeSnippet type="single" code="{cssImport}" />
+                  </p>
+                </Column>
+              </Row>
+            </TabContent>
+            <TabContent>
+              <p>
+                An alternative to loading styles is to link an external
+                StyleSheet from a Content Delivery Networks (CDN) like
+                <OutboundLink inline size="lg" href="https://unpkg.com/">
+                  unpkg.com
+                </OutboundLink>.
+              </p>
+              <p>
+                This is best suited for rapid prototyping or if your set-up does
+                not use a CSS loader.
+              </p>
+              <Row padding noGutter>
+                <Column>
+                  <p>
+                    <CodeSnippet type="multi" code="{cssCdn}" />
+                  </p>
+                </Column>
+              </Row>
+            </TabContent>
+            <TabContent>
+              <p>
+                The most performant method to load styles is to import SCSS
+                directly from <code>carbon-components</code>. Although it
+                requires more set up, you can reduce the size of the bundle CSS
+                by importing individual component styles instead of a
+                pre-compiled CSS StyleSheet.
+              </p>
+              <p>
+                Refer to the <OutboundLink
+                  inline
+                  size="lg"
+                  href="https://github.com/carbon-design-system/carbon/blob/main/docs/guides/sass.md"
+                  >official Carbon guide on SASS</OutboundLink
+                > for documentation.
+              </p>
+            </TabContent>
+          </div>
+        </Tabs>
+      </Column>
+    </Row>
+
     <Row>
       <Column>
         <h3>Portfolio</h3>
         <p>
-          The broader Carbon Svelte effort includes libraries for icons,
-          pictograms, and data visualization.
+          The Carbon Svelte portfolio includes packages for icons, pictograms,
+          and data visualization.
         </p>
       </Column>
     </Row>
@@ -106,7 +223,7 @@
         <TileCard
           borderBottom
           title="Carbon Charts Svelte"
-          subtitle="20 chart types, powered by d3"
+          subtitle="20+ charts, powered by d3"
           target="_blank"
           href="https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte"
         />
@@ -124,3 +241,9 @@
     </Row>
   </Grid>
 </Content>
+
+<style>
+  p {
+    margin-bottom: var(--cds-spacing-05);
+  }
+</style>