Dbljump shared design

The shared visual foundations for Dbljump products. The package provides framework-independent design tokens and a canonical home for identity assets used by more than one product.

The visual direction is a stable marine foundation with an electric cyan accent. Bright information, success, warning, and danger colours carry some of the energy of video games while remaining reserved for their semantic roles.

Ownership boundary

If changing an asset should intentionally affect the identity of several Dbljump products, it belongs in shared-design. If it belongs to one product or one page, it stays local.

This repository is for visual foundations, not shared product copy or translations.

Principles

• Use semantic tokens in application code; use primitive palette tokens only when defining or extending the system.
• Keep marine as the primary action and hierarchy colour.
• Use cyan for brand energy, selection, focus, and restrained highlights.
• Use status colours only to communicate status, never as general decoration.
• Pair bright colours with their supplied on-base foreground. Do not assume white text is accessible.
• Do not add raw colour values to application components.
• Add an asset only when it is canonical, reusable, and owned at the Dbljump identity level.

Structure

src/
├── tokens/ Canonical token definitions
└── assets/
├── logos/ Dbljump wordmarks and logo combinations
├── icons/ Shared brand and product icons
└── favicons/ Shared browser and app identity assets

Generated token formats and distributable copies of supported assets live in dist/. Product-specific illustrations, page graphics, and component imagery remain in their product repositories.

Before adding or replacing identity artwork, follow the shared asset specification. It defines the canonical symbol variants, favicon derivatives, file construction rules, and acceptance checks.

Package outputs

Import	Contents
@dbljump/shared-design/css	Theme-aware CSS custom properties
@dbljump/shared-design/scss	Sass variables prefixed with $dbl-
@dbljump/shared-design/json	Resolved token values for tooling
@dbljump/shared-design/assets	JSON manifest of distributed identity assets
@dbljump/shared-design/assets/*	A specific distributed asset

Development

Node 18 or newer is required. There are no third-party dependencies.

npm run build
npm test

Edit token definitions in src/tokens/ or add canonical identity assets to the appropriate directory in src/assets/, then run the build. Supported asset formats are SVG, PNG, WebP, ICO, and JPEG. Generated files in dist/ are committed so that consumers installed from a Git tag do not need to run the generator.

Plain CSS

Import the stylesheet once near the start of an application's CSS:

@import"@dbljump/shared-design/css";
.example {
color:var(--dbl-semantic-color-text-primary);
background:var(--dbl-semantic-color-background-surface);
border-radius:var(--dbl-radius-lg);
}

Semantic colour properties follow a data-theme="light" or data-theme="dark" attribute. Without an explicit attribute, the light theme is the default and prefers-color-scheme: dark is respected. Primitive and theme-specific properties are also available when a semantic role is not appropriate.

Sass

Use the module interface for Dbljump-specific styles:

@use"@dbljump/shared-design/scss"asdbl;
.example {
color: dbl.$dbl-theme-light-color-text-primary;
background: dbl.$dbl-theme-light-color-background-surface;
border-radius: dbl.$dbl-radius-lg;
}

Sass is resolved at build time, so theme-specific colour variables are explicit. Use CSS semantic properties when an interface switches theme at runtime.

Frameworks

Framework mappings belong in consuming applications. This keeps the central vocabulary independent of Bootstrap, Tailwind, Starlight, or any future CSS system.

For example, an application using Bootstrap can define its Sass variables from the light-theme tokens before importing Bootstrap:

@use"@dbljump/shared-design/scss"asdbl;
$primary: dbl.$dbl-theme-light-color-brand-primary;
$success: dbl.$dbl-theme-light-color-status-success-base;
$warning: dbl.$dbl-theme-light-color-status-warning-base;
$danger: dbl.$dbl-theme-light-color-status-danger-base;
@import"bootstrap/scss/bootstrap";

Tailwind applications can reference the generated CSS properties from their theme configuration or CSS theme layer. Keep those version-specific mappings in the application as well.

Typography

Interface and display text prefer Inter. The primitive palette also provides a Source Serif 4 stack for products with a specific serif role. Both stacks include dependable local fallbacks. A consuming application must load the preferred webfonts itself if identical typography across platforms is required; this package does not download or bundle fonts.

The central package intentionally does not assign the serif family a semantic or component role. That decision belongs to the consuming product. For example:

.product-specific-content {
font-family:var(--dbl-font-family-serif);
}

Keeping the token primitive prevents a product-specific meaning from spreading into unrelated applications.

Versioning

• Patch releases correct documentation or generated output.
• Minor releases add tokens, assets, or deliberate backwards-compatible visual adjustments.
• Major releases rename, remove, or structurally change public tokens and asset paths.