npm package: @sul/ui
Description: SUL UI is designed to provide a solid foundation for websites and applications. With a primary goal to standardize components across projects.
Author: Stiff Upper Lip LLC | andrew@sul.io
Latest version: 1.0.0-alpha.1

# SUL UI

SUL UI is designed to provide a solid foundation for websites and applications.
With a primary goal to standardize components across projects.

SUL UI is an extension of [theme-ui](https://theme-ui.com/) and is based on a
[theme specification](https://system-ui.com/theme).

Core Principles:

- Each component is simple and intuitive
- Each component is 100% tested
- Each component is responsive
- Each component is well defined with design, ux and development documentation

## Install

```sh
npm install @sul/ui
```

## Usage

SUL UI is designed to be simple. Each component is built to work in isolation
and self-supporting.

### Quick Start

```javascript
import React from 'react'
import ReactDOM from 'react-dom'
import { ThemeProvider, Button } from '@sul/ui'

import theme from './theme'

const App = () => (
  <ThemeProvider theme={theme}>
    <Button>Hello World</Button>
  </ThemeProvider>
)

ReactDOM.render(<App />, document.querySelector('#app'))
```

To provide the theme in context, wrap your application with the `ThemeProvider`
component and pass in a custom `theme` object.

The `theme` object follows the system-ui
[theme specification](https://system-ui.com/theme).

```javascript
// example theme.js
export default {
  fonts: {
    body:
      'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif',
    heading: '"Avenir Next", sans-serif',
    monospace: 'Menlo, monospace',
  },
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#33e',
  },
}
```

## Component Status

**Current version: Pre-release 1.0.0-alpha.1**

SUL UI is a living, breathing system that will grow with our needs. Here you'll
find the ongoing status of our system. Stable signifies the component is ready
to be used in a production environment. Experimental components, designs and
other resources are presented for testing and feedback. They're not intended for
production use.

### Elements

Provide basic building blocks. These are typically low-level presentational
components.

| Component   | Stable   | Experimental |
| ----------- | -------- | ------------ |
| AspectRatio | &#10003; | -            |
| Button      | &#10003; | -            |
| Divider     | &#10003; | -            |
| Form        | &#10003; | -            |
| Heading     | &#10003; | -            |
| Icon        | &#10003; | -            |
| Image       | &#10003; | -            |
| Link        | &#10003; | -            |
| Text        | &#10003; | -            |

### Layout

Provide or manipulate structure in some way.

| Component | Stable   | Experimental |
| --------- | -------- | ------------ |
| Article   | &#10003; | -            |
| Box       | &#10003; | -            |
| Card      | &#10003; | -            |
| Container | &#10003; | -            |
| Flex      | &#10003; | -            |
| Grid      | &#10003; | -            |
| Section   | &#10003; | -            |

### Modules

Modules are lower-level functional utilities or components. Typically these are
extended and used in presentational level components.

| Component | Stable   | Experimental |
| --------- | -------- | ------------ |
| Layer     | &#10003; | -            |
| Popover   | -        | &#10003;     |

### Patterns

Provide advanced layout and additional functionality. These components are
typically more opinionated on structure.

| Component | Stable   | Experimental |
| --------- | -------- | ------------ |
| Copyright | &#10003; | -            |
| MailTo    | &#10003; | -            |
| Modal     | &#10003; | -            |

### Utilities

| Utility  | Stable   | Experimental |
| -------- | -------- | ------------ |
| keyboard | &#10003; | -            |

### Tag Descriptions

| Tag       | Name         | Definition                                                                                                                              |
| --------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| &#10003;  | Ready        | The component is design and dev ready                                                                                                   |
| &#x26A0;  | Under Review | Indicates that a component’s design, code, or usage is being re-examined or created.                                                    |
| X         | Deprecated   | Deprecated components have either been completely replaced by new components or are no longer being supported in the component library. |
| (New)     |              | This component is brand new to SUL UI                                                                                                   |
| (Updated) |              | Applied only to existing components after they have been under review, tweaked, and re-released to the design system.                   |

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available,
see the [tags on this repository](https://github.com/sulweb/sul-ui/tags).

Please read
[CHANGELOG.md](https://github.com/sulweb/sul-ui/blob/master/CHANGELOG.md) for
detailed changes to this project.

## Authors

- **Andrew Smith** - _Initial work_ -
  [Stiff Upper Lip](https://github.com/sulweb)

## License

This project is licensed under the MIT License - see the
[LICENSE.md](https://github.com/sulweb/sul-ui/blob/master/LICENSE.md) file for
details.