Skip to content

DESIGN.md

Latest commit

 

History

History
215 lines (201 loc) · 6.22 KB

DESIGN.md

File metadata and controls

215 lines (201 loc) · 6.22 KB
Raw
version alpha
name marimo
description Design system for marimo, a reactive Python notebook for reproducible, git-friendly, deployable work.
colors
background background-dark foreground foreground-dark surface-muted surface-muted-dark muted-foreground muted-foreground-dark popover popover-dark popover-foreground popover-foreground-dark card card-dark card-foreground card-foreground-dark border border-dark input input-dark primary primary-dark on-primary on-primary-dark secondary secondary-dark on-secondary on-secondary-dark accent accent-dark on-accent on-accent-dark ring destructive on-destructive error on-error success on-success action action-hover on-action link link-dark link-visited link-visited-dark stale stale-dark code-background code-background-dark surface surface-dark code-foreground code-foreground-dark data-grid-accent
#FFFFFF
#181C1A
#0F172A
#ECEEED
#F1F5F9
#020303
#64748B
#AAB2AF
#FFFFFF
#252927
#0F172A
#AAB2AF
#FFFFFF
#252927
#0F172A
#C0C6C3
#E2E8F0
#3B403E
#A3A3A3
#474C4A
#0880EA
#28879F
#F8FAFC
#B6ECF7
#F1F5F9
#ECEEED
#0F172A
#252927
#EDF6FF
#1D5B6A
#0B68CB
#B6ECF7
#94A3B8
#FF6666
#F8FAFC
#EA5D5D
#F8FAFC
#66FF7F
#F8FAFC
#FEF2A5
#FFF8BB
#946800
#0B68CB
#479BF5
#8E4EC6
#BF9BDF
#EBE2CC
#3E3720
#FFFFFF
#282C34
#FFFFFF
#252927
#000000
#ABB2BF
#7C3AED
typography
body-md body-sm label-md label-xs markdown-heading code-editor slide-h1
fontFamily fontSize fontWeight lineHeight letterSpacing
PT Sans
1rem
400
1.75rem
0em
fontFamily fontSize fontWeight lineHeight letterSpacing
PT Sans
0.875rem
400
1.25rem
0em
fontFamily fontSize fontWeight lineHeight letterSpacing
PT Sans
0.875rem
500
1.25rem
0em
fontFamily fontSize fontWeight lineHeight letterSpacing
PT Sans
0.75rem
600
1rem
0em
fontFamily fontSize fontWeight lineHeight letterSpacing
Lora
1.875rem
600
2.25rem
-0.025em
fontFamily fontSize fontWeight lineHeight letterSpacing
Fira Mono
14px
400
1.25rem
0em
fontFamily fontSize fontWeight lineHeight letterSpacing
PT Sans
4.375rem
600
1.2
0em
rounded
sm DEFAULT md lg cell xl full
4px
8px
6px
8px
10px
0.75rem
9999px
spacing
unit xs sm md lg xl content-compact content-medium content-wide grid-row-height grid-columns
0.5rem
0.25rem
0.5rem
1rem
1.5rem
3rem
740px
1110px
1400px
20px
24
components
app-shell cell output-area code-editor button-primary button-action input data-table
backgroundColor textColor typography
{colors.background}
{colors.foreground}
{typography.body-md}
backgroundColor textColor typography rounded width
{colors.surface}
{colors.foreground}
{typography.body-md}
{rounded.cell}
100%
backgroundColor textColor typography padding width
{colors.surface}
{colors.foreground}
{typography.body-md}
1rem
100%
backgroundColor textColor typography width
{colors.code-background}
{colors.code-foreground}
{typography.code-editor}
100%
backgroundColor textColor typography rounded height
{colors.primary}
{colors.on-primary}
{typography.label-md}
{rounded.md}
2.25rem
backgroundColor textColor typography rounded height
{colors.action}
{colors.on-action}
{typography.label-md}
{rounded.md}
2.25rem
backgroundColor textColor typography rounded height
{colors.background}
{colors.foreground}
{typography.body-sm}
{rounded.sm}
1.5rem
backgroundColor textColor typography width
{colors.surface}
{colors.foreground}
{typography.body-sm}
100%

Brand Assets

Visual Character

  • Compact, software-native, and utilitarian.
  • White or near-black work surfaces with slate borders and muted secondary text.
  • Restrained blue for primary interaction; yellow for action, stale, or needs-run states.
  • Avoid decorative gradients, marketing-style heroes, nested cards, and one-off palettes.

Color

  • Use background, surface, foreground, border, and muted tokens for structure.
  • Use primary for primary actions, selection, progress, and clear focus only.
  • Use action and stale colors for manual action or freshness state, not generic warning.
  • Use destructive, error, and success colors only for their semantic states.
  • Preserve light and dark token pairs whenever a color appears in both modes.

Typography

  • Use PT Sans for UI and prose, Lora for authored markdown headings, and Fira Mono for code-like values.
  • Keep control text compact and legible.
  • Do not add viewport-based type scaling beyond marimo's app defaults.

Surfaces

  • Use borders first and subtle shadows second.
  • Cells, outputs, editors, markdown, tables, and data grids should be full-width and overflow-safe.
  • Keep data UI dense and inspectable: stable columns, predictable overflow, readable headers, and no decorative framing around tables or charts.
  • Cards are for repeated items, dialogs, or genuinely framed tools; do not style page sections as cards.

Components

  • Buttons should be compact, label-like, focusable, and drawn from primary, secondary, or action semantics.
  • Icon buttons should use familiar existing icons and tooltips for unclear actions.
  • Inputs, selects, and textareas should be compact, bordered, readable, and use code typography only for code-like values.
  • Tabs, menus, popovers, dialogs, and tooltips should use semantic surfaces, borders, focus states, and restrained shadow.
  • Runtime states should pair color with labels, icons, borders, position, or shape.

Motion

Use short transitions for hover, focus, loading, resize, drag, and stale-output changes. Avoid decorative animation.