Skip to content

DESIGN.md

Latest commit

 

History

History
39 lines (21 loc) · 2.47 KB

DESIGN.md

File metadata and controls

39 lines (21 loc) · 2.47 KB
Raw

Design notes

This document records the reasoning behind specific decisions so future changes stay consistent with intent rather than drifting.

1. Two-token motion system

Material 3 Expressive separates motion into spatial tokens (position, size, corner radius, rotation) and effect tokens (color, opacity). A single bouncy curve applied to color transitions can look like a rendering glitch rather than deliberate motion.

  • SpringBehavior is used for spatial changes. Overshoot is permitted. The overshoot is pulled back to 1.0 from the raw Easing.OutBack default of 1.70158, as full-strength overshoot reads as jittery at widget scale.
  • EffectBehavior is used for color and opacity changes. It is critically damped with no overshoot and uses Easing.OutCubic for a slightly faster settling time, since color transitions do not benefit from the extra beat a bounce silhouette provides.

Rule: if the property is spatial, it may overshoot. If it is a color or opacity, it never does.

2. Hairline borders instead of soft shadows

Thin (0.5-1px) borders are used over elevation shadows for depth and separation. This matches the direction of modern desktop and web UI frameworks.

  • TonalSurface default border is a hairline at low opacity, not an alpha composited glow-style border.
  • Analog face outer stroke is 1.5px hairline, not a thicker tinted outline.

3. Single restrained accent

Two-tone stacking where hours and minutes each carry a saturated color competes for attention. One accent, used deliberately and sparingly, lets neutral on-surface tones carry most of the UI.

In StackedDigitalClock, hours render in onSurface and only minutes carry the accent tint. This is the only place a non-neutral color appears by default.

4. Tabular numerals and tight tracking

Every digit-bearing Text element sets font.features: { "tnum": 1 }. Proportional digits change width as they change value, causing visible jitter. Tabular numerals eliminate this by giving each digit the same advance width.

Hero digits use tight negative letter spacing (approximately -2% of font pixel size).

5. Spacing rhythm

Gaps and padding follow an 8pt-multiple grid (4, 8, 12, 16, 24), consistent with Apple HIG and Material spacing scales. Deviations should be commented with a reason.

6. Accent-fill pills have no hairline border

A hairline border on top of a saturated fill reads as muddy. Accent-tone pills in PillDigitalClock use solid tonal fill with no border. This is intentional, not an oversight.