# foods

> `@foodpilot/foods` is FoodPilot's design system for React: the MUI-based components, tenant themes (FoodPilot, WinePilot, Positive) and charts of platform-app. Its Storybook (https://foods-storybook.foodpilot.tech) documents every component as IBM Carbon's does: an Overview page with the usage guidelines from the Figma Design System (https://www.figma.com/design/ucJSnn3mHlv4MCnwe1oZ2Z/Design-System), the stories and the props.

- Install `@foodpilot/foods` with its peers: `react` and `react-dom` 18 or 19, `@mui/material` ^6.4, `@emotion/react` and `@emotion/styled` ^11.14, `i18next`, `react-i18next` and `lodash`. `@mui/icons-material`, `@mui/lab`, the `@mui/x-*` packages, `recharts` and `material-react-table` are needed only by the components that use them.
- Wrap the application in `FoodsThemeProvider` from `@foodpilot/foods/themes` (`theme`: `"foodpilot"`, `"winepilot"` or `"collective"`) and style with the theme tokens (palette, 8 px spacing, typography variants, shadows), never raw values.
- Every export is named. Import from the root entry or, for the best tree-shaking, from a component entry: `@foodpilot/foods`, `@foodpilot/foods/themes`, `@foodpilot/foods/Button`, `@foodpilot/foods/Link`, `@foodpilot/foods/Badge`, `@foodpilot/foods/Box`, `@foodpilot/foods/CustomTypography`, `@foodpilot/foods/Icons`, `@foodpilot/foods/Tooltip`, `@foodpilot/foods/Tags`, `@foodpilot/foods/Number`, `@foodpilot/foods/NumberInput`, `@foodpilot/foods/Progress`, `@foodpilot/foods/LinearProgress`, `@foodpilot/foods/Input`, `@foodpilot/foods/Select`, `@foodpilot/foods/MultiSelect`, `@foodpilot/foods/UnitConverterPanel`, `@foodpilot/foods/Checkbox`, `@foodpilot/foods/Radio`, `@foodpilot/foods/Textarea`, `@foodpilot/foods/Search`, `@foodpilot/foods/Filter`, `@foodpilot/foods/ToggleSwitch`, `@foodpilot/foods/Field`, `@foodpilot/foods/Form`, `@foodpilot/foods/Accordion`, `@foodpilot/foods/Banner`, `@foodpilot/foods/Cards`, `@foodpilot/foods/CardImage`, `@foodpilot/foods/Dialog`, `@foodpilot/foods/Grid`, `@foodpilot/foods/Layout`, `@foodpilot/foods/Navigation`, `@foodpilot/foods/Popover`, `@foodpilot/foods/ProgressCard`, `@foodpilot/foods/Tabs`, `@foodpilot/foods/ComparisonBlock`, `@foodpilot/foods/Text`, `@foodpilot/foods/CMS`, `@foodpilot/foods/Treeview`, `@foodpilot/foods/Chart`, `@foodpilot/foods/RichTextEditor`, `@foodpilot/foods/ActionPlan`, `@foodpilot/foods/Pagination`, `@foodpilot/foods/Avatar`, `@foodpilot/foods/Snackbar`, `@foodpilot/foods/FileButton`.
- Components translate their texts with `react-i18next`, with the English strings as keys; the application provides the translations.
- Pick components from the Components lists; Layout holds page layouts and Preview components still in progress. Optional lists the Legacy and Deprecated pages: never use them in new work.

## Getting Started

- [Welcome](https://foods-storybook.foodpilot.tech/?path=/docs/getting-started-welcome--welcome): [Source](https://github.com/Foodpilot/foods/blob/main/src/getting-started/Welcome.mdx)
- [Designers](https://foods-storybook.foodpilot.tech/?path=/docs/getting-started-designers--designers): The FoodPilot Design System lives in two places that describe the same components: the [Figma Design System](https://www.figma.com/design/ucJSnn3mHlv4MCnwe1oZ2Z/Design-System) and this Storybook, which renders the real `@foodpilot/foods` React components that platform-app uses. [Source](https://github.com/Foodpilot/foods/blob/main/src/getting-started/Designers.mdx)
- [Developers](https://foods-storybook.foodpilot.tech/?path=/docs/getting-started-developers--developers): How to install and use `@foodpilot/foods` in an application, and how to work on the library and this Storybook. [Source](https://github.com/Foodpilot/foods/blob/main/src/getting-started/Developers.mdx)
- [Product](https://foods-storybook.foodpilot.tech/?path=/docs/getting-started-product--product): `@foodpilot/foods` is the React component library behind platform-app, for the FoodPilot, WinePilot and Positive tenants. [Source](https://github.com/Foodpilot/foods/blob/main/src/getting-started/Product.mdx)

## Components: Actions

- [Button](https://foods-storybook.foodpilot.tech/?path=/docs/button--overview): FoodPilot's Button is MUI's Button with the Figma families as `variant`: Primary for the one main action of a view, Secondary beside it, Validate to confirm entered data, Delete, Delete outline and Error (Delete text) for destructive actions, Text for low-emphasis actions and Dataviz inside a data-coloured container; icon-only actions use FoodsIconButton. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/Button/Button.stories.tsx)
- [ButtonPlayground](https://foods-storybook.foodpilot.tech/?path=/docs/buttonplayground--overview): Every prop of the FoodPilot Button (MUI's Button with the Figma variants) as a control. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/ButtonPlayground.stories.tsx)
- [FoodsDeleteButton](https://foods-storybook.foodpilot.tech/?path=/docs/foodsdeletebutton--overview): Icon-only Delete button (fixed trash icon) for removing a single item inline, such as a table row, a tag or an attachment. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/FoodsDeleteButton.stories.tsx)
- [FoodsToggleButton](https://foods-storybook.foodpilot.tech/?path=/docs/foodstogglebutton--overview): A row of toggle buttons where one is selected at a time, each with an optional icon, colour or link. platform-app uses it for in-page navigation; MUI's ToggleButton is an input, so prefer Tabs for new navigation. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/FoodsToggleButton.stories.tsx)
- [Link](https://foods-storybook.foodpilot.tech/?path=/docs/link--overview): An inline destination link that inherits the surrounding text size. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/Link.stories.tsx)
- [TertiaryToggleButton](https://foods-storybook.foodpilot.tech/?path=/docs/tertiarytogglebutton--overview): A row of toggle buttons to pick one value among a few short text choices, such as a storage condition. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/TertiaryToggleButton.stories.tsx)
- [TertiaryToggleButtonNodeTitle](https://foods-storybook.foodpilot.tech/?path=/docs/tertiarytogglebuttonnodetitle--overview): TertiaryToggleButton whose choices are rich nodes, such as a score with its value and unit, rendered verbatim. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/TertiaryToggleButtonNodeTitle.stories.tsx)
- [ToggleSwitch](https://foods-storybook.foodpilot.tech/?path=/docs/toggleswitch--overview): A switch for a binary setting that applies immediately, without a Save step: a notification, a feature flag, a preference. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Actions/ToggleSwitch.stories.tsx)

## Components: Avatar and user

- [Avatar](https://foods-storybook.foodpilot.tech/?path=/docs/avatar--overview): MUI's Avatar with FoodPilot's small, medium and big variants: it shows a user's profile picture, or the first letter of `alt` when the picture is missing or fails to load. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Avatar%20and%20user/Avatar.stories.tsx)
- [AvatarGroup](https://foods-storybook.foodpilot.tech/?path=/docs/avatargroup--overview): MUI's AvatarGroup with FoodPilot's small, medium and big variants: it stacks the avatars of the users sharing an object, such as a campaign. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Avatar%20and%20user/AvatarGroup.stories.tsx)
- [FoodsAvatar](https://foods-storybook.foodpilot.tech/?path=/docs/foodsavatar--overview): Figma's `Avatar / Default`: a user's profile picture, or their initials when there is none. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Avatar%20and%20user/FoodsAvatar.stories.tsx)

## Components: Content

- [AccordionProduct](https://foods-storybook.foodpilot.tech/?path=/docs/accordionproduct--overview): Accordion of the ingredient and packaging lines of the product form. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/AccordionProduct.stories.tsx)
- [AdditionalContentBox](https://foods-storybook.foodpilot.tech/?path=/docs/additionalcontentbox--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/AdditionalContentBox.stories.tsx)
- [ArticlesBlock (ArticlesBox)](https://foods-storybook.foodpilot.tech/?path=/docs/articlesblock--overview): CMS block of the landing pages listing one to four articles. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/ArticlesBlock.stories.tsx)
- [Banner](https://foods-storybook.foodpilot.tech/?path=/docs/banner--overview): Persistent message about a page or section. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/Banner/Banner.stories.tsx)
- [CategoryBox](https://foods-storybook.foodpilot.tech/?path=/docs/categorybox--overview): Grey chip naming a category or a tag, as on the product summary. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/CategoryBox.stories.tsx)
- [ContextualContentBox](https://foods-storybook.foodpilot.tech/?path=/docs/contextualcontentbox--overview): Box explaining a concept or a feature in context (what a score means, how the action plan works), or showing the info text set in Sure on SSQ headings: a title, two or three sentences and an optional call to action. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/ContextualContentBox.stories.tsx)
- [DottedBox](https://foods-storybook.foodpilot.tech/?path=/docs/dottedbox--overview): Dashed box marking an empty or optional area, such as a multi-value SSQ field with no element yet or the zone to add an item. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/DottedBox.stories.tsx)
- [FormAccordion](https://foods-storybook.foodpilot.tech/?path=/docs/formaccordion--overview): Accordion of the pages of a questionnaire (SSQ): one page is open at a time and each header shows the page title with its indicator value. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/FormAccordion.stories.tsx)
- [GenericAccordion](https://foods-storybook.foodpilot.tech/?path=/docs/genericaccordion--overview): Collapsible section of the product and supplier summaries: a header with an icon, a title and its controls (a disabled Modifier button when none are given), above content that the chevron shows or hides. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/GenericAccordion.stories.tsx)
- [HelperBox](https://foods-storybook.foodpilot.tech/?path=/docs/helperbox--overview): Short, neutral hint next to a form field, a control or a section: how to fill it in, where the data comes from. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/HelperBox.stories.tsx)
- [HeroBlock](https://foods-storybook.foodpilot.tech/?path=/docs/heroblock--overview): CMS hero block opening a landing page: a title, a subtitle, a rich description, an optional image and an optional call to action. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/HeroBlock.stories.tsx)
- [IndicatorBlock](https://foods-storybook.foodpilot.tech/?path=/docs/indicatorblock--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/IndicatorBlock.stories.tsx)
- [InfoHeaderWithIllustration](https://foods-storybook.foodpilot.tech/?path=/docs/infoheaderwithillustration--overview): Header introducing a feature that has no data yet, such as the decarbonisation trajectory before an action plan exists: an illustration, a bold lead, a short explanation and the primary action that starts it. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/InfoHeaderWithIllustration.stories.tsx)
- [LineGroupBox](https://foods-storybook.foodpilot.tech/?path=/docs/linegroupbox--overview): Bordered line of a stacked group, such as the transformation steps of the product form: `isFirst` rounds its top corners and `isLast` its bottom ones, so consecutive lines read as one group. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/LineGroupBox.stories.tsx)
- [SectionBox](https://foods-storybook.foodpilot.tech/?path=/docs/sectionbox--overview): White section with a header, its content and an optional footer separated by borders, as on the product details page. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/SectionBox.stories.tsx)
- [SeeMoreCard](https://foods-storybook.foodpilot.tech/?path=/docs/seemorecard--overview): Card with its main content and a See more / See less button that toggles extra content (`hidden`), as on the company overview scores. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/SeeMoreCard.stories.tsx)
- [SolidGreyBox](https://foods-storybook.foodpilot.tech/?path=/docs/solidgreybox--overview): Grey bordered box holding a reminder or a computed value inside a form, such as the net weight of all the ingredients of a recipe. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/SolidGreyBox.stories.tsx)
- [TextTitle](https://foods-storybook.foodpilot.tech/?path=/docs/texttitle--overview): Title preceded by a badge, as on the form pages: a number renders a step Badge, any other node (an icon) is scaled up in grey. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/TextTitle.stories.tsx)
- [TextTitleGreyIcon](https://foods-storybook.foodpilot.tech/?path=/docs/texttitlegreyicon--overview): Title preceded by its icon in a grey circle, as on the ingredient and packaging grids of the product form. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/TextTitleGreyIcon.stories.tsx)
- [TypographyList](https://foods-storybook.foodpilot.tech/?path=/docs/typographylist--overview): Text joining a list of words with `separator`, cut after `maxLength` characters (separators excluded): the cut word ends with an ellipsis and a +N counter gives the number of hidden words, as for the sectors of a supplier. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/TypographyList.stories.tsx)
- [WarningBox](https://foods-storybook.foodpilot.tech/?path=/docs/warningbox--overview): Yellow warning about a setting or a situation that needs attention, such as an SSO mode without a valid connector. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/WarningBox.stories.tsx)
- [WhiteBox](https://foods-storybook.foodpilot.tech/?path=/docs/whitebox--overview): White card with a light grey border and shadow: the base surface of FoodPilot pages and of many components. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Content/WhiteBox.stories.tsx)

## Components: Data display

- [ActionPlanPresentation (ActionPlanNetImpactBody)](https://foods-storybook.foodpilot.tech/?path=/docs/actionplanpresentation--overview): Pieces of the Action plan summary. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ActionPlanPresentation.stories.tsx)
- [Badge](https://foods-storybook.foodpilot.tech/?path=/docs/badge--overview): Round counter showing a short value, typically a number of items, in three sizes. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/Badge.stories.tsx)
- [ComparisonArrow](https://foods-storybook.foodpilot.tech/?path=/docs/comparisonarrow--overview): Percentage tag comparing a value with a reference value. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ComparisonArrow.stories.tsx)
- [ComparisonBlock](https://foods-storybook.foodpilot.tech/?path=/docs/comparisonblock--overview): Compares a score with a reference value (sector average, previous campaign, reference product) as a percentage with an arrow or sign. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ComparisonBlock.stories.tsx)
- [DoughnutCard](https://foods-storybook.foodpilot.tech/?path=/docs/doughnutcard--overview): Shared clipped surface for score summaries. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/DoughnutCard.stories.tsx)
- [DoughnutChart](https://foods-storybook.foodpilot.tech/?path=/docs/doughnutchart--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/DoughnutChart.stories.tsx)
- [EvolutionChart](https://foods-storybook.foodpilot.tech/?path=/docs/evolutionchart--overview): Stacked bars comparing how a total splits into categories (e.g. emissions per category) from one period to the next. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/EvolutionChart.stories.tsx)
- [FoodsBadge](https://foods-storybook.foodpilot.tech/?path=/docs/foodsbadge--overview): An icon of the FoodPilot set centred in a box sized from the icon plus extra padding, used as a pictogram badge. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/FoodsBadge.stories.tsx)
- [FoodsTags](https://foods-storybook.foodpilot.tech/?path=/docs/foodstags--overview): Short label with explicit readOnly, removable and clickable modes. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/FoodsTags.stories.tsx)
- [FormUnit](https://foods-storybook.foodpilot.tech/?path=/docs/formunit--overview): Score tag: a score value with its unit in a compact bordered pill, for questionnaires, list rows, cards and headers. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/FormUnit.stories.tsx)
- [HistogramComparisonChart](https://foods-storybook.foodpilot.tech/?path=/docs/histogramcomparisonchart--overview): Bars comparing a score over a few periods, such as the starting, current and target years, with the change between consecutive bars labelled above them. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/HistogramComparisonChart.stories.tsx)
- [HorizontalGaugeChart](https://foods-storybook.foodpilot.tech/?path=/docs/horizontalgaugechart--overview): Gauge placing a company's score and its group average between the group's minimum and maximum, with the median marked on the scale. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/HorizontalGaugeChart.stories.tsx)
- [LinearProgress](https://foods-storybook.foodpilot.tech/?path=/docs/linearprogress--overview): Percentage bar with an Absolute type for completion and a Relative type for comparing shares. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/LinearProgress.stories.tsx)
- [MRTGrid](https://foods-storybook.foodpilot.tech/?path=/docs/mrtgrid--overview): Data table built on Material React Table with the FoodPilot styling: sortable and resizable columns, row selection, and page navigation. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/MRTGrid/MRTGrid.stories.tsx)
- [NumberWithUnit](https://foods-storybook.foodpilot.tech/?path=/docs/numberwithunit--overview): Score text: a value with its unit, in the four number sizes, with the unit beside or below the value. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/NumberWithUnit.stories.tsx)
- [PolymorphicChart](https://foods-storybook.foodpilot.tech/?path=/docs/polymorphicchart--overview): One chart API for score breakdowns: donut, pie, bar, line, radar, cumulative, table and raw charts take the same values, labels, colours, icons and legend. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/PolymorphicChart.stories.tsx)
- [ProgressCard](https://foods-storybook.foodpilot.tech/?path=/docs/progresscard--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ProgressCard.stories.tsx)
- [ScatterPlot](https://foods-storybook.foodpilot.tech/?path=/docs/scatterplot--overview): Scatter plot placing products or organisations on two scores, such as the carbon footprint against the water use, grouped into coloured series. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ScatterPlot.stories.tsx)
- [Score](https://foods-storybook.foodpilot.tech/?path=/docs/score--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/Score.stories.tsx)
- [ScoreCard](https://foods-storybook.foodpilot.tech/?path=/docs/scorecard--overview): Card showing one score of an entity with its context: the score name and its variation selector in the header, the score content (here its trajectory) in the body, and a footer button leading to the details. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ScoreCard/ScoreCard.stories.tsx)
- [ScoreDistribution](https://foods-storybook.foodpilot.tech/?path=/docs/scoredistribution--overview): Controlled score breakdown for lifecycle, sub-score, and impact views. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ScoreDistribution.stories.tsx)
- [ScoreOverviewCard](https://foods-storybook.foodpilot.tech/?path=/docs/scoreoverviewcard--overview): Controlled score selector card for Product score overviews. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ScoreOverviewCard.stories.tsx)
- [ScoreSelect](https://foods-storybook.foodpilot.tech/?path=/docs/scoreselect--overview): Compact boxed score heading. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ScoreSelect.stories.tsx)
- [ScoreValue](https://foods-storybook.foodpilot.tech/?path=/docs/scorevalue--overview): Big score number with its unit, in white for dark surfaces such as a selected card. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/ScoreValue.stories.tsx)
- [TrajectoryCards](https://foods-storybook.foodpilot.tech/?path=/docs/trajectorycards--overview): Cards following a score from its starting point to its target with and without the action plan, and how much of the objective the plan reaches. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/TrajectoryCards.stories.tsx)
- [TrajectoryChart](https://foods-storybook.foodpilot.tech/?path=/docs/trajectorychart--overview): Bars following a score over time: the calculated scores of past years, then the projected years without and with the action plan, against the goal line. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/TrajectoryChart.stories.tsx)
- [WaterfallChart](https://foods-storybook.foodpilot.tech/?path=/docs/waterfallchart--overview): Waterfall of an action plan: from the reference and starting values, each action adds or removes its impact until the target value, compared with the goal. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Data%20display/WaterfallChart.stories.tsx)

## Components: Feedbacks

- [AnchoredPopover](https://foods-storybook.foodpilot.tech/?path=/docs/anchoredpopover--overview): Popover opened under its trigger: `themed` adds the padding, border and arrow of FoodPilot's popovers, `headless` only rounds the corners for a custom layout such as BigPopoverLayout. anchorPosition aligns it with the left, the centre or the right of the trigger. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Feedbacks/AnchoredPopover.stories.tsx)
- [BigPopoverLayout](https://foods-storybook.foodpilot.tech/?path=/docs/bigpopoverlayout--overview): Layout of FoodPilot's large popovers, such as the column picker or the filters: a header with an icon, a title and a close button, a scrollable 420px-high body and optional Cancel / Validate actions. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Feedbacks/BigPopoverLayout.stories.tsx)
- [FoodsSnackbar](https://foods-storybook.foodpilot.tech/?path=/docs/foodssnackbar--overview): Figma's `Snackbar`: a short confirmation of an action the user just made, at the bottom center of the screen. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Feedbacks/FoodsSnackbar.stories.tsx)
- [FoodsTooltip](https://foods-storybook.foodpilot.tech/?path=/docs/foodstooltip--overview): Tooltip giving short, non-essential information on hover and on keyboard focus of its trigger: an icon button label, the definition of an indicator, a truncated text. variant `simple` is Figma's Simple tooltip, `default` the legacy one; long or essential content belongs in the page or a popover. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Feedbacks/FoodsTooltip.stories.tsx)
- [FoodsTooltipSimple (FoodsTooltip)](https://foods-storybook.foodpilot.tech/?path=/docs/foodstooltipsimple--overview): Figma's Simple tooltip (`variant` simple): a short label shown on hover and on keyboard focus of its trigger, such as the full text of a truncated label. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Feedbacks/FoodsTooltipSimple.stories.tsx)
- [OptionsPopover](https://foods-storybook.foodpilot.tech/?path=/docs/optionspopover--overview): Card listing options in titled sections, with a check mark on the active one, for the sort or display menus of a popover. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Feedbacks/OptionsPopover.stories.tsx)
- [WhitePopover](https://foods-storybook.foodpilot.tech/?path=/docs/whitepopover--overview): White card with an arrow, opened under its trigger (an input, an icon) while the pointer is over it and closed when it leaves. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Feedbacks/WhitePopover.stories.tsx)

## Components: Inputs

- [BaseRadio](https://foods-storybook.foodpilot.tech/?path=/docs/baseradio--overview): Low-level radio group built from a list of `{ id, name, state, disabled }` entries, in that order. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/BaseRadio.stories.tsx)
- [FoodsCheckbox](https://foods-storybook.foodpilot.tech/?path=/docs/foodscheckbox--overview): A list of checkboxes built from any list of objects: the user selects zero, one or several independent options, and `onChange` returns the selected objects. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsCheckbox.stories.tsx)
- [FoodsFileButton](https://foods-storybook.foodpilot.tech/?path=/docs/foodsfilebutton--overview): A button that opens the file picker and checks the chosen file's type (`accept`) and size (`maxSize`) before handing it to `onFileSelected`, or the reason it was refused to `onReject`. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsFileButton.stories.tsx)
- [FoodsFormBase](https://foods-storybook.foodpilot.tech/?path=/docs/foodsformbase--overview): The frame of a multi-page form (a questionnaire, a product creation): a sticky top bar with the title, the page thread, the saving status and the Previous / Next actions, then the current page. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsFormBase/FoodsFormBase.stories.tsx)
- [FoodsMultiSelect](https://foods-storybook.foodpilot.tech/?path=/docs/foodsmultiselect--overview): A multi-select with removable Tags in the field and a checkbox list. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsMultiSelect.stories.tsx)
- [FoodsNumberInput](https://foods-storybook.foodpilot.tech/?path=/docs/foodsnumberinput--overview): Controlled numeric input with a stepper, bounds, and optional unit, hint, reset, and error message. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsNumberInput.stories.tsx)
- [FoodsRadioList](https://foods-storybook.foodpilot.tech/?path=/docs/foodsradiolist--overview): A radio group built from any list of objects, for picking exactly one of 2 to 5 options that stay visible. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsRadioList.stories.tsx)
- [FoodsSelect](https://foods-storybook.foodpilot.tech/?path=/docs/foodsselect--overview): A select for picking one value from a closed list of 5 or more options, with a search field, optional group headers, an optional no-value line (`noValue`) and a reset to the default value (`originalValue`). [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsSelect/FoodsSelect.stories.tsx)
- [FoodsSelect / FoodsSelectServerPagination](https://foods-storybook.foodpilot.tech/?path=/docs/foodsselectserverpagination--overview): The FoodsSelect variant whose search is controlled by the caller (`search`, `setSearch`, `isSearchFound`). [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsSelect/FoodsSelectServerPagination.stories.tsx)
- [FoodsTextInput](https://foods-storybook.foodpilot.tech/?path=/docs/foodstextinput--overview): A single-line field for a short text or numeric value in a form, with an optional unit, error message, contextual hint, and default value. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FoodsTextInput.stories.tsx)
- [FormBox](https://foods-storybook.foodpilot.tech/?path=/docs/formbox--overview): The white, rounded container of a form section. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FormBox.stories.tsx)
- [FormPropertyBox](https://foods-storybook.foodpilot.tech/?path=/docs/formpropertybox--overview): The white box of one questionnaire property: its title, an optional score indicator, an optional hint (a string may contain HTML) and the field itself as children. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/FormPropertyBox.stories.tsx)
- [Pills (FoodsPills)](https://foods-storybook.foodpilot.tech/?path=/docs/pills--overview): A compact tag showing an active filter, its name next to its current value, with an optional icon. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/Pills.stories.tsx)
- [RadioBoolean](https://foods-storybook.foodpilot.tech/?path=/docs/radioboolean--overview): A Yes/No radio pair for boolean questions. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/RadioBoolean.stories.tsx)
- [RadioList](https://foods-storybook.foodpilot.tech/?path=/docs/radiolist--overview): A titled radio group built from a record of `{ name, state, disabled }` entries, with an optional description under the title. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/RadioList.stories.tsx)
- [RichTextEditor](https://foods-storybook.foodpilot.tech/?path=/docs/richtexteditor--overview): A Tiptap rich text editor with a formatting toolbar (fonts, marks, links, alignment, lists, icons, images). [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/RichTextEditor.stories.tsx)
- [RoundInput](https://foods-storybook.foodpilot.tech/?path=/docs/roundinput--overview): A pill-shaped MUI `InputBase` for compact fields; `error` turns it red. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/RoundInput.stories.tsx)
- [RoundNumberInput](https://foods-storybook.foodpilot.tech/?path=/docs/roundnumberinput--overview): A `RoundInput` of type number followed by its unit. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/RoundNumberInput.stories.tsx)
- [SearchBox](https://foods-storybook.foodpilot.tech/?path=/docs/searchbox--overview): A search field for filtering a list, a table or a page by keyword. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/SearchBox.stories.tsx)
- [SelectionCard](https://foods-storybook.foodpilot.tech/?path=/docs/selectioncard--overview): A card-sized radio option with a title, a description and an icon, for choices that need explaining. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/SelectionCard.stories.tsx)
- [SelectionCardGroup](https://foods-storybook.foodpilot.tech/?path=/docs/selectioncardgroup--overview): A radio group of `SelectionCard`s: one card is selected at a time, and the arrow keys move the selection to the next enabled card. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/SelectionCardGroup.stories.tsx)
- [Textarea](https://foods-storybook.foodpilot.tech/?path=/docs/textarea--overview): A multi-line field for comments and justifications. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/Textarea.stories.tsx)
- [Treeview (FoodsTreeview)](https://foods-storybook.foodpilot.tech/?path=/docs/treeview--overview): A tree of nested items (MUI RichTreeView) for picking a leaf, such as a product category. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/Treeview.stories.tsx)
- [UnitConverterPanel](https://foods-storybook.foodpilot.tech/?path=/docs/unitconverterpanel--overview): An inline panel that converts a value entered in another unit (for instance a gas bill in m³) into the unit a question expects, shows the converted result and lets the user apply it. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Inputs/UnitConverterPanel.stories.tsx)

## Components: Modals

- [BottomSheetDialog](https://foods-storybook.foodpilot.tech/?path=/docs/bottomsheetdialog--overview): BottomSheetDialog slides up from the bottom of the screen on mobile (below the md breakpoint, 900px) and opens as a centred dialog on desktop. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Modals/BottomSheetDialog.stories.tsx)
- [PrimaryDialog](https://foods-storybook.foodpilot.tech/?path=/docs/primarydialog--overview): Modal dialog with a title, a close button and Cancel / Validate actions. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Modals/PrimaryDialog.stories.tsx)
- [UnsavedChangesDialog](https://foods-storybook.foodpilot.tech/?path=/docs/unsavedchangesdialog--overview): A controlled exit dialog shared by product editors and Action plan templates. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Modals/UnsavedChangesDialog.stories.tsx)

## Components: Navigation

- [BreadcrumbItem](https://foods-storybook.foodpilot.tech/?path=/docs/breadcrumbitem--overview): One level of `Breadcrumbs`: a link to a parent page (`href`) or a button (`onClick`), the current page (`active`, not actionable), a long label cut with a tooltip (`long`), or the trigger of the hidden levels (`collapsed`). [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/BreadcrumbItem.stories.tsx)
- [Breadcrumbs](https://foods-storybook.foodpilot.tech/?path=/docs/breadcrumbs--overview): Shows where the current page sits in the hierarchy: every ancestor is a link (`href`) or a button (`onSelect`) to its page, and the current page closes the trail, bold and not actionable. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/Breadcrumbs.stories.tsx)
- [CountTabs](https://foods-storybook.foodpilot.tech/?path=/docs/counttabs--overview): Tabs that filter one list into categories, each with its item count (`Label - 78`). [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/CountTabs.stories.tsx)
- [FoodsNavbar](https://foods-storybook.foodpilot.tech/?path=/docs/foodsnavbar--overview): The main left navigation of foodpilot-app: the organization, the menu entries (links, drawers of sub-items, custom renders), the collapse button and the user account. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/FoodsNavbar/FoodsNavbar.stories.tsx)
- [FoodsTabs](https://foods-storybook.foodpilot.tech/?path=/docs/foodstabs--overview): The tabs of FoodPilot pages: `primary` for the main sections in a page header, `secondary` for a second level inside a section, `buttons` for switching views of the same content. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/FoodsTabs/FoodsTabs.stories.tsx)
- [Pagination (FoodsPagination)](https://foods-storybook.foodpilot.tech/?path=/docs/pagination--overview): A MUI pagination whose pages can carry a label and a completion state, shown in a tooltip on hover. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/Pagination.stories.tsx)
- [SecondaryTabs](https://foods-storybook.foodpilot.tech/?path=/docs/secondarytabs--overview): The second level of tabs, inside a page section: bordered tabs above the content of the selected one. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/SecondaryTabs.stories.tsx)
- [SectionTabs](https://foods-storybook.foodpilot.tech/?path=/docs/sectiontabs--overview): The tabs that switch between the sections of a page, each with an optional icon and tooltip; `renderComponents` also renders the content of the selected section below them. [Source](https://github.com/Foodpilot/foods/blob/main/src/components/Navigation/SectionTabs.stories.tsx)

## Elements

- [Breakpoints](https://foods-storybook.foodpilot.tech/?path=/docs/elements-breakpoints--breakpoints): The [Grid system](https://www.figma.com/design/ucJSnn3mHlv4MCnwe1oZ2Z/Design-System?node-id=8765-3558) foundation of the Figma Design System. [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/Breakpoints.mdx)
- [Colors](https://foods-storybook.foodpilot.tech/?path=/docs/elements-colors--colors): The [Colors](https://www.figma.com/design/ucJSnn3mHlv4MCnwe1oZ2Z/Design-System?node-id=8765-3554) foundation of the Figma Design System, as `@foodpilot/foods` exports it (`lib/themes/common/colors.ts` and the tenant themes). [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/Colors.mdx)
- [FocusRing](https://foods-storybook.foodpilot.tech/?path=/docs/focusring--overview): Shared keyboard focus styles for controls. [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/FocusRing.stories.tsx)
- [Icons / FoodsIcon](https://foods-storybook.foodpilot.tech/?path=/docs/foodsicon--overview): SVG icon of the FoodPilot set, picked by its `icon` key. [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/Icons/FoodsIcon.stories.tsx)
- [Icons / FoodsIllustrations](https://foods-storybook.foodpilot.tech/?path=/docs/foodsillustrations--overview): Illustration of the FoodPilot set, picked by its `illustration` key, on a circle or rectangle background coloured by `variant`: the tenant's primary colour (`theme`) or one of the dataviz colours. 112 × 112 px unless `width` and `height` say otherwise. [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/Icons/FoodsIllustrations.stories.tsx)
- [Shadows](https://foods-storybook.foodpilot.tech/?path=/docs/elements-shadows--shadows): The [Shadow](https://www.figma.com/design/ucJSnn3mHlv4MCnwe1oZ2Z/Design-System?node-id=11858-137) foundation of the Figma Design System, exported as `shadows` (`lib/themes/common/colors.ts`). [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/Shadows.mdx)
- [Spacing](https://foods-storybook.foodpilot.tech/?path=/docs/elements-spacing--spacing): The [Spacing](https://www.figma.com/design/ucJSnn3mHlv4MCnwe1oZ2Z/Design-System?node-id=8765-3557) foundation of the Figma Design System. [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/Spacing.mdx)
- [Typography](https://foods-storybook.foodpilot.tech/?path=/docs/typography--overview): Typography variants of the FoodPilot themes, applied through the `variant` of MUI Typography: headings h1 to h6, then small, body, big and huge texts in four weights, the cta style and the number styles. [Source](https://github.com/Foodpilot/foods/blob/main/src/elements/Typography/Typography.stories.tsx)

## Layout

- [BlockListContainer](https://foods-storybook.foodpilot.tech/?path=/docs/blocklistcontainer--overview): BlockListContainer lays out a list of blocks, as in the action plan: a header (InitHeader, ListHeader…) above a grey area that stacks its blocks, such as empty states, suggestions, or BlockItemContainer cards of select, checkbox and radio fields. [Source](https://github.com/Foodpilot/foods/blob/main/src/layout/BlockListContainer.stories.tsx)

## Preview

- [About preview](https://foods-storybook.foodpilot.tech/?path=/docs/preview-about-preview--about-preview): Components under **Preview** are still being built or redesigned. [Source](https://github.com/Foodpilot/foods/blob/main/src/preview/AboutPreview.mdx)
- [RichTextEditor](https://foods-storybook.foodpilot.tech/?path=/docs/experimental-richtexteditor--overview): A rich text editor component with formatting options. [Source](https://github.com/Foodpilot/foods/blob/main/src/preview/RichTextEditor/RichTextEditor.stories.tsx)

## Optional

- [Deprecated / Actions / ButtonVariantAudit](https://foods-storybook.foodpilot.tech/?path=/docs/buttonvariantaudit--overview): Visual inventory of the 16 general-purpose variants. [Source](https://github.com/Foodpilot/foods/blob/main/src/deprecated/Actions/ButtonVariantAudit.stories.tsx)
- [Deprecated / Data display / ScoreCardHeader](https://foods-storybook.foodpilot.tech/?path=/docs/scorecardheader--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/deprecated/Data%20display/ScoreCardHeader.stories.tsx)
- [Deprecated / Navigation / ButtonTabs](https://foods-storybook.foodpilot.tech/?path=/docs/buttontabs--overview): Deprecated: use `FoodsTabs` with `tabVariant="buttons"` instead. [Source](https://github.com/Foodpilot/foods/blob/main/src/deprecated/Navigation/ButtonTabs.stories.tsx)
- [Legacy / Content / CustomTypography](https://foods-storybook.foodpilot.tech/?path=/docs/customtypography--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Content/CustomTypography.stories.tsx)
- [Legacy / Content / LightIndicatorBlock](https://foods-storybook.foodpilot.tech/?path=/docs/lightindicatorblock--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Content/LightIndicatorBlock.stories.tsx)
- [Legacy / Content / QuoteBox](https://foods-storybook.foodpilot.tech/?path=/docs/quotebox--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Content/QuoteBox.stories.tsx)
- [Legacy / Content / TextArrowList](https://foods-storybook.foodpilot.tech/?path=/docs/textarrowlist--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Content/TextArrowList.stories.tsx)
- [Legacy / Data display / BreakdownTable](https://foods-storybook.foodpilot.tech/?path=/docs/breakdowntable--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Data%20display/BreakdownTable.stories.tsx)
- [Legacy / Data display / Progress](https://foods-storybook.foodpilot.tech/?path=/docs/progress--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Data%20display/Progress.stories.tsx)
- [Legacy / Data display / ScoreContainer](https://foods-storybook.foodpilot.tech/?path=/docs/scorecontainer--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Data%20display/ScoreContainer.stories.tsx)
- [Legacy / Inputs / FormBase](https://foods-storybook.foodpilot.tech/?path=/docs/formbase--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Inputs/FormBase.stories.tsx)
- [Legacy / Inputs / NumberField](https://foods-storybook.foodpilot.tech/?path=/docs/numberfield--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Inputs/NumberField.stories.tsx)
- [Legacy / Inputs / PrimaryCheckbox](https://foods-storybook.foodpilot.tech/?path=/docs/primarycheckbox--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Inputs/PrimaryCheckbox.stories.tsx)
- [Legacy / Inputs / TextField](https://foods-storybook.foodpilot.tech/?path=/docs/textfield--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Inputs/TextField.stories.tsx)
- [Legacy / Navigation / IconThread](https://foods-storybook.foodpilot.tech/?path=/docs/iconthread--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Navigation/IconThread.stories.tsx)
- [Legacy / Navigation / Navbar](https://foods-storybook.foodpilot.tech/?path=/docs/navbar--overview): [Source](https://github.com/Foodpilot/foods/blob/main/src/legacy/Navigation/Navbar.stories.tsx)
- [README](https://github.com/Foodpilot/foods/blob/main/README.md): installation, Storybook and contribution workflow.
- [AGENTS.md](https://github.com/Foodpilot/foods/blob/main/AGENTS.md): the repository rules for changes to foods.
- [Import examples](https://github.com/Foodpilot/foods/blob/main/IMPORT_EXAMPLES.md)
- [Bundle analysis](https://github.com/Foodpilot/foods/blob/main/BUNDLE_ANALYSIS.md): size budgets.