@7shifts/sous-chef 4.4.1 → 4.5.0

package/llms-instructions/llms-components.md

@@ -1,425 +1,225 @@
+<!-- AUTO-GENERATED by scripts/build-llms-components.js. Do not edit manually. Run `yarn build-llms-components` to regenerate. -->
+
 # @7shifts/sous-chef — Component Reference
 
 All component APIs and use cases are defined in the Storybook MCP. You can get detailed information about any specific component.
 
-In this document, you will find additional information on how to use components in specific situations.
+In this document, you will find a list of the available components grouped by category, with a short description of what each one does.
+
+If you want information (props, guidelines) about an specific component, you can use the tool sous-chef_get_component_details, providing the name of the component as an argument.
 
 ## Actions
 
-Components available:
+Actions are the components a user interacts with to trigger behaviour or navigate.
 
 ### Button
 
-When using a button with an icon and text, you don't need to use the `Inline` component to align the elements:
-
-```tsx
-<Button>
-    <IconPencil />
-    Edit
-</Button>
-```
-
-Also, the icon size is inferred by the `Button` component.
+Default buttons are used for secondary, understated, or redundant actions. If you don't know what a button should be, it's probably this.
 
 ### Link
 
+Links are used to redirect to other pages. Usually external sources are opened on a separate browser tab.
+
 ### PaginationControls
 
-Only use this component if you need to control pagination outside of the `DataTable` component. If you are using `DataTable`, it already provides props for controlling pagination.
+PaginationControls renders a Previous and Next button pair for moving through a paginated data set. It handles keyboard shortcuts globally and can optionally scroll the viewport to a target element when the page changes.
 
 ### Toggle
 
-It should be used outside of a form. If it is inside a form, then you should use a `CheckboxField` instead.
-The `Toggle` component is used when there is no `Save` button to persist the data, so when the user changes its value, it is automatically persisted, usually in settings.
+Toggle lets a user switch a single setting on or off with an immediate effect. The change takes effect the moment the toggle is flipped — no save or confirm step required.
 
 ## Controls
 
 Controls contains the components that are usually used in toolbars, for example in a list filter.
 
-Components available:
-
 ### DateFilter
 
-Use this component to filter content on the page by date, whether by day, week, or month.
-DON'T use it in a form with a submit button. Inside a form, you should use the `DateField`, `DateRangeField`, or `WeekField` components for picking a date.
+To filter content on the page by dates, which can be done by either day, week, or month.
 
 ### SegmentedControl
 
-Segmented control is typically used in a toolbar to switch between different views. It can have two or three options.
-DON'T use it as tabs. Sous Chef does not have a `Tab` component yet, so if you need one, check whether there is an application-specific `Tab` component to use. If not, then you need to create one.
+Segmented Control is typically used in a toolbar to switch between different views. It can have as many options as needed.
 
 ### ToolbarSelect
 
-This component is used to select options (similar to `SelectField`). However, this is meant to be used outside of a Form, more specifically in toolbars where there is no need for a label.
+ToolbarSelect is a compact dropdown filter for use in toolbars. It lets a user narrow page content or a paired component content by selecting from a predefined list of options.
 
 ## Empty States
 
-Components available:
+Empty states are shown when there is no data or content to display.
 
 ### EmptyState
 
-This component should be used outside the context of a list because list components already handle the empty state. For example, `DataTable` handles the empty state when `items` is an empty array.
-Use this component when you want to show an empty state inside a modal or for a first-time user experience.
+Empty states are moments in a user’s experience which appear when the application’s content can’t be shown for a number of reasons.
 
 ### Paywall
 
-It is similar to the `EmptyState` component, but it is designed for conversion flows with proper upsell theming on headers and other features.
+Paywalls should be displayed when a user’s account does not have the proper subscription tier to use a specific feature or part of a feature. They should typically contain actions to enable and learn more about the feature behind the paywall.
 
 ## Feedback
 
 Feedback components bring information to the user's attention.
 
-Components available:
-
 ### CircularProgress
 
