DEV Community: OmniDev

Building Fluentic Style: Styling DOM You Do Not Own With `createSheet`

OmniDev — Mon, 31 Aug 2026 03:01:42 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

Most Fluentic examples start with a component that owns its DOM.

<button css={styles.root}>
  <span css={styles.icon}>{icon}</span>
  <span css={styles.label}>{children}</span>
</button>

That is the clean case.

The component renders the elements.

The component owns the styles.

The css prop attaches directly to the element that needs the style.

But not every UI is made of DOM you own.

Sometimes the interesting markup belongs to a third-party library.

A select library owns the control.

A date picker owns the calendar cells.

A rich text editor owns the content DOM.

A table library owns row and cell wrappers.

A menu might render its panel in a portal.

In those cases, the problem changes.

The question is no longer:

How do I style the element I am rendering?

The question becomes:

How do I style meaningful DOM inside a component I do not control?

That is the place where createSheet(...) became useful.

The Normal Fluentic Flow

When you own the DOM, Fluentic can stay very direct.

import { style } from '@fluentic/style';

const buttonStyles = {
  root: style({
    display: 'inline-flex',
    alignItems: 'center',
    gap: 8,
    borderRadius: 8,
    padding: '8px 12px',
  }),

  label: style({
    fontWeight: 650,
  }),
};

export function Button(props: { children: React.ReactNode }) {
  return (
    <button css={buttonStyles.root}>
      <span css={buttonStyles.label}>{props.children}</span>
    </button>
  );
}

The style value goes exactly where it belongs.

For a reusable component, the parts that outside code may style can become slots:

const buttonStyles = {
  root: style.slot({
    display: 'inline-flex',
    alignItems: 'center',
    gap: 8,
  }),

  label: style.slot({
    fontWeight: 650,
  }),
};

Then a theme can provide changes to those slots:

const dangerButton = style.scope([
  buttonStyles.root({
    backgroundColor: '#dc2626',
    color: 'white',
  }),

  buttonStyles.label({
    fontWeight: 800,
  }),
]);

That works because the component owns the styling targets.

The component decides which parts are public.

The caller styles those parts through Fluentic values, not through private DOM structure.

But third-party components are different.

Third-Party DOM Has A Different Boundary

Imagine wrapping React Select.

Your wrapper might look like this:

export function Select() {
  return (
    <div>
      <ReactSelect classNamePrefix="react-select" unstyled />
    </div>
  );
}

React Select renders internal DOM with classes like:

.react-select__control
.react-select__single-value
.react-select__menu
.react-select__option

Those are real styling targets, but they are not elements your wrapper renders directly.

You cannot write this:

<div css={styles.control} />

because you do not render the control element.

You may only own the boundary around it.

That is the gap createSheet(...) is meant to fill.

Naming Third-Party Parts

createSheet(...) is Fluentic’s way to attach a group of selector-based styles to one boundary element.

Instead of styling an element directly, the sheet says:

When this generated class is attached here, apply these Fluentic styles to these known selectors inside it.

So the first step is to name the third-party DOM parts you want to style:

import { createTokens, style } from '@fluentic/style';
import { createSheet } from '@fluentic/style/css';

const selectTokens = createTokens({
  accent: '#2563eb',
  panel: '#eff6ff',
  text: '#1e3a8a',
});

const selectPart = {
  control: style.selector('.react-select__control'),
  value: style.selector('.react-select__single-value'),
  menu: style.selector('.react-select__menu'),
  option: style.selector('.react-select__option'),
};

The selector strings still come from the third-party library.

That part is unavoidable.

But the important thing is where they live.

Instead of scattering .react-select__control through CSS files, nested selectors, wrapper components, and one-off overrides, the wrapper gathers the library’s public selector contract in one place.

After that, the styles can look like normal Fluentic style data.

const selectSheet = createSheet([
  selectPart.control({
    minHeight: 42,
    border: '1px solid',
    borderColor: selectTokens.accent,
    borderRadius: 10,
    backgroundColor: selectTokens.panel,
    boxShadow: 'none',
  }).hover({
    borderColor: '#1d4ed8',
  }),

  selectPart.value({
    color: selectTokens.text,
    fontWeight: 650,
  }),
]);

There is also a shorter form when the selector part has a default style immediately.

style.selector(...) can receive the style object directly, similar to style(...) or style.slot(...):

const selectSheet = createSheet([
  style.selector('.react-select__control', {
    minHeight: 42,
    border: '1px solid',
    borderColor: selectTokens.accent,
    borderRadius: 10,
    backgroundColor: selectTokens.panel,
    boxShadow: 'none',
  }).hover({
    borderColor: '#1d4ed8',
  }),

  style.selector('.react-select__single-value', {
    color: selectTokens.text,
    fontWeight: 650,
  }),
]);

I usually like naming selector parts when the wrapper is going to grow.

It gives the third-party selector contract a home.

But for a small wrapper, or for a quick one-off sheet, the direct form is convenient.

Attaching The Sheet To A Wrapper

A sheet is still an attachable Fluentic style value.

You can pass it directly to the css prop. The element that receives the sheet becomes the boundary for the selector rules.

export function Select() {
  return (
    <div css={selectSheet}>
      <ReactSelect classNamePrefix="react-select" unstyled />
    </div>
  );
}

In this version, the wrapper <div> receives Fluentic’s generated sheet class.

The selector rules are emitted under that class, so they only apply to matching third-party DOM inside this wrapper:

:where(.sheetClass) .react-select__control {
  min-height: 42px;
}

So this is not a loose global rule.

The sheet is attached to one boundary element, and its selectors are scoped from there.

Sometimes you do not want an extra wrapper element.

That can work too, as long as the third-party component lets you pass a class to the element that should become the sheet boundary.

React Select exposes a className prop for its root element, so the sheet can be resolved and passed directly:

import { getClassName } from '@fluentic/style';

export function Select() {
  const { className } = getClassName(selectSheet);

  return (
    <ReactSelect
      className={className}
      classNamePrefix="react-select"
      unstyled
    />
  );
}

Now the root element rendered by React Select becomes the boundary.

The same selector rules still apply. The only thing that changed is where Fluentic’s generated class lands.

With the wrapper version, it lands on your <div>.

With the direct version, it lands on the root element rendered by React Select.

For third-party APIs that accept normal className and style props, pass the resolved result through together:

import { getClassName } from '@fluentic/style';

export function FieldBridge() {
  const fieldProps = getClassName(fieldSheet);

  return (
    <ThirdPartyField
      {...fieldProps}
    />
  );
}

That is useful because getClassName(...) may return both a className and a style object. The style object carries token variables or dynamic inline values when the resolved style needs them.

If you need to merge Fluentic’s resolved props with existing props, make that explicit:

import {
  getClassName,
  mergeClassName,
  mergeStyle,
  type StyleProp,
} from '@fluentic/style';

export function FieldBridge(props: {
  css?: StyleProp;
  className?: string;
  style?: React.CSSProperties;
}) {
  const fieldProps = getClassName(fieldSheet);

  return (
    <ThirdPartyField
      className={mergeClassName([fieldProps.className, props.className])}
      style={mergeStyle([fieldProps.style, props.style])}
    />
  );
}

The direct path is best when the third-party component exposes the right root className or element props.

The wrapper path is best when you want a boundary element you fully own.

Why This Is Not Just Global CSS Again

Selector sheets still use selectors.

That is the point.

When the DOM belongs to another library, selectors may be the right contract.

But the selector does not become the whole styling approach.

The selector only says:

This is the third-party part I want to style.

The declarations are still Fluentic style data.

That means they can still use:

tokens
selector chains
priority rules
runtime resolution
CSS extraction
debug names
sourcemaps

The selector is the bridge.

It connects Fluentic styling to DOM that Fluentic did not render.

Why Not Just Use `className`?

Sometimes className is enough.

The direct getClassName(...) example above is exactly that case: the library gives you a boundary element, and you attach the generated sheet class there.

But selector sheets solve a different problem than a normal element class.

They are for cases where the library exposes fixed internal selectors, but not direct control over every internal element.

That is common with selects, editors, calendars, tables, menus, and other rich UI primitives.

The wrapper has a stable outside boundary.

The library has stable internal class names or data attributes.

createSheet(...) connects those two without turning every override into separate CSS.

Once the selectors are named, the rest of the styling path stays Fluentic:

tokens -> selector parts -> sheets -> combineStyle(...) -> css prop

That matters when the wrapper grows.

A small border override can become compact mode, danger tone, brand theme, disabled state, portal menu styles, and consumer overrides.

With selector sheets, those pieces remain composable style data.

Sheets Can Compose

A third-party wrapper usually starts small.

Then it gets a compact mode.

const compactSheet = createSheet([
  selectPart.control({
    minHeight: 34,
    borderRadius: 6,
  }),

  selectPart.value({
    fontSize: 13,
  }),
]);

Now the wrapper can compose the base sheet with the compact sheet:

import { combineStyle, type StyleProp, type StyleTheme } from '@fluentic/style';

export function Select(props: {
  compact?: boolean;
  css?: StyleProp;
  theme?: StyleTheme;
}) {
  const css = combineStyle(
    selectSheet,
    props.compact && compactSheet,
    props.theme,
  );

  return (
    <div css={[css, props.css]}>
      <ReactSelect classNamePrefix="react-select" unstyled />
    </div>
  );
}

Use combineStyle(...) to resolve the sheet with themes, variants, and token overrides.

Then append incoming props.css at the final attachment point with an array.

The same composition can work with the direct path when the third-party component accepts the resolved props:

export function FieldBridge(props: {
  compact?: boolean;
  css?: StyleProp;
  theme?: StyleTheme;
}) {
  const css = combineStyle(
    fieldSheet,
    props.compact && compactFieldSheet,
    props.theme,
  );

  const fieldProps = getClassName([css, props.css]);

  return (
    <ThirdPartyField
      {...fieldProps}
    />
  );
}

This is the same composition idea as normal Fluentic styles.

Base first.

Variant next.

Incoming theme after that.

Direct css last, at the final element boundary.

The difference is only the target shape.

Instead of styling elements directly, the sheet styles known selectors under the attached boundary.

Local Themes For Third-Party Components

Third-party wrappers often need local themes.

A select might need a blue tone, a rose tone, and a compact mode, but that does not always mean the entire app theme should know about React Select.

A selector sheet can contain token overrides too:

const blueSelect = createSheet([
  selectTokens.accent('#2563eb'),
  selectTokens.panel('#eff6ff'),
  selectTokens.text('#1e3a8a'),
]);

const roseSelect = createSheet([
  selectTokens.accent('#c0265a'),
  selectTokens.panel('#fce7ef'),
  selectTokens.text('#8f1238'),
]);

Then the wrapper can compose the selected tone with the structural sheet:

const css = combineStyle(
  selectSheet,
  props.tone === 'rose' ? roseSelect : blueSelect,
  props.compact && compactSheet,
);

And the incoming css prop still belongs at the final attachment point:

<div css={[css, props.css]} />

The control and value styles still read from selectTokens.

The token values can change locally, scoped to the wrapper instance.

That is the part I like here.

You do not have to introduce global CSS variables by hand.

You do not have to make the app theme aware of every third-party library.

You can keep the styling surface local to the wrapper.

Same Element Selectors

The basic selector form assumes the library class is somewhere below the attached sheet class:

style.selector('.react-select__control')

That produces a descendant selector:

:where(.sheetClass) .react-select__control { ... }

Sometimes the class you care about is on the attached element itself.

For that, the selector can use &:

const selectPart = {
  root: style.selector('&.react-select'),
};

That produces:

:where(.sheetClass).react-select { ... }

The difference is small but important:

.part   the part is below the attached class
&.part  the part is the attached element

This lets the sheet describe the DOM relationship instead of pretending all third-party markup has the same shape.

Portal Menus

Portals make the boundary more interesting.

A select control may render inside your wrapper, while the menu renders under document.body.

<div class="select-wrapper sheetClass">
  <div class="react-select__control">...</div>
</div>

<body>
  <div class="react-select__menu">...</div>
</body>

A wrapper sheet cannot reach across the document.

Once the menu moves outside the wrapper, this selector no longer matches:

:where(.sheetClass) .react-select__menu

because .react-select__menu is no longer below .sheetClass.

For portal cases, the sheet class needs to be attached to the portal target too.

Fluentic has createStyleTarget(...) for elements you do not render directly.

The React hook can stay small because createStyleTarget() owns the class and style bookkeeping:

import { createStyleTarget } from '@fluentic/style/css';
import { useEffect, useMemo } from 'react';

function useStyleTarget() {
  const target = useMemo(() => createStyleTarget(), []);

  useEffect(() => {
    return () => target.destroy();
  }, [target]);

  return target;
}

Then the wrapper can apply menu styles to the portal target:

import { combineStyle, type StyleProp, type StyleTheme } from '@fluentic/style';

export function Select(props: {
  compact?: boolean;
  css?: StyleProp;
  portalTarget: HTMLElement | null;
  theme?: StyleTheme;
}) {
  const target = useStyleTarget();

  const rootCss = combineStyle(
    [selectSheet, menuSheet],
    props.theme,
    props.compact && compactSheet,
  );

  const portalCss = combineStyle(
    menuSheet,
    props.theme,
  );

  target.apply(props.portalTarget, portalCss, {
    enabled: !!props.portalTarget,
  });

  return (
    <div css={[rootCss, props.css]}>
      <ReactSelect
        classNamePrefix="react-select"
        menuPortalTarget={props.portalTarget}
        unstyled
      />
    </div>
  );
}

Including menuSheet in rootCss keeps the non-portal case working.

Applying portalCss to the portal target covers the detached menu.

This is one of the cases where selector sheets feel less like a styling convenience and more like a DOM-boundary tool.

Optional Same-Or-Descendant Matching

Sometimes the same selector needs to work in both shapes.

The menu might be below the wrapper in one mode, but be the attached portal element in another.

For that, Fluentic supports &?.

const selectPart = {
  menu: style.selector('&?.react-select__menu'),
};

That means:

match the attached element if it has this class,
or match a descendant with this class

So these three forms have different meanings:

.part    descendant under the attached class
&.part   same element as the attached class
&?.part  either shape

That keeps portal-aware sheets from needing duplicate rules for the same component part.

Guardrails

Selector sheets are intentionally narrower than arbitrary global CSS.

Prefer one selector per style.selector(...) call:

const control = style.selector('.react-select__control');
const input = style.selector('.react-select__input-container');

If one logical part has multiple supported selectors, use an array:

const field = style.selector([
  '.react-select__control',
  '.react-select__input-container',
]);

Avoid comma-separated selector strings:

const field = style.selector('.one, .two');

Arrays keep the selector structure visible to Fluentic.

That matters for extraction, debugging, and keeping the wrapper’s selector contract readable.

There is another boundary too.

createSheet(...) expects selector items or token overrides.

If you are styling a normal element you own, use style(...).

If you are exposing component parts you own, use style.slot(...) and style.scope(...).

If the target is a selector under a boundary element, use createSheet(...).

What About Library CSS?

Some third-party libraries ship their own CSS.

Sometimes that CSS has high specificity.

Sometimes it loads after your app styles.

Fluentic can order the rules it owns, but it cannot move an external stylesheet into Fluentic’s ordering system.

For intentional interop overrides, Fluentic supports important values:

const selectSheet = createSheet([
  selectPart.control({
    borderColor: style.important(selectTokens.accent),
    boxShadow: style.important('none'),
  }),
]);

That emits the final declaration with !important.

I see this mostly as an interop tool.

Ordinary Fluentic styles usually should not need it, because composition, variants, scopes, and sheet order already describe the priority inside the styles Fluentic controls.

But third-party CSS is not always polite.

Sometimes a wrapper needs an explicit escape hatch.

Debugging Still Matters

Selector sheets still produce atomic rules.

If a later sheet sets the same selector property, the later class wins for that resolved style prop.

In debug mode, sheet selector classes use a shorter default format than ordinary atomic classes:

:where(.sheet-color-red--abc) .react-select__single-value {
  color: red;
}

The full selector is omitted by default because third-party selectors can get long.

If you want it while debugging, you can configure sheetClassNameFormat:

configureStyleRuntime({
  css: {
    debugClassName: true,
    sheetClassNameFormat: 'sheet-[(selector)-](property)[-(value)]--$hash',
  },
});

That is useful when you are tracing which selector sheet produced a rule.

The larger point is that selector sheets do not leave the Fluentic pipeline.

They still have generated classes.

They still have style data.

They can still participate in sourcemaps and debug traces.

The third-party selector does not become anonymous CSS pasted somewhere else.

When To Use `createSheet`

I think of createSheet(...) as the tool for DOM boundaries.

Use normal style(...) when you own the element.

Use style.slot(...) and style.scope(...) when you own a reusable component and want to expose public styling targets.

Use createSheet(...) when the target is a selector owned by something else:

third-party component internals
fixed library class names
data attributes from another component
portal or overlay DOM
wrapper components around non-Fluentic APIs
generated HTML from Markdown or CMS content

It is not meant to replace slots.

If you own the component, slots are usually the better contract. A slot is a TypeScript value that names a public component part directly.

But when the DOM is already owned by a library, a selector may be the only honest contract available.

createSheet(...) gives that contract a Fluentic shape.

Why This Became Its Own API

At first, I thought maybe normal styles plus getClassName(...) would be enough for most interop.

And for direct element interop, that is often true.

But third-party component wrappers kept showing a different pattern.

The wrapper owned one boundary element.

The library owned many internal elements.

The app wanted those internal elements to follow the same themes, variants, and debug path as the rest of the design system.

That is not really a className problem.

It is a selector boundary problem.

So createSheet(...) became the API for saying:

Attach this generated class here, and let these known selectors below it receive Fluentic styles.

That keeps the compromise small.

The selector is still there because the DOM is not yours.

But the rest of the styling flow stays connected.

Docs

Related docs:

Fluentic Style is still new and currently in beta.

I am still looking for early users and feedback, especially from people building real component systems where styling needs to cross more than one kind of boundary: owned DOM, reusable component slots, third-party selectors, and portal targets.

That is the reason createSheet(...) exists.

Not because Fluentic wants selectors to become the main component styling API.

Almost the opposite.

It exists for the places where selectors are the honest boundary, so the rest of the component styling approach does not have to fall apart there.

Building Fluentic Style: Why `combineStyle` Became More Than A Merge Helper

OmniDev — Sat, 29 Aug 2026 00:28:39 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

combineStyle is one of those APIs that looks smaller than the problem behind it.

const css = combineStyle(
  cardStyles,
  bindScope(cardStyles.root, props.theme),
);

At first glance, it looks like a merge helper.

But I eventually stopped thinking about it that way.

To me, combineStyle became the place where a component’s own styles meet styles passed from outside.

The problem was not “how do I merge two things?”

The real problem was:

How do component styles stay extendable without making JSX turn into a pile of manual style merging?

That is the part I kept running into.

The Simple Version Is Always Fine

A component usually starts clean.

Maybe you have a Card.

import { style } from '@fluentic/style';

const cardStyles = {
  root: style({
    padding: 24,
    borderRadius: 12,
    backgroundColor: 'white',
  }),

  title: style({
    fontSize: 20,
    fontWeight: 700,
  }),

  body: style({
    color: '#475569',
  }),
};

type CardProps = {
  title: string;
  body: string;
};

export function Card(props: CardProps) {
  return (
    <article css={cardStyles.root}>
      <h2 css={cardStyles.title}>{props.title}</h2>
      <p css={cardStyles.body}>{props.body}</p>
    </article>
  );
}

This is the happy path: the markup stays readable, the styles are nearby, and for many components this is enough.

The JSX mostly tells me what the component renders.

That is the feeling I want to keep.

Then The Component Becomes Reusable

At some point, the component needs more styling inputs.

Maybe one page needs a featured card.

Maybe another page needs a compact card.

Maybe a design system wants to expose a few component parts so product code can style them.

With class names, I usually end up adding something like this:

type CardProps = {
  title: string;
  body: string;
  classes?: {
    root?: string;
    title?: string;
    body?: string;
  };
};

Then the component starts stitching its own classes together with incoming classes:

export function Card(props: CardProps) {
  return (
    <article className={cx(styles.root, props.classes?.root)}>
      <h2 className={cx(styles.title, props.classes?.title)}>
        {props.title}
      </h2>

      <p className={cx(styles.body, props.classes?.body)}>
        {props.body}
      </p>
    </article>
  );
}

This works.

I have written this kind of code many times.

Then variants arrive:

export function Card(props: CardProps) {
  return (
    <article
      className={cx(
        styles.root,
        props.compact && styles.compactRoot,
        props.featured && styles.featuredRoot,
        props.classes?.root,
      )}
    >
      <h2
        className={cx(
          styles.title,
          props.compact && styles.compactTitle,
          props.featured && styles.featuredTitle,
          props.classes?.title,
        )}
      >
        {props.title}
      </h2>

      <p
        className={cx(
          styles.body,
          props.featured && styles.featuredBody,
          props.classes?.body,
        )}
      >
        {props.body}
      </p>
    </article>
  );
}

Still normal frontend code.

Still understandable.

But the JSX is no longer only showing the structure of the component.

It is also carrying the styling merge rules.

And the more parts the component has, the more that merge logic spreads through the markup.

That is the part I wanted Fluentic to avoid.

The JSX should mostly express the data, the elements, and the component structure.

Styling composition should have a clear place instead of leaking into every className or css prop.

The First Idea Was A Hook

At one point, I thought Fluentic might need something hook-like.

function Card(props: CardProps) {
  const css = useStyles(cardStyles, props.theme);

  return (
    <article css={css.root}>
      <h2 css={css.title}>{props.title}</h2>
      <p css={css.body}>{props.body}</p>
    </article>
  );
}

For React, this feels familiar.

A hook gives you a place to prepare styles before render.

A hook can read props.

A hook can memoize.

So the idea is not strange.

But the more Fluentic grew, the less I wanted the style resolver to be a hook.

A hook could still call a shared cache internally, so this was not only a performance argument.

The bigger issue was that this operation does not really need React state, React lifecycle, or React component identity.

Style composition depends on the style objects and scopes you pass in.

Making the main API a hook would make React part of something that does not actually require React.

