BionicLoop Design Language + Palette System

Version: 0.1 (implementation-first)

This document defines design language, color palettes (light/dark), semantic color tokens, and usage rules intended for direct implementation in iOS (SwiftUI/UIKit) and Android (Compose/View).

Primary goal: instrument-panel calm with strict separation between brand/interaction color and safety colors (red/amber/green) used for alarms and plots.

Design language

Principles

Instrument panel, not a social app: data-forward, calm, restrained.
Neutrals do the talking: backgrounds, surfaces, typography are neutral; color is used sparingly.
Safety colors are reserved: red/amber/green are never decorative.
Single accent: one cool brand accent for interaction and selected state only.
Glanceability > density: key values readable at arm’s length; details on tap.

Visual treatment

Surfaces: flat + subtle elevation. Avoid gradients doing emotional work.
Corners: consistent radius across cards and controls (see Tokens).
Shadows: minimal; light mode gets subtle shadows, dark mode prefers borders/inner highlights.
Motion: small, predictable, short. Prefer crossfade/slide-in to bounce.

Iconography

Use simple outline glyphs (SF Symbols / Material Symbols) with consistent stroke weight.
Home CTA (meal): prefer plate + fork (neutral, event-based), not medical or math icons.

Color system overview

Token groups

Neutrals — background, surfaces, text, dividers, gridlines.
Accent — brand/interaction: CTA, selection, focus rings, links.
Safety — alarms and plot zones only: critical red, caution amber, safe green.
Data — plot series colors (CGM, insulin, predictions). Keep minimal.

Hard rules

✅ Accent must not be red/green/amber.
✅ Safety colors must not be used for general UI chrome (tabs, buttons, highlights).
✅ When safety colors appear, pair with icon + label; do not rely on color alone.

Palette: Dark mode (primary)

Designed for OLED comfort, high legibility, low glare.

dark:
  bg:              "#0B0C0E"  # app background
  surface:         "#15171A"  # cards/panels
  surfaceRaised:   "#1C1F24"  # elevated cards/controls
  surfaceOverlay:  "#111316"  # sheets/overlays base
  divider:         "#262A30"
  grid:            "#262A30"  # same as divider; reduce opacity in charts
  textPrimary:     "#F2F4F7"
  textSecondary:   "#9AA1AB"
  textTertiary:    "#6E7580"
  icon:            "#E6EAF0"  # default icon color (use secondary for inactive)
  disabled:        "#3A3F47"

Palette: Light mode (clinical, not bubbly)

Clean paper-like neutrals that don’t compete with alerts.

light:
  bg:              "#F7F9FC"
  surface:         "#FFFFFF"
  surfaceRaised:   "#EEF2F7"
  surfaceOverlay:  "#FFFFFF"
  divider:         "#D7DCE4"
  grid:            "#D7DCE4"
  textPrimary:     "#111418"
  textSecondary:   "#5B6470"
  textTertiary:    "#8A92A0"
  icon:            "#1B1F24"
  disabled:        "#C7CDD6"

Accent (brand/interaction)

Single cool accent used for interaction states and emphasis not tied to safety.

accent:
  primary:     "#4DA3FF"
  muted:       "#2F6FB3"
  subtleFill:  "#1C2C3D"  # dark-mode subtle selection fill
  subtleFillLight: "#E7F1FF"  # light-mode subtle selection fill

Usage - Primary buttons, selected tabs, toggles, links, focus rings. - Non-critical informational badges (e.g., “Meal support active”) only if not safety-related.

Safety colors (alarms + plot zones ONLY)

These tokens must be consistent and predictable across the product.

safety:
  criticalRed:
    primary:    "#D92D20"
    muted:      "#8B1D18"
    subtleFill: "#2A1414"
  cautionAmber:
    primary:    "#F7B500"
    muted:      "#A77A00"
    subtleFill: "#2A2414"
  safeGreen:
    primary:    "#1E9E62"
    muted:      "#146C44"
    subtleFill: "#14251D"

Rules - Solid primary = immediate attention/action. - Muted = historical/acknowledged/non-urgent context. - SubtleFill = background tint behind a localized card/banner (never full-screen unless emergency).

Accessibility - Always pair alarms with: - icon (e.g., triangle/exclamation) - label text (“Low glucose”, “High glucose”, “Pod error”) - optional action button

Data visualization tokens

Keep plots readable and calm; safety colors only for zones/threshold crossings.

dataViz:
  cgmLineDark:        "#E6EAF0"
  cgmLineLight:       "#1B1F24"
  cgmDotsDark:        "#F2F4F7"
  cgmDotsLight:       "#111418"
  insulinBarsDark:    "#5FA8FF"
  insulinBarsLight:   "#2F6FB3"
  predictionLine:     "#9AA1AB"   # secondary neutral

Chart rules - CGM series is primary; insulin is secondary: - insulin bars at lower opacity than CGM line/dots - Gridlines use grid at ~25–35% opacity. - If showing safety zones: - use safety.*.subtleFill at low opacity (8–14%) behind chart area.

Typography + hierarchy

Type roles

Value (CGM number): Semibold, largest on screen, high contrast.
Units + metadata: Secondary text, smaller, never compete with value.
State labels: Medium/Regular, smaller than value, short phrases.

Don’ts

Don’t bold and color safety text simultaneously—choose one.
Don’t use all-caps for alarms (reads as shouting).

Component styling tokens

These are implementation-oriented defaults.

components:
  radius:
    card: 16
    control: 14
    pill: 999
  spacing:
    xs: 4
    sm: 8
    md: 12
    lg: 16
    xl: 24
  stroke:
    hairline: 1
    thick: 2
  elevation:
    lightShadowOpacity: 0.10  # light mode only

Button system

Primary CTA (e.g., “I’m eating”)

Dark mode: accent fill + neutral text
Light mode: accent fill + white text
Optional leading icon (plate + fork)

Safety actions

If a button resolves an alarm:
use safety.criticalRed.primary for critical,
safety.cautionAmber.primary for warnings,
never use safety colors for routine CTAs.

Status strip (glanceable top row)

Recommended items: - CGM value + trend arrow (primary) - Insulin delivery state (neutral/accent) - Algorithm state (neutral/accent) - Alarm indicator (safety color only when active)

Color rules - Normal state labels use textSecondary. - Active but non-alarm states may use accent.muted. - Alarm badges use safety colors.

Implementation notes (Codex-friendly)

Suggested token naming

Prefer a stable “design token” naming scheme that maps to iOS/Android easily:

color.bg
color.surface
color.text.primary
color.accent.primary
color.safety.critical.primary
color.viz.cgmLine

Opacity guidance

Where a token is used with opacity (e.g., gridlines, subtle fills), do not invent new hexes—apply alpha in code: - gridlines: 0.25–0.35 - subtle zone fills: 0.08–0.14 - disabled: 0.45–0.60 on text/icons depending on background

Dark mode shadow

Prefer borders/inner highlights over drop shadows: - 1px stroke using divider at ~40% opacity on raised surfaces.

Quick checklist

[ ] Only one non-safety accent across app chrome
[ ] Red/amber/green reserved for alarms/plot zones
[ ] CGM is visually dominant over insulin bars
[ ] All alarm states have icon + label + action (not color-only)
[ ] Light mode remains clinical/neutral (no “wellness” pastels)