Luz Design System Guide

How to use the @repo/luz design system in the platform app.

Quick Start

import { Button, Stack, Card } from '@repo/luz';

export function MyComponent() {
  return (
    <Stack gap="4">
      <Card>
        <Button>Click me</Button>
      </Card>
    </Stack>
  );
}

Package Overview

Luz is a local monorepo package at packages/luz. It provides reusable UI components built on Tailwind CSS, Radix UI, and TanStack Table.

Import from: @repo/luz

Available Components

Primitives

Component	Description
`Button`	Action button
`Box`	Generic container
`Card`	Card container
`Icon`	Hero icon wrapper
`Indicator`	Status/badge indicator
`Tooltip`	Hover tooltip
`Text`	Body text
`Heading`	Heading text
`DataText`	Data-formatted text

Forms

Component	Description
`Checkbox`	Checkbox input
`Dropdown`	Select dropdown

Layout

Component	Description
`Stack`	Vertical/horizontal stack
`Flex`	Flexbox container
`Grid`	Grid layout
`LayoutContainer`	Page content wrapper
`LayoutHeader`	Header section
`LayoutPage`	Full page wrapper
`ModuleSection`	Tabbed section with header

Data Display

Component	Description
`DataTable`	Table with sorting, pagination, selection
`SelectableDataTable`	DataTable with bulk actions
`DataLabel`	Key-value label
`DataBlock`	Data block container
`Tag`	Status tag
`ExposureTag`	Risk exposure tag
`MitigationTag`	Mitigation level tag
`RiskProfile`	Risk profile display

Component	Description
`Breadcrumb`	Breadcrumb navigation
`BigTabs`	Large tab navigation
`Toolbar`	Search and filter toolbar
`Menu`	Dropdown menu
`BulkActionsToolbar`	Floating bulk actions

Composite

Component	Description
`Scorecard`	Complex card with header/body/actions
`EntityCard`	Entity information card
`Flags`	Country flag display
`BrandedSummary`	Branded summary card

Usage Patterns

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>
  );
}

Scorecard Pattern

import {
  Scorecard,
  ScorecardHeader,
  ScorecardHeaderLeft,
  ScorecardHeaderRight,
  ScorecardBody,
  ScorecardContent,
  ScorecardLink,
} from '@repo/luz';

<Scorecard>
  <ScorecardHeader>
    <ScorecardHeaderLeft>
      <Heading size="3">Title</Heading>
    </ScorecardHeaderLeft>
    <ScorecardHeaderRight>
      <Tag>Status</Tag>
    </ScorecardHeaderRight>
  </ScorecardHeader>
  <ScorecardBody>
    <ScorecardContent>
      {/* Content */}
    </ScorecardContent>
  </ScorecardBody>
  <ScorecardLink href="/details">View details</ScorecardLink>
</Scorecard>

DataTable Pattern

import { DataTable } from '@repo/luz';
import { createColumnHelper } from '@tanstack/react-table';

const columnHelper = createColumnHelper<DataType>();

const columns = [
  columnHelper.accessor('name', {
    header: 'Name',
    cell: (info) => info.getValue(),
  }),
  columnHelper.accessor('status', {
    header: 'Status',
    cell: (info) => <Tag>{info.getValue()}</Tag>,
  }),
];

<DataTable
  data={data}
  columns={columns}
  pagination={{ pageIndex: 0, pageSize: 10 }}
  onPaginationChange={setPagination}
/>

import {
  Toolbar,
  ToolbarSearch,
  ToolbarFilter,
  ToolbarResults,
  ToolbarResultItem,
} from '@repo/luz';

<Toolbar>
  <ToolbarSearch placeholder="Search..." value={query} onChange={setQuery} />
  <ToolbarFilter label="Status" options={statusOptions} />
  <ToolbarResults>
    {results.map((item) => (
      <ToolbarResultItem key={item.id}>{item.name}</ToolbarResultItem>
    ))}
  </ToolbarResults>
</Toolbar>

Utility Exports

Class Name Helper

import { cn } from '@repo/luz';

<div className={cn('base-class', isActive && 'active-class')} />

Color Constants

import {
  DATA_EXPOSURE_COLORS,
  DATA_MITIGATION_COLORS,
  RISK_COLORS,
  STATUS_COLORS,
} from '@repo/luz';

Design Tokens

import { tokens, semanticTokens, textStyles } from '@repo/luz';

Styles Setup

Luz styles must be imported in your app's root layout:

// apps/web/src/app/layout.tsx
import '@repo/luz/styles.css';

Storybook

Browse all components with live examples:

# From repo root
cd packages/luz
npm run storybook

Storybook runs on http://localhost:6006

Key Principles

Use luz components - Don't write custom Tailwind in web app 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