polished

Polished brings the Sass-style helper functions developers relied on for pre-processed stylesheets — color manipulation, layout mixins, unit math — into plain JavaScript, so they work with any CSS-in-JS approach: styled-components, emotion, JSS, Aphrodite, Radium, or even inline style objects. Every function is curried and side-effect free, so functions like lighten(0.1) or darken(0.1) can be partially applied and composed with any functional-composition helper (Ramda’s compose, for example) into reusable style helpers.

The library ships as tree-shakeable named exports across color manipulation (darken, lighten, mix, readableColor, getContrast), layout mixins (clearFix, cover, triangle, hideVisually, linearGradient), unit helpers (rem, em, stripUnit, modularScale), and a small expression evaluator (math) for doing arithmetic across CSS units. It has first-class Flow type definitions plus generated TypeScript definitions, making it usable from either type system with no extra configuration.

What You Get

• A full curried color-manipulation API (darken, lighten, saturate, desaturate, mix, adjustHue, complement, invert, readableColor, getContrast, getLuminance) that accepts and returns hex, rgb(a), and hsl(a) strings
• Layout mixins for common CSS patterns that are tedious to hand-write — clearFix, cover, triangle, hideText/hideVisually, linearGradient/radialGradient, fluidRange, wordWrap
• Unit helpers (em, rem, remToPx, stripUnit, modularScale, getValueAndUnit) so typographic and spacing scales don’t need hand calculation
• A math() expression evaluator that safely computes formulas across mixed CSS units (math('(12px + 2px) * 3')) with full operator precedence, without needing native CSS calc()
• Framework-agnostic output — every helper returns a plain string or plain style object, so it drops into styled-components, emotion, JSS, Aphrodite, Radium, or inline styles equally

Common Use Cases

• Deriving a full color palette (hover/active/disabled shades) from a single brand color using lighten/darken/desaturate instead of hand-picking hex values
• Building reusable style helpers by composing curried polished functions with a functional compose() utility, mirroring Sass mixin composition
• Ensuring WCAG-compliant text contrast automatically with readableColor/meetsContrastGuidelines rather than manually checking contrast ratios
• Converting design-token pixel values to rem/em consistently across a codebase via rem()/em()/modularScale()
• Writing print-safe or cross-browser CSS patterns (clearfix, visually-hidden text, CSS triangles, retina image swaps) without copy-pasting boilerplate CSS snippets

Under The Hood

Architecture polished is organized as one pure function per file, grouped by domain into src/color, src/mixins, src/helpers, src/math, src/easings, and src/shorthands, with shared low-level logic (hex/HSL/RGB conversion, currying, a typed PolishedError) isolated in src/internalHelpers; a single src/index.js imports and re-exports every function as a named export, giving consumers tree-shakeable, framework-agnostic access. Every public function is stateless and returns a plain string or plain style object rather than mutating anything or depending on a runtime — most color and mixin functions are wrapped with an internal curry helper (internalHelpers/_curry.js, itself flow-typed against the same pattern used in flow-static-land) so they can be partially applied and composed like Sass mixins, meaning the library’s core abstraction is functional composition rather than object-oriented API design; changing that curry helper or the shared HSL/RGB conversion utilities would ripple through nearly every exported function.

Tech Stack The source is authored in ES2015+ JavaScript with Flow type annotations rather than TypeScript, built via Babel (@babel/cli, @babel/preset-env, @babel/preset-flow) into a CommonJS lib/ output and bundled separately with Rollup (rollup-plugin-terser, rollup-plugin-sourcemaps) into UMD/ESM/CJS dist/ bundles; TypeScript consumers get generated .d.ts definitions produced from the Flow types via tsgen, so both type systems are supported without hand-maintaining two definition sets. Tests run on Jest with jsdom, docs are generated straight from JSDoc-style comments into a static site via the documentation tool, and CI runs through GitHub Actions with Husky + lint-staged enforcing ESLint (airbnb-base) and Prettier on every commit. The only runtime dependency is @babel/runtime, keeping the published bundle intentionally minimal.

Code Quality The repository pairs nearly every source file with a matching test file (85 test files across src/**/test, effectively one suite per exported function), with Jest coverage collection enabled by default and CI gating merges on the Node test workflow. Error handling is centralized through a custom PolishedError class with numbered, documented error codes (internalHelpers/_errors.js, cross-referenced in errors.md) instead of ad hoc thrown strings, giving consistent, greppable failure messages across the library. Every exported function carries a JSDoc block with a plain-language description plus three parallel @example snippets (plain style object, styled-components usage, and rendered CSS output), which doubles as both inline documentation and the source for the generated docs site — a level of documentation discipline well above typical utility libraries.

What Makes It Unique polished’s math() function is the most distinctive piece: a hand-rolled expression evaluator that parses and computes arithmetic formulas across mixed CSS units with full operator precedence (parentheses, exponents, square roots, min/max), something native CSS calc() still can’t do when units differ, and something few comparable CSS-in-JS helper libraries attempt. Beyond that, the library’s core value — bringing curried, composable Sass-style helpers into a framework-agnostic, plain-JS form usable by any CSS-in-JS library rather than being tied to one — was a genuinely useful bridge when it launched alongside the early styled-components ecosystem; today, with native CSS gaining calc(), clamp(), and color-mix(), much of that functionality has moved toward standard patterns rather than remaining unique to this library, so its innovation lies more in execution quality and API ergonomics than in a novel underlying idea.