That felt like the wrong direction, especially once Fluentic started moving toward Next.js server/client support, SolidJS support, and compiler-transformed JSX.

So combineStyle became a plain function.

const css = combineStyle(cardStyles, ...inputs);

No hook.

No component instance required.

No React lifecycle required.

Just styles in, final styles out.

The Fluentic Version

In Fluentic, when a component wants to expose styleable parts, those parts can become slots.

import {
  bindScope,
  combineStyle,
  style,
  type StyleProp,
  type StyleTheme,
} from '@fluentic/style';

const cardStyles = {
  root: style.slot({
    padding: 24,
    borderRadius: 12,
    backgroundColor: 'white',
  }),

  title: style.slot({
    fontSize: 20,
    fontWeight: 700,
  }),

  body: style.slot({
    color: '#475569',
  }),
};

type CardProps = {
  title: string;
  body: string;
  compact?: boolean;
  featured?: boolean;
  css?: StyleProp;
  theme?: StyleTheme;
};

A slot still feels like writing a normal style.

The extra part is that another style can point to it later.

Outside styles can provide changes for root, title, body, or any other public slot the component exposes.

Those grouped changes are scopes:

const compactCard = style.scope([
  cardStyles.root({
    padding: 16,
  }),

  cardStyles.title({
    fontSize: 16,
  }),
]);

const featuredCard = style.scope([
  cardStyles.root({
    backgroundColor: '#0f172a',
    color: 'white',
  }),

  cardStyles.title({
    color: '#e0f2fe',
  }),

  cardStyles.body({
    color: '#cbd5e1',
  }),
]);

Then the component prepares the final styles in one place:

export function Card(props: CardProps) {
  const css = combineStyle(
    cardStyles,
    bindScope(
      cardStyles.root,
      props.compact && compactCard,
      props.featured && featuredCard,
      props.theme,
    ),
  );

  return (
    <article css={[css.root, props.css]}>
      <h2 css={css.title}>{props.title}</h2>
      <p css={css.body}>{props.body}</p>
    </article>
  );
}

This is the pattern I wanted.

The component has one style resolution point.

The JSX receives the final styles.

The root still accepts props.css for direct root element styling.

The theme prop accepts styles for component slots.

The component still decides where those styles attach.

<Card
  title="Revenue"
  body="$42,300"
  featured
  theme={dashboardCardTheme}
/>

A small note on the names here:

StyleTheme is the type Fluentic uses for styles passed into component slots.

The prop does not have to be called theme, but that is the convention Fluentic docs use.

bindScope(cardStyles.root, props.theme) tells Fluentic where those incoming scopes should attach. For a card, that target is usually the root slot.

Why `bindScope` Matters Here

Scopes need a target slot.

You can call each scope directly:

const css = combineStyle(
  cardStyles,
  props.compact && compactCard(cardStyles.root),
  props.featured && featuredCard(cardStyles.root),
  props.theme?.(cardStyles.root),
);

That works for simple cases.

But once you have multiple scopes, repeating the same target gets noisy.

bindScope lets the component say the target once:

const css = combineStyle(
  cardStyles,
  bindScope(
    cardStyles.root,
    props.compact && compactCard,
    props.featured && featuredCard,
    props.theme,
  ),
);

This is also why props.theme usually stays last.

The component can apply its own state or variant scopes first, then let external component styling come after.

That keeps the override order predictable.

Base styles first.

Component variants next.

Styles passed from outside last.

And if the root element also accepts a direct css prop, that can stay at the root element:

<article css={[css.root, props.css]}>

So there are two related extension points:

theme -> styles provided to component slots
css   -> styles attached to the root element

That distinction keeps the component API flexible without making every element carry a long merge expression.

The Difference In JSX

Without this kind of resolution point, the component often ends up with a style merge matrix:

<article
  className={cx(
    styles.root,
    props.compact && styles.compactRoot,
    props.featured && styles.featuredRoot,
    props.classes?.root,
  )}
>
  <h2
    className={cx(
      styles.title,
      props.compact && styles.compactTitle,
      props.featured && styles.featuredTitle,
      props.classes?.title,
    )}
  >
    {props.title}
  </h2>

  <p
    className={cx(
      styles.body,
      props.featured && styles.featuredBody,
      props.classes?.body,
    )}
  >
    {props.body}
  </p>
</article>

With combineStyle, the composition moves up to one place:

const css = combineStyle(
  cardStyles,
  bindScope(
    cardStyles.root,
    props.compact && compactCard,
    props.featured && featuredCard,
    props.theme,
  ),
);

Then the JSX stays closer to the component structure:

return (
  <article css={[css.root, props.css]}>
    <h2 css={css.title}>{props.title}</h2>
    <p css={css.body}>{props.body}</p>
  </article>
);

This is a small difference in code, but it changes the maintenance feeling.

The style composition has a home.

The markup does not need to repeat the same merge pattern for every part.

The Cache Question

The hard part is that hooks make caching feel obvious.

With a hook, you can imagine useMemo.

You can imagine instance-local caching.

You can make the work feel tied to React render behavior.

A plain function does not automatically give you that comfort.

So combineStyle had to answer:

If this is just a function, how does it avoid doing too much work?

The answer in Fluentic is to reuse work based on the style objects and the path used to resolve them.

Most component styles are stable values:

const cardStyles = {
  root: style.slot({ padding: 24 }),
  title: style.slot({ fontWeight: 700 }),
};

Scopes are often stable too:

const compactCard = style.scope([
  cardStyles.root({ padding: 16 }),
  cardStyles.title({ fontSize: 16 }),
]);

So when many component instances use the same styles and scopes, Fluentic can reuse the work instead of treating each instance like a completely new styling case.

combineStyle(
  cardStyles,
  bindScope(cardStyles.root, compactCard),
);

The useful question is not only:

What happened in this component instance?

It is also:

Have these styles already been resolved this way?

That fits Fluentic better than making the API a React hook.

A hook can still be useful in some styling systems, but combineStyle does not need to be one.

Production Should Not Pay For Dev-Time Work

There is another important piece here.

combineStyle should not make every render feel like Fluentic is compiling styles again from scratch.

In development, Fluentic needs to understand your style code, keep debug names, generate sourcemaps, and make DevTools useful.

That work is valuable while building.

But it should not become the normal production cost.

In production, Fluentic’s compiler and bundler plugin can turn style chains into extracted CSS and prepared JavaScript output.

The browser still handles the parts that only become known while the app is rendering, like scopes chosen by props or state, theme values, and prop-driven style values.

But the heavier work of reading the style chain and generating CSS belongs to the build.

So the goal for combineStyle is practical:

Keep component style composition predictable and fast enough that component authors do not have to think about it.

It should be easy to prepare final styles in one place and keep the JSX readable.

Why This Became The Handoff Point

At first, combineStyle looked like a utility.

Now I see it as the handoff point inside a component.

It is where the component gathers:

its default styles
its slots
variant styles
state styles
styles passed from outside
token/theme overrides
root-level css

Then JSX receives the final styles.

That matters because Fluentic is trying to support more than one styling layer.

Quick element styling:

<div css={{ padding: 16 }} />

Component part styling:

<Card theme={featuredCardTheme} />

Root element styling:

<Card css={pageCardSpacing} />

App-level theming:

<main css={[appRoot, darkTheme]}>
  <Card theme={dashboardCardTheme} />
</main>

And the component handoff point:

const css = combineStyle(
  cardStyles,
  bindScope(cardStyles.root, props.theme),
);

That is the reason combineStyle exists.

Not because merging styles is difficult by itself.

It exists so a component has one explicit place where its own styles meet styles passed from outside, while its JSX stays focused on structure.

Docs

Related docs:

Fluentic Style is still new and currently in beta.

I am still looking for early users and feedback, especially from people building real component systems where styling needs to go beyond one element and one class name.

Beyond CSS-in-JS: From Element Styles To Component Themes

OmniDev — Thu, 27 Aug 2026 01:45:42 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

I started Fluentic Style with a small idea:

I wanted React Native-style composition in React web.

<View style={[base, active && activeStyle, props.style]} />

That kind of style composition always felt practical to me.

You have a base style.

You add another style when some state is active.

You still let styles come from props.

So the first Fluentic idea looked like this:

<div css={[base, active && selected, props.css]} />

That was the starting point.

I wrote about it here:

Bringing React Native Style Composition to React

But the more Fluentic evolved, the clearer it became that the real problem was never just CSS-in-JS or build-time extraction.

What felt missing was a better pattern for component-level styling, and for theming that can move from app-wide defaults down to a specific component.

The bigger question became:

Can a styling system cover the everyday path from styling one element, to styling reusable components, to component themes, to app-wide themes, while still keeping debugging and production extraction usable?

That is the version of Fluentic I am building now.

Not just another CSS-in-JS syntax.

More like an attempt to connect the parts of styling that often feel split apart.

The Problem Is Not Only Putting CSS In JS

CSS-in-JS gave frontend developers something useful.

It made styles feel closer to components.

It made dynamic styling easier.

It made local styling easier.

It made React UI feel less split between a component file and a separate stylesheet.

But daily app styling is bigger than:

How do I put CSS on this DOM element?

That is one layer.

A real app usually moves through several layers:

element style

component style

component variant

component theme

app-wide theme

production output

debugging

Many styling approaches are good at one or two of those.

Some are great for quick element styles.

Some are great for app-wide tokens.

Some are great for utility classes.

Some are great for local CSS files.

Some are great for runtime dynamic values.

Some are great for extracted CSS.

But in real app work, I kept wanting those layers to connect better.

That became the bigger Fluentic goal:

style composition from elements, to components, to component themes, to app-wide themes

without turning each layer into a separate styling system.

Start With One Element

The smallest case should stay small.

If I only need to style one element, I should be able to write one style and attach it.

import { style } from '@fluentic/style';

const saveButton = style({
  borderRadius: 8,
  padding: '8px 12px',
});

<button css={saveButton}>Save changes</button>;

If that element needs hover, media, or state styles, it should still stay attached to the same style idea:

const saveButton = style({
  borderRadius: 8,
  padding: '8px 12px',
}).hover({
  backgroundColor: '#f3f4f6',
});

<button css={saveButton}>Save changes</button>;

For teams that like utility-class authoring, Fluentic can also work closer to that style:

const saveButton = cx(
  'inline-flex',
  'items-center',
  'rounded-md',
  'px-3',
  'py-2',
).hover('bg-slate-100');

<button css={saveButton}>Save changes</button>;

So Fluentic does not start by forcing every use case into components, themes, or design-system structure.

Sometimes you just need to style an element.

That should be easy.

Then The Element Becomes A Component

The next problem appears when that styled element becomes reusable.

A button is not always just one DOM node.

It can have parts:

function Button(props) {
  return (
    <button>
      <span>{props.icon}</span>
      <span>{props.children}</span>
    </button>
  );
}

Now the styling question changes.

There is a root.

There is an icon.

There is a label.

Maybe a loading indicator.

Maybe an action area.

Maybe a wrapper around some third-party element.

Frontend teams already think in these names:

root, icon, label, content, trigger, item, control, thumb, track, portal

The old HTML/CSS way would usually name those parts with classes:

.button { ... }
.button__icon { ... }
.button__label { ... }
.button[data-danger] .button__label { ... }

That is understandable.

But in a component system, the component owns the inside.

So when the outside needs to style those parts, React APIs often grow shapes like this:

<Button
  className="danger-button"
  iconClassName="danger-icon"
  labelClassName="danger-label"
>

or:

<Button
  classes={{
    root: 'danger-button',
    icon: 'danger-icon',
    label: 'danger-label',
  }}
>

or:

<Button
  styles={{
    label: { fontWeight: 700 },
  }}
>

These are practical. I have written APIs like this many times.

But the repeated shape is clear:

the component has parts, and outside code needs a supported way to style those parts

Fluentic’s answer is style.slot(...).

A slot is a normal style for the component itself, but it also gives that component part an identity that outside styles can target later.

const buttonStyles = {
  root: style.slot({
    borderRadius: 8,
    padding: '8px 12px',
  }),

  icon: style({
    flex: '0 0 auto',
  }),

  label: style.slot({
    fontWeight: 700,
  }),
};

Notice that not every internal element needs to be a slot.

icon can stay private with style(...).

root and label become public styling targets with style.slot(...).

That is the first important split:

use style(...) for ordinary element styles

use style.slot(...) when a component part should be styleable from outside

Component Themes Are Not The Same As App Themes

Once a component exposes slots, outside code needs a way to provide styles for those slots.

That is where style.scope(...) comes in.

A scope groups changes for public component parts:

const dangerButton = style.scope([
  buttonStyles.root({
    backgroundColor: '#dc2626',
  }),

  buttonStyles.label({
    color: 'white',
  }),
]);

The component receives that as a theme-like input:

type ButtonProps = {
  children: React.ReactNode;
  icon?: React.ReactNode;
  theme?: StyleTheme;
};

Then the component prepares the styles it will render:

function Button(props: ButtonProps) {
  const css = combineStyle(
    buttonStyles,
    bindScope(buttonStyles.root, props.theme),
  );

  return (
    <button css={css.root}>
      {props.icon ? <span css={css.icon}>{props.icon}</span> : null}
      <span css={css.label}>{props.children}</span>
    </button>
  );
}

This is different from passing a raw class name into each part.

The outside says what it wants to change:

<Button theme={dangerButton}>Delete</Button>

The component still decides where those styles attach.

That is why I think of scopes as component-facing themes.

They are not only global colors.

They can change slots, tokens, states, media rules, and multiple component parts together.

App-Wide Themes Need A Different Layer

App-wide theming is related, but it is not exactly the same problem.

Sometimes the app wants to define shared values:

const color = createTokens({
  surface: '#ffffff',
  text: '#111827',
  accent: '#2563eb',
  danger: '#dc2626',
});

A style can use those tokens:

const page = style({
  backgroundColor: color.surface,
  color: color.text,
});

Then an app theme can override those token values:

const darkTheme = createTheme([
  color.surface('#0f172a'),
  color.text('#f8fafc'),
]);

That is app-facing theming.

It answers:

What should surface, text, or accent mean in this part of the app?

A component theme answers a different question:

How should this component’s public parts or component-specific tokens change?

Fluentic supports both.

Use createTheme(...) when the theme only changes token values.

Use style.scope(...) when the theme needs to affect component slots, component tokens, states, media conditions, or multiple parts together.

This distinction matters because app-wide themes and component themes often live in different realms.

A design system may define app tokens.

A component library may expose component tokens and slots.

An app may need to map app values into component values.

For example:

const button = createTokens({
  color: {
    surface: '#2563eb',
    surfaceHover: '#1d4ed8',
    text: '#ffffff',
  },
});

const appButtonTheme = style.scope([
  button.color.surface(color.accent),
  button.color.surfaceHover(color.accent),
  button.color.text('#ffffff'),
]);

The app theme controls what color.accent means.

The component theme says how the button should use that app value.

That is the kind of bridge I wanted Fluentic to support.

Not app theming over here, component theming over there, and manual glue in between.

One styling path that can connect them.

Variants Become Scopes Too

Component variants are usually where styling logic starts getting busy.

A variant like this looks simple:

<Button size="sm" tone="danger" />

But internally it may affect several parts:

root padding
label font size
icon size
background color
hover color
disabled color

Without a shared styling shape, that often becomes a matrix of class names or conditionals.

In Fluentic, a variant can be a scope:

const compactButton = style.scope([
  buttonStyles.root({
    gap: 6,
    paddingBlock: 6,
    paddingInline: 10,
  }),

  buttonStyles.label({
    fontSize: 13,
  }),
]);

const dangerButton = style.scope([
  buttonStyles.root({
    backgroundColor: '#dc2626',
  }),

  buttonStyles.label({
    color: 'white',
  }),
]);

And because scopes are values, they compose:

<Button
  theme={[
    compact && compactButton,
    danger && dangerButton,
    props.theme,
  ]}
>
  Delete
</Button>

This is where Fluentic starts feeling bigger than element-level CSS-in-JS.

The same composition idea can move from:

<div css={[base, active && selected]} />

to:

<Button theme={[compact && compactButton, danger && dangerButton]} />

The shape stays familiar.

The layer changes.

Debugging Still Has To Follow The Whole Path

A nice authoring API is not enough if generated CSS becomes a dead end.

That is one of the places where I think styling tools often ask developers to accept too much friction.

You write nice code.

DevTools shows generated class names or injected CSS.

Then you have to guess where the rule came from.

Fluentic emits atomic CSS, but not only for output size or dedupe.

Atomic CSS also gives a useful debugging unit:

one generated rule can map back to one styling decision

For example:

style({
  backgroundColor: '#2563eb',
}).hover({
  backgroundColor: '#1d4ed8',
});

A generated hover background-color rule should be able to point back to the backgroundColor inside .hover(...).

For slots and scopes, the trace should stay meaningful too.

If this wins:

const dangerButton = style.scope([
  buttonStyles.label({
    color: 'white',
  }),
]);

the generated color rule should be able to lead back to the scoped label override.

That is why Fluentic keeps debug metadata and sourcemap information in development.

The debug story should follow the same path:

style → slot → scope → generated CSS → source trace

If component styling is part of the model, debugging component styling has to be part of the model too.

Production Extraction Should Fit The Same Model

The other big requirement is production.

A runtime-only CSS-in-JS library can be convenient, especially in small apps.

But production apps need more.

They need extracted CSS.

They need SSR and framework integrations.

They need predictable output.

They need the runtime to do less work when the build can prepare things ahead of time.

Fluentic’s compiler and bundler plugins extract the static style declarations from patterns like:

style(...)
style.slot(...)
style.scope(...)

and emit extracted atomic CSS plus prepared JavaScript output.

But real apps still have runtime-known choices:

<Button
  theme={[
    compact && compactButton,
    danger && dangerButton,
    props.theme,
  ]}
>
  Delete
</Button>

The build can prepare CSS from the style declarations.

The runtime still resolves which themes, scopes, token values, and prop-driven choices apply during render.

That is important.

I do not want a system where extracted CSS only works for the boring cases, and the moment a component becomes dynamic you move to a different styling model.

The goal is one authoring model:

build extracts what can be prepared

runtime resolves what the app decides while rendering

Syntax Should Be Flexible, But The Path Should Stay Connected

CSS-in-JS discussions often become syntax discussions.

Objects.

Tagged templates.

Utility classes.

Inline styles.

Generated classes.

CSS files.

I understand why. Syntax is what developers touch every day.

Fluentic started object-first:

const card = style({
  padding: 16,
  borderRadius: 12,
});

But Fluentic now also supports Tailwind-like class-name authoring:

const card = cx('rounded-xl', 'bg-white', 'p-4');

It also supports Tailwind-style object presets and custom transforms.

A design system can create its own vocabulary:

const panel = ui({
  row: true,
  center: true,
  gapX: 12,
});

The point is not that every team should write styles the same way.

The point is that different syntaxes can still feed the same Fluentic path.

Once they become Fluentic styles, they can still participate in:

element styling
slots
scopes
token themes
component themes
atomic CSS output
production extraction
sourcemaps
debug metadata

That is the practical reason custom transforms matter.

They are not only a syntax trick.

They let a team adapt the authoring vocabulary without leaving the rest of the styling system behind.

Frameworks Need Bridges, Not A New Styling Model

Fluentic started with React.

React is still the main focus.

But modern frontend is not only one JSX/runtime story.

Next.js App Router brings server components, server/client rendering, HMR, streaming concerns, development CSS, sourcemaps, and production extraction.

SolidJS has its own compiler-centered JSX path.

Preact has a different prop shape.

So Fluentic is moving toward a stable styling core with framework-specific bridges.

React can use Fluentic’s JSX runtime, or it can use a cssProp compiler transform.

Next.js gets a deeper integration for App Router, RSC development styling, debug CSS, sourcemaps, and production extraction.

SolidJS client-side support uses a css prop transform before Solid’s compiler.

The goal is:

keep the style path stable, adapt the framework handoff

That keeps Fluentic from being only a React runtime library.

The style ideas can stay the same while the JSX integration changes per framework.

What Fluentic Currently Has

Fluentic Style is still new and currently in beta.

But it already covers much more than my first small idea.

Authoring:

style(...) object styles
cx(...) class-name authoring
Tailwind-like class-name preset
Tailwind-style object preset
custom style functions
custom transforms

Element and component composition:

css prop arrays
conditional styles
style.slot(...) for public component parts
style.scope(...) for component themes and slot overrides
combineStyle(...)
bindScope(...)

Theming:

createToken(...)
createTokens(...)
createTheme(...) for token-only themes
style.scope(...) for component themes, slot overrides, and token mapping

Build and debug:

atomic CSS in development and production
production CSS extraction
prepared JavaScript output
debug metadata
sourcemap support
development utilities for inspecting generated styles

Frameworks:

React
Next.js App Router
SolidJS client-side support
Preact-oriented adapter path

That is far beyond the original idea.

The first goal was:

bring React Native-style composition to React web

The current goal is closer to:

make everyday styling composition work from element styles to component styles to component themes to app-wide themes, with debugging and production output still part of the same story

That is the part that keeps me building it.

Closing

I do not think existing CSS-in-JS approaches are wrong.

I do not think CSS is broken.

A lot of styling approaches are useful, and I still use many familiar patterns.

Fluentic is my attempt to connect the parts that I kept seeing split apart:

quick element styling
component styling
component theming
app-wide theming
style composition
generated CSS debugging
production extraction
framework integration
flexible authoring syntax

It is still beta, and I expect the API to keep improving.

But the direction is clear now.

Fluentic is no longer only my attempt to bring React Native-style arrays to React web.

It is an attempt to make styling feel more complete for component-based apps: from one element, to a reusable component, to local component themes, to app-wide themes, while still caring about CSS output, DevTools, production builds, and framework realities.

Useful links:

Building Fluentic Style: Rethinking How Outside Styles Reach Inside Components

OmniDev — Sun, 23 Aug 2026 00:20:24 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

The feeling I keep having is that styling in component frameworks often asks components to fit back into the old HTML + CSS model, instead of asking what CSS composition should look like when components are the main unit.

That is not meant as a takedown of CSS.

I like CSS.

And the HTML + CSS model makes a lot of sense in its own world.

In that model, you write HTML, give elements class names, and use selectors when a nested part needs styling.

