@telesign/boreal-style-guidelines

v0.1.0-alpha.0

Published

19 days ago

Base guidelines for boreal - Multi-brand design system (Proximus, Masiv, Telesign, BICS)

Downloads

126

0High
0Medium
0Low

boreal design system design-tokens css-variables scss proximus engage protect connect

Boreal Design System - Style Guidelines

Multi-brand design token system for Proximus, Engage, Protect, and Connect projects.

🎨 Features

Primitive Tokens: Color palettes, spacing, layouts, radii, etc.
Multi-Brand Themes: Support for 4 different brands
CSS Custom Properties: CSS variables that change based on data-theme
SCSS Variables: For use in Stencil components
Configurable Prefix: Easily modify custom property prefix
Automatic Validation: Ensures all generated tokens are valid

✨ What's New in 0.0.2

Stencil Generator: New SCSS variables that wrap CSS custom properties for Stencil integration
Global Generator: Automatically compiles global SCSS files (reset, grid, etc.)
Fixed Variable References: SCSS and CSS outputs now preserve variable references instead of resolving to values
New Package Exports: Added ./stencil, ./scss, and ./scss/global entry points
DTCG Token Format: Supports the Design Token Community Group format ($type/$value), $extensions are automatically ignored
Updated Theme Names: Replaced masiv → engage, telesign → protect, bics → connect
Token Key Sanitization: Underscores in token keys (e.g. font_size) are automatically converted to hyphens (font-size)
@import Ordering: @import statements are placed at the top of generated CSS files

See CHANGELOG.md for complete details.

📦 Installation

This package is part of the Boreal DS monorepo. Install all dependencies from the workspace root:

# From monorepo root
pnpm install

To add a new dependency to this package specifically:

# From monorepo root
pnpm add -D <package> --filter @telesign/boreal-style-guidelines

🔨 Usage

Generate CSS and SCSS Files

pnpm build

This command generates:

dist/css/global.css - Global variables (primitives) + compiled global styles
dist/css/boreal.css - Complete bundle with all themes and global styles
dist/css/theme-{themeName}.css - Individual theme CSS
dist/scss/_index.scss - Main SCSS entry point
dist/scss/variables/_index.scss - SCSS variables
dist/scss/maps/_index.scss - SCSS maps
dist/scss/global/_index.scss - Global SCSS files (reset, etc.)
dist/stencil/_index.scss - Stencil integration (SCSS vars wrapping CSS vars)

Use in HTML

<!DOCTYPE html>
<html data-theme="proximus">
  <head>
    <!-- Option 1: Load complete bundle -->
    <link rel="stylesheet" href="dist/css/boreal.css" />

    <!-- Option 2: Load global + specific theme -->
    <link rel="stylesheet" href="dist/css/global.css" />
    <link rel="stylesheet" href="dist/css/theme-proximus.css" />
  </head>
  <body>
    <div
      style="background: var(--boreal-primary-base); color: var(--boreal-white);"
    >
      Hello Proximus!
    </div>
  </body>
</html>

Switch Themes Dynamically

// Switch to Engage theme
document.documentElement.setAttribute("data-theme", "engage");

// Switch to Protect theme
document.documentElement.setAttribute("data-theme", "protect");

🎯 Available Themes

proximus
engage
protect
connect

🔧 Stencil Integration

Load Global Styles in project you use components, IMPORTANT: the stencil vars point to this.

Go to use in projects to see more options to include in projects

In your src/global/global.css or src/app.css:

/* Load complete bundle with all themes and global styles (reset, etc.) */
@import "@telesign/boreal-style-guidelines/dist/css/boreal.css";

Configure SASS in Stencil

Install SASS (run from monorepo root):

pnpm add -D @stencil/sass --filter @telesign/boreal-web-components

In stencil.config.ts:

import { Config } from "@stencil/core";
import { sass } from "@stencil/sass";

export const config: Config = {
  plugins: [
    sass({
      includePaths: ["node_modules"],
    }),
  ],
  // ... rest of config
};

Use in Projects

Option 1: CSS Variables

my-component.css:

.btn-primary {
  background: var(--boreal-ui-primary);
  color: var(--boreal-white);
  padding: var(--boreal-spacing-s) var(--boreal-spacing-m);
  border-radius: var(--boreal-radius-s);
  border: none;
  cursor: pointer;
  transition: background 0.2s;
}

.btn-primary:hover {
  background: var(--boreal-ui-primary-dark);
}

Option 2: SCSS Variables (Recommended for only one themes and reuse)

my-component.scss:

// Option A: Use main SCSS entry point (includes variables, maps, and global)
@use "@telesign/boreal-style-guidelines/scss" as boreal;

// Option B: Use only variables
@use "@telesign/boreal-style-guidelines/scss/variables" as boreal;

.card {
  background: boreal.$boreal-ui-default;
  border-radius: boreal.$boreal-radius-m;
  padding: boreal.$boreal-spacing-m;
}

Stencil Integration (CSS vars wrapped in SCSS) IMPORTANT: Dev Components

my-component.scss:

@use "@telesign/boreal-style-guidelines/stencil" as boreal;

.card {
  // SCSS variables that reference CSS custom properties
  background: boreal.$boreal-ui-default; // Outputs: var(--boreal-ui-default)
  border-radius: boreal.$boreal-radius-m;
  padding: boreal.$boreal-spacing-m;
}

⚙️ Configuration

