sass-mohfarawati/.codex/skills/frontend-system/SKILL.md

name, description

name	description
mohfarawati-ui-rules	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.