<div class="card">
  <h2 class="card-title">Revenue</h2>
  <p class="card-body">$42,300</p>
</div>

.card {
  padding: 16px;
  border-radius: 12px;
}

.card-title {
  font-size: 18px;
  font-weight: 700;
}

.card .card-body {
  color: #475569;
}

That model has problems.

Global CSS can leak. Naming is hard. Specificity can become painful. Large stylesheets can become difficult to maintain.

But the basic mental model is easy to understand:

Give the part a name, then style that named part.

Even when the ecosystem adds SCSS, BEM, naming conventions, CSS Modules, and other tools, a lot of the core idea stays familiar.

There is markup.

There are names.

There are selectors.

Styles reach elements through those names.

That world feels coherent because HTML and CSS are built around that relationship.

Then components change the shape of UI.

Components Change The Unit

In React and other component frameworks, we usually stop thinking of UI as one big HTML document.

We think in components:

<Card title="Revenue">$42,300</Card>

That is a huge improvement.

A component owns its internal markup.

It receives props.

It composes with children.

It hides implementation details.

It can be typed.

It can be transformed by tooling.

It can become part of a design system.

But styling still has to answer a familiar question:

How do I style the thing inside?

In HTML + CSS, if I want to style the title inside a card, I can write:

.compact-card .card-title {
  font-size: 14px;
}

In a component world, that assumes a lot:

the component exposes a .card-title class
the DOM structure stays the same
outside CSS is allowed to reach inside
the styling system is not isolating class names
the component author intends that part to be customized

Sometimes that is fine.

I still use selector-based styling in many places.

But the component boundary changes the feeling.

The component owns the inside.

Outside code still wants to customize it.

That is the tension.

The Usual Ways We Handle This

Over time, frontend code has found many practical ways to handle this.

One common approach is more class props:

<Card
  className="compact-card"
  titleClassName="compact-title"
  bodyClassName="compact-body"
  actionClassName="compact-action"
/>

This is explicit and easy to understand.

But the component API starts growing around styling needs.

Every public part needs a prop.

Every prop needs a name.

Every name becomes a contract.

A slightly more organized version is a per-part override object:

<Card
  classes={{
    root: 'compact-card',
    title: 'compact-title',
    body: 'compact-body',
    action: 'compact-action',
  }}
  styles={{
    root: { padding: 12 },
    title: { fontSize: 14 },
    body: { color: '#475569' },
  }}
/>

This gives the consumer two common escape hatches:

classes when they already have CSS somewhere
styles when they want to pass a small direct override

That is convenient.

Inside the component, though, every public part still becomes a merge point:

type CardProps = {
  title: string;
  children: React.ReactNode;
  actionLabel: string;
  classes?: {
    root?: string;
    title?: string;
    body?: string;
    action?: string;
  };
  styles?: {
    root?: React.CSSProperties;
    title?: React.CSSProperties;
    body?: React.CSSProperties;
    action?: React.CSSProperties;
  };
};

function Card(props: CardProps) {
  return (
    <article
      className={cx('card', props.classes?.root)}
      style={{ ...rootStyle, ...props.styles?.root }}
    >
      <h2
        className={cx('card-title', props.classes?.title)}
        style={{ ...titleStyle, ...props.styles?.title }}
      >
        {props.title}
      </h2>

      <p
        className={cx('card-body', props.classes?.body)}
        style={{ ...bodyStyle, ...props.styles?.body }}
      >
        {props.children}
      </p>

      <button
        className={cx('card-action', props.classes?.action)}
        style={{ ...actionStyle, ...props.styles?.action }}
      >
        {props.actionLabel}
      </button>
    </article>
  );
}

This is not strange code.

I have written this kind of code a lot.

It is practical.

But it shows the repeated shape: every styleable part needs a name, a prop shape, and a merge point.

Variants are another common path:

<Card size="sm" tone="danger" density="compact" />

Variants are great when the design cases are known.

But when a variant affects many inner parts, the component starts carrying a small style matrix:

function Card(props: CardProps) {
  const rootClass = cx(
    'card',
    props.size === 'sm' && 'card-sm',
    props.density === 'compact' && 'card-compact',
    props.tone === 'danger' && 'card-danger',
  );

  const titleClass = cx(
    'card-title',
    props.size === 'sm' && 'card-title-sm',
    props.tone === 'danger' && 'card-title-danger',
  );

  const bodyClass = cx(
    'card-body',
    props.density === 'compact' && 'card-body-compact',
  );

  const actionClass = cx(
    'card-action',
    props.tone === 'danger' && 'card-action-danger',
  );

  return (
    <article className={rootClass}>
      <h2 className={titleClass}>{props.title}</h2>
      <p className={bodyClass}>{props.children}</p>
      <button className={actionClass}>{props.actionLabel}</button>
    </article>
  );
}

Again, not wrong.

Sometimes this is exactly the right choice.

CSS variables are also useful:

<Card
  style={{
    '--card-title-size': '14px',
    '--card-body-color': '#475569',
  }}
/>

They are native, flexible, and they compose well with CSS.

But the component still needs to intentionally expose those variables:

.card-title {
  font-size: var(--card-title-size, 18px);
}

.card-body {
  color: var(--card-body-color, #475569);
}

That is a good tool, but it is still a public styling surface the component author has to design.

So I do not see these approaches as wrong.

They are practical, and they exist because the problem is real.

The part that stays interesting to me is the repeated shape:

Outside styles want to reach meaningful component parts, and component authors need a clean way to expose those parts without leaking the whole DOM.

That is the problem I want Fluentic to explore.

Co-Location Helps, But It Solves A Different Layer

Tailwind and utility-first styling change the day-to-day feeling of writing CSS for many developers.

Instead of jumping between JSX and a CSS file, you can write the style directly where the element is rendered:

<button className="inline-flex items-center rounded-md px-3 py-2 text-sm font-medium">
  Save
</button>

That is a big deal.

The style is close to the element.

You can read the JSX and understand a lot of the visual output immediately.

Fluentic can support writing styles right where the element is rendered too.

For example, you can write Tailwind-like classes through Fluentic:

<button css={cx('inline-flex', 'items-center', 'rounded-md', 'px-3', 'py-2')}>
  Save
</button>

or write a style object directly on the element:

<button
  css={style({
    display: 'inline-flex',
    alignItems: 'center',
    borderRadius: 8,
    paddingInline: 12,
    paddingBlock: 8,
    fontSize: 14,
    fontWeight: 600,
  })}
>
  Save
</button>

But co-location mostly answers this question:

How do I style the element I am writing right now?

That is useful.

It just is not the same as the reusable component problem.

Once the UI becomes this:

<Card title="Revenue">$42,300</Card>

the outside code is no longer writing the h2, the body, or the action button directly.

Those elements live inside Card.

So the harder question becomes:

How does outside code style the parts inside a component it does not render directly?

Co-location does not remove that boundary.

It makes styling local elements nicer.

But a reusable component still needs a way to expose the internal parts that are intentionally styleable.

A Card Component Starts Simple

Imagine you start with a card component used in one place.

At this point, it does not need a public styling API.

It just owns its styles.

import { style } from '@fluentic/style';

const cardStyles = {
  root: style({
    display: 'grid',
    gap: 12,
    padding: 16,
    borderRadius: 12,
    backgroundColor: '#ffffff',
    border: '1px solid #e2e8f0',
  }),

  title: style({
    margin: 0,
    fontSize: 18,
    fontWeight: 700,
    color: '#0f172a',
  }),

  body: style({
    margin: 0,
    color: '#475569',
    lineHeight: 1.6,
  }),

  action: style({
    justifySelf: 'start',
    border: 0,
    borderRadius: 8,
    paddingInline: 12,
    paddingBlock: 8,
    backgroundColor: '#2563eb',
    color: '#ffffff',
  }),
};

type CardProps = {
  title: string;
  children: React.ReactNode;
  actionLabel: string;
};

export function Card(props: CardProps) {
  return (
    <article css={cardStyles.root}>
      <h2 css={cardStyles.title}>{props.title}</h2>
      <p css={cardStyles.body}>{props.children}</p>
      <button css={cardStyles.action}>{props.actionLabel}</button>
    </article>
  );
}

This is enough when the card only has one job.

The styles are owned by the component, and no outside code needs to customize the inner parts.

But apps rarely stay frozen.

Maybe the same card structure starts showing up in more places.

Maybe one page needs a compact version.

Maybe another page needs a danger version.

Maybe a dashboard wants the same base card, but with a different title color and action button.

At that point, the component starts becoming a common base component, and the styling question changes.

That is when the component needs to expose some styling surface.

The question is how.

Change Public Parts To Slots

In Fluentic, the small shift is to change the parts that should be customizable from style(...) to style.slot(...).

import { style } from '@fluentic/style';

export const cardStyles = {
  root: style.slot({
    display: 'grid',
    gap: 12,
    padding: 16,
    borderRadius: 12,
    backgroundColor: '#ffffff',
    border: '1px solid #e2e8f0',
  }),

  title: style.slot({
    margin: 0,
    fontSize: 18,
    fontWeight: 700,
    color: '#0f172a',
  }),

  body: style.slot({
    margin: 0,
    color: '#475569',
    lineHeight: 1.6,
  }),

  action: style.slot({
    justifySelf: 'start',
    border: 0,
    borderRadius: 8,
    paddingInline: 12,
    paddingBlock: 8,
    backgroundColor: '#2563eb',
    color: '#ffffff',
  }),
};

A slot is still very close to a normal Fluentic style.

The component can render it as its own base style.

The extra thing Fluentic keeps is slot identity.

That means this value can later be used as a target inside a scope:

style.scope([
  cardStyles.title({
    fontSize: 14,
  }),
]);

That is the new capability.

The component author is not only writing styles.

They are also naming the parts that outside code may style on purpose.

The component is saying:

These are the public styling targets: root, title, body, and action.

Not every internal element needs to be public.

Only the parts that should be customizable become slots.

The public target is not a string class name buried in markup.

It is a TypeScript value exported by the component.

Add A Theme Prop

Once a component has slots, outside code needs a way to pass styles for those slots.

In Fluentic, that is usually a theme prop.

import type { StyleTheme } from '@fluentic/style';

type CardProps = {
  title: string;
  children: React.ReactNode;
  actionLabel: string;
  theme?: StyleTheme;
};

The theme prop is not the same thing as css.

css attaches style to one rendered DOM element.

A component theme can contain styles for multiple internal parts.

So the component receives a theme, resolves it against its slots, and then renders the resolved styles.

That is where combineStyle(...) and bindScope(...) come in.

import {
  bindScope,
  combineStyle,
  type StyleTheme,
} from '@fluentic/style';

import { cardStyles } from './cardStyles';

type CardProps = {
  title: string;
  children: React.ReactNode;
  actionLabel: string;
  theme?: StyleTheme;
};

export function Card(props: CardProps) {
  const css = combineStyle(
    cardStyles,
    bindScope(cardStyles.root, props.theme),
  );

  return (
    <article css={css.root}>
      <h2 css={css.title}>{props.title}</h2>
      <p css={css.body}>{props.children}</p>
      <button css={css.action}>{props.actionLabel}</button>
    </article>
  );
}

The component still owns the DOM.

The outside theme does not directly reach into the markup.

The component chooses the root slot, binds incoming themes to that root, and resolves the styles.

Then the component renders:

<article css={css.root}>
  <h2 css={css.title}>{props.title}</h2>
  <p css={css.body}>{props.children}</p>
  <button css={css.action}>{props.actionLabel}</button>
</article>

That is the boundary I want.

Outside code provides styling intent.

The component decides where that intent attaches.

Scopes Are Outside Styles For Slots

Now outside code can create a scope.

A scope is a group of styles provided to slots.

import { style } from '@fluentic/style';
import { cardStyles } from './cardStyles';

export const compactCard = style.scope([
  cardStyles.root({
    gap: 8,
    padding: 12,
  }),

  cardStyles.title({
    fontSize: 14,
  }),

  cardStyles.body({
    lineHeight: 1.45,
  }),
]);

Usage:

<Card title="Revenue" actionLabel="Open" theme={compactCard}>
  $42,300
</Card>

This is where the old CSS idea comes back, but in a component-aware shape.

Old CSS:

.compact-card .card-title {
  font-size: 14px;
}

Fluentic:

const compactCard = style.scope([
  cardStyles.title({
    fontSize: 14,
  }),
]);

The intent is similar:

When this outside styling applies, change the title.

But the target is different.

It is not .card-title.

It is cardStyles.title.

That means the target can be typed, composed, transformed, extracted, and debugged as Fluentic style data.

Scopes Can Change Multiple Parts Together

Most useful component themes affect more than one part.

A danger card might change the root border, title color, and action button.

export const dangerCard = style.scope([
  cardStyles.root({
    borderColor: '#dc2626',
    backgroundColor: '#fef2f2',
  }),

  cardStyles.title({
    color: '#991b1b',
  }),

  cardStyles.action({
    backgroundColor: '#dc2626',
  }),
]);

Usage:

<Card title="Delete project" actionLabel="Delete" theme={dangerCard}>
  This action cannot be undone.
</Card>

Without something like scopes, this often turns into many separate props:

<Card
  rootClassName="danger-root"
  titleClassName="danger-title"
  actionClassName="danger-action"
/>

or one large manual object:

<Card
  classes={{
    root: 'danger-root',
    title: 'danger-title',
    action: 'danger-action',
  }}
/>

With Fluentic, the outside styling idea is one value:

theme={dangerCard}

That value can affect multiple public parts.

Scopes Compose

Because scopes are values, they can compose.

<Card
  title="Revenue"
  actionLabel="Open"
  theme={[
    compactCard,
    highlightedCard,
    props.danger && dangerCard,
  ]}
>
  $42,300
</Card>

This is one of the parts I care about most.

The composition still feels close to the style-array idea that inspired Fluentic in the first place:

theme={[baseTheme, compact && compactCard, danger && dangerCard]}

But now the composition can reach multiple component parts.

That is hard to express with plain class props without manually merging many fields.

With scopes, each theme can carry its own slot overrides, and the component resolves them at the boundary.

Scopes Can Have State And Media Conditions

A scope can also use chain methods.

For example, a theme can change several parts when the component root is hovered:

export const interactiveCard = style.scope()
  .hover([
    cardStyles.root({
      borderColor: '#2563eb',
    }),

    cardStyles.title({
      color: '#2563eb',
    }),

    cardStyles.action({
      backgroundColor: '#1d4ed8',
    }),
  ]);

This means:

When the scoped root is hovered, apply these slot overrides.

That is very close to the old selector idea:

.card:hover .card-title {
  color: #2563eb;
}

But Fluentic keeps the target as a slot reference.

The component still controls which DOM element is the root.

The component still controls where the title is rendered.

The outside style only targets the public slot.

Why This Is Not Just Class Names Again

At a glance, slots might look like class names with extra steps.

But they are not the same thing.

A class name contract says:

Here is a string. You may target it.

A slot says:

Here is a component part. You may provide style data for it.

That difference matters.

With class names, outside code often depends on the DOM:

.compact-card .card-title {
  font-size: 14px;
}

With slots, outside code depends on the component’s public styling contract:

style.scope([
  cardStyles.title({
    fontSize: 14,
  }),
]);

The component can change its internal markup and still keep the title slot.

The outside theme still targets cardStyles.title.

So the styling contract is not:

There is an h2 with this class under this parent.

The contract is:

This component exposes a title part.

That feels like a better match for component-based UI.

The Public API Gets Smaller

Without slots and scopes, a component can easily grow this shape:

type CardProps = {
  className?: string;
  titleClassName?: string;
  bodyClassName?: string;
  actionClassName?: string;
  compact?: boolean;
  danger?: boolean;
  highlighted?: boolean;
};

With slots and scopes, the component API can stay smaller:

type CardProps = {
  title: string;
  children: React.ReactNode;
  actionLabel: string;
  theme?: StyleTheme;
};

The styling surface still exists.

It just lives in the exported style contract:

export const cardStyles = {
  root: style.slot({ ... }),
  title: style.slot({ ... }),
  body: style.slot({ ... }),
  action: style.slot({ ... }),
};

This separation feels important.

The component props describe what the component does.

The slots describe which parts can be styled.

The themes describe how outside code wants to style those parts.

Debugging Still Has To Work

This would be much less useful if scopes disappeared into generated CSS and became impossible to trace.

If this wins:

const dangerCard = style.scope([
  cardStyles.title({
    color: '#991b1b',
  }),
]);

I want the generated color rule to point back toward:

cardStyles.title({
  color: '#991b1b',
})

Not just:

Some generated class somewhere.

That is why slots and scopes are part of Fluentic’s style data model.

They carry identity.

A generated rule can know:

This came from a scope.

This targeted the title slot.

This declared color.

This source location produced the rule.

That means the debugging story can still work with component themes.

Slots and scopes are not only runtime helpers.

They are information Fluentic can preserve through generated atomic CSS, development metadata, sourcemaps, and production extraction.

I wrote more about the debugging side here:

Building Fluentic Style: Making Generated CSS Debuggable Again

Production Still Gets CSS

The authoring model can be high-level, but the browser still needs CSS.

Fluentic’s compiler can recognize style(...), style.slot(...), style.scope(...) patterns.

That means component slots and outside scopes can still participate in production CSS extraction.

The component can be written with style data:

const css = combineStyle(
  cardStyles,
  bindScope(cardStyles.root, props.theme),
);

But the production build can still emit extracted CSS and prepared JavaScript output.

That was important to me.

I did not want component-part styling to be a runtime-only trick.

If this pattern is going to be useful in real component libraries, it needs to fit production builds too.

The Part That Feels New

For me, the interesting idea is not the method names.

It is not:

Fluentic has style.slot(...) and style.scope(...).

The interesting idea is:

Fluentic tries to bring back the easy mental model of “style this named part,” but without going back to fragile DOM selectors and string class contracts.

That is what makes this feel different.

A component can expose public styling targets without exposing its whole DOM.

A parent can customize multiple inner parts without receiving a pile of class props.

A theme can be composed as a value.

A scope can carry state and media conditions.

A generated rule can still trace back to the exact slot override that produced it.

That is the component styling API I kept wanting.

The Result

I think this is one of the more important parts of Fluentic.

Not because every component needs slots.

Many elements only need a normal style(...).

But when a component becomes reusable, and outside code needs to style its internal parts, the usual options get awkward fast.

Fluentic’s answer is:

style.slot(...) names a public component part.

style.scope(...) groups outside styles for those parts.

combineStyle(...) resolves the component styles at the component boundary.

bindScope(...) binds incoming themes to the component-owned root slot.

That gives component authors a way to say:

These are the parts you can style, and here is the safe way to style them.

No prop soup.

No guessing DOM selectors.

No turning every class name into a public contract.

Just component parts as style targets.

Fluentic Style is still new and currently in beta. I am looking for early users to try it in real React, Next.js, Preact, Solid, and component-library codebases.

Useful links:

Feedback would help a lot right now, especially from people building component libraries or design-system components. I would love to know whether this slot/scope model matches the styling problems you hit in real UI code.

Building Fluentic Style: The Anatomy of Debuggable Atomic CSS

OmniDev — Mon, 17 Aug 2026 04:29:04 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

Generated CSS has always had one awkward problem for me.

It can make authoring styles nicer, but debugging them worse.

You write clean component code.

You compose styles with objects, functions, conditions, tokens, variants, themes, or whatever the library gives you.

Then something looks wrong in the browser.

So you open DevTools.

And suddenly you are staring at generated class names, generated CSS, injected style tags, transformed files, or sourcemaps that only kind of help.

That is the moment where a styling library either earns trust or loses it.

Because the question is not only:

Can this library generate CSS?

The real question is:

When the CSS is wrong, can I find the code that made it wrong?

While building Fluentic, this became one of the things I cared about most.

I did not want generated CSS to feel like a black box.

And that changed how I started looking at atomic CSS.

Docs related to this topic:

Atomic CSS Has An Ugly Side

Atomic CSS has a simple core idea:

One CSS property/value.

One generated rule.

One reusable class.

That gives you obvious benefits.

Repeated declarations can dedupe. Output can be reused. Runtime insertion can avoid adding the same rule again and again. Production CSS can be easier for the compiler to collect and sort.

But atomic CSS also has a reputation.

And honestly, some of it is fair.

It can push more classes into the HTML.

It can make rendered markup look noisy.

It can feel less human when you inspect an element and see a long list of generated class names instead of one meaningful component class.

For example, this authored style:

const button = style({
  display: 'inline-flex',
  alignItems: 'center',
  gap: 8,
  borderRadius: 8,
  paddingInline: 16,
  paddingBlock: 8,
  backgroundColor: '#2563eb',
  color: '#ffffff',
}).hover({
  backgroundColor: '#1d4ed8',
});

does not become one nice .button rule.

Conceptually, it becomes many tiny generated rules:

.display-a1b2c3 { display: inline-flex }
.align-items-d4e5f6 { align-items: center }
.gap-g7h8i9 { gap: 8px }
.border-radius-j1k2l3 { border-radius: 8px }
.padding-inline-m4n5o6 { padding-inline: 16px }
.padding-block-p7q8r9 { padding-block: 8px }
.background-color-s1t2u3 { background-color: #2563eb }
.color-v4w5x6 { color: #ffffff }
.hover-background-color-y7z8a9:hover { background-color: #1d4ed8 }

And the HTML can look busy:

<button
  class="display-a1b2c3 align-items-d4e5f6 gap-g7h8i9 border-radius-j1k2l3 padding-inline-m4n5o6 padding-block-p7q8r9 background-color-s1t2u3 color-v4w5x6 hover-background-color-y7z8a9"
>
  Save
</button>

That is less pretty than:

<button class="button">Save</button>

I do not want to pretend otherwise.

If your main debugging workflow is reading class names from HTML, atomic CSS can feel messy.

That is the bad part.

But DevTools Does Not Debug CSS As A Component Class

The interesting part is what happens after you stop looking at the HTML as the main debugging surface.

When something looks wrong, I usually inspect the element and look at the CSS rule that won.

For example:

background-color: #1d4ed8

Then the real question becomes:

Where did this background-color come from?

Not:

What is the one perfect class name for this whole button?

But:

Where in my source code, ideally the exact line and column, is this winning CSS property declared?

That is where atomic CSS starts to become surprisingly useful.

Because each generated atomic rule is already about one thing.

One rule.

One CSS property.

One value.

One selector or media context.

That maps very nicely to the debugging question.

In Fluentic, a generated base background-color rule can point back to:

backgroundColor: '#2563eb'

And a generated hover background-color rule can point back to:

.hover({
  backgroundColor: '#1d4ed8',
})

More specifically:

Generated hover background-color rule

→ backgroundColor property

→ inside the .hover(...) chain call

That is the part that made atomic CSS click differently for me.

The tiny rule is not only an output optimization.

It is a good source-tracing unit.

Grouped CSS Makes This Harder

Imagine generated CSS that keeps the whole style object together:

.button-a1b2c3 {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  border-radius: 8px;
  padding-inline: 16px;
  padding-block: 8px;
  background-color: #2563eb;
  color: #ffffff;
}

This looks nicer as generated CSS.

But for debugging, it creates a different problem.

One generated rule now represents many authored properties.

If DevTools lands on .button-a1b2c3, where should the source trace go?

display?

alignItems?

gap?

borderRadius?

paddingInline?

backgroundColor?

color?

You can try to map individual generated declaration ranges back to individual source properties, but the shape is already more complicated.

And real component styling does not stay simple for long.

You get:

Spreads.

Merges.

Selectors.

Media queries.

Scopes.

Themes.

Tokens.

Custom transforms.

Runtime-known values.

Grouped CSS can still be useful, but the generated rule carries many authored decisions at once.

Atomic CSS flips that shape.

Instead of one generated rule trying to explain many source locations, each generated rule can focus on one authored styling decision.

.generated-background-color

→ backgroundColor source location

.generated-padding-inline

→ paddingInline source location

.generated-hover-background-color

→ backgroundColor inside .hover(...)

That is the debugging advantage I think people do not talk about enough.

Atomic CSS fragments the output.

But that same fragmentation can make source tracing more precise.

The Hidden Problem With Dedupe

There is one catch.

Atomic CSS is great at dedupe because the same CSS property/value can appear in many places.

For example:

const card = style({
  color: '#0f172a',
});

const title = style({
  color: '#0f172a',
});

Both produce the same CSS idea:

color: #0f172a

For production, sharing one generated rule is great.

If the same atomic rule appears in many places, Fluentic can emit that CSS rule once in the final CSS and reuse the generated class wherever it is needed.

But development has a different goal.

When I inspect a generated class in DevTools, I do not only want to know:

This is color: #0f172a.

I want to know:

Where in my source code is this color: #0f172a declared?

Was it the card?

Was it the title?

Was it a shared helper?

Was it a scope override?

Was it produced by a transform?

That is the tension:

Production wants global dedupe.

Debugging wants callsite precision.

So Fluentic treats development and production differently.

In development, the generated class identity includes callsite-local information.

That means two identical CSS property/value pairs from different style callsites can still get different debug classes and different sourcemap targets.

Conceptually:

Development:

color: #0f172a at card.styles.ts:10

→ color-card-a1b2c3

→ sourcemap to card.styles.ts:10

color: #0f172a at title.styles.ts:20

→ color-title-d4e5f6

→ sourcemap to title.styles.ts:20

That is less deduped in development, but it makes DevTools much more trustworthy.

Production does not use that callsite-local behavior.

In production, if the same atomic rule appears in many places, Fluentic emits the CSS rule once and reuses it wherever that same rule is needed.

Conceptually:

Production:

color: #0f172a

→ one generated atomic rule

→ reused by every matching style

That tradeoff matters.

If development used only globally deduped atomic classes, sourcemaps would have to pick one source location for a rule that may have come from many authored places.

That would make the debugging experience feel random.

So Fluentic uses callsite-local identity in development for better source tracing, and production identity for global dedupe.

Development: optimize for precise debugging.

Production: optimize for extracted CSS and global dedupe.

Same styling model.

Different identity goals.

A Fluentic Atomic Rule Is More Than CSS Text

For Fluentic, an atomic rule is not only the CSS string the browser receives.

It can also carry identity:

Rule key.

CSS text.

Property/debug field.

Selector or media context.

Priority.

Callsite/source URL.

Debug metadata.

A simplified mental model looks like this:

{
  key: "...",
  css: ".background-color-abc { background-color: #2563eb }",
  debugField: "backgroundColor",
  priority: "...",
  callsite: {
    filePath: "button.styles.ts",
    line: 12,
    column: 3
  }
}

The browser uses the CSS.

DevTools and Fluentic’s development tooling use the identity.

That identity lets a generated rule answer questions like:

Which property produced me?

Which chain context am I in?

Which source file should DevTools open?

Which priority bucket do I belong to?

Was I produced from a slot or scope?

Was I an element marker rule?

Without that identity, atomic CSS is just a pile of tiny classes.

With that identity, each rule becomes a handle back to the authored style.

That is the difference.

Selector Context Has To Survive Too

A property name alone is not enough.

This style uses the same property three times:

const button = style({
  backgroundColor: '#2563eb',
}).hover({
  backgroundColor: '#1d4ed8',
}).active({
  backgroundColor: '#1e40af',
});

Those are three different authored decisions.

They produce different CSS contexts:

Base backgroundColor.

Hover backgroundColor.

Active backgroundColor.

A useful debugger should not collapse those together.

A generated base rule should trace to the base backgroundColor.

A generated hover rule should trace to the backgroundColor inside .hover(...).

A generated active rule should trace to the backgroundColor inside .active(...).

This is why Fluentic style chains produce structured style data before CSS.

The chain call is part of the identity.

Style property

selector/media chain context → generated atomic rule → source trace

That is much more useful than:

This came from the button style somewhere.

I want the generated CSS to tell me exactly which part of the style chain produced it.

Priority Is Part Of Debugging Too

Finding the source is only half of debugging CSS.

The other half is understanding why a rule won.

In a real component system, the same CSS property can come from many places:

Base style.

Hover state.

Active state.

Media query.

Scope override.

Theme override.

Parent-provided style.

Weighted value.

Layer.

Fluentic needs to decide which generated rule wins without depending on random insertion order.

So generated rules carry priority information.

That priority can account for things like:

Selector context.

Scope context.

Media context.

Property order.

Value weight.

Layer.

This matters in DevTools.

When I inspect a generated rule, I do not only care where it came from.

I also care why it is taking effect.

Atomic CSS gives Fluentic small units to sort, layer, dedupe, and inspect.

The output is not just:

Many tiny classes.

It is:

Many tiny rules with known identity and priority.

That is much more debuggable.

Slots And Scopes Need Source Identity Too

Root element styles are only the beginning.

Reusable components usually have parts:

const cardStyles = {
  root: style.slot({
    padding: 16,
    backgroundColor: '#ffffff',
  }),

  title: style.slot({
    fontWeight: 700,
    color: '#0f172a',
  }),

  body: style.slot({
    color: '#475569',
  }),
};

Then outside styles can target those parts:

const danger = style.scope([
  cardStyles.root({
    borderColor: '#dc2626',
  }),

  cardStyles.title({
    color: '#dc2626',
  }),
]);

Eventually this becomes generated CSS.

But the authored decisions are different:

Card root base background.

Card title base color.

Danger scope root border.

Danger scope title color.

If the title is red in the browser, I want to know:

Was this title base style?

Was this danger scope?

Which slot was targeted?

Which style call produced the rule?

Atomic output should not erase those identities.

So Fluentic’s rule identity has to work with component concepts too.

Not only CSS property names.

That is why slots and scopes are part of the style data model. They are not just helper functions that disappear before debugging.

Debug Class Names Help, But They Are Not Enough

Readable generated class names can help.

A class like this is nicer:

.background-color-blue-abc

than this:

.a1b2c3

But class names should not carry the whole debugging burden.

Names can get long.

Names can be compressed or changed by production output.

Names can only describe so much.

For Fluentic, debug class names are hints.

Sourcemaps and debug metadata are the real debugging path.

Debug class name helps you recognize the rule.

Sourcemap/debug metadata helps DevTools take you to the source.

Atomic CSS makes this especially useful because the generated rule is already small enough to point at one authored property in one styling context.

That is the thing I wanted.

Not just readable generated CSS.

Clickable generated CSS.

Atomic CSS Is Output, Not The Authoring Model

This is an important distinction.

Fluentic does not ask you to author atomic classes by hand.

You can write style chains:

const button = style({
  display: 'inline-flex',
  alignItems: 'center',
  paddingInline: 16,
}).hover({
  backgroundColor: '#1d4ed8',
});

You can write Tailwind-like class-name chains:

const button = cx('inline-flex', 'items-center', 'px-4')
  .hover('bg-blue-700');

You can even define custom style dialects:

const button = ui({
  row: true,
  center: true,
  gapX: 8,
});

Atomic CSS is the output format.

Not the authoring model.

That is why Fluentic can keep higher-level concepts like:

Style chains.

Slots.

Scopes.

Tokens.

Themes.

Runtime-known values.

Debug metadata.

and still emit atomic CSS underneath.

The user gets a higher-level styling API.

The browser gets small CSS rules.

DevTools gets source traces.

That is the intended triangle.

Dev And Prod Use Atomic CSS Differently

Fluentic emits atomic CSS in both development and production, but the goals are different.

In development, the atomic rules carry extra debugging help:

Readable debug names.

Callsite-local identities.

Sourcemap callsites.

Debug fields.

Element marker rules.

Priority inspection.

StyleDevUtils controls.

In production, the output is prepared for the app:

Extracted CSS.

Globally deduped atomic rules.

Prepared JavaScript output.

Runtime support for runtime-known values.

Same basic rule model.

Different delivery mode.

That was important to me.

I did not want one styling system for development and a completely different styling system for production.

If development output is atomic and production output is atomic, the mental model stays closer.

But development and production do not need the same identity strategy.

Development needs precise source tracing.

Production needs extracted CSS and global dedupe.

Why This Made Debugging Feel Possible

Before building this, I mostly thought about atomic CSS in the usual way:

Dedupe.

Reuse.

Small output.

Fast insertion.

Those are real benefits.

But Fluentic made me care about another benefit:

One generated rule can map to one authored styling decision.

That is the debug story.

If generated CSS is grouped too coarsely, sourcemaps have to explain too much at once.

If generated CSS is atomic, the source trace can be much more direct.

One CSS property/value.

One generated atomic rule.

One source location.

Of course, real styling has more context than that.

Selectors, media queries, scopes, themes, spreads, merges, runtime values, and duplicated declarations all make the system more complicated.

But atomic CSS gives the debugging model a clean base unit.

That is why I think atomic CSS is not only a performance or output-size choice.

It can also be a debugging choice.

The Tradeoff

The tradeoff is still real.

Atomic CSS can make HTML noisier.

It can make generated stylesheets less pleasant to read by hand.

It can feel strange if you expect one component class to describe the whole component.

I accept that cost because Fluentic is not trying to make generated HTML the main debugging interface.

The generated class is a handle.

The sourcemap is the path back to source.

The browser DevTools should become useful again.

That is the bet.

The Result

For Fluentic, atomic CSS is not just:

Smaller generated CSS.

It is also:

A precise source-tracing unit.

A dedupe unit.

A priority unit.

A runtime insertion unit.

A production extraction unit.

That is the anatomy I care about.

The rule is tiny, but it carries enough identity to stay useful.

That is what makes Fluentic’s generated CSS debuggable.

Not because every class name is beautiful.

But because every generated rule can know what authored decision produced it.

Fluentic Style is still new and currently in beta. I am looking for early users to try it in real React, Next.js, Preact, Solid, and component-library codebases.

Useful links:

Feedback would help a lot right now, especially around generated CSS inspection, atomic output, sourcemaps, rule priority, and whether this debugging model matches how you inspect real UI.

Building Fluentic Style: Bringing the `css` Prop to SolidJS

OmniDev — Mon, 17 Aug 2026 04:15:29 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

Fluentic started as a styling model I was exploring for React web apps.

The shape was inspired by the style composition I liked from React Native:

<View style={[base, active && activeStyle, props.style]} />

For web JSX, that became:

<div css={[base, active && activeStyle, props.css]} />

But as Fluentic grew, the architecture became less tied to React itself.

Most of Fluentic lives in plain TypeScript:

style(...)
style chains
style.slot(...)
style.scope(...)
combineStyle(...)
tokens
themes
custom transforms
debug metadata
production extraction

Those pieces do not really care whether the final app is React, Solid, Preact, or another JSX framework.

The framework-specific part is much smaller.

It happens at the point where a style value is attached to a real DOM element.

In Fluentic, that boundary is the css prop:

Fluentic style data
  -> css prop
  -> framework-specific class/style output

That made me ask a different question:

Can Fluentic keep the same styling model,
but adapt the final css prop handoff for other JSX frameworks?

SolidJS became the first real test of that idea.

Docs:

The Feature

The user-facing goal is simple.

I wanted this to work in SolidJS:

import { style } from '@fluentic/style';

const card = style({
  padding: 16,
  borderRadius: 8,
  backgroundColor: '#ffffff',
}).hover({
  boxShadow: '0 12px 30px rgb(15 23 42 / 0.16)',
});

export function App() {
  return <div css={card}>Styled by Fluentic.</div>;
}

That gives Solid apps the same Fluentic authoring model:

typed style objects
chain methods for states and media
css prop composition
component slots
scopes
tokens and themes
custom style dialects
debug tooling
production CSS extraction

So this is not only about adding another way to set class.

The interesting part is bringing Fluentic’s style data model to Solid DOM elements.

Why Solid Needed A Different Path

In React, Fluentic can use a custom JSX runtime.

A React app can configure:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@fluentic/style/jsx"
  }
}

For plugin builds, React can use:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@fluentic/style/plugin/jsx"
  }
}

