Merge pull request #217 from MetroStar/doc-updates

Documentation Updates

README.md

@@ -18,13 +18,13 @@ In the beginning, Comet was built with a primary focus of USWDS. Today however,
 
 ## Overview
 
-`comet-uswds` - The base USWDS component library implemented in React with TypeScript.
+[comet-uswds](https://github.com/MetroStar/comet/tree/main/packages/comet-uswds) - The base USWDS component library implemented in React with TypeScript.
 
-`comet-data-viz` - A set of Victory Chart components provided as a Comet wrapper.
+[comet-data-viz](https://github.com/MetroStar/comet/tree/main/packages/comet-data-viz) - A set of Victory Chart components provided as a Comet wrapper.
 
-`comet-extras` - A set of custom components, intended to fill in the gaps where USWDS does not provide an implementation.
+[comet-extras](https://github.com/MetroStar/comet/tree/main/packages/comet-extras) - A set of custom components, intended to fill in the gaps where USWDS does not provide an implementation.
 
-`comet-cli` - A CLI for creating Comet Apps.
+[comet-cli](https://github.com/MetroStar/comet/tree/main/packages/comet-cli) - A CLI for creating Comet Apps.
 
 ## Getting Started
 

packages/comet-data-viz/README.md

@@ -17,4 +17,20 @@ yarn add @metrostar/comet-data-viz
 
 ```tsx
 import { BarGraph } from '@metrostar/comet-data-viz';
+
+const chart = {
+  title: 'Bar graph',
+  width: 400,
+  height: 300,
+};
+
+const data = [
+  { x: 'Cat', y: 2 },
+  { x: 'Dog', y: 7 },
+  { x: 'Fish', y: 3 },
+  { x: 'Snake', y: 1 },
+  { x: 'Rabbit', y: 2 },
+];
+
+<BarGraph chart={chart} alignment="start" color="#0d7ea2" barRatio={1} data={data} />;
 ```

packages/comet-extras/README.md

@@ -17,4 +17,10 @@ yarn add @metrostar/comet-extras
 
 ```tsx
 import Tabs, { TabPanel } from '@metrostar/comet-extras';
+
+<Tabs id="tabs">
+  <TabPanel id="tab-panel-1" label="Tab 1">
+    <p>Content of Tab 1</p>
+  </TabPanel>
+</Tabs>;
 ```

packages/comet-uswds/README.md

@@ -2,9 +2,15 @@
 
 Comet is a React with TypeScript Component Library based on USWDS 3.0.
 
-## Getting Started
+In order to utilize Comet within your app, you must first ensure USWDS is pre-configured in your app. Please review the following for details specific to USWDS prior proceeding: [USWDS Documentation](https://designsystem.digital.gov/documentation/developers/).
 
-In order to utilize Comet within your app, you must first ensure USWDS is pre-configured in your app. Please review the following for details: [USWDS Documentation](https://designsystem.digital.gov/documentation/developers/).
+## Getting started with the Comet Starter App (recommended)
+
+1. Clone the comet starter repo here: [Comet Starter](https://github.com/MetroStar/comet-starter)
+
+2. Follow the steps for "Running the Project Locally"
+
+## Getting Started with a Custom App (pre-configured for USWDS)
 
 1. Add Comet to your project:
 
@@ -19,4 +25,101 @@ yarn add @metrostar/comet-uswds
 
 ```tsx
 import { Alert } from '@metrostar/comet-uswds';
+
+<Alert id="alert-1" type="info">
+  This is the alert body
+</Alert>;
+```
+
+## Getting Started with a Custom App (NOT pre-configured for USWDS)
+
+_Note: the below setup assumes your project is setup for Vite and SCSS._
+
+1. Add USWDS and Comet to your project:
+
+```sh
+# npm
+npm i --save @uswds/uswds @metrostar/comet-uswds
+
+# or yarn
+yarn add @uswds/uswds @metrostar/comet-uswds
+```
+
+2. Add uswds directory to your src folder
+3. Add base USWDS file (uswds.scss) to the uswds directory, with the following:
+
+```scss
+// Include a USWDS settings file (required)
+@forward './uswds-settings.scss';
+
+// Point to the USWDS source code (required)
+@forward '~uswds/packages/uswds';
+
+// Include your project's custom Sass (optional)
+// @forward "project-custom.scss";
+```
+
+4. Add base USWDS settings file (uswds-settings.scss) to the uswds directory, with the following:
+
+```scss
+@use 'uswds-core' with (
+  // General settings
+  $theme-show-notifications: false,
+  $theme-font-path: '~uswds/dist/fonts',
+  $theme-image-path: '~uswds/dist/img'
+);
+```
+
+5. Add uswds to the top of your your SASS entry point (styles.scss), with the following:
+
+```scss
+@forward 'uswds/uswds.scss';
+```
+
+6. Update your Vite config file (vite.config.ts) as needed with the following USWDS specific configurations:
+
+```ts
+import react from '@vitejs/plugin-react';
+import autoprefixer from 'autoprefixer';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { defineConfig } from 'vite';
+import EnvironmentPlugin from 'vite-plugin-environment';
+import eslint from 'vite-plugin-eslint';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react(), tsconfigPaths(), eslint(), EnvironmentPlugin('all')],
+  resolve: {
+    alias: {
+      '~uswds': path.resolve(__dirname, 'node_modules/@uswds/uswds'),
+    },
+  },
+  css: {
+    preprocessorOptions: {
+      scss: {
+        includePaths: ['node_modules/@uswds/uswds/packages'],
+      },
+    },
+    postcss: {
+      plugins: [autoprefixer],
+    },
+  },
+});
+```
+
+7. Add your first Comet component:
+
+```tsx
+import { Alert } from '@metrostar/comet-uswds';
+
+<Alert id="alert-1" type="info">
+  This is the alert body
+</Alert>;
 ```
+
+For any further troubleshooting, please refer to the comet starter app linked above.