Change CSS Variable Prefix

Edit src/config/constants.ts:

export const CSS_VAR_PREFIX = "--boreal-"; // Change to '--br-', '--my-ds-', etc.

Then regenerate:

pnpm build

Package Exports

The package provides several import paths for flexibility:

// CSS imports
import '@telesign/boreal-style-guidelines'; // Main bundle (boreal.css)
import '@telesign/boreal-style-guidelines/css/global'; // Only global styles
import '@telesign/boreal-style-guidelines/css/theme-proximus'; // Specific theme

// SCSS imports
@use '@telesign/boreal-style-guidelines/scss'; // Main SCSS entry (variables + maps + global)
@use '@telesign/boreal-style-guidelines/scss/variables'; // Only variables
@use '@telesign/boreal-style-guidelines/scss/maps'; // Only maps
@use '@telesign/boreal-style-guidelines/scss/global'; // Only global SCSS

// Stencil integration
@use '@telesign/boreal-style-guidelines/stencil'; // SCSS vars wrapping CSS vars

📁 Project Structure

boreal-styleguidelines/
├── src/
│   ├── config/              # Configuration and constants
│   │   ├── constants.ts     # CSS prefix, paths, themes
│   │   └── types.ts         # TypeScript types
│   ├── generators/          # CSS/SCSS generators
│   │   ├── generate.ts      # Main generation script
│   │   ├── css-generator.ts # CSS custom properties generation
│   │   ├── scss-generator.ts # SCSS variables and maps generation
│   │   ├── token-processor.ts # Shared token processing logic
│   │   ├── global-generator.ts # Global SCSS compilation
│   │   └── validate.ts      # Token validation
│   ├── styles/              # Base styles
│   │   └── global/
│   │       └── reset.scss   # CSS Reset
│   └── tokens/              # Design tokens
│       ├── primitives/      # Primitive tokens (colors, spacing, etc.)
│       ├── theme/           # Brand/theme tokens
│       └── usage/           # Usage tokens (semantic)
├── dist/                    # Generated files
│   ├── css/                 # CSS custom properties
│   ├── scss/                # SCSS variables and maps
│   │   ├── _index.scss      # Main SCSS entry point
│   │   ├── variables/       # SCSS variables
│   │   ├── maps/            # SCSS maps
│   │   └── global/          # Global SCSS files
│   └── stencil/             # Stencil integration
│       └── _index.scss      # SCSS vars wrapping CSS vars
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

🔧 Available Scripts

# Clean, generate and validate all styles
pnpm build

# Clean only
pnpm clean

# Generate only
pnpm generate

# Validate generated tokens
pnpm validate

📖 Naming Conventions

CSS Custom Properties

Format: --{prefix}{category}-{subcategory}-{variant}

Examples:

--boreal-primary-base
--boreal-spacing-m
--boreal-neutral-700
--boreal-text-default

SCSS Variables

Format: ${prefix}{category}-{subcategory}-{variant}

Examples:

$boreal-primary-base
$boreal-spacing-m
$boreal-neutral-700

Token Naming Rules

✅ Allowed:

Lowercase letters: a-z
Numbers: 0-9
Hyphens: -

❌ Not Allowed:

Spaces
Parentheses: ( )
Uppercase letters
Special characters

The system automatically sanitizes invalid names:

"ui (components)" → "ui"
"bg (layout)" → "bg"
"base-alt-(text)" → "base-alt"
"font_size" → "font-size"
"line_height" → "line-height"

🎨 Semantic vs Primitive Tokens

Primitives

Base values that don't change between themes (e.g., color.proximus.cobalt.cobalt-50)

Semantic (Usage)

Tokens that reference primitives and change based on theme:

primary-base → {color.proximus.cobalt.cobalt-40} in Proximus theme
text-default → {neutral-700}
bg-primary → {primary-base}

📝 Adding a New Theme

Create src/tokens/theme/new-theme.json using the DTCG format ($type/$value)
Define theme tokens following existing format
Add theme to src/config/constants.ts:

export const THEMES = {
  PROXIMUS: "proximus",
  ENGAGE: "engage",
  PROTECT: "protect",
  CONNECT: "connect",
  NEW_THEME: "new-theme", // ← Add here
} as const;

Rebuild: pnpm build

🧪 Token Validation

The build process automatically validates all generated tokens to ensure:

✅ Valid CSS variable names (no spaces or parentheses)
✅ Valid SCSS variable names
✅ Correct format (--boreal-{name} or $boreal-{name})

Run validation manually:

pnpm validate

Example output:

🔍 Validating generated tokens...

✓ css/global.css - Valid
✓ css/boreal.css - Valid
✓ css/theme-proximus.css - Valid
✓ scss/variables/_primitives.scss - Valid

✅ All tokens are valid!

🎯 Available Token Categories

Colors

Primary, Accent: Brand colors with variants (base, light, lighter, dark, darker)
Semantic: success, danger, warning, information
Neutral: 900, 800, 700, 600, 500, 400, 300, 200, 100, 50
Usage: text, background, UI, icon, stroke
Extended: Additional color palette

Spacing

4xs, 3xs, 2xs, 1xs, xs, s, m, ml, l, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl

Layout

xs, s, m, ml, l, xl, 2xl, 3xl, 4xl, 5xl, 6xl

Border Radius

none, xs2, xs, s, m, l, xl, full

Icons

s, m, l, xl