That fits React’s automatic JSX runtime nicely.

So the first tempting thought was:

React uses a Fluentic JSX runtime.
Maybe Solid needs a Fluentic JSX runtime too?

But SolidJS is not React with a different import.

Solid has its own compiler path. In a Vite app, Solid usually goes through vite-plugin-solid, and the official TypeScript setup keeps JSX preserved for Solid’s compiler:

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "solid-js",
    "types": ["vite/client"]
  }
}

That jsxImportSource points to solid-js.

I did not want Fluentic support to mean replacing that path with a Fluentic one and hoping everything still behaves like Solid.

The safer shape was:

Let Solid compile Solid JSX.
Let Fluentic handle only css={...}.

The Small Transform

The Solid integration uses the Fluentic Vite plugin before vite-plugin-solid:

import { CssPropPresets, plugin as stylePlugin } from '@fluentic/style/plugin/vite';
import { defineConfig } from 'vite';
import solid from 'vite-plugin-solid';

export default defineConfig({
  plugins: [
    stylePlugin({
      cssProp: CssPropPresets.Solid,
    }),
    solid(),
  ],
});

The order matters.

your TSX
  -> Fluentic sees css={...} while it is still JSX
  -> Fluentic rewrites css on DOM JSX elements
  -> vite-plugin-solid compiles the remaining Solid JSX

Solid still handles Solid JSX.

Fluentic only handles the styling handoff.

That is the whole integration idea.

What Gets Rewritten

Solid DOM elements use class, not React’s className.

So CssPropPresets.Solid tells Fluentic:

class prop -> "class"
style prop -> "style"
style mode -> "solid"
adapter    -> "@fluentic/style/adapter/solid"

If you write:

<div
  {...props}
  class="base"
  style={styleObj}
  css={styles.root}
  data-id="x"
/>

Fluentic rewrites that DOM JSX element before Solid compiles it.

Conceptually, it becomes something like this:

import { mergeJsxProps as _fluenticMergeJsxProps } from '@fluentic/style/adapter/solid';

<div
  {..._fluenticMergeJsxProps([
    props,
    {
      class: 'base',
      style: styleObj,
      css: styles.root,
      'data-id': 'x',
    },
  ])}
/>

The exact generated code can change, but the shape is the point.

Fluentic gathers the props that need merging, then passes them to the Solid adapter.

The adapter resolves the Fluentic style value and returns normal Solid-compatible props:

existing spread props
existing class
existing style
Fluentic css prop
other DOM props
  -> Solid adapter
  -> class/style props Solid understands

So this authoring code:

<div class="base" style={styleObj} css={styles.root} />

behaves like:

base class
+ Fluentic generated class
+ existing style object
+ runtime style output if Fluentic needs it

Solid does not need to understand Fluentic style data.

By the time Solid compiles the JSX, the DOM element has already been adapted back into the prop shape Solid expects.

A Real Before And After

Here is a small Solid component:

import { style } from '@fluentic/style';

const styles = {
  root: style({
    color: 'red',
  }).hover({
    color: 'blue',
  }),
};

export function View(props: { active?: boolean }) {
  const localStyle = {
    opacity: props.active ? 1 : 0.6,
  };

  return (
    <div
      {...props}
      class="base"
      style={localStyle}
      css={styles.root}
      data-view="root"
    />
  );
}

Before vite-plugin-solid compiles the JSX, Fluentic rewrites the DOM element with css={...}.

Conceptually:

import { mergeJsxProps as _fluenticMergeJsxProps } from '@fluentic/style/adapter/solid';
import { style } from '@fluentic/style';

const styles = {
  root: style({
    color: 'red',
  }).hover({
    color: 'blue',
  }),
};

export function View(props: { active?: boolean }) {
  const localStyle = {
    opacity: props.active ? 1 : 0.6,
  };

  return (
    <div
      {..._fluenticMergeJsxProps([
        props,
        {
          class: 'base',
          style: localStyle,
          css: styles.root,
          'data-view': 'root',
        },
      ])}
    />
  );
}

Then Solid compiles the JSX normally.

That is the key.

Fluentic does not need to own Solid’s JSX runtime.

It only needs to remove css={...} from the DOM handoff and turn it into class and style.

Why Not Just Set `class`?

Because css={...} is not just another spelling for class.

A class helper can do this:

<div class={someClassName} />

That is useful, but Fluentic’s css prop carries structured style data.

It can carry conditional style arrays:

<div css={[base, active && selected]} />

It can carry style chains:

const item = style({
  color: '#334155',
}).hover({
  color: '#0f172a',
});

It can carry component parts:

const listStyles = {
  root: style.slot({
    display: 'grid',
    gap: 8,
  }),

  item: style.slot({
    padding: 8,
  }),
};

And it can carry outside styles for those parts:

const compact = style.scope([
  listStyles.root({
    gap: 4,
  }),

  listStyles.item({
    padding: 6,
  }),
]);

It can also participate in production extraction and development debugging.

So the css prop is the place where Fluentic’s style model attaches to a DOM element.

That is why the transform matters.

Why Only DOM JSX Elements?

Fluentic rewrites css={...} on DOM JSX elements:

<div css={styles.root} />
<section css={styles.card} />
<button css={styles.button} />

But it leaves custom component calls alone:

<Button css={styles.root} />

That is deliberate.

A custom component is someone else’s API.

Maybe it accepts css.

Maybe it forwards it.

Maybe it maps it to slots.

Maybe it ignores it.

Fluentic should not guess.

So the boundary stays clear:

DOM JSX element
  -> compile css prop to class/style

custom component
  -> leave css prop alone as component API

This keeps the Solid integration small and predictable.

Fluentic adapts the DOM handoff.

It does not try to understand every Solid component.

Existing `class`, `style`, And Spreads Still Matter

A css prop transform cannot just replace class and style.

Solid code already uses them:

<div
  {...props}
  class={props.active ? 'is-active' : 'is-idle'}
  style={{
    opacity: props.active ? 1 : 0.5,
  }}
  css={styles.root}
/>

A spread can already contain class, style, event handlers, data attributes, or anything else.

So the transform cannot be as naive as:

<div class={getClassName(styles.root).className} />

The actual job is:

preserve normal JSX props
resolve css into class/style
merge existing class with Fluentic class
merge existing style with Fluentic runtime style
leave unrelated props alone

That is why the adapter exists.

The css prop looks small when you write it, but the framework handoff needs to be careful.

Why This Feels Right For Solid

The TypeScript setup stays Solid-shaped:

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "solid-js",
    "types": ["vite/client"]
  }
}

The plugin order tells the story:

Fluentic handles css={...}
Solid handles Solid JSX

And the styling model stays Fluentic:

style(...)
style chains
style.slot(...)
style.scope(...)
combineStyle(...)
tokens
themes
custom transforms
class-name chains
debug utilities
production extraction

Only the final handoff changed.

For React, that handoff can happen through a Fluentic JSX runtime.

For Solid, it happens through a css prop transform before vite-plugin-solid.

For Preact, another compiler config preset can adapt to its prop shape.

The common idea is:

Fluentic owns the style data.
The framework owns rendering.
The adapter translates at the DOM prop boundary.

That is the part that made this integration feel bigger than Solid alone.

If another JSX-based framework has a clear DOM prop shape, Fluentic may not need to become that framework.

It may only need to adapt the css prop at the right boundary.

A More Flexible JSX Integration

The SolidJS work also made Fluentic’s JSX integration more flexible in general.

Before this, React mostly used Fluentic through the JSX runtime setup.

That still works, and it is still a good option when you want Fluentic to handle the css prop through jsxImportSource:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@fluentic/style/plugin/jsx"
  }
}

But the Solid integration proved another setup can work too:

keep the framework's normal JSX setup
let Fluentic transform css={...} on DOM JSX elements
send the props through a framework adapter
let the framework compiler/runtime do the rest

That option is now available for React too.

So if a React app does not want to use Fluentic’s custom JSX runtime, or it already needs another JSX runtime setup, it can use the cssProp transform instead:

import { CssPropPresets, plugin as stylePlugin } from '@fluentic/style/plugin/vite';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    stylePlugin({
      cssProp: CssPropPresets.React,
    }),
    react(),
  ],
});

In that setup, React keeps its normal JSX runtime.

Fluentic only compiles the css prop on DOM JSX elements and routes the result through the React adapter.

So React now has two integration options:

Fluentic JSX runtime
  -> useful when you want css prop support through jsxImportSource

cssProp compiler transform
  -> useful when you want to keep the framework's normal JSX setup

The same adapter idea is what makes Solid support possible.

It also gives Fluentic a cleaner route for other JSX frameworks.

The built-in compiler config presets currently cover:

