@7shifts/sous-chef 4.7.1 → 4.8.0

package/dist/layout/Card/Card.d.ts

@@ -10,5 +10,8 @@ type Props = {
     actions?: MenuAction[];
     testId?: string;
 } & PositionStyles & DataProps;
+/**
+ * Card is a versatile container that groups related content or options into a visually distinct surface. It's used to introduce visual separation between pieces of content without requiring a full page boundary. It is used to perceptually group content into a meaningful whole. Cards are simple container components that can hold whatever content the designer sees fit.
+ */
 declare const Card: ({ children, onClick, onClose, isSelected, disabled, actions, testId, ...rest }: Props) => React.JSX.Element;
 export default Card;

package/dist/layout/Page/Page.d.ts

@@ -18,5 +18,8 @@ type Props = {
     testId?: string;
     children: React.ReactNode;
 };
+/**
+ * Page component is used to control the elements within a page like breadcrumbs, title, subtitle, actions, banner, and filter bar.
+ */
 declare const Page: ({ children, breadcrumbs, title, subtitle, actions, banner, filterBar, size, testId }: Props) => React.JSX.Element;
 export default Page;

package/dist/lists/Accordion/Accordion.d.ts

@@ -6,5 +6,8 @@ type Props = {
     onExpand?: (item: AccordionItemType) => void;
     defaultOpenId?: string;
 } & DataProps;
+/**
+ * Accordion groups related content into a list of collapsible sections. Only one section can be open at a time, keeping the interface compact while still making all content accessible.
+ */
 declare const Accordion: ({ items, onExpand, defaultOpenId, ...rest }: Props) => React.JSX.Element | null;
 export default Accordion;

package/dist/lists/ActionList/ActionList.d.ts

@@ -7,5 +7,8 @@ type Props = {
     emptyState?: ActionListEmptyState;
     maxHeight?: number;
 };
+/**
+ * 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.
+ */
 declare const ActionList: ({ children, testId, title, emptyState, maxHeight }: Props) => React.JSX.Element;
 export default ActionList;

package/dist/lists/DataTable/DataTable.d.ts

@@ -33,5 +33,8 @@ type Props<T> = {
     stickyColumns?: StickyColumns;
     emptyState?: DataTableEmptyStateType;
 } & DataProps & PositionStyles;
+/**
+ * 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.
+ */
 declare const DataTable: <T extends unknown>({ items, columns, itemComponent, maxHeight, hasPrevious, hasNext, onPreviousClick, onNextClick, onSort, isLoading, showActionMenu, footerComponent, hasVerticalBorders, testId, skeletonRowLayout, stickyColumns, emptyState, ...rest }: Props<T>) => React.JSX.Element;
 export default DataTable;

package/dist/media/Avatar/Avatar.d.ts

@@ -8,5 +8,8 @@ type Props = {
     alt?: string;
     testId?: string;
 };
+/**
+ * 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.
+ */
 declare const Avatar: React.FC<Props>;
 export default Avatar;

package/dist/media/Badge/Badge.d.ts

@@ -2,9 +2,12 @@ import React from 'react';
 type Props = {
     children: React.ReactNode;
     theme?: 'success' | 'danger' | 'warning' | 'info';
-    /** This will show a black tooltip when the user hover the button */
+    /** This will show a black tooltip when the user hover the badge */
     title?: string;
     testId?: string;
 };
+/**
+ * Badge is a small circular indicator used to draw attention to something associated with another element — a count, a status, or a quick action.
+ */
 declare const Badge: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
 export default Badge;

package/dist/media/Chip/Chip.d.ts

@@ -7,5 +7,8 @@ type Props = {
     /** This is used for overriding the default data-testid */
     testId?: string;
 };
+/**
+ * Chip is a compact label used to communicate status about a nearby element — things like feature availability, product tier, or release stage. It is visually similar to Pill but serves a distinct purpose: where Pill communicates the status of data or records, Chip communicates the status of the product or interface itself.
+ */
 declare const Chip: ({ children, theme, testId }: Props) => React.JSX.Element;
 export default Chip;

