aiturk-mobil/DESIGN.md

version, name, description, omitted, colors, typography, rounded, spacing, components

version	name	description	omitted	colors	typography	rounded	spacing	components
alpha	Hermes Mobile Design System	High-density, minimal Material 3 interface for the Hermes Agent Android client		bg-root bg-surface bg-surface-container-lowest bg-surface-container-low bg-surface-container bg-surface-container-high bg-surface-container-highest bg-surface-variant text-primary text-secondary text-muted text-on-primary text-on-secondary text-on-tertiary text-outline primary primary-container on-primary-container secondary secondary-container on-secondary-container tertiary tertiary-container on-tertiary-container status-success status-success-container status-on-success status-warning status-warning-container status-on-warning status-error status-error-container status-on-error status-on-error-container status-info status-info-container status-on-info terminal-bg terminal-border terminal-text terminal-muted code-keyword code-string code-comment code-number diff-add-bg diff-add-text diff-delete-bg diff-delete-text #0F1416 #0F1416 #0F1416 #171C1E #1B2022 #252B2D #303638 #171C1E #DEE3E5 #CEE7EC #BEC8CA #0F1416 #0F1416 #0F1416 #889294 #80D5D2 #303638 #DEE3E5 #B2CBD0 #252B2D #CEE7EC #A3C9EC #303638 #DEE3E5 #81D692 #252B2D #0F1416 #ECC248 #252B2D #0F1416 #FFB4AB #252B2D #0F1416 #FFB4AB #8ECEFF #252B2D #0F1416 #1E1E1E #333333 #D4D4D4 #808080 #569CD6 #CE9178 #6A9955 #B5CEA8 rgba(61, 220, 132, 0.15) #3DDC84 rgba(255, 92, 92, 0.15) #FF5C5C	font-sans font-mono display-large display-medium display-small headline-large headline-medium headline-small title-large title-medium title-small body-large body-medium body-small label-large label-medium label-small Roboto, 'Segoe UI', system-ui, sans-serif 'JetBrains Mono', 'Roboto Mono', monospace fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 44px 700 52px -0.5px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 36px 700 44px -0.25px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 30px 600 38px 0px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 28px 600 34px 0px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 24px 600 30px 0px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 20px 600 26px 0.1px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 20px 600 26px 0.1px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 16px 500 22px 0.15px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 14px 500 20px 0.1px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 16px 400 24px 0.25px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 14px 400 20px 0.25px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 12px 400 16px 0.4px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 14px 500 20px 0.1px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 12px 500 16px 0.5px fontFamily fontSize fontWeight lineHeight letterSpacing {typography.font-sans} 11px 500 16px 0.5px	none extra-small small medium large extra-large full 0dp 4dp 8dp 12dp 16dp 28dp 9999dp	xs sm md lg xl xxl 2dp 6dp 12dp 18dp 24dp 36dp	top-app-bar chat-user-bubble chat-assistant-bubble tool-chip code-card backgroundColor textColor height {colors.bg-surface} {colors.text-primary} 56dp backgroundColor textColor rounded padding {colors.primary} {colors.text-on-primary} {rounded.medium} 10dp 14dp backgroundColor textColor rounded padding {colors.bg-surface-container} {colors.text-primary} {rounded.medium} 10dp 14dp backgroundColor textColor rounded padding {colors.bg-surface-container-high} {colors.text-primary} {rounded.full} 4dp 10dp backgroundColor textColor rounded padding {colors.terminal-bg} {colors.terminal-text} {rounded.small} 8dp 12dp

Overview

Hermes Mobile (com.m57.hermescontrol) is a high-density, keyboard-first, distraction-free Android client for the Hermes Agent platform. The UI philosophy prioritizes information density, low battery drain (OLED-friendly), and instantaneous feedback over decorative visual noise.

The visual language follows Material 3 guidelines strictly adapted for developer utilities:

• Tone: Technical, focused, utilitarian, crisp.
• Form Factors: Native Android phones, foldables, and tablets via adaptive Navigation 3 layouts.
• Core Principle: Zero fluff. Fast render cycles, explicit states, flat surfaces, and zero visual ambiguity.

Colors

The app supports 6 dynamic presets managed by PaletteTemplate.kt (Default/Slate, Monochrome, Gruvbox, Catppuccin, AMOLED, Nord), plus dynamic Android 12+ wallpaper theming:

