@7shifts/sous-chef 4.4.1 → 4.5.0

package/llms-instructions/guidelines/Dropdown.guidelines.md

@@ -0,0 +1,54 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   For contextual action menus — a set of actions tied to a specific item or element
+-   When multiple related controls need to be grouped behind a single trigger to save space
+-   For secondary navigation or settings that don't warrant permanent placement in the UI
+-   When the options are a simple list — labels, icons, or selectable items
+
+## When Not to Use
+
+-   When the content inside needs to be a form, rich content, or more than a list of actions — use `Popover` instead
+-   When only one action is available — surface it as a `Button` directly
+-   For primary navigation or actions the user needs to discover — dropdown content is hidden and easy to miss
+-   When the user needs to compare options with supporting detail — consider a dedicated UI surface instead
+
+## Usage
+
+### Trigger
+
+-   The trigger is any interactive element — typically a button or icon — that the user clicks to open the menu.
+-   Dropdowns default to opening on click (`triggersOn="click"`), which is the recommended setting.
+-   Hover (`triggersOn="hover"`) is available but should be used sparingly — hover menus are harder to use on touch devices and can feel surprising. Prefer click unless there's a strong reason for hover.
+
+### Submenus
+
+-   Dropdowns can have Submenus which fly off to the right or left of the main Dropdown.
+-   Use these to nest different options within a single menu item - For example choosing a flag to apply from a list, or choosing an optional theme (Light mode, Dark mode)
+-   You can trigger a Submenu from a Submenu, however try to avoid this whenever possible.
+-   Use `IconChevronRight` in the suffix to indicate a Submenu will trigger off this menu item.
+
+### Alignment
+
+-   The dropdown panel aligns to the trigger by default.
+-   Use `alignment` to control whether the panel opens left or right of the trigger when needed to avoid overflow.
+
+### Dividers
+
+Use `DropdownListDivider` to group related items visually. A divider between destructive actions (like Delete) and the rest of the list is a common and useful pattern.
+
+## Tips & Tricks
+
+-   Keep dropdown lists short and scannable. If a menu has more than 6–8 items, consider grouping with dividers or rethinking the information architecture.
+-   Lead with the most commonly used actions. Users scan from the top — don't bury "Edit" below five less-frequent options.
+-   Destructive actions like Delete should always sit at the bottom of the list, separated by a divider, and use a danger theme to signal their weight.
+-   Avoid putting form fields or multi-step interactions inside a Dropdown. If you need that, use a `Popover`.
+-   Icons in list items help scannability, but aren't required. If you use icons, be consistent across the whole list — mixing icon and non-icon items looks unbalanced.
+
+## Additional Rules
+
+-   `trigger` is required and must accept a forwarded ref.
+-   Prefer `triggersOn="click"` over `triggersOn="hover"` — the hover variant is flagged as a non-preferred option in the component API.
+-   `DropdownList` is required as the direct child of `Dropdown` to correctly apply list styles and spacing.
+-   `triggerWidth="full"` stretches the panel to match the full trigger width — useful for select-style dropdowns.

package/llms-instructions/guidelines/EmptyState.guidelines.md

