Start with the job

Name the person, the job they need to finish, the current obstacle and the observable result before adding a screen or setting. A feature must remove work, reduce uncertainty or enable a necessary decision.

Make the next step obvious

Every active workflow shows its current state, next meaningful action, responsible person or team, and any blocker. Completed work moves out of the attention queue. Do not invent an action when the user is waiting on someone else.

Payment recorded. IT: prepare the device. Buyer: invoice receipt pending.

Earn certainty with evidence

Distinguish configured, queued, running, confirmed, failed and unknown. Show the source and freshness of consequential claims. Never turn an unavailable check into a green result, an empty count or proof of completion.

Remove the second piece of work

Reuse known data, sensible defaults and linked records. Prefer a useful suggestion to another mandatory field. Offer repeatable automation after a real repeated task; do not make scripting a requirement for basic use.

Keep the person in control

Make changes explainable, attributable and recoverable where technically possible. The simplest interface still exposes scope, consequences and meaningful choices. Never hide a safety-critical distinction to make a screen look clean.

Measure outcomes honestly

Track task completion, errors, time to first useful result, repeat manual steps and recovery effort. Compare the same tasks and dataset before and after. Report observed time savings separately from estimates and external service costs.

Use the registry

Product marks come only from design/logos/registry.json. Keep their exact paths, 24 × 24 viewBox, 1.6 stroke and round caps/joins. Do not substitute a similar icon, emoji, gradient tile or generated image.

Keep brand ownership clear

Kebabstack is the suite; Hub, Desk, Assets, Trust, Contracts, Forms, Watch, Crumbs, Kitchen and Vault retain their registered product names. Company branding and external app logos remain separate. Phone is a reserved, planned mark, not a shipped capability. The suite skewer, wordmark, variants and clear-space rules come from design/brand/registry.json and its usage guide; legacy ring-handle assets are not alternatives for new work.

Preserve proportions and meaning

Use 20–24 px marks in navigation, 26–36 px in headers and 36–48 px in catalogues, with at least 4 viewBox units of clear space. Keep a nearby product name. Decorative marks use empty alt text; icon-only controls have an accessible action name.

Use colour by purpose

Sage is the logo colour, forest is the main action colour, and warm orange is a restrained brand accent. Product identity never carries health or permission status. Logo sage is not approved for small body text on every background.

Keep the character restrained

Use warm paper, precise linework, generous grouping and occasional editorial diagrams. Avoid mascots, confetti, skeuomorphic tiles and stock imagery in work queues. Marketing may be more expressive; critical work remains calm.

Use semantic tokens

Use tokens.json for the target palette, spacing, type, radii, motion and layer values. Components refer to purpose, not a literal hex code. hub/dist/tokens.css is the canonical generated runtime stylesheet; hub/dist/components.css defines shared workspace controls. Run runtime:sync and runtime:check instead of copying or redefining app palettes.

Keep text legible

Use the system sans stack or the existing locally hosted Inter for UI and headings. Use monospace only for identifiers, code and compact technical metadata. Body text is 16 px; dense desktop rows may use 14 px. Labels and useful metadata are at least 12 px. Never shrink text to hide a layout problem.

Use a small type scale

Use 32–40 px page titles, 24 px section titles, 18 px panel titles and 16 px body text. Keep heading weight 500–600, body 400, line height 1.5–1.65 and long text around 60–75 characters per line. Use sentence case; reserve spaced uppercase for short optional eyebrows.

Separate boundaries from decoration

Subtle borders may group cards. Interactive boundaries, focus rings and meaningful graphics need sufficient contrast independently. Text uses approved foreground/background pairs; colour is never the only indication of error, selection or health.

Use one rhythm

Build from 4, 8, 12, 16, 24, 32, 48 and 64 px spacing. Default cards use a 16 px radius, controls 8 px, overlays 16 px and pills only for short statuses. Use 24 px panel padding and 16 px on small screens. Prefer a divider or spacing over nested cards.

Design both themes

Theme preference follows system until explicitly changed and is shared through the established suite shell. Check every semantic state in both themes. Dark mode is a deliberate palette, not CSS inversion. Exported documents declare their own readable print palette.

Keep one home for each decision

