The Design Language System for ACT & Encoura front-end projects. View the UI components here.
In order to use the DLS, you must install it along with
Material UI version 5.x
and
React version 17.x
or 18.x
.
npm install --save @actinc/dls@latest @mui/material @mui/lab @mui/x-data-grid @emotion/styled @emotion/react react react-dom
This DLS is built on top of the theme engine from Material UI, and ships with several themes out of the box:
"ACT"
: for ACT's "traditional" look and feel"ACT_ET"
: for ACT's "Emerging Technology" look and feel"ENCOURA_CLASSIC"
: for Encoura's "Classic" look and feel"ENCOURAGE"
: for the Encoura's "Encourage" look and feel
To apply one of these themes to your components, simply wrap your application
in the ThemeProvider
component and specify a theme!
import { ThemeProvider } from '@actinc/dls/components';
...
const MyApp = () => (
// specify a theme here!
<ThemeProvider theme="ACT_ET">
<App />
</ThemeProvider>
);
You can exend the core DLS themes using using our variation on the
createTheme
generator from Material UI:
import deepMerge from 'deepmerge';
import { createTheme } from '@actinc/dls/styles/createTheme';
import { THEME_ACT } from '@actinc/dls/styles/themeAct';
import { ThemeProvider } from '@actinc/dls/components';
const myExtendedTheme = createTheme(deepMerge(THEME_ACT, {
// theme customizations go here!
}));
const MyApp = () => (
<ThemeProvider theme={myExtendedTheme}>
<App />
</ThemeProvider>
);
Alternatively, you can build your own theme from scratch using our variation on the
createTheme
generator from Material UI. Our version takes the same parameters, but will
return a strongly typed version of the theme with any customizations you may
have added.
import { ThemeProvider } from '@actinc/dls/components';
import { createTheme } from '@actinc/dls/styles/createTheme';
const myCustomTheme = createTheme({
// build your theme here!
});
const MyApp = () => (
<ThemeProvider theme={myCustomTheme}>
<App />
</ThemeProvider>
);
Within your styled components, if you need to access custom a theme variable
that is not present in the default MUI Theme
type, we provide a helper
function to generate a styled
function that is strongly typed to your theme:
import { createThemeStyled } from '@actinc/dls/helpers/styled';
import { THEME_ACT } from '@actinc/dls/styles/themeAct';
import TableCell from '@mui/material/TableCell';
const styled = createThemeStyled(THEME_ACT);
const StyledTypography = styled(TableCell)(({ theme }) => ({
// `customDims` is not available on the default theme
height: theme.customDims.heights.tableHeader,
}))
The ACT
and ACT_ET
themes assume that the
Montserrat font is available in
the browser. Therefore, it is recommended that you include the following font
reference in the head
of your React app:
<link
href="https://fonts.googleapis.com/css?family=Montserrat:300,400,500,600,700&display=swap"
rel="stylesheet"
/>
The ENCOURA_CLASSIC
theme assumes that the
Museo font
is available in the browser. Therefore, it is recommended that you include the
following font reference in the head
of your React app:
<style type="text/css">
@font-face {
font-family: 'Museo';
src: url('path/to/Museo300.otf');
font-style: normal;
font-weight: 300;
}
@font-face {
font-family: 'Museo';
src: url('path/to/Museo500.otf');
font-style: normal;
font-weight: 500;
}
@font-face {
font-family: 'Museo';
src: url('path/to/Museo700.otf');
font-style: normal;
font-weight: 700;
}
</style>
The Museo font files can be downloaded here.
The ENCOURAGE
theme assumes that the
Work Sans,
Roboto, and the
Roboto Mono fonts are available
in the browser. Therefore, it is recommended that you include the following font
reference in the head
of your React app:
<link
href="https://fonts.googleapis.com/css2?display=swap&family=Work+Sans:[email protected]"
rel="stylesheet"
/>
<link
href="https://fonts.googleapis.com/css2?display=swap&family=Roboto:wght@300;400;500;700"
rel="stylesheet"
/>
<link
href="https://fonts.googleapis.com/css2?display=swap&family=Roboto+Mono:[email protected]"
rel="stylesheet"
/>
It is recommended to inject the CssBaseline
component from Material UI near
the root of your component tree in order to reset and normalize browser styles
for your project:
import { CssBaseline } from '@mui/material';
...
const MyApp = () => (
...
<CssBaseline />
...
);
If your project's React framework supports SSR, you can configure the DLS components for server-side rendering. See the official Next.js example here.
The DLS re-exports all icons that are provided by the
mdi-material-ui
package.
You can search for a specific icon to use on materialdesignicons.com. Once you've found the perfect icon, you can use it in your project like so:
import { PollBox } from '@actinc/dls/icons';
...
const MyComponent = () => (
...
<PollBox />
...
);
That's it! You're ready to use the DLS. Simply import the components, constants, context, helpers, hooks, icons, styles, and types that you need:
// components
import { Alert } from '@actinc/dls/components';
// constants
import { SORT_DIRECTION_TYPES } from '@actinc/dls/constants';
// context
import { AlertContext } from '@actinc/dls/context';
// helpers
import { search } from '@actinc/dls/helpers';
// hooks
import { useLocalStorage } from '@actinc/dls/hooks';
// icons
import { ChevronDown } from '@actinc/dls/icons';
// styles & themes
import { THEME_ACT } from '@actinc/dls/styles/themeAct';
// types
import { SortObject } from '@actinc/dls/types';
The DLS provides a customized styled helper which omits transient props
(those starting with $) from the rendered HTML, while still being able to use
those parameters in styled components. Use as a drop in replacement of the
styled
function that exists in @mui/material/styles
:
import { styled } from '@actinc/dls/helpers/styled';
import Button, { ButtonProps } from '@mui/material/Button';
import * as React from 'react';
const StyledButton = styled(Button)<ButtonProps & { $ultraWide: boolean }>(
({ $ultraWide, theme }) => ({
paddingLeft: $ultraWide ? theme.spacing(8) : theme.spacing(4),
paddingRight: $ultraWide ? theme.spacing(8) : theme.spacing(4),
}),
);
const MyComponent: React.FC = () => {
return <StyledButton $ultraWide />;
};
- This implementation is how Styled Components does it: https://styled-components.com/docs/api#transient-props
- Unfortunately emotion (the default styling engine in React) doesn't seem to care: emotion-js/emotion#2193 (comment)
Version <= 6 of the DLS were built and exported as CommonJS modules. While this allowed the simplest integration of the DLS into any project, it also resulted in project bundles being larger than desired due to the inability of bundlers to tree-shake the DLS.
In version >= 7 of the DLS, we are now building and exporting the library as
ECMAScript modules.
This allows your project's bundler to much more easily read and
tree-shake
the DLS right out of the box. (No more need for
babel-plugin-transform-imports
!)
Furthermore, the DLS's package.json
is also setting:
"sideEffects": false,
to instruct builders to enable even deeper tree-shaking. This should make bundle sizes significantly smaller with less effort. However, the tradeoff is that in certain scenarios, like Lazy Loading, if you are expecting a dependency to be there that is now removed from tree-shaking, things will break and you may need to import that dependency directly in a parent bundle.
One downside of exporting the DLS as ECMAScript modules is that the import
and
export
keywords are preserved, which may cause your packager/runner to throw:
SyntaxError: Unexpected token 'export'
If you see this error, you'll need to instruct your packager/runner to transpile the DLS on-the-fly.
You can do this in a Next.js app by adding the DLS to the
transpilePackages
option in your next.config.js
file.
transpilePackages: ['@actinc/dls'],
You can do this in the Jest test runner by omitting the
DLS from the
transformIgnorePatterns
option in your jest.config.js
file.
transformIgnorePatterns: ['/node_modules/(?!(@actinc/dls)/)'],
Check out the developer guide to learn how to build effectively for the DLS.
To run the DLS locally:
- Install node modules:
npm install
- Start the Storybook component visualizer:
npm start
There are lots of npm scripts at your disposal during local development. Here are some of the more important ones:
Script | Description |
---|---|
npm run build | Transpile DLS from TypeScript (./src ) into ES5 (./dist ). |
npm run build-storybook | Create a static website for deployment (./storybook-static ). |
npm start | Start the Storybook component visualizer. |
npm test | Run all tests. |
npm run release | Publish a new release of the DLS. |
Some npm packages are pinned to non-current versions for a specific reason:
Package | Version | Reason |
---|---|---|
@storybook/mdx2-csf |
0.0.3 |
0.0.4 is not yet compatible with @storybook/addon-docs . |