### Generic Marketplace Component Installation

Source: https://github.com/vercel/components.build/blob/main/skills/building-components/references/marketplaces.mdx

A generic example of installing a component from a marketplace using a placeholder for the author and component name.

```bash
npx shadcn@latest add https://21st.dev/r/<author>/<component>
```

--------------------------------

### Install Component from Marketplace

Source: https://github.com/vercel/components.build/blob/main/skills/building-components/references/marketplaces.mdx

Install a component from a marketplace using the provided CLI command. This example shows how to add a dialog-stack component from 21st.dev.

```bash
npx shadcn@latest add https://21st.dev/r/haydenbleasel/dialog-stack
```

--------------------------------

### Install Component from Marketplace

Source: https://github.com/vercel/components.build/blob/main/content/docs/docs.mdx

Use the marketplace's CLI to install a component.

```bash
npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>
```

--------------------------------

### Install Component with shadcn CLI

Source: https://github.com/vercel/components.build/blob/main/content/docs/docs.mdx

Use the shadcn CLI to install a component from a registry.

```bash
npx shadcn@latest add <your-component-url>
```

--------------------------------

### Install Component with npm

Source: https://github.com/vercel/components.build/blob/main/content/docs/docs.mdx

Use the npm CLI to install a component published to npm.

```bash
npm install <your-component-name>
```

--------------------------------

### Install NPM Package

Source: https://github.com/vercel/components.build/blob/main/content/docs/npm.mdx

Install your component library as a dependency using npm.

```bash
npm install @acme/ui-components
```

--------------------------------

### Install Component with Custom Registry CLI

Source: https://github.com/vercel/components.build/blob/main/content/docs/docs.mdx

Use a custom registry CLI to install a component.

```bash
npx your-registry-cli@latest add <your-component-url>
```

--------------------------------

### Install Component from Registry URL

Source: https://github.com/vercel/components.build/blob/main/content/docs/registry.mdx

Install a component directly from its registry URL using the shadcn CLI. This bypasses the need for npm packages or build steps.

```bash
npx shadcn@latest add https://your-project-name.vercel.app/metric-card.json
```

--------------------------------

### Install Radix UI Slot Package

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Command to install the Radix UI `react-slot` package, which provides the `Slot` component for advanced composition.

```bash
npm install @radix-ui/react-slot
```

--------------------------------

### Registry Component Metadata Example

Source: https://github.com/vercel/components.build/blob/main/content/docs/registry.mdx

Shows the structure of metadata for a registry component, including name, type, description, dependencies, and files.

```json
{
  "name": "announcement",
  "type": "registry:component",
  "description": "A compound badge component designed to display announcements with theming support",
  "dependencies": ["class-variance-authority", "lucide-react"],
  "registryDependencies": ["badge"],
  "files": [
    {
      "type": "registry:component",
      "content": "..."
    }
  ],
  "category": "ui"
}
```

--------------------------------

### Install use-controllable-state Hook

Source: https://github.com/vercel/components.build/blob/main/content/docs/state.mdx

This command installs the @radix-ui/react-use-controllable-state package, which provides a utility for merging controllable and uncontrolled state patterns.

```bash
npm install @radix-ui/react-use-controllable-state
```

--------------------------------

### Basic Accordion Usage

Source: https://github.com/vercel/components.build/blob/main/content/docs/composition.mdx

Demonstrates how to use a pre-built Accordion component with sample data. This example shows a simple integration point for the Accordion component.

```tsx
import { Accordion } from "@/components/ui/accordion";

const data = [
  {
    title: "Accordion 1",
    content: "Accordion 1 content",
  },
  {
    title: "Accordion 2",
    content: "Accordion 2 content",
  },
  {
    title: "Accordion 3",
    content: "Accordion 3 content",
  },
];

return <Accordion data={data} />;
```

--------------------------------

### Polymorphic Button Examples

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Demonstrates how the `as` prop can change the rendered HTML element of a Button component while maintaining its functionality.

```tsx
<Button as="a" href="/home">
  Go Home
</Button>

<Button as="button" type="submit">
  Submit Form
</Button>

<Button as="div" role="button" tabIndex={0}>
  Custom Element
</Button>
```

