widgies

Widgies

A tiny, zero-dependency set of Web Component widgets you can drop into any web page with one script tag.

• Plain English docs—no jargon.
• Accessible by default—ARIA labels, keyboard support, high-contrast, prefers-reduced-motion.
• Auto light & dark themes—switches with prefers-color-scheme.
• Works everywhere—React, Vue, Svelte, or just HTML.

Quick Start

<!-- 1. Import Widgies from a CDN or your build folder -->
<script type="module" src="https://unpkg.com/widgies@0.1.0/dist/widgies.min.js"></script>

<!-- 2. Optional: override design tokens -->
<style>
  :root {
    /* universal */
    --widgies-radius: 0.5rem;
    --widgies-font: 16px/1.4 Inter, sans-serif;

    /* light mode */
    --widgies-surface-light: #ffffffe6;
    --widgies-text-light: #1a1a1a;
    --widgies-accent-light: #6c4cff;

    /* dark mode */
    --widgies-surface-dark: #181824e6;
    --widgies-text-dark: #f5f5ff;
    --widgies-accent-dark: #a88bff;
  }
</style>

<!-- 3. Drop a widget – no extra JS needed -->
<widgies-timer minutes="25" aria-label="25-minute timer"></widgies-timer>

Available Widgets

Tag	What it does	Key attributes
<widgies-calculator>	4-function calculator	–
<widgies-timer>	Countdown / Pomodoro timer	minutes seconds
<widgies-random-number>	Cryptographically safe RNG	min max
<widgies-qr-code>	QR code generator	text
<widgies-affirmation>	Random positive messages	interval (ms)
<widgies-ambient>	Nature sounds for focus	sound
<widgies-unit-converter>	Multi-category unit converter	–
<widgies-currency-exchange>	Real-time currency rates	–
<widgies-color-palette>	Color picker and palette tool	–
<widgies-dad-jokes>	Random dad joke generator	–
<widgies-magic-8-ball>	Classic Magic 8-Ball	–
<widgies-fortune-cookie>	Virtual fortune cookies	–
<widgies-random-image>	Curated random images	–
<widgies-tiny-planet>	Animated planet visualization	–

📖 Complete Widgets Reference →

All widgets share theme tokens, focus rings, and ARIA roles. Bundle size ≈15 kB gzipped.

Installation

npm install widgies

// Option 1: Import all widgets (auto-registers)
import 'widgies';

// Option 2: Import individual widgets
import 'widgies/calculator';
import 'widgies/timer';
import 'widgies/random-number';
import 'widgies/qr-code';
import 'widgies/affirmation';
import 'widgies/ambient';
import 'widgies/unit-converter';
import 'widgies/currency-exchange';
import 'widgies/color-palette';
import 'widgies/dad-jokes';
import 'widgies/magic-8-ball';
import 'widgies/fortune-cookie';
import 'widgies/random-image';
import 'widgies/tiny-planet';

// Option 3: Import widget classes for manual registration
import { CalculatorWidget, TimerWidget } from 'widgies';
CalculatorWidget.register();
TimerWidget.register();

Or via CDN:

<script type="module" src="https://unpkg.com/widgies@latest/dist/widgies.min.js"></script>

Development

# Install dependencies
npm install

# Build the widget bundle
npm run build

# Generate TypeScript declarations
npm run types

# Build and watch for changes
npm run dev

# Run tests
npm test

# Full build (bundle + types)
npm run prepare

License

MIT