@swiftlogistics/ui

Features

• Dark-first Design - Optimized for logistics and enterprise dashboards
• 70+ Components - Comprehensive set of UI elements
• Nuxt 4 Ready - Full compatibility with latest Nuxt
• Fully Responsive - Mobile-first approach
• TypeScript - Full type support and IntelliSense
• Tree-shakable - Import only what you need
• Accessible - WCAG 2.1 compliant components
• Performance - Optimized for Core Web Vitals

Installation

# npm
npm install @swiftlogistics/ui

# yarn
yarn add @swiftlogistics/ui

# pnpm
pnpm add @swiftlogistics/ui

Quick Start

1. Add to Nuxt Config

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@swiftlogistics/ui'],
  
  swiftlogistics: {
    prefix: 'Sl',           // Component prefix (default: 'Sl')
    theme: 'dark',          // Default theme
    primaryColor: 'orange', // Primary brand color
    components: 'all'       // Auto-import all components
  }
})

2. Use Components

<template>
  <div>
    <SlButton color="primary" glow>Get Started</SlButton>
    
    <SlCard hoverable class="mt-4">
      <SlInput v-model="search" icon="i-lucide-search" placeholder="Search..." />
    </SlCard>
  </div>
</template>

3. Add Toast Notifications

<!-- app.vue -->
<template>
  <UApp>
    <SlToastProvider position="bottom-right">
      <NuxtLayout>
        <NuxtPage />
      </NuxtLayout>
    </SlToastProvider>
  </UApp>
</template>

<script setup>
useToastProvider()
</script>

Component Categories

Elements (Basic)

| Component | Description | |-----------|-------------| | SlButton | Action buttons with variants, loading states, glow effects | | SlCard | Glass-morphism cards with hover/floating effects | | SlIcon | Lucide icons wrapper with sizing | | SlBadge | Status badges with pulse animation | | SlAvatar | User avatars with status indicators | | SlSkeleton | Loading skeleton placeholders | | SlSpinner | Loading spinners | | SlDivider | Section dividers | | SlGradientText | Gradient text effects | | SlCounter | Animated number counters |

Forms

| Component | Description | |-----------|-------------| | SlInput | Text inputs with icons and validation | | SlTextarea | Multi-line text areas | | SlSelect | Single/Multi-select dropdowns | | SlMultiSelect | Tag-style multi-select | | SlDropdown | Context menus | | SlAutocomplete | Search with suggestions | | SlCheckbox | Checkboxes | | SlRadio / SlRadioGroup | Radio buttons | | SlSwitch | Toggle switches | | SlRange | Range sliders | | SlDatePicker | Date selection calendar | | SlFileUpload | Drag & drop file upload | | SlPinInput | OTP/PIN code input | | SlFormGroup | Form field wrappers |

Data Display

| Component | Description | |-----------|-------------| | SlTable | Sortable data tables | | SlDataTable | Advanced tables with search, filters, pagination | | SlList | Simple lists | | SlAccordion | Collapsible sections | | SlTabs | Tab panels | | SlPagination | Page navigation | | SlCalendar | Event calendars | | SlTimeline | Vertical timelines | | SlTree | Hierarchical trees | | SlKanban | Kanban boards |

Feedback

| Component | Description | |-----------|-------------| | SlAlert | Status alerts (info, success, warning, error) | | SlToast / SlToastProvider | Notification toasts | | SlModal | Dialog modals | | SlDrawer | Side panels | | SlTooltip | Hover tooltips | | SlPopover | Popover menus | | SlProgressStep | Step/wizard indicators | | SlRingProgress | Circular progress | | SlLoadingBar | Top loading bar |

Navigation

| Component | Description | |-----------|-------------| | SlBreadcrumbs | Navigation breadcrumbs | | SlSteps | Multi-step wizards | | SlCommandPalette | Cmd+K command menu | | SlContextMenu | Right-click context menus |

Blocks (Composite)

| Component | Description | |-----------|-------------| | SlFeatureItem | Feature highlights with icons | | SlStatCard | Statistics cards | | SlServiceTab | Service selection tabs | | SlTestimonialCard | Customer testimonials | | SlTimelineItem | Timeline events | | SlPricingCard | Pricing tables |

Sections (Page Sections)