package/dist/media/Pill/Pill.d.ts

@@ -6,5 +6,8 @@ type Props = {
     theme?: PillTheme;
     testId?: string;
 };
+/**
+ * Pill is a compact status label that communicates the current state of a data record or object. It appears alongside the thing it describes and gives users a quick, at-a-glance read on what state something is in — approved, pending, active, declined, and so on.
+ */
 declare const Pill: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
 export default Pill;

package/dist/navigation/Breadcrumbs/Breadcrumbs.d.ts

@@ -2,5 +2,8 @@ import React from 'react';
 type Props = {
     children: React.ReactNode;
 };
+/**
+ * Breadcrumbs show the user where they are in the app's hierarchy and let them navigate back up to a parent page. They appear at the top of a page when that page is reached by drilling into a deeper level of the product.
+ */
 declare const Breadcrumbs: ({ children }: Props) => React.JSX.Element;
 export default Breadcrumbs;

package/dist/navigation/PrimaryNav/PrimaryNav.d.ts

@@ -11,5 +11,8 @@ type Props = {
     /** Accessible label announced for the nav landmark. Defaults to "Main". */
     ariaLabel?: string;
 };
+/**
+ * PrimaryNav is a vertical navigation component that provides a consistent way for users to navigate through the main sections of an application.
+ */
 declare const PrimaryNav: ({ children, isExpanded, onToggleExpand, footer, shortLogo, longLogo, ariaLabel }: Props) => React.JSX.Element;
 export default PrimaryNav;

package/dist/navigation/Tabs/Tabs.d.ts

@@ -5,5 +5,8 @@ type Props = {
     defaultValue?: string;
     onValueChange?: (value: string) => void;
 };
+/**
+ * Tabs organize content into sections within a single view, letting users switch between them without leaving the page.
+ */
 declare const Tabs: ({ children, value, defaultValue, onValueChange }: Props) => React.JSX.Element;
 export default Tabs;

package/dist/overlay/Calendar/Calendar.d.ts

@@ -23,6 +23,8 @@ type Props = {
     testId?: string;
     onMonthChange?: (month: Date) => void;
 };
-/**Calendar overlay component*/
+/**
+ * Calendar is a date picker component that allows users to select a single day or a week. Used when you want to trigger it from a custom element such a button.
+ */
 declare const Calendar: React.FC<Props>;
 export default Calendar;

package/dist/overlay/Dropdown/Dropdown.d.ts

@@ -14,5 +14,8 @@ type Props = {
     /** Sets the z-index of the dropdown menu pane */
     zIndex?: number | ZIndex;
 };
+/**
+ * Dropdown is an overlay that reveals a list of actions or options when a user clicks or hovers a trigger element. It is the go-to pattern for contextual menus — things like "Edit, Duplicate, Delete" on a table row, or a set of filter options behind a button.
+ */
 declare const Dropdown: ({ trigger, triggersOn, alignment, width, maxHeight, testId, children, triggerWidth, zIndex }: Props) => React.JSX.Element;
 export default Dropdown;

package/dist/overlay/HintModal/HintModal.d.ts

@@ -11,5 +11,8 @@ export type Props = {
     testId?: string;
     onSetDoNotShowAgainStatus?: (doNotShowAgain: boolean) => void;
 } & PositionStyles;
+/**
+ * Hint Modal is a lightweight modal used to surface tips, guidance, or onboarding callouts to users the first time they encounter a feature or page. Unlike a regular Modal, it is not triggered by a user action — it appears automatically when the user navigates somewhere that warrants a guided introduction. It includes a "Don't show this again" option so users can dismiss it permanently once they've absorbed the information.
+ */
 declare const HintModal: ({ header, children, mediaUrl, onClose, modalId, primaryButton, secondaryButton, testId, onSetDoNotShowAgainStatus, ...positionProps }: Props) => React.JSX.Element;
 export default HintModal;

package/dist/overlay/Modal/Modal.d.ts

