# Design guidelines

> How an embedded page and an extension should look and behave inside the platform, from the platform's constraints to our recommendations.

Source: https://developers-staging.foodpilot.tech/launch/design

In this page you will make your embedded pages feel part of the platform. The first section lists what the platform enforces; the rest are our recommendations.

## What the platform gives you, and its limits

| Element | Where | Limit |
|---|---|---|
| Menu entries | `navigation` in the manifest, under the platform's **Apps** menu | Up to 10; a label in English (required) and in French (optional), at most 40 characters each |
| Page title | `title()` | 100 characters |
| Progress bar under the header | `loading(true)` and `loading(false)` | |
| Loading placeholder | Shown until you call `ready()` | |
| Toasts | `toast()`, kind `info`, `success` or `error` | 200 characters |
| Confirmation dialog | `confirm()` | Message 500 characters, button 30 |
| Product tab frame | `product.details.tab` | 600 px high by default, from 200 to 2000 |
| Organization overview card | `organization.overview.card` | 200 px high by default, from 80 to 600 |

Your page receives the user's language in the `locale` query parameter and in the session token.

## Look like the platform

- **Use the platform's design library.** The platform is built with fooDS; its components, colours and type are in its [Storybook](https://foods-storybook.foodpilot.tech). Match its spacing, typography and colours rather than your own brand.
- **No second header.** The platform draws its own header and menu around your page: do not add a logo bar or a global navigation. Use `title()` for the page name.
- **Use the platform's feedback.** Show results with `toast()` and ask with `confirm()` instead of your own banners and modals: they look and behave like the rest of the platform.
- **Fit the frame.** Your page lives in a frame of variable width: no fixed widths, no horizontal scroll.

## Behave like the platform

- **Call `ready()` early**, as soon as the first meaningful content is shown, so the placeholder does not linger. For longer work afterwards, use `loading()`.
- **Speak the user's language.** At least English and French, from `locale`.
- **Say what happens.** After an action, a toast; before a destructive one, a confirmation; when data is not available, a short sentence, not a blank area.
- **Respect permissions.** If the installation does not cover an organization, say so plainly instead of showing an error.

## Extensions are small

- **One idea per extension.** A product tab shows what your app knows about this product; an overview card shows one figure or status and links to your full page.
- **Follow your content's height** with `autoResize()`, within the slot's range.
- **Load fast.** The extension appears inside a page the user opened for something else.

## Accessibility

- Text reaches a contrast of 4.5:1 against its background, controls 3:1.
- Every action is reachable with the keyboard and shows where the focus is.
- Images that carry meaning have a text alternative.
