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

name, description

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

Frontend System

This skill ensures that all frontend work follows the established UI architecture and design system used in this project.

The system is defined by the real implementation in the codebase, not by external design assumptions.

Source of truth

The current system is defined by:

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

These files define the project's UI primitives, tokens, layout rules, and styling system.

Primitive architecture

All shared UI must originate from the local primitive layer.

Primary primitives live in:

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 rather than reimplementing their behavior.

If new shared UI behavior is required, extend the primitive layer instead of bypassing it.

Class composition

Use the project's shared helper:

cn()

from:

lib/utils.ts

for class composition.

Variant logic should use:

class-variance-authority (cva)

when the primitive already exposes variants.

Allowed libraries

Frontend code may use only the libraries already present in the system.

UI primitives:

• @radix-ui/react-* through local primitives

Styling:

• tailwindcss

Class composition:

• class-variance-authority
• clsx
• tailwind-merge

Motion:

• framer-motion
• tailwindcss-animate

Icons:

• lucide-react

Do not introduce additional UI frameworks or icon libraries.

Token system

Styling must rely on the semantic token layer defined in:

• app/globals.css
• tailwind.config.ts

Prefer semantic tokens over raw color values.

Shared UI must not introduce new arbitrary color values when tokens already exist.

Radius system

The project uses a shared radius token system.

Approved radius token categories include:

• surface radius
• nested element radius
• pill radius

These tokens are mapped in Tailwind and must be used for shared UI.

Shared components should not introduce arbitrary radius values.

Surface and card system

Shared surfaces should follow the established card system.

Primary shared surfaces originate from:

• Card
• AppCard

These primitives define the canonical surface styles used throughout the application.

Feature code should not duplicate card styling directly.

Instead, reuse these primitives or extend them where necessary.

Layout system

Shared layout constraints should use the project's container system.

The container primitive defines width limits and horizontal padding behavior.

Container variants include categories such as:

• default layout width
• narrow content width
• wide layout width
• admin layout width

Layout code should reuse the container primitive rather than defining ad-hoc layout wrappers.

Spacing rhythm

The project uses a consistent spacing rhythm.

Common spacing categories include:

• surface padding
• component internal spacing
• layout gaps
• vertical content spacing

Spacing values should remain consistent with the existing system used in primitives and layout components.

Avoid introducing arbitrary spacing values for shared components.

Motion system

Motion is implemented through two layers.

Custom motion:

• framer-motion

Primitive state transitions:

• tailwindcss-animate

Before introducing new motion patterns, inspect existing motion components and reuse their behavior when possible.

Icon system

The project uses a single icon library:

• lucide-react

Icons should be imported from this library only.

Do not introduce additional icon libraries.

Arbitrary Tailwind values

Arbitrary Tailwind values are not globally forbidden.

They may be used when required for:

• layout-specific grid definitions
• rare content sizing constraints
• typography fitting adjustments
• one-off layout edge cases not covered by tokens

However, arbitrary values must not replace the shared token system.

They should not be used for shared-system styling when project tokens already exist, especially for categories such as:

• radius
• colors
• shadows
• borders
• shared surface styling

When arbitrary values are used, they should remain narrow in scope and justified by layout or typography needs.

Forbidden patterns

The following patterns must be avoided:

• introducing a new UI framework
• bypassing the local primitive layer when an equivalent primitive already exists
• creating feature-level implementations of components that already exist in components/ui
• importing Radix primitives directly in feature code when a local wrapper exists
• introducing raw styling for shared UI surfaces when tokenized styles already exist
• creating duplicate design systems
• adding styling abstractions that conflict with the existing token system

Transitional areas

Some files still contain transitional visual code.

These areas must not be treated as canonical UI system references for new work.

Examples include decorative hero components, experimental visual effects, or legacy route-level styling.

When implementing new UI, prefer primitives and tokens defined in the main system rather than copying patterns from transitional files.

Implementation guidance for Codex

When implementing frontend code:

1. Inspect existing primitives before writing new UI.
2. Reuse primitives from components/ui.
3. Prefer semantic tokens over raw styling.
4. Follow the established radius, surface, spacing, and container systems.
5. Reuse motion patterns before introducing new ones.
6. Keep new UI aligned with the current frontend architecture.

If a requested UI does not fit the current primitives, extend the primitive layer rather than bypassing it.