1. Surfaces:
   • bg-root: Deep canvas background (#0F1416 in Default Dark, #000000 in AMOLED).
   • bg-surface: Top app bars, bottom sheets, navigation drawer background.
   • bg-surface-container: Assistant message bubbles, session list cards, settings group panels (#1B2022).
   • bg-surface-container-high: Dialogs, interactive chips, elevated tool surfaces (#252B2D).
   • bg-surface-container-highest: Selected containers and active pills (#303638).
2. Accents & Tints:
   • Primary accent (#80D5D2 Slate Bright Teal) is reserved for interactive controls, user bubbles, selected drawer icons, and active tabs.
   • Selected navigation drawer items MUST tint icons directly to primary to prevent low-contrast grey-on-grey visual loss.
3. Semantic Status Colors (HermesStatusColors):
   • Status indicators (success, warning, error, info) must always satisfy a minimum 3:1 contrast ratio against their respective container backgrounds (onErrorContainer on errorContainer).
   • Every theme preset must explicitly define onErrorContainer (#FFB4AB in Default Dark) to prevent invisible text bugs.

Typography

• UI Fonts: System Roboto / sans-serif with strict semantic scaling to prevent layout shifts.
• Code & Logs: Tabular JetBrains Mono for terminal traces, tool payloads, JSON viewers, and memory tokens.
• Scale Discipline (Type.kt):
  • Screen titles: 20sp (title-large) with 0.1sp tracking.
  • Card headings: 16sp (title-medium) with 0.15sp tracking.
  • Chat content: 16sp (body-large) with 24sp line-height for readability.
  • Metadata & Subtitles: 14sp (body-medium) or 12sp (body-small / label-medium).
  • Hero stats & Display numbers: 44sp (display-large) down to 30sp (display-small).

Layout

• Scaffolding (HermesScaffold):
  • Global TopAppBar containing screen title, connection indicator, profile switch dropdown, and quick action icon buttons.
  • No Floating Action Buttons (FABs): Primary triggers live in the top-bar actions or fixed bottom composer docks.
  • Scaffold Padding Foot-Gun Rule: Content lambdas must NEVER apply Modifier.padding(paddingValues) on root children — the scaffold's internal Box already handles top-bar offsets.
• Spacing Scale (Spacing.kt):
  • xs: 2dp: Hairline gaps, micro dividers.
  • sm: 6dp: Default inner padding, icon-to-text gap.
  • md: 12dp: Card content, screen edge, section gaps.
  • lg: 18dp: Hero spacing, between major sections.
  • xl: 24dp: Full-feature spacing, large section break.
  • xxl: 36dp: Maximum outer margin.
• Controls & Navigation:
  • Horizontal chip bars must be single-row with horizontalScroll(). Never stack chips vertically into multi-row wraps.
  • Dropdown pickers take precedence over cycle buttons to ensure all options are discoverable in one tap.

Elevation & Depth

• Elevation Language: Surface luminance layering (surfaceContainer tiers) and 1px borders (outline / outlineVariant) replace heavy drop shadows.
• Flat Surface Rule:
  • Chat background is flat colorScheme.background.
  • User message bubbles use solid colorScheme.primary (no multi-color gradients).
  • Shimmer effects (StateViews.kt) are used strictly as animated loading states, never as static background decorations.

Shapes

• Corner Radii Hierarchy (Shapes.kt):
  • 0dp (rounded.none): Terminal panels, full-bleed code blocks.
  • 4dp (rounded.extra-small): Chips, badges, inline toggles.
  • 8dp (rounded.small): Text fields, small cards, code cards.
  • 12dp (rounded.medium): Standard cards, list rows, message bubbles, dialogs.
  • 16dp (rounded.large): Large cards, bottom sheets.
  • 28dp (rounded.extra-large): Feature cards, full-bleed surfaces.
  • 9999dp (rounded.full): Interactive filter chips, timeline markers, circular icon buttons.

Components

• Top App Bar: Flat surface, 56dp height, contains title marquee, WS connection status pill, and action buttons.
• Chat Timeline:
  • User Bubbles: Right-aligned, solid primary fill, high-contrast text (onPrimary).
  • Assistant Bubbles: Left-aligned, surfaceContainer fill (#1B2022), full Markdown renderer support.
  • Tool Bubbles: Expandable rows with tool vector icon, execution state indicator, parameter summary, and full payload bottom sheet.
• Action & Filter Chips:
  • Must represent real system state (e.g., active model, selected profile, filter criteria).
  • Active chips: primaryContainer fill with onPrimaryContainer text/icon.
  • Inactive chips: surfaceContainerHigh fill with text-secondary text.
  • Disabled controls: Visually greyed out with alpha = 0.38f.
• Dialogs & Bottom Sheets:
  • Standard CRUD flows must provide all 4 operations (Create, Read, Update, Delete) with confirmation gates for destructive actions.
  • Every managed resource must have a discoverable navigation surface in the UI.

Do's and Don'ts

Do's

• DO use official androidx.compose.material.icons vectors for every UI element and status indicator.
• DO use Icons.AutoMirrored.Filled.* for directional icons (ArrowBack, Send, VolumeUp, MenuBook).
• DO maintain \ge 4.5:1 text contrast and \ge 3:1 container contrast across all 6 presets.
• DO use Android string <plurals> for count labels (1 agent vs 2 agents).
• DO grey out disabled controls (enabled = false) visibly.
• DO ensure every created resource has a discoverable UI list or navigation tab.

Don'ts

• DON'T render emoji glyphs (✅, ❌, ⭕, 🔄, ⚡, 🛠, 📄) in the app UI — replace them with real vector icons.
• DON'T use Floating Action Buttons (FABs); anchor actions in top bars or fixed docks.
• DON'T apply Modifier.padding(paddingValues) inside HermesScaffold content lambdas.
• DON'T use gradient backgrounds on chat surfaces or message bubbles.
• DON'T create multi-layer nested cards or unnecessary decorative borders.
• DON'T use cycle buttons where a dropdown menu provides immediate option visibility.