# @3dsource/source-ui-native

> All local file paths in this document are relative to the package root (`@3dsource/source-ui-native/`).


> Lightweight UI primitives with no Angular or RxJS package dependencies (only `tslib`). Can be used in any project (React, Vue, plain HTML, Lovable, etc.) by importing just the compiled CSS stylesheet. Applications using the Angular components provide Angular and RxJS themselves. Angular components use signals API (`input()`, `output()`), `OnPush` change detection, `ViewEncapsulation.None`, and CSS custom properties (`--src-*`) for theming.

For breadcrumbs, color picker, popover, slider group, tab line, tooltip, the CDK modal, styled Angular Material form fields and ngx-toastr toasts, see the companion library `@3dsource/source-ui`.

Rules that apply to every task — the guides below explain each one:

- Import the stylesheet first: `@use '../node_modules/@3dsource/source-ui-native/styles/source.ui.native.scss' as source-ui-native;` in Angular, or `@3dsource/source-ui-native/styles/source-ui-native.min.css` anywhere else. Use only the documented paths.
- Put the `section_3dsourcecom` class on the element that wraps the whole app (never on `<html>`); add `section_3dsourcecom--dark` beside it for the dark theme.
- Native modals need `<src-overlay-container>` once in the root component's template.
- Use default input values (size, appearance, weight, context) unless asked otherwise. Where both a component (`<src-button>`) and an element class (`.src-button`) exist, either works: keep to the form the project already uses. Layout and form plumbing (`src-form`, `src-label`, `src-list`) exist only as element classes.
- Style only with `--src-*` design tokens and `src-*` classes: no Tailwind or other utility CSS, no `all: unset`, no invented token names.
- Customize a component in this order: inputs first, then its camelCase custom properties (like `--srcDividerColor`) on the inner `.src-*` element (`.src-divider { ... }` in global styles or `.my-block ::ng-deep .src-divider { ... }` in a component; on the component tag they have no effect), and plain CSS overrides only when both are not enough.
- Use SVG icons with `fill="currentColor"`; never the Material Icons font or the `material-icons` class. `<src-icon>` in the examples is an icon component that the app creates, as [Icons](./guides/icons.md) shows; the library has none.
- Bind test ids as a property: `[data-testid]="'save'"`, not `data-testid="save"`.

## Setup

Complete these steps when adding Source UI to a new app. Order matters — nothing renders correctly without steps 1 and 2.

1. **Import the stylesheet.** Use only the two files below. The SCSS entry uses dots (`source.ui.native.scss`), the compiled CSS uses dashes (`source-ui-native.min.css`).

   For Angular projects, add to `styles.scss`:

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

   The path is relative to the importing file: from `src/styles.scss` it is `../node_modules/...`. Add `../` until it reaches `node_modules`, e.g. `../../../node_modules/...` from `projects/app/src/styles.scss`.

   For non-Angular / CSS-only projects, link `node_modules/@3dsource/source-ui-native/styles/source-ui-native.min.css` from `<head>`, or import it in your bundler by package specifier: `import '@3dsource/source-ui-native/styles/source-ui-native.min.css';` (the package `exports` map exposes `./styles/*`, and CSS/SCSS files are declared as side effects, so bundlers keep the import). In a TypeScript file, if `tsc` reports TS2882 for this import, add `declare module '*.css';` to a `.d.ts` file.

2. **Add the `section_3dsourcecom` root class.** Put it on an element that wraps your whole app — inner `<app-root>` wrapper, a root `<section>`, or `<body>` as a last resort. NOT on `<html>`. Example:

   ```html
   <body class="section_3dsourcecom">
     ...
   </body>
   ```

   Without this class the base reset, typography, scrollbar styles and the page background (`--src-surface-background`) do not apply. Design tokens (declared on `:root`) and element classes are global, but the reset this class scopes also sets `box-sizing: border-box`. Without the class, elements with `width: 100%` and padding grow wider than their container (a `.src-input` in a 300px box renders 322px wide), so always add it.

3. **Place `<src-overlay-container>` in the root component's template** if the app uses the native modal (`SourceModalNativeService`). Angular only creates components inside the root component, so the tag does nothing in `index.html`. Add `SourceOverlayContainerComponent` (from `@3dsource/source-ui-native`) to the root component's `imports` and the tag once, at the end of its template:

   ```html
   <!-- app.component.html -->
   <div class="section_3dsourcecom">
     <router-outlet />
     <src-overlay-container />
   </div>
   ```

   `SourceModalNativeService.open(...)` attaches into this container; without it, `open()` throws "SourceOverlayContainerComponent is not registered". No other API currently uses this container (popovers, CDK Dialog, and ngx-toastr all bypass it).

   If the app disables CDK popovers (`{ provide: OVERLAY_DEFAULT_CONFIG, useValue: { usePopover: false } }`), also provide `{ provide: SOURCE_MODAL_USE_TOP_LAYER, useValue: false }` from `@3dsource/source-ui-native`. Otherwise CDK overlays (for example `mat-select`) opened inside a native modal render behind it: the modal sits in the browser top layer, the overlays do not.

4. **(Optional) Enable dark theme.** Add `section_3dsourcecom--dark` alongside `section_3dsourcecom` to switch to dark tokens. Both light and dark token sets are bundled — no extra import. Toggle by adding/removing the `--dark` class at runtime. CDK overlays (the CDK modal, popover, tooltip, Material panels from `@3dsource/source-ui`) render outside that element, so also add `cdk-overlay-container--dark` to the CDK overlay container while the dark theme is on.

5. **(If using `@3dsource/source-ui`)** Install it as a peer of `@3dsource/source-ui-native` and follow the [@3dsource/source-ui setup guide](../source-ui/guides/setup.md) for Angular Material / CDK prerequisites (providers).

## Key concepts

