Design contract
One design language across every app, built-in or external. The whole contract is a plain stylesheet of CSS custom properties — /mosaic.css (v0.1.0) — plus the conventions below. Link it, or copy it into your app and override --color-accent only.
Principles
- iOS-native neutrals, dark by default. The ramp flips to light with
prefers-color-scheme, and honors a manual override on<html data-theme="light|dark">. - Accent-only app identity. Your app differs by one accent color; every neutral comes from the shared ramp.
- Flat & flush top-level views. Section hairlines run edge to edge; text keeps the gutter. Cards are for nested content.
- No trademarked glyphs. Monochrome line icons that catch an app's essence.
- One basemap. Tiled maps use CARTO no-labels dark/light — scheme-aware, honoring the manual theme override. Polyline weights: 2 in thumbnails, 4 on detail maps; route color is the app accent.
Tokens
| Token | Role |
|---|---|
--color-bg / -surface / -surface-2 | background ramp |
--color-border | hairlines |
--color-fg / -muted | text ramp |
--color-accent | your app's one identity color |
--radius-ctl / -card / -sheet | 8 / 12 / 16px radii; pills are full |
--row-h | the one list-row height (56px) |
--nav-h / --mini-player-h | chrome heights, override only if yours differ |
Type ramp
| Role | Spec |
|---|---|
| page/section label | 10px, light, uppercase, 0.25em tracking, muted |
| hero number | ~36px thin, tabular numerals |
| row primary | 14px |
| row secondary / meta | 12px, muted |
Safe areas
Backgrounds bleed to the physical screen edges; interactive elements stay out of the notch and home-indicator bands. .safe-top and .safe-bottom helpers are included in the stylesheet.
Theme sync
Mosaic persists the user's appearance choice in localStorage (mosaic.style.theme) and reflects it as data-theme on <html>. Cross-origin apps can't read that key — follow prefers-color-scheme and you'll match the system default; optionally offer the same manual override yourself.