CssPropPresets.React
CssPropPresets.Preact
CssPropPresets.Solid

And if another JSX framework needs a different DOM prop shape, Fluentic can use a custom adapter.

A custom adapter exports mergeJsxProps, and the compiler routes transformed JSX props through it.

Docs:

This is the part that makes the Solid work feel important beyond Solid.

It pushed Fluentic toward a styling core that can stay stable while the JSX bridge adapts per framework.

Development And Production

Solid apps can enable Fluentic dev utilities before rendering:

import { enableStyleDevUtils } from '@fluentic/style/dev';
import { render } from 'solid-js/web';
import { App } from './App';

if (import.meta.env.DEV) {
  enableStyleDevUtils();
}

render(() => <App />, document.getElementById('root')!);

This adds the browser-side helpers Fluentic uses for development inspection: checking generated style usage, switching sourcemap tracing mode, and toggling element markers.

The practical benefit is that generated CSS stays easier to debug. You can inspect what Fluentic generated, trace rules back toward the authored style code, and turn DOM element markers on when you need to see which JSX element produced a generated class.

More details:

The same compiler path can also participate in production extraction.

That matters because I did not want Solid support to mean “runtime-only mode forever.”

The app still writes Fluentic style chains.

The production build can still emit extracted CSS and prepared JavaScript output.

Runtime-known choices can still resolve through Fluentic’s runtime.

So Solid support is not only:

make css prop work visually

It is also:

make css prop fit the same Fluentic extraction/debug/runtime path

Current Scope

One important note: the current SolidJS support is for client-side Solid apps.

That means a Vite + Solid app can use Fluentic’s css prop transform, style chains, slots, scopes, themes, development utilities, and production extraction.

SolidStart and Solid SSR are not something I have properly tested yet.

They will likely need more dedicated integration work. SSR support is a different problem from client-side Solid because it needs a bridge for server-rendered styles, hydration, streamed output, and development debugging.

So for now, I want to describe the current support clearly: Vite + client-side Solid first.

For React, Fluentic already has a deeper Next.js App Router integration covering server/client development, RSC, HMR, sourcemaps, and production extraction. I wrote about that here:

Building Fluentic Style: Making CSS Debugging Work Across Next.js Server and Client

The goal is to bring the same level of seriousness to Solid SSR later, but the current Solid support should be read as client-side Solid support first.

The Result

SolidJS support is small on purpose.

That is what I like about it.

It does not replace Solid’s JSX setup.

It does not ask Solid users to pretend they are writing React.

It does not fork Fluentic’s style model.

It just transforms the one thing Fluentic owns:

css={...}

and lets Solid keep doing the rest.

That boundary is enough to bring Fluentic style chains, slots, scopes, themes, debugging, and extraction into Solid apps.

Fluentic Style is still new and currently in beta. I am looking for early users to try it in real SolidJS, React, Next.js, Preact, and component-library codebases.

Useful links:

Feedback would help a lot right now, especially from SolidJS users. I would love to know whether this css prop transform feels natural in real Solid apps, and what styling patterns people want beyond Tailwind-style utility classes.

Building Fluentic Style: CSS Rule Order Should Not Feel Like Astrology

OmniDev — Thu, 06 Aug 2026 01:01:49 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

Atomic CSS gives you a nice primitive:

one CSS property/value
one generated rule
one reusable class

That is great for dedupe.

If two places produce the same atomic rule, the final CSS can emit that rule once and reuse it wherever needed.

But dedupe is not the whole story.

At some point, two generated rules are both valid, both target the same CSS property, and both match the element.

Then the question is not:

can we reuse this rule?

The question is:

which rule should win?

And that is where CSS rule order can start feeling like astrology.

Docs related to this topic:

The Simple Case Is Easy

This is easy:

const button = style({
  backgroundColor: '#2563eb',
  color: '#ffffff',
});

There is only one value for each property.

No state.

No media.

No theme.

No parent override.

No component scope.

Atomic CSS works nicely here.

backgroundColor: #2563eb
  -> one generated background-color rule

color: #ffffff
  -> one generated color rule

Dedupe can help if the same values appear elsewhere.

Nothing weird yet.

Then States Start Fighting

Now add hover and active:

const button = style({
  backgroundColor: '#2563eb',
}).hover({
  backgroundColor: '#1d4ed8',
}).active({
  backgroundColor: '#1e40af',
});

When the button is only hovered, hover should win.

When the button is active, active should usually win over hover.

Both selectors can match at the same time.

:hover
:active

Atomic dedupe does not answer this.

The rules are different:

:hover background-color
:active background-color

The question is order.

Should active come after hover?

Should disabled come after active?

Should focus-visible beat hover?

For common states, Fluentic’s default style builder has a priority order.

Conceptually:

link -> visited -> hover -> focusWithin -> focus -> focusVisible -> active -> disabled

Later states win earlier states when they target the same property.

So by default, active wins over hover, and disabled sits above the common interaction states.

That is not magic.

It is a convention encoded into the selector priority model.

Semantic States Make This More Important

Pseudo-classes are only the start.

Design systems often have semantic states:

pressed
selected
expanded
open
invalid
current
danger

Those states usually map to selectors:

[aria-pressed="true"]
[aria-selected="true"]
[data-state="open"]
[data-tone="danger"]

And those states need an order too.

For example:

const tab = ui({
  color: '#475569',
}).hover({
  color: '#0f172a',
}).selected({
  color: '#2563eb',
});

If a selected tab is also hovered, which color should win?

A lot of CSS systems leave that answer to whatever rule was generated later.

That can work for a while.

But in a component library, source order becomes harder to trust:

rules can come from different files
variants can compose conditionally
themes can add overrides
scopes can target component parts
runtime-known values can appear later
extraction can reorder output for dedupe

I do not want the answer to be:

whichever one happened to be inserted last

For design-system states, I want the priority to be explicit.

Custom Selector Priority

Fluentic lets a custom style builder define its own selector methods and priority order.

import { createStyleFn, type CSSProperties, type } from '@fluentic/style';
import { selector, selectorPriority } from '@fluentic/style/selector';

const selectors = {
  hover: selector(':hover'),
  focusVisible: selector(':focus-visible'),
  active: selector(':active'),
  pressed: selector('[aria-pressed="true"]'),
  selected: selector('[aria-selected="true"]'),
  disabled: selector(':disabled'),
};

const prioritySelectors = selectorPriority(selectors, [
  'hover',
  'focusVisible',
  'active',
  'pressed',
  'selected',
  'disabled',
]);

export const { style: ui } = createStyleFn({
  style: type<CSSProperties>,
  selectors: prioritySelectors,
});

The list is ordered from lower priority to higher priority.

So in this builder:

focusVisible beats hover
active beats focusVisible
pressed beats active
selected beats pressed
disabled beats selected

Then component code can read like the design system:

const trigger = ui({
  color: '#475569',
}).hover({
  color: '#0f172a',
}).pressed({
  color: '#334155',
}).selected({
  color: '#2563eb',
}).disabled({
  color: '#94a3b8',
});

The important part is not that Fluentic picked one perfect universal order.

There is no universal order.

The important part is that a design system can define the order once, then every component using that builder follows it.

That gives more confidence than relying on accidental source order.

Priority Is Not A Single Flat Number

When I first thought about rule order, it was tempting to imagine a single score:

base = 0
hover = 10
active = 20
disabled = 30

But real styling does not stay that simple.

A rule can be inside a media query.

A rule can come from a scope.

A rule can target a child slot while a parent is hovered.

A value can be intentionally weighted.

A longhand property can refine a shorthand property.

So Fluentic uses buckets instead of one flat score.

The practical order is nested:

value weight
  direct selector bucket
    parent selector bucket
      media bucket
        property bucket

Lower buckets are emitted first.

Higher buckets win later in the cascade.

That sounds abstract, so let’s unpack it.

Base, Media, And State Are Different Buckets

Consider this:

const button = style({
  color: 'black',
}).media('(max-width: 700px)', {
  color: 'blue',
}).hover({
  color: 'red',
});

At a small width, the media rule can override the base color.

So blue beats black.

But when the button is hovered, should base media beat hover?

Usually no.

Hover is a state rule.

So while hovered, red should still win.

base color: black
base media color: blue
hover color: red

At small width and hovered:

red wins

If you want hover to change at that breakpoint, write that case in the same state context:

const button = style({
  color: 'black',
}).hover({
  color: 'red',
}).media(
  '(max-width: 700px)',
  style({
    color: 'blue',
  }).hover({
    color: 'purple',
  }),
);

Now there is a hover rule inside the media context.

At small width and hovered:

purple wins

That is more explicit.

Media does not jump over every selector just because it appeared later.

It wins inside its context.

Parent State And Direct State Are Different Too

Component scopes make this even more interesting.

Imagine a card with a button slot:

const card = {
  button: style.slot({
    color: 'black',
  }).active({
    color: 'red',
  }),
};

Now a parent hover scope wants to change the button:

const cardHover = style.scope().hover([
  card.button({
    color: 'blue',
  }),
]);

This means:

when the card scope is hovered, make the button blue

But the button itself also has an active state:

when the button is active, make it red

If the card is hovered and the button is active, what should win?

Fluentic treats these as different contexts:

parent selector -> button color blue
direct selector -> button color red

The direct button active state should not be accidentally crossed by an unrelated parent hover override.

So red can still win.

If the design really wants the card-hover + button-active case to win, write that case directly:

const cardHoverButtonActive = style.scope().hover([
  card.button().active({
    color: 'purple',
  }),
]);

Now the authored code says exactly what is happening:

when the card is hovered
and the button is active
make the button purple

That is much easier to trust than hoping a generated CSS order happens to line up.

Value Weight Is The Escape Hatch

Sometimes a design-system rule needs to sit above normal selector and media behavior.

For that, Fluentic has value weight:

const button = style({
  color: style.weight('#111827', 1),
}).hover({
  color: '#2563eb',
});

Here the weighted base color can beat the unweighted hover color.

That is not something I expect most app code to use often.

It is an escape hatch for design-system authors.

The rule is:

use normal composition first
use selector priority for state conventions
use value weight only when a rule intentionally needs to sit above normal behavior

I like having this escape hatch because it is explicit.

If a value is unusually strong, the source code says so.

No mystery specificity trick.

No random !important.

No hoping a file loads later.

Property Order Still Matters

CSS has shorthand and longhand relationships.

This should work:

const box = style({
  margin: 4,
  marginTop: 8,
});

marginTop should refine margin.

So property order is part of the bucket model too.

Longhands can be emitted after shorthands they refine.

That is a small detail, but it matters if the generated CSS is atomic.

Because margin and margin-top are separate generated rules.

Atomic output makes this explicit:

margin
margin-top

The rule order still has to preserve CSS expectations.

Layers Or Sorted Output In Development

During development, rule order is also something you may want to inspect.

Fluentic dev utilities can switch priority output:

StyleDevUtils.setPriorityMode.toLayer();
StyleDevUtils.setPriorityMode.toSort();

Layer mode makes priority buckets easier to see.

Sort mode is closer to compact generated output.

That is useful because debugging order problems is not only about the final winner.

Sometimes I want to understand the buckets themselves.

which bucket is this rule in?
why did this one appear later?
is this scope context or direct selector context?

Making that visible helps rule order feel less mysterious.

Dedupe Is Good, But Confidence Needs Order

Atomic dedupe answers one kind of question:

can identical rules share output?

Priority answers a different question:

when multiple rules match, which one wins?

Both matter.

If you only optimize for dedupe, rule order can become a side effect of the implementation.

If you only rely on CSS source order, component composition can become fragile as the app grows.

Fluentic tries to make rule order follow the structure of the authored style:

value weight
selector context
scope context
media context
property relationship

The generated CSS still uses the normal cascade.

But the ordering model comes from the style data, not from vibes.

That is the important part for me.

Where This Leaves Fluentic

I do not want developers to tune priority all day.

Most app code should not think about this much.

You should write:

style({
  color: 'black',
}).hover({
  color: 'blue',
}).active({
  color: 'red',
});

and get the expected result.

But when a design system grows, the edge cases start to matter:

custom semantic states
component scopes
theme overrides
parent-provided styles
responsive variants
shorthand/longhand conflicts
escape hatches

That is where rule order should be predictable.

Not because Fluentic ignores CSS.

Because Fluentic uses CSS with a stable generated order.

That is the goal:

atomic CSS for dedupe
priority buckets for confidence
source structure for debugging

CSS rule order should not feel like astrology.

It should feel like something you can explain from the code you wrote.

Fluentic Style is still new and currently in beta. I am looking for early users to try it in real React, Next.js, Preact, Solid, and component-library codebases.

Useful links:

Feedback would help a lot right now, especially around selector priority, component scopes, media behavior, generated CSS order, and whether this priority model matches the way you expect component styles to override each other.

Building Fluentic Style: Making CSS Debugging Work Across Next.js Server and Client

OmniDev — Sun, 02 Aug 2026 03:25:54 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

It is one thing to make a styling library feel good in a client-side app.

It is another thing to make it feel good in Next.js App Router.

In a simple SPA-style development setup, most of the styling loop lives in one place:

component renders in the browser
Fluentic style chain resolves
atomic CSS rule is inserted
DevTools can inspect the generated rule
sourcemap points back to authored code

That is already a lot of work.

But at least the browser is the main place where the style is produced and consumed.

Next.js App Router changes the shape of the problem.

Now the page can involve:

server rendering
React Server Components
client components
streamed HTML
hydration
client-side navigation
HMR
Webpack or Turbopack
development sourcemaps
production extraction

So the hard part is not just “can Fluentic run in Next.js?”

The hard part is:

Can Fluentic keep the same CSS debugging experience when styles cross the server/client boundary?

That is what this post is about.

Docs for the Next.js integration are here:

The Goal Was Not A Special Next.js API

I did not want Fluentic to have one mental model for client apps and another one for Next.js.

This should still be normal Fluentic:

const card = style({
  padding: 16,
  borderRadius: 12,
}).hover({
  boxShadow: '0 12px 30px rgb(15 23 42 / 0.16)',
});

export function Card() {
  return <section css={card}>Hello</section>;
}

And this should still be normal Fluentic too:

const buttonStyles = {
  root: style.slot({
    display: 'inline-flex',
    border: 0,
  }),

  label: style.slot({
    fontWeight: 700,
  }),
};

const danger = style.scope([
  buttonStyles.root({
    backgroundColor: '#dc2626',
  }),

  buttonStyles.label({
    color: '#ffffff',
  }),
]);

The Next.js integration should be an integration detail.

Not a styling API boundary.

That was the design goal:

client app:
  css prop
  atomic CSS
  HMR
  sourcemaps
  StyleDevUtils

Next.js App Router:
  same css prop
  same atomic CSS model
  same debug controls
  server/client bridge hidden by integration

Next.js Splits The Debugging Problem In Two

For Fluentic development in Next.js, I ended up thinking about the problem in two parts.

First:

initial server-rendered HTML should already have the CSS it needs

The page should not show unstyled HTML and wait for the client runtime to catch up.

No missing style flash.

No “it becomes correct after hydration.”

Second:

after the client JavaScript loads, the browser should pick up the debug metadata
and prepare the development stylesheet with proper sourcemap behavior

That is where DevTools tracing matters.

The generated CSS should still be inspectable. The rule should still lead back to the authored style property, chain call, slot, scope, or JSX css prop.

Those are two different jobs:

server job:
  make initial rendered HTML styled immediately

client job:
  collect debug payloads
  insert generated atomic rules into the dev stylesheet
  keep sourcemaps and DevTools tracing useful
  clean up temporary server-to-client attributes

A simple client-only runtime does not solve the first job.

A simple server-inserted style tag does not solve the second job.

Fluentic needs both.

Why RSC Makes This Awkward

React Server Components make this harder because the client cannot just “reach into” server component execution.

A server component can render HTML that already includes Fluentic style usage.

But the browser runtime is not running that server component.

So if the client runtime is the only place that knows how to insert development CSS, it may not know about styles that were produced on the server side.

And if the server only emits a style tag, the initial page can look right, but the client-side debug system may not have the structured rule metadata it needs for source tracing.

That creates a gap:

server knows what it rendered
client owns browser DevTools stylesheet
debug metadata needs to survive the trip

That is the real integration problem.

Some Simpler Approaches Are Not Enough

One approach is:

just inject a style tag from the server

That helps the initial render.

But App Router development does not stop at the initial render.

After the client is loaded, a user can navigate with next/link, trigger a route segment update, or receive new RSC output. That new server-produced output can contain elements with generated Fluentic class names that were not present on the first page.

So a one-time server style tag is not enough.

It can make the first HTML look correct, but it does not give the already-running client a reliable way to discover new server-produced style rules later.

Another approach is:

just let the client runtime regenerate everything

That can work in a pure client app.

But with RSC, the client does not execute the server component that produced the markup. The client may see DOM with generated class names, but it does not automatically have the original server-side style-chain execution that created those rules.

So the client cannot simply “rerun the component” to recover the missing debug CSS.

Another approach is:

write real CSS files during development

That may sound obvious, but it fights the smooth development loop I wanted. Fluentic development CSS is generated from JS/TS style chains with debug metadata, sourcemaps, element markers, rule priorities, and HMR-sensitive output. I wanted style edits to keep following the app/module update path instead of making every dev update depend on a separate CSS-file coordination layer.

So I ended up needing two cooperating paths.

One path runs during server rendering so the initial HTML arrives with the CSS it already needs.

The other path runs in the browser, watches for new server/RSC output, picks up its style metadata, and merges those rules into the development stylesheet.

That became the shape of Fluentic’s Next.js development bridge.

That covers both cases:

first HTML response
  -> seed CSS prevents missing styles on initial render

later RSC/navigation output
  -> DOM payload lets the running client discover and insert new rules

Part One: Seed CSS For The Initial HTML

The first job is avoiding missing styles on initial render.

In development, Fluentic collects the RSC/server-side style rules that were produced during server rendering.

Then the Next.js dev bridge can insert the changed CSS into the HTML using Next’s server insertion hook.

Conceptually:

server render
  -> Fluentic style usage produces atomic rules
  -> rules are collected in an RSC dev style store
  -> server insertion emits a development style tag
  -> initial HTML arrives with the CSS it needs

That is what prevents the initial page from waiting for the client runtime before it looks styled.

In Fluentic, this is handled by the development bridge component used in app/layout.tsx:

import { StyleDev } from '@fluentic/style/dev/rsc';
import type { ReactNode } from 'react';

import './globals.css';

export default function RootLayout(props: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>{props.children}</body>

      {process.env.NODE_ENV === 'development' && (
        <StyleDev enableStyleDevUtils />
      )}
    </html>
  );
}

On the server side, StyleDev uses useServerInsertedHTML.

It checks whether the collected RSC development CSS changed. If it did, it emits a development <style> tag into the server-rendered HTML.

That style tag is not the whole debugging system.

It is the initial seed.

Its job is:

make the server-rendered page appear styled immediately

Part Two: Send Debug Payloads Through The DOM

The second job is the more interesting one.

After the client JavaScript loads, Fluentic needs the browser-side development stylesheet to know about the rules that came from the server/RSC path.

That stylesheet is where the normal Fluentic dev behavior lives:

atomic rule insertion
dedupe
priority/layers
element marker rules
debug metadata
sourcemap callsites
StyleDevUtils controls

So Fluentic needs to move structured rule information from server-rendered output to the client.

The approach is deliberately simple:

put a development payload on the rendered DOM element
let the client observer pick it up
insert the missing rules into the dev stylesheet
remove the temporary attribute

In Fluentic, the dev attribute is:

data-css-dev

The JSX/runtime path used for RSC can attach this development payload to rendered elements.

That payload can include rule information such as:

rule key
CSS text
priority
callsite
debug data
debug field

This is the important part.

The client does not only receive “some CSS string.”

It receives enough structured information to insert the rule into Fluentic’s development sheet with the same debug behavior as client-side styles.

Part Three: The Client Observer Picks It Up

On the client side, Fluentic starts a MutationObserver.

The observer watches the document for elements with the development payload attribute:

data-css-dev

It handles two cases:

new elements are added
existing elements receive or change data-css-dev

When it finds pending elements, it schedules a flush.

During the flush, it:

reads the data-css-dev payload
parses the rule list
skips rules already inserted
inserts missing atomic rules into the global dev sheet
handles element marker rules
flushes the sheet
removes data-css-dev from the element
cleans up initial seed style/link elements when no longer needed

So the development flow becomes:

server/RSC output appears in DOM
  -> element carries data-css-dev
  -> client observer sees it
  -> Fluentic inserts missing dev rules
  -> DOM payload is cleaned up
  -> DevTools sees normal generated CSS with debug metadata

That is the bridge.

It turns server-rendered style usage into browser-side development stylesheet state.

Why A MutationObserver?

A useEffect that runs once is not enough.

In App Router development, the DOM can change after the initial client load.

RSC payloads can stream or update parts of the tree.

Client-side navigation with next/link can bring in new server-rendered route segments.

New server-produced elements can appear later with generated class names and matching debug payloads.

So the client bridge needs to react to the DOM changing, not just the app mounting.

A MutationObserver fits that job.

It lets Fluentic watch for new data-css-dev payloads without asking users to wrap every styled component or manually notify the runtime.

It also keeps the bridge development-only.

The payload attribute is temporary.

After the client reads it, Fluentic removes it from the DOM.

Why This Keeps HMR Smooth

One nice side effect of this design is that HMR can stay close to the normal JS/DOM development flow.

In development, Fluentic does not need every style edit to become a manually managed CSS file.

The app changes.

Next updates server/client output.

Server-rendered HTML can carry fresh development payloads.

The client observer picks them up.

The dev stylesheet updates.

That means HMR still feels like editing a normal React app:

edit TS/TSX style chain
Next refreshes the affected output
DOM receives updated dev payloads
Fluentic observer inserts updated atomic rules
DevTools sourcemaps still point back to source

There is machinery underneath, but the component author should not feel that machinery.

The point is to keep the smooth SPA-like development loop even when the app is no longer just a SPA.

Debug Metadata Survives The Server/Client Trip

This was the part I cared about most.

It is not enough for the visual CSS to work.

The generated CSS still needs to be debuggable.

The payload path preserves the information Fluentic needs:

