# Product Visual Design System

This document defines shared visual standards for the Flutter application. Platform-specific interaction, capability, packaging, and release requirements belong in [`platform-rules/README.md`](platform-rules/README.md).

## Design principles

- Prefer semantic design tokens over raw color, spacing, or dimension values.
- Keep the interface neutral, restrained, and consistent across platforms.
- Adapt layout and interaction to the available space without creating unrelated visual systems.
- Preserve accessibility, text scaling, keyboard access, and visible focus states.
- Use Forui components as the foundation and add product wrappers only when they provide stable application-wide behavior.

## Semantic color roles

Define light and dark values for these roles rather than using colors directly in feature widgets:

- `background`
- `surface`
- `surfaceElevated`
- `textPrimary`
- `textSecondary`
- `border`
- `primary`
- `primaryForeground`
- `success`
- `warning`
- `danger`
- `focus`

Starting palette values:

| Role | Value | Use |
| --- | --- | --- |
| Primary | `#2563EB` | Actions, links, and selection |
| Light background | `#F8FAFC` | Light-mode page canvas |
| Dark surface | `#111827` | Dark-mode panels |
| Light border | `#E2E8F0` | Light-mode separators |

These values are starting points. Forui theme colors and component styles remain the source of truth for Forui widgets.

## Spacing, dimensions, and shape

Use a 4 logical px base grid:

| Token | Value |
| --- | ---: |
| `space1` | 4 |
| `space2` | 8 |
| `space3` | 12 |
| `space4` | 16 |
| `space6` | 24 |
| `space8` | 32 |
| `space12` | 48 |
| Small radius | 6 |
| Standard radius | 10 |
| Large radius | 14 |
| Standard border | 1 |
| Standard icon | 20 |
| Compact control height | 36 |
| Standard control height | 40 |
| Comfortable control height | 44–48 |
| Minimum touch target | 48 |
| Maximum reading width | 800 |

Do not use fixed-height text containers that clip enlarged system text. Use content constraints and intrinsic sizing where text may wrap or scale.

## Typography

- Use a consistent system sans-serif font for UI text.
- Start body text at 14–16 logical px.
- Do not reduce secondary text below comfortable readability to fit more information.
- Use weight and spacing for hierarchy before adding more colors.
- Give editor text a separate configurable reading scale.
- Use monospace styling for code where appropriate.
- Test all important screens with enlarged system text and browser zoom.

## Responsive visual policy

Use centralized layout classes based on `LayoutBuilder` constraints:

| Layout class | Width | Visual policy |
| --- | --- | --- |
| Compact | `< 600` | One main pane and compact app bar or bottom navigation |
| Medium | `600–839` | Navigation rail or drawer with optional secondary pane |
| Expanded | `840–1199` | Persistent sidebar and main content |
| Wide | `1200+` | Sidebar, main content, and optional secondary panel |

These classes describe shared layout behavior. Navigation input, system gestures, URLs, file access, and window behavior are defined by each platform rule document.

## Component standards

| Component | Required behavior |
| --- | --- |
| `AppButton` | Primary, secondary, outline, ghost, and destructive variants |
| `AppIconButton` | Consistent sizing, tooltip, focus, and accessibility label |
| `AppTextField` | Label, helper text, validation, disabled, and error states |
| `AppSearchField` | Search input, clear action, loading, and empty states |
| `AppDialog` | Confirmation and form dialogs with keyboard dismissal rules |
| `AppSheet` | Mobile-friendly secondary actions and forms |
| `AppToast` | Brief success and non-blocking feedback |
| `AppEmptyState` | Human-readable message and optional next action |
| `AppErrorState` | Recoverable error message and retry action |
| `AppLoadingState` | Loading indicator and optional supporting text |
| `AppPageHeader` | Title, description, actions, and breadcrumbs when relevant |
| `AppSidebar` | Selected state, collapse behavior, and accessible navigation labels |
| `AppResponsiveContainer` | Content width and horizontal padding |
| `AppSplitView` | Main content and secondary panel on larger windows |
| `AppStatusBadge` | Semantic status labels, not decorative colors |

Every interactive component must define disabled, focus, hover where relevant, loading, and accessibility behavior. Every asynchronous feature must define loading, success, empty, and error states.

## Accessibility baseline

- Provide accessible names for all interactive controls.
- Maintain visible focus indicators for keyboard users.
- Ensure color is not the only way to communicate status.
- Support system text scaling without clipping or loss of actions.
- Keep touch targets at least 48 logical px where practical.
- Test contrast, keyboard navigation, screen-reader labels, and reduced-motion preferences where supported.