- All components use the `src-` selector prefix (e.g. `<src-button>`, `<src-badge>`)
- Angular component imports: `import { SourceButtonComponent } from '@3dsource/source-ui-native'` or `import { SourcePopoverTriggerComponent } from '@3dsource/source-ui'`. All components are exported from the package root — no deep import paths.
- 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 `--src-*` CSS custom properties: [Design tokens](#design-tokens).
- Every component with a `testID` input binds it to the rendered element as `data-testid` (`<src-modal-native>` takes it as `data.testID` in the modal config; `<src-overlay-container>` has none). Bind it as a property, `[data-testid]="'save'"`: a static `data-testid="save"` also stays on the host element, so tests find two elements.
- 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): [Using Source Elements](#using-source-elements).
- Modals use the native `<dialog>`: open them with `SourceModalNativeService.open<R, D>(component, config)`. Pass `SourceModalNativeComponent` for the built-in chrome, `SourceModalComponent` from `@3dsource/source-ui` for the CDK chrome, or your own component. Prefer it over the CDK `Dialog` for new code. Old names `SourceModalElement*` are deprecated aliases of `*Native*`.
  - Never put `<src-modal-native>` in a template: open it only through `SourceModalNativeService`.
  - Every footer button closes the modal with the value its `action()` returns. For forms or validation, open a custom component.
  - `afterClosed()` emits that value, or `undefined` after Esc, a backdrop click or the header close button.
  - A custom component template starts with `.src-modal`: the service already provides the `<dialog>`.
  - Examples and all fields: [SourceModalNativeComponent API](./docs/components/modal-native.md).
- Where to put the `section_3dsourcecom` root class and how to turn on the dark theme: [Setup](#setup), steps 2 and 4.
- **Customizing a component**, in this order:
  1. Its inputs (`size`, `appearance`, `context` and so on).
  2. Its custom properties (camelCase, like `--srcDividerColor`). They are declared on the component's inner `.src-*` element, so a value set on the component tag or on a parent is replaced there. Override them on that element: `.src-divider { --srcDividerLength: 120px; }` in global styles, or `.my-block ::ng-deep .src-divider { --srcDividerLength: 120px; }` in your component.
  3. Plain CSS rules, only if the first two are not enough.
- **Scrollbar**: global scrollbar styling is applied automatically (`scrollbar-width: thin`). Override `--srcScrollbarThumbColor` and `--srcScrollbarTrackColor` on the `section_3dsourcecom` element or on any element inside it; above it they have no effect, because that class declares them.
- 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.).
- STRICT RULE: Do NOT use `all: unset` to reset browser defaults. It also unsets `box-sizing: border-box` and causes layout bugs. Reset defaults explicitly (e.g. `appearance: none; background: none; border: none; padding: 0; margin: 0; font: inherit; color: inherit; cursor: pointer;`).

## Components

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.

If a user asks for "a button", "a card", "a table row", "a sidebar item", etc:

1. Search for an existing component with the same meaning
2. If exact match is missing, pick the closest semantic match
3. Only create new components as a last resort

- **Angular Components** (require Angular): badge, banner, button, copyright, divider, hint, icon-button, loading, logo-loading, modal-native, overlay-container, slider, tile
- **Source Elements (CSS-only, no Angular needed)**: badge, banner, breadcrumbs, button, button-group, checkbox, divider, form, hint, icon-button, input, label, list, modal, radio, select, textarea, tile, toggle, toolbar — pure CSS classes applied to standard HTML elements

## Using Source Elements

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.

**Where both a component and an element exist** (`<src-button>` and `.src-button`, `<src-icon-button>` and `.src-icon-button`, …), either works: keep to the form the project already uses, so the markup stays consistent. Layout and form plumbing (`src-form`, `src-form__item`, `src-label`, `src-list`) exist only as element classes. CSS-only elements are also the only option for projects without Angular.

**Defaults rule:** Always use default property values (size, appearance, weight, context) unless the user explicitly requests otherwise. Do not assume non-default values based on visual context — the defaults are intentional.

**Button-group rule:** All buttons inside a `.src-button-group` must share the same size — whether set via `size` attribute (Angular components) or `--size-*` class modifier (CSS elements). Mixing sizes breaks visual alignment.

## Forms

### Form field

Every form field follows: label + control + hint (optional).

```html
<div class="src-form__item">
  <label class="src-label" for="email">Email</label>
  <input
    id="email"
    type="email"
    class="src-input"
    placeholder="name@example.com"
  />
  <p class="src-hint">We will never share your email.</p>
</div>
```

Error state:

```html
<div class="src-form__item">
  <label class="src-label" for="username">Username</label>
  <input
    id="username"
    type="text"
    class="src-input src-input--context-error"
    placeholder="Enter username"
  />
  <p class="src-hint src-hint--context-error" role="alert" aria-live="assertive">
    Minimum 3 characters required.
  </p>
</div>
```

In Angular, prefer `<src-hint context="error">`: it sets these attributes itself. Its `id` input goes on the inner `<p>`, so the control can point at it with `aria-describedby`.

Works the same with `src-select` and `src-textarea` instead of `src-input`.

### Form layout

`.src-form` is the **required wrapper** for any form. It provides a flex-column layout with consistent gaps. All form content goes inside it.

**Structure:** `.src-form` > `.src-form__row` > `.src-form__item` (label + control + hint).

Available children of `.src-form`:

- `.src-form__item` — flex-column container for one field (label + control + hint). Can be placed directly in `.src-form` or inside a `.src-form__row`
- `.src-form__row` — grid row, single column by default. Wraps one or more `.src-form__item`
- `.src-form__row--double` — modifier for two-column grid row
- `.src-form__row--triple` — modifier for three-column grid row
- `.src-form__row-group` — groups consecutive rows under a common title. Contains `.src-form__row-group-label` + one or more `.src-form__row`
- `.src-form__row-group-label` — title/label for a row group. No predefined styles — apply `.src-label` or your own class for styling
- `.src-form__button-row` — right-aligned row for action buttons at the bottom of the form

```html
<form class="src-form">
  <div class="src-form__row src-form__row--double">
    <div class="src-form__item">
      <label class="src-label" for="first">First name</label>
      <input id="first" type="text" class="src-input" placeholder="John" />
    </div>
    <div class="src-form__item">
      <label class="src-label" for="last">Last name</label>
      <input id="last" type="text" class="src-input" placeholder="Doe" />
    </div>
  </div>
  <div class="src-form__row">
    <div class="src-form__item">
      <label class="src-label" for="bio">Bio</label>
      <textarea
        id="bio"
        class="src-textarea"
        rows="3"
        placeholder="Tell us about yourself..."
      ></textarea>
    </div>
  </div>
  <div class="src-form__button-row">
    <src-button appearance="plain" weight="ghost" (onClick)="cancel()"
      >Cancel</src-button
    >
    <src-button weight="primary" (onClick)="save()">Save</src-button>
  </div>
</form>
```

Custom properties: `--srcFormRowGap` (gap between rows, default 16px), `--srcFormItemsGap` (gap between items in a row, default 12px), `--srcFormOffset` (padding for focus outlines).

### Checkbox, radio, and toggle in forms

```html
<div class="src-form__item">
  <label class="src-checkbox">
    <input type="checkbox" />
    <span class="src-checkbox__label">Subscribe to newsletter</span>
  </label>
</div>

<div class="src-form__item">
  <div class="src-label" id="plan-label">Plan</div>
  <div class="src-radio-group" role="radiogroup" aria-labelledby="plan-label">
    <label class="src-radio">
      <input type="radio" name="plan" value="free" checked />
      <span class="src-radio__label">Free</span>
    </label>
    <label class="src-radio">
      <input type="radio" name="plan" value="pro" />
      <span class="src-radio__label">Professional</span>
    </label>
  </div>
</div>

<div class="src-form__item">
  <label class="src-toggle">
    <input type="checkbox" />
    <span class="src-toggle__label">Enable notifications</span>
  </label>
</div>
```

Keep `.src-radio` inside `.src-radio-group`: the group declares the border and colors of the radio. Add `.src-radio-group--horizontal` to put the radios in a row.

## Typography

Source UI provides CSS classes for consistent text styling. Apply them to any HTML element. Native heading tags (`h1`–`h6`) are also styled automatically.

Primary typeface: Inter (imported in the stylesheet).

### When to use what

- **Headings** (`src-headings-*`): Page-level titles only. These are large and should NOT be used for card titles, accordion headers, or panel labels.
- **Titles** (`src-title-*`): Card headers, accordion titles, sidebar sections, panel headers, group labels — any UI chrome that needs emphasis but is not a page-level heading.
- **Body** (`src-body-*`): Default reading text with compact line-height. Use for UI text, descriptions, paragraphs.
- **Body Relaxed** (`src-body-relaxed-*`): Same sizes as Body but with increased line-height. Use for long-form content, help text, articles.
- **Labels** (`src-label-*`): Medium-weight text for links, navigation items, UI controls. Not the same as the `src-label` form element class.

### Scale reference

Headings (semibold, header font; `h1`–`h6` and `src-headings-*` have `margin: 0`, so add the spacing below them yourself):

- `src-headings-4xl` (= `h1`) — page title
- `src-headings-3xl` — large section header
- `src-headings-2xl` (= `h2`) — section header
- `src-headings-xl` (= `h3`) — subsection header
- `src-headings-lg` (= `h4`) — smallest heading, use sparingly

Titles (semibold):

- `src-title-md` (= `h5`) — card/panel header
- `src-title-base` (= `h6`) — dialog and popover title, accordion title, sidebar section header
- `src-title-sm` — compact title, toolbar label
- `src-title-xs` — uppercase technical label (auto text-transform)

Body (regular weight):

- `src-body-md` — primary UI text (16px)
- `src-body-base` — default body text (14px)
- `src-body-sm` — secondary/small text (12px)

Body Relaxed (regular weight, taller line-height):

- `src-body-relaxed-md`, `src-body-relaxed-base`, `src-body-relaxed-sm`

Labels (medium weight):

- `src-label-xl`, `src-label-lg`, `src-label-md`, `src-label-sm`, `src-label-tech` (uppercase)

Prefer applying the class. If you must reproduce one in custom SCSS, take the tokens from this table: the class suffix is not the token suffix.

| Class | font-size | line-height |
| --- | --- | --- |
| `src-title-md` | `--src-font-size-md` (20px) | `--src-font-line-md` (28px) |
| `src-title-base` | `--src-font-size-base` (16px) | `--src-font-line-base` (24px) |
| `src-title-sm` | `--src-font-size-sm` (14px) | `--src-font-line-sm` (20px) |
| `src-title-xs` | `--src-font-size-tech` (9px) | `--src-font-line-xs` (16px) |
| `src-body-md` | `--src-font-size-base` (16px) | `--src-font-line-base` (24px) |
| `src-body-base` | `--src-font-size-sm` (14px) | `--src-font-line-sm` (20px) |
| `src-body-sm` | `--src-font-size-xs` (12px) | `--src-font-line-xs` (16px) |
| `src-body-relaxed-md` | `--src-font-size-base` (16px) | `--src-font-line-md` (28px) |
| `src-body-relaxed-base` | `--src-font-size-sm` (14px) | `--src-font-line-base` (24px) |
| `src-body-relaxed-sm` | `--src-font-size-xs` (12px) | `--src-font-line-sm` (20px) |
| `src-label-xl` | `--src-font-size-md` (20px) | `--src-font-line-md` (28px) |
| `src-label-lg` | `--src-font-size-base` (16px) | `--src-font-line-base` (24px) |
| `src-label-md` | `--src-font-size-sm` (14px) | `--src-font-line-sm` (20px) |
| `src-label-sm` | `--src-font-size-xs` (12px) | `--src-font-line-xs` (16px) |
| `src-label-tech` | `--src-font-size-tech` (9px) | `--src-font-line-xs` (16px) |

STRICT RULE: Do NOT use deprecated classes `src-heading-h1`..`src-heading-h6` or `src-heading-massive`.

### Text colors

Not all text should be the same color. Use semantic text tokens:

Body text (content areas):

- `--src-text-body-main` — primary text (headings, important content)
- `--src-text-body-secondary` — supporting text (descriptions, subtitles)
- `--src-text-body-grey` — muted text (placeholders, timestamps)
- `--src-text-body-lable` — form labels, captions
- `--src-text-body-disabled` — disabled state

Semantic body colors:

- `--src-text-body-accent` — links, interactive text
- `--src-text-body-success` — success messages
- `--src-text-body-destruct` — error messages, destructive text

UI text (buttons, controls, navigation on colored backgrounds):

- `--src-text-ui-secondary-main` — primary UI text on neutral background
- `--src-text-ui-secondary-secondary` — secondary UI text on neutral background
- `--src-text-ui-primary-main` — text on primary/accent-colored backgrounds
- `--src-text-ui-accent-main` / `--src-text-ui-success-main` / `--src-text-ui-distruct-main` / `--src-text-ui-warning-main` — colored interactive text

Inverted (for dark backgrounds in light theme, or vice versa):

- `--src-text-body-main-invert`, `--src-text-body-secondary-invert`
- `--src-text-ui-primary-main-invert`, `--src-text-ui-secondary-main-invert`

STRICT RULE: Do NOT use raw hex colors for text. Always use `--src-text-*` tokens. They adapt automatically to light/dark theme.

### Icon colors

Icons have their own color tokens. Do not reuse `--src-text-*` for icons — icon tokens have different values optimized for icon contrast.

- `--src-icon-default` — standard icon color (slightly lighter than body text)
- `--src-icon-label` — muted icon next to labels
- `--src-icon-hover` — icon on hover
- `--src-icon-grey` — decorative/disabled-looking icons
- `--src-icon-disabled` — disabled state

Semantic:

- `--src-icon-info` / `--src-icon-info-hover`
- `--src-icon-success` / `--src-icon-success-hover`
- `--src-icon-error` / `--src-icon-error-hover`
- `--src-icon-warning` / `--src-icon-warning-hover`
- `--src-icon-attention` / `--src-icon-attention-hover`

Inverted (for dark/colored backgrounds):

- `--src-icon-main-invert`, `--src-icon-secondary-invert`

Fallback: if a specific icon token doesn't exist for your case, `color: inherit` from the parent text color is acceptable. But prefer `--src-icon-*` tokens when available.

## Surfaces and shadows

### Surface hierarchy

The interface is built around layered surfaces that create structure and depth.

**Page background:**

- `--src-surface-background` — the application canvas behind everything. The library paints it on the element with `section_3dsourcecom`. If that element must stay transparent, for example when your UI lies over other content, add `.section_3dsourcecom { background-color: transparent; }` to your styles.

**Container surfaces (cards, panels, sections):**

- `--src-surface-container-main` — primary container (white in light theme). Use for cards, panels, main content areas.
- `--src-surface-container-secondary` — alternate container for less prominent areas (sidebars, alternate sections).
- `--src-surface-container-on-top` — semi-transparent alpha surface (8% opacity in light, 4% in dark). Use it only as a soft fill on top of another surface, for example a hover state or the track of the pill tab line. It is never the only background of a panel.

**Floating surfaces:**

- Popovers, modals and other floating panels use `--src-surface-container-main` with a shadow.
- The dimmed backdrop behind a modal uses `--src-surface-curtain`.

**Semantic surfaces (feedback containers):**

- `--src-surface-container-info` — informational context (light blue)
- `--src-surface-container-success` — success feedback (light green)
- `--src-surface-container-error` — error feedback (light red)

**Nesting rule:** Semantic surfaces (info, success, error) can be nested inside primary or secondary containers. Give the nested surface its matching border: `--src-border-infoPrompt-info`, `--src-border-infoPrompt-success` or `--src-border-infoPrompt-error`. The outer container keeps `--src-border-container-basic`.

**Container styling:** Containers use the border `--src-border-container-basic`. Take the radius and padding from the Padding and Border radius tables in [Design tokens](#design-tokens): a card uses `--src-layout-radius-const-rounded` (8px) and `--src-layout-padding-const-lg` (16px).

### Shadows

Shadows use two color tokens combined at different offsets to create elevation. Do NOT write raw `box-shadow` values with hex colors — always use `--src-shadow-*` color tokens.

**Color tokens:**

- `--src-shadow-light` — the lower-opacity shadow color
- `--src-shadow-hard` — the higher-opacity shadow color
- `--src-shadow-accent-light` — the accent (blue) color of the focus ring
- `--src-shadow-focused` — the width of the focus ring (4px)

**Elevation levels:**

Elevation follows a strict hierarchy tied to how "above" the page an element appears. Higher = closer to the user = bigger shadow. Do not mix levels — a dropdown should never have a bigger shadow than the modal it sits inside.

| Level | Use for | box-shadow |
| --- | --- | --- |
| xs | Cards and panels sitting on the page. | `0 1px 2px 1px var(--src-shadow-light, rgba(148, 163, 184, 0.16))` |
| sm | Toolbars; the thumbs of sliders and toggles. | `0 4px 12px 0 var(--src-shadow-light, rgba(148, 163, 184, 0.16)), 0 0 2px 0 var(--src-shadow-hard, rgba(71, 85, 105, 0.24))` |
| md | Popovers, the breadcrumbs overflow panel, other panels that float over a section. | `0 2px 8px 0 var(--src-shadow-light, rgba(148, 163, 184, 0.16)), 0 8px 24px 0 var(--src-shadow-hard, rgba(71, 85, 105, 0.24))` |
| lg | Modals, dialogs, full-screen overlays. The highest elevation. | `0 1px 4px 0 var(--src-shadow-light, rgba(148, 163, 184, 0.16)), 0 16px 36px 4px var(--src-shadow-hard, rgba(71, 85, 105, 0.24))` |

**Rule:** If the element is part of the page flow, use xs. Toolbars use sm. Popovers and panels that float over a section use md. If it blocks the whole page, use lg. When unsure, default to xs — most custom containers only need xs.

**Active and focused elements** get a focus ring, not a bigger shadow: `box-shadow: 0 0 0 var(--src-shadow-focused, 4px) var(--src-shadow-accent-light, rgba(1, 123, 255, 0.16))`, as in `.src-tile--active` and the focus state of inputs, radios and checkboxes.

**Additional semantic shadows:**

- `--src-shadow-success` / `--src-shadow-success-hover` — success state glow
- `--src-shadow-error` / `--src-shadow-error-hover` — error state glow

## 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 `public/assets/icons/` (new CLI projects serve `public/`; in projects with `src/assets`, use `src/assets/icons/`). The service requests `assets/icons/<name>.svg`.
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 a root `SvgIconService` that fetches each icon once, caches it, and de-duplicates concurrent requests for the same icon. The icons are the project's own files, so the service marks them as trusted with `bypassSecurityTrustHtml`; do not point it at external URLs. On Angular 19 and 20, add `provideHttpClient()` to the app providers. (This service is NOT part of the library — copy it into your codebase.)

```typescript
import { HttpClient } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import type { SafeHtml } from '@angular/platform-browser';
import type { Observable } from 'rxjs';
import { catchError, map, of, shareReplay } from 'rxjs';

@Injectable({
  providedIn: 'root',
})
export class SvgIconService {
  #http = inject(HttpClient);
  sanitizer = inject(DomSanitizer);
  #PATH_TO_ICON_FOLDER = 'assets/icons';

  #cache = new Map<string, Observable<SafeHtml>>();

  get(name: string): Observable<SafeHtml> {
    const path = `${this.#PATH_TO_ICON_FOLDER}/${name}.svg`;

    if (!this.#cache.has(name)) {
      this.#cache.set(
        name,
        this.#http.get(path, { responseType: 'text' }).pipe(
          map((rawSvg) => this.sanitizer.bypassSecurityTrustHtml(rawSvg)),
          catchError((err) => {
            this.#cache.delete(name);
            console.warn(`Icon "${name}" not found at ${path}. ${err.message}`);
            return of(this.sanitizer.bypassSecurityTrustHtml(''));
          }),
          shareReplay(1),
        ),
      );
    }

    return this.#cache.get(name)!;
  }
}
```

5. Create an `SvgIconComponent` that delegates to the service (also NOT part of the library — copy it into your codebase):

```typescript
import { Component, inject, input } from '@angular/core';
import { toObservable, toSignal } from '@angular/core/rxjs-interop';
import { switchMap } from 'rxjs';
import { SvgIconService } from './svg-icon.service';

