145 lines
2.9 KiB
Markdown
145 lines
2.9 KiB
Markdown
---
|
|
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. |