@tenerife.music/ui 2.1.0 → 2.3.0

package/README.md

@@ -3,18 +3,18 @@
 **Token-driven UI architecture for long-living React products**
 Strict. 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.0-blue?style=for-the-badge)
+![npm version](https://img.shields.io/badge/npm-v2.3.0-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.0](CHANGELOG.md#230) (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">
@@ -102,6 +102,12 @@ export default function App() {
 > 📖 **Note:** This example demonstrates API shape only. Understanding the system
 > requires familiarity with tokens, variants, and architectural constraints.
 
+### Fonts (Optional)
+
+TUI ships with **system font fallbacks** by default. We do **not** bundle or require fonts.
+If you want canonical visuals, you can load Inter / Clash Display / Satoshi in your app,
+but this is optional.
+
 ---
 
 ## ✨ Key Characteristics
@@ -119,22 +125,25 @@ export default function App() {
 
 ## 📚 Documentation
 
-| Document                  | Description                             |
-| ------------------------- | --------------------------------------- |
-| **Complete Guide**        | System overview and usage principles    |
-| Tokens Guide              | Design token structure and philosophy   |
-| Theme Guide               | Theme configuration and modes           |
-| **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        |
+| Document                 | Description                             | Link                                                                                   |
+| ------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------- |
+| **Architecture Context** | Single source of truth (IMMUTABLE)      | [docs/ARCHITECTURE_CONTEXT.md](docs/ARCHITECTURE_CONTEXT.md)                           |
+| **Foundation Lock**      | Authoritative source of truth           | [docs/architecture/FOUNDATION_LOCK.md](docs/architecture/FOUNDATION_LOCK.md)           |
+| **Architecture Lock**    | Canonical architectural constraints     | [docs/architecture/ARCHITECTURE_LOCK.md](docs/architecture/ARCHITECTURE_LOCK.md)       |
+| **A11Y Lock**            | Accessibility system lock (WCAG 2.1 AA) | [docs/architecture/locks/A11Y_LOCK.md](docs/architecture/locks/A11Y_LOCK.md)           |
+| **Tokens Overview**      | Design token structure and philosophy   | [docs/reference/TOKENS_OVERVIEW.md](docs/reference/TOKENS_OVERVIEW.md)                 |
+| **Theme System**         | Theme architecture and tooling          | [docs/theming/THEME_SYSTEM_ARCHITECTURE.md](docs/theming/THEME_SYSTEM_ARCHITECTURE.md) |
+| **API Reference**        | Public API documentation                | [docs/reference/API_REFERENCE.md](docs/reference/API_REFERENCE.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)                                                       |
+| Storybook                | Component examples and contracts        | Run `pnpm storybook` locally                                                           |
 
 ### 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
+  - **CLI Generator**: Use `pnpm 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)
+- **Component Refactoring**: [Component Refactoring Pipeline (18A)](docs/workflows/foundation/FOUNDATION_STEP_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
@@ -146,35 +155,69 @@ export default function App() {
 
 ## 🏗 Architecture Overview
 
-### Foundation Layer (Locked)
+TenerifeUI uses a **5-layer architecture** with strict boundaries:
+
+### Foundation Layer (Locked & Closed)
+
+**Status:** ✅ **LOCKED** (Foundation Closed - 2026-01-02)  
+**Purpose:** Tokens and theme system only
+
+The Foundation layer is **immutable** and **closed**. All Foundation Authority Contracts are **LOCKED**.
+
+**Reference:** [FOUNDATION_LOCK.md](docs/architecture/FOUNDATION_LOCK.md)
+
+### Primitives Layer (Locked)
+
+**Status:** ✅ **CANONICAL**  
+**Purpose:** Atomic UI components, no orchestration
+
+**Location:** `src/PRIMITIVES/`
+
+**Examples:**
+
+- Button, Input, Textarea, Checkbox, Radio, Switch
+- Badge, Alert, Heading, Text, Icon, Image
+- Progress, Skeleton, Divider, Field, Label, Link
+
+**Rule:** PRIMITIVES **MUST NOT** contain orchestration logic or overlay infrastructure.
+
+### Composition Layer (Canonical)
+
+**Status:** ✅ **CANONICAL**  
+**Purpose:** Layout, overlays, interaction orchestration
+
+**Location:** `src/COMPOSITION/`
+
+**Sub-layers:**
+
+- `COMPOSITION/overlays/` - All overlay components (Modal, Popover, ContextMenu, Toast, Dialog, Tooltip)
+- `COMPOSITION/layout/` - Layout components (Card, Flex, Grid, Stack, Container, Section)
+- `COMPOSITION/navigation/` - Navigation components (Tabs, Breadcrumbs, Pagination)
+- `COMPOSITION/controls/` - Control components (Select)
+
+**Rule:** All overlays **MUST** live in COMPOSITION layer only.
+
+### Patterns Layer (Canonical)
+
+**Status:** ✅ **CANONICAL**  
+**Purpose:** Business/UI patterns (no overlays)
 
-The Foundation layer defines **canonical behavior** and is **immutable**.
-There is exactly **one Foundation component per category**.
+**Location:** `src/PATTERNS/`
 
-- Modal (Dialog)
-- Tabs
-- Select
-- ContextMenu
-- Toast
-- Button (**FINAL LOCK**)
+**Examples:**
 
-All Foundation components:
+- Cards, Lists, Tables, Filters, Menus, States
 
-- delegate behavior to Radix UI (or native HTML elements)
-- expose token-driven visual APIs
-- are backward-compatible and locked
+**Rule:** PATTERNS **MUST NOT** define overlay primitives or overlay infrastructure.
 
-### Extension Layer
+### Domain Layer (Canonical)
 
-Extensions compose Foundation components or implement primitives
-that rely strictly on tokens and shared semantics.
+**Status:** ✅ **CANONICAL**  
+**Purpose:** App-specific sections
 
-Examples:
+**Location:** `src/DOMAIN/`
 
-- Input / Textarea
-- Card / Badge
-- Layout primitives (Stack, Grid, Container)
-- Data and feedback components
+**Reference:** [ARCHITECTURE_STATE.md](docs/architecture/ARCHITECTURE_STATE.md) for complete layer definitions
 
 ---
 
@@ -205,7 +248,7 @@ TUI provides **build-time CLI tooling** for generating and validating themes.
 **Key Points:**
 
 - Themes are generated at **build time**, not runtime
-- All themes live in `src/EXTENSIONS/themes/` (canonical path)
+- All themes live in `src/themes/` (canonical path)
 - Validation is **mandatory** — invalid themes cannot be committed (CI enforced)
 - UI library **never generates themes** — it only consumes pre-generated CSS
 
@@ -216,7 +259,7 @@ TUI provides **build-time CLI tooling** for generating and validating themes.
 pnpm theme:generate -- --palette my-brand --base-color "210 40% 50%" --modes light,dark
 
 # Validate themes
-pnpm theme:validate -- src/EXTENSIONS/themes/*.css
+pnpm theme:validate -- src/themes/*.css
 ```
 
 **Documentation:**
@@ -275,25 +318,25 @@ See [CHANGELOG Version Canon Rules](CHANGELOG.md#version-canon-rules) and [Relea
 
 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)
+1. **Check Component Needs**: Review [Component Needs Inventory](docs/workflows/tasks/COMPONENT_NEEDS_INVENTORY.md) to ensure the component is needed
+2. **Use CLI Generator**: Run `pnpm component:generate -- <ComponentName> [--category <category>]`
+3. **Follow Checklist**: Complete all items in [Extension Component Creation Checklist](docs/workflows/tasks/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)
+1. **Create GitHub Issue**: Use the [Component Request template](.github/ISSUE_TEMPLATE/component-request.md) (if available)
 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))
+4. **Wait for Review**: Requests are reviewed according to project governance (see [Feedback Collection Process](docs/workflows/tasks/FEEDBACK_COLLECTION_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
+- **Component Analysis**: `pnpm component:analyze` - Analyzes codebase for component patterns
+- **Feedback Collection**: `pnpm feedback:collect` - Collects and analyzes usage feedback
+- **Component Generator**: `pnpm component:generate -- <Name> [--category <category>]` - Generates component scaffold
 
 ---
 

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