chore: adding more context to readmes (#154)

* chore: adding more context to readmes

* chore: adding layout blurb

LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2021 project44, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,34 +1,78 @@
-# Manifest Design System
+<div align="center">
+  <a href="https://www.manifestdesignsystem.com"><img src="apps/docs/public/images/logo.png" width="200" height="200" /></a>
+</div>
 
-> Manifesting Project 44 experiences through design.
+<h1 align="center">Manifest Design System</h1>
 
+> Manifest Design System is the open source implementation of the project44 design language, used to
+> build consistent, accessible and delightful products at project44. While the design language is
+> closed source, the technology is open and contributions are welcomed and encouraged.
+
+<div align="center">
+
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@project44-manifest/react/latest.svg)](https://bundlephobia.com/result?p=@project44-manifest/react@latest)
 [![LICENSE](https://img.shields.io/apm/l/atomic-design-ui.svg?style=flat)](https://github.com/project44/manifest/blob/main/LICENSE)
+[![npm latest package](https://img.shields.io/npm/v/@project44-manifest/react/latest.svg?label=@project44-manifest/react)](https://www.npmjs.com/package/@project44-manifest/react)
 [![CI](https://github.com/project44/manifest/actions/workflows/ci.yml/badge.svg)](https://github.com/project44/manifest/actions/workflows/ci.yml)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
 
-## Getting Started
+</div>
+
+## Documentation
 
-For detailed installation and usage guidelines, please see our
+For usage guidelines and full documentation please visit our
 [documentation website](https://www.manifestdesignsystem.com).
 
-| Package                               | Version                                                                                                                                                                  |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **@project44-manifest/design-tokens** | [![badge](https://img.shields.io/npm/v/@project44-manifest/design-tokens.svg?style=flat-square-square)](https://www.npmjs.com/package/@project44-manifest/design-tokens) |
-| **@project44-manifest/react**         | [![badge](https://img.shields.io/npm/v/@project44-manifest/react.svg?style=flat-square-square)](https://www.npmjs.com/package/@project44-manifest/react)                 |
-| **@project44-manifest/system**        | [![badge](https://img.shields.io/npm/v/@project44-manifest/system.svg?style=flat-square-square)](https://www.npmjs.com/package/@project44-manifest/system)               |
-| **@project44-manifest/theme**         | [![badge](https://img.shields.io/npm/v/@project44-manifest/theme.svg?style=flat-square-square)](https://www.npmjs.com/package/@project44-manifest/theme)                 |
+## Getting Started
+
+Just getting started? Check out [`@project44-manifest/react`](./packages/react).
 
-## Documentation
+Need something more specific? You may want to check out these packages:
+
+| Package name                                | Description                                    |
+| ------------------------------------------- | ---------------------------------------------- |
+| [`design tokens`](./packages/design-tokens) | The design tokens for Manifest Design System.  |
+| [`react`](./packages/react)                 | React components, patterns and styling engine. |
+| [`theme`](./packages/theme)                 | A theme implementing our design tokens.        |
+
+Manifest uses [Turborepo](https://turbo.build/repo) as it's build system, to get started working
+with repo install the dependencies and build the packages:
+
+```sh
+yarn && yarn build
+```
+
+To run a command for a single workspace use the `--filter` tag provided by turbo.
+
+```sh
+yarn turbo run --filter=@project44-manifest/react
+```
+
+Some common commands includes:
+
+| Command                                                     | Purpose                                                    |
+| ----------------------------------------------------------- | ---------------------------------------------------------- |
+| `yarn turbo run dev --filter=@project44-manifest/storybook` | Starts a development server for the react components.      |
+| `yarn turbo run dev --filter=@project44-manifest/doc`       | Starts a development server for the documentation website. |
+
+The following commands will run in all packages:
 
-- [Documentation Website](https://www.manifestdesignsystem.com)
-- [Contributing](./.github/CONTRIBUTING.md)
-- [Code of conduct](./.github/CODE_OF_CONDUCT.md)
+| Command          | Purpose                                                              |
+| ---------------- | -------------------------------------------------------------------- |
+| `yarn build`     | Builds all the packages, tools and apps in the repo.                 |
+| `yarn clean`     | Removes build assets and caches.                                     |
+| `yarn coverage`  | Generate test coverage reports for each package.                     |
+| `yarn dev`       | Runs development servers and watch for code changes within packages. |
+| `yarn format`    | Check code formatting.                                               |
+| `yarn lint`      | Run linting.                                                         |
+| `yarn test`      | Run unit tests.                                                      |
+| `yarn typecheck` | Validate TypeScript types.                                           |
 
-## 🙌 Contributing
+## Contributing
 
 Contributions are always welcome!! Please review our [Contribution Guide](/.github/CONTRIBUTING.md)
 to get started.
 
 ## License
 
-[MIT](/LICENSE)
+Licensed under the [MIT](/LICENSE).

package.json

@@ -6,6 +6,7 @@
   "workspaces": [
     "apps/*",
     "packages/*",
+    "packages/react-components/*",
     "tools/*"
   ],
   "scripts": {

packages/design-tokens/README.md

@@ -3,7 +3,7 @@
 Design Tokens for Manifest Design System, project44's design system.
 
 For a full list of tokens, please see the
-[documentation website](https://www.manifestdesignsystem.com)
+[documentation website](https://www.manifestdesignsystem.com/docs/tokens)
 
 ## Installation
 
@@ -30,3 +30,12 @@ import { tokens } from '@project44-manifest/design-tokens';
 
 console.log(tokens.color.palette.blue[50]);
 ```
+
+## Contributing
+
+Contributions are always welcome!! Please review our [Contribution Guide](/.github/CONTRIBUTING.md)
+to get started.
+
+## License
+
+Licensed under the [MIT](/LICENSE).

packages/react/README.md

@@ -0,0 +1,134 @@
+# @project44-manifest/react
+
+> A react library consisting of components, patterns and a styling engine that implement the design
+> principles of the [Manifest Design System](https://www.manifestdesignsystem.com) by project44.
+
+## Installation
+
+```bash
+yarn add @project44-manifest/react react react-dom
+```
+
+## Usage
+
+The `@project44-manifest/react` library includes everything you need to build experiences leveraging
+the Manifest Design System.
+
+To start using the library start by wrapper you application with the `Provider`.
+
+```tsx
+import { Provider } from '@project44-manifest/react';
+
+function MyApp({ children }) {
+  return <Provider>{children}</Provider>;
+}
+```
+
+This provider will initialize our `SSRProvider`, which ensures that our auto-generated id's are
+consistent between the server and client. It also initializes the `OverlayProvider` that manages
+overlay elements ensuring that they properly hidden from screen readers.
+
+### Font
+
+Manifest Design System was designed using [Inter](https://rsms.me/inter/) as its font. Please be
+sure to include the font type in the <head> of your application's HTML.
+
+```html
+<link
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap"
+  rel="stylesheet"
+/>
+```
+
+### Icons
+
+Currently Manifest Design System uses material design icons. Please be sure to include the font type
+in the <head> of your application's HTML.
+
+```html
+<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" />
+```
+
+### Accessibility
+
+Manifest is built with accessibility in mind, each component will assign the correct events and aria
+attributes needed to meet the [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/) guidelines. We rely
+heavily on [react-aria](https://react-spectrum.adobe.com/react-aria/index.html) for provide
+accessible UI primitives.
+
+### Polymorphism
+
+All Manifest components are polymorphic, meaning that each component can be rendered using a
+different element or node using the `as` prop.
+
+```tsx
+import { Button } from '@porject44-manifest/react';
+
+<Button as="span" />;
+```
+
+> This should be used sparingly though, as Manifest automatically appends all the necessary
+> aria-attributes to an element.
+
+### Styling
+
+The `@project44-manifest/react` library ships with a pre-configured styling engine powered by
+[Stitches](https://stitches.dev).
+
+All the components support the `css` prop for overriding styles. It's like the style attribute, but
+it supports tokens, media queries, nesting and token-aware values.
+
+For more information about the `css` prop, check out the Stitches
+[documentation](https://stitches.dev/docs/overriding-styles#the-css-prop).
+
+> Please note that all components have been built to the specification of the Manifest Design
+> System. Therefor overriding component styles should be used sparingly. If you need to control the
+> layout of components we recommend using the layout primitives supplied by Manifest instead of
+> overriding individual component styles.
+
+```tsx
+import { Button } from '@project44-manifest/react';
+
+<Button css={{ backgroundColor: '$palette-color-black' }} />;
+```
+
+> Notice the usage of [theme tokens](https://stitches.dev/docs/tokens) in the above example, it is
+> highly encouraged to use theme tokens vs. hard coded values as this allows all components to
+> inherit any changes made at the theme level. Check out our
+> [theme specification](../theme/README.md) for a complete list of available theme tokens.
+
+### Composing components
+
+If you need to compose your own components utilizing the design system in react we recommend using
+the polymorphic `Box` component. The `Box` component ships with support for the `css` and `as`
+props, allowing you to quickly and easily build custom components that follow Manifest Design
+System.
+
+```tsx
+import { Box } from '@project44-manifest/react';
+
+function MyComponent() {
+  return (
+    <Box as="span" css={{ color: '$palette-grey-100' }}>
+      Hello World
+    </Box>
+  );
+}
+```
+
+Along with the `Box`, Manifest provides a robust set of layout primitives that can be used to
+control layout and composing components.
+
+These primitives include a `Container`, `Flex`, `Grid`, and `Stack` component.
+
+Please refer the the [documentation website](https://www.manifestdesignsystem.com/docs/components)
+for usage information and best practices.
+
+## Contributing
+
+Contributions are always welcome!! Please review our [Contribution Guide](/.github/CONTRIBUTING.md)
+to get started.
+
+## License
+
+Licensed under the [MIT](/LICENSE).