DEV Community

Faisal Ahmad
Faisal Ahmad

Posted on

PaperDots UI: Tactile 2D Paper & Ink-Dot Physics with Shadcn Registry CLI (Built for Julian)

#devchallenge #weekendchallenge #hf26challenge #opensource

🎨 PaperDots UI: Tactile 2D Paper & Ink-Dot Physics for the Living Web

This project was built for the **Hacktoberfest 2026 Weekend Challenge: Build for a Friend* (October 2–5, 2026).*

1. The Friend: Meet Julian 🤝

A few days ago, my friend Julian—an independent risograph printmaker, analog synthesist, and digital zine creator—sat down with me over coffee. Julian was working on an interactive web edition of their print publication, "Analog Futures".

Julian pulled up their laptop, scrolled through several popular component libraries, and sighed:

"Look at every web framework today. Tailwind, Shadcn, Material UI... they're all made for corporate SaaS dashboards. Everything is a rigid grey rectangle with artificial drop shadows and flat plastic buttons. Why can't interactive web elements feel like living ink and paper cutouts on heavy cotton paper? Why can't a button burst into square paper chips or gentle confetti when you tap it, or a volume slider feel like physical ink beads on a paper thread?"

Julian isn't a shader engineer or math programmer. Manually writing numerical spring physics, Poisson-disc stippling, and canvas particle renderers from scratch was an impossible hurdle.

So for this Hacktoberfest Weekend Challenge, I built PaperDots UI (PaperDots.js) specifically for Julian: a 100% light, tactile paper UI library that is directly installable via Shadcn CLI or PaperDots CLI, featuring distinct per-component animations, deep customization knobs, and open-weight Gemma fine-tuned with Thinking Machines' Tinker at its core.

2. Installable via CLI & Shadcn Registry 🚀

Instead of static code comparisons, PaperDots UI is designed to be directly installed into modern projects:

# 1. Install via Shadcn Registry:
npx shadcn@latest add https://paperdots-ui-showcase.onrender.com/r/paper-button.json
npx shadcn@latest add https://paperdots-ui-showcase.onrender.com/r/paper-slider.json

# 2. Or install via PaperDots CLI:
npx paperdots-ui add button
npx paperdots-ui add --all

# 3. Or install via npm:
npm install paperdots-ui
Enter fullscreen mode Exit fullscreen mode

3. What We Built: Distinct Animations for Every Component 🛠️

Every component in PaperDots has its own unique, physical animation routines rather than generic effects:

Distinct Animation Matrix:

  • PaperDotButton: 6 distinct click modes:
    • hydraulic-pop: Instant radial explosion with snappy spring return (<350ms).
    • ripple-wave: Circular traveling wave radiating outward from the cursor.
    • stamp-press: Mechanical vertical impact with horizontal bulge and spring bounce.
    • confetti-drift: Upward eruptive spray of paper chips that gently flutter down.
    • particle-vortex: Swirling cyclone that spins around the click point.
    • micro-chatter: Vintage typewriter carriage vibration on click.
  • PaperDotMorph:
    • equalizer-wave: Living acoustic vertical wave oscillation across particles when in Play mode.
    • crystalline-snap: Crystalline geometric freeze brake when Paused.
    • vortex-morph: Swirling ink vortex when switching between 7 vector silhouettes (Play, Pause, Heart, Star, Check, Arrow, Circle).
  • PaperDotSlider:
    • elastic-string: Beads bend along a catenary curve with elastic string drag tension.
    • ink-dilation: Particles expand in radius with ink bleed as dragging velocity increases.
    • magnetic-tick: Micro-shock tremors and crisp clicks at step intervals.
  • PaperDotToggle:
    • cylinder-roll: Tangential momentum rolling.
    • page-flip: Vertical crease collapse simulating turning a zine page.
    • slingshot-snap: Rubber band windup with high-velocity snap.
  • PaperDotProgress:
    • domino-cascade: Sequential jumping domino chips.
    • capillary-bleed: Capillary ink bleed spreading along the track.
    • strobe-pulse: Traveling harmonic light wave.
  • PaperDotInput:
    • typewriter-recoil: Mechanical acoustic carriage recoil on each keystroke.
    • focus-halo: Soft breathing margin expansion when active.
    • perimeter-wave: Traveling perimeter shockwave.
  • PaperDotBadge:
    • beacon-pulse: Radiant double-pulse beacon chip.
    • shimmer-wave: Diagonal light sweep across chips.
    • float-drift: Buoyant floating paper leaf.
  • PaperDotCard:
    • magnetic-deflection: Perimeter chips deflect away from cursor magnetism.
  • PaperDotLoader:
    • constellation: Orbital sinusoidal ink bleed constellation.

