# Orchard Suite Design System — Figma Make Guidelines

The Orchard Suite design system is a shared React component library (`@theorchard/suite-components`) used across Sony Music / The Orchard web applications. It provides 70+ components, a multi-brand theming engine (`@theorchard/suite-theming`), and a design token set based on semantic CSS custom properties.

## Package Map

| Package | Contains |
|---|---|
| `@theorchard/suite-components` | All UI components (Button, Select, Modal, Alert, etc.) + `useToast` hook |
| `@theorchard/suite-frontend` | `Page`, `formatMessage`, `formatDate`, `formatNumber`, `filterData`, `NotFoundPage`, `ErrorPage` |
| `@theorchard/suite-icons` | `GlyphIcon`, `AppIcon`, `BrandIcon`, `StoreIcon`, `NavIcon` |
| `@theorchard/suite-theming` | `ThemeProvider`, `ThemeContext`, `useTheme`, `themes` map |

Figma Make generates shadcn/ui components in `src/app/components/ui/`. These coexist with suite components. **Prefer suite components** when an equivalent exists — use shadcn components only for UI patterns not covered by the suite (e.g. `Accordion`, `Carousel`, `Sheet`).

## Most-Used Components

Listed by actual usage frequency across all Suite apps — prioritise these when generating code:

| API | Package | Note |
|---|---|---|
| `Button` | suite-components | Most common interactive element |
| `formatMessage` | suite-frontend | i18n for all user-facing text |
| `GlyphIcon` | suite-icons | Inline icons throughout the UI |
| `GridTable` | suite-components | Primary data table |
| `Alert` | suite-components | Persistent contextual messages |
| `Page` | suite-frontend | Root layout wrapper |
| `useToast` hook | suite-components | Prefer over direct `<Toast>` |
| `HelpTooltip` | suite-components | More common than `Tooltip` alone |
| `Select` | suite-components | Single-option dropdown |
| `SkeletonLoader` | suite-components | Preferred loading pattern |
| `Card` | suite-components | Object representation |
| `Tooltip` | suite-components | Hover-triggered label |
| `Section` | suite-components | Page content grouping |
| `Field` | suite-components | Labelled form control wrapper |
| `LoadingSpinner` | suite-components | Section-level loading |

→ [components/suite-frontend.md](./components/suite-frontend.md) for frontend utilities documentation

## Reading Order

Start here, then navigate to the specific file you need:

1. **[setup.md](./setup.md)** — required imports, providers, CSS setup
2. **[components/suite-frontend.md](./components/suite-frontend.md)** — i18n, feature flags, identity, date/number formatting
3. **[foundations/themes.md](./foundations/themes.md)** — brand tokens (Orchard, AWAL, Sony, KNR)
4. **[foundations/color.md](./foundations/color.md)** — semantic color tokens
5. **[foundations/typography.md](./foundations/typography.md)** — font scale and weights
6. **[foundations/spacing.md](./foundations/spacing.md)** — sizing and spacing tokens

## Component Catalog

### Buttons

| Component | Type | Purpose |
|---|---|---|
| `Button` | atom | Primary action trigger; supports `primary`, `secondary`, `tertiary`, `danger` variants |
| `GlyphButton` | atom | Icon-only button with tooltip on hover |
| `GlyphToggle` | atom | Icon button that toggles on/off state |
| `ToggleButton` | atom | Text/icon button that changes colour to indicate active state |
| `SegmentedButton` | molecule | Group of buttons for switching views or modes |

→ [components/buttons.md](./components/buttons.md)

### Forms

| Component | Type | Purpose |
|---|---|---|
| `Field` | molecule | Wrapper combining `Label` + form control + optional error |
| `Form` | molecule | Wrapper grouping related form controls |
| `Label` | molecule | Form field caption with optional/required and help indicators |
| `Checkbox` | atom | Multi-select toggle for a set of options |
| `Radio` | atom | Single-select toggle for a set of options |
| `Switch` | atom | Binary on/off toggle |
| `NumberInput` | atom | Numeric input with increment/decrement controls |
| `SearchInput` | molecule | Text input with search icon for filtering |
| `Slider` | molecule | Range selector on a continuous scale |
| `SegmentedInput` | molecule | Visually connected group of inputs |
| `EditableMetadata` | molecule | Inline editable string metadata value |
| `UploadArea` | organism | File upload by click or drag-and-drop |

→ [components/forms.md](./components/forms.md)

### Selects

| Component | Type | Purpose |
|---|---|---|
| `Select` | molecule | Single-option dropdown |
| `MultiSelect` | molecule | Multi-option dropdown |
| `HeaderSelect` | molecule | Select triggered from a column header |
| `CountrySelect` | molecule | Single-country dropdown with flag icons |
| `MarketSelector` | molecule | Multi-country select with market groupings |
| `TimezoneSelector` | molecule | Single-timezone dropdown |
| `DatePicker` | molecule | Calendar-based single date selector |
| `DateRangePicker` | molecule | Calendar-based date-range selector |

→ [components/selects.md](./components/selects.md)

### Overlays

