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)

#191970

bg-primary

text-primary

#708090

bg-secondary

text-secondary

#00FFFF

bg-accent

text-accent

#B0E0E6

bg-muted

#2F4F4F

text-foreground

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

Typography.H1

font-semibold text-4xl text-foreground

Typography.H2

font-semibold text-3xl text-foreground

Typography.H3

font-medium text-2xl text-foreground

Typography.H4

font-medium text-xl text-default-900

Typography.TextLg

text-lg text-foreground

Typography.Text

text-base text-foreground

Typography.TextSm

text-sm text-default-600

Typography.Label

font-medium text-sm text-foreground

Typography.Caption

text-xs text-muted-foreground

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