Skip to content

DESIGN.md

Latest commit

 

History

History
149 lines (131 loc) · 5.25 KB

DESIGN.md

File metadata and controls

149 lines (131 loc) · 5.25 KB
Raw
name ParseKit
description Menu-bar document converter — private, local, native macOS craft
colors
ink ink-secondary accent accent-hover accent-fg surface surface-elevated border link status-success status-error status-warning dark-bg dark-ink dark-accent
#1B1713
#6B5E52
#3F3830
#322C26
#F9F7F2
#F7F4EE
#FFFFFF
#B8A99A
#5C4A3A
#2F8A4A
#C23B2E
#C9892A
#1C1A17
#F5F2EB
#E8C99A
typography
display body mono label
fontFamily fontSize fontWeight lineHeight letterSpacing
Instrument Serif, Georgia, Times New Roman, serif
1.25rem
400
1.2
-0.015em
fontFamily fontSize fontWeight lineHeight letterSpacing
-apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, sans-serif
0.875rem
400
1.4
normal
fontFamily fontSize fontWeight lineHeight letterSpacing
JetBrains Mono, SF Mono, Menlo, monospace
0.8125rem
500
1.3
-0.01em
fontFamily fontSize fontWeight lineHeight letterSpacing
-apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, sans-serif
0.72rem
500
1.25
0.01em
rounded
sm md lg pill
6px
8px
12px
999px
spacing
xs sm md lg xl
4px
8px
12px
16px
24px
components
button-primary button-primary-hover button-secondary chip card
backgroundColor textColor rounded padding
{colors.accent}
{colors.accent-fg}
{rounded.md}
8px 14px
backgroundColor textColor
{colors.accent-hover}
{colors.accent-fg}
backgroundColor textColor rounded padding
transparent
{colors.ink}
{rounded.md}
8px 12px
backgroundColor textColor rounded padding
transparent
{colors.ink}
{rounded.pill}
5px 10px
backgroundColor textColor rounded padding
{colors.surface-elevated}
{colors.ink}
{rounded.lg}
14px

Overview

ParseKit is a product-register macOS menu-bar tool: design serves conversion, not marketing spectacle. Visual system is Bone White, Pressed — warm restrained neutrals, charcoal primary, native SF Pro body, Instrument Serif only for display (app title / about). Motion is short (120–180ms), ease-out, interruptible, reduced-motion aware. Identity lives in craft density and privacy posture, not loud color.

Canonical tokens: src/index.css (:root, [data-theme], system dark). Brand narrative: brand.md. Product brief: PRODUCT.md.

Colors

OKLCH is source of truth in CSS; hex above is sRGB approximation for tooling.

Role Light (OKLCH) Use
Ink oklch(0.18 0.01 50) Body text
Secondary oklch(0.48 0.03 50) Hints, labels (keep ≥4.5:1 on surface)
Accent oklch(0.32 0.03 50) Primary buttons, focus
Accent FG oklch(0.98 0.005 85) Text on primary
Surface glass oklch(0.97 0.01 85) + blur Popover material
Border oklch(0.72 0.02 50 / 0.95) Hairlines
Success / Error / Warning status-* tokens Semantic only

Dark theme flips ink/surface and warms the accent (oklch(0.78 0.08 75)). Prefer restrained strategy: neutrals dominate; accent ≤10% of surface.

Typography

  • UI / body: system sans (--font-sans) — native macOS feel.
  • Display only: Instrument Serif (--font-serif) for app name / about — not for buttons, data, or dense labels.
  • Data / counts: JetBrains Mono (--font-mono), tabular-nums for token counts.
  • Scale ratio ~1.15–1.2; display letter-spacing floor ≥ -0.04em (hero metrics ~-0.03em).
  • Prefer weight + size hierarchy over all-caps eyebrows on every section.

Elevation

Mostly tonal layering (secondary-bg, glass) over heavy drop shadows.

  • Prefer: 1px border or soft shadow ≤8px blur — not both as decoration.
  • Popover: glass material + restrained inset highlight.
  • Focus: --focus-ring translucent accent ring (never remove).

Components

Component Notes
Primary button .run-parse-btn / accent fill; :active scale(0.97)
Secondary button Transparent / light border; quieter press scale
Chips Pill outline for optional choices (destination)
Scoreboard Post-convert result: one hero number, platter stats, progressive disclosure for method
Drop zone Dominant affordance for first-run convert
Segmented control Period toggle (today / month / lifetime)
Banners Error/notice with fly enter; reduced-motion → fade

States required on interactive: default, hover, focus-visible, active, disabled.

Do's and Don'ts

Do

  • Keep conversion path obvious: drop → run → open output.
  • Use local metrics language (estimate, privacy line).
  • Animate transform/opacity only; honor prefers-reduced-motion and prefers-reduced-transparency.
  • Align new UI to tokens in src/index.css before inventing hex.

Don't

  • Side-stripe accents (border-left >1px on cards/callouts).
  • Hero-metric SaaS clichés with gradients and confetti.
  • Nested cards; identical icon+title+body grids.
  • Uppercase tracked kicker on every block.
  • scale(0) entrances; bounce/elastic easing.
  • Pair thick border + wide soft shadow (ghost-card).
  • Put Instrument Serif on dense UI chrome.