Introduction & Philosophy

Getting Started

BrutxUI is a high-fidelity React component registry built with a Neo-Brutalist design language. Rather than operating as a heavy node dependency, BrutxUI is a copy-paste-first component library (inspired by shadcn/ui) designed for full customization, performance, and accessibility.

Honest Positioning & Use Cases

Neo-Brutalism is distinct, loud, and high-contrast. We built BrutxUI with a clear purpose in mind:

Where BrutxUI Shines

Best suited for bold SaaS projects, developer portals, indie hacker utilities, creative portfolios, analytics dashboards, web3 landing pages, and consumer tools trying to break through generic template noise.

Where to Soften It

May not be ideal out-of-the-box for highly conservative enterprise intranets, medical records, or traditional corporate fintech systems—unless you leverage our built-in Pastel or Monochrome theme presets to soften the contrast.

Why copy-paste over npm dependencies?

Following the shadcn/ui workflow philosophy, you install BrutxUI components directly into your local components folder (e.g. components/ui/).

100% Code Ownership: The code belongs to you. Need to change the core logic of a Popover or alter a Button variant? Open the file and edit it directly. No waiting on library updates.
Zero Runtime Overhead: Only bundle components you are actively importing. Tree-shaking operates natively at build time.
Composability over Abstraction: Simple APIs with low nesting depths to make extensions extremely intuitive.

System Customizability (CSS Variables & Presets)

BrutxUI features a unified theme and tokens design system built around standard CSS custom properties. You can configure borders, shadows, and base colors globally in your global CSS file.

Global Design Tokens

Alter shadow offsets and border widths globally. The components will adjust automatically:

:root {
    --brutal-border-width: 3px;     /* Thickness of outlines */
    --brutal-border-color: #000000; /* Border colors */
    --brutal-shadow-color: #000000; /* Drop shadow colors */
    --brutal-shadow-offset: 4px;    /* Normal card/button offset */
}

Customization Presets

Easily adjust the visual aggression level of BrutxUI components by wrapping your application in one of our built-in preset classes:

1. Classic Brutalism

High-contrast borders, thick shadows, and punchy neon accents.

2. Pastel Neo-Brut

Slightly rounded border radius, softened shadows, and comforting pastel colors.

3. High-Contrast Mono

Strict black-and-white visual palette for sleek, minimalist interfaces.

AI-First Integration (Cursor / LLMs)

We provide first-class support for AI coding assistants. If you use Cursor, VSCode, or other LLMs, they can seamlessly digest our registry structure:

llms.txt: Accessible at the root workspace (/llms.txt), offering a condensed context layout for large language models to construct error-free components.
.cursorrules: Pre-configured guidelines enforcing accessibility, design token safety, and TypeScript correctness.

Accessibility First

BrutxUI must not compromise usability. Every BrutxUI component is built with accessibility as a core constraint:

Radix UI Foundation: Primitives handle proper ARIA state attributes, screen reader interaction traps, focus rings, and browser focus management natively.
Color Contrast: Heavy outline indicators protect visibility inside both light and dark modes.
Responsive Layouts: Responsive flex-grid grids protect content readability across screen viewports.