@7shifts/sous-chef 4.4.1 → 4.6.0-beta.0

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.

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

@@ -0,0 +1,33 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   For global messages that apply to the entire application, not a specific page or section
+-   When the message must stay visible until the user dismisses it or the condition resolves
+-   For billing, subscription, or plan-level notices that affect access across the app
+-   App-wide service announcements, outages, or planned maintenance
+
+## When Not to Use
+
+-   For page- or section-specific messages — use `InlineBanner` instead
+-   For brief action confirmations — use `Toast` instead
+-   For compact, space-constrained contexts — use `MicroBanner` instead
+
+## Usage
+
+-   Choose a theme that is appropriate to the urgency and context of your message. See the `Themes` page for more information on using themes.
+-   Keep the message brief — PersistentBanner has no title, so the body text must stand alone and be scannable in one line
+-   For buttons use `hollow-contrast` for primary, `link-contrast` for secondary — do not override them
+-   You can make a banner dismissable. Use when the information is non-critical and users can reasonably acknowledge it later.
+-   One at a time — only one Persistent Banner should appear at a time. If multiple messages compete, show the most critical one.
+-   Reserve for app-wide scope — if the message applies only to a specific page or workflow, use Inline Banner instead.
+-   Lead with the issue — state what happened or what is needed before explaining why.
+
+## Additional Rules
+
+-   Use `onDismiss` to let the user close the banner. When provided, a close button appears automatically. Managing whether the banner re-appears is the responsibility of the caller.
+    `theme` defaults to "info". Always pass it explicitly.
+-   `theme` defaults to `"info"`. Always pass it explicitly.
+-   `primaryButton` and `secondaryButton` accept `Button` elements. The component forcefully applies `hollow-contrast` to the primary button and `link-contrast` to the secondary button — any `theme` passed on the button itself will be overridden.
+-   `onLoad` fires once on mount — use it to trigger analytics or logging when the banner becomes visible.
+-   `onDismiss` does not hide the banner automatically. The caller is responsible for conditionally rendering the component based on dismissed state.

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

@@ -0,0 +1,55 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To show the status of a record — a shift, an employee, a request, an approval
+-   When a list or table row has a state that users need to scan quickly
+-   When status needs to be communicated without interrupting the reading flow of a label or title
+
+## When Not to Use
+
+-   To communicate system or product-level status (feature availability, release stage) — use `Chip` instead
+-   When the status requires more explanation than a short label can provide — use `InlineBanner` or `MicroBanner` or a tooltip alongside it
+-   As a decorative element — every Pill should correspond to a real, meaningful state
+
+## Usage
+
+### Chip or Pill?
+
+Pill and Chip are visually similar and often confused. Use this table to decide which one to reach for:
+
+| Question                                                       | Yes  | No   |
+| -------------------------------------------------------------- | ---- | ---- |
+| Is it in a DataTable?                                          | Pill | Chip |
+| Are there multiple items in a cluster that each have a status? | Pill | Chip |
+| Is the status related to a page, section, card, or menu item?  | Chip | Pill |
+| Is the status something the user can change through an action? | Pill | Chip |
+| Is the status promotional in nature?                           | Chip | Pill |
+| Can the item be created, edited, or deleted?                   | Pill | Chip |
+
+### Themes
+
+Pill's theme controls its colour and signals the nature of the status at a glance. Use themes consistently across the product so users learn to read them quickly:
+
+| Theme     | Use                                   | Examples                                        |
+| --------- | ------------------------------------- | ----------------------------------------------- |
+| `default` | Neutral or unclear state              | Pending, Unavailable, Inactive                  |
+| `success` | Positive or active state              | Active, Approved, Available, Connected, Enabled |
+| `danger`  | Critical or negative state            | Declined, Deleted, Closed, Errors               |
+| `warning` | Cautionary or at-risk state           | Expiring, Overdue, Needs Attention              |
+| `info`    | Something has changed or been updated | Modified, Updated                               |
+| `upsell`  | Premium or gated content              | Pro, Premium                                    |
+
+## Tips & Tricks
+
+-   Pill content is almost always a short status label — one to three words.
+-   Use themes consistently. If "Approved" is always `success` green in one part of the product, it should be everywhere. Inconsistent theme use erodes the visual language users learn to rely on.
+-   Pill and Chip look alike but mean different things. Ask: is this the state of a record in the system, or the state of a product feature? Record → Pill. Feature → Chip.
+-   Avoid using more than one Pill per row in a dense list unless each one describes a genuinely different dimension of that record. Multiple pills per row adds visual noise and competes for attention.
+-   Default (grey) is for genuinely neutral states — not a fallback when you're unsure which theme to use. If the state has a clear positive or negative valence, pick the right colour.
+
+## Additional Rules
+
+-   `theme` defaults to `default` if not specified.
+-   When `children` is a string or non-numeric value, an `alphabetical` style variant is applied automatically for appropriate letter-spacing and padding.
+-   Pill accepts a forwarded ref, making it usable as an anchor for tooltips or popovers when additional context is needed.

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