--------------------------------

### Button Usage Examples

Source: https://github.com/vercel/components.build/blob/main/skills/building-components/references/data-attributes.mdx

Demonstrates various ways to use the `Button` component, including basic usage with variants, parent targeting via `data-slot`, and state-based styling using `data-state` attributes.

```tsx
// Basic usage with variants
<Button variant="primary" size="lg">Submit</Button>
```

```tsx
// Parent targeting via data-slot
<form className="[&_[data-slot=button]]:w-full">
  <Button>Submit</Button>
</form>
```

```tsx
// State-based styling via data-state
<Button
  loading={isLoading}
  className="data-[loading=true]:opacity-50"
>
  Submit
</Button>
```

--------------------------------

### Define Button Variants with CVA

Source: https://github.com/vercel/components.build/blob/main/content/docs/styling.jp.mdx

Use CVA to declaratively define styles for different button variants and sizes. This example shows a typical setup for a reusable button component.

```tsx
const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive:
          "bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
        outline:
          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-9 px-4 py-2 has-[>svg]:px-3",
        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
        icon: "size-9",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)
```

--------------------------------

### Exporting and Using Component Prop Types

Source: https://github.com/vercel/components.build/blob/main/skills/building-components/references/types.mdx

This example illustrates exporting component prop types and demonstrates common use cases like extracting specific types, extending components, and type-safe prop forwarding.

```tsx
// 1. Extracting specific prop types
import type { CardRootProps } from "@/components/ui/card";
type variant = CardRootProps["variant"];

// 2. Extending components
export type ExtendedCardProps = CardRootProps & {
  isLoading?: boolean;
};

// 3. Creating wrapper components
const MyCard = (props: CardRootProps) => (
  <CardRoot {...props} className={cn("my-custom-class", props.className)} />
);

// 4. Type-safe prop forwarding
function useCardProps(): Partial<CardRootProps> {
  return {
    variant: "outlined",
    className: "custom-card",
  };
}
```

--------------------------------

### Applying Styles in Order of Precedence

Source: https://github.com/vercel/components.build/blob/main/content/docs/styling.cn.mdx

This example illustrates the recommended order for applying CSS classes to ensure predictable styling: base styles, variant styles, conditional styles, and finally user overrides.

```tsx
className={cn(
  'base-styles',            // 1. Base
  variant && variantStyles, // 2. Variants
  isActive && 'active',     // 3. Conditionals
  className                 // 4. User overrides
)}
```

--------------------------------

### Component with Default and Conditional Classes

Source: https://github.com/vercel/components.build/blob/main/content/docs/styling.cn.mdx

This example demonstrates a common pattern of merging default component styles with conditional classes and user-provided overrides using a utility function.

```tsx
import { useState } from 'react';
import { cn } from '@/lib/utils'; // Assuming cn is imported from a utility file

const Component = ({ className, ...props }: ComponentProps) => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div
      className={cn(
        "rounded-lg border bg-white shadow-sm",
        isOpen && "bg-blue-500",
        className
      )}
      {...props}
    />
  );
};

```

--------------------------------

### Radix UI `Slot` Component Implementation

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Example implementation of a component using Radix UI's `Slot` with `asChild` prop for prop merging and composition.

```tsx
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";

const itemVariants = cva("rounded-lg border p-4", {
  variants: {
    variant: {
      default: "bg-white",
      primary: "bg-blue-500 text-white",
    },
    size: {
      default: "h-10 px-4",
      sm: "h-8 px-3",
      lg: "h-12 px-6",
    },
  },
  defaultVariants: {
    variant: "default",
    size: "default",
  },
});

function Item({
  className,
  variant = "default",
  size = "default",
  asChild = false,
  ...props
}: React.ComponentProps<"div"> &
  VariantProps<typeof itemVariants> & { asChild?: boolean }) {
  const Comp = asChild ? Slot : "div";
  return (
    <Comp
      data-slot="item"
      data-variant={variant}
      data-size={size}
      className={cn(itemVariants({ variant, size, className }))}
      {...props}
    />
  );
}
```

--------------------------------

### Document Supported HTML Elements

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Clearly document the range of supported HTML elements for the `as` prop using JSDoc comments, including default values and examples.

