Design Dojo 🥋

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.

API Reference

See docs/API.md for exported components, utilities, and types.

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 (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

npm install @plures/design-dojo

Peer dependencies:

npm install svelte@^5.0.0

Optional peer deps (enable telemetry / praxis integration):

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):

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

Primitives

<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

<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

<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

<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 for interactive component demos and full prop documentation.

Getting Started (Development)

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/ 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)

Report accessibility issues via GitHub Issues with the a11y label.

Changelog

See CHANGELOG.md for the full release history and releases for downloadable artifacts.

Contributing

We welcome contributions! Please read 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
• 💬 Questions / discussion — GitHub Discussions
• 🔒 Security vulnerabilities — see Security Policy

Part of the Pares ecosystem. The UI layer that makes everything else worth building.