DEV Community: Maxim Procopenco

Delete your z-index scale

Maxim Procopenco — Tue, 20 Oct 2026 07:27:08 +0000

A menu cut off by its card or buried under a sticky header is a stacking bug the browser can now fix for you, with no portal and no z-index scale. Here is the fix, what we measured in Chrome, and where it still falls short.

The examples here are screenshots; they run live in the original article.

The problem

Your card has overflow: hidden, so its menu is clipped at the edge. You make the menu position: fixed, and then the card gets a hover transform, which makes the card the menu's containing block again. The page's sticky header covers it, and z-index: 9999 does nothing, because the transform created a stacking context the 9999 can't leave.

The CSS issue asking for a way out of overflow: hidden has been open since 2019. Most React apps settled on a portal to <body> plus a scale:

:root {
  --z-dropdown: 1000;
  --z-modal: 1050;
  --z-popover: 1070;
  --z-tooltip: 1080;
  --z-toast: 1090;
}

The portal works, but the layer leaves the subtree it was declared in:

A dark section's theme, a custom property or a dir stops reaching it.
Tab from the trigger skips the layer, which now sits at the end of <body>.
A dropdown inside a popover is portalled out of it, so picking an option counts as a press outside and closes the popover.
React events still bubble through the React tree, which React's own issue has tracked since 2017.

The fix: the top layer and anchor positioning

An element with the popover attribute is shown in the browser's top layer. It paints above every stacking context, ignores every ancestor's overflow, and isn't positioned by a transformed ancestor. z-index doesn't apply there: the last layer opened is on top. Anchor positioning then places it beside its trigger in CSS and flips it when there's no room.

The important part is that the layer stays where you declared it in the DOM, so every portal cost above disappears. Support: the Popover API is in Chrome 114, Firefox 125 and Safari 17. Anchor positioning is in Chrome 125, Firefox 147 and Safari 26.

In Box Kite that is <Popover>. The card below clips its content, and a sibling sits on top of it with z-index: 9999:

import Box from '@box-kite/react';
import Button from '@box-kite/react/components/button';
import Checkbox from '@box-kite/react/components/checkbox';
import Flex from '@box-kite/react/components/flex';
import Popover from '@box-kite/react/components/popover';

export function FilterCard() {
  return (
    <Box>
      <Box overflow="hidden" translateY={-1} p={4} b={1} borderColor="base-300" borderRadius={3}>
        <Popover label="Filters" align="start" trigger={(trigger) => <Button {...trigger}>Filters</Button>}>
          <Flex d="column" gap={2}>
            <Checkbox label="Only mine" />
            <Checkbox label="Has attachments" />
          </Flex>
        </Popover>
      </Box>
      <Box position="relative" css={{ zIndex: 9999 }} mt={2} p={3} borderRadius={2} bgColor="red-500" color="white" textAlign="end">
        A sibling with z-index: 9999
      </Box>
    </Box>
  );
}

No portal, no z-index. The panel is a named role="dialog", and the trigger carries aria-expanded and aria-controls. Focus moves into the panel, Escape closes it and returns focus to the trigger, and a press outside closes it too.

Every layer works this way

Tooltip, Menu, the Dropdown popup, Dialog, the toasts, the date pickers and the DataGrid's column menu are all in the top layer, and none of them is portalled. Here they are in a dark, clipped, transformed toolbar on a light page, with the dropdown open inside the Filters popover:

import Box from '@box-kite/react';
import Button from '@box-kite/react/components/button';
import Dropdown from '@box-kite/react/components/dropdown';
import Flex from '@box-kite/react/components/flex';
import Menu from '@box-kite/react/components/menu';
import Popover from '@box-kite/react/components/popover';
import Tooltip from '@box-kite/react/components/tooltip';

export function Toolbar() {
  return (
    <Box.Theme use="local" theme="dark">
      <Flex gap={2} p={4} borderRadius={3} overflow="hidden" translateY={-1} bgColor="slate-900">
        <Popover label="Filters" align="start" trigger={(trigger) => <Button {...trigger}>Filters</Button>}>
          <Dropdown label="Owner" defaultValue="ada">
            <Dropdown.Item value="ada">Ada</Dropdown.Item>
            <Dropdown.Item value="grace">Grace</Dropdown.Item>
          </Dropdown>
        </Popover>
        <Tooltip content="Deletes the row for good">{(trigger) => <Button {...trigger}>Delete</Button>}</Tooltip>
        <Menu trigger={(trigger) => <Button {...trigger}>Actions</Button>}>
          <Menu.Item>Duplicate</Menu.Item>
          <Menu.Item>Archive</Menu.Item>
        </Menu>
      </Flex>
    </Box.Theme>
  );
}