```typescript
interface BoxProps {
  /**
   * The HTML element to render as
   * @default 'div'
   * @example 'section', 'article', 'aside', 'main'
   */
  as?: "div" | "section" | "article" | "aside" | "main" | "header" | "footer";
}
```

--------------------------------

### Import Component from NPM Package

Source: https://github.com/vercel/components.build/blob/main/content/docs/npm.mdx

Import and use components from your installed npm package in your application.

```tsx
import { Button } from "@acme/ui-components";

// Component is imported from node_modules
// Source code is not directly editable
```

--------------------------------

### Card Informational Components Example

Source: https://github.com/vercel/components.build/blob/main/content/docs/composition.mdx

Utilize Title and Description components to display primary headings and supporting text within cards. These components help convey information clearly and concisely.

```tsx
<CardTitle>Project Statistics</CardTitle>
<CardDescription>
  View your project's performance over time
</CardDescription>
```

--------------------------------

### Handling Different Element Types with Discriminated Unions

Source: https://github.com/vercel/components.build/blob/main/skills/building-components/references/types.mdx

This example shows how to define props for a button component that can render as a native button or a div using discriminated unions.

```tsx
export type ButtonProps =
  | (React.ComponentProps<"button"> & { asChild?: false })
  | (React.ComponentProps<"div"> & { asChild: true });

// Or with a polymorphic approach
export type PolymorphicProps<T extends React.ElementType> = {
  as?: T;
} & React.ComponentPropsWithoutRef<T>;
```

--------------------------------

### Data Slot Naming Convention Examples

Source: https://github.com/vercel/components.build/blob/main/content/docs/data-attributes.cn.mdx

Follow kebab-case, be specific, match component purpose, and avoid implementation details when naming `data-slot` attributes for consistency.

```tsx
// Good examples
data-slot="search-input"
data-slot="navigation-menu"
data-slot="error-message"
data-slot="submit-button"
data-slot="card-header"

// Avoid
data-slot="input"           // Too generic
data-slot="blueButton"      // Includes styling
data-slot="div-wrapper"     // Implementation detail
data-slot="mainContent"     // Use camelCase
```

--------------------------------

### Render Prop (Function-as-Child) Example

Source: https://github.com/vercel/components.build/blob/main/content/docs/definitions.mdx

Use when the parent must own data/behavior but the consumer must fully control markup. The parent supplies state/data, and the consumer delegates rendering via a function child.

```tsx
<ParentComponent data={data}>
  {(item) => <ChildComponent key={item.id} {...item} />}
</ParentComponent>
```

--------------------------------

### Collapsible Interactive Elements Example

Source: https://github.com/vercel/components.build/blob/main/content/docs/composition.mdx

Use Trigger components to initiate actions like opening or closing content. The Content component holds the collapsible content itself. Ensure the Trigger is correctly associated with its Content.

```tsx
<CollapsibleTrigger>Click to expand</CollapsibleTrigger>
<CollapsibleContent>
  Hidden content revealed here
</CollapsibleContent>
```

--------------------------------

### Dialog Content Structure Example

Source: https://github.com/vercel/components.build/blob/main/content/docs/composition.mdx

Organize dialog content using Header, Body, and Footer components for clear structure. The Header typically contains titles, the Body holds the main content, and the Footer includes actions.

```tsx
<DialogHeader>
  {/* Dialog title */}
</DialogHeader>
<DialogBody>
  {/* Dialog content */}
</DialogBody>
<DialogFooter>
  {/* Dialog footer */}
</DialogFooter>
```

--------------------------------

### Accordion Root Component Example

Source: https://github.com/vercel/components.build/blob/main/content/docs/composition.mdx

The Root component acts as the main container for the Accordion, managing state and providing context to its children. It requires open and setOpen props for controlling its state.

```tsx
<AccordionRoot>{/* Child components */}</AccordionRoot>
```

--------------------------------

### Radix UI integration with data attributes

Source: https://github.com/vercel/components.build/blob/main/content/docs/data-attributes.mdx

Radix UI primitives automatically apply data attributes like `data-state` for styling. This example shows styling an overlay and content based on the dialog's open state.

