Design, Typography and UX Guidelines

See docs/AGENTS.md for the main guidelines document. For mobile-specific constraints (safe areas, touch targets, mobile navigation), also follow docs/AGENTS_MOBILE.md.

CRITICAL RULE: Before implementing any UI feature, review this design guide and AGENTS_FRONTEND.md together.

Scope

Use this document when working on:

• Visual design direction (look and feel, graphic language)
• Typography system (font usage, scale, rhythm)
• UX/UI behavior (navigation, hierarchy, interactions)
• Accessibility and responsive quality of interfaces

Visual Direction

• Start with a clear visual intent before coding: define atmosphere, contrast level, and brand personality.
• Use a restrained color system: neutral base + one primary accent + optional status colors.
• Avoid decorative noise: too many shadows, gradients, icon styles, or competing visual motifs.
• Keep visual consistency across pages: same corner radius families, border contrast, and card elevation.
• Prefer visual hierarchy through spacing, scale, and weight before introducing new colors.
• Do not mix unrelated design languages in the same flow (e.g., glassmorphism + brutalist + enterprise defaults).

Brand and Logo Rules

• Brand rendering must be centralized:
  • Use Logo for all visual brand lockups (header, sidebar, auth pages, landing).
  • Use BrandName only for plain text labels where logo image is not needed.
  • Do not hardcode brand strings directly in JSX ("Aaperture", "Aperture").
• When a page uses brand signature text, render it via Logo (showMark={false} allowed) to keep a single source of truth.
• Baseline usage (STUDIO CRM) should be rendered via Logo (showBaseline) instead of handwritten JSX text.
• Prefer the typographic lockup + baseline on high-visibility brand surfaces:
  • main sidebar header (desktop + mobile)
  • auth/public headers
  • login/marketing hero brand blocks
  • public landing navigation/footer
• On client portal headers, prefer typographic brand lockup (Logo with showMark={false}) instead of image mark.
• Sidebar branding hierarchy is mandatory:
  • App name in main desktop sidebar must be visually prominent (use larger typographic scale than nav labels).
  • Collapsed sidebar initial must stay clearly legible and aligned with the same brand tone.
  • Mobile sidebar header must preserve the same brand prominence as desktop.

Transactional Email Visual System

• Transactional/system emails are part of the product brand experience and must follow the same premium/light design language as the web app.
• Prefer a typographic wordmark (Aaperture) over legacy image logos in email headers unless a specific legal/white-label requirement mandates an image.
• Brand casing matters:
  • Use Aaperture (not AAPERTURE, Aperture, or mixed variants).
• Email visual direction:
  • Light warm neutral background
  • Refined card container with soft border
  • Restrained bronze/amber accent for CTA and highlights
  • No flashy gradients or saturated blue defaults
• Typography in emails:
  • Serif display for brand/title moments
  • Clean UI sans for body copy
  • Strong hierarchy with generous spacing and readable line-height
• Info/status blocks in emails should use subtle tinted surfaces + left border accents, not heavy fills.
• Email buttons should feel premium and calm:
  • rounded corners
  • subtle border / inset highlight
  • no generic bright-blue CTA default

Client Portal Visual Rules (Premium/Minimal)

• Use a restrained palette only: neutrals + one subtle accent (prefer warm accent like amber/bronze).
• Avoid multicolor gradients, rainbow accents, and mixed icon colors in navigation/KPI areas.
• Header and navigation must stay clean and premium: soft borders, low-contrast surfaces, no flashy fills.
• Keep icon treatments uniform across cards and nav (same container style, same visual weight).
• Prefer contrast by typography, spacing, and elevation before introducing new colors.
• Primary actions must stay monochrome: black/white/gray button styling for app, client access token pages, and client portal.
• Dark mode must mirror light mode quality: same hierarchy, same spacing rhythm, same premium surfaces, and no extra saturated colors.
• In dark mode, prefer charcoal/graphite surfaces with neutral text contrast; avoid blue/purple glow effects.

Typography Rules

• Define and reuse a typography scale for all screens (xs, sm, base, lg, xl, etc.).
• Keep body text highly readable: adequate line-height, stable letter spacing, and strong contrast.
• Use at most 2 font families in one interface:
  • One for UI/content
  • One optional display family for strong headings/brand moments
• Avoid all-caps for long labels or paragraphs; reserve it for short metadata/chips.
• Keep heading rhythm consistent:
  • One primary h1 per page
  • Descending hierarchy without skipping levels
• Do not use random one-off font sizes. Extend tokens instead.
• Brand signature typography (hero, auth, marketing headers): font-serif italic font-normal tracking-tight.
• Product UI typography (navigation labels, settings, data tables): default system typography from design system components.

