# 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. 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`, `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. 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