-It is a circular bar that shows the progress. Use this component when you want a small indicator of progress. If you want something bigger, use the `ProgressBar`.
+The CircularProgress component is used to indicate the overall progress of something that has a set number of things to be completed.
 
 ### InlineBanner
 
-It is the most commonly used banner for displaying information. It fills all the space available in the container where it is placed.
-If you want a smaller banner, then use the `MicroBanner` component.
-
-When rendering it in a page using the `Page` component, you can place it in the `banner` prop.
+InlineBanner displays a contextual message inline within a page or section
 
 ### MicroBanner
 
-It is a small banner that does not take all the space available in the container. It can be used where space is limited, for example, in top bars.
+MicroBanner component for compact information display with or without a call to action
 
 ### PersistentBanner
 
-It should be used for something that needs a lot of attention, for example, a failed subscription payment. Usually, it is placed above the top bar.
+Persistent Banner component is used to provide overarching information in the application. It is usually placed above the main nav bar.
 
 ### ProgressBar
 
-It is a bar that takes all the space available on the container it is placed. It is usually used inside a modal as the progress tracker of a wizard, for example.
+The ProgressBar component is used to indicate the overall progress for a task with a varying amount of steps to complete.
 
 ### Skeleton
 
-Used for building skeleton loading states. The `DataTable` already handles the loading state.
-Use this component when you want to create a loading state for some view, for example a card, or something else.
+Skeleton renders an animated placeholder that mirrors the shape of content while it is loading. It reduces perceived wait time by showing the user where content will appear before it arrives. It will begin to show a loading animation after 3.5 seconds to reduce user frustration on long loading pages.
 
 ### Spinner
 
-This is the classic loading state. Skeleton brings a more modern loading state.
+Used to notify users that their action is being processed or when a partial or full page is being loaded.
 
 ### Toast
 
-It is a simple function that shows a small pop-up at the bottom of the page. It should be used to show the user that an action has completed or that something failed.
-
-```
-toast('User updated')
-```
+Toasts are used to inform the user about an action that happened.
 
 ## Forms
 
-For common form composition examples, refer to the [Composing components](llms-composing-components.md) document.
-
-Components available:
-
-### AsyncSelectField
-
-It is similar to the `SelectField`; however, it has a `loadOptions` prop that returns a `Promise` to load the data. With `SelectField`, you need to pass the `options` prop directly.
-Use this component when you DON'T have all the options upfront and you need to fetch data from an API, or when your endpoint is paginated.
-
-### CheckboxField
-
-Simple checkbox field.
+Form components are used to collect user input and data.
 
 ### ColorField
 
-Used when you need to pick a color. It gives all the sequention color tokens as options.
-
-### CurrencyField
-
-Used when the user needs to type a currency value.
-
-### DateField
-
-Used when the user needs to pick up a SINGLE date. If the user needs a range then use the `DateRangeField`. If the user needs a week, then use the `WeekField`.
-
-### DateRangeField
-
-Used when the user wants to pick a range of dates (start and end).
-
-### Form
-
-This is the component that holds the form state, usually through the `formik` prop, and is responsible for submitting the data.
+Color fields allow users to select a color from a predefined set of options. They are ideal for settings or configurations where color selection is necessary.
 
 ### FormFeedback
 
-Used to show a form validation error at the form-wide level. Individual form fields already handle their own error state.
+FormFeedback is used to indicate an error within a form, for example when there is invalid or missing data in a form field.
 
 ### FormFooter
 
-It is responsible for holding the submit button and other form actions. It takes the `actions` prop and automatically positions the buttons properly.
-
-### FormRow
-
-Used when you need to place form fields on the same row. It distributes the space evenly between the form fields.
-For forms, give preference to `FormRow` instead of the `Inline` component.
+`FormFooter` contains the CTAs for a `Form` and handles all the `Button` styling when the `actions` prop is used.
 
 ### FormSection
 
