UI Design System

UI Design System Skill

This skill enforces consistent UI patterns across the SG Cars Trends web application, ensuring a modern, professional dashboard design.

When to Activate

• Building new dashboard components or pages
• Reviewing existing UI for consistency
• Implementing navigation, cards, buttons, or metrics displays
• Applying colour scheme or typography
• Creating new features that require UI components
• Migrating or refactoring existing components

Design Principles

1. No sidebar - Horizontal pill navigation only
2. Pill-shaped elements - Use rounded-full for interactive elements
3. Large rounded cards - Use rounded-2xl or rounded-3xl
4. Professional automotive aesthetic - Navy Blue primary, clean typography
5. Generous whitespace - Grid-based layouts with gap-6 or gap-8

Colour Palette (GitHub Issue #406)

Semantic Colour Usage

• text-primary / bg-primary - Brand elements, primary buttons
• text-foreground - Body text (Dark Slate Gray)
• text-default-900 - Strong emphasis (H4 headings)
• text-default-600 - Secondary text (TextSm)
• text-muted-foreground - Captions, metadata

Opacity Scale

• text-foreground/60 - Secondary text
• text-foreground/40 - Muted text
• text-white - Only for image overlays

Component Patterns

Navigation (Horizontal Pill Tabs)

<div className="flex items-center gap-2 rounded-full border p-1">
  <Button className="rounded-full" color="primary">Dashboard</Button>
  <Button className="rounded-full" variant="light">Calendar</Button>
  <Button className="rounded-full" variant="light">Projects</Button>
</div>

Cards

import { Card, CardHeader, CardBody } from "@heroui/card";
import Typography from "@web/components/typography";

<Card className="rounded-2xl shadow-sm">
  <CardHeader className="flex flex-col items-start gap-2">
    <Typography.H4>Card Title</Typography.H4>
    <Typography.TextSm>Description text</Typography.TextSm>
  </CardHeader>
  <CardBody>{/* Content */}</CardBody>
</Card>

Buttons

• Primary: <Button className="rounded-full" color="primary">Action</Button>
• Secondary: <Button className="rounded-full" variant="bordered">Cancel</Button>
• Icon: <Button className="rounded-full" isIconOnly><Icon /></Button>

Status Badges

<Chip className="rounded-full" color="success" size="sm">
  <span className="mr-1">●</span> Done
</Chip>
<Chip className="rounded-full" color="warning" size="sm">
  <span className="mr-1">●</span> Waiting
</Chip>
<Chip className="rounded-full" color="danger" size="sm">
  <span className="mr-1">●</span> Failed
</Chip>

Metrics Display

<div className="flex flex-col gap-1">
  <Typography.Caption>Total Registrations</Typography.Caption>
  <div className="flex items-baseline gap-2">
    <span className="font-bold text-3xl">46,500</span>
    <Chip className="rounded-full" color="success" size="sm">+2.5%</Chip>
  </div>
</div>

Typography Rules

Always use Typography components from @web/components/typography:

Enforcement Rules

• ✅ Always use Typography.H4 for CardHeader titles
• ✅ Always use Typography.TextSm for CardHeader descriptions
• ✅ Use Typography.H2 for section headings
• ❌ Avoid raw <h1>, <h2>, <h3>, <h4> tags outside MDX content
• ⚠️ Exception: Raw tags allowed for MDX blog content and image overlays

Layout Guidelines

Spacing

• Use flex flex-col gap-* for vertical spacing (not space-y-*)
• Standard gaps: gap-2, gap-4, gap-6, gap-8
• Avoid margin-top for sibling spacing

Grid Layouts

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  <Card className="rounded-2xl">{/* ... */}</Card>
  <Card className="rounded-2xl">{/* ... */}</Card>
  <Card className="rounded-2xl">{/* ... */}</Card>
</div>

Anti-Patterns (What NOT to Do)

Navigation

• ❌ Vertical sidebar navigation
• ❌ Square/rectangular tabs
• ❌ Dropdown-only navigation

Cards

• ❌ Sharp corners (rounded-none, rounded-sm)
• ❌ Heavy shadows (shadow-lg, shadow-xl)
• ❌ Raw <h3> tags in CardHeader

Buttons

• ❌ Square buttons (rounded-none, rounded-md)
• ❌ Hardcoded colours (bg-blue-500)
• ❌ Missing hover states

Colours

• ❌ Hardcoded hex values in components
• ❌ text-white outside image overlays
• ❌ Inconsistent opacity values

Spacing

• ❌ space-y-* utilities
• ❌ mt-* for sibling spacing
• ❌ Odd gap values (gap-3, gap-5, gap-7)

Tools Used

• Read: Examine existing component implementations
• Grep: Find similar patterns in codebase
• Context7 MCP: Fetch latest HeroUI documentation
  • mcp__context7__resolve-library-id - Find library ID
  • mcp__context7__get-library-docs - Get component docs

Accessibility Requirements (WCAG AA)

• Normal text: Minimum 4.5:1 contrast ratio
• Large text: Minimum 3:1 contrast ratio
• Interactive elements: Minimum 3:1 for focus indicators
• Information must not be conveyed by colour alone
• All interactive elements must be keyboard accessible

Related Documentation

• apps/web/CLAUDE.md - Full UI guidelines
• GitHub Issue #406 - Colour scheme specification
• HeroUI documentation - Component API reference