Components #

Use this guide when you add or change a public component in @luke-ui/react.

Components and primitives #

Luke UI exposes one normal component API. Start with the component that fits the use case.

When the component API does not cover a custom composition, drop down to a primitive under @luke-ui/react/primitives/*. Primitives describe a lower-level composition API, not implementation simplicity. Foundational components such as Text, Icon, Heading, and Box remain normal component entrypoints.

import { Button } from '@luke-ui/react/button';
import { Text } from '@luke-ui/react/text';
import { TextInputRoot } from '@luke-ui/react/primitives/text-input';
import { Field, FieldLabel } from '@luke-ui/react/primitives/field';
import { ComboboxRoot } from '@luke-ui/react/primitives/combobox';

Do not add a root @luke-ui/react/primitives barrel. Import each primitive entrypoint explicitly.

Component creation #

Use the component generator for new normal component entrypoints:

pnpm run generate:component --args <name> <docs-group>

Use the primitive generator for new @luke-ui/react/primitives/* entrypoints:

pnpm run generate:primitive --args <name>

Creation rules live in packages/turbo-generators/src/component-creation-plan.ts and primitive-creation-plan.ts. Keep validation, defaults, and scaffold rules there so Turbo and Plop share them. Only components accept documentation groups.

The component generator creates the component guide's primary apps/docs/src/examples/<component>/basic.tsx example and references it with ExampleBlock. The primitive generator creates apps/docs/src/examples/<name>-primitive/basic.tsx, the matching MDX page under components/primitives/, and updates components/primitives/meta.json. Replace the placeholder content with one focused, renderable use of the component or primitive.

Do not move creation rules into one-off generator code.

Public subpath modules live under src/exports/. Single-segment subpaths use a flat module such as src/exports/button.ts. Grouped subpaths use nested modules such as src/exports/primitives/button.ts. A component's implementation lives under src/core/. Support modules and multi-part primitives each keep their own file. Public entrypoints use explicit named exports. See PUBLIC_API.md for the public surface rules.

Icons #

Icon SVGs live in packages/@luke-ui/react/icons. After adding, renaming, or removing one, regenerate the spritesheet and the iconNames union:

pnpm --dir packages/@luke-ui/react run generate:icons

The generated iconNames export drives the docs gallery at /docs/iconography, so a new icon appears there with no further changes.