Company people, app access and suite connections live in Hub. Ticket handling lives in Desk; custody in Assets; posture in Trust; agreement records in Contracts. Cross-app pages summarize and deep-link to the owning tool instead of duplicating editable settings.

Use a shallow, task-shaped menu

Group frequent work first, then configuration, then help and operations when needed. Use familiar object or task names. Keep global app switching separate from local navigation. Show a contextual Back link or breadcrumb for deeper records; do not stack three independent tab bars.

Remember the working context

Use stable, shareable routes for records and meaningful views. Preserve authorized destination, filters, sorting and pagination across Back, refresh and SSO. Do not put tokens, personal information or secrets in routes or analytics.

Navigation describes a destination

Use links for navigation and buttons for actions. Mark the current location. Icon and label align in a fixed slot; the whole target has a consistent hit area. Browser open-in-new-tab works for record links.

Use one vocabulary

Use person for a directory record, account or session only when that distinction matters, and explicit app roles from the central policy. Prefer Apps → Updates to internal names such as Pantry. Domain terms can differ only where their meaning differs.

Queue: decide what needs attention

Put title, scope and primary action first, then search and relevant filters, then the work list. Default to the meaningful unfinished scope. Show a compact count, owner, state and next useful fact; move full histories and identifiers to detail.

Detail: do the work, then inspect

Show identity and status once, followed by the next action. Put active work in the main column and supporting facts in a quieter side column. On small screens, use a single logical DOM order with the next action before secondary metadata.

Settings: explain the choice

Group settings by operator task and show current configuration before editing. Reveal conditional fields only when relevant; explain effects beside the control. Offer useful defaults. Do not show obsolete toggles or options that never change.

Setup: reach the first useful result

Use short steps only for genuine dependencies. Allow save/resume, validation and a safe test. Show prerequisites, required external access and who can complete blocked steps. Collapse completed setup; keep setup status distinct from service health.

Give content room to reflow

Use a fluid content width up to 1280 px for normal work, up to 1600 px for justified dense operations, and about 720 px for reading. Use 32 px desktop and 16 px mobile gutters. Collapse sidebars before compressing controls. Constrain wide tables locally, not the whole page.

Public tasks stay focused

Guest dealrooms, customer intake, embedded forms and public status pages expose only their scoped task. They do not inherit admin navigation, company directory search or unrelated product promotion. Provide recovery for expired access and preserve non-sensitive drafts where safe.

One main action per decision

Use a forest-filled button for the next useful action in the active region, outlined secondary actions and quiet links for tertiary navigation. Label verbs with their object: Save policy, Assign device, Publish update. Do not give every card a competing primary button. Use the measured button geometry and states in the visual catalogue; tokens.json owns the dimensions.

Explain unavailable actions

Hide actions the role can never perform, without leaking protected data. For a permitted action blocked by prerequisites, keep its reason visible and link to the remedy. Do not rely on a tooltip attached to a disabled button. Read-only views identify who can make changes.

Menus and tabs have distinct jobs

Menus hold infrequent secondary actions; essential next actions stay visible. Tabs switch related content and expose current selection. Workflow steps show progress; filters narrow a collection. Do not disguise one as another. Use native controls or fully implement their keyboard pattern. The Menus & tabs catalogue defines spacing, hit areas, active indicators and keyboard behavior.

Use overlays sparingly

Use a dialog for a short, focused decision; a drawer for contextual inspection; a page for lengthy work. Modal content traps focus, labels its purpose, makes the background inert and returns focus on close. Escape and the close control preserve or explicitly discard drafts. Avoid nested dialogs.

Make selection and actions explicit

A checkbox selects; a record link opens. Bulk actions state the number and scope selected, including whether selection spans pages. Preview consequences for destructive or externally visible changes. Report per-item results and make retry target only failed eligible items.

Prefer standard controls

Use native buttons, links, inputs, selects and details where they satisfy the task. A custom searchable picker needs labels, active option, keyboard selection, clear state and no-results behavior. Dragging always has a non-dragging alternative.

Label and group every input

Keep labels visible; placeholders are examples, never labels. Associate help and errors programmatically. Mark optional fields when most are required, otherwise mark required fields consistently. Use fieldsets for related choices.

Keep save behavior predictable