-Used when you need to group some form fields together. It handles the title and subtitle of the section.
-You can also use it as a card with the `as="card"` prop. In forms, if you see form fields inside a card, it is usually a `FormSection` component with the `as="card"` prop.
-
-### MultiSelectField
-
-Similar to the `SelectField` but for selecting multiple options.
-
-### NumberField
-
-Form field for informing numbers.
-
-### PasswordField
-
-Used for entering passwords. Unlike the other form fields, this component does not have a `caption` prop. Instead, it handles the configured password criteria in the caption, for example when the password is too weak.
-
-### PercentageField
-
-Used for informing a percentage number.
+`FormSection` provides visual seperation between sections within a `Form` and can have a title and subtitle.
 
 ### PhoneField
 
-Used for entering a phone number. By default, it uses the `country` passed to the `SousChefProvider`, but it can be overridden by passing the `defaultCountry` prop.
-
-### PillSelectField
-
-It is similar to the `SelectField` but all the options are shown side-by-side in the screen. Use this component when you have just a few options to display.
-
-### RadioGroupField
-
-Used when the user needs to select only one option. Options can also be displayed as cards when using the `RadioGroupBoxOption` as children.
-
-Subcomponents:
-
--   RadioGroupOption
--   RadioGroupBoxOption
-
-### SelectField
-
-Used when you need to select only one option from the dropdown.
-
-### TextAreaField
-
-Similar to the `TextField` but it can have multiple lines and can also have toolbar at the bottom where you can place some buttons.
-
-### TextField
-
-This is the main component for typing a text in a form.
-
-### TimeField
-
-Used for pick a specific time. If you need a range of times then use the `TimeRangeField`.
-
-### TimeRangeField
-
-Used when you need to select a start time and an end time.
-
-### WeekField
-
-Used when you need to select a week. This component will give you the start of the week to be saved in the form state.
+A field for entering phone numbers. It includes a selection field for country code and can validate phone numbers.
 
 ## Media
 
-Available components
+Media components display compact visual or status information, such as avatars and labels.
 
 ### Avatar
 
-By default, the `Avatar` component already handles a user illustration with an appropriate background color, so you don't need to pass the `color` prop for this use case.
-You can also pass letters as children, usually initials. In that case, you can set the `color` prop if you want a specific color.
-You can also show a user image passing the `url` prop.
+Avatar represents a person or entity — such as a company, location, department, or role — with a visual identifier. It appears wherever a person or entity's identity needs to be communicated at a glance.
 
 ### Badge
 
-It is a circle that is usually used to show a counter, for example, the number of unseen notifications. It can also be used with an icon.
+Badge is a small circular indicator used to draw attention to something associated with another element — a count, a status, or a quick action. It always appears in relation to something else, never on its own.
 
 ### Chip
 
-A chip is similar looking to pill, but is instead used to convey system status such as "New", "Beta", or "Add-on".
+A chip is similar looking to pill, but is instead used to convey system status such as "New", "Beta", or "Add-on"
 
 ### Pill
 
-A Pill is used to inform users on the status of a nearby object or of an action that’s been taken. It is bigger than a Chip.
+A Pill is used to inform users on the status of a nearby object or of an action that’s been taken. The default state is used to convey general status or state, such as: Pending Unavailable, Inactive.
 
 ## Layout
 
-Available components:
+Layout components structure and arrange the content of a page.
 
-### Card
+### CalloutCard
 
-It is a simple container with a border (and border radius) and some content in it. It is a flexible component meant to render everything the user passes as children.
-When using it inside a form, check whether it is more suitable to use a `FormSection` component instead.
+CalloutCards are containers to present a new product or feature to users.
 
-### Inline
+### Card
 
-Used to align elements side by side. It uses CSS `flex` concepts for its props. For complex use cases where you need to control how each item grows, you can use the `flex` prop.
-Pay special attention to the `flex` prop. It is an array of elements, each of which can be a string or number, where each element sets the `flex` prop for a child element. For example:
+Cards are containers to introduce division between content.
 
