UI and Components

The component library lives in packages/ui and is built on Chakra UI v3. The web app and Storybook consume it via @repo/ui/* imports.

Chakra UI System

The design system is configured in packages/ui/src/chakra.system.tsx using Chakra v3's createSystem API:

• Global CSS: Inter font, Lucide icon stroke width, selection colors.
• Custom tokens: Color palettes (gossamer, bluishGray), spacing, etc.
• Semantic tokens: brand, success, error, warning, destructive, sidebar background.
• Recipes: Custom button, badge, kbd defaults; editable and tooltip slot tweaks.
• Keyframes: Morphing gradient animations for the auth pages.

Theme Provider

packages/ui/src/ThemeProvider.tsx wires up:

1. ChakraProvider with the custom system.
2. next-themes ThemeProvider with attribute="class" (dark/light mode support).
3. Sonner <Toaster /> for toast notifications.

To regenerate Chakra types after changing the system:

pnpm --filter @repo/ui chakra:typegen
Copy

Color Palette

Chakra v3 introduces colorPalette as a contextual theming mechanism. Setting colorPalette="brand" on a component makes every colorPalette.* token reference inside it resolve against the brand color scale. This replaces the need to hard-code color scales on every child.

How It Works

1. A parent element sets colorPalette="brand" (or any palette name).
2. Descendants use semantic tokens like colorPalette.fg, colorPalette.solid, colorPalette.muted in style props.
3. Those tokens resolve to the corresponding shade of the active palette.

<Box colorPalette="success">
  {/* color resolves to success.fg (green.700 light / green.300 dark) */}
  <Text color="colorPalette.fg">Saved successfully</Text>
</Box>
Copy

Global and Recipe Defaults

The system config in packages/ui/src/chakra.system.tsx establishes several defaults:

Additionally, @repo/ui wrapper components like Tabs.Trigger and Switch.Root default to brand via colorPalette ?? "brand".

Available Palettes

Semantic palettes are defined in packages/ui/src/lib/createColorPalette.ts via createSemanticColorPalette, which maps a primitive color scale to semantic steps (solid, fg, muted, subtle, emphasized, focusRing, border, contrast, and shades 50--950):

Raw Chakra scales (gray, blue, green, red, purple, yellow, etc.) also work as colorPalette values and are used for finer-grained styling.

Conventions

Use semantic palette names for intent, not raw colors. Prefer colorPalette="error" over colorPalette="red" so the meaning is clear and the underlying scale can be changed in one place.

Primary actions use brand:

<Button colorPalette="brand" trackingData={{ event: "save" }}>
  Save
</Button>
Copy

Status indicators map domain states to palettes. Type the map with BoxProps["colorPalette"] for safety:

const STATUS_COLOR_MAP: Record<
  SessionProgressStatus,
  BoxProps["colorPalette"]
> = {
  complete: "success",
  processing: "purple",
  transcribing: "blue",
  failed: "error",
  initialized: "gray",
};

<Badge colorPalette={STATUS_COLOR_MAP[status]}>{statusLabel}</Badge>;
Copy

Referencing the active palette in child styles -- useful for icons or text that should follow the palette set by a parent:

<SparklesIcon
  colorPalette="ai"
  color={{ _dark: "colorPalette.fg", _light: "colorPalette.solid" }}
/>
Copy

Dynamic palette switching for interactive states like copy buttons:

<IconButton colorPalette={isCopied ? "success" : "gray"} ... />
Copy

Semantic Token Steps

Each palette created by createSemanticColorPalette provides these steps:

Import Patterns

Components are imported per-file, not from a barrel:

import { Button } from "@repo/ui/Button";
import { Field } from "@repo/ui/Field";
import { Dialog } from "@repo/ui/Dialog";
import { Drawer } from "@repo/ui/Drawer";
import { Table } from "@repo/ui/Table";
Copy

Composites and hooks have their own entry points:

import { DataTable, MultiFilterMenu } from "@repo/ui/composites";
import { useDebounce, useMediaQuery } from "@repo/ui/hooks";
Copy

Theme hook (separate entry):

import { useTheme } from "@repo/ui/useTheme"; // resolvedTheme, setTheme
Copy

Component Patterns

The UI package uses three main patterns:

1. Thin Wrappers

Re-export Chakra components as-is when no extra behavior is needed:

// packages/ui/src/Theme.tsx
export { Theme } from "@chakra-ui/react";
Copy

2. Augmented Components

Wrap Chakra components with additional behavior. The Button is the primary example -- it requires analytics trackingData:

// packages/ui/src/Button.tsx
export type ButtonProps = ChakraButtonProps & {
  trackingData: AnalyticsEvent | (() => AnalyticsEvent);
};

export const Button = ({ ref, children, ...props }: ButtonProps) => {
  const analytics = useAnalytics();

  const handleOnClick: ChakraButtonProps["onClick"] = async (event) => {
    await trackClickEvent(analytics, props.trackingData);
    props.onClick?.(event);
  };

  return (
    <ChakraButton ref={ref} {...props} onClick={handleOnClick}>
      {children}
    </ChakraButton>
  );
};
Copy

Every Button in the app must provide trackingData, ensuring analytics coverage by default.

3. Composed Slot APIs

Build richer components using Chakra's slot pattern with static subcomponents:

// packages/ui/src/Field.tsx
export type FieldProps = Omit<ChakraField.RootProps, "label"> & {
  label?: React.ReactNode;
  helperText?: React.ReactNode;
  errorText?: React.ReactNode;
  optionalText?: React.ReactNode;
};

