Aio Neobrutalism

Neobrutalism Design System Bootstrapper

Objective Workflow

Phase 1: DETECT — Identify Project Tech Stack

Scan the project root to determine the web framework and styling approach:

# Check for package.json, framework config files, CSS preprocessors
ls package.json tsconfig.json vite.config.* next.config.* nuxt.config.* tailwind.config.* postcss.config.* 2>/dev/null

Identify:

• Framework: React, Vue, Svelte, Next.js, Nuxt, Astro, plain HTML
• Styling: Tailwind CSS, CSS Modules, styled-components, Sass/Less, plain CSS
• Component library: shadcn/ui, Radix, MUI, Vuetify, or none
• Entry points: main CSS file, layout files, global styles location

Phase 2: GENERATE — Create CSS Tokens and Base Styles

Based on detected stack, generate the appropriate token format:

• Tailwind: Extend theme in tailwind config with neobrutalism tokens (borders, shadows, colors)
• CSS Variables: Generate :root block with all design tokens
• styled-components/CSS-in-JS: Generate a theme object
• Plain CSS: Copy code/base.css directly

Always include the neobrutalism fonts:

<link href="https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,100..900;1,100..900&family=Bricolage+Grotesque:wght@200..800&display=swap" rel="stylesheet" />

Phase 3: APPLY — Transform Existing UI Components

1. List all UI component files in the project (buttons, cards, inputs, modals, nav)
2. For each component, apply the 6 Rules (see reference below):
   • Add thick black borders (2-4px solid #000)
   • Replace soft shadows with hard shadows (4px 4px 0 #000)
   • Remove border-radius or reduce to 0px
   • Replace gradients with solid vibrant colors
   • Increase font weights to 700-900
   • Add press-down or elevate-up interaction patterns
3. Prioritize: buttons first, then cards, then inputs, then navigation

Phase 4: REVIEW — Show Before/After

For each transformed component:

• Show the before state (existing styles)
• Show the after state (neobrutalism styles)
• Flag any anti-patterns found (blurred shadows, gradients, excessive radius)
• Verify hover states and cursor: pointer on all interactive elements

Reference Material

The 6 Rules

1. Thick black borders: 2-4px solid #000
2. Hard shadows: 4px 4px 0 #000 (NEVER blur)
3. Sharp corners: 0px border-radius
4. Vibrant colors: 2-3 accent colors max, high contrast
5. Bold typography: weights 700-900
6. No gradients: solid colors only

Core Tokens

/* Borders */
border: 2px solid #000; /* inputs */
border: 3px solid #000; /* cards, containers */

/* Shadows */
box-shadow: 4px 4px 0 #000; /* standard */
box-shadow: 8px 8px 0 #000; /* modals */

/* Timing */
transition: all 100ms cubic-bezier(0.4, 0, 0.2, 1);

Two Interaction Patterns

Press-Down (Buttons)

/* Default: elevated */
box-shadow: 4px 4px 0 #000;

/* Hover: lands where shadow was */
hover {
  transform: translate(4px, 4px);
  box-shadow: none;
  background: #000;
  color: #fff;
}

/* Active: tactile feedback */
active {
  scale: 0.95;
}

Elevate-Up (Navigation)

/* Default: flat */
border: transparent;
box-shadow: none;

/* Hover: lifts up */
hover {
  box-shadow: 4px 4px 0 #000;
  transform: translate(-1px, -1px);
  border-color: #000;
}

Anti-Patterns

• Blurred shadows
• Gradients
• Excessive border-radius (>30px)
• More than 3 accent colors
• Transitions >300ms
• Missing hover states on interactive elements
• Missing cursor: pointer on clickable elements

Component References

Interactive

• Button - variants, sizes, states
• Input - form inputs, focus
• Select - dropdowns, menus
• Checkbox - checkboxes, switches

Containers

• Card - static vs clickable
• Dialog - modals
• Sheet - slide-over panels
• Tabs - tab navigation

Feedback

• Badge - tags, status
• Alert - inline notifications
• Toast - temporary notifications

Supporting

• Popover - floating content
• Table - data tables
• Label - typography

System

• Base CSS - complete stylesheet (copy to project)
• CSS Variables - complete tokens
• Colors - palette reference
• Interaction Patterns - detailed patterns
• Affordances - clickable vs static
• Decorations - sketchy effects

Resources

• Research Report - comprehensive research
• Neobrutalism.dev - ShadCN components
• NN/G Article - definition