Design Principles
Make source-backed tasks understandable, operable and recoverable while preserving MobTranslate’s Earth palette and the authority of the people whose language it presents.
Start with the task and its evidence
Describe who is trying to do what, what information they need, and what a successful result actually proves. A learner opening a source, a curator reviewing an entry and a contributor granting recording permission have different responsibilities. Build the interface around those responsibilities.
A visual state is a statement to the user. “Saved” needs a verified save; “reviewed” needs an actual review; a machine draft remains a draft. Styling cannot supply missing authority. The styleguide’s local examples label their simulated outcomes.
| Principle | Design decision | Review question |
|---|---|---|
| Evidence before confidence | Keep source, review and publication state near the content. | Can someone inspect why this result is shown? |
| Authority before convenience | Separate listening, retention and research permissions. | Does the interface imply consent or endorsement that was never granted? |
| A complete path | Design waiting, failure, cancellation and retry with the initial action. | What happens if the connection disappears after submission? |
| Multiple ways to operate | Support keyboard, pointer and assistive technology. | Can the task finish without dragging, hovering or hearing? |
| Continuity | Retain input and context across errors and layout changes. | Does recovery force the user to start again? |
Choose semantics before appearance
- Navigation uses a link with a destination. A local action uses a button. Selection uses a labelled input or a source-verified selection primitive.
- Use a persistent label before relying on hints. Icons can reinforce meaning; unfamiliar icons cannot replace a readable action name.
- Start with document headings, landmarks, lists and tables. Choose a composite widget only when the task needs its additional interaction model.
- Expose advanced options when they become relevant without hiding essential constraints, source information or permission choices.
- Base UI behavior is a starting point. Every wrapper and application composition still needs verification.
Use the actual token layers
The shared CSS is the rendered source of truth. It contains raw Earth palette values, semantic roles and shared dimensional/motion values. The generated catalogue shows the actual declarations and overrides. TypeScript palette, semantic and shadow values are generated from the same source. They describe authored light/dark snapshots; live CSS follows theme changes and local inheritance. Component presets have source bindings and a live specification inspector. Separate typography helpers, consuming overrides and contextual layout still require their own verification.
The CSS primary role is ochre, not blue. Pair a role with its matching foreground and inspect the actual state. Product rules sometimes use component classes with literal dimensions; this is not a claim that every property already has a dedicated component token.
| Layer | Example in this package | Use |
|---|---|---|
| Palette | --color-ochre-600 | Reference color or deliberate palette work; avoid choosing it solely because it looks attractive. |
| Semantic role | --color-primary and --color-primary-foreground | Action meaning; foreground/background/state roles travel together. |
| Shared dimensions | --spacing-4, --radius-lg, --shadow-lg | Consistent rhythm, shape and hierarchy. |
| Component contract | .mt-btn-icon and .mt-fab-md | Current source-defined dimensions; document and test changes. |
| Scoped adaptation | Custom properties on a themed wrapper | Deliberate local scope; verify portalled content separately. |
Hierarchy and restraint
- Give the current task one dominant action. Secondary actions should remain discoverable without competing for emphasis.
- Use cards for meaningful containment. Prefer rows and headings for continuous data or document sections.
- Use elevation for layering and separation. A larger shadow does not mean a claim is more trustworthy.
- Keep controls familiar across learner, curator and administrative contexts. Density may change; meaning and keyboard behavior should not.
- Let the reading column support long source text. Reflow surrounding controls before truncating language content or essential evidence.
A worked design decision
| Situation | Proposed design | Reason and acceptance evidence |
|---|---|---|
| An entry has no recording | Show “No recording available” and a clear contribution path if authorized. | Do not synthesize an unlabeled voice. Verify the unavailable path and permission requirements. |
| A request is pending | Keep the entered text and provide cancellation when supported. | Avoid duplicate submission and lost input. Verify success, failure and cancellation independently. |
| A review changes | Display the new state with its source and effective context. | Never infer review from a green badge alone. Verify the actual record returned by the product. |
| A narrow screen | Stack tools around the reading content; retain labelled actions. | Inspect 320 CSS px, long names, translated interface text and zoom. |
| A permission is withdrawn | Reflect the current consent record in playback/listing and explain the outcome. | An old checkbox is not ongoing authority. Verify the persisted boundary in the consuming application. |
Decision record and change process
- Record the task, evidence, affected users, alternatives and chosen tradeoff.
- Link the relevant token/component source and name compatibility risks.
- Specify the default plus waiting, empty, error, disabled, selected and recovery paths that actually apply.
- Choose measurable acceptance evidence: browser operations, computed values, data outcomes and manual assistive-technology checks.
- Use a reviewable change and verify actual consumers before deployment. Update documentation when the contract changes.
Failure cases
- Claiming all components are accessible because they wrap a primitive.
- Choosing a palette shade for status without checking its meaning or contrast.
- Hiding source or uncertainty in a tooltip that cannot be reached on touch.
- Using a loading spinner as the only indication of a request or silently discarding a failed submission.
- Equating a local demonstration, successful build or green screenshot with a verified product outcome.
Verification checklist
- Name the user task and show a complete recovery path.
- Check real tokens and role pairs in both themes, every relevant state and scoped overlays.
- Complete the flow with keyboard and a narrow viewport; preserve focus and input.
- Review the copy for source attribution, permission scope and uncertainty.
- Record remaining limitations and the exact evidence needed to resolve them.