npm package: @plures/design-dojo
Description: [![CI](https://github.com/plures/design-dojo/actions/workflows/ci.yml/badge.svg)](https://github.com/plures/design-dojo/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@plures/design-dojo)](https://www.npmjs.com/package/@plures/desi
Latest version: 0.10.17

# Design Dojo 🥋

[![CI](https://github.com/plures/design-dojo/actions/workflows/ci.yml/badge.svg)](https://github.com/plures/design-dojo/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/@plures/design-dojo)](https://www.npmjs.com/package/@plures/design-dojo)
[![npm downloads](https://img.shields.io/npm/dm/@plures/design-dojo)](https://www.npmjs.com/package/@plures/design-dojo)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
[![Storybook](https://img.shields.io/badge/Storybook-live-ff4785)](https://plures.github.io/design-dojo/)
[![Svelte 5](https://img.shields.io/badge/Svelte-5-ff3e00)](https://svelte.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)

> The difference between a web app and a great app is 1000 refinements.

**Design Dojo** is a training ground for building desktop-quality UI with Svelte 5. Not "good enough for web" — **sharp enough that users forget it's a WebView.**

Every Pares product (mobile, desktop, Total Recall timeline, the book reader) depends on UI that feels native. This repo is where we get there.

## Philosophy

### What "Desktop-Quality" Means

A web app says: *"I'm a website in a window."*
A desktop app says: *"I belong here."*

The difference:
- **60fps or nothing** — no jank, no layout shift, no FOUC
- **Pixel-precise** — every border, shadow, and spacing is intentional
- **Physics-based motion** — spring animations, not CSS transitions
- **Typography as architecture** — Nerd Fonts, ligatures, variable weights
- **Surfaces, not cards** — depth through blur, transparency, and layering
- **Instant** — no loading spinners. Optimistic UI. Local-first.

### Learning from Cosmic Desktop

[Cosmic](https://github.com/pop-os/cosmic-epoch) (System76) is building a Rust desktop environment from scratch. Key lessons:

1. **`iced` widget model** — every element is a composable widget with layout, draw, and event handling
2. **GPU-accelerated rendering** — wgpu backend, not DOM layout
3. **Consistent spacing system** — 4px grid, optical alignment
4. **Color as system** — semantic tokens, not hex values
5. **Blur and transparency** — frosted glass done right (not CSS `backdrop-filter` hacks)
6. **Typography scale** — mathematical ratios, not arbitrary sizes
7. **Motion as language** — spring physics with configurable damping/stiffness

We can't use iced (it's Rust-native, not web). But we can steal every design principle and implement them in Svelte + SVG + Canvas.

## Structure

```
design-dojo/
├── src/
│   ├── lib/
│   │   ├── primitives/     # Button, Input, Toggle, Slider, Checkbox
│   │   ├── layout/         # Stack, Grid, Split, Sidebar, Dock
│   │   ├── surfaces/       # Card, Panel, Sheet, Modal, Popover
│   │   ├── navigation/     # Tabs, Breadcrumb, Command Palette
│   │   ├── feedback/       # Toast, Progress, Skeleton, Spinner
│   │   ├── icons/          # Nerd Font integration, SVG icon system
│   │   ├── animation/      # Spring, Morph, Parallax, Stagger
│   │   ├── motion/         # Physics engine, gesture recognizer
│   │   └── data-viz/       # Charts, Graphs, Timeline (SVG + Canvas)
│   └── stories/            # Storybook stories for visual testing
│       ├── primitives/
│       ├── layout/
│       ├── animation/
│       ├── surfaces/
│       └── showcase/       # Full compositions, real app mockups
├── docs/
│   ├── principles/         # Design system documentation
│   ├── cosmic-lessons/     # What we learned from Cosmic Desktop
│   └── techniques/         # SVG, Canvas, WebGL, animation deep-dives
├── static/fonts/           # Nerd Fonts, variable fonts
├── .storybook/             # Storybook configuration
└── package.json
```

## The Training Path

### Belt System 🥋

**White Belt** — Primitives
- Build a button that *feels* like clicking a real thing
- Input fields with smooth focus transitions
- Toggles with spring physics
- Understand the 4px grid

**Yellow Belt** — Layout & Surfaces
- Split panes with smooth drag handles
- Frosted glass panels (CSS + SVG filter fallback)
- Sidebar with collapse animation
- Z-depth system (not just `box-shadow`)

**Green Belt** — Motion & Animation
- Spring physics engine (mass, stiffness, damping)
- SVG path morphing between states
- Stagger animations for lists
- Gesture recognition (swipe, pinch, long-press)

**Blue Belt** — Data Visualization
- SVG charts that animate on data change
- Canvas-based timeline (thousands of items, 60fps)
- WebGL particle effects for transitions
- Real-time data streams with smooth interpolation

**Brown Belt** — Composition
- Full app shells (sidebar + header + content + status bar)
- Command palette (Cmd+K) with fuzzy search
- Notification system with stacked toasts
- Theme engine (light/dark/custom with smooth transition)

**Black Belt** — Mastery
- Components indistinguishable from native
- Sub-16ms render times on all components
- Accessibility (a11y) without compromising aesthetics
- The showcase: build a real Pares UI that makes people say "wait, this is a web app?"

## The Pares Manus Advantage

This is where we're different from every other UI library author.

With **Pares Manus** (Windows Agent Node), Praxis can:
1. **Capture what renders** — screenshot after every change
2. **Compare to intent** — "does this look like what I meant?"
3. **Measure pixel differences** — automated visual regression
4. **Test on real displays** — HiDPI, multi-monitor, different scaling
5. **Iterate visually** — not just write code and hope, but see-adjust-refine

The feedback loop goes from "write → deploy → look → context switch → fix" to **"write → see → fix → see → ship"**. That's how you get to 1000 refinements.

## Tech Stack

- **Svelte 5** — runes, snippets, fine-grained reactivity
- **SVG** — icons, illustrations, data viz, morphing
- **Canvas 2D** — high-performance rendering (timelines, particle effects)
- **WebGL** (selective) — GPU-accelerated effects where Canvas isn't enough
- **Storybook** — visual component development and testing
- **Nerd Fonts** — 9000+ icons, ligatures, developer-friendly
- **CSS Custom Properties** — design tokens, theme engine
- **`popmotion`/custom** — spring physics, decay, keyframe animations

## Installation

```bash
npm install @plures/design-dojo
```

**Peer dependencies:**

```bash
npm install svelte@^5.0.0
```

Optional peer deps (enable telemetry / praxis integration):

```bash
npm install @plures/praxis @opentelemetry/api
```

**Requirements:** Node.js 22+, npm 10+

## Usage

Import design tokens first (add to your app's root layout or `+layout.svelte`):

```svelte
<script>
  import '@plures/design-dojo/tokens.css';
</script>
```

### Primitives

```svelte
<script>
  import { Button, Input, Toggle, Select } from '@plures/design-dojo/primitives';

  let value = $state('');
  let enabled = $state(false);
</script>

<Button onclick={() => console.log('clicked')}>Save</Button>
<Input bind:value placeholder="Search…" />
<Toggle bind:checked={enabled} label="Dark mode" />
```

### Layout

```svelte
<script>
  import { SplitPane, Sidebar, ActivityBar } from '@plures/design-dojo/layout';
</script>

<SplitPane>
  {#snippet left()}
    <Sidebar><!-- nav content --></Sidebar>
  {/snippet}
  {#snippet right()}
    <!-- main content -->
  {/snippet}
</SplitPane>
```

### Motion / Spring physics

```svelte
<script>
  import { useSpring } from '@plures/design-dojo/motion';

  const scale = useSpring(1, { stiffness: 300, damping: 20 });
</script>

<div
  style="transform: scale({scale.value})"
  onmouseenter={() => (scale.target = 1.05)}
  onmouseleave={() => (scale.target = 1)}
>
  Hover me
</div>
```

### Surfaces

```svelte
<script>
  import { GlassPanel, Pane } from '@plures/design-dojo/surfaces';
</script>

<GlassPanel>
  <Pane>Content with frosted-glass depth</Pane>
</GlassPanel>
```

## Component Reference

| Subpath | Components |
|---------|-----------|
| `@plures/design-dojo/primitives` | `Button`, `Input`, `Toggle`, `Select`, `Text`, `SearchInput`, `MarkdownEditor`, `ContextMenu` |
| `@plures/design-dojo/layout` | `SplitPane`, `Sidebar`, `ActivityBar`, `StatusBar`, `StatusBarItem`, `Box`, `EditorTabs` |
| `@plures/design-dojo/surfaces` | `GlassPanel`, `Pane`, `ChatPane` |
| `@plures/design-dojo/motion` | `useSpring`, `useTransition`, `useReducedMotion`, `TransitionGroup` |
| `@plures/design-dojo/gesture` | `useGesture` (Svelte action) |
| `@plures/design-dojo/icons` | Nerd Font icon system |
| `@plures/design-dojo/overlays` | Modal, Popover, Toast, drawer |
| `@plures/design-dojo/data` | Data-bound components |
| `@plures/design-dojo/canvas` | `Canvas`, `CanvasRect`, `CanvasCircle`, `CanvasLine`, `CanvasText`, `CanvasGroup` |
| `@plures/design-dojo/svg` | `Rect`, `Circle`, `Path`, `Text`, `Group`, `Gradient`, `Filter`, `Mask` |
| `@plures/design-dojo/scroll` | `useScrollProgress`, `useParallax`, `scrollReveal` |
| `@plures/design-dojo/typography` | `loadVariableFont`, `buildVariationSettings`, `TYPE_SCALE` |
| `@plures/design-dojo/app` | `SyncIndicator` and app-shell components |
| `@plures/design-dojo/tokens.css` | CSS custom-property design tokens |
| `@plures/design-dojo/tui-tokens.css` | TUI (terminal-style) design tokens |

See the [live Storybook](https://plures.github.io/design-dojo/) for interactive component demos and full prop documentation.

## Getting Started (Development)

```bash
git clone https://github.com/plures/design-dojo.git
cd design-dojo
npm install
npm run storybook    # Component development at http://localhost:6006
npm run dev          # Full app preview
npm test             # Run unit tests
npm run build        # Build distributable package
```

## Principles

See [`docs/principles/`](docs/principles/) for the full design system documentation.

Quick rules:
1. **No `px` literals** — use spacing tokens (`--space-1` through `--space-12`)
2. **No `color: #hex`** — use semantic tokens (`--color-text`, `--color-surface`)
3. **No `transition: all`** — animate specific properties, use springs for interaction
4. **No `z-index` wars** — use the stacking context system
5. **No `!important`** — if you need it, the architecture is wrong

## Accessibility

Design Dojo targets **WCAG 2.1 AA** compliance across all components. All interactive elements include:
- Keyboard navigation and focus management
- ARIA roles, labels, and live regions
- Sufficient color contrast ratios
- Respect for the user's `prefers-reduced-motion` setting via `useReducedMotion` (see [`src/lib/motion/use-reduced-motion.svelte.ts`](https://github.com/plures/design-dojo/blob/main/src/lib/motion/use-reduced-motion.svelte.ts))

Report accessibility issues via [GitHub Issues](https://github.com/plures/design-dojo/issues) with the `a11y` label.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for the full release history and [releases](https://github.com/plures/design-dojo/releases) for downloadable artifacts.

## Contributing

We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup and workflow
- Coding conventions (Svelte 5 runes, ESM, strict TypeScript)
- How to add a new component
- PR standards and commit message format

## Support

- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/plures/design-dojo/issues)
- 💬 **Questions / discussion** — [GitHub Discussions](https://github.com/plures/design-dojo/discussions)
- 🔒 **Security vulnerabilities** — see [Security Policy](https://github.com/plures/design-dojo/security/policy)

---

*Part of the [Pares](https://github.com/plures) ecosystem. The UI layer that makes everything else worth building.*