The panels are dark because they inherit the section's theme; nothing was copied across. Picking an owner leaves the Filters panel open, because the dropdown's list is still a DOM child of the panel.

Writing your own layer

The same thing by hand is a handful of props. One line is a trap: the browser hides a closed popover with a rule any author display outranks, and every Box sets display. Without not={{ open: { display: 'none' } }}, the closed panel stays on the page.

import Box from '@box-kite/react';
import Button from '@box-kite/react/components/button';

export function RowActions() {
  return (
    <>
      <Button anchorName="row-actions" props={{ popoverTarget: 'row-actions-panel' }}>
        Actions
      </Button>
      <Box
        id="row-actions-panel"
        position="fixed"
        positionAnchor="row-actions"
        positionArea="block-end span-inline-end"
        positionTryFallbacks="flip-block"
        mt={2}
        p={4}
        not={{ open: { display: 'none' } }}
        props={{ popover: 'auto' }}
      >
        Anything at all
      </Box>
    </>
  );
}

That gives you the paint, the placement and light dismiss, but no role, name or focus handling. Overlay and useAnchorPosition cover the placement for a layer that isn't one of the patterns above.

The honest limits

All measured in Chrome 155:

On top means on top of everything. Once its trigger scrolls under a sticky header, an open panel still paints above the header.
An open layer doesn't re-flip on scroll. Chrome never re-runs position-try-fallbacks for a top-layer element. A panel opened below its trigger stayed below as we scrolled, and ran off the bottom of the window. Reopening it picks the right side.
A toast fired from inside a modal lands under it. It's dimmed, can't be pressed or focused, and is missing from the accessibility tree. Part of that is the platform: everything outside an open modal is inert, even a popover above it. We found this writing the article, and the fix is on the roadmap. Until then, show the result inside the dialog, or toast after it closes.
Older browsers get the old trade-offs. Without anchor positioning the layer is placed by measuring in JavaScript. Without the Popover API it falls back to a portal.
Never declare a layer inside its trigger. A menu inside a <button> can't be reached with the keyboard. Put it beside the trigger.

Try it

Popover, Menu and Dialog: the patterns and their keyboard maps.
Anchor positioning: the props and the hook.
npm install @box-kite/react, then delete one portal and one z-index and see what still needs them.

Originally published on box-kite.dev. Box Kite is open source under MIT — if it is useful to you, a star on GitHub helps other people find it. Install it with npm install @box-kite/react.

Your first web page with Box Kite

Maxim Procopenco — Tue, 13 Oct 2026 06:45:49 +0000

This guide takes you from an empty folder to a responsive landing page with a dark mode, live on the internet, without writing a single CSS file. You need Node.js installed and a terminal; knowing a little HTML helps, and knowing React is not required — the page is small enough to read line by line.

Box Kite is a React library where every CSS property is a typed prop. Instead of writing a class name in one file and its rules in another, you write p={6} or bgColor="indigo-600" on the element itself, and the library generates the CSS for you. Your editor autocompletes every name and every value, and a typo is an error before the page ever runs.

Step 1: create the app

Open a terminal in the folder where you keep your projects and run:

npm create vite@latest my-site -- --template react-ts
cd my-site
npm install
npm install @box-kite/react
npm run dev

