SEEK Braid Interface Guidelines

Concise rules for building accessible, fast, SEEK-brand-aligned UIs with the Braid Design System.

Use MUST/SHOULD/NEVER to guide decisions.

Reference: https://seek-oss.github.io/braid-design-system/

AGENTS.md

Add AGENTS.md to your project so agents apply these guidelines during generation.

Download AGENTS.md

Technical Implementation Guidelines

The following sections (1-13) provide technical best practices for web development. Always prioritize Braid components and design tokens over custom implementations. These guidelines complement Braid usage—they don't replace it.

Key principle: If Braid provides a component or token for your use case, use it. Only apply custom solutions when Braid doesn't cover your specific need, and document such patterns following the 80/20 Rule.

0. Braid First

  • MUST: Use Braid components as primary building blocks (Button, TextField, Checkbox, RadioGroup, Tabs, Dialog, Box, Stack, Columns, Tiles)
  • MUST: Use Braid themes and tones (positive, critical, caution, neutral, info, promote) instead of custom hex colours
  • MUST: Use layout primitives instead of manual margins/padding
  • MUST: Keep code understandable to non-developers—Braid favours simple, composable APIs
  • SHOULD: Prototype in Braid Playroom before generating custom code
  • NEVER: Re-implement components already provided by Braid

1. Interactions

Keyboard

  • MUST: Full keyboard support per WAI-ARIA APG
  • MUST: Visible focus rings (:focus-visible; group with :focus-within)
  • MUST: Manage focus (trap, move, return) per APG patterns for overlays
  • NEVER: outline: none without visible focus replacement via Braid/theme

Targets & Input

  • MUST: Hit target ≥24px desktop, ≥44px mobile; expand hit area if visual <24px
  • MUST: Mobile <input> font-size ≥16px to prevent iOS zoom
  • NEVER: Disable browser zoom (user-scalable=no, maximum-scale=1)
  • MUST: touch-action: manipulation to prevent double-tap zoom
  • SHOULD: Align -webkit-tap-highlight-color with active Braid theme
  • MUST: If it looks clickable, it must be clickable—no dead visual affordances

2. Forms

Inputs & Labels

  • MUST: Use Braid form components (TextField, PasswordField, Dropdown, Autosuggest, Checkbox, RadioGroup, Textarea, MonthPicker)
  • MUST: Every control has a programmatically associated label; clicking label focuses/toggles control
  • MUST: Correct type, inputMode, and autoComplete for right keyboard/validation/autofill
  • SHOULD: Disable spellcheck for emails, codes, usernames

Hydration & Loading

  • MUST: Inputs are hydration-safe (no lost focus/value after React hydration)
  • NEVER: Block paste in <input>/<textarea> (including passwords and OTPs)
  • MUST: Loading buttons show spinner while keeping original label

Submission & Validation

  • MUST: Enter submits single focused input; in <textarea>, ⌘/Ctrl+Enter submits
  • MUST: Keep submit enabled until request starts; then disable with spinner; use idempotent endpoints
  • MUST: Accept free text, validate after—don't block typing
  • MUST: Allow incomplete form submission to surface validation errors
  • MUST: Errors inline next to fields; on submit, focus first error
  • MUST: Trim values to handle trailing whitespace

Security & Assistive Tools

  • MUST: Warn on unsaved changes before navigation
  • MUST: Compatible with password managers & 2FA; allow pasting codes; use appropriate autoComplete tokens
  • MUST: No dead zones on checkboxes/radios—label and control share one generous hit target

3. State & Navigation

  • MUST: URL reflects state—filters, tabs, pagination, expanded panels must be deep-linkable
  • MUST: Back/Forward restores scroll position
  • MUST: Links use <a>/<Link> for navigation; support Cmd/Ctrl-click, middle-click
  • NEVER: Use <div onClick> or <button> for navigation when link is semantically correct

4. Feedback

  • SHOULD: Optimistic UI for likely-to-succeed operations; reconcile on response; rollback or Undo on failure
  • MUST: Confirm destructive actions (e.g. deleting a job ad) or provide Undo window
  • MUST: Use polite aria-live for toasts/inline validation
  • SHOULD: Ellipsis (…) for options opening follow-ups ("Rename…") and loading states ("Saving…")

5. Touch & Drag

  • MUST: Generous targets, clear affordances; avoid finicky precision interactions
  • MUST: Delay first tooltip in a group; subsequent peers show instantly
  • MUST: overscroll-behavior: contain in modals/drawers to prevent scroll chaining
  • MUST: During drag, disable text selection and apply inert to dragged elements

6. Animation

  • MUST: Honor prefers-reduced-motion—provide reduced variant or disable
  • MUST: Use Braid components' built-in animations where available (e.g., Dialog, Drawer, Accordion)
  • SHOULD: For custom animations, prefer CSS > Web Animations API > JS libraries
  • MUST: Animate compositor-friendly props only (transform, opacity)
  • NEVER: Animate layout props (top, left, width, height)
  • NEVER: transition: all—list properties explicitly
  • SHOULD: Animate only to clarify cause/effect or add deliberate delight—avoid gratuitous motion
  • MUST: Animations interruptible and input-driven (no autoplay loops)
  • MUST: Correct transform-origin—motion starts where it physically should
  • MUST: SVG transforms on <g> wrapper with transform-box: fill-box
  • NEVER: Override Braid component animations unless documenting a justified custom pattern