@@ -0,0 +1,58 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When a page or section has no data to display and the user needs context and a next step
+-   For first-time experiences where a feature has not yet been set up
+-   When a user doesn't have access to content in a given section
+-   When an error occurred within a page or section
+-   User cleared: Occurs when a user has successfully completed an action like clearing their inbox or task list, and there is nothing left to show
+
+## When Not to Use
+
+-   When content is loading — use a skeleton or loading state instead
+-   When the absence of content is expected and unremarkable — don't force an empty state where a blank area is sufficient
+-   When a page is locked behind a paywall — use `Paywall` instead
+
+## Usage
+
+### Small Small should be used either when only a portion of the content on a page
+
+isn't shown or when a sub-feature on a page isn't shown.{' '}
+
+### Medium
+
+Also known as horizontal empty states. Used inline either when only a portion of the content on a page isn't shown or when a sub-feature on a page isn't shown. They differ from Small in that they provide the user more context to the empty state and they have some kind of call-to-action.
+
+### large
+
+Also known as the Full Page empty states. Used when an entire page isn't available.
+
+### As a Card
+
+Use `as="card"` with `size="medium"` when the empty state needs to sit within a card container. Pass `onClose` to let the user dismiss it.
+
+### Images
+
+-   The image should use our Bento image format.
+-   Large empty states can use either a single frame bento, or a multi-frame collage
+-   Medium and small empty states should use a single frame bento
+-   Bentos frames can contain an Inking illustration, a lifestyle photo or UI mockup
+
+### Copy Best Practices
+
+-   Write in sentence case, with the usual exceptions of proper nouns such as a person, feature name, location, etc., being title case
+-   Use as few words as possible in the title and description. Be direct and clear.
+-   Avoid repeating content from the title in the body. Say things once with intent
+-   Avoid technical terms or jargon. Communicate using common words
+-   Always choose a simpler shorter words over longer fancier words
+-   The title should communicate the message fully if possible, users are more likely to read this
+-   The body/description should be used to provide further important details or next steps
+-   caption appears below the action buttons — use it for secondary guidance or legal-style caveats, not as a substitute for body text.
+
+## Additional Rules
+
+-   `title` is required. All other props are optional.
+-   `as` defaults to `"banner"`. Pass `as="card"` explicitly when the empty state should render inside a `Card` wrapper.
+-   `onClose` is only valid when `as="card"`. Passing it in banner mode has no effect.
+-   `mediaUrl` expects a path to an image or gif. Use paths relative to the Storybook static directory (e.g. `"images/EmptyState.png"`) or absolute URLs.

package/llms-instructions/guidelines/Forms.guidelines.md

