finality-ux-sampler 1.1.1

package/ATTRIBUTION.md

@@ -0,0 +1,10 @@
+# Attribution
+
+When you reuse the sampler's interface copy or visual design, include a credit
+in your app's credits, documentation, or another place suitable for your use:
+
+> Interface copy and design adapted from [Finality UX Kit Free Sampler](https://finality-ux-kit.pages.dev/from-code/), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Changes: describe your changes here.
+
+If you use the work without changes, replace the last sentence with “Used
+without changes.” Preserve the MIT notice when redistributing the component
+code. No visible product logo or tracking code is required.

package/LICENSE

@@ -0,0 +1,11 @@
+Finality UX Kit Free Sampler
+
+Component implementation, JavaScript/TypeScript interfaces and integration
+examples: MIT. See LICENSE-CODE.txt.
+
+Visual design and interface copy, including the text in dist/states.json and
+dist/states.mjs: Creative Commons Attribution 4.0 International (CC BY 4.0).
+See LICENSE-DESIGN.txt and ATTRIBUTION.md.
+
+The package combines these works; it does not offer a choice between licenses.
+These free-sampler licenses do not license the separate paid Finality Core Kit.

package/LICENSE-CODE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Finality UX Kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE-DESIGN.txt

@@ -0,0 +1,16 @@
+Finality UX Kit Free Sampler design and interface copy
+Copyright (c) 2026 Finality UX Kit
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+You may share and adapt the free sampler's design and interface copy for any
+purpose provided you give appropriate credit, link to the license, and indicate
+changes. This notice is a summary; the full license controls.
+
+License: https://creativecommons.org/licenses/by/4.0/
+Full legal text: https://creativecommons.org/licenses/by/4.0/legalcode
+Creator: Finality UX Kit
+Source: https://finality-ux-kit.pages.dev/from-code/
+
+This license covers the visual design and interface copy in this free package.
+It does not grant rights to third-party names or trademarks or to the separately
+sold Finality Core Kit. See ATTRIBUTION.md for an example credit.

package/README.md

@@ -0,0 +1,123 @@
+# Finality UX Kit — Free Sampler
+
+One React/Tailwind card and eight editable wallet and transaction copy examples.
+Use it to prototype connection, network, signature, approval, pending, finalized,
+and reverted states with explicit recovery instructions.
+
+The package renders the state you supply. It does not connect a wallet, send
+transactions, verify payments, or advance a flow automatically. Base, amounts,
+confirmation counts, transaction IDs and receipt times in the catalog are
+illustrative: replace them with data verified by your application. Transition
+entries describe examples; `external:` targets require your application's logic.
+A signed message alone does not prove that a transaction was submitted.
+
+For the free SVG import board, copy CSV and JSON, [download the full free
+sampler](https://finality-ux-kit.pages.dev/starter/?source=code). The separate
+[Finality Core Kit](https://finality-ux-kit.pages.dev/from-code/) adds an
+eleven-state transfer flow, native Figma components and a typed React controller.
+
+## Install
+
+```sh
+npm install finality-ux-sampler react
+```
+
+React 18.2 or 19 and Tailwind CSS 3.4 or 4 are supported. Runtime exports are
+compiled ESM; your application does not need to transpile JSX inside this
+package. CommonJS `require()` is not the supported interface. TypeScript
+declarations cover the root and `finality-ux-sampler/states` exports.
+
+## Include Tailwind styles
+
+The package ships utility classes, not a stylesheet. Tailwind normally excludes
+`node_modules`, so add the package explicitly to your existing Tailwind setup.
+
+For Tailwind 4, in **`src/app.css`**:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/finality-ux-sampler/src";
+```
+
+The `@source` path is relative to that CSS file. Adjust it if your stylesheet
+lives elsewhere.
+
+For Tailwind 3.4, add this entry to **`tailwind.config.js`** in your project root:
+
+```js
+export default {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/finality-ux-sampler/src/**/*.jsx",
+  ],
+  theme: { extend: {} },
+  plugins: [],
+};
+```
+
+Keep your app's existing content paths, theme and plugins when merging this
+example. The card uses fixed utility names, so all five tones can be detected.
+
+## Render a state
+
+```jsx
+import { FinalityStateCard, finalityStates } from "finality-ux-sampler";
+
+export function PendingCard({ transaction, onViewActivity, onCopyId }) {
+  const example = finalityStates.find(s => s.id === "transaction.pending");
+  const state = {
+    ...example,
+    title: "Your transfer is processing",
+    status: "Submitted",
+    body: `Transfer ${transaction.id} was submitted. Check its existing result.`,
+  };
+
+  return (
+    <FinalityStateCard
+      state={state}
+      onPrimaryAction={onViewActivity}
+      onSecondaryAction={() => onCopyId(transaction.id)}
+    />
+  );
+}
+```
+
+Pass callbacks for the actions your app supports. A missing callback disables
+its button. `disabled={true}` disables both actions while your own operation is
+pending. Callbacks receive the displayed state; the host owns network requests,
+timeouts, duplicate-submission prevention, error handling and focus after a
+wallet dialog. In a Next.js App Router app, render the interactive card from a
+client component with `"use client"`.
+
+## Catalog and types
+
+```ts
+import { finalityCatalog, finalityStates } from "finality-ux-sampler/states";
+import type { FinalityState, FinalityStateId } from "finality-ux-sampler/states";
+```
+
+The plain JSON export is `finality-ux-sampler/states.json`; import it using the
+JSON-module syntax supported by your runtime or bundler.
+
+| State ID | Example |
+| --- | --- |
+| `wallet.disconnected` | Choose a wallet |
+| `network.unsupported` | Review the expected network |
+| `signature.requested` | Review a signature |
+| `signature.rejected` | Recover from rejection |
+| `approval.requested` | Review a spending cap |
+| `transaction.pending` | Check an existing transaction |
+| `transaction.finalized` | Review a verified receipt |
+| `transaction.reverted` | Review a revert before retrying |
+
+The sampler does not include an unknown-result card. Treat a timeout as an
+unknown outcome in your host flow, preserve the original request, and check it
+before allowing a retry that could send money again.
+
+## License and support
+
+Code is MIT; design and interface copy are CC BY 4.0. See `LICENSE` and
+`ATTRIBUTION.md` for the file boundaries and a ready-to-use credit. The separate
+paid Core Kit has its own license. No analytics or tracking is included here.
+
+[Support](https://finality-ux-kit.pages.dev/support/).

package/dist/FinalityStateCard.mjs

@@ -0,0 +1,99 @@
+import React from "react";
+const toneClassNames = Object.freeze({
+  neutral: {
+    shell: "border-slate-700 bg-slate-900",
+    badge: "bg-slate-800 text-slate-200",
+    icon: "bg-slate-800 text-slate-200"
+  },
+  attention: {
+    shell: "border-sky-900 bg-slate-900",
+    badge: "bg-sky-950 text-sky-200",
+    icon: "bg-sky-950 text-sky-200"
+  },
+  warning: {
+    shell: "border-amber-900 bg-slate-900",
+    badge: "bg-amber-950 text-amber-200",
+    icon: "bg-amber-950 text-amber-200"
+  },
+  danger: {
+    shell: "border-rose-900 bg-slate-900",
+    badge: "bg-rose-950 text-rose-200",
+    icon: "bg-rose-950 text-rose-200"
+  },
+  success: {
+    shell: "border-emerald-900 bg-slate-900",
+    badge: "bg-emerald-950 text-emerald-200",
+    icon: "bg-emerald-950 text-emerald-200"
+  }
+});
+function cx(...values) {
+  return values.filter(Boolean).join(" ");
+}
+function FinalityStateCard({
+  state,
+  onPrimaryAction,
+  onSecondaryAction,
+  disabled = false
+}) {
+  if (!state || !toneClassNames[state.tone]) {
+    throw new Error("FinalityStateCard requires a valid Finality state.");
+  }
+  const tone = toneClassNames[state.tone];
+  const live = state.live === "off" ? void 0 : state.live;
+  return /* @__PURE__ */ React.createElement(
+    "article",
+    {
+      className: cx(
+        "grid min-h-[30rem] grid-rows-[auto_auto_1fr_auto] rounded-[1.5rem] border p-6 text-slate-50 shadow-2xl shadow-black/20",
+        tone.shell
+      ),
+      "data-state-id": state.id,
+      "data-state-version": "1.1.1"
+    },
+    /* @__PURE__ */ React.createElement("header", { className: "flex items-start justify-between gap-4" }, /* @__PURE__ */ React.createElement("div", null, /* @__PURE__ */ React.createElement("p", { className: "font-mono text-xs uppercase tracking-[0.16em] text-slate-400" }, state.eyebrow), /* @__PURE__ */ React.createElement("h2", { className: "mt-3 text-2xl font-semibold leading-tight" }, state.title)), /* @__PURE__ */ React.createElement(
+      "span",
+      {
+        "aria-hidden": "true",
+        className: cx(
+          "grid size-11 shrink-0 place-items-center rounded-2xl font-mono text-sm uppercase",
+          tone.icon
+        )
+      },
+      String(state.order).padStart(2, "0")
+    )),
+    /* @__PURE__ */ React.createElement(
+      "p",
+      {
+        "aria-live": live,
+        className: cx(
+          "mt-6 w-fit rounded-full px-3 py-1 font-mono text-xs font-semibold uppercase tracking-[0.12em]",
+          tone.badge
+        )
+      },
+      state.status
+    ),
+    /* @__PURE__ */ React.createElement("div", { className: "py-6" }, /* @__PURE__ */ React.createElement("p", { className: "text-base leading-7 text-slate-300" }, state.body), /* @__PURE__ */ React.createElement("dl", { className: "mt-6 space-y-4 border-t border-slate-800 pt-5 text-sm" }, /* @__PURE__ */ React.createElement("div", null, /* @__PURE__ */ React.createElement("dt", { className: "font-semibold text-slate-100" }, "Safe recovery"), /* @__PURE__ */ React.createElement("dd", { className: "mt-1 leading-6 text-slate-400" }, state.recovery)), /* @__PURE__ */ React.createElement("div", null, /* @__PURE__ */ React.createElement("dt", { className: "font-semibold text-slate-100" }, "Safety note"), /* @__PURE__ */ React.createElement("dd", { className: "mt-1 leading-6 text-slate-400" }, state.safetyNote)))),
+    /* @__PURE__ */ React.createElement("div", { className: "grid gap-3" }, /* @__PURE__ */ React.createElement(
+      "button",
+      {
+        type: "button",
+        disabled: disabled || typeof onPrimaryAction !== "function",
+        onClick: () => onPrimaryAction?.(state),
+        className: "min-h-12 rounded-xl bg-lime-300 px-4 py-3 font-semibold text-slate-950 outline-none transition hover:bg-lime-200 focus-visible:ring-4 focus-visible:ring-lime-200/40 disabled:cursor-not-allowed disabled:opacity-50 motion-reduce:transition-none"
+      },
+      state.primaryAction
+    ), /* @__PURE__ */ React.createElement(
+      "button",
+      {
+        type: "button",
+        disabled: disabled || typeof onSecondaryAction !== "function",
+        onClick: () => onSecondaryAction?.(state),
+        className: "min-h-12 rounded-xl border border-slate-700 px-4 py-3 font-semibold text-slate-100 outline-none transition hover:border-slate-500 hover:bg-slate-800 focus-visible:ring-4 focus-visible:ring-lime-200/30 disabled:cursor-not-allowed disabled:opacity-50 motion-reduce:transition-none"
+      },
+      state.secondaryAction
+    ))
+  );
+}
+export {
+  FinalityStateCard
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentType } from "react";
+import type { FinalityState } from "./states.js";
+export * from "./states.js";
+export interface FinalityStateCardProps {
+  state: FinalityState;
+  onPrimaryAction?: (state: FinalityState) => void;
+  onSecondaryAction?: (state: FinalityState) => void;
+  disabled?: boolean;
+}
+export const FinalityStateCard: ComponentType<FinalityStateCardProps>;

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { FinalityStateCard } from "./FinalityStateCard.mjs";
+export { finalityCatalog, finalityStates } from "./states.mjs";

package/dist/states.d.ts

@@ -0,0 +1,27 @@
+export type FinalityStateId = "wallet.disconnected" | "network.unsupported" | "signature.requested" | "signature.rejected" | "approval.requested" | "transaction.pending" | "transaction.finalized" | "transaction.reverted";
+export type FinalityTone = "neutral" | "attention" | "warning" | "danger" | "success";
+export interface FinalityTransition { event: string; label: string; target: string; }
+export interface FinalityState {
+  order: number;
+  id: FinalityStateId;
+  family: string;
+  tone: FinalityTone;
+  icon: string;
+  eyebrow: string;
+  title: string;
+  body: string;
+  status: string;
+  primaryAction: string;
+  secondaryAction: string;
+  recovery: string;
+  safetyNote: string;
+  live: "off" | "polite";
+  figmaVariant: string;
+  reactVariant: string;
+  transitions: FinalityTransition[];
+}
+export const finalityStates: FinalityState[];
+export const finalityCatalog: {
+  catalog: { id: string; version: string; title: string; updatedAt: string; language: string; stateCount: number; licenses: { design: string; code: string } };
+  states: FinalityState[];
+};

package/dist/states.json

@@ -0,0 +1,246 @@
+{
+  "catalog": {
+    "id": "finality-ux-sampler",
+    "version": "1.1.1",
+    "title": "Finality UX Kit — Free Sampler",
+    "updatedAt": "2026-08-21",
+    "language": "en",
+    "stateCount": 8,
+    "licenses": {
+      "design": "CC BY 4.0",
+      "code": "MIT"
+    }
+  },
+  "states": [
+    {
+      "order": 1,
+      "id": "wallet.disconnected",
+      "family": "wallet",
+      "tone": "neutral",
+      "icon": "wallet",
+      "eyebrow": "Before the request",
+      "title": "Connect a wallet you trust",
+      "body": "No wallet is connected. Choose one to review this action; connecting does not approve or submit anything.",
+      "status": "Not connected",
+      "primaryAction": "Choose wallet",
+      "secondaryAction": "Why connect?",
+      "recovery": "Check the site address before selecting a wallet.",
+      "safetyNote": "Never enter a seed phrase on this screen.",
+      "live": "off",
+      "figmaVariant": "State=Disconnected,Tone=Neutral",
+      "reactVariant": "disconnected",
+      "transitions": [
+        {
+          "event": "wallet_connected",
+          "label": "Wallet connected",
+          "target": "external:next-request"
+        }
+      ]
+    },
+    {
+      "order": 2,
+      "id": "network.unsupported",
+      "family": "network",
+      "tone": "warning",
+      "icon": "network",
+      "eyebrow": "Network check",
+      "title": "Switch to Base to continue",
+      "body": "This action is prepared for Base, but your wallet is connected to Ethereum. Review the network change in your wallet.",
+      "status": "Wrong network",
+      "primaryAction": "Switch network",
+      "secondaryAction": "Cancel action",
+      "recovery": "If Base is unexpected, cancel and verify the original link.",
+      "safetyNote": "A network switch does not authorize a transaction.",
+      "live": "polite",
+      "figmaVariant": "State=Unsupported network,Tone=Warning",
+      "reactVariant": "unsupported-network",
+      "transitions": [
+        {
+          "event": "network_changed",
+          "label": "Expected network selected",
+          "target": "external:retry-intent"
+        },
+        {
+          "event": "cancelled",
+          "label": "Action cancelled",
+          "target": "external:idle"
+        }
+      ]
+    },
+    {
+      "order": 3,
+      "id": "signature.requested",
+      "family": "signature",
+      "tone": "attention",
+      "icon": "signature",
+      "eyebrow": "Wallet action",
+      "title": "Review the signature request",
+      "body": "Your wallet has the final request. Match the site, action, and displayed details before you sign.",
+      "status": "Waiting for signature",
+      "primaryAction": "Open wallet",
+      "secondaryAction": "Cancel request",
+      "recovery": "If the wallet details differ from this screen, reject the request.",
+      "safetyNote": "A signature can authorize actions even when no network fee is shown.",
+      "live": "polite",
+      "figmaVariant": "State=Signature requested,Tone=Attention",
+      "reactVariant": "signature-requested",
+      "transitions": [
+        {
+          "event": "signature_approved",
+          "label": "Signature approved",
+          "target": "transaction.pending"
+        },
+        {
+          "event": "signature_rejected",
+          "label": "Signature rejected",
+          "target": "signature.rejected"
+        }
+      ]
+    },
+    {
+      "order": 4,
+      "id": "signature.rejected",
+      "family": "signature",
+      "tone": "neutral",
+      "icon": "close",
+      "eyebrow": "Request ended",
+      "title": "You rejected the request",
+      "body": "Nothing was signed or submitted. You can close this action or review the details and start again.",
+      "status": "Not submitted",
+      "primaryAction": "Review and retry",
+      "secondaryAction": "Close",
+      "recovery": "A fresh request should show the same site, action, and amount.",
+      "safetyNote": "Repeated prompts can be a warning sign; pause if you did not retry.",
+      "live": "polite",
+      "figmaVariant": "State=Signature rejected,Tone=Neutral",
+      "reactVariant": "signature-rejected",
+      "transitions": [
+        {
+          "event": "retry",
+          "label": "Fresh request created",
+          "target": "signature.requested"
+        },
+        {
+          "event": "dismissed",
+          "label": "Flow closed",
+          "target": "external:idle"
+        }
+      ]
+    },
+    {
+      "order": 5,
+      "id": "approval.requested",
+      "family": "approval",
+      "tone": "warning",
+      "icon": "shield",
+      "eyebrow": "Permission request",
+      "title": "Review the 250 USDC spending cap",
+      "body": "This permission lets the app use up to 250 USDC. It is not the transfer itself and remains active until used or revoked.",
+      "status": "Approval required",
+      "primaryAction": "Review permission",
+      "secondaryAction": "Use a lower cap",
+      "recovery": "Prefer the smallest cap and duration that complete the intended action.",
+      "safetyNote": "Unlimited approvals increase the impact of a compromised app.",
+      "live": "polite",
+      "figmaVariant": "State=Approval requested,Tone=Warning",
+      "reactVariant": "approval-requested",
+      "transitions": [
+        {
+          "event": "approval_signed",
+          "label": "Approval submitted",
+          "target": "transaction.pending"
+        },
+        {
+          "event": "approval_rejected",
+          "label": "Approval rejected",
+          "target": "signature.rejected"
+        }
+      ]
+    },
+    {
+      "order": 6,
+      "id": "transaction.pending",
+      "family": "transaction",
+      "tone": "attention",
+      "icon": "clock",
+      "eyebrow": "Submitted",
+      "title": "Transaction is confirming",
+      "body": "Transaction 0x8D…91A was submitted. One confirmation is recorded; two are required before this app treats it as final.",
+      "status": "1 of 2 confirmations",
+      "primaryAction": "View activity",
+      "secondaryAction": "Copy transaction ID",
+      "recovery": "Do not submit the same action again while its final status is unknown.",
+      "safetyNote": "Leaving this page does not cancel a submitted transaction.",
+      "live": "polite",
+      "figmaVariant": "State=Transaction pending,Tone=Attention",
+      "reactVariant": "transaction-pending",
+      "transitions": [
+        {
+          "event": "finalized",
+          "label": "Required finality reached",
+          "target": "transaction.finalized"
+        },
+        {
+          "event": "reverted",
+          "label": "Execution reverted",
+          "target": "transaction.reverted"
+        },
+        {
+          "event": "timeout",
+          "label": "Status remains unknown",
+          "target": "external:transaction-unknown"
+        }
+      ]
+    },
+    {
+      "order": 7,
+      "id": "transaction.finalized",
+      "family": "transaction",
+      "tone": "success",
+      "icon": "check",
+      "eyebrow": "Complete",
+      "title": "Transfer reached finality",
+      "body": "The confirmed transfer completed at 14:32 UTC. The receipt includes the network, amount, destination, and transaction ID.",
+      "status": "Finalized",
+      "primaryAction": "View receipt",
+      "secondaryAction": "Copy transaction ID",
+      "recovery": "Keep the receipt if this action is part of a later support request.",
+      "safetyNote": "Verify the destination and amount in the receipt, not only the success label.",
+      "live": "polite",
+      "figmaVariant": "State=Transaction finalized,Tone=Success",
+      "reactVariant": "transaction-finalized",
+      "transitions": [
+        {
+          "event": "receipt_opened",
+          "label": "Receipt opened",
+          "target": "external:block-explorer"
+        }
+      ]
+    },
+    {
+      "order": 8,
+      "id": "transaction.reverted",
+      "family": "transaction",
+      "tone": "danger",
+      "icon": "error",
+      "eyebrow": "Did not complete",
+      "title": "Transaction reverted",
+      "body": "The requested state change did not complete. The network may still charge a fee for the failed execution.",
+      "status": "Reverted onchain",
+      "primaryAction": "Review failure",
+      "secondaryAction": "View transaction",
+      "recovery": "Fix the stated cause before creating a new transaction.",
+      "safetyNote": "Do not promise that all funds or fees are unchanged after a revert.",
+      "live": "polite",
+      "figmaVariant": "State=Transaction reverted,Tone=Danger",
+      "reactVariant": "transaction-reverted",
+      "transitions": [
+        {
+          "event": "cause_resolved",
+          "label": "Failure cause resolved",
+          "target": "external:rebuild-transaction"
+        }
+      ]
+    }
+  ]
+}

package/dist/states.mjs

@@ -0,0 +1,247 @@
+export const finalityCatalog = {
+  "catalog": {
+    "id": "finality-ux-sampler",
+    "version": "1.1.1",
+    "title": "Finality UX Kit — Free Sampler",
+    "updatedAt": "2026-08-21",
+    "language": "en",
+    "stateCount": 8,
+    "licenses": {
+      "design": "CC BY 4.0",
+      "code": "MIT"
+    }
+  },
+  "states": [
+    {
+      "order": 1,
+      "id": "wallet.disconnected",
+      "family": "wallet",
+      "tone": "neutral",
+      "icon": "wallet",
+      "eyebrow": "Before the request",
+      "title": "Connect a wallet you trust",
+      "body": "No wallet is connected. Choose one to review this action; connecting does not approve or submit anything.",
+      "status": "Not connected",
+      "primaryAction": "Choose wallet",
+      "secondaryAction": "Why connect?",
+      "recovery": "Check the site address before selecting a wallet.",
+      "safetyNote": "Never enter a seed phrase on this screen.",
+      "live": "off",
+      "figmaVariant": "State=Disconnected,Tone=Neutral",
+      "reactVariant": "disconnected",
+      "transitions": [
+        {
+          "event": "wallet_connected",
+          "label": "Wallet connected",
+          "target": "external:next-request"
+        }
+      ]
+    },
+    {
+      "order": 2,
+      "id": "network.unsupported",
+      "family": "network",
+      "tone": "warning",
+      "icon": "network",
+      "eyebrow": "Network check",
+      "title": "Switch to Base to continue",
+      "body": "This action is prepared for Base, but your wallet is connected to Ethereum. Review the network change in your wallet.",
+      "status": "Wrong network",
+      "primaryAction": "Switch network",
+      "secondaryAction": "Cancel action",
+      "recovery": "If Base is unexpected, cancel and verify the original link.",
+      "safetyNote": "A network switch does not authorize a transaction.",
+      "live": "polite",
+      "figmaVariant": "State=Unsupported network,Tone=Warning",
+      "reactVariant": "unsupported-network",
+      "transitions": [
+        {
+          "event": "network_changed",
+          "label": "Expected network selected",
+          "target": "external:retry-intent"
+        },
+        {
+          "event": "cancelled",
+          "label": "Action cancelled",
+          "target": "external:idle"
+        }
+      ]
+    },
+    {
+      "order": 3,
+      "id": "signature.requested",
+      "family": "signature",
+      "tone": "attention",
+      "icon": "signature",
+      "eyebrow": "Wallet action",
+      "title": "Review the signature request",
+      "body": "Your wallet has the final request. Match the site, action, and displayed details before you sign.",
+      "status": "Waiting for signature",
+      "primaryAction": "Open wallet",
+      "secondaryAction": "Cancel request",
+      "recovery": "If the wallet details differ from this screen, reject the request.",
+      "safetyNote": "A signature can authorize actions even when no network fee is shown.",
+      "live": "polite",
+      "figmaVariant": "State=Signature requested,Tone=Attention",
+      "reactVariant": "signature-requested",
+      "transitions": [
+        {
+          "event": "signature_approved",
+          "label": "Signature approved",
+          "target": "transaction.pending"
+        },
+        {
+          "event": "signature_rejected",
+          "label": "Signature rejected",
+          "target": "signature.rejected"
+        }
+      ]
+    },
+    {
+      "order": 4,
+      "id": "signature.rejected",
+      "family": "signature",
+      "tone": "neutral",
+      "icon": "close",
+      "eyebrow": "Request ended",
+      "title": "You rejected the request",
+      "body": "Nothing was signed or submitted. You can close this action or review the details and start again.",
+      "status": "Not submitted",
+      "primaryAction": "Review and retry",
+      "secondaryAction": "Close",
+      "recovery": "A fresh request should show the same site, action, and amount.",
+      "safetyNote": "Repeated prompts can be a warning sign; pause if you did not retry.",
+      "live": "polite",
+      "figmaVariant": "State=Signature rejected,Tone=Neutral",
+      "reactVariant": "signature-rejected",
+      "transitions": [
+        {
+          "event": "retry",
+          "label": "Fresh request created",
+          "target": "signature.requested"
+        },
+        {
+          "event": "dismissed",
+          "label": "Flow closed",
+          "target": "external:idle"
+        }
+      ]
+    },
+    {
+      "order": 5,
+      "id": "approval.requested",
+      "family": "approval",
+      "tone": "warning",
+      "icon": "shield",
+      "eyebrow": "Permission request",
+      "title": "Review the 250 USDC spending cap",
+      "body": "This permission lets the app use up to 250 USDC. It is not the transfer itself and remains active until used or revoked.",
+      "status": "Approval required",
+      "primaryAction": "Review permission",
+      "secondaryAction": "Use a lower cap",
+      "recovery": "Prefer the smallest cap and duration that complete the intended action.",
+      "safetyNote": "Unlimited approvals increase the impact of a compromised app.",
+      "live": "polite",
+      "figmaVariant": "State=Approval requested,Tone=Warning",
+      "reactVariant": "approval-requested",
+      "transitions": [
+        {
+          "event": "approval_signed",
+          "label": "Approval submitted",
+          "target": "transaction.pending"
+        },
+        {
+          "event": "approval_rejected",
+          "label": "Approval rejected",
+          "target": "signature.rejected"
+        }
+      ]
+    },
+    {
+      "order": 6,
+      "id": "transaction.pending",
+      "family": "transaction",
+      "tone": "attention",
+      "icon": "clock",
+      "eyebrow": "Submitted",
+      "title": "Transaction is confirming",
+      "body": "Transaction 0x8D…91A was submitted. One confirmation is recorded; two are required before this app treats it as final.",
+      "status": "1 of 2 confirmations",
+      "primaryAction": "View activity",
+      "secondaryAction": "Copy transaction ID",
+      "recovery": "Do not submit the same action again while its final status is unknown.",
+      "safetyNote": "Leaving this page does not cancel a submitted transaction.",
+      "live": "polite",
+      "figmaVariant": "State=Transaction pending,Tone=Attention",
+      "reactVariant": "transaction-pending",
+      "transitions": [
+        {
+          "event": "finalized",
+          "label": "Required finality reached",
+          "target": "transaction.finalized"
+        },
+        {
+          "event": "reverted",
+          "label": "Execution reverted",
+          "target": "transaction.reverted"
+        },
+        {
+          "event": "timeout",
+          "label": "Status remains unknown",
+          "target": "external:transaction-unknown"
+        }
+      ]
+    },
+    {
+      "order": 7,
+      "id": "transaction.finalized",
+      "family": "transaction",
+      "tone": "success",
+      "icon": "check",
+      "eyebrow": "Complete",
+      "title": "Transfer reached finality",
+      "body": "The confirmed transfer completed at 14:32 UTC. The receipt includes the network, amount, destination, and transaction ID.",
+      "status": "Finalized",
+      "primaryAction": "View receipt",
+      "secondaryAction": "Copy transaction ID",
+      "recovery": "Keep the receipt if this action is part of a later support request.",
+      "safetyNote": "Verify the destination and amount in the receipt, not only the success label.",
+      "live": "polite",
+      "figmaVariant": "State=Transaction finalized,Tone=Success",
+      "reactVariant": "transaction-finalized",
+      "transitions": [
+        {
+          "event": "receipt_opened",
+          "label": "Receipt opened",
+          "target": "external:block-explorer"
+        }
+      ]
+    },
+    {
+      "order": 8,
+      "id": "transaction.reverted",
+      "family": "transaction",
+      "tone": "danger",
+      "icon": "error",
+      "eyebrow": "Did not complete",
+      "title": "Transaction reverted",
+      "body": "The requested state change did not complete. The network may still charge a fee for the failed execution.",
+      "status": "Reverted onchain",
+      "primaryAction": "Review failure",
+      "secondaryAction": "View transaction",
+      "recovery": "Fix the stated cause before creating a new transaction.",
+      "safetyNote": "Do not promise that all funds or fees are unchanged after a revert.",
+      "live": "polite",
+      "figmaVariant": "State=Transaction reverted,Tone=Danger",
+      "reactVariant": "transaction-reverted",
+      "transitions": [
+        {
+          "event": "cause_resolved",
+          "label": "Failure cause resolved",
+          "target": "external:rebuild-transaction"
+        }
+      ]
+    }
+  ]
+};
+export const finalityStates = finalityCatalog.states;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "finality-ux-sampler",
+  "version": "1.1.1",
+  "description": "Free React/Tailwind state card with eight wallet and transaction copy examples.",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./states": {
+      "types": "./dist/states.d.ts",
+      "import": "./dist/states.mjs",
+      "default": "./dist/states.mjs"
+    },
+    "./states.json": "./dist/states.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "LICENSE-CODE.txt",
+    "LICENSE-DESIGN.txt",
+    "ATTRIBUTION.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "keywords": [
+    "web3",
+    "wallet",
+    "transaction",
+    "ux",
+    "react",
+    "tailwind",
+    "figma",
+    "microcopy"
+  ],
+  "license": "(MIT AND CC-BY-4.0)",
+  "homepage": "https://finality-ux-kit.pages.dev/from-code/",
+  "bugs": {
+    "url": "https://finality-ux-kit.pages.dev/support/"
+  },
+  "author": "Finality UX Kit",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/FinalityStateCard.jsx

@@ -0,0 +1,121 @@
+import React from "react";
+
+const toneClassNames = Object.freeze({
+  neutral: {
+    shell: "border-slate-700 bg-slate-900",
+    badge: "bg-slate-800 text-slate-200",
+    icon: "bg-slate-800 text-slate-200"
+  },
+  attention: {
+    shell: "border-sky-900 bg-slate-900",
+    badge: "bg-sky-950 text-sky-200",
+    icon: "bg-sky-950 text-sky-200"
+  },
+  warning: {
+    shell: "border-amber-900 bg-slate-900",
+    badge: "bg-amber-950 text-amber-200",
+    icon: "bg-amber-950 text-amber-200"
+  },
+  danger: {
+    shell: "border-rose-900 bg-slate-900",
+    badge: "bg-rose-950 text-rose-200",
+    icon: "bg-rose-950 text-rose-200"
+  },
+  success: {
+    shell: "border-emerald-900 bg-slate-900",
+    badge: "bg-emerald-950 text-emerald-200",
+    icon: "bg-emerald-950 text-emerald-200"
+  }
+});
+
+function cx(...values) {
+  return values.filter(Boolean).join(" ");
+}
+
+export function FinalityStateCard({
+  state,
+  onPrimaryAction,
+  onSecondaryAction,
+  disabled = false
+}) {
+  if (!state || !toneClassNames[state.tone]) {
+    throw new Error("FinalityStateCard requires a valid Finality state.");
+  }
+
+  const tone = toneClassNames[state.tone];
+  const live = state.live === "off" ? undefined : state.live;
+
+  return (
+    <article
+      className={cx(
+        "grid min-h-[30rem] grid-rows-[auto_auto_1fr_auto] rounded-[1.5rem] border p-6 text-slate-50 shadow-2xl shadow-black/20",
+        tone.shell
+      )}
+      data-state-id={state.id}
+      data-state-version="1.1.1"
+    >
+      <header className="flex items-start justify-between gap-4">
+        <div>
+          <p className="font-mono text-xs uppercase tracking-[0.16em] text-slate-400">
+            {state.eyebrow}
+          </p>
+          <h2 className="mt-3 text-2xl font-semibold leading-tight">
+            {state.title}
+          </h2>
+        </div>
+        <span
+          aria-hidden="true"
+          className={cx(
+            "grid size-11 shrink-0 place-items-center rounded-2xl font-mono text-sm uppercase",
+            tone.icon
+          )}
+        >
+          {String(state.order).padStart(2, "0")}
+        </span>
+      </header>
+
+      <p
+        aria-live={live}
+        className={cx(
+          "mt-6 w-fit rounded-full px-3 py-1 font-mono text-xs font-semibold uppercase tracking-[0.12em]",
+          tone.badge
+        )}
+      >
+        {state.status}
+      </p>
+
+      <div className="py-6">
+        <p className="text-base leading-7 text-slate-300">{state.body}</p>
+        <dl className="mt-6 space-y-4 border-t border-slate-800 pt-5 text-sm">
+          <div>
+            <dt className="font-semibold text-slate-100">Safe recovery</dt>
+            <dd className="mt-1 leading-6 text-slate-400">{state.recovery}</dd>
+          </div>
+          <div>
+            <dt className="font-semibold text-slate-100">Safety note</dt>
+            <dd className="mt-1 leading-6 text-slate-400">{state.safetyNote}</dd>
+          </div>
+        </dl>
+      </div>
+
+      <div className="grid gap-3">
+        <button
+          type="button"
+          disabled={disabled || typeof onPrimaryAction !== "function"}
+          onClick={() => onPrimaryAction?.(state)}
+          className="min-h-12 rounded-xl bg-lime-300 px-4 py-3 font-semibold text-slate-950 outline-none transition hover:bg-lime-200 focus-visible:ring-4 focus-visible:ring-lime-200/40 disabled:cursor-not-allowed disabled:opacity-50 motion-reduce:transition-none"
+        >
+          {state.primaryAction}
+        </button>
+        <button
+          type="button"
+          disabled={disabled || typeof onSecondaryAction !== "function"}
+          onClick={() => onSecondaryAction?.(state)}
+          className="min-h-12 rounded-xl border border-slate-700 px-4 py-3 font-semibold text-slate-100 outline-none transition hover:border-slate-500 hover:bg-slate-800 focus-visible:ring-4 focus-visible:ring-lime-200/30 disabled:cursor-not-allowed disabled:opacity-50 motion-reduce:transition-none"
+        >
+          {state.secondaryAction}
+        </button>
+      </div>
+    </article>
+  );
+}