|
1 | 1 | # @kidcash/ui |
2 | 2 |
|
3 | | -Playful React component library extracted from [KidCash](https://www.kidcashapp.com), the family allowance app. |
| 3 | +[](https://www.npmjs.com/package/@kidcash/ui) |
| 4 | +[](https://bundlephobia.com/package/@kidcash/ui) |
| 5 | +[](./LICENSE) |
| 6 | +[](https://www.typescriptlang.org/) |
| 7 | +[](https://www.kidcashapp.com) |
4 | 8 |
|
5 | | -🚧 v0.1.0 in development. See [docs](https://kit.kidcashapp.com) (deploying soon). |
| 9 | +> Playful React component library extracted from [**KidCash**](https://www.kidcashapp.com), the family allowance app — liquid glass, spring physics, and 9 themes for finance, family, and kid-focused interfaces. |
6 | 10 |
|
7 | | -## Install |
| 11 | +**Battle-tested in production** at [kidcashapp.com](https://www.kidcashapp.com), where parents and kids manage [allowance](https://www.kidcashapp.com/allowance), [chores](https://www.kidcashapp.com/chores), and [savings goals](https://www.kidcashapp.com/save-for) together. Free, open source, MIT licensed. |
8 | 12 |
|
9 | 13 | ```bash |
10 | | -npm install @kidcash/ui |
| 14 | +npm install @kidcash/ui framer-motion |
11 | 15 | ``` |
12 | 16 |
|
13 | | -MIT licensed (code). Mascot illustration: see [LICENSE-MASCOT.md](./LICENSE-MASCOT.md). |
| 17 | +> 🚧 **v0.1.x — early access.** API may shift before 1.0. Please pin exact versions. |
| 18 | +
|
| 19 | +## Quick start |
| 20 | + |
| 21 | +```tsx |
| 22 | +import '@kidcash/ui/preset.css'; |
| 23 | +import { ThemeProvider, GlassCard, Button } from '@kidcash/ui'; |
| 24 | + |
| 25 | +export default function App() { |
| 26 | + return ( |
| 27 | + <ThemeProvider defaultTheme="aurora"> |
| 28 | + <GlassCard variant="strong" glow="primary"> |
| 29 | + <h1>Hello, glass.</h1> |
| 30 | + <Button variant="primary">Get started</Button> |
| 31 | + </GlassCard> |
| 32 | + </ThemeProvider> |
| 33 | + ); |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +Wrap your app in `ThemeProvider`, import the preset CSS, and you're set. Peer deps: `react >=19`, `react-dom >=19`, `tailwindcss >=4`. |
| 38 | + |
| 39 | +## What's inside |
| 40 | + |
| 41 | +**Foundations** — `GlassCard`, `Button`, `Pill`, `Avatar`, `AvatarStack`, `Skeleton`, `Keyboard` |
| 42 | + |
| 43 | +**Typography & motion** — `GradientText`, `AnimatedNumber`, `Marquee`, `Spotlight`, `Confetti`, `FloatingCoins`, `FlyingMascot` |
| 44 | + |
| 45 | +**Inputs & feedback** — `Slider`, `ProgressBar`, `EmojiPicker`, `Tooltip`, `Toast` (`ToastProvider` + `useToast`) |
| 46 | + |
| 47 | +**Overlays** — `Modal`, `Sheet`, `CommandPalette`, `BackToTop` |
| 48 | + |
| 49 | +**Family-finance specials** — `BirthdayCountdown`, `AchievementBadge`, `AchievementBadgeGrid`, `CelebrationOverlay` |
| 50 | + |
| 51 | +27 components total, all framer-motion-animated, all theme-aware, all server-component-friendly (`'use client'` boundaries marked). |
| 52 | + |
| 53 | +## 9 themes out of the box |
| 54 | + |
| 55 | +| Dark | Light | |
| 56 | +|---|---| |
| 57 | +| `aurora`, `frosted-crystal`, `candy-glow`, `ocean-depth`, `sunset-dunes`, `midnight-garden` | `cotton-cloud`, `lemon-fizz`, `mint-breeze` | |
| 58 | + |
| 59 | +Switch live with `<ThemeSelector />` or programmatically via `useTheme()`. All theme tokens are CSS custom properties so you can extend the palette without forking. |
| 60 | + |
| 61 | +## Why this kit exists |
| 62 | + |
| 63 | +[shadcn](https://ui.shadcn.com) nailed minimal. [Mantine](https://mantine.dev) nailed comprehensive. [Aceternity](https://ui.aceternity.com) and [Magic UI](https://magicui.design) nailed flashy. None of them nailed **playful, kid-friendly, and finance-native** — the aesthetic that makes a 9-year-old want to deposit their birthday money and a parent feel safe routing the family's allowance through your app. |
| 64 | + |
| 65 | +That's the gap `@kidcash/ui` fills, extracted directly from [KidCash](https://www.kidcashapp.com)'s production codebase. Every primitive earned its keep on a real surface used by real families. |
| 66 | + |
| 67 | +## Used in production by KidCash |
| 68 | + |
| 69 | +Built and maintained by the team at [**KidCash**](https://www.kidcashapp.com) — a multi-platform family allowance app available on iOS, Android, web, Apple Watch, Apple TV, Vision Pro, macOS, Siri Shortcuts, and Alexa. |
| 70 | + |
| 71 | +If this kit is useful to you, the easiest way to support it is to [download the KidCash app](https://www.kidcashapp.com) and tell another parent. The proceeds from KidCash fund development of this kit. |
| 72 | + |
| 73 | +You can read more about the family-finance philosophy behind it on the [KidCash blog](https://www.kidcashapp.com/blog). |
| 74 | + |
| 75 | +## Documentation & demos |
| 76 | + |
| 77 | +- 📖 **Live playground:** [kit.kidcashapp.com](https://kit.kidcashapp.com) (deploying soon) |
| 78 | +- 📦 **npm package:** [npmjs.com/package/@kidcash/ui](https://www.npmjs.com/package/@kidcash/ui) |
| 79 | +- 🐛 **Issues:** [github.com/simsketch/kidcash-ui/issues](https://github.com/simsketch/kidcash-ui/issues) |
| 80 | +- 💬 **Discussions:** [github.com/simsketch/kidcash-ui/discussions](https://github.com/simsketch/kidcash-ui/discussions) |
| 81 | +- 🌐 **The app this kit powers:** [kidcashapp.com](https://www.kidcashapp.com) |
| 82 | + |
| 83 | +## Versioning & API stability |
| 84 | + |
| 85 | +> 🚧 v0.1.x is **early access**. APIs may break between minor versions before 1.0 — please pin exact versions in your `package.json`. |
| 86 | +
|
| 87 | +Once we cut 1.0 we follow semantic versioning strictly: breaking changes go through one minor of deprecation warnings before they land. |
| 88 | + |
| 89 | +## Contributing |
| 90 | + |
| 91 | +PRs welcome. The fastest path: |
| 92 | + |
| 93 | +```bash |
| 94 | +git clone https://github.com/simsketch/kidcash-ui |
| 95 | +cd kidcash-ui && pnpm install |
| 96 | +pnpm --filter playground dev |
| 97 | +# edit packages/ui/src/components/<your-component>.tsx |
| 98 | +# Vite HMR picks it up immediately via the source alias |
| 99 | +``` |
| 100 | + |
| 101 | +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the longer version. Tests run with `pnpm --filter @kidcash/ui test`. CI auto-publishes on `v*` tag pushes via [npm provenance](https://docs.npmjs.com/generating-provenance-statements) (signed build attestations). |
| 102 | + |
| 103 | +## License |
| 104 | + |
| 105 | +- **Code:** MIT — use it however you want, commercial or personal. |
| 106 | +- **Mascot illustration** (`@kidcash/ui/mascot.png`): see [LICENSE-MASCOT.md](./LICENSE-MASCOT.md). The KidCash mascot is **not** MIT — please don't ship it as your own brand. |
| 107 | +- **KidCash brand, logos, copy:** © KidCash. The kit is open; the brand isn't. |
| 108 | + |
| 109 | +--- |
| 110 | + |
| 111 | +<sub>Made with 💜 by the team at [KidCash](https://www.kidcashapp.com) — the family allowance app for parents who want to teach money instead of just track it.</sub> |
0 commit comments