Why Salty CSS Chose Semantic Components Over Atomic CSS and Primitives Over Pre-baked UI Kits

Every styling library is a collection of tradeoffs. In recent years, the frontend ecosystem has optimized heavily for the absolute smallest possible CSS file size, often at the direct expense of the developer experience (DX) and code readability.

Salty CSS makes a different set of tradeoffs. We prioritize a flawless, TypeScript-first developer experience, semantic component structures, and out-of-the-box design system primitives. We believe that developer time is more expensive than a few kilobytes of heavily cached, gzipped CSS.

Here is the philosophy that drives Salty CSS, why we reject the Atomic CSS paradigm for our specific use cases, and why we focus on primitives over pre-baked UI kits.

Why Not Atomic CSS?

Atomic (or utility-first) CSS has dominated the conversation recently. Tools like Tailwind CSS generate a massive set of single-purpose classes, while build-time extractors like Panda CSS parse your AST to generate atomic classes on the fly.

Let's be intellectually honest: purely atomic CSS will mathematically result in a smaller global stylesheet. If you are building a highly lean, repetitive SaaS dashboard, atomic extraction is a fantastic architectural choice.

But Salty CSS wasn't built just for lean SaaS dashboards. It was built for design-led, highly dynamic websites. When you are building sites with complex, unique visual effects, dynamic content blocks (like Headless CMS layouts), and rich variants, the atomic model starts to break down:

1. The HTML Soup: Utility-first approaches inevitably lead to bloated, unreadable markup. Finding the actual DOM structure underneath forty utility classes is a cognitive tax.

2. The AST Overhead: Build-time atomic extractors (like Panda) rely on AST parsing. In a highly dynamic, block-based website, maintaining proper scoping and complex variant logic often forces these tools to generate incredibly heavy, complex class combinations behind the scenes just to function seamlessly. Ironically, in these specific scenarios, the performance of scoped atomic styles actually suffers.

Semantic Scoping & Mitigation

Salty CSS chooses semantic, component-level scoping. When you write styled("button", { ... }), you get a single, predictable hash class that represents that exact visual state.

We mitigate the file size tradeoff through smart compiler architecture:

• Hash Deduplication: If two completely different components generate the exact same style object, they produce the same hash and are deduplicated in the final CSS automatically.

• Component-Level Import Strategy: By configuring importStrategy: 'component', you can split your CSS so the browser only loads the exact stylesheets needed for the rendered route, rather than a monolithic global file.

Roadmap: Auto-Extraction We are currently developing a compiler optimization for production builds that bridges the gap. The compiler will analyze the final stylesheet, find highly repeated property combinations (e.g., display: flex; align-items: center; justify-content: center;), and automatically extract them into shared, semi-atomic rules under the hood. You keep the perfect component DX, and the compiler transparently reduces the final CSS weight.

Primitives over Pre-baked UI Kits

Salty CSS is not a UI kit. It does not provide a pre-styled <Button> or a <Modal>.

Pre-baked UI kits are great for prototyping, but they almost always become a liability when you need to match a bespoke Figma design perfectly. Overriding a highly opinionated UI library often requires more CSS than just building the component from scratch.

Salty CSS is designed to be the foundational layer for building your own UI kit.

"A Pinch of Salt": Batteries Included

When you build a bespoke design system, you quickly realize you need more than just a class name generator. You need tools to handle fluid scaling, color manipulation, and typography. Historically, this meant bloating your package.json with external dependencies like polished or writing complex calc() math by hand.

Salty CSS brings these essential primitives natively, strictly constrained to the build-time environment:

• Fluid Viewport Clamps: The defineViewportClamp utility replaces rigid, stair-stepped media queries with smooth, fluid scaling. You define a reference screen size, and the compiler mathematically translates it into native CSS clamp() functions.

• Build-Time Color Manipulation: The color() function allows you to chain transformations like .lighten(), .darken(), and .alpha() directly in your style objects. Because this executes during compilation, you get a pure CSS string in the browser without shipping a heavy color manipulation library in your client bundle.

By providing these tools natively, Salty CSS ensures that your design system remains cohesive, strictly typed, and completely zero-runtime. We provide the salt; you cook the meal.