0
# Polished
1
2
Polished is a lightweight toolset for writing styles in JavaScript that provides Sass-style helper functions and mixins for CSS-in-JS solutions. It offers comprehensive color manipulation, CSS utility functions, layout mixins, animation easings, and shorthand generators with full TypeScript support and functional programming patterns.
3
4
## Package Information
5
6
- **Package Name**: polished
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript/Flow definitions)
9
- **Installation**: `npm install polished`
10
11
## Core Imports
12
13
```javascript
14
import { lighten, darken, rem, clearFix, rgba } from "polished";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { lighten, darken, rem, clearFix, rgba } = require("polished");
21
```
22
23
## Basic Usage
24
25
```javascript
26
import { lighten, darken, rem, clearFix, rgba, fluidRange } from "polished";
27
28
// Color manipulation
29
const primaryColor = "#3498db";
30
const lightVariant = lighten(0.2, primaryColor); // "#5DADE2"
31
const darkVariant = darken(0.15, primaryColor); // "#2E86C1"
32
33
// Unit conversion
34
const fontSize = rem("16px"); // "1rem"
35
36
// CSS mixins
37
const buttonStyles = {
38
...clearFix(), // Clearfix mixin
39
backgroundColor: rgba(52, 152, 219, 0.8),
40
...fluidRange(
41
{ prop: "fontSize", fromSize: "14px", toSize: "18px" },
42
"320px", "1200px"
43
)
44
};
45
```
46
47
## Architecture
48
49
Polished is organized around six main functional areas:
50
51
- **Color System**: 29 functions for color manipulation, analysis, and conversion with full color theory support
52
- **CSS Helpers**: 9 utility functions for unit conversion, CSS variables, and common calculations
53
- **Layout Mixins**: 16 styling patterns for layout, typography, and visual effects
54
- **CSS Shorthands**: 15 generators for CSS shorthand properties with intelligent value distribution
55
- **Animation Easings**: 3 predefined easing functions for smooth animations
56
- **Mathematical Operations**: CSS unit-aware calculations with formula parsing
57
58
All functions follow functional programming principles with currying support, enabling composition and reusability across different CSS-in-JS libraries.
59
60
## Capabilities
61
62
### Color Manipulation
63
64
Comprehensive color manipulation functions supporting HSL, RGB, and named colors with automatic format detection and conversion.
65
66
```javascript { .api }
67
function lighten(amount: number, color: string): string;
68
function darken(amount: number, color: string): string;
69
function saturate(amount: number, color: string): string;
70
function desaturate(amount: number, color: string): string;
71
function adjustHue(degree: number, color: string): string;
72
function mix(weight: number, color: string, otherColor: string): string;
73
function hslToColorString(hslColor: HslColor): string;
74
function rgbToColorString(rgbColor: RgbColor): string;
75
function toColorString(color: string | RgbColor | HslColor): string;
76
```
77
78
[Color Functions](./color.md)
79
80
### CSS Helper Utilities
81
82
Essential utilities for unit conversion, CSS variables, modular scaling, and directional properties.
83
84
```javascript { .api }
85
function rem(pxval: string | number, base?: string | number): string;
86
function em(pxval: string | number, base?: string | number): string;
87
function modularScale(steps: number, base?: string | number, ratio?: number): string;
88
function cssVar(cssVariable: string, defaultValue?: string | number): string | number;
89
```
90
91
[Helper Functions](./helpers.md)
92
93
### Layout and Styling Mixins
94
95
Pre-built styling patterns for common layout needs, typography effects, and responsive design.
96
97
```javascript { .api }
98
function clearFix(): Styles;
99
function ellipsis(width?: string): Styles;
100
function cover(offset?: string): Styles;
101
function fluidRange(cssProp: FluidRangeConfiguration | FluidRangeConfiguration[], minScreen?: string, maxScreen?: string): Styles;
102
function timingFunctions(): TimingFunctions;
103
```
104
105
[Layout Mixins](./mixins.md)
106
107
### CSS Shorthand Generators
108
109
Intelligent generators for CSS shorthand properties with flexible value handling and automatic expansion.
110
111
```javascript { .api }
112
function margin(...values: Array<?string | ?number>): Styles;
113
function padding(...values: Array<?string | ?number>): Styles;
114
function border(side?: string, width?: string, style?: string, color?: string): Styles;
115
function borderRadius(side?: string, radius?: string): Styles;
116
function backgroundImages(...images: Array<string>): Styles;
117
function backgrounds(...backgrounds: Array<BackgroundConfiguration>): Styles;
118
```
119
120
[Shorthand Properties](./shorthands.md)
121
122
### Animation Easings
123
124
Predefined cubic-bezier timing functions for smooth, professional animations.
125
126
```javascript { .api }
127
function easeIn(mode: string): string;
128
function easeOut(mode: string): string;
129
function easeInOut(mode: string): string;
130
```
131
132
[Animation Functions](./easings.md)
133
134
### Mathematical Operations
135
136
CSS unit-aware mathematical calculations with support for complex formulas and mixed units.
137
138
```javascript { .api }
139
function math(formula: string, additionalSymbols?: Object): string;
140
```
141
142
[Math Functions](./math.md)
143
144
## Types
145
146
```javascript { .api }
147
interface Styles {
148
[key: string]: string | number | Styles;
149
}
150
151
interface FluidRangeConfiguration {
152
prop: string;
153
fromSize: string;
154
toSize: string;
155
}
156
157
interface TimingFunction {
158
[key: string]: string;
159
}
160
161
interface BackgroundConfiguration {
162
image?: string;
163
position?: string;
164
size?: string;
165
repeat?: string;
166
attachment?: string;
167
origin?: string;
168
clip?: string;
169
color?: string;
170
}
171
172
interface HslColor {
173
hue: number;
174
saturation: number;
175
lightness: number;
176
alpha?: number;
177
}
178
179
interface RgbColor {
180
red: number;
181
green: number;
182
blue: number;
183
alpha?: number;
184
}
185
186
interface TimingFunctions {
187
[key: string]: string;
188
}
189
190
interface InterpolationValue {
191
[key: string]: string | number;
192
}
193
```