Frontend Guidelines

Purpose

This document defines the frontend architecture, design system, component strategy and UI conventions for the Symfony UX Starter Kit.

All frontend implementations must follow these guidelines.

---

Frontend Stack

The following frontend stack is mandatory.

Styling

• Tailwind CSS
• Preline UI

Interaction

• Stimulus
• Symfony UX

Components

• Symfony UX Twig Components
• Symfony UX Live Components

UX Packages

• Symfony UX Autocomplete
• Symfony UX ChartJS
• Symfony UX Dropzone
• Symfony UX Icons
• Symfony UX Map
• Symfony UX Toolkit

---

Forbidden Technologies

Do not introduce:

• Bootstrap CSS
• Flowbite
• DaisyUI
• React
• Vue
• Angular
• jQuery

Bootstrap Icons are allowed through Symfony UX Icons.

---

Design Philosophy

The UI should follow modern SaaS and professional application standards.

Inspirations:

• Linear
• Vercel
• Stripe Dashboard
• GitHub
• Notion

The interface should be:

• clean
• minimalist
• responsive
• accessible
• dark-mode friendly

---

Design System

Colors

Primary background:

slate-950

Surface:

slate-900

Primary color:

blue-600

Primary hover:

blue-500

Primary active:

blue-700

Accent:

cyan-500

Text:

gray-100

Muted text:

gray-400

Borders:

slate-800

Success:

green-500

Warning:

amber-500

Danger:

red-500

---

Typography

Primary Font

Plus Jakarta Sans

Used for:

• titles
• forms
• navigation
• cards
• tables
• content

Monospace Font

JetBrains Mono

Used for:

• technical values
• identifiers
• invoice references
• order references
• monetary values
• code snippets

---

Forbidden Fonts

Do not use:

• Arial
• Verdana
• Tahoma
• Times New Roman

---

Dark Mode

Dark mode is mandatory.

All components must support dark mode.

No light-only components are allowed.

---

Responsive Design

All pages must support:

• desktop
• tablet
• mobile

Mobile-first principles should be preferred.

---

Layout

The application uses a shared layout.

Sidebar
Header
Content Area

Structure:

+---------------------+
| Sidebar             |
|                     |
+------+--------------+
       | Header       |
       +--------------+
       | Content      |
       |              |
       +--------------+

---

Sidebar

The sidebar is a reusable Symfony UX Component.

Responsibilities:

• navigation
• active state
• icons
• responsive collapse

Component:

Sidebar

---

Navbar

The navbar is a reusable Symfony UX Component.

Responsibilities:

• branding
• navigation
• account actions
• authentication links

Component:

Navbar

---

Component Strategy

Preline provides visual implementation.

Symfony UX Components provide application abstraction.

Architecture:

Page
↓
Symfony UX Component
↓
Preline
↓
Tailwind

---

Component First Rule

Before creating a new component:

1. Search existing components.
2. Reuse existing components.
3. Extend existing components.
4. Create a new component only if necessary.

---

Reusable Components

Expected components:

Card
Modal
Alert
Badge
Dropdown
Table
Navbar
Sidebar
StatWidget
Pagination
FormField

---

Component Naming

Good:

Card
Modal
Table
Badge

Bad:

UserCard
CustomerCard
ProfileCard
DashboardCard

Prefer configurable generic components.

Example:

<twig:Card title="Profile">
    ...
</twig:Card>

---

Component Compliance

When a task references an existing Preline component:

The generated component must visually resemble the official Preline component.

The objective is adaptation, not reinterpretation.

Preline Compliance

Preline UI is the visual source of truth.

When implementing a component based on a Preline component:

1. Start from the official Preline markup.
2. Preserve the overall structure.
3. Preserve spacing conventions.
4. Preserve visual hierarchy.
5. Adapt only what is required for Symfony UX integration.

Do not redesign components.

Do not invent alternative layouts when a Preline component already exists.

Cards

Cards are the primary container component.

Cards should:

• use rounded corners
• have subtle borders
• support headers
• support actions
• support footer areas

Example:

<twig:Card title="User Information">
    ...
</twig:Card>

---

Tables

Tables must be responsive.

Tables should support:

• empty states
• loading states
• pagination
• sorting preparation

Component:

Table

---

Forms

Forms should use Symfony Forms.

All form fields should be wrapped using reusable components.

Example:

FormField

Responsibilities:

• label
• error
• help text
• accessibility

---

Buttons

Button hierarchy:

Primary:

blue-600

Secondary:

slate-700

Danger:

red-500

Success:

green-500

---

Modals

Modals should be implemented through:

Modal

Avoid custom modal implementations.

Use Preline modal behavior.

---

Alerts

Alert component variants:

success
warning
danger
info

Reusable component:

Alert

---

Badges

Badge component variants:

success
warning
danger
info
neutral

Reusable component:

Badge

---

Icons

Icons must be provided through:

Symfony UX Icons

Preferred icon set:

Bootstrap Icons

No SVG duplication in templates.

No inline SVG unless strictly necessary.

---

Charts

Charts use:

Symfony UX ChartJS

Charts are demonstration-only.

Keep examples generic.

---

Maps

Maps use:

Symfony UX Map

Leaflet should be used for demonstrations.

The account page demonstrates user localisation.

---

Dropzone

Uploads use:

Symfony UX Dropzone

The home page should demonstrate upload capabilities.

---

Autocomplete

Autocomplete uses:

Symfony UX Autocomplete

The home page should contain a demonstration component.

---

Home Page

Purpose:

Demonstrate available UI components.

Examples:

• Card
• Alert
• Badge
• Table
• Chart
• Dropzone
• Autocomplete
• Map
• Live Component

No business data.

---

Account Page

Purpose:

Demonstrate authenticated profile management.

Displayed information:

• first name
• last name
• email
• avatar
• biography
• roles
• localisation

Use reusable components exclusively.

---

Accessibility

Requirements:

• keyboard navigation
• labels on all inputs
• visible focus states
• proper contrast ratios

Accessibility is not optional.

---

Custom CSS

Avoid custom CSS whenever possible.

Prefer:

• Tailwind utilities
• reusable components

Custom CSS should be exceptional.

---

UI Generation Rule

When creating a new page:

1. Reuse existing layout.
2. Reuse existing components.
3. Respect dark mode.
4. Respect typography.
5. Respect palette.
6. Respect responsiveness.
7. Respect accessibility.

No exceptions.

Variant Logic

Toute logique liée aux variantes visuelles doit être définie dans le composant PHP.

Cela inclut :

• classes CSS ;
• icônes ;
• labels internes ;
• styles d’état.

Les templates Twig ne doivent pas contenir de longues conditions if/elseif pour gérer les variantes.