@kpf_/kiso 1.1.0 → 1.2.0

package/AI_USAGE.md

@@ -0,0 +1,99 @@
+# Kiso AI Consumption Protocol (v1.0.2+)
+
+> **IDENTITY:** You are an AI Agent tasked with building high-end interfaces using the **Kiso Design System**.
+> **PHILOSOPHY:** Kiso is built on **Tactile Intelligence**—interfaces should feel physical, weighted, and responsive to interaction through physics-based motion.
+> **SOURCE:** This document is your technical master reference for consuming `@kpf_/kiso`.
+
+## 📦 Installation & Setup
+
+```bash
+npm install @kpf_/kiso
+```
+
+**CRITICAL:** You MUST import global styles in your root layout (e.g., `layout.tsx`, `App.tsx`):
+```tsx
+import '@kpf_/kiso/style.css'
+```
+
+## 🧩 Component Landscape
+
+Kiso is organized into Atomic folders. Use the following categorized inventory to avoid hallucinations.
+
+### 1. Atoms (Base Elements)
+*   **Typography:** `Text`, `Heading`, `Label`, `Caption`, `Code`, `Link`
+*   **Layout:** `Stack`, `Grid`, `Container`, `Divider`, `Spacer`, `AspectRatio`
+*   **Status:** `Badge`, `Tag`, `Spinner`, `ProgressBar`, `Skeleton`
+*   **Media:** `Avatar`, `Image`, `Icon`
+*   **Forms:** `Button`, `Input`, `Toggle`, `Textarea`, `Checkbox`, `Radio`, `Select`, `OTPInput`
+*   **Containers:** `Card`
+
+### 2. Molecules (Component Clusters)
+*   **Feedback:** `Toast`, `Toaster`, `Alert`, `Snackbar`, `EmptyState`
+*   **Navigation:** `Dropdown`, `Tabs`, `Breadcrumbs`, `Pagination`, `Stepper`, `Timeline`
+*   **Interaction:** `Modal`, `Popover`, `AccordionItem`, `Tooltip`, `CopyToClipboard`
+*   **Composites:** `FormField`, `PasswordField`, `SearchInput`, `StatCard`, `InfoRow`
+
+### 3. Organisms (Layout & Sections)
+*   **Shell:** `Navbar`, `Sidebar`, `Footer`
+*   **Forms:** `LoginForm`, `SignupForm`, `ProfileForm`
+*   **Content:** `HeroSection`, `FeatureGrid`, `FAQSection`, `PricingTable`
+*   **Data:** `DataTable`, `DashboardStats`, `ActivityFeed`
+*   **Overlays:** `ConfirmationDialog`
+
+### 4. Motion (Tactile Primitives)
+*   **Text:** `StaggerText`, `TextScramble`
+*   **Physics:** `Magnetic`, `Tilt`, `Spotlight`
+*   **Flow:** `HotSlider`, `ViewTransition`
+
+## 🎨 Design System Constraints
+
+Do **NOT** use generic Tailwind colors or utility-first overrides for component cores.
+
+- **Colors:** `bg-kiso-green`, `text-kiso-forest`, `border-kiso-stroke`, `bg-kiso-gray`
+- **Transitions:** `ease-kiso` (Tactile spring timing)
+- **Shadows:** `shadow-kiso-sm`, `shadow-kiso-md`
+- **Rounding:** `rounded-kiso-md`, `rounded-kiso-lg`
+
+## 🛡️ Strict Compliance Rules (The "Kiso Guardrails")
+
+1.  **NO CLASSNAME PROP:** Kiso components do **NOT** accept `className`. Use provided props (`variant`, `size`, `status`, `rounded`).
+2.  **Wrappers for Layout:** If you must apply margin, width, or positioning classes, wrap the Kiso component in a primitive `div` or use Kiso `Stack`/`Grid`.
+3.  **Continuous Build Verification (CBV):** Always run `npm run lint && npm run build` after implementing Kiso components to ensure prop types and exports are valid.
+4.  **No Hallucinations:** If a component is not listed above, it does not exist in Kiso.
+5.  **Motion Preference:** Prioritize `StaggerText` for headings and `Magnetic`/`Tilt` for primary CTAs to maintain "Tactile" feel.
+
+## 📚 Implementation Example
+
+```tsx
+import { 
+  Card, 
+  Heading, 
+  Text, 
+  Button, 
+  Stack, 
+  Magnetic, 
+  Tilt 
+} from '@kpf_/kiso'
+
+export function ProductShowcase() {
+  return (
+    <Tilt max={10}>
+      <Card padding="lg" shadow="md">
+        <Stack gap={6} align="start">
+          <Heading level="h2">The Kiso Modular Kit</Heading>
+          <Text variant="muted">
+            Physics-based components for modern tactile intelligence.
+          </Text>
+          
+          <div className="flex gap-4 mt-2">
+            <Magnetic strength={0.2}>
+              <Button variant="primary" size="lg">Get Started</Button>
+            </Magnetic>
+            <Button variant="outline" size="lg">Documentation</Button>
+          </div>
+        </Stack>
+      </Card>
+    </Tilt>
+  )
+}
+```

