Patterns & interfaces

This document captures reusable patterns used across tools (SiteTax, Watermarkd, future apps). The goal is consistency: similar problems should feel similar to use.

General principles

• Prefer one clear control over multiple clever ones.
• Always show the outcome of a change in the same screen, if possible.
• Avoid hidden states; users should understand what the tool is doing at a glance.

Numeric input pattern

For values like amounts, percentages, or positions, use a combination of:

• A plain numeric text field.
• Optional slider or stepper when it helps (e.g. overlay size, opacity).
• Inline label or unit (%, px, etc.).

Rule: the value should always be readable and copyable as text.

Result card pattern

For tools that compute something (tax classification, exports, totals):

• Show a single “main result” line in bold.
• Below it, show 1–3 lines of explanation.
• Avoid hiding the explanation behind taps unless necessary.

Example (SiteTax): Taxable – job marked as repair. Repairs are generally taxable.

Explanation line

Every important decision produced by logic should have a plain-language explanation line.

• Keep it one sentence.
• State what the tool assumed.
• Use neutral language.

Toggle / override pattern

When the user can override a logic decision (e.g. marking something non-taxable):

• Show the computed result first.
• Offer a simple control (toggle, segmented control, picker) to override.
• Mark overrides visually (e.g. add “(overridden)” text or secondary color).

Layout: single-column

Most tools should follow a single-column layout, especially on mobile:

• Inputs stacked from top to bottom.
• Result section pinned near the bottom or clearly separated.
• Scrolling is acceptable; horizontal scroll almost never is.

Text & tone

• Use direct, plain English: “Taxable”, “Non-taxable capital improvement”.
• Favor “This tool assumes…” over aggressive warnings.
• Keep labels short; explanations can carry nuance.

Platform notes

Web

• Inputs should work with keyboard only (no mouse required).
• Use standard HTML controls wherever possible.

iOS

• Prefer native SwiftUI controls (Slider, Toggle, Picker).
• Respect system fonts and accessibility settings when practical.

Pattern backlog

Patterns that might be formalized later:

• Multi-step flows (wizards).
• Export configuration panels.
• Field-oriented “quick entry” layouts.