Installation

Get Karen nagging your layouts in under a minute.

Install via npm:

npm install -g @karen/cli

Or use with npx:

npx @karen/cli audit

Quick Start

Run your first audit in 3 simple steps.

Navigate to your project

cd your-project

Run the audit

karen audit

Let AI fix the issues

karen fix --ai

How It Works

Karen uses headless browser testing to catch CSS issues that slip past your eyes.

Viewport Testing
Karen tests your layouts across multiple viewports, from mobile to 4K displays.
Element Inspection
Every element is checked for overflow, improper spacing, and responsive issues.
Issue Reporting
Clear, actionable reports tell you exactly what's wrong and where.
AI Remediation
Claude analyzes the issues and generates fixes that actually work.

Overflow Detection

Karen catches elements that overflow their containers before your users do.

What Karen Catches

• Horizontal scrollbars on mobile
• Text that exceeds container width
• Images larger than their parent
• Fixed-width elements on small screens

Example Configuration

// karen.config.js
export default {
  overflow: {
    enabled: true,
    threshold: 5, // pixels
    ignore: ['.carousel', '.scrollable']
  }
}

Spacing Audit

Enforce consistent spacing throughout your design system.

Define Your Scale

// karen.config.js
export default {
  spacing: {
    scale: [4, 8, 12, 16, 24, 32, 48, 64],
    tolerance: 2 // pixels
  }
}

Karen will flag any padding or margin values that don't match your scale.

Typescale Enforcement

Keep your typography consistent by enforcing a type scale hierarchy.

What Karen Enforces

• Font sizes match your defined scale
• Line heights are appropriate for font sizes
• Heading hierarchy follows logical progression
• No random one-off font sizes scattered around

Configure Your Type Scale

// karen.config.js
export default {
  typography: {
    scale: [12, 14, 16, 20, 24, 32, 48, 64],
    lineHeight: {
      min: 1.2,
      max: 1.8
    },
    enforceHierarchy: true
  }
}

Karen flags font sizes that don't match your scale, like that random 17px you snuck in.

Color Palette Consistency

Detect rogue colors that don't belong in your design system.

What Karen Detects