callsite
source URL
source content when available
debug object
debug field
rule priority
rule key

That lets Fluentic insert development rules that can still point back to the authored source.

So a CSS rule produced through RSC development can still participate in the same debugging story:

generated atomic rule
  -> authored property
  -> chain call
  -> slot/scope
  -> JSX css prop marker

This is why Fluentic does not treat RSC dev CSS as “just HTML style text.”

The initial style tag makes the page look correct.

The structured payload lets the client-side debug stylesheet understand where the rules came from.

Those are different responsibilities.

Element Markers Still Work

Element markers are a good example of why the client pickup step matters.

In development, Fluentic can add a marker class to host elements that receive a css prop.

The marker rule points DevTools back to the JSX element where the css prop was attached.

In the RSC observer, element marker rules are handled specially.

If element markers are enabled, Fluentic inserts the marker rule.

If element markers are disabled, Fluentic can remove the marker class from the element.

That means the same debug control still works in Next.js App Router:

StyleDevUtils.setElementMarker.toOn();
StyleDevUtils.setElementMarker.toOff();

The user does not need a different debugging model because the element came from the server/RSC path.

StyleDevUtils Still Feels Like The Client App

Once StyleDev enables the dev utilities, the familiar console helper is available:

StyleDevUtils.info();
StyleDevUtils.usage();
StyleDevUtils.getConfig();

StyleDevUtils.setSourcemapMode.toStyle();
StyleDevUtils.setSourcemapMode.toValue();

StyleDevUtils.setElementMarker.toOn();
StyleDevUtils.setElementMarker.toOff();

StyleDevUtils.setPriorityMode.toLayer();
StyleDevUtils.setPriorityMode.toSort();

StyleDevUtils.reset();

This matters because the debugging surface should not split into:

client app debug tools
Next.js debug tools
RSC debug tools

The architecture is different.

The workflow should still feel like Fluentic.

You inspect generated CSS.

You follow sourcemaps.

You toggle element markers.

You change spread/merge trace mode.

You inspect priority output.

The server/client bridge should make that possible without becoming a second API.

The Next Plugin Wires The Build System Parts

The runtime bridge is only part of the integration.

The Next plugin also has to wire Fluentic into the build system paths Next uses internally.

User setup is small:

import stylePlugin from '@fluentic/style/plugin/nextjs';

const nextConfig = {
  // your Next config
};

export default stylePlugin(nextConfig);

And TypeScript uses the Fluentic JSX runtime entry:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@fluentic/style/plugin/jsx"
  }
}

Under the hood, the plugin handles:

Webpack path
Turbopack path
runtime entries
development CSS route
sourcemap sidecar
CSS cache
production CSS output
static export support

The plugin owns the Fluentic CSS entry in development and production.

So users keep normal app CSS imports in app/layout.tsx, but they do not manually import a Fluentic-generated CSS file.

That is important because Fluentic generated CSS is tied to compiler configuration, debug metadata, sourcemap behavior, runtime mode, and production output.

It should be managed by the integration.

Sourcemaps Need More Than CSS Text

At this point, the bridge can move CSS rules and debug metadata from server/RSC output to the client development stylesheet.

But sourcemaps add another problem.

For DevTools to let you click a generated CSS rule and jump back to the original TypeScript or TSX source, the sourcemap needs a source target.

One direct approach would be to include the original source content in the debug payload.

That works, but it is heavy.

If every server/RSC style payload had to carry source file contents, the HTML payload could get larger quickly. Generating sourcemaps would also become more expensive, because the bridge would be moving more than the rule metadata it actually needs for normal operation.

So Fluentic takes a lighter approach in the Next.js plugin.

In development, the Fluentic Next plugin starts a sidecar server alongside the Next.js dev server.

The generated Fluentic CSS can point its sourcemap source URLs at that sidecar server.

So instead of carrying the full original source content inside every dev payload, the rule only needs enough information to build a short source URL.

Conceptually:

generated CSS rule
  -> sourcemap source URL
  -> Fluentic sidecar server
  -> original TS/TSX source file

That keeps the RSC/debug payload smaller.

The payload can carry a file path and debug location information, while the original source text is served on demand by the sidecar when DevTools follows the sourcemap.

That was the tradeoff I wanted:

heavy path:
  put source contents inside every debug payload

lighter path:
  put source location in the payload
  serve original source through the sidecar when DevTools asks for it

This makes sourcemaps feel like normal DevTools sourcemaps without forcing every server-to-client style payload to carry full source files around.

Production Is A Different Mode

Development is about:

fast updates
server/client bridge
RSC payload pickup
debug metadata
sourcemaps
StyleDevUtils

Production is about:

CSS extraction
prepared JavaScript output
small runtime support
normal Next build output

For production, you run the normal Next build:

next build

The Fluentic plugin handles the production CSS path.

Fluentic style chains are compiled into extracted CSS and prepared JavaScript output.

Static export works through normal Next.js configuration too. You still pass the Next config object to stylePlugin(...); Fluentic wraps it, but output and trailingSlash are Next.js options:

import stylePlugin from '@fluentic/style/plugin/nextjs';

const nextConfig = {
  output: 'export',
  trailingSlash: true,
};

export default stylePlugin(nextConfig);

So the integration does not introduce a separate export mode. It follows the normal Next.js config shape.

That is separate from the development bridge.

The bridge exists for development-only problems: initial dev CSS, RSC payload pickup, HMR, debug metadata, sourcemaps, and DevTools controls.

Production has a different job: emit extracted CSS and prepared JavaScript output for the final Next build.

Runtime-Known Values Still Work

Next.js also makes it obvious why Fluentic cannot be only a static extractor.

Real app styling has values known at render time:

props
conditions
themes
scopes
component composition
runtime-selected variants

Fluentic’s production path extracts CSS from the style-chain structure and prepares style data for runtime composition.

At render time, the runtime can pick up runtime-known values, resolve selected scopes and themes, and attach the right generated classes.

That means the authoring API does not split when styles become dynamic.

It is still regular TypeScript.

You can branch, pass values around, compose scopes, and let the rendered app choose the final styling inputs.

That matters in Next.js because the app is not purely build-time and not purely client-time.

It is both.

Why This Was Hard To Get Right

The hard part was not one API call.

The hard part was keeping several promises true at the same time:

initial HTML should already be styled
client dev stylesheet should receive server/RSC rules
debug metadata should survive
sourcemaps should still point back to source
HMR should feel natural
client navigation should discover new server-produced styles
element markers should still work
Webpack and Turbopack both need integration paths
production should still extract CSS
runtime-known values should still compose

If any one of those is ignored, the integration can still “work” in a narrow sense.

But it would not be the experience I wanted.

A page could render, but flicker.

CSS could appear, but lose sourcemaps.

Initial load could work, but next/link navigation could introduce generated class names without matching dev rules.

Server styles could work, but client debugging could be vague.

Development could work, but production extraction could be a separate story.

I wanted the whole thing to feel coherent.

Why Not Stay SPA-Only?

It would have been much easier to keep Fluentic focused on client-side apps.

A lot of styling ideas look good there.

But modern React apps are not only SPAs.

Next.js App Router, RSC, server rendering, streaming, and hybrid server/client trees are normal now.

So for Fluentic, “works in the browser” was not enough.

I wanted:

works in client apps
works in Next.js App Router
works across server/client development
keeps generated CSS debuggable
keeps production extraction
keeps the same component styling model

A styling library does not need to support every framework in the universe.

But if it says it supports modern React, the Next.js story has to be real.

Not a footnote.

Where This Leaves The Integration

The key design decision was:

Do not make Next.js a separate styling model.
Make Next.js an integration path for the same styling model.

That is why the user-facing setup is small:

stylePlugin(nextConfig)
StyleDev in app/layout.tsx
same css prop
same StyleDevUtils

And the hard parts stay inside the integration:

server-inserted initial CSS
RSC dev style store
data-css-dev payloads
client MutationObserver pickup
rule dedupe
temporary DOM cleanup
element marker handling
sourcemap sidecar
Webpack/Turbopack wiring
production extraction

The component author should still feel like they are writing Fluentic.

Even in Next.js App Router.

What Comes Next

This post is the mechanism story.

There is still more I want to show later:

the exact generated development CSS shape
how RSC payload rules carry debug metadata
how element markers behave in App Router
how Webpack and Turbopack integration differ internally
how production extracted CSS is patched into Next output
how runtime-known values are represented in prepared style data

But the main idea is already there:

Next.js with server, client, and RSC is not the same problem as a SPA.

Fluentic should still keep CSS debuggable there.

That is the point of the Next.js integration.

Fluentic Style is still new and currently in beta. I am looking for early users to try it in real Next.js App Router, React, Preact, Solid, and component-library codebases.

Useful links:

Feedback would help a lot right now, especially around Next.js App Router, RSC development, Turbopack/Webpack behavior, HMR, sourcemaps, static export, and whether the debugging workflow feels smooth in real Next apps.

Building Fluentic Style: Making Generated CSS Debuggable Again

OmniDev — Sun, 02 Aug 2026 00:35:48 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

Generated CSS is not the problem.

Generated CSS that cannot explain where it came from is the problem.

That is one of the things I kept running into with styling tools over the years.

A library can have a nice authoring API. It can have good TypeScript support. It can emit atomic CSS. It can extract CSS in production. It can even give readable class names.

But eventually something looks wrong in the browser.

Then you inspect the element.

And the real question is not:

What CSS rule won?

The browser already tells you that.

The real question is:

Which authored styling decision produced this generated CSS rule?

That is the part I wanted Fluentic to care about from the beginning.

Docs for the debugging pieces are here:

Atomic CSS Should Not Sacrifice Sourcemaps

Fluentic emits atomic CSS in development and production.

I like atomic CSS output.

It dedupes repeated declarations. It gives small reusable rules. It makes priority and extraction easier to reason about. It works well with a compiler.

But atomic CSS also makes debugging easier to ruin.

One authored style can become many generated rules:

const button = style({
  display: 'inline-flex',
  alignItems: 'center',
  paddingInline: 16,
  paddingBlock: 8,
  backgroundColor: '#2563eb',
  color: '#ffffff',
}).hover({
  backgroundColor: '#1d4ed8',
});

The browser does not see “button style”.

It sees generated atomic CSS.

So if the hover background is wrong, a readable class name is not enough for me.

I do not only want to know “this came from something button-ish.”

I want the generated hover background-color rule to point back to the backgroundColor property inside the .hover(...) chain call.

That is the level of debugging I kept wanting.

generated hover background-color rule
  -> button.styles.ts
  -> .hover({ backgroundColor: '#1d4ed8' })

For the base rule:

generated background-color rule
  -> button.styles.ts
  -> backgroundColor: '#2563eb'

That is the difference between “search around this file” and “DevTools can take me to the authored decision.”

Atomic CSS is cool.

But it should not mean giving up precise sourcemaps.

Readable Names Are Helpful, But Not Enough

Some styling systems work around generated CSS by putting extra information into class names or generated CSS labels.

That can be useful.

A class name with a component name, file hint, or line hint is better than a hash with no context.

But readable names are still not the same as source-level debugging.

A label can tell you roughly where to look.

A sourcemap can take you to the exact property.

And styling bugs often need exactness.

If a file has many style objects, many spreads, many variants, and the same property repeated in base, hover, media, scope, and theme overrides, “somewhere near Button” is not enough.

I want DevTools to answer:

Which property?
Which chain call?
Which slot?
Which scope?
Which JSX element?
Which reusable value?

That was the bar I wanted for Fluentic.

Debugging Starts From The Browser

Most styling bugs start from the rendered page.

You see something wrong:

wrong color
wrong spacing
wrong hover state
wrong responsive rule
wrong override
wrong component part

Then you inspect the element.

At that point, Fluentic tries to keep several paths back to source.

wrong generated CSS rule?
  follow the rule sourcemap

wrong DOM element?
  follow the element marker

wrong spread or merge value?
  choose style trace or value trace

wrong component override?
  follow slot and scope identity

That is why debugging cannot be bolted on after everything becomes a string.

Fluentic APIs create structured style data first.

style()       -> element style identity
chain methods -> selector / media / merge identity
style.slot()  -> component part identity
style.scope() -> grouped override identity
tokens        -> shared value identity
css prop      -> rendered JSX element identity

That identity is useful for runtime composition.

It is useful for production CSS extraction.

And it is useful for development debugging.

Property-Level Sourcemaps

The first piece is property-level sourcemaps.

If this is the authored code:

const title = style({
  color: '#0f172a',
  fontWeight: 700,
}).hover({
  color: '#2563eb',
});

then the generated base color rule should trace to:

title.styles.ts
color: '#0f172a'

And the generated hover color rule should trace to:

title.styles.ts
.hover({ color: '#2563eb' })

Not just the file.

Not just the nearest style call.

The property is the useful target.

That matters because in real code, the same CSS property can appear many times:

const title = style({
  color: '#0f172a',
}).hover({
  color: '#2563eb',
}).focusVisible({
  color: '#1d4ed8',
}).media('(max-width: 700px)', {
  color: '#334155',
});

If DevTools only points to the top of the style object, I still have to guess.

If the generated rule points to the property in the right chain context, the browser already did most of the work.

Chain Calls Need Their Own Context

A style chain is not only an object.

The same property inside different chain calls means different things.

const button = style({
  backgroundColor: '#2563eb',
}).hover({
  backgroundColor: '#1d4ed8',
}).active({
  backgroundColor: '#1e40af',
});

There are three backgroundColor values here.

They should not all debug the same way.

base backgroundColor
hover backgroundColor
active backgroundColor

When the active rule wins, I want to land on the active property.

When the hover rule wins, I want to land on the hover property.

This is where Fluentic’s chain structure matters. The generated rule can keep the selector/media context that produced it.

So DevTools does not just answer:

backgroundColor exists in this style

It can answer:

this generated background-color rule came from backgroundColor inside .hover(...)

That is a much better debugging experience.

Element Markers: From DOM Back To JSX

CSS rule sourcemaps answer:

Which style produced this CSS rule?

But sometimes the question starts from the DOM node:

Which JSX element attached this style?

In development, Fluentic can add an element marker class to host elements that receive a css prop.

Conceptually:

return <article css={css.root}>...</article>;

gets a development-only marker.

The marker rule is intentionally tiny:

.<marker-class>{--fluentic-element-marker:0}

It exists so DevTools has a sourcemap target that points back to the JSX element where the css prop was attached.

That helps when the CSS rule is not the first question.

Sometimes you inspect a DOM node and just want to know:

Which component rendered this?
Which JSX line attached css={css.root}?
Is this the root element or an inner slot?

Element markers make the DOM-to-JSX path explicit.

No custom browser extension should be required for that basic workflow. It should work with normal browser DevTools and sourcemaps.

Spread And Merge Need Two Debug Views

Reusable style fragments are useful.

They also make sourcemaps tricky.

Example:

const textReset = style.raw({
  margin: 0,
  lineHeight: 1.4,
});

const title = style({
  ...textReset,
  fontWeight: 700,
});

If DevTools shows the generated line-height rule, where should it point?

There are two useful answers.

Sometimes I want the original value:

textReset
lineHeight: 1.4

Sometimes I want the style that used it:

title
...textReset

Both are valid.

So Fluentic has sourcemap modes:

StyleDevUtils.setSourcemapMode.toStyle();
StyleDevUtils.setSourcemapMode.toValue();

toStyle() points spread or merged rules toward the style call that assembled them.

toValue() points them toward the original reusable value when possible.

This is one of those small details that feels boring until you are debugging a real component library.

When a shared reset is wrong, I want the original value.

When one component uses the shared reset in a surprising way, I want the use site.

One fixed sourcemap answer cannot cover both questions well.

Slots And Scopes Should Not Become Anonymous

Root styling is the easy case.

Reusable components are harder.

A component might expose styleable parts:

const buttonStyles = {
  root: style.slot({
    display: 'inline-flex',
    border: 0,
  }),

  icon: style.slot({
    width: 16,
    height: 16,
  }),

  label: style.slot({
    fontWeight: 700,
  }),
};

Then an outside variant or theme might target those parts:

const danger = style.scope([
  buttonStyles.root({
    backgroundColor: '#dc2626',
  }),

  buttonStyles.label({
    color: '#ffffff',
  }),
]);

After generation, all of this still becomes CSS.

But the authored meaning is different:

root base style
icon base style
label base style
danger scope -> root override
danger scope -> label override

Those identities should not disappear.

If the label is white, I want to know whether that came from the label base style or the danger scope override.

If the root background changed, I want to know which scope produced it.

If a parent provides a theme override, I want to know which slot it targeted.

The generated CSS should not flatten all of those decisions into anonymous classes.

Slots and scopes are part of the debug story, not only the authoring API.

Tokens Are The One I Still Want To Improve

Most of the trail is already in place: properties, chain calls, spreads, merges, slots, scopes, and JSX css props.

The piece I am still thinking about is tokens.

Tokens already carry identity for styling and theming. But I still want token debugging to become more source-aware too.

For example, if a generated rule uses a token value, I want the debugging path to help answer:

Which token was used?
Where was that token defined?
Which theme changed it?
Which component consumed it?

That is harder because token values can move through theme layers and runtime resolution.

But it is the direction I want.

A style system should not stop at “this CSS variable exists.”

It should help explain the token path too.

Dev Utilities Should Be Normal DevTools-Friendly

I did not want the basic debugging story to require a custom browser extension.

Extensions can be great.

But the first path should work with browser DevTools, generated CSS, and sourcemaps.

Fluentic exposes development utilities through the console:

StyleDevUtils.info();
StyleDevUtils.usage();
StyleDevUtils.getConfig();

info() gives a quick overview of the active development setup:

runtime mode
CSS mode
priority mode
sourcemap mode
element marker state
plugin state

There are toggles too:

StyleDevUtils.setSourcemapMode.toStyle();
StyleDevUtils.setSourcemapMode.toValue();

StyleDevUtils.setElementMarker.toOn();
StyleDevUtils.setElementMarker.toOff();

StyleDevUtils.setPriorityMode.toLayer();
StyleDevUtils.setPriorityMode.toSort();

These are not separate styling APIs.

They are debugging views.

Sometimes I want source traces to point at the style call.

Sometimes I want them to point at the reusable value.

Sometimes I want element markers on.

Sometimes I want to inspect priority layers.

I should not have to rewrite component code to change the debugging view.

Runtime-Only Development Still Has A Trace Path

Plugin-powered development has the best metadata because the plugin sees source files while transforming them.

But Fluentic also supports runtime-only development.

In that mode, Fluentic can use:

StyleDevUtils.traceSourcemap();

That lets a runtime setup fetch browser-served JavaScript sourcemaps and remap development CSS comments closer to the original TypeScript.

It is not the same as plugin-recorded metadata, because the plugin has more source context.

But the principle is the same:

generated CSS should not be a dead end

Even in runtime-only mode, I still wanted a path back toward authored code.

React Server Components Need Debugging Too

Modern React apps can move styles through server and client boundaries.

For Next.js App Router and React Server Components development, Fluentic provides a dev client:

import { StyleDev } from '@fluentic/style/dev/rsc';

export default function RootLayout(props: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {props.children}
        {process.env.NODE_ENV === 'development'
          ? <StyleDev enableStyleDevUtils />
          : null}
      </body>
    </html>
  );
}

That keeps the same StyleDevUtils workflow available when styles are moving through an RSC development path.

This mattered to me because debugging should not only work in the smallest Vite demo.

If the library supports modern React modes, the debugging workflow has to follow.

Why This Works: Identity Survives Long Enough

This is the design reason behind all of this.

Fluentic keeps style information as structured data before it becomes final CSS.

author API -> style data -> runtime resolver
                       -> compiler extraction
                       -> debug metadata

If style information becomes opaque strings too early, the browser can still get CSS.

But debugging loses context.

Fluentic tries to keep identity attached long enough:

style()       -> element style
chain method  -> selector/media context
style.slot()  -> component part
style.scope() -> grouped override
token/value   -> themeable source
css prop      -> rendered JSX element

That identity is what lets generated atomic CSS point back toward source.

It is also what lets the same authoring API support runtime composition, production extraction, and development debugging.

Debuggability is not separate from the style model.

It has to be part of it.

The Tradeoff I Wanted

I do not think every styling library has to make the same tradeoff.

Some libraries choose the smallest possible runtime.

Some optimize around strict build-time constraints.

Some prioritize framework compatibility.

Some use readable generated class names as the main debug hint.

Some rely on labels and naming conventions.

Those can all be reasonable choices.

But for Fluentic, I wanted source-level debugging to be first-class.

Because this is the thing I kept wanting as a user:

If a styling library generates CSS for me,
it should help me debug that generated CSS too.

I do not want a library that feels great while writing styles but becomes vague when the UI is wrong.

I do not want to choose between:

nice authoring API
good generated CSS
real sourcemaps

I want those designed together.

That does not mean Fluentic debugging is done forever.

It is still beta. Tokens can get better. Different bundlers and framework modes will keep exposing edge cases. Debugging UI is always full of weird details.

But the direction is clear:

generated CSS should lead back to source

Not only through readable names.

Not only approximately.

Through sourcemaps, debug metadata, element markers, trace modes, and preserved style identity.

What Comes Next

This post is the high-level debugging story.

The next step is showing more of the mechanics:

how generated atomic CSS maps to authored properties
how element markers connect DOM nodes to JSX
how toStyle() and toValue() change spread/merge tracing
how slots and scopes stay visible while debugging overrides
how debug class names and sourcemaps work together
how this behaves with extraction and runtime-known values

The goal is simple:

When a style is wrong, DevTools should help answer what code produced it.

Not make you guess.

Fluentic Style is still new and currently in beta. I am looking for early users to try it in real React, Preact, Solid, and component-library codebases.

Useful links:

Feedback would help a lot right now, especially around debugging workflows, sourcemap quality, generated CSS inspection, bundler integrations, token tracing, and whether this source-tracing model matches the way you debug real UI.

Building Fluentic Style: Behind the Tailwind Presets

OmniDev — Sat, 01 Aug 2026 01:09:43 +0000

This is part of my Building Fluentic Style series, where I’m writing down the design decisions, tradeoffs, and small surprises from building Fluentic Style.

In the previous post, I wrote about how I did not want a Tailwind preset, then ended up adding two.

