saucey

saucey compresses the sprawl of CSS into ~40 props across three modules — frame, layout, and text — authored as $frame / $layout / $text keys inside a css() call. A compile-time hook expands them into real Panda CSS, so tokens, conditions, atomic classes, and static extraction all come from Panda for free. You author intent; the compiler does the rest. Wrong is a type error.

Why it exists

CSS hands you 500+ properties and infinite ways to combine them — and "just write clean CSS" doesn't scale. The surface area is enormous, conventions get broken the moment they're inconvenient (by humans and LLMs), and a model will happily reach for whatever satisfies the immediate prompt regardless of the mess it leaves behind.

saucey removes the option to misbehave instead of asking nicely:

• ~40 props, not 500. The essential vocabulary designers already think in — borrowed from the inspector panels of Figma, Framer, and Sketch — behind one function. Small enough to hold in your head, and to tell a model "only ever use this."
• Wrong is a type error. Every value is a token or a constrained option; an off-system color or a typo doesn't compile. Docs are a suggestion; the compiler is a contract.
• Reads like the Figma inspector. Styling reads top-to-bottom as intent — you review what it means, not how it works. Designers can contribute in the words they already use.
• Free at runtime. It's a compile-time transform on top of Panda — tokens, conditions, atomic CSS, and static extraction are Panda's job; saucey adds zero runtime cost.
• LLM-friendly. A tiny, constrained, typesafe surface a model can follow without inventing its own — the groundwork for agentic workflows that stay deterministic.
• Human-friendly. Code reviews are easier to reason about, and tweaking the final 10% is read-it, find-it, change-it — not prompt-roulette.

Core concepts

Three modules, ~40 props. Every visual decision is one of three keys inside css():

css({
  $frame:  { /* the box:      w, h, corners, fill, border, pad, overflow, z, opacity … */ },
  $layout: { /* its children: flow, gap, align, wrap, cols, rows … */ },
  $text:   { /* the type:     font, size, weight, color, case, decoration, truncate … */ },
});

Progressive disclosure — a prop takes its simplest form first and escalates only when you ask for more power:

$frame: { fill: "accent.9" }                                        // a token
$frame: { fill: ["accent.6", "accent.9"] }                          // → a gradient
$frame: { fill: { type: "image", src: "--hero", position: "top" } } // → an image, positioned
$frame: {                                                           // → layered, first = bottom
  fill: [
    { type: "image", src: "--hero" },        // base layer
    { type: "solid", color: "accent.9/20" }, // tint on top
  ],
}

Abstraction — saucey folds multi-prop CSS concepts into one intent, and blocks the footguns. One word in, the right CSS out:

$layout: { align: "center" }   // → the justify-content + align-items pair
$layout: { gap: "auto" }       // → space-between   ("gap: '-tight'" → overlapping children)

$raw — the escape hatch. For the rare property no module covers (cursor, content, transition), drop to raw Panda under $raw — raw props live in that one labeled, greppable key, never scattered at the top level. So raw-CSS usage stays easy to spot in review: you stay on top of whatever debt you choose to take on, instead of it hiding in the styling.

The compile-time trick. saucey is a single Panda parser:before hook. Before Panda ever sees your source, sauceyToPanda finds every $frame / $layout / $text inside a css() call and rewrites it into valid Panda CSS — then Panda does the heavy lifting. Tokens work, conditions work, and the whole layer disappears at build time:

// panda.config.ts
import { sauceyToPanda } from "@saucey/panda";
 
export default defineConfig({
  hooks: {
    "parser:before": ({ content }) => sauceyToPanda(content, { codegen: "…/panda-codegen" }),
  },
});

The other half is the runtime seam: connectSaucey binds css / cssv to a project's generated Panda types, so every value is strict against the real token and condition set:

// the project's saucey seam
import { connectSaucey } from "@saucey";
import { css, cva } from "./panda-codegen/css";
 
export const { css, cssv, normalizeCSSProp } = connectSaucey<PandaGenTypes>({ css, cva });

A taste of the API

Author styles — modules are keys; conditions nest. css() returns a resolved object with a .toClasses() you drop on any element:

import { css } from "@system/styles";
 