-```tsx
-<Inline flex={['0 1 auto', 1]}>
-    <div>item 1</div>
-    <div>item 2</div>
-</Inline>
-```
+### Inline
 
-It is literally setting the CSS `flex: 0 1 auto;` to the first element and `flex: 1` to the second element.
+Layout component to easily line elements up in a row.
 
 ### Page
 
-It is used to create a single page with slots to place all page elements, such as title, subtitle, banner, filter bar, actions, and children.
-IMPORTANT: It should not be used for high-level app layout, such as the nav bar and top bar. Also, if it has a small left menu, it is probably a `PageLayout` component.
-
-For examples of how to set up a page layout, refer to the [Composing components](llms-composing-components.md) document.
-
-### PageLayout
-
-It should be used to hold a group of pages where there is a left side menu (using the `menu` prop). Usually, when the user clicks on a menu item it should navigate to some specific route.
-In its children, it should contain a router where each route renders a component that uses a `Page` component.
-
-For examples of how to set up a page layout, refer to the [Composing components](llms-composing-components.md) document.
+The Page component is used to control the elements within a page. It can be full width or restricted using the `size` prop. To better see it, open this example on a full page.
 
 ### Stack
 
-Used to align elements vertically. It is similar to the `Inline` component. It uses CSS `flex` concepts for its props. For complex use cases where you need to control how each item grows, you can use the `flex` prop.
-Pay special attention to the `flex` prop. It is an array of elements, each of which can be a string or number, where each element sets the `flex` prop for a child element. For example:
-
-```tsx
-<Inline flex={['0 1 auto', 1]}>
-    <div>item 1</div>
-    <div>item 2</div>
-</Inline>
-```
-
-It is literally setting the CSS `flex: 0 1 auto;` to the first element and `flex: 1` to the second element.
+Layout component to easily stack elements up in a column.
 
 ## Lists
 
 Components used to display a list of data.
 
-Available components:
-
 ### Accordion
 
 Accordions are lists used to group information into collapsible sections. Only one section can be open at a time.
-Don't use this component if you have columns, in that case, use the `DataTable` component instead.
 
 ### ActionList
 
-It is similar to the `Accordion` but it does not collapse items. It is a more rich data display that should be used for displaying a list of actions that the user needs to take.
-It is usually used on dashboard pages.
-
-Subcomponents:
-
--   ActionListItem
+A list of tasks or items that require user attention and can be completed with an action. Each item should have at least one clear action for the user to take.
 
 ### DataTable
 
-This is the main component used to display a dynamic list of data (usually coming from an endpoint).
-With this component, you can build simple tables by passing an array of `items`, but you can also build more complex use cases, such as sortable columns, pagination, and editable cells.
-
-Subcomponents:
-
--   DataTableRow
--   DataTableCell
--   DataTableEditableCell
-
-For examples of how to compose tables, refer to the [Composing components](llms-composing-components.md) document.
+DataTable displays structured data in rows and columns. Use it when data is inherently tabular — each row represents a record and each column represents an attribute of that record.
 
 ## Navigation
 
-Available components
+Navigation components help a user move around the application and understand where they are.
 
 ### Breadcrumbs
 
-The `Page` component already handles breadcrumbs. However, if you need to render breadcrumbs outside of the page component then you can use this component.
+Used on top of pages to let the user navigate back to parent routes. IMPORTANT: It requires the `react-router-dom` Router to be present on a upper level of the document tree.
+
+### PrimaryNav
+
+PrimaryNav is the main navigation component for Sous Chef. It provides a vertical navigation menu with support for nested sub-items, badges, and a footer section. The navigation can be expanded or collapsed, and it highlights the active item based on the current selection. The component is designed to be flexible and customizable, allowing for various use cases within the application.
 
 ## Overlay
 
 Overlays are components that render on top of the main page.
 
-Available components:
-
 ### Calendar
 
