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.

The dynamic theme engine does not rely on static "Light/Dark" toggle classes. 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.

Lithos UI is not an NPM black-box dependency. It is a Code Ownership Kit. You copy the raw blocks into your project so you retain absolute control over the markup.

Starting a new project? Click the green "Use this template" 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?

1. Ensure your project is running React and Tailwind CSS v3+.
2. Copy the index.css global tokens into your main stylesheet.
3. Drop the components from the /components folder into your standard architecture.

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.