Quick Start

Follow this Quick Start to beign using the OLYSENSE Design System (ODS).

Step 1 - Install Icons

At this time, icons must be manully placed in public or assets folders.

Many configurations use a public or assets folders to serve static content, such as images and icons. The Icon component, by default, looks for SVG icons at 'assets/icons/${name}.svg' located in one of these folders. If would like to use a different base path, you can set a different base path using a setBasePath utility function.

The OLYSENSE Design System has an Icon Library that is utilized by our OLYSENSE Design System Components. Once the icons have been downloaded and configured they can be used with the components.

Download Icons

Setting Base Path

If would like to use a different base path, you can use the setBasePath utility function to set a different base path that is appropriate for your configuration. Place your icons in the new path so they can be located at 'assets/icons/${name}.svg' . 


import { setBasePath } from '@ods/components/utilities/base-path';
setBasePath('path/to/your/public/folder/');

Module Federation

If your application is configured using Module Federation, ensure that the icons are shared correctly between federated modules from the host application. Otherwise, the icons may not render as expected in the consuming applications.

Step 2 - Install Components

Using Components
npm install @ods/components

After the installation is complete, the following packages; including theming packages, will be added as dependencies to your package.json.


package.json
"dependencies": {
  "@ods/components": "...",
  "@ods/theme": "...",
  "@ods/design-tokens": "..."
}

Step 3 - Setup Theming

Import Theme Tokens

OLYSENSE Design System components leverage design tokens through CSS Custom Properties. The file below has to be imported at the entry point of your application for our components to render correctly.


index.ts
// Will be deprecated after design token 2.0 migration.
import '@ods/theme/assets/tokens.css';
// Design Tokens 2.0
import '@ods/design-tokens/assets/tokens.css';

Enable Dark Mode (Optional)

To enable dark mode support, add an HTML data attribute data-color or CSS class to the body element of the page. If a data attribute or class is not specified, light mode will be the default.


index.html
<body class="dark">
  ...
</body>


// or


<body data-color='dark'>
  ...
</body>

Step 4 - Use Components

Web Components

If you’re developing in a no-react framework, you’ll want to leverage the ODS Web Components. To do so, import the components in a central location on your project. Usually a barrel file at the root of your project. This should only be imported once in your project. Once imported, the components will be available everywhere.

We also export the prop types for each component to avoid the need of having to define these properties in your application and improve the developer experience.


example.html
<script>
  import { OdsButtonProps } from '@ods/components/web';


  type ButtonVariant = OdsButtonProps['variant'];


  const buttonVariant:ButtonVariant = 'primary'; // valid as primary is a variant type
  const buttonVariant:ButtonVariant = 'other-text'; // invalid as other-text is not a variant type
</script>


<body>
  <ods-button>Click Me</ods-button>
</body>

React Components

You do not have to install the Web Components above if you are using React components.

If you’re using React, import the react components into your project.

We also export the prop types for each component to avoid the need of having to define these properties in your application and improve the developer experience.


example.tsx
import { OdsButton, OdsButtonProps } from "@ods/components/react";


export const ButtonExample = ({
    variant
}: {
    variant: OdsButtonProps['variant']
}) => (
    <OdsButton variant={variant}>
        Primary Button
    </OdsButton>
)

Cherry Picking

If you wish to install a specific component versus all of them at once, you can do so by importing from the component specific path as shown here. This can be beneficial for things like tree shaking, allowing you to potentially increase the performance of your application by reducing the size of a particular page.


page.tsx
// Importing just the React Button Component
import { OdsButton } '@ods/components/react.button';


<OdsButton>Click Me</OdsButton>

Step 5 - Optional

You can install the optional OLYSENSE Design System’s Style Utilities; which includes a wide range of utility classes for layout and typography, that can be used to modify an element’s appearance in your application.

Learn More

Search