Skip to content
This repository has been archived by the owner on Jul 12, 2019. It is now read-only.

Commit

Permalink
docs(icons): update icon docs (#453)
Browse files Browse the repository at this point in the history
  • Loading branch information
@joshblack
joshblack authored Mar 27, 2019
1 parent b4d9a87 commit 8001ddc
Show file tree
Hide file tree
Showing 6 changed files with 2,131 additions and 911 deletions.
56 changes: 56 additions & 0 deletions packages/icons/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,62 @@ command instead:
yarn add @carbon/icons
```

## Usage

Icons in Carbon are provided through a variety of packages, often specific for
the framework that will use them. Currently, we support the following packages
for various frameworks:

- [Angular](../icons-angular)
- [React](../icons-react)
- [Vue](../icons-vue)

We also support using icons in Vanilla JavaScript.

In order to use an icon, it may be helpful to reference our [Icon library](https://carbon-elements.netlify.com/icons/examples/preview/) reference page in order to find the specific icon you would like to use.

### Vanilla

Once you've found an icon and you're looking to use it in Vanilla JavaScript,
you can import the icon by writing the following in your JavaScript file:

```js
import IconName from '@carbon/icons/<module-type>/path-to-icon/size';
```

For example, if I wanted to import the 16x16 [`add`](https://carbon-elements.netlify.com/icons/examples/preview/#16%2Fadd) icon, I would write:

```js
import AddIcon from '@carbon/icons/es/add/16';
```

In this case, `es` is used for ES2015 modules (ESM), but one may also use `lib`
for CommonJS or `umd` for UMD modules.

In order to render this to the screen, we'll make use of our
[`icon-helpers`](../packages/icon-helpers) package. This package gives us two
options for rendering our icons: `toString` and `toSVG`. If rendering in
templates, you may want to use the former. If rendering to the DOM, `toSVG` may
be helpful.

In our case, we'll use `toSVG` to create a node in the DOM for the 16x16 `add`
icon:

```js
import { getAttributes, toSVG } from '@carbon/icon-helpers';
import addIcon from '@carbon/icons/es/add/16';

const addIconNode = toSVG({
...addIcon,
attrs: getAttributes(addIcon.attrs),
});
```

### Reference

You can view a full reference of our icons [here](https://carbon-elements.netlify.com/icons/examples/preview/). This is useful for finding
the path information in order to import an icon.

## 🙌 Contributing

We're always looking for contributors to help us fix bugs, build new
Expand Down
1 change: 0 additions & 1 deletion packages/icons/examples/preview/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<h1>Icons ESM Demo</h1>
<div id="root"></div>
<script src="./index.js"></script>
</body>
Expand Down
241 changes: 155 additions & 86 deletions packages/icons/examples/preview/index.js
View file
Original file line number Diff line number Diff line change
@@ -1,105 +1,174 @@
import 'url-polyfill';

import { getAttributes } from '@carbon/icon-helpers';
import Prism from 'prismjs';
import React, { useState } from 'react';
import ReactDOM from 'react-dom';
import meta from '../../meta.json';

const GITHUB_ICON_URL =
'https://github.com/IBM/carbon-elements/tree/master/packages/icons/src/svg';

const MODES = {
expanded: 'expanded',
minimal: 'minimal',
standard: 'standard',
};

function App({ meta }) {
const [mode, setMode] = useState(MODES.standard);
const headers = [
'Name',
'Size',
'Preview',
mode !== MODES.minimal && 'Download',
mode !== MODES.minimal && 'GitHub',
mode !== MODES.minimal && 'Issues',
mode === MODES.expanded && 'Module',
mode === MODES.expanded && 'Relative',
].filter(Boolean);
const headers = ['Name', 'Size', 'Preview', 'GitHub', 'Issues', 'Path'];

return (
<React.Fragment>
<div>
{`Viewing mode: ${mode}`}
<div>
<button onClick={() => setMode(MODES.minimal)}>Minimal</button>
<button onClick={() => setMode(MODES.standard)}>Standard</button>
<button onClick={() => setMode(MODES.expanded)}>Expanded</button>
<div className="bx--grid">
<div className="bx--row">
<div className="bx--col">
<h1>Icons</h1>
</div>
</div>
<div className="bx--row">
<div className="bx--col-sm-4 bx--col-md-6 bx--col-lg-6">
<h2>Usage</h2>
<p>
Icons in Carbon are now provided through a set of packages that
let you use icons in various frameworks. We currently support:
</p>
<ul>
<li>
<a href="//www.npmjs.com/package/@carbon/icons">Vanilla</a>
</li>
<li>
<a href="//www.npmjs.com/package/@carbon/icons-angular">
Angular
</a>
</li>
<li>
<a href="//www.npmjs.com/package/@carbon/icons-react">React</a>
</li>
<li>
<a href="//www.npmjs.com/package/@carbon/icons-vue">Vue</a>
</li>
</ul>
<p>
In order to use icons in alongside these packages, you will need a
couple of pieces of information, namely the icon size and name.
For most product UIs, you will want to use the 16x16 icons.
</p>
<em>
Note: You can share links to specific icons by clicking on the
name of an icon in the table below and sharing that URL with a
collaborator.
</em>
<p>
In order to make use of an icon, you should look at the{' '}
<strong>Path</strong> header. This header will provide you with
the path to import the module in code. In general, the structure
of how to import an icon will follow:
</p>
<pre>
<code
className="language-js"
dangerouslySetInnerHTML={{
__html: Prism.highlight(
`import IconName from '@carbon/icon-<package>/es/<path-to-icon>/<size>';`,
Prism.languages.javascript,
'javascript'
),
}}
/>
</pre>
<p>
For example, if I wanted to import the <a href="#16%2Fadd">add</a>{' '}
icon in React, it would look like:
</p>
<pre>
<code
className="language-js"
dangerouslySetInnerHTML={{
__html: Prism.highlight(
`import IconName from '@carbon/icon-react/es/add/16';`,
Prism.languages.javascript,
'javascript'
),
}}
/>
</pre>
<p>
The path information comes from the table below under the{' '}
<strong>Path</strong> header. If you would like to use CommonJS or
UMD modules, you can replace the path value of <code>es</code>{' '}
with either <code>lib</code> or <code>umd</code> respectively.
</p>
<p>
For specific guidance on how to use these icons, checkout each
package's README to learn more!
</p>
</div>
</div>
</div>
<Table headers={headers}>
{meta.map(info => {
const {
basename,
descriptor,
filename,
moduleName,
original,
outputOptions,
prefix,
size,
} = info;
const { attrs } = descriptor;
const svg = js2svg(descriptor);
const name = original
? prefix.join('/') + '/' + basename + ` (Downsized to ${size})`
: prefix.join('/') + '/' + basename;
const id = window.encodeURIComponent(name);

const download = ['..', '..', 'svg', ...prefix, filename].join('/');
const source = [GITHUB_ICON_URL, ...prefix, filename].join('/');

return (
<tr key={id} id={id}>
<td className="icon-name">
<a href={`#${id}`}>{name}</a>
</td>
<td className="icon-size">{`${attrs.width}x${attrs.height}`}</td>
<td className="icon-preview-container">
<div className="icon-preview">{svg}</div>
</td>
{!(mode === MODES.minimal) && (
<React.Fragment>
<td>
<a href={download} download>
Download
</a>
</td>
<td>
<a href={source} rel="noopener noreferrer" target="_blank">
Source
</a>
</td>
<td>
<a
href={getBugTemplate(info, source)}
rel="noopener noreferrer"
target="_blank">
Template
</a>
</td>
</React.Fragment>
)}
{mode === MODES.expanded && (
<React.Fragment>
<td>{moduleName}</td>
<td>{outputOptions.file}</td>
</React.Fragment>
)}
</tr>
);
})}
</Table>
<section>
<div className="bx--grid">
<div className="bx--row">
<div className="bx--col">
<Table headers={headers}>
{meta.map(info => {
const {
basename,
descriptor,
filename,
moduleName,
original,
outputOptions,
prefix,
size,
} = info;
const { attrs } = descriptor;
const svg = js2svg(descriptor);
const name = original
? prefix.join('/') +
'/' +
basename +
` (Downsized to ${size})`
: prefix.join('/') + '/' + basename;
const id = window.encodeURIComponent(name);
const source = [GITHUB_ICON_URL, ...prefix, filename].join(
'/'
);

return (
<tr key={id} id={id}>
<td className="icon-name">
<a href={`#${id}`}>{name}</a>
</td>
<td className="icon-size">{`${attrs.width}x${
attrs.height
}`}</td>
<td className="icon-preview-container">
<div className="icon-preview">{svg}</div>
</td>
<td>
<a
href={source}
rel="noopener noreferrer"
target="_blank">
Source
</a>
</td>
<td>
<a
href={getBugTemplate(info, source)}
rel="noopener noreferrer"
target="_blank">
Create
</a>
</td>
<td>
<div className="icon-code-snippets">
<code>{outputOptions.file}</code>
</div>
</td>
</tr>
);
})}
</Table>
</div>
</div>
</div>
</section>
</React.Fragment>
);
}
Expand Down
15 changes: 8 additions & 7 deletions packages/icons/examples/preview/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,15 @@
"develop": "parcel index.html --no-cache"
},
"devDependencies": {
"@babel/core": "^7.1.0",
"@babel/plugin-transform-react-jsx": "^7.0.0",
"@babel/preset-env": "^7.1.0",
"parcel-bundler": "^1.10.0-beta.1"
"@babel/core": "^7.4.0",
"@babel/plugin-transform-react-jsx": "^7.3.0",
"@babel/preset-env": "^7.4.2",
"parcel-bundler": "^1.12.3"
},
"dependencies": {
"react": "^16.7.0-alpha.2",
"react-dom": "^16.7.0-alpha.2",
"url-polyfill": "^1.1.3"
"prismjs": "^1.16.0",
"react": "^16.8.5",
"react-dom": "^16.8.5",
"url-polyfill": "^1.1.5"
}
}
Loading

0 comments on commit 8001ddc

Please sign in to comment.