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