One is object-based.

One is class-name-based.

That sounded like a Tailwind feature from the outside, but internally it became something bigger for Fluentic.

The interesting part was not only Tailwind.

The interesting part was the lower-level system underneath it:

object style chains
class-name style chains
custom transforms
custom selector methods
typed validation
runtime resolution
CSS extraction
debug metadata

The Tailwind presets are just one use of that system.

The more general idea is that Fluentic can host different styling dialects.

The Tailwind Presets Are Built On Public Pieces

The Tailwind docs are here:

But the important thing is that these presets are not a separate secret mode.

They are built from the same lower-level APIs that users can reach for:

That matters because Tailwind is not the end of the story.

A team might want Tailwind-like names.

Another team might want design-system words like row, center, tone, surface, pressed, or below.

Another team might want class names because that is how their UI code already reads.

Fluentic should not require all of those teams to write styles with one exact vocabulary.

Two Inputs, Same Fluentic Path

Fluentic now has two main custom authoring paths.

Object-based chains:

ui({
  row: true,
  center: true,
  gapX: 8,
}).selected({
  backgroundColor: '#eef2ff',
});

Class-name-based chains:

cx('row', 'center', 'gap-x-8')
  .selected('bg-selected');

Those look different.

But they can both become Fluentic style data:

object fields   -> transform -> Fluentic style data
class names     -> transform -> Fluentic style data
chain methods   -> selectors, media, states
slots/scopes    -> component styling boundaries
compiler        -> CSS extraction for production output
debug tools     -> source-aware generated CSS

That is the whole point.

The syntax can change without replacing the rest of the styling system.

Object Chains: Custom Fields With Pure TypeScript

The object-based path uses createStyleFn(...).

You define the style shape you want, then write a transform that turns your custom fields into normal CSS properties.

For example, a small layout dialect:

import {
  createStyleFn,
  styleTransform,
  type CSSProperties,
  type,
} from '@fluentic/style';
import { selector } from '@fluentic/style/selector';

type LayoutStyle = CSSProperties & {
  row?: boolean;
  column?: boolean;
  center?: boolean;
  gapX?: CSSProperties['columnGap'];
  gapY?: CSSProperties['rowGap'];
};

const layoutTransform = styleTransform<LayoutStyle>({
  transform(style) {
    const { row, column, center, gapX, gapY, ...css } = style;

    if (row || column) {
      css.display = 'flex';
      css.flexDirection = row ? 'row' : 'column';
    }

    if (center) {
      css.alignItems = 'center';
      css.justifyContent = 'center';
    }

    if (gapX !== undefined) css.columnGap = gapX;
    if (gapY !== undefined) css.rowGap = gapY;

    return css;
  },
});

const selectors = {
  hover: selector(':hover'),
  selected: selector('[aria-selected="true"]'),
};

export const { style: ui } = createStyleFn({
  style: type<LayoutStyle>,
  selectors,
  transform: layoutTransform,
});

Then component code can use those custom fields:

const tab = ui({
  row: true,
  center: true,
  gapX: 8,
  paddingInline: 12,
  paddingBlock: 8,
}).selected({
  backgroundColor: '#eef2ff',
});

The transform is just TypeScript.

No plugin DSL.

No compiler macro language.

No special config syntax just to say “when row is true, write flex row CSS.”

You destructure the custom fields, write normal CSS properties, and return the remaining object.

That is why I like this part of Fluentic a lot. Custom transforms stay boring in the best possible way.

Class-Name Chains: Custom Names With `createClassNameFn`

The class-name path uses createClassNameFn(...).

Instead of transforming an object, you transform each class name.

import {
  classNameTransform,
  createClassNameFn,
  type CSSProperties,
} from '@fluentic/style';
import { selector } from '@fluentic/style/selector';

type UiClassName =
  | 'row'
  | 'center'
  | 'gap-x-8'
  | 'bg-selected'
  | 'opacity-muted';

const transform = classNameTransform<UiClassName>({
  transform(className) {
    const css: CSSProperties = {};

    if (className === 'row') {
      css.display = 'flex';
      css.flexDirection = 'row';
    }

    if (className === 'center') {
      css.alignItems = 'center';
      css.justifyContent = 'center';
    }

    if (className === 'gap-x-8') {
      css.columnGap = 8;
    }

    if (className === 'bg-selected') {
      css.backgroundColor = '#eef2ff';
    }

    if (className === 'opacity-muted') {
      css.opacity = 0.64;
    }

    return css;
  },
});

const selectors = {
  hover: selector(':hover'),
  selected: selector('[aria-selected="true"]'),
};

export const { className: cx } = createClassNameFn({
  selectors,
  transform,
});

Now the authoring style is class-name based:

const tab = cx('row', 'center', 'gap-x-8')
  .selected('bg-selected')
  .hover('opacity-muted');

And because the class-name type is a TypeScript union, invalid names can be caught:

cx('row', 'gap-x-8'); // ok

cx('gap-x-999');
//  ^ TypeScript error

For a tiny design-system dialect, a union is enough.

For a larger one, you can use template literal types, lookup tables, generated maps, helper functions, whatever TypeScript already gives you.

Again, the transform is just regular TypeScript logic.

Custom Chain Methods Are Where It Gets Interesting

Custom fields and class names decide what CSS declarations exist.

Custom chain methods decide when those declarations apply.

This is where Fluentic’s selector system becomes important.

Instead of repeating raw selectors everywhere:

ui().select('&[data-state="open"]', {
  opacity: 1,
});

You can turn shared selector conventions into named methods:

ui().open({
  opacity: 1,
});

The lower-level selector syntax is small, but it carries a lot:

import {
  assertEnumSelector,
  selector,
  selectorPriority,
} from '@fluentic/style/selector';

const selectors = {
  hover: selector(':hover'),
  focusVisible: selector(':focus-visible'),

  open: selector('[data-state="open"]'),

  tone: selector(
    '[data-tone="$"]',
    assertEnumSelector('neutral', 'danger'),
  ),

  state: selector(
    '[data-state="$$"]',
    assertEnumSelector('open', 'closed'),
  ),

  below: selector('@media (max-width: $$)', 'media'),
};

const prioritySelectors = selectorPriority(selectors, [
  'hover',
  'focusVisible',
  'open',
]);

Then those selectors become typed chain methods:

const menuButton = ui({
  border: 0,
  padding: '8px 12px',
}).open({
  backgroundColor: '#eef2ff',
}).tone('danger', {
  color: '#b91c1c',
}).below('700px', {
  padding: '6px 10px',
});

The method signatures come from the selector definitions.

A selector with no argument:

open: selector('[data-state="open"]')

becomes:

.open(style)

A selector with one $ argument:

tone: selector('[data-tone="$"]', assertEnumSelector('neutral', 'danger'))

becomes:

.tone('neutral' | 'danger', style)

A selector with $$ can accept one value or an array:

state: selector('[data-state="$$"]', assertEnumSelector('open', 'closed'))

becomes:

.state('open', style)
.state(['open', 'closed'], style)

An at-rule selector:

below: selector('@media (max-width: $$)', 'media')

becomes a media-style chain method:

.below('700px', style)

And the validation is not only runtime convention. The validator can narrow the TypeScript signature:

ui().tone('danger', {
  color: '#b91c1c',
});

ui().tone('warning', {
  color: '#92400e',
});
//        ^ TypeScript error if "warning" is not in the enum selector

That is the part I care about.

A design system can move from selector strings by memory to typed methods with a central definition.

[data-state="open"]       -> .open(...)
[data-tone="danger"]      -> .tone('danger', ...)
@media (max-width: 700px) -> .below('700px', ...)

The selector stays CSS-shaped.

The authoring API becomes TypeScript-shaped.

The Same Selector Methods Work For Class Names

The selector system is not only for object styles.

The class-name chain gets the same methods:

const trigger = cx('row', 'center', 'gap-x-8')
  .open('bg-selected')
  .tone('danger', 'text-danger')
  .below('700px', 'gap-x-4');

That is why the Tailwind class-name preset can keep Tailwind-like names while still using Fluentic chains for conditions.

Class names are the vocabulary.

Chain methods are the structure.

cx('bg-blue-600')
  .hover('bg-blue-700')
  .md('px-6')

Instead of making hover: and md: part of the string itself, Fluentic keeps those as methods.

That makes the condition explicit in the style chain, and it keeps the same extension path open for app-specific states:

cx('bg-surface')
  .open('shadow-lg')
  .tone('danger', 'border-danger')
  .below('640px', 'px-3');

Why This Reduces Limits

This is what the Tailwind preset work taught me.

If Fluentic only supported CSS object fields, it would be nice for people who like object styles.

If Fluentic only supported class names, it would be familiar for utility-first users.

But supporting both makes the lower-level idea much more useful.

A team can choose the authoring shape that fits the code:

direct CSS object
  good for precise component styles

custom object dialect
  good for design-system fields and typed shortcuts

custom class-name dialect
  good for utility naming and migration from existing code

custom selector methods
  good for shared states, breakpoints, data attributes, and component conventions

And these are not separate systems.

They all still flow into Fluentic’s component styling pieces:

css prop
style.slot(...) / cx.slot(...)
style.scope(...) / cx.scope(...)
combineStyle(...)
tokens and themes
runtime resolution
production CSS extraction
debug source metadata

That means the user gets more freedom at the top without losing the shared behavior underneath.

You can build a Tailwind-like dialect.

You can build a design-system dialect.

You can build a small team-local vocabulary.

You can keep raw CSS properties where that is clearer.

The point is not to hide CSS forever.

The point is to let teams choose the right words while still keeping styles composable inside a component system.

Extraction And Debugging Still Matter

There is one more upside that I think is important.

Custom fields, custom class names, and custom transform functions can sound like they would push you outside the normal styling pipeline.

In Fluentic, they do not.

You are still writing Fluentic style chains. The custom pieces only decide the vocabulary you write at the top. The result still has the same structure underneath: style parts, selectors, slots, scopes, themes, and values.

That is intentional.

Fluentic emits atomic CSS in both development and production. Because the custom vocabulary still goes through the style-chain structure, the compiler and bundler plugins can recognize it and apply the same production path: code optimization, extracted atomic CSS, and prepared JavaScript output.

This is not only for the boring case where a style object sits at module scope and never changes.

Real component code has conditions, props, themes, scopes, and values that only exist at runtime. Fluentic is designed for that. The compiler extracts CSS from the style-chain structure, while the runtime uses the prepared style data to pick up runtime-known values, resolve selected scopes and themes, and attach the right generated classes.

The important part is that you do not have to switch APIs when a style depends on component state or props.

It is still regular TypeScript. You can branch, pass values around, compose scopes, and let the rendered app choose the final styling inputs.

That was important to me.

I did not want custom style dialects to feel like a cute dev-only layer that breaks once the app becomes dynamic.

In development, the same structure gives Fluentic enough information to attach debug metadata and sourcemaps to generated atomic CSS. I will cover that more in the next post.

This also changes how I think about transform performance.

A custom transform can look a little heavier than a normal style object:

const transform = styleTransform<LayoutStyle>({
  transform(style) {
    const { row, center, gapX, ...css } = style;

    if (row) {
      css.display = 'flex';
      css.flexDirection = 'row';
    }

    if (center) {
      css.alignItems = 'center';
      css.justifyContent = 'center';
    }

    if (gapX !== undefined) {
      css.columnGap = gapX;
    }

    return css;
  },
});

At first glance, it is fair to wonder:

“Am I shipping this function to the browser and running it for every style?”

In production builds with the Fluentic plugin, the answer is usually no.

The transform runs during the build for extracted style chains. The plugin turns the authored style chain into prepared output and generated CSS. By the time the production JavaScript reaches the browser, the transform function is no longer part of the hot path for those extracted styles.

That means you do not need to obsess over every byte or every branch in a transform function the same way you would for code running on every render.

Write the transform clearly first.

Of course, development mode still runs transforms so the authoring experience can stay flexible and immediate. So I still try not to make transforms absurdly slow.

But the tradeoff is much nicer than it looks at first:

development  -> transform runs for flexibility and fast iteration
production   -> plugin runs transform during build and emits extracted CSS
browser      -> consumes prepared style output instead of rerunning the transform

That made custom transforms feel much more practical to me.

They can stay plain TypeScript instead of becoming a tiny hand-optimized compiler language.

The same applies to debugging.

In development, Fluentic still emits atomic CSS, but the generated CSS can carry source information. Each generated CSS item can trace back to the style, field, chain call, slot, scope, or JSX css prop that produced it.

So when you inspect generated CSS in browser DevTools, the path back to source should not feel like guessing.

You should not have to wonder:

Which helper produced this class?
Which style chain added this hover rule?
Which slot override changed this property?
Which JSX element received this css prop?

The generated CSS should lead you back to the original code.

No special browser extension should be required for the basic workflow. It should work with normal browser DevTools and sourcemaps.

I will cover the debugging details in the next post, because this deserves its own space.

But this is one of the reasons I liked the custom style system more after adding the Tailwind presets.

The custom syntax is not outside Fluentic.

It becomes Fluentic.

Where This Leaves The Tailwind Presets

So yes, Fluentic has two Tailwind presets:

But the part I am more excited about is what they proved.

Fluentic can support:

object-based style dialects
class-name-based style dialects
custom transforms written as pure TypeScript
custom selector methods with typed arguments
centralized selector validation
component slots and scopes on top
production CSS extraction
source-aware development debugging

The Tailwind presets are useful by themselves.

But they also showed me the bigger shape.

Fluentic Style is not just one styling vocabulary.

It is a way to make styling vocabularies work inside a typed, composable JSX styling system.

Fluentic Style is still new and currently in beta. I am looking for early users to try it in real React, Preact, Solid, and component-library codebases.

Useful links:

Feedback would help a lot right now, especially around custom style builders, Tailwind preset coverage, selector methods, build integrations, and whether this styling-language approach feels useful in real projects.

Building Fluentic Style: I Didn’t Want a Tailwind Preset. Then I Added Two.

OmniDev — Fri, 31 Jul 2026 10:12:34 +0000

TL;DR: Fluentic Style is a new JSX styling library for React, Preact, Solid, and compatible JSX runtimes. It starts with typed style objects and a css prop, then adds selector chains, component slots, scopes, themes, runtime resolution, and optional static CSS extraction for production builds.

Fluentic started as an object-first styling API.

That was intentional.

The original shape was built around typed style objects, explicit composition, selector chains, component slots, scopes, themes, and optional static extraction later.

So the first Fluentic style looked more like this:

import { style } from '@fluentic/style';

const button = style({
  display: 'inline-flex',
  alignItems: 'center',
  gap: 8,
  border: 0,
  borderRadius: 8,
  paddingInline: 16,
  paddingBlock: 8,
  backgroundColor: '#2563eb',
  color: '#ffffff',
}).hover({
  backgroundColor: '#1d4ed8',
});

This is still the Fluentic style I personally reach for first.

It is regular TypeScript. The style is data. The chain adds a state. The result can work at runtime, and the compiler can extract the static parts later.

So when I started thinking about Tailwind support, my first instinct was pretty predictable:

Bring Tailwind’s vocabulary into Fluentic’s object-based style world.

And then, somehow, I ended up adding two Tailwind presets.

The docs for both live here:

The First Preset Was Object-Based

The first version was the Fluentic-shaped answer.

Instead of regular CSS property names, it used a Tailwind-like object dialect:

const button = tw({
  inlineFlex: true,
  items: 'center',
  gap: '$2',
  px: '$4',
  py: '$2',
  bg: '$blue.600',
  text: '$white',
  rounded: '$md',
}).hover({
  bg: '$blue.700',
}).md({
  px: '$6',
});

I still like this API.

It keeps a lot of the things I wanted Fluentic to care about:

styles are grouped as objects
TypeScript can understand the shape
dynamic branches can affect several declarations together
selectors and media stay in chain methods
the output is still Fluentic style data

It also keeps the useful part of Tailwind’s vocabulary: px, py, bg, rounded, items, gap, theme scales, breakpoints, and so on.

But there is a tradeoff.

A Tailwind user still has to translate from the syntax they already know:

inline-flex        -> inlineFlex: true
items-center       -> items: 'center'
gap-2              -> gap: '$2'
bg-blue-600        -> bg: '$blue.600'
hover:bg-blue-700  -> .hover({ bg: '$blue.700' })

That translation is not awful.

But it is still translation.

And if the point of a Tailwind preset is to make Tailwind-oriented codebases easier to adopt, asking every user to move through an object dialect is not always the best bridge.

That was the interesting part.

The first preset matched Fluentic’s original API taste.

But it did not fully match Tailwind’s muscle memory.

So I Added A Class-Name Preset Too

The second preset keeps class names closer to the way Tailwind users already write them:

const button = tw(
  'inline-flex',
  'items-center',
  'gap-2',
  'rounded-md',
  'bg-blue-600',
  'px-4',
  'py-2',
  'text-white',
)
  .hover('bg-blue-700')
  .md('px-6');

This feels much closer to Tailwind.

But it is still Fluentic.

The variants are not packed into the class string:

tw('bg-blue-600')
  .hover('bg-blue-700')
  .md('px-6');

Instead of:

bg-blue-600 hover:bg-blue-700 md:px-6

That part is deliberate.

Fluentic already has chain methods for states, selectors, media queries, scopes, and other styling conditions. I did not want Tailwind support to bypass that.

So class names became the input vocabulary, but chains still carry the structure.

In practice, it looks like this:

class names    -> transform -> Fluentic style data
chain methods  -> selectors, media, and conditions
runtime        -> resolves dynamic styles
compiler       -> extracts static styles
debug tools    -> trace generated CSS back to source

The syntax changed.

The rest of Fluentic stayed the same.

The class-name chain is not just a class string helper either. It also supports the same slot and scope shape as the object-style chain.

The Part That Changed My Mind

Before this, I mostly thought about Fluentic as an object-style API with chain methods.

After adding both Tailwind presets, that felt too narrow.

The object API is still important. It is still the default path. It is still the one I prefer for complex component styling.

But Fluentic can support more than one authoring style.

The input can be regular CSS objects:

style({
  backgroundColor: '#2563eb',
}).hover({
  backgroundColor: '#1d4ed8',
});

It can be a Tailwind-like object dialect:

tw({
  bg: '$blue.600',
}).hover({
  bg: '$blue.700',
});

It can be a Tailwind-like class-name dialect:

tw('bg-blue-600').hover('bg-blue-700');

And projects can define their own naming and transform logic too.

That last part matters most to me.

Fluentic does not need to own every word in the styling language.

It needs to provide the pieces underneath:

style values
selector chains
slots
scopes
tokens
runtime resolution
compiler extraction
debugging metadata

The vocabulary on top can be different per team.

If you want to see the lower-level APIs behind that idea, these docs are the useful ones:

Why Not Just Use Tailwind?

Fair question.

Tailwind is good. A lot of people are fast with it. The naming system is familiar, the docs are strong, and the ecosystem is huge.

I did not add Tailwind presets because I think Fluentic should replace Tailwind.

I added them because Tailwind-style vocabulary is useful, and I wanted to see what happens when that vocabulary runs through Fluentic’s component styling system.

For example, Fluentic still has component slots with the class-name chain:

const card = {
  root: tw.slot('rounded-xl', 'bg-white', 'p-6'),
  title: tw.slot('text-xl', 'font-bold'),
  body: tw.slot('text-slate-600'),
};

And scopes can still target those slots:

const compact = tw.scope([
  card.root('p-4'),
  card.title('text-lg'),
  card.body('text-sm'),
]);

That is the part I care about.

The class names are not the component contract.

The slots are.

The component can decide which parts are styleable without exposing its private DOM structure.

Where This Leaves Fluentic

I did not want a Tailwind preset.

Then I added one.

Then I added another one because the first one was a little too loyal to Fluentic’s original object-first API.

That feels like a useful library-design lesson.

Sometimes the API you prefer is not the API that helps people cross the bridge.

And sometimes supporting another way to write styles does not weaken the idea.

It clarifies what the library is actually responsible for.

Fluentic now supports:

object-based style chains
class-name-based style chains
custom selectors
custom transforms
Tailwind-like presets on top

Both Tailwind presets still go through the same Fluentic path: chains, slots, scopes, runtime resolution, extraction, and debugging.

So no, Fluentic did not become Tailwind.

But adding Tailwind support made Fluentic more honest about itself.

Fluentic is not trying to own every styling word you write.

It is trying to make those words composable once they enter your component system.

Fluentic Style is still new and currently in beta. The core authoring model is usable today, but I am still looking for early users to try it in real React, Preact, Solid, and component-library codebases.

If this direction is interesting, here are the main links:

Feedback would help a lot right now, especially around API shape, Tailwind preset coverage, build integrations, debugging, and whether the slot/scope model makes sense in real component work.

Building Fluentic Style: Bringing React Native Style Composition to React

OmniDev — Sat, 04 Jul 2026 13:27:46 +0000

Fluentic Style is my attempt to make React styling feel explicit, composable, and predictable again, without giving up the ergonomics developers expect.

Years ago, I worked on web apps with Emotion, and I loved it.

It was flexible, productive, and convenient. But over time, some of the codebases I worked on became harder and harder to change. I do not blame Emotion for that. The problem was how I used the convenience it gave me.

I wrote class names that depended on DOM structure. I used nested selectors because they were quick. I reached into child elements from parent styles. It worked, until months later I had to change something and no longer felt confident about what else would break.

That feeling is what I remember most.

Not that the styling was impossible. Not that the tool was bad. Just that I slowly lost confidence when changing UI.

The Problem Was Confidence

A lot of frontend styling problems are not about whether something is technically possible.

CSS is powerful. CSS-in-JS is powerful. Utility classes are powerful. CSS Modules are useful. Static extraction is useful.

The hard part is usually confidence.

Can I change this component without accidentally changing another component?

Can I understand where this style comes from?

Can I tell which style wins?

Can I move this element without breaking some selector far away?

Can I delete this class name?

Can I add a variant without making the component more fragile?

When styles depend on class names, DOM structure, nested selectors, and implicit relationships between elements, every change becomes a little less obvious.

You can still build good systems this way. Many teams do.

But that way of styling makes it very easy to create hidden coupling.

And hidden coupling is where confidence starts to fade.

