mirror of
https://github.com/anomalyco/hex.git
synced 2026-11-22 21:23:02 +01:00
* Trace a recording pill hover and reversal offscreen (t1571) * Keep the recording meter anchored and show each audio track (t1571) * Keep light and dark recording snapshots from Linux (t1571) * Draw dictation’s listening field inside the meeting pill (t1571) * Refresh meeting pill goldens with the listening field (t1571) * Paint just the listening dots on the meeting surface (t1571) * Keep dots-only recording goldens in light and dark (t1571) * Keep recording controls and the dictation HUD dark on light desktops (t1571) * Refresh the dark overlays on light-host goldens (t1571) * Keep the finished meeting in its corner and let Close dismiss it (t1571) * Refresh finished summary goldens with the close control (t1571) * Open shipped features from What’s new (t1574) * Keep release-specific links distinct from feature navigation (t1574) * Document and translate the feature feed (t1574) * Verify dark and light navigation to both controls (t1574) * Show feature icons and calendar-day headings in What’s new (t1574) * Verify local-day boundaries and refresh both feed goldens (t1574) * Separate What's new navigation from build details (t1574) * Check What’s new selection through accessibility (t1574) * Refresh only the lower sidebar in the Linux goldens (t1574) * Refresh the pill, Sounds, and What's new goldens after the stack (t1571) * Hold the recording clock still in the dark-host test (t1571)
146 lines
9.3 KiB
Markdown
146 lines
9.3 KiB
Markdown
# Hex Design System
|
||
|
||
Hex's window, meeting capsules, transcription picker, and onboarding are
|
||
drawn with [Rune](https://github.com/anomalyco/rune) in OpenCode's design
|
||
language:
|
||
|
||
- **`rune-kit`** provides the generic components, named after
|
||
`@opencode/ui`'s: `Button`, `IconButton`, `Switch`, `SegmentedControl`,
|
||
`Select`, `Menu`, `Popover`, `TextInput`, `TextArea`, `Badge`, `Progress`,
|
||
and the rest.
|
||
- **`rune-theme-opencode`** provides every colour, elevation, radius, type
|
||
style, and motion token (`rune_theme_opencode::kit(dark)`), which is
|
||
`@opencode/ui`'s tokens as data. Hex follows the system appearance, so every
|
||
view works in light and dark; Labs › Appearance can force the main window
|
||
light or dark. The dictation HUD (including its previews) and the meeting
|
||
recording pill (including its expanded controls and finished summary) always draw dark. Other
|
||
overlays follow the OS.
|
||
|
||
The window follows OpenCode Desktop's layout: a deep-background sidebar and a
|
||
raised, rounded content panel. Hex keeps its own information, sections, and
|
||
copy; the look comes from the kit.
|
||
|
||
The dictation HUD ([`rune_hud.rs`](../src/rune_hud.rs)) is outside the
|
||
system: Dot scope is a shader (`rune_hud.wgsl`) drawn
|
||
by a Rune overlay's compositor on every OS, hand-tuned in HUD Lab.
|
||
|
||
## Rules
|
||
|
||
1. **Kit tokens only.** Views name kit tokens through `Paint`
|
||
([`rune_ui/controls.rs`](../src/rune_ui/controls.rs)): `p.k.c.*` colours,
|
||
`p.k.ty.*` type, `p.k.radius.*`, `p.k.elevation.*`, `p.k.motion.*`, or
|
||
the `Paint` shorthands (`text`, `muted`, `faint`, `accent`, `danger`,
|
||
`success`). The raw numbers left in views are layout metrics: row heights,
|
||
column widths, and gaps. Never write a colour literal outside the theme
|
||
crate.
|
||
2. **Kit components first.** Use a `rune-kit` component when one fits. When
|
||
Hex needs more, extend the Hex piece below that does the job, or add one
|
||
beside it; never keep two helpers for the same job.
|
||
3. **One accent per screen.** The kit's contrast button
|
||
(`ButtonKind::Primary`) marks at most one action per screen: the thing the
|
||
person came to do. A meeting capsule is its own screen. States are not
|
||
actions: an ongoing state (recording, an available update) is a Secondary
|
||
button with a `status_dot`. `ButtonKind::Danger` is for destructive and
|
||
armed confirmations only; success colours mark ready and live states only.
|
||
4. **Few visible actions.** A detail header shows its one to three most common
|
||
actions; the rest go in an overflow menu, with the destructive choice last.
|
||
A destructive choice ends in "…" and keeps its two-step confirmation.
|
||
Space presses the focused button; Return presses only a `.default_button()`.
|
||
Make one the confirming action of a dialog, a tour step, or a recoverable
|
||
confirmation once it shows, never a pane's standing action, and never an
|
||
irreversible one (Clear all history, Confirm delete of a mode).
|
||
5. **Hover is instant, and only on one target.** A settings row never paints
|
||
a hover or press fill; only the controls inside it react (a row that
|
||
toggles is a `pressable_row`). Hover fills belong to things that are one
|
||
clickable target: list rows, picker rows, sidebar items. Every `.hover(…)`
|
||
needs nothing extra: the window's root sets
|
||
`.hover_motion_within(Anim::INSTANT, Anim::INSTANT)` (and each overlay
|
||
window's root does too), so every hover below it, kit controls and popups
|
||
included, switches with no fade either way. Never give an element its own
|
||
`hover_motion`. Press and selection motion stay as the
|
||
kit draws them, except in lists: a `list_row` or list + detail `item`
|
||
selects on the pointer's press with no press overlay, and the selected
|
||
fill and the detail swap in that frame (`select_at_once`).
|
||
6. **Verify by looking.** Render every view you touched with a `--snap` scene
|
||
in light and dark (see [Verification](#verification)).
|
||
|
||
## Hex pieces
|
||
|
||
These live in [`rune_ui/controls.rs`](../src/rune_ui/controls.rs) and
|
||
[`rune_ui/lists.rs`](../src/rune_ui/lists.rs) and compose kit components:
|
||
|
||
| Job | Piece |
|
||
|---|---|
|
||
| Settings page (the gutter and the rhythm between sections) | `page` (cards hang `row_px` past the gutter so row text sits on the title's edge) or `bare_page` (free-standing content on the gutter); their numbers are `METRICS`, the one set of layout tokens |
|
||
| Settings card, titled card, a card whose label line carries a control | `card`, `section`, `section_with` (Advanced, a status, an add button) |
|
||
| Settings row (title, description, control) | `setting_row`, `described_row`, `link_row` (a one-line link under the title, at the plain row height), `toggle_row`; a row that toggles shows `row_switch`; any other row pressed as a whole: `pressable_row` |
|
||
| A few exclusive choices / a dropdown | `segmented`, `select` |
|
||
| A value whose choices open in a sheet, not a menu | `sheet_button` (the value and a trailing chevron) |
|
||
| Main, other, and destructive actions | `button(…, ButtonKind::{Primary, Secondary, Danger}, …)`; inside a row: `small_button`; icon only (with an accessible label): `icon_button` |
|
||
| How a modal enters and leaves | `modal_transition` on the surface (scale 0.96 and fade), `modal_scrim_transition` on its scrim |
|
||
| Shortcut keycaps | `keycaps` (Small keys in a recessed tray as tall as a recorder); one live key that sinks when pressed: `keycap` inside `key_tray`; the recorder is `settings::hotkey_control` |
|
||
| Status (never clickable) | `tone_tag`; a live or recorded state: `status_dot` |
|
||
| Short message under a control | `note` |
|
||
| Text entry saved when typing pauses | `text_field` |
|
||
| Keyboard highlight in a search popover | `Highlight` |
|
||
| List + detail (Commands, Meetings, History) | `list_detail`: `list_column` (search over the rows, on the title's edge, no divider) and `item` rows (no hover fill, time on the right, a hover action in its place via `row_action`), grouped by `group`; the selected item in `body`'s raised card with `card_header`, `card_title`, `meta_text`, `ghost_icon` actions, `card_scroll`, and `facts`; `empty_state` for nothing to show |
|
||
| List + detail (Activity) | `split` with `list_row`, `group_label`, `detail_header`, `detail_title`, `section_label`, `fact` |
|
||
| Keyboard-selectable list (sidebar, list + detail, picker languages) | `source_list` around rows made with `list_row` or `source_item` |
|
||
| Nothing to show, errors | `message`, `placeholder`, `error_panel` |
|
||
| A permission's Allow / Allowed control | `permission_control`, `allowed` |
|
||
| Slider | `slider` |
|
||
|
||
Pane-specific pieces stay in their pane module: the listener card and model
|
||
cards in [`rune_ui/settings.rs`](../src/rune_ui/settings.rs) and
|
||
[`rune_ui/picker.rs`](../src/rune_ui/picker.rs), the onboarding pieces in
|
||
[`rune_ui/onboarding_kit`](../src/rune_ui/onboarding_kit.rs), and the capsules in
|
||
[`rune_ui/meeting_capsules.rs`](../src/rune_ui/meeting_capsules.rs).
|
||
`platform::Capabilities` decides which panes and rows exist on each OS; a
|
||
missing capability omits the row instead of imitating it.
|
||
|
||
## Copy
|
||
|
||
- Sentence case for every label, button, title, and section label:
|
||
"Open settings", "Stop & transcribe", "Permissions needed". Proper nouns keep
|
||
their capitals: Hex, OpenCode, Apple Intelligence, Finder, Zoom.
|
||
- One product name: "Hex", in copy, comments, and docs alike. `HEX_*`
|
||
environment variables are identifiers, not copy.
|
||
- Use "…" (one character) for ellipses, for both progress ("Saving…") and for
|
||
buttons that open a further choice ("Choose a file…").
|
||
- Row descriptions are one phrase with no closing period ("Hold to dictate,
|
||
release to transcribe"). Two sentences keep their periods.
|
||
- Keep one direct line per control. Don't add intro paragraphs above cards,
|
||
repeat field labels per row, put state words next to switches, or warn
|
||
"cannot be undone" beside a two-step confirmation.
|
||
- Every translated string (`tr`, `tr_fill`, `tr_named`) needs all five
|
||
languages in [`desktop/i18n.rs`](../src/desktop/i18n.rs);
|
||
`every_translated_string_has_every_language` scans each UI source.
|
||
Developer-only panes (Activity, HUD Lab) stay English.
|
||
- Exception: native macOS menus (`macos_rune/status_item.rs` and the app menu in
|
||
`macos_rune.rs`) follow the macOS title-case convention ("Check for
|
||
Updates…", "Paste Last Dictation", "Stop & Transcribe").
|
||
|
||
## Verification
|
||
|
||
```sh
|
||
# Headless renders of named fixture scenes (`SCENES` in src/rune_ui.rs):
|
||
cargo run -- app -- --list-scenes
|
||
cargo run -- app -- --snap /tmp/hex-modes.png --scene modes
|
||
cargo run -- app -- --snap /tmp/hex-modes-light.png --scene modes --theme light
|
||
cargo run -- app -- --snap /tmp/hex-mac-settings.png --scene mac-settings
|
||
# Both themes of several scenes into one folder:
|
||
OUT=/tmp/hex-snaps scripts/snap-set.sh modes mac-settings
|
||
# Goldens (light and dark) and pane behavior:
|
||
scripts/check rune_ui
|
||
# After an intended visual change, rewrite the goldens (Linux only):
|
||
HEX_UPDATE_GOLDENS=1 cargo test --locked --bin hex rune_ui
|
||
```
|
||
|
||
On a machine without a GPU, render on lavapipe with
|
||
`VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.json`. Goldens live in
|
||
`tests/golden/` and are compared within a small per-pixel tolerance. The golden
|
||
tests run only on Linux; from a Mac, dispatch `check-linux.yml` on the branch
|
||
and take its `golden-actual` artifact. Look at every changed image and commit
|
||
it with the change that caused it. A scene is a fixture, not native end-to-end
|
||
proof: the meeting capsules and the HUD have no scene, and the real window,
|
||
overlays, and input still need a person on each OS.
|