@@ -0,0 +1,42 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When a short task is directly tied to a specific element — editing contact details on a profile row, configuring an option on a widget
+-   When a user needs to interact with content, not just read it — buttons, forms, or selections that relate to the trigger
+-   When a modal would feel like overkill — the task is lightweight and doesn't require the user's full, undivided attention
+-   For micro-flows of one or two steps that are part of a larger workflow
+
+## When Not to Use
+
+-   For complex multi-step flows — if the task has more than a couple of steps or requires significant decision-making, use a `Modal`
+-   For read-only information with no interaction needed — use a `Tooltip` instead
+-   As a replacement for a `Dropdown` when the content is simply a list of actions — `Dropdown` is the right tool for action menus
+-   When the content is so large it obscures a significant portion of the page
+
+## Usage
+
+### Content
+
+Popover is an intentionally open canvas — it doesn't prescribe a structure the way Modal or Dropdown does. You build the content yourself using whatever layout and components the task requires. Keep the content focused on a single task or piece of information. If you find yourself adding tabs or multiple distinct sections, the task has outgrown the Popover.
+
+### Trigger behaviour
+
+Like Dropdown, Popover accepts a `trigger` element and opens on click or hover. Click is strongly preferred for interactive content — hover triggers are difficult to use on touch devices and can be accidentally triggered.
+
+### Placement and alignment
+
+The popover panel positions itself relative to the trigger. Use `alignment` to control which side it opens on when the default causes overflow or covers adjacent content.
+
+## Tips & Tricks
+
+-   Think of Popover as the middle ground on the disruption scale: more capable than a Tooltip, lighter than a Modal. If your content is purely informational, reach for Tooltip. If it needs a decision, reach for Modal. If it needs light interaction in context, Popover is the right fit.
+-   Popovers work best when they feel attached to what triggered them — keep content tightly focused on the element the user clicked.
+-   Never chain Popovers — opening a second Popover from inside a Popover adds complexity that's hard for users to navigate. If a task has branching paths, escalate to a Modal.
+-   If you're unsure whether to use a Dropdown or a Popover: Dropdown is for lists of actions. Popover is for everything richer than that.
+
+## Additional Rules
+
+-   `trigger` is required and must accept a forwarded ref.
+-   Popover and Dropdown share the same underlying positioning API — the distinction is in what goes inside, not how they open.
+-   Content is rendered as an open `children` slot — use layout components like `Stack` and `Inline` to structure the panel contents.

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

@@ -0,0 +1,35 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To show progress through a multi-step flow — onboarding, setup wizards, form sequences
+-   File uploads or processing operations where percentage completion is quantifiable
+-   Stepped checkout or configuration flows that benefit from named checkpoints (e.g. "Step 1", "Invite Team")
+-   When a horizontal format fits the layout better than a circular indicator
+
+## When Not to Use
+
+-   When progress is circular or needs to be displayed compactly — use `CircularProgress` instead
+-   When there is no meaningful progress to communicate — do not use as a decorative element
+-   When the total amount of work/steps is unknown
+-   When communicating pass/fail or complete/incomplete status
+
+## Usage
+
+Supports two modes: Simple and Stepped
+
+### Simple
+
+A continuously filling bar. Progress is treated as a percentage by default, or against a custom max value.
+
+### Stepped
+
+The bar fills to the center of the active step, anchoring the indicator to a discrete position. With step labels enabled, text labels render below the bar — one per step, evenly distributed across the full width.
+
+### Best Practices
+
+-   Use `maxValue` without `steps` when progress is a raw number rather than a step index — for example, `progress={35}` out of `maxValue={100}` for a percentage.
+-   Keep step labels short so they fit evenly below the bar without wrapping.
+-   Step labels should be short noun phrases: "Step 1", "Account Setup", "Invite Team". Avoid full sentences.
+-   Keep label style consistent across all steps in a given bar — do not mix "Step N" style labels with verbose descriptive labels in the same instance.
+-   Labels use sentence case.

