|| PIlotI ||

A config-driven CSS framework following CUBE CSS methodology.

Piloti (pilotis) — architectural columns that lift a building, providing the foundation. Just like pilotis support architecture, Piloti supports your design system.

Features

• Token-based — Colors, spacing, typography from config
• Auto-generated utilities — Build from your tokens
• Responsive — Breakpoint-prefixed classes (sm:, md:, lg:, xl:)
• CUBE CSS compositions — Stack, cluster, flow
• Customizable — Your config, your design system

Installation

npm install piloti
npx piloti

Quick Start

1. Create your config

Create piloti.config.json in your project root:

{
  "settings": {
    "basePixel": 16,
    "breakpoints": {
      "sm": "640px",
      "md": "768px",
      "lg": "1024px"
    }
  },
  "tokens": {
    "color": {
      "primary": "#4f46e5",
      "secondary": "#e5e7eb",
      "accent": "#f59e0b"
    },
    "spacing": {
      "0": "0px",
      "1": "4px",
      "2": "8px",
      "4": "16px",
      "8": "32px"
    }
  },
  "utilities": [
    {
      "prefix": "p",
      "property": "padding",
      "fromToken": "spacing",
      "values": ["0", "1", "2", "4", "8"],
      "responsive": true
    },
    {
      "prefix": "bg",
      "property": "background-color",
      "fromToken": "color",
      "values": ["primary", "secondary", "accent"]
    }
  ]
}

2. Generate CSS

npx piloti

This creates piloti-output/ with:

• variables.css — CSS custom properties
• utilities.css — Utility classes
• responsive.css — Responsive utilities
• index.css — Entry point

3. Import in your project

@import url('./piloti-output/index.css');

Or in JS:

import './piloti-output/index.css';

CLI Options

npx piloti [options]

Options:
  -c, --config <path>   Path to config file (default: ./piloti.config.json)
  -o, --output <path>   Output directory (default: ./piloti-output)
  -h, --help            Show help

Examples

# Use default config location
npx piloti

# Custom config
npx piloti --config ./tokens/design-system.json

# Custom output
npx piloti --output ./src/styles/generated

Config Reference

Settings

{
  "settings": {
    "basePixel": 16,
    "breakpoints": {
      "sm": "640px",
      "md": "768px",
      "lg": "1024px",
      "xl": "1280px"
    }
  }
}

Tokens

{
  "tokens": {
    "color": { "primary": "#000", "accent": "#f00" },
    "spacing": { "1": "4px", "2": "8px" },
    "fontSize": { "sm": "14px", "base": "16px" },
    "radius": { "sm": "2px", "full": "9999px" },
    "shadow": { "md": "0 4px 6px rgba(0,0,0,0.1)" },
    "lineHeight": { "tight": "1.25", "normal": "1.5" },
    "zIndex": { "10": "10", "50": "50" }
  }
}

Utilities

{
  "utilities": [
    {
      "prefix": "p",
      "property": "padding",
      "fromToken": "spacing",
      "values": ["1", "2", "4"],
      "responsive": true
    },
    {
      "prefix": "d",
      "property": "display",
      "values": ["flex", "grid", "block", "none"],
      "responsive": true
    },
    {
      "prefix": "justify",
      "property": "justify-content",
      "values": ["start", "center", "between"],
      "valueMap": {
        "start": "flex-start",
        "center": "center",
        "between": "space-between"
      }
    }
  ]
}

Generated Classes

With the default config, you get:

| Category | Examples | |----------|----------| | Display | .d-flex, .d-grid, .d-none | | Flexbox | .flex-row, .flex-col, .justify-center, .items-center | | Spacing | .p-4, .m-2, .gap-4, .mx-auto | | Colors | .text-primary, .bg-accent | | Typography | .font-xl, .leading-tight | | Shadows | .shadow-md, .shadow-lg | | Responsive | .sm:d-flex, .md:w-1/2, .lg:gap-8 |

Using with the Base Framework

For compositions (stack, cluster, flow) and reset styles, also import:

@import url('node_modules/piloti/src/main.css');
@import url('./piloti-output/index.css'); /* Your custom tokens */

License

MIT