diff --git a/apps/engineering/app/design/[[...slug]]/page.tsx b/apps/engineering/app/design/[[...slug]]/page.tsx
index a41bea2606..15779eb4fc 100644
--- a/apps/engineering/app/design/[[...slug]]/page.tsx
+++ b/apps/engineering/app/design/[[...slug]]/page.tsx
@@ -1,5 +1,5 @@
import { componentSource } from "@/app/source";
-import { createTypeTable } from "fumadocs-typescript/ui";
+import { TypeTable } from "fumadocs-ui/components/type-table";
import defaultMdxComponents from "fumadocs-ui/mdx";
import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/page";
import type { Metadata } from "next";
@@ -15,7 +15,6 @@ export default async function Page(props: {
if (!page) {
notFound();
}
- const { AutoTypeTable } = createTypeTable();
const MDX = page.data.body;
@@ -26,7 +25,7 @@ export default async function Page(props: {
{page.data.description}
-
+
);
diff --git a/apps/engineering/content/design/components/badge.mdx b/apps/engineering/content/design/components/badge.mdx
index c2db9b40af..270c6d2a60 100644
--- a/apps/engineering/content/design/components/badge.mdx
+++ b/apps/engineering/content/design/components/badge.mdx
@@ -4,6 +4,10 @@ description: A versatile badge component for displaying status, categories, or l
---
import { DefaultVariants, SizeVariants, MonoFont, StatusBadges, InteractiveBadges } from "./badge.example";
+## Overview
+
+The Badge component provides a consistent way to display status indicators, categories, or labels throughout your application. It's designed to provide quick visual context with multiple styling options and accessibility features.
+
## Usage
```tsx
@@ -23,20 +27,39 @@ export default function MyComponent() {
## Examples
### Default Variants
+All available variants for different use cases.
### Size Variants
+Different sizes available for the badge component.
+
### Monospace Font
+Badges with monospace font for technical content like IDs or codes.
+
### Status Badges
+Common status indicators used in applications.
+
### Interactive Badges
+
+Interactive styling with hover effects.
+
+## Features
+
+- **Multiple Variants**: Six different visual styles (primary, secondary, success, warning, blocked, error)
+- **Size Options**: Default and small sizes for different contexts
+- **Font Options**: Support for monospace font for technical content
+- **Accessibility**: Built-in accessibility support with proper contrast ratios
+- **Customizable**: Extensive styling options through className prop
+- **Responsive**: Adapts to different screen sizes
+
## Props
| Prop | Type | Default | Description |
@@ -55,19 +78,40 @@ export default function MyComponent() {
- **blocked**: Orange styling for blocked or restricted states
- **error**: Red styling for errors or negative states
-## Accessibility
+## Structure
-The Badge component follows accessibility best practices:
+The Badge component is a simple, self-contained component that doesn't require sub-components. It renders as a single span element with appropriate styling and accessibility attributes.
-- Uses semantic HTML with proper color contrast ratios
-- Text is readable and meets WCAG guidelines
-- Can be used with screen readers without issues
-- Hover states provide visual feedback for interactive elements
+## Styling
-## Best Practices
+The Badge component includes default styling with:
+
+- Consistent padding and border radius
+- Color-coded variants for semantic meaning
+- Dark mode support
+- Hover states for interactive badges
+- Focus states for accessibility
+- Responsive design
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+ Custom Badge
+
+```
+
+## Accessibility
+
+The Badge component follows accessibility best practices:
-- Use badges to provide quick visual context about status or categories
-- Choose appropriate variants that match the semantic meaning
-- Keep badge text concise and descriptive
-- Use consistent badge styling across your application
-- Consider using the monospace font for technical content like IDs or codes
\ No newline at end of file
+- **Semantic HTML**: Uses semantic HTML with proper color contrast ratios
+- **Text Readability**: Text is readable and meets WCAG guidelines
+- **Screen Reader Support**: Can be used with screen readers without issues
+- **Visual Feedback**: Hover states provide visual feedback for interactive elements
+- **Focus Management**: Proper focus states for keyboard navigation
diff --git a/apps/engineering/content/design/components/buttons/button.mdx b/apps/engineering/content/design/components/buttons/button.mdx
index 5317f42630..12a9cc59ac 100644
--- a/apps/engineering/content/design/components/buttons/button.mdx
+++ b/apps/engineering/content/design/components/buttons/button.mdx
@@ -23,179 +23,241 @@ import {
ShapeVariantsExample,
} from "./button.examples";
-## Basic Variants
+## Overview
-Button comes in three basic variants that serve different UI purposes:
+The Button component provides a comprehensive button system for creating interactive elements throughout your application. It's designed to handle various use cases with multiple variants, color schemes, sizes, and states while maintaining accessibility and consistent styling.
-### Primary
+## Usage
+
+```tsx
+import { Button } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+
+
+
+
+ );
+}
+```
+
+## Examples
+
+### Basic Variants
+The Button comes in three basic variants
+#### Primary
The default button style with a solid background. Use for primary actions and main call-to-actions.
-### Outline
-
+#### Outline
Button with transparent background and visible border. Ideal for secondary actions that don't require as much visual emphasis.
-### Ghost
-
+#### Ghost
Button with no background or border until interacted with. Perfect for tertiary actions or when space is limited.
-## Color Variants
-
-Each button variant can be combined with different color schemes to convey the nature of the action:
-
-### Danger - Primary
+### Color Variants
+Each button variant can be combined with different color schemes to convey the nature of the action.
+#### Danger Variants
Solid background danger variant for destructive actions that should be clearly highlighted.
-
+***Primary***
-### Danger - Outline
+
-Danger variant with outline style. Use for destructive actions that require less visual prominence.
+***Outline***
-### Danger - Ghost
-
-Minimal danger variant. Suitable for destructive actions in tight UI spaces or alongside other content.
+***Ghost***
-### Warning - Primary
-
+#### Warning Variants
Warning variant with solid background for actions that require caution but aren't destructive.
-
+***Primary***
-### Warning - Outline
+
-Warning variant with outline style for secondary cautionary actions.
+***Outline***
-### Warning - Ghost
-
-Warning variant with ghost style for tertiary cautionary actions.
+***Ghost***
-### Success - Primary
-
+#### Success Variants
Success variant with solid background for positive or confirming actions.
-
+***Primary***
-### Success - Outline
+
-Success variant with outline style for secondary positive actions.
+***Outline***
-### Success - Ghost
-
-Success variant with ghost style for subtle positive actions.
+***Ghost***
-### Info - Primary
-
+#### Info Variants
Info variant with solid background for purely informational actions.
-
+***Primary***
-### Info - Outline
+
-Info variant with outline style for secondary informational actions.
+***Outline***
-### Info - Ghost
-
-Info variant with ghost style for subtle informational actions.
+***Ghost***
-## Size Variants
-
+### Size Variants
All button variants and color schemes can be combined with different sizes to fit various UI contexts.
-## Special Features
-
-Button includes additional features that enhance usability and interaction:
-
-### With Icons
+### Special Features
+Button includes additional features that enhance usability and interaction.
+#### With Icons
Buttons can include icons from the Lucide library for enhanced visual meaning. Icons can be placed before or after text.
-### With Keyboard Shortcuts
-
-Buttons can display and respond to keyboard shortcuts for improved accessibility and power-user workflows.
+#### Shape Variants
+For special layouts, buttons can use the `shape` prop.
-## Additional Features
-
-The Button component includes some additional features not shown in the examples above:
-
-### Legacy Variant Support
+
-For backward compatibility, the component supports legacy variants:
+## Features
-- `default` will be mapped to `primary` variant
-- `destructive` will be mapped to `primary` variant with `danger` color
+- **Multiple Variants**: Three basic variants (primary, outline, ghost) with different visual emphasis
+- **Color Schemes**: Five color options (default, danger, warning, success, info) for semantic meaning
+- **Size Options**: Five sizes (sm, md, lg, xlg, 2xlg) for different contexts
+- **Interactive States**: Loading, disabled, hover, and focus states
+- **Icon Support**: Built-in support for Lucide icons
+- **Accessibility**: Full accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Keyboard Support**: Full keyboard navigation and shortcuts
-### Shape Variants
+## Props
-For special layouts, buttons can use the `shape` prop:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "outline" \| "ghost"` | `"primary"` | The variant style to use for the button |
+| `color` | `"default" \| "success" \| "warning" \| "danger" \| "info"` | `"default"` | The color scheme to use for the button |
+| `size` | `"sm" \| "md" \| "lg" \| "xlg" \| "2xlg"` | `"sm"` | The size of the button |
+| `shape` | `"square"` | - | Special shape variant for the button |
+| `loading` | `boolean` | - | Display a loading spinner instead of the children |
+| `disabled` | `boolean` | - | Disables the button |
+| `keyboard` | `object` | - | Keyboard shortcut configuration |
+| `keyboard.display` | `string` | - | The shortcut displayed on the button |
+| `keyboard.trigger` | `(e: KeyboardEvent) => boolean` | - | Function to decide whether the button should be pressed |
+| `keyboard.callback` | `(e: KeyboardEvent) => void \| Promise` | - | The function to be called when triggered |
+| `asChild` | `boolean` | - | Allows you to use your own component as a button |
+| `loadingLabel` | `string` | `"Loading, please wait"` | Optional label for screen readers when in loading state |
+| `onClick` | `(event: React.MouseEvent) => void` | - | Callback triggered when button is clicked |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | The type of button |
+| `className` | `string` | - | Additional CSS classes to apply |
+
+## Variants
-
+### Primary
+- Solid background with high visual emphasis
+- Use for main actions and primary call-to-actions
+- Default variant for most use cases
-## Props
+### Outline
+- Transparent background with visible border
+- Secondary actions with moderate emphasis
+- Good for forms and secondary actions
-The Button component accepts all standard HTML button attributes plus the following:
-
-
-
-## Usage Guidelines
-
-When using the Button component:
-
-- **Hierarchy**: Maintain a clear visual hierarchy with your button choices
- - Use **primary** buttons for main actions and primary call-to-actions
- - Use **outline** buttons for secondary actions
- - Use **ghost** buttons for tertiary actions or in dense UIs
-- **Color semantics**: Apply color variants based on the action's impact:
- - **Default** for neutral or standard actions
- - **Success** for positive, confirming, or creative actions
- - **Warning** for cautionary actions that require attention
- - **Danger** for destructive or irreversible actions
-- **Interaction states**:
- - Ensure **loading** state is shown during asynchronous operations to prevent multiple submissions
- - Use **disabled** state appropriately for actions that are currently unavailable
- - Test that focus states are clearly visible for keyboard navigation
-- **Sizing and spacing**:
- - Use appropriate **size** based on the button's importance and the available space
- - Maintain consistent spacing between buttons in a group (recommend 16px/1rem)
- - For button groups, maintain consistent sizing within the group
-- **Content guidelines**:
- - Use concise, action-oriented text (e.g., "Save changes" instead of "Submit")
- - Add icons to enhance meaning, but avoid overloading buttons with too many elements
- - For destructive actions, consider using explicit verbs ("Delete" instead of "Remove")
-- **Accessibility**:
- - Consider adding keyboard shortcuts for frequently used actions
- - Ensure sufficient color contrast between text and background (WCAG AA minimum)
- - Add appropriate aria attributes for complex button behaviors
-- **Responsive behavior**:
- - On mobile, ensure buttons are at least 44×44px (touch target size)
- - Consider stacking buttons vertically on very small screens
+### Ghost
+- No background or border until interacted with
+- Tertiary actions or minimal visual impact
+- Perfect for dense UIs or subtle interactions
+
+## Color Schemes
+
+### Default
+- Neutral styling for general actions
+- Gray/blue color scheme
+- Most common choice for standard actions
+
+### Danger
+- Red color scheme for destructive actions
+- Use for delete, remove, or destructive operations
+- Should be used sparingly and with clear intent
+
+### Warning
+- Yellow/orange color scheme for cautionary actions
+- Use for actions that require attention but aren't destructive
+- Good for confirmations or warnings
+
+### Success
+- Green color scheme for positive actions
+- Use for save, confirm, or successful operations
+- Encourages positive user actions
+
+### Info
+- Blue color scheme for informational actions
+- Use for help, info, or neutral operations
+- Good for educational or informational contexts
+
+## Structure
+
+The Button component is a self-contained component that renders as a single button element with appropriate styling, accessibility attributes, and optional icon support.
+
+## Styling
+
+The Button component includes default styling with:
+
+- Consistent padding and border radius across variants
+- Color-coded schemes for semantic meaning
+- Smooth transitions for state changes
+- Dark mode support
+- Responsive design
+- Focus states for accessibility
+- Customizable through className prop
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
+
+## Accessibility
+
+The Button component is built with accessibility in mind:
+
+- **Semantic HTML**: Uses proper button element with appropriate roles
+- **ARIA Attributes**: Proper ARIA labels and states for screen readers
+- **Keyboard Navigation**: Full keyboard support including Enter and Space
+- **Focus Management**: Clear focus indicators and logical tab order
+- **Loading States**: Proper ARIA attributes for loading states
+- **Screen Reader Support**: Announces button states and actions appropriately
+- **High Contrast**: Maintains proper contrast ratios across all variants
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/buttons/copy-button.mdx b/apps/engineering/content/design/components/buttons/copy-button.mdx
index 9ce262c55d..03f71300f7 100644
--- a/apps/engineering/content/design/components/buttons/copy-button.mdx
+++ b/apps/engineering/content/design/components/buttons/copy-button.mdx
@@ -1,20 +1,48 @@
---
title: CopyButton
-summary: A button component that copies text to clipboard with visual feedback and accessibility features
+description: A button component that copies text to clipboard with visual feedback and accessibility features for enhanced user experience.
---
import { Default } from "./copy-button.examples"
-The `CopyButton` component provides a simple way to copy text to the clipboard with visual feedback. It extends the base Button component and includes built-in copy functionality with proper accessibility support.
+## Overview
+
+The CopyButton component provides a simple way to copy text to the clipboard with visual feedback. It's designed to extend the base Button component with built-in copy functionality, proper accessibility support, and analytics tracking capabilities.
+
+## Usage
+
+```tsx
+import { CopyButton } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+
+
+
+ );
+}
+```
+
+## Examples
+
+### Basic Usage
+Different usage patterns and variants of the CopyButton component.
+
+
## Features
-- Visual feedback with icon change on copy (TaskUnchecked → TaskChecked)
-- Accessible with screen reader support and ARIA labels
-- Automatic reset after 2 seconds
-- Extends ButtonProps for full button customization
-- Analytics support with optional src prop
-- Prevents event propagation to parent elements
-- TypeScript support with proper typing
+- **Visual Feedback**: Icon changes from TaskUnchecked to TaskChecked on copy
+- **Accessibility**: Full screen-reader support with ARIA labels
+- **Auto Reset**: Automatically resets after 2 seconds
+- **Button Integration**: Extends ButtonProps for full customization
+- **Analytics Support**: Optional src prop for tracking
+- **Event Prevention**: Prevents event propagation to parent elements
+- **TypeScript Support**: Full TypeScript support with proper typing
## Props
@@ -25,29 +53,19 @@ The `CopyButton` component provides a simple way to copy text to the clipboard w
| `variant` | `ButtonVariant` | `"outline"` | Button variant (outline, ghost, primary, etc.) |
| `className` | `string?` | `undefined` | Additional CSS classes to apply to the button |
-The component also accepts all standard Button props.
-## Usage
-
+## Variants
+The component accepts all standard Button props.
-## Behavior
+## Structure
-1. **Click Handling**: On click, the button copies the provided text to the clipboard
-2. **Visual Feedback**: The icon changes from TaskUnchecked to TaskChecked state
-3. **Auto Reset**: After 2 seconds, the icon reverts to its original state
-4. **Event Prevention**: Parent click events are prevented from triggering (`e.stopPropagation`)
-5. **Analytics**: If provided, the `src` prop is passed to analytics for tracking
+The CopyButton component is a specialized button that:
-## Accessibility
-
-The component includes comprehensive accessibility features:
-
-- **ARIA Label**: `aria-label="Copy to clipboard"` for screen readers
-- **Screen Reader Text**: Hidden "Copy" text for additional context
-- **Title Attribute**: `title="Copy to clipboard"` for tooltip on hover
-- **Focus Management**: Proper focus states with `focus:ring-0 focus:border-grayA-6`
-- **Keyboard Support**: Full keyboard navigation support inherited from Button component
+1. **Renders as Button**: Uses the base Button component for styling and behavior
+2. **Copy Functionality**: Handles clipboard operations with visual feedback
+3. **State Management**: Manages copy state and auto-reset functionality
+4. **Analytics Integration**: Optionally tracks copy events
## Styling
@@ -57,11 +75,25 @@ The component includes default styling:
- Focus states: `focus:ring-0 focus:border-grayA-6`
- Icons: Full-size icons with `w-full h-full`
- Default variant: `outline` for subtle appearance
+- Customizable through className prop
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
-## Best Practices
+## Accessibility
+
+The component includes comprehensive accessibility features:
-- Use the `src` prop for analytics tracking when copying sensitive data
-- Provide meaningful `value` content for better user experience
-- Consider the button's context when choosing variants
-- Ensure sufficient contrast for the button in your design
-- Test with screen readers to verify accessibility
+- **ARIA Label**: `aria-label="Copy to clipboard"` for screen readers
+- **Screen Reader Text**: Hidden "Copy" text for additional context
+- **Title Attribute**: `title="Copy to clipboard"` for tooltip on hover
+- **Focus Management**: Proper focus states with `focus:ring-0 focus:border-grayA-6`
+- **Keyboard Support**: Full keyboard navigation support inherited from Button component
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/buttons/keyboard-button.mdx b/apps/engineering/content/design/components/buttons/keyboard-button.mdx
index 9687c25883..3493e86c8e 100644
--- a/apps/engineering/content/design/components/buttons/keyboard-button.mdx
+++ b/apps/engineering/content/design/components/buttons/keyboard-button.mdx
@@ -1,16 +1,44 @@
---
-title: 'KeyboardButton'
-description: 'A component for displaying keyboard shortcuts with optional modifier keys'
+title: KeyboardButton
+description: A component for displaying keyboard shortcuts with optional modifier keys in a visually appealing and accessible format.
---
import { Default } from "./keyboard-button.examples"
+## Overview
+
+The KeyboardButton component is designed to display keyboard shortcuts in a visually appealing and accessible way. It's built to support both regular keys and modifier keys (like ⌘, ⇧, CTRL, ⌥) in a consistent format that matches design system standards.
+
+## Usage
+
+```tsx
+import { KeyboardButton } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+
+
+
+
+ );
+}
+```
+
+## Examples
+
+### Default and Modifier Key
+Examples showing both regular keys and modifier key combinations.
+
+
+
## Features
-- Displays keyboard shortcuts with optional modifier keys
-- Accessible with proper ARIA attributes
-- Supports both light and dark themes
-- Responsive design with mobile considerations
-- Customizable through className prop
+- **Modifier Key Support**: Displays modifier keys (⌘, ⇧, CTRL, ⌥) with main shortcuts
+- **Accessibility**: Built-in accessibility with proper ARIA attributes
+- **Theme Support**: Supports both light and dark themes
+- **Responsive Design**: Adapts to different screen sizes with mobile considerations
+- **Customizable**: Extensive styling options through className prop
+- **Consistent Formatting**: Maintains consistent visual appearance across the app
## Props
@@ -20,26 +48,45 @@ import { Default } from "./keyboard-button.examples"
| `modifierKey` | `"⌘" \| "⇧" \| "CTRL" \| "⌥" \| null` | Optional modifier key to be displayed before the main shortcut |
| `className` | `string` | Additional CSS classes to customize the component |
-The component also accepts all standard HTML div element props.
+The component also accepts all standard HTML span element props.
-## Usage
+## Structure
-Default and Modifier Key
+The KeyboardButton component is a simple, self-contained component that renders as a single span element with:
-
+1. **Modifier Key Display**: Optional modifier key with proper spacing
+2. **Main Shortcut**: The primary key being displayed
+3. **Styling Container**: Consistent padding and visual treatment
+
+## Styling
+
+The component features:
+
+- Consistent padding and sizing across all instances
+- Drop shadow effects for depth and visual separation
+- Hover and focus states for better interaction
+- Dark mode support with appropriate color schemes
+- Responsive behavior (hidden on mobile devices)
+- Customizable through className prop
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
## Accessibility
The component includes:
-- Proper ARIA labels for screen readers
-- Keyboard focus management
-- Descriptive title attributes for tooltips
-## Design
-
-The component features:
-- Consistent padding and sizing
-- Drop shadow effects
-- Hover and focus states
-- Dark mode support
-- Responsive behavior (hidden on mobile devices)
+- **ARIA Labels**: Proper ARIA labels for screen readers
+- **Keyboard Focus**: Keyboard focus management
+- **Descriptive Titles**: Title attributes for tooltips
+- **Semantic Structure**: Uses appropriate HTML elements
+- **Screen Reader Support**: Announces keyboard shortcuts appropriately
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/buttons/refresh-button.mdx b/apps/engineering/content/design/components/buttons/refresh-button.mdx
index 6379a4e867..cc1123f979 100644
--- a/apps/engineering/content/design/components/buttons/refresh-button.mdx
+++ b/apps/engineering/content/design/components/buttons/refresh-button.mdx
@@ -4,6 +4,9 @@ description: "A button component for refreshing data with keyboard shortcuts and
---
import { Default, WithLiveMode, DisabledState } from "./refresh-button.examples";
+## Overview
+
+The RefreshButton component offers built-in keyboard-shortcut support and live-mode toggling. It handles refresh operations with visual feedback, keyboard navigation, and robust accessibility features.
## Features
- **Keyboard Shortcut**: Built-in support for ⌥+⇧+R (Option+Shift+R) shortcut
diff --git a/apps/engineering/content/design/components/buttons/visual-button.mdx b/apps/engineering/content/design/components/buttons/visual-button.mdx
index e199812165..426594cbe8 100644
--- a/apps/engineering/content/design/components/buttons/visual-button.mdx
+++ b/apps/engineering/content/design/components/buttons/visual-button.mdx
@@ -1,16 +1,12 @@
---
title: VisibleButton
-description: A toggle button that switches between visible and hidden states, commonly used for showing/hiding sensitive information.
+description: A toggle button that switches between visible and hidden states, commonly used for showing/hiding sensitive information like passwords or API keys.
---
import { VisibleButtonDemo } from "./visual-button.examples"
-## Features
+## Overview
-- Toggle between visible/hidden states.
-- Accessible with screen readers.
-- Dark mode support.
-- Customizable styling through `className` prop.
-- Configurable button `variant`.
+The VisibleButton component provides a toggle button that switches between visible and hidden states. It's designed to be commonly used for showing/hiding sensitive information like passwords, API keys, or other confidential data with proper accessibility support.
## Usage
@@ -37,8 +33,20 @@ function Example() {
## Examples
+### Basic Usage
+Examples showing different variants and use cases for the VisibleButton component.
+
+## Features
+
+- **Toggle Functionality**: Switches between visible/hidden states with icon changes
+- **Accessibility**: Built-in accessibility with screen reader support
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Customizable Styling**: Extensive styling options through className prop
+- **Configurable Variants**: Supports different button variants
+- **State Management**: Integrates with React state for controlled behavior
+
## Props
| Prop | Type | Description |
@@ -49,25 +57,52 @@ function Example() {
| `title` | `string` | Text used for accessibility labels and tooltip |
| `variant` | `ButtonProps["variant"]` | Optional button variant (defaults to "outline") |
-Additional props are forwarded to the underlying `Button` component. See [Button component](/design/components/buttons/button) for more details.
+Additional props are forwarded to the underlying `Button` component. See [Button component](/design/components/buttons/button) for more details.
-## Behavior
+## Variants
-1. Clicking the button toggles between visible (Eye icon) and hidden (EyeSlash icon) states.
-2. The button's aria-label and title attributes update based on the current state and provided title prop.
+The component accepts all standard Button props.
-## Accessibility
+## Structure
+
+The VisibleButton component is a specialized button that:
-- Includes dynamic aria-labels based on the title prop.
-- Uses semantic button element with proper ARIA attributes.
-- Maintains focus states for keyboard navigation.
-- Shows tooltip on hover with current action.
+1. **Renders as Button**: Uses the base Button component for styling and behavior
+2. **Icon Management**: Switches between Eye and EyeSlash icons based on state
+3. **State Integration**: Integrates with external state management
+4. **Accessibility**: Provides proper ARIA labels and descriptions
-## Design
+## Styling
The button features:
-- A minimal, circular design.
-- Icon-based state indication (Eye/EyeSlash).
-- Hover and focus states.
-- Dark mode support.
-- Responsive sizing (inherits from Button component).
+
+- A minimal, circular design for subtle appearance
+- Icon-based state indication (Eye/EyeSlash)
+- Hover and focus states for better interaction
+- Dark mode support with appropriate color schemes
+- Responsive sizing (inherits from Button component)
+- Customizable through className prop
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
+
+## Accessibility
+
+The component includes comprehensive accessibility features:
+
+- **Dynamic ARIA Labels**: aria-labels based on the title prop and current state
+- **Semantic Button**: Uses semantic button element with proper ARIA attributes
+- **Focus Management**: Maintains focus states for keyboard navigation
+- **Tooltip Support**: Shows tooltip on hover with current action
+- **Screen Reader Support**: Announces state changes appropriately
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/cards/card.example.tsx b/apps/engineering/content/design/components/cards/card.example.tsx
index 0c8c8c846b..95dbf2480a 100644
--- a/apps/engineering/content/design/components/cards/card.example.tsx
+++ b/apps/engineering/content/design/components/cards/card.example.tsx
@@ -1,15 +1,7 @@
"use client";
import { RenderComponentWithSnippet } from "@/app/components/render";
import { Button } from "@unkey/ui";
-import {
- Card,
- CardContent,
- CardDescription,
- CardFooter,
- CardHeader,
- CardTitle,
- MetricCardTitle,
-} from "@unkey/ui";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@unkey/ui";
export function BasicCard() {
return (
@@ -112,33 +104,6 @@ export function CompleteCard() {
);
}
-export function MetricCard() {
- return (
-
-
-
-
- Total API Calls
- 1,234,567
-
-
-
-
- This month
- +12.5%
-
-
- This week
- +8.2%
-
-
-
-
-
-
- );
-}
-
export function CardGrid() {
return (
@@ -165,11 +130,11 @@ export function CardGrid() {
Requests
- 45.2K
+ 45.2K
Success Rate
- 99.9%
+ 99.9%
diff --git a/apps/engineering/content/design/components/cards/card.mdx b/apps/engineering/content/design/components/cards/card.mdx
index 801924c806..6ed9db5259 100644
--- a/apps/engineering/content/design/components/cards/card.mdx
+++ b/apps/engineering/content/design/components/cards/card.mdx
@@ -1,17 +1,24 @@
---
title: Card
-description: A flexible container component for grouping related content with optional header, footer, and content sections.
+description: A flexible container component for grouping related content with optional header, footer, and content sections for consistent layouts.
---
-import { BasicCard, CardWithHeader, CardWithFooter, CompleteCard, MetricCard, CardGrid } from "./card.example"
+import { BasicCard, CardWithHeader, CardWithFooter, CompleteCard, CardGrid } from "./card.example"
-## Basic Usage
+## Overview
+
+The Card component provides a flexible container system for grouping related content throughout your application. It's designed to create consistent layouts with optional header, footer, and content sections while maintaining accessibility and responsive design.
+
+## Usage
```tsx
-import { Card, CardContent } from "@unkey/ui";
+import { Card, CardContent, CardHeader, CardTitle } from "@unkey/ui";
export default function MyComponent() {
return (
+
+ Card Title
+
Your content goes here
@@ -23,46 +30,43 @@ export default function MyComponent() {
## Examples
### Basic Card
-A simple card with just content.
+
+A simple card with just content for simple layouts.
### Card with Header
-Card with a title and description in the header.
+
+Card with a title and description in the header for introducing content sections.
### Card with Footer
-Card with action buttons in the footer.
+
+Card with action buttons in the footer for user interactions.
### Complete Card
-Card with header, content, and footer sections.
-
-
-### Metric Card
-Specialized card for displaying metrics with MetricCardTitle.
+Card with header, content, and footer sections working together.
-
+
### Card Grid
-Multiple cards in a responsive grid layout.
-
+Multiple cards in a responsive grid layout for dashboard-style interfaces.
-## Components
+
-The Card system is composed of several subcomponents:
+## Features
-- **Card**: The main container
-- **CardHeader**: Container for title and description
-- **CardTitle**: Main heading text (h2 element)
-- **MetricCardTitle**: Title specifically for metrics (p element)
-- **CardDescription**: Subtitle or description text
-- **CardContent**: Main content area
-- **CardFooter**: Footer area with border separator
+- **Composable Architecture**: Flexible subcomponents for custom layouts
+- **Consistent Styling**: Built-in spacing, typography, and design system integration
+- **Responsive Design**: Adapts to different screen sizes automatically
+- **Accessibility**: Semantic HTML structure with proper heading hierarchy
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Customizable**: Extensive styling options through className props
## Props
@@ -87,13 +91,6 @@ The Card system is composed of several subcomponents:
| `className` | `string` | `undefined` | Additional CSS classes |
| `children` | `React.ReactNode` | `undefined` | Title text |
-### MetricCardTitle
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | `undefined` | Additional CSS classes |
-| `children` | `React.ReactNode` | `undefined` | Metric title text |
-
### CardDescription
| Prop | Type | Default | Description |
@@ -115,27 +112,51 @@ The Card system is composed of several subcomponents:
| `className` | `string` | `undefined` | Additional CSS classes |
| `children` | `React.ReactNode` | `undefined` | Footer content |
-## Features
+`` inherits all common HTML `
` attributes (e.g. `id`, `style`) in addition to the props listed above.
+
+## Structure
+
+The Card system is composed of several subcomponents that work together:
+
+1. **Card**: Main container component
+2. **CardHeader**: Container for title and description
+3. **CardTitle**: Main heading text (`h2`)
+4. **CardDescription**: Subtitle or description text
+5. **CardContent**: Main content area
+6. **CardFooter**: Footer section with optional separator
-- Composable architecture for flexible layouts
-- Consistent styling with design system
-- Built-in spacing and typography
-- Responsive design
-- Border and background styling
-- Accessible semantic structure
+## Styling
-## Best Practices
+The Card component includes default styling with:
-- Use `CardTitle` for main headings and `MetricCardTitle` for numeric metrics
-- Include `CardDescription` to provide context for the card content
-- Use `CardFooter` for actions or additional information
-- Combine components based on your content needs
-- Apply consistent spacing using the default padding
+- Consistent spacing and typography from the design system
+- Border and background styling for visual separation
+- Responsive design that adapts to container size
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className props
+
+### Custom Styling
+
+You can customize the appearance using className props:
+
+```tsx
+
+
+ Custom Title
+
+
+ Custom content
+
+
+```
## Accessibility
-- Uses semantic HTML elements (h2 for CardTitle, p for descriptions)
-- Maintains proper heading hierarchy
-- Provides sufficient color contrast
-- Supports keyboard navigation
-- Screen reader friendly structure
\ No newline at end of file
+The Card component is built with accessibility in mind:
+
+- **Semantic HTML**: Uses appropriate HTML elements (h2 for CardTitle, p for descriptions)
+- **Heading Hierarchy**: Maintains proper heading hierarchy for screen readers
+- **Color Contrast**: Provides sufficient color contrast between text and background
+- **Keyboard Navigation**: Supports keyboard navigation through focusable elements
+- **Screen Reader Support**: Announces card structure and content appropriately
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/cards/settings-card.mdx b/apps/engineering/content/design/components/cards/settings-card.mdx
index 54eae39d5e..e79e9f7d5b 100644
--- a/apps/engineering/content/design/components/cards/settings-card.mdx
+++ b/apps/engineering/content/design/components/cards/settings-card.mdx
@@ -1,50 +1,130 @@
---
title: SettingCard
-description: The SettingCard component provides a consistent layout for settings sections in your application. It includes a title, description, and content area with optional styling options.
+description: A card component for settings options with consistent layout, optional borders, and configurable content width for settings interfaces.
---
import { SettingsCardBasic, SettingsCardsWithSharedEdge, SettingsCardsWithSquareEdge, SettingsCardsWithDivider } from "./settings-card.example"
-## Basic Usage
+## Overview
-The basic SettingCard includes a title, description, and content area.
+The SettingCard component provides a consistent layout for settings sections in your application. It's designed to include a title, description, and content area with optional styling options for creating cohesive settings interfaces.
-
+## Usage
-## Settings Cards With Shared Edge
+```tsx
+import { SettingCard } from "@unkey/ui";
-Two SettingCard components sharing a common edge. Useful when settings might be related or make sense visualy together.
+export default function MyComponent() {
+ return (
+
+
Setting content goes here
+
+ );
+}
+```
-
+## Examples
+
+### Basic SettingCard
+The basic SettingCard includes a title, description, and content area with border styling.
-## Settings Cards With seperating border
+
-Same as above with a border set.
+### Settings Cards With Shared Edge
+Two SettingCard components share a common edge for related settings.
-
+
-## Square Corners
+### Settings Cards With Separating Border
+Same as above with a border separator for visual distinction.
-Single SettingCard with no border prop set.
+
+
+### Square Corners
+Single SettingCard with no border prop set for rounded corners.
## Features
-- Consistent layout for settings sections
-- Built-in title and description handling
-- Optional border and divider styling
-- Configurable content width
-- Responsive design
-- Accessible by default
+- **Consistent Layout**: Standardized structure for settings sections
+- **Built-in Typography**: Title and description handling with proper hierarchy
+- **Optional Borders**: Configurable border and divider styling
+- **Content Width**: Flexible content width configuration
+- **Responsive Design**: Adapts to different screen sizes
+- **Accessibility**: Built-in accessibility support
+- **Dark Mode Support**: Consistent appearance in light and dark themes
## Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
-| title | string | required | The title of the settings section |
-| description | string | required | Description text for the settings section |
-| children | React.ReactNode | required | Card content |
-| className | string | undefined | Additional CSS classes |
-| border | boolean | undefined | Whether to show a border around the card |
-| contentWidth | "default" \| "full" | "default" | Width of the content area |
+| `title` | `string` | **Required** | The title of the settings section |
+| `description` | `string` | **Required** | Description text for the settings section |
+| `children` | `React.ReactNode` | **Required** | Card content |
+| `className` | `string` | `undefined` | Additional CSS classes |
+| `border` | `"top" \| "bottom" \| "both"` | `undefined` | Border styling options |
+| `contentWidth` | `"default" \| "full" \| string` | `"default"` | Width of the content area |
+
+## Structure
+
+The SettingCard component is composed of:
+
+1. **Container** - Main wrapper with border and spacing
+2. **Header Section** - Title and description area
+3. **Content Area** - Flexible content container
+4. **Border System** - Optional border styling
+
+## Styling
+
+The SettingCard component includes default styling with:
+
+- Consistent spacing and typography
+- Border options for visual separation
+- Responsive design that adapts to container size
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className prop
+
+### Border Options
+
+- **`"top"`**: Only shows a top border
+- **`"bottom"`**: Only shows a bottom border
+- **`"both"`**: Shows both top and bottom borders
+- **`undefined`**: No borders (rounded corners)
+
+### Content Width Options
+
+- **`"default"`**: Standard content width
+- **`"full"`**: Full width content
+- **Custom classes**: Any Tailwind width class (e.g., `"w-full lg:w-1/2"`)
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+ Custom content
+
+```
+
+## Accessibility
+
+The SettingCard component is built with accessibility in mind:
+
+- **Semantic HTML**: Uses appropriate HTML elements for structure
+- **Heading Hierarchy**: Maintains proper heading hierarchy for screen readers
+- **Color Contrast**: Provides sufficient color contrast between text and background
+- **Keyboard Navigation**: Supports keyboard navigation through focusable elements
+- **Screen Reader Support**: Announces card structure and content appropriately
diff --git a/apps/engineering/content/design/components/code.mdx b/apps/engineering/content/design/components/code.mdx
index 9830e16231..83b9bf31eb 100644
--- a/apps/engineering/content/design/components/code.mdx
+++ b/apps/engineering/content/design/components/code.mdx
@@ -2,19 +2,11 @@
title: Code
description: A versatile code component for displaying inline and block code snippets with customizable styling and integrated buttons.
---
-
import { CodeExample, CodeVariants } from "./code.example";
-## Features
-
-- Multiple variants (default, ghost, legacy)
-- Integrated copy and visibility buttons
-- Consistent monospace font
-- Customizable styling
-- Accessible by default
-- Responsive design
-- Focus states for better interaction
+## Overview
+The Code component provides a consistent way to display code snippets within your application. It's designed to handle both inline and block code displays, with customizable styling options and integrated button functionality for an enhanced user experience.
## Usage
```tsx
@@ -35,17 +27,25 @@ function MyComponent() {
## Examples
### Default Variant with Buttons
-
-The default variant provides a subtle background with a border and integrated buttons.
+The default variant provides a subtle background with a border and integrated buttons for copying and visibility toggling.
### Variant Styles
-
-The Code component supports different visual styles.
+The Code component supports different visual styles for various use cases.
+## Features
+
+- **Multiple Variants**: Three different visual styles (default, ghost, legacy)
+- **Integrated Buttons**: Built-in support for copy and visibility buttons
+- **Consistent Typography**: Monospace font for code readability
+- **Customizable Styling**: Extensive styling options through className props
+- **Accessibility**: Built-in accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Focus States**: Proper focus management for keyboard navigation
+
## Props
| Prop | Type | Default | Description |
@@ -65,17 +65,28 @@ The component also accepts all standard HTML pre element props.
- Subtle background with border
- White background in light mode, black in dark mode
- Gray border for visual separation
+- Ideal for code snippets with buttons
### Ghost
- Transparent background
- No border
- Minimal visual impact
+- Perfect for inline code or subtle code display
### Legacy
- Primary text color
- Subtle background
- Hover effects with primary border
- Rounded corners
+- Backward compatibility option
+
+## Structure
+
+The Code component is composed of a main container with optional button integration:
+
+1. **Code** - The main wrapper component
+2. **Buttons Container** - Optional area for copy and visibility buttons
+3. **Pre Element** - The actual code content container
## Styling
@@ -89,24 +100,28 @@ The Code component includes:
- Responsive design
- Flexible button positioning
-## Best Practices
+### Custom Styling
-- Use the default variant for code snippets with buttons
-- Use the ghost variant when you need minimal visual impact
-- Use the legacy variant for backward compatibility
-- Add appropriate padding around the code component
-- Consider using syntax highlighting for complex code blocks
-- Ensure sufficient contrast between code and background
-- Use semantic HTML structure for better accessibility
-- Position buttons appropriately using the buttonsClassName prop
+You can customize the appearance using className props:
+
+```tsx
+
+ Your code here
+
+```
## Accessibility
The Code component is built with accessibility in mind:
-- Proper ARIA attributes
-- Keyboard focus management
-- High contrast text
-- Semantic HTML structure
-- Screen reader support
-- Focus states for interactive elements
\ No newline at end of file
+- **ARIA Attributes**: Proper ARIA labels and roles for screen readers
+- **Keyboard Navigation**: Full keyboard support for all interactions
+- **Focus Management**: Clear focus indicators and logical tab order
+- **High Contrast**: Maintains proper contrast ratios
+- **Semantic HTML**: Uses appropriate HTML elements and roles
+- **Screen Reader Support**: Announces code content appropriately
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/dialogs/date-time.mdx b/apps/engineering/content/design/components/dialogs/date-time.mdx
index 03db3dc243..90336fd942 100644
--- a/apps/engineering/content/design/components/dialogs/date-time.mdx
+++ b/apps/engineering/content/design/components/dialogs/date-time.mdx
@@ -1,17 +1,136 @@
---
-title: DateTime
+title: "DateTime"
+description: "A comprehensive date and time picker component that supports both single date and date range selection with time input capabilities."
---
-import { Button } from "@unkey/ui"
-import { RenderComponentWithSnippet } from "@/app/components/render"
-import { Row } from "@/app/components/row"
import { DateTimeExample } from "./date-time.example"
+## Overview
-## Example
+The DateTime component provides a flexible and accessible date and time selection interface. It's designed to handle both single date selection and date range picking with optional time input, making it perfect for filtering, scheduling, and data analysis use cases.
-
+## Usage
+```tsx
+import { Button, DateTime, Range, TimeUnit } from "@unkey/ui";
+export default function MyComponent() {
+ const handleDateTimeChange = (date?: Range, startTime?: TimeUnit, endTime?: TimeUnit) => {
+ // Handle date and time changes
+ };
+ return (
+
+
+
+
+
+
+
+ );
+}
+```
+
+## Examples
+
+### Basic Usage
+A comprehensive example showing date range selection with time input and apply functionality.
+
+
+
+## Features
+
+- **Date Range Selection**: Support for both single date and date range picking
+- **Time Input**: Precise time selection with hours, minutes, and seconds
+- **Accessibility**: Built-in keyboard navigation and screen reader support
+- **Responsive**: Adapts to different screen sizes and orientations
+- **Customizable**: Extensive styling and configuration options
+- **Date Constraints**: Min/max date validation and disabled date ranges
+- **Context Management**: Internal state management with external change callbacks
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | `undefined` | Child components (Calendar, TimeInput, Actions) |
+| `className` | `string` | `undefined` | Additional CSS classes for the container |
+| `minDate` | `Date` | `undefined` | Minimum selectable date |
+| `maxDate` | `Date` | `undefined` | Maximum selectable date |
+| `initialRange` | `DateRange` | `undefined` | Initial date range selection |
+| `onChange` | `(date?: DateRange, start?: TimeUnit, end?: TimeUnit) => void` | `undefined` | Callback when date or time changes |
+
+### Calendar Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"single" \| "range"` | `"single"` | Calendar selection mode |
+| `className` | `string` | `undefined` | Additional CSS classes |
+| `classNames` | `Record` | `undefined` | Custom class names for calendar elements |
+| `showOutsideDays` | `boolean` | `true` | Show days from adjacent months |
+| `disabledDates` | `Array<{from?: Date, to?: Date, before?: Date, after?: Date}>` | `undefined` | Dates to disable |
+
+### TimeInput Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"single" \| "range"` | `"single"` | Time input type (single time or time range) |
+| `className` | `string` | `undefined` | Additional CSS classes |
+| `inputClassNames` | `string` | `undefined` | Custom classes for input fields |
+
+### Actions Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | `undefined` | Additional CSS classes |
+| `children` | `React.ReactNode` | `undefined` | Action buttons or content |
+
+## Structure
+
+The DateTime component is composed of several sub-components that work together:
+
+1. **DateTime** - The main container component that provides context
+2. **DateTime.Calendar** - Calendar component for date selection
+3. **DateTime.TimeInput** - Time input component for precise time selection
+4. **DateTime.Actions** - Container for action buttons
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent spacing and typography
+- Dark mode support
+- Responsive design
+- Customizable through className props
+- Focus states for accessibility
+
+### Custom Styling
+
+You can customize the appearance using className props:
+
+```tsx
+
+
+
+
+
+
+
+```
+
+## Accessibility
+
+The DateTime component is built with accessibility in mind:
+
+- **Keyboard Navigation**: Full keyboard support for all interactions
+- **Screen Reader Support**: Proper ARIA labels and announcements
+- **Focus Management**: Clear focus indicators and logical tab order
+- **High Contrast**: Maintains proper contrast ratios
+- **Semantic HTML**: Uses appropriate HTML elements and roles
+- **Date Format**: Supports various date formats and localization
diff --git a/apps/engineering/content/design/components/dialogs/dialog-container.mdx b/apps/engineering/content/design/components/dialogs/dialog-container.mdx
index e754c52ab8..da7add6d49 100644
--- a/apps/engineering/content/design/components/dialogs/dialog-container.mdx
+++ b/apps/engineering/content/design/components/dialogs/dialog-container.mdx
@@ -1,17 +1,70 @@
---
title: DialogContainer
-summary: The Dialog Container is a flexible modal component that provides a consistent way to display content in a modal dialog. It's built on top of Radix UI's Dialog primitive with additional styling and functionality.
+description: A flexible modal component that provides a consistent way to display content in a modal dialog with predefined structure and styling.
---
import { DialogContainerExample } from "./dialog-container.example"
+## Overview
+
+`DialogContainer` is a flexible modal that offers a consistent way to display content.
+
+## Usage
+
+```tsx
+import { DialogContainer } from "@unkey/ui";
+
+export default function MyComponent() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+
+ Confirm
+
+ }
+ >
+
Your dialog content here
+
+ );
+}
+```
+
+## Examples
+
+### Basic Example
+A complete example showing the DialogContainer with all its features.
+
+
+
## Features
-- Accessible modal implementation
-- Customizable overlay and content styling
-- Close button with warning support
-- Keyboard navigation support
-- Customizable animations
-- Responsive design
+- **Accessible Modal**: Accessible modal implementation with proper ARIA attributes
+- **Customizable Overlay**: Customizable overlay and content styling
+- **Close Button**: Built-in close button with warning support
+- **Keyboard Navigation**: Full keyboard navigation support
+- **Customizable Animations**: Configurable animations and transitions
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Predefined Structure**: Header, content, and footer sections
+
+## Props
+
+| Prop | Type | Default | Description |
+|-------------------|-------------------------|-----------|--------------------------------------------------|
+| `isOpen` | `boolean` | - | Controls the open state of the dialog |
+| `onOpenChange` | `(value: boolean) => void` | - | Callback when the open state changes |
+| `title` | `string` | - | The title of the dialog |
+| `subTitle` | `string` | - | Optional subtitle for the dialog |
+| `footer` | `ReactNode` | - | Optional footer content |
+| `className` | `string` | - | Additional classes for the dialog container |
+| `contentClassName` | `string` | - | Additional classes for the dialog content |
+| `preventAutoFocus` | `boolean` | `true` | Whether to prevent autofocus on open |
+| `children` | `ReactNode` | - | The content to display in the dialog |
## Structure
@@ -25,53 +78,34 @@ The DialogContainer is composed of three main parts:
The component comes with default styling that includes:
-- Responsive width and height constraints
-- Drop shadow and rounded corners
-- Overlay with backdrop blur
-- Dark mode support
-- Customizable through `className` and `contentClassName` props
+- **Responsive Width**: Responsive width and height constraints
+- **Visual Effects**: Drop shadow and rounded corners
+- **Overlay**: Overlay with backdrop blur effect
+- **Dark Mode**: Full dark mode support
+- **Customizable**: Extensive styling through `className` and `contentClassName` props
-## Usage
+### Custom Styling
+
+You can customize the appearance using className props:
```tsx
- Confirm
-
- }
+ title="Custom Dialog"
+ className="custom-dialog-class"
+ contentClassName="custom-content-class"
>
-
Your dialog content here
+ Custom content
```
-### Basic Example
-
-
-
-## Props
-
-| Prop | Type | Default | Description |
-|-------------------|-------------------------|-----------|--------------------------------------------------|
-| isOpen | boolean | - | Controls the open state of the dialog |
-| onOpenChange | (value: boolean) => void | - | Callback when the open state changes |
-| title | string | - | The title of the dialog |
-| subTitle | string | - | Optional subtitle for the dialog |
-| footer | ReactNode | - | Optional footer content |
-| className | string | - | Additional classes for the dialog container |
-| contentClassName | string | - | Additional classes for the dialog content |
-| preventAutoFocus | boolean | true | Whether to prevent auto-focus on open |
-| children | ReactNode | - | The content to display in the dialog |
-
## Accessibility
The DialogContainer implements the following accessibility features:
-- Manages focus trap within the dialog
-- Supports keyboard navigation (Esc to close)
-- Proper ARIA attributes for screen readers
-- Focus management can be controlled via `preventAutoFocus`
+- **Focus Management**: Manages focus trap within the dialog
+- **Keyboard Support**: Supports keyboard navigation (Esc to close)
+- **ARIA Attributes**: Proper ARIA attributes for screen readers
+- **Focus Control**: Focus management can be controlled via `preventAutoFocus`
+- **Screen Reader Support**: Announces dialog state changes appropriately
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/dialogs/dialog.mdx b/apps/engineering/content/design/components/dialogs/dialog.mdx
index 380d492cde..acfeab9538 100644
--- a/apps/engineering/content/design/components/dialogs/dialog.mdx
+++ b/apps/engineering/content/design/components/dialogs/dialog.mdx
@@ -1,35 +1,15 @@
---
title: Dialog
-summary: The Dialog component is a foundational modal component built on top of Radix UI's Dialog primitive. It provides accessible modal functionality with customizable styling and behavior options.
+description: A foundational modal component built on Radix UI primitives with accessible modal functionality, customizable styling, and flexible behavior options.
---
import { DialogExample } from "./dialog.example"
-## Features
-
-- **Accessible**: Built on Radix UI primitives with full accessibility support
-- **Flexible**: Composable components for custom layouts
-- **Close Warning Support**: Optional confirmation when closing dialogs
-- **Keyboard Navigation**: Full keyboard support including Escape to close
-- **Customizable**: Extensive styling options through className props
-- **TypeScript**: Full TypeScript support with proper type definitions
-
-## Structure
+## Overview
-The Dialog component is composed of several sub-components that work together:
-
-1. **Dialog** - The root component that manages dialog state
-2. **DialogTrigger** - The element that opens the dialog
-3. **DialogContent** - The main dialog container with overlay
-4. **DialogHeader** - Container for title and description
-5. **DialogTitle** - The dialog's title
-6. **DialogDescription** - Optional description text
-7. **DialogFooter** - Container for action buttons
-8. **DialogClose** - Component that closes the dialog when clicked
+The Dialog component provides a comprehensive modal system for displaying content in overlay dialogs. It's built on top of Radix UI's Dialog primitive with additional styling and functionality, offering accessible modal behavior with customizable appearance and flexible composition patterns.
## Usage
-### Basic Dialog
-
```tsx
import {
Dialog,
@@ -42,143 +22,125 @@ import {
DialogClose,
} from "@unkey/ui";
-
+export default function MyComponent() {
+ return (
+
+ );
+}
```
-### Controlled Dialog
-
-```tsx
-import { useState } from "react";
-
-const [isOpen, setIsOpen] = useState(false);
-
-
-```
+## Examples
-### Dialog with Close Warning
+### Basic Dialog
+A complete example showing various dialog patterns and configurations.
-```tsx
-
-```
+
-### Example
+## Features
-
+- **Accessible**: Built on Radix UI primitives with full accessibility support
+- **Flexible**: Composable components for custom layouts
+- **Close Warning Support**: Optional confirmation when closing dialogs
+- **Keyboard Navigation**: Full keyboard support including Escape to close
+- **Customizable**: Extensive styling options through className props
+- **TypeScript**: Full TypeScript support with proper type definitions
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Responsive Design**: Adapts to different screen sizes
-## Component Props
+## Props
### Dialog
| Prop | Type | Default | Description |
|-------------|-------------------------|---------|------------------------------------------------|
-| open | boolean | - | Controls the open state of the dialog |
-| onOpenChange | (value: boolean) => void | - | Callback when the open state changes |
-| children | ReactNode | - | The dialog content |
+| `open` | `boolean` | - | Controls the open state of the dialog |
+| `onOpenChange` | `(value: boolean) => void` | - | Callback when the open state changes |
+| `children` | `ReactNode` | - | The dialog content |
### DialogContent
| Prop | Type | Default | Description |
|-------------------|-------------------------|---------|--------------------------------------------------|
-| showCloseWarning | boolean | false | Whether to show warning when closing |
-| onAttemptClose | () => void | - | Callback when user attempts to close |
-| xButtonRef | RefObject<HTMLButtonElement> | - | Ref for the close button |
-| className | string | - | Additional classes for the dialog content |
-| children | ReactNode | - | The content to display in the dialog |
+| `showCloseWarning` | `boolean` | `false` | Whether to show warning when closing |
+| `onAttemptClose` | `() => void` | - | Callback when user attempts to close |
+| `xButtonRef` | `RefObject` | - | Ref for the close button |
+| `className` | `string` | - | Additional classes for the dialog content |
+| `children` | `ReactNode` | - | The content to display in the dialog |
### DialogTrigger
| Prop | Type | Default | Description |
|----------|-----------|---------|--------------------------------|
-| asChild | boolean | false | Whether to render as child element |
-| children | ReactNode | - | The trigger element |
+| `asChild` | `boolean` | `false` | Whether to render as child element |
+| `children` | `ReactNode` | - | The trigger element |
### DialogClose
| Prop | Type | Default | Description |
|----------|-----------|---------|--------------------------------|
-| asChild | boolean | false | Whether to render as child element |
-| children | ReactNode | - | The close trigger element |
+| `asChild` | `boolean` | `false` | Whether to render as child element |
+| `children` | `ReactNode` | - | The close trigger element |
### DialogHeader
| Prop | Type | Default | Description |
|----------|--------|---------|--------------------------------|
-| className | string | - | Additional classes for header |
-| children | ReactNode | - | Header content |
+| `className` | `string` | - | Additional classes for header |
+| `children` | `ReactNode` | - | Header content |
### DialogFooter
| Prop | Type | Default | Description |
|----------|--------|---------|--------------------------------|
-| className | string | - | Additional classes for footer |
-| children | ReactNode | - | Footer content |
+| `className` | `string` | - | Additional classes for footer |
+| `children` | `ReactNode` | - | Footer content |
### DialogTitle
| Prop | Type | Default | Description |
|----------|--------|---------|--------------------------------|
-| className | string | - | Additional classes for title |
-| children | ReactNode | - | Title content |
+| `className` | `string` | - | Additional classes for title |
+| `children` | `ReactNode` | - | Title content |
### DialogDescription
| Prop | Type | Default | Description |
|----------|--------|---------|--------------------------------|
-| className | string | - | Additional classes for description |
-| children | ReactNode | - | Description content |
+| `className` | `string` | - | Additional classes for description |
+| `children` | `ReactNode` | - | Description content |
+
+
+## Structure
+
+The Dialog component is composed of several sub-components that work together:
+
+1. **Dialog** - The root component that manages dialog state
+2. **DialogTrigger** - The element that opens the dialog
+3. **DialogContent** - The main dialog container with overlay
+4. **DialogHeader** - Container for title and description
+5. **DialogTitle** - The dialog's title
+6. **DialogDescription** - Optional description text
+7. **DialogFooter** - Container for action buttons
+8. **DialogClose** - Component that closes the dialog when clicked
## Styling
@@ -213,16 +175,4 @@ The Dialog component implements the following accessibility features:
- **Keyboard Navigation**: Full keyboard support (Escape to close, Tab navigation)
- **ARIA Attributes**: Proper ARIA labels and roles for screen readers
- **Focus Trap**: Prevents focus from leaving the dialog when open
-- **Screen Reader Support**: Announces dialog state changes
-
-### Keyboard Shortcuts
-
-- **Escape**: Closes the dialog (unless `showCloseWarning` is true)
-- **Tab**: Navigates through focusable elements within the dialog
-- **Shift + Tab**: Navigates backwards through focusable elements
-
-## Related Components
-
-- **[DialogContainer](./dialog-container.mdx)** - Higher-level dialog component with predefined structure
-- **[NavigableDialog](./navigable-dialog.mdx)** - Multi-step dialog with navigation
-- **[DateTime](./date-time.mdx)** - Date and time picker dialog component
\ No newline at end of file
+- **Screen Reader Support**: Announces dialog state changes
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/dialogs/navigable-dialog.mdx b/apps/engineering/content/design/components/dialogs/navigable-dialog.mdx
index fd60dafc47..b86d1d6974 100644
--- a/apps/engineering/content/design/components/dialogs/navigable-dialog.mdx
+++ b/apps/engineering/content/design/components/dialogs/navigable-dialog.mdx
@@ -1,39 +1,12 @@
---
title: NavigableDialog
-summary: The Navigable Dialog is a multi-step modal component that provides a consistent way to display content with navigation between different sections. It's built on top of the Dialog Container with additional navigation capabilities.
+summary: "The Navigable Dialog is a multi-step modal component that provides a consistent way to display content with navigation between different sections."
---
import { NavigableDialogExample } from "./navigable-dialog.example";
-## Features
-
-- Multi-step navigation with sidebar
-- Icon support for navigation items
-- Accessible modal implementation
-- State management between steps
-- Customizable styling for each section
-- Keyboard navigation support
-- Responsive design
-
-## Structure
-
-The NavigableDialog is composed of several components that work together:
-
-1. **NavigableDialogRoot** - The container component that manages dialog state
-2. **NavigableDialogHeader** - Contains the title and optional subtitle
-3. **NavigableDialogBody** - Wrapper for navigation and content
-4. **NavigableDialogNav** - Sidebar navigation with icons and labels
-5. **NavigableDialogContent** - The main content area that displays the active section
-6. **NavigableDialogFooter** - Optional section for actions like buttons
+## Overview
-## Styling
-
-The component includes default styling with:
-
-- Responsive layout with side navigation
-- Smooth transitions between sections
-- Icon support in navigation items
-- Dark mode support
-- Customizable through className props
+The Navigable Dialog is a multi-step modal component that provides a consistent way to display content with navigation between different sections. It’s built on top of the `DialogContainer` component, with additional navigation capabilities.
## Usage
@@ -75,7 +48,20 @@ The component includes default styling with:
-## Component Props
+## Variants
+
+The component accepts all standard DialogContainer props.
+
+## Features
+
+- Multi-step navigation with sidebar
+- Icon support for navigation items
+- Accessible modal implementation
+- State management between steps
+- Customizable styling for each section
+- Full keyboard-navigation support
+- Responsive design
+## Props
### NavigableDialogRoot
@@ -111,6 +97,27 @@ The component includes default styling with:
| title | string | - | The title of the dialog |
| subTitle | string | - | Optional subtitle for the dialog|
+## Structure
+
+The NavigableDialog is composed of several components that work together:
+
+1. **NavigableDialogRoot** - The container component that manages dialog state
+2. **NavigableDialogHeader** - Contains the title and optional subtitle
+3. **NavigableDialogBody** - Wrapper for navigation and content
+4. **NavigableDialogNav** - Sidebar navigation with icons and labels
+5. **NavigableDialogContent** - The main content area that displays the active section
+6. **NavigableDialogFooter** - Optional section for actions like buttons
+
+## Styling
+
+The component includes default styling with:
+
+- Responsive layout with side navigation
+- Smooth transitions between sections
+- Icon support in navigation items
+- Dark mode support
+- Customizable through className props
+
## Accessibility
The NavigableDialog implements the following accessibility features:
diff --git a/apps/engineering/content/design/components/empty.mdx b/apps/engineering/content/design/components/empty.mdx
index e7dae14058..07f1ae655b 100644
--- a/apps/engineering/content/design/components/empty.mdx
+++ b/apps/engineering/content/design/components/empty.mdx
@@ -1,34 +1,123 @@
---
title: Empty
+description: A component for displaying empty states when data is missing, with customizable content and actions.
---
import { EmptyExample } from "./empty.examples";
-
## Overview
-The `` component should be used when data is missing, replacing the normal component.
-
-
-## Empty.Icon
-
-The `` is a default `` icon with styling.
-
-
-## Empty.Title
+The Empty component provides a consistent way to display empty states throughout your application. It's designed to replace normal content when data is missing, offering users clear context and actionable next steps.
-The `` is used to display a title within the `` component. It can be utilized to emphasize text or provide a warning.
+## Usage
+```tsx
+import { Button, Empty } from "@unkey/ui";
-## Empty.Description
+export default function MyComponent() {
+ return (
+
+
+ No Data Found
+ There are no items to display.
+
+
+
+
+ );
+}
+```
-The `` explains why the `` component is displayed instead of data.
+## Examples
-
-## Empty.Actions
-
-The `` offers the user one or multiple actions to resolve the lack of data. For instance, if there are too many filters on a table, a button can be added to remove those filters.
-
-
-## Full Example
+### Basic Empty State
+A complete empty state with icon, title, description, and action button.
+
+## Features
+
+- **Composable Structure**: Modular components for flexible layouts
+- **Default Icon**: Built-in UFO icon with consistent styling
+- **Customizable Content**: Flexible title, description, and action areas
+- **Accessibility**: Built-in accessibility support
+- **Responsive Design**: Adapts to different screen sizes
+- **Consistent Styling**: Matches design system standards
+
+## Props
+
+### Empty (Main Container)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Empty state content components |
+| `className` | `string` | `undefined` | Additional CSS classes |
+
+### Empty.Icon
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | `undefined` | Additional CSS classes for the icon |
+
+### Empty.Title
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Title text content |
+| `className` | `string` | `undefined` | Additional CSS classes |
+
+### Empty.Description
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Description text content |
+| `className` | `string` | `undefined` | Additional CSS classes |
+
+### Empty.Actions
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Action buttons or links |
+| `className` | `string` | `undefined` | Additional CSS classes |
+
+## Structure
+
+The Empty component is composed of several subcomponents that work together:
+
+1. **Empty** - The main container component
+2. **Empty.Icon** - Default UFO icon with styling
+3. **Empty.Title** - Main heading text for emphasis
+4. **Empty.Description** - Explanatory text about the empty state
+5. **Empty.Actions** - Container for action buttons or links
+
+## Styling
+
+The Empty component includes default styling with:
+
+- Centered layout with consistent spacing
+- Typography hierarchy for title and description
+- Icon styling with appropriate sizing
+- Action area with button spacing
+- Responsive design
+- Dark mode support
+
+### Custom Styling
+
+You can customize the appearance using className props:
+
+```tsx
+
+
+ Custom Title
+
+ Custom description text
+
+
+
+
+
+```
+
+## Accessibility
+
+The Empty component is built with accessibility in mind:
+
+- **Semantic HTML**: Uses appropriate heading elements for titles
+- **Screen Reader Support**: Proper text hierarchy and descriptions
+- **Focus Management**: Logical tab order for action buttons
+- **High Contrast**: Maintains proper contrast ratios
+- **Descriptive Content**: Clear explanations of empty states
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/filter/control-cloud.mdx b/apps/engineering/content/design/components/filter/control-cloud.mdx
index b3a08ce525..22b48850a8 100644
--- a/apps/engineering/content/design/components/filter/control-cloud.mdx
+++ b/apps/engineering/content/design/components/filter/control-cloud.mdx
@@ -1,6 +1,6 @@
---
title: ControlCloud
-description: A dynamic filter display component that shows active filters as interactive pills with keyboard navigation and removal capabilities.
+description: A dynamic filter display component that shows active filters as interactive pills with keyboard navigation and removal capabilities for enhanced data filtering interfaces.
---
import {
BasicControlCloud,
@@ -10,6 +10,10 @@ import {
InteractiveExample
} from "./control-cloud.examples";
+## Overview
+
+The ControlCloud component provides a dynamic way to display active filters as interactive pills. It's designed to show users what filters are currently applied to their data, with keyboard navigation, removal capabilities, and customizable formatting for enhanced data filtering interfaces.
+
## Usage
```tsx
@@ -106,6 +110,40 @@ type FilterValue = {
};
```
+## Structure
+
+The ControlCloud component is composed of:
+
+1. **Filter Pills Container** - Wrapper for all filter pills
+2. **Individual Filter Pills** - Each filter displayed as a removable pill
+3. **Keyboard Navigation System** - Handles focus and navigation
+4. **Time Display Components** - Special formatting for time-based filters
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent pill styling with hover and focus states
+- Color-coded filter types for visual distinction
+- Responsive design that adapts to container width
+- Dark mode support with appropriate color schemes
+- Focus indicators for keyboard navigation
+- Customizable through className props
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
+
## Keyboard Navigation
The ControlCloud component provides comprehensive keyboard navigation:
@@ -125,43 +163,6 @@ The ControlCloud component provides comprehensive keyboard navigation:
- **`⌥+⇧+D`**: Clear all filters and set a default time range (endTime = now, startTime = now - historicalWindow)
- **`⌥+⇧+C`**: Focus the first filter pill for keyboard navigation
-## Customization
-
-### Field Name Formatting
-
-Customize how field names are displayed:
-
-```tsx
-const formatFieldName = (field: string): string => {
- switch (field) {
- case "startTime":
- return "Start time";
- case "endTime":
- return "End time";
- case "status":
- return "Status";
- default:
- return field.charAt(0).toUpperCase() + field.slice(1);
- }
-};
-```
-
-### Value Formatting
-
-Customize how values are displayed:
-
-```tsx
-const formatValue = (value: string | number, field: string): string => {
- if (field === "duration") {
- return `${value}ms`;
- }
- if (field === "status") {
- return `HTTP ${value}`;
- }
- return String(value);
-};
-```
-
## Accessibility
The ControlCloud component is built with accessibility in mind:
@@ -170,29 +171,4 @@ The ControlCloud component is built with accessibility in mind:
- **Screen Reader Support**: Proper ARIA labels and announcements
- **Focus Management**: Clear focus indicators and logical tab order
- **High Contrast**: Maintains proper contrast ratios
-- **Semantic HTML**: Uses appropriate HTML elements and roles
-
-## Best Practices
-
-- **Consistent Field Names**: Use consistent field name formatting across your application
-- **Clear Value Display**: Format values in a user-friendly way
-- **Keyboard Shortcuts**: Document keyboard shortcuts for power users
-- **Empty State**: Handle the empty state gracefully (component is hidden when no filters)
-- **Filter Management**: Implement proper filter state management in your application
-- **Time Windows**: Set appropriate historical windows for time-based shortcuts
-- **Performance**: Consider memoizing format functions for large filter arrays
-
-## Integration
-
-The ControlCloud component is commonly used with:
-
-- **Data Tables**: Display active filters above table content
-- **Log Viewers**: Show applied log filters
-- **Analytics Dashboards**: Display metric filters
-- **Search Interfaces**: Show active search criteria
-
-## Related Components
-
-- **ControlPill**: Individual filter pill component (internal)
-- **TimestampInfo**: Time display component for time-based filters
-- **KeyboardButton**: Keyboard shortcut display component
\ No newline at end of file
+- **Semantic HTML**: Uses appropriate HTML elements and roles
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/form-inputs/checkbox.mdx b/apps/engineering/content/design/components/form-inputs/checkbox.mdx
index d51ccd8e20..4de3566b93 100644
--- a/apps/engineering/content/design/components/form-inputs/checkbox.mdx
+++ b/apps/engineering/content/design/components/form-inputs/checkbox.mdx
@@ -1,9 +1,7 @@
---
title: "Checkbox"
-description: "A versatile checkbox component with multiple variants, states, and sizes"
+description: "A versatile checkbox component with multiple variants, states, and sizes for creating accessible, user-friendly selection inputs."
---
-import { RenderComponentWithSnippet } from "@/app/components/render";
-import { Check } from "@unkey/icons";
import {
CheckboxBasicVariants,
CheckboxOutlineVariants,
@@ -25,162 +23,224 @@ import {
CheckboxGroupExample,
} from "./checkbox.examples";
-## Basic Variants
+## Overview
-Checkbox comes in three basic variants that serve different UI purposes:
+The Checkbox component provides a versatile checkbox system that supports various styles, states, and interactive features. It's built with accessibility in mind and provides consistent interaction patterns across all variants, making it adaptable to any UI context while maintaining proper focus states and keyboard interactions.
-### Primary
+## Usage
+
+```tsx
+import { Checkbox } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+
+
+
+
+ );
+}
+```
+## Examples
+
+### Basic Variants
+Checkbox comes in three basic variants that serve different UI purposes:
+
+#### Primary
The default checkbox style with a solid background when checked. Use for primary selection actions.
-### Outline
-
+#### Outline
Checkbox with transparent background and visible border when checked. Ideal for secondary selection actions that don't require as much visual emphasis.
-### Ghost
-
+#### Ghost
Checkbox with no background when unchecked and subtle hover states. Perfect for tertiary selection actions or when space is limited.
-## Color Variants
-
+### Color Variants
Each checkbox variant can be combined with different color schemes to convey the nature of the selection:
-### Danger - Primary
+#### Danger Variants
+***Primary***
-### Danger - Outline
+***Outline***
-### Danger - Ghost
+***Ghost***
-### Warning - Primary
+#### Warning Variants
+***Primary***
-### Warning - Outline
+***Outline***
-### Warning - Ghost
+***Ghost***
-### Success - Primary
+#### Success Variants
+***Primary***
-### Success - Outline
+***Outline***
-### Success - Ghost
+***Ghost***
-### Info - Primary
+#### Info Variants
+***Primary***
-### Info - Outline
+***Outline***
-### Info - Ghost
+***Ghost***
-## Size Variants
-
+### Size Variants
All checkbox variants and color schemes can be combined with different sizes to fit various UI contexts.
-## With Labels
-
+### With Labels
Checkbox components can be combined with labels for better user experience.
-## Checkbox Group Example
-
+### Checkbox Group
Checkboxes can be grouped together for related selection options.
-## Additional Features
+## Features
-The Checkbox component includes some additional features not shown in all examples above:
+- **Multiple Variants**: Three basic variants (primary, outline, ghost) with different visual emphasis
+- **Color Schemes**: Five color options (default, danger, warning, success, info) for semantic meaning
+- **Size Options**: Multiple sizes for different contexts and touch targets
+- **Interactive States**: Hover, focus, checked, and disabled states
+- **Accessibility**: Full accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Keyboard Support**: Full keyboard navigation and shortcuts
-### Legacy Variant Support
+## Props
-For backward compatibility, the component supports legacy variants:
-- `default` will be mapped to `primary` variant
-- `destructive` will be mapped to `primary` variant with `danger` color
+The Checkbox component accepts all standard HTML input attributes plus the following:
-### Customizing Indicator
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "outline" \| "ghost"` | `"primary"` | The variant style to use for the checkbox |
+| `color` | `"default" \| "success" \| "warning" \| "danger" \| "info"` | `"default"` | The color scheme to use for the checkbox |
+| `size` | `"sm" \| "md" \| "lg" \| "xlg"` | `"md"` | The size of the checkbox |
+| `checked` | `boolean` | - | Whether the checkbox is checked |
+| `defaultChecked` | `boolean` | - | Default checked state when uncontrolled |
+| `disabled` | `boolean` | - | Whether the checkbox is disabled |
+| `required` | `boolean` | - | Required state for the checkbox |
+| `name` | `string` | - | Name of the checkbox for form submission |
+| `value` | `string` | - | Value of the checkbox for form submission |
+| `onCheckedChange` | `(checked: boolean) => void` | - | Callback triggered when checkbox state changes |
+| `className` | `string` | - | Additional CSS classes to apply |
+
+## Variants
-The Checkbox uses the `Check` component from `@unkey/icons` as the default indicator when checked. The icon size adapts automatically to the size of the checkbox.
+### Primary
+- Solid background when checked
+- Use for primary selection actions
+- Default variant for most use cases
-## Props
+### Outline
+- Transparent background with visible border when checked
+- Secondary selection actions with moderate emphasis
+- Good for forms and secondary actions
-The Checkbox component accepts all standard HTML input attributes plus the following:
+### Ghost
+- No background when unchecked and subtle hover states
+- Tertiary selection actions or minimal visual impact
+- Perfect for dense UIs or subtle interactions
-
+## Color Schemes
+
+### Default
+- Neutral styling for general selections
+- Gray/blue color scheme
+- Most common choice for standard selections
+
+### Danger
+- Red color scheme for critical selections
+- Use for potentially destructive or critical operations
+- Should be used sparingly and with clear intent
+
+### Warning
+- Yellow/orange color scheme for cautionary selections
+- Use for selections that require attention but aren't destructive
+- Good for confirmations or warnings
-## Implementation Details
+### Success
+- Green color scheme for positive selections
+- Use for confirming or positive operations
+- Encourages positive user actions
-The Checkbox component is built with Radix UI's `@radix-ui/react-checkbox` primitive for accessibility and proper keyboard navigation. It includes:
+### Info
+- Blue color scheme for informational selections
+- Use for neutral or informational operations
+- Good for educational or informational contexts
-- Custom styling for all states: unchecked, checked, disabled, and focus
-- Support for different variants through CSS variable variants
-- Automatic icon size adjustment based on checkbox size
-- Proper ARIA attributes for screen readers
+## Structure
-## Usage Guidelines
+The Checkbox component is a self-contained component that renders as a single checkbox element with appropriate styling, accessibility attributes, and optional icon support.
-When using the Checkbox component:
+## Styling
-- **Semantic meaning**: Choose appropriate colors to match the semantic meaning of your checkboxes
- - Use **default** for standard selections without specific connotations
- - Use **success** for positive or confirming selections
- - Use **warning** for cautionary selections that require attention
- - Use **danger** for critical or potentially destructive selections
- - Use **info** for informational or neutral selections
+The Checkbox component includes default styling with:
-- **Accessibility**:
- - Always pair checkboxes with visible labels that clearly describe the selection
- - Ensure sufficient color contrast between the checkbox and its background
- - Group related checkboxes together with a descriptive group label
- - Test keyboard navigation (Tab to focus, Space to toggle)
+- Consistent sizing and border radius across variants
+- Color-coded schemes for semantic meaning
+- Smooth transitions for state changes
+- Dark mode support
+- Responsive design
+- Focus states for accessibility
+- Customizable through className prop
-- **Interaction design**:
- - Use appropriate sizing based on the context and target devices (consider touch targets for mobile)
- - Maintain consistent spacing between checkboxes in a group
- - Provide clear visual feedback for all states (hover, focus, checked, disabled)
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
-- **Content guidelines**:
- - Write clear, concise labels that describe the option being selected
- - Use sentence case for checkbox labels
- - For groups of checkboxes, use a descriptive heading that explains the purpose of the group
+## Accessibility
-- **Form design**:
- - Consider using the `required` attribute when a checkbox must be checked to proceed
- - For lengthy terms and conditions, consider linking to the full text rather than showing it all
- - For mutually exclusive options, consider using radio buttons instead
+The Checkbox component is built with accessibility in mind:
-- **Responsive design**:
- - Ensure checkboxes and their labels are properly sized and spaced on all devices
- - Consider stacking checkboxes vertically on smaller screens for better touch targets
+- **Semantic HTML**: Uses proper checkbox element with appropriate roles
+- **ARIA Attributes**: Proper ARIA labels and states for screen readers
+- **Keyboard Navigation**: Full keyboard support including Tab and Space
+- **Focus Management**: Clear focus indicators and logical tab order
+- **Screen Reader Support**: Announces checkbox states and actions appropriately
+- **High Contrast**: Maintains proper contrast ratios across all variants
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/form-inputs/form-checkbox.mdx b/apps/engineering/content/design/components/form-inputs/form-checkbox.mdx
new file mode 100644
index 0000000000..15c12d5cb7
--- /dev/null
+++ b/apps/engineering/content/design/components/form-inputs/form-checkbox.mdx
@@ -0,0 +1,261 @@
+---
+title: FormCheckbox
+description: A form checkbox component with built-in label, description, and error handling capabilities for creating accessible, user-friendly selection inputs.
+---
+import {
+ DefaultFormCheckboxVariant,
+ RequiredFormCheckboxVariant,
+ RequiredWithErrorFormCheckboxVariant,
+ OptionalFormCheckboxVariant,
+ SuccessFormCheckboxVariant,
+ WarningFormCheckboxVariant,
+ ErrorFormCheckboxVariant,
+ DisabledFormCheckboxVariant,
+ CheckedFormCheckboxVariant,
+ OutlineFormCheckboxVariant,
+ GhostFormCheckboxVariant,
+ LargeFormCheckboxVariant,
+ MediumFormCheckboxVariant,
+ SmallFormCheckboxVariant,
+ XLargeFormCheckboxVariant,
+ ComplexFormCheckboxVariant
+} from "./form-checkbox.variants"
+
+## Overview
+
+The FormCheckbox component provides a comprehensive checkbox system that combines labels, descriptions, and validation states. It's designed to create accessible, user-friendly forms that require selection inputs with proper labeling, helpful context, and clear validation feedback while maintaining consistency with the design system.
+
+## Usage
+
+```tsx
+import { FormCheckbox } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+ );
+}
+```
+
+## Examples
+
+### Default FormCheckbox
+
+The default FormCheckbox includes a label and optional description text, providing clear context for users.
+
+
+
+### Required Field
+
+Use the required prop to indicate mandatory fields. This automatically adds a "Required" tag to the label.
+
+
+
+### Required Field with Error
+
+When a required field has an error, the "Required" tag changes to error styling to draw more attention.
+
+
+
+### Optional Field
+
+Use the optional prop to explicitly indicate non-mandatory fields. This adds an "Optional" badge to the label.
+
+
+
+### Success State
+
+Indicates successful validation or acceptance of selection. The success icon and text provide positive feedback.
+
+
+
+### Warning State
+
+Used for potentially impactful selections that should be made with caution. Includes a warning icon and explanatory text.
+
+
+
+### Error State
+
+Shows validation errors or other issues that need user attention. Features prominent error styling and message.
+
+
+
+### Disabled State
+
+Apply when the field should be non-interactive, such as during form submission or based on other field values.
+
+
+
+### Checked State
+
+Pre-selected checkbox with an initial checked state that users can toggle.
+
+
+
+### Outline Variant
+
+A subtler alternative to the primary variant with transparent background when checked.
+
+
+
+### Ghost Variant
+
+The most minimal styling for checkboxes that need less visual emphasis.
+
+
+
+### Different Sizes
+
+Checkboxes can be sized appropriately for different UI needs.
+
+#### Small
+
+
+
+#### Medium
+
+
+
+#### Large
+
+
+
+#### XLarge
+
+
+
+### Complex Usage
+Example of FormCheckboxes with multiple props configured for a specific use case, such as a cookie consent form.
+
+
+
+## Features
+
+- **Built-in Labeling**: Automatic label association with proper accessibility
+- **Description Support**: Optional helper text for additional context
+- **Validation States**: Multiple states (success, warning, error) with appropriate styling
+- **Required/Optional Indicators**: Clear visual indicators for field requirements
+- **Multiple Variants**: Different visual styles (default, outline, ghost) for various contexts
+- **Size Options**: Different sizes for different UI needs
+- **Accessibility**: Full accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Customizable**: Extensive styling options through className props
+
+## Props
+
+The FormCheckbox component extends the standard Checkbox component props with additional form-specific properties:
+
+| Prop | Type | Default | Description |
+|--------------------|--------------------------------------------------------------------------|-------------|-------------------------------------------------------|
+| `label` | `string` | - | The label text to display next to the checkbox |
+| `description` | `string \| React.ReactNode` | - | Optional helper text displayed below the checkbox |
+| `required` | `boolean` | - | Whether the field is required. Adds a "Required" indicator |
+| `optional` | `boolean` | - | Whether the field is optional. Adds an "Optional" indicator |
+| `error` | `string` | - | Error message to display. Overrides description and applies error styling |
+| `variant` | `"primary" \| "outline" \| "ghost"` | `"primary"` | The variant style to use for the checkbox |
+| `color` | `"default" \| "success" \| "warning" \| "danger" \| "info"` | `"default"` | The color scheme to use for the checkbox |
+| `size` | `"sm" \| "md" \| "lg" \| "xlg"` | `"md"` | The size of the checkbox |
+| `checked` | `boolean` | `false` | Whether the checkbox is checked |
+| `defaultChecked` | `boolean` | - | Default checked state when uncontrolled |
+| `disabled` | `boolean` | - | Whether the checkbox is disabled |
+| `name` | `string` | - | Name of the checkbox for form submission |
+| `value` | `string` | - | Value of the checkbox for form submission |
+| `onCheckedChange` | `(checked: boolean) => void` | - | Callback triggered when checkbox state changes |
+| `className` | `string` | - | Additional CSS classes to apply |
+| `id` | `string` | - | Unique identifier for the checkbox. Auto-generated if not provided |
+
+## Variants
+
+### Default
+- Standard checkbox with label and optional description
+- Use for most checkbox inputs
+- Balanced visual weight and accessibility
+
+### Required
+- Includes "Required" indicator for mandatory fields
+- Use for fields that must be completed
+- Clear visual indication of importance
+
+### Optional
+- Includes "Optional" indicator for non-mandatory fields
+- Use for fields that can be left empty
+- Provides clarity in forms with mixed requirements
+
+### Success
+- Green styling for positive validation states
+- Use for successfully validated selections
+- Encourages positive user feedback
+
+### Warning
+- Yellow/orange styling for cautionary states
+- Use for selections that need attention but aren't errors
+- Indicates potential issues
+
+### Error
+- Red styling for validation errors
+- Use for failed validation or critical issues
+- Clearly indicates problems that need resolution
+
+### Outline
+- Subtler styling with transparent background when checked
+- Use for less prominent selections
+- Good for secondary options
+
+### Ghost
+- Minimal styling for checkboxes that need less visual emphasis
+- Use for tertiary or subtle selections
+- Perfect for dense UIs
+
+## Structure
+
+The FormCheckbox component is composed of:
+
+1. **Checkbox Element** - The actual checkbox input with validation states
+2. **Label Container** - Contains the label text and required/optional indicators
+3. **Description Text** - Optional helper text below the checkbox
+4. **Error Message** - Validation error display when applicable
+5. **Status Icons** - Visual indicators for different states
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent spacing and typography from design system
+- Color-coded validation states for semantic meaning
+- Proper label positioning and association
+- Multiple visual variants for different contexts
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className props
+
+### Custom Styling
+
+You can customize the appearance using className props:
+
+```tsx
+
+```
+
+## Accessibility
+
+The FormCheckbox component is built with accessibility in mind:
+
+- **Label Association**: Labels are properly associated with checkboxes using htmlFor/id
+- **Error Announcements**: Error messages are announced to screen readers using role="alert"
+- **Required Indicators**: Required fields are marked both visually and via aria-required
+- **Helper Text**: Helper text is linked to checkboxes using aria-describedby
+- **Validation States**: Error states are indicated using aria-invalid
+- **Focus Management**: Checkboxes maintain proper focus states for keyboard navigation
+- **Screen Reader Support**: Announces validation states and requirements appropriately
+- **Keyboard Navigation**: Full keyboard support for all interactions
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/form-inputs/form-checkbox.variants.tsx b/apps/engineering/content/design/components/form-inputs/form-checkbox.variants.tsx
index c5b6968a24..ce2f8fc838 100644
--- a/apps/engineering/content/design/components/form-inputs/form-checkbox.variants.tsx
+++ b/apps/engineering/content/design/components/form-inputs/form-checkbox.variants.tsx
@@ -216,6 +216,24 @@ export const GhostFormCheckboxVariant = () => {
};
// Different size variant
+export const XLargeFormCheckboxVariant = () => {
+ return (
+ `}
+ >
+
+
+ );
+};
+
export const LargeFormCheckboxVariant = () => {
return (
{
);
};
+export const MediumFormCheckboxVariant = () => {
+ return (
+ `}
+ >
+
+
+ );
+};
+
+export const SmallFormCheckboxVariant = () => {
+ return (
+ `}
+ >
+
+
+ );
+};
+
// Complex example with multiple props
export const ComplexFormCheckboxVariant = () => {
return (
diff --git a/apps/engineering/content/design/components/form-inputs/form-chekbox.mdx b/apps/engineering/content/design/components/form-inputs/form-chekbox.mdx
deleted file mode 100644
index 11c26471ad..0000000000
--- a/apps/engineering/content/design/components/form-inputs/form-chekbox.mdx
+++ /dev/null
@@ -1,145 +0,0 @@
----
-title: FormCheckbox
-description: A form checkbox component with built-in label, description, and error handling capabilities.
----
-import {
- DefaultFormCheckboxVariant,
- RequiredFormCheckboxVariant,
- RequiredWithErrorFormCheckboxVariant,
- OptionalFormCheckboxVariant,
- SuccessFormCheckboxVariant,
- WarningFormCheckboxVariant,
- ErrorFormCheckboxVariant,
- DisabledFormCheckboxVariant,
- CheckedFormCheckboxVariant,
- OutlineFormCheckboxVariant,
- GhostFormCheckboxVariant,
- LargeFormCheckboxVariant,
- ComplexFormCheckboxVariant
-} from "./form-checkbox.variants"
-
-## Default
-
-The default FormCheckbox includes a label and optional description text, providing clear context for users.
-
-
-
-## Checkbox States
-
-### Required Field
-
-Use the required prop to indicate mandatory fields. This automatically adds a "Required" tag to the label.
-
-
-
-### Required Field with Error
-
-When a required field has an error, the "Required" tag changes to error styling to draw more attention.
-
-
-
-### Optional Field
-
-Use the optional prop to explicitly indicate non-mandatory fields. This adds an "Optional" badge to the label.
-
-
-
-### Success State
-
-Indicates successful validation or acceptance of selection. The success icon and text provide positive feedback.
-
-
-
-### Warning State
-
-Used for potentially impactful selections that should be made with caution. Includes a warning icon and explanatory text.
-
-
-
-### Error State
-
-Shows validation errors or other issues that need user attention. Features prominent error styling and message.
-
-
-
-### Disabled State
-
-Apply when the field should be non-interactive, such as during form submission or based on other field values.
-
-
-
-### Checked State
-
-Pre-selected checkbox with an initial checked state that users can toggle.
-
-
-
-## Variants
-
-### Outline Variant
-
-A subtler alternative to the primary variant with transparent background when checked.
-
-
-
-### Ghost Variant
-
-The most minimal styling for checkboxes that need less visual emphasis.
-
-
-
-### Different Sizes
-
-Checkboxes can be sized appropriately for different UI needs.
-
-
-
-## Complex Usage
-
-Example of FormCheckboxes with multiple props configured for a specific use case, such as a cookie consent form.
-
-
-
-## Props
-
-The FormCheckbox component extends the standard Checkbox component props with additional form-specific properties:
-
-
-
-## Accessibility
-
-FormCheckbox is built with accessibility in mind:
-
-- Labels are properly associated with checkboxes using htmlFor/id
-- Error messages are announced to screen readers using role="alert"
-- Required fields are marked both visually and via aria-required
-- Helper text is linked to checkboxes using aria-describedby
-- Error states are indicated using aria-invalid
-- Checkboxes maintain proper focus states for keyboard navigation
-
-## Best Practices
-
-When using the FormCheckbox component:
-
-- Always provide clear, concise labels that describe the action being taken
-- Use description text to provide additional context about the implications of selection
-- Write labels as positive statements (what will happen if checked)
-- Keep error messages specific and actionable
-- Use required fields sparingly and logically
-- Group related checkboxes together with a descriptive heading
-- Consider the mobile experience with appropriate touch targets
-- Maintain consistent validation patterns across your form
-- Test with screen readers and keyboard navigation to ensure accessibility
-
-## Layout Guidelines
-
-- Labels should be positioned to the right of the checkbox
-- Error messages should appear immediately below the checkbox
-- Description text should be helpful but not too lengthy
-- Consider using the optional badge for clarity in forms with many fields
-- For groups of related checkboxes, consider using a fieldset with legend
-- Maintain consistent spacing between multiple checkboxes in a group
-- Use appropriate visual hierarchy when nesting checkboxes (e.g., for "select all" patterns)
diff --git a/apps/engineering/content/design/components/form-inputs/form-input.mdx b/apps/engineering/content/design/components/form-inputs/form-input.mdx
index 3b7efee791..5f51db6141 100644
--- a/apps/engineering/content/design/components/form-inputs/form-input.mdx
+++ b/apps/engineering/content/design/components/form-inputs/form-input.mdx
@@ -1,6 +1,6 @@
---
title: FormInput
-description: A form input component with built-in label, description, and error handling capabilities.
+description: A form input component with built-in label, description, and error handling capabilities for creating accessible, user-friendly forms.
---
import {
DefaultFormInputVariant,
@@ -16,111 +16,197 @@ import {
ComplexFormInputVariant
} from "./form-input.variants"
-## Default
+## Overview
+The FormInput component provides a comprehensive form input system that combines labels, descriptions, and validation states. It's designed to create accessible, user-friendly forms with proper labeling, helpful context, and clear validation feedback while maintaining consistency with the design system.
+
+## Usage
+
+```tsx
+import { FormInput } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+ );
+}
+```
+
+## Examples
+
+### Default FormInput
The default FormInput includes a label and optional description text, providing clear context for users.
-## Input States
-
### Required Field
-
Use the required prop to indicate mandatory fields. This automatically adds a "Required" tag to the label.
### Required Field with Error
-
When a required field has an error, the "Required" tag changes to error styling to draw more attention.
### Optional Field
-
Use the optional prop to explicitly indicate non-mandatory fields. This adds an "Optional" tag to the label.
### Success State
-
Indicates successful validation or acceptance of input value. The success icon and text provide positive feedback.
### Warning State
-
Used for potentially problematic inputs that don't prevent form submission. Includes a warning icon and explanatory text.
### Error State
-
Shows validation errors or other issues that need user attention. Features prominent error styling and message.
### Disabled State
-
Apply when the field should be non-interactive, such as during form submission or based on other field values.
### With Default Value
-
Pre-populated input with an initial value that users can modify.
### Read-only State
-
For displaying non-editable information while maintaining form layout consistency.
-## Complex Usage
-
+### Complex Usage
Example of a FormInput with multiple props configured for a specific use case.
+## Features
+
+- **Built-in Labeling**: Automatic label association with proper accessibility
+- **Description Support**: Optional helper text for additional context
+- **Validation States**: Multiple states (success, warning, error) with appropriate styling
+- **Required/Optional Indicators**: Clear visual indicators for field requirements
+- **Accessibility**: Full accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Customizable**: Extensive styling options through className props
+
## Props
The FormInput component extends the standard Input component props with additional form-specific properties:
-) => void` | - | Callback triggered when input value changes |
+| `onFocus` | `(event: React.FocusEvent) => void` | - | Callback triggered when input gains focus |
+| `onBlur` | `(event: React.FocusEvent) => void` | - | Callback triggered when input loses focus |
+| `className` | `string` | - | Additional CSS classes to apply |
+| `id` | `string` | - | Unique identifier for the input. Auto-generated if not provided |
+
+## Variants
+
+### Default
+- Standard form input with label and optional description
+- Use for most form fields
+- Balanced visual weight and accessibility
+
+### Required
+- Includes "Required" indicator for mandatory fields
+- Use for fields that must be completed
+- Clear visual indication of importance
+
+### Optional
+- Includes "Optional" indicator for non-mandatory fields
+- Use for fields that can be left empty
+- Provides clarity in forms with mixed requirements
+
+### Success
+- Green styling for positive validation states
+- Use for successfully validated inputs
+- Encourages positive user feedback
+
+### Warning
+- Yellow/orange styling for cautionary states
+- Use for inputs that need attention but aren't errors
+- Indicates potential issues
+
+### Error
+- Red styling for validation errors
+- Use for failed validation or critical issues
+- Clearly indicates problems that need resolution
+
+## Structure
+
+The FormInput component is composed of:
+
+1. **Label Container** - Contains the label text and required/optional indicators
+2. **Input Element** - The actual input field with validation states
+3. **Description Text** - Optional helper text below the input
+4. **Error Message** - Validation error display when applicable
+5. **Status Icons** - Visual indicators for different states
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent spacing and typography from design system
+- Color-coded validation states for semantic meaning
+- Proper label positioning and association
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className props
+
+### Custom Styling
+
+You can customize the appearance using className props:
+
+```tsx
+
+```
## Accessibility
-FormInput is built with accessibility in mind:
-
-- Labels are properly associated with inputs using htmlFor/id
-- Error messages are announced to screen readers using role="alert"
-- Required fields are marked both visually and via aria-required
-- Helper text is linked to inputs using aria-describedby
-- Error states are indicated using aria-invalid
-
-## Best Practices
-
-When using the FormInput component:
-
-- Always provide clear, concise labels
-- Use description text to provide additional context when needed
-- Keep error messages specific and actionable
-- Use required fields sparingly and logically
-- Group related FormInputs using fieldset and legend when appropriate
-- Consider the mobile experience when writing labels and descriptions
-- Maintain consistent validation patterns across your form
-- Use appropriate input types (email, tel, etc.) for better mobile keyboards
-- Consider character/word limits in descriptions and error messages
-- Test with screen readers to ensure accessibility
-
-## Layout Guidelines
+The FormInput component is built with accessibility in mind:
-- Labels should be clear and concise
-- Error messages should appear immediately below the input
-- Description text should be helpful but not too lengthy
-- Consider using the optional tag for clarity in forms with many fields
+- **Label Association**: Labels are properly associated with inputs using htmlFor/id
+- **Error Announcements**: Error messages are announced to screen readers using role="alert"
+- **Required Indicators**: Required fields are marked both visually and via aria-required
+- **Helper Text**: Helper text is linked to inputs using aria-describedby
+- **Validation States**: Error states are indicated using aria-invalid
+- **Screen Reader Support**: Announces validation states and requirements appropriately
+- **Keyboard Navigation**: Full keyboard support for all interactions
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/form-inputs/form-textarea.mdx b/apps/engineering/content/design/components/form-inputs/form-textarea.mdx
index 17bf82c511..790a20b88d 100644
--- a/apps/engineering/content/design/components/form-inputs/form-textarea.mdx
+++ b/apps/engineering/content/design/components/form-inputs/form-textarea.mdx
@@ -1,6 +1,6 @@
---
title: FormTextarea
-description: A form textarea component with built-in label, description, and error handling capabilities.
+description: A form textarea component with built-in label, description, and error handling capabilities for creating accessible, user-friendly multi-line text inputs.
---
import {
DefaultFormTextareaVariant,
@@ -16,111 +16,203 @@ import {
ComplexFormTextareaVariant
} from "./form-textarea.variants"
-## Default
+## Overview
+The FormTextarea component provides a comprehensive multi-line text input system that combines labels, descriptions, and validation states. It's designed to create accessible, user-friendly forms that require longer text inputs with proper labeling, helpful context, and clear validation feedback while maintaining consistency with the design system.
+
+## Usage
+
+```tsx
+import { FormTextarea } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+ );
+}
+```
+
+## Examples
+
+### Default FormTextarea
The default FormTextarea includes a label and optional description text, providing clear context for users.
-## Textarea States
-
### Required Field
-
Use the required prop to indicate mandatory fields. This automatically adds a "Required" tag to the label.
### Required Field with Error
-
When a required field has an error, the "Required" tag changes to error styling to draw more attention.
### Optional Field
-
Use the optional prop to explicitly indicate non-mandatory fields. This adds an "Optional" badge to the label.
### Success State
-
Indicates successful validation or acceptance of input value. The success icon and text provide positive feedback.
### Warning State
-
Used for potentially problematic inputs that don't prevent form submission. Includes a warning icon and explanatory text.
### Error State
-
Shows validation errors or other issues that need user attention. Features prominent error styling and message.
### Disabled State
-
Apply when the field should be non-interactive, such as during form submission or based on other field values.
### With Default Value
-
Pre-populated textarea with an initial value that users can modify.
### Read-only State
-
For displaying non-editable information while maintaining form layout consistency.
-## Complex Usage
-
+### Complex Usage
Example of a FormTextarea with multiple props configured for a specific use case.
+## Features
+
+- **Built-in Labeling**: Automatic label association with proper accessibility
+- **Description Support**: Optional helper text for additional context
+- **Validation States**: Multiple states (success, warning, error) with appropriate styling
+- **Required/Optional Indicators**: Clear visual indicators for field requirements
+- **Multi-line Support**: Designed for longer text inputs with resizable behavior
+- **Accessibility**: Full accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Customizable**: Extensive styling options through className props
+
## Props
The FormTextarea component extends the standard Textarea component props with additional form-specific properties:
-) => void` | - | Callback triggered when textarea value changes |
+| `onFocus` | `(event: React.FocusEvent) => void` | - | Callback triggered when textarea gains focus |
+| `onBlur` | `(event: React.FocusEvent) => void` | - | Callback triggered when textarea loses focus |
+| `className` | `string` | - | Additional CSS classes to apply |
+| `id` | `string` | - | Unique identifier for the textarea. Auto-generated if not provided |
+
+## Variants
+
+### Default
+- Standard form textarea with label and optional description
+- Use for most multi-line text inputs
+- Balanced visual weight and accessibility
+
+### Required
+- Includes "Required" indicator for mandatory fields
+- Use for fields that must be completed
+- Clear visual indication of importance
+
+### Optional
+- Includes "Optional" indicator for non-mandatory fields
+- Use for fields that can be left empty
+- Provides clarity in forms with mixed requirements
+
+### Success
+- Green styling for positive validation states
+- Use for successfully validated inputs
+- Encourages positive user feedback
+
+### Warning
+- Yellow/orange styling for cautionary states
+- Use for inputs that need attention but aren't errors
+- Indicates potential issues
+
+### Error
+- Red styling for validation errors
+- Use for failed validation or critical issues
+- Clearly indicates problems that need resolution
+
+## Structure
+
+The FormTextarea component is composed of:
+
+1. **Label Container** - Contains the label text and required/optional indicators
+2. **Textarea Element** - The actual textarea field with validation states
+3. **Description Text** - Optional helper text below the textarea
+4. **Error Message** - Validation error display when applicable
+5. **Status Icons** - Visual indicators for different states
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent spacing and typography from design system
+- Color-coded validation states for semantic meaning
+- Proper label positioning and association
+- Resizable textarea behavior
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className props
+
+### Custom Styling
+
+You can customize the appearance using className props:
+
+```tsx
+
+```
## Accessibility
-FormTextarea is built with accessibility in mind:
-
-- Labels are properly associated with textareas using htmlFor/id
-- Error messages are announced to screen readers using role="alert"
-- Required fields are marked both visually and via aria-required
-- Helper text is linked to textareas using aria-describedby
-- Error states are indicated using aria-invalid
-
-## Best Practices
-
-When using the FormTextarea component:
-
-- Always provide clear, concise labels
-- Use description text to provide additional context when needed
-- Keep error messages specific and actionable
-- Use required fields sparingly and logically
-- Group related form elements using fieldset and legend when appropriate
-- Consider the mobile experience when writing labels and descriptions
-- Maintain consistent validation patterns across your form
-- Consider character/word limits for lengthy inputs
-- Use the rows attribute to set an appropriate initial height
-- Test with screen readers to ensure accessibility
-
-## Layout Guidelines
+The FormTextarea component is built with accessibility in mind:
-- Labels should be clear and concise
-- Error messages should appear immediately below the textarea
-- Description text should be helpful but not too lengthy
-- Consider using the optional badge for clarity in forms with many fields
+- **Label Association**: Labels are properly associated with textareas using htmlFor/id
+- **Error Announcements**: Error messages are announced to screen readers using role="alert"
+- **Required Indicators**: Required fields are marked both visually and via aria-required
+- **Helper Text**: Helper text is linked to textareas using aria-describedby
+- **Validation States**: Error states are indicated using aria-invalid
+- **Screen Reader Support**: Announces validation states and requirements appropriately
+- **Keyboard Navigation**: Full keyboard support for all interactions
+- **Resize Support**: Proper handling of textarea resize functionality
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/form-inputs/input.mdx b/apps/engineering/content/design/components/form-inputs/input.mdx
index 4e37a6aae3..5a4a728ef7 100644
--- a/apps/engineering/content/design/components/form-inputs/input.mdx
+++ b/apps/engineering/content/design/components/form-inputs/input.mdx
@@ -1,108 +1,170 @@
---
title: Input
-description: A text input field component with different states, validations, and icon support.
+description: A versatile input component with multiple variants, states, and styling options for creating consistent form inputs throughout your application.
---
-
-import { RenderComponentWithSnippet } from "@/app/components/render";
-import {
- InputDefaultVariant,
- InputSuccessVariant,
- InputWarningVariant,
- InputErrorVariant,
- InputDisabledVariant,
- InputWithDefaultValue,
- InputWithPasswordToggle,
- InputWithBothIcons,
- InputWithPrefix,
- InputWithPrefixAndIcon,
- InputWithPrefixVariants,
-} from "./input.variants.tsx";
-
-## Default
-
-The default input style with neutral colors. Can include optional icons for better visual context.
+import {
+ InputDefaultVariant,
+ InputSuccessVariant,
+ InputWarningVariant,
+ InputErrorVariant,
+ InputDisabledVariant,
+ InputWithDefaultValue,
+ InputWithPasswordToggle,
+ InputWithBothIcons
+} from "./input.variants";
+
+## Overview
+
+The Input component provides a comprehensive input system for creating form fields throughout your application. It's designed to handle various input types with multiple variants, states, and styling options while maintaining accessibility and consistent design patterns.
+
+## Usage
+
+```tsx
+import { Input } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+
+
+
+
+
+ );
+}
+```
+
+## Examples
+
+### Default Variant
+Standard input with default styling and behavior.
-## States
-
-Input components can reflect different states through visual styling:
-
-### Success State
-
-Use the success state to indicate valid input or successful validation. The checkmark icon provides immediate visual feedback.
+### Success Variant
+Input with success styling for positive validation states.
-### Warning State
-
-The warning state can be used to show potential issues that don't prevent form submission. The alert icon draws attention to the warning state.
+### Warning Variant
+Input with warning styling for cautionary states.
-### Error State
-
-Use the error state to indicate invalid input that needs correction. The alert icon emphasizes the error state.
+### Error Variant
+Input with error styling for validation errors.
-### Disabled State
-
-Use the disabled state when user interaction should be prevented, such as during form submission or when the input depends on other conditions.
+### Disabled Variant
+Input in disabled state for unavailable interactions.
-### With Default Value State
-
-Input pre-populated with an initial value that users can modify or build upon.
+### With Default Value
+Input with a pre-filled default value.
-## Interactive Elements
-
-### Password Toggle
-
-Example of an input with a clickable icon to toggle password visibility.
+### With Password Toggle
+Input with password visibility toggle functionality.
-### Search with Icons
-
-Example of an input with both leading and trailing icons for enhanced functionality.
+### With Both Icons
+Input with both left and right icons for enhanced functionality.
-### Prefix Support
-
-Basic Prefix
-Add a prefix to provide context or format guidance to users.
-
-
-Prefix with Icon Combine prefixes with icons for enhanced visual context.
+## Features
-
-Prefix with Different Variants Prefixes work with all input variants and maintain
-consistent styling.
-
-
+- **Multiple Variants**: Different visual styles (default, success, warning, error)
+- **Interactive States**: Hover, focus, and disabled states
+- **Icon Support**: Left and right icon positioning
+- **Password Toggle**: Built-in password visibility toggle
+- **Accessibility**: Full accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Customizable**: Extensive styling options through className prop
## Props
-The Input component accepts all standard HTML input attributes plus the following:
-
-
-
-## Icon Guidelines
-
-When using icons with the Input component:
-
-- Icons should be sized appropriately (recommended: 16x16px using `h-4 w-4` classes)
-- Icons inherit colors based on the input's variant state
-- Interactive icons (like password toggle) should be wrapped in buttons
-- Avoid using too many icons which might clutter the interface
-- Left icons are typically used for input type indication (search, email, etc.)
-- Right icons are commonly used for interactive elements (password toggle, clear button, etc.)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "success" \| "warning" \| "error"` | `"default"` | The visual variant of the input |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | The size of the input |
+| `disabled` | `boolean` | `false` | Whether the input is disabled |
+| `placeholder` | `string` | - | Placeholder text for the input |
+| `value` | `string` | - | Controlled value for the input |
+| `defaultValue` | `string` | - | Default value for uncontrolled input |
+| `leftIcon` | `React.ReactNode` | - | Icon to display on the left side |
+| `rightIcon` | `React.ReactNode` | - | Icon to display on the right side |
+| `className` | `string` | - | Additional CSS classes |
+
+The component also accepts all standard HTML input element props.
+
+## Variants
+
+### Default
+- Standard input styling with neutral colors
+- Use for most form inputs
+- Balanced visual weight
+
+### Success
+- Green color scheme for positive states
+- Use for validated or successful inputs
+- Encourages positive user feedback
+
+### Warning
+- Yellow/orange color scheme for cautionary states
+- Use for inputs that need attention
+- Indicates potential issues
+
+### Error
+- Red color scheme for error states
+- Use for validation errors or failed inputs
+- Clearly indicates problems
+
+## Structure
+
+The Input component is composed of:
+
+1. **Input Container** - Main wrapper with styling and positioning
+2. **Left Icon** - Optional icon on the left side
+3. **Input Element** - The actual input field
+4. **Right Icon** - Optional icon on the right side
+5. **Password Toggle** - Optional password visibility toggle
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent padding and border radius
+- Color-coded variants for semantic meaning
+- Smooth transitions for state changes
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className prop
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
+
+## Accessibility
+
+The Input component is built with accessibility in mind:
+
+- **Semantic HTML**: Uses proper input elements with appropriate attributes
+- **ARIA Attributes**: Proper ARIA labels and descriptions for screen readers
+- **Keyboard Navigation**: Full keyboard support including Tab navigation
+- **Focus Management**: Clear focus indicators and logical tab order
+- **Screen Reader Support**: Announces input states and validation appropriately
+- **High Contrast**: Maintains proper contrast ratios across all variants
diff --git a/apps/engineering/content/design/components/form-inputs/select.mdx b/apps/engineering/content/design/components/form-inputs/select.mdx
index 0bd10e442a..02648fb9d2 100644
--- a/apps/engineering/content/design/components/form-inputs/select.mdx
+++ b/apps/engineering/content/design/components/form-inputs/select.mdx
@@ -1,80 +1,147 @@
---
title: Select
-description: A customizable dropdown menu component built on Radix UI primitives with multiple visual variants.
+description: A customizable select component built with Radix UI primitives for creating accessible dropdown menus with multiple variants and styling options.
---
-
import { SelectExample, SelectExampleVariants } from "./select.example";
## Overview
-The Select component provides a consistent and accessible way to present users with a list of options, making it ideal for forms, navigation menus, and any interface requiring user selection from predefined choices. The component handles complex interactions like keyboard navigation, focus management, and screen reader compatibility automatically, allowing developers to focus on styling and business logic rather than accessibility implementation details.
-
-## Features
-
-- Multiple variants (default, success, warning, error)
-- Left icon support
-- Fully accessible
-- Customizable styling
-- Animated transitions
-- Keyboard navigation
-
-## Variants
-
-The Select component supports four variants:
-
-- `default`: Standard select with gray styling
-- `success`: Green styling for successful states
-- `warning`: Yellow styling for warning states
-- `error`: Red styling for error states
+The Select component provides a customizable dropdown menu built on top of Radix UI's Select primitive. It's designed to create accessible, user-friendly select inputs with various styling options, multiple variants, and comprehensive accessibility features while maintaining consistency with the design system.
## Usage
+```tsx
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+ );
+}
+```
+
+## Examples
+
+### Basic Select
+A complete example showing various select patterns and configurations.
+
### Variant Styles
+Different visual styles for various select states.
+## Features
+
+- **Multiple Variants**: Different visual styles (default, success, warning, error) for semantic meaning
+- **Left Icon Support**: Optional icon display on the left side for enhanced visual context
+- **Fully Accessible**: Built on Radix UI primitives with comprehensive accessibility
+- **Customizable Styling**: Extensive styling options through className props
+- **Animated Transitions**: Smooth animations for open/close states
+- **Keyboard Navigation**: Full keyboard support for all interactions
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+
## Props
### SelectTrigger
| Prop | Type | Description |
|------|------|-------------|
-| variant | "default" \| "success" \| "warning" \| "error" | The visual variant of the select |
-| leftIcon | React.ReactNode | Optional icon to display on the left side |
-| wrapperClassName | string | Additional classes for the wrapper element |
-| className | string | Additional classes for the trigger element |
+| `variant` | `"default" \| "success" \| "warning" \| "error"` | The visual variant of the select |
+| `leftIcon` | `React.ReactNode` | Optional icon to display on the left side |
+| `wrapperClassName` | `string` | Additional classes for the wrapper element |
+| `className` | `string` | Additional classes for the trigger element |
### SelectContent
| Prop | Type | Description |
|------|------|-------------|
-| position | "popper" \| "item-aligned" | The positioning strategy for the dropdown |
-| className | string | Additional classes for the content element |
+| `position` | `"popper" \| "item-aligned"` | The positioning strategy for the dropdown |
+| `className` | `string` | Additional classes for the content element |
### SelectItem
| Prop | Type | Description |
|------|------|-------------|
-| value | string | The value of the select item |
-| disabled | boolean | Whether the item is disabled |
-| className | string | Additional classes for the item element |
+| `value` | `string` | The value of the select item |
+| `disabled` | `boolean` | Whether the item is disabled |
+| `className` | `string` | Additional classes for the item element |
-## Accessibility
+## Variants
-The Select component is built with accessibility in mind:
+### Default
+- Standard select with gray styling
+- Use for most select inputs
+- Balanced visual weight and accessibility
-- Keyboard navigation support
-- ARIA attributes
-- Focus management
-- Screen reader support
-- Proper role attributes
+### Success
+- Green styling for successful states
+- Use for validated or successful selections
+- Encourages positive user feedback
-## Best Practices
+### Warning
+- Yellow styling for warning states
+- Use for selections that need attention
+- Indicates potential issues
+
+### Error
+- Red styling for error states
+- Use for validation errors or failed selections
+- Clearly indicates problems that need resolution
+
+## Structure
+
+The Select component is composed of several sub-components that work together:
+
+1. **Select** - The root component that manages select state
+2. **SelectTrigger** - The element that opens the select dropdown
+3. **SelectValue** - Displays the selected value or placeholder
+4. **SelectContent** - The dropdown container with options
+5. **SelectItem** - Individual selectable options
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent spacing and typography from design system
+- Color-coded variants for semantic meaning
+- Smooth animations for open/close transitions
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className props
+
+### Custom Styling
+
+You can customize the appearance using className props:
+
+```tsx
+
+
+
+```
+
+## Accessibility
+
+The Select component is built with accessibility in mind:
-1. Always provide a placeholder or default value
-2. Use appropriate variants for different states
-3. Group related options using SelectGroup
-4. Add icons when they provide additional context
-5. Use disabled state for unavailable options
\ No newline at end of file
+- **Keyboard Navigation**: Full keyboard support including arrow keys and Enter
+- **ARIA Attributes**: Proper ARIA labels and roles for screen readers
+- **Focus Management**: Maintains focus context during dropdown interactions
+- **Screen Reader Support**: Announces selections and state changes appropriately
+- **High Contrast**: Maintains proper contrast ratios across all variants
+- **Semantic HTML**: Uses appropriate HTML elements and roles
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/form-inputs/textarea.mdx b/apps/engineering/content/design/components/form-inputs/textarea.mdx
index c419764015..d969ff81af 100644
--- a/apps/engineering/content/design/components/form-inputs/textarea.mdx
+++ b/apps/engineering/content/design/components/form-inputs/textarea.mdx
@@ -1,8 +1,7 @@
---
title: Textarea
-description: A multi-line text input component with different states, validations, and icon support.
+description: A multi-line text input component with different states, validations, and icon support for creating accessible, user-friendly text areas.
---
-import { RenderComponentWithSnippet } from "@/app/components/render"
import {
TextareaDefaultVariant,
TextareaSuccessVariant,
@@ -14,77 +13,174 @@ import {
TextareaWithBothIcons
} from "./textarea.variants.tsx"
+## Overview
-## Default
+The Textarea component provides a versatile multi-line text input system that supports various states, validations, and icon placements. It's designed to collect longer user input with appropriate visual feedback and enhanced usability through icons, while maintaining accessibility and consistent design patterns.
-The default textarea style with neutral colors. Can include optional icons for better visual context.
+## Usage
-
+```tsx
+import { Textarea } from "@unkey/ui";
-## States
+export default function MyComponent() {
+ return (
+ }
+ />
+ );
+}
+```
-Textarea components can reflect different states through visual styling:
+## Examples
-### Success State
+### Default Textarea
+The default textarea style with neutral colors. Can include optional icons for better visual context.
+
+
+### Success State
Use the success state to indicate valid input or successful validation. The checkmark icon provides immediate visual feedback.
### Warning State
-
The warning state can be used to show potential issues that don't prevent form submission. The alert icon draws attention to the warning state.
### Error State
-
Use the error state to indicate invalid input that needs correction. The alert icon emphasizes the error state.
### Disabled State
-
Use the disabled state when user interaction should be prevented, such as during form submission or when the input depends on other conditions.
-### With Default Value State
-
+### With Default Value
Textarea pre-populated with an initial value that users can modify or build upon.
-## Interactive Elements
-
### Character Count
-
Example of a textarea with character count functionality to help users stay within length limits.
-### Textarea with Icons
+### With Icons
Example of a textarea with both leading and trailing icons for enhanced functionality.
+## Features
+
+- **Multiple States**: Different visual styles (default, success, warning, error, disabled) for semantic meaning
+- **Icon Support**: Left and right icon positioning for enhanced visual context
+- **Character Count**: Built-in character counting functionality
+- **Resizable**: Users can resize textareas to fit their content needs
+- **Accessibility**: Full accessibility support with proper ARIA attributes
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+- **Customizable**: Extensive styling options through className props
+
## Props
The Textarea component accepts all standard HTML textarea attributes plus the following:
-) => void` | - | Callback triggered when textarea value changes |
+| `onFocus` | `(event: React.FocusEvent) => void` | - | Callback triggered when textarea gains focus |
+| `onBlur` | `(event: React.FocusEvent) => void` | - | Callback triggered when textarea loses focus |
+| `className` | `string` | - | Additional CSS classes to apply |
+
+## Variants
+
+### Default
+- Standard textarea with neutral colors
+- Use for most multi-line text inputs
+- Balanced visual weight and accessibility
+
+### Success
+- Green styling for positive validation states
+- Use for successfully validated inputs
+- Encourages positive user feedback
+
+### Warning
+- Yellow/orange styling for cautionary states
+- Use for inputs that need attention but aren't errors
+- Indicates potential issues
+
+### Error
+- Red styling for validation errors
+- Use for failed validation or critical issues
+- Clearly indicates problems that need resolution
+
+### Disabled
+- Grayed out styling for non-interactive state
+- Use when user interaction should be prevented
+- Clear visual indication of unavailability
+
+## Structure
+
+The Textarea component is composed of:
+
+1. **Textarea Container** - Main wrapper with styling and positioning
+2. **Left Icon** - Optional icon on the left side
+3. **Textarea Element** - The actual textarea field
+4. **Right Icon** - Optional icon on the right side
+5. **Character Count** - Optional character counting display
+
+## Styling
+
+The component includes default styling with:
+
+- Consistent padding and border radius
+- Color-coded variants for semantic meaning
+- Smooth transitions for state changes
+- Resizable behavior for user flexibility
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className props
+
+### Custom Styling
+
+You can customize the appearance using the className prop:
+
+```tsx
+
+```
-## Icon Guidelines
+## Accessibility
-When using icons with the Textarea component:
+The Textarea component is built with accessibility in mind:
-- Icons should be sized appropriately (recommended: 16x16px using `h-4 w-4` classes)
-- Icons inherit colors based on the textarea's variant state
-- Interactive icons should be wrapped in buttons
-- Avoid using too many icons which might clutter the interface
-- Left icons are typically used for input type indication (notes, description, etc.)
-- Right icons are commonly used for interactive elements (expand/collapse, character count toggle, etc.)
+- **Semantic HTML**: Uses proper textarea elements with appropriate attributes
+- **ARIA Attributes**: Proper ARIA labels and descriptions for screen readers
+- **Keyboard Navigation**: Full keyboard support including Tab navigation
+- **Focus Management**: Clear focus indicators and logical tab order
+- **Screen Reader Support**: Announces textarea states and validation appropriately
+- **High Contrast**: Maintains proper contrast ratios across all variants
+- **Resize Support**: Proper handling of textarea resize functionality
\ No newline at end of file
diff --git a/apps/engineering/content/design/components/id.mdx b/apps/engineering/content/design/components/id.mdx
index b945fd7445..5c8d5f65f4 100644
--- a/apps/engineering/content/design/components/id.mdx
+++ b/apps/engineering/content/design/components/id.mdx
@@ -1,49 +1,102 @@
---
-title: Id
+title: ID
+description: A specialized component for displaying and formatting ID values with truncation, width control, and consistent styling for technical content.
---
+import { ValueTruncateExample } from "./id.valueTruncate";
+import { WidthExample } from "./id.width";
-import { ValueTruncateExample } from "./id.valueTruncate"
-import { WidthExample } from "./id.width"
-import { TypeTable } from 'fumadocs-ui/components/type-table';
-
-
+## Overview
+The ID component provides a specialized way to display and format ID values throughout your application. It's designed to handle technical content like API keys, user IDs, or other identifier strings with consistent styling, truncation options, and width control for optimal display.
+## Usage
-## Overview
+```tsx
+import { ID } from "@unkey/ui";
-For the `` component to be used, the `` must be used at the root of the application or somewhere higher in the scope. This is to ensure that the tooltip is rendered correctly.
+export default function MyComponent() {
+ return (
+
+
+
+
+
+ );
+}
+```
-## Truncate & Value
+## Examples
+
+### Value Truncation
+Examples showing different truncation options for long ID values.
-`Id` should be used to display a unique identifier. The `Id` value is passed into the `value` prop. If the value needs to be truncated, a number should be passed to the `truncate` prop.
-## Container Width Full
+### Width Control
+Examples demonstrating width control for different display contexts.
+## Features
+
+- **Value Display**: Consistent formatting for ID values
+- **Truncation Support**: Optional truncation for long values
+- **Width Control**: Configurable width for different display contexts
+- **Consistent Styling**: Monospace font and consistent appearance
+- **Accessibility**: Proper ARIA attributes and screen reader support
+- **Responsive Design**: Adapts to different screen sizes
+- **Dark Mode Support**: Consistent appearance in light and dark themes
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | **Required** | The ID value to display |
+| `truncate` | `boolean` | `false` | Whether to truncate long values |
+| `width` | `string` | - | CSS width class for the component |
+| `className` | `string` | - | Additional CSS classes |
+
+## Structure
+
+The ID component is a simple, self-contained component that renders as a single span element with:
+
+1. **Value Display** - The main ID value with optional truncation
+2. **Styling Container** - Consistent styling and width control
+3. **Accessibility Features** - ARIA attributes and screen reader support
+
+## Styling
+
+The component includes default styling with:
+
+- Monospace font for consistent ID display
+- Consistent padding and spacing
+- Truncation with ellipsis for long values
+- Dark mode support with appropriate color schemes
+- Focus states for accessibility
+- Customizable through className and width props
+
+### Custom Styling
+
+You can customize the appearance using the className and width props:
+
+```tsx
+
+```
+
+## Accessibility
+
+The ID component is built with accessibility in mind:
+- **Semantic HTML**: Uses appropriate HTML elements for ID display
+- **ARIA Attributes**: Proper ARIA labels for screen readers
+- **Screen Reader Support**: Announces ID values appropriately
+- **High Contrast**: Maintains proper contrast ratios
+- **Focus Management**: Clear focus indicators when interactive
diff --git a/apps/engineering/content/design/components/inline-link.mdx b/apps/engineering/content/design/components/inline-link.mdx
index fd2d0e41dc..a7753775fc 100644
--- a/apps/engineering/content/design/components/inline-link.mdx
+++ b/apps/engineering/content/design/components/inline-link.mdx
@@ -1,44 +1,68 @@
---
title: InlineLink
-description: A component for creating inline links with optional icons and styling.
+description: A versatile inline link component with customizable styling, icon support, and target options for creating consistent link experiences throughout your application.
---
+import { InlineLinkBasic, InlineLinkWithIcon, InlineLinkWithTarget, InlineLinkWithCustomClass } from "./inline-link.example";
-import { InlineLinkBasic, InlineLinkWithIcon, InlineLinkWithTarget, InlineLinkWithCustomClass } from "./inline-link.example"
+## Overview
-## Basic Usage
+The InlineLink component provides a consistent way to create inline links within text content. It supports icons, custom styling, and target attributes. The component extends all standard HTML anchor element attributes for maximum flexibility.
-The basic InlineLink includes a label and href.
+## Usage
+
+```tsx
+import { InlineLink } from "@unkey/ui";
+
+export default function MyComponent() {
+ return (
+
+ Documentation
+
+ External Link
+
+ }>
+ Help Center
+
+