@commonapp/common-app-design-system

Common App Design System (CADS)

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