The first command creates a React app with TypeScript, the fourth adds Box Kite, and the last one starts a development server. Open the address it prints (usually http://localhost:5173) and you will see Vite's starter page.

There is nothing else to set up: no configuration file, no plugin, no stylesheet to import. Delete src/App.css and src/index.css, remove the line importing index.css from src/main.tsx, and the app is ready.

Step 2: tell your AI assistant about it (optional, but do it)

If you write code with an AI assistant — Claude Code, Cursor, Copilot, Codex — this step matters more than any other. Box Kite's prop names look like props from other libraries, but the numbers mean different things, and an assistant writing from memory will guess wrong.

The package carries its own instructions. Add a line to your project's AGENTS.md (or CLAUDE.md) pointing at them:

Before writing UI code, read node_modules/@box-kite/react/AGENTS.md.

Two more things make an assistant noticeably better at it. The skill teaches the rules to most coding agents in one command, and the MCP server lets the assistant ask the library itself what CSS a prop produces before it writes one:

npx skills add box-kite/box-kite
claude mcp add box-kite -- npx -y @box-kite/mcp

The second line is for Claude Code; the Built for AI page has the same setup for every other assistant. If you would rather let the assistant build the whole page, Start with AI has prompts to paste — this guide is the version where you see every line.

Step 3: put something in the middle of the screen

Replace everything in src/App.tsx with this:

import Flex from '@box-kite/react/components/flex';
import { H1, P } from '@box-kite/react/components/semantics';

export default function App() {
  return (
    <Flex d="column" ai="center" jc="center" gap={4} minHeight="fit-screen" p={6}>
      <H1 fontSize={48} fontWeight={700}>
        Hello, world
      </H1>
      <P fontSize={18} color="slate-600">
        My first page with Box Kite.
      </P>
    </Flex>
  );
}

Save, and the heading sits in the middle of the window. Three things are worth noticing:

Flex is a component, not a setting. It renders a <div> laid out with flexbox. d="column" stacks the children, ai="center" centres them across, jc="center" centres them along. H1 and P render a real <h1> and <p>, which matters for search engines and screen readers.
Spacing is a scale of 4. gap={4} is 16px and p={6} is 24px: every step is a quarter of a rem. You think in a grid of 4px and never type a unit.
fontSize is the exception: it is in pixels. fontSize={48} is 48px. This is the one number that catches people out, which is why it is in the rules your assistant reads.

Step 4: make it work on a phone

A layout that looks right on a laptop usually needs less padding and a smaller heading on a phone. In Box Kite a screen size is a prop that takes the props to use from that width up:

import Flex from '@box-kite/react/components/flex';
import { H1, P } from '@box-kite/react/components/semantics';

export default function App() {
  return (
    <Flex d="column" ai="center" jc="center" gap={4} minHeight="fit-screen" p={6} md={{ p: 12 }}>
      <H1 fontSize={32} md={{ fontSize: 48 }} fontWeight={700} textAlign="center">
        Hello, world
      </H1>
      <P fontSize={18} color="slate-600">
        My first page with Box Kite.
      </P>
    </Flex>
  );
}

Write the phone version first, then say what changes on a bigger screen: md means 768px wide and up, so the heading is 32px on a phone and 48px on a laptop. Narrow the browser window and watch it change. The other sizes are sm, lg, xl and xxl, and they all work the same way.

Step 5: a row of cards and a button

Most landing pages are a heading, a few cards and a call to action. Cards are a grid; a button is a Button:

import Box from '@box-kite/react';
import Button from '@box-kite/react/components/button';
import Flex from '@box-kite/react/components/flex';
import Grid from '@box-kite/react/components/grid';
import { H1, H2, P } from '@box-kite/react/components/semantics';

const features = [
  { title: 'Fast', text: 'Pages that load before you finish blinking.' },
  { title: 'Simple', text: 'Every style lives on the element it styles.' },
  { title: 'Typed', text: 'A misspelt colour is an error, not a surprise.' },
];

export default function App() {
  return (
    <Flex d="column" ai="center" gap={10} p={6} md={{ p: 12 }}>
      <H1 fontSize={32} md={{ fontSize: 48 }} fontWeight={700} textAlign="center">
        Hello, world
      </H1>

      <Grid gridTemplateColumns={1} md={{ gridTemplateColumns: 3 }} gap={6} maxWidth={240} width="fit">
        {features.map((feature) => (
          <Box key={feature.title} p={6} borderRadius={3} b={1} borderColor="slate-200" hover={{ borderColor: 'indigo-400', shadow: 'md' }}>
            <H2 fontSize={20} fontWeight={600} mb={2}>
              {feature.title}
            </H2>
            <P color="slate-600">{feature.text}</P>
          </Box>
        ))}
      </Grid>

      <Button px={6} py={3} fontWeight={600}>
        Get started
      </Button>
    </Flex>
  );
}

One column on a phone, three from 768px up. b={1} is a 1px border — border widths are in pixels, like fontSize — and borderRadius={3} is on the spacing scale, so 12px. hover={{ borderColor: 'indigo-400', shadow: 'md' }} is what a card looks like while the pointer is over it: a state is a prop holding the props for that state, the same shape as md.

Button comes styled — indigo, a shade darker on hover, a focus ring for keyboard users, and adjusted for dark mode — so it needs only the props you want to change.

The colours are a palette: slate, indigo, sky, emerald, rose and the rest, each from 50 (lightest) to 950 (darkest). Type bgColor=" in your editor and it lists them all.

Step 6: add a dark mode

A dark mode is two things: the colours each element uses in the dark, and something that decides which one is showing. The first is a theme prop on any element; the second is Box.Theme, once, around the app.

In src/main.tsx, wrap the app:

import Box from '@box-kite/react';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <Box.Theme use="global" storageKey="theme">
      <App />
    </Box.Theme>
  </StrictMode>,
);