const BaseField = forwardRef<HTMLDivElement, FieldProps>(function Field(props, ref) {
  const { label, children, helperText, errorText, optionalText, ...rest } = props;
  return (
    <ChakraField.Root ref={ref} {...rest}>
      {label && (
        <ChakraField.Label>
          {label}
          <ChakraField.RequiredIndicator fallback={optionalText} />
        </ChakraField.Label>
      )}
      {children}
      {helperText && <ChakraField.HelperText>{helperText}</ChakraField.HelperText>}
      {errorText && <ChakraField.ErrorText>{errorText}</ChakraField.ErrorText>}
    </ChakraField.Root>
  );
});

export const Field = Object.assign(BaseField, {
  Label: ChakraField.Label,
  HelperText: ChakraField.HelperText,
  ErrorText: ChakraField.ErrorText,
  RequiredIndicator: ChakraField.RequiredIndicator,
  Root: ChakraField.Root,
});
Copy

Composites

Larger components live in packages/ui/src/composites/:

Import via @repo/ui/composites.

Icons (@repo/ui/icons)

Icons live inside @repo/ui and are exported via the ./icons entry point. The module re-exports lucide-react icons wrapped with the shared Icon component under semantic names:

// packages/ui/src/icons/index.tsx
export { SearchIcon, ClientsIcon, TemplatesIcon, ... };
Copy

Usage:

import { SearchIcon, ClientsIcon } from "@repo/ui/icons";
Copy

Forms (@repo/use-form)

The @repo/use-form package wraps react-hook-form with automatic Zod validation:

// packages/use-form/src/index.ts
export function useForm<TSchema extends FormSchema>(
  props: UseFormProps<TSchema>,
) {
  return useReactHookForm({
    ...props,
    resolver: zodResolver(props.schema),
  });
}
Copy

You always pass a schema instead of a resolver:

import { useForm } from "@repo/use-form";
import { z } from "zod";

const schema = z.object({
  firstName: z.string().min(1),
  lastName: z.string().min(1),
});

function PersonForm() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    schema,
    defaultValues: { firstName: "", lastName: "" },
  });

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Field label="First Name" errorText={errors.firstName?.message}>
        <Input {...register("firstName")} />
      </Field>
    </form>
  );
}
Copy

Form Hook Convention

Feature-specific form hooks are colocated with their feature:

apps/web/app/(app)/settings/
├── page.tsx
└── lib/
    └── usePersonalInformationForm.ts  # schema + defaultValues + useForm
Copy

The hook encapsulates the schema and defaults. The component only receives control / register.

Re-exports from @repo/use-form for advanced use:

export {
  useController,
  useFieldArray,
  useFormState,
  useWatch,
} from "@repo/use-form";
Copy

Lower-level internals (e.g. Controller) are available via @repo/use-form/internals.

Analytics

How It Works

1. @repo/analytics-core defines an abstract AnalyticsClient and AnalyticsEvent type.
2. @repo/analytics-react provides AnalyticsProvider and useAnalytics().
3. The web app initializes a LoggerAnalyticsClient (logs to console) in apps/web/lib/providers.tsx.
4. The Button component automatically tracks clicks via the required trackingData prop.

Tracking Events

<Button trackingData={{ event: "save_template", properties: { templateId } }}>
  Save
</Button>
Copy

Or with a lazy factory when properties are computed:

<Button trackingData={() => ({ event: "submit_form", properties: getFormData() })}>
  Submit
</Button>
Copy

Storybook

Component stories live in apps/storybook/src/stories/. Run Storybook locally:

pnpm --filter storybook dev  # http://localhost:6006
Copy

Where Does a Component Belong?

New components can live in one of three places. Use this decision framework to pick the right one.

Decision Flowchart

flowchart TD
  Start["New component"] --> DomainCheck{"Is it domain-specific?"}
  DomainCheck -->|No| PkgUI["packages/ui"]
  DomainCheck -->|Yes| ReuseCheck{"Used by multiple\nroute features?"}
  ReuseCheck -->|No| Colocate["feature/components/"]
  ReuseCheck -->|Yes| Shared["shared/domain/"]

packages/ui -- Generic, Reusable Primitives

A component belongs in packages/ui when it is not tied to any domain and could be dropped into any app or Storybook story without knowledge of clients, session notes, templates, etc.

Examples: Button, Dialog, DataTable, Field, Tabs, SearchInput, icons.

Characteristics:

• Zero imports from @repo/trpc, @repo/db/schema, route definitions, or domain stores.
• Configurable via props, not domain-specific hooks.
• Has (or should have) a Storybook story.

apps/web/shared/<domain>/ -- Domain-Aware, Cross-Feature

A component belongs in shared/ when it composes @repo/ui primitives with domain data (tRPC queries, branded IDs, route definitions) and is imported by two or more route features.

Examples: PatientCombobox, TemplateCombobox, StartSessionDrawer, SessionNoteProgressBadge.

Characteristics:

• Imports domain types (PatientId, SessionProgressStatus) and uses tRPC queries.
• Has a barrel index.ts re-exporting components and hooks.
• Follows the same components/ + lib/ shape as route features.

apps/web/app/(app)/<feature>/components/ -- Page-Scoped

A component belongs colocated with its route when it is only used by that single feature.

Examples: ClientsTable, AddClientDrawer, LoginForm, AuditPreviewDrawer.

Characteristics:

• Lives in the components/ subfolder next to its page.tsx.
• Can freely import from shared/ and @repo/ui.

Promotion Path

Components move up the ladder as their usage grows:

feature/components/  -->  shared/<domain>/  -->  packages/ui
Copy

Start by colocating. When a second feature needs the same component, move it to shared/. When a component becomes fully generic (no domain imports), promote it to packages/ui.

A real example: CollapsibleSection currently lives in apps/web/shared/session-notes/components/ with a TODO noting it is a candidate for @repo/ui once it is generalized.

Next: Code Style and Tooling