@avilovn/miuri-ui

Token-driven React UI kit.

About

miuri-ui is built around design tokens and strict UI contracts:

• styles.css contains only base design-system primitives (colors, typography, radii, motion, states).
• Components keep behavior and visual logic inside React (inline style + token contracts).
• Tokens are exposed through TypeScript contracts (primitives, semantic, tokens.component.*).

Installation

npm install @avilovn/miuri-ui

Usage

Import the stylesheet globally, for example in your main index.css:

@import "@avilovn/miuri-ui/styles.css";

Or import it from your app root component/layout:

import "@avilovn/miuri-ui/styles.css";

Then use components:

import { Button } from "@avilovn/miuri-ui";

Components

Button

• variant: default | brand | outline | ghost | destructive | secondary | link
• size: xxs | xs | sm | default | lg | icon-xxs | icon-xs | icon-sm | icon | icon-lg
• radius: none | xs | sm | lg | full
• justify: start | center | end | between (for non-icon sizes)
• states: loading, disabled, fullWidth, pressed
• asChild, className

Badge

• variant: default | secondary | brand | destructive | outline | ghost
• asChild, className

Card

• Card: variant: default | outline | ghost, padding: sm | md | lg, radius: none | sm | lg, asChild, className
• slots: CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter

Typography

• Heading: level: hero | 1 | 2 | 3 | 4, tone, weight, truncate, asChild, className
• Text: variant: lead | body | body-strong | small | small-strong | caption, tone, weight, truncate, asChild, className

Flex

• layout props: direction, wrap, justify, align
• spacing: size: xs | sm | md | lg or gap
• note: size-based spacing uses design-token CSS variables from styles.css; if you need host-only raw spacing, pass gap like "12px"
• fullWidth, asChild, className

Tree

• data-driven structure: items: TreeNode[]
• TreeNode slots: label (ReactNode), leading, trailing, children, disabled
• state: selectedId/defaultSelectedId, expandedIds/defaultExpandedIds, focusedId/defaultFocusedId
• behavior: autoExpandOnSelect (default true) expands selected parent and selected-path ancestors
• callbacks: onSelectedIdChange, onExpandedIdsChange, onFocusedIdChange, onItemSelect, onItemToggle
• layout: size: xs | sm | md, radius, indent, showGuideLines, expandButtonSize
• typography: textVariant, selectedTextVariant
• controls: headless TreeExpandTrigger, convenience TreeExpandButton, custom expand control via renderExpandButton(payload), custom actions via renderActions(payload)
• headless state: useTreeState
• compound API for custom trees: TreeProvider, TreeContent, TreeContentItem, TreeContentRow, TreeContentBranch, TreeContentExpandTrigger, TreeContentExpandButton, TreeContentLabel, useTreeContentItem
• low-level primitives for atom composition: TreeRoot, TreeItem, TreeRow, TreeBranch, TreeExpandTrigger, TreeExpandButton
• className

Collapsible

• state: open/defaultOpen, onOpenChange, disabled
• size: xxs | xs | sm | default | lg
• primitives: Collapsible, CollapsibleTrigger, CollapsibleContent
• defaults: lightweight trigger/content recipe with spacing, typography and built-in chevron indicator
• custom icons: pass them as children inside CollapsibleTrigger; use asChild for a fully custom trigger/content recipe
• CollapsibleContent supports forceMount for smooth reveal animations
• asChild, className

Accordion

• state: type: single | multiple, value/defaultValue, onValueChange, collapsible, disabled
• size: xxs | xs | sm | default | lg
• primitives: Accordion, AccordionItem, AccordionTrigger, AccordionContent
• defaults: subtle divider rhythm, spaced trigger/content layout and built-in chevron indicator
• custom icons: pass them as children inside AccordionTrigger; use asChild for a fully custom trigger/content recipe
• AccordionContent supports forceMount for smooth reveal animations
• controlled single mode works well for checkout / stepper flows: open next or specific item by updating value from buttons or external controls
• asChild, className

AspectRatio

• ratio (positive finite number, default 1)
• asChild, className

Progress

• value (0..100)
• variant: default | secondary | brand | destructive
• size: xs | sm | md | lg
• radius: none | sm | full
• striped, className

Spinner

• size: number | string
• className

Toast

• primitives: Toast, ToastIcon, ToastBody, ToastTitle, ToastDescription, ToastActions, ToastAction, ToastClose
• system API: ToastProvider, ToastViewport, Toaster, useToast
• ToastProvider: max, duration
• ToastViewport: placement (top/bottom + left/center/right), offset, gap, portal, zIndex
• toast(options): variant, title, description, icon, duration, progress, dismissible, render, className, style
• action buttons and advanced layouts should be implemented via render (custom toast)

Tooltip

• primitives: TooltipProvider, Tooltip, TooltipTrigger, TooltipContent
• TooltipProvider: duration (default open delay for hover interactions)
• Tooltip: open/defaultOpen, onOpenChange, duration (local override), disabled
• TooltipTrigger: supports asChild, keyboard and pointer interactions
• TooltipContent: side, align, sideOffset, alignOffset, forceMount, portal, zIndex, className

Motion

• wrapper-based layer: no changes required in base components
• MotionProvider: reduceMotion (system | boolean), durationScale, preset overrides
• Motion: preset, delay, duration, easing, disabled, asChild, className
• MotionStagger: preset, staggerMs, asChild, className
• built-in preset pool: fade-in, fade-up, fade-down, text-reveal, card-enter, hover-lift, press-scale, focus-pop, attention-pulse, shimmer
• advanced wrappers:
  • text: TextHighlighter, SpinningText, MorphingText, TextReveal, TypingAnimation, BlurTextAnimate
  • data/value: NumberTicker
  • surfaces: BlurFade, AnimatedBeam (path mode: containerRef/fromRef/toRef), BentoGridAnimation

Contracts

Token Layers

1. primitives — raw scale: color, typography, space, radius, motion, icon, control.
2. semantic — interface roles: surface, text, action, border, focus, state, input, elevation.
3. tokens.component.* — component aliases (button, badge, card, toast, progress, typography).

CSS Variable Contract

Core values are exposed through CSS variables prefixed with --mi-* (for example --mi-action-default-bg, --mi-text-primary, --mi-focus-ring).

Theming

<html data-theme="light">

Available themes:

• light
• dark

Environment Support

• prefers-reduced-motion: reduce disables motion-heavy transitions.
• forced-colors: active enables system high-contrast behavior.

Contract Customization

Override tokens globally or in a local scope:

<section
  style={
    {
      "--mi-action-default-bg": "#111111",
      "--mi-action-default-hover": "#1f1f1f",
      "--mi-action-default-active": "#2d2d2d",
      "--mi-action-default-border": "#111111",
      "--mi-action-default-text": "#ffffff",
    } as React.CSSProperties
  }
>
  <Button>Scoped override</Button>
</section>

License

MIT