# Ionic Site Shared
This repo is the implementation of Ionic's Design System. The design system iteslf is on [Figma](https://www.figma.com/files/project/1012866/Design-System). More reading on Design Systems and our implementation can be found on [Notion](https://www.notion.so/ionic/DS-4d5b524cc90040a7a4d0b0165346b106).
This repo is based on [stencil-app-starter](https://github.com/ionic-team/stencil-app-starter).
## Documentation
The need for documentation is known. We are [currently working with the capacitor team](https://github.com/ionic-team/stencil/issues/2541) to aid in documenting functional components.
## Components vs Design System
This shared repo contains components that implement our design system. Things like buttons, cards, headings, form fields... It also contains resused components unrelated to our design system. Things like Prismic/Disqus integration tools, additional reading links, ads... Multiple Ionic sites use these components, but they are not part of the formal design system. These components are in `src/components` while Design System components are in `src/ds/components`.
## NPM Link
Until this repo is more mature, it may be useful to work in this repo while actively working on sites that use these components themselves. The [NPM Link](https://docs.npmjs.com/cli/link) command lets you link dependencies in your `package.json` to another project on your computer instead of grabbing it from npm. For example to link this repo with the `capacitor-site` project, assuming this repo is the same parent director as the `capacitor-site` you would run this from the `capacitor-site` root folder:
```bash
# starting out in the root of this project
npm link ../ionic-site-shared
```
## Getting Started
To start building a new web component using Stencil, clone this repo to a new directory:
```bash
git clone https://github.com/ionic-team/stencil-component-starter.git my-component
cd my-component
git remote rm origin
```
and run:
```bash
npm install
npm start
```
To build the component for production, run:
```bash
npm run build
```
To run the unit tests for the components, run:
```bash
npm test
```
Need help? Check out our docs [here](https://stenciljs.com/docs/my-first-component).
## Using this component
### Script tag
- [Publish to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages)
- Put a script tag similar to this `` in the head of your index.html
- Then you can use the element anywhere in your template, JSX, html etc
### Node Modules
- Run `npm install my-component --save`
- Put a script tag similar to this `` in the head of your index.html
- Then you can use the element anywhere in your template, JSX, html etc
### In a stencil-starter app
- Run `npm install my-component --save`
- Add an import to the npm packages `import my-component;`
- Then you can use the element anywhere in your template, JSX, html etc