🎨 Beam Tokens

Design tokens for the Beam Design System with support for CSS, SASS, and CSS-in-JS. Design tokens are the building blocks of UI elements, the smallest pieces of a design system that can be abstracted and reused across a product. They are the visual design atoms that make up molecules, organisms, and templates. ⚛️

🔖 Table of Contents

1. ✨ Features
2. 💻 Installation
3. 🛠️ Usage
   • CSS Usage
   • SCSS/SASS Usage
   • CSS-in-JS Usage
4. 🖌️ Theming
   • Base Theming
   • Accent Theming
   • Product Theming
   • Brand Theming
   • Brand and Accent Theming
   • Headless Typography
5. ⚙️ How It Works

Features

• CSS Variables - Use design tokens as CSS custom properties
• SASS Variables - Import tokens as SASS variables for preprocessing
• CSS-in-JS Support - Direct JavaScript imports for styled-components, Emotion, etc.
• Multiple Themes - Light, dark, accent, product, and brand themes
• Internationalization - Language-specific typography support
• TypeScript Support - Full type definitions for all tokens

Installation

npm install @viasat/beam-tokens

yarn add @viasat/beam-tokens

pnpm add @viasat/beam-tokens

Usage

Beam Tokens are primarily CSS variables that can be used anywhere CSS variables are supported. They provide a consistent way to access design system values across your application.

CSS Usage

Import the tokens CSS file and use them as CSS custom properties:

import '@viasat/beam-tokens/styles.css';

Use Beam Tokens in your CSS file:

.my-class {
  background-color: var(--bm-sem-color-surface-01);
  color: var(--bm-sem-color-text-primary);
}

Load a Beam theme and your custom class into your application:

<div class="bm-light my-class">
  <p>Hello World</p>
</div>

SCSS/SASS Usage

Beam Tokens are also available as SASS variables for preprocessing:

// Import CSS variables (required)
import '@viasat/beam-tokens/styles.css';

// my-file.scss
@use '@viasat/beam-tokens/tokens';

.my-class {
  background-color: tokens.$bm-sem-color-surface-00;
  color: tokens.$bm-sem-color-text-primary;
}

CSS-in-JS Usage

Import tokens as JavaScript variables for use with styled-components, Emotion, and other CSS-in-JS libraries:

// my-file.jsx
import { css } from '@emotion/css';
import styled from 'styled-components';

// Import the tokens
import { bmSemColorSurface00, bmSemColorTextPrimary } from '@viasat/beam-tokens';

// Example with styled-components
export const MyComponent = styled.div`
  background-color: ${bmSemColorSurface00};
  color: ${bmSemColorTextPrimary};
`;

// Example with Emotion
export const myClass = css`
  background-color: ${bmSemColorSurface00};
  color: ${bmSemColorTextPrimary};
`;

Render the component in your application with a Beam theme:

// my-app.jsx
import { MyComponent, myClass } from 'my-file.jsx';

export const MyApp = () => {
  return (
    <div className="bm-light">
      <MyComponent>Hello World</MyComponent>
      <div className={myClass}>Hello again</div>
    </div>
  );
};

Theming

Theming is a core feature of Beam Tokens. We provide a set of themes that can be used to style your application. Each theme is a set of CSS variables that override Beam's default design tokens.

💡 React Users: For React applications, we recommend using the BeamThemeProvider utility component instead of manually managing theme classes. This provides a more robust and type-safe theming experience.

Base Theming

To use a theme, add the theme class to any element in your application. The theme will apply to that element and all its descendants. For application-wide theming, apply the theme class to the root element:

import React from 'react';
import '@viasat/beam-tokens/styles.css';

const App = () => (
  <div className="bm-light">{/* Your application content goes here */}</div>
);

export default App;

For dark mode, use the bm-dark class:

const App = () => (
  <div className="bm-dark">{/* Your application content goes here */}</div>
);

Accent Theming

Accent theming emphasizes a particular color or set of colors in your application. These themes work well for applications that want to highlight specific colors:

import React from 'react';
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-tokens/themes/blue.css';

const App = () => (
  <div className="bm-light bm-blue">{/* Your application content goes here */}</div>
);

Product Theming

Product theming focuses on modifying the shape and spacing of elements rather than colors. This involves adjusting properties such as border radius and spacing to create a distinct style.

Choose between bm-enterprise (default) or bm-consumer themes:

import React from 'react';
import '@viasat/beam-tokens/styles.css';

const App = () => (
  <>
    <div className="bm-light bm-enterprise">{/* Enterprise styling */}</div>
    <div className="bm-light bm-consumer">{/* Consumer styling */}</div>
  </>
);

Brand Theming

Brand theming replaces Viasat branding with your own. These themes apply brand-specific colors, typography, and styling attributes:

import React from 'react';
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-tokens/themes/onefi.css';

const App = () => (
  <div className="bm-light bm-onefi bm-onefi-starlux">
    {/* Your application content goes here */}
  </div>
);

Brand and Accent Theming

Combine brand and accent theming for more customization:

import React from 'react';
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-tokens/themes/blue.css';
import '@viasat/beam-tokens/themes/onefi.css';

const App = () => (
  <div className="bm-light bm-onefi bm-blue">
    {/* Your application content goes here */}
  </div>
);

Headless Typography

Beam Tokens support headless typography, allowing you to override default font styles with custom ones. You can also apply language-specific typography using the bm-lang-[Lang-Code] class or lang="[Lang-Code]" attribute:

import React from 'react';
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-tokens/themes/onefi.css';

const App = () => (
  <>
    {/* Base brand theming */}
    <div className="bm-light bm-onefi bm-onefi-emirates">
      {/* Application content */}
    </div>

    {/* Language-specific fonts */}
    <div lang="ar" className="bm-light bm-onefi bm-onefi-emirates">
      {/* Arabic content */}
    </div>

    {/* Alternative language class */}
    <div className="bm-light bm-lang-ar bm-onefi bm-onefi-emirates">
      {/* Arabic content */}
    </div>
  </>
);

💡 Note: Language codes should follow the ISO 639-1 standard. In some cases, the browser may automatically apply the correct font based on the language attribute.

How It Works

Beam Tokens employs a streamlined process to efficiently manage design tokens from their inception to deployment:

1. Designers define tokens: Using Figma and Token Studio, designers create and define design tokens, committing them to version control with Git. This phase ensures a collaborative and well-documented approach to token creation.

2. GitHub Actions: Upon detecting new tokens, GitHub Actions automatically triggers our token pipeline. This step enables a seamless, automated process for handling new tokens without manual intervention. Only a manual review is required to approve the pull request.

3. Custom Style Dictionary transform and format: The tokens then pass through our custom Style Dictionary transformers, where values are mutated according to project requirements. Formatters output the tokens in the desired format (CSS, SASS, etc.). This phase enables customization and ensures compatibility with various styling approaches.

4. Bundle and deploy: Finally, the newly generated assets are bundled and deployed within this package, readily available for use. This step guarantees that the latest design tokens are accessible and up-to-date for developers.

By following this streamlined process, Beam Tokens ensures a fluid integration of design tokens into your projects, fostering collaboration between designers and developers.

License

MIT © Viasat