Nons UIKit

Schema-driven UI component library for the Nons platform — Vue 3, TypeScript, token-based design system.

Installation

npm install @nons-dev/uikit

Quick Start

1. Initialize Project Config:

   npx @nons-dev/uikit init

   This generates nons.config.yaml and a locales/ directory in your consumer project root.

2. Configure Vite Plugin: Add the Nons config plugin to your vite.config.ts to automate theme configuration injection:

   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue'
   import { nonsConfigPlugin } from '@nons-dev/uikit/plugin'
   
   export default defineConfig({
     plugins: [vue(), nonsConfigPlugin()],
   })

3. Bootstrap Library:

   import { bootstrapRegistry } from '@nons-dev/uikit'
   import '@nons-dev/uikit/style.css'

Architecture

nons.config.yaml       Project-level configuration (Preset, Locale, Direction, Font)
core/                  Schema types, registry, schema renderer, runtime context
ui/                    Vue 3 component source files (primitives, composites, layouts, sections)
design-system/         Global styles, CSS reset, and compiled tokens (shipped in dist/)
├── css/
│   ├── index.css          Global styles entrypoint
│   ├── reset.css          CSS reset using design tokens
│   ├── theme-vars.css     Generated CSS custom properties (Color primitives, typography roles, spacing, radius)
│   ├── theme.config.json  Generated Tailwind configuration map
│   └── tokens.ts          Generated TypeScript token constants
plugins/               i18n, direction, permissions
adapters/              Data provider layer (mock API, storage abstraction)
locales/               Persian (fa) and English (en) translation JSON files
scripts/               CLI tool (nons) and Vite plugin
generated/             Auto-generated component registry (auto-registry.ts, components.json)

🛠️ Developer Guide: Updating Styles & Tokens

For developers working on the uikit package, the design system utilizes a compiled token system managed by the Go CLI (nons).

1. The Source of Truth

The central repository of themes and primitives lives in the design-system monorepo project:

• Primitives: registry/colors.yaml, registry/typography.yaml, registry/spacing.yaml, registry/radius.yaml, registry/shadow.yaml
• Themes: themes/dashboard.yaml (Admin Panel Theme)

2. Compiling Tokens

When design system configurations or theme files change, you must recompile tokens:

# Compile locally stored design system tokens (creates theme-vars.css, theme.config.json, tokens.ts)
nons ds build

The compiler maps the tokens and writes the compiled assets straight to design-system/css/.

3. Updating Components

When creating or modifying components in ui/:

• Run the component registry generator to register new files, props, events, or slots:

  npm run generate:registry

  (This is also run automatically during npm run build in the prebuild phase).

📐 Design System Rules & Guidelines

To maintain consistency and prevent design drift, all developers must strictly follow these rules:

🔴 Rule 1: Zero Hardcoded Values

Never use raw colors (#fff, rgb(), oklch()), margins, paddings, borders, or font sizes inside a component's <style> block. All visual values must reference the official design system variables.

🔴 Rule 2: Token Naming Standard

All legacy variables (like --space-*, --radius-*, --font-*) have been completely removed. Refer to direct design system tokens:

• Spacing: Use var(--ds-spacing-*) (e.g., var(--ds-spacing-1), var(--ds-spacing-4-5))
• Radius: Use var(--ds-radius-*) (e.g., var(--ds-radius-sm), var(--ds-radius-full))
• Border Width: Use var(--ds-border-width-default) or var(--ds-border-width-lg)
• Typography Sizes: Use role-based variables: var(--ds-font-body-md-fontSize), var(--ds-font-title-lg-fontSize), etc.
• Typography Line Heights: Use role-based dashed variables: var(--ds-font-body-md-line-height), var(--ds-font-title-lg-line-height), etc.
• Font Family: Use --ff-primary (regular UI font) or --ff-mono (monospace code font).
• Font Weight: Use --font-weight-regular (400), --font-weight-medium (500), --font-weight-semibold (600), or --font-weight-bold (700).

🔴 Rule 3: Flat UI & Terminal Vibe

The design language is flat. Avoid using shadows (except the predefined var(--ds-shadow-md) where essential). Keep components layout-clean and rely on solid themed borders (var(--ds-border-width-default) solid var(--border-primary)) to separate sections.

🔴 Rule 4: Layout Spacing Separation

Do not define margins (margin, margin-top, etc.) on components. Component boundaries must be clean. Parent layout containers are responsible for spacing sibling components via CSS grid/flex gap.

Development & Test Commands

npm install

# Start Vite dev server with playground app (contains component explorer)
npm run dev

# Run TypeScript check, compile registry, compile library dist, and copy assets
npm run build

# Preview the built production playground
npm run preview

CLI Utilities Reference

npx @nons-dev/uikit init              # Create nons.config.yaml + locales/ in project root
npx @nons-dev/uikit validate          # Validate nons.config.yaml structure
npx @nons-dev/uikit list              # List all components
npx @nons-dev/uikit show <name>       # Show component details (props, events, slots)
npx @nons-dev/uikit schema <name>     # Show schema JSON for a component
npx @nons-dev/uikit search <query>    # Search components by name or description