# Veriforce Design System

> This is a MUI component library, for MUI v7 and v9, with a custom theme built on design tokens. It uses FontAwesome for icons.

Install: `npm install @alcumus/design-tokens` (GitHub Packages) or
`npm install @pec/design-tokens` (Artifactory).

```js
import "@alcumus/design-tokens/css";
import { theme } from "@alcumus/design-tokens/theme/mui-7";
```

These apply to every file, whether or not the linked docs restate them:

- Import MUI components directly: `import Button from '@mui/material/Button'`
- Never use raw HTML elements — `<Typography>` not `<p>`, `<Button>` not `<button>`
- Use FontAwesome icons only — never `@mui/icons-material`
- Use the `sx` prop with `theme.spacing()` for layout — never raw pixel values
- Reference design tokens via the theme — never hard-code colors or fonts
- Check the relevant component group file for design system-specific guidance before implementing

## Foundations

- [Colors](https://alcumus.github.io/design-system/guidelines/foundations/colors.md): Our color system is built on a set of semantic color scales derived from our design tokens.
- [Data Formatting](https://alcumus.github.io/design-system/guidelines/foundations/data-formatting.md): Formatting rules for all data displayed in the UI. Follow these when generating sample data.
- [Data Visualization](https://alcumus.github.io/design-system/guidelines/foundations/data-visualization.md): Principles and palettes for representing data visually across Veriforce products. These guidelines ensure that charts, graphs and data displays are readable, accessible and consistent — regardless of which product surface they appear on.
- [Icons](https://alcumus.github.io/design-system/guidelines/foundations/icons.md): FontAwesome (Free) only. Do not use MUI icons. Icons inherit color from their parent by default.
- [Spacing](https://alcumus.github.io/design-system/guidelines/foundations/spacing.md): MUI uses an 8px base spacing scale. We use the `theme.spacing()` function and the `sx` prop for consistent spacing throughout the application.
- [Typography](https://alcumus.github.io/design-system/guidelines/foundations/typography.md): Our type system uses MUI's Typography component with customized theme tokens for font family, weight and sizing.
- [Voice Tone](https://alcumus.github.io/design-system/guidelines/foundations/voice-tone.md): All UI text should sound like it comes from the same knowledgeable, trustworthy colleague. We help people manage contractor safety and compliance — the stakes are real, and our voice reflects that.

## Patterns

- [Add Table Data](https://alcumus.github.io/design-system/guidelines/patterns/add-table-data.md): The most common write operation — adding a new record to a data table via a dialog form.
- [Edit Table Data](https://alcumus.github.io/design-system/guidelines/patterns/edit-table-data.md): The standard edit workflow — open the record from the row overflow menu, edit it in the right surface for its complexity and keep **Save changes** in view the whole time.
- [Filter Table Data](https://alcumus.github.io/design-system/guidelines/patterns/filter-table-data.md): The standard filtering workflow — pertinent filters sit in the toolbar, the rest behind Add filter and the table narrows in place as values change.
- [Form Validation](https://alcumus.github.io/design-system/guidelines/patterns/form-validation.md): Standardizes how forms communicate errors, validate input and guide correction across all Veriforce products.
- [Remove Table Data](https://alcumus.github.io/design-system/guidelines/patterns/remove-table-data.md): The standard destructive workflow — initiate removal from a row context menu, confirm in a destructive dialog, see the row fade out with a success toast.
- [Unsaved Changes](https://alcumus.github.io/design-system/guidelines/patterns/unsaved-changes.md): How an edit surface commits work and how it handles a user leaving with edits in flight — saving stays in view, and a dirty exit prompts rather than traps.

## Conventions

Standing rules that hold across every surface.

- [Button Hierarchy](https://alcumus.github.io/design-system/guidelines/conventions/button-hierarchy.md): Establishes the rules for button hierarchy, placement and treatment across all Veriforce surfaces — so users can scan and act confidently.
- [Focus Management](https://alcumus.github.io/design-system/guidelines/conventions/focus-management.md): Where focus lands when a surface opens, moves or closes — so a keyboard user is never dropped somewhere they can't see.
- [Navigation Hierarchy](https://alcumus.github.io/design-system/guidelines/conventions/navigation-hierarchy.md): Establishes which control owns which level of the app's information architecture — so a destination is reachable one way, from one place, at one URL.
- [Required Fields](https://alcumus.github.io/design-system/guidelines/conventions/required-fields.md): When a form marks required fields with an asterisk — and how to shape forms so it rarely has to.

## Layouts

Page-level shells. Pick the layout first, then compose components into it.

- [AppLayout](https://alcumus.github.io/design-system/guidelines/layouts/app-layout.md): The canonical app shell — the required starting point for **any full-page screen**. It fixes the one correct arrangement of the three frame pieces (sidebar, app bar, content) so no screen has to reinvent it.
- [DetailPage](https://alcumus.github.io/design-system/guidelines/layouts/detail-page.md): The standard layout for viewing a single entity — a back button and title row, followed by tabbed content.
- [TablePage](https://alcumus.github.io/design-system/guidelines/layouts/table-page.md): A full list / index page — the most common admin screen in Veriforce apps. Use it for any collection of records: projects, contractors, sites, inspections, users.

## Components

- [buttons components](https://alcumus.github.io/design-system/guidelines/components/buttons.md): Button, Fab, SpeedDial, ToggleButton
- [data-display components](https://alcumus.github.io/design-system/guidelines/components/data-display.md): Avatar, Badge, Chip, Divider, EmptyState, Icon, Keycap, List, Table, TableCells, Timeline, Tooltip
- [feedback components](https://alcumus.github.io/design-system/guidelines/components/feedback.md): Alert, Backdrop, Dialog, Popover, Progress, Skeleton, Snackbar
- [inputs components](https://alcumus.github.io/design-system/guidelines/components/inputs.md): Autocomplete, Checkbox, Filter, PhoneField, Radio, Select, Slider, Switch, TextField, TransferList
- [layouts components](https://alcumus.github.io/design-system/guidelines/components/layouts.md): Container, PageHeader, Sidebar, TableToolbar
- [navigation components](https://alcumus.github.io/design-system/guidelines/components/navigation.md): AppBar, Breadcrumbs, Drawer, DrawerHeader, Link, Menu, OrganizationPicker, Pagination, Stepper, Tabs
- [surfaces components](https://alcumus.github.io/design-system/guidelines/components/surfaces.md): Accordion, Card

## Docs site

- [Veriforce Design System](https://alcumus.github.io/design-system/): The same guidance as browsable pages with live component previews — component URLs follow https://alcumus.github.io/design-system/components/<name>.

## Optional

- [Guidelines](https://alcumus.github.io/design-system/guidelines/Guidelines.md): Full bundle — coding conventions plus a file index, for when only one file can be fetched