Skip to content

DESIGN.md

Latest commit

 

History

History
150 lines (107 loc) · 7.08 KB

DESIGN.md

File metadata and controls

150 lines (107 loc) · 7.08 KB
Raw

TextAction Design System

0. Research Log

  • Embedded references: shortlisted Raycast, Linear, and Superhuman; selected the operational taste-skill rules with Raycast as the closest keyboard-first command-surface reference.
  • Product reference: Bob's select-text → choose-action → view-result interaction supplied by the user.
  • Skipped lanes: Lazyweb and generated concept images were intentionally skipped because this is a compact native Windows MVP with a concrete interaction reference, not a greenfield marketing surface.

1. Atmosphere & Identity

TextAction is a quiet command surface that should feel instant, compact, and trustworthy. Its signature is a cool near-black floating panel with one restrained blue focus accent and tactile keyboard-key hints. It should resemble a native precision utility, not a chat application.

Design read: a keyboard-first Windows productivity utility for people who work across browsers, editors, and terminals, with a restrained Raycast-inspired language.

Design dials: variance 3, motion 2, density 7. The window is operational, frequently invoked, and must prioritize scan speed and keyboard access.

2. Color

The MVP is dark-only so it remains visually stable across host applications.

Role Token Value Usage
Canvas Surface.Canvas #080A0D Transparent-window backdrop
Primary surface Surface.Primary #111419 Menu and result windows
Elevated surface Surface.Elevated #191D24 Hovered or selected rows
Pressed surface Surface.Pressed #222833 Active controls
Primary text Text.Primary #F5F7FA Titles and results
Secondary text Text.Secondary #A7AFBC Descriptions and metadata
Tertiary text Text.Tertiary #7A8595 Hints and disabled text
Default border Border.Default #2A303A Window and control containment
Subtle border Border.Subtle #20252D Dividers
Accent Accent.Primary #62A8FF Selection, focus, links
Accent muted Accent.Muted #183A61 Selected-row background tint
Success Status.Success #61C995 Success state
Warning Status.Warning #E8B65B Recoverable warning
Error Status.Error #FF7373 Errors

Rules:

  • Accent is reserved for focus, selection, and actionable text.
  • Status colors are semantic only.
  • New colors must be added here before use.

3. Typography

The primary font is Segoe UI Variable Text, falling back to Segoe UI. The monospace font is Cascadia Mono, falling back to Consolas.

Role Size Weight Line height Usage
Window title 18 SemiBold 26 Result title
Action title 14 SemiBold 20 Menu items
Body 14 Normal Native WPF metrics (≈21) Result content
Secondary 12 Normal 18 Descriptions
Caption 11 SemiBold 16 Key hints and status

Body text never drops below 12 device-independent pixels. Text rendering uses ClearType defaults and no decorative type. The read-only WPF TextBox keeps its native line metrics; the approximate value above is a visual target, not a forced property.

4. Spacing & Layout

Base unit: 4 device-independent pixels.

Token Value Usage
Space.1 4 Tight icon/key spacing
Space.2 8 Related inline content
Space.3 12 Row padding
Space.4 16 Window inset
Space.5 20 Comfortable separation
Space.6 24 Major internal separation

Windows size to their purpose:

  • Action menu: 420 × content, capped at 520 high.
  • Result window: 680 × 520, resizable down to 480 × 320.
  • Corners: 12 for windows, 8 for rows and buttons, 5 for key caps.

The action menu appears near the current cursor while staying inside the active monitor's work area.

5. Components

Action row

  • Structure: icon tile, title/description stack, optional shortcut hint.
  • Variants: default and disabled.
  • States: default, pointer hover, keyboard selected/focus, disabled.
  • Accessibility: reachable with Up/Down, invoked with Enter, dismissed with Escape; text labels remain visible.
  • Motion: no positional animation; selection changes use an immediate tonal shift.
  • Layout: horizontal cluster with a flexible text stack.

Key cap

  • Structure: short uppercase label inside a compact bordered surface.
  • States: default only; it is informational, not interactive.
  • Accessibility: shortcut is also exposed in the action row's accessible name.
  • Depth: flat dark key surface with a one-pixel border.

Result toolbar button

  • Variants: primary text action and quiet text action.
  • States: default, hover, pressed, focus, disabled.
  • Accessibility: minimum 40 × 40 target; descriptive label and visible focus border.
  • Motion: pressed feedback uses an immediate tonal background plus reduced opacity.

Status banner

  • Variants: loading, warning, error.
  • States: static message; loading includes indeterminate progress.
  • Accessibility: announced through the result window status text.

Text result surface

  • Structure: scrollable, selectable, wrapping read-only text.
  • States: populated, loading, error; blank provider output is treated as an error rather than a successful empty state.
  • Accessibility: keyboard-selectable and copyable; high-contrast text.
  • Layout: owns vertical scrolling.

6. Motion & Interaction

Type Duration Usage
Micro Immediate Hover, selection, and pressed tonal feedback

The MVP avoids decorative or window-entry animation. Esc always closes the active surface. The action menu focuses its first enabled action. The result window remains available until explicitly closed.

7. Depth & Surface

Strategy: tonal shift and restrained borders.

  • Menu and result windows use a one-pixel border against the host desktop. The MVP intentionally avoids custom outer-shadow and inset-highlight rendering.
  • Selected rows use tonal shift plus the muted accent; they do not add a second floating card.
  • Buttons rely on tonal state changes, not separate card containers.

8. Accessibility Constraints & Accepted Debt

Constraints:

  • Target WCAG 2.2 AA contrast.
  • Complete keyboard operation for the primary flow.
  • Visible focus on every interactive control.
  • Screen-reader names on actions and toolbar buttons.
  • Status and error text never rely on color alone.
  • Touch targets are at least 40 × 40 in the result window.

Accepted debt:

Item Location Why accepted Owner / Exit
Dark theme only Entire MVP Keeps the first release focused and visually predictable across host apps Add system/light theme after MVP feedback
API key stored in user config when entered directly Configuration MVP supports safer env:VARIABLE references and documents them as preferred Replace direct storage with Windows Credential Manager in a later release
Clipboard capture uses simulated Ctrl+C Windows selection capture Windows lacks one universal cross-app selected-text API Investigate UI Automation fallback after MVP