DEV Community: OmniDev

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: CSS Rule Order Should Not Feel Like Astrology

The Simple Case Is Easy

Then States Start Fighting

Semantic States Make This More Important

Custom Selector Priority

Priority Is Not A Single Flat Number

Base, Media, And State Are Different Buckets

Parent State And Direct State Are Different Too

Value Weight Is The Escape Hatch

Property Order Still Matters

Layers Or Sorted Output In Development

Dedupe Is Good, But Confidence Needs Order

Where This Leaves Fluentic

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

The Goal Was Not A Special Next.js API

Next.js Splits The Debugging Problem In Two

Why RSC Makes This Awkward

Some Simpler Approaches Are Not Enough

Part One: Seed CSS For The Initial HTML

Part Two: Send Debug Payloads Through The DOM

Part Three: The Client Observer Picks It Up

Why A MutationObserver?

Why This Keeps HMR Smooth

Debug Metadata Survives The Server/Client Trip

Element Markers Still Work

StyleDevUtils Still Feels Like The Client App

The Next Plugin Wires The Build System Parts

Sourcemaps Need More Than CSS Text

Production Is A Different Mode

Runtime-Known Values Still Work

Why This Was Hard To Get Right

Why Not Stay SPA-Only?

Where This Leaves The Integration

What Comes Next

Building Fluentic Style: Making Generated CSS Debuggable Again

Atomic CSS Should Not Sacrifice Sourcemaps

Readable Names Are Helpful, But Not Enough

Debugging Starts From The Browser

Property-Level Sourcemaps

Chain Calls Need Their Own Context

Element Markers: From DOM Back To JSX

Spread And Merge Need Two Debug Views

Slots And Scopes Should Not Become Anonymous

Tokens Are The One I Still Want To Improve

Dev Utilities Should Be Normal DevTools-Friendly

Runtime-Only Development Still Has A Trace Path

React Server Components Need Debugging Too

Why This Works: Identity Survives Long Enough

The Tradeoff I Wanted

What Comes Next

Building Fluentic Style: Behind the Tailwind Presets

The Tailwind Presets Are Built On Public Pieces

Two Inputs, Same Fluentic Path

Object Chains: Custom Fields With Pure TypeScript

Class-Name Chains: Custom Names With createClassNameFn

Custom Chain Methods Are Where It Gets Interesting

The Same Selector Methods Work For Class Names

Why This Reduces Limits

Extraction And Debugging Still Matter

Where This Leaves The Tailwind Presets

Building Fluentic Style: I Didn’t Want a Tailwind Preset. Then I Added Two.

The First Preset Was Object-Based

So I Added A Class-Name Preset Too

The Part That Changed My Mind

Why Not Just Use Tailwind?

Where This Leaves Fluentic

Building Fluentic Style: Bringing React Native Style Composition to React

The Problem Was Confidence

Then I Spent Years in React Native

React Web Has Something React Native Misses

Extraction Is Not the New Idea

What I Want From a Styling System

1. Styles Should Be Values

2. Override Order Should Be Obvious

3. Variants Should Be Explicit

4. Reusable Components Need More Than Root Styling

5. Selectors Should Exist, But They Should Not Become the Whole Model

6. Runtime Work Should Be Small

7. Debugging Should Lead Back to the Code

Class-Name Chains: Custom Names With `createClassNameFn`