```tsx
import * as Dialog from "@radix-ui/react-dialog";

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    {/* Radix automatically adds data-state="open" | "closed" */}
    <Dialog.Overlay className="data-[state=open]:animate-in data-[state=closed]:animate-out" />
    <Dialog.Content className="data-[state=open]:fade-in data-[state=closed]:fade-out" />
  </Dialog.Portal>
</Dialog.Root>
```

--------------------------------

### Deploy Project to Vercel

Source: https://github.com/vercel/components.build/blob/main/content/docs/registry.mdx

Deploy your component project to Vercel for static hosting. This command initiates the production deployment process.

```bash
vercel --prod
```

--------------------------------

### Component Import Comparison

Source: https://github.com/vercel/components.build/blob/main/content/docs/registry.mdx

Illustrates the difference between importing from a traditional npm package and a registry-based component.

```typescript
// Traditional npm package
import { Button } from "some-ui-library";

// Registry-based component
// Copy source from registry into your project
// src/components/ui/button.tsx contains the full source
import { Button } from "@/components/ui/button";
```

--------------------------------

### Custom Trigger Elements with asChild

Source: https://github.com/vercel/components.build/blob/main/content/docs/as-child.mdx

Provides examples of replacing default triggers with custom link elements or icon-only button components using `asChild`.

```tsx
// Custom link trigger
<Collapsible.Trigger asChild>
  <a href="#" className="text-blue-600 underline">
    Toggle Details
  </a>
</Collapsible.Trigger>

// Icon-only trigger
<Popover.Trigger asChild>
  <IconButton>
    <Settings className="h-4 w-4" />
  </IconButton>
</Popover.Trigger>
```

--------------------------------

### Simplified asChild Implementation

Source: https://github.com/vercel/components.build/blob/main/content/docs/as-child.mdx

Illustrates the core logic of the `asChild` prop, showing how it clones the child element and merges props and event handlers.

```tsx
// Simplified implementation
function Component({ asChild, children, ...props }) {
  if (asChild) {
    // Clone child and merge props
    return React.cloneElement(children, {
      ...props,
      ...children.props,
      // Merge event handlers
      onClick: (e) => {
        props.onClick?.(e);
        children.props.onClick?.(e);
      },
    });
  }

  // Render default element
  return <button {...props}>{children}</button>;
}
```

--------------------------------

### Accordion Component Implementation

Source: https://github.com/vercel/components.build/blob/main/content/docs/composition.mdx

Demonstrates how to use the Accordion component by mapping data to Accordion items, triggers, and content. Ensure Accordion root is properly configured with open and setOpen props.

```tsx
import * as Accordion from "@/components/ui/accordion";

const data = [
  {
    title: "Accordion 1",
    content: "Accordion 1 content",
  },
  {
    title: "Accordion 2",
    content: "Accordion 2 content",
  },
  {
    title: "Accordion 3",
    content: "Accordion 3 content",
  },
];

return (
  <Accordion.Root open={false} setOpen={() => {}}>
    {data.map((item) => (
      <Accordion.Item key={item.title}>
        <Accordion.Trigger>{item.title}</Accordion.Trigger>
        <Accordion.Content>{item.content}</Accordion.Content>
      </Accordion.Item>
    ))}
  </Accordion.Root>
);
```

--------------------------------

### Container Component with `as` Prop for Semantic HTML

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Illustrates using the `as` prop on a Container component to render different semantic HTML elements such as `nav`, `main`, and `aside`, ensuring appropriate structure for content.

```tsx
// Navigation container
<Container as="nav" className="navigation">
  <NavItems />
</Container>

// Main content area
<Container as="main" className="content">
  <Article />
</Container>

// Sidebar
<Container as="aside" className="sidebar">
  <Widgets />
</Container>
```

--------------------------------

### Design System Integration with asChild

Source: https://github.com/vercel/components.build/blob/main/content/docs/as-child.mdx

Shows how `asChild` enables seamless integration with existing design system components, like using a custom `Button` component as a `DropdownMenu.Trigger`.

```tsx
import { Button } from "@/components/ui/button";

<DropdownMenu.Trigger asChild>
  <Button variant="outline" size="icon">
    <MoreVertical className="h-4 w-4" />
  </Button>
</DropdownMenu.Trigger>
```