Use an explicit Save for policies, integrations, settings and multi-field edits. If autosave is appropriate, show saving, saved and failed states and preserve the draft on failure. A toggle must not silently commit the rest of a form. Warn about abandoning a meaningful unsaved draft.

Validate where the correction belongs

Validate format near the field after meaningful interaction. On submit, focus an error summary with links to invalid fields; keep entered values. Backend validation remains authoritative. Clearly distinguish invalid input from unavailable service or denied permission.

Reuse known information

Pre-fill confirmed data with its source and let authorized users correct it. Use appropriate autocomplete and inputmode. Do not ask for data already held just because another tool owns it. Only collect information needed for the stated purpose.

Handle sensitive inputs deliberately

Mask secrets, expose them only on an authorized explicit action, and explain whether they can be retrieved again. Never prefill a masked placeholder as a new credential. Keep tokens out of URLs, logs, screenshots and telemetry. A successful copy is reported only after the clipboard operation succeeds.

Review consequential actions concretely

For deletion, publication, permission changes, financial issuance and fleet actions, show affected scope, consequences and recovery limits before the final action. Routine reversible edits need no ritual confirmation. Recheck current authority and record version at execution.

Show decision fields first

Default to identity, state, owner, relevant time and the next-action signal. Choose additional columns only for the task. Right-align comparable numbers and use tabular numerals; keep units and currency visible. Never mix currencies into an unexplained total.

Keep query scope visible

Search, active filters and sort order are visible and resettable. Say whether counts describe the complete authorized collection, the filtered result or the current page. Sorting applies to the promised dataset, not just the downloaded rows.

Preserve context during refresh

Keep focus, scroll, selection and in-progress edits stable. Do not reorder a queue under the pointer while the user is acting; announce new items with a refresh affordance when needed. Reject stale asynchronous results after identity, route or filter changes.

Distinguish absent from zero

Use Not recorded, Not checked, Not applicable and Unavailable where appropriate. A confirmed zero is a value. Show the last successful observation and freshness for imported or monitored data. Keep technical detail in a disclosure with a support reference.

Make imports recoverable

Preview mapping, validation, duplicates and affected records before import. Provide a small downloadable example with fictitious data and precise field definitions. Report accepted and rejected rows separately and provide safe retry guidance.

Exports describe their evidence

Show scope, filters, generation time, timezone, currency and relevant policy version. Restrict export to current role and purpose. Neutralize spreadsheet formulas in untrusted CSV text; do not put private data into filenames. Reports preserve the distinction between draft, approved and released.

Design the complete state set

Every data region defines initial/loading, loaded, empty, filtered-empty, partial, stale, error and forbidden states where applicable. A skeleton is a loading placeholder, not a count of zero. Keep independent regions useful when one fails.

Use progress that is real

Acknowledge an action immediately. Show the current meaningful stage for longer work, not a fabricated percentage. Explain when it is safe to leave and whether the job continues. If a wait exceeds its timeout, offer a useful recovery path.

Separate accepted from completed

A request accepted into a queue is not a confirmed external result. Show saved in Hub, awaiting app confirmation, confirmed or failed separately. Optimistic UI is limited to reversible low-risk edits that can visibly recover.

Make errors actionable

Lead with what failed and what remains intact, then the next useful action. Preserve input. Offer retry only when safe; for ambiguous outcomes, check operation status before resubmitting. Put raw stack traces and sensitive provider errors behind sanitized operator diagnostics.

Could not confirm the update. Your draft is still here. Check the job status before trying again.

Notify accessibly without stealing focus

Use a polite live region for routine asynchronous results; use urgent alerts only for urgent failures. Success toasts are supplementary, not the only receipt for important work. Keep actionable errors persistent until addressed.

Empty states explain a path

Distinguish first use from no matches, lack of permission and missing integration. Offer one role-appropriate next action. Never show setup controls to employees who cannot use them.

Name outcomes, not implementation flags

Use a small set of domain states with explicit entry/exit conditions. Model waiting, blocked and failed deliberately. Complete means the stated outcome is achieved; Cancelled is a terminal side branch, not the next step after success.

Show the next actor

Each unfinished case names who is responsible now, the blocker and a due time if one exists. A stage counter and a per-record progress indicator have different scopes. Do not ask the current user to perform another person’s acceptance.

Coordinate without duplicating authority