Then give the page its two sets of colours, and a button to switch:

import Box from '@box-kite/react';
import Button from '@box-kite/react/components/button';
import Flex from '@box-kite/react/components/flex';
import { H1 } from '@box-kite/react/components/semantics';

function ThemeButton() {
  const [theme, setTheme] = Box.Theme.useTheme();

  return <Button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>{theme === 'dark' ? 'Light mode' : 'Dark mode'}</Button>;
}

export default function App() {
  return (
    <Flex
      d="column"
      ai="center"
      gap={6}
      minHeight="fit-screen"
      p={6}
      theme={{
        light: { bgColor: 'white', color: 'slate-900' },
        dark: { bgColor: 'slate-950', color: 'slate-100' },
      }}
    >
      <ThemeButton />
      <H1 fontSize={32} fontWeight={700}>
        Hello, world
      </H1>
    </Flex>
  );
}

On its first visit the page follows the operating system's setting. Once someone presses the button, storageKey="theme" remembers their choice for the next visit. Any element can carry a theme prop, so a card can say theme={{ dark: { borderColor: 'slate-800' } }} and nothing else.

If you later render your pages on a server and want the right theme on the very first frame, the dark mode article explains the one extra script that takes.

Step 7: when a prop does nothing, read the console

Sooner or later you will write a prop that has no effect. In development, Box Kite says so in the browser console, and says what to write instead:

[box-kite] fontSize={4} is 4px text: fontSize's divider is 16, not the spacing scale's 4, so the number is the pixel size. For 16px write fontSize={16}.
[box-kite] href is an HTML attribute, not a style prop, so at the top level it was dropped: write props={{ href: ... }}.

The second one is the other rule worth learning early: HTML attributes (href, id, type, aria-label) go in a props object, because every top-level prop is a style. A link is written like this:

import { Link } from '@box-kite/react/components/semantics';

export function Docs() {
  return (
    <Link props={{ href: 'https://www.box-kite.dev' }} color="indigo-600" textDecoration="underline">
      Read the docs
    </Link>
  );
}

And a misspelt colour never gets as far as the console — bgColor="bleu-500" is a TypeScript error the moment you type it.

Step 8: put it on the internet

Stop the development server and build the site:

npm run build

Vite writes the finished site into a dist folder: an index.html and a few JavaScript files. Any static host serves it. The quickest is Netlify Drop — drag the dist folder onto the page and you get a public address in seconds. GitHub Pages and Cloudflare Pages work the same way once the project is in a repository.

There is no stylesheet to upload and nothing to configure on the host: the CSS is generated by the page as it runs.

What you learned

Every CSS property is a prop, and its name and values autocomplete. There are no CSS files.
Layout is Flex and Grid; text is H1, P and the other semantic elements.
Spacing and corners are a scale of 4 (p={4} is 16px); font sizes and border widths are pixels.
A screen size (md), a state (hover) and a theme (theme={{ dark: … }}) are props that hold more props.
HTML attributes go in props, and the console tells you when a prop did nothing.

Where to go next

