Revise docs (#416)

* chore: add license badge to README

* perf(docs): ignore node_modules in markdown preprocessor

* docs: remove tabs for install commands on homepage

* docs(button-set): improve copy

* docs(button): improve usage for icon-only, link buttons

* docs: various copy improvements

README.md

@@ -1,6 +1,8 @@
 # carbon-components-svelte
 
 [![NPM][npm]][npm-url]
+![GitHub](https://img.shields.io/github/license/ibm/carbon-components-svelte?color=262626&style=for-the-badge)
+![npm downloads to date](https://img.shields.io/npm/dt/carbon-components-svelte?color=262626&style=for-the-badge)
 [![Build][build]][build-badge]
 
 carbon-components-svelte is a Svelte component library that implements the [Carbon Design System](https://github.com/carbon-design-system), an open source design system by IBM.
@@ -9,7 +11,7 @@ A design system can facilitate frontend development and prototyping because it e
 
 ## [Documentation](http://ibm.biz/carbon-svelte)
 
-<a href="https://www.vercel.com?utm_source=carbon-components-svelte&utm_campaign=oss" target="_blank"><img height="30px" 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="32px" src="./docs/public/powered-by-vercel.svg" alt="Deploys by Vercel" /></a>
 
 ## Getting started
 
@@ -132,7 +134,7 @@ Refer to the [Contributing guidelines](CONTRIBUTING.md).
 
 [Apache 2.0](LICENSE)
 
-[npm]: https://img.shields.io/npm/v/carbon-components-svelte.svg?color=%23161616
+[npm]: https://img.shields.io/npm/v/carbon-components-svelte.svg?color=262626&style=for-the-badge
 [npm-url]: https://npmjs.com/package/carbon-components-svelte
-[build]: https://travis-ci.com/ibm/carbon-components-svelte.svg?branch=master&color=%230f62fe
+[build]: https://img.shields.io/travis/com/ibm/carbon-components-svelte?color=24a148&style=for-the-badge
 [build-badge]: https://travis-ci.com/ibm/carbon-components-svelte

docs/src/components/ComponentApi.svelte

@@ -64,7 +64,7 @@
 
 <p style="margin-bottom: var(--cds-layout-02)">
   Component source code:
-  <Link size="lg" href="{source}" target="_blank">
+  <Link inline size="lg" href="{source}" target="_blank">
     {component.filePath}
     <Launch16 />
   </Link>

docs/src/components/Footer.svelte

@@ -16,7 +16,11 @@
           href="https://www.vercel.com?utm_source=carbon-components-svelte&utm_campaign=oss"
           target="_blank"
         >
-          <img src="/powered-by-vercel.svg" alt="Deploys by Vercel" />
+          <img
+            height="36px"
+            src="/powered-by-vercel.svg"
+            alt="Deploys by Vercel"
+          />
         </Link>
       </Column>
     </Row>

docs/src/layouts/ComponentLayout.svelte

@@ -171,7 +171,7 @@
         <slot />
         <h2 id="component-api">Component API</h2>
         <p>
-          Component documentation is
+          API documentation is
           <Link inline href="https://github.com/IBM/sveld" target="_blank">
             auto-generated by sveld.
           </Link>

docs/src/pages/components/Button.svx

@@ -42,10 +42,18 @@ description: High-level description
 
 ### Icon-only button
 
-<Button icon={Add16} hasIconOnly tooltipPosition="bottom" tooltipAlignment="center" iconDescription="Tooltip text" />
+Set `hasIconOnly` to `true` to use the icon-only button variant.
+
+**Note:** you must provide an `iconDescription` for the button tooltip.
+
+The tooltip position and alignment can be controlled by the `tooltipPosition`, `tooltipAlignment` props, respectively.
+
+<Button hasIconOnly tooltipPosition="bottom" tooltipAlignment="center" iconDescription="Tooltip text" icon={Add16} />
 
 ### Link button
 
+If an `href` value is specified, the component will render an [anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) with a "button" role.
+
 <Button href="#">Link button</Button>
 
 ### Custom element

docs/src/pages/components/ButtonSet.svx

@@ -8,7 +8,9 @@ source: Button/ButtonSet.svelte
   import Preview from "../../components/Preview.svelte";
 </script>
 
-### Default (juxtaposed)
+### Default
+
+Buttons in a button set are juxtaposed by default.
 
 <ButtonSet>
   <Button kind="secondary">Cancel</Button>
@@ -17,6 +19,8 @@ source: Button/ButtonSet.svelte
 
 ### Stacked
 
+Set `stacked` to `true` to use the stacked variant.
+
 <ButtonSet stacked>
   <Button icon={Login16}>Log in</Button>
   <Button kind="ghost">Sign up</Button>

docs/src/pages/components/Search.svx

@@ -5,7 +5,7 @@
 
 ### Default
 
-The `Search` component is extra-large by default. There are [large](#large-size) and [small](#small-size) size variants.
+The `Search` component size is extra-large by default. There are [large](#large-size) and [small](#small-size) size variants.
 
 <Search />
 

docs/src/pages/index.svelte

@@ -6,9 +6,6 @@
     Column,
     CodeSnippet,
     Link,
-    Tabs,
-    Tab,
-    TabContent,
   } from "carbon-components-svelte";
   import TileCard from "../components/TileCard.svelte";
   import { metatags } from "@sveltech/routify";
@@ -28,8 +25,7 @@
       <Column>
         <h1>Carbon Components Svelte</h1>
         <p class="big-paragraph">
-          <code>carbon-components-svelte</code>
+          carbon-components-svelte is a
-          is a
           <Link
             inline
             class="big-link"
@@ -51,36 +47,27 @@
           A design system can facilitate frontend development and prototyping
           because it encourages reuse, consistency, and extensibility.
         </p>
-        <h3>Install</h3>
       </Column>
     </Row>
-    <Row noGutter style="margin-bottom: var(--cds-layout-02)">
+    <Row style="margin-bottom: var(--cds-layout-02)">
       <Column>
-        <Tabs>
+        <h3>Install</h3>
-          <Tab label="Yarn" />
+        <h4>Installing with yarn:</h4>
-          <Tab label="npm" />
+        <CodeSnippet
-          <div
+          code="{installYarn}"
-            slot="content"
+          on:click="{() => {
-            style="margin-left: calc(-1 * var(--cds-spacing-05)); margin-right: calc(-1 * var(--cds-spacing-05));"
+            copy(installYarn);
-          >
+          }}"
-            <TabContent>
+        />
-              <CodeSnippet
+
-                code="{installYarn}"
+        <h4>Using npm:</h4>
-                on:click="{() => {
+
-                  copy(installYarn);
+        <CodeSnippet
-                }}"
+          code="{installNpm}"
-              />
+          on:click="{() => {
-            </TabContent>
+            copy(installNpm);
-            <TabContent>
+          }}"
-              <CodeSnippet
+        />
-                code="{installNpm}"
-                on:click="{() => {
-                  copy(installNpm);
-                }}"
-              />
-            </TabContent>
-          </div>
-        </Tabs>
       </Column>
     </Row>
     <Row>

docs/svelte.config.js

@@ -127,6 +127,7 @@ module.exports = {
   extensions: [".svelte", ".svx"],
   preprocess: [
     require("svelte-preprocess")({
+      typescript: false,
       replace: [
         ["process.env.VERSION", JSON.stringify(pkg.version)],
         ["process.env.NODE_ENV", JSON.stringify(NODE_ENV)],
@@ -148,6 +149,7 @@ module.exports = {
     }),
     {
       markup({ content, filename }) {
+        if (/node_modules/.test(filename)) return null;
         if (filename.endsWith(".svx") && filename.match(/pages\/(recipes)/)) {
           const toc = [];