--------------------------------

### Controlled Stepper Component

Source: https://github.com/vercel/components.build/blob/main/content/docs/state.mdx

This example demonstrates a Stepper component where the state is controlled by the parent component. It accepts 'value' and 'setValue' props, delegating state management responsibility.

```tsx
type StepperProps = {
  value: number;
  setValue: (value: number) => void;
};

export const Stepper = ({ value, setValue }: StepperProps) => (
  <div>
    <p>{value}</p>
    <button onClick={() => setValue(value + 1)}>Increment</button>
  </div>
);
```

--------------------------------

### ARIA States for Interactive Elements

Source: https://github.com/vercel/components.build/blob/main/skills/building-components/references/accessibility.mdx

Apply ARIA states to communicate the current condition of interactive elements to assistive technologies. Examples include checked, expanded, and selected states.

```tsx
// Checked state
<div
  role="checkbox"
  aria-checked={isChecked}
  tabIndex={0}
>
  Accept terms
</div>

// Expanded state
<button
  aria-expanded={isOpen}
  aria-controls="panel-1"
>
  Toggle Panel
</button>
<div id="panel-1" hidden={!isOpen}>
  Panel content
</div>

// Selected state
<li
  role="option"
  aria-selected={isSelected}
>
  Option 1
</li>
```

--------------------------------

### Styled Card Component with `as` Prop

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Illustrates applying the `as` prop to a styled-component `Card` to render it as different HTML elements (`article`, `section`, `li`) while preserving its defined styles.

```tsx
const Card = styled.div`
  padding: 1rem;
  border-radius: 8px;
  background: white;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
`;

// Same styles, different elements
<Card as="article">Article content</Card>
<Card as="section">Section content</Card>
<Card as="li">List item content</Card>
```

--------------------------------

### 使用 data-state 对状态进行样式化

Source: https://github.com/vercel/components.build/blob/main/content/docs/data-attributes.cn.mdx

使用 `data-*` 属性以声明式方式暴露组件状态，允许使用者使用标准的 CSS 选择器根据状态来为组件添加样式。这避免了为不同状态暴露单独的 className props。

```tsx
const Dialog = ({ className, ...props }: DialogProps) => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div
      data-state={isOpen ? 'open' : 'closed'}
      className={cn('transition-all', className)}
      {...props}
    />
  );
};
```

```tsx
<Dialog className="data-[state=open]:opacity-100 data-[state=closed]:opacity-0" />
```

--------------------------------

### Composing Multiple Behaviors with asChild

Source: https://github.com/vercel/components.build/blob/main/content/docs/as-child.mdx

Demonstrates how multiple `asChild` props can be composed onto a single element to combine behaviors, such as opening a dialog and showing a tooltip.

```tsx
<Dialog.Trigger asChild>
  <Tooltip.Trigger asChild>
    <button>Open dialog (with tooltip)</button>
  </Tooltip.Trigger>
</Dialog.Trigger>
```

--------------------------------

### HTML Output for Box Component

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Shows the resulting HTML structure when using the Box component with and without the `as` prop.

```html
<!-- Default -->
<div>Content</div>

<!-- With as="section" -->
<section>Content</section>

<!-- With as="nav" -->
<nav>Content</nav>
```

--------------------------------

### Warn on Inappropriate Element Usage

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Implement runtime checks, especially in development (`__DEV__`), to warn users when an inappropriate element is used with a component, guiding them to provide necessary accessibility attributes.

```typescript
function Button({ as: Element = "button", ...props }) {
  if (__DEV__ && Element === "div" && !props.role) {
    console.warn(
      'Button: When using as="div", provide role="button" for accessibility',
    );
  }

  return <Element {...props} />;
}
```

--------------------------------

### Implement Keyboard Navigation for Menus

Source: https://github.com/vercel/components.build/blob/main/content/docs/accessibility.mdx

Ensure interactive components like menus support keyboard navigation by handling keydown events for arrow keys, Home, End, and Escape.