The playground — change props and watch the CSS they write.
Box — every prop, searchable, with the CSS each one produces.
Components — dialogs, menus, tabs, forms and a data grid, all keyboard-accessible.
Start with AI — the same page, written by your assistant from a few prompts.

Originally published on box-kite.dev. Box Kite is open source under MIT — if it is useful to you, a star on GitHub helps other people find it. Install it with npm install @box-kite/react.

Why I Chose TypeScript Over Tailwind and Built My Own React Styling Library

Maxim Procopenco — Tue, 03 Mar 2026 10:36:04 +0000

My name is Maxim. I've been a full-stack software engineer for my entire career. And on June 4, 2022, I made an initial commit to a repo called react-box.

I wasn't planning to build an open source library. I was deep in a project, writing React components day after day, and I kept noticing the same pattern: I'd build a component, then go create a CSS file for it. Or wrap it in styled-components. Or write a long chain of Tailwind classes. Every time, I felt like I was leaving TypeScript's world — the world where my editor knows everything, catches my mistakes, and guides me — to enter a world of strings where anything goes and nothing is checked.

So I started extracting something. Not for GitHub stars. Not for a product launch. Just because I was tired of repeating myself. That extraction became @cronocode/react-box — a React component library where every CSS property is a typed prop.

Why Not Tailwind?

I want to be clear: Tailwind is a great tool. It solved a real problem for millions of developers, and I respect that.

But here's the thing — I was already living inside TypeScript. My IDE already knew my types. It autocompleted my function arguments, caught typos at compile time, and told me when I passed the wrong value. So why, the moment I needed to style something, was I suddenly writing untyped strings in a className attribute?

Tailwind turns CSS into utility classes. I wanted to turn CSS into typed function arguments.

Here's the difference in practice:

// Tailwind approach
<div className="flex items-center gap-4 p-6 bg-indigo-500
  text-white rounded-lg hover:bg-indigo-600
  md:p-8 md:gap-6">
  Content
</div>

// React Box approach
<Flex ai="center" gap={4} p={6} bgColor="indigo-500"
  color="white" borderRadius={8}
  hover={{ bgColor: 'indigo-600' }}
  md={{ p: 8, gap: 6 }}>
  Content
</Flex>

In the second version, every prop name and every value gets autocomplete. If I type bgColor="indgo-500" — that's a compile error. Hover states and responsive breakpoints are structured objects, not string prefixes. TypeScript understands the whole thing.

I didn't choose this path because Tailwind is wrong. I chose it because TypeScript was already there, and it felt wrong not to use it.

The Anatomy of Box

At the heart of the library is a single component called Box. It accepts around 144 CSS properties as typed props and renders any HTML element you need.

The simplest usage looks like this:

import Box from '@cronocode/react-box';

<Box p={4} bgColor="blue-500" color="white" borderRadius={8}>
  Hello World
</Box>

No CSS file. No styled-components setup. No theme provider required. Just import and go. That p={4} becomes padding: 1rem (16px) — the library uses a divider system where spacing values divide by 4 to produce rem units, so you think in a consistent 4px grid.

But you don't use raw Box for everything. The library ships with semantic components that map to the right HTML elements:

import Flex from '@cronocode/react-box/components/flex';
import Button from '@cronocode/react-box/components/button';
import { H1, P } from '@cronocode/react-box/components/semantics';

<Flex d="column" gap={4}>
  <H1 fontSize={32} fontWeight={700}>Welcome</H1>
  <P color="gray-600">Build UIs with type-safe props.</P>
  <Button hover={{ bgColor: 'indigo-700' }}>
    Get Started
  </Button>
</Flex>

Flex renders a div with display: flex. H1 renders an h1. Button renders a button. Each one accepts the full set of Box props with complete TypeScript support. There are 17 semantic HTML wrappers — H1 through H6, P, Span, Nav, Header, Footer, Link, Img, and more.

Now here's where it gets interesting. Hover states, responsive breakpoints, and dark theme styles all compose as nested objects:

<Box
  p={4}
  bgColor="white"
  hover={{ bgColor: 'gray-100' }}
  md={{ p: 8, hover: { bgColor: 'gray-200' } }}
  theme={{
    dark: {
      bgColor: 'gray-900',
      hover: { bgColor: 'gray-800' },
    },
  }}
/>