| Component | Description | |-----------|-------------| | SlHero | Hero sections with CTAs | | SlTracking | Shipment tracking widgets | | SlServices | Service showcase | | SlStats | Statistics grids | | SlFeatures | Feature grids | | SlTestimonials | Testimonial carousels | | SlCTA | Call-to-action sections |

Layouts

| Component | Description | |-----------|-------------| | SlHeader | Navigation headers | | SlFooter | Page footers | | SlSidebar | Dashboard sidebars |

Configuration Options

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@swiftlogistics/ui'],
  
  swiftlogistics: {
    // Component prefix (default: 'Sl')
    prefix: 'Sl',
    
    // Theme mode: 'dark' | 'light' | 'auto'
    theme: 'dark',
    
    // Primary brand color
    primaryColor: 'orange',
    
    // Which components to auto-import
    // 'all' or ['Button', 'Card', 'Input']
    components: 'all',
    
    // Auto-install Nuxt UI
    installNuxtUI: true,
    
    // Global CSS styles
    globalStyles: true
  }
})

Composables

useToast

<script setup>
const toast = useToast()

// Show notifications
toast.success('Order shipped!', 'Tracking number: #12345')
toast.error('Payment failed', 'Please try again')
toast.warning('Low inventory', 'Only 5 items left')
toast.info('New update', 'Version 2.0 is available')

// With actions
toast.add({
  title: 'Confirm Action',
  description: 'Are you sure?',
  variant: 'warning',
  duration: 0, // Don't auto-close
  actions: [
    {
      label: 'Confirm',
      callback: () => console.log('Confirmed'),
      variant: 'solid'
    },
    {
      label: 'Cancel',
      callback: () => toast.remove(toastId)
    }
  ]
})
</script>

useCounter

<script setup>
const { current, animate, isAnimating } = useCounter({
  start: 0,
  end: 1000,
  duration: 2000,
  decimals: 0
})

// Start animation
onMounted(() => {
  animate()
})
</script>

<template>
  <span>{{ current }}</span>
</template>

useScrollReveal

<script setup>
// Auto-animate elements with .sl-scroll-reveal class
useScrollReveal()
</script>

<template>
  <div class="sl-scroll-reveal">This will fade in on scroll</div>
</template>

useModal / useDrawer

<script setup>
const modal = useModal()
const drawer = useDrawer()

const openModal = () => modal.open()
const closeModal = () => modal.close()
</script>

<template>
  <SlModal v-model="modal.isOpen">
    Content here
  </SlModal>
  
  <SlDrawer v-model="drawer.isOpen" title="Settings">
    Drawer content
  </SlDrawer>
</template>

Theming

CSS Variables

:root {
  /* Primary Colors */
  --sl-color-primary-500: #f97316;
  --sl-color-primary-600: #ea580c;
  
  /* Backgrounds */
  --sl-bg-primary: #0a0a0a;
  --sl-bg-secondary: #171717;
  --sl-bg-elevated: rgba(255, 255, 255, 0.03);
  
  /* Text */
  --sl-text-primary: #ffffff;
  --sl-text-secondary: #a3a3a3;
  
  /* Borders */
  --sl-border-primary: rgba(255, 255, 255, 0.1);
  
  /* Shadows */
  --sl-shadow-glow: 0 0 20px rgba(249, 115, 22, 0.25);
}

Customizing Theme

<style>
/* Override in your app */
:root {
  --sl-color-primary-500: #3b82f6; /* Change to blue */
}
</style>

TypeScript

Full TypeScript support with exported types:

import type { 
  ButtonProps, 
  CardProps, 
  ToastOptions,
  TableColumn,
  TreeNodeData 
} from '@swiftlogistics/ui'

const columns: TableColumn[] = [
  { key: 'name', label: 'Name', sortable: true },
  { key: 'status', label: 'Status', type: 'status' }
]

Examples

Complete Page Example

<template>
  <div>
    <SlHeader
      brand-name="Swift"
      brand-highlight="Logistics"
      :nav-items="navItems"
      :primary-cta="{ label: 'Get Quote', onClick: openQuote }"
    />
    
    <SlHero
      badge="New: AI-Powered Tracking"
      title="Global Logistics"
      gradient-text="Reimagined"
      description="Seamless freight forwarding with real-time visibility"
      :ctas="heroCTAs"
      :stats="heroStats"
    >
      <template #visual>
        <SlCard floating class="max-w-md">
          <!-- Tracking widget -->
        </SlCard>
      </template>
    </SlHero>
    
    <SlServices
      eyebrow="Our Services"
      title="Comprehensive Solutions"
      description="End-to-end supply chain management"
      :services="services"
    />
    
    <SlFooter
      brand-name="Swift"
      brand-highlight="Logistics"
      description="Global logistics powered by technology"
      :columns="footerColumns"
      :socials="socials"
      :contacts="contacts"
      copyright="© 2026 SwiftLogistics. All rights reserved."
    />
  </div>
