improve documentation (#424)

* chore(deps-dev): pin sveld dependency to v0.3.0

* docs: escape HTML in component prop descriptions

* docs(ordered-list): describe use case for using native styles

#418

* docs: update count for icons, charts packages

* docs(readme): update description, links

README.md

@@ -5,13 +5,25 @@
 ![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.
+Carbon Components Svelte is a [Svelte](https://github.com/sveltejs/svelte) component library that implements the [Carbon Design System](https://github.com/carbon-design-system), an open source design system by IBM.
 
-A design system can facilitate frontend development and prototyping because it encourages reuse, consistency, and extensibility.
+Design systems facilitate design and development through reuse, consistency, and extensibility.
+
+The Carbon Svelte portfolio also includes:
+
+- **[Carbon Icons Svelte](https://github.com/IBM/carbon-icons-svelte)**: 5800+ Carbon icons as Svelte components
+- **[Carbon Pictograms Svelte](https://github.com/IBM/carbon-pictograms-svelte)**: 600+ Carbon pictograms as Svelte components
+- **[Carbon Charts Svelte](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte)**: 16 chart types, powered by d3
 
 ## [Documentation](http://ibm.biz/carbon-svelte)
 
-<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>
+<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>
+
+The [documentation website](http://ibm.biz/carbon-svelte) contains live demos and examples. Other forms of documentation are auto-generated:
+
+- **[Component Index](COMPONENT_INDEX.md)**: Markdown file documenting component props, slots, and events
+- **[TypeScript definitions](types)**: Component TypeScript definitions
+- **[Component API](docs/src/COMPONENT_API.json)**: Component API metadata in JSON format
 
 ## Getting started
 

docs/src/components/ComponentApi.svelte

@@ -138,7 +138,10 @@
               {#if prop.description}
                 {#each prop.description.split('\n') as line}
                   <div class="description">
-                    {@html line.replace(/`(.*?)`/g, '<code>$1</code>')}.
+                    {@html line
+                      .replace(/\</g, '&lt;')
+                      .replace(/\>/g, '&gt;')
+                      .replace(/`(.*?)`/g, '<code>$1</code>')}.
                   </div>
                 {/each}
               {:else}

docs/src/pages/components/OrderedList.svx

@@ -51,6 +51,8 @@ components: ["OrderedList", "ListItem"]
 
 ### Native list styles
 
+Use the `native` attribute to enable default browser list styles. This is useful for large lists (i.e., 1000 or more items) where the list number may overlap with the list item text.
+
 <OrderedList native>
   <ListItem>
     Ordered list level 1

docs/src/pages/index.svelte

@@ -25,7 +25,7 @@
       <Column>
         <h1>Carbon Components Svelte</h1>
         <p class="big-paragraph">
-          carbon-components-svelte is a
+          Carbon Components Svelte is a
           <Link
             inline
             class="big-link"
@@ -44,8 +44,8 @@
           by IBM.
         </p>
         <p>
-          A design system can facilitate frontend development and prototyping
-          because it encourages reuse, consistency, and extensibility.
+          Design systems facilitate design and development through reuse,
+          consistency, and extensibility.
         </p>
       </Column>
     </Row>
@@ -74,8 +74,8 @@
       <Column>
         <h3>Portfolio</h3>
         <p>
-          The broader Carbon Svelte effort extends to the icons, pictograms, and
-          data visualization libraries.
+          The broader Carbon Svelte effort includes libraries for icons,
+          pictograms, and data visualization.
         </p>
       </Column>
     </Row>
@@ -94,7 +94,7 @@
         <TileCard
           borderBottom
           title="Carbon Icons Svelte"
-          subtitle="5000+ icons"
+          subtitle="5800+ icons"
           target="_blank"
           href="https://github.com/IBM/carbon-icons-svelte"
         />
@@ -113,7 +113,7 @@
       <Column xlg="{5}" lg="{8}" md="{4}">
         <TileCard
           title="Carbon Charts Svelte"
-          subtitle="13 chart types, powered by d3"
+          subtitle="16 chart types, powered by d3"
           target="_blank"
           href="https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte"
         />

package.json

@@ -39,7 +39,7 @@
     "rollup": "^2.33.3",
     "rollup-plugin-svelte": "^6.1.1",
     "rollup-plugin-terser": "^7.0.2",
-    "sveld": "^0.3.0",
+    "sveld": "0.3.0",
     "svelte": "^3.29.7",
     "svelte-check": "^1.1.15",
     "svelte-loader": "^2.13.6",

yarn.lock

@@ -2728,7 +2728,7 @@ supports-color@^7.0.0, supports-color@^7.1.0:
   dependencies:
     has-flag "^4.0.0"
 
-sveld@^0.3.0:
+sveld@0.3.0:
   version "0.3.0"
   resolved "https://registry.npmjs.org/sveld/-/sveld-0.3.0.tgz#a1a8c188511a8d5674c72fd8b2987278fae0d062"
   integrity sha512-aEuxRaeN11P+k0DvQ+32lEzRQNzv+dFO5qRC4wSM0p5MW9i6sxgPmnYV3xy5TSzaYXVmSI9JJRSMDd3C1ayw0w==