Practice

Design rules for tools

A shared look and a shared set of manners, so that twenty tools written by ten people still feel like one product.

Every pyNavis tool is written by a different person, at a different time, for a different job. Nothing enforces consistency between them. What the user sees is not your tool, it is the pile: a ribbon tab of buttons and dock panels that all claim to belong together, and the first one that looks or behaves differently makes the whole tab feel improvised. The rules here apply to every surface you draw, a dialog, a pane.xaml panel, or a window of your own.

This page is the contract. The first half is what a tool has to look like, taken from the pyNavis design system v2.2. The second half is how it has to behave, which matters more and is easier to get wrong. Both halves are short on purpose.

The direction, in one paragraph#

Neutral grays, hairlines and whitespace carry the structure. The Windows accent appears in exactly three places: the primary action, the selection rail, and the focus ring. Numbers are quiet tabular text, not chips. Controls are the native affordances users already know, meaning checkbox, toggle, segmented and standard captions. Each tool gets one signature moment, the 28px weight-300 readout number pair. Solid surfaces only.

If you take one thing from that: your tool should be boring to look at and obvious to use. The interesting part is the model, not the chrome.

Accent in three places#

The slop test#

Before shipping any surface, check it against the tells below. If a screenshot of your tool could pass for a template demo, it fails. The goal is an interface a Windows user trusts instantly and then stops noticing.

Type#

Layout#

Colour#

Twelve tokens plus the accent. If a colour you want is not in this table, the answer is one of these tokens, not a new colour.

Read the current theme with pynavis.script.is_dark_theme() and paint your own dialogs from the correct column. Read it when you build the window, not once at import time.

from pynavis import script

dark = script.is_dark_theme()
paper = '#202020' if dark else '#FFFFFF'
ink   = '#E8E8E8' if dark else '#1A1A1A'
muted = '#9A9A9A' if dark else '#6B6B6B'

How a tool has to behave#

The visual rules keep tools looking alike. These keep them trustworthy, which is the harder half. Each one has a failure mode a real tool has shipped with.

Report every outcome#

A tool that does its job and shows nothing is indistinguishable from a tool that crashed silently. Every path out of your script ends in something the user can see, with the single exception below.

count = purge_unused(doc)
if count:
    toast.success('Purged %d unused items' % count)
else:
    toast.info('Nothing to purge')

count = purge_unused(doc)
if count:
    toast.success('Purged %d unused items' % count)
# zero purged: the tool looks broken

Cancelling is silent#

The exception. When the user cancels, say nothing at all. They know what they did, and "Cancelled" is a notification about their own hand.

if forms.confirm('Delete 412 viewpoints?'):
    delete()
    toast.success('Deleted 412 viewpoints')
# No is not an outcome to report

if forms.confirm('Delete 412 viewpoints?'):
    delete()
    toast.success('Deleted 412 viewpoints')
else:
    toast.info('Cancelled')

Failure is a sentence, not a traceback#

Predictable failures, meaning a missing file, a locked document, a value the user typed wrong, get caught and reported in plain words that say the fix. Genuine bugs should still raise: the runtime puts the traceback in the output window, which is exactly where you want it.

try:
    data = json.load(open(path))
except (IOError, ValueError):
    toast.error('Could not read the mapping file',
                path)
else:
    apply_mapping(data)

try:
    data = json.load(open(path))
except Exception as exc:
    forms.alert(str(exc))     # modal, and
                              # says nothing useful
    raise

One undo step per user action#

Ten thousand separate edits give the user ten thousand Ctrl+Z presses, and they will also exhaust the host's undo stack, which quietly makes the work irreversible. Wrap a bulk edit in a single transaction.

from pynavis import viewpoints

with viewpoints.transaction('Rename viewpoints'):
    for view in views:
        view.DisplayName = new_name(view)

for view in views:
    view.DisplayName = new_name(view)
# 4,200 undo steps, and the stack
# drops the earliest of them

Counted progress, and a way out#

Show progress for anything that can run longer than a second or two, and offer Cancel for anything that can run longer than several seconds. Put the count in the label: "Renaming 4,200 of 11,038" tells the user whether to wait or to stop, and a percentage alone does not.

total = len(items)
for i, item in enumerate(items):
    process(item)
    if i % 100 == 0:
        output.progress(float(i) / total,
                        'Checking %d of %d' % (i, total))
output.progress(1.0)

for item in items:
    process(item)
    output.progress(0.5, 'Working...')
# indeterminate, and repainted
# once per item

When a run is cancelled part way, report the split honestly. "Deleted 3,180 of 4,200. 1,020 were left when you cancelled." That is a warning, not a success, and it must never claim work was undone when it was not.

Empty states are states#

Nothing selected, no results, no active document: each of these is a real answer and needs saying, along with what the user should do about it.

items = selection.get_items()
if not items:
    toast.info('Nothing selected',
               'Select the items to export, '
               'then run this again.')

items = selection.get_items()
export(items)          # writes an empty
                       # file and says
                       # "Exported 0 items"

Never open a window to say one line#

A bare print() opens the whole output window to show one sentence, and if that is all the script writes, the user gets a nearly empty window. It reads as a bug because it looks exactly like one.

toast.success('Saved 3 viewpoints')

print('Saved 3 viewpoints')

Speak the model's language#

The user knows what they see in Navisworks. They do not know your variable names, and they should never meet an API type name.

toast.warning('3 saved viewpoints have '
              'the same name')

toast.warning('3 SavedViewpoint instances '
              'collided on DisplayName')

Copy rules#

• Sentence case. "Group clashes", not "Group Clashes".
• No em dashes or en dashes. A comma, a colon, a semicolon, or two sentences. This is a hard rule and it applies to every string a user can read.
• No emoji, anywhere in the UI. Not in toasts, not in button labels, not in the output window.
• Plain verbs. "Delete", "Rename", "Export". Not "Proceed", not "Execute", never "Utilize".
• Errors say the fix. "Could not read the mapping file" plus the path beats "An error occurred", every time.
• Count things. "Renamed 412 items" beats "Renamed items". The number is what the user actually wanted to know.
• No apology, no exclamation. State what happened.
• Say what the user sees. Viewpoints, selection sets, clash tests, search sets. Not ModelItem, not SavedViewpoint.

The same result, twice#

Before you ship#

Run your tool against this list. It takes two minutes and it catches almost everything.

• Every exit path shows something, and cancel shows nothing.
• Nothing selected, no results and no active document each have a message that says what to do next.
• Predictable failures are caught and reported as a plain sentence with the fix.
• Anything longer than a second shows counted progress; anything longer than several seconds can be cancelled.
• A bulk edit is one undo step.
• No print() for a one-line status.
• No window opened for a single sentence.
• The accent appears in three places at most, and the selection is neutral.
• Every control is reachable by Tab and shows a focus ring.
• Disabled controls look disabled and say why in a caption.
• The tool is readable in both themes; you checked with is_dark_theme() both ways.
• Every string is sentence case, free of emoji, and free of em dashes.
• No string names an API type the user has never heard of.
• A screenshot of it would not look out of place beside the rest of the ribbon.