package/README.md

@@ -1,169 +1,86 @@
 # Kiso Design System
 
-Package: `@kpf/kiso`
-Version: `1.0.0`
-Framework: React 19 / TypeScript
+Package: `@kpf_/kiso`  
+Version: `1.0.2` (Build Verified)  
+Philosophy: **Tactile Intelligence**
 
-**Kiso** (Japanese for *Foundation*) is a strict, atomic UI library built for tactile interaction and precise motion. It enforces a specific set of physics curves (`ease-kiso`) and a hardcoded token system to ensure visual consistency across applications.
+**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.
 
-## Integration
-
-### 1. Installation
+## 🚀 Installation
 
 ```bash
-npm install @kpf/kiso framer-motion
+npm install @kpf_/kiso framer-motion @phosphor-icons/react
 ```
 
-### 2. Styles & Fonts
-
-Kiso relies on **Plus Jakarta Sans** and a compiled CSS file for token injection.
-
-In your root entry file (e.g., `main.tsx` or `layout.tsx`):
+## 🔌 Setup
 
-```typescript
-// 1. Import the Font
-import '@fontsource/plus-jakarta-sans/400.css';
-import '@fontsource/plus-jakarta-sans/500.css';
-import '@fontsource/plus-jakarta-sans/600.css';
-import '@fontsource/plus-jakarta-sans/700.css';
+### 1. Global Styles
+In your root layout (e.g., `layout.tsx` or `App.tsx`):
 
-// 2. Import Kiso Core Styles
-import '@kpf/kiso/dist/style.css';
+```tsx
+import '@kpf_/kiso/style.css'
 ```
 
-### 3. Provider Setup
+### 2. Fonts
+Kiso is designed around **Plus Jakarta Sans** (Primary) and **JetBrains Mono** (Code).
 
-The system requires a global context for feedback loops (Toasts). Wrap your application root:
-
-```typescript
-import { ToastProvider } from '@kpf/kiso';
-
-function App() {
-  return (
-    <ToastProvider>
-      <YourApplication />
-    </ToastProvider>
-  );
-}
+```tsx
+// 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
+## 🧩 Component Architecture
 
-Kiso favors **Compound Component** patterns for complex molecules to keep the API surface minimal.
+Kiso is organized into Atomic tiers for maximum composability.
 
 ### Atoms
-
-#### Button
-Utilizes tactile press physics (`scale-96`) and custom easing.
-
-```typescript
-import { Button } from '@kpf/kiso';
-
-<Button variant='primary' onClick={handleClick}>
-  Confirm Action
-</Button>
-
-<Button variant='destructive' isLoading={isDeleting}>
-  Delete Item
-</Button>
-```
-
-#### Input
-Includes slot support for icons and right-aligned actions.
-
-```typescript
-import { Input } from '@kpf/kiso';
-import { MagnifyingGlass } from '@phosphor-icons/react';
-
-<Input 
-  placeholder='Search...' 
-  leftIcon={<MagnifyingGlass />} 
-  error={hasError}
-/>
-```
-
-### Molecules (Stateful)
-
-#### Modal System
-Uses a compound pattern. The `Content` component handles the entrance animation automatically based on the `variant` prop (`standard` | `sheet` | `bottom`).
-
-```typescript
-import { Modal } from '@kpf/kiso';
-
-<Modal.Root open={isOpen} onOpenChange={setIsOpen}>
-  <Modal.Content variant='sheet'>
-    <Modal.Header>
-      <h2>Transaction Details</h2>
-    </Modal.Header>
-    
-    <div className='p-6'>
-      {/* Content */}
-    </div>
-
-    <Modal.Footer>
-       <Button variant='secondary' onClick={close}>Close</Button>
-    </Modal.Footer>
-  </Modal.Content>
-</Modal.Root>
-```
-
-#### Toast Feedback
-Triggered via hook.
-
-```typescript
-import { useToast } from '@kpf/kiso';
-
-const { success, error } = useToast();
-
-const handleSubmit = () => {
-  try {
-    saveData();
-    success('Changes saved successfully.');
-  } catch (err) {
-    error('Failed to save data.');
-  }
-};
-```
-
-### Motion System
-
-Kiso provides pre-configured motion primitives powered by Framer Motion. These use the **wise-drama** bezier curve (`0.1, 0.9, 0.2, 1`).
-
-#### Stagger Text
-Splits strings into characters and cascades them in.
-
-```typescript
-import { StaggerText } from '@kpf/kiso';
-
-<StaggerText 
-  text='Welcome Back' 
-  className='text-4xl font-bold text-kiso-forest' 
-/>
-```
-
-#### View Transition (Wizard)
-Handles the exit/enter overlap logic for multi-step forms.
-
-```typescript
-import { ViewTransition } from '@kpf/kiso';
-
-// direction is 'forward' | 'backward'
-<ViewTransition direction={navDirection}>
-  {step === 1 && <StepOne key='step1' />}
-  {step === 2 && <StepTwo key='step2' />}
-</ViewTransition>
+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.
+
+```tsx
+import { Tilt, Card, StaggerText } from '@kpf_/kiso'
+
+<Tilt>
+  <Card padding="lg">
+    <StaggerText text="Tactile Logic" />
+  </Card>
+</Tilt>
 ```
 
