@tenerife.music/ui 2.1.1 → 2.3.1

package/README.md

@@ -1,20 +1,20 @@
 # 🌴 TUI
 
 **Token-driven UI architecture for long-living React products**
-Strict. Predictable. Built for system-level consistency.
+Predictable. Built for system-level consistency.
 
-![Release](https://img.shields.io/github/v/tag/Tureckiy-zart/tenerife-ui?style=for-the-badge&sort=semver)
-![npm version](https://img.shields.io/npm/v/@tenerife.music/ui?style=for-the-badge)
+![Release](https://img.shields.io/badge/release-v2.3.1-blue?style=for-the-badge)
+![npm version](https://img.shields.io/badge/npm-v2.3.1-blue?style=for-the-badge)
 ![React](https://img.shields.io/badge/React-18+-blue?style=for-the-badge)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?style=for-the-badge)
 ![TailwindCSS](https://img.shields.io/badge/TailwindCSS-3.4-38b2ac?style=for-the-badge)
 ![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
 
-**Current Release:** [v2.1.0](CHANGELOG.md#210) (npm)  
+**Current Release:** [v2.3.1](CHANGELOG.md#231) (npm)  
 **Next Release:** [Unreleased] — See [CHANGELOG](CHANGELOG.md#unreleased)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Tureckiy-zart/tenerife-ui/main/.github/banner.png" width="100%" alt="TUI Banner" />
+  <img src=".github/banner.png" width="100%" alt="TUI Banner" />
 </p>
 
 <p align="center">
@@ -30,8 +30,7 @@ Strict. Predictable. Built for system-level consistency.
 
 TUI is **not a beginner-friendly UI library**.
 
-This system is intentionally built for developers and teams who value
-**architectural consistency, long-term scalability, and system-level thinking**
+Built for teams who value **architectural consistency** and **long-term scalability**
 over quick experimentation or visual convenience.
 
 ### This library is for you if:
@@ -39,7 +38,6 @@ over quick experimentation or visual convenience.
 - You build **long-living products**, not throwaway interfaces
 - You want to **prevent design entropy**, not fight it later
 - You prefer **strict rules over flexible chaos**
-- You see constraints as a **feature**, not a limitation
 - You are comfortable trading short-term DX for long-term maintainability
 
 ### This library is NOT for you if:
@@ -53,11 +51,8 @@ over quick experimentation or visual convenience.
 
 - **Tokens are the single source of truth**
 - **The Foundation layer is locked and immutable**
-- **Design decisions must be explicit and centralized**
-- **Constraints exist to protect the system — even from its author**
 
-If the system feels strict, uncomfortable, or limiting at first —
-that means it is working as intended.
+If the system feels strict or limiting — that means it is working as intended.
 
 ---
 
@@ -93,7 +88,7 @@ import { Button } from "@tenerife.music/ui";
 export default function App() {
   return (
     <ThemeProvider defaultMode="night">
-      <Button variant="default">Click me</Button>
+      <Button variant="primary">Click me</Button>
     </ThemeProvider>
   );
 }
@@ -125,63 +120,38 @@ but this is optional.
 
 ## 📚 Documentation
 
-| Document                  | Description                             |
-| ------------------------- | --------------------------------------- |
-| **Complete Guide**        | System overview and usage principles    |
-| Tokens Guide              | Design token structure and philosophy   |
-| Theme Guide               | Theme configuration and modes           |
-| Fonts Guide               | Optional font setup                     |
-| **Architecture Lock**     | Canonical architectural constraints     |
-| **Final Foundation Lock** | Authoritative source of truth           |
-| **A11Y Lock**             | Accessibility system lock (WCAG 2.1 AA) |
-| Storybook                 | Component examples and contracts        |
-
-### Development Resources
-
-- **Component Creation**: [Extension Component Creation Checklist](docs/workflows/tasks/COMPONENT_CREATION_CHECKLIST.md)
-  - **CLI Generator**: Use `pnpm run component:generate -- <ComponentName> [--category <category>]` to generate component scaffold
-  - See checklist for complete process and requirements
-- **Component Refactoring**: [Component Refactoring Pipeline (18A)](docs/workflows/foundation/COMPONENT_REFACTORING_PIPELINE.md)
-  - **Canonical process** for reviewing, improving, and validating existing components
-  - Mandatory 12-step pipeline (STEP 0-11) for Foundation and Extension components
-  - See pipeline for complete refactoring process and requirements
-- **Component Examples**: [Extension Component Examples](docs/reference/EXTENSION_COMPONENT_EXAMPLES.md)
-- **Component Needs**: [Component Needs Inventory](docs/workflows/tasks/COMPONENT_NEEDS_INVENTORY.md)
-- **Feedback Process**: [Usage Feedback Process](docs/workflows/tasks/FEEDBACK_COLLECTION_PROCESS.md)
+### Public Docs
 
----
-
-## 🏗 Architecture Overview
-
-### Foundation Layer (Locked)
+| Document                 | Description                           | Link                                                                             |
+| ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------- |
+| **Getting Started**      | Integration and setup guide           | [docs/reference/INTEGRATION_GUIDE.md](docs/reference/INTEGRATION_GUIDE.md)       |
+| **API Reference**        | Public API documentation              | [docs/reference/API_REFERENCE.md](docs/reference/API_REFERENCE.md)               |
+| **Tokens Overview**      | Design token structure and philosophy | [docs/reference/TOKENS_OVERVIEW.md](docs/reference/TOKENS_OVERVIEW.md)           |
+| **Components Inventory** | Complete component list               | [docs/reference/COMPONENTS_INVENTORY.md](docs/reference/COMPONENTS_INVENTORY.md) |
+| **Documentation Hub**    | Complete documentation index          | [docs/README.md](docs/README.md)                                                 |
 
-The Foundation layer defines **canonical behavior** and is **immutable**.
-There is exactly **one Foundation component per category**.
+Storybook is used as an internal visual contract and can be run locally.
 
-- Modal (Dialog)
-- Tabs
-- Select
-- ContextMenu
-- Toast
-- Button (**FINAL LOCK**)
+### Advanced Architecture
 
-All Foundation components:
+- **Architecture Context**: [docs/ARCHITECTURE_CONTEXT.md](docs/ARCHITECTURE_CONTEXT.md)
+- **Foundation Lock**: [docs/architecture/FOUNDATION_LOCK.md](docs/architecture/FOUNDATION_LOCK.md)
+- **Architecture Lock**: [docs/architecture/ARCHITECTURE_LOCK.md](docs/architecture/ARCHITECTURE_LOCK.md)
+- **A11Y Lock**: [docs/architecture/locks/A11Y_LOCK.md](docs/architecture/locks/A11Y_LOCK.md)
 
-- delegate behavior to Radix UI (or native HTML elements)
-- expose token-driven visual APIs
-- are backward-compatible and locked
+---
 
-### Extension Layer
+## 🏗 Architecture (High-level)
 
-Extensions compose Foundation components or implement primitives
-that rely strictly on tokens and shared semantics.
+TUI is built on a strict multi-layer architecture:
 
-Examples:
+- Foundation — locked tokens & primitives
+- Primitives — atomic UI building blocks
+- Composition — layout & interaction orchestration
+- Patterns — reusable UI patterns
+- Domain — product-specific components
 
-- Input / Textarea
-- Card / Badge
-- Layout primitives (Stack, Grid, Container)
-- Data and feedback components
+→ Full architecture: [docs/ARCHITECTURE_CONTEXT.md](docs/ARCHITECTURE_CONTEXT.md)
 
 ---
 
@@ -199,45 +169,17 @@ Tokens are **immutable contracts**, not convenience variables.
 
 ---
 
-## 🎨 Theme Tooling
-
-TUI provides **build-time CLI tooling** for generating and validating themes.
-
-**Theme Tooling is a build-time compiler, not a runtime system.**
-
-- **Theme Generator** (`pnpm theme:generate`) — creates Theme Contract v1 compliant themes
-- **Theme Validator** (`pnpm theme:validate`) — validates themes against contract
-- **Parity Checker** (`pnpm theme:parity-check`) — ensures token consistency
-
-**Key Points:**
-
-- Themes are generated at **build time**, not runtime
-- All themes live in `src/EXTENSIONS/themes/` (canonical path)
-- Validation is **mandatory** — invalid themes cannot be committed (CI enforced)
-- UI library **never generates themes** — it only consumes pre-generated CSS
-
-**Quick Start:**
-
-```bash
-# Generate a theme
-pnpm theme:generate -- --palette my-brand --base-color "210 40% 50%" --modes light,dark
-
-# Validate themes
-pnpm theme:validate -- src/EXTENSIONS/themes/*.css
-```
+## 🎨 Theming
 
-**Documentation:**
-
-- [Theme System — Contract & Tooling](tools/theme-contract/README.md) - **Complete guide** (start here)
-- [Theme Generator](tools/theme-generator/README.md) - Generator documentation
-- [Theme Validator](tools/theme-validator/README.md) - Validator documentation
+TUI consumes pre-generated themes.
+Theme authoring and validation tooling is documented separately: [tools/theme-contract/README.md](tools/theme-contract/README.md).
 
 ---
 
-## 🧩 Domain-Specific Components
+## 🧩 Product-Specific Extensions
 
-The following components are **used internally** in Tenerife Music projects
-and are **not generic UI primitives**:
+The following components exist as product-level extensions
+and are not intended as generic UI primitives:
 
 - EventCard
 - VenueCard
@@ -245,8 +187,9 @@ and are **not generic UI primitives**:
 - TicketCard
 - PromoCard
 
-> These components are tightly coupled to specific product domains
-> and are documented for reference, not as reusable primitives.
+> These components are tightly coupled to specific product domains,
+> are not part of the public API, and are documented for reference only.
+> Use `Card`, `Grid`, and other public components to build custom layouts.
 
 ---
 
@@ -278,29 +221,7 @@ npm view @tenerife.music/ui versions --json
 
 See [CHANGELOG Version Canon Rules](CHANGELOG.md#version-canon-rules) and [Release Process](docs/RELEASE_PROCESS.md) for details.
 
-### Creating New Components
-
-To create a new Extension component:
-
-1. **Check Component Needs**: Review [Component Needs Inventory](docs/tasks/COMPONENT_NEEDS_INVENTORY.md) to ensure the component is needed
-2. **Use Template Generator**: Run `tsx scripts/generate-extension-component.ts <ComponentName> --category <category>`
-3. **Follow Checklist**: Complete all items in [Extension Component Creation Checklist](docs/tasks/EXTENSION_COMPONENT_CREATION_CHECKLIST.md)
-4. **Reference Examples**: Use [Extension Component Examples](docs/reference/EXTENSION_COMPONENT_EXAMPLES.md) as patterns
-
-### Requesting Components
-
-To request a new component:
-
-1. **Create GitHub Issue**: Use the [Component Request template](.github/ISSUE_TEMPLATE/component-request.md)
-2. **Provide Use Case**: Describe the specific use case and frequency of need
-3. **Document Workaround**: Explain current solution and pain points
-4. **Wait for Review**: Requests are reviewed monthly (see [Feedback Review Process](docs/tasks/FEEDBACK_REVIEW_PROCESS.md))
-
-### Development Tools
-
-- **Component Analysis**: `tsx scripts/analyze-component-needs.ts` - Analyzes codebase for component patterns
-- **Feedback Collection**: `tsx scripts/collect-usage-feedback.ts` - Collects and analyzes usage feedback
-- **Component Generator**: `tsx scripts/generate-extension-component.ts <Name> --category <category>` - Generates component scaffold
+Contributing & internal workflows → see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 

package/dist/extensions/next/index.cjs

@@ -1,9 +1,11 @@
 'use strict';
 
 var NextLink = require('next/link');
-var React = require('react');
-var classVarianceAuthority = require('class-variance-authority');
+var React2 = require('react');
+var clsx = require('clsx');
+var tailwindMerge = require('tailwind-merge');
 var jsxRuntime = require('react/jsx-runtime');
+var classVarianceAuthority = require('class-variance-authority');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -26,9 +28,182 @@ function _interopNamespace(e) {
 }
 
 var NextLink__default = /*#__PURE__*/_interopDefault(NextLink);
-var React__namespace = /*#__PURE__*/_interopNamespace(React);
+var React2__namespace = /*#__PURE__*/_interopNamespace(React2);
 
 // src/EXTENSIONS/next/NextLinkAdapter.tsx
+
+// src/FOUNDATION/lib/responsive-props.ts
+function isResponsiveValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getBaseValue(value) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (isResponsiveValue(value)) {
+    return value.base;
+  }
+  return value;
+}
+function getSpacingCSSVar(key) {
+  if (key === "none") {
+    return `var(--spacing-none)`;
+  }
+  if (key.includes("-") && !key.startsWith("--")) {
+    const parts = key.split("-");
+    if (parts.length >= 2) {
+      const type = parts[0];
+      const size = parts.slice(1).join("-");
+      if (type && ["section", "container", "grid", "stack", "component"].includes(type)) {
+        return `var(--layout-${type}-${size})`;
+      }
+    }
+  }
+  if (key.includes(".")) {
+    const normalizedKey = key.replace(".", "-");
+    return `var(--spacing-${normalizedKey})`;
+  }
+  return `var(--spacing-${key})`;
+}
+function getRadiusCSSVar(key) {
+  return `var(--radius-${key})`;
+}
+function getColorCSSVar(key) {
+  if (key.startsWith("hsl(")) {
+    return key;
+  }
+  if (key.startsWith("var(")) {
+    return key;
+  }
+  const legacyMap = {
+    background: "--tm-surface-base",
+    foreground: "--tm-text-primary",
+    card: "--tm-surface-raised",
+    "card-foreground": "--tm-text-primary",
+    popover: "--tm-surface-overlay",
+    "popover-foreground": "--tm-text-primary",
+    muted: "--tm-muted",
+    "muted-foreground": "--tm-muted-foreground",
+    destructive: "--tm-destructive",
+    "destructive-foreground": "--tm-destructive-foreground",
+    border: "--tm-border-default",
+    ring: "--tm-focus-ring",
+    input: "--tm-border-default",
+    primary: "--tm-primary",
+    "primary-foreground": "--tm-primary-foreground",
+    secondary: "--tm-secondary",
+    "secondary-foreground": "--tm-secondary-foreground",
+    accent: "--tm-accent",
+    "accent-foreground": "--tm-accent-foreground",
+    disabled: "--tm-disabled",
+    "disabled-foreground": "--tm-disabled-foreground",
+    success: "--tm-status-success",
+    "success-foreground": "--tm-status-success-foreground",
+    error: "--tm-status-error",
+    "error-foreground": "--tm-status-error-foreground",
+    warning: "--tm-status-warning",
+    "warning-foreground": "--tm-status-warning-foreground",
+    info: "--tm-status-info",
+    "info-foreground": "--tm-status-info-foreground"
+  };
+  const mapped = legacyMap[key];
+  if (mapped) {
+    return `var(${mapped})`;
+  }
+  if (key.startsWith("surface-")) {
+    const suffix = key.replace("surface-", "");
+    if (suffix === "base") return "var(--tm-surface-base)";
+    if (suffix === "overlay" || suffix === "glass") return "var(--tm-surface-overlay)";
+    if (suffix.startsWith("elevated") || suffix === "raised") return "var(--tm-surface-raised)";
+  }
+  if (key.startsWith("text-")) {
+    const suffix = key.replace("text-", "");
+    if (suffix === "primary") return "var(--tm-text-primary)";
+    if (suffix === "secondary") return "var(--tm-text-secondary)";
+    if (suffix === "muted" || suffix === "tertiary") return "var(--tm-text-muted)";
+    if (suffix === "inverse") return "var(--tm-text-inverse)";
+  }
+  return `var(--${key})`;
+}
+function cn(...inputs) {
+  return tailwindMerge.twMerge(clsx.clsx(inputs));
+}
+function getBaseValue2(value) {
+  return getBaseValue(value);
+}
+function shadowToClass(value) {
+  if (!value || value === "none") return void 0;
+  return `shadow-${value}`;
+}
+var BoxComponent = React2__namespace.forwardRef(
+  ({
+    as: Component = "div",
+    px,
+    py,
+    m,
+    mx,
+    my,
+    mt,
+    mr,
+    mb,
+    ml,
+    radius,
+    shadow,
+    bg,
+    className,
+    style,
+    ...props
+  }, ref) => {
+    const pxValue = getBaseValue2(px);
+    const pyValue = getBaseValue2(py);
+    const mValue = getBaseValue2(m);
+    const mxValue = getBaseValue2(mx);
+    const myValue = getBaseValue2(my);
+    const mtValue = getBaseValue2(mt);
+    const mrValue = getBaseValue2(mr);
+    const mbValue = getBaseValue2(mb);
+    const mlValue = getBaseValue2(ml);
+    const radiusValue = getBaseValue2(radius);
+    const bgValue = getBaseValue2(bg);
+    const inlineStyles = {
+      ...pxValue !== void 0 && {
+        paddingLeft: getSpacingCSSVar(String(pxValue)),
+        paddingRight: getSpacingCSSVar(String(pxValue))
+      },
+      ...pyValue !== void 0 && {
+        paddingTop: getSpacingCSSVar(String(pyValue)),
+        paddingBottom: getSpacingCSSVar(String(pyValue))
+      },
+      ...mValue !== void 0 && { margin: getSpacingCSSVar(String(mValue)) },
+      ...!m && mxValue !== void 0 && {
+        marginLeft: getSpacingCSSVar(String(mxValue)),
+        marginRight: getSpacingCSSVar(String(mxValue))
+      },
+      ...!m && myValue !== void 0 && {
+        marginTop: getSpacingCSSVar(String(myValue)),
+        marginBottom: getSpacingCSSVar(String(myValue))
+      },
+      ...!m && !my && mtValue !== void 0 && { marginTop: getSpacingCSSVar(String(mtValue)) },
+      ...!m && !mx && mrValue !== void 0 && { marginRight: getSpacingCSSVar(String(mrValue)) },
+      ...!m && !my && mbValue !== void 0 && { marginBottom: getSpacingCSSVar(String(mbValue)) },
+      ...!m && !mx && mlValue !== void 0 && { marginLeft: getSpacingCSSVar(String(mlValue)) },
+      ...radiusValue !== void 0 && { borderRadius: getRadiusCSSVar(radiusValue) },
+      ...bgValue !== void 0 && { backgroundColor: getColorCSSVar(bgValue) },
+      ...style
+    };
+    const classes = cn(
+      // Shadow
+      shadowToClass(shadow),
+      className
+    );
+    const ComponentAny = Component;
+    const finalStyle = Object.keys(inlineStyles).length > 0 || style ? { ...inlineStyles, ...style } : void 0;
+    return /* @__PURE__ */ jsxRuntime.jsx(ComponentAny, { ref, className: classes, style: finalStyle, ...props });
+  }
+);
+BoxComponent.displayName = "Box";
+var Box = BoxComponent;
+Box.displayName = "Box";
 var FORBIDDEN_SPACING_PATTERNS = [
   // Raw color utilities (bg-red-500, text-blue-600, etc.)
   // These are always forbidden as they bypass the color token system
@@ -505,9 +680,9 @@ var linkVariants = tokenCVA({
     size: "md"
   }
 });
-var Link = React__namespace.forwardRef(
+var Link = React2__namespace.forwardRef(
   ({ variant, size, leftIcon, rightIcon, children, disabled, onClick, href, tabIndex, ...props }, ref) => {
-    const handleClick = React__namespace.useCallback(
+    const handleClick = React2__namespace.useCallback(
       (e) => {
         if (disabled) {
           e.preventDefault();
@@ -541,9 +716,142 @@ var Link = React__namespace.forwardRef(
   }
 );
 Link.displayName = "Link";
-var NextLinkAdapter = React__namespace.forwardRef(
-  ({ href, prefetch, replace, scroll, shallow, locale, ...props }, ref) => {
+
+// src/FOUNDATION/tokens/components/text.ts
+var TEXT_TOKENS = {
+  /**
+   * Font sizes by text size variant
+   * Maps to foundation fontSize tokens
+   */
+  fontSize: {
+    xs: "text-xs",
+    // Maps to fontSize.xs[0]
+    sm: "text-sm",
+    // Maps to fontSize.sm[0]
+    md: "text-base",
+    // Maps to fontSize.base[0]
+    lg: "text-lg",
+    // Maps to fontSize.lg[0]
+    xl: "text-xl"},
+  /**
+   * Font weights by weight variant
+   * Maps to foundation fontWeight tokens
+   */
+  fontWeight: {
+    normal: "font-normal",
+    // Maps to fontWeight.normal (400)
+    medium: "font-medium",
+    // Maps to fontWeight.medium (500)
+    semibold: "font-semibold",
+    // Maps to fontWeight.semibold (600)
+    bold: "font-bold"
+    // Maps to fontWeight.bold (700)
+  }};
+var TEXT_COLOR_CLASSES = {
+  primary: "text-[hsl(var(--tm-text-primary))]",
+  secondary: "text-[hsl(var(--tm-text-secondary))]",
+  tertiary: "text-[hsl(var(--tm-text-muted))]",
+  muted: "text-[hsl(var(--tm-text-muted))]",
+  inverse: "text-[hsl(var(--tm-text-inverse))]",
+  disabled: "text-[hsl(var(--tm-disabled-foreground))]",
+  success: "text-[hsl(var(--tm-status-success))]",
+  warning: "text-[hsl(var(--tm-status-warning))]",
+  error: "text-[hsl(var(--tm-status-error))]",
+  info: "text-[hsl(var(--tm-status-info))]"
+};
+var DEFAULT_SIZE = "md";
+var DEFAULT_WEIGHT = "normal";
+var textVariants = tokenCVA({
+  base: "text-[hsl(var(--tm-text-primary))]",
+  variants: {
+    size: {
+      xs: TEXT_TOKENS.fontSize.xs,
+      sm: TEXT_TOKENS.fontSize.sm,
+      md: TEXT_TOKENS.fontSize.md,
+      lg: TEXT_TOKENS.fontSize.lg,
+      xl: TEXT_TOKENS.fontSize.xl
+    },
+    weight: {
+      normal: TEXT_TOKENS.fontWeight.normal,
+      medium: TEXT_TOKENS.fontWeight.medium,
+      semibold: TEXT_TOKENS.fontWeight.semibold,
+      bold: TEXT_TOKENS.fontWeight.bold
+    },
+    // Role-based color variant (enforced via TypeScript generic)
+    color: {
+      primary: TEXT_COLOR_CLASSES.primary,
+      secondary: TEXT_COLOR_CLASSES.secondary,
+      tertiary: TEXT_COLOR_CLASSES.tertiary,
+      muted: TEXT_COLOR_CLASSES.muted,
+      inverse: TEXT_COLOR_CLASSES.inverse,
+      disabled: TEXT_COLOR_CLASSES.disabled,
+      success: TEXT_COLOR_CLASSES.success,
+      warning: TEXT_COLOR_CLASSES.warning,
+      error: TEXT_COLOR_CLASSES.error,
+      info: TEXT_COLOR_CLASSES.info
+    }
+  },
+  defaultVariants: {
+    size: DEFAULT_SIZE,
+    weight: DEFAULT_WEIGHT
+  }
+});
+var TextComponent = React2__namespace.forwardRef(
+  ({ as = "span", size, weight, typographyRole: _typographyRole, color, ...props }, ref) => {
+    const Component = as;
+    const colorVariant = color ? { color } : void 0;
+    const className = textVariants({ size, weight, ...colorVariant });
+    return /* @__PURE__ */ jsxRuntime.jsx(Component, { ref, className, ...props });
+  }
+);
+TextComponent.displayName = "Text";
+var Text = TextComponent;
+var NextLinkAdapter = React2__namespace.forwardRef(
+  ({
+    href,
+    prefetch,
+    replace,
+    scroll,
+    shallow,
+    locale,
+    variant,
+    size,
+    leftIcon,
+    rightIcon,
+    disabled,
+    onClick,
+    target,
+    rel,
+    download,
+    tabIndex,
+    title,
+    role,
+    onFocus,
+    onBlur,
+    onMouseEnter,
+    onMouseLeave,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+    "aria-current": ariaCurrent,
+    "aria-disabled": ariaDisabled,
+    children
+  }, ref) => {
     const hrefString = typeof href === "string" ? href : href.pathname || String(href);
+    const finalAriaDisabled = disabled ? true : ariaDisabled;
+    const finalTabIndex = disabled ? tabIndex ?? -1 : tabIndex;
+    const className = linkVariants({ variant, size });
+    const handleClick = React2__namespace.useCallback(
+      (e) => {
+        if (disabled) {
+          e.preventDefault();
+          e.stopPropagation();
+          return;
+        }
+        onClick?.(e);
+      },
+      [disabled, onClick]
+    );
     return /* @__PURE__ */ jsxRuntime.jsx(
       NextLink__default.default,
       {
@@ -553,7 +861,36 @@ var NextLinkAdapter = React__namespace.forwardRef(
         scroll,
         shallow,
         locale,
-        children: /* @__PURE__ */ jsxRuntime.jsx(Link, { ref, href: hrefString, ...props })
+        children: /* @__PURE__ */ jsxRuntime.jsxs(
+          Box,
+          {
+            as: "a",
+            ref,
+            className,
+            href: hrefString,
+            target,
+            rel,
+            download,
+            tabIndex: finalTabIndex,
+            title,
+            role,
+            onClick: handleClick,
+            onFocus,
+            onBlur,
+            onMouseEnter,
+            onMouseLeave,
+            "aria-label": ariaLabel,
+            "aria-labelledby": ariaLabelledBy,
+            "aria-describedby": ariaDescribedBy,
+            "aria-current": ariaCurrent,
+            "aria-disabled": finalAriaDisabled,
+            children: [
+              leftIcon && /* @__PURE__ */ jsxRuntime.jsx("span", { className: LINK_TOKENS.iconWrapper, children: leftIcon }),
+              /* @__PURE__ */ jsxRuntime.jsx(Text, { as: "span", typographyRole: "link", size, children }),
+              rightIcon && /* @__PURE__ */ jsxRuntime.jsx("span", { className: LINK_TOKENS.iconWrapper, children: rightIcon })
+            ]
+          }
+        )
       }
     );
   }

package/dist/extensions/next/index.d.cts

@@ -20,8 +20,8 @@ interface NextLinkAdapterProps extends Omit<LinkProps, "href"> {
 /**
  * NextLinkAdapter
  *
- * A compatibility adapter that bridges Next.js `next/link` with TenerifeUI `Link`.
- * This adapter allows Foundation Link (which is an <a>) to function as the child of NextLink.
+ * A compatibility adapter that bridges Next.js `next/link` with TenerifeUI link tokens.
+ * This adapter renders a single <a> element as the child of NextLink.
  * Next.js 13+ automatically handles <a> children without creating nested anchors.
  *
  * @example

package/dist/extensions/next/index.d.ts

@@ -20,8 +20,8 @@ interface NextLinkAdapterProps extends Omit<LinkProps, "href"> {
 /**
  * NextLinkAdapter
  *
- * A compatibility adapter that bridges Next.js `next/link` with TenerifeUI `Link`.
- * This adapter allows Foundation Link (which is an <a>) to function as the child of NextLink.
+ * A compatibility adapter that bridges Next.js `next/link` with TenerifeUI link tokens.
+ * This adapter renders a single <a> element as the child of NextLink.
  * Next.js 13+ automatically handles <a> children without creating nested anchors.
  *
  * @example