hitomi
A desktop BlueSky client built using Rust and `iced`. tangled.org/nateledford.com/hitomi
rust-gui bluesky rust iced
Star
Fork
Watch
hitomi DESIGN.md
4.5 kB · 59 lines
Markdown
at main

name: Hitomi description: A macOS-native Bluesky client using system appearance and compact AppKit-informed controls. #

Design System: Hitomi #

Direction #

Hitomi follows macOS conventions instead of carrying a product-owned visual theme. The app uses the active AppKit semantic colors, the system accent, .SF NS typography, compact controls, grouped content, and standard window chrome. Authentication remains a focused task; Home provides Home, Notifications, Bookmarks, and Liked timeline destinations.

Semantic registry #

DESIGN.md owns product direction. docs/design-system/semantic-taxonomy.json owns exact semantic names, current and target mappings, inventory, findings, and validation records. docs/design-system/semantic-audit.md is the human projection of that registry; Rust/AppKit source and smoke observations are evidence, not replacement policy.

Appearance #

  • Refresh colors when Iced reports a system-theme change.
  • Prefer AppKit semantic colors for label, secondary and tertiary label, window, under-page, control, separator, selection, disabled control text, accent, and semantic status colors.
  • Derive accent rollover from the base accent toward the semantic label, pressed toward the control background, and disabled fill from the control background toward the base accent. Keep derived fills opaque so they remain distinct over translucent window material.
  • Use Iced light or dark palette derivation only if AppKit color conversion is unavailable.
  • Use root window material at 82% alpha, toolbar/control material at 72%, and alert tint at 8%.
  • Keep root surfaces translucent only where the semantic backing remains legible. Do not add an NSVisualEffectView overlay.
  • Use semantic status colors only for status: blue info, green success, orange warning, red danger.

Typography #

  • System face requested: .SF NS.
  • Large title: 26px semibold, 1.10 line height.
  • Title: 20px semibold, 1.15 line height.
  • Headline: 15px semibold, 1.20 line height.
  • Body: 13px regular, 1.35 line height.
  • Label: 12px medium, 1.20 line height.
  • Caption: 11px regular, 1.20 line height.

Layout and Components #

  • Spacing scale: 4, 8, 12, 16, 20, and 24px.
  • Controls use a 6px radius; panels use 8px; grouped timeline surfaces use 10px.
  • Control heights: 22px mini, 24px small, 28px regular, 32px large.
  • Keep the primary action solid. Use outline or ghost styling for neutral, reversible actions.
  • Unavailable actions are disabled; in-progress actions show a spinner and do not accept input.
  • Icon-only actions retain a visible text fallback when the icon font is unavailable.
  • Alerts use a subtle semantic fill with a one-pixel semantic border.
  • Loading placeholders are static semantic surfaces; do not add perpetual shimmer.
  • Tabs are controlled selectors. Support underline, pill, and segmented styles; callers choose orientation and fit/fill distribution, retain responsive-breakpoint ownership, and render the selected pane. Optional icons never replace visible labels; selected, enabled, and disabled tabs use semantic system colors.

Window and Screen Rules #

  • Preserve native macOS titlebars and traffic-light controls. Every main-window screen has a blank 52px titlebar and drag region with a horizontal semantic separator.
  • Home alone may render an 80px full-height translucent source-list rail behind the native traffic lights. Its enabled Settings control is bottom-anchored with 12px bottom padding and opens the singleton Settings window.
  • The native application menu owns Settings… with ⌘,; View retains session-only Show/Hide Sidebar and Automatically Hide Sidebar controls. Automatic hiding starts below 400px; the supported main-window minimum is 320×420.
  • Login and root-feedback surfaces remain single-pane. Do not add persistence, a compact timeline mode, a custom traffic-light implementation, or sidebar animation.
  • Keep Settings, secondary image windows, and sign-out confirmation inside the same semantic surface system.
  • Keep indefinite motion limited to visible progress spinners. Any future panel or sheet transition uses a 160–220ms critically damped or cross-faded motion with no overshoot.

Accessibility Constraint #

Iced does not currently expose the required macOS accessibility tree. During internal dogfooding, status labels remain visible and action labels remain meaningful, but Hitomi does not claim native accessibility conformance.