package/llms-instructions/guidelines/SegmentedControl.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
+
+-   In a toolbar to switch between two or three distinct views of the same content (e.g. Day / Week / Month)
+-   When the options are mutually exclusive and switching between them is immediate
+-   When all available options should be visible at a glance rather than hidden in a dropdown
+
+## When Not to Use
+
+-   When you are switching between sub-pages - use a tab instead.
+-   When the entire content of the page is switching - use a tab instead.
+-   When there are too many options to comfortably fit in the frame.
+-   When the user is submitting a value as part of a form — use a radio group instead.
+-   When the options trigger an action rather than change a view — use a `Button` group instead
+
+## Usage
+
+-   You may include as many items as necessary and will fit in your frame, however the SegmentedControl should never be longer than the component it is controlling.
+-   Keep option labels short — one or two words. The control is sized to its content, so long labels create an unbalanced layout.
+-   Use nouns or short noun phrases that describe the view, not verbs — "Day", "Week", "Month", not "Show Day", "Show Week".

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

@@ -0,0 +1,30 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When loading a page, list, table, or card where the layout is known in advance
+-   When the loading duration is long enough that a blank area would feel broken
+-   To prevent layout shift — match the skeleton dimensions closely to the content that will replace it
+
+## When Not to Use
+
+-   For short, unpredictable loading operations — use `Spinner` instead
+-   As a permanent placeholder — it should always be replaced by real content once loading is complete.
+-   When the layout of the loading content is unknown — a rough skeleton is better than no skeleton, but if the shape would be misleading, use `Spinner`
+
+## Usage
+
+-   Use `as` to match a specific Sous Chef component shape. When no preset fits, use `height` and `width` to size it manually.
+    -   `avatar` - Circular avatar at various sizes
+    -   `button` - Button-shaped rectangle
+    -   `pill` - Pill/badge shape
+    -   _(none)_ - Plain rectangle — size with `height` and `width`
+
+*   Build skeleton layouts that closely match the structure of the real content — a row of skeletons for a list, a wide block for a heading, narrower blocks for body text
+*   The loading animation is intentionally delayed by 3.5 seconds to avoid a flash on fast loads
+
+## Additional Rules
+
+-   When `as` is not provided, `height` and `width` must be set manually — an unsized skeleton collapses to zero height.
+-   `height` and `width` accept a number (pixels) or a string with units (e.g. `"75%"`, `"2rem"`).
+-   `as` and manual sizing can be combined — `as` sets the shape, and `height`/`width` override the default dimensions of that shape if needed.

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

