Build frontends that refuse to break.
Lithos UI is a free, neo-brutalist React component library engineered with absolute structural integrity. It ditches fragile CSS gaps and soft shadows in favor of hard math, rigid grids, and high-contrast accessibility.
Modern web layouts often rely on the CSS gap property, which can cause unpredictable overflow and sub-pixel rendering issues on complex nested grids.
Lithos UI strictly enforces a Zero-Gap Architecture. All structural spacing is handled via a combination of explicit parent negative margins (e.g., -m-4) and direct child margins (m-4), guaranteeing that layouts snap cleanly across breakpoints without viewport bleed.
For accent colors, the dynamic theme engine does not rely on hardcoded contrast scales. Instead, it uses the YIQ Luminance formula—a mathematical calculation based on human optical sensitivity (heavily weighting the green spectrum).
When you inject a custom HEX code, the engine calculates the perceived biological brightness and automatically forces all nested typography and active UI elements to absolute #000000 or #FFFFFF to ensure maximum WCAG compliance.
CSS specificity wars ruin dynamic themes. Lithos UI utilizes a Javascript-injected Universal Override block (<style>) targeting *, :root, .dark, .obsidian with !important flags. This guarantees that user-selected dynamic tokens completely overpower hardcoded Tailwind classes, ensuring instant, glitch-free repaints.
To prevent Tailwind class bloat ("DRY" architecture), Lithos UI packages its mechanical interactions into global CSS utility tokens. By applying the .lithos-click class to any button, the element instantly inherits the system's strict 2px borders, brutalist 2px shadows, and our signature zero-latency "Hard-Drop" click physics. No redundant transition or active states required.
| Component | Status | Docs |
|---|---|---|
| Alert | Stable | Link |
| Avatar | Stable | Link |
| Accordion | Stable | Link |
| Badge | Stable | Link |
| Breadcrumb | Stable | Link |
| Button | Stable | Link |
| Calendar | Stable | Link |
| Card | Stable | Link |
| CodeViewer | Stable | Link |
| PreviewBlock | Stable | Link |
| Toast (ToastProvider) | Stable | Link |
| Toggle | Stable | Link |
| Component | Status | Docs |
|---|---|---|
| Navbar | Beta | — |
| Footer | Beta | — |
| NotFound | Beta | — |
| ComingSoon | Beta | — |
| Component | Status | Docs |
|---|---|---|
| Hero | Beta | — |
| FeatureGrid | Beta | — |
| Pricing | Beta | — |
| Testimonials | Beta | — |
| FAQ | Beta | — |
| ThemeEngine | Beta | — |
Lithos UI is currently a Code Ownership Kit. You copy the raw blocks into your project so you retain absolute control over the markup. It will eventually become a published NPM package, but it will always remain 100% free and open-source.
As we continue to grow, more ready-made components, layout blocks, and dynamic features will be added to the library.
Starting a new project? Click the Fork button at the top of the repository to instantly generate a fresh React app with the global design tokens and Theme Engine pre-configured.
Adding to an existing project?
- Ensure your project is running React and Tailwind CSS v4+.
- Copy the
index.cssglobal tokens into your main stylesheet. - Drop the components from the
/componentsfolder into your standard architecture.
Lithos UI is currently pre-1.0 (0.x.y). During this phase:
0.X.0(minor) releases may include breaking changes.0.x.X(patch) releases are intended to be safe, non-breaking updates.
After 1.0.0, Lithos UI will follow standard semantic versioning where breaking changes only ship in major versions.
See CHANGELOG.md for release history.
The entire visual weight of the library is controlled by these 7 variables. Modify them in your index.css or manipulate them via Javascript for live-theming.
:root {
--lithos-bg: #ffffff; /* The deep background */
--lithos-text: #000000; /* Primary typography */
--lithos-border: #000000; /* Structural lines */
--lithos-accent: #00ff00; /* The loud brand color */
--lithos-accent-text: #000000; /* Auto-calculated by YIQ */
--lithos-surface: #ffffff; /* Card backgrounds */
--lithos-shadow: rgba(0, 0, 0, 1); /* Brutalist shadow offset */
}(Note: Interactive physics and structural weight are handled via the @layer utilities block in index.css, primarily through the .lithos-click token.)
Lithos UI includes a native Dark Mode trigger. Simply apply the .obsidian class to the document body or top-level wrapper, and the global tokens will instantly invert, while respecting your primary --lithos-accent color.
Lithos UI is free for unlimited commercial and personal projects. See LICENSE.md for full details.