</template>

<script setup>
const navItems = [
  { label: 'Services', to: '#services' },
  { label: 'Tracking', to: '#tracking' },
  { label: 'About', to: '#about' }
]

const heroCTAs = [
  { label: 'Get Started', variant: 'solid', glow: true, onClick: () => {} },
  { label: 'Watch Demo', variant: 'outline', icon: 'i-lucide-play' }
]

const heroStats = [
  { value: 150, label: 'Countries' },
  { value: 98, suffix: '%', label: 'On-Time' },
  { value: 24, suffix: '/7', label: 'Support' }
]

useScrollReveal()
</script>

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Contributing

# Clone
git clone https://github.com/swiftlogistics/ui.git

# Install
npm install

# Dev server
npm run dev

# Build
npm run build

# Test
npm run test

License

MIT License © 2026 SwiftLogistics

CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

## [1.0.0] - 2026-03-13

### Added
- Initial release with 70+ components
- Full Nuxt 4 and Vue 3 support
- Dark-first design system
- TypeScript definitions
- Auto-import functionality
- Toast notification system
- Form validation support
- Data tables with sorting/filtering
- Calendar and date picker
- Kanban board component
- Tree view component
- Command palette
- Comprehensive documentation

### Components
- 10 Element components
- 14 Form components
- 10 Data display components
- 9 Feedback components
- 4 Navigation components
- 6 Block components
- 7 Section components
- 3 Layout components

### Composables
- useToast / useToastProvider
- useCounter / useAnimatedNumber
- useScrollReveal
- useClickOutside
- useKeyStroke
- useLocalStorage
- useModal / useDrawer

LICENSE

MIT License

Copyright (c) 2026 SwiftLogistics

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

CONTRIBUTING.md

# Contributing to @swiftlogistics/ui

Thank you for your interest in contributing!

## Development Setup

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/ui.git
cd ui

# Install dependencies
npm install

# Start dev server
npm run dev

Project Structure

src/
├── runtime/
│   ├── components/     # Vue components
│   │   ├── elements/   # Basic building blocks
│   │   ├── forms/      # Form inputs
│   │   ├── data/       # Data display
│   │   ├── feedback/   # Alerts, toasts, modals
│   │   ├── navigation/ # Menus, breadcrumbs
│   │   ├── blocks/     # Composite components
│   │   ├── sections/   # Page sections
│   │   └── layouts/    # Layout components
│   ├── composables/    # Vue composables
│   ├── types/          # TypeScript definitions
│   └── assets/         # CSS and static files
├── module.ts           # Nuxt module entry
└── index.ts            # Package exports

Adding a Component

1. Create Vue file in appropriate folder
2. Export from components/index.ts
3. Add TypeScript types in types/index.ts
4. Add documentation in README
5. Add example in playground

Code Style

• Use TypeScript for all new code
• Follow Vue 3 Composition API pattern
• Use script setup syntax
• Prefix components with Sl
• Use CSS variables for theming

Testing

# Type check
npm run typecheck

# Build test
npm run build

# Pack test
npm pack --dry-run

Submitting Changes

1. Create feature branch: git checkout -b feature/my-feature
2. Commit changes: git commit -m "feat: add new component"
3. Push to fork: git push origin feature/my-feature
4. Open Pull Request

Commit Convention

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Formatting
• refactor: Code restructuring
• test: Tests
• chore: Maintenance

Questions?

Open an issue on GitHub.

### API Documentation (`docs/API.md`)