This is a single component that handles base styles, hover state, medium breakpoint, medium breakpoint hover, dark theme, and dark theme hover — all as a typed, nested object. No string concatenation. No utility class combinations to memorize. TypeScript tells you what's valid at every nesting level.

Under the Hood

The styling engine works differently from what you might expect. When you write p={4}, the library doesn't set an inline style. Instead, it generates a short CSS class name (like ._2a) and a corresponding CSS rule (._2a { padding: 1rem }), then injects it directly into the browser's CSSOM using CSSStyleSheet.insertRule(). Not innerHTML — direct stylesheet manipulation.

The key insight is deduplication. If 50 components across your app all use p={4}, there's still only one CSS rule. An internal IdentityFactory ensures each unique value gets exactly one class. Your stylesheet stays small no matter how many components you have.

The library ships with 200+ color variables (a Tailwind-like palette), but they're loaded lazily. Navigate to a page that uses violet-500 for the first time? The CSS variable gets injected on the fly. Colors you never use never touch the DOM.

And there's no build step for styles. It works with Vite, Webpack, Next.js — whatever you use. npm install @cronocode/react-box and you're done. The entire main Box component is 99 lines of code.

Making It Yours

The library is designed to be extended, not forked. Box.extend() lets you add custom CSS variables and new props:

import Box from '@cronocode/react-box';

Box.extend(
  { 'brand-primary': '#ff6600' },  // Custom CSS variables
  {},                                // New props
  {
    bgColor: [{
      values: ['brand-primary'] as const,
      styleName: 'background-color',
      valueFormat: (value, getVar) => getVar(value),
    }],
  },
);

// Now this works with full autocomplete:
<Box bgColor="brand-primary" />

And Box.components() lets you define design system components with variants:

Box.components({
  card: {
    styles: { display: 'flex', d: 'column', p: 4, borderRadius: 8, shadow: 'medium' },
    variants: {
      bordered: { b: 1, borderColor: 'gray-200', shadow: 'none' },
      elevated: { shadow: 'large' },
    },
  },
});

<Box component="card" variant="bordered">Content</Box>

You get a type-safe component system on top of a type-safe styling system. The theme system supports light/dark mode with auto-detection from system preferences, and you can scope theme styles to individual components or apply them globally.

Over time, I also built higher-level components: a full DataGrid with sorting, filtering, column grouping, row selection, and virtualization. A Dropdown with multi-select. A Tooltip that uses portals to escape overflow containers. Each one is a separate entry point for tree-shaking — you only ship what you use.

Teaching AI to Use It

Here's something I didn't expect to build: an AI context document.

In 2025, I realized that a growing share of code in my projects was being written by AI assistants. And they kept getting my library wrong — using inline styles instead of Box props, writing <Box tag="button"> instead of <Button>, confusing the numeric formatters (fontSize divides by 16, spacing divides by 4).

So I wrote BOX_AI_CONTEXT.md — a comprehensive reference document that ships with the npm package. It contains every prop, every formatter rule, every "do this, not that" pattern. It starts with the two most common AI mistakes in bold: never use inline styles and always use component shortcuts.

Not many npm packages ship with AI-readable documentation as a first-class feature. But in 2026, if your library doesn't explain itself to AI, half the code written against it will be wrong. I'd rather teach the machine once than fix its output every time.

Does It Make Sense?

I'll be honest — I don't know if anyone will use this. In a world where Tailwind dominates and AI writes more code every day, maybe the tool you use to style components matters less than ever. Maybe more.

But I know this: I built something that solved my problem. I extracted it from my daily work, documented it, published it 169 times, and wrote an AI context document so that even the machines could understand it. I made it open source not because I expect stars, but because that's what you do when you build something useful — you share it.

There's a special kind of freedom in building your own tools. You make every decision. You own every trade-off. You don't wait for a PR to be approved by a framework team. You just build the thing the way you think it should work, and then you use it every day to see if you were right.

Sometimes you were. Sometimes you ship version 170 to fix what version 169 got wrong. And that's fine. That's the work.

If you're curious, take a look:

Website: box.cronocode.com
GitHub: github.com/cronocodesolutions/react-box
npm: @cronocode/react-box

Or don't. Just go build something of your own. That's the whole point.

Tags: #react #typescript #css #opensource