const styles = css({
  $frame: { w: "full", fill: "base.2", corners: "lg", pad: "wide" },
  $layout: { flow: "stackX", align: "center", gap: "normal" },
  $text: { size: "body", color: "base.11" },
  _hover: { $frame: { fill: "base.3" } },   // conditions + tokens, free from Panda
});
 
<div className={styles.toClasses()} />;

Compose fragments — css() is variadic: each object resolves to CSS properties independently, then Panda merges those properties. Non-competing props stack; only a genuinely competing one is overridden (last wins):

const cardBase = css({ $frame: { w: "full", corners: "lg" } });
 
css(cardBase, { $frame: { fill: "accent.3" } }).toClasses(); // w + corners + fill — nothing replaced
css(cardBase, { $frame: { corners: "full" } }).toClasses();  // corners → full; w survives

Selective variants — cssv defines a recipe for a closed set of author-chosen options (never reactive state — that's a data-* attribute + a condition):

import { css, cssv } from "@system/styles";
 
const button = cssv({
  variants: {
    tone: {
      primary:   { $frame: { fill: "accent.9" }, $text: { color: "base.1" } },
      secondary: { $frame: { fill: "base.3" }, $text: { color: "base.12" } },
    },
  },
  defaultVariants: { tone: "primary" },
});
 
<button className={button({ tone }).toClasses()} />;

Tokenizers — palette & font

The tokens the modules resolve against don't come from a static file — they come from tokenizers: createPaletteCollection and createFontCollection (from @saucey/tokenizers). Define your palettes and fonts once and each gives you two things — the Panda tokens the modules reference at build time, and a runtime hook to read and switch them live.

Palette — define each palette by its light/dark anchors (OKLCH start / center / end); the tokenizer expands them into a full shade ramp plus the semantic roles (accent, base, …). Dark mode is derived by swapping start ↔ end:

import { createPaletteCollection, createUsePalette } from "@saucey/tokenizers";
 
export const paletteCollection = createPaletteCollection(
  { shades: 13, oklch: "normalized" },
  {
    orange: {
      light: { start: [0.97, 0.2, 0.1], center: [0.7, 0.85, 0.1], end: [0.13, 0.4, 0.1] },
      dark:  { start: [0.13, 0.4, 0.1], center: [0.7, 0.85, 0.1], end: [0.97, 0.2, 0.1] },
    },
    // … more palettes
  },
);
 
export const usePalette = createUsePalette(paletteCollection); // → the runtime hook

Font — define each face (source + variation settings) and the semantic roles (accent / base / code); the tokenizer wires the @font-face + size/weight tokens and the useFont hook. fluidScale builds a clamp() ramp between two breakpoints:

import { createFontCollection, createUseFont } from "@saucey/tokenizers";
 
export const fontCollection = createFontCollection(
  { inter: { src: ["url(…) format('woff2')"], fontWeight: "1 1000" } },
  { accent: { font: "inter", settable: true }, base: { font: "inter" }, code: { font: "jetbrains" } },
);
 
export const useFont = createUseFont(fontCollection); // → the runtime hook

Wire the collection into Panda's preset. The same collection hands Panda the tokens the modules resolve against — the semantic aliases (accent, base, …), the CSS-variable values behind them, and @font-face — so fill: "accent.9" and size: "body" become real, statically-extracted tokens:

// panda-preset
definePreset({
  theme: {
    semanticTokens: {
      colors: paletteCollection.semanticTokens(), // accent / base / danger → the ramp
      fonts:  fontCollection.semanticTokens(),
    },
  },
  globalCss: paletteCollection.globalCss(),        // the --colors-* values (light + dark)
  globalFontface: fontCollection.globalFontface(), // @font-face declarations
});

Read and switch at runtime. The boundary call creates a Provider and owns the state; anything below inherits it — resolve a shade, flip the mode, swap a palette, all live:

// app root — owns the theme, renders the provider
const { PaletteProvider } = usePalette({ accent: "orange", base: "stone", mode: "light" });
 
// anywhere below — read / mutate the nearest boundary (no provider returned)
const { palette, setPalette } = usePalette("inherit");
palette.toHex("accent.9"); // resolve a token → hex, for the rare non-CSS need (canvas, motion)
setPalette.mode("dark");   // flip light ↔ dark, live
setPalette.accent("red");  // swap the accent palette, live