diff --git a/apps/docs/content/docs/docs/composition.mdx b/apps/docs/content/docs/docs/composition.mdx
index 609524d0..f22cf39e 100644
--- a/apps/docs/content/docs/docs/composition.mdx
+++ b/apps/docs/content/docs/docs/composition.mdx
@@ -90,6 +90,6 @@ import { vars } from '@luke-ui/react/theme';
/>;
```
-Read [Styling](/docs/styling) for semantic variables and layout utilities. Read the
-[primitive documentation](/components/primitives/button) before you build a custom component from a
-specific primitive.
+Read [Styling](/docs/styling) for semantic variables, layout utilities, and component recipes. Read
+the [primitive documentation](/components/primitives/button) before you build a custom component
+from a specific primitive.
diff --git a/apps/docs/content/docs/docs/styling.mdx b/apps/docs/content/docs/docs/styling.mdx
index 71056f04..df336443 100644
--- a/apps/docs/content/docs/docs/styling.mdx
+++ b/apps/docs/content/docs/docs/styling.mdx
@@ -1,7 +1,8 @@
---
title: Styling
description:
- Choose component props, layout utilities, variables, or themes. Do not override internals.
+ Choose component props, recipes, layout utilities, variables, or themes. Do not override
+ internals.
---
Luke UI ships static CSS. It does not inject styles at runtime. Import the shared stylesheet and a
@@ -37,6 +38,41 @@ defines its type and spacing steps in source.
+### Apply a component recipe
+
+Import a recipe when you own the element and need that component's visual treatment. Use the
+component when you want its behaviour as well.
+
+Each recipe lives on the component or primitive entrypoint that owns it. Import `buttonRecipe` from
+`@luke-ui/react/button`. There is no `@luke-ui/react/recipes` barrel.
+
+Recipes follow a fixed name. The function is the component in camel case plus `Recipe`. The variants
+type is the component in Pascal case plus `RecipeVariants`.
+
+
+
+A single-part recipe such as `buttonRecipe` returns one class string. Pass the same variant names
+the component accepts.
+
+```tsx
+import { buttonRecipe, type ButtonRecipeVariants } from '@luke-ui/react/button';
+
+const variants: ButtonRecipeVariants = { appearance: 'subtle', tone: 'neutral' };
+const className = buttonRecipe(variants);
+```
+
+A slotted recipe such as `inputGroupRecipe` returns one function per part. Call the part you are
+styling.
+
+```tsx
+import { inputGroupRecipe } from '@luke-ui/react/primitives/input-group';
+
+const { group, control } = inputGroupRecipe({ size: 'medium' });
+```
+
+Do not import a recipe to restyle a Luke UI component from the outside. Use the component's props
+for supported variation.
+
### Use layout utilities for structure
`Box` and layout utilities from `@luke-ui/react/styles` handle spacing, sizing, positioning, and
diff --git a/apps/docs/src/examples/styling/button-recipe.tsx b/apps/docs/src/examples/styling/button-recipe.tsx
new file mode 100644
index 00000000..996a83ac
--- /dev/null
+++ b/apps/docs/src/examples/styling/button-recipe.tsx
@@ -0,0 +1,9 @@
+import { buttonRecipe } from '@luke-ui/react/button';
+
+export default () => {
+ return (
+
+ Settings
+
+ );
+};
diff --git a/docs/STYLING.md b/docs/STYLING.md
index 353325fd..6c743e01 100644
--- a/docs/STYLING.md
+++ b/docs/STYLING.md
@@ -209,7 +209,8 @@ recipes should add their own `@media (prefers-reduced-motion: reduce)` override.
Public recipes export from the component or primitive entrypoint that owns the styling contract, for
example `buttonRecipe` from `@luke-ui/react/button` or `inputGroupRecipe` from
-`@luke-ui/react/primitives/input-group`.
+`@luke-ui/react/primitives/input-group`. The hosted Styling page documents when a developer imports
+one, the `buttonRecipe` / `ButtonRecipeVariants` names, and single-part versus slotted calls.
Recipes are component-specific. Keep them separate from general layout utilities.
diff --git a/packages/@luke-ui/react/README.md b/packages/@luke-ui/react/README.md
index 3da8da02..19bb1b37 100644
--- a/packages/@luke-ui/react/README.md
+++ b/packages/@luke-ui/react/README.md
@@ -45,7 +45,9 @@ AI agents can fetch documentation at:
- Any docs URL with `.md` appended: per-page Markdown.
Start with the normal component API. Use primitives from `@luke-ui/react/primitives/*` when you need
-a custom composition the component API does not cover.
+a custom composition the component API does not cover. Import a colocated recipe such as
+`buttonRecipe` from the same component entrypoint when you own the element and need that visual
+treatment. There is no `@luke-ui/react/recipes` barrel.
## License