matrix-design-system

A Matrix-inspired React design system: green on near-black, Open Sans for prose, Courier Prime for anything terminal-flavoured. Every component here is a real component from fabrizioduroni.it.

Install

npm install matrix-design-system

react, react-dom and framer-motion are peer dependencies — framer-motion because its AnimatePresence context has to be shared with your own animated components, which a second copy would break.

Everything in the root barrel works with just those installed. Three groups need heavier libraries, so they live behind their own entry points and you install a peer only if you import one:

| Import from | Install | For | | -------------------------------------- | ------------------------------------------------------ | ------------------------------------------ | | matrix-design-system/chart | recharts | ChartPanel, ChartTooltip, DonutChart | | matrix-design-system/markdown | react-markdown, unified, the remark/rehype plugins | Markdown | | matrix-design-system/command-palette | cmdk | CommandPalette and its items |

Nothing else is optional: the rain effect is part of the design system's identity — BrandHeader and the matrix backgrounds all render it — so matrix-rain-webgpu is a plain dependency and comes along automatically.

Use

import { Accordion, Chip, SectionHeading, StatCard } from "matrix-design-system";
import { DonutChart } from "matrix-design-system/chart";
import "matrix-design-system/styles.css";

The stylesheet must be imported after Tailwind:

@import "tailwindcss";
@import "matrix-design-system/styles.css";

The page surface must be dark. The stylesheet sets html body to #001100 on #E8FFE8; most components are near-invisible on white.

Styling

Style your own layout with Tailwind utilities — they resolve against this theme, so use its names rather than stock Tailwind colours:

| Family | Names | | -------- | ---------------------------------------------------------------------------- | | Brand | primary (#00FF41), primary-dark, secondary, accent (#39FF14) | | Surfaces | general-background (#001100), general-background-light, black, white | | Text | primary-text (#E8FFE8), secondary-text, text-above-primary | | Fonts | font-sans → Open Sans · font-mono → Courier Prime |

The breakpoint scale is overridden: xs 576 · sm 768 · md 992 · lg 1200 · xl 1600 · 2xl 2000 (px). So md: starts at 992px, not 768px — the most common way a layout built with this theme behaves differently from expected.

Composed classes worth reaching for: .glassmorphism (and -lite, -no-scale), .glow-border, .glow-container, .pill, .call-to-action, .container-fixed.

Fonts are not bundled: load Open Sans and Courier Prime yourself.

Framework-agnostic by design

The package imports nothing from any framework. Where a component needs framework behaviour it takes it as a prop, with a working default:

import NextLink from "next/link";
import NextImage from "next/image";

<InternalLink to="/blog" linkComponent={NextLink}>Blog</InternalLink>
<ImageGlow src={photo} alt="" imageComponent={NextImage} />
<Menu currentPath={usePathname()} navHrefs={...} linkComponent={NextLink} />

Without them you get a real <a> and a real <img> — PlainImage reproduces next/image's fill, placeholder and lazy-loading behaviour — so the components work anywhere, just without client-side routing or image optimisation.

No provider required

There is no theme or context provider to wrap anything in. Components read their styling from CSS custom properties, and the two global preferences (motion, glassmorphism variant) come from localStorage with sensible defaults.

License

MIT © Fabrizio Duroni

Claude Design sync

.design-sync/ and .ds-sync/ in this folder are the claude.ai/design converter. It reads the Storybook stories beside each component — there are no hand-authored previews, so a story is the only place a component's example lives.

Run /design-sync from a session rooted at this package, not at the repository root. Every path the converter uses is resolved from its working directory and it does no upward search, so a root-level run fails with [CONFIG] … ENOENT. Rooting the session here also keeps the skill consistent with itself, since it stages .ds-sync/ relative to the session root.

The two folders must stay siblings: the fork in .design-sync/overrides/ imports ../.ds-sync/lib/, and .design-sync/node_modules symlinks to ../.ds-sync/node_modules.

.design-sync/NOTES.md has the full invocation and the re-sync watch-list.