@signosoft/signpad-js 0.2.3 → 0.3.0

package/README.md

@@ -2,14 +2,14 @@
 
 ## 📍 Table of Contents
 
-| Core Concepts & Overview                  | Getting Started & Usage            | Advanced & Support                 |
-| :---------------------------------------- | :--------------------------------- | :--------------------------------- |
-| 📜 [Description](#-description)           | 📦 [Installation](#-installation)  | 🤝 [Feedback](#-feedback--support) |
-| 🎬 [Demo](#-demo)                         | 🔐 [Licensing](#-get-your-license) | 📄 [License](#-license)            |
-| ⚙️ [Tech stack](#-tech-stack--built-with) | 🚀 [Quick Start](#-quick-start)    |                                    |
-|                                           | 📋 [Properties](#-properties)      |                                    |
-|                                           | 🧩 [Methods](#-methods)            |                                    |
-|                                           | 🎨 [Styling](#-styling--theming)   |                                    |
+| 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)            |
+|                                           | 📋 [Properties](#-properties)     |                                    |
+|                                           | 🧩 [Methods](#-methods)           |                                    |
+|                                           | 🎨 [Styling](#-styling--theming)  |                                    |
 
 ## 📜 Description
 
@@ -38,33 +38,61 @@ It expertly handles the complexities of **WebHID device connections**, signature
 - [![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=fff)](https://vitejs.dev/)
   <br/>
 
-## 🔐 Get your license
+## 🔐 Lease Setup
 
-To use the Signosoft Signpad component and its hardware drivers, a valid license key is **required**.
+To use the Signosoft Signpad component and its hardware drivers, a valid `lease` is **required**.
 
 #### 🛑 CRITICAL: Mandatory Initialization
 
-Without a valid license key, the component <b>WILL NOT INITIALIZE</b> and all hardware communication features will be <b>disabled</b>.
+Without a valid lease, the component <b>WILL NOT INITIALIZE</b> and hardware communication features will be <b>disabled</b>.
 
-### 1. How to obtain a license:
+### 1. Lease flow
 
-1.  Go to [www.signosoft.com](https://www.signosoft.com)
-2.  **Sign in** to your account.
-3.  Navigate to **Settings** > **Get License**.
-4.  Click **Generate API Key** (License Key).
-5.  Copy your key and add it to your configuration.
+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`.
 
-### 2. Implementation:
+> Security note: In production, call the lease API from your backend and return only the lease to frontend.
 
-Add the key to the `licenseKey` field in your configuration object:
+### 2. Frontend implementation (plain JavaScript reference)
 
-```typescript
-const config: SignpadConfig = {
-  licenseKey: "YOUR-LICENSE-KEY-HERE", // Required
-  // ... other options
+```javascript
+async function fetchLease() {
+  try {
+    const response = await fetch(
+      "https://test.signosoft.com/api/v1/driver/leases",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          licenceKey: "YOUR-LICENSE-KEY",
+          validityHours: 24,
+          port: 4204,
+        }),
+      },
+    );
 
-  // For local development, ensure your license is valid for localhost.
-};
+    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/>
@@ -169,7 +197,13 @@ export class SignosoftSignpadDirective implements OnChanges {
 Import the library, the directive, and add the **`CUSTOM_ELEMENTS_SCHEMA`**.
 
 ```typescript
-import { Component, ViewChild, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+import {
+  Component,
+  ViewChild,
+  CUSTOM_ELEMENTS_SCHEMA,
+  AfterViewInit,
+  signal,
+} from "@angular/core";
 import "@signosoft/signpad-js"; // Import the Web Component registration
 import {
   type SignosoftSignpad,
@@ -184,14 +218,54 @@ import { SignosoftSignpadDirective } from "./directives/signosoft-signpad.direct
   templateUrl: "./app.component.html",
   schemas: [CUSTOM_ELEMENTS_SCHEMA], // Mandatory for custom HTML tags
 })
-export class AppComponent {
+export class AppComponent implements AfterViewInit {
   @ViewChild(SignosoftSignpadDirective)
   signpadDirective!: SignosoftSignpadDirective;
 
-  config: SignpadConfig = {
-    licenseKey: "YOUR-LICENSE-KEY",
-    // More info in "properties" section
-  };
+  public config = signal<SignpadConfig>({
+    lease: undefined,
+  });
+
+  async ngAfterViewInit() {
+    await this.applyLeaseToConfig();
+  }
+
+  public async fetchLease(): Promise<any> {
+    try {
+      const response = await fetch(
+        "https://test.signosoft.com/api/v1/driver/leases",
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            licenceKey: "YOUR-LICENSE-KEY",
+            validityHours: 24,
+            port: 4204,
+          }),
+        },
+      );
+
+      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;
+    }
+  }
+
+  public async applyLeaseToConfig() {
+    const lease = await this.fetchLease();
+    this.config.update((currentConfig) => ({
+      ...currentConfig,
+      lease,
+    }));
+  }
 
   // Helper to access methods easily (ok, clear, cancel, etc.)
   public get signpad(): SignosoftSignpad | undefined {
@@ -207,7 +281,7 @@ Use the custom tag in your HTML and bind the configuration object.
 ```html
 <div>
   <div>
-    <signosoft-signpad [config]="config"></signosoft-signpad>
+    <signosoft-signpad [config]="config()"></signosoft-signpad>
   </div>
 </div>
 ```
@@ -235,21 +309,50 @@ npm install @signosoft/signpad-js
 
 ## 2. Implementation
 
-In React, we use the `useRef` hook to interact with the component's methods (like `ok()` or `clear()`) and pass the configuration directly via props.
+In React, we use `useRef` for methods and `useEffect` to fetch a lease before updating config.
 
 ```tsx
-import { useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import "@signosoft/signpad-js"; // Registers the web component
 import type { SignpadConfig } from "@signosoft/signpad-js";
 
+async function fetchLease() {
+  try {
+    const response = await fetch(
+      "https://test.signosoft.com/api/v1/driver/leases",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          licenceKey: "YOUR-LICENSE-KEY",
+          validityHours: 24,
+          port: 4204,
+        }),
+      },
+    );
+
+    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;
+  }
+}
+
 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: SignpadConfig = {
-    licenseKey: "YOUR-LICENSE-KEY",
-    // More info in "properties" section
-  };
+  useEffect(() => {
+    fetchLease().then((lease) => setConfig((prev) => ({ ...prev, lease })));
+  }, []);
 
   return (
     <div>
@@ -309,7 +412,7 @@ export default defineConfig({
 
 ## 3. Implementation
 
-In Vue 3, we use `ref` to hold the reference to the DOM element and pass the configuration via the `:config` attribute.
+In Vue 3, we use `ref` for both the element and config, then fetch the lease and assign it to config.
 
 ```typescript
 <script setup lang="ts">
@@ -320,11 +423,40 @@ 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: SignpadConfig = {
-  licenseKey: "YOUR-LICENSE-KEY",
-  // More info in "properties" section
+const signpadConfig = ref<SignpadConfig>({ lease: undefined });
+
+const fetchLease = async () => {
+  try {
+    const response = await fetch("https://test.signosoft.com/api/v1/driver/leases", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        licenceKey: "YOUR-LICENSE-KEY",
+        validityHours: 24,
+        port: 4204,
+      }),
+    });
+
+    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;
+  }
 };
 
+fetchLease()
+  .then((lease) => {
+    signpadConfig.value = {
+      ...signpadConfig.value,
+      lease,
+    };
+  });
+
 </script>
 
 <template>
@@ -376,8 +508,41 @@ const pad = document.querySelector("signosoft-signpad");
 
 // 1. Initial Configuration
 pad.config = {
-  licenseKey: "YOUR-LICENSE-KEY",
+  lease: undefined,
+};
+
+const fetchLease = async () => {
+  try {
+    const response = await fetch(
+      "https://test.signosoft.com/api/v1/driver/leases",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          licenceKey: "YOUR-LICENSE-KEY",
+          validityHours: 24,
+          port: 4204,
+        }),
+      },
+    );
+
+    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;
+  }
 };
+
+fetchLease().then((lease) => {
+  pad.config = { ...pad.config, lease };
+});
 ```
 
 ## 3. HTML Structure
@@ -421,10 +586,9 @@ The component is primarily configured through a single `config` property. This o
 
 ### 🔑 Core Options
 
-| Option               | Type     | Required | Description                                                           |
-| :------------------- | :------- | :------- | :-------------------------------------------------------------------- |
-| **`licenseKey`**     | `string` | **Yes**  | Your unique API key from signosoft.com. Mandatory for initialization. |
-| `customCssVariables` | `object` | No       | Custom theme object generated via the `getSignpadTheme` utility.      |
+| Option      | Type     | Required | Description                                                                   |
+| :---------- | :------- | :------- | :---------------------------------------------------------------------------- |
+| **`lease`** | `object` | **Yes**  | Lease payload returned from the lease API call. Mandatory for initialization. |
 
 ### 🔄 autoconnectOptions
 
@@ -482,25 +646,27 @@ The component provides two ways to interact with internal processes.
 
 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?: any` | 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 captured signature data. |
+| `handleClear`  | —                                   | Extends the internal Clear button logic.                                |
+| `handleCancel` | —                                   | Extends the internal Cancel button logic.                               |
 
 #### 🔔 Event Callbacks (`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. |
-| `onConnect`    | `event: CustomEvent`            | Dispatched when a device or mouse fallback connects.                                               |
-| `onDisconnect` | —                               | Dispatched when the hardware connection is closed.                                                 |
-| `onOk`         | `data: any`                     | Dispatched when signature is confirmed.                                                            |
-| `onClear`      | —                               | Dispatched when the canvas has been cleared.                                                       |
-| `onCancel`     | —                               | Dispatched when the user aborts the session.                                                       |
-| `onError`      | `error: Error`                  | Dispatched on critical failures (License, Driver, etc.).                                           |
+| Callback       | Payload                                          | Description                                                                                        |
+| :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------------- |
+| `onPen`        | `event: CustomEvent<IPenData> `                  | Dispatched when a device or mouse fallback are in contact with component or signature pad display. |
+| `onConnect`    | `event: CustomEvent`                             | Dispatched when a device or mouse fallback connects.                                               |
+| `onDisconnect` | —                                                | Dispatched when the hardware connection is closed.                                                 |
+| `onOk`         | `event: CustomEvent<ISignatureConfirmationData>` | Dispatched when signature is confirmed.                                                            |
+| `onClear`      | —                                                | Dispatched when the canvas has been cleared.                                                       |
+| `onCancel`     | —                                                | Dispatched when the user aborts the session.                                                       |
+| `onError`      | `error: Error`                                   | Dispatched on critical failures (Lease, Driver, etc.).                                             |
+
+> `actionHandlers` and `eventCallbacks` are separate hooks and can both be configured.
 
 ---
 
@@ -508,7 +674,7 @@ Standard event listeners triggered _after_ specific actions. Useful for observin
 
 ```typescript
 this.config = {
-  licenseKey: "your-signosoft-license-key",
+  lease: leasePayloadFromApi,
   autoconnectOptions: {
     autoConnect: true,
   },
@@ -532,15 +698,15 @@ this.config = {
 
 The following methods are available on the component instance to control the signing process programmatically.
 
-| Method           | Returns            | Description                                                                      |
-| :--------------- | :----------------- | :------------------------------------------------------------------------------- |
-| `connect()`      | `Promise<boolean>` | Connects device to component                                                     |
-| `disconnect()`   | `Promise<void>`    | Disconnects device from component                                                |
-| `startSigning()` | `Promise<void>`    | Initializes a new signing session on the canvas and hardware.                    |
-| `stopSigning()`  | `Promise<any>`     | Immediately ends the session and returns the captured signature data.            |
-| `ok()`           | `Promise<any>`     | Finalizes the session, cleans the device screen, and returns the signature data. |
-| `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.                       |
+| Method           | Returns                                            | Description                                                                      |
+| :--------------- | :------------------------------------------------- | :------------------------------------------------------------------------------- |
+| `connect()`      | `Promise<boolean>`                                 | Connects device to component                                                     |
+| `disconnect()`   | `Promise<void>`                                    | Disconnects device from component                                                |
+| `startSigning()` | `Promise<void>`                                    | Initializes a new signing session on the canvas and hardware.                    |
+| `stopSigning()`  | `Promise<any>`                                     | Immediately ends the session and returns the captured signature data.            |
+| `ok()`           | `Promise<ISignatureConfirmationData \| undefined>` | Finalizes the session, cleans the device screen, and returns the signature data. |
+| `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.                       |
 
 ---
 
@@ -599,6 +765,87 @@ This is the standard way to confirm a signature. It:
 3. Dispatches the `SIGN_OK` event.
 4. Returns the final signature payload (coordinates, pressure, metadata).
 
+**Returned payload shape (`ISignatureConfirmationData`)**
+
+```js
+[
+  points, // index 0: Data about each point
+  imageBase64, // index 1: Image in base64
+  metadata, // index 2: Information about tablet and canvas
+];
+```
+
+```js
+// [0] Points structure
+{
+  absoluteX: number,
+  absoluteY: number,
+  inContact: boolean,
+  pressure: number,
+  ready: boolean,
+  relativeX: number, // normalized 0..1
+  relativeY: number, // normalized 0..1
+  sequence: number,
+  timestamp: number | bigint
+}
+```
+
+```js
+// [1] Image structure
+{
+  data: image / png;
+  (base64, Some - long - string);
+}
+```
+
+```js
+// [2] Metadata structure
+{
+  canvas: {
+    top: number,
+    left: number,
+    right: number,
+    bottom: number,
+    width: number,
+    height: number,
+    cssWidth: number,
+    cssHeight: number,
+    dpr: 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
+  }
+}
+```
+
+`handleOk(data)` receives the same structure. `onOk` receives it in `event.detail`.
+
+#### 📜 `onPen` payload
+
+`onPen` is emitted continuously while writing and provides a single `IPenData` object in `event.detail`.
+
+```js
+{
+  absoluteX: number,
+  absoluteY: number,
+  inContact: boolean,
+  pressure: number,
+  ready: boolean,
+  relativeX: number, // normalized 0..1
+  relativeY: number, // normalized 0..1
+  sequence: number,
+  timestamp: number | bigint
+}
+```
+
 #### 📜 `stopSigning()`
 
 A low-level method that forces the driver to stop capturing data and returns the raw signature object. Unlike `ok()`, it does not trigger the full "Finalization" flow (UI transitions or device screen clearing).
@@ -613,44 +860,97 @@ Stops the session immediately. It does not collect any signature data and resets
 
 ## 🎨 Styling & Theming
 
-The component is designed to be fully customizable to match your brand's identity. You can style it using **CSS Variables** or by using our built-in **Theme Generator**.
-
-### 🛠️ Built-in Theme Generator
-
-The easiest way to create a consistent theme is to use our CLI utility. It generates a configuration object that you can pass directly to the component.
-
-**1. Run the generator in your terminal:**
-
-```bash
-npx getSignpadTheme
-```
-
-The CLI will guide you through:
-
-- **Output path:** Where to save the file.
-- **Filename:** What to call the file.
-- **Format:** Choose between `.js` or `.ts`.
+The component uses a hybrid theming model:
 
-**2. Import and apply the theme:**
-Once generated, import the file and pass it to your configuration object:
+- It ships with complete default styles (works out of the box).
+- You can override the visual design through CSS variables.
 
-```typescript
-import { myCustomTheme } from "./styles/myCustomTheme";
+## ✍️ Override via CSS
 
-this.config = {
-  licenseKey: "...",
-  customCssVariables: myCustomTheme,
-};
-```
+You can override variables in your stylesheet
 
-### ✍️ Manual CSS Customization
+### 📎 Copy-Paste Starter
 
-You can override the CSS variables directly in your global stylesheet to fine-tune the appearance:
+Paste this directly into your app stylesheet and adjust values:
 
 ```css
 signosoft-signpad {
-  --primary-color-0: #0056b3;
-  --sign-canvas-bg-base: #ffffff;
+  /* 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;
+
+  /* Constraints */
+  --min-height: 48px;
+  --spacing-constraints: 16px 24px;
+
+  /* CSS Variables */
+  --sign-font-family: Arial, Helvetica, sans-serif;
+
+  /* Top Bar */
+  --sign-top-bar-bg-base: var(--background-color-10);
+  --sign-top-bar-text-base: var(--primary-color-0);
+  --sign-top-bar-padding: var(--spacing-constraints);
+  --sign-top-bar-min-height: var(--min-height);
+
+  /* Canvas Area */
+  --sign-canvas-bg-base: var(--background-color-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-canvas-height-offset: var(--sign-line-height);
+
+  /* Bottom Bar */
+  --sign-bottom-bar-bg-base: var(--background-color-10);
+  --sign-bottom-bar-padding: var(--spacing-constraints);
+  --sign-bottom-bar-min-height: var(--min-height);
+  --sign-bottom-bar-gap: 12px;
+
+  /* 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;
+
+  /* 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);
+
+  /* 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);
+
+  /* Device State Text Colors */
+  --sign-device-state-text-color-connected: green;
+  --sign-device-state-text-color-disconnected: red;
+
+  /* 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;
 }
 ```
 
@@ -678,41 +978,44 @@ signosoft-signpad {
 
 #### Top Bar
 
-| Variable                    | Description                      |
-| :-------------------------- | :------------------------------- |
-| `--sign-top-bar-bg-base`    | Background color of the top bar. |
-| `--sign-top-bar-text-base`  | Text color in the top bar.       |
-| `--sign-top-bar-padding`    | Inner padding of the top bar.    |
-| `--sign-top-bar-min-height` | Minimum height of the 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-padding`    | `var(--spacing-constraints)` | Inner padding of the top bar.    |
+| `--sign-top-bar-min-height` | `var(--min-height)`          | Minimum height of the top bar.   |
 
 #### Canvas & Signature Line
 
-| Variable                            | Description                                   |
-| :---------------------------------- | :-------------------------------------------- |
-| `--sign-canvas-bg-base`             | Background color of the drawing area.         |
-| `--sign-line-height`                | Vertical offset/height for the guide line.    |
-| `--sign-line-border-base`           | Color of the signature guide line.            |
-| `--sign-line-additional-text-color` | Color of the helper text below the line.      |
-| `--sign-line-margin`                | Spacing around the guide line.                |
-| `--sign-canvas-line-text-font-size` | Font size for guide line labels.              |
-| `--sign-canvas-height-offset`       | Canvas offset calculation for the guide line. |
+| Variable                            | Default                                        | Description                                   |
+| :---------------------------------- | :--------------------------------------------- | :-------------------------------------------- |
+| `--sign-canvas-bg-base`             | `var(--background-color-0)`                    | Background color of the drawing area.         |
+| `--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. |
 
 #### Bottom Bar
 
-| Variable                       | Description                              |
-| :----------------------------- | :--------------------------------------- |
-| `--sign-bottom-bar-bg-base`    | Background color of the bottom bar.      |
-| `--sign-bottom-bar-padding`    | Inner padding of the bottom bar.         |
-| `--sign-bottom-bar-min-height` | Minimum height of the bottom bar.        |
-| `--sign-bottom-bar-gap`        | Space between buttons in the bottom bar. |
+| Variable                       | Default                      | Description                              |
+| :----------------------------- | :--------------------------- | :--------------------------------------- |
+| `--sign-bottom-bar-bg-base`    | `var(--background-color-10)` | 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. |
 
 #### Buttons (General)
 
-| Variable                   | Default       | Description                      |
-| :------------------------- | :------------ | :------------------------------- |
-| `--sign-button-font-size`  | `12px - 16px` | Fluid font size for all buttons. |
-| `--sign-button-padding`    | `14px 16px`   | Inner padding for all buttons.   |
-| `--sign-button-min-height` | `48px`        | Minimum height for buttons.      |
+| 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.   |
 
 #### Primary Buttons (OK, Clear, Cancel)
 
@@ -727,31 +1030,130 @@ signosoft-signpad {
 
 #### Link/Connect Buttons
 
-| Variable                          | Description                                  |
-| :-------------------------------- | :------------------------------------------- |
-| `--sign-button-link-bg-base`      | Background color for secondary/link buttons. |
-| `--sign-button-link-text-base`    | Text color for secondary/link buttons.       |
-| `--sign-button-link-border-base`  | Border for secondary/link buttons.           |
-| `--sign-button-link-text-hover`   | Hover text color.                            |
-| `--sign-button-link-border-hover` | Hover border color.                          |
+| 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.                       |
 
 #### 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(...)` | Background of the loading spinner. |
-| `--sign-loading-overlay-spinner-color`        | `#4e56ea`   | Color of the animated spinner.     |
-| `--sign-loading-overlay-spinner-size`         | `30px`      | Size of the spinner icon.          |
+| 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
+## 💬 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:
+
+- `MAJOR` (`x.0.0`): breaking changes
+- `MINOR` (`x.y.0`): backward-compatible feature set
+- `PATCH` (`x.y.z`): backward-compatible bug fixes
+
+Commit naming for version bumps:
+
+- 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>`
+
+Example (version bump with feature changes):
+
+```bash
+git commit -m "MAIN-000/feat: release from 0.2.4 to 0.3.0 - add signature method"
+```
+
+Example (version-only commit):
+
+```bash
+git commit -m "MAIN-000/chore: release from 0.2.4 to 0.3.0"
+```
+
+How version increment works:
+
+- `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`)
+
+Examples:
+
+```bash
+# patch
+git commit -m "MAIN-000/fix: release from 1.0.0 to 1.0.1 - fix onPen throttle edge case"
+
+# minor
+git commit -m "MAIN-000/feat: release from 1.1.1 to 1.2.0 - add lease refresh helper"
+
+# major
+git commit -m "MAIN-000/refactor: release from 1.1.1 to 2.0.0 - remove legacy API"
+```
+
 ## 📄 License
 
 **Proprietary Commercial License**