Release 0.3.0-draft.1 · Development standards
Interfaces express the brand through readable hierarchy and truthful behaviour. The component should help a person finish the task with confidence.
Component contract
| Component | Required content and states | Design decision |
|---|---|---|
| Button / link | Clear label; default, hover, focus; loading/disabled where relevant | One primary action per local task; distinguish navigation from action |
| Field / select | Persistent label, help, required/optional state, error and retained value when supported | Error beside the field plus summary for long forms |
| Checkbox / radio | Label, checked, unchecked, disabled and focus | Show choice and consequence without colour alone |
| Alert | Severity, explanation and next action | Use icon/text; avoid ephemeral messages for vital failures |
| Tabs / accordion | Active/expanded state; keyboard behaviour; meaningful headings | Do not conceal required steps or essential disclosures |
| Navigation / breadcrumbs | Current location, destination labels, compact state | Preserve orientation on small screens |
| Dialog | Title, close/cancel, focused entry, focus return | Use only when a contained interruption is necessary |
| Card | Title, useful supporting content, explicit destination/action | Avoid nested competing interactive targets |
| Table | Caption, headers, units, missing-value meaning, overflow strategy | Align comparable data; preserve header relationships |
| Tooltip | Short supplementary information, focus access | Never the only source of required instructions |
| Pagination | Current page and next/previous labels | Preserve filters and announce updated content appropriately |
| Download | File type, size when known, purpose, access/availability | Do not imply the file exists until it does |
| Consent | Separate purposes, meaningful choices, saved state | No visual pressure or preselected optional consent |
Content limits should be tested with long names and translated or expanded copy. Avoid brittle character caps as a substitute for responsive layouts. Use wrapping and simpler copy before clipping essential information.
State language
Empty: explain what belongs here and offer one next action. Loading: state the operation; show a loader only while work is pending. Error: identify the failed operation, preserve safe input where implemented, offer recovery. Success: name the completed event. Unavailable: explain the limitation and offer an honest route onward; do not disguise it as an empty result.
For AI tasks, explain the supplied input, destination/provider when relevant to the decision, explicit trigger, output and review point. Differentiate “draft prepared”, “suggestion selected”, “approved” and “executed”. Never make a decorative progression look like actual autonomous activity. Product privacy statements must be verified with the actual implementation; this handbook does not settle past conflicting disclosures.
Inclusive operation
Use semantic controls, logical keyboard order, visible focus and accessible names. Design at narrow widths and with enlarged text. Keep touch targets comfortably usable; 44 px is a helpful design target, not a claim that every component already conforms. Test screen-reader announcements for asynchronous changes and prevent focus from disappearing behind overlays. Reduced motion must preserve meaning.
Operating rules
UI-001 — Make actual side effects clear
- Do: Describe what a control actually does and who acts next.
- When: Forms, tools and AI flows
- Variation: Separate preparation, approval and execution states.
- Avoid: Calling a saved request a booking or a prepared output an executed action.
- Check: Compare labels and confirmations with implemented behaviour.
UI-002 — Design complete states
- Do: Define empty, loading, error, success and unavailable behaviour alongside default.
- When: Every data-dependent or interactive component
- Variation: Omit irrelevant states with an explicit reason.
- Avoid: Showing indefinite success-like loaders or blank failures.
- Check: Exercise representative state transitions and recovery.
UI-003 — Preserve accessible operation
- Do: Make controls understandable and usable by keyboard, touch and assistive technology.
- When: Digital products and portals
- Variation: Responsive rearrangement that preserves reading and focus order.
- Avoid: Colour-only meanings, hidden focus or essential text inside images.
- Check: Test keyboard, focus, names, announcements, reflow and text scaling.