-It is a standalone calendar that needs an `anchorRef` from a trigger, for example, a button created with React `useRef`.
-Use this component outside of a Form context. If you are in a form, then use the form fields for picking a date.
+Calendar is a date-picking overlay that anchors to a trigger element and lets the user select a single day or a full week. It is not a form field — it is a standalone panel that you control the opening and closing of yourself. In most cases, a `DateField` or `DateRangeField` is the right choice; reach for Calendar directly when you need more control over how and when the picker appears.
 
 ### Dropdown
 
 A Dropdown is where you can have menu options that are hidden until the user clicks or hovers on a trigger element.
-If you want to render a more complex interaction or content within a dropdown, consider using a Popover instead.
-
-Subcomponents:
-
--   DropdownList
--   DropdownListItem
--   DropdownListItemSelectable
--   DropdownListItemDivider
 
 ### HintModal
 
-HintModal can be used to provide tips or guidance to users on a page. It is not typically triggered by a button. Instead, it should be rendered when a user navigates to a page where they might require additional guidance.
-It shows on the bottom-right side of the screen.
-For larger information or forms, use the `Modal` component instead.
+HintModal can be used to provide tips or guidance to users on a page. It not typically triggered by a button, instead it should be rendered when a user navigates to a page where they might require additional guidance.
 
 ### Modal
 
-Used to interrupt the page flow and show a container to display some information, such as a paywall, a set of steps in a wizard, or a form.
-It already handles the `header` and `subHeader`.
-
-Subcomponents:
-
--   ModalBody
--   ModalFooter
-
-When using a form inside a modal, refer to the [Composing components](llms-composing-components.md) document, as it has some special configuration to work well in a modal.
+Modal is a focused overlay that interrupts the current experience and demands the user's attention. It blocks all interaction with the rest of the page until the user responds — making it best suited for decisions, confirmations, and self-contained flows where that level of focus is warranted.
 
 ### Popover
 
-Similar to a `Dropdown` but, instead of options, you have the flexibility to render anything you want in the children. It will be placed in the overlay.
-For small overlays, like a text with a title, use the `Tooltip` instead.
+A Popover is a type of dropdown but it is meant to be used for more complex interactions and content that goes beyond a list of actions. If you find yourself needing to put a form, information, or multiple actions within a dropdown, it's probably best to use a Popover instead of a Dropdown.
 
 ### Tooltip
 
-Used to show small overlays, usually it is triggered on hover. If you need to render more complex things use the `Popover` component instead.
+Tooltip is a small, non-interactive label that appears on hover to provide a brief explanation. It is the lightest overlay in the system — low interruption, no interaction, disappears when the user moves away. Its job is to add micro-clarity: explaining an icon, defining an abbreviation, or surfacing supplementary detail without cluttering the UI.
 
 ## Typography
 
-### Text
-
-This is the atomic component for rendering text and headings. You can use the `as` prop to set how it will be displayed:
+Typography components are used to display text in various styles and hierarchies.
 
-Example:
-
-```tsx
-<Text as="h1">Title</Text>
-```
-
-You can give emphasis to a text using the `emphasis` prop:
-
-Example:
-
-```tsx
-<Text emphasis="bold">Title</Text>
-<Text emphasis=["bold", "italic"]>Title</Text> // with multiple emphasis
-```
-
-If you want to give emphasis just to some parts of the text you can use the sub components:
-
-Example:
-
-```tsx
-<Text>
-    Example of a <Bold>bold</Bold> text and <Italic>italic</Italic> text.
-</Text>
-```
-
-The subcomponents use a `span` tag under the hood, so they do not break the DOM structure.
-
-Subcomponents:
+### Text
 
--   Italic
--   Bold
--   Underline
+The Text component is used to format text style, size, line spacing, alignment, and color.

package/llms-instructions/llms-icons-and-illustrations.md

@@ -1,3 +1,5 @@
+<!-- AUTO-GENERATED by scripts/build-llms-icons-and-illustrations.js. Do not edit manually. Run `yarn build-llms-icons-and-illustrations` to regenerate. -->
+
 # Sous Chef Design System - Icons and Illustrations
 
 In Sous Chef, icons and ink illustrations are treated as normal React components.