urkit-ui

Urkit UI

A modern, accessible UI component library for Nuxt 4 with custom CSS architecture (no Tailwind).

✨ Features

• 🎨 Custom CSS Architecture - Beautiful components without Tailwind dependency
• 🚀 Nuxt 4 Ready - Built specifically for Nuxt 4
• ♿ Accessible - WCAG compliant components
• 🎭 Customizable - Flexible theming and icon system
• 📦 Zero Config - Works out of the box with sensible defaults
• 🔧 TypeScript - Full TypeScript support
• 🎯 Auto-Import - Components automatically available in your app

📦 Available Components

Currently available components in v0.2.0:

Component	Description	Status
UrButton	Full-featured button with variants, sizes, loading states, and icons	✅ Stable
UrInput	Comprehensive input component with validation, password toggle, icons, and select	✅ Stable
UrIcon	Flexible icon system with namespace support	✅ Stable
UrAlert	Alert component for messages and notifications with multiple variants and statuses	✅ Stable
UrBadge	Badge component for labels and status indicators with colors and variants	✅ Stable

Coming Soon

• ✨ UrCard - Card container component
• ✨ UrModal - Modal/dialog component
• ✨ UrToast - Toast notification system
• ✨ UrCheckbox - Checkbox input component
• ✨ UrRadio - Radio button component
• ✨ UrSelect - Dropdown select component
• ✨ UrTextarea - Multi-line text input
• And more...

🚀 Quick Start

Installation

# Using pnpm (recommended)
pnpm add urkit-ui

# Using npm
npm install urkit-ui

# Using yarn
yarn add urkit-ui

Setup

Add urkit-ui to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['urkit-ui']
})

That's it! Components are now auto-imported with the Ur prefix.

Usage

<template>
  <div>
    <UrButton variant="primary">Click Me</UrButton>

    <UrInput
      v-model="email"
      type="email"
      label="Email"
      placeholder="Enter your email"
    />
  </div>
</template>

<script setup lang="ts">
const email = ref('')
</script>

📚 Components

Button

Full-featured button component with multiple variants, sizes, and states.

<UrButton
  variant="primary"
  mode="filled"
  size="md"
  icon="icons:plus"
  :loading="false"
>
  Click Me
</UrButton>

Variants: primary, error, success, neutral Modes: filled, stroke, lighter, ghost Sizes: sm, md, lg, xlg

Input

Comprehensive input component with validation, icons, and advanced features.

<UrInput
  v-model="value"
  type="text"
  label="Label"
  placeholder="Placeholder"
  icon="icons:search"
/>

Features:

• Text, password, email, number inputs
• Password toggle with requirements validation
• Icons and affixes (prefix/suffix)
• Button integration
• Select dropdown
• Disabled and error states

Alert

Alert component for displaying important messages and notifications.

<UrAlert
  status="success"
  title="Success!"
  description="Your changes have been saved."
  :dismissable="true"
  @dismiss="handleDismiss"
/>

Variants: filled, light, lighter, stroke Sizes: xsmall, small, large Statuses: error, warning, success, information, feature

Features:

• Multiple variants and sizes
• 5 status types with unique icons
• Optional description and action buttons
• Dismissable with close button
• Slots for custom content

Badge

Badge component for labels and status indicators.

<UrBadge
  variant="filled"
  size="medium"
  color="blue"
>
  New
</UrBadge>

Variants: filled, light, lighter, stroke Sizes: small, medium, large Colors: gray, blue, orange, red, green, yellow, purple, sky, pink, teal

🎨 Icon System

Urkit includes a flexible icon system with namespace support and automatic caching.

📘 Complete Icon Documentation - Usage, custom icons, and advanced configuration

Included Icons

The module includes essential icons to get you started:

Alert Icons (Outlined style):

• 🚨 icons:alert-error - Error alert icon
• ⚠️ icons:alert-warning - Warning alert icon
• ✅ icons:alert-success - Success alert icon
• ℹ️ icons:alert-info - Information alert icon
• ✨ icons:alert-feature - Feature announcement icon

UI Icons (Outlined style):

• ❌ icons:close - Close/dismiss icon (16×16)
• 🔍 icons:search - Search icon (24×24)
• 👁️ icons:show - Show password icon (24×24)
• 🙈 icons:hide - Hide password icon (24×24)

<!-- Use included icons -->
<UrIcon name="icons:search" :size="24" />
<UrIcon name="icons:alert-success" :size="20" />
<UrIcon name="icons:close" :size="16" />

💡 All icons use currentColor for dynamic theming. See ICONS.md for complete documentation.

Custom Icons

Method 1: Override Built-in Icons

Place SVG files in your project's public/assets/icons/ directory:

your-app/
└── public/
    └── assets/
        └── icons/
            └── custom-icon.svg  ← Overrides module's icon

Method 2: Add Custom Namespace

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['urkit-ui'],

  urkit: {
    iconNamespaces: {
      icons: '/assets/icons',      // Default
      logos: '/assets/logos',      // Default
      custom: '/custom/icons'      // Your custom namespace
    }
  }
})

Then use: <UrIcon name="custom:my-icon" />

⚙️ Configuration

Customize Urkit UI in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['urkit-ui'],

  urkit: {
    // Customize component prefix (default: 'Ur')
    prefix: 'Ur',

    // Customize brand colors
    colors: {
      primary: {
        500: '#0ea5e9',  // Your brand color
        600: '#0284c7',
        700: '#0369a1'
      }
    },

    // Customize icon namespaces
    iconNamespaces: {
      icons: '/assets/icons',
      logos: '/assets/logos',
      social: '/custom/social-icons'
    }
  }
})

🎨 Color Customization

Urkit UI uses a purple theme by default. Easily customize to match your brand:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['urkit-ui'],

  urkit: {
    colors: {
      primary: {
        50: '#f0f9ff',
        500: '#0ea5e9',  // Main brand color
        600: '#0284c7',  // Hover
        700: '#0369a1'   // Active
      },
      neutral: {
        1: '#fafafa',
        7: '#737373',
        12: '#171717'
      }
    }
  }
})

See COLORS.md for complete customization guide, examples, and color scales.

📖 Documentation

• Complete Usage Guide - Detailed component documentation and examples
• Icon System Guide - Icon usage, custom icons, and namespaces
• Color Customization - Brand color customization guide
• Architecture - Technical architecture and asset management

🔧 Requirements

• Nuxt 4.0.0 or later
• Node.js 18 or later

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📬 Support

• 📦 NPM Package
• 🐛 Report Issues
• 💬 Discussions
• 📖 Documentation

👨‍💻 Development

This section is for contributors developing the Urkit UI module itself.

Setup

# Install dependencies
pnpm install

# Prepare module
pnpm run dev:prepare

# Start playground
pnpm run dev

Building

# Build the module
pnpm run prepack

Project Structure

urkit-ui/
├── src/
│   ├── module.ts                 # Module configuration
│   └── runtime/
│       ├── assets/css/           # CSS files
│       ├── components/           # Vue components
│       ├── composables/          # Composables
│       └── public/              # Public assets (icons, logos)
├── playground/                   # Testing playground
├── USAGE.md                     # Usage documentation
└── ARCHITECTURE.md              # Architecture documentation