• Colors not in your defined palette
• Similar but slightly different shades (like #333 vs #323232)
• Hardcoded hex values instead of CSS variables
• Inconsistent opacity values

Define Your Palette

// karen.config.js
export default {
  colors: {
    palette: [
      '#000000', '#FFFFFF', '#FF5733',
      '#3498DB', '#2ECC71'
    ],
    tolerance: 5, // allow slight variations
    requireVars: true // enforce CSS variables
  }
}

Karen will roast you for using #F3F4F5 AND #F4F5F6. Pick a system.

Accessibility & Contrast

Karen enforces WCAG guidelines so your users can actually read your content.

What Karen Checks

• Text-to-background contrast ratios (WCAG AA/AAA)
• Interactive element contrast (buttons, links, inputs)
• Touch target sizes (minimum 44x44px)
• Focus indicator visibility

Configure Accessibility Rules

// karen.config.js
export default {
  accessibility: {
    contrastLevel: 'AAA', // or 'AA'
    minTouchTarget: 44, // pixels
    checkFocus: true,
    colorBlindness: ['deuteranopia', 'protanopia']
  }
}

Gray text on gray background? Karen's calling WCAG on you.

Design System Chaos

Catch inconsistencies that creep into your design system over time.

What Karen Tracks

• Buttons styled 47 different ways across your app
• Inconsistent border radius values
• Shadow styles that don't match your elevation system
• Font weight variations that aren't documented

Document Your System

// karen.config.js
export default {
  designSystem: {
    borderRadius: [0, 4, 8, 16],
    shadows: ['sm', 'md', 'lg', 'xl'],
    fontWeights: [400, 500, 600, 700],
    trackComponents: ['button', 'input', 'card']
  }
}

Karen documents every inconsistency so you can fix them all at once.

Responsive Checks

Test across all your breakpoints automatically.

Custom Breakpoints

// karen.config.js
export default {
  breakpoints: {
    mobile: 375,
    tablet: 768,
    desktop: 1440,
    '4k': 3840
  }
}

AI-Powered Fixes

Let Claude handle the tedious CSS fixes so you can focus on building features.

Enable AI Fixes

karen fix --ai

Karen will send the audit results to Claude, which generates precise CSS fixes.

Configuration

// karen.config.js
export default {
  ai: {
    provider: 'claude',
    model: 'claude-3-5-sonnet',
    autoApply: false // require confirmation
  }
}

karen.config.js

Complete configuration reference for customizing Karen's behavior.

Full Configuration Example

// karen.config.js
export default {
  // Pages to audit
  pages: ['http://localhost:3000', '/about', '/contact'],
  
  // Viewport configurations
  breakpoints: {
    mobile: 375,
    tablet: 768,
    desktop: 1440
  },
  
  // Overflow detection
  overflow: {
    enabled: true,
    threshold: 5,
    ignore: ['.carousel']
  },
  
  // Spacing audit
  spacing: {
    scale: [4, 8, 12, 16, 24, 32, 48, 64],
    tolerance: 2
  },
  
  // Typography checks
  typography: {
    scale: [12, 14, 16, 20, 24, 32, 48, 64],
    lineHeight: { min: 1.2, max: 1.8 },
    enforceHierarchy: true
  },
  
  // Color palette
  colors: {
    palette: ['#000', '#FFF', '#FF5733'],
    tolerance: 5,
    requireVars: true
  },
  
  // Accessibility
  accessibility: {
    contrastLevel: 'AAA',
    minTouchTarget: 44,
    checkFocus: true
  },
  
  // Design system
  designSystem: {
    borderRadius: [0, 4, 8, 16],
    shadows: ['sm', 'md', 'lg', 'xl'],
    fontWeights: [400, 500, 600, 700]
  },
  
  // AI configuration
  ai: {
    provider: 'claude',
    model: 'claude-3-5-sonnet',
    autoApply: false
  },
  
  // CI integration
  ci: {
    failOn: ['critical', 'high'],
    outputFormat: 'json'
  }
}

Custom Rules

Extend Karen with your own CSS auditing rules.

// karen.config.js
export default {
  rules: {
    'no-red-text': {
      check: (element) => {
        const color = getComputedStyle(element).color
        return color.includes('rgb(255, 0, 0)')
      },
      message: 'Red text detected. Karen disapproves.',
      severity: 'warning'
    }
  }
}

karen audit

Run a comprehensive layout audit on your application.

karen audit [options]

--config

Path to config file

--pages

Specific pages to audit

--output

Output file for results

karen fix

Apply fixes to detected issues, optionally with AI assistance.

karen fix [options]

--ai

Use AI to generate fixes

--auto-apply

Apply fixes without confirmation

--severity

Only fix issues above severity level

karen watch

Watch for changes and audit automatically during development.

karen watch

Karen will monitor your CSS files and re-audit on changes.

karen ci

Run Karen in CI/CD pipelines to catch issues before deployment.

GitHub Actions Example

name: Karen Audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g @karen/cli
      - run: karen ci --fail-on critical

Programmatic Usage

Use Karen programmatically in your Node.js applications.

import { Karen } from '@karen/cli'

const karen = new Karen({
  pages: ['http://localhost:3000'],
  breakpoints: { mobile: 375, desktop: 1440 }
})

const results = await karen.audit()
console.log(results.issues)

if (results.hasCritical) {
  await karen.fix({ ai: true })
}

Troubleshooting

Common issues and how to resolve them.

Karen can't find my pages

Make sure your dev server is running and the URLs in your config are correct.

Too many false positives

Adjust the threshold values in your config or add specific elements to the ignore list.

AI fixes aren't working

Ensure you have your Claude API key set in your environment variables.

Best Practices

Get the most out of Karen with these recommendations.

Run audits frequently
Use watch mode during development to catch issues early.
Start with defaults
Don't over-configure initially. Karen's defaults work for most projects.
Review AI fixes
Always review AI-generated fixes before applying them to production.
Integrate with CI
Block deployments on critical issues to maintain layout quality.