@Component({
  selector: 'src-icon',
  template: `
    <div
      [innerHTML]="svg()"
      [style.--srcIconSize]="size()"
      class="src-icon"
    ></div>
  `,
  styles: `
    .src-icon {
      width: var(--srcIconSize);
      height: var(--srcIconSize);
      color: inherit;
    }
  `,
})
export class SvgIconComponent {
  readonly name = input<string>('');
  readonly size = input<string>('100%');
  #svgIconService = inject(SvgIconService);
  readonly svg = toSignal(
    toObservable(this.name).pipe(
      switchMap((name) => this.#svgIconService.get(name)),
    ),
    { initialValue: '' },
  );
}
```

6. Usage: `<src-icon name="close"></src-icon>`, `<src-icon name="chevron_left" size="32px"></src-icon>`
7. Default size: `100%` (the icon fills its slot); inside the default md components this resolves to about `20px`. Color inherits from the parent element.

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

Inline the SVG directly in your HTML:

```html
<button class="src-icon-button" aria-label="Settings">
  <svg viewBox="0 0 24 24" fill="currentColor"><path d="..." /></svg>
</button>
```

### Icon design tokens

- `--src-icon-size` — default icon size (20px, `var(--src-space-5)`)
- `--src-icon-default`, `--src-icon-info`, `--src-icon-success`, `--src-icon-error`, `--src-icon-warning` — contextual icon colors

## Design Tokens (inline)

> Auto-generated from 1029 total tokens. Below is a curated subset of semantic tokens most useful for development. Full token data: one file per category in docs/tokens/.

### primitives (scope: global)
Source: `variables/primitives/primitives.scss`

| Token | Value |
|-------|-------|
| --src-space-0 | 0px |
| --src-space-px | 1px |
| --src-space-0-5 | 2px |
| --src-space-1 | 4px |
| --src-space-1-5 | 6px |
| --src-space-2 | 8px |
| --src-space-2-5 | 10px |
| --src-space-3 | 12px |
| --src-space-3-5 | 14px |
| --src-space-4 | 16px |
| --src-space-5 | 20px |
| --src-space-6 | 24px |
| --src-space-7 | 28px |
| --src-space-8 | 32px |
| --src-space-9 | 36px |
| --src-space-10 | 40px |
| --src-space-11 | 44px |
| --src-space-12 | 48px |
| --src-space-14 | 56px |
| --src-space-16 | 64px |
| --src-space-20 | 80px |
| --src-space-24 | 96px |
| --src-space-28 | 112px |
| --src-space-32 | 128px |
| --src-space-36 | 144px |
| --src-space-40 | 160px |
| --src-space-44 | 176px |
| --src-space-48 | 192px |
| --src-space-52 | 208px |
| --src-space-56 | 224px |
| --src-space-60 | 240px |
| --src-space-64 | 256px |
| --src-space-72 | 288px |
| --src-space-80 | 320px |
| --src-space-96 | 384px |
| --src-color-primary-50 | #f1f6ffff |
| --src-color-primary-100 | #d6e9ffff |
| --src-color-primary-200 | #add4ffff |
| --src-color-primary-300 | #7dbbffff |
| --src-color-primary-400 | #4ea4ffff |
| --src-color-primary-500 | #017bffff |
| --src-color-primary-600 | #016fe6ff |
| --src-color-primary-700 | #0162ccff |
| --src-color-primary-800 | #014ca3ff |
| --src-color-primary-900 | #003a7aff |
| --src-color-primary-950 | #00244dff |
| --src-color-alpha-accent-10 | #017bff14 |
| --src-color-alpha-accent-50 | #017bff1f |
| --src-color-alpha-accent-100 | #017bff29 |
| --src-color-alpha-accent-200 | #017bff3d |
| --src-color-alpha-accent-300 | #017bff52 |
| --src-color-alpha-accent-400 | #017bff5c |

### color-light (scope: global)
Source: `variables/color/light.scss`

| Token | Value |
|-------|-------|
| --src-surface-background | var(--src-color-grey-50) |
| --src-surface-background-inverse | var(--src-color-grey-800) |
| --src-ui-accent-default | var(--src-color-primary-500) |
| --src-ui-accent-default-hover | var(--src-color-primary-600) |
| --src-ui-accent-disabled | var(--src-color-alpha-test-200) |
| --src-ui-accent-success | var(--src-color-green-500) |
| --src-ui-accent-success-hover | var(--src-color-green-600) |
| --src-ui-accent-error | var(--src-color-red-500) |
| --src-ui-accent-error-hover | var(--src-color-red-600) |
| --src-ui-accent-active | var(--src-color-grey-700) |
| --src-ui-accent-active-hover | var(--src-color-grey-900) |
| --src-ui-secondary-default | var(--src-color-alpha-default-10) |
| --src-ui-secondary-default-hover | var(--src-color-alpha-default-50) |
| --src-ui-secondary-disabled | var(--src-color-alpha-white-10) |
| --src-ui-secondary-active | var(--src-color-alpha-accent-50) |
| --src-ui-secondary-info | var(--src-color-alpha-accent-10) |
| --src-ui-secondary-info-hover | var(--src-color-alpha-accent-50) |
| --src-ui-secondary-success | var(--src-color-alpha-success-10) |
| --src-ui-secondary-success-hover | var(--src-color-alpha-success-50) |
| --src-ui-secondary-error | var(--src-color-alpha-destruct-10) |
| --src-ui-secondary-error-hover | var(--src-color-alpha-destruct-100) |
| --src-ui-secondary-progress | var(--src-color-alpha-warning-10) |
| --src-ui-input-default | var(--src-color-alpha-white-10) |
| --src-ui-input-secondary | var(--src-color-alpha-default-10) |
| --src-ui-input-hover | var(--src-color-alpha-accent-10) |
| --src-ui-input-disabled | var(--src-color-alpha-default-50) |
| --src-ui-input-success | var(--src-color-alpha-white-10) |
| --src-ui-input-success-hover | var(--src-color-alpha-success-10) |
| --src-ui-input-error | var(--src-color-alpha-white-10) |
| --src-ui-input-error-hover | var(--src-color-alpha-destruct-10) |
| --src-surface-curtain | var(--src-color-alpha-default-600) |
| --src-surface-fade | var(--src-color-alpha-white-600) |
| --src-surface-bg | var(--src-color-alpha-default-200) |
| --src-ui-light | var(--src-light) |
| --src-border-control-default | var(--src-color-neutral-300) |
| --src-border-control-hover | var(--src-color-neutral-500) |
| --src-border-button-basic | var(--src-color-grey-200) |
| --src-border-button-basic-hover | var(--src-color-grey-400) |
| --src-border-button-info | var(--src-color-primary-300) |
| --src-border-button-info-hover | var(--src-color-primary-500) |
| --src-border-button-success | var(--src-color-green-400) |
| --src-border-button-success-hover | var(--src-color-green-500) |
| --src-border-button-error | var(--src-color-red-300) |
| --src-border-button-error-hover | var(--src-color-red-500) |
| --src-border-button-disabled | var(--src-color-grey-200) |
| --src-border-input-basic | var(--src-color-grey-300) |
| --src-border-input-hover | var(--src-color-grey-400) |
| --src-border-input-filled | var(--src-color-grey-300) |
| --src-border-input-active | var(--src-color-primary-500) |
| --src-border-input-success | var(--src-color-green-500) |
| --src-border-input-success-hover | var(--src-color-green-600) |
| --src-border-input-error | var(--src-color-red-500) |
| --src-border-input-error-hover | var(--src-color-red-500) |
| --src-border-container-basic | var(--src-color-grey-300) |
| --src-border-container-hover | var(--src-color-grey-400) |
| --src-border-container-light | var(--src-color-alpha-default-50) |
| --src-border-container-active | var(--src-color-primary-400) |
| --src-border-container-success | var(--src-color-green-200) |
| --src-border-container-error | var(--src-color-red-200) |
| --src-text-body-main | var(--src-color-grey-900) |
| --src-text-body-secondary | var(--src-color-grey-600) |
| --src-text-body-grey | var(--src-color-grey-400) |
| --src-text-body-lable | var(--src-color-grey-500) |
| --src-text-body-disabled | var(--src-color-grey-400) |
| --src-text-body-main-invert | var(--src-color-grey-50) |
| --src-text-body-secondary-invert | var(--src-color-grey-300) |
| --src-icon-default | var(--src-color-grey-700) |
| --src-icon-label | var(--src-color-grey-500) |
| --src-icon-hover | var(--src-color-grey-900) |
| --src-icon-grey | var(--src-color-grey-400) |
| --src-icon-disabled | var(--src-color-grey-400) |
| --src-icon-main-invert | var(--src-light) |
| --src-icon-secondary-invert | var(--src-color-grey-200) |
| --src-icon-info | var(--src-color-primary-500) |
| --src-icon-info-hover | var(--src-color-primary-600) |
| --src-icon-success | var(--src-color-green-600) |
| --src-icon-success-hover | var(--src-color-green-700) |
| --src-icon-error | var(--src-color-red-500) |
| --src-icon-error-hover | var(--src-color-red-600) |
| --src-icon-warning | var(--src-color-tertiary-600) |
| --src-icon-warning-hover | var(--src-color-tertiary-700) |
| --src-icon-attention | var(--src-color-yellow-800) |
| --src-icon-attention-hover | var(--src-color-yellow-900) |
| --src-graphics-positive | var(--src-color-green-500) |
| --src-graphics-negative | var(--src-color-red-500) |
| --src-graphics-accent | var(--src-color-primary-500) |
| --src-graphics-dark-grey | var(--src-color-grey-500) |
| --src-graphics-orange | #f5a80fff |
| --src-graphics-yellow | #f0e442ff |
| --src-graphics-turquoise | #00ced1ff |
| --src-graphics-brown | #8b4513ff |
| --src-graphics-black | var(--src-color-grey-700) |
| --src-text-body-accent | var(--src-color-primary-600) |
| --src-text-body-success | var(--src-color-green-600) |
| --src-text-body-destruct | var(--src-color-red-600) |
| --src-text-ui-primary-main | var(--src-light) |
| --src-text-ui-primary-secondary | var(--src-color-grey-200) |
| --src-text-ui-primary-disabled | var(--src-color-grey-400) |
| --src-text-ui-primary-main-invert | var(--src-color-grey-50) |
| --src-text-ui-primary-secondary-invert | var(--src-color-grey-200) |
| --src-text-ui-secondary-main | var(--src-color-grey-900) |
| --src-text-ui-secondary-secondary | var(--src-color-grey-600) |
| --src-text-ui-secondary-grey | var(--src-color-grey-400) |
| --src-text-ui-secondary-disabled | var(--src-color-grey-400) |
| --src-text-ui-secondary-main-invert | var(--src-color-grey-50) |
| --src-text-ui-secondary-secondary-invert | var(--src-color-grey-300) |
| --src-shadow-hard | var(--src-color-alpha-test-200) |
| --src-shadow-light | var(--src-color-alpha-default-50) |
| --src-shadow-accent-light | var(--src-color-alpha-accent-100) |
| --src-shadow-accent-hard | var(--src-color-alpha-accent-200) |
| --src-shadow-success | var(--src-color-alpha-success-50) |
| --src-shadow-success-hover | var(--src-color-alpha-success-200) |
| --src-shadow-error | var(--src-color-alpha-destruct-100) |
| --src-shadow-error-hover | var(--src-color-alpha-destruct-200) |
| --src-text-ui-accent-main | var(--src-color-primary-600) |
| --src-text-ui-accent-hover | var(--src-color-primary-700) |
| --src-text-ui-success-main | var(--src-color-green-600) |
| --src-text-ui-success-hover | var(--src-color-green-700) |
| --src-text-ui-distruct-main | var(--src-color-red-500) |
| --src-text-ui-distruct-hover | var(--src-color-red-600) |
| --src-surface-container-main | var(--src-light) |
| --src-surface-container-on-top | var(--src-color-alpha-default-10) |
| --src-surface-container-secondary | var(--src-color-grey-50) |
| --src-surface-container-info | var(--src-color-primary-50) |
| --src-surface-container-success | var(--src-color-green-50) |
| --src-surface-container-error | var(--src-color-red-50) |
| --src-surface-toast-basic | var(--src-color-alpha-default-50) |
| --src-surface-toast-info | var(--src-color-primary-600) |
| --src-surface-toast-success | var(--src-color-green-600) |
| --src-surface-toast-error | var(--src-color-red-500) |
| --src-border-infoPrompt-basic | var(--src-color-grey-300) |
| --src-border-infoPrompt-light | var(--src-color-alpha-default-50) |
| --src-border-infoPrompt-info | var(--src-color-primary-200) |
| --src-border-infoPrompt-success | var(--src-color-green-200) |
| --src-border-infoPrompt-error | var(--src-color-red-200) |
| --src-gradient-light-start | var(--src-color-alpha-test-100) |
| --src-gradient-light-end | var(--src-color-alpha-default-10) |
| --src-gradient-accent-light | var(--src-color-alpha-accent-10) |
| --src-gradient-accent-hard | var(--src-color-alpha-accent-50) |
| --src-gradient-success | var(--src-color-alpha-success-50) |
| --src-gradient-success-hover | var(--src-color-alpha-success-200) |
| --src-gradient-error | var(--src-color-alpha-destruct-100) |
| --src-gradient-error-hover | var(--src-color-alpha-destruct-200) |
| --src-tech-sticker | var(--src-color-tertiary-100) |
| --wireframe-main | var(--src-color-neutral-600) |
| --wireframe-secondary | var(--src-color-neutral-500) |
| --wireframe-light | var(--src-color-neutral-300) |
| --wireframe-surface-primary | var(--src-light) |
| --wireframe-surface-secondary | var(--src-color-alpha-default-50) |
| --wireframe-border | var(--src-color-alpha-default-200) |
| --wireframe-invert | var(--src-light) |
| --src-tech-description | var(--src-color-tertiary-900) |
| --src-light | #ffffffff |
| --src-dark | #000000ff |
| --src-ui-status-basic-neutral | var(--src-color-grey-500) |
| --src-ui-status-basic-neutral-hover | var(--src-color-grey-600) |
| --src-ui-status-basic-critical | var(--src-color-red-500) |
| --src-ui-status-basic-critical-hover | var(--src-color-red-600) |
| --src-ui-status-basic-info | var(--src-color-primary-500) |
| --src-ui-status-basic-info-hover | var(--src-color-primary-600) |
| --src-ui-status-basic-success | var(--src-color-green-500) |
| --src-ui-status-basic-success-hover | var(--src-color-green-500) |
| --src-ui-status-basic-warning | var(--src-color-tertiary-500) |
| --src-ui-status-basic-warning-hover | var(--src-color-tertiary-600) |
| --src-ui-status-basic-attention | var(--src-color-yellow-500) |
| --src-ui-status-basic-attention-hover | var(--src-color-yellow-600) |
| --src-ui-status-light-neutral | var(--src-color-alpha-default-100) |
| --src-ui-status-light-neutral-hover | var(--src-color-alpha-default-200) |
| --src-ui-status-light-critical | var(--src-color-alpha-destruct-100) |
| --src-ui-status-light-critical-hover | var(--src-color-alpha-destruct-200) |
| --src-ui-status-light-info | var(--src-color-alpha-accent-200) |
| --src-ui-status-light-info-hover | var(--src-color-alpha-accent-300) |
| --src-ui-status-light-success | var(--src-color-alpha-success-100) |
| --src-ui-status-light-success-hover | var(--src-color-alpha-success-200) |
| --src-ui-status-light-warning | var(--src-color-alpha-warning-200) |
| --src-ui-status-light-warning-hover | var(--src-color-alpha-warning-300) |
| --src-ui-status-light-attention | var(--src-color-alpha-attention-200) |
| --src-ui-status-light-attention-hover | var(--src-color-alpha-attention-300) |
| --src-text-ui-warning-main | var(--src-color-tertiary-600) |
| --src-text-ui-warning-hover | var(--src-color-tertiary-700) |
| --src-text-ui-attention-main | var(--src-color-yellow-800) |
| --src-text-ui-attention-hover | var(--src-color-yellow-900) |

### color-dark (scope: .section_3dsourcecom--dark, .cdk-overlay-container--dark)
Source: `variables/color/dark.scss`

| Token | Value |
|-------|-------|
| --src-surface-background | var(--src-color-grey-900) |
| --src-surface-background-inverse | var(--src-color-grey-50) |
| --src-ui-accent-default | var(--src-color-primary-400) |
| --src-ui-accent-default-hover | var(--src-color-primary-500) |
| --src-ui-accent-disabled | var(--src-color-alpha-white-100) |
| --src-ui-accent-success | var(--src-color-green-600) |
| --src-ui-accent-success-hover | var(--src-color-green-500) |
| --src-ui-accent-error | var(--src-color-red-600) |
| --src-ui-accent-error-hover | var(--src-color-red-500) |
| --src-ui-accent-active | var(--src-color-grey-200) |
| --src-ui-accent-active-hover | var(--src-color-grey-50) |
| --src-ui-secondary-default | var(--src-color-alpha-white-50) |
| --src-ui-secondary-default-hover | var(--src-color-alpha-default-100) |
| --src-ui-secondary-disabled | var(--src-color-alpha-default-100) |
| --src-ui-secondary-active | var(--src-color-alpha-accent-100) |
| --src-ui-secondary-info | var(--src-color-alpha-accent-200) |
| --src-ui-secondary-info-hover | var(--src-color-alpha-accent-100) |
| --src-ui-secondary-success | var(--src-color-alpha-success-200) |
| --src-ui-secondary-success-hover | var(--src-color-alpha-success-50) |
| --src-ui-secondary-error | var(--src-color-alpha-destruct-200) |
| --src-ui-secondary-error-hover | var(--src-color-alpha-destruct-100) |
| --src-ui-secondary-progress | var(--src-color-alpha-warning-10) |
| --src-ui-input-default | var(--src-color-alpha-white-10) |
| --src-ui-input-secondary | var(--src-color-alpha-default-200) |
| --src-ui-input-hover | var(--src-color-alpha-default-200) |
| --src-ui-input-disabled | var(--src-color-alpha-default-200) |
| --src-ui-input-success | var(--src-color-alpha-white-10) |
| --src-ui-input-success-hover | var(--src-color-alpha-success-50) |
| --src-ui-input-error | var(--src-color-alpha-white-10) |
| --src-ui-input-error-hover | var(--src-color-alpha-destruct-50) |
| --src-surface-curtain | var(--src-color-alpha-default-600) |
| --src-surface-fade | var(--src-color-alpha-default-200) |
| --src-surface-bg | var(--src-color-alpha-white-50) |
| --src-ui-light | var(--src-dark) |
| --src-border-control-default | var(--src-color-neutral-300) |
| --src-border-control-hover | var(--src-color-neutral-100) |
| --src-border-button-basic | var(--src-color-grey-600) |
| --src-border-button-basic-hover | var(--src-color-grey-500) |
| --src-border-button-info | var(--src-color-primary-500) |
| --src-border-button-info-hover | var(--src-color-primary-400) |
| --src-border-button-success | var(--src-color-green-700) |
| --src-border-button-success-hover | var(--src-color-green-600) |
| --src-border-button-error | var(--src-color-red-500) |
| --src-border-button-error-hover | var(--src-color-red-600) |
| --src-border-button-disabled | var(--src-color-grey-800) |
| --src-border-input-basic | var(--src-color-grey-700) |
| --src-border-input-hover | var(--src-color-grey-500) |
| --src-border-input-filled | var(--src-color-grey-700) |
| --src-border-input-active | var(--src-color-primary-500) |
| --src-border-input-success | var(--src-color-green-600) |
| --src-border-input-success-hover | var(--src-color-green-400) |
| --src-border-input-error | var(--src-color-red-700) |
| --src-border-input-error-hover | var(--src-color-red-700) |
| --src-border-container-basic | var(--src-color-grey-800) |
| --src-border-container-hover | var(--src-color-grey-600) |
| --src-border-container-light | var(--src-color-alpha-white-50) |
| --src-border-container-active | var(--src-color-primary-500) |
| --src-border-container-success | var(--src-color-green-800) |
| --src-border-container-error | var(--src-color-red-800) |
| --src-text-body-main | var(--src-color-grey-50) |
| --src-text-body-secondary | var(--src-color-grey-300) |
| --src-text-body-grey | var(--src-color-grey-400) |
| --src-text-body-lable | var(--src-color-grey-300) |
| --src-text-body-disabled | var(--src-color-grey-500) |
| --src-text-body-main-invert | var(--src-color-grey-900) |
| --src-text-body-secondary-invert | var(--src-color-grey-600) |
| --src-icon-default | var(--src-color-grey-200) |
| --src-icon-label | var(--src-color-grey-400) |
| --src-icon-hover | var(--src-color-grey-50) |
| --src-icon-grey | var(--src-color-grey-400) |
| --src-icon-disabled | var(--src-color-grey-500) |
| --src-icon-main-invert | var(--src-light) |
| --src-icon-secondary-invert | var(--src-color-grey-200) |
| --src-icon-info | var(--src-color-primary-500) |
| --src-icon-info-hover | var(--src-color-primary-400) |
| --src-icon-success | var(--src-color-green-500) |
| --src-icon-success-hover | var(--src-color-green-400) |
| --src-icon-error | var(--src-color-red-400) |
| --src-icon-error-hover | var(--src-color-red-300) |
| --src-icon-warning | var(--src-color-tertiary-400) |
| --src-icon-warning-hover | var(--src-color-tertiary-300) |
| --src-icon-attention | var(--src-color-yellow-400) |
| --src-icon-attention-hover | var(--src-color-yellow-600) |
| --src-graphics-positive | var(--src-color-green-400) |
| --src-graphics-negative | var(--src-color-red-400) |
| --src-graphics-accent | var(--src-color-primary-500) |
| --src-graphics-dark-grey | var(--src-color-grey-400) |
| --src-graphics-orange | #ffb92dff |
| --src-graphics-yellow | #f0e442ff |
| --src-graphics-turquoise | #00ced1ff |
| --src-graphics-brown | #8b4513ff |
| --src-graphics-black | var(--src-color-grey-200) |
| --src-text-body-accent | var(--src-color-primary-400) |
| --src-text-body-success | var(--src-color-green-400) |
| --src-text-body-destruct | var(--src-color-red-400) |
| --src-text-ui-primary-main | var(--src-light) |
| --src-text-ui-primary-secondary | var(--src-color-grey-200) |
| --src-text-ui-primary-disabled | var(--src-color-grey-400) |
| --src-text-ui-primary-main-invert | var(--src-color-grey-900) |
| --src-text-ui-primary-secondary-invert | var(--src-color-grey-700) |
| --src-text-ui-secondary-main | var(--src-color-grey-50) |
| --src-text-ui-secondary-secondary | var(--src-color-grey-200) |
| --src-text-ui-secondary-grey | var(--src-color-grey-400) |
| --src-text-ui-secondary-disabled | var(--src-color-grey-500) |
| --src-text-ui-secondary-main-invert | var(--src-color-grey-900) |
| --src-text-ui-secondary-secondary-invert | var(--src-color-grey-600) |
| --src-shadow-hard | var(--src-color-alpha-dark-100) |
| --src-shadow-light | var(--src-color-alpha-dark-50) |
| --src-shadow-accent-light | var(--src-color-alpha-accent-300) |
| --src-shadow-accent-hard | var(--src-color-alpha-accent-400) |
| --src-shadow-success | var(--src-color-alpha-success-200) |
| --src-shadow-success-hover | var(--src-color-alpha-success-50) |
| --src-shadow-error | var(--src-color-alpha-destruct-200) |
| --src-shadow-error-hover | var(--src-color-alpha-destruct-100) |
| --src-text-ui-accent-main | var(--src-color-primary-400) |
| --src-text-ui-accent-hover | var(--src-color-primary-300) |
| --src-text-ui-success-main | var(--src-color-green-400) |
| --src-text-ui-success-hover | var(--src-color-green-300) |
| --src-text-ui-distruct-main | var(--src-color-red-400) |
| --src-text-ui-distruct-hover | var(--src-color-red-300) |
| --src-surface-container-main | var(--src-color-grey-800) |
| --src-surface-container-on-top | var(--src-color-alpha-white-10) |
| --src-surface-container-secondary | var(--src-color-grey-950) |
| --src-surface-container-info | var(--src-color-blue-950) |
| --src-surface-container-success | var(--src-color-green-950) |
| --src-surface-container-error | var(--src-color-red-950) |
| --src-surface-toast-basic | var(--src-color-alpha-default-200) |
| --src-surface-toast-info | var(--src-color-primary-400) |
| --src-surface-toast-success | var(--src-color-green-400) |
| --src-surface-toast-error | var(--src-color-red-400) |
| --src-border-infoPrompt-basic | var(--src-color-grey-800) |
| --src-border-infoPrompt-light | var(--src-color-alpha-white-50) |
| --src-border-infoPrompt-info | var(--src-color-primary-800) |
| --src-border-infoPrompt-success | var(--src-color-green-800) |
| --src-border-infoPrompt-error | var(--src-color-red-800) |
| --src-gradient-light-start | var(--src-color-alpha-dark-200) |
| --src-gradient-light-end | var(--src-color-alpha-dark-100) |
| --src-gradient-accent-light | var(--src-color-alpha-accent-300) |
| --src-gradient-accent-hard | var(--src-color-alpha-accent-400) |
| --src-gradient-success | var(--src-color-alpha-success-200) |
| --src-gradient-success-hover | var(--src-color-alpha-success-50) |
| --src-gradient-error | var(--src-color-alpha-destruct-200) |
| --src-gradient-error-hover | var(--src-color-alpha-destruct-100) |
| --src-tech-sticker | var(--src-color-tertiary-800) |
| --wireframe-main | var(--src-color-neutral-300) |
| --wireframe-secondary | var(--src-color-neutral-400) |
| --wireframe-light | var(--src-color-neutral-500) |
| --wireframe-surface-primary | var(--src-dark) |
| --wireframe-surface-secondary | var(--src-color-alpha-white-50) |
| --wireframe-border | var(--src-color-alpha-white-100) |
| --wireframe-invert | var(--src-dark) |
| --src-tech-description | var(--src-color-tertiary-50) |
| --src-light | #ffffffff |
| --src-dark | #000000ff |
| --src-ui-status-basic-neutral | var(--src-color-alpha-white-100) |
| --src-ui-status-basic-neutral-hover | var(--src-color-alpha-white-600) |
| --src-ui-status-basic-critical | var(--src-color-alpha-destruct-100) |
| --src-ui-status-basic-critical-hover | var(--src-color-alpha-destruct-50) |
| --src-ui-status-basic-info | var(--src-color-alpha-accent-300) |
| --src-ui-status-basic-info-hover | var(--src-color-alpha-accent-200) |
| --src-ui-status-basic-success | var(--src-color-alpha-success-200) |
| --src-ui-status-basic-success-hover | var(--src-color-alpha-success-100) |
| --src-ui-status-basic-warning | var(--src-color-alpha-warning-300) |
| --src-ui-status-basic-warning-hover | var(--src-color-alpha-warning-200) |
| --src-ui-status-basic-attention | var(--src-color-alpha-attention-300) |
| --src-ui-status-basic-attention-hover | var(--src-color-alpha-attention-200) |
| --src-ui-status-light-neutral | var(--src-color-alpha-white-100) |
| --src-ui-status-light-neutral-hover | var(--src-color-alpha-white-600) |
| --src-ui-status-light-critical | var(--src-color-alpha-destruct-200) |
| --src-ui-status-light-critical-hover | var(--src-color-alpha-destruct-100) |
| --src-ui-status-light-info | var(--src-color-alpha-accent-300) |
| --src-ui-status-light-info-hover | var(--src-color-alpha-accent-200) |
| --src-ui-status-light-success | var(--src-color-alpha-success-200) |
| --src-ui-status-light-success-hover | var(--src-color-alpha-success-100) |
| --src-ui-status-light-warning | var(--src-color-alpha-warning-300) |
| --src-ui-status-light-warning-hover | var(--src-color-alpha-warning-200) |
| --src-ui-status-light-attention | var(--src-color-alpha-attention-300) |
| --src-ui-status-light-attention-hover | var(--src-color-alpha-attention-200) |
| --src-text-ui-warning-main | var(--src-color-tertiary-400) |
| --src-text-ui-warning-hover | var(--src-color-tertiary-500) |
| --src-text-ui-attention-main | var(--src-color-tertiary-200) |
| --src-text-ui-attention-hover | var(--src-color-tertiary-100) |

### typeface (scope: global)
Source: `variables/typeface/web.scss`

| Token | Value |
|-------|-------|
| --src-font-family-header | Inter |
| --src-font-family-body | Inter |
| --src-font-family-mono | PT Mono |
| --src-font-weight-bold | Bold |
| --src-font-weight-semiBold | SemiBold |
| --src-font-weight-medium | Medium |
| --src-font-weight-regular | Regular |
| --src-font-size-tech | 9px |
| --src-font-size-xs | 12px |
| --src-font-size-sm | 14px |
| --src-font-size-base | 16px |
| --src-font-size-md | 20px |
| --src-font-size-lg | 24px |
| --src-font-size-xl | 28px |
| --src-font-size-2xl | 32px |
| --src-font-size-3xl | 40px |
| --src-font-line-tech | 12px |
| --src-font-size-4xl | 48px |
| --src-font-line-xs | 16px |
| --src-font-line-sm | 20px |
| --src-font-line-base | 24px |
| --src-font-line-md | 28px |
| --src-font-line-lg | 32px |
| --src-font-line-xl | 36px |
| --src-font-line-2xl | 44px |
| --src-font-line-3xl | 52px |
| --src-font-line-4xl | 56px |
| --src-font-spacing-tech | 1.2000000476837158px |
| --src-font-spacing-xl | -0.20000000298023224px |
| --src-font-spacing-2xl | -0.30000001192092896px |
| --src-font-spacing-3xl | -0.5px |
| --src-font-spacing-4xl | -1px |

### ui-md (scope: global)
Source: `variables/ui/_md.scss`

| Token | Value |
|-------|-------|
| --src-media-thumbnail | 48px |
| --src-media-preview | 1024px |
| --src-padding-xs | var(--src-space-2) |
| --src-padding-sm | var(--src-space-3) |
| --src-padding-md | var(--src-space-4) |
| --src-padding-lg | var(--src-space-5) |
| --src-padding-xl | var(--src-space-7) |
| --src-height-xs | var(--src-space-4) |
| --src-icon-size | var(--src-space-5) |
| --src-icon-line-width | 1.440000057220459px |
| --src-height-sm | var(--src-space-5) |
| --src-border-border | 1px |
| --src-height-base | var(--src-space-9) |
| --src-border-rounded-none | 0px |
| --src-height-lg | 52px |
| --src-border-rounded-xs | var(--src-space-1) |
| --src-border-rounded | var(--src-space-1-5) |
| --src-border-rounded-parent | var(--src-space-2-5) |
| --src-border-rounded-lg | var(--src-space-4) |
| --src-border-rounded-full | 9999px |
| --src-gap-none | 0px |
| --src-gap-lg | var(--src-space-2-5) |
| --src-text-weight-base | var(--src-font-weight-medium) |
| --src-text-lineHeight | var(--src-font-line-sm) |
| --src-text-fontSize | var(--src-font-size-sm) |
| --src-gap-md | var(--src-space-1-5) |
| --src-gap-xl | var(--src-space-3-5) |
| --src-gap-sm | var(--src-space-1) |
| --src-text-weight-bold | var(--src-font-weight-bold) |
| --src-text-weight-medium | var(--src-font-weight-semiBold) |
| --src-shadow-focused | var(--src-space-1) |
| --src-shadow-ambient-inner | -1px |
| --src-shadow-ambient-inner-light | 1px |
| --src-shadow-ambient-outer | 1px |
| --src-shadow-blur | 1px |

### layout-md (scope: @media (min-width: 768px))
Source: `variables/layout/_md.scss`

| Token | Value |
|-------|-------|
| --src-layout-padding-const-xs | var(--src-space-1) |
| --src-layout-padding-const-sm | var(--src-space-2) |
| --src-layout-padding-const-md | var(--src-space-3) |
| --src-layout-padding-const-lg | var(--src-space-4) |
| --src-layout-padding-const-xl | var(--src-space-6) |
| --src-layout-padding-const-2xl | var(--src-space-8) |
| --src-layout-padding-var-xs | var(--src-space-2) |
| --src-layout-padding-table-sm | var(--src-space-3) |
| --src-layout-padding-var-sm | var(--src-space-3) |
| --src-layout-padding-var-md | var(--src-space-4) |
| --src-layout-padding-var-lg | var(--src-space-5) |
| --src-layout-padding-var-xl | var(--src-space-8) |
| --src-layout-padding-var-2xl | var(--src-space-11) |
| --src-layout-gap-const-none | 0px |
| --src-layout-gap-const-xs | var(--src-space-1) |
| --src-layout-gap-const-sm | var(--src-space-2) |
| --src-layout-gap-const-md | var(--src-space-3) |
| --src-layout-gap-const-lg | var(--src-space-4) |
| --src-layout-gap-const-xl | var(--src-space-6) |
| --src-layout-gap-const-2xl | var(--src-space-8) |
| --src-layout-gap-var-none | 0px |
| --src-layout-gap-var-sm | var(--src-space-2) |
| --src-layout-gap-var-md | var(--src-space-3) |
| --src-layout-gap-var-lg | var(--src-space-4) |
| --src-layout-gap-var-xl | var(--src-space-8) |
| --src-layout-height-const-sm | var(--src-space-7) |
| --src-layout-height-const-md | var(--src-space-8) |
| --src-layout-height-const-lg | var(--src-space-9) |
| --src-layout-height-const-h-xl | var(--src-space-10) |
| --src-layout-height-const-h-2xl | var(--src-space-16) |
| --src-layout-height-var-xs | var(--src-space-8) |
| --src-layout-height-var-sm | var(--src-space-10) |
| --src-layout-height-var-base | var(--src-space-20) |
| --src-layout-height-var-md | var(--src-space-28) |
| --src-layout-height-var-lg | var(--src-space-24) |
| --src-layout-height-var-xl | var(--src-space-36) |
| --src-layout-radius-var-rounded-kid | var(--src-space-2) |
| --src-layout-radius-var-rounded-parent | var(--src-space-3) |
| --src-layout-radius-rounded-none | 0px |
| --src-layout-border-border | 1px |
| --src-layout-table-height | var(--src-space-14) |
| --src-layout-radius-const-rounded-sm | var(--src-space-1-5) |
| --src-layout-radius-const-rounded | var(--src-space-2) |
| --src-layout-radius-const-rounded-md | var(--src-space-3) |
| --src-layout-radius-const-rounded-lg | var(--src-space-4) |
| --src-layout-radius-const-rounded-xl | var(--src-space-6) |
| --src-layout-radius-const-rounded-2xl | var(--src-space-8) |
| --src-layout-radius-rounded-ui-full | 9999px |
| --src-shadow-basic | var(--src-space-1-5) |
| --src-graphs-label | var(--src-space-2) |
| --src-graphs-label-var | var(--src-space-2-5) |
| --src-graphs-height-label-var | var(--src-space-7) |
| --src-graphs-height-label-const | var(--src-space-5) |
| --src-graphs-height-s | var(--src-space-8) |
| --screen-width | 768px |
| --card-width | 320px |
| --preview-width | 216px |
| --src-typography-var-p-sm-fontSize | var(--src-font-size-sm) |
| --src-typography-var-p-sm-weight | var(--src-font-weight-regular) |
| --src-typography-var-p-sm-lineHeight | var(--src-font-line-sm) |
| --src-typography-var-p-md-fontSize | var(--src-font-size-base) |
| --src-typography-var-p-md-weight | var(--src-font-weight-regular) |
| --src-typography-var-p-md-lineHeight | var(--src-font-line-base) |
| --src-typography-var-h-sm-fontSize | var(--src-font-size-md) |
| --src-typography-var-h-sm-weight | var(--src-font-weight-semiBold) |
| --src-typography-var-h-sm-lineHeight | var(--src-font-line-md) |
| --src-typography-var-h-md-fontSize | var(--src-font-size-lg) |
| --src-typography-var-h-md-weight | var(--src-font-weight-semiBold) |
| --src-typography-var-h-md-lineHeight | var(--src-font-line-lg) |
| --src-typography-var-h-lg-fontSize | var(--src-font-size-xl) |
| --src-typography-var-h-lg-weight | var(--src-font-weight-semiBold) |
| --src-typography-var-h-lg-lineHeight | var(--src-font-line-xl) |
| --src-typography-var-h-xl-fontSize | var(--src-font-size-3xl) |
| --src-typography-var-h-xl-weight | var(--src-font-weight-semiBold) |
| --src-typography-var-h-xl-lineHeight | var(--src-font-line-3xl) |
| --src-typography-var-p-lg-fontSize | var(--src-font-size-lg) |
| --src-typography-var-p-lg-weight | var(--src-font-weight-regular) |
| --src-typography-var-p-lg-lineHeight | var(--src-font-line-lg) |

## Theming: Custom Accent Colors

**Beta.** Custom accent theming is in beta: the palette algorithm and the override approach may change.

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` (6 alpha variants)

2. **Semantic tokens** in `color/light.scss` and `color/dark.scss` reference the primitives:
   - `--src-ui-accent-default: var(--src-color-primary-500)` (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: #ffece5ff;
  --src-color-primary-100: #ffd0c2ff;
  --src-color-primary-200: #ffaa8fff;
  --src-color-primary-300: #ff835cff;
  --src-color-primary-400: #ff5c29ff;
  --src-color-primary-500: #ff5722ff; /* your base color */
  --src-color-primary-600: #ff4408ff;
  --src-color-primary-700: #e43700ff;
  --src-color-primary-800: #c52f00ff;
  --src-color-primary-900: #922300ff;
  --src-color-primary-950: #551400ff;

  /* 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
```

In a CSS-only project, put the same `:root` block in a `.css` file loaded after `source-ui-native.min.css`.

### 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

## Component API reference (inline)

> Full API for every component inlined below. No external links needed.

### SourceBadgeComponent (@3dsource/source-ui-native)
**Selector:** `src-badge` · **Kind:** Component

**Usage:**
```html
<src-badge context="success">
  <src-icon name="check" srcIconPrefix></src-icon>
  Active
</src-badge>

<src-badge context="error" size="sm">3</src-badge>

<src-badge
  backgroundColor="var(--src-ui-status-basic-attention, #f0e442)"
  textColor="var(--src-text-body-main, #111827)"
>
  Beta
</src-badge>

<src-badge context="success" ariaLabel="Revenue up 12 percent" [data-testid]="'revenue-trend'">
  12%
  <src-icon name="arrow_upward" srcIconPostfix></src-icon>
</src-badge>

<src-badge [role]="null" customClass="menu-counter">5</src-badge>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| backgroundColor | string | "var(--src-ui-accent-default, #017bffff)" | — | no | Background color of the badge. Applies only when `context` is not set: any `context`, including `'default'`, uses its own colors. Without `context` the badge is accent blue. |
| context | SourceBadgeContextKeys | — | default, info, success, warning, attention, error | no | Defines the context of the badge (e.g. status). |
| size | SourceBadgeSizeKeys | "md" | sm, md, lg, xl | no | Size of the badge. |
| textColor | string | "var(--src-text-body-main-invert, #f9fafbff)" | — | no | Text color inside the badge. Applies only when `context` is not set. |
| customClass | string \| string[] | — | — | no | Custom class(es) to apply to the badge. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the badge in tests. |
| role | string \| null | "status" | — | no | ARIA role for the badge, with a default of "status" for accessibility. |
| ariaLabel | string | — | — | no | ARIA label for the badge, used for accessibility. |

### SourceBannerComponent (@3dsource/source-ui-native)
**Selector:** `src-banner` · **Kind:** Component

**Usage:**
```html
<src-banner context="warning">
  <src-icon size="var(--src-icon-size)" name="warning" srcIconPrefix></src-icon>
  <div srcBannerTitle>Attention</div>
  Your session will expire in 5 minutes.
  <src-icon-button appearance="inline" srcIconPostfix ariaLabel="Close" (onClick)="closeBanner()">
    <src-icon name="close-small"></src-icon>
  </src-icon-button>
</src-banner>

<src-banner context="info" size="md" [isFullWidth]="false" [data-testid]="'trial-banner'">
  Your trial ends in 3 days.
</src-banner>

<src-banner context="error" role="alert">
  <div srcBannerTitle>Payment failed</div>
  Check your card details and try again.
</src-banner>

<src-banner ariaLive="polite">{{ syncStatus() }}</src-banner>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| context | SourceBannerContextKeys | "default" | default, info, success, warning, critical, error | no | Defines the banner context. |
| size | SourceBannerSizeKeys | "sm" | sm, md, lg, xl | no | Size of the banner. |
| isFullWidth | boolean | true | — | no | If true, the banner will take the full width of its container. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the banner in tests. |
| role | string | — | — | no | ARIA role for the banner, used for accessibility (e.g. "region", "alert"). |
| ariaLive | 'polite' \| 'assertive' \| 'off' | — | — | no | ARIA live region setting for the banner, used for accessibility to indicate how updates should be announced. |

### SourceButtonComponent (@3dsource/source-ui-native)
**Selector:** `src-button` · **Kind:** Component

**Usage:**
```html
<src-button
  weight="primary"
  size="lg"
  (onClick)="handleSave($event)"
>
  <src-icon srcIconPrefix name="save"></src-icon>
  Save changes
</src-button>

<src-button appearance="plain" weight="ghost" (onClick)="handleCancel($event)">
  Cancel
</src-button>

<src-button
  context="error"
  ariaLabel="Delete selected files"
  [isDisabled]="!hasSelection()"
  [data-testid]="'delete-selected'"
  (onClick)="deleteSelected()"
>
  Delete
</src-button>

<form id="profile-form" (ngSubmit)="saveProfile()">
  <!-- form fields -->
</form>
<src-button
  type="submit"
  formID="profile-form"
  weight="primary"
  [isFullWidth]="true"
  [isLoading]="saving()"
  [isDisabled]="saving()"
>
  Save profile
</src-button>

<src-button appearance="plain" [isPressed]="menuOpen()" (onClick)="toggleMenu()">
  Actions
  <src-icon srcIconPostfix name="expand_more"></src-icon>
</src-button>

<src-button appearance="inline" [isInverted]="true" customClass="toolbar-link" (onClick)="openHelp()">
  Help
</src-button>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| type | SourceButtonTypeKeys | "button" | button, submit, reset | no | Type of the inner `<button>`. Use `'submit'` to submit its form: the form around the button, or the form that `formID` names. |
| appearance | SourceButtonAppearanceKeys | "filled" | plain, inline, filled, default | no | Visual style: 'filled' (default), 'plain' or 'inline'. 'default' is a legacy value that looks the same as 'filled'. |
| weight | SourceButtonWeightKeys | "secondary" | primary, secondary, ghost | no | Is this the principal call to action on the page? |
| size | SourceButtonSizeKeys | "md" | sm, md, lg, xl | no | How big it should be? |
| context | SourceButtonContextKeys | "default" | default, error, success, info | no | Color variation of button. Usually represent context of action. |
| customClass | string \| string[] | "" | — | no | Add custom class if you need harder customization. |
| isFullWidth | boolean | false | — | no | Is this button should fill all available width of the container? |
| isPressed | boolean | false | — | no | Pressed state for button |
| isDisabled | boolean | false | — | no | Standard disabled state for button |
| isLoading | boolean | false | — | no | Shows a spinner instead of the label. The button stays clickable: set `isDisabled` as well to block repeat clicks. |
| isInverted | boolean | false | — | no | If true, applies inverted color scheme for use on dark or colored backgrounds. Works only with `appearance="inline"`. |
| srcButtonConfig | SourceButton | — | — | no | Even though it is not recommended, you can set the buttons configuration using one input. A valid use-case for it is settings for buttons in src-modal. |
| formID | string | — | — | no | The form element to associate the button with (its form owner). The value of this attribute must be the id of a form in the same document. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the button in tests. |
| ariaLabel | string | — | — | no | ARIA label for the button, used for accessibility. |

**Outputs:**

| Output | Type | Description |
|--------|------|-------------|
| onClick | Event | Optional click handler |

### SourceCopyrightComponent (@3dsource/source-ui-native)
**Selector:** `src-copyright` · **Kind:** Component

**Usage:**
```html
<src-copyright></src-copyright>

<src-copyright [isCollapsible]="true"></src-copyright>

<src-copyright linkUrl="https://example.com/" logoFill="#000000"></src-copyright>

<src-copyright linkText="Built with 3D Source" [data-testid]="'app-copyright'"></src-copyright>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| linkText | string | "Powered by 3D Source" | — | no | If you need other phrase then Powered by 3D Source change it here |
| linkUrl | string | "https://www.3dsource.com/" | — | no | URL the copyright link opens. Change it if the link should lead somewhere other than 3dsource.com. |
| logoFill | string | "#6897AB" | — | no | Fill color of the 3D Source logo icon. The default works in any theme, but you can recolor the logo here if needed. |
| isCollapsible | boolean | false | — | no | Shows only the logo in a 32px square that expands on hover to show the text. Mostly used in an absolute container above the view. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the copyright element in tests. |

### SourceDividerComponent (@3dsource/source-ui-native)
**Selector:** `src-divider` · **Kind:** Component

**Usage:**
```html
<src-divider [data-testid]="'filters-divider'"></src-divider>

<!-- Vertical: give it a flex row (or grid) parent; it takes its height from there -->
<div style="display: flex; align-items: center;">
  <span>Left</span>
  <src-divider orientation="vertical"></src-divider>
  <span>Right</span>
</div>

<!-- Custom properties of .src-divider: --srcDividerColor, --srcDividerThickness, --srcDividerLength, --srcDividerInset, --srcDividerOffsetStart, --srcDividerOffsetEnd -->
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| orientation | SourceDividerOrientationKeys | "horizontal" | horizontal, vertical | no | Direction of the line. A vertical divider takes its height from its parent, so it needs a flex row or grid parent; in block or inline flow it is 0px tall. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the divider in tests. |

### SourceHintComponent (@3dsource/source-ui-native)
**Selector:** `src-hint` · **Kind:** Component

**Usage:**
```html
<input class="src-input" aria-describedby="full-name-hint" />
<src-hint id="full-name-hint">Enter your full legal name as shown on your ID.</src-hint>

<src-hint context="error" [data-testid]="'name-error'">This field is required.</src-hint>

<src-hint context="success">Email is available.</src-hint>

<src-hint context="info" size="sm">
  <src-icon name="info" srcIconPrefix></src-icon>
  Changes are saved automatically.
</src-hint>

<src-hint role="status" ariaLive="polite">3 of 10 files uploaded.</src-hint>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| isError | boolean | false | — | no | Deprecated: use `context="error"` instead. `isError` only colors the hint red; `context="error"` also sets `role="alert"` and `aria-live="assertive"`. |
| context | SourceHintContextKeys | "default" | default, error, success, info | no | Context of the message. Can be "default", "info", "success" or "error" - change the color of the hint. |
| size | SourceHintSizeKeys | "md" | sm, md, lg, xl | no | Size of the hint. Can be "sm", "md", "lg" or "xl". Default is "md". |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the hint in tests. |
| id | string | — | — | no | ID attribute for the hint element, useful for aria-describedby on form inputs. |
| role | string | — | — | no | ARIA role for the hint. Automatically set to "alert" when context is "error". |
| ariaLive | 'polite' \| 'assertive' \| 'off' | — | — | no | ARIA live region setting. Automatically set to "assertive" when context is "error". |

### SourceIconButtonComponent (@3dsource/source-ui-native)
**Selector:** `src-icon-button` · **Kind:** Component

**Usage:**
```html
<src-icon-button
  weight="primary"
  context="error"
  ariaLabel="Delete item"
  [isDisabled]="!hasSelection()"
  [data-testid]="'delete-item'"
  (onClick)="handleDelete($event)"
>
  <src-icon name="delete"></src-icon>
</src-icon-button>

<src-icon-button appearance="inline" [counter]="5" ariaLabel="Notifications" (onClick)="openNotifications()">
  <src-icon name="bell"></src-icon>
</src-icon-button>

<src-icon-button
  shape="round"
  appearance="plain"
  size="sm"
  ariaLabel="Close"
  (onClick)="close()"
>
  <src-icon name="close"></src-icon>
</src-icon-button>

<src-icon-button
  appearance="plain"
  [isPressed]="filtersShown()"
  ariaLabel="Filters"
  (onClick)="toggleFilters()"
>
  <src-icon name="filter"></src-icon>
</src-icon-button>

<src-icon-button appearance="inline" [isInverted]="true" ariaLabel="Close" (onClick)="close()">
  <src-icon name="close"></src-icon>
</src-icon-button>

<form (ngSubmit)="search()">
  <src-icon-button type="submit" name="search" ariaLabel="Search">
    <src-icon name="search"></src-icon>
  </src-icon-button>
</form>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| name | string | — | — | no | Name of button. Could be used for form |
| type | SourceIconButtonTypeKeys | "button" | button, submit, reset | no | Type of the inner `<button>`. Use `'submit'` to submit the form around the button. |
| appearance | SourceIconButtonAppearanceKeys | "filled" | filled, plain, inline | no | Set basic style of button |
| weight | SourceIconButtonWeightKeys | "secondary" | primary, secondary, ghost | no | Shows the importance of the button |
| size | SourceIconButtonSizeKeys | "md" | sm, md, lg, xl | no | How big it should be? |
| shape | SourceIconButtonShapeKeys | "square" | square, round | no | Shape of button - square with rounded corners or round. Use round only for close, back and collapse buttons. |
| context | SourceIconButtonContextKeys | "default" | default, error, success, info, warning | no | Color variation of button. Usually represent context of action. |
| counter | number \| undefined | "undefined" | — | no | Use counter attribute to display counter in the top right corner of the button. A counter of 0 is hidden. |
| isPressed | boolean | false | — | no | Standard active state for button |
| isInverted | boolean | false | — | no | If true, applies inverted color scheme for use on dark or colored backgrounds. Works only with `appearance="inline"`. |
| isDisabled | boolean | false | — | no | Standard disabled state for button |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the icon button in tests. |
| ariaLabel | string | — | — | no | ARIA label for the button, required for accessibility since icon buttons have no visible text. |

**Outputs:**

| Output | Type | Description |
|--------|------|-------------|
| onClick | Event | Optional click handler |

### SourceLoadingComponent (@3dsource/source-ui-native)
**Selector:** `src-loading` · **Kind:** Component

**Usage:**
```html
<!-- Indeterminate spinner -->
<src-loading></src-loading>

<!-- Determinate progress bar -->
<src-loading
  [size]="64"
  [progress]="75"
  [strokeWidth]="6"
  backgroundStrokeColor="#e0f8ee"
  progressStrokeColor="#007a5c"
></src-loading>

<!-- Indeterminate progressbar instead of the default status role -->
<src-loading role="progressbar" ariaLabel="Loading projects" [data-testid]="'projects-loading'"></src-loading>

<!-- progress is a percentage; ariaValue* can describe it on another scale: 3 of 10 files -->
<src-loading
  [progress]="30"
  lineCap="butt"
  ariaLabel="Uploading files"
  [ariaValueNow]="3"
  [ariaValueMin]="0"
  [ariaValueMax]="10"
></src-loading>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| size | number | 32 | — | no | Size of the loading circle in pixels. Do not set px - value will be transformed to pixels automatically. |
| progress | number \| null | "null" | — | no | Set the percentage of a process here to make loader works as a progressbar, or leave null to make it just an animated circle. |
| lineCap | SourceLoadingLineCapKeys | "round" | round, square, butt | no | The stroke-linecap attribute is a presentation attribute defining the shape to be used at the end of open subpaths when they are stroked. |
| backgroundStrokeColor | string | "transparent" | — | no | The color of the track behind the progress line. Drawn only when `progress` is set. |
| progressStrokeColor | string | "var(--src-ui-accent-default, #017bffff)" | — | no | The color of the filled line. |
| strokeWidth | number | 3 | — | no | The width of the line in pixels. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the loading indicator in tests. |
| role | string | — | — | no | ARIA role for the loader. Defaults to status (indeterminate) or progressbar (when progress is set). |
| ariaLabel | string | — | — | no | ARIA label for the loading indicator. |
| ariaValueNow | number | — | — | no | Current progress value for progressbar role. Automatically set from progress input. |
| ariaValueMin | number | — | — | no | Minimum value for progressbar role. |
| ariaValueMax | number | — | — | no | Maximum value for progressbar role. |

### SourceLogoLoadingComponent (@3dsource/source-ui-native)
**Selector:** `src-logo-loading` · **Kind:** Component

**Usage:**
```html
<src-logo-loading [size]="64"></src-logo-loading>

<!-- Indeterminate progressbar instead of the default status role -->
<src-logo-loading
  strokeColor="var(--src-ui-accent-default, #017bff)"
  role="progressbar"
  ariaLabel="Loading the configurator"
  [data-testid]="'configurator-loading'"
></src-logo-loading>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| size | number | 32 | — | no | Size of the loading icon |
| strokeColor | string | "#6897AB" | — | no | Fill color of the logo shapes. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the logo loading indicator in tests. |
| role | string | "status" | — | no | ARIA role for the loading indicator. |
| ariaLabel | string | — | — | no | ARIA label for the loading indicator. |

### SourceModalNativeComponent (@3dsource/source-ui-native)
**Selector:** `src-modal-native` · **Kind:** Component

**Usage:**
```html
// Open only through SourceModalNativeService. Never put <src-modal-native> in a template.
// Requires <src-overlay-container> in the root component template.
import { SourceModalNativeService, SourceModalNativeComponent, SOURCE_MODAL_DATA, SOURCE_MODAL_REF, type SourceModalData, type SourceModalRef } from '@3dsource/source-ui-native';

modalService = inject(SourceModalNativeService);

// Mode 1: built-in chrome (open SourceModalNativeComponent itself)
openSimple() {
  const ref = this.modalService.open<string, SourceModalData>(SourceModalNativeComponent, {
    // also: width (sizes the <dialog>, not the card), height, min/max sizes, panelClass, id, role, ariaLabel, ariaLabelledBy, ariaDescribedBy
    data: {
      headerTitle: 'Confirm action',
      closeButton: true,
      closeButtonAriaLabel: 'Close dialog',
      context: 'warning', // colored icon next to the title; 'default' shows none
      content: 'Are you sure you want to proceed? This action cannot be undone.',
      testID: 'confirm-modal', // inner ids get it as a prefix: 'confirm-modal-header-close'
      footerButtons: [
        { label: 'Cancel', action: () => undefined },
        { label: 'Confirm', srcButtonConfig: { weight: 'primary' }, action: () => 'confirmed' },
      ],
    },
  });
  ref.afterClosed().subscribe((result) => console.log(result)); // 'confirmed', or undefined after Cancel, Esc, a backdrop click or the close button
}

// Grouped footer buttons: an array of arrays, each inner array is one group
footerButtons: [
  [{ label: 'Delete all', srcButtonConfig: { weight: 'ghost', context: 'error' }, action: () => 'reset' }],
  [
    { label: 'Cancel', action: () => undefined },
    { label: 'Save', srcButtonConfig: { weight: 'primary' }, action: () => 'saved' },
  ],
],

// Mode 2: custom component (forms, validation, any layout)
openCustom() {
  const ref = this.modalService.open<EditResult, { userId: number }>(EditUserModalComponent, {
    data: { userId: 42 },
  });
  ref.afterClosed().subscribe((result) => console.log(result));
}

// Custom modal class:
interface EditResult { ok: boolean; }

@Component({
  selector: 'app-edit-user-modal',
  templateUrl: './edit-user-modal.component.html',
})
export class EditUserModalComponent {
  readonly data = inject<{ userId: number }>(SOURCE_MODAL_DATA);
  readonly #ref = inject<SourceModalRef<EditResult>>(SOURCE_MODAL_REF);

  save() { this.#ref.close({ ok: true }); }
  cancel() { this.#ref.close(); }
}

// Custom modal template: start with .src-modal, the service already provides the <dialog>
<div class="src-modal">
  <div class="src-modal__header">
    <button type="button" class="src-icon-button src-icon-button--plain src-icon-button--round src-icon-button--size-sm src-modal__close" aria-label="Close" (click)="cancel()">
      <svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><!-- close icon --></svg>
    </button>
  </div>
  <div class="src-modal__body">
    <div class="src-modal__title">Edit user</div>
    <div class="src-modal__scroll-box">...your form...</div>
  </div>
  <div class="src-modal__footer">
    <div class="src-modal__footer-group">
      <button type="button" class="src-button src-button--plain" (click)="cancel()">Cancel</button>
      <button type="button" class="src-button src-button--primary" (click)="save()">Save</button>
    </div>
  </div>
</div>

// Mode 3: source-ui chrome through the native service (needs @3dsource/source-ui)
import { SourceModalComponent } from '@3dsource/source-ui';
this.modalService.open<string, SourceModalData>(SourceModalComponent, {
  data: { headerTitle: 'Saved', footerButtons: [{ label: 'OK', action: () => 'ok' }] },
});
```

**SourceModalData:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| headerTitle | string | no | Title rendered in the modal body. |
| closeButton | boolean | no | Renders a close (×) button in the top-right of the header. |
| closeButtonAriaLabel | string | no | ARIA label for the icon-only close button. Defaults to 'Close'. |
| context | SourceModalContextKeys | no | Visual context ('default' \| 'info' \| 'success' \| 'warning' \| 'error'). Renders a colored icon next to the title. |
| content | string | no | HTML string rendered via [innerHTML] inside src-modal__scroll-box. The wrapper is rendered only when content is provided. |
| footerButtons | DialogButtonsData \| DialogButtonsData[] | no | Footer buttons. Pass a flat array for one group, or an array of arrays for multiple groups (groups are spaced apart in the footer). Each button closes the modal with the value its action() returns, so a footer button cannot keep the modal open. For forms, use a custom component. |
| testID | string | no | data-testid value applied to the modal root and composed into inner selectors (e.g. '<testID>-header-close'). |

**Service — SourceModalNativeService:**

- `open<R = unknown, D = unknown>(component: Type<unknown>, config: SourceModalConfig<D>): SourceModalRef<R, D>` — Opens `component` inside a native `<dialog>` and returns a ref. `config.data` is injected via `SOURCE_MODAL_DATA` for the projected component; the rest of `config` (aria-* fields, role, panelClass, sizing) is applied to the dialog wrapper. Requires `<src-overlay-container>` in the app root. Never use the <src-modal-native> tag in a template. In browsers without the Popover API, or with SOURCE_MODAL_USE_TOP_LAYER set to false, the dialog opens with show() instead of showModal(). `width` sizes the dialog wrapper, as in CDK; to resize the `.src-modal` card, set `--srcModalWidth` on it.

**SourceModalRef<R, D>:**

Handle returned by SourceModalNativeService.open(). Custom components inject SOURCE_MODAL_REF to access this ref and close the modal with a result.

| Method | Description |
|--------|-------------|
| `close(result?: R)` | Closes the dialog and completes both `closed` and `afterClosed()` with the result. Idempotent — second call is a no-op. |
| `afterClosed(): Observable<R \| undefined>` | Observable that emits the close result once and completes. It emits undefined after Esc, a backdrop click or the header close button. |
| `closed: Observable<R \| undefined>` | Same stream as `afterClosed()` exposed as a property — provides CDK-style ergonomics (`ref.closed.subscribe(...)`). |
| `data: D` | The `data` payload that was passed in the config — same value as injecting SOURCE_MODAL_DATA from inside the projected component. |

### SourceOverlayContainerComponent (@3dsource/source-ui-native)
**Selector:** `src-overlay-container` · **Kind:** Component

**Usage:**
```html
<!-- Once, at the end of the root component's template -->
<div class="section_3dsourcecom">
  <router-outlet />
  <src-overlay-container />
</div>
```

### SourceSliderComponent (@3dsource/source-ui-native)
**Selector:** `src-slider` · **Kind:** Component

**Usage:**
```html
<!-- Not a form control: bind [value] and handle (onChange) or (onInput); [formControl] and ngModel do not work -->
<src-slider
  [min]="0"
  [max]="100"
  [step]="5"
  [value]="40"
  [showTicks]="true"
  (onChange)="onVolumeChange($event)"
></src-slider>

<!-- Custom thumb: project an element marked srcIconThumb -->
<src-slider [min]="0" [max]="100" [value]="40">
  <src-icon srcIconThumb name="drag"></src-icon>
</src-slider>

<label class="src-label" for="temperature">Temperature</label>
<src-slider
  id="temperature"
  [min]="10"
  [max]="30"
  [value]="temperature()"
  [ariaValueText]="temperature() + ' degrees'"
  [data-testid]="'temperature-slider'"
  (onInput)="temperature.set($event)"
></src-slider>

<!-- Vertical: the layout box stays horizontal, so give the container the height -->
<div style="height: 160px;">
  <src-slider
    orientation="vertical"
    [min]="0"
    [max]="100"
    [value]="volume()"
    [thumbSize]="20"
    [trackHeight]="6"
    [isDisabled]="muted()"
    ariaLabel="Volume"
    (onChange)="volume.set($event)"
  ></src-slider>
</div>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| id | string | — | — | no | ID of the input to connect the label and input[type=range]. |
| value | number | — | — | yes | The value of the slider. |
| min | number | — | — | yes | The minimum value of the range. |
| max | number | — | — | yes | The maximum value of the range. |
| thumbSize | number | 16 | — | no | The size of the thumb. |
| trackHeight | number | 4 | — | no | The height of the visual track. The height of the input will not be affected. |
| step | number | 1 | — | no | The step size of the slider. |
| showTicks | boolean | false | — | no | Whether to show ticks at each step. |
| isDisabled | boolean | false | — | no | Whether the slider is disabled. |
| orientation | 'horizontal' \| 'vertical' | "horizontal" | — | no | Orientation of the slider. `'vertical'` rotates the horizontal slider with a CSS transform, so its layout box stays horizontal: give its container the height the slider needs. The minimum is at the bottom. |
| testID (alias: data-testid) | string | "" | — | no | Test ID for querying the slider in tests. |
| ariaLabel | string | — | — | no | ARIA label for the slider, used when there is no visible label. |
| ariaValueText | string | — | — | no | Custom text representation of the current value (e.g., 50C instead of 50). |

**Outputs:**

| Output | Type | Description |
|--------|------|-------------|
| onChange | number | Optional change event handler. |
| onInput | number | Optional input event handler. |

### SourceTileComponent (@3dsource/source-ui-native)
**Selector:** `src-tile` · **Kind:** Component

**Usage:**
```html
<!-- Contract: only children marked srcTileImage, srcTileProps, srcTileTitle or srcTileDelete are rendered; any other content is dropped -->
<src-tile counter="3">
  <img src="path/to/image.jpg" alt="Material preview" srcTileImage />
  <div srcTileProps>
    <src-icon size="20px" name="cube"></src-icon>
  </div>
  <div srcTileTitle>Oak wood</div>
  <src-icon-button srcTileDelete size="sm" shape="round" (onClick)="removeTile($event)">
    <src-icon size="var(--src-icon-size)" name="close"></src-icon>
  </src-icon-button>
</src-tile>

<!-- Selectable tile -->
<src-tile [isActive]="selected === 'oak'" (click)="selected = 'oak'">
  <img src="oak.jpg" alt="Oak wood" srcTileImage />
  <div srcTileTitle>Oak wood</div>
</src-tile>

<!-- Tile grid: use CSS grid to lay out tiles; the tile component handles its own sizing. -->
<div
  style="display: grid; grid-template-columns: repeat(auto-fill, minmax(120px, 1fr)); gap: var(--src-layout-gap-const-md, 12px);"
>
  <src-tile counter="3">
    <img src="oak.jpg" alt="Oak wood" srcTileImage />
    <div srcTileTitle>Oak wood</div>
  </src-tile>
  <src-tile>
    <img src="maple.jpg" alt="Maple" srcTileImage />
    <div srcTileTitle>Maple</div>
  </src-tile>
  <src-tile>
    <img src="walnut.jpg" alt="Walnut" srcTileImage />
    <div srcTileTitle>Walnut</div>
  </src-tile>
</div>

<src-tile
  width="160px"
  aspectRatio="16/9"
  counter="+3"
  counterPlacement="top-right"
  [titleLineClamp]="2"
  [data-testid]="'scene-tile'"
>
  <img src="scene.jpg" alt="Living room scene" srcTileImage />
  <div srcTileTitle>Living room with oak floor and walnut furniture</div>
</src-tile>

<src-tile [isLoading]="uploading()" [isDisabled]="uploading()">
  <img src="maple.jpg" alt="Maple" srcTileImage />
  <div srcTileTitle>Maple</div>
</src-tile>

<!-- Read-only preview: no hover or active feedback -->
<src-tile [isInteractive]="false">
  <img src="walnut.jpg" alt="Walnut" srcTileImage />
  <div srcTileTitle>Walnut</div>
</src-tile>
```

**Inputs:**

| Input | Type | Default | Values | Required | Description |
|-------|------|---------|--------|----------|-------------|
| width | string | — | — | no | CSS width of the tile container (e.g. '92px', '100%'). When omitted the tile fills its parent. |
| counter | string | — | — | no | Text displayed in the counter badge overlay on the image (e.g. '+3'). |
| counterPlacement | SourceTileCounterPlacementKeys | "center" | top-right, top-left, bottom-right, bottom-left, center | no | Position of the counter badge within the image area. |
| aspectRatio | string | "1/1" | — | no | CSS aspect-ratio of the image area (e.g. '1/1', '6/5'). |
| titleLineClamp | number | — | — | no | Maximum number of visible title lines before text is clamped with ellipsis. |
| isInteractive | boolean | true | — | no | When false the tile has no hover/active feedback and uses a default cursor. |
| isActive | boolean | — | — | no | Applies the active/selected visual state with accent border and shadow. |
| isDisabled | boolean | — | — | no | Dims the tile and disables all pointer events. |
| isLoading | boolean | — | — | no | Shows a loading overlay with a spinner on top of the image area. |
| testID (alias: data-testid) | string | "" | — | no | Sets a data-testid attribute on the root element for testing. |

## Source Elements (CSS-only styling)

CSS-only Source Elements — BEM classes applied to native HTML tags. No Angular imports needed. Requires source.ui.native.scss stylesheet.

Stylesheet: `@3dsource/source-ui-native/styles/source-ui-native.min.css`

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

### Badge Element

Status badge. Use for labels, tags, and status indicators.

**Core class:** `src-badge` — Inline-flex pill badge for status labels and tags.

**Usage:**
```html
<span class="src-badge src-badge--context-success">
  <span class="src-badge__icon">
    <svg viewBox="0 0 20 20" fill="currentColor"><!-- check icon --></svg>
  </span>
  Active
</span>

<span class="src-badge src-badge--context-error src-badge--size-sm">3</span>
```

**Size modifiers:**
- `src-badge--size-sm` — Small size for the badge.
- `src-badge--size-md` (default) — Default size for the badge.
- `src-badge--size-lg` — Large size for the badge.
- `src-badge--size-xl` — Extra large size for the badge.

**Context modifiers:**
- `src-badge--context-default` (default) — Neutral background, muted label colour.
- `src-badge--context-info` — Info-blue styling.
- `src-badge--context-success` — Success-green styling.
- `src-badge--context-warning` — Warning-amber styling.
- `src-badge--context-attention` — Attention-yellow styling.
- `src-badge--context-error` — Error-red styling.

**Sub-elements:**
- `src-badge__icon` — Prefix/postfix icon wrapper inside badge.

**Custom properties:** `--srcBadgeBackgroundColor`, `--srcBadgeTextColor`

### Banner Element

Notification banner. Use for page-level alerts.

**Core class:** `src-banner` — Full-width notification banner container.

**Usage:**
```html
<div class="src-banner src-banner--context-info src-banner--size-sm">
  <span class="src-banner__icon-prefix">
    <svg viewBox="0 0 20 20" fill="currentColor"><!-- info icon --></svg>
  </span>
  <div class="src-banner__content">
    <div class="src-banner__title">Information</div>
    Your changes have been saved successfully.
  </div>
  <span class="src-banner__icon-postfix">
    <button type="button" class="src-icon-button src-icon-button--inline" aria-label="Close">
      <svg viewBox="0 0 20 20" fill="currentColor"><!-- close icon --></svg>
    </button>
  </span>
</div>
```

**Context modifiers:**
- `src-banner--context-info` — Info-blue styling.
- `src-banner--context-success` — Success-green styling.
- `src-banner--context-warning` — Warning-amber styling.
- `src-banner--context-error` (alias: `src-banner--context-critical`) — Error-red styling.
- `src-banner--context-critical` — Critical-red styling (same as error).

**Size modifiers:**
- `src-banner--size-sm` — Small size, the default of the banner by design: other elements default to md, the banner to sm. Add it explicitly, because without a size class the banner gets the md tokens. Tech-style uppercase title.
- `src-banner--size-md` — Medium size. Tech-style uppercase title.
- `src-banner--size-lg` — Large size. Capitalized title with larger font.
- `src-banner--size-xl` — Extra-large size. Capitalized title with larger font.

**Sub-elements:**
- `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.

### Breadcrumbs Element

CSS-only breadcrumb navigation trail. Renders items in a horizontal list with "/" separators. Content inside each item is fully consumer-controlled (links, buttons, spans).

**Core class:** `src-breadcrumbs` — Wrapper for the breadcrumb navigation. Apply to a <nav> element.

**Usage:**
```html
<nav aria-label="Breadcrumb" class="src-breadcrumbs">
  <ol class="src-breadcrumbs__list">
    <li class="src-breadcrumbs__item">
      <a class="src-label-md" href="/">Home</a>
    </li>
    <li class="src-breadcrumbs__item">
      <a class="src-label-md" href="/components">Components</a>
    </li>
    <li class="src-breadcrumbs__item" aria-current="page">
      <span class="src-label-md">Breadcrumbs</span>
    </li>
  </ol>
</nav>
```

**Modifier modifiers:**
- `src-breadcrumbs--wrap` — Wraps a long trail onto several lines, so the labels show in full; a label wider than the trail itself still ends with an ellipsis. Apply to the <nav> together with .src-breadcrumbs.

**Sub-elements:**
- `src-breadcrumbs__list` (required) — Flex container for breadcrumb items. Apply to an <ol> inside .src-breadcrumbs. A long trail stays on one line; the labels shrink and end with an ellipsis.
- `src-breadcrumbs__item` (required) — Individual breadcrumb item. Apply to each <li>. Renders a "/" separator via ::after (hidden on last item).

**Custom properties:** `--srcBreadcrumbListGap`, `--srcBreadcrumbSeparatorOffset`

### Button Group Element

CSS-only wrapper that visually combines adjacent buttons or icon-buttons into a single unit. Flattens inner border-radii so the group appears as one continuous control.

**Core class:** `src-button-group` — Inline flex container that visually joins adjacent buttons into a single unit by flattening inner border-radii.

**Usage:**
```html
<div class="src-button-group">
  <button type="button" class="src-button src-button--plain src-button--size-sm">Components</button>
  <button type="button" class="src-icon-button src-icon-button--plain src-icon-button--size-sm" aria-label="More options">
    <svg viewBox="0 0 20 20" fill="currentColor"><!-- arrow drop down icon --></svg>
  </button>
</div>
<!-- <src-button> and <src-icon-button> go into the group the same way; give all buttons one size -->
```

### Button Element

Interactive button. Use for actions and navigation. On an <a>, place the button in a flex container, or it stretches to the full width.

**Core class:** `src-button` — The main class for the button element.

**Usage:**
```html
<!-- Wrap an icon and the label in a <span>: it sizes the svg and sets the gap -->
<button type="button" class="src-button src-button--primary src-button--size-lg">
  <span>
    <svg viewBox="0 0 20 20" fill="currentColor"><!-- save icon --></svg>
    Save changes
  </span>
</button>

<button type="button" class="src-button src-button--plain src-button--ghost">
  Cancel
</button>

<button type="button" class="src-button src-button--primary src-button--context-error">
  Delete
</button>
```

**Weight modifiers:**
- `src-button--primary` — Change visual weight to more prominent.
- `src-button--secondary` (default) — Change visual weight to default button.
- `src-button--ghost` — Change visual weight for less prominent button.

**Appearance modifiers:**
- `src-button--plain` — Minimalistic button without background color and border.
- `src-button--inline` — Minimalistic button without background color, border and paddings around.

**Size modifiers:**
- `src-button--size-sm` — Small size for the button.
- `src-button--size-md` (default) — Default size for the button.
- `src-button--size-lg` — Large size for the button.
- `src-button--size-xl` — Extra large size for the button.
- `src-button--full-width` — Full width button.

**Context modifiers:**
- `src-button--context-info` — Visual context for button - used for informational purposes. Paint the button in blue color. For primary button does not exist.
- `src-button--context-success` — Visual context for a button indicating a successful action. The button is painted green.
- `src-button--context-error` — Visual context for a button indicating a failed action. Paint the button in red color.

**State modifiers:**
- `src-button--pressed` — Button pressed state.

### Checkbox Element

Styled native checkbox.

**Core class:** `src-checkbox` — Flex container for styled native checkbox. Wraps input[type="checkbox"] with custom appearance. No indeterminate style: an indeterminate checkbox looks unchecked. For a "select all" checkbox, use mat-checkbox with indeterminate from @3dsource/source-ui.

**Usage:**
```html
<label class="src-checkbox">
  <input type="checkbox" checked />
  <span class="src-checkbox__label">I agree to the terms and conditions</span>
</label>

<label class="src-checkbox">
  <input type="checkbox" disabled />
  <span class="src-checkbox__label">Disabled option</span>
</label>
```

**Size modifiers:**
- `src-checkbox--size-sm` — Small size for the checkbox and its label.
- `src-checkbox--size-md` (default) — Default size for the checkbox and its label.
- `src-checkbox--size-lg` — Large size for the checkbox and its label.
- `src-checkbox--size-xl` — Extra large size for the checkbox and its label.

**Sub-elements:**
- `src-checkbox__label` — Text label beside the checkbox.

### Divider Element

Separator line. Horizontal by default.

**Core class:** `src-divider` — Separator line. Horizontal by default.

**Usage:**
```html
<hr class="src-divider" />

<!-- Vertical: give it a flex row (or grid) parent; it takes its height from there -->
<div style="display: flex; align-items: center;">
  <span>Left</span>
  <hr class="src-divider src-divider--vertical" />
  <span>Right</span>
</div>

<!-- Custom thickness and color -->
<hr class="src-divider" style="--srcDividerThickness: 2px; --srcDividerColor: var(--src-border-container-basic, #d1d5db);" />

<!-- With inset (shortens the line on both ends) -->
<hr class="src-divider" style="--srcDividerInset: 12px;" />
```

**Modifier modifiers:**
- `src-divider--vertical` — Renders the divider as a vertical line. It takes its height from a flex row or grid parent; outside one it is 0px tall.

**Custom properties:** `--srcDividerColor`, `--srcDividerThickness`, `--srcDividerLength`, `--srcDividerInset`, `--srcDividerOffsetStart`, `--srcDividerOffsetEnd`

### Hint Element

Contextual message below form fields or content.

**Core class:** `src-hint` — Contextual hint or validation message below form fields.

**Usage:**
```html
<p class="src-hint">Enter a value between 1 and 100.</p>

<p class="src-hint src-hint--context-error" role="alert" aria-live="assertive">
  <span class="src-hint__icon">
    <svg viewBox="0 0 20 20" fill="currentColor"><!-- error icon --></svg>
  </span>
  This field is required.
</p>

<p class="src-hint src-hint--context-success">Username is available.</p>
```

**Size modifiers:**
- `src-hint--size-sm` — Small size for the hint.
- `src-hint--size-md` (default) — Default size for the hint.
- `src-hint--size-lg` — Large size for the hint.
- `src-hint--size-xl` — Extra large size for the hint.

**Context modifiers:**
- `src-hint--context-error` — Red text for error messages.
- `src-hint--context-info` — Blue text for informational messages.
- `src-hint--context-success` — Green text for success messages.
- `src-hint--error` (alias: `src-hint--context-error`) — Legacy alias for --context-error.

**Sub-elements:**
- `src-hint__icon` — Prefix icon slot.

### Icon Button Element

Icon-only action button. Use for toolbar actions and compact controls.

**Core class:** `src-icon-button` — The main class for the button element.

**Usage:**
```html
<button type="button" class="src-icon-button src-icon-button--ghost src-icon-button--round" aria-label="Close">
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- close icon --></svg>
</button>

<button type="button" class="src-icon-button src-icon-button--inline src-icon-button--size-sm" aria-label="Close">
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- close icon --></svg>
</button>

<button type="button" class="src-icon-button src-icon-button--primary src-icon-button--size-lg" aria-label="Add">
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- add icon --></svg>
</button>

<button type="button" class="src-icon-button src-icon-button--context-info src-icon-button--size-xl" aria-label="Info">
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- info icon --></svg>
</button>

<button type="button" class="src-icon-button src-icon-button--context-success" aria-label="Approve">
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- check icon --></svg>
</button>

<!-- src-icon-button--context-warning works with src-icon-button--inline only -->
<button type="button" class="src-icon-button src-icon-button--inline src-icon-button--context-warning" aria-label="Warning">
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- warning icon --></svg>
</button>

<button type="button" class="src-icon-button src-icon-button--plain src-icon-button--context-error" aria-label="Delete" disabled>
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- delete icon --></svg>
</button>

<button type="button" class="src-icon-button src-icon-button--plain src-icon-button--pressed" aria-pressed="true" aria-label="Filters">
  <svg viewBox="0 0 20 20" fill="currentColor"><!-- filter icon --></svg>
</button>
```

**Appearance modifiers:**
- `src-icon-button--plain` — Represents a plain icon button.
- `src-icon-button--inline` — Represents an inline icon button without paddings around.

**Weight modifiers:**
- `src-icon-button--primary` — Change visual weight to more prominent.
- `src-icon-button--secondary` (default) — Change visual weight to default button.
- `src-icon-button--ghost` — Change visual weight for less prominent button.

**Size modifiers:**
- `src-icon-button--size-sm` — Small size for the button. Used for popovers and modals.
- `src-icon-button--size-md` (default) — Default size for the button.
- `src-icon-button--size-lg` — Large size for the button.
- `src-icon-button--size-xl` — Extra large size for the button.

**Shape modifiers:**
- `src-icon-button--round` — Shape modificator. You can use Size modificators with this class. Use it only for close, back and collapse buttons.

**Context modifiers:**
- `src-icon-button--context-info` — Visual context for button - used for informational purposes. Paint the button in blue color.
- `src-icon-button--context-success` — Visual context for a button indicating a successful action. Paint the button in green color.
- `src-icon-button--context-warning` — Visual context for a button indicating a warning. Paint the button in orange color. Works for inline appearance only.
- `src-icon-button--context-error` — Visual context for a button indicating a failed action. Paint the button in red color.

**State modifiers:**
- `src-icon-button--pressed` — Standard active state for button

### Input Element

Text input field. Use for single-line text entry.

**Core class:** `src-input` — The main class for the input element.

**Usage:**
```html
<label class="src-label" for="email-input">Email</label>
<input
  id="email-input"
  type="email"
  class="src-input"
  placeholder="name@example.com"
/>

<label class="src-label" for="error-input">Username</label>
<input
  id="error-input"
  type="text"
  class="src-input src-input--context-error"
  placeholder="Enter username"
  value="ab"
/>
<p class="src-hint src-hint--context-error">Minimum 3 characters required.</p>
```

**Weight modifiers:**
- `src-input--primary` (default) — Default visual appearance of input - with visible border.
- `src-input--secondary` — Visual appearance for less prominent input - with visible background, but without border.
- `src-input--ghost` — Visual appearance for the least prominent input - without visible background and border.

**Size modifiers:**
- `src-input--size-sm` — Smallest size of input.
- `src-input--size-md` (default) — Default size of input.
- `src-input--size-lg` — Large size of input.
- `src-input--size-xl` — Extra large size of input.

**Context modifiers:**
- `src-input--context-success` — Green border for the input. Used for success context.
- `src-input--context-error` — Red border for the input. Used for error context.

**State modifiers:**
- `src-input--disabled` — Disabled look only: the field stays reachable by Tab, editable and is submitted with the form. To disable the field, use the disabled attribute, which gives the same look.

### Label Element

Uppercase, small technical text label for form fields.

**Core class:** `src-label` — Uppercase, small technical text label for form fields.

**Usage:**
```html
<label class="src-label" for="name-field">Full name</label>
<input id="name-field" type="text" class="src-input" placeholder="John Doe" />
```

### List Element

List container with styled items.

**Core class:** `src-list` — The main class for the list element.

**Usage:**
```html
<ul class="src-list">
  <li class="src-list__item src-list__item--selected">Dashboard</li>
  <li class="src-list__item">Projects</li>
  <li class="src-list__item src-list__item--disabled">Archived</li>
  <li class="src-list__item src-list__item--flex src-list__item--context-error">
    <svg viewBox="0 0 20 20" fill="currentColor"><!-- delete icon --></svg>
    Delete workspace
  </li>
</ul>

<!-- Clickable list: src-list__item and its states go on the <button> -->
<ul class="src-list">
  <li>
    <button type="button" class="src-list__item src-list__item--selected">Dashboard</button>
  </li>
  <li>
    <button type="button" class="src-list__item">Projects</button>
  </li>
  <li>
    <button type="button" class="src-list__item" disabled>Archived</button>
  </li>
  <li>
    <button type="button" class="src-list__item src-list__item--flex src-list__item--context-error">
      <svg viewBox="0 0 20 20" fill="currentColor"><!-- delete icon --></svg>
      Delete workspace
    </button>
  </li>
</ul>

<!-- Navigation list: the same on <a>; a disabled link gets the class and no href -->
<ul class="src-list">
  <li>
    <a class="src-list__item src-list__item--selected" href="#">Dashboard</a>
  </li>
  <li>
    <a class="src-list__item" href="#">Projects</a>
  </li>
  <li>
    <a class="src-list__item src-list__item--disabled">Archived</a>
  </li>
</ul>
```

**Size modifiers:**
- `src-list--compact` — Decreased padding around the list and between list items.

**Sub-elements:**
- `src-list__item` (required) — The main class for the list item element. On a clickable item, put it on a `<button type="button">` (or an `<a>` for navigation) inside the `<li>`, not on the `<li>`: the button or link takes the click.
- `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; on a `<button>` item, use the attribute. A link has no disabled attribute: use this class and leave out `href`.
- `src-list__item--selected` — Selected state for the list item. On a clickable item, set it on the `<button>` or `<a>`.
- `src-list__item--context-error` — Visually distinct appearance to emphasize a critical action.

### Modal Native Element

CSS structure for modal layout (header / body / footer). Used by the Angular `SourceModalNativeComponent` and by custom CDK Dialog modals. The `<dialog class="src-dialog">` wrapper is only for CSS-only use. In a component opened by `SourceModalNativeService` or CDK `Dialog`, the service provides the dialog: start the template with `.src-modal`.

**Core class:** `src-modal` — Grid container for modal layout (header / body / footer). To change the width, colors or paddings of the modal, set the `--srcModal*` properties on the `.src-modal` element itself, for example `.my-modal .src-modal { --srcModalWidth: 600px; }`, where `my-modal` is a class on the `<dialog>` (`panelClass` in `SourceModalNativeService`). Set on the `<dialog>` itself, they have no effect: `.src-modal` sets its own values. The `width` option of the service changes the size of the `<dialog>`, not of the card; to make the card wider, set `--srcModalWidth`.

**Usage:**
```html
<!-- CSS-only use. In a component opened by SourceModalNativeService or CDK Dialog, drop the <dialog> wrapper and start with .src-modal. -->
<dialog class="src-dialog">
  <div class="src-modal">
    <div class="src-modal__header">
      <button type="button" class="src-icon-button src-icon-button--plain src-icon-button--round src-icon-button--size-sm src-modal__close" aria-label="Close">
        <svg viewBox="0 0 20 20" fill="currentColor"><!-- close icon --></svg>
      </button>
    </div>
    <div class="src-modal__body">
      <h2 class="src-modal__title">Confirm deletion</h2>
      <div class="src-modal__scroll-box">
        <p>Are you sure you want to delete this item? This action cannot be undone.</p>
      </div>
    </div>
    <div class="src-modal__footer">
      <div class="src-modal__footer-group">
        <button type="button" class="src-button src-button--plain src-button--ghost">Cancel</button>
        <button type="button" class="src-button src-button--primary src-button--context-error">Delete</button>
      </div>
    </div>
  </div>
</dialog>
```

**Sub-elements:**
- `src-dialog` — For CSS-only use without Angular: apply on a native `<dialog>` element to reset its padding/border/background and style its `::backdrop` with the design-system curtain color. Open it with `showModal()` and close it with `close()`. In Angular, open modals with `SourceModalNativeService`, which creates the `<dialog>` itself.
- `src-modal__header` — Header row. Hosts only the close button: the title goes into `.src-modal__body` as `.src-modal__title`. No bottom border by default: set `--srcModalTitleBorder` to add one.
- `src-modal__body` — Scrollable content area with padding. Grid-based; children `__title` and `__scroll-box` span the full width by default.
- `src-modal__body--icon` — Switches body grid to two columns (24px icon + content). Use together with `.src-modal__icon` when rendering a context icon (info/success/warning/error).
- `src-modal__icon` — Icon slot in the left column of `.src-modal__body--icon`. Spans all body rows.
- `src-modal__title` — Semibold title inside the body. Word-break on overflow.
- `src-modal__scroll-box` — Scrollable content wrapper spanning the full body grid width.
- `src-modal__footer` — Action buttons row. Right-aligned by default; when two `.src-modal__footer-group` children are present it switches to space-between via `:has()`. Top border. On narrow viewports (<=767px) stacks column-reverse.
- `src-modal__footer-group` — Button group inside `.src-modal__footer`. Use one group for right-aligned buttons, or two groups to split them between left and right.
- `src-modal__close` — Absolutely-positioned close button at top-right of the header. Typically applied to `.src-icon-button`.

**Custom properties:** `--srcModalWidth`, `--srcModalMaxWidth`, `--srcModalMaxHeight`, `--srcModalBg`, `--srcModalBoxShadow`, `--srcModalBorderRadius`, `--srcModalTitleSize`, `--srcModalTitleLineHeight`, `--srcModalTitleColor`, `--srcModalBodyPadding`, `--srcModalTitleBorder`, `--srcModalFooterBorder`

### Radio Group Element

Radio button group container.

**Core class:** `src-radio-group` — Flex column container for radio buttons.

**Usage:**
```html
<div class="src-radio-group">
  <label class="src-radio">
    <input type="radio" name="plan" value="free" checked />
    <span class="src-radio__label">Free</span>
  </label>
  <label class="src-radio">
    <input type="radio" name="plan" value="pro" />
    <span class="src-radio__label">Professional</span>
  </label>
  <label class="src-radio">
    <input type="radio" name="plan" value="enterprise" disabled />
    <span class="src-radio__label">Enterprise (coming soon)</span>
  </label>
</div>
```

**Layout modifiers:**
- `src-radio-group--horizontal` — Switches to horizontal flex-row with wrapping.

**Sub-elements:**
- `src-radio` (required) — Flex container for a single radio button. Wraps input[type="radio"] with custom appearance. Place it inside .src-radio-group: the group declares the border and colors of the radio, and on its own the radio has no border.
- `src-radio__label` — Text label beside the radio button.
- `src-radio--size-sm` — Small size for the radio and its label.
- `src-radio--size-md` (default) — Default size for the radio and its label.
- `src-radio--size-lg` — Large size for the radio and its label.
- `src-radio--size-xl` — Extra large size for the radio and its label.

**Custom properties:** `--srcRadioSize`, `--srcRadioGroupGap`

### Select Element

Native dropdown select. Same modifiers as src-input.

**Core class:** `src-select` — The main class for the select element.

**Usage:**
```html
<label class="src-label" for="country-select">Country</label>
<select id="country-select" class="src-select">
  <option value="">Select a country</option>
  <option value="us">United States</option>
  <option value="de">Germany</option>
  <option value="jp">Japan</option>
</select>
```

**Weight modifiers:**
- `src-select--primary` (default) — Default visual appearance of select - with visible border.
- `src-select--secondary` — Visual appearance for less prominent select - with visible background, but without border.
- `src-select--ghost` — Visual appearance for the least prominent select - without visible background and border.

**Size modifiers:**
- `src-select--size-sm` — Smallest size of select.
- `src-select--size-md` (default) — Default size of select.
- `src-select--size-lg` — Large size of select.
- `src-select--size-xl` — Extra large size of select.

**Context modifiers:**
- `src-select--context-success` — Green border for the select. Used for success context.
- `src-select--context-error` — Red border for the select. Used for error context.

**State modifiers:**
- `src-select--disabled` — Disabled look only: the select stays reachable by Tab and is submitted with the form. To disable the select, use the disabled attribute, which gives the same look.

### Textarea Element

Multi-line text input.

**Core class:** `src-textarea` — The main class for the textarea element.

**Usage:**
```html
<label class="src-label" for="comment-field">Comment</label>
<textarea
  id="comment-field"
  class="src-textarea src-textarea--size-lg"
  rows="4"
  placeholder="Write your comment..."
></textarea>

<textarea
  class="src-textarea src-textarea--context-error"
  rows="3"
  placeholder="Write your comment..."
>Invalid content</textarea>
<p class="src-hint src-hint--context-error">Comment exceeds maximum length.</p>
```

**Weight modifiers:**
- `src-textarea--secondary` — Visual appearance with background fill, no border.
- `src-textarea--ghost` — Transparent background, no border.

**Size modifiers:**
- `src-textarea--size-sm` — Smallest size (28px min-height).
- `src-textarea--size-md` (default) — Default size (36px min-height).
- `src-textarea--size-lg` — Large size (44px min-height).
- `src-textarea--size-xl` — Extra large size (56px min-height).

**Context modifiers:**
- `src-textarea--context-success` — Green border for success context.
- `src-textarea--context-error` — Red border for error context.

**State modifiers:**
- `src-textarea--disabled` — Disabled look only: the textarea stays reachable by Tab, editable and is submitted with the form. To disable the textarea, use the disabled attribute.

### Tile Element

Image thumbnail tile. Use for material previews, preset cards, and option selectors.

**Core class:** `src-tile` — Tile container. Sets relative positioning, width, and custom property defaults.

**Usage:**
```html
<div class="src-tile src-tile--active">
  <div class="src-tile__image">
    <img src="material.avif" alt="Oak wood" />
    <div class="src-tile__counter src-tile__counter--top-right">3</div>
    <div class="src-tile__props">
      <svg viewBox="0 0 20 20" fill="currentColor"><!-- cube icon --></svg>
    </div>
  </div>
  <div class="src-tile__title">Oak wood</div>
  <div class="src-tile__delete">
    <button type="button" class="src-icon-button src-icon-button--round src-icon-button--size-sm" aria-label="Delete">
      <svg viewBox="0 0 20 20" fill="currentColor"><!-- close icon --></svg>
    </button>
  </div>
</div>

<!-- Color swatch: .color-swatch { display: block; width: 100%; height: 100%; background-color: #3c9fc9; } -->
<div class="src-tile">
  <div class="src-tile__image">
    <span class="color-swatch"></span>
  </div>
  <div class="src-tile__title">Steel blue</div>
</div>
```

**Modifier modifiers:**
- `src-tile--active` — Active/selected state with accent border and focus shadow.
- `src-tile--static` — Non-interactive tile — no hover/active feedback, default cursor.
- `src-tile--disabled` — Dimmed tile with reduced opacity and no pointer events.
- `src-tile--clamped` — Enables line-clamping on the title. Set --srcTileTitleLineClamp to control the number of visible lines.

**Sub-elements:**
- `src-tile__image` (required) — Image area with border, border-radius, aspect-ratio, and hover/active states. Place an <img> inside: it fills the area. Any other element, like a color swatch, needs its own size: display: block; width: 100%; height: 100%.
- `src-tile__title` — Title text below the image area. Hidden when empty.
- `src-tile__delete` — Absolutely positioned delete button slot at top-right corner of the tile.
- `src-tile__props` — Icon strip at bottom-left of the image area. Child elements are sized via --srcTilePropsItemSize.
- `src-tile__counter` — Counter badge overlay on the image. Requires a placement modifier.
- `src-tile__counter--center` — Centers the counter in the image area. The <src-tile> component uses it by default.
- `src-tile__counter--top-right` — Places the counter at top-right of the image area.
- `src-tile__counter--top-left` — Places the counter at top-left of the image area.
- `src-tile__counter--bottom-right` — Places the counter at bottom-right of the image area.
- `src-tile__counter--bottom-left` — Places the counter at bottom-left of the image area.
- `src-tile__loading` — Full-overlay loading state covering the image area with a faded background.

**Custom properties:** `--srcTileWidth`, `--srcTileAspectRatio`, `--srcTileBorderColor`, `--srcTileBorderRadius`, `--srcTileBoxShadow`, `--srcTileTransition`, `--srcTileImagePadding`, `--srcTilePointerEvents`, `--srcTileHoverBorderColor`, `--srcTileHoverBoxShadow`, `--srcTileActiveBorderColor`, `--srcTileActiveBoxShadow`, `--srcTileDisabledOpacity`, `--srcTileTitleColor`, `--srcTileTitleFontSize`, `--srcTileTitleLineHeight`, `--srcTileTitleLineClamp`, `--srcTilePropsItemSize`, `--srcTilePropsColor`, `--srcTilePropsBg`, `--srcTileCounterBg`, `--srcTileCounterColor`

### Toggle Element

Toggle switch wrapping a native checkbox.

**Core class:** `src-toggle` — Toggle switch wrapping a native checkbox. Styled as a pill-shaped track with animated thumb.

**Usage:**
```html
<label class="src-toggle">
  <input type="checkbox" checked />
  <span class="src-toggle__label">Enable notifications</span>
</label>

<label class="src-toggle">
  <input type="checkbox" disabled />
  <span class="src-toggle__label">Dark mode (unavailable)</span>
</label>
```

**Sub-elements:**
- `src-toggle__label` — Text label beside the toggle.

### Toolbar Element

Inline container for grouping buttons and icon-buttons with shadow and rounded corners.

**Core class:** `src-toolbar` — Inline container for grouping buttons and icon-buttons with shadow and rounded corners.

**Usage:**
```html
<div class="src-toolbar">
  <button type="button" class="src-icon-button" aria-label="More options">...</button>
  <hr class="src-divider src-divider--vertical" />
  <button type="button" class="src-button src-button--plain">Action</button>
</div>

<!-- Vertical -->
<div class="src-toolbar src-toolbar--vertical">
  <button type="button" class="src-icon-button" aria-label="Add">...</button>
  <button type="button" class="src-icon-button src-icon-button--plain" aria-label="Edit">...</button>
  <hr class="src-divider" />
  <button type="button" class="src-icon-button src-icon-button--context-info" aria-label="Info">...</button>
  <button type="button" class="src-icon-button" aria-label="Settings">...</button>
</div>
```

**Modifier modifiers:**
- `src-toolbar--compact` — Removes inner paddings.
- `src-toolbar--vertical` — Stacks children vertically. Separate groups with a horizontal `<hr class="src-divider">`: a vertical divider collapses here.
- `src-toolbar--disabled` — Disables pointer events and applies a muted background. Buttons inside should be disabled separately.

**Size modifiers:**
- `src-toolbar--size-sm` — Small toolbar.
- `src-toolbar--size-md` (default) — Medium toolbar (default).
- `src-toolbar--size-lg` — Large toolbar.
- `src-toolbar--size-xl` — Extra-large toolbar.

**Custom properties:** `--srcToolbarBgColor`, `--srcToolbarBorderColor`, `--srcToolbarBorder`, `--srcToolbarPaddings`, `--srcToolbarGap`, `--srcToolbarBorderRadius`, `--srcToolbarShadow`
## Design tokens

- [primitives](./docs/tokens/primitives.md): Raw color palette (`--src-color-*`) and spacing scale (`--src-space-*`); the values that semantic tokens point to
- [color-light](./docs/tokens/color-light.md): Semantic colors of the light theme, the default: surfaces, text, icons, borders, UI accents and states, shadows, gradients
- [color-dark](./docs/tokens/color-dark.md): The same semantic color names with dark-theme values; active under `.section_3dsourcecom--dark`
- [typeface](./docs/tokens/typeface.md): Font tokens (`--src-font-*`): families, sizes, line heights, letter spacing, weights
- [ui-sm](./docs/tokens/ui-sm.md): Component sizing tokens for the small size, for smaller and denser interfaces; active on an element with a `*--size-sm` modifier (such as `src-button--size-sm`) and inside it
- [ui-md](./docs/tokens/ui-md.md): Component sizing tokens at the default size, on `:root`: padding, gaps, icon size, border radius, text size and line height, focus ring width
- [ui-lg](./docs/tokens/ui-lg.md): Component sizing tokens for the large size, for roomy layouts and key actions that stand alone on a page (such as a sign-in form); active on an element with a `*--size-lg` modifier (such as `src-button--size-lg`) and inside it
- [ui-xl](./docs/tokens/ui-xl.md): Component sizing tokens for the extra large size; active on an element with a `*--size-xl` modifier (such as `src-button--size-xl`) and inside it
- [layout-sm](./docs/tokens/layout-sm.md): Layout tokens for spacing around and between containers: `--src-layout-gap-const-*`, `--src-layout-padding-const-*`, `--src-layout-radius-const-*`; the base values, for screens under 768px. The `*-const-*` tokens keep these values on every screen.
- [layout-md](./docs/tokens/layout-md.md): Layout token values for screens from 768px; only the responsive tokens change here, the `*-const-*` ones stay the same
- [layout-lg](./docs/tokens/layout-lg.md): Layout token values for screens from 1440px; only the responsive tokens change here, the `*-const-*` ones stay the same
- [layout-xl](./docs/tokens/layout-xl.md): Layout token values for screens from 1920px; only the responsive tokens change here, the `*-const-*` ones stay the same

## Optional

- [Full documentation (self-contained)](./docs/llms-full.txt): Every guide plus all component APIs, Source Elements and design tokens inlined — no external links needed