-## Design Tokens
+## 🛡️ Strict Guidelines
 
-Do not use arbitrary values. Use the Kiso token set for consistency.
+- **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`).
 
-| Category | Token | Value |
-| --- | --- | --- |
-| **Color** | `text-kiso-forest` | Primary Text (#163300) |
-| | `bg-kiso-green` | Primary Action (#9FE870) |
-| | `bg-kiso-gray` | Backgrounds (#F2F4F8) |
-| | `border-kiso-stroke` | Borders (#D3D5D8) |
-| **Shadow** | `shadow-kiso-modal` | Deep elevation for dialogs |
-| **Ease** | `ease-kiso` | Standard interaction curve |
-| **Ease** | `ease-drama` | Long-form motion curve |
+## 📄 License
+MIT © Kim Fajardo

package/dist/components/motion/Magnetic.d.ts

@@ -1,6 +1,24 @@
 import * as React from "react";
 export interface MagneticProps {
     children: React.ReactNode;
+    /**
+     * How far the element should move.
+     * @default 0.5
+     */
     strength?: number;
+    /**
+     * Whether to pull towards or push away from the cursor.
+     * @default 'attract'
+     */
+    mode?: 'attract' | 'repel';
+    /**
+     * Transition configuration for the spring physics.
+     * @default { damping: 15, stiffness: 150, mass: 0.1 }
+     */
+    springConfig?: {
+        damping: number;
+        stiffness: number;
+        mass: number;
+    };
 }
-export declare const Magnetic: React.MemoExoticComponent<({ children, strength }: MagneticProps) => import("react/jsx-runtime").JSX.Element>;
+export declare const Magnetic: React.MemoExoticComponent<({ children, strength, mode, springConfig }: MagneticProps) => import("react/jsx-runtime").JSX.Element>;