feat: New storybook documentation structure

.github/workflows/publish-storybook-pr-preview.yml

@@ -0,0 +1,36 @@
+name: Deploy Storybook PR preview
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.MP_SEMANTIC_RELEASE_BOT }}
+      GIT_AUTHOR_NAME: mparticle-automation
+      GIT_AUTHOR_EMAIL: developers@mparticle.com
+      GIT_COMMITTER_NAME: mparticle-automation
+      GIT_COMMITTER_EMAIL: developers@mparticle.com
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install and Build
+        if: github.event.action != 'closed' # You might want to skip the build if the PR has been closed
+        run: |
+          npm install
+          npm run build-storybook
+          touch ./storybook-static/.nojekyll
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./storybook-static/

.github/workflows/publish-storybook.yml

@@ -1,20 +1,26 @@
 name: Publish Storybook
-
 on:
   push:
     branches:
-      - 'main' # change to the branch you wish to deploy from
-
+      - main
 permissions:
-  contents: read
-  pages: write
-  id-token: write
-
+  contents: write
 jobs:
-  deploy:
+  build-and-deploy:
+    concurrency: ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
     runs-on: ubuntu-latest
     steps:
-      - id: build-publish
-        uses: bitovi/github-actions-storybook-to-github-pages@v1.0.3
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
+        run: |
+          npm ci
+          npm run build-storybook
+          touch ./storybook-static/.nojekyll
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          path: storybook-static
+          folder: storybook-static # The folder the action should deploy.
+          clean-exclude: pr-preview/

.storybook/main.ts

@@ -2,6 +2,7 @@ import type { StorybookConfig } from '@storybook/react-vite'
 import react from '@vitejs/plugin-react'
 import { PluginOption, Plugin } from 'vite'
 import { withoutVitePlugins } from '@storybook/builder-vite'
+import remarkGfm from 'remark-gfm'
 
 type StorybookVitePlugins = { plugins: (PluginOption[] | Plugin)[] }
 
@@ -11,9 +12,24 @@ const config: StorybookConfig & StorybookVitePlugins = {
     options: {},
   },
 
