Aller au contenu principal

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.

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.

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.

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.