@3dsource/source-ui-native

A design system foundation for 3D Source applications: standalone Angular components plus a self-contained SCSS style kit that works with any framework.

Overview

The library ships two things:

1. Angular components -- standalone, signal-based, OnPush — ready to drop into any Angular project.
2. SCSS styles & design tokens -- can be imported into React, Vue, plain HTML, or any other stack. You write or copy the markup yourself (snippets available in the demo app), and the styles take care of the rest.

Installation

Requirements:

• Node.js 20 or newer for repository tooling
• Angular >=19.0.0 <23.0.0 when using the Angular components
• RxJS >=7.8.0 <8.0.0

npm install @3dsource/source-ui-native

Angular and RxJS are not declared as package dependencies. Applications using the Angular components must provide compatible Angular and RxJS versions. The SCSS style kit can be consumed without Angular.

AI coding agents

The package ships documentation for coding agents (llms.txt, guides/, docs/) that matches the installed version. To make the agents in your project read it, add the block below to AGENTS.md in the project root. If the project has a CLAUDE.md, also add the line @AGENTS.md to it: Claude Code reads AGENTS.md on its own only when there is no CLAUDE.md.

## 3D Source UI libraries

This project uses `@3dsource/source-ui-native` and, when needed, `@3dsource/source-ui`. Their docs ship inside the packages and match the installed version. Before you write or change UI code that uses them, read the `llms.txt` of each installed package and follow its links (setup, rules, the API of each component you use):

- `node_modules/@3dsource/source-ui-native/llms.txt`
- `node_modules/@3dsource/source-ui/llms.txt`

Search tools usually skip `node_modules`, so open these files by path. The paths start from the folder of the `package.json` that lists `@3dsource/*`. In a monorepo this can be an app folder, not the repository root.

Do not guess component names, inputs or CSS classes. Use only what these files list.

Which package to install:

- By default, only `@3dsource/source-ui-native`.
- Add `@3dsource/source-ui` (always together with `@3dsource/source-ui-native`) only for: breadcrumbs, color picker, popover, slider group, tab line, tooltip, the CDK modal, styled Angular Material form fields, ngx-toastr toasts.
- `@3dsource/source-ui` needs Angular. In a project without Angular, use only the styles of `@3dsource/source-ui-native`. Its `llms.txt` explains how.

If the agent cannot read the files of your project (for example, an AI chat in the browser), give it the public copy of the docs on jsDelivr. Each link is one file with all the guides and the API of the package. For @3dsource/source-ui, give both links, because it works only together with @3dsource/source-ui-native.

• https://cdn.jsdelivr.net/npm/@3dsource/source-ui-native/docs/llms-full.txt
• https://cdn.jsdelivr.net/npm/@3dsource/source-ui/docs/llms-full.txt

The links show the latest release, and for up to 7 days after a new release they can still show the previous one. For the docs of a specific version, add it to the package name, for example @3dsource/source-ui-native@<version>.

Usage

Importing Styles

Add the following import to your main styles file:

@use '../node_modules/@3dsource/source-ui-native/styles/source.ui.native.scss';

Wrap the application (or the area that uses the design system) in the scope class used by the tokens and typography:

<body class="section_3dsourcecom">
  <app-root></app-root>
</body>

Using Components

Import the desired component and add it to your component's imports:

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { SourceButtonComponent } from '@3dsource/source-ui-native';

@Component({
  selector: 'app-example',
  imports: [SourceButtonComponent],
  template: `<src-button weight="primary" size="md">Click Me</src-button>`,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ExampleComponent {}

Available Components

UI Elements

• src-badge - Display badges and tags
• src-banner - Show notification banners
• src-button - Customizable button component
• src-copyright - Display copyright information
• src-divider - Horizontal divider for lists
• src-hint - Show hints or error messages
• src-icon-button - Display icon button
• src-loading - Loading indicator
• src-logo-loading - Loading indicator with logo
• src-modal-native - Modal component and service for simple modals
• src-slider - Simple slider component
• src-tile - Image thumbnail tile for previews, presets, and option selectors
• src-toolbar - CSS-only inline container for grouping buttons
• Basic styles for lists, form elements, overlays

Native modals are opened with SourceModalNativeService. Import SourceOverlayContainerComponent and place <src-overlay-container /> inside the .section_3dsourcecom scope to host them.

Component Examples

Button Component

<src-button weight="primary" size="md">Click Me</src-button>

Badge Component

<src-badge context="info">Info</src-badge>

Loading Component

import { SourceLoadingComponent } from '@3dsource/source-ui-native';

<src-loading [size]="64" backgroundStrokeColor="#e0f8ee" progressStrokeColor="#007a5c" />

Customization

Components can be customized by overriding global CSS variables or by setting values for particular components variables. Whole table of CSS custom properties is available in the documentation site

:root {
  --src-color-primary-500: #3f51b5;
  --src-text-body-main: #fff;
}

.src-button {
  --srcButtonBgColor: #3f51b5;
  --srcButtonBorderRadius: 6px;
  --srcButtonFontColor: #fff;
  --srcButtonPaddings: 8px 16px;
}

You can see all available options and examples in documentation

Browser Support

The demo that exercises these components uses the root Browserslist target baseline widely available on 2026-05-07. The package does not declare a separate browser matrix; the consuming application's Angular/build configuration controls its final browser target.

Repository development

Run commands from the repository root:

pnpm source-ui-native:build
pnpm source-ui-native:compile-styles
pnpm source-ui-native:release:patch

build runs ng-packagr and produces both expanded and minified CSS bundles. The release command performs verification, changes the package version and publishes the verified tarball to npm.