@@ -0,0 +1,99 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   Any time you need to collect information from the user using field components
+-   When a group of fields belongs together as a single unit of input (creating a shift, editing a profile, configuring a setting)
+-   When fields need a consistent layout, spacing, and validation model
+
+## When Not to Use
+
+-   When the user is making a selection rather than entering data — use a standalone `Select`, `Toggle`, or `SegmentedControl` instead
+-   When a single inline action is needed — avoid wrapping isolated controls in a Form just for layout
+-   When there is no submission of information from the user being written by the system
+
+## Usage
+
+### Anatomy
+
+Forms are comprised of the following components:
+
+-   `Form` - The wrapper that the entire form sits in
+-   `FormSection` - A visual grouping of fields within a form that can have a title and subtitle
+-   `FormRow` - A horizontal row of up to 4 fields
+-   `FormFooter` Contains the CTA buttons that control the entire form
+-   `FormField` An individual field in a form
+
+![Form anatomy](/images/form_anatomy.png)
+
+### Form Widths
+
+-   Forms have a default width of 500px, but you may override this if your design requires it. This should be done as a necessity, not as an aesthetic choice.
+-   A form field’s width includes all elements within the field (i.e. label, caption, error, and the input itself).
+-   To override the default width, pass the `wide` prop to `<Form />` to remove this constraint when the layout requires it.
+
+### Form rows
+
+-   Form rows support up to four fields per row. Each field's width can be set to 25%, 33%, 50%, 66%, or 75% — sizes across the row must add up to 100% or less.
+-   If no sizes are specified, the fields will split the width equally.
+-   All rows in a form have 20px vertical spacing between them. Fields within a FormRow have 20px horizontal spacing. Both are built in.
+-   Use `<FormRow />` whenever you have multiple fields in a single row, or when a single field needs to be narrower than the full form width (e.g. ~240px to match an adjacent row).
+-   `<FormRow />` is not needed for a single field that can fill the full form width.
+-   `<FormRow />` always lives within a `<Form />`. Its width is determined by its parent — typically the Form's 500px.
+-   Use the columns prop on FormRow (1–4) when fields in a row need to align with another row that has a different number of fields.
+-   `<FormRow />` without a `<Form />` parent will grow to fill its container — always nest it inside a Form.
+
+### Submission and Validation
+
+-   Typically speaking, each form uses a single submit button to complete. This uses our standard `button` component.
+-   The primary CTA Button is disabled while required fields are incomplete. A field doesn't need to be valid to enable it — just attempted (i.e. the user has interacted with it).
+-   Field error states trigger after the user interacts with a field and leaves it in an invalid state. They do not show on initial load.
+-   Example: a required field is empty, the user clicks into it and then moves focus away while it's still empty → error state triggers.
+-   Form buttons have a built-in minimum width of 100px.
+
+### Organizing Fields
+
+-   Use the Gestalt Principles to guide how you group and order fields — proximity, similarity, and continuation all apply.
+-   Aim for a scannable layout. Users should be able to find what they need quickly.
+-   Field width should reflect the expected length of the value it holds — a short code field shouldn't span the full form width.
+-   Group fields that are directly related (e.g. start date and end date) in the same row.
+-   When you have repeating rows of the same field type, the column header can appear only on the top row if the fields are self-explanatory in context (e.g. break rows in the Add Shift modal).
+
+### Copy
+
+-   Use sentence case for all labels, captions, and placeholder text. Proper nouns (people, feature names, locations) use title case.
+-   Set smart default values when reasonable expectations are known and the cost of being wrong is low (e.g. pre-selecting the day based on the cell that was clicked).
+-   Use placeholder text as a helpful example — not as a label substitute or instruction.
+-   Don't put "(required)" or "(optional)" signifiers inside placeholder text — put them in the label instead.
+
+### Required vs. Optional Fields
+
+Because forms often have many required and many optional fields, marking every field would be overwhelming. Use your judgment:
+
+-   If most fields are required and there are one or two optional outliers, label just the optional ones with "(optional)".
+-   If most fields are optional and there are one or two required outliers, label just the required ones with "(required)".
+-   Use lowercase for both.
+
+### Field Types
+
+| Field              | Use                                                                                                                                                                                                                                                                               |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AsyncSelectField` | A variation of select field that loads a dynamic list of options from a source rather than a fixed set of options. Use when you need to select from a dynamic list that can change such as roles, employees, locations, etc.                                                      |
+| `CheckboxField`    | A simple check box with an option beside it. Allows the user to confirm a statement or enable an option with a simple boolean action. Use for things like agreeing to terms, or enabling one or more options in a list (where multiple selections are allowed).                   |
+| `ColorField`       | A dropdown style field that lets the user choose one color token from our sequential colour palette. Use for things like choosing a role color.                                                                                                                                   |
+| `CurrencyField`    | A variation of a TextField, but it only accepts numbers, and will auto format the number into a currency format when the user leaves the field. Use anytime the user must enter a currency value and nothing else.                                                                |
+| `DateField`        | A dropdown style field for selecting a single specific date. It will load a calendar widget when activated allowing the user to find and pick a day.                                                                                                                              |
+| `DateRangeField`   | A dropdown style field with 2 inputs. It allows the user to select a specific start date and end date separately to create a range of dates.                                                                                                                                      |
+| `MultiSelectField` | A dropdown style field that lets you select and input more than one option within the field. Uses removable chips to represent selected items.                                                                                                                                    |
+| `NumberField`      | A special text input field that only accepts numbers. It has validation and formatting in place to properly display number values. In its default state it only allows whole numbers, but it can be configured to allow decimals and negative values.                             |
+| `PasswordField`    | A field used for passwords. It obfuscates the input by default, but has the option to reveal the input. Can also include required password criteria.                                                                                                                              |
+| `PercentageField`  | A special text input field that only accepts numbers. Comes with validation and formatting in place to properly display percentage values. In its default state it only allows integers between 0 and 100, but it can be configured to allow decimals and negative values.        |
+| `PhoneField`       | A field for entering phone numbers. It includes a selection field for country code and can validate phone numbers.                                                                                                                                                                |
+| `PillSelectField`  | A field where the user can select one or more from a vertical line of pills. Can also be made fully reactive allowing users to add and delete their own options. Use this to select from a more visual list with a limited number of options, like selecting the day of the week. |
+| `RadioGroupField`  | A list of radio options appearing either as an input or box. Use when the user can only select one option from a visual list and the user needs to be able to see all the options to make an informed decision.                                                                   |
+| `SelectField`      | Simple dropdown field where the user chooses one option from a set list.                                                                                                                                                                                                          |
+| `TextAreaField`    | A taller input field used to get long form text from the user. Has options to add a toolbar, character counter and character limit. Use when the input is expected to be longer than a single line.                                                                               |
+| `TextField`        | A basic open input field used to get text from the user, with options to add a prefix or suffix element if necessary. Accepts any characters, so do not use if you want to limit the format of the input to numbers only.                                                         |
+| `TimeField`        | A special field designed for selecting a specific time of the day. Users can choose from a dropdown of preset time intervals, or type directly into the field. When the user leaves the field, the input is automatically formatted into either AM/PM time or 24h time.           |
+| `TimeRangeField`   | A special input field for selecting a time range. Comprised of 2 individual time fields, the user selects a start time and an end time individually.                                                                                                                              |
+| `WeekField`        | A special dropdown style field used to select a single week from a calendar widget. Selections must always be 7 consecutive days, but you may customize the day of the week the selectable range starts on.                                                                       |

package/llms-instructions/guidelines/HintModal.guidelines.md

@@ -0,0 +1,47 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To introduce a new feature or page the first time a user encounters it
+-   When proactive guidance would meaningfully reduce confusion or friction
+-   For short onboarding tips that are helpful once but don't need to repeat on every visit
+-   When a media asset (image, illustration) helps communicate the tip more clearly
+
+## When Not to Use
+
+-   As a replacement for a regular `Modal` when a decision or action is required from the user — Hint Modal is guidance-only
+-   For critical information the user must act on — use a `Modal` or `InlineBanner` instead
+-   For tips that are always relevant — if the content is useful every visit, surface it persistently in the UI rather than in an overlay
+-   Repeatedly on the same page — if users keep seeing it, the "Don't show again" mechanism isn't working or the feature needs better in-context documentation
+
+## Usage
+
+### Triggering
+
+Hint Modal is not wired to a button click. Render it conditionally when the user lands on the relevant page — it will manage its own visibility using local storage, keyed to the `modalId` you provide. If the user has previously checked "Don't show this again", the component will not render.
+
+### Content
+
+Keep the header short and direct — name the feature or the thing the user is looking at. The body should explain what it does and why it's useful, in plain language. One or two short paragraphs is the right length.
+
+### Media
+
+An optional `mediaUrl` adds an image above the content area — useful for showing a screenshot, illustration, or short animation that makes the tip concrete. Use real product imagery where possible rather than generic illustrations.
+
+### Actions
+
+A `primaryButton` is required — typically a "Got it" button that closes the modal. An optional `secondaryButton` can be used for a secondary action like linking to a help article. Keep the primary action label affirming and simple.
+
+## Tips & Tricks
+
+-   The "Don't show this again" checkbox is built in — don't add your own dismiss mechanism. Trust the component to handle repeat visits.
+-   If your tip needs more than a short paragraph to explain, the feature probably needs better in-product documentation rather than a longer modal.
+-   Hint Modals work best for genuinely new things. Using them for features that have been in the product a long time feels out of place and will be dismissed quickly.
+-   Pair with a meaningful `mediaUrl` when you have one — a screenshot or annotated image dramatically increases how much information a user absorbs at a glance.
+
+## Additional Rules
+
+-   `modalId` is required and must be unique per hint — it is used as the local storage key to track "Don't show again" state.
+-   `primaryButton` is required. Pass a `Button` element — the component does not render default actions on its own.
+-   Visibility is partially managed internally via local storage. Once a user checks "Don't show again", the modal will not render again for that `modalId` unless the key is cleared.
+-   `onSetDoNotShowAgainStatus` fires when the checkbox state changes, if you need to sync this externally.

package/llms-instructions/guidelines/Icons.guidelines.md

@@ -0,0 +1,59 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   Alongside a label to reinforce meaning and aid scannability — a save icon next to "Save changes", a warning icon next to an error message
+-   As the sole content of an icon button when the action is well-established and space is tight — always pair with a `Tooltip` in this case
+-   To communicate status at a glance in a list or table row — a status icon can convey meaning faster than text alone
+-   In navigation items, section headers, or feature names where a visual anchor helps users orient quickly
+
+## When Not to Use
+
+-   As a standalone element without a label or tooltip — icons are rarely self-explanatory enough to stand alone, especially for new or infrequent users
+-   As decoration or expressive visual element with no functional meaning — use an `InkIllustration` for empty states, onboarding moments, or anywhere illustration-quality imagery is appropriate
+
+## Usage
+
+### Sourcing Icons
+
+-   We use `Font Awesome` from the `Classic` family which can be found on fontawesome.com
+-   For `outline` use the `Classic Light`
+-   For `solid` use `Classic Solid`
+-   If using a new icon that doesn't exist in the current Sous Chef library, send a message in the #sous-chef channel and the Design Systems team can add it to Sous Chef
+
+### Variants
+
+Each icon comes in two variants: `outline` (default) and `solid`. Outline is the standard choice for most UI contexts. Solid is used to communicate a selected, active, or filled state. Solid may also be used selectively as a visual choice when extra contrast is needed, but this should be done sparingly and with care.
+
+### Sizes
+
+| Size      | Dimensions |
+| --------- | ---------- |
+| `small`   | 12×12px    |
+| `medium`  | 16×16px    |
+| `default` | 20×20px    |
+| `large`   | 24×24px    |
+
+`default` is the standard for most UI contexts. Use `small` for dense layouts like table cells or compact toolbars. `flexible` removes the fixed width and height entirely, letting you control the size through CSS — useful in edge cases where none of the named sizes fit the surrounding layout.
+
+![Icon size guide](/images/iconsizes.png)
+
+When an icon is placed inside a `Button`, its size is automatically set to `medium` — you don't need to specify it.
+
+### Colour
+
+By default, icons inherit the colour of their surrounding text. Pass a `color` prop to override this when the icon needs to carry its own colour — for example, a red warning icon or a green success indicator.
+
+## Tips & Tricks
+
+-   When using an icon-only button, always add a `Tooltip` so keyboard and mouse users can discover what the button does. An icon without a label is an assumption about what users already know.
+-   When using a stand alone icon as an interactive control, place the icon inside a `button` component. Do not use it as a raw icon. This will ensure it has the correct hit box, hover, active and disabled states.
+-   If you're not finding the icon you need, search by concept rather than exact name. "Arrow right" might be called `IconChevronRight` or `IconArrowRight` depending on the style.
+
+## Additional Rules
+
+-   All icon components accept `size`, `variant`, `color`, and `testId` props.
+-   `variant` defaults to `'outline'` if not specified.
+-   `size` defaults to `'default'` (20×20px) if not specified.
+-   When used inside a `Button`, icon `size` is automatically overridden to `'medium'` — passing a different size inside a button will have no effect.
+-   `size="flexible"` renders with no `width` or `height` attributes — size must be controlled entirely via CSS.

package/llms-instructions/guidelines/InkIllustrations.guidelines.md

@@ -0,0 +1,38 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   In empty states, when a page or list has no content yet — an illustration softens the experience and gives users a sense of what the space is for
+-   In onboarding flows, tooltips, or hint modals where a visual makes a concept easier to grasp
+-   On confirmation or success screens where a moment of delight is appropriate
+-   As supporting imagery in marketing or promotional content within the product
+
+## When Not to Use
+
+-   As a substitute for a functional icon — use the icon library for UI controls, status indicators, and interface actions
+-   In dense, data-heavy interfaces where space is at a premium and illustrations compete with content
+-   When the illustration doesn't clearly relate to the surrounding content — an unrelated illustration creates confusion rather than delight
+-   Repeatedly on the same screen — one illustration per view is almost always the right amount
+
+## Usage
+
+### Sizing
+
+Unlike icons, illustration size is set as a CSS value string — for example `"100px"`, `"200px"`, or a responsive value like `"100%"`. There are no named size tokens. Choose a size that gives the illustration enough presence without overwhelming the surrounding layout. In empty states, something in the range of 80–150px typically works well.
+
+### Colour
+
+Ink Illustrations are fixed illustrations — they are not colour-customisable. They are designed to work across both light and dark contexts and should be used as-is. Standard illustrations use a single neutral colour token. Custom illustrations are special branded illustrations that use more than one colour. These often have several variations with different colour treatments you can choose from.
+
+## Tips & Tricks
+
+-   Empty states are the most common use case. A well-chosen illustration paired with a clear heading and a call-to-action ("Add your first employee") transforms a dead end into an invitation.
+-   People and hands illustrations work well for onboarding and educational moments — they feel approachable and human without being overly literal.
+-   Don't stretch illustrations with mismatched aspect ratios. Set either width or height and let the other dimension scale naturally.
+-   When pairing an illustration with text in an empty state, centre both horizontally and keep the text concise. The illustration draws the eye — the text closes the loop.
+
+## Additional Rules
+
+-   Each illustration is a standalone React component — import and use it directly, no wrapper component required.
+-   `size` accepts any valid CSS dimension string and defaults to `'100px'` if not provided.
+-   Illustrations are not interactive and do not accept event handlers.

package/llms-instructions/guidelines/InlineBanner.guidelines.md

@@ -0,0 +1,52 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To surface information, warnings, errors, or success states that are directly relevant to the content on the current page
+-   When the message should remain visible until the user dismisses it or the condition resolves
+-   When a CTA is needed alongside the message — upgrading a plan, resolving an issue, taking an action
+
+## When Not to Use
+
+-   For brief confirmations of completed actions — use `Toast` instead
+-   For app-wide or top-of-page announcements — use `PersistentBanner` instead
+-   For compact, space-constrained contexts — use `MicroBanner` instead
+-   For inline form field validation errors — show errors on the field itself instead
+-   Do not use banners as primary entry points to a flow or to communicate actions a user needs to complete on a regular basis.
+-   Avoid multiple banners on a page if possible. More than one banner dilutes their ability to draw attention and is disruptive to the user flow.
+
+## Usage
+
+-   Banners are naturally interruptive, but keep in mind their level of interruption should match the priority of the message they contain.
+-   Avoid more than one banner on screen at a time
+-   Add a title when the message needs a headline — this switches the banner to a multi-line layout
+-   Without a title, the banner renders as a compact single-line layout
+-   If the message is critical, do not let the user dismiss it.
+-   Use `primaryButton` and `secondaryButton` to offer CTAs. Button themes are inferred from the banner theme automatically — do not manually set button themes inside InlineBanner
+-   Use a caption below the CTAs for supplementary detail, plan names, or pricing info
+-   Only override the icon when there is a strong contextual reason — the default icon communicates the theme reliably
+
+### Where Do Banners Go?
+
+-   A good rule is to keep the banner relatively nearby to what it is referring to.
+-   Banners relevant to an entire page should be placed at the top of that page, below the page header. They should occupy the full width of the content area.
+-   Banners related to a section of a page (like a card, drawer, or modal) should be placed inside that section, below any section heading.
+-   When only a specific UI element is paywalled within a section of content, the feature is typically replaced with an UpsellBanner for said feature.
+
+### Choosing a theme
+
+| Theme     | When to use                                                                                                                                                                                             | Copy Tone                                                                                                                                               |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `info`    | Helpful information, an update or advice relevant to the current state.                                                                                                                                 | Written to highlight an opportunity: “Let's get you started\!”“Did you know…”                                                                           |
+| `warning` | Something that may cause problems if ignored or a potential problem on the current state.                                                                                                               | Casual but direct, _You should know before you proceed,_ tone.                                                                                          |
+| `danger`  | Something has gone wrong that must or should be resolved immediately. When the user is presented with a high risk action.                                                                               | Direct, clear and prescriptive about the next action. Explain what is wrong or dangerous, the consequences and how to resolve it.                       |
+| `success` | In most cases a toast can be used for a completed action. Use this instead when feedback is delayed, needs to be persistent or requires a call to action.                                               | Direct. Celebratory. Reiterating the benefit of the successful action .                                                                                 |
+| `upsell`  | When we need to communicate a message and it provides an opportunity to upsell a feature or addon. Should not be used as a persistent upsell state when a feature is missing \- use \`Paywall\` instead | Focus on the benefit a user will gain by upgrading. The benefit should be in context to what the user was doing or what section/page this banner is on. |
+
+## Additional Rules
+
+-   `children` is required — the banner body text.
+-   `theme` defaults to `"info"`. Always pass it explicitly so the intent is clear.
+-   Providing `title` changes the layout from single-line to multi-line. Do not use `title` for single-line messages where the body text is sufficient.
+-   `primaryButton` and `secondaryButton` accept a `Button` element. The component infers the correct button theme (`hollow` for primary, `link-primary` / `link-upsell` for secondary) — do not pass a `theme` prop on the button unless you intentionally need to override it.
+-   The `icon` prop is an escape hatch. Only use icons from Sous Chef — custom SVGs will break visual consistency.

package/llms-instructions/guidelines/Link.guidelines.md

@@ -0,0 +1,26 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To navigate to an external URL, opening it in a new tab
+-   To navigate within the app when the destination itself is the point — "View profile", "Learn more"
+-   When the clickable element lives inline inside a sentence or body copy
+
+## When Not to Use
+
+-   When the click triggers an action rather than navigation — use `Button` instead
+-   When the element stands alone as a primary or secondary call to action — use `Button` instead
+-   When opening a modal, drawer, or overlay — use `Button` instead
+
+## Usage
+
+-   Use theme="primary" (the default) on standard backgrounds. Use theme="contrast" when the link sits on a dark or inverse-coloured surface so it remains legible.
+-   Link text should describe the destination, not the action — "Scheduling documentation", not "Click here"
+-   Keep link labels concise; avoid linking full sentences
+-   Do not use Link for buttons that happen to be styled as text — if it triggers something, it's a Button
+
+## Additional Rules
+
+-   href is required. Do not render a Link without a valid destination.
+-   target defaults to \_blank. Explicitly pass target="\_self" for in-app navigation where staying in the same tab is the correct behaviour.
+-   theme defaults to "primary". Only pass theme="contrast" when the link is on a dark or inverse surface — using it on light backgrounds produces incorrect contrast ratios.

package/llms-instructions/guidelines/MicroBanner.guidelines.md

@@ -0,0 +1,21 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When a contextual message needs to fit inside a card, sidebar, or other constrained layout
+-   When only one action is needed alongside a brief message
+-   When the full scale of `InlineBanner` would be too dominant for the surrounding content
+
+## When Not to Use
+
+-   When the message needs two CTAs or a dismiss button — use `InlineBanner` instead
+-   For app-wide announcements — use `PersistentBanner` instead
+-   For transient action confirmations — use `Toast` instead
+
+## Usage
+
+-   See `InlineBanner` for broader guidelines on usage
+-   Unlike InlineBanners, MicroBanners can only have a maximum of 1 button
+-   Choosing between an `InlineBanner` and a `MicroBanner` is a design decision.
+-   As a general rule, you should use a MicroBanner when the space you're working within is too tight for a full banner (such as in a menu or sidebar).
+-   Use MicroBanner when it's ok to communicate less information and an InlineBanner is too disruptive to the layout of the page.

package/llms-instructions/guidelines/Modal.guidelines.md

@@ -0,0 +1,52 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When the user needs to make a decision before continuing — a confirmation, a destructive action, or a high-stakes choice
+-   As the entry or exit point of a short, self-contained flow — adding a location, inviting a team member, completing a quick setup
+-   When a complete task needs to stay in context without navigating to a new page
+-   For critical alerts that must be acknowledged before the user can proceed
+
+## When Not to Use
+
+-   In the middle of a longer multi-step flow — modal-within-modal patterns become disorienting quickly
+-   When the task only needs 1 or 2 lightweight actions — a `Popover` is less disruptive
+-   When the information is purely informational and requires no decision — use `InlineBanner`, `MicroBanner`, or `Tooltip` instead
+-   When the modal would cover content the user needs to reference while completing the task
+
+## Usage
+
+### Common Mistakes
+
+-   Modals are highly disruptive to a user's flow. As such, we should use them sparingly and with intention.
+-   Modal fatigue is a real problem, and occurs when users are served too many modals in a single experience. It causes users to lose focus, lose context and become frustrated.
+-   **NEVER** launch a modal from another modal.
+-   It can be tempting to use modals as a design short-cut when adding new functionality to an existing page without having to touch the existing design. Avoid this habit, and think about how you would design this page from scratch if the new functionality existed in the first place.
+
+### Structure
+
+A Modal is composed of four parts: the `Modal` wrapper (which handles the overlay and focus trapping), a `header` which contains the title (and an optional `subHeader`), a `ModalBody` for content, and a `ModalFooter` for actions. The `header` and optional `subHeader` appear at the top of the modal.
+
+### Sizing
+
+-   Modals by default are `500px` wide. We recommend sticking to this size whenever possible.
+-   A modal's height is variable based on the content. We recommend never making a modal more than `750px` in height.
+-   Avoid making a modal so large it feels like a full page; if content is that complex, consider whether a dedicated page is more appropriate.
+
+### Non-closable modals
+
+When `onClose` is omitted, the modal renders without a close button. Use this sparingly — during loading, for flows where closing partway through would leave data in an inconsistent state or for a critical action the user cannot ignore.
+
+## Tips & Tricks
+
+-   Modals are high interruption and high interaction. Use them deliberately — every unnecessary modal trains users to dismiss them without reading.
+-   A modal with a single "OK" button is usually a sign the content belongs in a banner or toast instead.
+-   Keep modal content focused. If you find yourself adding tabs, accordions, or nested forms, the modal is doing too much.
+-   The modal traps keyboard focus automatically — don't try to manage focus manually inside it.
+
+## Additional Rules
+
+-   `Modal` requires `Modal.setAppElement('#root')` (or equivalent) to be called once in the app, or `rootElementId` to be passed per instance, for correct accessibility behaviour.
+-   `ModalBody` and `ModalFooter` are required sub-components — do not render content directly as children of `Modal` without them.
+-   Use `loading={true}` during async operations to disable the close button and prevent users from interrupting a save or delete in progress.
+-   Modal uses a backdrop overlay; interaction with the page behind it is blocked while open.

package/llms-instructions/guidelines/PaginationControls.guidelines.md

@@ -0,0 +1,21 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   Consider adding pagination if your list of items is around 15 single line text rows in height or more.
+-   When a data set is split across multiple pages and the user needs to step forward or backward through them
+-   When the list or table has a fixed page size and the total count is large enough that showing all records at once is impractical
+
+## When Not to Use
+
+-   If there is a large data set and the user needs to be able quickly pick out a single item. If you are using this pattern consider including a search.
+-   When records load continuously as the user scrolls — use infinite scroll instead
+-   When there is only ever one page of results — hide or omit the controls entirely rather than rendering them in a permanently disabled state
+
+## Usage
+
+-   Place PaginationControls at the bottom of the paginated list or table, aligned to the trailing edge or centered depending on the layout.
+-   Both buttons are always rendered; disable `hasPrevious` on the first page and `hasNext` on the last page to communicate the boundary rather than hiding the buttons.
+-   Always keep both buttons visible. Hiding one button when it is unavailable causes the layout to shift and removes the affordance that pagination exists.
+-   Label the surrounding context clearly — PaginationControls provides no page count or position indicator. If the user needs to know "page 3 of 10", add that text adjacent to the controls.
+-   PaginationControls allow for keyboard navigation using the keys: (`J` / `K`)

package/llms-instructions/guidelines/Paywall.guidelines.md

@@ -0,0 +1,57 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When an entire page is locked because it belongs to a higher plan tier
+-   When a section or component within a page is locked behind a paid add-on
+-   When the user has access to the product but not to this specific feature
+
+## When Not to Use
+
+-   When content is empty for any reason other than a subscription gate — use `EmptyState` instead
+-   When the user has the right plan but hasn't set up the feature yet — use `EmptyState` instead
+-   When content is loading or erroring
+
+## Usage
+
+### Small
+
+Small should be used either when only a portion of the content on a page is paywalled or when a sub-feature on a page is paywalled.
+
+### Medium
+
+Also known as horizontal empty states. Used inline either when only a portion of the content on a page is paywalled or when a sub-feature on a page is paywalled. They differ from Small in that they provide the user more context to the empty state and they have some kind of call-to-action.
+
+### Large
+
+Also known as the Full Page Paywalls. Used when an entire page is paywalled.
+
+### As a Card
+
+Use `as="card"` with `size="medium"` when the Paywall needs to sit within a card container. Pass `onClose` to let the user dismiss it.
+
+### Images
+
+-   The image should use our Bento image format.
+-   Large empty states can use either a single frame bento, or a multi-frame collage
+-   Medium and small empty states should use a single frame bento
+-   Bentos frames can contain an Inking illustration, a lifestyle photo or UI mockup
+
+### Copy Best Practices
+
+-   Write in sentence case, with the usual exceptions of proper nouns such as a person, feature name, location, etc., being title case
+-   Use as few words as possible in the title and description. Be direct and clear.
+-   Avoid repeating content from the title in the body. Say things once with intent
+-   Avoid technical terms or jargon. Communicate using common words
+-   Always choose a simpler shorter words over longer fancier words
+-   The copy should explain what feature is behind a paywall and what value it can provide to the user if they add the feature to their plan.
+-   The title should communicate the message fully if possible, users are more likely to read this
+-   The body/description should be used to provide further important details or next steps
+-   caption appears below the action buttons — use it for secondary guidance or legal-style caveats, not as a substitute for body text.
+
+## Additional Rules
+
+-   `Paywall` passes `isPaywall={true}` to `EmptyStateContainer` internally — do not use `EmptyState` with any manual paywall flag. Always use the `Paywall` component so the visual treatment is applied correctly and consistently.
+-   `title` is required. All other props are optional but `actions.primary` should always be provided.
+-   `as`, `size`, `onClose`, `header`, `caption`, `mediaUrl`, and `actions` behave identically to `EmptyState` — refer to the EmptyState guidelines for usage details on those props.
+-   `onClose` is only valid when `as="card"`. Passing it in banner mode has no effect.