Beathers is a flexible utility library built for developers who want full control over their design system. It compiles only what you need, based on a configuration file (.js, .ts, or .json) where you define your own colors (with light/dark variants), fonts, breakpoints, and more. You can enable or disable entire sections like typography or layout helpers to keep your CSS output minimal and tailored.

Beathers features an enhanced CLI experience with professional, user-friendly console output including meaningful emojis, color coding, and clear formatting for all interactions. The CLI tools simplify config creation and support importing fonts and color packs with ease.

The library works with both SCSS and plain CSS, making it compatible with any modern frontend project, no matter your stack.

Get Started

Installation

npm install beathers
# or
yarn add beathers
# or
pnpm add beathers

Create Configuration File

Use the interactive CLI to create your theme configuration:

npx beathers init

This will prompt you to:

• Choose your configuration file format (JSON, JS, or TypeScript)
• Set up initial theme values like colors and typography
• Configure which features to enable/disable

Build Your Theme

Generate your custom CSS from the configuration:

npx beathers

CLI Commands

Beathers provides a comprehensive set of CLI commands to manage your design system with an enhanced, user-friendly interface:

Configuration

• npx beathers init - Initialize a new configuration file with interactive prompts
• npx beathers - Build theme from configuration with visual progress indicators
• npx beathers - Build with custom output path

Font Management

• npx beathers add-font - Add a new font to your configuration
• npx beathers remove-font - Remove a font from your configuration
• npx beathers import-font-sample - Import a sample font configuration

Color Management

• npx beathers add-colors - Add new colors to your configuration
• npx beathers remove-color - Remove a color from your configuration
• npx beathers import-color-pack - Import a complete color pack from available packs
• npx beathers import-color - Import a specific color from available packs

Help & Information

• npx beathers --help - Show all available commands
• npx beathers --version - Show current version

Import in Your Project

CSS Import (Recommended):

/* Import the compiled CSS */
@import 'node_modules/beathers/css/beathers.min.css';

SCSS Import:

// Import the entire library
@import 'node_modules/beathers/scss/beathers.min.scss';

// Or import specific modules
@import 'node_modules/beathers/scss/functions/colors';
@import 'node_modules/beathers/scss/style/grid';

// Or import using @use with changing variables
@use 'node_modules/beathers/scss/beathers.min.scss' with (
  $colors: (
    1: (
      'light': '#000000',
      'dark': '$ffffff',
    ),
  )
);

JavaScript/Framework Import:

// Next.js, React, Vue, Angular
import 'beathers/css/beathers.min.css'

Example Configuration

{
  "colors": {
    "primary": { "light": "#007bff", "dark": "#0056b3" },
    "success": { "light": "#28a745", "dark": "#20c997" }
  },
  "typography": {
    "defaultFontFamilies": ["Inter", "system-ui", "sans-serif"]
  },
  "settings": {
    "axisDivisions": 12,
    "breakpoints": {
      "sm": "640px",
      "md": "768px",
      "lg": "1024px"
    }
  }
}

Configuration

Beathers uses a configuration file to customize your theme. All options are optional and have sensible defaults.

Configuration File Options

You can create one of these files in your project root:

• beathers.configs.json - JSON format
• beathers.configs.js - JavaScript format
• beathers.configs.ts - TypeScript format (with type safety)

Key Configuration Sections

| Section | Description | Purpose | | -------------- | -------------------------------------------------- | --------------------------------------------------- | | colors | Define your color palette with light/dark variants | Brand colors, state colors (success, warning, etc.) | | typography | Configure fonts, sizes, and text settings | Font families, weights, sizes, and formatting | | settings | Layout and spacing configuration | Grid system, breakpoints, spacing values | | roles | Enable/disable specific features | Control which utilities are generated |

Common Configuration Properties

