---
name: mohfarawati-ui-rules
description: Enforce the project's frontend architecture and UI system when implementing or modifying frontend code.
---

# Frontend System

All frontend work must follow the existing UI architecture and design system implemented in this repository.

The system is defined by the **actual implementation**, not by external assumptions.

## Source of truth

The UI system is defined by:

- docs/frontend-system-current-state.md
- components/ui/*
- components/layout/*
- lib/utils.ts
- app/globals.css
- tailwind.config.ts

Always inspect these files before implementing UI.

---

# UI primitives

Shared UI components must originate from the local primitive layer:

`components/ui`

Examples include:

Button, Card, AppCard, Input, Textarea, Select, Dialog, Sheet, Tabs, DropdownMenu, Accordion, Badge, Checkbox, Table, Label, Separator.

Feature code **must reuse these primitives** instead of reimplementing them.

If new shared UI behavior is required, extend the primitive layer rather than bypassing it.

---

# Styling rules

## Class composition

Use `cn()` from:

`lib/utils.ts`

Variant logic should use `cva` when primitives support variants.

## Tokens

Use semantic tokens defined in:

- `app/globals.css`
- `tailwind.config.ts`

Prefer tokens over raw values.

Do not introduce arbitrary colors, radius values, shadows, or borders when tokens already exist.

---

# Allowed libraries

Only use libraries already present in the project.

UI primitives  
- `@radix-ui/react-*` (via local wrappers)

Styling  
- `tailwindcss`

Utilities  
- `class-variance-authority`
- `clsx`
- `tailwind-merge`

Motion  
- `framer-motion`
- `tailwindcss-animate`

Icons  
- `lucide-react`

Do not introduce additional UI frameworks or icon libraries.

---

# Layout and surfaces

Shared layout and surfaces must reuse existing primitives:

- `Card`
- `AppCard`
- container components from `components/layout`

Do not recreate card styles or layout wrappers inside feature code.

---

# Motion

Use existing motion patterns.

- custom motion: `framer-motion`
- primitive transitions: `tailwindcss-animate`

Avoid introducing new motion systems.

---

# Forbidden patterns

Avoid:

- introducing new UI frameworks
- bypassing `components/ui` when a primitive already exists
- importing Radix primitives directly in feature code
- duplicating design systems
- creating alternative styling abstractions
- hardcoding shared surface styles

---

# Arbitrary Tailwind values

Arbitrary Tailwind values are allowed only for rare layout or typography edge cases.

They must **not replace tokens** for shared styling (colors, radius, shadows, borders).

---

# Implementation guidance

When implementing frontend code:

1. Inspect existing primitives first.
2. Reuse components from `components/ui`.
3. Prefer tokens over raw styles.
4. Follow existing layout and surface patterns.
5. Reuse motion patterns.
6. Extend primitives instead of bypassing them.