foods

@foodpilot/foods is FoodPilot's design system for React: the MUI-based components, tenant themes and charts of platform-app.

• Storybook: foods-storybook.foodpilot.tech, organised like IBM Carbon's.
• Figma Design System: Design System, the design source of truth.
• For AI assistants: llms.txt (llmstxt.org), also served at foods-storybook.foodpilot.tech/llms.txt.

Use foods

npm install @foodpilot/foods

Peer dependencies:

• always: react and react-dom 18 or 19, @mui/material ^6.4, @emotion/react and @emotion/styled ^11.14, i18next, react-i18next and lodash;
• only for the components that use them: @mui/icons-material, @mui/lab, the @mui/x-* packages, recharts and material-react-table.

import { FoodsThemeProvider } from "@foodpilot/foods/themes";
import { Button } from "@foodpilot/foods/Button";

<FoodsThemeProvider theme="foodpilot">
    {/* "foodpilot" | "winepilot" | "collective" */}
    <App />
</FoodsThemeProvider>;

Every export is named, from the root entry or a component entry: see IMPORT_EXAMPLES.md. Style with the theme tokens (palette, 8 px spacing, typography variants, shadows), never raw values. Components translate their texts with react-i18next, the English strings being the keys; the application provides the translations.

Storybook

npm run storybook serves it on port 6006, npm run build-storybook builds it into storybook-static/. The demo.yml workflow deploys it after every release.

Each component has an Overview page (src/docs/DocsPage.tsx) with:

• its match with the Figma design (the doc status of its Figma frame) and the day its usage guidelines were copied from Figma;
• its description;
• the usage guidelines from Figma: do's and don'ts, anatomy, behaviour, content and states, or No usage guidelines yet;
• every story;
• the props (Component API);
• its references.

In Storybook:

• each story has controls, logs its callbacks in Actions and plays its main interaction in Interactions;
• the toolbar switches the tenant theme (FoodPilot, WinePilot, Positive), the background and the viewport;
• the texts are in English.

Contribute

AGENTS.md holds the rules for any change. In short:

• Stories: a component's stories go in src/components/<Category>/<Component>.stories.tsx, without a title, since the folder decides the sidebar, and their meta starts with a stable id, the file name in lower case, so the URLs survive a move. Their texts are in English, with fitting controls, fn() callbacks and a play function. Usage guidelines come from Figma, in parameters.guidelines, with the Figma doc status and the syncedAt day.

• llms.txt: when a component or its stories are added, moved or removed, run npm run llms and commit llms.txt. CI fails when it is stale.

• Legacy: a component's stories move to src/legacy/ with git mv once it is removed from the Figma Design System, then llms.txt is refreshed. The platform-design skill of the frontend harness reports the stories platform-app no longer imports; that alone does not move them.

• Checks:

  • npm run prettier, npm run lint, npm run tsc;
  • npm test, which includes the stories' plays and the llms.txt check;
  • npm run build, npm run depcruise:check.

  CI is described in docs/ci.md, size budgets in BUNDLE_ANALYSIS.md.

• Releases: npm run publish:patch|minor|major dispatches the release workflow from main. platform-app gets a change after that release and its own dependency update.