Link records through stable IDs and identify the owning tool. Offboarding can collect equipment, contracts, forms and tickets while each source enforces access. Deactivation stops access independently of ticket completion; equipment custody is not silently erased.

Treat manual exceptions as decisions

If a real process allows an override, name who may use it, the reason required, the evidence retained and which safeguards remain. Do not add a universal Force complete button or silently invent acceptance on someone else’s behalf.

Keep handovers explicit

Assignment, ownership, payment, physical handover, data erasure and closure are distinct facts. Preserve history when a person departs. External buyer flows require their own scoped access; disabling an employee account does not grant external access automatically.

Close the loop

Show completion evidence, remaining obligations and the relevant record of what happened. Remove resolved items from urgent queues without hiding their history. Offer a reusable template when a repeated workflow has stabilized.

One central source of app authority

Show effective app role, scope and provenance from Hub. Active Hub Owners and global Admins inherit app administration according to the central policy; only Owners delegate central app privileges. Do not add local app-admin lists. Follow docs/APP-PERMISSIONS.md for exact enforcement.

Limit views to their actual purpose

Employees see their own and explicitly shared objects. Project, responder and HR/Finance capabilities expose only the data needed for that task. Read-only reporting does not imply access to incident narratives, customer messages or company-wide tickets.

Explain inheritance and propagation

Show where access comes from and link authorized administrators to Hub. Distinguish policy saved from app enforcement confirmed. If fresh authorization cannot be established, fail closed and explain how to recover. Never promise immediate upstream IdP revocation.

Keep sign-in on one journey

Use the shared sign-in shell from tool entry through provider selection, verification and handoff. State the destination and company. Once company authentication succeeds, continue directly to the authorized destination without showing an interactive Hub home or original login screen.

Recover safely from interrupted login

Validate return destinations against configured origins. Keep background navigation inert during handoff; prevent duplicate submissions. Offer retry and a deliberate return on timeout. Re-authentication preserves safe task context without storing credentials or leaking protected drafts.

Treat guest access as a separate scope

Private links, embedded intake and public forms use narrowly scoped capabilities with clear validity and recovery behavior. Browser widgets never contain privileged API secrets. Existing external integrations such as Lunch keep their documented identity/data contracts.

Describe a rule in plain language

Every rule shows trigger, matching scope, prerequisites, action, owner and failure behavior. Show what it will not match when that affects a decision. Give human-readable examples based on authorized records.

When a person becomes inactive, open or update their offboarding case and collect accessible assigned equipment.

Preview consequential automation

Separate a non-mutating preview from a real run. Show affected records, external systems and required permissions. Require explicit configuration before automatic destructive or externally visible actions. Approved routine rules can then run without repeated prompts.

Make repeated events harmless

Use stable correlation and idempotency for repeat events and retries. Recheck authority and preconditions at execution. Show skipped, already handled and failed items separately. Never retry an uncertain financial or destructive action blindly.

Offer a useful run history

A run shows trigger, rule version, actor, affected scope, per-step outcomes, timestamps and links to evidence. Expose Pause, retry failed work and manual recovery where supported. Pausing future runs does not claim to undo actions already performed.

Suggest the next useful automation

Suggest a template after repeated manual work and show editable conditions. Avoid constant nudges, speculative savings and a blank workflow canvas as the first experience. Provide an accessible list/form editor even if a visual builder is added.

AI respects evidence and authority

Label generated drafts, cite accessible source records and state uncertainty or missing information. Treat retrieved text as data, not instructions. AI acts within the user’s rights; impactful actions use the same preview and execution safeguards as manual actions. Explain any external model data flow and retain only necessary history.

Minimize the default view

Show only fields useful for the current task and role. Avoid personal details in global lists, wallboards, notification previews and URLs. Reveal sensitive information explicitly when authorized, with a clear purpose.

Describe retention precisely

Show what is stored, why, the configured retention period, the event that starts it and who owns the policy. Distinguish source data, audit evidence, issued documents and backups. Automatic cleanup must expose last run, next due work, holds and failures.

Deletion is not revocation or archive

Name the actual action: revoke a link, archive a record, anonymize fields, delete data or expire a backup. Preview scope and irreversible effects, handle linked records and explain lawful retention holds without claiming automated legal judgment.

Do not claim compliance from appearance