@@ -0,0 +1,32 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When an operation is in progress and the user must wait — submitting a form, fetching data, processing a request
+-   As a loading state inside a `Button` (handled automatically by `Button`'s `loading` prop)
+
+## When Not to Use
+
+-   When loading a page or a structured list of content — use `Skeleton` instead, which reduces layout shift and sets better expectations
+-   When no async operation is happening — never show a spinner for decorative purposes
+-   loading times are expected to be more than a few seconds. If a spinner is used for a longer load time it can appear to be "stuck" even when its not.
+-   If load times are going to be more than a few seconds we should communicate how long the expected wait time will be.
+
+## Usage
+
+-   The default `size` of 28px suits most contexts. Increase it only when the spinner needs to fill a large empty area.
+-   Spinners have their own unique set of themes. These differ from the semantic themes that apply to other components like banners.
+
+| Theme      | When to use                                                              |
+| ---------- | ------------------------------------------------------------------------ |
+| `mint`     | Standard backgrounds (default)                                           |
+| `contrast` | Inverse-coloured surfaces that require more visual contrast              |
+| `disabled` | Inside a disabled element such as a disabled `Button` in a loading state |
+| `pride`    | Seasonal spinner that is active during pride month (June 1-30)           |
+
+## Additional Rules
+
+-   `Button` manages its own spinner internally via the `loading` prop — do not place a `Spinner` inside a `Button` manually.
+-   `theme` defaults to `"mint"`
+-   `block` defaults to `false`. Pass `block={true}` when centring in a container, rather than wrapping the spinner in a custom centering div.
+-   `size` is in pixels and defaults to `28`. Do not pass fractional values.

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

@@ -0,0 +1,34 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To confirm that an action completed successfully — "Schedule published", "Changes saved"
+-   To notify the user of an error that occurred as a result of an action they just took
+-   When the message is transient and the user does not need to act on it
+-   When an optional follow-up action (like "Undo") is available
+
+## When Not to Use
+
+-   When the message requires the user to read and respond before continuing — use a modal or `InlineBanner` instead
+-   When the message is persistent and must remain visible — use `InlineBanner` or `PersistentBanner` instead
+-   When the message is not triggered by a user action — use a banner instead
+-   For validation errors on a form — show errors inline on the field instead
+
+## Usage
+
+### Behaviour
+
+-   Toast dismisses on its own — the user does not need to interact with it.
+-   Toasts are automatically always placed 32px from the bottom of the screen, and are centred left and right.
+-   If an action is easily undoable, then provide the user the option to undo.
+
+### Best Practices
+
+-   Use `theme="default"` for confirmations and neutral notifications. Use `theme="danger"` for errors.
+-   Toasts should be fired after an action has occurred, such as clicking a submit button in a form.
+-   Make sure to call toast at least one component level below the `<SousChefProvider>`.
+
+### Copy Writing
+
+-   Keep toast messages to one short sentence — the user only has a few seconds to read it
+-   Write in past tense for confirmations ("Schedule published") and plain present tense for errors ("Something went wrong")

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

@@ -0,0 +1,19 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To enable or disable a feature or preference that takes effect immediately
+-   When the on/off state is clear and the consequence is easily reversible
+-   When a single boolean setting needs to stand on its own outside of a form
+
+## When Not to Use
+
+-   Inside a form that requires a submit action to save — use a `Checkbox` instead
+-   When the user is selecting one option from a group of mutually exclusive choices — use a radio group instead
+-   When more than two states are needed — use a `Select` or `SegmentedControl` instead
+
+## Usage
+
+-   The label should describe the feature or setting being controlled, not the state — "Email notifications", not "Turn on email notifications"
+-   Use `caption` to add a short supporting sentence when the label alone may not be enough to communicate the consequence of toggling
+-   Avoid using Toggle for settings where the effect is delayed or requires confirmation — the visual design implies immediate action

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

@@ -0,0 +1,22 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   In a page toolbar or a component toolbar to filter content by a single dimension — location, role, status, etc.
+-   When the option list is too long for a `SegmentedControl`
+-   When options need to be grouped or some options need to be individually disabled
+
+## When Not to Use
+
+-   Inside a form — use `SelectField` instead
+-   When the selection should trigger an action rather than filter content — use a `Button` or `DropdownButton` instead
+-   When the user needs to select multiple values — use a multi-select form field instead
+-   When there are only 2 or 3 static ungrouped actions - use a `SegmentedControl` instead
+
+## Usage
+
+-   Always place ToolbarSelect in a toolbar alongside other filters and controls, not inline within page content
+-   Use `prefix` to add an icon before the selected value, which helps identify what the filter controls at a glance — especially useful when multiple ToolbarSelects appear in the same toolbar
+-   Use `placeholder` to indicate what the filter represents when no selection has been made — e.g. "All locations", "All roles"
+-   Use grouped options (`WithDropdownGroups`) when the option list has a natural category structure that helps the user scan and find the right choice faster
+-   Use `creatableButton` sparingly — only when the user legitimately needs to add new options on the fly as part of their workflow

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

@@ -0,0 +1,45 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To label an icon-only button or control where the action isn't immediately obvious
+-   To define an unfamiliar term, metric, or abbreviation — things like "SPLH" that not every user will know on sight
+-   To show additional metadata that is helpful but not essential to the main task
+-   To provide extra context for a truncated label or condensed data point
+
+## When Not to Use
+
+-   For critical information the user must see to complete a task — don't hide required context behind a hover
+-   When the content needs buttons, links, or any interactive element — use a `Popover` instead
+-   When the explanation is more than one or two lines — if it takes a paragraph, it belongs in a help article or inline copy
+-   As a workaround for unclear UI copy — if something needs a tooltip to be understood, first ask whether the label itself can be improved
+
+## Usage
+
+### Content
+
+Keep it short — one line is ideal, two is the limit. Write in plain, direct language. If you need a heading alongside the content, the `header` prop adds a bold label above the body text.
+
+### Themes
+
+Tooltip always use the inverse theme the product is using. If the product is in `light mode` the tooltip will be dark. If the product is in `dark mode` the tooltip will be light. This helps give it enough contrast to stand out from the background.
+
+### Placement
+
+The tooltip appears above or below the trigger by default, and will reposition itself automatically based on available screen space. You can suggest a preferred `placement` (`top` or `bottom`), but the component may override it to keep the tooltip on screen.
+
+### Delays
+
+`delayOnOpen` adds a small pause before the tooltip appears — useful when a trigger is near other interactive elements and you want to avoid tooltips flashing as the user moves between them. `delayOnClose` keeps the tooltip open briefly after the user moves away, which is helpful when the overlay itself contains selectable text or a link (only relevant for the white theme with `delayOnClose`).
+
+## Tips & Tricks
+
+-   Every icon-only button should have a tooltip. "What does this button do?" is a question a tooltip can always answer.
+-   Don't rely on tooltips to rescue confusing UI. If every element on a page needs a tooltip to be understood, the interface needs redesigning, not more tooltips.
+-   Avoid putting the same text in both the visible label and the tooltip.
+
+## Additional Rules
+
+-   `overlay` is the content prop — it accepts text or JSX, but keep interactive elements out of tooltips unless you're using `delayOnClose` intentionally.
+-   Tooltip wraps its `children` as the trigger — whatever element is passed as children becomes the hover anchor.
+-   The component repositions automatically to stay on screen; the `placement` prop is a preference, not a guarantee.