|| 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

``bash
npm install piloti
npx piloti
`

Quick Start

$3

Create piloti.config.json in your project root:

`json
{
"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"]
}
]
}
`

$3

`bash
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

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

Or in JS:
`js
import './piloti-output/index.css';
`

CLI Options

`bash
npx piloti [options]

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

$3

`bash


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

$3

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

$3

`json
{
"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" }
}
}
`

$3

`json
{
"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:

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

License

MIT