Meridian
A general-purpose open-source design system by Efolusi. 123 accessible React components, 167 design tokens in light, dark and compact, 12 blocks, and 8 full example apps — served browser-native with no build step.
Live docs · Components · Blocks · Example apps · Themes
Warm paper, espresso ink, hairline structure. Copy it, theme it, ship it.
Quickstart
Four tags. No install, no bundler, no config — every component lands on one global.
<link rel="stylesheet" href="https://meridian.efolusi.com/styles.css">
<script src="https://unpkg.com/[email protected]/umd/react.production.min.js"></script>
<script src="https://unpkg.com/[email protected]/umd/react-dom.production.min.js"></script>
<script src="https://meridian.efolusi.com/_ds_bundle.js"></script>
const { Button, Card, CardContent, CardHeader, CardTitle, Stat } = window.EfolusiDesignSystem_4ffc3d;
<Card style={{ '--card-spacing': '20px' }}>
<CardHeader><CardTitle>Revenue</CardTitle></CardHeader>
<CardContent><Stat label="MRR" value="$48.2k" delta="12.4%" direction="up" /></CardContent>
<CardContent><Button onClick={save}>Save changes</Button></CardContent>
</Card>
A complete runnable page is in hello.html — open it in a browser, nothing else required.
Install source from the registry
Meridian is also a public GitHub Registry. Compatible registry clients can
install editable component source, types, usage guidance, and required Meridian
dependencies from efolusi/meridian/<item>. The same catalog is available over
HTTP at https://meridian.efolusi.com/site/registry.json, with installable items
under https://meridian.efolusi.com/site/registry/<item>.json.
Dark mode and compact density are attribute scopes, not rebuilds:
<html data-theme="dark" data-density="compact">
Other ways to install
| Path | When to use it | How |
|---|
| npm | you have a bundler (Vite, Next, Remix) | npm install @efolusi/meridian |
| CDN (above) | prototypes, demos, a single-file artifact | point the two tags at meridian.efolusi.com |
| Vendor the folder | you want to own and edit the source | copy the repo; link styles.css and _ds_bundle.js |
| Vendor one component | you need Button, not 109 | copy components/<group>/<Name>.jsx + .d.ts — MIT, no attribution required |
Meridian Guard
Guard checks authored React code against Meridian's generated component, icon,
token, deprecation, and accessibility contracts:
npm install --save-dev @efolusi/meridian-guard
npx meridian-guard src
See the Guard guide for CI, JSON output, exit codes,
the programmatic API, and current static-analysis boundaries.
npm
npm install @efolusi/meridian
import '@efolusi/meridian/styles.css'; // once, at the app root
import { Button, Field, FieldLabel } from '@efolusi/meridian';
// or per component, for the smallest graph — with or without the extension:
import { Button } from '@efolusi/meridian/forms/Button.js';
react and react-dom are peer dependencies (>=18). The package is the same source as the CDN bundle, compiled to ES modules, and it carries its own fonts, so the stylesheet works with no extra asset setup. Types are included and compile against @types/react 18 and 19.
Design language
Palette, type, spacing, motion, and the voice rules live in guidelines/brand.md. Accessibility, forms, and governance are in guidelines/.
What it covers
Meridian is general-purpose: the primitives and the patterns for an entire product surface, not just a component grab-bag. The example apps in showcases/ put them to work across the archetypes most teams reach for:
- AI workspace — chat threads, tool calls, run steps, an inline terminal → ChatMessage, PromptComposer, AgentRun, Terminal.
- Infrastructure console — clouds, databases, SSL, DNS, health at a glance → StatusDot, KeyValueList, CopyField, Table, Terminal.
- File tools — upload, convert, encode/decode, scan → FileDrop, FileTile, Progress.
- Trading & finance — portfolios, positions, P&L, live signals → Sparkline, Stat, Table, PaymentCard.
- Admin & marketing — dashboards, settings, pricing, docs → the full display, navigation, and data tiers.
Every component and screen here is original. Meridian has its own three-stroke mark (assets/meridian-mark.svg): a minimal /// symbol and forward path rendered in espresso. The visual brief pairs it with warm sand neutrals, humanist sans type, subtle 4px radii, comfortable density, light and dark themes, Lucide icons, and springy motion. No prior codebase or product UI was recreated.
Blocks
Pre-composed sections in blocks/ (Blocks group in the Design System tab): App shell, Login, Stats dashboard, Settings, Hero, Pricing, FAQ, 404 page, 500 page, Offline state, Empty state, Activity feed. Copy a block's markup as the starting point for a page — they compose the primitives, so they inherit theme + density automatically.
Landing rhythm (opt-in)
landing.css is a separate, opt-in layer for marketing pages: --section-y, --hero-top, --hero-bottom, --page-hero-top, --page-hero-bottom (64/80/96px section rhythm across phone, tablet, desktop) plus thin .mrd-section, .mrd-hero, .mrd-page-hero and .mrd-container classes.
It is deliberately not part of the token contract: how much air sits between marketing sections belongs to the page, not to a component. Import it only where you want that rhythm.
<link rel="stylesheet" href="https://meridian.efolusi.com/landing.css">
import '@efolusi/meridian/landing.css'
Theming & density
- Dark theme: set
data-theme="dark" on <html> or any subtree. Only semantic aliases remap (espresso surfaces, cream text, caramel links, retuned status tints); ramps stay fixed. Components are theme-safe because they style against semantic tokens only.
- Compact density: set
data-density="compact" for data-heavy ops views — control heights drop to 24/30/38px and table rows tighten via --table-pad-y/x.
- Both are attribute scopes, so a dark page can host a light card and vice versa. Specimen: Theming group in the Design System tab.
Patterns
guidelines/brand.md — palette derivation, type and spacing scales, motion, iconography, voice and copy rulesguidelines/theming.md — bring your own brand: token layers, the semantic override set, dark-mode invariants, font swaps, contrast dutiesguidelines/forms.md — validation timing (blur → change → submit), error copy, submit states, async checksguidelines/patterns.md — the product-state playbook: loading, empty, error, destructive flows, and agent surfacesguidelines/frameworks.md — install and integration guides for Next.js, Vite, Remix, and the zero-build CDN pathguidelines/accessibility.md — focus rules, full keyboard map, contrast targets, per-component semanticsguidelines/governance.md — semver rules, contribution contract, do/don't, deprecation policy
Component library
Authored from scratch (no source inventory existed). Namespace: window.EfolusiDesignSystem_4ffc3d.
components/forms/ — Button, IconButton, Input, Textarea, Select (+Trigger, +Value, +Content, +Group, +Label, +Item, +Separator), NativeSelect (+Option, +OptGroup), Checkbox, RadioGroup (+Item), Switch, Slider, Combobox (+Value, +Trigger, +Clear, +Input, +Content, +List, +Item, +Group, +Label, +Collection, +Empty, +Separator, +Chips, +Chip, +ChipsInput), NumberInput, InputOTP (+Group, +Slot, +Separator), ButtonTile (+Group), Toggle (+Group), ButtonGroup, InputGroup, Field (+Set, +Legend, +Group, +Content, +Label, +Title, +Description, +Separator, +Error), Labelcomponents/display/ — Card, Badge, Tag, Avatar (+AvatarGroup), Kbd, Divider, Separator, Accordion, Link, Toolbar, TreeList, Item (+Group, +Separator, +Media, +Content, +Title, +Description, +Actions, +Header, +Footer), Collapsible, AspectRatio, ScrollArea, Carousel, Resizablecomponents/navigation/ — Tabs, Breadcrumbs, Pagination, SegmentedControl, PageControl, SideNav, TopNav, Steps, Menubar, NavigationMenucomponents/feedback/ — Dialog, ConfirmDialog, Toast (Toaster + toast), Tooltip, Alert, Banner, Progress, Spinner, Loadercomponents/data/ — composable Chart (Recharts 3), Table, Stat, Empty, Skeleton, BarChart, LineChart, DonutChart, Sparkline, KeyValueList, StatusDotcomponents/overlay/ — composable DropdownMenu, Popover, Drawer, Sheet, Command (+Dialog, +Input, +List, +Empty, +Group, +Item, +Shortcut, +Separator), ContextMenu, HoverCard (+Trigger, +Content), Portalcomponents/ai/ — Message (+Group, +Avatar, +Content, +Header, +Footer), MessageScroller (+Provider, +Viewport, +Content, +Item, +Button), Bubble, ChatMessage, PromptComposer, RichComposer, Reasoning, ToolCall, AgentRun, Task, Todo, Confirmation, Conversation, Citation (+SourceList), SourceCard, Suggestions, PromptSteps, SelectionQuote, Marker, ModelSelector, UsageMeter, FeedbackBar, DocumentCard, GeneratedImage, Sandbox, WebPreview, Player, Transcriptcomponents/code/ — CodeBlock, Terminal, CopyField, Diff, Console, Exception, EnvListcomponents/files/ — Attachment (compound family), FileDrop, FileTile, FileTypeIconcomponents/dates/ — Calendar (+DayButton), TimePicker; date pickers compose Calendar with Popover and Fieldcomponents/finance/ — PaymentCardcomponents/icons/ — Icon (Lucide loader)
Intentional additions beyond the classic starter set: Icon (required wrapper for the copied Lucide SVGs), plus the data/overlay tier (Table, Stat, Drawer, …) sized to what the console, docs, and marketing kits actually use — nothing speculative.
Index
The layout is Meridian's own, organized by purpose: the system core stays at the root (that is the vendoring API and the compiler contract), the library and demo surfaces each get one shallow, self-describing directory, and the docs site consumes them all. Full rationale in ARCHITECTURE.md.
styles.css — global entry; imports everything under tokens/ (link this one file and the system is live)registry.json — source registry for compatible clients using efolusi/meridian/<item>tokens/ — fonts.css, colors.css, typography.css, spacing.css, effects.css, base.cssassets/ — Meridian icon, horizontal light/dark lockups, favicon, brand board and social artwork; fonts/ (5 variable WOFF2 + OFL license texts); icons/ (118 curated SVGs + license)_ds_bundle.js + _ds_manifest.json — compiled component bundle and machine-readable manifest (generated by the DS compiler; see ARCHITECTURE.md)components/<group>/ — the 123 components; each ships .jsx + .d.ts + .prompt.md + a group card HTMLblocks/ — 9 pre-composed sections to paste into a pageshowcases/<app>/ — 8 example apps in plain JSX: agent, auth, console, docs, infra, tools, trader, websitestarters/<journey>/ — 9 journeys to copy wholesale, each with linked pages and a consistent shell: marketing, auth, dashboard, app, docs, AI workspace, CRM, finance operations, and service desksite/ — the docs website (home, docs, components, blocks, example apps, charts, themes, colors), plus examples/ (the live demos), registry.json, and generated registry/ install itemsguidelines/ — foundation specimen cards + brand (design language), accessibility, forms, governancehello.html — a complete runnable page; open it in a browser to see the system working with nothing installedskills/ — the agent skill entry pointpackages/ — source workspaces for the standalone public tokens, icons, and Meridian Guard packages; publishable output is generated under each dist/mcp/ — independently versioned Meridian registry server workspacescripts/ — registry generator, contrast check, runtime-copy drift checktokens.json (DTCG) + tailwind.preset.js — design tokens for Style Dictionary, Figma Variables, and Tailwind (generated by scripts/build_tokens.py)ARCHITECTURE.md — how the pieces fit · STYLEGUIDE.md — contributor conventionsLICENSE — MIT · · — component contract + PR checklist
Showcases vs starters: showcases (showcases/) are rich screens written in plain JSX so you can lift code straight into a React app; starters (starters/) are self-contained multi-page journeys you copy wholesale. Four pairs intentionally cover the same category in both forms (console/dashboard, auth, website/marketing, docs); the AI workspace, CRM, finance operations, and service desk starters extend coverage into domain-specific enterprise workflows.
Caveats
- No original font binaries were provided; Bricolage Grotesque, Figtree, and JetBrains Mono (all OFL, from google/fonts) are the chosen substitutes. Replace the files in
assets/fonts/ to swap.
- Meridian's logo system is resolution-independent SVG; the social preview is also exported as a 1200×630 PNG for broad crawler support.
- All showcase screens are original demonstrations of the system, since no existing product UI was available to recreate.
License
MIT — free for commercial and personal use, modification, and redistribution. See LICENSE. Bundled fonts (SIL OFL 1.1) and Lucide-derived icons (ISC/MIT) keep their own licenses: THIRD_PARTY_NOTICES.md. The Meridian mark and the "Meridian"/"Efolusi" names are not covered by the MIT grant — don't use them to brand derived systems. Contributions welcome: CONTRIBUTING.md.
