@commonapp/common-app-design-system NPM

Common App Design System (CADS)

Illustration of a forklift, sedan, and race car driving past telephone poles towards an "Under construction" sign.

Welcome

The Common App design system (CADS) is a collaborative effort to centrally store and manage shared components across the organization. These components are built and designed framework agnostic, meaning they are made to work in any Javascript-based application we may have now or in the future.

System

CADS utilizes ionic's Stencil as a framework to create and release these components. The output is usable within our current Angular applications as well as in the dot org site and our Salesforce communities.

Using Stencil

Developers should utilize Stencil's own documentation as a primary resource when building and maintaining components. As opportunities to expand this on our end appear, additional information may be available through the CADS Confluence pages.

Local testing

In the src/ folder is an index.html file. This HTML file should be used to test actively developed components. Placing the components being worked on in this file works with the www output target of Stencil to create a localhost environment to work on components.

Changes made to the index.html file should not be committed to the main branch. We may explore using a .gitignore line to untrack this file but for the time being, do not stage, commit, or push any changes to this file beyond the templating that already exists.

Once Storybook stories are created, it's also possible to do live development through Storybook itself. The core npm run start command is setup to enable developers to work on Stencil components and test them within Storybook.

Available scripts

Stencil (component creation and management)

Script	Action
`npm run build`	Build all components with documentation.
`npm run build:prod`	Build all components in full production mode.
`npm run build:serve`	Run a hot-reloading Stencil build command.
`npm run build:watch`	Run a hot-reloading Stencil build command and open a localhost server for testing.
`npm run start`	Concurrently run `build:serve` and `storybook` for live component creation and testing within Storybook.
`npm run test:all`	Run Jest (unit) and end-to-end (E2E) tests on all components.
`npm run test:e2e`	Perform a single E2E test across all components.
`npm run test:e2e:watch`	Open a hot-reloading E2E testing instance.
`npm run test:unit`	Perform a single Jest unit test run across all components.
`npm run test:unit:watch`	Open a hot-reloading Jest unit testing instance.
`npm run generate`	Create a new Stencil component.

Style Dictionary (token creation and management)

Script	Action
`npm run tokenize`	Generate new token outputs from changes in the source token folders.

Storybook (documentation and testing)

Script	Action
`npm run storybook`	Start a local Storybook server to test and work on documentation.
`npm run storybook:build`	Run the build task for Storybook output. Outputs a static version of Storybook to the `./public` folder.

Linting and validation

Script	Action
`npm run eslint`	Manually run ESLint on the entire project.
`npm run prettier`	Manually run Prettier on the entire project.
`npm run stylelint`	Manually run Stylelint against all stylesheets in the `src/` folder.

Release

Script	Action
`npm run prepublishOnly`	Automatically run pre-publish by npm. Runs `build:prod`
`npm run preversion`	Automatically run pre version bump by npm. Runs `test:all`