4. 100% Light Tactile Printmaker Palettes & Spot Inks (No Dark UI) 🎨

All dark themes have been completely eliminated in favor of 13 authentic printmaker paper aesthetics, paired with 12 authentic Risograph spot inks:

13 Light Tactile Paper Palettes:

  • Risograph Classic: Federal Blue & Fluorescent Pink on unbleached warm newsprint (#FAF7F0)
  • Warm Zine Press: Coral & Forest Green on tactile parchment (#F5EFE6)
  • Pastel Risograph: Coral Pink & Sky Blue on cream cotton (#FFF9F5)
  • Fluorescent Neon: High-voltage neon ink on bright unbleached bond (#FAFAFA)
  • Lavender Lilac: Deep Violet & Sunflower Yellow on soft lavender paper (#F8F6FC)
  • Seafoam Coral: Mint Seafoam & Living Coral on ocean spray paper (#F4F9F8)
  • Sunflower Navy: Solar Sunflower & Deep Indigo on warm maize paper (#FFFDF5)
  • Terracotta Sun: Adobe Terracotta & Sunshine Yellow on baked clay paper (#FAF5EE)
  • Botanical & Ochre: Terracotta Ochre & Sage Green on French milled paper (#F8F5EE)
  • Matcha & Ink: Deep Moss & Clay Ochre on rice paper (#F2F6F3)
  • Monochrome Letterpress: Heavy Lead Black on heavy cotton rag (#F8F7F4)
  • Nordic Linen Print: Cobalt Blue & Amber on unbleached linen (#F6F8FA)
  • Kraft & Rubber Stamp: Post Office Red & Petrol Teal on raw postal kraft (#EADBCA)

12 Authentic Risograph Spot Inks (SPOT_INKS):

Julian prints with physical soy and rice bran ink drums. Developers can set inkColor?: string directly on any component to dye chips independently of the paper background:

  • Fluo Pink (#FF48B0) • Federal Blue (#0078BF) • Sunflower Yellow (#FFE800)
  • Mint Seafoam (#2EC4B6) • Scarlet Ink (#E63946) • Purple Violet (#7209B7)
  • Medium Teal (#00A896) • Forest Green (#2D6A4F) • Bright Coral (#FF6B6B)
  • Gold Ochre (#D4A373) • Terracotta (#C05621) • Soy Carbon (#1C1D1F) 
// Dye any component directly with authentic spot inks:
<Button inkColor={SPOT_INKS.fluorescentPink.hex} animationType="hydraulic-pop">
  Hot Pink Edition
</Button>
<PaperDotToggle inkColor={SPOT_INKS.mintSeafoam.hex} animationType="slingshot-snap" />
<PaperDotBadge inkColor={SPOT_INKS.terracotta.hex} label="Zine #12" />
Enter fullscreen mode Exit fullscreen mode

5. Why Open-Source AI is at the Core 🧠

The prompt for this challenge required that open-source AI be at the core of the project:

┌─────────────────────────────────────────────────────────────┐
│                    Julian's Natural Language                │
│    "A bouncy square-chip button with gentle pop physics"    │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│        Google Gemma 2B + Thinking Machines' Tinker          │
│    - Fine-tuned on PaperDots kinetic physics schema         │
│    - Generates Hooke's constants, stippling, and palettes   │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                   PaperDots Core Engine                     │
│    - 60 FPS Canvas 2D Euler Spring Integrator               │
│    - Procedural Paper Tooth & Ink Bleed Shaders             │
│    - Shadcn Registry & CLI Distribution                     │
└─────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Why Open Innovation Won:

  1. 100% Offline & Edge Freedom for Creators:
    Julian often works in print shops, off-grid residency studios, and on trains with no internet connection. Closed APIs require a persistent internet connection and recurring monthly token bills. Because our compiler runs on open-weight Gemma (using WebLLM in the browser or local Ollama), Julian can generate and compile new interactive dot components anywhere, anytime, with zero cloud lock-in.

  2. Tinker (Thinking Machines) Domain Adaptation:
    When testing generic zero-shot closed models, they constantly hallucinated invalid JSON, wrapped output in chatty conversational markdown, and produced unstable spring coefficients that exploded the canvas physics.

Using Thinking Machines' Tinker, we fine-tuned google/gemma-2-2b-it on 132 instruction-tuned pairs of natural language prompts mapped to our declarative PaperDotComponentDSL. The results were dramatic:

📊 Tinker Fine-Tuning Benchmark Results

Metric Baseline Zero-Shot Tinker Fine-Tuned (Gemma) Improvement
JSON Schema Adherence 71.4% (Syntax errors) 100.0% (Direct DSL JSON) +28.6% reliability
Physical Parameter Validity 68.2% (Wild spring values) 98.7% (Stable Hooke's constants) +30.5% kinetic realism
Average Inference Latency 1,380 ms (Cloud round-trip) 195 ms (Edge runtime) 7.08x Faster
Average Tokens Generated 340 tokens (Chatty text) 112 tokens (Pure DSL) 67.1% Less Overhead
Est. Cost per 1k Calls $0.68 $0.22 67.6% Cost Savings
  1. Data Ownership & Creative Sovereignty: Julian's proprietary zine illustrations and experimental interactive typography never leave their computer to train third-party corporate models.

6. Deployed on Render ($50 Hacktoberfest Credits) 🚀

To make PaperDots UI immediately accessible to Julian and the open-source community, we utilized the $50 Render credits from Hacktoberfest.

Using a single render.yaml Infrastructure-as-Code blueprint, Render hosts:

  • Global Edge Static Showcase: Instant load times for the interactive React 19 playground, installation hub, and registry (showcase/dist).
  • Python FastAPI Runtime: High-throughput inference server for running model inference and benchmark evaluations (api/main.py).

7. Handing It Over to Julian: What Happened? 🎉

The best part of this challenge was handing the live playground over to Julian.

I sent Julian the link to the interactive showcase, loaded up with the "Analog Futures #03" preset demo.

Julian tapped the coral square-chip button with hydraulic pop. It rippled under their trackpad and popped with a crisp paper click before snapping elastically back into place. They switched to the living equalizer play button, watched the chips dance to the audio commentary, and dragged the catenary string volume slider.

Julian's exact words:

"This is the first time the web hasn't felt like a plastic spreadsheet. Now my digital zine actually feels like it was pressed by hand."

8. Try It & Explore the Code 🔗

Conclusion & Partner Credits 🙌

Huge thanks to:

  • Hacktoberfest 2026 & DEV for the inspiring Build for a Friend prompt.
  • Thinking Machines for the Tinker platform and fine-tuning credits that made domain-adapted open-model compilation 7x faster.
  • Render for the $50 hosting credits powering our live showcase and API runtime.
  • Google Gemma for providing open-weight foundation models that allow creators to build without corporate gatekeeping.

Built with tactile ink, square chips, spring dynamics, and open-source AI.

Top comments (0)