GroundedHelper/frontend/design.md

Grounded — Design Language

Reference: an airy fitness-app look. Sage mist drifting into cream behind everything (AmbientBackground), frosted glass for controls and floating chrome (GlassSurface, glassCircle), ink type with a soft grey second tone, painted landscapes instead of photography (SceneArt), a floating glass tab bar with a dark square action button (FloatingNav), and one lime spark on night-green for the primary control.

Building blocks (designs/)

Piece	Use
AmbientBackground	The backdrop for every light screen.
GlassSurface / glassCircle	Frosted panels and square controls; onDark over a scene or tinted stage.
SceneArt	Painted sky, sun and ridges with an optional figure glyph. Palettes come from scenePalette(kind), goalScene(accent), classScene(class); seed with sceneSeed(title) so an item always wears the same picture.
DotDigits	The dotted clock in the routine player.
FloatingNav	Home's tab bar; the selected tab is a filled night block. The side action button is optional.
GroundedMark	The logo, drawn — a lime sun on a ground line under two arcs. The launcher PNGs in assets/icons/ were rendered from the same geometry.

Cards are image-led where an item has a kind (routines, goals, tasks): scene on top or as a thumbnail, white type over the shaded lower half, three light numbers along the bottom. Greetings are two-tone: Medium ink, then Regular colorInkSoft. Primary buttons are square night bars with a lime icon.

Sheet is light (ambient) by default; passing chrome, banner or scene gives a tinted stage with white type. Home, Routines and the player build their own layouts from the same pieces.

The sections below describe the original record-style type scale, which still applies to labels and metrics.

Type — Inter

TextType.Light is Inter Display Regular (the display cut, for titles and big numbers); Regular, Medium and Bold are Inter Regular, Medium and SemiBold.

Role	Family	Size	Use
Display	TextType.Light	30–44	Screen titles. Always light, never bold.
Title	TextType.Bold	17–20	Card and section titles.
Body	TextType.Regular	13–14, height: 1.5	Descriptions, copy.
Label	TextType.Bold	10–11, letterSpacing: 0.8–1.2, uppercase, colorGrey2	Metadata above a value.
Metric	TextType.Bold	24–34	Debt score, counts.

The label/value pair is the core unit: a tiny grey all-caps label sitting directly above a large dark value. Used everywhere numbers appear.

Geometry

• Softly rounded, never pill-soft: large cards and image cards 16, buttons 14, rows, tiles and fields 12, small controls 10, chips and badges 8, bars 4. Sheets round their top at 20.
• Portraits, the nav buttons, status dots, rings and the breathing circle are full circles.
• Screen padding 20 horizontal. Card padding 16. Section gap 28.
• Hairlines at colorDivider (black 7%), borders at colorBorder (black 8%).
• One soft shadow only: 0 4 18 rgba(0,0,0,0.03). No coloured glows.

Colour

After the coach reference: near-black ink and buttons (colorInk, colorNight #1C1C1C) on a neutral light grey ground (colorAmbient* around #EAEAEA), frosted near-white cards (colorGlassStrong) with white edges, and one warm orange accent (colorAccent #EC6A36, soft colorAccentSoft). colorLime is that orange too: the spark on dark buttons. Enforcement tiers keep their own colours, so standing still reads at a glance:

Standing	Colour
Good	green #2F6F4E
Warned	amber #C98A04
Grounded	rust #B5442F
Lockdown	oxblood #7A1F14

The tier colour is used consistently — header, chip, meter, queue accent — so the standing is legible without reading the word.

Navigation

The nav is a floating cluster of round frosted buttons, icons only; the open tab is a raised white disc. It switches tabs inside Home (Today, Routines, Goals, Groups, Progress) in place: nothing is pushed, a tab has no back arrow (tab: true), and Android back returns to Today. Tabs are built on first open and then kept.

Structure

Every screen is: black headerBar (back, title, action) → white sheet with a square top edge → sectionHeader (label + light display title) → content.

Rules

• Display titles are Light. Bold is for labels and metrics only.
• Numbers get a label above them, never beside them.
• Chips carry state, never actions.
• One primary button per screen; everything else is outlined or text.
• Empty states are plain. An empty overdue queue is good news, not a party.

Home

Home opens on a light header panel (colorHeaderTop → colorHeaderBottom, text colorHeaderText): greeting and avatar, a Today / Weekly toggle, a seven-day streak panel ending today (a leaf on every kept day, kept = 80%+), then the numbers. Today shows minutes held against planned, a ring with + that opens the "Add to today" sheet, the plan as thumbnails, the report-card letter as the Score, and one bar per commitment class. Weekly swaps in the week's average, a bar per day and the class completion rates. Below the block, on the light ambient surface: the rest of the day. Bars on the dark block use the colorBar* tokens.

Groups

see/group/: people keeping each other honest. A group has members, shared goals and a chat.

• Shared goals are split into objectives with a number and a unit (200 km, 40 runs, 30,000 words). Every member logs toward them; the card shows the group total, your share and a night Log button. Like personal goals, they carry no debt.
• Leaderboard ranks members by kept rate over the last 7 days, with streak, last check-in (red "quiet" after 24h) and a nudge button.
• Chat keeps the work and the talk together: plain messages are square bubbles (yours in night, others white with the author's colour), while check-ins (green bar) and nudges (amber bar) are cards in the thread. The open chat polls every 4 seconds.
• Members are drawn by memberAvatar / avatarStack (designs/MemberAvatar.dart): square painted portraits with the initial.
• Groups are reached from the nav (Groups tab), the Home "Your groups" rail (tap opens the chat) and the add sheet.

Progress

see/progress/: progress over time, reached from the nav (Progress tab).

• A Day / Week / Month switch over one white card: routines held against the target, a change chip measured against the same point of the previous period, and bars (days of the week, weeks of the month) with the current one in night and future ones as stubs. Day shows a meter instead.
• Two tiles below: active time against its target, and the daily streak.
• Runs come from the device's run log (RoutineRunRecord), written when the routine runner logs. Targets are local (ProgressTargets).
• Targets (TargetSetup) is the only setup screen: routines per week, active minutes per week and reminders before scheduled routines. Until it is saved once, Progress measures against the schedule and shows a night "Set your weekly target" prompt. Targets never touch debt.

Coach

see/coach/: the centre tab. Questions about your own data, answered by CoachEngine from the run log, routines, today's plan, the overdue queue and the debt score. There is no model and no guessing: six question kinds (keeping routines, where you slip, streak, what's left today, active time, debt), matched by keyword; anything else gets the list. An answer is a frosted card with bold figures (markedText), an optional bar chart (solid accent where the target was met, soft accent where short, a dashed outline for the target, a callout over the standout bar) and buttons that do something real: start a routine, open overdue, targets or progress, or ask the follow-up. Messages fade and rise in; bars grow.