Product Wording Rules

• This is a client-facing product. Default wording must sound clear, calm, and useful to a real user, not to the internal team.
• Prefer direct labels that explain the outcome or the action:
  • good: What to do now, Missing contact info, Send follow-up email
  • avoid: Decision engine, Blocking gaps, Run best action, Entity context
• Replace internal jargon with user language whenever possible:
  • avoid technical/internal terms like payload, trigger, workspace quick action, blocking gap, next move
  • prefer details, start, shortcuts, what is missing, next step
• Buttons and section titles must be understandable without extra context.
• Helper copy should explain why something matters in one short sentence, not describe internal logic.
• If a label sounds like CRM/operator jargon, rewrite it before shipping.

Sizing and Scale Rules

• Size tokens are mandatory for typography and components; avoid ad-hoc one-off values.
• Define and reuse semantic sizes:
  • Typography scale (xs, sm, base, lg, xl, 2xl, ...)
  • Icon sizes (sm, md, lg)
  • Control heights (sm, md, lg) for inputs/buttons/selects
• Keep density consistent per screen:
  • Do not mix compact and spacious controls in the same form section
  • Keep button and input heights aligned in horizontal action groups
• Responsive sizing principle:
  • Mobile defaults first
  • Scale up only when readability and hierarchy need it
  • Prefer token jumps over arbitrary pixel tweaks
• Button density rules:
  • Keep action density consistent across the product: page actions should feel compact and aligned.
  • Default app action sizing:
    • text/button actions: small density (size="sm" equivalent height rhythm)
    • icon-only actions: compact icon button baseline (size="icon" compact)
  • Do not mix oversized and compact action buttons in the same action group.
  • Larger icon buttons are exceptions for touch-critical zones only (mobile fullscreen controls, image/lightbox navigation, public step navigation).
  • Overflow menus must be represented by a compact icon trigger (...) instead of a text button in dense headers.
  • Header/list create actions should consistently use a leading + icon and compact sizing.

Token Source of Truth (Required)

• Design tokens must be defined in a single source:
  • frontend/src/styles/design-tokens.css
• Tailwind must consume these tokens (not duplicate hardcoded values):
  • frontend/tailwind.config.ts
• Global styles should only reference tokens:
  • frontend/src/index.css
• For new visual decisions (color, typography, spacing, radius, shadow), add or update tokens first, then apply them in components.
• Arbitrary sizing values in page code are not allowed by default:
  • Avoid classes like text-[11px], h-[300px], min-h-[400px], w-[200px], sm:max-w-[500px].
  • Use semantic tokens from design-tokens.css through Tailwind utilities/variables instead.
• Typography token usage:
  • text-3xs, text-2xs, text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl, text-4xl.
  • Do not introduce one-off text sizes without adding a token first.

Status Color Harmonization

• Pending/waiting states: warning/orange
• Validated/accepted/completed states: success/green
• Canceled states: secondary/neutral gray (not destructive)
• Refused/rejected/failed/disabled/overdue states: destructive/red
• Apply the same semantic meaning across all domains (quotes, invoices, sessions, tasks, users).

Layout and Spacing

• Build with a predictable spacing scale (e.g., 4/8px rhythm) and stick to it.
• Group related elements by proximity and alignment, not by extra borders.
• Ensure pages scan in this order:
  • Context/header
  • Primary action
  • Core content
  • Secondary controls
• Avoid cramped containers. Prioritize whitespace over adding visual separators.
• Keep line lengths readable in dense forms and content-heavy pages.
• In dense enterprise screens (lists, CRM, session workspace), prefer compact vertical rhythm over oversized headers/paddings.
• List-page bottom spacing must remain proportional; avoid oversized safe-area padding that creates large dead zones.

Information Architecture and De-duplication

• Use one source of truth per information block.
• Do not repeat the same context in header, overview, and right sidebar simultaneously.
• If data already exists in a contextual sidebar, in-tab content should provide action/context links, not duplicate cards.
• Replace duplicated summaries with complementary information (next actions, operational tasks, decision-critical data).
• In overview screens, remove repeated "meta" blocks that restate the hero/session context.

Detail View Workspace Contract

• Detail pages with hero + tabs + content must feel like one workspace, not a card placed inside another card.
• Do not add a large rounded page wrapper with extra padding around the full detail view when hero, navigation, and content cards already provide structure.
• Keep navigation compact:
  • sidebar and top tab menus must use restrained icon sizing,
  • avoid oversized row heights,
  • use short labels when longer labels make the menu visually heavier than sibling workspaces.
