The compass components package is the implementation of the compass design system meant (but not limited) to be used in the mattermost products: Messaging, Playbooks and Focalboard.
The intention behind the püackage is to create a unified look and feel across the products.
-
install compass components from npm
in your project run
npm i @mattermost/compass-components
-
import
ThemeProvider
in your application rootIn order for the compass components to be syled correctly you need to wrap your applcation in a
ThemeProvider
.It also manages custom themes for your application (if you wish so).
import ThemeProvider from '@mattermost/compass-components/utilities/theme';
-
import the components you need into your files
import Text from '@mattermost/compass-components/components/Text';
This is just a basic exmaple how the ThemeProvider
can be used to provide a theme and toggle between two themes
import { useState } from 'react';
import ThemeProvider, {
lightTheme,
darkTheme,
} from '@mattermost/compass-components/utilities/theme';
import Button from '@mattermost/compass-components/components/button';
function App() {
const [themeIndex, setThemeIndex] = useState(0);
const themes = [lightTheme, darkTheme];
const handleClick = () => setThemeIndex(themeIndex === 0 ? 1 : 0);
return (
<ThemeProvider theme={themes[themeIndex]}>
<Button
icon={'mattermost'}
iconPosition={'start'}
label={'TESTBUTTON'}
onClick={handleClick}
/>
</ThemeProvider>
);
}
export default App;
-
Fork/Checkout this repository to a folder on your computer (we will use the user folder in this example)
cd path/to/your/projects/folder git clone https://github.com/<YOUR_GITHUB_USERNAME>/compass-components.git
It should now be cloned to
path/to/your/projects/folder/compass-components
-
Install all dependencies needed for running storybook
go to the project folder:
cd compass-components
and install dependencies with
npm
:npm install --legacy-peer-deps
NOTE: adding the flag
--legacy-peer-deps
is curently needed when there is no validpackage-lock.json
in place, sincepeerDependencies
differ fand cannot be resolved for storybook and other packages. -
Run storybook
once all packages are installed you can run storybook:
npm run storybook
when storybook is up and running you can access it by navigating in your browser to
localhost:6006
.
- node version 16.x
- npm version 7.x
As we are a company committed to open-source we welcome every contribution from the wider community. This section should outline the very basic steps to contribute to the project.
For ease of use we created a convenience generate component
function to create a boilerplate template for new
components.
Simply run
npm run gc
You will be asked which kind of component you would like to create:
Foundation
(Atomic component) - will go into thesrc/foundations
folderComponent
(Molecule component) - will go into thesrc/components
folderUtility
(Utility component) - will go into thesrc/utilities
folder
The function will create a component structure like this:
ComponentName/
├── ComponentName.constants.ts
├── ComponentName.props.ts
├── ComponentName.root.ts
├── ComponentName.stories.mdx
├── ComponentName.tsx
├── ComponentName.types.ts
└── index.ts
we mainly use 3 different types of namings and each one has their own use-case:
naming style | used for | example |
---|---|---|
PascalCase |
component names | MenuItem |
props definitions | type PMenuItem = { ... } |
|
types definitions | type TMenuItemSize = { ... } |
|
UPPER_CASE |
constants | const MENU_ITEM_SIZES = ... |
camelCase |
everything else | const setMenuItemSize = () => { ... } |
for an easier way to test this package in your locally running project we added a script to build, pack and save it.
Simply run the following command in the compass-component package root and it will perform all the actions, except for installing it in your project (but it will give you a command to do so :D)
npm run pack
after the scrpt finishes it gives you a command to run in your project root, that should look simething like this:
npm install -S "$COMPASS_COMPONENTS_PACKAGE_PATH"
INFO:
the script will export a variable
COMPASS_COMPONENTS_PACKAGE_PATH
to your shell. This is not ultimately needed and is being set only for convenience. You can still install the package directly using a path (absolute or relative to your projects folder).the installable tarball is saved to the compass-component root folder (
<PATH_TO_COMPASS_COMPONENTS>/packed.tgz
)