Update contributing guide and improve docs (#408)

* update contributing guide and improve docs

* symlink work plz?

* add changeset

.changeset/happy-shrimps-carry.md

@@ -0,0 +1,5 @@
+---
+"@ngrok/mantle": patch
+---
+
+Revamp the readme and contributing guide

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
-# ngrok Documentation Code of Conduct
+# Mantle Code of Conduct
 
 ## Our Pledge
 
@@ -24,9 +24,9 @@ Examples of unacceptable behavior by participants include:
 
 ## Our Responsibilities
 
-The ngrok documentation team is responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+The Mantle team is responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
 
-The ngrok documentation team has the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+The Mantle team has the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
 ## Scope
 

CONTRIBUTING.md

@@ -1,31 +1,97 @@
-# Contributing to the ngrok documentation
+# Contributing to Mantle
 
-Thank you for your interest in contributing to the ngrok documentation! We welcome contributions from the community and are grateful for your help in making our documentation better.
+Thank you for your interest in contributing to the Mantle! We welcome contributions from the community and are grateful for your help in making our design system better.
 
 ## Getting started
 
-To get started, fork the ngrok documentation repository on GitHub and clone your fork locally.
-ngrok docs is built using Docusaurus. Use the instructions on [README.md](README.md) to setup your local environment.
-The documentation is written in Markdown and organized into directories by topic.
+First, [fork the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) and clone to your local machine:
 
-## Making changes
+```sh
+git clone git@github.com:<your username>/mantle.git
+cd mantle
+```
 
-To make changes to the documentation, edit the relevant Markdown files in your local clone of the repository. If you are unsure which files to edit, you can use the GitHub search functionality to find the relevant files.
+## Installation
 
-When making changes, please follow the Markdown style guide and try to keep your changes concise and to the point. If you are making significant changes or adding new content, please consider including examples or other resources to help readers understand the topic better.
+The following prerequisites are required to contribute to `@ngrok/mantle`. Install the prerequisites through either the [automated](#automated-installation) or [manual](#manual-installation) installation guides below.
 
-Once you have finished making your changes, we recommend you run a local build with docusaurus (command `pnpm run build`) to ensure your contribution will not present errors with links or build. After a successful build, push them to your fork on GitHub and create a pull request to submit your changes for review.
+- [Node 20](https://nodejs.org/en/download)
+- [pnpm 9](https://pnpm.io/installation#using-npm)
+- [nvm](https://github.com/nvm-sh/nvm)
 
-## Code of conduct
+### Automated Installation
+
+We use [direnv](https://direnv.net/) to assist you with setting up all of the required tooling.
+
+Prefer to install and manage the tooling yourself? See [the manual installation instructions below](#manual-installation).
+
+First, install `direnv`:
+
+| OS     | command                 |
+| ------ | ----------------------- |
+| macOS  | brew install direnv     |
+| ubuntu | sudo apt install direnv |
+
+For all other OSes, see the [direnv installation guide](https://direnv.net/docs/installation.html).
+
+> [!NOTE]
+> Don't forget to [set up direnv integration with your shell](https://direnv.net/docs/hook.html).
+
+Next, run:
+
+```sh
+direnv allow
+```
+
+> [!WARNING]
+> If `direnv allow` does nothing for you (you should see things happening!), consider following the [guides to integrate direnv with your shell](https://direnv.net/docs/hook.html) and then try `direnv allow` again! As a last resort, you can follow the [manual installation instructions up above](#manual-installation).
+
+This will install `nvm` (if not already installed) as well as set the correct `node` and `pnpm` versions for you. It will also run `pnpm install` at the end to install all `node_modules`.
+
+### Manual Installation
+
+If you prefer to manually manage and install the tooling yourself, follow these steps:
 
-We ask that all contributors follow our [code of conduct](CODE_OF_CONDUCT.md) when contributing to the documentation. This code of conduct outlines our expectations for behavior and helps ensure that the ngrok community is a welcoming and inclusive place for everyone.
+1. Install [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) or your node version manager of choice.
+2. Ensure that `node 20` is installed. With `nvm`, run `nvm install`.
+3. Enable `pnpm` with `corepack`: `corepack enable pnpm`
+4. Install `pnpm` with `corepack`: `corepack install`
+5. Install project dependencies with `pnpm`: `pnpm install`
 
-## Review process
+## Local Development
 
-Once you have submitted your pull request, the ngrok documentation team will review your changes and provide feedback or suggestions for improvement. We may also make additional changes to your pull request to ensure that it meets the standards of the ngrok documentation.
+We use [Turborepo](https://turbo.build/) and pnpm workspaces to help manage the Mantle monorepo.
 
-Once your pull request has been reviewed and any necessary changes have been made, it will be merged into the main ngrok documentation repository.
+To get started, simply run:
 
-## Thank you!
+```
+pnpm -w run start
+```
+
+This will spin up the Remix documentation site, and is configured to watch for changes to components (so your changes will be instantly reflected).
+
+## Submitting a Pull Request
+
+Before working on a large change, it is best to open an issue first to discuss.
+
+After making your changes locally, go ahead and submit a pull request. The Mantle team will review your changes and provide feedback or suggestions for improvement. We may also make additional changes to your pull request to ensure that it meets the standards of Mantle.
+
+We use [changesets](https://github.com/changesets/changesets) to help us manage versioning and changelogs. You can think of a changeset as an _intent to change_. If your changes require a publish and release, feel free to add a changeset to your PR, otherwise we can add one for you if you're unsure.
+
+Handy command to add a changeset via the CLI:
+
+```
+pnpm -w run changeset
+```
+
+Some helpful tips:
+
+- You don't have to use the cli if you prefer to just create one manually (though the cli is definitely easiest).
+- Feel free to edit the changeset file however many times you want (it's just an `.md` file) while working on your PR.
+- Check out their [common questions](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) for more tips or read their [docs](https://github.com/changesets/changesets/tree/main/docs).
+
+Once your pull request has been reviewed and any necessary changes have been made, it will be merged.
+
+## Code of conduct
 
-Thank you for contributing to the ngrok documentation! Your help is greatly appreciated and will make our documentation better for everyone.
+We ask that all contributors follow our [code of conduct](CODE_OF_CONDUCT.md) when contributing. This code of conduct outlines our expectations for behavior and helps ensure that the ngrok community is a welcoming and inclusive place for everyone.

README.md

@@ -0,0 +1 @@
+packages/mantle/README.md

packages/mantle/README.md

@@ -11,7 +11,12 @@
 
 [Mantle](https://mantle.ngrok.com) is [ngrok](https://ngrok.com/)’s UI library and design system. It’s inspired by [shadcn/ui](https://ui.shadcn.com) and uses [Radix](https://www.radix-ui.com) with [Tailwind](https://tailwindcss.com/) for styling. It’s documented using [Remix](https://remix.run/docs).
 
-## Getting Started
+## Documentation
+
+- [mantle.ngrok.com](https://mantle.ngrok.com) - our official component documentation site (reflects latest releases)
+- [develop.mantle.ngrok.com](https://develop.mantle.ngrok.com) - staging site for all merges to `main`
+
+## Installation
 
 Install `@ngrok/mantle` with your preferred package manager:
 
@@ -40,61 +45,6 @@ export default {
 
 Next, check out the [Overview & Setup](https://mantle.ngrok.com/) and [Theme Provider](https://mantle.ngrok.com/components/theme-provider) usage docs and start using mantle components in your application!
 
-### Prerequisites
-
-The following prerequisites are required to contribute to `@ngrok/mantle`.
-We walk through the [tooling installation](#installation) steps below.
-
-- [Node 20](https://nodejs.org/en/download)
-- [pnpm 9](https://pnpm.io/installation#using-npm)
-- [nvm](https://github.com/nvm-sh/nvm)
-
-### Installation
-
-Install the prerequisites through either the [automated](#automated-installation) or [manual](#manual-installation) installation guides.
-
-#### Automated Installation
-
-We use [direnv](https://direnv.net/) to assist you with setting up all of the required tooling.
-Prefer to install and manage the tooling yourself? See [the manual installation instructions below](#manual-installation).
-
-First, install `direnv`:
-
-| OS     | command                 |
-| ------ | ----------------------- |
-| macOS  | brew install direnv     |
-| ubuntu | sudo apt install direnv |
-
-For all other OSes, see the [direnv installation guide](https://direnv.net/docs/installation.html).
-
-> [!NOTE]
-> Don't forget to [set up direnv integration with your shell](https://direnv.net/docs/hook.html).
-
-Next, clone the repo and move into the directory:
-
-```sh
-git clone git@github.com:ngrok-oss/mantle.git
-cd frontend
-```
-
-Next, run:
-
-```sh
-direnv allow
-```
-
-> [!WARNING]
-> If `direnv allow` does nothing for you (you should see things happening!), consider following the [guides to integrate direnv with your shell](https://direnv.net/docs/hook.html) and then try `direnv allow` again! As a last resort, you can follow the [manual installation instructions up above](#manual-installation).
-
-This will install `nvm` (if not already installed) as well as set the correct `node` and `pnpm` versions for you.
-It will also run `pnpm install` at the end to install all `node_modules`.
-
-#### Manual Installation
-
-If you prefer to manually manage and install the tooling yourself, follow these steps:
+## Contributing
 
-1. Install [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) or your node version manager of choice.
-2. Ensure that `node 20` is installed. With `nvm`, run `nvm install`.
-3. Enable `pnpm` with `corepack`: `corepack enable pnpm`
-4. Install `pnpm` with `corepack`: `corepack install`
-5. Install project dependencies with `pnpm`: `pnpm install`
+Please read our [contribution guide](https://github.com/ngrok-oss/mantle/blob/main/CONTRIBUTING.md).