• Reuse the same navigation shell across comparable screens:
  • PageBackActionsBar for the top back/actions row
  • WorkspaceTabsNav for compact top or sidebar tab navigation
• Do not introduce a new visual treatment for tabs or back/action rows when the information architecture is the same.
• Stateful detail navigation must be deep-linkable:
  • active tab belongs in the URL/query state,
  • refresh/back-forward should preserve the current tab.
• Tab content should not accumulate top spacing:
  • avoid stacking large TabsContent margins with intro cards and additional section wrappers,
  • first content block should feel attached to the navigation rhythm.
• Hero/header owns primary identity, status, and primary actions.
• Overview content must complement the hero, not restate the same summary, actions, or badges.
• Within contextual detail sidebars (client/contact/session info), avoid double-padding patterns:
  • do not combine generous card shell padding with equally spacious inner sub-cards unless the separation is clearly justified.

Settings Sidebar Contract

• Contextual settings sidebars must feel like secondary workspaces, not raw sheets.
• Use the shared sidebar shell with:
  • restrained header,
  • subtle border,
  • lightly tinted content background,
  • footer actions separated from scrolling content.
• First content block should usually be a compact summary card:
  • what this panel controls,
  • which sections/tabs it contains,
  • avoid repeating the page title verbatim.
• Dense settings should be grouped into calm internal surfaces:
  • rounded panels,
  • soft border/background,
  • no naked switch rows floating directly on the sheet background.
• Footer actions must stay stable and readable:
  • full-width on mobile,
  • aligned right on desktop,
  • same visual contract as dialogs.
• Detail pages that use a settings sidebar should not dump the full settings UI inline in the main content area. Keep the page body focused on overview/context, then open the full settings workspace from a visible trigger.

Page Header Card Contract

• Standard app pages must not start with a naked title/subtitle pair.
• Use a framed page header surface for page context:
  • title,
  • optional subtitle,
  • optional metadata badges,
  • optional actions.
• Reuse the shared PageHeader component for this pattern instead of rebuilding a custom top block.
• The page header card should feel compact and structural:
  • soft border,
  • standard app radius,
  • restrained padding,
  • no decorative gradients.
• Keep the header card separate from the main content card below; do not nest the full page inside another oversized wrapper.
• When a page needs richer top metadata, place it in the header card under the subtitle rather than duplicating context in a second intro card.

Search And Filter Bar Contract

• Search/filter bars are secondary control surfaces, not hero blocks.
• Keep them compact:
  • one calm card shell,
  • low-contrast border,
  • compact control heights,
  • no oversized padding.
• Search input should own the available width first; filter actions should wrap cleanly on smaller screens.
• Clear all must stay visually secondary to search and filter controls.
• Filter popovers must feel editorial and readable:
  • compact section headers,
  • soft row states,
  • restrained active treatment,
  • no harsh boxed checklist feeling.

Session Workspace Layout Contract

• Header must stay compact and premium; avoid oversized hero stacks.
• Session date should be emphasized only when it is the event date; otherwise remove ambiguous date chips.
• Desktop session navigation may be left sticky, but sticky offset must respect top app navigation and never overlap it.
• Right context sidebar should contain stable session context; tabs should focus on domain work and avoid repeating sidebar content.
• Overflow and utility actions in session headers must follow compact action sizing and icon-only overflow rules.

Day Planner Visual Contract

• Wedding day planner uses a vertical time timeline as primary representation.
• Visual hierarchy in planner blocks:
  • time first,
  • title second,
  • location/category as low-emphasis metadata.
• Category/status colors must stay restrained and premium:
  • muted tinted backgrounds,
  • medium-contrast borders,
  • no saturated neon accents.
• Keep scheduler chrome minimal:
  • hide non-essential toolbars,
  • avoid duplicate date context already shown in page header.
• Client planner view must communicate read-only published version clearly; modification path is a proposal CTA, not direct edit controls.

Dashboard Cockpit Contract

• Dashboard is an operating cockpit, not a collection of unrelated cards.
• The reading order must be:
  • quick orientation,
  • immediate actions,
  • cross-domain movement/risk,
  • operational sections,
  • secondary maintenance blocks.
• The top of the dashboard must stay compact:
  • one compact overview block,
  • one primary actions block,
  • one secondary cross-domain block.
• Avoid stacking multiple blocks that all repeat counts and status summaries.
• Actions Now must read as decision support:
  • short action-oriented titles,
  • one clear consequence or summary line,
  • compact CTA,
  • no large decorative empty space.
• Operations must read as daily orchestration:
  • one clear next session focus,
  • one concise requests area,
  • avoid stacking too many equally important sub-blocks,
  • prioritize the items to open now over exhaustive monitoring.