7. Layout

  • SHOULD: Use Braid layout primitives (Box, Stack, Columns, Tiles, Inline, Spread, ContentBlock, PageBlock, Page, Bleed)
  • SHOULD: Optical alignment—adjust ±1px when perception beats geometry
  • MUST: Deliberate alignment to grid/baseline/edges—no accidental placement
  • SHOULD: Balance icon/text lockups (weight/size/spacing/tone)
  • MUST: Verify mobile, tablet, desktop, wide (simulate ultra-wide at ~50% zoom)
  • MUST: Respect safe areas (env(safe-area-inset-*))
  • MUST: Avoid unwanted scrollbars; fix overflows at source
  • SHOULD: Flex/grid over JS measurement for layout

Spacing Scale

Braid's standard white space scale: none, xxsmall, xsmall, small, medium, gutter, large, xlarge, xxlarge, xxxlarge

Responsive example:

<Stack space={{ mobile: 'small', tablet: 'medium', desktop: 'large' }}>

8. Content & Accessibility

Content & States

  • SHOULD: Inline help first; tooltips as last resort for additional hints
  • MUST: Skeletons mirror final content structure to avoid layout shift
  • MUST: <title> matches current page context
  • MUST: No dead ends—always offer next step or recovery path
  • MUST: Design empty, sparse, dense, and error states explicitly

Typography & Numbers

  • SHOULD: Curly quotes (" "); avoid widows/orphans (text-wrap: balance)
  • MUST: font-variant-numeric: tabular-nums for number comparisons (salaries, counts, metrics)

Status & Semantics

  • MUST: Redundant status cues—never rely on colour alone; pair tones with icons and/or text
  • MUST: Accessible names exist even when visuals omit labels; icon-only buttons need aria-label
  • MUST: Use … character (not ...)

Headings, Links & Locale

  • MUST: Hierarchical headings (<h1>–<h6>); include "Skip to content" link
  • MUST: scroll-margin-top on headings to avoid sticky header occlusion
  • MUST: Resilient to user-generated content—handle short, average, and very long strings
  • MUST: Locale-aware formatting (Intl.DateTimeFormat, Intl.NumberFormat)—use language preferences, not IP
  • MUST: Non-breaking spaces for glued terms (10 MB, keyboard shortcuts, brand names)

Accessibility Tree

  • MUST: Accurate aria-label/aria-labelledby; decorative elements use aria-hidden="true"
  • MUST: Prefer native semantics (button, a, label, table) before ARIA roles

9. Content Handling

  • MUST: Text containers handle long content (truncate, line-clamp, break-words)
  • MUST: Flex children need min-width: 0 to allow truncation
  • MUST: Handle empty states—no broken UI for empty strings/arrays

10. Performance

  • SHOULD: Test iOS Low Power Mode, macOS Safari, lower-end devices, throttled networks
  • MUST: Measure reliably—disable extensions that skew runtime
  • MUST: Track and minimize React re-renders (React DevTools/React Scan)
  • MUST: Batch layout reads/writes; avoid reflows/repaints
  • MUST: Mutations (POST/PATCH/DELETE) target <500ms; show progress if longer
  • SHOULD: Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
  • MUST: Virtualize large lists (>50 items) or use content-visibility: auto
  • MUST: Preload above-fold images; lazy-load the rest; prevent CLS with explicit dimensions

11. Dark Mode & Theming

  • MUST: Use Braid's theme system (apac, seekJobs, seekBusiness) instead of custom theme implementations
  • MUST: For dark themes, Braid handles color-scheme: dark automatically—don't override
  • SHOULD: <meta name="theme-color"> matches page background of active Braid theme
  • NEVER: Manually style native form elements—use Braid's Dropdown, TextField, etc. which handle theming automatically

12. Hydration

  • MUST: Inputs with value need onChange (or use defaultValue)
  • SHOULD: Guard date/time rendering against hydration mismatch

13. Design Tokens & Visual Consistency

  • MUST: Use Braid's elevation tokens for shadows and depth—never custom box-shadow values
  • MUST: Use Braid's border radius tokens (standard, large, xlarge, full) via borderRadius prop
  • MUST: Use Braid's semantic colour tokens—never hardcode hex/rgb values
  • MUST: Meet WCAG AA contrast requirements (4.5:1 for normal text, 3:1 for large text and UI components)
  • MUST: Use Braid tones (critical, caution, positive, neutral, info, promote) for semantic colour
  • MUST: For data visualizations, ensure colour-blind-friendly palettes with redundant encodings (patterns, labels, shapes)
  • SHOULD: Use Braid's Card component for elevated surfaces rather than custom shadows
  • NEVER: Override Braid's design tokens with custom values unless documenting a justified custom pattern

SEEK Resources