```tsx
// ✅ Complete keyboard support
function Menu() {
  const handleKeyDown = (e: React.KeyboardEvent) => {
    switch (e.key) {
      case "ArrowDown":
        focusNextItem();
        break;
      case "ArrowUp":
        focusPreviousItem();
        break;
      case "Home":
        focusFirstItem();
        break;
      case "End":
        focusLastItem();
        break;
      case "Escape":
        closeMenu();
        break;
    }
  };

  return (
    <div role="menu" onKeyDown={handleKeyDown}>
      {/* menu items */}
    </div>
  );
}
```

--------------------------------

### Avoid Invalid HTML Nesting

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Illustrates common HTML nesting errors with polymorphic components, such as nesting a button within a button or a div within a paragraph, and shows valid nesting examples.

```html
// ❌ Invalid - button inside button
<Button as="button">
  <Button as="button">Nested</Button>
</Button>

// ❌ Invalid - div inside p
<Text as="p">
  <Box as="div">Invalid nesting</Box>
</Text>

// ✅ Valid nesting
<Text as="div">
  <Box as="div">Valid nesting</Box>
</Text>
```

--------------------------------

### Text Component with `as` Prop for Reusability

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Demonstrates a flexible Text component that uses the `as` prop to render different HTML elements (`h1`, `p`, `span`, `label`) while maintaining consistent styling and size variants.

```tsx
// Text component used for different elements
<Text as="h1" size="2xl">Page Title</Text>
<Text as="p" size="md">Body paragraph</Text>
<Text as="span" size="sm">Inline text</Text>
<Text as="label" size="sm">Form label</Text>
```

--------------------------------

### Apply Styles in Order

Source: https://github.com/vercel/components.build/blob/main/content/docs/styling.jp.mdx

Combine base styles, variant styles, conditional styles, and user overrides using `cn` for a predictable styling order.

```tsx
className={cn(
  'base-styles',
  variant && variantStyles,
  isActive && 'active',
  className
)}
```

--------------------------------

### tailwind-merge with Tailwind Utility Classes

Source: https://github.com/vercel/components.build/blob/main/content/docs/styling.cn.mdx

Demonstrates how `tailwind-merge` handles conflicts across various Tailwind utility classes, including spacing, text size, and hover states.

```tsx
twMerge('px-4 py-2', 'px-8'); // Returns: "py-2 px-8"
twMerge('text-sm', 'text-lg'); // Returns: "text-lg"
twMerge('hover:bg-red-500', 'hover:bg-blue-500'); // Returns: "hover:bg-blue-500"
```

--------------------------------

### Button Component with `as` Prop

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Demonstrates using the `as` prop to explicitly define the underlying HTML element for a Button component, allowing for different semantic tags like `a` or `button`.

```tsx
// Explicit element type
<Button as="a" href="/home">Link Button</Button>
<Button as="button" type="submit">Submit Button</Button>
```

--------------------------------

### Manual TypeScript Implementation of `as` Prop

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

A simplified and a more complete TypeScript implementation of the `as` prop pattern for polymorphic components.

```tsx
// Simplified implementation
function Component({ as: Element = "div", children, ...props }) {
  return <Element {...props}>{children}</Element>;
}

// More complete implementation with TypeScript
type PolymorphicProps<E extends React.ElementType> = {
  as?: E;
  children?: React.ReactNode;
} & React.ComponentPropsWithoutRef<E>;

function Component<E extends React.ElementType = "div">({
  as,
  children,
  ...props
}: PolymorphicProps<E>) {
  const Element = as || "div";
  return <Element {...props}>{children}</Element>;
}
```

--------------------------------

### Using Radix UI `Slot` with `asChild`

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Demonstrates two ways to use the `Item` component: default rendering as a div and using `asChild` to merge props with a child `a` tag.

```tsx
// Default: renders as a div
<Item variant="primary">Content</Item>

// With asChild: merges props with child component
<Item variant="primary" asChild>
  <a href="/home">Link with Item styles</a>
</Item>
```

--------------------------------

### CSS for Color Contrast Requirements

Source: https://github.com/vercel/components.build/blob/main/content/docs/accessibility.mdx

Define CSS rules to meet WCAG contrast ratio guidelines for text and non-text elements. Examples show ratios for normal text (7:1), large text (4.5:1), and icons/borders (3:1).