• Cash & Documents must read as commercial follow-through:
  • what is already secured,
  • what still needs conversion,
  • which document flows are blocked,
  • avoid generic finance KPI language when a more actionable wording exists.
• Contacts must stay secondary and CRM-oriented:
  • show recent movement,
  • surface duplicate cleanup only when relevant,
  • avoid turning the contacts block into a second full KPI dashboard.
• Dashboard cockpit copy must stay plain-language and action-oriented:
  • prefer Que traiter aujourd’hui ?, Voir le planning, À relancer, À débloquer
  • avoid raw analytics/admin wording like visible sections, pipeline documents, total requests
  • if a label reads like internal reporting vocabulary, rewrite it in user-facing operational language.
• Conversion Funnel must explain where movement is lost:
  • use plain business language,
  • prefer friction/progression wording over analytics jargon,
  • show one main weak point instead of many competing warnings.
• Overview must remain a lightweight orientation layer:
  • fast signals only,
  • no duplicated cards already explained in lower sections,
  • no oversized KPI dashboard treatment.
• Cross-domain blocks must feel calmer than admin analytics:
  • restrained tinting,
  • minimal shadows,
  • compact vertical rhythm,
  • hierarchy from typography before color.

Lists And Pagination

• On desktop list pages, keep the table header and pagination visible while only the rows area scrolls.
• Pagination belongs to the list footer, separated from rows with a subtle top border.
• Prefer compact, calm pagination controls. Avoid heavy footers or duplicated page-reset logic.
• On mobile, pagination must stack cleanly and remain readable without horizontal compression.

Dialog And Modal Contract

• Shared dialogs must use the common Dialog shell. Do not recreate close buttons, overlays, or footer structure unless the flow truly requires it.
• Dialogs should feel premium and calm:
  • soft overlay,
  • restrained border,
  • compact but breathable spacing,
  • no harsh shadow stacks or oversized empty zones.
• Keep dialog headers concise:
  • clear title,
  • short supporting copy,
  • avoid repeating the same context inside the body.
• Footer actions belong behind a subtle separator and should stack cleanly on mobile.
• Form modals should use a stable top bar and a scrollable body, not multiple nested card shells.
• Import, export, and selection dialogs should group dense inputs into 1-3 calm internal panels:
  • rounded surfaces with restrained border/background,
  • no raw checkbox rows or bare result blocks,
  • file summaries and contextual hints should read as designed surfaces, not utility leftovers.
• Calendar and booking dialogs should follow the same rhythm:
  • detail sections in calm panels,
  • action rows stacked cleanly on mobile,
  • edit states should not collapse into a single undifferentiated form wall.

UX and Interaction

• Prioritize clarity over novelty for core user paths.
• Primary actions must be obvious at first glance and stable across breakpoints.
• Do not hide critical actions behind hover-only interactions.
• Every state must be designed:
  • Loading
  • Empty
  • Error
  • Success/confirmation
• Forms must provide:
  • Clear labels (not placeholder-only)
  • Inline validation feedback
  • Predictable submit/cancel behavior
• Use progressive disclosure for advanced settings; keep default flows simple.

Motion and Feedback

• Motion should explain state change, not decorate.
• Use short, subtle transitions for UI continuity (150-250ms baseline).
• Avoid excessive motion on frequently repeated interactions.
• Respect reduced motion preferences (prefers-reduced-motion).
• Provide immediate interaction feedback for click/tap, async actions, and completion states.

Accessibility Baseline (Required)

• WCAG AA contrast minimum for text and key UI controls.
• Full keyboard navigation for actionable elements and dialogs.
• Visible focus states; never remove focus indicators without replacement.
• Semantic structure:
  • Landmarks (header, main, nav, footer)
  • Proper heading levels
  • Correct button vs link semantics
• All icon-only buttons require accessible names (aria-label or visible text).
• Screen-reader friendly status messages for async results and validation errors.

Responsive and Device Quality

• Design mobile-first, then enhance at larger breakpoints.
• Ensure touch targets are at least 44x44px.
• On mobile, critical actions should remain reachable without precision gestures.
• Avoid fixed pixel widths for core layout containers and dialogs.
• Validate behavior on:
  • Small mobile viewport
  • Tablet viewport
  • Standard desktop viewport

Definition of Done for UI Work

A UI task is complete only if all points below are true:

1. Visual hierarchy is clear and consistent with existing product language.
2. Typography follows the shared scale and font usage rules.
3. All major UX states are implemented (loading/empty/error/success).
4. Keyboard navigation and focus visibility are working.
5. Mobile and desktop behavior are both verified.
6. No obvious contrast or readability regressions are introduced.