katachi-ui

v1.0.1

Published

6 months ago

Katachi UI - A comprehensive Vue 3 design system with Tailwind CSS, SCSS, and FontAwesome

0High
0Medium
0Low

tcsn

katachi-ui katachi vue vue3 design-system components tailwind scss fontawesome typescript ui framework form shape

Katachi UI

A comprehensive Vue 3 design system built with composition API, SCSS, Tailwind CSS, and FontAwesome icons.

Katachi (形) means "form" or "shape" in Japanese - representing the beautiful structure of your UI components.

Features

🚀 Vue 3 with Composition API
🎨 Tailwind CSS for styling
💅 SCSS for custom styling
🎯 TypeScript support
📦 Tree-shakable components
🧪 Vitest for testing
📖 Storybook for documentation
🔧 ESLint & Prettier for code quality

Installation

npm install katachi-ui

CDN Usage

For CodePen, JSFiddle, or other online editors, you can use CDN links:

jsDelivr (Recommended)

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/style.css">

<!-- JavaScript (UMD) -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.umd.js"></script>

<!-- Or use latest version (auto-updates) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katachi-ui/dist/style.css">
<script src="https://cdn.jsdelivr.net/npm/katachi-ui/dist/index.umd.js"></script>

UNPKG

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/style.css">

<!-- JavaScript (UMD) -->
<script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script>

<!-- Or use latest version -->
<link rel="stylesheet" href="https://unpkg.com/katachi-ui/dist/style.css">
<script src="https://unpkg.com/katachi-ui/dist/index.umd.js"></script>

CDN Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Katachi UI CDN Example</title>
  <!-- Vue 3 -->
  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <!-- Katachi UI CSS -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katachi-ui/dist/style.css">
  <!-- Katachi UI JS -->
  <script src="https://cdn.jsdelivr.net/npm/katachi-ui/dist/index.umd.js"></script>
</head>
<body>
  <div id="app">
    <katachi-button variant="primary">Hello Katachi!</katachi-button>
    <katachi-input v-model="message" label="Your message" placeholder="Type something..."></katachi-input>
  </div>

  <script>
    const { createApp } = Vue;
    
    createApp({
      data() {
        return {
          message: ''
        }
      }
    })
    .use(KatachiUI.default)
    .mount('#app');
  </script>
</body>
</html>

Usage

Global Registration

import { createApp } from 'vue'
import Katachi from 'katachi-ui'
import 'katachi-ui/dist/style.css'

const app = createApp(App)
app.use(Katachi)

Individual Component Import

<template>
  <div>
    <Button variant="primary" @click="onClick">
      Click me
    </Button>
  </div>
</template>

<script setup>
import { Button } from 'katachi-ui'

const onClick = () => {
  console.log('Button clicked!')
}
</script>

Components

Button

<Button variant="primary" size="md" :loading="false">
  Primary Button
</Button>

Props:

variant: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger'
size: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
loading: boolean
disabled: boolean
block: boolean
icon: FontAwesome icon name

Input

<Input
  v-model="value"
  label="Email"
  type="email"
  placeholder="Enter your email"
  prefix-icon="envelope"
  required
/>

Props:

type: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search'
label: string
placeholder: string
helpText: string
errorMessage: string
disabled: boolean
readonly: boolean
required: boolean
clearable: boolean
prefixIcon: FontAwesome icon name
suffixIcon: FontAwesome icon name

Card

<Card title="Card Title" :actions="true">
  <template #actions>
    <Button size="sm">Edit</Button>
  </template>
  
  <p>Card content goes here</p>
  
  <template #footer>
    <div class="flex justify-end">
      <Button>Action</Button>
    </div>
  </template>
</Card>

Modal

<Modal
  v-model:visible="modalVisible"
  title="Modal Title"
  size="md"
  icon="info"
  icon-type="info"
>
  <p>Modal content</p>
  
  <template #footer>
    <Button variant="outline" @click="modalVisible = false">
      Cancel
    </Button>
    <Button @click="modalVisible = false">
      Confirm
    </Button>
  </template>
</Modal>

Online Playground

CodePen Setup

For CodePen, add these external resources:

CSS:

https://cdn.jsdelivr.net/npm/katachi-ui/dist/style.css

JavaScript:

https://unpkg.com/vue@3/dist/vue.global.js
https://cdn.jsdelivr.net/npm/katachi-ui/dist/index.umd.js

CodePen Example:

HTML:

<div id="app">
  <div class="p-6 space-y-4">
    <h1 class="text-2xl font-bold">Katachi UI Demo</h1>
    
    <katachi-button variant="primary" @click="showModal = true">
      Open Modal
    </katachi-button>
    
    <katachi-input 
      v-model="name" 
      label="Your Name" 
      placeholder="Enter your name"
      prefix-icon="user"
    ></katachi-input>
    
    <katachi-card title="User Info">
      <p>Hello, {{ name || 'Anonymous' }}!</p>
    </katachi-card>
    
    <katachi-modal v-model:visible="showModal" title="Welcome!">
      <p>This is a modal dialog from Katachi UI!</p>
      <template #footer>
        <katachi-button variant="outline" @click="showModal = false">
          Close
        </katachi-button>
      </template>
    </katachi-modal>
  </div>
</div>

JavaScript:

const { createApp } = Vue;

createApp({
  data() {
    return {
      name: '',
      showModal: false
    }
  }
})
.use(KatachiUI.default)
.mount('#app');

JSFiddle Setup

Similar setup for JSFiddle:

Add Vue 3 CDN in Resources
Add Katachi UI CSS and JS CDNs
Use the same HTML/JS code structure

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build:lib

# Run tests
npm test

# Run Storybook
npm run storybook

# Lint code
npm run lint

Customization

Tailwind Configuration

The design system uses a custom Tailwind configuration with extended color palette and spacing. You can override these in your project's tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          // Your custom primary colors
        }
      }
    }
  }
}

SCSS Variables

You can override SCSS variables by importing them before the main styles:

// Your custom variables
$primary-color: #your-color;

// Import design system styles
@import '@tcsn/design-system/src/styles/main.scss';

Browser Support

Modern browsers (Chrome, Firefox, Safari, Edge)
IE11+ (with polyfills)

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request