box-kite

# Box Kite

[![npm](https://img.shields.io/npm/v/@box-kite/react)](https://www.npmjs.com/package/@box-kite/react)
[![bundle size](https://img.shields.io/bundlephobia/minzip/@box-kite/react)](https://bundlephobia.com/package/@box-kite/react)
[![Tests](https://github.com/box-kite/box-kite/actions/workflows/test.yml/badge.svg)](https://github.com/box-kite/box-kite/actions/workflows/test.yml)
[![license](https://img.shields.io/npm/l/@box-kite/react)](LICENSE)

`Box` is a single React component with 235 typed CSS props. It generates the CSS for the values you
pass at runtime and caches every rule by its content, so the same value anywhere in the app reuses
one class — a project styles itself in TypeScript, with no CSS files to write and no class-name
convention to remember.

[Docs and live demos](https://www.box-kite.dev) · [Blog](https://www.box-kite.dev/blog/) · [Contributing](CONTRIBUTING.md) ·
[Support](SUPPORT.md) · [Security](SECURITY.md) ·
[Releases](https://github.com/box-kite/box-kite/releases)

**Built to be written by an AI.** The rules, every prop with the CSS it emits and a docs folder are
inside the package, generated from the prop registry itself — so what your agent reads is never a
version behind what it is writing against: [Built for AI](https://www.box-kite.dev/ai-context/) ·
[`npx @box-kite/mcp`](https://www.npmjs.com/package/@box-kite/mcp) ·
[generative UI](https://www.box-kite.dev/generative-ui/)

## Getting Started

1. Installation

```bash
npm install @box-kite/react
```

React 16.14 or newer, including 18 and 19 (both are covered by CI). TypeScript is optional but the
props are typed for it.

Two packages ship, and a React project installs one of them:

| Package                                           | What it is                                                        |
| ------------------------------------------------- | ----------------------------------------------------------------- |
| **`@box-kite/react`**                             | `Box`, every component, the hooks. Depends on the one below.      |
| [`@box-kite/core`](#using-the-core-without-react) | The engine and the types, no framework. For an app with no React. |

`@box-kite/core/types` is where a project declares its own props and components — the augmentation
target lives with the prop registry it extends, not with a binding.

2. Use it

Spacing counts in quarters of a rem: `p={3}` is `0.75rem`, `m={2}` is `0.5rem`. The example below is
a box with `margin: 0.5rem` and `padding: 1.75rem`.

```JS
import Box from "@box-kite/react";

export default function Component(props: Props) {
  return (
    <Box className="custom-class" m={2} p={7}>
      basic example
    </Box>
  );
}
```

**NOTE**: the root `font-size` is `16px`, so a quarter of a rem is 4px. Not every prop divides by
four — `fontSize` divides by 16 (`fontSize={14}` is `0.875rem`), and border widths and `lineHeight`
are plain pixels (`b={1}` is 1px).

There is nothing to memorise, though: every prop's hover documentation carries a worked example of
the CSS it writes — `p={4} → padding: 1rem`, `fontSize={14} → font-size: 0.875rem` — and those lines
are generated by running the engine, so the editor cannot tell you a scale the library stopped using.

## Colours

The palette is Tailwind's, in OKLCH: twenty-six families of eleven steps — `slate-50` through
`rose-950`, the four Tailwind 4.3 added (`mauve`, `mist`, `olive`, `taupe`) included — declared as CSS
variables the first time a page asks for one. Any colour value takes an opacity modifier:

```JS
<Box bgColor="blue-500/40" borderColor="black/10" hover={{ bgColor: 'blue-500/60' }} />
```

That compiles to `color-mix(in oklab, var(--blue-500) 40%, transparent)`: the mix wraps the
**variable**, so a themed token is still themed and everything asking for the same value still shares
one class. It is not `opacity`, which fades the element, its text and its children — this fades one
declaration. Every colour prop takes it (`color`, `bgColor`, `borderColor`, `outlineColor`, `fill`,
`stroke`), as does a `vars` entry and a variable of your own from `Box.extend()`.

## Gradients, shadows and filters

A gradient is a value, not a string you assemble: the key names the kind and carries its geometry, and
the stops are palette colours, so the whole thing is themed, takes the opacity modifier and shares one
class with every other element asking for it.

```JS
<Box bgGradient={{ linear: 'r', colors: ['blue-500', 'pink-500'] }} />
<Box bgGradient={{ radial: 'circle', at: 'top left', colors: [['sky-500', '20%'], 'indigo-900'] }} />
<Box bgGradient={{ conic: 45, colors: ['red-500', 'yellow-500', 'red-500'], interpolate: 'oklch' }} />
```

`interpolate` is worth knowing: sRGB drags a two-stop gradient through a grey middle, and `oklch` does
not. `oklch-longer` takes the long way round the hue circle, which is what turns two stops into a
spectrum. A gradient is judged whole — one unknown stop or one misspelt key and it emits no rule at
all, rather than quietly painting something else.

`box-shadow` is one CSS property, which normally means one shadow wins. Here it is **four layers** that
compose, so an elevation, a ring and an inner hairline coexist:

```JS
<Box shadow="md" ring={2} ringColor="indigo-500" borderRadius={2} />
<Box insetShadow="sm" insetRing={1} shadow="lg" shadowColor="blue-500/40" />
```

`shadow` is Tailwind's elevation scale (`xxs` through `xxl`, and the older `small`/`medium`/`large`
presets still work), `insetShadow` draws inside the border box, and `ring`/`insetRing` are a width in
px. A ring follows `borderRadius` and costs no layout, which is what makes it different from
`outline`. Each layer has its own colour prop — `shadowColor`, `ringColor`, and so on — which shows
nothing until the layer it belongs to is painted, exactly as `borderColor` needs a border width.
`textShadow` and `textShadowColor` are the text-side pair.

Filters stack the same way, and for the same reason: `filter` is one property whose value is a list, so
each of the nine functions sets a layer of its own and all nine write one composed declaration.

```JS
<Box blur="sm" grayscale={100} />
<Box brightness={110} saturate={150} hueRotate={90} />
<Box dropShadow="lg" dropShadowColor="indigo-500/40" />
<Box backdropBlur="sm" backdropSaturate={180} bgColor="white/20" />
```

A number is the function's own unit — a percentage for `brightness`, `contrast`, `grayscale`,
`invert`, `saturate` and `sepia`, degrees for `hueRotate`, pixels for `blur`, which takes Tailwind's
`xs`–`xxxl` scale too. `dropShadow` is cast by the _shape_ rather than the box, which is what a
transparent PNG or an SVG path wants. The nine `backdrop*` props are the same functions applied to
what is behind the element — the glassmorphism half.

`maskImage` takes the gradient record over again and reads its alpha channel, so a fade to
`transparent` is an edge fade; and `bgClip="text"` with `color="transparent"` is how a gradient
becomes lettering.

```JS
<Box maskImage={{ linear: 'b', colors: ['black', ['black', '55%'], 'transparent'] }} />
<H1 color="transparent" bgClip="text" bgGradient={{ linear: 'r', colors: ['violet-500', 'cyan-400'] }}>
  Painted by the background
</H1>
```

## Components

Every component here is a `Box` underneath — the same style props, the same theming, the same
`component`/`variant` defaults — with the right HTML tag, the ARIA its pattern owes and, where the
pattern has one, its keyboard. Each is a separate entry point, so a `Textbox` does not pull the
`DataGrid` into your bundle. Module paths below are relative to the package name, i.e.
`@box-kite/react/components/flex`.

```JS
import Box from "@box-kite/react";
```

### Layout and content

| Component                                                                    | Module                      | What it is                                                                                     |
| ---------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
| `Flex`                                                                       | `components/flex`           | `Box` with `display: flex`                                                                     |
| `Grid`                                                                       | `components/grid`           | `Box` with `display: grid`                                                                     |
| `H1`–`H6`, `P`, `Span`, `Link`, `Img`, `Nav`, `Header`, `Main`, `Section`, … | `components/semantics`      | one `Box` per semantic tag — 25 of them                                                        |
| `Svg`, `Path`, `Circle`, `Rect`, `SvgText`, …                                | `components/svg`            | one component per SVG element — 20 of them, so a drawing never writes `tag`                    |
| `Icon`                                                                       | `components/icon`           | Box props on an icon somebody else drew — lucide, Tabler, react-icons, a raw `<svg>`           |
| `Sparkline`, `ProgressRing`, `Gauge`, `MiniDonut`                            | `components/chart`          | chart micro-primitives over those elements — a chart that takes Box props and no chart library |
| `ChartContainer`                                                             | `components/chart`          | the theming bridge: the variables a Recharts (or any) chart reads, declared in both themes     |
| `BaseSvg`                                                                    | `components/baseSvg`        | deprecated: `Svg` with the 24×24 icon preset                                                   |
| `VisuallyHidden`                                                             | `components/visuallyHidden` | text for a screen reader only — clipped away rather than hidden,