@@ -18,6 +18,9 @@ type Props = {
     shouldReturnFocusAfterClose?: boolean;
     testId?: string;
 } & DataProps;
+/**
+ * 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.
+ */
 declare const Modal: {
     ({ children, header, subHeader, onClose, loading, zIndex, rootElementId, width, height, maxWidth, shouldReturnFocusAfterClose, testId, ...otherProps }: Props): React.JSX.Element;
     setAppElement(rootElement: string | HTMLElement): void;

package/dist/overlay/Popover/Popover.d.ts

@@ -14,5 +14,8 @@ type Props = {
     /** Sets the z-index of the dropdown menu pane */
     zIndex?: number | ZIndex;
 };
+/**
+ * Popover is a contextual overlay "widget" that appears anchored to a trigger element and can contain rich, interactive content. It sits between a `Tooltip` and a `Modal` in terms of weight — less disruptive than a modal, but capable of real interaction unlike a tooltip. Use it when you need the user to take action in context, without pulling them away from what they were doing.
+ */
 declare const Popover: (props: Props) => React.JSX.Element;
 export default Popover;

package/dist/overlay/Tooltip/Tooltip.d.ts

@@ -24,5 +24,8 @@ type Props = {
     testId?: string;
     maxHeight?: string | number;
 };
+/**
+ * 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.
+ */
 declare const Tooltip: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLElement>>;
 export default Tooltip;

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

@@ -0,0 +1,20 @@
+## When to Use
+
+-   When the user needs to select from a list of options that is loaded dynamically from an API or other async source — employees, roles, locations, etc.
+-   When the full list of options is too large to load upfront and should be fetched on demand or filtered server-side
+-   When the available options depend on another field's value (e.g. employees filtered by location)
+
+## When Not to Use
+
+-   When the list of options is fixed and known at render time — use `SelectField` instead
+-   When the user must be able to select more than one option — use `MultiSelectField` instead
+-   When the options are few and benefit from being fully visible — use `RadioGroupField` or `PillSelectField` instead
+-   When the user needs to enter free-form text — use `TextField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Write placeholder text as a concrete search prompt ("Search for an employee") rather than a generic instruction ("Select something")
+-   Keep labels short — one to three words is ideal

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

@@ -25,6 +25,7 @@ Avatars can display different kinds of content. Within 7shifts, the entity being
 ### Sizes
 
 Avatars come in four sizes: `small`, `medium`, `large`, and `extra-large`. Choose the size based on how prominent the identity needs to be and what works in your layout.
+On table cells and list rows, `medium` is the most common size as `small` is quite small.
 
 ### Colour
 

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

@@ -2,6 +2,7 @@
 
 ## When to Use
 
+-   When using it outside of a `Page` component as it already handles breadcrumbs for you. But if you are using it outside of a `Page` component, use breadcrumbs when the user may need to navigate back to a parent page.
 -   When a page is nested within a parent section and the user may need to navigate back — for example, an employee detail page nested under the Employees list
 -   When the navigation path has two or more levels and the parent context is meaningful
 -   When the user arrived at the current page by drilling down from a list or overview

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

@@ -0,0 +1,20 @@
+## When to Use
+
+-   To collect a simple boolean confirmation from the user — agreeing to terms, enabling a setting, or acknowledging a statement
+-   When the user can independently toggle an option on or off without affecting other fields
+-   When multiple options may be selected from a list (use one `CheckboxField` per option rather than `RadioGroupField`, which enforces single selection)
+-   When a parent checkbox needs to represent a group of children with mixed checked/unchecked states — use the `indeterminate` prop
+
+## When Not to Use
+
+-   When only one option from a list may be chosen — use `RadioGroupField` instead
+-   When the user is selecting from a predefined list of many options — use `SelectField`, `MultiSelectField`, or `PillSelectField` instead
+-   When the value is not a simple boolean — use the appropriate typed field (`TextField`, `NumberField`, etc.)
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels and captions
+-   Write labels as affirmative statements the user is confirming ("Appear as employee", "Accept terms and conditions") rather than as questions
+-   Keep labels concise; use `caption` for any additional explanation that does not fit in a short label

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

@@ -0,0 +1,18 @@
+## When to Use
+
+-   When the user needs to choose a single color from the design system's sequential color palette — for example, assigning a color to a role, a tag, or a category
+-   When the stored value must be a hex string that maps back to a theme-aware sequential color token
+
+## When Not to Use
+
+-   When the user needs to select from a list of non-color options — use `SelectField` instead
+-   When color is purely decorative and not a user-configurable value — render a static swatch instead
+-   When you need a free-form text input — use `TextField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels and captions
+-   Keep labels short and descriptive — "Role color", "Tag color", "Event color"
+-   Use caption text to explain what the color will be applied to (e.g. "The color displayed on the schedule for this role")

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

@@ -0,0 +1,28 @@
+## When to Use
+
+-   When the user must enter a monetary value — wages, prices, budgets, tips, or any other currency amount
+-   When the input should be formatted as currency on blur (e.g. `1234.56` becomes `1,234.56`)
+-   When only non-negative numeric input is valid and a currency symbol prefix is expected
+
+## When Not to Use
+
+-   When the value is a plain number without currency semantics — use `NumberField` instead
+-   When the value is a percentage — use `PercentageField` instead
+-   When the user should pick from a predefined list of amounts — use `SelectField` instead
+-   When the input accepts any characters — use `TextField` instead
+
+## Usage
+
+### Formatting behaviour
+
+-   On blur the raw numeric value is normalized: two decimal places by default, zero decimal places when `step` is a whole number
+-   A thousands-separator mask (`1,234.56`) is displayed over the input when the field is not focused
+-   Scrolling over the input does not change the value (scroll-to-change is disabled)
+-   Negative values and the `e` key (scientific notation) are always blocked regardless of `step`
+
+### Copy
+
+-   Use short, descriptive labels in sentence case — "Hourly rate", "Amount", "Total cost"
+-   Do not use the label to explain the currency; the `currencySymbol` prefix communicates that visually
+-   Captions can clarify scope or units — e.g. "Before tax" or "Per shift" — but keep them brief
+-   Avoid placeholder text; the currency symbol prefix already signals the expected format

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

@@ -0,0 +1,22 @@
+## When to Use
+
+-   When the user must select a single specific date from a calendar widget
+-   When free-form date entry alone is insufficient and a visual calendar picker improves accuracy
+-   When you need to constrain selectable dates (e.g. past dates only, future dates only, or an arbitrary set of rules)
+-   When you want to highlight notable dates — pay days, holidays, blackout periods — directly on the calendar
+
+## When Not to Use
+
+-   When the user needs to select a start and end date — use `DateRangeField` instead
+-   When the user needs to select an entire week — use `WeekField` instead
+-   When the user needs to select a time — use `TimeField` instead
+-   When a date and time are needed together, compose `DateField` with `TimeField` separately
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Keep labels short and specific to the date being captured (e.g. "Start date", "Birthday", "Effective date")
+-   When the date has business significance, use a caption to clarify the expected value (e.g. "Date the change takes effect")
+-   Avoid overriding the placeholder unless the default format string is genuinely unclear in context

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

@@ -0,0 +1,21 @@
+## When to Use
+
+-   When the user must select both a start date and an end date to define a contiguous date range (e.g. time-off requests, pay periods, reporting windows)
+-   When the two date boundaries need to be chosen independently — the user picks the start first, then the end, via separate calendar pickers
+-   When you need to surface contextual date information alongside the picker (e.g. pay days, holidays, blackout periods) using `highlightedDays`
+
+## When Not to Use
+
+-   When only a single date is needed — use `DateField` instead
+-   When the selection must always span exactly seven consecutive days — use `WeekField` instead
+-   When the user is selecting a time range rather than a date range — use `TimeRangeField` instead
+-   When the range boundaries are times within a single day — use `TimeField` or `TimeRangeField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels and captions
+-   Labels should be short and describe the range being selected, not the action (e.g. "Time off range", "Pay period", "Report dates")
+-   Captions can clarify the purpose or constraints (e.g. "Select start and end date", "Maximum 7 days")
+-   The default placeholder mirrors the date format (`MM/DD/YYYY`); only override it if the format is non-obvious to the user

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

@@ -0,0 +1,22 @@
+## When to Use
+
+-   When the user needs to select more than one option from a predefined list — selected items appear as removable chips inside the field
+-   When the set of valid options is fixed and known ahead of time; for dynamic lists loaded from a server, use `AsyncSelectField` instead
+-   When you want to allow the user to create new options on the fly in addition to selecting from the existing list (via `onCreate` + `creatableButton`)
+-   When options benefit from logical grouping (e.g. cities grouped by province)
+
+## When Not to Use
+
+-   When only a single selection is allowed — use `SelectField` instead
+-   When the list of options is loaded dynamically from a server — use `AsyncSelectField` instead
+-   When the number of choices is small and benefits from full visual exposure — use `PillSelectField` or `CheckboxField` instead
+-   When the user must confirm a single boolean — use `CheckboxField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Write placeholder text as a concrete example of what to pick ("Select a language"), not as an instruction ("Choose options")
+-   Keep labels short — one to three words is ideal
+-   Label the `creatableButton` with an action phrase that names the thing being created ("Add city", "Create new type")

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

@@ -0,0 +1,29 @@
+## When to Use
+
+-   When the user must enter a numeric value — whole numbers by default
+-   When you need built-in range enforcement (minimum and maximum bounds)
+-   When the value may include decimals — configure `precision` and `stepSize` accordingly
+-   When negative values are valid — set `min` to a negative number to unlock them
+
+## When Not to Use
+
+-   When the value is a currency amount — use `CurrencyField` instead, which handles currency formatting automatically
+-   When the value is a percentage — use `PercentageField` instead
+-   When the input accepts any characters or free-form text — use `TextField` instead
+-   When the user should pick from a predefined list — use `SelectField` or `AsyncSelectField` instead
+-   When the value is a date or time — use `DateField`, `TimeField`, or their range variants instead
+
+## Usage
+
+### Behavior notes
+
+-   Scientific notation (`e`) and the `+` key are always blocked
+-   The `-` key is blocked when `min` is `0` or greater (the default); set `min` to a negative value to allow negative input
+-   The `.` key is blocked when `precision` is `0` (the default) or when the current value is already at `max`
+-   Scrolling the mouse wheel over the field does not change the value — the input loses focus on wheel to prevent accidental changes
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Keep labels short and specific to the value being entered (e.g. "Time off hours", "Max shifts per week")
+-   Write placeholder text as a concrete example ("e.g. 8"), not as an instruction ("Enter a number")

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

@@ -2,6 +2,7 @@
 
 ## When to Use
 
+-   When controlling pagination outside of the `DataTable` component. The `DataTable` component has its own built-in pagination controls, but if you are using a custom table or list implementation, you can use `PaginationControls` to provide the same functionality.
 -   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

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

@@ -0,0 +1,20 @@
+## When to Use
+
+-   To collect a password or other sensitive text input that should be masked by default
+-   When the user needs the option to reveal what they have typed (the toggle is always rendered)
+-   When you want to display a live checklist of password requirements that updates as the user types — use the `criterias` prop for this
+
+## When Not to Use
+
+-   When the input is not a password or sensitive secret — use `TextField` instead
+-   When you want to collect a PIN or numeric code — use `NumberField` or `TextField` depending on whether non-numeric characters are valid
+-   When you need to confirm a password matches — render two separate `PasswordField` instances and validate the values yourself; the component does not handle confirmation internally
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels and placeholder text
+-   Label the field "Password" for login flows and "New password" / "Confirm password" for registration or change-password flows
+-   Keep placeholder text generic (e.g. "Type your password") — avoid hinting at format requirements in the placeholder; use `criterias` for that instead
+-   Write each criteria label as a short, scannable rule in plain language (e.g. "Min. 8 characters", "1 uppercase letter")

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

@@ -0,0 +1,22 @@
+## When to Use
+
+-   When the user must enter a percentage value — tips contribution, tax rate, discount percentage, etc.
+-   When the input must be constrained to a numeric range with a `%` suffix displayed automatically
+-   When the percentage should be a whole integer between 0 and 100 (the default behavior)
+-   When the percentage may need decimal precision (e.g. 12.5%) or allow negative values (e.g. -10%)
+
+## When Not to Use
+
+-   When the value is a plain number with no percentage meaning — use `NumberField` instead
+-   When the value is a currency amount — use `CurrencyField` instead
+-   When the value is free-form text — use `TextField` instead
+-   When the user should pick from a predefined list of options — use `SelectField` or `AsyncSelectField` instead
+-   When the value is a date or time — use `DateField`, `TimeField`, or their range variants instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Keep labels short and outcome-focused — "Tips contribution", "Discount rate", "Tax rate"
+-   Use caption text to clarify the range or meaning when it is not obvious from the label alone (e.g. "The amount of sales contributed to the tip pool")

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

@@ -0,0 +1,23 @@
+## When to Use
+
+-   When collecting a phone number from the user, especially when the number may be international
+-   When you need built-in country code selection alongside phone number input
+-   When phone number validation is required — the field formats input as the user types and validates on blur using `libphonenumber-js`
+-   When integrating with Formik/Yup validation using the exported `isValidPhoneNumber` helper
+
+## When Not to Use
+
+-   When collecting free-form text that happens to include numbers — use `TextField` instead
+-   When collecting a numeric value (not a phone number) — use `NumberField` instead
+-   When you only need a plain text input with no formatting — use `TextField` instead
+
+## Usage
+
+Changing the country resets the phone input and calls `onChange("")` automatically.
+
+### Copy
+
+-   Use sentence case for labels and captions
+-   A label of "Phone" is sufficient in most contexts; use "Mobile number" or "Work phone" only when distinguishing between multiple phone fields
+-   Write captions as context, not instructions — e.g. "The best number we can reach you" rather than "Enter your phone number"
+-   Do not use placeholder text as a substitute for a label

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

@@ -0,0 +1,22 @@
+## When to Use
+
+-   When the user must select one or more options from a small, fixed set and the options benefit from being visible all at once rather than hidden in a dropdown
+-   When options are short labels that fit naturally as pills — days of the week, shift types, role names
+-   When the option count is low enough that displaying them inline does not cause visual clutter (roughly 2–10 items)
+-   When users may also need to add or remove their own custom options at runtime (use the creatable mode via `createOptionLabel` and `onCreate`)
+
+## When Not to Use
+
+-   When the option list is long or dynamic — use `SelectField` or `AsyncSelectField` instead
+-   When only a single selection is allowed and all options must be visible — use `RadioGroupField` instead
+-   When multiple selections are needed from a longer, searchable list — use `MultiSelectField` instead
+-   When options carry enough detail that a pill label alone is insufficient context
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels and captions
+-   Keep option labels short — one or two words is ideal for pills (e.g. "Mon", "Server", "Host")
+-   Caption text should describe what the selection controls, not restate the label (e.g. "Select the days your location is open")
+-   For `createOptionLabel`, use an action phrase such as "Add your own" or "Add option"

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

@@ -0,0 +1,20 @@
+## When to Use
+
+-   When the user must select exactly one option from a visible list and needs to see all choices at once to make an informed decision
+-   When the number of options is small enough that displaying them all simultaneously is practical
+-   When the visual presentation of choices matters — use box-style options (`RadioGroupBoxOption`) for card-like selections with icons or extra context, and standard options (`RadioGroupOption`) for simple text lists
+
+## When Not to Use
+
+-   When the user can select more than one option — use `CheckboxField` or `MultiSelectField` instead
+-   When the option list is long or dynamic — use `SelectField` or `AsyncSelectField` instead, which hide options behind a dropdown
+-   When choosing from a short, visually distinct set where a pill layout is preferred — use `PillSelectField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for the group `label`, option labels, and `caption` text
+-   Keep option labels concise — one to four words is ideal
+-   Use `caption` on individual options (via `RadioGroupOption` or `RadioGroupBoxOption`) to add brief clarifying detail without cluttering the label
+-   Write the group `label` as a noun or short noun phrase ("Restaurant type", "Day parts"), not as a question or instruction

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

@@ -0,0 +1,24 @@
+## When to Use
+
+-   When the user must choose exactly one option from a fixed, predefined list
+-   When the list of options is static and known at render time — use `AsyncSelectField` when options are dynamic or fetched from a server
+-   When the number of options is large enough that radio buttons would be unwieldy, but the user still only needs a single selection
+-   When options can be logically grouped into labeled categories
+
+## When Not to Use
+
+-   When the list of options is dynamic or loaded from a server — use `AsyncSelectField` instead
+-   When the user needs to select more than one option — use `MultiSelectField` instead
+-   When the list is short and all options should be visible at once — use `RadioGroupField` instead
+-   When the user should select from a visual set of pills (e.g. days of the week) — use `PillSelectField` instead
+-   When the value is a date or time — use `DateField`, `TimeField`, or their range variants instead
+-   When the value is a color — use `ColorField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Write placeholder text as a prompt to act, e.g. "Select a language" rather than repeating the label verbatim
+-   Keep labels short — one to three words is ideal
+-   For grouped options, use concise, descriptive group labels (e.g. "Saskatchewan", "Alberta") that help the user scan quickly

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

@@ -15,6 +15,10 @@
 
 ## Usage
 
+### Spanning Tabs
+
+A set of Tabs should always span to fill the entire width of their container, even when the tabs themselves are not long enough to fill it. This gives Tabs a grounded structural feel, instead of feeling like they are floating. The `TabPanel` should also span the entire width of the container and always match the width of the tabs.
+
 ### Tab labels
 
 Keep tab labels short — one or two words at most. Labels should name the content category, not describe an action. Use sentence case.

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

@@ -0,0 +1,25 @@
+## When to Use
+
+-   When the input is expected to span multiple lines — notes, descriptions, comments, or other long-form text
+-   When the user needs more vertical space to write freely without a fixed line cap
+-   When you want to optionally enforce a character limit and show a live countdown to the user
+-   When the field needs an embedded toolbar (e.g. action buttons, formatting controls) rendered inside the input area
+
+## When Not to Use
+
+-   When a single line of input is sufficient — use `TextField` instead
+-   When only numbers are valid — use `NumberField` instead
+-   When the value is a currency amount — use `CurrencyField` instead
+-   When the value is a percentage — use `PercentageField` instead
+-   When the user should pick from a predefined list — use `SelectField` or `AsyncSelectField` instead
+-   When the value is a date or time — use `DateField`, `TimeField`, or their range variants instead
+-   When the input is a password — use `PasswordField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Write placeholder text as a concrete example ("e.g. Available Monday mornings"), not as an instruction ("Enter your notes")
+-   Keep labels short — one to three words is ideal
+-   Use captions to set expectations about how the text will be used (e.g. "These notes will be visible on the schedule")

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

@@ -0,0 +1,22 @@
+## When to Use
+
+-   To collect short, free-form text from the user — names, titles, search queries, notes
+-   When the input accepts any characters and has no format constraints
+-   When a single line of input is sufficient — use `TextAreaField` for longer or multi-line text
+
+## When Not to Use
+
+-   When only numbers are valid — use `NumberField` instead
+-   When the value is a currency amount — use `CurrencyField` instead
+-   When the value is a percentage — use `PercentageField` instead
+-   When the user should pick from a predefined list — use `SelectField` or `AsyncSelectField` instead
+-   When the value is a date or time — use `DateField`, `TimeField`, or their range variants instead
+-   When the input is a password — use `PasswordField` instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Write placeholder text as a concrete example ("e.g. Alex Smith"), not as an instruction ("Enter your name")
+-   Keep labels short — one to three words is ideal