```css
/* Normal text (< 18pt or < 14pt bold) */
.text {
  color: #595959; /* 7:1 ratio against white */
  background: white;
}

/* Large text (≥ 18pt or ≥ 14pt bold) */
.heading {
  color: #767676; /* 4.5:1 ratio against white */
  font-size: 1.5rem;
  font-weight: bold;
}

/* Non-text elements (icons, borders) */
.icon {
  color: #949494; /* 3:1 ratio against white */
}
```

--------------------------------

### Using asChild with Semantic HTML Elements

Source: https://github.com/vercel/components.build/blob/main/content/docs/as-child.mdx

Demonstrates how `asChild` allows using semantic HTML elements like `<a>` for navigation or custom components like `IconButton`.

```tsx
// Use a link for navigation
<AlertDialog.Trigger asChild>
  <a href="/delete">Delete Account</a>
</AlertDialog.Trigger>

// Use a custom button component
<Tooltip.Trigger asChild>
  <IconButton icon={<InfoIcon />} />
</Tooltip.Trigger>
```

--------------------------------

### 与 Radix UI 的集成

Source: https://github.com/vercel/components.build/blob/main/content/docs/data-attributes.cn.mdx

Radix UI 广泛使用 data 属性模式，自动将 data 属性应用到其 primitives。它提供了多种 data 属性用于样式化。

```tsx
import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    {/* Radix automatically adds data-state="open" | "closed" */}
    <Dialog.Overlay className="data-[state=open]:animate-in data-[state=closed]:animate-out" />
    <Dialog.Content className="data-[state=open]:fade-in data-[state=closed]:fade-out" />
  </Dialog.Portal>
</Dialog.Root>
```

--------------------------------

### Apply Visible Focus Indicators and Color Contrast

Source: https://github.com/vercel/components.build/blob/main/content/docs/accessibility.mdx

Enhance visual accessibility with clear focus indicators using `:focus-visible` and ensure sufficient color contrast ratios for text.

```css
/* ✅ Visible focus indicators */
button:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

/* ✅ Sufficient color contrast (4.5:1 for normal text, 3:1 for large text) */
.text {
  color: #333; /* Against white: 12.6:1 ratio */
  background: white;
}

/* ✅ Responsive text sizing */
.text {
  font-size: 1rem; /* Respects user preferences */
}
```

--------------------------------

### Accessible Navigation with asChild

Source: https://github.com/vercel/components.build/blob/main/content/docs/as-child.mdx

Illustrates using `asChild` to maintain proper semantics for navigation elements by rendering a custom `Link` component as a `NavigationMenu.Link`.

```tsx
<NavigationMenu.Link asChild>
  <Link href="/products" className="nav-link">
    Products
  </Link>
</NavigationMenu.Link>
```

--------------------------------

### Layout Flex Component Implementation

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Presents a `Flex` layout component that utilizes the `as` prop to render as different HTML elements (defaulting to `div`) and applies flexbox utility classes for layout management.

```tsx
function Flex({ as: Element = 'div', ...props }) {
  return (
    <Element
      className={cn('flex', props.className)}
      {...props}
    />
  );
}

// Semantic HTML
<Flex as="header" className="justify-between">
  <Logo />
  <Navigation />
</Flex>

<Flex as="main" className="flex-col">
  <Content />
</Flex>
```

--------------------------------

### Button Component with `as` Prop for Accessibility

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Shows how the `as` prop on a Button component can be used to render elements like `a` or `h2` with button-like styling, improving accessibility by using semantically correct tags where appropriate.

```tsx
// Link that looks like a button
<Button as="a" href="/signup">
  Sign Up Now
</Button>

// Button that submits a form
<Button as="button" type="submit">
  Submit
</Button>

// Heading with button styles
<Button as="h2" role="presentation">
  Section Title
</Button>
```

--------------------------------

### Button Styling Without tailwind-merge

Source: https://github.com/vercel/components.build/blob/main/content/docs/styling.mdx

Demonstrates how multiple conflicting classes can lead to unpredictable styling results when not merged intelligently.