| Property | Type | Example | | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | COLORS | | color Color variants (as json) | "color": { light: #${string}$, dark: #${string}$ } | "primary": {"light": "#007bff", "dark": "#0056b3"} | | TYPOGRAPHY | | defaultFontFamilies Fallback fonts (as array) | string[] | ["system-ui", "sans-serif"] | | fontMainPath Your fonts path | string | "/fonts/" | | fontFormat Your fonts format | string | "woff2" | | fontWeights Your fonts weights (as array) | thin | extra-light | light | regular | medium | semibold | bold | extra-bold | black | ["regular", "medium", "bold"] | | fontStyles Your fonts styles (as array) | normal|italic,oblique | ["normal"] | | fontSizes Your fonts sizes (as json) | Record<string, ${number}px | ${number}rem | ${number}em> | subtitle1: "16px" (Azvailable: h1, h2, h3, h4, h5, h6, subtitle1, subtitle2, button, body1, body2, caption, overline) (Note: You can add/remove) | | textTruncate Text truncation | number | 3 | | fonts Custom font definitions (Local/External) (as json) | {weights: same as weights, styles: same as styles, variants: {"fontName" :{title: string, unicode?: string, format?: woff, isLocal?: boolean, url?: https://${string}, http://${string}}}} | {variants: {"font1" :{title: "roboto"}}} | | SETTINGS | | axisDivisions Grid system divisions | number | 12 | | opacities Available opacity values min: 0 - max: 100 (as array) | number[] | [10, 20] | | blurValues Blur effect values (as array) | number[] | [2, 4, 8, 16, 32] | | insetValues Inset values (as array) | number[] | [0, 5] | | bordersValue Default border width (as array) | number[] | [1, 2] | | radiuses Border radius values (as array) | number[] | [5,10,15] | | breakpoints Responsive breakpoints (as json) | Record<sm | md | lg | xl | xxl, ${number}px | ${number}rem | ${number}em> | {"sm": "640px", "md": "768px"} | | wrappers Container widths (as json) | Record<sm | md | lg | xl | xxl, { width: ${number}px | ${number}rem | ${number}em; padding?: ${number}px ${number}rem ${number}em}> | {"sm": {"width": "540px", "padding":"15px"}} | | guttersValues Spacing values (as json) | Record<auto | number, ${number}px | ${number}rem | ${number}em> | {"auto": "1rem", 1: "0.25rem"} | | GLASS | | blur Backdrop filter blur intensity | 0 | ${number}px | 8px | | borderThickness Glass border width | ${number}px | ${number}rem | ${number}em | 1px | | lightAngle Angle for border lighting | ${number}deg | 45deg | | glassColor Base glass background color (as json) | { light?: "#${string}"; dark?: "#${string}" } | {light: #ffffff, dark: #000000} | | border1Color Primary border color (as json) | { light?: "#${string}"; dark?: "#${string}" } | {light: #e6e6e6, dark: #303030} | | border2Color Secondary border color (as json) | { light?: "#${string}"; dark?: "#${string}" } | {light: #e6e6e6, dark: #303030} | | ROLES | | useFontFamilies Include font family utilities | boolean | true | | useFontFamiliesMediaQueries Include responsive font family utilities | boolean | false | | useFontSizes Include font size utilities | boolean | true | | useFontSizesMediaQueries Include responsive font size utilities | boolean | true | | useFontShapes Include font style utilities | boolean | true | | useFontShapesMediaQueries Include responsive font style utilities | boolean | false | | useTextAligns Include text alignment utilities | boolean | true | | useTextAlignsMediaQueries Include responsive text alignment utilities | boolean | true | | useTextTruncate Include text truncation utilities | boolean | true | | useTextTruncateMediaQueries Include responsive text truncation utilities | boolean | true | | useColors Include color utilities | boolean | true | | useColorsOpacities Include color opacity utilities | boolean | true | | useColorsLightMode Include light mode colors | boolean | true | | useColorsDarkMode Include dark mode colors | boolean | true | | useCurrentColors Include currentColor utilities | boolean | true | | useRootColors Include CSS custom properties | boolean | true | | useGrid Include grid system | boolean | true | | useFlex Include flexbox utilities | boolean | true | | useGridMediaQueries Include responsive grid utilities | boolean | true | | useWrappers Include container utilities | boolean | true | | useShadows Include shadow utilities | boolean | true | | useShadowsMediaQueries Include responsive shadow utilities | boolean | false | | useDisplays Include display utilities | boolean | true | | useDisplaysMediaQueries Include responsive display utilities | boolean | false | | useOverflows Include overflow utilities | boolean | true | | useOverflowsMediaQueries Include responsive overflow utilities | boolean | false | | useOpacities Include opacity utilities | boolean | true | | useOpacitiesMediaQueries Include responsive opacity utilities | boolean | false | | useBlur Include blur utilities | boolean | true | | useBlurMediaQueries Include responsive blur utilities | boolean | false | | useObjectFits Include object-fit utilities | boolean | true | | useObjectFitsMediaQueries Include responsive object-fit utilities | boolean | false | | usePositions Include positioning utilities | boolean | true | | usePositionsMediaQueries Include responsive positioning utilities | boolean | false | | useInsets Include inset utilities | boolean | true | | useInsetsMediaQueries Include responsive inset utilities | boolean | false | | useSizes Include sizing utilities | boolean | true | | useSizesMediaQueries Include responsive sizing utilities | boolean | true | | useGutters Include spacing utilities | boolean | true | | useGuttersMediaQueries Include responsive spacing utilities | boolean | true | | useBorders Include border utilities | boolean | true | | useBordersMediaQueries Include responsive border utilities | boolean | false | | useTextBorders Include text border utilities | boolean | true | | useTextBordersMediaQueries Include responsive text border utilities | boolean | false | | useRadius Include border radius utilities | boolean | true | | useRadiusMediaQueries Include responsive border radius utilities | boolean | false | | useGlass Include glassmorphism utilities | boolean | false | | useLoader Include loader utilities | boolean | false | | useDialog Include dialog utilities | boolean | false | | useButton Include button utilities | boolean | false |

TypeScript Configuration Example

// beathers.configs.ts
import { Theme } from 'beathers'

export default {
  colors: {
    primary: { light: '#007bff', dark: '#0056b3' },
    secondary: { light: '#6c757d', dark: '#495057' },
    success: { light: '#28a745', dark: '#20c997' },
  },
  typography: {
    defaultFontFamilies: ['Inter', 'system-ui', 'sans-serif'],
    fontSizes: {
      xs: '12px',
      sm: '14px',
      base: '16px',
      lg: '18px',
      xl: '20px',
    },
  },
  settings: {
    axisDivisions: 12,
    breakpoints: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
      xxl: '1536px',
    },
  },
  roles: {
    useBlur: false,
  },
} satisfies Theme

Documentation

Comprehensive guides to help you master Beathers and build amazing designs with our utility-first CSS framework.

• Colors & Theming → Colors Guide
• Typography & Text → Typography Guide
• Layout & Structure → Grid System Guide
• Visual Effects → Shaping Guide

Contact & Support