@signosoft/signpad-js 0.6.0 → 0.7.0

package/README.md

@@ -1,101 +1,56 @@
 # @signosoft/signpad-js
 
+<a id="table-of-contents"></a>
+
 ## 📍 Table of Contents
 
-| Core Concepts & Overview                  | Getting Started & Usage                             | Advanced & Support                 |
-| :---------------------------------------- | :-------------------------------------------------- | :--------------------------------- |
-| 📜 [Description](#-description)           | 📦 [Installation](#-installation)                   | 💬 [Feedback](#-feedback--support) |
-| 🎬 [Demo](#-demo)                         | 🔐 [Licensing](#-lease-setup)                       | 🛠️ [Contributing](#-contributing)  |
-| ⚙️ [Tech stack](#-tech-stack--built-with) | 🚀 [Quick Start](#-quick-start)                     | 📄 [License](#-license)            |
-| 🖊️ [Devices](#️-device-compatibility)      | 📋 [Properties](#-properties)                       |                                    |
-|                                           | 🧩 [Methods](#-methods)                             |                                    |
-|                                           | 🔄 [States](#-component-states)                     |                                    |
-|                                           | 🎨 [Styling](#-styling--theming)                    |                                    |
-|                                           | 🌐 [Localization](#-localization--translation-keys) |
-|                                           |                                                     |
+| Overview                                 | Getting Started & API                        | Customization & Support                            |
+| :--------------------------------------- | :------------------------------------------- | :------------------------------------------------- |
+| 📜 [Description](#description)           | 📦 [Installation](#installation)             | 🌐 [Localization](#localization--translation-keys) |
+| 🎬 [Demo](#demo)                         | 🌍 [Requirements](#environment-requirements) | 🎨 [Styling](#styling--theming)                    |
+| 🧰 [Tech stack](#tech-stack--built-with) | 🔐 [Licensing](#lease-setup)                 | ♿ [Accessibility](#accessibility)                 |
+| 🔌 [Devices](#device-compatibility)      | 🚀 [Quick Start](#quick-start)               |                                                    |
+|                                          | 📋 [Properties](#properties)                 | 💬 [Feedback](#feedback--support)                  |
+|                                          | 📤 [Results & errors](#results--errors)      | 📄 [License](#license)                             |
+|                                          | 🧩 [Methods](#methods)                       |                                                    |
+|                                          | 🔄 [States](#component-states)               |                                                    |
+|                                          | ⚠️ [Error codes](#error-codes)               |                                                    |
+|                                          | 🧱 [Types](#type-definitions)                |                                                    |
+
+<a id="description"></a>
 
 ## 📜 Description
 
-`signosoft-signpad` is a powerful and flexible web component built with LitElement, designed for seamless digital signature capture integration into modern web applications. It provides a **unified interface** for working with various signature devices like **Wacom or Ugee**, supporting both stylus and mouse-based signing.
+`signosoft-signpad` is a web component built with Lit that captures handwritten signatures in the browser. It reads signature tablets (Wacom STU, Ugee UG05, XP-Pen) over WebHID and uses mouse or touch input when no tablet is connected.
 
-This component **works effortlessly** with any modern stack:
+It works in plain JavaScript, React, Angular and Vue:
 | **JavaScript** | **React** | **Angular** | **Vue** |
 |:-:|:-:|:-:|:-:|
 | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/javascript/javascript-original.svg" alt="JS" width="35" height="35"> | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="35" height="35"> | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="35" height="35"> | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="35" height="35"> ||
 
-It expertly handles the complexities of **WebHID device connections**, signature session lifecycles, and high-fidelity stroke rendering.
-<br/>
+The component manages the WebHID connection, the signing session (connect, sign, OK / Clear / Cancel) and pressure-sensitive stroke rendering.
+
+> **Before you start:** you need Chrome or Edge 89+, HTTPS (`localhost` is fine for development), a [lease](#lease-setup), and a click or tap before the browser can open the device picker. Details: [Environment Requirements](#environment-requirements).
+> <br/>
+
+<a id="demo"></a>
 
 ## 🎬 Demo
 
-<img src="https://unpkg.com/@signosoft/signpad-js@latest/docsVideo.gif" alt="Signosoft Demo" width="500" />
+<img src="https://unpkg.com/@signosoft/signpad-js@latest/presentation.gif" alt="Signosoft Signpad presentation" width="400" />
+
+<a id="tech-stack--built-with"></a>
 
-## ⚙️ Tech Stack / Built With
+## 🧰 Tech Stack / Built With
 
 - [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
 - [![Lit](https://img.shields.io/badge/Lit-4C64FF?logo=Lit&logoColor=white)](https://lit.dev/)
 - [![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=fff)](https://vitejs.dev/)
   <br/>
 
-## 🔐 Lease Setup
-
-To use the Signosoft Signpad component with physical signature hardware, a valid `lease` is **required**.
+<a id="device-compatibility"></a>
 
-#### 🛑 CRITICAL: Mandatory Initialization
-
-Without a valid lease, the component can still render, but driver initialization and hardware communication features will be <b>disabled</b>.
-
-### 1. Lease flow
-
-1. Generate/get your license key in Signosoft portal.
-2. Request a lease from the Signosoft lease API.
-3. Put the returned lease into `config.lease`.
-
-> Security note: In production, call the lease API from your backend and return only the lease to frontend.
-
-### 2. Frontend implementation (plain JavaScript reference)
-
-```JS
-async function fetchLease() {
-  try {
-    const response = await fetch(
-      "https://test.signosoft.com/api/v1/public/driver-leases/create",
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          token: "YOUR-LICENSE-TOKEN",
-          validityHours: 24,
-        }),
-      },
-    );
-
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(
-        `License server error: ${response.statusText} - ${errorText}`,
-      );
-    }
-
-    return await response.json();
-  } catch (error) {
-    console.error("Signosoft Signpad: License initialization failed", error);
-    throw error;
-  }
-}
-
-async function applyLeaseToConfig(currentConfig) {
-  const lease = await fetchLease();
-  return {
-    ...currentConfig,
-    lease,
-  };
-}
-```
-
-<br/>
-
-## 🖊️ Device Compatibility
+## 🔌 Device Compatibility
 
 The component communicates with signature tablets via the **WebHID API**. Devices are matched against a built-in configuration database; unrecognized devices fall back to a generic driver.
 
@@ -108,6 +63,8 @@ The component communicates with signature tablets via the **WebHID API**. Device
 
 > **Mouse fallback:** If no supported device is connected (or the user dismisses the HID picker), the component automatically activates mouse/touch input so signing can still proceed in the browser.
 
+<a id="installation"></a>
+
 ## 📦 Installation
 
 Install the library via npm:
@@ -126,131 +83,119 @@ yarn add @signosoft/signpad-js
 pnpm add @signosoft/signpad-js
 ```
 
-### 🌍 Environment Requirements
+<a id="environment-requirements"></a>
+
+## 🌍 Environment Requirements
 
 To ensure proper communication via the **WebHID API**:
 
-- **HTTPS:** Required for all production environments (WebHID security policy).
+- **HTTPS:** Required for all production environments (WebHID security policy). `http://localhost` is allowed for development.
+- **User gesture:** The browser only opens the HID device picker in response to a user action (click/tap). The built-in Connect button already satisfies this; if you call `connect()` yourself, do it from an event handler (click/tap). The browser rejects the picker otherwise and the component falls back to mouse mode if enabled. Devices the user already authorized are reconnected without the picker.
 - **Supported Browsers:** Chrome 89+, Edge 89+, Opera (Chromium-based).
+- **Server-side rendering:** the package can be imported on the server, but the component only works in the browser (WebHID, canvas). Create it on the client, for example after the first render.
 - **TypeScript:** Built-in support; no extra `@types` needed.
-  <br/>
 
-## 🚀 Quick Start
+<a id="lease-setup"></a>
 
-First, install the core package:
+## 🔐 Lease Setup
 
-```bash
-npm install @signosoft/signpad-js
-```
+To use the Signosoft Signpad component with physical signature hardware, a valid `lease` is **required**.
 
-### 🧰 Framework Integration Guide
+### CRITICAL: Mandatory Initialization
 
-<details>
-<summary>
-  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="15" height="15">
-  <b>Angular</b> <font color="green"><b>(Live)</b></font>
-</summary>
-<br>
+Without a valid lease, the component can still render, but driver initialization and hardware communication features will be <b>disabled</b>.
 
-# <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angular/angular-original.svg" alt="Angular" width="30" height="30"> Angular Integration Guide
+### 1. Lease flow
 
-This guide describes how to integrate the `@signosoft/signpad-js` web component into an Angular application.
+1. Go to https://apps.signosoft.com/
+2. Create account
+3. In dashboard go to "manage account" -> "licence"
+4. Create licence with your desired origins
+5. Done
 
-## 1. Installation
+> Security note: In production, call the lease API from your backend and return only the lease to frontend.
 
-Install the core package using npm:
+### 2. Pricing
 
-```bash
-npm install @signosoft/signpad-js
-```
+Every signature completed on the signpad is billed against the credits of your lease: **0.0050 USD per signature** (JavaScript driver), excluding VAT. Current prices are on [signosoft.com/pricing](https://www.signosoft.com/pricing). When the credits run out, the component stops signing and reports `BIL-01` (`BILLING_DENIED`, see [error codes](#signpaderrorcode)).
 
-## 2. Create the Bridge Directive
+<a id="quick-start"></a>
 
-Since `signosoft-signpad` is a Web Component, Angular requires a Directive to properly sync configuration changes and provide typed access to the component instance.
+## 🚀 Quick Start
 
-Create `signosoft-signpad.directive.ts`:
+Every example below logs the finished signature in `onOk`; what that data contains is described in [Signature result](#signature-result-isignatureconfirmationdata). Before the framework guides, install the package ([Installation](#installation)), check the [requirements](#environment-requirements) and get a [lease](#lease-setup).
 
-```typescript
-import {
-  Directive,
-  ElementRef,
-  Input,
-  OnChanges,
-  SimpleChanges,
-} from "@angular/core";
-import type { SignosoftSignpad, SignpadConfig } from "@signosoft/signpad-js";
+> **Plain JS snippets:** in this document `signosoftPad` is the element, obtained once like this. Framework guides (Angular, React, Vue) get it through their own refs.
+>
+> ```js
+> const signosoftPad = document.querySelector("signosoft-signpad");
+> ```
 
-@Directive({
-  selector: "signosoft-signpad",
-  standalone: true,
-})
-export class SignosoftSignpadDirective implements OnChanges {
-  @Input() config?: SignpadConfig;
+> **Size:** the component renders at a fixed `25rem × 31.25rem` (400×500 px) by itself; no wrapper element is needed. To resize or make it fluid, set `--signpad-width` / `--signpad-height` (see [Layout & Constraints](#layout--constraints)).
 
-  constructor(private host: ElementRef<SignosoftSignpad>) {}
+### Framework Integration Guide
 
-  // Access the native Web Component instance
-  get signpadRef(): SignosoftSignpad {
-    return this.host.nativeElement;
-  }
+<details>
+<summary>
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="15" height="15">
+  <b>Angular</b> <font color="green"><b>(Live)</b></font>
+</summary>
+<br>
 
-  ngOnChanges(changes: SimpleChanges) {
-    const el = this.host.nativeElement as any;
-    for (const key of Object.keys(changes)) {
-      el[key] = (this as any)[key];
-    }
-  }
-}
-```
+#### <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angular/angular-original.svg" alt="Angular" width="30" height="30"> Angular Integration Guide
+
+This guide describes how to integrate the `@signosoft/signpad-js` web component into an Angular application. It uses the current signal-based Angular APIs (`viewChild()`, `afterNextRender()`), so it needs **Angular 20 or newer** (standalone components are the default, so there is no `standalone: true`).
 
-## 3. Implementation in Component
+##### 1. Implementation in Component
 
-Import the library, the directive, and add the **`CUSTOM_ELEMENTS_SCHEMA`**.
+Import the library and add the **`CUSTOM_ELEMENTS_SCHEMA`**. Angular passes `[config]` to the element as a property, so no extra wrapper is needed.
 
 ```typescript
 import {
   Component,
-  ViewChild,
   CUSTOM_ELEMENTS_SCHEMA,
-  AfterViewInit,
+  ElementRef,
+  afterNextRender,
   signal,
+  viewChild,
 } from "@angular/core";
-import "@signosoft/signpad-js"; // Import the Web Component registration
-import {
-  type SignosoftSignpad,
-  type SignpadConfig,
-} from "@signosoft/signpad-js";
-import { SignosoftSignpadDirective } from "./directives/signosoft-signpad.directive";
+import "@signosoft/signpad-js"; // Registers the Web Component
+import type { SignosoftSignpad, SignpadConfig } from "@signosoft/signpad-js";
 
 @Component({
   selector: "app-root",
-  standalone: true,
-  imports: [SignosoftSignpadDirective],
-  templateUrl: "./app.component.html",
+  templateUrl: "./app.html",
   schemas: [CUSTOM_ELEMENTS_SCHEMA], // Mandatory for custom HTML tags
 })
-export class AppComponent implements AfterViewInit {
-  @ViewChild(SignosoftSignpadDirective)
-  signpadDirective!: SignosoftSignpadDirective;
+export class App {
+  // The element behind #pad in the template: call ok(), clear(), startSigning() on it
+  readonly pad = viewChild.required<ElementRef<SignosoftSignpad>>("pad");
 
-  public config = signal<SignpadConfig>({
+  readonly config = signal<SignpadConfig>({
     lease: undefined,
+    eventCallbacks: {
+      onOk: (event) => {
+        // The signature: [points, imageBase64, metadata]
+        const [points, imageBase64, metadata] = event.detail;
+        console.log(points, imageBase64, metadata);
+      },
+    },
   });
 
-  async ngAfterViewInit() {
-    await this.applyLeaseToConfig();
+  constructor() {
+    // Runs in the browser after the first render
+    afterNextRender(() => this.applyLeaseToConfig());
   }
 
-  public async fetchLease(): Promise<any> {
+  async fetchLease(): Promise<any> {
     try {
       const response = await fetch(
-        "https://test.signosoft.com/api/v1/public/driver-leases/create",
+        "https://api-test.signosoft.com/v1/public/driver-leases",
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({
-            token: "YOUR-LICENSE-TOKEN",
-            validityHours: 24,
+            key: "YOUR-LICENSE-TOKEN",
           }),
         },
       );
@@ -269,7 +214,7 @@ export class AppComponent implements AfterViewInit {
     }
   }
 
-  public async applyLeaseToConfig() {
+  async applyLeaseToConfig() {
     const lease = await this.fetchLease();
     this.config.update((currentConfig) => ({
       ...currentConfig,
@@ -277,23 +222,78 @@ export class AppComponent implements AfterViewInit {
     }));
   }
 
-  // Helper to access methods easily (ok, clear, cancel, etc.)
-  public get signpad(): SignosoftSignpad | undefined {
-    return this.signpadDirective?.signpadRef;
+  // Example: start a new session with blue ink from your own button
+  startBlue() {
+    return this.pad().nativeElement.startSigning({ color: "#0000ff" });
   }
 }
 ```
 
-## 4. Component Template
+##### 2. Component Template
 
-Use the custom tag in your HTML and bind the configuration object.
+Use the custom tag in your HTML, name it with `#pad` and bind the configuration object.
 
 ```html
-<div>
-  <div>
-    <signosoft-signpad [config]="config()"></signosoft-signpad>
-  </div>
-</div>
+<signosoft-signpad #pad [config]="config()"></signosoft-signpad>
+<button (click)="startBlue()">Sign with blue ink</button>
+```
+
+The `config` signal is the only link between your code and the component: assign a new object to it and the component updates. `this.pad().nativeElement` is the element itself, so every method from [Methods](#methods) is available on it.
+
+##### 3. Optional: a typed directive
+
+Not required. Add it if you want Angular to type-check `[config]` in templates and a typed handle to the element (`instance`) instead of `viewChild<ElementRef>`.
+
+```typescript
+// signosoft.directive.ts
+import { Directive, ElementRef, effect, inject, input } from "@angular/core";
+import type { SignosoftSignpad, SignpadConfig } from "@signosoft/signpad-js";
+
+@Directive({ selector: "signosoft-signpad" })
+export class SignosoftSignpadDirective {
+  readonly config = input<SignpadConfig>();
+  private readonly host = inject<ElementRef<SignosoftSignpad>>(ElementRef);
+
+  get instance(): SignosoftSignpad {
+    return this.host.nativeElement;
+  }
+
+  constructor() {
+    // Push every config change into the Web Component
+    effect(() => {
+      const config = this.config();
+      if (config) this.host.nativeElement.config = config;
+    });
+  }
+}
+```
+
+To use it, change three things in the component from steps 1 and 2:
+
+```typescript
+import { SignosoftSignpadDirective } from "./signosoft.directive";
+
+@Component({
+  selector: "app-root",
+  templateUrl: "./app.html",
+  imports: [SignosoftSignpadDirective], // importing the file is not enough, list the directive here
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class App {
+  // Finds the directive by its class instead of the #pad template reference
+  readonly pad = viewChild.required(SignosoftSignpadDirective);
+
+  startBlue() {
+    // .instance is the SignosoftSignpad element
+    return this.pad().instance.startSigning({ color: "#0000ff" });
+  }
+}
+```
+
+The template no longer needs `#pad`:
+
+```html
+<signosoft-signpad [config]="config()"></signosoft-signpad>
 ```
 
 </details>
@@ -305,19 +305,23 @@ Use the custom tag in your HTML and bind the configuration object.
 </summary>
 <br>
 
-# <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="30" height="30"> React - Quick start
+#### <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="30" height="30"> React - Quick start
 
 This guide describes how to integrate the `@signosoft/signpad-js` web component into a React application (Functional Components with Hooks).
 
-## 1. Installation
+It needs **React 19 or newer**: React 19 passes the `config` object to the custom element as a property. React 18 turns unknown JSX props into string attributes, so `config` would arrive as `"[object Object]"`. On React 18 assign it yourself in an effect:
+
+```tsx
+const signpadRef = useRef<any>(null);
 
-Install the core package using npm:
+useEffect(() => {
+  if (signpadRef.current) signpadRef.current.config = config;
+}, [config]);
 
-```bash
-npm install @signosoft/signpad-js
+return <signosoft-signpad ref={signpadRef} />;
 ```
 
-## 2. Implementation
+##### 1. Implementation
 
 In React, we use `useRef` for methods and `useEffect` to fetch a lease before updating config.
 
@@ -329,13 +333,12 @@ import type { SignpadConfig } from "@signosoft/signpad-js";
 async function fetchLease() {
   try {
     const response = await fetch(
-      "https://test.signosoft.com/api/v1/public/driver-leases/create",
+      "https://api-test.signosoft.com/v1/public/driver-leases",
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          token: "YOUR-LICENSE-TOKEN",
-          validityHours: 24,
+          key: "YOUR-LICENSE-TOKEN",
         }),
       },
     );
@@ -357,7 +360,16 @@ async function fetchLease() {
 function App() {
   // Use ref to access component methods (ok, clear, connect, etc. by signpadRef.current)
   const signpadRef = useRef<any>(null);
-  const [config, setConfig] = useState<SignpadConfig>({ lease: undefined });
+  const [config, setConfig] = useState<SignpadConfig>({
+    lease: undefined,
+    eventCallbacks: {
+      onOk: (event) => {
+        // The signature: [points, imageBase64, metadata]
+        const [points, imageBase64, metadata] = event.detail;
+        console.log(points, imageBase64, metadata);
+      },
+    },
+  });
 
   useEffect(() => {
     fetchLease().then((lease) => setConfig((prev) => ({ ...prev, lease })));
@@ -383,19 +395,11 @@ export default App;
 </summary>
 <br>
 
-# <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="30" height="30"> Vue.js Integration Guide
+#### <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="30" height="30"> Vue.js Integration Guide
 
 This guide describes how to integrate the `@signosoft/signpad-js` web component into a Vue 3 application using the Composition API (`<script setup>`).
 
-## 1. Installation
-
-Install the core package using npm:
-
-```bash
-npm install @signosoft/signpad-js
-```
-
-## 2. Configure Vue to recognize Custom Elements
+##### 1. Configure Vue to recognize Custom Elements
 
 By default, Vue will try to resolve `signosoft-signpad` as a Vue component and will throw a warning. You need to tell Vue to ignore this tag.
 
@@ -419,7 +423,7 @@ export default defineConfig({
 });
 ```
 
-## 3. Implementation
+##### 2. Implementation
 
 In Vue 3, we use `ref` for both the element and config, then fetch the lease and assign it to config.
 
@@ -432,16 +436,24 @@ import type { SignpadConfig, SignosoftSignpad, IPenData } from "@signosoft/signp
 // Use ref to access component methods (ok, clear, connect, etc. by signpadRef.value)
 const signpadRef = ref<SignosoftSignpad | null>(null);
 
-const signpadConfig = ref<SignpadConfig>({ lease: undefined });
+const signpadConfig = ref<SignpadConfig>({
+  lease: undefined,
+  eventCallbacks: {
+    onOk: (event) => {
+      // The signature: [points, imageBase64, metadata]
+      const [points, imageBase64, metadata] = event.detail;
+      console.log(points, imageBase64, metadata);
+    },
+  },
+});
 
 const fetchLease = async () => {
   try {
-    const response = await fetch("https://test.signosoft.com/api/v1/public/driver-leases/create", {
+    const response = await fetch("https://api-test.signosoft.com/v1/public/driver-leases", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        token: "YOUR-LICENSE-TOKEN",
-        validityHours: 24,
+        key: "YOUR-LICENSE-TOKEN",
       }),
     });
 
@@ -486,21 +498,15 @@ fetchLease()
 </summary>
 <br>
 
-# 🍦 Vanilla JS Integration Guide
+#### 🍦 Vanilla JS Integration Guide
 
 This guide describes how to integrate the `@signosoft/signpad-js` web component into a plain JavaScript project without any frameworks.
 
-## 1. Installation
+##### 1. Load the component
 
-Install the package via npm:
+Install the package first (see [Installation](#installation)). If you are not using a bundler, you can include the script directly in your HTML (ensure the path points to the compiled bundle in `node_modules` or a CDN).
 
-```bash
-npm install @signosoft/signpad-js
-```
-
-Or, if you are not using a bundler, you can include the script directly in your HTML (ensure the path points to the compiled bundle in `node_modules` or a CDN).
-
-## 2. JavaScript Implementation
+##### 2. JavaScript Implementation
 
 In Vanilla JS, you interact with the component by selecting it from the DOM and assigning the configuration directly to its `config` property.
 
@@ -512,23 +518,29 @@ import "@signosoft/signpad-js";
  * Helps VS Code provide autocomplete for methods and properties.
  * @type {import('@signosoft/signpad-js').SignosoftSignpad}
  */
-const pad = document.querySelector("signosoft-signpad");
+const signosoftPad = document.querySelector("signosoft-signpad");
 
 // 1. Initial Configuration
-pad.config = {
+signosoftPad.config = {
   lease: undefined,
+  eventCallbacks: {
+    onOk: (event) => {
+      // The signature: [points, imageBase64, metadata]
+      const [points, imageBase64, metadata] = event.detail;
+      console.log(points, imageBase64, metadata);
+    },
+  },
 };
 
 const fetchLease = async () => {
   try {
     const response = await fetch(
-      "https://test.signosoft.com/api/v1/public/driver-leases/create",
+      "https://api-test.signosoft.com/v1/public/driver-leases",
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          token: "YOUR-LICENSE-TOKEN",
-          validityHours: 24,
+          key: "YOUR-LICENSE-TOKEN",
         }),
       },
     );
@@ -548,13 +560,13 @@ const fetchLease = async () => {
 };
 
 fetchLease().then((lease) => {
-  pad.config = { ...pad.config, lease };
+  signosoftPad.config = { ...signosoftPad.config, lease };
 });
 ```
 
-## 3. HTML Structure
+##### 3. HTML Structure
 
-Add the custom element tag to your HTML and create the necessary control buttons.
+Add the custom element tag to your HTML. The component renders its own Connect, OK, Clear and Cancel buttons, so no extra controls are required.
 
 ```html
 <!-- index.html -->
@@ -574,15 +586,17 @@ Add the custom element tag to your HTML and create the necessary control buttons
 </html>
 ```
 
-## 4. Key Concepts
+##### 4. Key Concepts
 
 - **Direct Property Assignment:** Unlike some frameworks that use attributes, in Plain JS you should assign the configuration directly: `element.config = { ... }`.
 - **Module System:** Ensure your `<script>` tag has `type="module"` to use the `import` statement.
 - **Methods:** All methods like `.connect()`, `.ok()`, and `.clear()` are available directly on the DOM element object.
-- **DOM Events:** The component dispatches standard DOM events (like `sign-ok`, `sign-clear`) which you can listen to using `addEventListener`.
+- **DOM Events:** every callback is also dispatched as a DOM `CustomEvent` (name in the "DOM event" column of [Event Callbacks](#eventcallbacks)) that bubbles and crosses shadow boundaries, so you can use `addEventListener` on the element or a parent.
 
 </details>
 
+<a id="properties"></a>
+
 ## 📋 Properties
 
 The component is primarily configured through a single `config` property. This object controls everything from licensing and hardware behavior to UI visibility and localization.
@@ -591,30 +605,36 @@ The component is primarily configured through a single `config` property. This o
 | :------- | :-------------- | :------ | :----------------------------------------------- |
 | `config` | `SignpadConfig` | `{}`    | The main configuration object for the component. |
 
-### 🔑 Core Options
+### What goes in `config`
 
-| Option      | Type     | Required                   | Description                                                                                                                                                                                   |
-| :---------- | :------- | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`lease`** | `object` | Required for hardware mode | Lease payload returned from the lease API call. The component still renders without it, but driver initialization and hardware communication are disabled (see [Lease Setup](#-lease-setup)). |
+Everything below is a key of the one `config` object. Every key is optional.
 
-### 👁️ uiVisibilityOptions
+```typescript
+const config: SignpadConfig = {
+  lease: {}, // licence, required for hardware mode
+  theme: "light", // look: "light" | "dark" | "auto"
+  languageOptions: {}, // texts
+  uiVisibilityOptions: {}, // show/hide UI parts
+  canvasAndDrawingOptions: {}, // pen color and width
+  actionHandlers: {}, // your code in the OK/Clear/Cancel flow
+  eventCallbacks: {}, // observe events
+};
+```
 
-Toggles the visibility of specific User Interface elements.
+**Not part of `config`:**
+
+- **Methods** such as `connect()`, `startSigning()`, `ok()` are called on the element, see [Methods](#methods).
+- **DOM events** can be listened to with `addEventListener`, see [`eventCallbacks`](#eventcallbacks).
+- **Size and colors of the component** are CSS variables, see [Styling & Theming](#styling--theming).
+- **What you get back** (signature, errors) is described in [Results & Errors](#results--errors).
+
+### `lease`
 
-| Field                        | Type      | Default | Description                                                       |
-| :--------------------------- | :-------- | :------ | :---------------------------------------------------------------- |
-| `topBarVisible`              | `boolean` | `true`  | Shows/hides the entire top navigation bar.                        |
-| `topBarClearButtonVisible`   | `boolean` | `false` | Shows a "Clear" button in the top-left corner.                    |
-| `topBarConnectButtonVisible` | `boolean` | `true`  | Shows the connect/disconnect button area in the top-right corner. |
-| `bottomBarVisible`           | `boolean` | `true`  | Shows/hides the entire bottom action bar.                         |
-| `okButtonVisible`            | `boolean` | `true`  | Shows the **OK** button in the bottom bar.                        |
-| `clearButtonVisible`         | `boolean` | `true`  | Shows the **Clear** button in the bottom bar.                     |
-| `cancelButtonVisible`        | `boolean` | `true`  | Shows the **Cancel** button in the bottom bar.                    |
-| `canvasLineVisible`          | `boolean` | `true`  | Shows the horizontal signature guide line on the canvas.          |
-| `deviceStatusTextVisible`    | `boolean` | `true`  | Shows the name of the connected device (e.g., "Wacom STU-540").   |
-| `additionalTextVisible`      | `boolean` | `true`  | Shows helper status messages (e.g., "Ready to sign").             |
-
-### 🖋️ canvasAndDrawingOptions
+| Option      | Type     | Required                   | Description                                                                                                                                                                                  |
+| :---------- | :------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`lease`** | `object` | Required for hardware mode | Lease payload returned from the lease API call. The component still renders without it, but driver initialization and hardware communication are disabled (see [Lease Setup](#lease-setup)). |
+
+### `canvasAndDrawingOptions`
 
 Adjusts the visual appearance of the digital ink.
 
@@ -626,112 +646,132 @@ Adjusts the visual appearance of the digital ink.
 
 > Note: Since standard mice do not support physical pressure, the system emulates a normalized pressure of 0.5, ensuring consistent line rendering during fallback sessions.
 
-### 🌐 languageOptions
+### `uiVisibilityOptions`
 
-Handles component localization. It can load external files or use inline definitions.
+Toggles the visibility of specific User Interface elements.
 
-| Field          | Type     | Description                                                                                                                                                 |
-| :------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lang`         | `string` | The active language code. Built-in translations are bundled for `'en'` and `'cs'`; other languages (including `'pt'`) require `langPath` or `translations`. |
-| `langPath`     | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format.                                                                          |
-| `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files.                                                       |
+| Field                            | Type      | Default | Description                                                                                                                                                                                                                                                                                                                  |
+| :------------------------------- | :-------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `topBarVisible`                  | `boolean` | `true`  | Shows/hides the entire top navigation bar.                                                                                                                                                                                                                                                                                   |
+| `topBarClearButtonVisible`       | `boolean` | `false` | Shows a "Clear" button in the top-left corner.                                                                                                                                                                                                                                                                               |
+| `topBarConnectButtonVisible`     | `boolean` | `true`  | Shows the connect/disconnect button area in the top-right corner. The button is hidden while an OK, Clear or Cancel action is processing.                                                                                                                                                                                    |
+| `bottomBarVisible`               | `boolean` | `true`  | Shows/hides the entire bottom action bar.                                                                                                                                                                                                                                                                                    |
+| `okButtonVisible`                | `boolean` | `true`  | Shows the **OK** button in the bottom bar.                                                                                                                                                                                                                                                                                   |
+| `clearButtonVisible`             | `boolean` | `true`  | Shows the **Clear** button in the bottom bar.                                                                                                                                                                                                                                                                                |
+| `cancelButtonVisible`            | `boolean` | `true`  | Shows the **Cancel** button in the bottom bar.                                                                                                                                                                                                                                                                               |
+| `canvasLineVisible`              | `boolean` | `true`  | Shows the horizontal signature guide line on the canvas.                                                                                                                                                                                                                                                                     |
+| `deviceStatusTextVisible`        | `boolean` | `true`  | Shows the name of the connected device (e.g., "Wacom STU-540").                                                                                                                                                                                                                                                              |
+| `additionalTextVisible`          | `boolean` | `true`  | Shows helper status messages (e.g., "Ready to sign").                                                                                                                                                                                                                                                                        |
+| `startNewSignatureButtonVisible` | `boolean` | `true`  | After OK or Cancel the signing session is over and nothing is captured until `startSigning()` is called. While in that state the bottom bar shows a **Start new signature** button instead of OK/Clear/Cancel. Set `false` to hide it and call `startSigning()` yourself (it is also hidden with `bottomBarVisible: false`). |
+
+### `languageOptions`
 
-## 🌐 Localization & Translation Keys
+Handles component localization. It can load external files or use inline definitions.
 
-Localization is driven from `languageOptions`, but you can also provide overrides at runtime:
-
-1. **Set the language code** in `config.languageOptions.lang`. English (`en`) is the fallback, and Czech (`cs`) is bundled alongside it. Other languages, including Portuguese (`pt`), must be supplied via `langPath` or `translations` — they are not bundled.
-2. **Load a hosted file** by pointing `languageOptions.langPath` to the directory that contains `[lang].json`. The loader will fetch `${langPath}/${lang}.json` (or the exact file if you include the `.json` suffix).
-3. **Override only specific phrases** by passing a `translations` object—either a flat key map or a per-language map (`{ en: {...}, cs: {...} }`). Inline values take precedence over both built-in and fetched files.
-4. **Dynamic placeholders** (for example, `{device}` in `TEXT_SIGNING_WITH_DEVICE`) are replaced using the `LocalizationManager.t` helper. Keep the braces intact if you expect runtime interpolation.
-
-The complete list of keys that can be translated is maintained in `src/i18n/en.json`. You can copy the structure when creating new language files or inline overrides. The defaults are:
-
-| Key                          | Default (English)                                   |
-| :--------------------------- | :-------------------------------------------------- |
-| `OK`                         | OK                                                  |
-| `CLEAR`                      | Clear                                               |
-| `CANCEL`                     | Cancel                                              |
-| `CLEAR_SIGNATURE`            | Clear signature                                     |
-| `DISCONNECT`                 | Disconnect                                          |
-| `CONNECT_SIGNPAD`            | Connect Signpad                                     |
-| `MOUSE`                      | Mouse                                               |
-| `CONNECTED_UNKNOWN_DEVICE`   | Connected (Unknown Device)                          |
-| `AUTO_CONNECTING`            | Auto-connecting to device...                        |
-| `CONNECTING_TO_DEVICE`       | Connecting to your device...                        |
-| `REVERTING_TO_DEFAULT`       | Reverting to default input...                       |
-| `DISCONNECTING_DEVICE`       | Disconnecting device...                             |
-| `COMPONENT_INITIALIZED`      | Component initialized.                              |
-| `TEXT_START_SIGNING`         | Connect your device.                                |
-| `TEXT_SIGN_WITH_PHYSICAL`    | Please sign using the device pen.                   |
-| `TEXT_SIGN_WITH_MOUSE`       | Please sign using your mouse.                       |
-| `TEXT_SIGN_GENERIC`          | Sign in the area above using mouse or pen.          |
-| `TEXT_SIGNING_WITH_DEVICE`   | Signing with {device}                               |
-| `NO_DEVICE_FOUND`            | No device found.                                    |
-| `CONNECTION_ERROR`           | Connection error.                                   |
-| `ERROR_DISCONNECTION`        | Error during disconnection.                         |
-| `ERROR_INSTANTIATING_DRIVER` | Error instantiating driver.                         |
-| `INSUFFICIENT_TOKENS`        | Not enough tokens to sign. Reconnecting…            |
-| `INVALID_LICENSE_KEY`        | Invalid license key.                                |
-| `READY_TO_CONNECT`           | Ready to connect.                                   |
-| `SIGNPAD_DETECTED`           | Signpad detected. Click 'Connect Signpad' to begin. |
-| `READY_TO_SIGN_MOUSE`        | Ready to sign. Use your mouse.                      |
-| `READY_TO_SIGN_PHYSICAL`     | Ready to sign. Use the device pen.                  |
+| Field          | Type     | Description                                                                                                                                                                                        |
+| :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lang`         | `string` | The active language code. Built-in translations are bundled for `'en'`, `'cs'` and `'pt'`; other languages require `langPath` or `translations` (see [Applying a language](#applying-a-language)). |
+| `langPath`     | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format.                                                                                                                 |
+| `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files.                                                                                              |
 
-If you add any new keys, mirror them in every language file you provide to guarantee they fall back gracefully to English.
+### `theme`
 
-### ⚙️ Logic & Events
+Color theme of the component.
 
-The component provides two ways to interact with internal processes.
+| Option      | Type                          | Required                    | Description                                                                                                                                                                                                                                                                                                                                                   |
+| :---------- | :---------------------------- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`theme`** | `'light' \| 'dark' \| 'auto'` | Optional, default `'light'` | Color theme. `'dark'` switches the bars, buttons and overlay to the dark design tokens; `'auto'` follows the OS `prefers-color-scheme` and updates live. The signature canvas stays light in every theme, because the default ink is black. Exported as type `SignpadTheme`. The component sets `data-theme` on its host element, so you can style around it. |
 
-#### 🛠️ Action Handlers (`actionHandlers`)
+### `actionHandlers`
 
 These allow you to **inject custom logic** directly into the internal button flows. Your code runs alongside the component's internal logic.
 
-| Handler        | Arguments                           | Description                                                             |
-| :------------- | :---------------------------------- | :---------------------------------------------------------------------- |
-| `handleOk`     | `data?: ISignatureConfirmationData` | Extends the internal OK button logic. Receives captured signature data. |
-| `handleClear`  | —                                   | Extends the internal Clear button logic.                                |
-| `handleCancel` | —                                   | Extends the internal Cancel button logic.                               |
+| Handler        | Arguments                           | Description                                                                                                                                  |
+| :------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handleOk`     | `data?: ISignatureConfirmationData` | Extends the internal OK button logic. Receives the captured signature, see [Signature result](#signature-result-isignatureconfirmationdata). |
+| `handleClear`  | —                                   | Extends the internal Clear button logic.                                                                                                     |
+| `handleCancel` | —                                   | Extends the internal Cancel button logic.                                                                                                    |
+
+Handlers may be `async`. The component awaits them, and only then dispatches the matching `sign-ok` / `sign-clear` / `sign-cancel` event.
+
+```typescript
+const config: SignpadConfig = {
+  lease,
+  actionHandlers: {
+    // Runs after the signature is captured, before `sign-ok` is dispatched
+    handleOk: async (data) => {
+      if (!data) return;
+      const [, imageBase64, metadata] = data;
+      await fetch("/api/signatures", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ imageBase64, metadata }),
+      });
+    },
+    handleClear: () => console.log("Signature cleared"),
+    handleCancel: () => console.log("Signing cancelled"),
+  },
+};
+```
 
-#### 🔔 Event Callbacks (`eventCallbacks`)
+### `eventCallbacks`
 
 Standard event listeners triggered _after_ specific actions. Useful for observing the component from your application state.
 
-| Callback       | Payload                                          | Description                                                                                        |
-| :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------------- |
-| `onPen`        | `event: CustomEvent<IPenData>`                   | Dispatched when a device or mouse fallback are in contact with component or signature pad display. |
-| `onConnecting` | `event: CustomEvent<void>`                       | Dispatched when a device is in loading state.                                                      |
-| `onConnect`    | `event: CustomEvent<{ deviceInfo: any }>`        | Dispatched when a device or mouse fallback connects.                                               |
-| `onDisconnect` | `event: CustomEvent<void>`                       | Dispatched when the hardware connection is closed.                                                 |
-| `onOk`         | `event: CustomEvent<ISignatureConfirmationData>` | Dispatched when signature is confirmed.                                                            |
-| `onClear`      | `event: CustomEvent<void>`                       | Dispatched when the canvas has been cleared.                                                       |
-| `onCancel`     | `event: CustomEvent<void>`                       | Dispatched when the user aborts the session.                                                       |
-| `onError`      | `event: CustomEvent<ISignpadErrorDetail>`        | Dispatched on critical failures (lease, driver, connection, billing, etc.).                        |
+| Callback       | DOM event         | Payload                                          | Description                                                                                                                                       |
+| :------------- | :---------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `onPen`        | `sign-pen`        | `event: CustomEvent<IPenData>`                   | Dispatched when a device or mouse fallback are in contact with component or signature pad display.                                                |
+| `onConnecting` | `sign-connecting` | `event: CustomEvent<void>`                       | Dispatched when a device is in loading state.                                                                                                     |
+| `onConnect`    | `sign-connect`    | `event: CustomEvent<{ deviceInfo: any }>`        | Dispatched when a device or mouse fallback connects.                                                                                              |
+| `onDisconnect` | `sign-disconnect` | `event: CustomEvent<void>`                       | Dispatched when the hardware connection is closed.                                                                                                |
+| `onOk`         | `sign-ok`         | `event: CustomEvent<ISignatureConfirmationData>` | Dispatched when signature is confirmed. The signature is in `event.detail`, see [Signature result](#signature-result-isignatureconfirmationdata). |
+| `onClear`      | `sign-clear`      | `event: CustomEvent<void>`                       | Dispatched when the canvas has been cleared.                                                                                                      |
+| `onCancel`     | `sign-cancel`     | `event: CustomEvent<void>`                       | Dispatched when the user aborts the session.                                                                                                      |
+| `onError`      | `sign-error`      | `event: CustomEvent<ISignpadErrorDetail>`        | Dispatched on critical failures (lease, driver, connection, billing, etc.).                                                                       |
 
 > `actionHandlers` and `eventCallbacks` are separate hooks and can both be configured.
 
-#### 🚨 `onError` payload (`ISignpadErrorDetail`)
+**Listening with the config.** Pass the callbacks in `eventCallbacks`; each receives the `CustomEvent`:
 
 ```typescript
-{
-  category: SignpadErrorCategory; // BILLING_DENIED | NETWORK | OTHER
-  message: string; // error.message, for convenience
-  error: Error; // the original error
-}
+const config: SignpadConfig = {
+  lease,
+  eventCallbacks: {
+    onOk: (event) => {
+      const [points, imageBase64] = event.detail; // see Signature result
+      console.log(`${points.length} points`, imageBase64);
+    },
+  },
+};
 ```
 
-`category` also drives automatic recovery:
+**Listening without the config.** Every callback is also a DOM event (column "DOM event"), so `addEventListener` works on the element like on any other:
 
-- **`BILLING_DENIED`** — the lease has run out of signing credits/tokens. Signing automatically restarts a few seconds after the error is shown.
-- **`OTHER`** — any other recoverable failure (e.g. a driver hiccup, a cancelled device picker). Signing automatically restarts the same way as `BILLING_DENIED`.
-- **`NETWORK`** — a connectivity problem (lease fetch failed, device physically disconnected, origin validation failed). The error stays shown; signing does **not** auto-restart, since retrying on a timer can't fix a network or configuration problem — the user (or your app) must retry manually, e.g. via `connect()`.
+```js
+signosoftPad.addEventListener("sign-ok", (event) => {
+  const [points, imageBase64] = event.detail; // see Signature result
+  console.log(`${points.length} points`, imageBase64);
+});
+```
+
+#### `onPen` payload
+
+`onPen` is emitted continuously while writing and provides a single `IPenData` object in `event.detail`.
 
-> **Migration note (breaking payload shape change):** `event.detail` used to be the raw `Error`. It is now `ISignpadErrorDetail`; use `event.detail.error` for the original `Error` instance. `event.detail.message` still works unchanged.
+```typescript
+interface IPenData {
+  relativeX: number; // normalized 0..1
+  relativeY: number; // normalized 0..1
+  pressure?: number;
+  timestamp?: number; // Unix ms (Date.now()) at the time of capture
+  inContact: boolean;
+  [key: string]: any; // the driver may add more fields; the component does not populate absoluteX, absoluteY, ready or sequence
+}
+```
 
 ---
 
-### 💡 Example Implementation
+### Full example
 
 ```typescript
 this.config = {
@@ -752,6 +792,131 @@ this.config = {
 };
 ```
 
+<a id="results--errors"></a>
+
+## 📤 Results & Errors
+
+What the component hands back to your code: the captured signature and the errors it reports.
+
+### Signature result (`ISignatureConfirmationData`)
+
+The captured signature arrives in three places, always in the same shape: `ok()` returns it, `actionHandlers.handleOk(data)` receives it, and `eventCallbacks.onOk` (DOM event `sign-ok`) carries it in `event.detail`.
+
+It is an **array of three items**, not an object, so read it by position or destructure it:
+
+```ts
+eventCallbacks: {
+  onOk: (event) => {
+    const [points, imageBase64, metadata] = event.detail;
+  },
+},
+```
+
+| Index | Name          | Type             | Content                                |
+| :---- | :------------ | :--------------- | :------------------------------------- |
+| `0`   | `points`      | `IPenData[]`     | Every captured pen sample.             |
+| `1`   | `imageBase64` | `string \| null` | PNG data URL of the signature.         |
+| `2`   | `metadata`    | object           | Canvas size, tablet info and duration. |
+
+#### `[0]` points
+
+Every captured pen sample, in order. `pressure` is `0.5` on the mouse/touch fallback.
+
+```typescript
+interface IPenDataPoint {
+  relativeX: number; // normalized 0..1
+  relativeY: number; // normalized 0..1
+  absoluteX?: number; // not populated by the component
+  absoluteY?: number; // not populated by the component
+  pressure: number;
+  timestamp: number; // Unix ms (Date.now()) at the time of capture
+  inContact: boolean;
+}
+```
+
+#### `[1]` imageBase64
+
+Base64 PNG data URL of the signature, e.g. `"data:image/png;base64,iVBORw0KGgo..."`, or `null` if no image could be captured.
+
+#### `[2]` metadata
+
+The fields depend on whether a physical tablet or the mouse/touch fallback produced the signature.
+
+```typescript
+interface ISignatureResultMeta {
+  canvas?: ISignatureCanvasMeta;
+  // Physical tablet only. `undefined` on the mouse/touch fallback.
+  tablet?: ISignatureTabletMeta;
+  // Mouse/touch fallback only: seconds between the first and last pen sample.
+  // Not reported for a physical tablet.
+  duration?: number;
+  [key: string]: any;
+}
+
+interface ISignatureCanvasMeta {
+  width?: number;
+  height?: number;
+  // Mouse/touch fallback only:
+  cssWidth?: number;
+  cssHeight?: number;
+  dpr?: number;
+  // Physical tablet only:
+  top?: number;
+  left?: number;
+  right?: number;
+  bottom?: number;
+  [key: string]: any;
+}
+
+interface ISignatureTabletMeta {
+  name?: string;
+  aspectRatio?: number;
+  isCanvasStyleTablet?: boolean;
+  screenWidth?: number;
+  screenHeight?: number;
+  drawingArea?: { x: number; y: number; width: number; height: number };
+  serialNumber?: string | Promise<string>;
+  vendorId?: number | null;
+  productId?: number | null;
+  [key: string]: any;
+}
+```
+
+---
+
+### Error handling (`onError`)
+
+Critical failures (lease, driver, connection, billing, ...) do not throw. The component switches to the `ERROR` state, shows an overlay and reports the failure through `eventCallbacks.onError` (DOM event `sign-error`). Branch on `event.detail.code`:
+
+```typescript
+const config: SignpadConfig = {
+  lease,
+  eventCallbacks: {
+    onError: (event) => {
+      const { code, message, error } = event.detail;
+      if (code === SignpadErrorCode.BILLING_DENIED) {
+        notifyAdmin("Out of signing credits");
+      }
+      console.error(code, message, error);
+    },
+  },
+};
+```
+
+`event.detail` is `ISignpadErrorDetail`:
+
+```typescript
+interface ISignpadErrorDetail {
+  code: SignpadErrorCode; // "AREA-NN", e.g. "CON-01", see Error codes
+  message: string; // error.message, for convenience
+  error: Error; // the original error
+}
+```
+
+All values of `code`, what they mean and how the user recovers are in [Error codes](#error-codes).
+
+<a id="methods"></a>
+
 ## 🧩 Methods
 
 The following methods are available on the component instance to control the signing process programmatically.
@@ -766,190 +931,322 @@ The following methods are available on the component instance to control the sig
 | `clear()`        | `Promise<void>`                                    | Wipes the signature from the UI and hardware without ending the session.         |
 | `cancel()`       | `Promise<void>`                                    | Aborts the current session and resets the component state.                       |
 
+**Example:** a full signing round. The snippets for each method below call the method on the same `signosoftPad` element.
+
+```js
+await signosoftPad.connect(); // opens the WebHID picker, so call it from a click handler
+
+// ... the user signs ...
+
+const data = await signosoftPad.ok(); // ends the session and returns the signature
+if (data) {
+  const [points, imageBase64, metadata] = data;
+  console.log(`${points.length} points`, imageBase64, metadata);
+}
+
+// OK and Cancel end the session, so start a new one before the next signature
+await signosoftPad.startSigning();
+```
+
 ---
 
-#### 📜 `connect()`
+### `connect()`
+
+Connects a device to the component. Because it uses the **WebHID API**, it must be triggered by a **user gesture** (like a button click) to satisfy browser security requirements.
 
-This is the primary method to start using the Signpad. Because it uses the **WebHID API**, this must be triggered by a **user gesture** (like a button click) to satisfy browser security requirements.
+```js
+await signosoftPad.connect(); // call it from a click handler
+```
+
+It first tries to silently reconnect to a previously authorized device. If that fails, it opens the browser's device selection dialog and, if no physical device is selected, falls back to mouse/touch mode automatically.
 
-The method first attempts to silently reconnect to a previously authorized device. If that fails, it opens the browser's device selection dialog and, if no physical device is selected, falls back to mouse/touch mode automatically.
+**Returns:** `Promise<void>`, resolved once the connection attempt (or fallback) is complete.
 
-**Returns:**
+**Tip:** always call it from a click handler so the user can pick their device from the browser list.
 
-- A `Promise<void>` that resolves once the connection attempt (or fallback) is complete.
+---
 
-#### 📜 `disconnect()`
+### `disconnect()`
 
 Safely terminates the communication channel with the signature tablet.
 
-**What happens during disconnect:**
+```js
+await signosoftPad.disconnect();
+```
+
+What happens:
 
 1. The hardware driver is stopped and released.
 2. The internal cache of device information is cleared.
-3. The component UI transitions back to the `DISCONNECTED` state.
+3. The component switches to mouse input (`CONNECTED_MOUSE_FALLBACK`). Failures of the driver's own disconnect are logged, not surfaced.
 4. Any active mouse listeners are removed.
 5. A `SIGN_DISCONNECT` event is dispatched.
 
-#### 💡 Best Practices
+**Returns:** `Promise<void>`
 
-- **Initial Connection:** Always call `connect()` from a click handler so the user can select their device from the browser list.
-- **Cleanup:** It is good practice to call `disconnect()` when the component is being destroyed or the user navigates away from the signing page to free up the USB port.
+**Tip:** call it when the component is destroyed or the user leaves the signing page, to free the USB port.
 
-#### 📜 `startSigning(options?: IDrawingOptions)`
+---
 
-Prepares the component for a new signature. It transitions the state to `CONNECTING`, resets any previous drawing data, and activates the pen input for either a physical device or mouse fallback.
+### `startSigning(options?: IDrawingOptions)`
 
-```typescript
-// Example: Start a session with custom ink
-await signpad.startSigning({
+Prepares the component for a new signature. OK and Cancel end the signing session, so call this (or let the user press the built-in **Start new signature** button, see `startNewSignatureButtonVisible`) before the next signature.
+
+```js
+// Start a session with custom ink
+await signosoftPad.startSigning({
   color: "#0000FF",
   maxWidth: 4,
   minWidth: 2,
 });
 ```
 
-#### 📜 `ok()`
+It transitions the state to `CONNECTING`, resets any previous drawing data, and activates the pen input for either a physical device or mouse fallback.
 
-This is the standard way to confirm a signature. It:
+**Returns:** `Promise<void>`
 
-1. Stops the signing process.
-2. Clears the physical device's screen (if connected).
-3. Dispatches the `SIGN_OK` event.
-4. Returns the final signature payload (coordinates, pressure, metadata).
+---
+
+### `stopSigning()`
 
-**Returned payload shape (`ISignatureConfirmationData`)**
+Low-level method that forces the driver to stop capturing data and returns the signature payload. Unlike `ok()`, it does not trigger the full finalization flow (UI transitions or device screen clearing).
 
 ```js
-[
-  points, // index 0: Data about each point
-  imageBase64, // index 1: Image in base64
-  metadata, // index 2: Information about tablet and canvas
-];
+const [penDataBatch, imageBase64, metadata] = await signosoftPad.stopSigning();
 ```
 
+**Returns:** `Promise<any>`, a 3-element tuple:
+
+- `penDataBatch`: array of `IPenData` points collected during the session
+- `imageBase64`: PNG data URL of the signature drawn on canvas, or `null` if unavailable
+- `metadata`: object with `canvas` (dimensions, DPR) and `tablet` (device info) fields
+
+---
+
+### `ok()`
+
+The standard way to confirm a signature.
+
 ```js
-// [0] Points structure — same IPenData shape documented under onPen below
-{
-  relativeX: number, // normalized 0..1
-  relativeY: number, // normalized 0..1
-  pressure: number,
-  inContact: boolean,
-  timestamp: number,          // Unix ms (Date.now()) at the time of capture
+const data = await signosoftPad.ok();
+if (data) {
+  const [points, imageBase64, metadata] = data;
 }
 ```
 
+It:
+
+1. Stops the signing process.
+2. Clears the physical device's screen (if connected).
+3. Dispatches the `SIGN_OK` event.
+4. Returns the final signature payload (coordinates, pressure, metadata).
+
+After `ok()` the signing session is over: nothing is captured until a new one starts. The bottom bar then shows **Start new signature** (see `startNewSignatureButtonVisible`), or you call `startSigning()` yourself.
+
+**Returns:** `Promise<ISignatureConfirmationData | undefined>`, the same payload `handleOk` and `onOk` receive; see [Signature result](#signature-result-isignatureconfirmationdata).
+
+---
+
+### `clear()`
+
+Resets the drawing state on both the web canvas and the physical tablet's display, so the user can start over without leaving the current session.
+
 ```js
-// [1] imageBase64 — base64 PNG data URL, or null if no image could be captured
-"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...";
+await signosoftPad.clear();
 ```
 
+**Returns:** `Promise<void>`. Dispatches `SIGN_CLEAR`.
+
+---
+
+### `cancel()`
+
+Stops the session immediately, without collecting any signature data.
+
 ```js
-// [2] Metadata structure
-// The exact shape depends on whether a physical tablet or the mouse/touch
-// fallback produced the signature — the two paths report different fields.
-
-// Mouse / touch fallback:
-{
-  canvas: {
-    width: number,
-    height: number,
-    cssWidth: number,
-    cssHeight: number,
-    dpr: number
-  },
-  tablet: undefined,
-  duration: number  // seconds elapsed between the first and last recorded pen sample
-}
+await signosoftPad.cancel();
+```
 
-// Physical tablet (driver-reported):
-{
-  canvas: {
-    top?: number,
-    left?: number,
-    right?: number,
-    bottom?: number,
-    width: number,
-    height: number
-  },
-  tablet: {
-    name: string,
-    aspectRatio: number,
-    isCanvasStyleTablet: boolean,
-    screenWidth: number,
-    screenHeight: number,
-    drawingArea: { x: number, y: number, width: number, height: number },
-    serialNumber: Promise<string> | string,
-    vendorId: number | null,
-    productId: number | null
-  }
-  // no `duration` field is reported for the physical-tablet path
-}
+Like `ok()`, it ends the signing session: the bottom bar then shows **Start new signature**, or call `startSigning()` to begin again.
+
+**Returns:** `Promise<void>`. Dispatches `SIGN_CANCEL`.
+
+<a id="component-states"></a>
+
+## 🔄 Component States
+
+The component progresses through a finite set of states, exposed via the `SignpadState` enum (importable from `@signosoft/signpad-js`). Useful for observing the component lifecycle in your application.
+
+| State                      | Value                        | Description                                                                                               |
+| :------------------------- | :--------------------------- | :-------------------------------------------------------------------------------------------------------- |
+| `CONNECTING`               | `"connecting"`               | Preparing or connecting. Also the initial state while waiting for the lease.                              |
+| `CONNECTED_PHYSICAL`       | `"connected_physical"`       | Physical tablet connected and ready.                                                                      |
+| `CONNECTED_MOUSE_FALLBACK` | `"connected_mouse_fallback"` | No tablet found; mouse/touch fallback is active.                                                          |
+| `PROCESSING_OK`            | `"processing_ok"`            | OK action is being processed (finalizing signature).                                                      |
+| `PROCESSING_CLEAR`         | `"processing_clear"`         | Clear action is being processed.                                                                          |
+| `PROCESSING_CANCEL`        | `"processing_cancel"`        | Cancel action is being processed.                                                                         |
+| `DISCONNECTING`            | `"disconnecting"`            | Disconnect in progress.                                                                                   |
+| `ERROR`                    | `"error"`                    | An error occurred (see `onError` callback and [Error codes](#error-codes)). Recovery depends on the code. |
+
+<a id="error-codes"></a>
+
+## ⚠️ Error Codes
+
+Reported through the `onError` callback (`sign-error` event), see [Error handling](#error-handling-onerror). The `code` field uses the `SignpadErrorCode` enum, importable from `@signosoft/signpad-js`. Format `AREA-NN`; it decides how the user gets out of the error:
+
+| Code   | `SignpadErrorCode`     | Meaning                                                                                                                                  | Recovery (component)                                  | What your app should do                                                                                              |
+| :----- | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
+| LIC-01 | `LICENSE_MISSING`      | No `lease` in config after ~6 s. Integration error.                                                                                      | None. Passing a valid `lease` recovers automatically. | Make sure `config.lease` is set; fix the lease fetch (check `onError` / network tab).                                |
+| LIC-02 | `LICENSE_INVALID`      | The driver rejected the lease (malformed, or its signature/validity/origin check failed). An **expired** lease is reported the same way. | None. Pass a new `lease`.                             | Fetch a **fresh lease** on every mount and do not cache it across days; verify the licence allows the page's origin. |
+| DRV-01 | `DRIVER_INIT_FAILED`   | Driver / WASM could not be started.                                                                                                      | "Restart session" button                              | Log it; if it persists, check that WASM/`locateFile` assets load and the browser is supported.                       |
+| CON-01 | `CONNECT_FAILED`       | Unexpected failure while connecting.                                                                                                     | "Restart session" button                              | Nothing required; ask the user to retry or reconnect the device.                                                     |
+| NET-01 | `NETWORK_ERROR`        | Network / billing check unreachable.                                                                                                     | "Restart session" button                              | Check connectivity and any proxy/CSP blocking the licence server.                                                    |
+| BIL-01 | `BILLING_DENIED`       | The lease ran out of signing credits.                                                                                                    | "Restart session" button                              | Top up credits on the licence; a restart will not help until then.                                                   |
+| SES-01 | `START_SIGNING_FAILED` | The signing session could not be started.                                                                                                | "Restart session" button                              | Nothing required; ask the user to restart the session.                                                               |
+| ACT-01 | `ACTION_FAILED`        | OK / Clear / Cancel failed.                                                                                                              | "Restart session" button                              | Nothing required; the user can retry the action.                                                                     |
+
+The error overlay shows the message followed by the code, e.g. `... (Error code BIL-01)` (the suffix is not translated), and a "Restart session" button (for every code except `LIC-01`/`LIC-02`) is shown in the top bar. Nothing restarts automatically, so the user always sees the error first. The button works regardless of `topBarConnectButtonVisible`; if the top bar is hidden (`topBarVisible: false`) it is shown in the overlay instead.
+
+<a id="type-definitions"></a>
+
+## 🧱 Type Definitions
+
+Every type is exported from `@signosoft/signpad-js` and ships with the package, so you get autocompletion and type checking without extra setup. Each one is defined once, where it is used:
+
+```typescript
+import type {
+  SignpadConfig,
+  ISignatureConfirmationData,
+} from "@signosoft/signpad-js";
 ```
 
-`handleOk(data)` receives the same structure. `onOk` receives it in `event.detail`.
+| Type                                                                                                                  | Used for                                    | Defined in                                                                           |
+| :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ | :----------------------------------------------------------------------------------- |
+| `SignpadConfig`, `SignpadTheme`                                                                                       | the `config` object                         | [Properties](#properties)                                                            |
+| `IDrawingOptions`                                                                                                     | pen color and width                         | [`startSigning()`](#startsigning-options-idrawingoptions), [Properties](#properties) |
+| `IUIVisibilityOptions`                                                                                                | show/hide UI parts                          | [uiVisibilityOptions](#uivisibilityoptions)                                          |
+| `ILanguageOptions`, `LanguageCode`, `ITranslationSet`                                                                 | language and translations                   | [languageOptions](#languageoptions)                                                  |
+| `IActionHandlers`                                                                                                     | `handleOk` / `handleClear` / `handleCancel` | [actionHandlers](#actionhandlers)                                                    |
+| `IEventCallbacks`                                                                                                     | `onOk`, `onPen`, `onError`, ...             | [eventCallbacks](#eventcallbacks)                                                    |
+| `IPenData`                                                                                                            | `onPen` payload                             | [`onPen` payload](#onpen-payload)                                                    |
+| `ISignatureConfirmationData`, `IPenDataPoint`, `ISignatureResultMeta`, `ISignatureCanvasMeta`, `ISignatureTabletMeta` | the signature                               | [Signature result](#signature-result-isignatureconfirmationdata)                     |
+| `ISignpadErrorDetail`                                                                                                 | `onError` payload                           | [Error handling](#error-handling-onerror)                                            |
+| `SignpadState`                                                                                                        | component state (enum)                      | [Component States](#component-states)                                                |
+| `SignpadErrorCode`                                                                                                    | error codes (enum)                          | [Error codes](#error-codes)                                                          |
+| `SignpadEventType`                                                                                                    | `sign-*` DOM event names (enum)             | [Event Callbacks](#eventcallbacks)                                                   |
+
+The enums exist at runtime, so import them without `type`.
+
+<a id="localization--translation-keys"></a>
 
-#### 📜 `onPen` payload
+## 🌐 Localization & Translation Keys
 
-`onPen` is emitted continuously while writing and provides a single `IPenData` object in `event.detail`.
+All texts come from `config.languageOptions` (`lang`, `langPath`, `translations`). There is no other way to set them.
 
-```js
-{
-  relativeX: number, // normalized 0..1
-  relativeY: number, // normalized 0..1
-  pressure: number,
-  inContact: boolean,
-  timestamp: number,          // Unix ms (Date.now()) at the time of capture
-}
+| You want                      | Set                                                                                                     |
+| :---------------------------- | :------------------------------------------------------------------------------------------------------ |
+| English, Czech or Portuguese  | `lang: "cs"` (built in)                                                                                 |
+| Another language, e.g. German | `lang: "de"` and `langPath: "/i18n"`, with a `de.json` you host                                         |
+| Your own JSON file            | `import yourJson from "./de.json"`, then `translations: yourJson` (works from any file in your project) |
+| Change a few texts only       | `translations: { OK: "Confirm" }`                                                                       |
+
+### Applying a language
+
+**Why there are two ways.** The component runs in the browser, and a browser can only load what a server hands out. So a translation file reaches the component in one of two ways:
+
+- **Served as a static file (`langPath`).** Put the file in the folder your web server serves as static files and point `langPath` at its URL. The component downloads it with `fetch` when the language is needed. A file anywhere else in your project, such as `src/de.json` or `./../de.json`, is not served, so it cannot be loaded and the texts silently stay English.
+- **Bundled into your app (`translations`).** If the file lives anywhere else in your project, `import` it and pass it as `translations`. The bundler includes it in your build, so no served folder and no request are needed.
+
+**Hosted file (`langPath`).** For any language that is not built in (anything except `en`, `cs`, `pt`):
+
+1. Copy `node_modules/@signosoft/signpad-js/src/i18n/en.json`, translate the values and save it as `de.json` in a folder your app serves as static files.
+2. Set `langPath` to that folder. The component loads `${langPath}/${lang}.json`.
+
+```ts
+languageOptions: { lang: "de", langPath: "/i18n" }   // loads /i18n/de.json
 ```
 
-> The `IPenData` type also allows optional `absoluteX`, `absoluteY`, `ready`, and `sequence` fields for forward compatibility with the underlying driver, but the component does not currently populate them.
+`langPath` is the URL of that folder, not a path on disk. If the server serves the folder at the site root, a file saved as `<static folder>/i18n/de.json` is reachable at `/i18n/de.json`, so `langPath` is `"/i18n"`. Which folder is served as static files depends on your project setup; check where your tooling copies files that are not bundled.
 
-#### 📜 `stopSigning()`
+**Your own texts (`translations`).** Pass an object of key-value strings, flat or one object per language. Keys you leave out come from the selected language:
 
-A low-level method that forces the driver to stop capturing data and returns the signature payload as a 3-element tuple `[penDataBatch, imageBase64, metadata]`. Unlike `ok()`, it does not trigger the full "Finalization" flow (UI transitions or device screen clearing).
+```ts
+languageOptions: { lang: "cs", translations: { START_NEW_SIGNATURE: "Podepsat znovu" } }
 
-- `penDataBatch` — array of `IPenData` points collected during the session
-- `imageBase64` — PNG data URL of the signature drawn on canvas, or `null` if unavailable
-- `metadata` — object with `canvas` (dimensions, DPR) and `tablet` (device info) fields
+languageOptions: { lang: "cs", translations: { cs: { OK: "Potvrdit" }, en: { OK: "Confirm" } } }
+```
 
-#### 📜 `clear()`
+A JSON file you already have works the same way, import it and pass it:
 
-Resets the drawing state on both the web canvas and the physical tablet's display. This allows the user to start their signature over without leaving the current session. It dispatches the `SIGN_CLEAR` event.
+```ts
+import signpadTexts from "./i18n/signpad.json";
 
-#### 📜 `cancel()`
+languageOptions: { lang: "cs", translations: signpadTexts }
+```
 
-Stops the session immediately. It does not collect any signature data and resets the component to its ready state. This method dispatches the `SIGN_CANCEL` event.
+If the file is nested (it also holds your app's texts), pass only the part for the signpad: `translations: appTexts.signpad`.
 
-## 🔄 Component States
+**Changing the language at runtime.** Assign a new config with a different `lang`; the texts update without a reconnect:
 
-The component progresses through a finite set of states, exposed via the `SignpadState` enum (importable from `@signosoft/signpad-js`). Useful for observing the component lifecycle in your application.
+```ts
+signosoftPad.config = {
+  ...signosoftPad.config,
+  languageOptions: { ...signosoftPad.config.languageOptions, lang: "pt" },
+};
+```
 
-| State                          | Value                            | Description                                                                                                                                                         |
-| :----------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `INITIAL`                      | `"initial"`                      | Component just mounted, no initialization yet.                                                                                                                      |
-| `CONNECTING`                   | `"connecting"`                   | Connection attempt in progress.                                                                                                                                     |
-| `WAITING_FOR_DEVICE_SELECTION` | `"waiting_for_device_selection"` | Browser HID picker is open, waiting for user selection.                                                                                                             |
-| `CONNECTED_PHYSICAL`           | `"connected_physical"`           | Physical tablet connected and ready.                                                                                                                                |
-| `CONNECTED_MOUSE_FALLBACK`     | `"connected_mouse_fallback"`     | No tablet found; mouse/touch fallback is active.                                                                                                                    |
-| `SIGNING_ACTIVE`               | `"signing_active"`               | Defined for future use; the component does not currently transition to this state — drawing happens while still in `CONNECTED_PHYSICAL`/`CONNECTED_MOUSE_FALLBACK`. |
-| `PROCESSING_OK`                | `"processing_ok"`                | OK action is being processed (finalizing signature).                                                                                                                |
-| `PROCESSING_CLEAR`             | `"processing_clear"`             | Clear action is being processed.                                                                                                                                    |
-| `PROCESSING_CANCEL`            | `"processing_cancel"`            | Cancel action is being processed.                                                                                                                                   |
-| `DISCONNECTING`                | `"disconnecting"`                | Disconnect in progress.                                                                                                                                             |
-| `DISCONNECTED`                 | `"disconnected"`                 | Component is idle and disconnected.                                                                                                                                 |
-| `ERROR`                        | `"error"`                        | An error occurred (see `onError` callback). Signing automatically restarts a few seconds later unless the error's `category` is `NETWORK`.                         |
-
-### 🚨 `SignpadErrorCategory`
-
-Also importable from `@signosoft/signpad-js`, carried on the `onError` payload (see [`onError` payload](#-onerror-payload-isignpaderrordetail) above):
-
-| Value            | Value string       | Auto-restarts signing? |
-| :--------------- | :------------------ | :---------------------- |
-| `BILLING_DENIED` | `"billing_denied"` | Yes                     |
-| `NETWORK`        | `"network"`         | No                       |
-| `OTHER`          | `"other"`           | Yes                     |
+**Good to know**
+
+- Missing keys fall back to English. If the file cannot be loaded, the component logs a message and shows English.
+- If `translations` has an entry for the active language, `langPath` is not fetched at all. Put the complete set into one of the two.
+- `langPath` can also be one exact file (`"/i18n/signpad.json"`). The same file is requested again when `lang` changes, so use a folder if you need a file per language.
+- A relative `langPath` (`"i18n"`) is resolved against the page URL. Start with `/` if your app is served from a sub-route.
+- Keep placeholders such as `{device}` in your texts; they are replaced at runtime.
+
+The complete list of keys that can be translated ships with the package as `node_modules/@signosoft/signpad-js/src/i18n/en.json`. Copy its structure when creating new language files or inline overrides. The defaults are:
+
+| Key                        | Default (English)                                                                        |
+| :------------------------- | :--------------------------------------------------------------------------------------- |
+| `OK`                       | OK                                                                                       |
+| `CLEAR`                    | Clear                                                                                    |
+| `CANCEL`                   | Cancel                                                                                   |
+| `CLEAR_SIGNATURE`          | Clear signature                                                                          |
+| `DISCONNECT`               | Disconnect                                                                               |
+| `CONNECT_SIGNPAD`          | Connect Signpad                                                                          |
+| `MOUSE`                    | Mouse                                                                                    |
+| `CONNECTED_UNKNOWN_DEVICE` | Connected (Unknown Device)                                                               |
+| `AUTO_CONNECTING`          | Auto-connecting to device...                                                             |
+| `CONNECTING_TO_DEVICE`     | Connecting to your device...                                                             |
+| `REVERTING_TO_DEFAULT`     | Reverting to default input...                                                            |
+| `DISCONNECTING_DEVICE`     | Disconnecting device...                                                                  |
+| `INITIALIZING`             | Preparing signature pad...                                                               |
+| `RESTART_SESSION`          | Restart session                                                                          |
+| `START_NEW_SIGNATURE`      | Start new signature                                                                      |
+| `PREPARING_SESSION`        | Preparing session...                                                                     |
+| `TEXT_PRESS_START_SIGNING` | Start a new signing session to continue.                                                 |
+| `CANVAS_ARIA_LABEL`        | Signature drawing area                                                                   |
+| `PROCESSING_OK`            | Processing OK...                                                                         |
+| `PROCESSING_CLEAR`         | Clearing...                                                                              |
+| `PROCESSING_CANCEL`        | Canceling...                                                                             |
+| `TEXT_START_SIGNING`       | Connect your device.                                                                     |
+| `TEXT_SIGN_WITH_PHYSICAL`  | Please sign using the device pen.                                                        |
+| `TEXT_SIGN_WITH_MOUSE`     | Please sign using your mouse.                                                            |
+| `TEXT_SIGN_GENERIC`        | Sign in the area above using mouse or pen.                                               |
+| `TEXT_SIGNING_WITH_DEVICE` | Signing with {device}                                                                    |
+| `LICENSE_MISSING`          | License key is missing. Provide a valid lease in the component config.                   |
+| `CONNECTION_ERROR`         | Could not connect to the signature pad. Try again.                                       |
+| `ERROR_DRIVER_INIT`        | The signature driver could not be started. Try again or reload the page.                 |
+| `NETWORK_ERROR`            | Network error. Check your internet connection and try again.                             |
+| `INSUFFICIENT_TOKENS`      | Not enough signing credits.                                                              |
+| `ERROR_STARTING_SIGNING`   | Could not start the signing session.                                                     |
+| `ERROR_PROCESSING_ACTION`  | The action could not be completed.                                                       |
+| `INVALID_LICENSE_KEY`      | The license key was rejected. Check that the lease is valid and issued for this website. |
+| `READY_TO_SIGN_MOUSE`      | Ready to sign. Use your mouse.                                                           |
+| `READY_TO_SIGN_PHYSICAL`   | Ready to sign. Use the device pen.                                                       |
 
----
+If you add any new keys, mirror them in every language file you provide to guarantee they fall back gracefully to English.
+
+<a id="styling--theming"></a>
 
 ## 🎨 Styling & Theming
 
@@ -958,36 +1255,49 @@ The component uses a hybrid theming model:
 - It ships with complete default styles (works out of the box).
 - You can override the visual design through CSS variables.
 
-## ✍️ Override via CSS
+### Design tokens
 
-You can override variables in your stylesheet
+Defaults come from the Signosoft design system tokens, shipped inside the component (`src/styles/primitive.css` for raw scales, `src/styles/semantic.css` for meaning, e.g. `--background-brand`, `--content-primary`, `--border-focus`). They are declared on the component's `:host`, so they do not depend on the host page and do not leak into it. `--sign-*` variables below are the public API; their defaults point at semantic tokens. Override `--sign-*` on the `signosoft-signpad` element.
 
-### 📎 Copy-Paste Starter
+<a id="override-via-css"></a>
 
-Paste this directly into your app stylesheet and adjust values:
+## 🪄 Override via CSS
+
+Set the `--sign-*` variables on the element in your own stylesheet. Variables set there beat the component's defaults, in light and dark theme alike:
 
 ```css
 signosoft-signpad {
-  /* Color Variables */
-  --primary-color-0: #4e56ea;
-  --primary-color-10: #7178ee;
-  --background-color-0: #f1f2fd;
-  --background-color-10: #e3e4fc;
-  --text-color-0: #333e4a;
-  --white-color: #ffffff;
-  --grey-color: #b5b9be;
+  --sign-top-bar-bg-base: #f3e8f8;
+  --sign-top-bar-text-base: #5d1776;
+  --sign-bottom-bar-bg-base: #f3e8f8;
+  --sign-button-primary-bg-base: #7a1f9a;
+  --sign-button-primary-bg-hover: #5d1776;
+}
+```
+
+The full list of variables follows below.
+
+### Copy-Paste Starter
+
+Paste this directly into your app stylesheet and adjust values:
 
+```css
+signosoft-signpad {
   /* Constraints */
-  --min-height: 48px;
-  --spacing-constraints: 16px 24px;
+  --min-height: var(--unit-48);
+  --spacing-constraints: var(--spacing-12) var(--spacing-16);
+
+  /* Host Sizing (override to make the component fluid, e.g. width: 100%; height: 100vh;) */
+  --signpad-width: 25rem;
+  --signpad-height: 31.25rem;
 
   /* CSS Variables */
-  --sign-font-family: Arial, Helvetica, sans-serif;
-  --sign-common-border-radius: 8px;
+  --sign-font-family: var(--fontFamily-primary), Arial, Helvetica, sans-serif;
+  --sign-common-border-radius: var(--borderRadius-s);
 
   /* Top Bar */
-  --sign-top-bar-bg-base: var(--background-color-10);
-  --sign-top-bar-text-base: var(--primary-color-0);
+  --sign-top-bar-bg-base: var(--background-brandSubtle);
+  --sign-top-bar-text-base: var(--brand-650);
   --sign-top-bar-padding: var(--spacing-constraints);
   --sign-top-bar-min-height: var(--min-height);
   --sign-top-bar-border-top-left-radius: var(--sign-common-border-radius);
@@ -996,26 +1306,27 @@ signosoft-signpad {
   --sign-top-bar-border-bottom-right-radius: 0;
 
   /* Canvas Area */
-  --sign-canvas-bg-base: var(--background-color-0);
+  --sign-canvas-bg-base: var(--brandBeige-100);
   --sign-canvas-wrapper-border-top-left-radius: 0;
   --sign-canvas-wrapper-border-top-right-radius: 0;
   --sign-canvas-wrapper-border-bottom-left-radius: 0;
   --sign-canvas-wrapper-border-bottom-right-radius: 0;
 
   /* Line */
-  --sign-line-height: 22px;
-  --sign-line-margin-bottom: 16px;
-  --sign-line-border-base: var(--primary-color-10);
-  --sign-line-additional-text-color: var(--text-color-0);
-  --sign-line-margin: 0px 24px var(--sign-line-margin-bottom) 24px;
-  --sign-canvas-line-text-font-size: 12px;
+  --sign-line-height: var(--unit-24);
+  --sign-line-margin-bottom: var(--spacing-16);
+  --sign-line-border-base: var(--border-secondary);
+  --sign-line-additional-text-color: var(--content-tertiary);
+  --sign-line-margin: 0 var(--spacing-16) var(--sign-line-margin-bottom)
+    var(--spacing-16);
+  --sign-canvas-line-text-font-size: var(--text-s-regular-fontSize);
   --sign-canvas-height-offset: var(--sign-line-height);
 
   /* Bottom Bar */
-  --sign-bottom-bar-bg-base: var(--background-color-10);
+  --sign-bottom-bar-bg-base: var(--background-brandSubtle);
   --sign-bottom-bar-padding: var(--spacing-constraints);
   --sign-bottom-bar-min-height: var(--min-height);
-  --sign-bottom-bar-gap: 12px;
+  --sign-bottom-bar-gap: var(--spacing-8);
   --sign-bottom-bar-border-top-left-radius: 0;
   --sign-bottom-bar-border-top-right-radius: 0;
   --sign-bottom-bar-border-bottom-left-radius: var(--sign-common-border-radius);
@@ -1024,76 +1335,66 @@ signosoft-signpad {
   );
 
   /* Button general settings */
-  --sign-button-font-size: 16px;
-  --sign-button-padding: 14px 16px;
-  --sign-button-min-height: var(--min-height);
-  --sign-button-border-radius: 8px;
-  --sign-button-font-weight: 500;
+  --sign-button-font-size: var(--text-m-semibold-fontSize);
+  --sign-button-padding: var(--spacing-10);
+  --sign-button-min-height: var(--unit-48);
+  --sign-button-border-radius: var(--borderRadius-pill);
+  --sign-button-font-weight: var(--text-m-semibold-fontWeight);
 
   /* Primary Buttons (OK, Clear, Cancel) */
-  --sign-button-primary-bg-base: var(--primary-color-0);
-  --sign-button-primary-bg-hover: var(--primary-color-10);
-  --sign-button-primary-bg-disabled: var(--grey-color);
-  --sign-button-primary-text-base: var(--white-color);
-  --sign-button-primary-text-hover: var(--white-color);
-  --sign-button-primary-text-disabled: var(--white-color);
-  --sign-button-primary-border-base: 1px solid var(--primary-color-0);
-  --sign-button-primary-border-hover: 1px solid var(--primary-color-10);
-  --sign-button-primary-border-disabled: 1px solid var(--grey-color);
-
-  /* Link Buttons (Connect signpad) */
-  --sign-button-link-bg-base: transparent;
-  --sign-button-link-bg-hover: var(--background-color-10);
-  --sign-button-link-bg-disabled: transparent;
-  --sign-button-link-text-base: var(--primary-color-0);
-  --sign-button-link-text-hover: var(--primary-color-10);
-  --sign-button-link-text-disabled: var(--grey-color);
-  --sign-button-link-border-base: 1px solid var(--primary-color-0);
-  --sign-button-link-border-hover: 1px solid var(--primary-color-10);
-  --sign-button-link-border-disabled: 1px solid var(--grey-color);
+  --sign-button-primary-bg-base: var(--background-brand);
+  --sign-button-primary-bg-hover: var(--background-brandHover);
+  --sign-button-primary-bg-pressed: var(--background-brandPressed);
+  --sign-button-primary-bg-disabled: var(--background-disabled);
+  --sign-button-primary-text-base: var(--content-primaryInverse);
+  --sign-button-primary-text-hover: var(--content-primaryInverse);
+  --sign-button-primary-text-disabled: var(--content-disabled);
+  --sign-button-primary-border-base: var(--borderWidth-xs) solid transparent;
+  --sign-button-primary-border-hover: var(--borderWidth-xs) solid transparent;
+  --sign-button-primary-border-disabled: var(--borderWidth-xs) solid transparent;
 
   /* Device State Text Colors */
-  --sign-device-state-text-color-connected: green;
-  --sign-device-state-text-color-disconnected: red;
+  --sign-device-state-text-color-connected: var(--brand-650);
 
   /* Loading Overlay */
-  --sign-loading-overlay-bg-color: rgba(255, 255, 255, 0.8);
-  --sign-loading-overlay-text-color: var(--text-color-0);
-  --sign-loading-overlay-spinner-color: var(--primary-color-0);
-  --sign-loading-overlay-spinner-border-color: rgba(78, 86, 234, 0.1);
-  --sign-loading-overlay-spinner-size: 30px;
+  --sign-loading-overlay-bg-color: color-mix(
+    in srgb,
+    var(--background-primary) 80%,
+    transparent
+  );
+  --sign-loading-overlay-text-color: var(--content-primary);
+  --sign-loading-overlay-spinner-color: var(--content-brandHover);
+  --sign-loading-overlay-spinner-border-color: var(--background-brandSubtle);
+  --sign-loading-overlay-spinner-size: var(--unit-32);
 }
 ```
 
-### 📋 Full CSS Variable Reference
+### Full CSS Variable Reference
 
-#### Base Colors & General
+#### General
 
-| Variable                      | Default             | Description                                     |
-| :---------------------------- | :------------------ | :---------------------------------------------- |
-| `--primary-color-0`           | `#4e56ea`           | Primary brand color.                            |
-| `--primary-color-10`          | `#7178ee`           | Primary hover/accent color.                     |
-| `--background-color-0`        | `#f1f2fd`           | Secondary background color.                     |
-| `--background-color-10`       | `#e3e4fc`           | Main bar background color.                      |
-| `--text-color-0`              | `#333e4a`           | Main text color.                                |
-| `--white-color`               | `#ffffff`           | Pure white color.                               |
-| `--grey-color`                | `#b5b9be`           | Disabled state color.                           |
-| `--sign-font-family`          | `Arial, sans-serif` | Global font family.                             |
-| `--sign-common-border-radius` | `8px`               | Shared radius token reused by bars and buttons. |
+| Variable                      | Default                                                   | Description                                                                                                                                                              |
+| :---------------------------- | :-------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--sign-font-family`          | `var(--fontFamily-primary), Arial, Helvetica, sans-serif` | Global font family. The default starts with the design system font `Inter`, which is **not bundled** — load it on the host page, otherwise the `Arial` fallback is used. |
+| `--sign-common-border-radius` | `var(--borderRadius-s)`                                   | Shared radius token reused by bars and buttons.                                                                                                                          |
 
 #### Layout & Constraints
 
-| Variable                | Default     | Description                            |
-| :---------------------- | :---------- | :------------------------------------- |
-| `--min-height`          | `48px`      | Minimum height for bars and buttons.   |
-| `--spacing-constraints` | `16px 24px` | Default padding/margin for containers. |
+| Variable                | Default                               | Description                                                                  |
+| :---------------------- | :------------------------------------ | :--------------------------------------------------------------------------- |
+| `--signpad-width`       | `25rem`                               | Host element width. Override to resize, e.g. `100%` for a fluid container.   |
+| `--signpad-height`      | `31.25rem`                            | Host element height. Override to resize, e.g. `100vh` for a fluid container. |
+| `--min-height`          | `var(--unit-48)`                      | Minimum height for bars and buttons.                                         |
+| `--spacing-constraints` | `var(--spacing-12) var(--spacing-16)` | Default padding/margin for containers.                                       |
+
+> **Sizing:** By default the component renders at a fixed `400x500` size so it doesn't stretch to fill its parent on integration. To make it fluid, override `--signpad-width` / `--signpad-height` on the host element (e.g. `signosoft-signpad { --signpad-width: 100%; --signpad-height: 100vh; }`).
 
 #### Top Bar
 
 | Variable                                    | Default                            | Description                         |
 | :------------------------------------------ | :--------------------------------- | :---------------------------------- |
-| `--sign-top-bar-bg-base`                    | `var(--background-color-10)`       | Background color of the top bar.    |
-| `--sign-top-bar-text-base`                  | `var(--primary-color-0)`           | Text color in the top bar.          |
+| `--sign-top-bar-bg-base`                    | `var(--background-brandSubtle)`    | Background color of the top bar.    |
+| `--sign-top-bar-text-base`                  | `var(--brand-650)`                 | Text color in the top bar.          |
 | `--sign-top-bar-padding`                    | `var(--spacing-constraints)`       | Inner padding of the top bar.       |
 | `--sign-top-bar-min-height`                 | `var(--min-height)`                | Minimum height of the top bar.      |
 | `--sign-top-bar-border-top-left-radius`     | `var(--sign-common-border-radius)` | Top-left radius of the top bar.     |
@@ -1103,29 +1404,29 @@ signosoft-signpad {
 
 #### Canvas & Signature Line
 
-| Variable                                           | Default                                        | Description                                                                  |
-| :------------------------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------- |
-| `--sign-canvas-bg-base`                            | `var(--background-color-0)`                    | Background color of the drawing area.                                        |
-| `--sign-canvas-wrapper-border-top-left-radius`     | `0`                                            | Top-left canvas radius, typically rounded when the top bar is hidden.        |
-| `--sign-canvas-wrapper-border-top-right-radius`    | `0`                                            | Top-right canvas radius, typically rounded when the top bar is hidden.       |
-| `--sign-canvas-wrapper-border-bottom-left-radius`  | `0`                                            | Bottom-left canvas radius, typically rounded when the bottom bar is hidden.  |
-| `--sign-canvas-wrapper-border-bottom-right-radius` | `0`                                            | Bottom-right canvas radius, typically rounded when the bottom bar is hidden. |
-| `--sign-line-height`                               | `22px`                                         | Vertical offset/height for the guide line.                                   |
-| `--sign-line-margin-bottom`                        | `16px`                                         | Bottom spacing used in canvas line layout.                                   |
-| `--sign-line-border-base`                          | `var(--primary-color-10)`                      | Color of the signature guide line.                                           |
-| `--sign-line-additional-text-color`                | `var(--text-color-0)`                          | Color of the helper text below the line.                                     |
-| `--sign-line-margin`                               | `0px 24px var(--sign-line-margin-bottom) 24px` | Spacing around the guide line.                                               |
-| `--sign-canvas-line-text-font-size`                | `12px`                                         | Font size for guide line labels.                                             |
-| `--sign-canvas-height-offset`                      | `var(--sign-line-height)`                      | Canvas offset calculation for the guide line.                                |
+| Variable                                           | Default                                                                | Description                                                                  |
+| :------------------------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
+| `--sign-canvas-bg-base`                            | `var(--brandBeige-100)`                                                | Background color of the drawing area.                                        |
+| `--sign-canvas-wrapper-border-top-left-radius`     | `0`                                                                    | Top-left canvas radius, typically rounded when the top bar is hidden.        |
+| `--sign-canvas-wrapper-border-top-right-radius`    | `0`                                                                    | Top-right canvas radius, typically rounded when the top bar is hidden.       |
+| `--sign-canvas-wrapper-border-bottom-left-radius`  | `0`                                                                    | Bottom-left canvas radius, typically rounded when the bottom bar is hidden.  |
+| `--sign-canvas-wrapper-border-bottom-right-radius` | `0`                                                                    | Bottom-right canvas radius, typically rounded when the bottom bar is hidden. |
+| `--sign-line-height`                               | `var(--unit-24)`                                                       | Vertical offset/height for the guide line.                                   |
+| `--sign-line-margin-bottom`                        | `var(--spacing-16)`                                                    | Bottom spacing used in canvas line layout.                                   |
+| `--sign-line-border-base`                          | `var(--border-secondary)`                                              | Color of the signature guide line.                                           |
+| `--sign-line-additional-text-color`                | `var(--content-tertiary)`                                              | Color of the helper text below the line.                                     |
+| `--sign-line-margin`                               | `0 var(--spacing-16) var(--sign-line-margin-bottom) var(--spacing-16)` | Spacing around the guide line.                                               |
+| `--sign-canvas-line-text-font-size`                | `var(--text-s-regular-fontSize)`                                       | Font size for guide line labels.                                             |
+| `--sign-canvas-height-offset`                      | `var(--sign-line-height)`                                              | Canvas offset calculation for the guide line.                                |
 
 #### Bottom Bar
 
 | Variable                                       | Default                            | Description                              |
 | :--------------------------------------------- | :--------------------------------- | :--------------------------------------- |
-| `--sign-bottom-bar-bg-base`                    | `var(--background-color-10)`       | Background color of the bottom bar.      |
+| `--sign-bottom-bar-bg-base`                    | `var(--background-brandSubtle)`    | Background color of the bottom bar.      |
 | `--sign-bottom-bar-padding`                    | `var(--spacing-constraints)`       | Inner padding of the bottom bar.         |
 | `--sign-bottom-bar-min-height`                 | `var(--min-height)`                | Minimum height of the bottom bar.        |
-| `--sign-bottom-bar-gap`                        | `12px`                             | Space between buttons in the bottom bar. |
+| `--sign-bottom-bar-gap`                        | `var(--spacing-8)`                 | Space between buttons in the bottom bar. |
 | `--sign-bottom-bar-border-top-left-radius`     | `0`                                | Top-left radius of the bottom bar.       |
 | `--sign-bottom-bar-border-top-right-radius`    | `0`                                | Top-right radius of the bottom bar.      |
 | `--sign-bottom-bar-border-bottom-left-radius`  | `var(--sign-common-border-radius)` | Bottom-left radius of the bottom bar.    |
@@ -1133,167 +1434,87 @@ signosoft-signpad {
 
 #### Buttons (General)
 
-| Variable                      | Default             | Description                    |
-| :---------------------------- | :------------------ | :----------------------------- |
-| `--sign-button-font-size`     | `16px`              | Font size for all buttons.     |
-| `--sign-button-padding`       | `14px 16px`         | Inner padding for all buttons. |
-| `--sign-button-min-height`    | `var(--min-height)` | Minimum height for buttons.    |
-| `--sign-button-border-radius` | `8px`               | Border radius for all buttons. |
-| `--sign-button-font-weight`   | `500`               | Font weight for all buttons.   |
+| Variable                      | Default                             | Description                    |
+| :---------------------------- | :---------------------------------- | :----------------------------- |
+| `--sign-button-font-size`     | `var(--text-m-semibold-fontSize)`   | Font size for all buttons.     |
+| `--sign-button-padding`       | `var(--spacing-10)`                 | Inner padding for all buttons. |
+| `--sign-button-min-height`    | `var(--unit-48)`                    | Minimum height for buttons.    |
+| `--sign-button-border-radius` | `var(--borderRadius-pill)`          | Border radius for all buttons. |
+| `--sign-button-font-weight`   | `var(--text-m-semibold-fontWeight)` | Font weight for all buttons.   |
 
 #### Primary Buttons (OK, Clear, Cancel)
 
-| Variable                                | Description                          |
-| :-------------------------------------- | :----------------------------------- |
-| `--sign-button-primary-bg-base`         | Background color of primary buttons. |
-| `--sign-button-primary-bg-hover`        | Hover background color.              |
-| `--sign-button-primary-bg-disabled`     | Disabled background color.           |
-| `--sign-button-primary-text-base`       | Text color for primary buttons.      |
-| `--sign-button-primary-text-hover`      | Hover text color.                    |
-| `--sign-button-primary-text-disabled`   | Disabled text color.                 |
-| `--sign-button-primary-border-base`     | Border of primary buttons.           |
-| `--sign-button-primary-border-hover`    | Hover border color.                  |
-| `--sign-button-primary-border-disabled` | Disabled border color.               |
-
-#### Link/Connect Buttons
-
-| Variable                             | Default                             | Description                                  |
-| :----------------------------------- | :---------------------------------- | :------------------------------------------- |
-| `--sign-button-link-bg-base`         | `transparent`                       | Background color for secondary/link buttons. |
-| `--sign-button-link-bg-hover`        | `var(--background-color-10)`        | Hover background color.                      |
-| `--sign-button-link-bg-disabled`     | `transparent`                       | Disabled background color.                   |
-| `--sign-button-link-text-base`       | `var(--primary-color-0)`            | Text color for secondary/link buttons.       |
-| `--sign-button-link-text-hover`      | `var(--primary-color-10)`           | Hover text color.                            |
-| `--sign-button-link-text-disabled`   | `var(--grey-color)`                 | Disabled text color.                         |
-| `--sign-button-link-border-base`     | `1px solid var(--primary-color-0)`  | Border for secondary/link buttons.           |
-| `--sign-button-link-border-hover`    | `1px solid var(--primary-color-10)` | Hover border color.                          |
-| `--sign-button-link-border-disabled` | `1px solid var(--grey-color)`       | Disabled border color.                       |
+| Variable                                | Default                                   | Description                                         |
+| :-------------------------------------- | :---------------------------------------- | :-------------------------------------------------- |
+| `--sign-button-primary-bg-base`         | `var(--background-brand)`                 | Background color of primary buttons.                |
+| `--sign-button-primary-bg-hover`        | `var(--background-brandHover)`            | Hover background color.                             |
+| `--sign-button-primary-bg-pressed`      | `var(--background-brandPressed)`          | Background while the button is pressed (`:active`). |
+| `--sign-button-primary-bg-disabled`     | `var(--background-disabled)`              | Disabled background color.                          |
+| `--sign-button-primary-text-base`       | `var(--content-primaryInverse)`           | Text color for primary buttons.                     |
+| `--sign-button-primary-text-hover`      | `var(--content-primaryInverse)`           | Hover text color.                                   |
+| `--sign-button-primary-text-disabled`   | `var(--content-disabled)`                 | Disabled text color.                                |
+| `--sign-button-primary-border-base`     | `var(--borderWidth-xs) solid transparent` | Border of primary buttons.                          |
+| `--sign-button-primary-border-hover`    | `var(--borderWidth-xs) solid transparent` | Hover border color.                                 |
+| `--sign-button-primary-border-disabled` | `var(--borderWidth-xs) solid transparent` | Disabled border color.                              |
 
 #### Status & Overlays
 
-| Variable                                      | Default                    | Description                        |
-| :-------------------------------------------- | :------------------------- | :--------------------------------- |
-| `--sign-device-state-text-color-connected`    | `green`                    | Text color when device is ready.   |
-| `--sign-device-state-text-color-disconnected` | `red`                      | Text color when disconnected.      |
-| `--sign-loading-overlay-bg-color`             | `rgba(255, 255, 255, 0.8)` | Background of the loading spinner. |
-| `--sign-loading-overlay-text-color`           | `var(--text-color-0)`      | Loading overlay text color.        |
-| `--sign-loading-overlay-spinner-color`        | `var(--primary-color-0)`   | Color of the animated spinner.     |
-| `--sign-loading-overlay-spinner-border-color` | `rgba(78, 86, 234, 0.1)`   | Base border color of spinner ring. |
-| `--sign-loading-overlay-spinner-size`         | `30px`                     | Size of the spinner icon.          |
-
-## 💬 Feedback & Support
-
-We are constantly working to improve our components and drivers. Your feedback is essential to us. Whether you found a bug, have a feature request, or need technical assistance, please reach out to us:
-
-- 📧 **Support Email:** [esign@signosoft.com](mailto:esign@signosoft.com)
-- 🌐 **Official Website:** [www.signosoft.com](https://www.signosoft.com)
-
-## 🛠️ Contributing
-
-### Commit naming convention
-
-- Every commit message must start with Jira task id and category:
-  - `MAIN-000/<category>: <summary>`
-- For work in progress:
-  - `MAIN-000/<category>: WIP - <summary>`
-
-Allowed categories:
-
-- `feat`: adding a new feature
-- `fix`: fixing a bug
-- `refactor`: performance/readability/maintainability change
-- `chore`: docs, formatting, tests, cleanup, tooling
-- `merge`: branch merge into `main`
-
-Use infinitive verb form in commit summaries:
-
-- <span style="color: #16a34a;"><strong>RIGHT:</strong></span> `add`, `fix`, `remove`, `update`, `refactor`
-- <span style="color: #dc2626;"><strong>WRONG:</strong></span> Continuous tense: `adding`, `removing` Past tense: `added`, `fixed`
-
-Examples:
-
-```bash
-git commit -m "MAIN-000/feat: add new button component; add button to templates"
-```
-
-```bash
-git commit -m "MAIN-000/fix: add stop directive to button component to prevent propagation"
-```
-
-```bash
-git commit -m "MAIN-000/refactor: rewrite button component in TypeScript"
-```
-
-```bash
-git commit -m "MAIN-000/chore: write button documentation"
-```
-
-```bash
-git commit -m "MAIN-000/merge: new button"
-```
-
-```bash
-git commit -m "MAIN-000/feat: WIP - basic signing functionality"
-```
-
-### Versioning and release commits
-
-Follow Semantic Versioning:
+| Variable                                      | Default                                                          | Description                        |
+| :-------------------------------------------- | :--------------------------------------------------------------- | :--------------------------------- |
+| `--sign-device-state-text-color-connected`    | `var(--brand-650)`                                               | Text color when device is ready.   |
+| `--sign-loading-overlay-bg-color`             | `color-mix(in srgb, var(--background-primary) 80%, transparent)` | Background of the loading spinner. |
+| `--sign-loading-overlay-text-color`           | `var(--content-primary)`                                         | Loading overlay text color.        |
+| `--sign-loading-overlay-spinner-color`        | `var(--content-brandHover)`                                      | Color of the animated spinner.     |
+| `--sign-loading-overlay-spinner-border-color` | `var(--background-brandSubtle)`                                  | Base border color of spinner ring. |
+| `--sign-loading-overlay-spinner-size`         | `var(--unit-32)`                                                 | Size of the spinner icon.          |
 
-- `MAJOR` (`x.0.0`): breaking changes
-- `MINOR` (`x.y.0`): backward-compatible feature set
-- `PATCH` (`x.y.z`): backward-compatible bug fixes
+> **Accessibility (WCAG 2.1 AA):** if you override `--sign-loading-overlay-bg-color` or `--sign-loading-overlay-text-color`, keep the text/background contrast ratio at **4.5:1 or higher**. The overlay background is semi-transparent, so measure against the worst case: the overlay color blended over the canvas, including dark pen strokes. Raise the background alpha if the text is hard to read over strokes.
 
-Commit naming for version bumps:
+<a id="accessibility"></a>
 
-- Version-only change: use `chore`
-- Version bump with actual code/features in same commit: use `feat`/`fix`/`refactor` based on dominant change
-- For release commits, include both versions in message: `release from <old> to <new>`
+## ♿ Accessibility
 
-Example (version bump with feature changes):
+The component targets WCAG 2.1 AA for everything it renders. What is in place:
 
-```bash
-git commit -m "MAIN-000/feat: release from 0.2.4 to 0.3.0 - add signature method"
-```
+- **Names and state:** all controls are native `<button>`s with visible, localized text; disabled buttons use the native `disabled` state. The drawing canvas has `role="img"` and a localized name (`CANVAS_ARIA_LABEL`).
+- **Announcements:** the component container sets `aria-busy` while connecting, disconnecting or processing OK/Clear/Cancel. The error/busy overlay message is announced (`role="alert"` for errors, `role="status"` while busy). Device status changes (e.g. connected / mouse) are announced through a polite live region.
+- **Keyboard and focus:** all buttons are reachable with Tab and show a `:focus-visible` outline (`--border-focus`). When an error appears and focus is already inside the component, focus moves to the "Restart session" button.
+- **Language:** the active language is set as `lang` on the component content, so screen readers pronounce `cs`/`pt` text correctly.
+- **Motion:** the spinner slows down and button transitions are disabled under `prefers-reduced-motion: reduce`.
+- **High contrast:** under `forced-colors: active` buttons, focus ring and overlay use system colors. The signing surface keeps its own light background (`forced-color-adjust: none`), because the ink is drawn on a canvas in `canvasAndDrawingOptions.color` (black by default) and would be invisible on a forced dark background.
 
-Example (version-only commit):
+**Known limitations (plan an alternative in your app):**
 
-```bash
-git commit -m "MAIN-000/chore: release from 0.2.4 to 0.3.0"
-```
+- **Signing itself is pointer-only** (pen, mouse or touch). The canvas cannot be operated with a keyboard or screen reader (WCAG 2.1.1). If you must support people who cannot draw, offer another way to sign or confirm in your app (e.g. a typed-name signature or an assisted flow) and treat the signpad as one option.
+- **Default color contrast:** the defaults are chosen for WCAG 2.1 AA: white on the primary button is 5.1:1 (`--background-brand` = `brand-650`; hover 6.5:1, pressed 8.3:1), top bar and device status text are at least 4.5:1, the spinner and focus ring are above 3:1. `--background-brand` was changed from `brand-500` (white on it is 2.7:1) to `brand-650` for this reason; `--background-brandHover` and `--background-brandPressed` are `brand-700` and `brand-750`. Disabled controls are exempt. If you override colors, re-check the ratios.
+- **Zoom and text size:** spacing, sizes and radii come from design tokens converted to `rem`, so they scale with the browser font size and page zoom. Border widths stay in `px`. `--signpad-width` / `--signpad-height` are also `rem`; reflow at 400% zoom depends on your page layout around the component.
 
-How version increment works:
+**If you override styles:** keep text/background contrast at 4.5:1 (3:1 for borders and UI components), do not remove the `:focus-visible` outline, and keep controls at least 24×24 px.
 
-- `PATCH` (`x.y.Z`): increase patch only (`1.4.2` -> `1.4.3`)
-- `MINOR` (`x.Y.0`): increase minor, reset patch (`1.4.9` -> `1.5.0`)
-- `MAJOR` (`X.0.0`): increase major, reset minor and patch (`1.9.7` -> `2.0.0`)
+<a id="feedback--support"></a>
 
-Examples:
+## 💬 Feedback & Support
 
-```bash
-# patch
-git commit -m "MAIN-000/fix: release from 1.0.0 to 1.0.1 - fix onPen throttle edge case"
+Found a bug, missing a feature, or need help with an integration? Write to us:
 
-# minor
-git commit -m "MAIN-000/feat: release from 1.1.1 to 1.2.0 - add lease refresh helper"
+- 📧 **Support Email:** [esign@signosoft.com](mailto:esign@signosoft.com)
+- 🌐 **Official Website:** [www.signosoft.com](https://www.signosoft.com)
 
-# major
-git commit -m "MAIN-000/refactor: release from 1.1.1 to 2.0.0 - remove legacy API"
-```
+<a id="license"></a>
 
 ## 📄 License
 
-**Proprietary Commercial License**
+**Source-available, proprietary commercial license**
 
 Copyright © 2026, Signosoft. All rights reserved.
 
-This software is proprietary to Signosoft and is protected by copyright laws. It is **not open source**.
+This software is proprietary to Signosoft and is protected by copyright laws. The source is available to inspect, but it is **not open source** (not an OSI-approved license): use requires a Signosoft account and paid tokens.
 
-### 🔐 Commercial Usage
+### Commercial Usage
 
 A valid, paid, and active commercial license agreement with Signosoft is **strictly required** for the use, operation, reproduction, distribution, or deployment of this software in any environment (including development, testing, staging, and production).
 
-### 📜 Key Terms
+### Key Terms
 
 - **Unauthorized Use:** Any use without a current, fully paid license is expressly prohibited and constitutes a violation of our intellectual property rights.
 - **Legal Action:** Signosoft reserves the right to pursue legal action to enforce its rights and seek damages for unauthorized use.