Package detail

The Perfect Fusion of Strength and Featherlight Agility

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

Common Configuration Properties

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