-  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(ts|tsx)'],
-
-  addons: ['@storybook/addon-links', '@storybook/addon-essentials', '@storybook/addon-interactions'],
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(ts|tsx)', '../docs/**/*.mdx'],
+
+  addons: [
+    '@storybook/addon-links',
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+    {
+      name: '@storybook/addon-docs',
+      options: {
+        mdxPluginOptions: {
+          mdxCompileOptions: {
+            // needed for rendering markdown tables in .mdx
+            remarkPlugins: [remarkGfm],
+          },
+        },
+      },
+    },
+  ],
 
   docs: {
     autodocs: true,

.storybook/preview.tsx

@@ -0,0 +1,40 @@
+import type { Preview } from '@storybook/react'
+
+const preview: Preview = {
+  parameters: {
+    layout: 'centered',
+    options: {
+      storySort: {
+        order: [
+          'About',
+          ['Introduction', 'Changelog', 'FAQ'],
+          'Component Process',
+          [
+            'Introduction',
+            'Components',
+            ['Using components', 'Change process'],
+            'Candidate Components',
+            ['Introducing new ones', 'Using existing ones', 'Promoting to a component'],
+            'Design Templates',
+          ],
+          'Foundations',
+          'Components',
+          ['Colors', 'Typography', 'Icons', 'Errors', 'Loading'],
+          'Candidate Components',
+          'Design Templates',
+          'Contributing',
+          ['Introduction', 'Commits', 'Testing in the platforms', 'Release Process', 'Maintainers'],
+        ],
+      },
+    },
+
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+}
+
+export default preview

docs/About/Changelog.mdx

@@ -0,0 +1,7 @@
+import {  Markdown } from "@storybook/blocks"
+
+import changelog from '../../CHANGELOG.md?raw'
+
+# CHANGELOG
+
+<Markdown>{changelog}</Markdown>

docs/About/FAQ.mdx

@@ -0,0 +1,6 @@
+# FAQ
+
+### What should I do if I can't implement my design specs using Antd atoms?
+
+Please ask questions about it in the #aquarium channel. Ideally have a branch with your work in progress and some Storybook
+stories so that we can see what you're trying to do.

docs/About/Introduction.mdx

@@ -0,0 +1,20 @@
+# Introduction
+
+This is where all component related documentation will live at mParticle. This is mainly a work in progress at this point
+and we are actively working on it.
+
+## How to read this
+
+TBD
+
+## Glossary
+
+| Term     | Meaning |
+| -------- | ------- |
+| Component Candidate  | TBD    |
+| Template | TBD     |
+| Eames    | TBD    |
+| Aquarium | TBD    |
+| Antd | TBD     |
+
+---

docs/Candidate Components/Directory/Component.mdx

@@ -0,0 +1,3 @@
+# Component
+
+TBD

docs/Candidate Components/Introduction.mdx

@@ -0,0 +1,3 @@
+# Introduction
+
+TBD

docs/Component Process/Candidate Components/Introducing new ones.mdx

@@ -0,0 +1,3 @@
+# Introducing new candidate components
+
+TBD

docs/Component Process/Candidate Components/Promoting to a component.mdx

@@ -0,0 +1,3 @@
+# Promoting to a component
+
+TBD

docs/Component Process/Candidate Components/Using existing ones.mdx

@@ -0,0 +1,19 @@
+import { Mermaid } from 'mdx-mermaid/Mermaid';
+
+# Using existings candidate components
+
+<Mermaid chart={`graph TD;
+    classDef product stroke:#ddd;
+    classDef design fill:#E4CCFF, stroke:gray;
+    classDef engineering fill:#0D99FF, stroke:gray, color:white;
+
+    A[Project is prioritized for design]:::product --> B
+
+    B[Designer reviews the project needs and identifies a needs for customization or componetization]:::design --> C
+
+    C[Unify: Trigger source of truth update by creating a ticket to Unify squad for updating  Storybook. Start tracking usage in the rule of 3.]:::engineering --> D
+
+    D[Design Handoff. Designer communicates to the project team that  a new  component candidate is introduced in the handoff]:::design --> E
+
+    E[Implement it using Aquarium atoms directly in the platforms]:::engineering
+`} />

docs/Component Process/Components/Change process.mdx

@@ -0,0 +1,3 @@
+# Change process
+
+TBD

docs/Component Process/Components/Using components.mdx

@@ -0,0 +1,3 @@
+# Using components
+
+TBD

docs/Component Process/Design Templates/Introduction.mdx

@@ -0,0 +1,3 @@
+# Design Templates
+
+TBD

docs/Component Process/Introduction.mdx

@@ -0,0 +1,3 @@
+# Introduction
+
+TBD

docs/Contributing/Commits.mdx

@@ -0,0 +1,41 @@
+# Commits
+
+## Commit conventions and PR titles
+
+- We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to help automating the release process. Both PR titles and commit messages should follow this convention.
+- [This repo is commitizen friendly](https://github.com/commitizen/cz-cli?tab=readme-ov-file#using-the-command-line-tool) so we can use `git cz` to commit changes.
+`npx cz` is also available if you don't have commitizen installed globally.
+- We also have a [commitlint](https://commitlint.js.org/) setup to enforce the commit message format.
+
+The standard format for commit messages is as follows:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer]
+```
+
+The following lists the different `types` allowed in the commit message:
+
+- feat: A new feature (automatic minor release)
+- fix: A bug fix (automatic patch release)
+- docs: Documentation only changes
+- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- refactor: A code change that neither fixes a bug nor adds a feature
+- perf: A code change that improves performance
+- test: Adding missing or correcting existing tests
+- chore: Changes that don't modify src or test files, such as automatic documentation generation, or building latest assets
+- ci: Changes to CI configuration files/scripts
+- revert: Revert commit
+- build: Changes that affect the build system or other dependencies
+
+In the footer, if there is a breaking change, start your footer with `BREAKING CHANGE:` followed by a description.
+
+## Editor configuration
+
+- **Prettier**: For configuring your editor to play nicely with Prettier, take a look at the [Editors doc page](https://prettier.io/docs/en/editors).
+- Also, if you're using VSCode you might want to set prettier as the default formatter and also turn on "Format on Save" option.
+- **ESLint**: Check [Integrations doc page](https://eslint.org/docs/latest/use/integrations)
+- **Stylelint**: Check [Editor integrations doc page](https://stylelint.io/awesome-stylelint/#editor-integrations)

docs/Contributing/Introduction.mdx

@@ -0,0 +1,4 @@
+# Introduction
+
+Thanks for the interest in contributing to the Aquarium! Being a component library requires a different approach to development and testing. 
+This document will guide you through the process of contributing to the Aquarium.

docs/Contributing/Maintainers.mdx

@@ -0,0 +1,3 @@
+# Maintainers
+
+TBD

docs/Contributing/Release Process.mdx

@@ -0,0 +1,32 @@
+# Release Process
+
+We use [semantic-release](https://github.com/semantic-release/semantic-release) to automate the versioning and publishing 
+of the mParticle Aquarium component library. Everything is handled by semantic-release, including determining the next version number, 
+generating the release notes, and publishing to npm. You can use the Github Release Aquarium action from the `main` branch to release from it.
+
+> [!IMPORTANT]  
+> Before releasing a version from main, send a message in the #aquarium Slack channel to align it and sync on other changes that can/should be included in the release.
+
+## Contributing with the release process
+
+To make changes to the release process, you can use the `--dry-run` from semantic-release flag to test the release
+process without actually publishing a new version.
+
+You will need two environment variables to run the release process locally:
+
+- NPM_TOKEN: You can create a personal npm account and use a personal token.
+Since we are using `--dry-run` it won't try to publish anything so having a valid read-only npm token works.
+
+- GITHUB_TOKEN: Create a [github personal access token (classic)](https://github.com/settings/tokens)
+and give it access to the mParticle organization via "Configure SSO" button.
+
+After settings both variables locally, run the following locally:
+
+```
+npx semantic-release --dry-run
+```
+
+## Additional readings:
+
+- [Semantic Release Workflow Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/workflow-configuration.md#workflow-configuration)
+- [Understanding npm distribution channels](https://docs.npmjs.com/cli/v8/commands/npm-dist-tag#purpose)

docs/Contributing/Testing in the platforms.mdx

@@ -0,0 +1,30 @@
+# Testing in the platforms
+
+## Testing in the CDP
+
+In order to test your changes, you will need to link the local version of the library. To do this, run the following commands:
+
+- Make sure to have the library built by running `npx vite build`. The linked version will use the build files from _dist/_ folder.
+- Make sure the `resolve.symlinks` property in you webpack config is set to `false`
+- `yarn link` in the root of the library
+- `yarn link @mparticle/aquarium` in the root of Nancy
+- Make sure your _/node_modules/@mparticle/aquarium_ folder contains all of the Aquarium code
+
+## Testing in Analytics
+
+TODO
+
+## Testing by installing from a branch
+
+Another way to test your changes is by installing the library from a branch. To do this, we need to push the _dist/_ folder to the remote
+and install it directly from there with the following command:
+
+```
+yarn add https://github.com/mParticle/aquarium#<branch-name>
+```
+
+## Testing by releasing an ad-hoc version
+
+To test ad-hoc versions of the Aquarium we use `feat/`, `fix/` or `chore/` branchs on Github and their corresponding distribution channels on npm.
+This allows us to release specific versions for testing specific features and install them on the platforms. To release it,
+just run the Github Action from the the branch you want to release.

docs/Design Templates/Directory.mdx

@@ -0,0 +1,3 @@
+# Directory
+
+TBD

docs/Foundations/Colors.mdx

@@ -0,0 +1,3 @@
+# Colors
+
+TBD