| Component | Type | Purpose |
|---|---|---|
| `Modal` | organism | Blocking dialog for confirmations and sub-processes |
| `FullscreenModal` | organism | Full-viewport modal for complex sub-flows |
| `Sidecar` | organism | Slide-in panel for tertiary context |
| `Popover` | organism | Click-triggered floating container |
| `Tooltip` | atom | Hover-triggered floating label |
| `HelpTooltip` | molecule | Help-icon + tooltip combo for field context |

→ [components/overlays.md](./components/overlays.md)

### Feedback

| Component | Type | Purpose |
|---|---|---|
| `Alert` | molecule | Persistent inline contextual message |
| `Toast` | molecule | Transient floating notification |
| `ErrorMessage` | molecule | Problem notification with recovery guidance |
| `InfoMessage` | molecule | Empty-state or no-results notification |
| `Status` | atom | Coloured dot/icon + text indicating object state |
| `Highlight` | atom | Semantic background colour on inline text |
| `LoadingSpinner` | atom | Spinning indicator for loading sections |
| `LoadingPageIndicator` | atom | Full-page animated loading placeholder |
| `SkeletonLoader` | atom | Wireframe placeholder for loading layouts |
| `Stepper` | organism | Multi-step process progress indicator |

→ [components/feedback.md](./components/feedback.md)

### Navigation

| Component | Type | Purpose |
|---|---|---|
| `MainNav` | organism | App-level primary navigation bar |
| `Breadcrumb` | molecule | Hierarchical page location indicator |
| `Tabs` | molecule | Section organiser within a page |
| `Pagination` | molecule | Page-based navigation for tables and lists |
| `Sidebar` | template | Collapsible inline panel that pushes content |

→ [components/navigation.md](./components/navigation.md)

### Layout & Structure

| Component | Type | Purpose |
|---|---|---|
| `Page` | template | Full page wrapper with header, body, nav slots |
| `PageGrid` | template | Grid system defining responsive layout rules |
| `PageHeader` | organism | Page-level object header with CTA slots |
| `Section` | template | Attribute container grouping related content |
| `Card` | organism | Object card that can be static or clickable |

→ [components/layout.md](./components/layout.md)

### Tables & Lists

| Component | Type | Purpose |
|---|---|---|
| `GridTable` | organism | Data table with sort, filter, and row actions |
| `ListView` | molecule | Flexible virtualised list powering selects |
| `ListBox` | molecule | Single-select inline list |
| `MarketListBox` | molecule | Inline multi-country selection list |

→ [components/tables.md](./components/tables.md)

### Visuals

| Component | Type | Purpose |
|---|---|---|
| `Icon` | atom | Unified icon wrapper (glyph, brand, app, store) |
| `GlyphIcon` | atom | Graphic symbol from the glyph set |
| `AppIcon` | atom | Visual app identifier with gradient |
| `BrandIcon` | atom | External brand logo |
| `NavIcon` | atom | App-section icon for navigation |
| `StoreIcon` | atom | Distribution store identifier |
| `CountryFlag` | atom | Country flag glyph |
| `CoverArt` | atom | Product / artist / video cover container |
| `UserThumb` | atom | User profile picture with initials fallback |
| `Illustration` | atom | Generic product illustration |

→ [components/visuals.md](./components/visuals.md)

### Objects & Attributes

| Component | Type | Purpose |
|---|---|---|
| `Tag` | molecule | Property label attached to an object |
| `TagCloud` | molecule | Expandable container of `Tag` items |
| `Pill` | molecule | Clickable concept/object badge with popover |
| `PillCloud` | molecule | Expandable container of `Pill` items |
| `Metadata` | molecule | Label + value pair or atom group |
| `MetadataList` | molecule | Horizontal divided list of `Metadata` items |

→ [components/utilities.md](./components/utilities.md)

### Utilities

| Component | Type | Purpose |
|---|---|---|
| `Divider` | atom | Visual separator between components |
| `TruncatedText` | atom | Text truncation wrapper (dynamic or fixed width) |
| `HiddenCount` | molecule | Count badge + expand glyph for hidden items |
| `FilterCloud` | molecule | Expandable container of filter controls |
| `ExpandableContent` | organism | Collapsible content panel inside a container |

→ [components/utilities.md](./components/utilities.md)

## Critical Rules

- MUST import components from `@theorchard/suite-components` — never implement custom alternatives for components that exist in the library.
- MUST wrap every app in `ThemeProvider` from `@theorchard/suite-theming` — without it, brand colours will not apply.
- MUST import suite styles via SCSS in `App.tsx` — components have no inline styles.
- MUST use `formatMessage` from `@theorchard/suite-frontend` for all user-facing text — no raw string literals.
- MUST use the `useToast` hook to trigger toasts — do not render `<Toast>` directly.
- Do NOT use deprecated components (`Col`, `Container`, `Row`, `Dropdown`, `Table`, `Nav`, `Image`, `Control`, `InputGroup`, `SearchDropdown`, `LoadingIndicator`). Note: these appear in legacy code — do not copy their usage patterns.
- Do NOT use Bootstrap grid (`Row`, `Col`) for new layout — use `Page`, `PageGrid`, and `Section` instead.
- Do NOT write raw `<input>`, `<select>`, or `<button>` elements when a suite component exists for that purpose.
- Do NOT override semantic CSS variables directly — customise via `ThemeProvider` config instead.
- Prefer `SkeletonLoader` over `LoadingSpinner` when the content shape is known — it is the more common loading pattern across all apps.