```markdown
# API Reference

## Components

### SlButton

**Props:**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | `'solid' \| 'outline' \| 'ghost' \| 'soft'` | `'solid'` | Button style |
| color | `ColorVariant` | `'primary'` | Color theme |
| size | `SizeVariant` | `'md'` | Button size |
| loading | `boolean` | `false` | Loading state |
| disabled | `boolean` | `false` | Disabled state |
| glow | `boolean` | `false` | Glow effect |
| rounded | `RoundedVariant` | `'lg'` | Border radius |
| block | `boolean` | `false` | Full width |
| to | `string` | - | Router link |
| href | `string` | - | External link |
| icon | `string` | - | Leading icon |
| trailingIcon | `string` | - | Trailing icon |

**Slots:**
- `default` - Button content
- `leading` - Leading content
- `trailing` - Trailing content

**Events:**
- `click` - Click event

**Example:**
```vue
<SlButton color="primary" glow size="lg" @click="handleClick">
  Get Started
</SlButton>

SlCard

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | hoverable | boolean | false | Enable hover effect | | floating | boolean | false | Floating animation | | padding | 'none' \| 'sm' \| 'md' \| 'lg' | 'md' | Inner padding | | variant | 'default' \| 'glass' \| 'solid' | 'default' | Card style |

Slots:

• default - Card content
• header - Header section
• footer - Footer section

SlInput

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | type | string | 'text' | Input type | | placeholder | string | - | Placeholder text | | size | SizeVariant | 'md' | Input size | | disabled | boolean | false | Disabled state | | icon | string | - | Leading icon | | trailingIcon | string | - | Trailing icon | | clearable | boolean | false | Show clear button |

Events:

• update:modelValue - Value change
• blur - Blur event
• focus - Focus event

SlToastProvider / useToast

Methods:

| Method | Params | Returns | Description | |--------|--------|---------|-------------| | add | ToastOptions | string | Add toast | | remove | id: string | void | Remove toast | | success | title, description? | string | Success toast | | error | title, description? | string | Error toast | | warning | title, description? | string | Warning toast | | info | title, description? | string | Info toast | | clear | - | void | Clear all |

ToastOptions:

| Property | Type | Description | |----------|------|-------------| | title | string | Toast title (required) | | description | string | Toast message | | variant | ToastVariant | 'info' \| 'success' \| 'warning' \| 'error' | | duration | number | Auto-close duration (ms), 0 = never | | closable | boolean | Show close button | | actions | ToastAction[] | Action buttons |

Composables

useCounter

function useCounter(options: {
  start?: number      // Start value (default: 0)
  end: number         // End value (required)
  duration?: number   // Animation duration in ms (default: 2000)
  decimals?: number   // Decimal places (default: 0)
  delay?: number      // Delay before start (default: 0)
}): {
  current: Ref<number>        // Current animated value
  isAnimating: Ref<boolean>   // Animation state
  animate: () => Promise<void> // Start animation
  reset: () => void           // Reset to start
  stop: () => void            // Stop animation
}

useScrollReveal

function useScrollReveal(
  selector?: string  // CSS selector (default: '.sl-scroll-reveal')
): void

Adds scroll-triggered animation to elements with matching selector.

useClickOutside

function useClickOutside(
  elementRef: Ref<HTMLElement>,
  callback: () => void
): void

useKeyStroke

function useKeyStroke(
  key: string | string[],
  handler: (event: KeyboardEvent) => void,
  options?: { target?: EventTarget }
): void

Types

All types are exported from @swiftlogistics/ui:

import type {
  // Component Props
  ButtonProps,
  CardProps,
  InputProps,
  SelectOption,
  TableColumn,
  ToastOptions,
  
  // Base Types
  ColorVariant,
  SizeVariant,
  RoundedVariant,
  PositionVariant,
  
  // Data Types
  TreeNodeData,
  KanbanColumn,
  CalendarEvent,
  
  // Module
  ModuleOptions
} from '@swiftlogistics/ui'

### Migration Guide (`docs/MIGRATION.md`)

```markdown
# Migration Guide

## From v0.x to v1.0

### Breaking Changes

- **Prefix changed**: Components now use `Sl` prefix instead of `Swift`
  ```vue
  <!-- Before -->
  <SwiftButton />
  
  <!-- After -->
  <SlButton />

• Color prop: Changed from variant to color

  <!-- Before -->
  <SlButton variant="primary" />
    
  <!-- After -->
  <SlButton color="primary" />

New Features

• Auto-import support
• 30+ new components
• Improved TypeScript definitions
• Better Nuxt 4 compatibility

Upgrading

# Update package
npm install @swiftlogistics/ui@latest

# Update nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@swiftlogistics/ui'], // Remove old module
  swiftlogistics: {
    prefix: 'Sl' // Update if using custom prefix
  }
})