juzmatch-design-system
v0.1.0-beta.0
Published
Shared web UI components and design tokens for JUZMATCH applications.
Readme
juzmatch-design-system
React UI components and design tokens for JUZMATCH web applications.
Install once, get the full component set, theming, and design tokens — kept in sync with the JUZMATCH Figma library.
import { Button } from 'juzmatch-design-system';
import 'juzmatch-design-system/styles.css';
export default function App() {
return <Button variant="primary">Get started</Button>;
}Install
# pnpm
pnpm add juzmatch-design-system
# npm
npm install juzmatch-design-system
# yarn
yarn add juzmatch-design-systemPeer dependencies (your app must provide these):
react≥ 18react-dom≥ 18
This package is published publicly as juzmatch-design-system.
Setup
1. Import the stylesheet — once, at your app's entry point
This sheet contains the compiled Tailwind utilities used by every component plus the design-token CSS variables. Without it, components will render unstyled.
// app/layout.tsx, _app.tsx, src/main.tsx — wherever your app starts
import 'juzmatch-design-system/styles.css';2. (Optional) Only the tokens
If you want the raw token CSS variables but plan to style outside of our components (custom CSS, your own Tailwind config, etc.), import just the token sheet:
import 'juzmatch-design-system/tokens.css';You then have access to all --jm-* CSS variables — e.g., var(--jm-color-bg-primary), var(--jm-radius-md), var(--jm-space-4).
3. That's it
You can now import any exported component:
import { Button } from 'juzmatch-design-system';Usage
Button
import { Button } from 'juzmatch-design-system';
<Button>Default</Button>
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Delete</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button fullWidth>Stretches to container</Button>
<Button disabled>Disabled</Button>
<Button onClick={() => save()}>With handler</Button>Props
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | 'primary' \| 'secondary' \| 'ghost' \| 'danger' | 'primary' | Visual style. |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Height + padding. |
| fullWidth | boolean | false | Stretch to container width. |
| disabled | boolean | false | Native disabled state. |
| type | 'button' \| 'submit' \| 'reset' | 'button' | Defaults to button to avoid accidental form submission. |
| ...rest | ButtonHTMLAttributes<HTMLButtonElement> | — | All native button attributes are forwarded. Ref forwarding is supported. |
Theming
The library ships light and dark themes out of the box. Switching is a single attribute on any ancestor element:
<html data-theme="dark">
{/* everything inside renders in dark mode */}
</html>Or scope it to a section:
<section data-theme="dark">
<Button>Dark button inside a light app</Button>
</section>All tokens are CSS variables, so theme switching is instant — no re-render, no JS.
Design tokens
Tokens are organised in two tiers:
- Primitives — raw values (
--jm-color-brand-500,--jm-radius-md, etc.). Don't use these directly in product code. - Semantic — what components and apps consume (
--jm-color-bg-primary,--jm-color-fg-default, etc.). These remap per theme.
import { tokens } from 'juzmatch-design-system';
// typed accessors returning CSS-var strings
tokens.color.bg.primary; // 'var(--jm-color-bg-primary)'
tokens.color.fg.onPrimary; // 'var(--jm-color-fg-on-primary)'
tokens.radius.md; // 'var(--jm-radius-md)'
tokens.space[4]; // 'var(--jm-space-4)'Use them in your own styles when you need design-system values but don't have a component to drop in:
<div style={{ background: tokens.color.bg.subtle, padding: tokens.space[4] }} />The full token catalogue is browsable in Storybook (see below).
TypeScript
Type definitions are bundled. No @types/... package needed.
import type { ButtonProps } from 'juzmatch-design-system';The package ships ESM and CJS builds via the exports field, so it works in Vite, Next.js (app + pages router), Remix, CRA, and node-based test runners.
Storybook (component reference)
A live Storybook is deployed per environment. Use it to browse components, inspect props, copy code snippets, and review tokens visually:
https://storybook.juzmatch.com
(URLs above will be updated to friendly domains once routing is wired up.)
Versioning
The package follows Semantic Versioning:
- Patch (
x.y.Z) — bug fixes, visual tweaks that don't affect the API. - Minor (
x.Y.0) — new components, new props, new tokens. Always backwards-compatible. - Major (
X.0.0) — breaking changes to the public API. CheckCHANGELOG.mdfor the migration notes.
Pin to a minor range in your package.json to receive bug fixes automatically:
{
"dependencies": {
"juzmatch-design-system": "^1.0.0"
}
}FAQ
Do I need to install Tailwind in my app?
No. The library ships a pre-compiled stylesheet (dist/styles.css). You only need Tailwind in your app if you want to use Tailwind utilities yourself — and even then, it doesn't have to match our version.
Can I override component styles?
Yes. Every component accepts a className prop that is merged with the built-in classes via tailwind-merge, so your overrides win without specificity hacks.
<Button className="rounded-full px-8">Pill</Button>Can I tree-shake unused components? Yes. The ESM build is fully tree-shakable. Import only what you use:
import { Button } from 'juzmatch-design-system';Does it support SSR? Yes. Components are pure React with no client-only side effects in their render paths.
Contributing
This is an internal JUZMATCH package. To propose changes, request a new component, or report a bug, see CONTRIBUTING.md in the repository.
License
UNLICENSED — © JUZMATCH. Internal use only.