mirror of
https://github.com/carbon-design-system/carbon-components-svelte.git
synced 2025-09-14 18:01:06 +00:00
Improve docs (#756)
* docs: remove Theme from new components * docs: add styling instructions * docs: add styling instructions * docs: update copy
This commit is contained in:
Eric Liu
GitHub
parent
d01995e11e
commit
13bd64e5c9
7 changed files with 157 additions and 23 deletions
19
README.md
19
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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
target="_blank"
|
||||
>
|
||||
<img
|
||||
height="36px"
|
||||
height="40px"
|
||||
src="/powered-by-vercel.svg"
|
||||
alt="Deploys by Vercel"
|
||||
/>
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue