# 3D Source UI Component Libraries

> Two Angular UI component libraries by 3D Source: `@3dsource/source-ui-native` (lightweight, zero-dependency UI primitives) and `@3dsource/source-ui` (higher-level components built on Angular CDK/Material). Both use Angular 19+ signals API (`input()`, `output()`), zoneless change detection, `ViewEncapsulation.None`, and CSS custom properties (`--src-*`) for theming.

## Key concepts

- All components use the `src-` selector prefix (e.g. `<src-button>`, `<src-badge>`)
- Inputs use Angular signals: `input()`, `input.required()`, `output()`
- Enum-like inputs are typed as union types derived from `as const` objects (e.g. `SourceButtonAppearanceKeys` = `"plain" | "inline" | "filled" | "default"`)
- Design tokens are SCSS CSS custom properties with `--src-` prefix, organized by category: color (light/dark themes), layout (responsive breakpoints), typeface, UI sizing
- `@3dsource/source-ui` depends on `@3dsource/source-ui-native` — always install both when using source-ui
- Modals have TWO approaches: native `<dialog>`-based via `SourceModalElementService` (source-ui-native, no CDK needed) and CDK Dialog-based via `Dialog.open(SourceModalComponent)` (source-ui, needs `@angular/cdk/dialog`)
- Popovers are opened via `SourcePopoverService`, not template binding
- The library provides TWO levels of styling: Angular Components (with `input()/output()` API) AND CSS-only Source Elements (BEM classes on native HTML tags — no Angular imports needed)
- The `section_3dsourcecom` class must be placed on the root app container element for Source UI styles to apply. Place it on `<app-root>` inner wrapper, the root `<section>`, or `<body>` as a last resort. Do NOT place it on `<html>`. Example: `<body class="section_3dsourcecom">` or `<div class="section_3dsourcecom">` as the first child of `<app-root>`.
- **Dark theme**: add `section_3dsourcecom--dark` class alongside `section_3dsourcecom` to activate the dark color scheme. For CDK overlays, add `cdk-overlay-container--dark` to the overlay container. Toggle between light and dark by adding/removing the `--dark` class. Both light and dark tokens are bundled — no extra import needed.
- **Scrollbar**: global scrollbar styling is applied automatically (`scrollbar-width: thin`). Override with `--srcScrollbarThumbColor` and `--srcScrollbarTrackColor` CSS custom properties on any ancestor element.
- STRICT RULE: Do NOT use Tailwind CSS or any utility-first CSS framework. All styling must use Source UI design tokens (`--src-*` CSS custom properties), Source Element BEM classes (`src-*`), and standard CSS/SCSS. Never generate Tailwind classes (`flex`, `p-4`, `bg-blue-500`, etc.).

## Library selection priority

STRICT RULE: Only install `@3dsource/source-ui` when Angular Material components (form fields, checkbox, radio, select, autocomplete, toggle) or CDK-based features (popover, color-picker, tabs, tooltip, CDK modal) are explicitly needed. Default to `@3dsource/source-ui-native` only.

Choose the appropriate library based on your project type:

1. **Non-Angular projects** (Lovable, Webflow, plain HTML, React, Vue, any non-Angular framework) → Install `@3dsource/source-ui-native` via npm. Import ONLY the compiled CSS file: `@3dsource/source-ui-native/styles/source-ui-native.min.css`. Use Source Elements (BEM CSS classes on native HTML tags). Do NOT install `@3dsource/source-ui` — it requires Angular and will not work.
2. **Angular without CDK/Material** → Install only `@3dsource/source-ui-native`. Use Angular components (`SourceButtonComponent`, `SourceBadgeComponent`, etc.) + Source Elements.
3. **Angular with CDK/Material** → Install both `@3dsource/source-ui-native` and `@3dsource/source-ui`. This gives access to color-picker, popover, tabs, tooltip, CDK modal, and styled Material form fields.

## Libraries

### @3dsource/source-ui-native v3.3.1

Lightweight UI primitives with zero dependencies (only `tslib`). **No Angular peer dependency** — works without Angular entirely. Can be used in any project (React, Vue, plain HTML, Lovable, etc.) by importing just the compiled CSS stylesheet. Includes:
- **Angular Components** (require Angular): badge, banner, button, copyright, divider, hint, icon-button, loading, logo-loading, modal-element, slider
- **Source Elements (CSS-only, no Angular needed)**: badge, banner, button, checkbox, divider, hint, icon-button, input, label, list, modal, radio, select, textarea, toggle — pure CSS classes applied to standard HTML elements

### @3dsource/source-ui v3.2.1

Higher-level components built on top of Angular CDK and Angular Material. **Requires Angular 20+** due to the `ngx-scrollbar` dependency chain. Provides custom styling for Material form fields (input, select, autocomplete, checkbox, radio, toggle) to match the Source UI design system. Peer dependencies: `@3dsource/source-ui-native >=2.0.0`, `@angular/core >=19.0.0`, `@angular/material >=19.0.0`, `ngx-scrollbar >=19.0.0` (effectively requires Angular 20+), `swiper >=11.2.6`. Components: color-picker, popover, slider-group, tabs, tooltip, toastr styling, Material form field styling.

**Important:** When using `@3dsource/source-ui`, you must provide `MAT_FORM_FIELD_DEFAULT_OPTIONS` with `{ appearance: 'outline' }` globally in your app config for correct form field styling.

## Component API reference

Machine-readable JSON API docs for each component. Each file contains: `name`, `selector`, `library`, `kind`, `inputs[]` (with `name`, `type`, `description`, `resolvedValues`, `defaultValue`, `isRequired`, `alias`), `outputs[]`.

### @3dsource/source-ui-native components

- [SourceBadgeComponent API](./docs/api/badge.json): `src-badge` — Inline status indicator. Use for labels, tags, counters, status markers. Supports `context` (info/success/warning/error) and `size` (sm/md/lg).
- [SourceBannerComponent API](./docs/api/banner.json): `src-banner` — Full-width notification bar. Use for page-level alerts, warnings, info messages. Supports `context` variants for severity.
- [SourceButtonComponent API](./docs/api/button.json): `src-button` — Primary interactive element. Use when you need Angular bindings (loading state, disabled via signal, programmatic control). Supports `appearance` (plain/inline/filled/default), `weight` (primary/secondary/ghost), `context` (info/success/error), `size` (sm/md/lg/xl). For simple HTML buttons without Angular — use Source Element `src-button` CSS class instead.
- [SourceCopyrightComponent API](./docs/api/copyright.json): `src-copyright` — "Powered by 3D Source" branding link. Use in footers. Supports `isCollapsed` toggle.
- [SourceDividerComponent API](./docs/api/divider.json): `src-divider` — Visual separator line. Use between content sections or list groups.
- [SourceHintComponent API](./docs/api/hint.json): `src-hint` — Contextual message below form fields or content. Use for validation messages, helper text. Supports `context` for severity (info/success/warning/error).
- [SourceIconButtonComponent API](./docs/api/icon-button.json): `src-icon-button` — Icon-only action button. Use for toolbars, compact actions. Supports `counter` for notification badges, and same appearance/weight/size/context as button. For simple HTML icon buttons — use Source Element `src-icon-button` CSS class instead.
- [SourceLoadingComponent API](./docs/api/loading.json): `src-loading` — Circular SVG progress/loading indicator. Use for inline loading states. Supports `size`, `progress`, custom stroke colors.
- [SourceLogoLoadingComponent API](./docs/api/logo-loading.json): `src-logo-loading` — Full-screen branded loading animation with 3D Source logo. Use for app/page-level loading states.
- [SourceModalElementComponent API](./docs/api/modal-element.json): `src-modal-element` — Lightweight modal using native HTML `<dialog>` element. No Angular CDK dependency. Opened via `SourceModalElementService.open(data)` where `data: SourceModalElementData` configures title, content, context, footer buttons. Requires `<src-overlay-container>` in app root. For advanced modals with CDK Dialog features (custom component projection, scrollbar) — use `SourceModalComponent` from `@3dsource/source-ui`.
- [SourceSliderComponent API](./docs/api/slider.json): `src-slider` — Low-level range slider. Supports horizontal/vertical orientation, ticks, custom thumb template, min/max/step. For slider with input field and units — use `src-slider-group` from `@3dsource/source-ui`.

### @3dsource/source-ui components

- SourceModalComponent: `src-modal` — Full-featured modal using Angular CDK Dialog. Open via `inject(Dialog).open(SourceModalComponent, { data: config })` where `config: SourceModalData`. Supports context variants (info/success/error), grouped footer buttons, custom button configs, ngx-scrollbar. Can also open any custom component as modal: `dialog.open(YourComponent)` with `src-modal` CSS classes for consistent styling.
- [SourceColorPickerComponent API](@3dsource/source-ui/docs/api/color-picker.json): `src-color-picker` — HEX color picker with palette grid and hue slider. Use for color selection in configuration UIs.
- [SourcePopoverTriggerComponent API](@3dsource/source-ui/docs/api/popover-trigger.json): `src-popover-trigger` — Clickable trigger element for popover. Popovers are opened via `SourcePopoverService.open()` passing a component reference and anchor element.
- [SourceSliderGroupComponent API](@3dsource/source-ui/docs/api/slider-group.json): `src-slider-group` — Slider with synchronized numeric input field, unit labels, and range display. Use for numeric value adjustment with precision input. Wraps `src-slider` from source-ui-native.
- [SourceTabsComponent API](@3dsource/source-ui/docs/api/tabs.json): `src-tabs` — Tab container supporting swiper mode (many tabs), full-width, and compact layouts. Contains `src-tab` panels. Uses Swiper for scrollable tab lines.
- [SourceTabLineComponent API](@3dsource/source-ui/docs/api/tab-line.json): `src-tab-line` — Standalone tab navigation bar (without tab panels). Use when you need only the tab line for custom navigation.
- [SourceTabComponent API](@3dsource/source-ui/docs/api/tab.json): `src-tab` — Individual tab panel inside `src-tabs`. Each tab has a label and content projection.
- [SourceTooltipDirective API](@3dsource/source-ui/docs/api/tooltip.json): `[srcTooltip]` — Directive for hover/focus tooltips. Apply to any element: `<button [srcTooltip]="'Help text'">`. Supports position, delay, max-width, custom class.
- [ColorPaletteComponent API](@3dsource/source-ui/docs/api/color-palette.json): `src-color-palette` — Internal: color picker palette grid. Not intended for standalone use.
- [ColorSliderComponent API](@3dsource/source-ui/docs/api/color-slider.json): `src-color-slider` — Internal: color picker hue slider. Not intended for standalone use.

## Source Elements (CSS-only styling)

Source Elements let you style standard HTML elements (`<button>`, `<input>`, `<select>`, etc.) using BEM CSS classes — no Angular component imports needed. Just add the class to a native HTML tag. All styles come from the `source.ui.native.scss` stylesheet.

- [Source Elements API (JSON)](./docs/api/source-elements.json): Machine-readable reference for all CSS-only elements with modifiers, sub-elements, and usage examples.

Use Source Elements when: you don't need Angular signal bindings, you want minimal overhead, or you're prototyping without Angular.

### Badge Element
Apply `src-badge` class to any appropriate HTML tag.
- **Context**: `src-badge--context-default` (default) | `src-badge--context-info` | `src-badge--context-success` | `src-badge--context-warning` | `src-badge--context-attention` | `src-badge--context-error`
- `src-badge__icon` — Prefix/postfix icon wrapper inside badge.
- Customise via CSS custom properties: `--srcBadgeBackgroundColor`, `--srcBadgeTextColor`.

### Banner Element
Apply `src-banner` class to any appropriate HTML tag.
- **Context**: `src-banner--context-info` | `src-banner--context-success` | `src-banner--context-warning` | `src-banner--context-error` | `src-banner--context-critical`
- `src-banner__icon-prefix` — Leading icon slot.
- `src-banner__icon-postfix` — Trailing icon slot (e.g. close button).
- `src-banner__title` — Uppercase bold title within the banner.
- `src-banner__content` — Main body content wrapper.

### Button Element
Apply `src-button` class to any appropriate HTML tag.
- **Weight**: `src-button--primary` | `src-button--secondary` (default) | `src-button--ghost`
- **Appearance**: `src-button--plain` | `src-button--inline`
- **Size**: `src-button--size-sm` | `src-button--size-md` (default) | `src-button--size-lg` | `src-button--size-xl` | `src-button--full-width`
- **Context**: `src-button--context-info` | `src-button--context-success` | `src-button--context-error`
- **State**: `src-button--pressed`
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/SourceButtonElement)

### Checkbox Element
Apply `src-checkbox` class to any appropriate HTML tag.
- `src-checkbox__label` — Text label beside the checkbox.
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/FormElements)

### Divider Element
Apply `src-divider` class to any appropriate HTML tag.
- Customise via CSS custom properties: `--srcDividerColor`, `--srcDividerThickness`, `--srcDividerOffsetTop`, `--srcDividerOffsetBottom`.

### Hint Element
Apply `src-hint` class to any appropriate HTML tag.
- **Context**: `src-hint--context-error` | `src-hint--context-info` | `src-hint--context-success` | `src-hint--error`
- `src-hint__icon` — Prefix icon slot.

### Icon Button Element
Apply `src-icon-button` class to any appropriate HTML tag.
- **Appearance**: `src-icon-button--plain` | `src-icon-button--inline`
- **Weight**: `src-icon-button--primary` | `src-icon-button--secondary` (default) | `src-icon-button--ghost`
- **Size**: `src-icon-button--size-sm` | `src-icon-button--size-md` (default) | `src-icon-button--size-lg` | `src-icon-button--size-xl`
- **Shape**: `src-icon-button--round`
- **Context**: `src-icon-button--context-info` | `src-icon-button--context-success` | `src-icon-button--context-warning` | `src-icon-button--context-error`
- **State**: `src-icon-button--pressed`
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/SourceIconButtonElement)

### Input Element
Apply `src-input` class to any appropriate HTML tag.
- **Weight**: `src-input--primary` (default) | `src-input--secondary` | `src-input--ghost`
- **Size**: `src-input--size-sm` | `src-input--size-md` (default) | `src-input--size-lg` | `src-input--size-xl`
- **Context**: `src-input--context-success` | `src-input--context-error`
- **State**: `src-input--disabled`
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/SourceInputElement)

### Label Element
Apply `src-label` class to any appropriate HTML tag.

### List Element
Apply `src-list` class to any appropriate HTML tag.
- **Size**: `src-list--compact`
- `src-list__item` — The main class for the list item element.
- `src-list__item--flex` — Class modifier for a flex list item. Use this when your content includes an icon or has a more complex structure. You can still style it in your CSS.
- `src-list__item--disabled` — List item disabled state. The "disabled" attribute is also supported.
- `src-list__item--selected` — Selected state for the list item.
- `src-list__item--context-error` — Visually distinct appearance to emphasize a critical action.
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/SourceListElement)

### Modal Element
Apply `src-modal` class to any appropriate HTML tag.
- `src-modal__header` — Header area with bottom border.
- `src-modal__body` — Scrollable content area with padding.
- `src-modal__body--icon` — Two-column grid layout (icon + content).
- `src-modal__icon` — Icon in the first column of icon-body layout.
- `src-modal__title` — Bold title text.
- `src-modal__scroll-box` — Scrollable content area spanning full grid width.
- `src-modal__footer` — Action buttons row, right-aligned, with top border.
- `src-modal__footer-group` — Button group within footer.
- `src-modal__close` — Absolutely positioned close button at top-right.

### Radio Group Element
Apply `src-radio-group` class to any appropriate HTML tag.
- **Layout**: `src-radio-group--horizontal`
- `src-radio` — Flex container for a single radio button. Wraps input[type="radio"] with custom appearance.
- `src-radio__label` — Text label beside the radio button.
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/FormElements)

### Select Element
Apply `src-select` class to any appropriate HTML tag.
- **Weight**: `src-select--primary` (default) | `src-select--secondary` | `src-select--ghost`
- **Size**: `src-select--size-sm` | `src-select--size-md` (default) | `src-select--size-lg` | `src-select--size-xl`
- **Context**: `src-select--context-success` | `src-select--context-error`
- **State**: `src-select--disabled`
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/SourceSelectElement)

### Textarea Element
Apply `src-textarea` class to any appropriate HTML tag.
- **Weight**: `src-textarea--secondary` | `src-textarea--ghost`
- **Size**: `src-textarea--size-sm` | `src-textarea--size-md` (default) | `src-textarea--size-lg` | `src-textarea--size-xl`
- **Context**: `src-textarea--context-success` | `src-textarea--context-error`
- **State**: `src-textarea--disabled`

### Toggle Element
Apply `src-toggle` class to any appropriate HTML tag.
- `src-toggle__label` — Text label beside the toggle.
- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/FormElements)

## Stylesheet import paths

STRICT RULE: Use ONLY the paths listed below. Do NOT fabricate paths like `@3dsource/source-ui-native/src/lib/styles/...` or `dist/...`.

**SCSS import (Angular projects with a builder) — add to your `styles.scss`:**
```
// source-ui-native only:
@use '../node_modules/@3dsource/source-ui-native/styles/source.ui.native.scss' as source-ui-native;

// source-ui-native + source-ui (both):
@use '../node_modules/@3dsource/source-ui-native/styles/source.ui.native.scss' as source-ui-native;
@use '../node_modules/@3dsource/source-ui/styles/source.ui.scss' as source-ui;
```

**Compiled CSS import (non-Angular / CSS-only / no builder) — add to `<head>` or import in your bundler:**
```
node_modules/@3dsource/source-ui-native/styles/source-ui-native.min.css
```

IMPORTANT: SCSS entry files use dots in the name (`source.ui.native.scss`), while compiled CSS uses dashes (`source-ui-native.min.css`). Do not confuse them.

## Icons

The library is icon-agnostic — no icon font is bundled. Icons are projected into components via `<ng-content>` (Angular) or placed directly inside elements (CSS-only).

STRICT RULE: Do NOT use the Material Icons font (`<link href="https://fonts.google.com/icon?family=Material+Icons">` or the `material-icons` CSS class). The font-based icon approach conflicts with Source UI styles. Use **SVG icons** instead.

Recommended icon source: [Material Symbols (Rounded)](https://fonts.google.com/icons?icon.style=Rounded) with settings: Style Rounded, Weight 400, Fill On, Optical size 20dp.

### SVG icon setup (Angular projects)

1. Create an `assets/icons/` folder in your project.
2. Download SVG icons from your design or from [Material Symbols](https://fonts.google.com/icons?icon.style=Rounded).
3. In each SVG file: set `fill="currentColor"` (for CSS color control), remove `width`/`height` attributes, keep `viewBox`.
4. Create an `SvgIconComponent` in your project (this component is NOT part of the library — copy it into your codebase):

```typescript
import { HttpClient } from '@angular/common/http';
import { Component, effect, inject, input, signal, untracked } from '@angular/core';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
import { first } from 'rxjs';

@Component({
  selector: 'src-icon',
  imports: [],
  template: `@if (svg()) {
    <div [innerHTML]="svg()" class="src-icon" [style.--srcIconSize]="size()"></div>
  }`,
  styles: [`
    .src-icon { width: var(--srcIconSize); height: var(--srcIconSize); color: inherit; }
    .src-icon svg { width: 100%; height: 100%; fill: currentColor; }
  `],
})
export class SvgIconComponent {
  name = input<string>('');
  size = input<string>('20px');
  PATH_TO_ICON_FOLDER = 'assets/icons';
  svg = signal<SafeHtml | null>(null);
  http = inject(HttpClient);
  sanitizer = inject(DomSanitizer);

  _ = effect(() => {
    const path = this.PATH_TO_ICON_FOLDER + '/' + this.name() + '.svg';
    untracked(() => {
      this.http.get(path, { responseType: 'text' }).pipe(first()).subscribe({
        next: (rawSvg) => this.svg.set(this.sanitizer.bypassSecurityTrustHtml(rawSvg)),
        error: () => console.warn('Icon "' + this.name() + '" not found at ' + path),
      });
    });
  });
}
```

5. Usage: `<src-icon name="close"></src-icon>`, `<src-icon name="chevron_left" size="32px"></src-icon>`
6. Default size: `20px`. Color inherits from parent element.

### SVG icon setup (non-Angular / CSS-only projects)

Inline the SVG directly in your HTML:
```html
<button class="src-icon-button">
  <svg viewBox="0 0 24 24" fill="currentColor"><path d="..."/></svg>
</button>
```

### Icon design tokens

- `--src-icon-size` — default icon size (16px)
- `--src-icon-default`, `--src-icon-info`, `--src-icon-success`, `--src-icon-error`, `--src-icon-warning` — contextual icon colors

- [Icons documentation](https://preview.3dsource.com/front-libraries/master/#/icons)

## Material Form Components (source-ui)

`@3dsource/source-ui` provides custom styling for Angular Material form fields. These are NOT separate Angular components — the library overrides default Material styles when you import `source.ui.scss`. Styled Material components:
- `<mat-form-field>` with `<input matInput>` — text input
- `<mat-form-field>` with `<mat-select>` — dropdown select
- `<mat-form-field>` with `<input matInput [matAutocomplete]>` — autocomplete
- `<mat-checkbox>` — styled checkbox
- `<mat-radio-group>` / `<mat-radio-button>` — styled radio
- `<mat-slide-toggle>` — styled toggle

All Material form fields support the same sizing system as Source Elements via class modifiers on the `<mat-form-field>` tag. Default size is `md` (no class needed). Context state classes use `--context-` prefix: `--context-success`, `--context-error` (previously `--state-success` / `--state-error`).

- [Demo](https://preview.3dsource.com/front-libraries/master/#/components/FormComponents)

## Full component registry

- [Component Registry](./docs/api/_registry.json): Index of all 20 components across both libraries with selectors, kinds, and JSON file references

## Design tokens

Design tokens are defined as SCSS CSS custom properties with `--src-` prefix. Machine-readable JSON with all 1020 tokens. See "Design system rules" section below for token selection and usage rules.

- [Design Tokens JSON](./docs/design-tokens.json): All tokens grouped by category (primitives, color-light, color-dark, typeface, ui-sm/md/lg/xl, layout-sm/md/lg/xl) with scope and value info
- [Per-category token index](./docs/tokens/_index.json): Load only the token category you need to save context. Categories: primitives, color-light, color-dark, typeface, ui-sm/md/lg/xl, layout-sm/md/lg/xl

Token source files are in `projects/3dsource/source-ui-native/src/lib/styles/variables/`:

- Color tokens: `color/light.scss` (light theme), `color/dark.scss` (dark theme)
- Layout tokens: `layout/_sm.scss`, `layout/_md.scss`, `layout/_lg.scss`, `layout/_xl.scss` (responsive breakpoints)
- UI tokens: `ui/_sm.scss`, `ui/_md.scss`, `ui/_lg.scss`, `ui/_xl.scss` (component sizing per breakpoint)
- Typography tokens: `typeface/web.scss`
- Primitive values: `primitives/primitives.scss`

## Design system rules

Before building custom UI, always search for an existing Source UI component or Source Element with the same semantic meaning. Only create new components as a last resort.

Full design system rules reference: [Design System Rules](./docs/llms-design-rules.md)

### Token selection priority

When styling, follow this priority chain:
1. Use an existing semantic token from `design-tokens.json` (`--src-space-*`, `--src-padding-*`, etc.)
2. If no exact semantic token exists — use the closest primitive from `design-tokens.json`
3. If no primitive fits — use a raw value (px/rem). **A raw value is always better than an invented token.**

STRICT RULE: Never invent a token name that does not exist in `design-tokens.json`.

### Token groups cheat sheet

- **Spacing**: `--src-space-*` (0–96 scale, e.g. `--src-space-4` = 16px)
- **UI sizing**: `--src-padding-*`, `--src-height-*`, `--src-gap-*`, `--src-icon-size`
- **Border radius**: `--src-border-rounded-*` (component-level), `--src-layout-radius-*` (layout-level)
- **Layout**: `--src-layout-padding-(const|var)-*`, `--src-layout-gap-(const|var)-*`, `--src-layout-height-(const|var)-*`
- **Typography**: `--src-font-*` (primitives), `--src-typography-var-*` (responsive composites)

### Responsive: `var` vs `const` tokens

- `var` tokens change by breakpoint (sm/md/lg/xl) — use for adaptive/responsive UI
- `const` tokens stay the same across all screen sizes — use for fixed-size UI
- Example: `--src-layout-padding-var-*` scales with viewport; `--src-layout-padding-const-*` does not

### Semantic color layers

Always use semantic color tokens, not raw color primitives:
- Surfaces: `--src-surface-*` — backgrounds
- Text: `--src-text-*` — font colors
- Icons: `--src-icon-*` — icon fills
- Borders: `--src-border-*` — border colors
- Accents/status: `--src-ui-*` — interactive states, status indicators
- Shadows: `--src-shadow-*` — elevation
- Gradients: `--src-gradient-*`

**Alpha rule**: Alpha tokens (`--src-color-alpha-*`) may only be used as overlays on top of a solid surface layer. Never use alpha as the only background without a solid surface under it.

### Radius hierarchy

Border radius tokens follow a hierarchy: smaller level number = bigger radius. Parent containers must have a larger (or equal) radius than nested children. Use only `--src-border-rounded-*` and `--src-layout-radius-*` tokens.

### Anti-patterns

- Using primitive color tokens (`--src-color-red-500`) for UI instead of semantic tokens (`--src-ui-accent-error`)
- Alpha token as standalone background (no solid surface beneath)
- Mixing `const` and `var` layout tokens in the same adaptive context
- Breaking radius hierarchy (child radius > parent radius)

## Theming: Custom Accent Colors

The accent color palette drives all primary interactive elements (buttons, selections, focus rings, links). You can override the default blue (`#017BFF`) with any brand color.

### How accent colors work

1. **Primitives** define the raw palette in `primitives/primitives.scss`:
   - `--src-color-primary-50` through `--src-color-primary-950` (11 shades)
   - `--src-color-alpha-accent-10` through `--src-color-alpha-accent-400` (5 alpha variants)

2. **Semantic tokens** in `color/light.scss` and `color/dark.scss` reference the primitives:
   - `--src-ui-accent-default: var(--src-ui-accent-default, #017bffff)` (primary action color)
   - `--src-ui-accent-default-hover: var(--src-color-primary-600)` (hover state)
   - `--src-ui-secondary-active: var(--src-color-alpha-accent-50)` (selected backgrounds)
   - etc.

3. **You only override primitives** — semantic mappings stay intact, so all components update automatically.

### Agent instruction: Override accent color

To change the accent color to a custom brand color (e.g. `#FF5722`):

1. Create `_accent-override.scss` in the user's project (NOT in the library):

```scss
// _accent-override.scss
// Custom accent color palette — override Source UI default blue
// Generated from base color: #FF5722
:root {
  // ── primary shades (50=lightest, 950=darkest) ──
  --src-color-primary-50:  #FFF3E0ff;
  --src-color-primary-100: #FFE0B2ff;
  --src-color-primary-200: #FFCC80ff;
  --src-color-primary-300: #FFB74Dff;
  --src-color-primary-400: #FFA726ff;
  --src-color-primary-500: #FF5722ff;  // ← your base color
  --src-color-primary-600: #F4511Eff;
  --src-color-primary-700: #E64A19ff;
  --src-color-primary-800: #D84315ff;
  --src-color-primary-900: #BF360Cff;
  --src-color-primary-950: #7F1D04ff;

  // ── Alpha variants (for backgrounds, hover states) ──
  // Format: base color (#FF5722) + alpha hex suffix
  --src-color-alpha-accent-10:  #FF572214;
  --src-color-alpha-accent-50:  #FF57221f;
  --src-color-alpha-accent-100: #FF572229;
  --src-color-alpha-accent-200: #FF57223d;
  --src-color-alpha-accent-300: #FF572252;
  --src-color-alpha-accent-400: #FF57225c;
}
```

2. Import it in `styles.scss` AFTER the Source UI stylesheets:

```scss
@use '../node_modules/@3dsource/source-ui-native/styles/source.ui.native.scss' as source-ui-native;
@use './accent-override'; // ← after library styles
```

### Palette generation algorithm

From a single base hex color, generate the 50–950 scale using HSL lightness steps:

| Shade | Lightness target |
|-------|-----------------|
| 50    | 95% |
| 100   | 88% |
| 200   | 78% |
| 300   | 68% |
| 400   | 58% |
| 500   | Base color (keep original lightness) |
| 600   | Base lightness − 5% |
| 700   | Base lightness − 12% |
| 800   | Base lightness − 18% |
| 900   | Base lightness − 28% |
| 950   | Base lightness − 40% |

Alpha variants use the base 500 color with these hex alpha suffixes:
- `10` → `14` (8% opacity)
- `50` → `1f` (12% opacity)
- `100` → `29` (16% opacity)
- `200` → `3d` (24% opacity)
- `300` → `52` (32% opacity)
- `400` → `5c` (36% opacity)

### Rules

- **NEVER modify** `primitives.scss`, `light.scss`, or `dark.scss` in the library
- **NEVER modify** semantic tokens — they reference primitives automatically
- The override file MUST be loaded AFTER the library stylesheet
- All 11 shades (50–950) and 6 alpha variants must be defined for full coverage
- Suffix `ff` on hex colors = fully opaque; alpha variants use partial opacity suffixes

## Demo site

- [Live demo site](https://preview.3dsource.com/front-libraries/master/): Interactive examples of all components with live code snippets (uses HashLocationStrategy — routes like `/#/components/SourceButtonComponent`)

## Optional

- [Full documentation](./docs/llms-full.txt): Self-contained comprehensive reference with all component APIs and design tokens inlined — no external links needed

- [Full component registry JSON](./docs/api/_registry.json): Machine-readable index for programmatic discovery
