diff --git a/docs/figma-make-kit/guidelines/components/_component-template.md b/docs/figma-make-kit/guidelines/components/_component-template.md new file mode 100644 index 0000000000..bdd291da3a --- /dev/null +++ b/docs/figma-make-kit/guidelines/components/_component-template.md @@ -0,0 +1,56 @@ + + +# + +`` — . + +## When to use + + + +Use `` for . Always use the component from `<@scope/package-name>`, never a raw ``. + +## Variants + + + +| Variant | Use for | +| ------------- | ------------- | +| `` | | +| `` | | + +IMPORTANT: Valid variants are `` — nothing else. Do NOT invent variant names. + +## Props + +| Prop | Type | Default | Description | +| ----------- | --------- | ----------- | ---------------------- | +| `` | `` | `` | | +| `className` | `string` | — | Additional CSS classes | +| `disabled` | `boolean` | `false` | Disable the component | + +## Examples + +```tsx +import { } from '<@scope/package-name>' + +{/* CORRECT — common usage */} +< variant="">Label> +``` + +```tsx +{ + /* WRONG — */ +} +; +``` + +## Rules + + + +- +- +- Do not style this component with typography or font utility classes — it manages its own type. diff --git a/docs/figma-make-kit/guidelines/components/accordion.md b/docs/figma-make-kit/guidelines/components/accordion.md new file mode 100644 index 0000000000..f039aad766 --- /dev/null +++ b/docs/figma-make-kit/guidelines/components/accordion.md @@ -0,0 +1,59 @@ +# BpkAccordion + +`BpkAccordion` — vertically stacked expand/collapse content sections. Purely presentational — expand/collapse state must be wired up externally or via one of two provided HOCs. + +## When to use + +Use `BpkAccordion` for stacked, collapsible sections (e.g. filters, FAQ). It does not manage state on its own — decide up front whether only one section should be open at a time or many. + +## Variants + +Not a prop — a choice of composition HOC: + +| Pattern | Behavior | +| --- | --- | +| `withSingleItemAccordionState(BpkAccordion)` | Only one item open at a time | +| `withAccordionItemState(BpkAccordionItem)` | Each item manages its own independent open/close state | + +## Props + +**`BpkAccordion`**: `children` (required, `BpkAccordionItem`s), `divider` (boolean, default `true`), `onDark` (boolean, default `false`). + +**`BpkAccordionItem`**: + +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `id` | `string` | required | | +| `title` | `string` | required | Header text | +| `children` | `ReactNode` | required | Collapsible content | +| `expanded` | `boolean` | `false` | Controlled open state | +| `icon` | `ReactElement` | `null` | Leading icon | +| `onClick` | `() => void` | no-op | Toggle handler | +| `tagName` | `Tag` | `'h3'` | Heading semantic tag | +| `textStyle` | `TextStyle` | `bodyDefault` | | + +## Examples + +```tsx +import { BpkAccordion, BpkAccordionItem, withSingleItemAccordionState } from '@skyscanner/backpack-web/bpk-component-accordion'; + +const SingleItemAccordion = withSingleItemAccordionState(BpkAccordion); + +{/* CORRECT — state managed by the HOC */} + + Filter content + Filter content + +``` + +```tsx +{/* WRONG — no expanded/onClick wired and no HOC; clicking the header does nothing */} + + Filter content + +``` + +## Rules + +- `BpkAccordionItem` alone is not interactive — always wire `expanded`/`onClick` yourself or use `withSingleItemAccordionState`/`withAccordionItemState`. +- Use `withSingleItemAccordionState` when only one section should be open at a time; use `withAccordionItemState` when multiple sections can be open independently. diff --git a/docs/figma-make-kit/guidelines/components/badge.md b/docs/figma-make-kit/guidelines/components/badge.md new file mode 100644 index 0000000000..6734bb3bc3 --- /dev/null +++ b/docs/figma-make-kit/guidelines/components/badge.md @@ -0,0 +1,54 @@ +# BpkBadge + +`BpkBadge` — a small inline status/label indicator, typically paired with text, rendered as a ``. + +## When to use + +Use `BpkBadge` for status labels, counters, and tags next to other content (e.g. "Cheapest", "Sold out", "New"). Always use `BpkBadge` from `@skyscanner/backpack-web/bpk-component-badge`, never a raw styled ``. + +## Variants + +| Variant (`BADGE_TYPES`) | Use for | +| --- | --- | +| `normal` (default) | Neutral label | +| `success` | Positive status | +| `warning` | Cautionary status | +| `critical` | Negative/urgent status | +| `strong` | High-emphasis neutral label | +| `brand` | Brand-colored label | +| `subtle` | Low-emphasis label | +| `inverse` | For use on dark backgrounds | +| `outline` | For use on dark or image backgrounds | + +IMPORTANT: Valid `type` values are exactly the `BADGE_TYPES` above — do NOT invent a variant name. + +## Props + +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `type` | `BadgeType` | `normal` | See variants table | +| `docked` | `'right'\|'left' \| null` | `null` | Docks the badge to an edge (e.g. overlaying imagery) | +| `centered` | `boolean` | `false` | Vertically aligns the badge to the center of surrounding text | +| `children` | `string \| ReactNode` | required | Text and/or icon content | +| `className` | `string \| null` | `null` | Additional CSS class | + +## Examples + +```tsx +import BpkBadge, { BADGE_TYPES } from '@skyscanner/backpack-web/bpk-component-badge'; +import BpkSmallTickIcon from '@skyscanner/backpack-web/bpk-component-icon/sm/tick'; + +{/* CORRECT — icon placed as a child, badge has no dedicated icon slot */} + Confirmed +``` + +```tsx +{/* WRONG — leadingIcon is not a BpkBadge prop */} +}>Confirmed +``` + +## Rules + +- There is no `size` prop — badges have one fixed size. +- Icons go directly in `children`, alongside the text — `BpkBadge` has no `leadingIcon`/`trailingIcon` slot (unlike `BpkButton`). +- Choose `type` by the status it represents (`success`/`warning`/`critical`), never by picking a color that "looks right." diff --git a/docs/figma-make-kit/guidelines/components/breadcrumb.md b/docs/figma-make-kit/guidelines/components/breadcrumb.md new file mode 100644 index 0000000000..9d7c7eec2e --- /dev/null +++ b/docs/figma-make-kit/guidelines/components/breadcrumb.md @@ -0,0 +1,46 @@ +# BpkBreadcrumb + +`BpkBreadcrumb` — shows the page hierarchy/path as a `nav` + list of links, with optional schema.org structured-data output. + +## When to use + +Use `BpkBreadcrumb` for hierarchical wayfinding on deep pages (e.g. Home > Hotels > Amsterdam). + +## Variants + +No type/variant enum — purely structural. + +## Props + +**`BpkBreadcrumb`**: `label` (string, required — `aria-label` on the `