Then I Spent Years in React Native

After that, I spent years mostly working on React Native projects.

React Native styling changed how I think about UI.

The styling model is much smaller:

<View style={[styles.root, disabled && styles.disabled, style]} />

Styles are objects.

Styles are passed as values.

Arrays compose styles.

The later style wins.

Variants are usually explicit.

The style belongs close to the element that uses it.

There is no class name pretending to be both identity and styling hook. There is no global selector reaching through some DOM structure. There is much less “where did this come from?”

Of course React Native styling is not perfect. It has its own limitations. But the mental model is very simple.

And after using that model for years, I came back to React web.

That was when web styling felt more complicated to me than it used to.

Not because CSS got worse.

Actually, CSS got much better.

We have better layout. Better selectors. Better browser support. Better build tools. Better frameworks.

But for component-heavy React work, I started to miss the React Native mental model a lot.

In React Native, this kind of style composition is completely normal:

<View style={[base, variant, state, props.style]} />

And that normality matters.

Base first. Then the variant. Then the current state. Then the style passed from outside.

It makes styling feel like data. Like values. Like composition.

Not like a string contract with the DOM.

React web already has pieces of this too. Emotion’s css prop can feel especially close, and other tools have their own ways to compose styles.

However the thing I wanted was not just style composition for one element.

React Native does not solve every part of this either. When a component has multiple internal elements, you still need to decide which parts can be styled and how those styles are passed through.

I wanted the same explicit composition to work not only for one root element, but across a whole styleable component: root, icon, label, header, content, footer, or whatever parts the component chooses to expose.

Not just root element composition:

<Component css={[base, variant, props.css]} />

But a component style theme where each public part can be composed explicitly, without the caller reaching into DOM structure or relying on class names as hidden hooks, with something as simple as this:

<Component theme={[baseTheme, variantTheme, props.theme]} />

That is where Fluentic started to feel different.

React Web Has Something React Native Misses

But I do not want to pretend React Native has the perfect model.

It does not.

The web has something extremely useful: selectors.

Sometimes selectors are exactly what you want.

You want hover states:

.button:hover {
  background: var(--hover);
}

You want focus states.

You want child coordination.

You want media queries.

You want pseudo elements.

You want to style based on parent state.

You want to express relationships without manually passing a style prop into every single element.

That is real power.

React Native often makes this more manual. You wire state. You pass style props. You conditionally apply styles element by element.

That explicitness is nice until it becomes repetitive.

So the question I kept thinking about was:

Can React styling keep the simple React Native mental model, but still keep the useful parts of CSS?

Can styles be values, while selectors still exist?

Can composition be explicit, while output is still real CSS?

Can override order be obvious, while runtime work stays small?

That question became the beginning of Fluentic.

Extraction Is Not the New Idea

Modern React styling has changed a lot.

Runtime CSS-in-JS used to feel like a reasonable default for many React apps. Today, the tradeoffs are more visible.

Performance matters.

Server rendering matters.

Streaming matters.

React Server Components changed what can happen on the server and what should happen on the client.

Build-time extraction is no longer a niche idea. In many modern stacks, it feels close to mandatory.

But extraction itself is not the interesting part anymore.

There are already many libraries that extract CSS.

That is not the main reason I started working on Fluentic.

The thing I felt missing was not “another extracted CSS-in-JS library”.

The thing I wanted was a different way to write and compose styles.

A model closer to what I had in my head after years of React Native:

styles as values
explicit composition
predictable override order
local ownership
variants without magic class names
selectors when useful, but not as the default way to connect everything
build-time output that fits modern React apps

That is the shape of Fluentic.

What I Want From a Styling System

When I started thinking about Fluentic, I wrote down the requirements more like a frontend developer who has been hurt by his own past decisions than like someone trying to invent a styling library.

The requirements were not only technical.

They were emotional too.

I wanted to feel confident changing UI again.

1. Styles Should Be Values

In React Native, a style is something you can pass around.

<View style={styles.card} />

Or compose:

<View style={[styles.card, elevated && styles.elevated]} />

That feels very different from:

<div className={`${styles.card} ${elevated ? styles.elevated : ""}`} />

The class name version works, of course. But the mental model is different.

One feels like composing values.

The other feels like constructing a string that points to styling somewhere else.

In Fluentic, the equivalent idea uses style(...) and the JSX css prop:

import { style } from '@fluentic/style';

const styles = {
  card: style({
    padding: 16,
    borderRadius: 8,
    backgroundColor: 'white',
  }),

  elevated: style({
    boxShadow: '0 12px 30px rgb(15 23 42 / 0.16)',
  }),
};

function Card({ elevated }: { elevated?: boolean }) {
  return (
    <section css={[styles.card, elevated && styles.elevated]}>
      Ready to style.
    </section>
  );
}

The syntax is different from React Native, because the target is still the browser.

But the feeling is familiar:

Base style first.

Conditional style after.

The style value is passed directly to the element.

2. Override Order Should Be Obvious

One of the nicest things about React Native style arrays is that the later item wins.

<View style={[styles.base, styles.large, props.style]} />

You can read that line and understand the override order.

Base first.

Then large.

Then external style.

There is very little mystery.

On the web, override order can come from many places:

stylesheet order
selector specificity
class order
nested selectors
cascade layers
inline styles
generated CSS order

Some of these are powerful. Some are necessary. But when building components, I often want the boring rule:

later style wins

Fluentic is designed around that kind of predictability.

<button css={[styles.button, primary && styles.primary, props.css]}>
  Save
</button>

That is the kind of composition I want to keep visible in React code.

3. Variants Should Be Explicit

I have written many components where styles were controlled by a mix of class names and nested selectors.

Something like:

.card.compact .title {
  font-size: 14px;
}

.card.highlighted .title {
  color: blue;
}

This is convenient.

It also couples the parent state, child structure, and class names together.

Later, when the component changes, the style assumptions are still sitting there.

For a local component, explicit composition can be enough:

const styles = {
  card: style({
    padding: 16,
    borderRadius: 8,
    backgroundColor: 'white',
  }),

  compactCard: style({
    padding: 12,
  }),

  title: style({
    fontSize: 20,
    fontWeight: 700,
  }),

  compactTitle: style({
    fontSize: 16,
  }),
};

function Card({ compact }: { compact?: boolean }) {
  return (
    <div css={[styles.card, compact && styles.compactCard]}>
      <h2 css={[styles.title, compact && styles.compactTitle]}>
        Title
      </h2>
    </div>
  );
}

This may look less magical.

That is the point.

A little less magic often means a lot more confidence later.

4. Reusable Components Need More Than Root Styling

Root-level styling is only the small case.

Reusable React components often have internal parts.

A button may have a root, an icon, and a label.

A card may have a root, header, title, content, and footer.

A caller might need to customize those parts without depending on DOM structure.

With normal class names, the public styling API often becomes accidental:

<button className="button">
  <span className="button__icon" />
  <span className="button__label">Save</span>
</button>

That works.

But now the caller knows your class names.

And if they use selectors, they may also start to know your markup.

Fluentic uses slots for this.

A slot is a named styling target that a component chooses to expose:

import { style } from '@fluentic/style';

const buttonStyles = {
  root: style.slot({
    display: 'inline-flex',
    alignItems: 'center',
    gap: 8,
    border: 0,
    borderRadius: 8,
    padding: '8px 12px',
  }),

  icon: style.slot({
    display: 'inline-flex',
    width: 16,
    height: 16,
  }),

  label: style.slot({
    fontWeight: 650,
  }),
};

This says something important:

root, icon, and label are allowed styling targets.

The DOM can stay private.

The component decides what it exposes.

5. Selectors Should Exist, But They Should Not Become the Whole Model

I still want hover and focus styles to feel natural.

In Fluentic, a simple element style can use fluent selector/state chains:

const button = style({
  backgroundColor: 'white',
  border: '1px solid var(--color-border)',
}).hover({
  backgroundColor: 'var(--color-surface-hover)',
}).focusVisible({
  outline: '2px solid var(--color-focus)',
  outlineOffset: 2,
});

Hover and focus states belong naturally in CSS.

I do not want to manually wire every interaction state in JavaScript just to avoid selectors.

But I also do not want selectors to become the main way components talk to each other.

Selectors are useful.

Selectors are also where hidden relationships often begin.

So Fluentic should support selectors, but still encourage local, explicit style ownership.

6. Runtime Work Should Be Small

Modern React apps already have enough work to do at runtime.

Styling should not require unnecessary client-side computation when the result can be known at build time.

This matters even more with SSR and React Server Components.

So Fluentic needs extraction.

But again, extraction is the implementation requirement, not the whole product idea.

The product idea is the way styles are written and composed.

7. Debugging Should Lead Back to the Code

This does not happen every day, but when it happens, it is painful.

I have had simple style issues take much longer than they should because tracing the final rule back to the code was not clear enough. Sometimes the source map was not precise. Sometimes the class name pointed me to generated output, but not to the exact style code that produced it.

That kind of debugging makes me lose confidence quickly.

Atomic CSS has a real benefit: it can keep the final CSS output small. But it also means the browser often shows many generated class names in the HTML. That tradeoff is acceptable only if those class names can still be traced back to the style code that created them.

If the browser shows an atomic class name, I still need a way to answer:

which code created this rule?
which component owns it?
did this come from the base style, a variant, a scope, or an incoming override?
why did this style win?

Because styling bugs are often not about one declaration. They are about the path that declaration took into the UI.

So Fluentic is not only about producing CSS. It is also about making generated styles easier to trace back to the React code that created them.

8. App Themes Should Not Be an Afterthought

There are two things many apps do not need on day one, but often wish they had prepared for from the beginning: i18n and theming.

At first, it is easy to assume the app only needs one language, one brand, one density, and one visual mode.

Then later the app needs dark mode. Or a different brand theme. Or a denser admin layout. Or product-specific styling.

That is when theming becomes painful.

Not because dark mode is hard by itself, but because the codebase was not prepared for styles to change at the app level.

So Fluentic has to support theming without forcing every value to become a carefully named token from day one.

Named tokens are useful when the name matters, which is usually when a component exposes values that other code is expected to override intentionally:

const card = createTokens({
  surface: '#ffffff',
  text: '#111827',
  border: '#d8e3df',
});

const cardStyles = {
  root: style.slot({
    backgroundColor: card.surface,
    color: card.text,
    border: '1px solid',
    borderColor: card.border,
  }),
};

Now the component has a small theme surface.

Other code does not need to know its DOM structure. It only needs to know the values the component chose to expose.

But at the app level, naming every color or spacing value can become more effort than help.

Sometimes the value itself is the clearest thing to read, search, and maintain.

That is why Fluentic also has createValues(...):

const color = createValues([
  '#ffffff | Surface',
  '#111827 | Text',
  '#d8e3df | Border',
]);

The app can use those values directly:

const page = style({
  backgroundColor: color('#ffffff | Surface'),
  color: color('#111827 | Text'),
});

And createTheme(...) can provide different values at the app or subtree level:

const darkTheme = createTheme([
  color('#ffffff | Surface', '#111827'),
  color('#111827 | Text', '#ffffff'),
  color('#d8e3df | Border', '#374151'),
]);

function App() {
  return (
    <main css={[page, darkTheme]}>
      <Dashboard />
    </main>
  );
}

At the component level, those app values can be mapped into the component’s exposed tokens through style.scope(...) and passed to the component:

const dashboardCardTheme = style.scope([
  card.surface(color('#ffffff | Surface')),
  card.text(color('#111827 | Text')),
  card.border(color('#d8e3df | Border')),
]);

<Card theme={dashboardCardTheme} />

The app theme still controls what those app values become. The component theme only says how this component should connect to those values.

The goal is not to force every app to define many themes from day one.

The goal is to make themeability available from the beginning, so dark mode and app-level styling do not become a retrofit later.

What Fluentic Is Trying To Be

Fluentic is my attempt to bring a React Native-inspired styling mental model to React web apps.

The goal is not to hide CSS.

The web is still the web.

You still need to understand layout, cascade, inheritance, media queries, pseudo states, and browser behavior.

Fluentic is not trying to make CSS disappear.

It is trying to make component styling feel more explicit, composable, and predictable.

The smallest version looks like this:

import { style, type StyleProp } from '@fluentic/style';

const styles = {
  button: style({
    height: 36,
    paddingInline: 12,
    borderRadius: 6,
    border: '1px solid #d1d5db',
    backgroundColor: '#ffffff',
  }).hover({
    backgroundColor: '#f3f4f6',
  }),

  primary: style({
    borderColor: '#2563eb',
    backgroundColor: '#2563eb',
    color: '#ffffff',
  }),

  disabled: style({
    opacity: 0.5,
    pointerEvents: 'none',
  }),
};

type ToolbarButtonProps = React.ComponentProps<'button'> & {
  primary?: boolean;
  css?: StyleProp;
};

function ToolbarButton({
  primary,
  disabled,
  css,
  ...props
}: ToolbarButtonProps) {
  return (
    <button
      {...props}
      disabled={disabled}
      css={[
        styles.button,
        primary && styles.primary,
        disabled && styles.disabled,
        css,
      ]}
    />
  );
}

For reusable components, Fluentic can go further with tokens, slots, scopes, and combineStyle(...).

import {
  style,
  createTokens,
  combineStyle,
  bindScope,
  type StyleProp,
  type StyleTheme,
} from '@fluentic/style';

const button = createTokens({
  color: {
    surface: '#2563eb',
    surfaceHover: '#1d4ed8',
    text: '#ffffff',
    dangerSurface: '#dc2626',
  },
  space: {
    gap: 8,
    paddingInline: 12,
  },
});

const buttonStyles = {
  root: style.slot({
    display: 'inline-flex',
    alignItems: 'center',
    gap: button.space.gap,
    border: 0,
    borderRadius: 8,
    paddingBlock: 8,
    paddingInline: button.space.paddingInline,
    backgroundColor: button.color.surface,
    color: button.color.text,
  }).hover({
    backgroundColor: button.color.surfaceHover,
  }),

  icon: style.slot({
    display: 'inline-flex',
    width: 16,
    height: 16,
  }),

  label: style.slot({
    fontWeight: 650,
    lineHeight: 1,
  }),
};

type ButtonProps = {
  children: React.ReactNode;
  css?: StyleProp;
  icon?: React.ReactNode;
  theme?: StyleTheme;
};

function BaseButton(props: ButtonProps) {
  const css = combineStyle(
    buttonStyles,
    bindScope(buttonStyles.root, props.theme),
  );

  return (
    <button css={[css.root, props.css]}>
      {props.icon ? <span css={css.icon}>{props.icon}</span> : null}
      <span css={css.label}>{props.children}</span>
    </button>
  );
}

Then variants can target public slots and component tokens instead of reaching through DOM structure:

const dangerButton = style.scope([
  button.color.surface(button.color.dangerSurface),

  buttonStyles.label({
    fontWeight: 700,
  }),
]);

const compactButton = style.scope([
  buttonStyles.root({
    gap: 6,
    paddingBlock: 6,
    paddingInline: 10,
  }),

  buttonStyles.label({
    fontSize: 13,
  }),
]);

function Button({
  danger,
  compact,
  theme,
  ...props
}: ButtonProps & {
  danger?: boolean;
  compact?: boolean;
}) {
  return (
    <BaseButton
      {...props}
      theme={[
        danger && dangerButton,
        compact && compactButton,
        theme,
      ]}
    />
  );
}

At the app level, values can stay readable while still being themeable.

import { createTheme, createValues, style } from '@fluentic/style';

const color = createValues([
  '#2563eb | Accent',
  '#1d4ed8 | AccentHover',
  '#ffffff | AccentText',
]);

const darkTheme = createTheme([
  color('#2563eb | Accent', '#60a5fa'),
  color('#1d4ed8 | AccentHover', '#93c5fd'),
  color('#ffffff | AccentText', '#0f172a'),
]);

Then the app can map those values into the component’s exposed tokens through a component theme:

const appButtonTheme = style.scope([
  button.color.surface(color('#2563eb | Accent')),
  button.color.surfaceHover(color('#1d4ed8 | AccentHover')),
  button.color.text(color('#ffffff | AccentText')),
]);

function App() {
  return (
    <main css={darkTheme}>
      <Button theme={appButtonTheme}>
        Save
      </Button>
    </main>
  );
}

The app theme decides what the app values become.

The component theme decides how this button connects to those values.

The component itself stays explicit about the parts and tokens it exposes.

The important part is not only the exact syntax.

The important part is the styling approach:

styles are defined as values
styles are composed explicitly
conditional styles are visible
component parts can be named with slots
variants can target slots without depending on DOM structure
app and component themes can be prepared early without becoming a separate styling system
selectors are available, but they are not the whole styling model
CSS is extracted for production builds
debugging should lead back to the React code, not stop at a generated class name

That is the balance I want.

React Native simplicity.

CSS power.

Modern React output.

A styling system where the everyday path stays simple, explicit when the component grows and prepared for the app-level concerns that usually arrive later.

Why Not Just Use Existing Tools?

This is a fair question.

There are many good styling tools now.

Some are utility-first.

Some are CSS-in-TypeScript.

Some are zero-runtime.

Some are compiler-first.

Some are design-system focused.

Some are close to CSS Modules with better ergonomics.

I am not building Fluentic because I think all of them are bad.

I am building it because I want a very specific feel.

The feel of React Native style composition, adapted to React web.

The thing I miss is not only extraction, type safety, or colocated styles.

It is the simple confidence of this line:

style={[base, variant, state, props.style]}

That mental model has been living rent-free in my head for years.

When I came back to React web, I wanted that feeling again.

But I also wanted hover, focus, media queries, selectors, SSR, extraction, component slots, and CSS output.

So Fluentic is my attempt to connect those worlds.

What I Am Trying To Avoid

Fluentic is also shaped by the things I want to avoid from my own past web code.

I want to avoid class names becoming a private styling API between parent and child components.

I want to avoid parent styles reaching too deeply into child structure.

I want to avoid selectors that make markup hard to change.

I want to avoid styling systems where I cannot easily answer “which style wins?”

I want to avoid too much runtime styling work.

I want to avoid cleverness that feels good today and suspicious six months later.

That last one is important.

A lot of styling decisions feel great when writing them.

The real test is how they feel when changing them later.

Fluentic Is Still Early

Fluentic is still early.

I am still exploring the API, constraints, compiler behavior, and the right balance between CSS power and React Native-like explicitness.

But the direction is clear:

React styling should feel more like composing values, and less like maintaining invisible relationships between class names and DOM structure.

That is the idea I want to test.

Not whether CSS can do everything. It can.

Not whether extraction is useful. It is.

The question is:

Can styling for component-heavy React apps feel predictable again?

Can we keep the parts of CSS that make the web powerful, while making everyday component styling feel closer to the React Native model?

That is what I am building with Fluentic.

You can check out Fluentic here:

GitHub: https://github.com/fluentic-dev/style
Docs: https://fluenticstack.com/style

If this problem feels familiar, especially if you have worked on both React web and React Native apps, I’d love to hear what you think.

Which parts of React styling become harder to change over time?

Which parts of React Native styling do you wish existed on React web?

And what component-styling cases should Fluentic cover next?

That feedback would be much more useful than stars alone, though I will not pretend stars hurt.

DEV Community: OmniDev

Building Fluentic Style: Styling DOM You Do Not Own With `createSheet`

The Normal Fluentic Flow

Third-Party DOM Has A Different Boundary

Naming Third-Party Parts

Attaching The Sheet To A Wrapper

Why This Is Not Just Global CSS Again

Why Not Just Use className?

Sheets Can Compose

Local Themes For Third-Party Components

Same Element Selectors

Portal Menus

Optional Same-Or-Descendant Matching

Guardrails

What About Library CSS?

Debugging Still Matters

When To Use createSheet

Why This Became Its Own API

Docs

Building Fluentic Style: Why `combineStyle` Became More Than A Merge Helper

The Simple Version Is Always Fine

Then The Component Becomes Reusable

The First Idea Was A Hook

The Fluentic Version

Why bindScope Matters Here

The Difference In JSX

The Cache Question

Production Should Not Pay For Dev-Time Work

Why This Became The Handoff Point

Docs

Beyond CSS-in-JS: From Element Styles To Component Themes

The Problem Is Not Only Putting CSS In JS

Start With One Element

Then The Element Becomes A Component

Component Themes Are Not The Same As App Themes

App-Wide Themes Need A Different Layer

Variants Become Scopes Too

Debugging Still Has To Follow The Whole Path

Production Extraction Should Fit The Same Model

Syntax Should Be Flexible, But The Path Should Stay Connected

Frameworks Need Bridges, Not A New Styling Model

What Fluentic Currently Has

Closing

Building Fluentic Style: Rethinking How Outside Styles Reach Inside Components

Components Change The Unit

The Usual Ways We Handle This

Co-Location Helps, But It Solves A Different Layer

A Card Component Starts Simple

Change Public Parts To Slots

Add A Theme Prop

Scopes Are Outside Styles For Slots

Scopes Can Change Multiple Parts Together

Scopes Compose

Scopes Can Have State And Media Conditions

Why This Is Not Just Class Names Again

The Public API Gets Smaller

Debugging Still Has To Work

Production Still Gets CSS

The Part That Feels New

The Result

Building Fluentic Style: The Anatomy of Debuggable Atomic CSS

Atomic CSS Has An Ugly Side

But DevTools Does Not Debug CSS As A Component Class

Grouped CSS Makes This Harder

The Hidden Problem With Dedupe

A Fluentic Atomic Rule Is More Than CSS Text

Selector Context Has To Survive Too

Priority Is Part Of Debugging Too

Slots And Scopes Need Source Identity Too

Debug Class Names Help, But They Are Not Enough

Atomic CSS Is Output, Not The Authoring Model

Dev And Prod Use Atomic CSS Differently

Why This Made Debugging Feel Possible

The Tradeoff

The Result

Building Fluentic Style: Bringing the `css` Prop to SolidJS

The Feature

Why Solid Needed A Different Path

The Small Transform

What Gets Rewritten

Why Not Just Use `className`?

When To Use `createSheet`

Why `bindScope` Matters Here

Why Not Just Set `class`?

Existing `class`, `style`, And Spreads Still Matter

Class-Name Chains: Custom Names With `createClassNameFn`