ui-primitives

name	ui-primitives
description	UI primitive components for this project (BlockStack, InlineStack, Text, Heading, Paragraph, Button, Icon). Use when writing JSX, creating components, or working with layout and typography.

UI Primitives

Always prefer UI primitives over raw HTML elements.

Layout

Use BlockStack and InlineStack from @/components/ui/layout instead of <div className="flex ...">:

• BlockStack = vertical flex (flex-col)
• InlineStack = horizontal flex (flex-row)
• Both support gap, align, blockAlign props
• Use as prop for semantic elements: <BlockStack as="ul">, <InlineStack as="li">

Typography

All typography components are exported from @/components/ui/typography.

Use Heading for headings instead of raw <h1-h6> or Text as="h*":

• <Heading level={2}>Title</Heading> — renders <h2> with role="heading" and aria-level
• Automatically sets size="md" + weight="semibold" for level 1, size="sm" for others
• Supports tone, size, weight, font overrides

Use Paragraph for paragraph text instead of raw <p> or Text as="p":

• <Paragraph size="sm" tone="subdued"> instead of <p className="text-sm text-muted">

Use Text for inline text (<span>, <dt>, <dd>, etc.):

• <Text as="dt" weight="semibold"> instead of <dt className="font-semibold">
• Supports: as, size, weight, tone, font props

Buttons

Use Button from @/components/ui/button

Icons

Use Icon from @/components/ui/icon

Styling

• Use shadcn/ui components from @/components/ui/ for all UI primitives
• Use TailwindCSS v4 for styling (not CSS modules or styled-components)
• Only use inline styling (style={...}) for dynamic/variable CSS values (e.g., style={{height: h}}). Never use inline styles for static values — use Tailwind classes instead
• Use cn() utility for conditional classes (from @/lib/utils)
• Prefer composition over prop drilling for complex components

Suggest Abstractions for Repeated Patterns

When you see similar Tailwind class combinations used multiple times, suggest creating reusable components or utility classes:

• Multiple buttons with similar styling -> Create a Button variant or new component
• Repeated container/card patterns -> Abstract into reusable Card component
• Common spacing/layout patterns -> Suggest utility classes or component abstractions
• Similar form field styling -> Create form field components

When Raw HTML is Acceptable

• Semantic elements not supported by primitives (e.g., <dl>, <ul>, <ol>, <table>)
• Complex layouts where primitives don't fit
• Performance-critical sections where abstraction overhead matters