Design for data access, correction, export, deletion requests and restricted audit review. Document deployment location, operator access and external data processing limits. Do not describe the suite as GDPR-certified, confidential from operators or compliant merely because a feature exists.

Keep audit useful and limited

Audit consequential changes with actor, time, scope, before/after where appropriate and result. Redact secrets and restrict sensitive event details. Search and export respect the same permissions and retention policy as the source.

Notify someone who can act

Every actionable notification includes what changed, impact, scope, owner, time and a direct permitted destination. Informational updates can be grouped. Distinguish delivery accepted, delivered where provable, acknowledged and resolved.

Deduplicate and route deliberately

Correlate repeated signals, rate-limit noisy sources and summarize repeats without hiding escalation. Respect configured severity, subscription scope and quiet hours; define explicit critical overrides. Recovery updates reference the same incident.

Separate technical failure from service impact

A failed monitor or unknown check is not proof of a service outage. Explain evidence, last successful observation and customer impact independently. Do not auto-publish internal diagnostic detail to a public status page.

Make on-call responsibility visible

Show who is primary and backup now, the schedule timezone, next handover and uncovered intervals. Swaps and overrides have an explicit interval and conflict check. Do not promise phone wake-up reliability before delivery, acknowledgment and fallback paths are verified.

Public status is a deliberate publication

Status updates need a clear audience, affected service, impact, timeline and next update expectation. Keep a publication history and distinguish planned maintenance from incidents. A monitor can prepare a draft under configured rules; automatic publication requires explicit policy.

Use quiet visual urgency

Use text labels and restrained semantic colour for severity. Avoid sirens, flashing banners, endless animation and default browser permission prompts. Ask for notification permission when a user chooses a useful channel and explain the benefit.

Give each metric a question

Show the metric’s meaning, scope, timeframe, source and freshness. Put items requiring action ahead of decorative totals. A summary links to the same filtered source view where authorized. Do not mix readiness, performance and volume into an unexplained score.

Use honest charts

Use labelled axes, units, time ranges and comparable baselines. Bars start at zero; a deliberately restricted line-chart axis is clearly labelled. Distinguish missing data from zero and forecasts from observations. Colour has a text or pattern alternative, and useful values are accessible without hover.

Do not invent trends

Only show history retained by the source, with coverage and gaps. Display sample size and denominator for rates or scores; state the score policy/version where relevant. Do not animate a number from zero in a way that implies a live observation.

TV mode is a separate audience

Use independently scoped read-only display access, explicit expiry/revocation and aggregate data by default. No employee names, private tickets, contracts or departure details on shared screens. Show unavailable sources and freshness prominently.

Design for the viewing distance

Provide a deliberate 16:9 wallboard layout tested at 1920 × 1080 and 3840 × 2160. Use a few large summaries and readable labels, not a scaled desktop table. Subtle change transitions may help orientation; avoid mandatory carousels and constant movement.

Reports preserve approval meaning

Operational summaries, submitted time, approved time, compensation calculation, released statements and payroll export are distinct. Show units, timezone, policy version, currency, adjustments and approval history. A report does not claim money was paid unless that result is verified.

Meet contrast and reflow requirements

Text normally needs at least 4.5:1 contrast; large text may use 3:1. Meaningful graphics and control boundaries need 3:1 where required. Support 200% text resizing and reflow at 320 CSS px without loss of functionality. Test text-spacing overrides.

Make every task keyboard operable

Use logical DOM order, visible focus, a skip link and landmarks. Keep focus unobscured by sticky bars and overlays. Do not use positive tabindex. Pointer actions have keyboard equivalents; drag actions also have a simple non-dragging method.

Use comfortable targets

Aim for 44 × 44 CSS px controls and touch targets; dense desktop controls may be 36 px where spacing and purpose justify it. Meet WCAG 2.2 target-size requirements or their documented exceptions; do not use a tiny icon as the sole hit area.

Expose names, relationships and updates

Use semantic headings, lists, tables with headers and accessible form associations. Icon-only actions name the action, not the shape. Status changes are announced appropriately; charts and images provide equivalent information.

Respect motion and sensory needs

Honor prefers-reduced-motion. No essential information depends on motion, sound, colour or hover alone. Avoid flashes and autoplay media. Provide pause/stop controls for nonessential persistent movement or automatically updating presentations where required.

