Best Practice

Guidelines for working with the platform app.

Design System

• Use the luz design system for all components - it provides the "lego blocks" built on Tailwind
• Components should be reusable and composable
• Do not write Tailwind CSS directly in web application components
• Compose, don't customize - build UIs by combining luz components
• Check Storybook first - see available props and variants before implementing
• Use layout components (Stack, Grid, LayoutContainer) for consistent spacing

Layout

• Layout components act as a "shell" around content
  • See: https://nextjs.org/docs/app/getting-started/layouts-and-pages
• Use slots for headers and sidebars
• Use query parameters for changing page values, not layout
• Use shallow linking with the <Link> component where possible

Layout Structure

import { LayoutContainer, LayoutHeader, Stack } from '@repo/luz';

export default function Page() {
  return (
    <LayoutContainer>
      <LayoutHeader>
        <Heading>Page Title</Heading>
      </LayoutHeader>
      <Stack gap="6">
        {/* Page content */}
      </Stack>
    </LayoutContainer>
  );
}

Components

Server Components (Default)

• Use React Server Components wherever possible
  • See: https://nextjs.org/docs/app/getting-started/server-and-client-components
• Use for rendering server-side data

Client Components

• Use only when small state updates are necessary

Data Fetching

• Use use() and <Suspense> for data fetching where possible
• Use Promise.all() to fetch data in parallel for better performance

State Management

Prop drilling should never be necessary. If you find yourself prop drilling, revisit your component composition.