@xplortech/apollo-foundation

v1.0.1

Published

17 days ago

The design tokens for Xplor and Xplor's Apollo design library

0High
0Medium
0Low

Apollo Foundation

This repo and NPM package contain the design tokens for Xplor's Apollo UI framework. Design tokens are low-level variables such as color values, fonts/typefaces, and text styles that help to ensure visual consistency across interfaces and products. Tokens are built per brand and per platform — the package supports the Apollo and Field Edge brands and outputs CSS, SCSS, JavaScript/TypeScript, Android, and iOS artifacts.

While Xplor recommends the use of Apollo components whenever possible, you may also use Apollo Foundation's design tokens directly in your UI for more custom development. The sections below describe how to install the package and set up tokens for each platform.

Installation

npm install @xplortech/apollo-foundation

The package publishes a pre-built build/ directory. Import paths are brand-based: use apollo or field-edge in the path depending on which brand you use.

Usage

Web (CSS)

Use CSS variables in stylesheets or link them in HTML. Variables are namespaced with --xpl- (kebab-case) to avoid conflicts.

Option A — Link in HTML

<link rel="stylesheet" href="node_modules/@xplortech/apollo-foundation/build/apollo/css/variables.css">

Option B — Import in CSS

@import "@xplortech/apollo-foundation/apollo/css/variables.css";

For brands with light/dark mode (e.g. Apollo), two files are built:

variables.css — Class-based: :root for light and .dark { ... } for dark. Add a .dark class on a parent (e.g. <html>) to switch.
variables-media.css — Media-query based: uses @media (prefers-color-scheme: dark). Use this if you prefer system-driven dark mode.

Use the same paths with field-edge for the Field Edge brand (e.g. field-edge/css/variables.css).

Web (SCSS)

Import the SCSS variables into your Sass/SCSS. For brands with light/dark mode you get _variables.scss (class-based) and _variables-media.scss (media-query).

// Class-based light/dark (use .dark on a parent to toggle)
@import "@xplortech/apollo-foundation/apollo/scss/variables";

// Or media-query based
@import "@xplortech/apollo-foundation/apollo/scss/variables-media";

Then use the variables in your styles:

.my-component {
  background: $xpl-color-background-primary;
  padding: $xpl-size-spacing-md;
}

For Field Edge, use field-edge/scss in the import path (e.g. @import "@xplortech/apollo-foundation/field-edge/scss/variables";).

Web (JavaScript / TypeScript)

Import color and font token objects from the brand’s JS build. TypeScript declarations (.d.ts) are included.

import { color } from "@xplortech/apollo-foundation/apollo/js/colors.js";
import { font } from "@xplortech/apollo-foundation/apollo/js/font.js";

With light/dark mode, color tokens expose value.light and value.dark:

// Single value (no mode)
const spacing = font.size.spacing.md.value;

// With mode (e.g. background primary)
const bgLight = color.background.primary.value.light;
const bgDark = color.background.primary.value.dark;

For Field Edge, use field-edge/js in the import path (e.g. @xplortech/apollo-foundation/field-edge/js/colors.js).

Android (Apollo brand)

The Apollo brand builds Android resources and a Kotlin theme. Output is under build/apollo/android/ (not exposed as a package export; use the path inside node_modules or copy the files).

Setup:

Copy (or link) the built files from node_modules/@xplortech/apollo-foundation/build/apollo/android/ into your app:
- colors.xml → app/src/main/res/values/colors.xml
- values-night/colors.xml → app/src/main/res/values-night/colors.xml (dark mode)
- dimens.xml → app/src/main/res/values/dimens.xml
- Theme.kt → your Kotlin source (e.g. com.xplor.apollo.design package)
In your app theme, reference the color and dimension resources (e.g. @color/xpl_*, @dimen/xpl_*) or use Theme.kt (e.g. ApolloTheme.colors.backgroundPrimary) in code.

Field Edge does not produce Android output (it targets React Native); use the web or iOS outputs for Field Edge.

iOS (Apollo and Field Edge)

The build outputs Swift files under build/{brand}/ios/. Apollo also gets legacy StyleDictionaryColor.swift and StyleDictionaryFont.swift; all brands get Theme.swift with a nested token structure and light/dark support.

Setup:

Copy the Swift files from node_modules/@xplortech/apollo-foundation/build/apollo/ios/ (or build/field-edge/ios/) into your Xcode project.
Add the files to your app target so they compile with your project.
Use the Theme enum (and, for Apollo, StyleDictionaryColor / StyleDictionarySize) in Swift:

// Theme (all brands)
view.backgroundColor = Theme.color.background.primary.value

// Apollo legacy
label.textColor = StyleDictionaryColor.red700

Variable naming

CSS and SCSS variables use the prefix --xpl- (or $xpl- in SCSS) and kebab-case. The pattern is --xpl-{category}-{path}, e.g. --xpl-color-background-primary, --xpl-size-spacing-md. For full token semantics and structure, see the Figma documentation.

For contributors

Scripts

npm run build — Build all tokens for all brands and platforms.
npm run dev — Watch src/tokens and rebuild on changes.
npm run clean — Remove the build/ directory.
npm run test — Run tests.
npm run test:coverage — Run tests with coverage.

Token source layout

src/tokens/global/ — Shared tokens (color palettes, font, size, etc.) used across brands.
src/tokens/brands/{brand}/ — Brand-specific tokens (e.g. apollo/color/light, apollo/color/dark, apollo/font). Light/dark directories under color enable mode-specific CSS/SCSS/JS and native outputs.
src/tokens/platforms/{platform}/ — Platform-specific overrides or additions (e.g. css/, scss/, js/, android/, ios/).

The builder uses Style Dictionary and runs once per brand and per platform; mode detection (light/dark) is inferred from the presence of brands/{brand}/color/light and color/dark.

More info

Design tokens in this package align with the Apollo Foundation Figma documentation.