```tsx
const Button = ({ className, ...props }: ComponentProps) => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div
      className={cn(
        "rounded-lg border bg-white shadow-sm",
        isOpen && "bg-blue-500",
        className,
      )}
      {...props}
    />
  );
};
```

--------------------------------

### Configure package.json for npm Publishing

Source: https://github.com/vercel/components.build/blob/main/content/docs/npm.mdx

This JSON configuration is essential for publishing your component library to npm. It defines package metadata, module entry points, build scripts, and dependencies.

```json
{
  "name": "@acme/ui-components",
  "version": "1.0.0",
  "description": "A collection of accessible React components",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    },
    "./styles.css": "./dist/styles.css"
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "dependencies": {
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.0.0"
  },
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.0.0"
  }
}
```

--------------------------------

### CSS for Mobile Touch Target Sizing

Source: https://github.com/vercel/components.build/blob/main/content/docs/accessibility.mdx

Ensure touch targets meet minimum size requirements (44x44px for iOS, 48x48dp for Android) using CSS `min-height` and `min-width`. Includes technique for adding invisible touch areas to small icons.

```css
/* Minimum 44x44px for iOS, 48x48dp for Android */
.button {
  min-height: 44px;
  min-width: 44px;
  padding: 12px 16px;
}

/* Add invisible touch area for small icons */
.icon-button {
  position: relative;
  padding: 8px;
}

.icon-button::before {
  content: "";
  position: absolute;
  top: -8px;
  right: -8px;
  bottom: -8px;
  left: -8px;
}
```

--------------------------------

### Interactive Clickable Component Implementation

Source: https://github.com/vercel/components.build/blob/main/content/docs/polymorphism.mdx

Details a `Clickable` component that uses the `as` prop to render as various elements (defaulting to `button`) and dynamically sets `role` and `tabIndex` for accessibility when not rendering as a native button or anchor.

```tsx
function Clickable({ as: Element = 'button', ...props }) {
  const isButton = Element === 'button';
  const isAnchor = Element === 'a';

  return (
    <Element
      role={!isButton && !isAnchor ? 'button' : undefined}
      tabIndex={!isButton && !isAnchor ? 0 : undefined}
      {...props}
    />
  );
}

// Various clickable elements
<Clickable as="button" onClick={handleClick}>Button</Clickable>
<Clickable as="a" href="/link">Link</Clickable>
<Clickable as="div" onClick={handleClick}>Div Button</Clickable>
```

--------------------------------

### 常见的状态模式

Source: https://github.com/vercel/components.build/blob/main/content/docs/data-attributes.cn.mdx

对各种组件状态使用 data 属性，例如 open/closed, selected, disabled, loading, orientation, 和 side/position。

```tsx
// Open/closed state
<Accordion data-state={isOpen ? 'open' : 'closed'} />

// Selected state
<Tab data-state={isSelected ? 'active' : 'inactive'} />

// Disabled state (in addition to disabled attribute)
<Button data-disabled={isDisabled} disabled={isDisabled} />

// Loading state
<Button data-loading={isLoading} />

// Orientation
<Slider data-orientation="horizontal" />

// Side/position
<Tooltip data-side="top" />
```

--------------------------------

### Form Integration with asChild

Source: https://github.com/vercel/components.build/blob/main/content/docs/as-child.mdx

Shows how `asChild` can be used within form libraries to integrate custom elements like checkboxes while preserving functionality.

```tsx
<FormField
  control={form.control}
  name="acceptTerms"
  render={({ field }) => (
    <FormItem>
      <Checkbox.Root asChild>
        <input type="checkbox" {...field} className="sr-only" />
      </Checkbox.Root>
    </FormItem>
  )}
/>
```

--------------------------------

### Migrate from CSS Modules to cn + Tailwind

Source: https://github.com/vercel/components.build/blob/main/content/docs/styling.jp.mdx

Convert CSS Modules class application to use the `cn` utility with Tailwind CSS classes for a unified styling approach.

```tsx
import styles from './Button.module.css';

<button className={`${styles.button} ${styles[variant]} ${className}`} />
```

```tsx
import { cn } from '@/lib/utils';

<button className={cn(
  'px-4 py-2 rounded-lg',
  variant === 'primary' && 'bg-blue-500 text-white',
  className
)} />
```