Kiso Design System

Package: @kpf_/kiso
Version: 1.0.2 (Build Verified)
Philosophy: Tactile Intelligence

Kiso (Japanese for Foundation) is a high-performance UI library built for physical interaction and precise motion. It enforces physics-based behaviors through custom springs and the signature ease-kiso bezier curve.

🚀 Installation

npm install @kpf_/kiso framer-motion @phosphor-icons/react

🔌 Setup

1. Global Styles

In your root layout (e.g., layout.tsx or App.tsx):

import '@kpf_/kiso/style.css'

2. Fonts

Kiso is designed around Plus Jakarta Sans (Primary) and JetBrains Mono (Code).

// Example using Google Fonts or Fontsource
import '@fontsource/plus-jakarta-sans/400.css';
import '@fontsource/plus-jakarta-sans/700.css';
import '@fontsource/jetbrains-mono/500.css';

🧩 Component Architecture

Kiso is organized into Atomic tiers for maximum composability.

Atoms

Primitive build blocks:

• Typography: Text, Heading, Label, Code, Link
• Forms: Button, Input, Toggle, Checkbox, Radio, OTPInput
• Layout: Stack, Grid, Container, Spacer, AspectRatio
• Visual: Avatar, Badge, Tag, Spinner, Card

Molecules

Stateful interaction patterns:

• Navigation: Tabs, Stepper, Timeline, Breadcrumbs, Pagination
• Feedback: Toaster, useToast, Alert, Snackbar, EmptyState
• Overlays: Modal, Popover, Tooltip, AccordionItem
• Composites: FormField, PasswordField, StatCard

Organisms

High-level production-ready sections:

• Forms: LoginForm, SignupForm, ProfileForm
• Marketing: HeroSection, FeatureGrid, PricingTable
• Data: DataTable, DashboardStats, ActivityFeed
• Shell: Navbar, Sidebar, Footer

✨ Motion (Tactile Intelligence)

Kiso includes physics-based primitives that go beyond simple transitions:

• Magnetic: Wraps elements to pull them toward the cursor.
• Tilt: Adds reactive 3D depth to containers on hover.
• Spotlight: A tracking radial reveal layer.
• StaggerText: Character-by-character entrance sequences.
• TextScramble: Decoding animations for headlines.

import { Tilt, Card, StaggerText } from '@kpf_/kiso'

<Tilt>
  <Card padding="lg">
    <StaggerText text="Tactile Logic" />
  </Card>
</Tilt>

🛡️ Strict Guidelines

• No className: Kiso components do NOT accept a className prop. All styling is variant/prop-driven to maintain design integrity.
• Layout Wrappers: Use Stack, Grid, or standard div elements to handle external positioning.
• Tokens: Always use kiso prefixed tailwind tokens for custom elements (bg-kiso-green, text-kiso-forest).

📄 License

MIT © Kim Fajardo