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.

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

Getting Started

npm install
npm run storybook    # Component development
npm run dev          # Full app preview

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

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