Keep authentication accessible

Allow password managers, paste and platform authentication aids. Avoid arbitrary memory puzzles. Explain passkey, provider and popup progress; provide recovery when the external flow closes or fails. Do not time out a user’s work without warning and a recovery path where feasible.

Say the outcome first

Use short sentences, concrete nouns and useful verbs. Explain the action and consequence next. Put implementation detail behind a relevant disclosure. Prefer one concise helper line to a paragraph that repeats the title.

Use consistent microcopy

Buttons describe the result; confirmations name scope; errors say what failed and how to proceed. Avoid vague OK, Submit, magic, bulletproof, guaranteed and blame. Completed work gets a calm receipt, not praise or confetti.

Make time unambiguous

Use locale-aware display and stable machine timestamps. Show an exact date/time and timezone for deadlines, schedules and evidence; relative time can supplement it. Let viewers distinguish their timezone from the schedule’s timezone. Define DST and period boundaries.

Localize meaning, not just strings

Keep language selection consistent with the suite. Support longer translations, plural forms, diacritics and locale number/date formatting. Do not concatenate translated sentence fragments. Keep a currency code with ambiguous symbols and never silently convert amounts.

Teach at the point of need

Offer brief contextual help and a linked guide for external setup. Show prerequisite, procedure, verification and recovery; label planned behavior separately. Keep changelogs focused on changed user behavior and migration impact.

Keep examples safe to publish

Use fictitious people, example.com domains, placeholder IDs and sanitized records in docs, screenshots, templates and fixtures. Do not copy customer data or internal policy into public examples.

Animate orientation, not decoration

Use 120 ms feedback, 180 ms state transitions and at most 240 ms for a deliberate panel movement. Prefer opacity and transforms; do not animate layout size in a busy queue. Never delay an action just to finish an animation.

Keep the first useful view lightweight

Reuse local assets, load detail when needed, bound lists and avoid loading all private data for an aggregate. Show independent results progressively. No third-party font or analytics request merely to render the core work surface.

Prevent layout and focus jumps

Reserve image and skeleton dimensions. Keep stable keys, labels and button widths during async work. Do not rerender the active input or reorder current work because a polling request finished.

Keep every touchpoint in the family

Apply the same logo, naming, token roles and content hierarchy to login, tools, Hub menu, Kitchen, Cloud Engine metadata, help, emails, exports, embeds and marketplace material. Functional documents such as invoices keep their required semantics.

Shared foundations stay shared

SDK client and runtime token copies remain byte-identical to their canonical sources. Use the shared sign-in shell. New components need documented states and keyboard behavior before adoption. Eliminate app overrides only as part of a verified migration, not by sweeping replacement.

Make extension a supported path

Give templates, stable IDs, scoped API examples, field/schema discovery, verification and failure examples. Show what a key may do and where it must be stored. Prefer a working first integration over a long catalogue of possible integrations.

Read the standard before changing UI

Read design/README.md, the relevant rules and the affected module guides before design work. Reference rule IDs in reviews. New tools use the same foundations; a new tool does not get a new design language.

Use explicit rule strength

Must is an acceptance requirement. Should is the default and may differ for a documented task-specific reason. A must exception needs a written decision, owner, affected scope, compensating measure and expiry/review date; it never authorizes a permission or safety bypass.

Record adoption honestly

Use Not reviewed, Gap found, In progress and Verified with date, commit, role, viewport and evidence. Do not label an entire app compliant after reviewing one page. Shared visual adoption and complete workflow/accessibility certification are separate evidence claims.

Verify before release

Use the acceptance checklist for role scope, workflow integrity, accessibility, privacy and visual consistency. Preserve real authorization and data-integrity regressions. Follow the existing tested-release and production-authorization workflow. A design change never grants rollout authority.

Change one source, regenerate copies

Edit standard.json and tokens.json as source; generate the browsable standard, Markdown and Hub-served copies with npm run design:build. Edit logos only in their registry. Bump the design version and changelog; bump affected modules for their releases.

Review the value of the interface

In each iteration, remove an unnecessary decision, duplicate entry or ambiguous state before adding a new configuration option. Test key jobs with an IT operator and the actual secondary roles, including employees and Finance.