dembrandt/dembrandt-skills

# Algorithmic Colour Palette

A brand palette of 2–3 colours is not enough for a UI. You need shades for states (hover, active, disabled), neutrals for backgrounds and borders, and semantic colours for status. Deriving these algorithmically from the brand colours produces a palette that feels coherent — everything is visually related to the brand rather than pulled from a generic grey or a stock colour library.

> **Don't guess the seed colours — extract them (dembrandt engine, optional).** If the brand already exists on the web, pull its *real* palette off the live site instead of eyeballing a hex: `get_color_palette` (or the `extract-design` skill) returns the actual computed brand and neutral colours from the DOM, which you then expand with the methods below. See [`extract-design`](../extract-design/SKILL.md) for setup.

## Deriving Interactive State Colours

From each brand colour, generate at minimum three variants: base, darker (hover/active), lighter (tint/background).

### Method: HSL adjustment

```
base:    hsl(H, S%, L%)

# The App Shell

The shell is the part of the screen that does not change when the user navigates: the bar across the top, whatever sits in it, and in heavy tools a strip along the bottom. Everything between them belongs to the application. The shell is small, and it carries more weight than its size suggests — it is the only thing a user sees on every screen of every tool.

## The Shell Belongs to the Estate, Not to the App

One company rarely has one application. It has a public site, a shop, a customer portal, an internal admin tool, and something older that nobody wants to touch but that people depend on. The user crosses between them during a working day, and each crossing is where the sense of one company either holds or breaks.

**The rule: the top bar is estate-level furniture. The app owns everything below it.** An app that restyles the shared bar to fit its own look has taken something that was not its to change — the bar's job is to be the one fixed point.

But *fixed* is not the same as *full*. What the shell contains may shrink to whatever of its jobs are still unanswered here; what remains is identical — same position, same behaviour, same wording. Quantity flexes, treatment does not.

This also settles a hierarchy question that otherwise gets argued per team. Anything *above* the application in scope lives in the shell; anything *within* the application lives in the app's own navigation.

| Lives in the shell (above the app) | Lives in the app's own nav (within it) |

# Authentic Product Representation

The fastest way to lose a visitor's trust is a product visual that is obviously staged. People have seen thousands of landing pages; they recognise a fabricated dashboard, a screenshot full of lorem ipsum, or a "terminal" that prints things the real tool never would. The visual that converts is the one that looks like it was screenshotted straight out of the working product — because it was, or because it was built to be indistinguishable from it.

The principle is simple: **the visual is the product, not a poster of it.** Every shortcut away from that — invented data, decorative chrome, a capability shown that does not exist — is a small withdrawal from the trust account.

This skill governs whether a visual is *credible*; what it has to accomplish in the page's argument comes from the product narrative framework in [[layout-paradigms-and-consistency]]. A fabricated proof point proves nothing.

---

## Design With Real Content

Idealised placeholder content hides the problems your design will actually face.

# Brand Visual Language

Visual shape communicates personality. A rounded corner says something different to the user than a sharp one — and that message arrives before they read a single word. The shapes in typography, border-radius, and iconography should tell a consistent story.

## Shape Language

| Shape | Tone | Associated with |
|---|---|---|
| **Rounded, pill-shaped** | Friendly, approachable, playful, modern | Consumer apps, health, kids, lifestyle, social |
| **Softly rounded (8–12px)** | Professional, warm, accessible | SaaS, productivity, general B2B |
| **Lightly rounded (2–4px)** | Precise, structured, efficient | Enterprise tools, finance, data platforms |
| **Sharp / no radius** | Technical, serious, authoritative | Developer tools, security, industrial |

Every component — cards, inputs, modals, badges — should follow the same radius logic.

# Button and Interactive Element States

Every interactive component must have a complete, visually distinct state for each interaction mode. Missing or ambiguous states make the UI feel unfinished and reduce user confidence.

## The Six States

| State | Trigger | Visual signal |
|---|---|---|
| **Rest** | Default | Base colour, cursor: pointer |
| **Hover** | Mouse over | Slightly darker, subtle background shift |
| **Active / Pressed** | Mouse down / tap | Noticeably darker, slight scale-down |
| **Focus** | Keyboard navigation | Visible focus ring, no change to fill |
| **Disabled** | Not available | Low contrast, cursor: not-allowed, no interaction |
| **Loading** | Async action in progress | Spinner or pulse, non-interactive |

# Clone a Website, Accurately

One-click cloners return a lookalike: it resembles the page, and nothing in the
process ever checked whether it matches it. This skill produces a different
artifact — values traceable to the source, and a diff that says what is still
wrong.

**The one rule: if the page states a value, read it. If it does not, and only
then, decide it.** A rebuild done that way is finished when the diff is empty,
which you can check, rather than when it looks about right, which nobody can.

Only the rebuild step cares whether the target is Figma, Penpot or a codebase.
Everything else is the same job.

# Color Mode and Theme

## The Decision: Light, Dark, or Both

Color mode is a brand and context decision, not a personal preference. Make it deliberately.

### Light (white design)
**Tone:** Open, trustworthy, content-forward, accessible, professional  
**Fits:** Marketing sites, e-commerce, editorial, SaaS with mixed audiences, consumer products, B2B tools where the content is the focus

Light mode is the safer default for most products. It performs better in bright environments and has broader accessibility coverage out of the box.

### Dark (dark design)
**Tone:** Premium, focused, immersive, technical, high-contrast data  

# Component Family Consistency

Every interactive component in a product — buttons, inputs, selects, checkboxes, radio buttons, pills, badges, tags, calendars, date pickers, sliders, toggles — belongs to the same visual family. They share a common design DNA. A user should be able to look at any component and feel that it belongs to the same product as every other component.

When components are designed in isolation without shared tokens, the product feels assembled from parts rather than built as a whole.

## Reuse Before You Build a New Component

The rule, stated as directives:

> Use existing components from the component library. Build a new one only after the audit below finds nothing that fits.
> Do not invent a new visual presentation if a fitting component exists.
> With every UI code change, check the changed files and their nearest sibling components for matching use cases, and keep them coherent. Report drift found elsewhere instead of fixing it unasked.
> The goal is a UI that strictly follows the design system, with no ad-hoc components.

# Coordinated Data Views

Some data has more than one natural representation. A set of locations has both a map and a list. A dependency network has both a diagram and a node table. A dataset has both a chart and a raw table. When both representations are genuinely useful for different tasks, show them simultaneously and keep them synchronized — this is called a coordinated view.

The core rule: **any selection or highlight made in one view is immediately reflected in the other.**

---

## When to Use Coordinated Views

Use coordinated views when:

1. The two representations serve different tasks — the table is for finding/scanning; the visual view is for understanding arrangement or relationships
2. Users will frequently move between the two — not just glance at one occasionally

# Data Display and Selection

Complex data collections — products, files, users, orders, tasks — have no single correct view. Different tasks call for different views. Browsing benefits from grid; comparing details benefits from list or table; bulk management benefits from a dense table with mass actions. Give users the choice.

---

## View Modes

Offer multiple views when the data has both visual and detailed dimensions.

| View | Best for | When to default |
|---|---|---|
| **Grid** | Visual items: products, images, files, cards | When items are visually distinct and browsing is the primary task |
| **List** | Moderate detail: tasks, emails, articles | When a key piece of text or metadata drives selection |

# dembrandt — UX Pipeline Orchestrator

> Concept by [@VictorGjn](https://github.com/VictorGjn).

Routes multi-concern UI/UX tasks through six ordered stages. Each stage loads sub-skills on demand — only what the task actually needs.

**When to use this skill vs a sub-skill directly:**

- Multi-concern task ("design review", "audit interface", "build UI") → use this orchestrator
- Single-concern task ("check my colour palette", "review button states") → go directly to the sub-skill
- Brand-to-token-to-spec pipeline with a URL or DESIGN.md → use `generate-ui-from-brand` instead
- Reproducing an existing page rather than designing one → use `clone-website` instead
- Reading the tokens off a live site and nothing more → use `extract-design` instead

# Domain Expert Configuration

A domain expert configuration UI exposes the parameters of a complex system — an optimisation algorithm, a planning engine, a simulation — to users who understand the problem domain deeply but have no knowledge of the system's internals.

The challenge: the system's parameters are defined in technical terms (weights, thresholds, flags, tolerances). The user thinks in domain terms (how long to wait, when to retry, how to group results). The UI must translate between these two vocabularies — always favouring the user's language.

---

## The Core Principle: Domain Language Over Technical Language

Every parameter label, tooltip, and error message should describe what the parameter *means in the user's world*, not what it *does inside the system*.

| Technical label | Domain label |
|---|---|

# Elevation and Depth

Elevation uses shadow and layering to communicate that an element sits above the base surface — giving UI a sense of physical depth. Combined with border-radius, it creates the tactile quality that makes cards graspable, modals clearly floating, and dropdowns feel like they've appeared on top of content.

## The Elevation Scale

Define a small set of elevation levels as tokens. Each level maps to a specific UI role.

| Level | Token | Shadow | Role |
|---|---|---|---|
| 0 | `--shadow-none` | none | Flat surface, inline elements |
| 1 | `--shadow-xs` | `0 1px 2px rgba(0,0,0,0.06)` | Subtle card, table row hover |
| 2 | `--shadow-sm` | `0 1px 3px rgba(0,0,0,0.10), 0 1px 2px rgba(0,0,0,0.06)` | Card, input focus ring area |
| 3 | `--shadow-md` | `0 4px 6px rgba(0,0,0,0.08), 0 2px 4px rgba(0,0,0,0.06)` | Dropdown, popover |

# Extract Design — Dembrandt

Dembrandt runs a headless Chromium browser against any URL, walks up to thousands of DOM elements, reads computed CSS, and returns a structured design system: colors with confidence scoring, typography styles, spacing scale, border radius, borders, shadows, and interactive component styles.

## How to Run

```bash
# Zero-install — npx fetches the package on first run (lowest friction)
npx -y dembrandt https://dembrandt.com

# Or install once (global), then call `dembrandt` directly
npm i -g dembrandt

# Basic extraction — outputs to terminal

# Form Design

Forms are where users give the product data. Every unnecessary obstacle between the user and a completed form is a failure. The design goal is to make correct input easy and incorrect input obvious — before the user submits.

---

## The Three Guidance Layers

Each layer serves a distinct purpose. Do not collapse them.

### Layer 1 — Helper Text
Explains *what* to enter. Appears below the input, always visible, in small secondary text.

```

# generate-ui-from-brand

**Type:** Pipeline / Orchestrator  
**Input:** URL or existing DESIGN.md  
**Output:** Actionable UI spec with decisions made

---

## Step 1 — Extract

**If a URL is provided and Dembrandt MCP is available:**

All MCP extraction tools are async — they return a `job_id` immediately. Poll `get_job_status` until `status` is `"completed"`, then read `result`.

# Gestalt UI Organisation

UI should be organised so that the visual structure communicates relationships — which commands, controls, and elements belong together — without requiring users to read labels or documentation.

## Core Gestalt Principles for UI Layout

### 1. Proximity
Elements that are close together are perceived as a group.

- Place related controls (e.g. Bold / Italic / Underline) close together with minimal gap between them
- Separate unrelated groups with larger whitespace
- Do not use lines or borders as the primary grouping mechanism — proximity alone should convey the relationship

**Example:** A toolbar with `[Cut] [Copy] [Paste]` grouped tightly, then a wider gap before `[Undo] [Redo]`, communicates two distinct command groups without any visual divider.

# Global Toolbar Controls

## What Belongs Here

Global controls affect the entire product experience but are not the user's primary task. They are reached occasionally — once per session or less — and should not compete visually with primary navigation or content.

Typical global toolbar controls:
- **Currency selector** (e-commerce, financial tools)
- **Language / locale switcher**
- **Region or market selector**
- **Unit system** (metric / imperial)
- **Theme toggle** (light / dark)
- **Accessibility preferences** (font size, contrast)

# Information Architecture

In small products, users find their way by exploring. In large applications — multi-module SaaS, ERPs, analytics platforms, marketplaces — exploration breaks down. The structure itself must do the navigational work. Information architecture is the design of that structure: what exists, what it is called, and how it relates to everything else.

Good IA is invisible. Users find what they need without thinking about the structure. Bad IA forces users to hold a map in their head.

---

## Naming is Design

The names given to entities, sections, and actions are one of the most consequential design decisions in a large application. Bad names create cognitive friction on every visit.

**Principles:**

# Layout Paradigms and Consistency

A layout is not a neutral container you pour content into. The layout paradigm you choose is part of the argument about how the content should be read, compared, and acted on. Two products showing the same data can communicate completely different things depending on whether that data is a feed, a table, or a board.

This skill operates at the **macro scale** of consistency. It sits above [[component-family-consistency]] (the *meso* scale — buttons and inputs sharing one DNA) and above token-level consistency like [[button-states]], [[status-colors-and-errors]], and [[modular-scale-typography]] (the *micro* scale). Consistency is not one rule — it is the same discipline applied at three altitudes.

## Consistency operates at three scales

| Scale | What stays consistent | Where it lives |
|---|---|---|
| **Estate** | Brand chassis and shared shell across *separate applications* | *this skill, Part 3* + [[app-shell]] |
| **Macro** | Layout paradigm and page skeleton across screens | *this skill* |
| **Meso** | Component family — shared radius, height, colour logic | [[component-family-consistency]], [[brand-visual-language]] |
| **Micro** | States, tokens, type scale, semantic colours | [[button-states]], [[status-colors-and-errors]], [[modular-scale-typography]], [[algorithmic-color-palette]] |

# Loading States and Perceived Performance

Users don't mind waiting as much if they understand *what* they are waiting for and *how much* progress is being made. Perceived performance is the design work of making a system feel faster than it actually is.

---

## Choosing the Right Loading State

| Wait Duration | Best Pattern | Use for |
|---|---|---|
| **Short (< 1s)** | **Inline Spinner / Loader** | Button actions, small updates, quick data fetches |
| **Medium (1s – 3s)** | **Skeleton Screen** | Cards, lists, dashboards, profile pages |
| **Long (> 3s)** | **Determinate Progress Bar** | File uploads, complex exports, heavy processing |
| **Full Page** | **Staggered Entry / Animated Sections** | Initial app load, hero sections, immersive transitions |

# Marketing and Product Are Two Surfaces of One Brand

The public site sells; the product is used. A visitor reads one marketing page for ninety seconds and leaves. An
operator opens the same brand every morning and stays for hours. Designing both to one specification produces
either a brochure that is exhausting to work in or a product screen that cannot sell anything.

So the two surfaces *should* diverge. The question is never whether, it is **which layer is allowed to diverge**.

Marketing and product are the pair that forces the question, because they are the two nobody can pretend are the
same job. But the rule underneath is not about two. Most brands run four or five surfaces: the site, the product,
the documentation, the transactional email, the status page, sometimes a sales deck. Each one is a different job
for a different reader at a different moment. **The brand owns the layer; every surface chooses from it.** Adding
a sixth surface then changes nothing about the rule, which is the test of whether the rule was right.

# Micro-Interactions

A micro-interaction is a moment. A checkbox that draws its checkmark. A heart that pulses when liked. A toggle that eases into place with a little overshoot. A confetti burst on completing a goal. These moments are small in duration — 200–600ms — but they communicate that the product was made by people who cared.

The reference is always the natural world. Nothing in nature snaps instantly. Everything has weight, momentum, and a moment of settling.

---

## What Makes a Good Micro-Interaction

A micro-interaction earns its place when it:

1. **Confirms an action** — makes the result of a click, tap, or input unmistakably clear
2. **Rewards a milestone** — celebrates something the user worked toward

# Modal and Overlay Patterns

Overlays appear above the main content layer. They range from lightweight popovers (non-blocking, anchored to a trigger) to full blocking modals (require a user response before the app continues). Choosing the right overlay type for the task prevents unnecessary interruption and keeps the user oriented.

---

## The Overlay Hierarchy

Choose the lightest type that satisfies the task. Heavier overlays carry higher cognitive cost.

| Type | Blocks background | Anchored to trigger | Typical content | Dismiss with |
|---|---|---|---|---|
| **Tooltip** | No | Yes | 1–2 lines of explanatory text | Cursor leave / focus out |
| **Popover** | No | Yes | Short interactive content: a form field, a picker, a small list | Click outside, Escape, explicit close |

# Modular Scale Typography

Typography feels cohesive when all font sizes are related to each other through a single mathematical ratio. Without a scale, sizes get picked arbitrarily and the result feels visually noisy — headings that don't contrast enough, body text too close in size to captions, labels that blend into content.

## What Is a Modular Scale

A modular scale starts from a **base size** and multiplies or divides by a **ratio** to generate every size in the system.

```
size(n) = base × ratio^n
```

Every size is thus a deliberate step away from the base — not a guess.

# Motion and Storytelling in UI

Animation and motion are not decoration — they are communication. When applied with the same discipline as typography or colour, they tell the user what is happening, where to look, and what the product feels like to use. The source material — Disney's 12 principles, cinematic language, comic book conventions — is centuries of accumulated knowledge about how to communicate through movement and sequence.

The key word is **subtlety**. In UI, motion should be felt, not watched.

---

## Disney's 12 Principles Applied to UI

### 1. Squash and Stretch
Objects compress on impact and extend on acceleration. In UI: a button that scales down slightly on press and springs back communicates physicality and responsiveness.

```css

# Nielsen's 10 Usability Heuristics

Foundational principles for evaluating and designing usable interfaces. Apply these as a review checklist and as design constraints from the start — not only as a post-hoc audit tool.

---

## 1. Visibility of System Status

The design should always keep users informed about what is going on, through appropriate feedback within a reasonable amount of time.

Users cannot make good decisions without knowing the current state of the system. Trust is built through clear, timely feedback.

**In practice:**
- Show loading states, progress indicators, and completion confirmations

# Notifications and Recovery

When something changes — success, failure, or anything in between — the user must know. And when something goes wrong, they must always have a path forward. A notification without a recovery action is just an apology.

---

## Pattern Selection

| Pattern | When to use | Dismissal |
|---|---|---|
| **Toast** | Transient result of a user action (saved, sent, deleted) | Auto-dismiss 4–6s, manual close |
| **Inline error** | Field-level validation, form errors | Clears on correction |
| **Alert banner** | Persistent issue affecting the current context | Manual dismiss or resolved state |
| **Modal / dialog** | Blocking error requiring a decision before continuing | User action required |

# Operational Expert Tool UI

An operational expert tool is software used by trained domain specialists — warehouse operators, dispatchers, planners, analysts — as their primary work surface, often for the entire working day. These users are not beginners discovering a product; they are professionals executing a defined job with the tool as their instrument.

This is a fundamentally different design context from consumer software or occasional-use SaaS. The design priorities are reversed: density and speed of action take precedence over discoverability and visual spaciousness.

---

## Primary Design Principles

### 1. Information over whitespace

An expert user does not need breathing room to orient themselves — they know the tool. Every pixel of empty space is a missed opportunity to show data they need to act on.

# Performance and Web Vitals

## Run a Lighthouse Audit

```bash
# CLI audit — outputs JSON and HTML report
npx lighthouse https://example.com --output html --output-path ./lighthouse-report.html

# Headless, useful in CI
npx lighthouse https://example.com --chrome-flags="--headless" --output json --output-path ./report.json

# Audit specific categories only
npx lighthouse https://example.com --only-categories=performance,accessibility,seo
```

# Real-World Metaphors in UI

UI patterns borrowed from the physical world reduce the learning curve because users already know how they work. A card feels like something you can pick up. A carousel feels like flipping through a stack. A drawer feels like it slides out from the side. These metaphors carry affordance — the user knows what to do before reading any instructions.

Use them deliberately, not decoratively.

## Common Metaphors and When to Use Them

### Card
A card is a bounded, self-contained unit of content — like a physical index card or a product on a shelf.

**Use when:**
- Content items are discrete and comparable (products, people, articles, tasks)
- Each item needs to be scanned quickly and potentially acted on

# Repeated Component Alignment

When a component is rendered many times — a card grid, a list, a table, a nav menu, a row of KPI tiles, a feed — it stops being a single box and becomes a **pattern**. The value of a pattern is rhythm: the eye learns the layout once and scans the same slot across every instance (the title row, the price row, the action row). Variable content length breaks that rhythm unless the component is built to absorb it.

The principle is general. A **card** is the most common case, but the same rule governs list rows, table cells, nav items, tiles, comment entries, dashboard widgets, search results — anything repeated. Treat each as a **fixed slot model**, not a free-form container.

The goal: **content of any length, instances that look identical.** This is partly content production (write to a target length) and partly layout engineering (build slots that tolerate the variance). This skill covers the layout half and where the two meet.

---

## The Slot Model

Name the slots once and treat them as a contract every instance honours. A product card, as a worked example:

# Responsive Paradigms

Mobile, tablet, and desktop are fundamentally different interaction contexts. The input method, screen real estate, viewing distance, and session intent all differ. Responsive design is not the same layout at different widths — it is a different design decision at each breakpoint.

## The Three Paradigms

### Mobile (< 768px)
- **Input:** Touch — fingers, not a cursor. Tap targets ≥ 44×44px.
- **Navigation:** Bottom tab bar (thumb reachable) or hamburger drawer. Top navigation is hard to reach.
- **Session:** Often interrupted, task-focused, shorter. Show the most important thing first.
- **Content:** Single column. Vertical scroll only. No hover states.
- **Primary action:** Floating action button (FAB) or full-width button at the bottom of the screen.

### Tablet (768px–1024px)

# Scroll Areas

## Avoid Scroll Areas by Default

Scroll containers inside a layout — panels, drawers, tables, modals with inner overflow — create friction. Users must discover that a region scrolls, manage multiple independent scroll positions simultaneously, and context-switch between scroll areas on the same screen.

**Default: let the page scroll.** A single page-level scroll is universally understood and requires no discovery. Before introducing an inner scroll area, ask whether the layout can be restructured so the page itself handles the overflow.

Alternatives to inner scroll:
- Pagination or load-more for long lists
- Collapsible sections (accordion) for long detail panels
- A separate page or route for content that would otherwise fill a scroll area
- Progressive disclosure — show less by default, expand on demand

# Semantic HTML and SEO

Good HTML is not just markup — it is the contract between your content, search engines, assistive technologies, and the browser. Semantic HTML, correct metadata, and progressive enhancement make UI resilient, findable, and accessible by default.

---

## Semantic HTML5

Use the element that describes the content's meaning, not just its appearance.

### Document structure
```html
<header>       <!-- site header, logo, primary nav -->
<nav>          <!-- navigation links -->

# Sizing Units

## The Question the Unit Answers

A unit is not a formatting preference. It is a declaration of what happens to a value when the user enlarges text.

- `rem` — this value belongs to the text and must grow with it.
- `px` — this value belongs to the screen and must stay put.
- `%`, `fr`, `ch`, `clamp()`, `min()` — this value belongs to the available space.

Pick the unit by answering that question, not by picking a house style and applying it everywhere. Both absolutist positions — all-rem and all-px — produce defects, and they are different defects.

## Zoom Is Not the Font-Size Setting

# Status Colours and Error Design

## Keep the Colour Set Small

Every status colour added to a system is a cognitive burden on the user. They must learn what each colour means, remember it, and interpret it correctly under stress — which is exactly when errors occur.

**The minimal set that covers almost everything:**

| Colour | Semantic meaning | Always means |
|---|---|---|
| **Red** | Error / failure / destructive | Something went wrong, or this action cannot be undone |
| **Orange / Amber** | Warning | Something needs attention before proceeding |
| **Green** | Success / positive | Action completed, state is healthy |
| **Blue** | Info / neutral status | Informational, no action required |

# Sticky and Fixed Elements

## position: fixed vs position: sticky

| Property | Behaviour | Use for |
|---|---|---|
| `position: fixed` | Removed from document flow. Always stays at the same viewport position regardless of scroll or parent. | Global navigation header, bottom toolbar, floating action button |
| `position: sticky` | Stays in document flow until it hits its scroll threshold, then locks in place. Returns to flow when parent scrolls past. | Table column headers, section headings in a long list, in-page toolbars within a scroll container |

**Prefer `sticky` over `fixed`** when the element belongs to a specific section or scroll context. Fixed elements sit above everything and affect the entire viewport — use them only for truly global UI.

## Top — Navigation Header

The global navigation header is the most common fixed element. It should:

# Surface Separation

A surface — a card, a panel, a toolbar, a row — needs to read as distinct from whatever sits behind it. There are exactly three ways to achieve that, and the mistake is almost always using more than one at full strength rather than choosing badly between them.

## Pick One Strategy Per Surface

| Strategy | Mechanism | Reads as | Best for |
|---|---|---|---|
| **Border** | 1px line at the boundary | Precise, drawn, documentary | Dense UI, tables, forms, anything where the edge itself carries meaning |
| **Elevation** | Shadow implying height | Floating, temporary, above | Modals, dropdowns, popovers, drag states |
| **Fill** | Contrasting background tone | Grouped, embedded, part of the page | Sections, sidebars, alternating rows, inline callouts |

Each answers a different question. A border says *where the surface ends*. An elevation says *how far above the page it sits*. A fill says *what it belongs to*. Choose based on which question the user actually has.

# Tab Navigation

Tabs organise related content under a shared context. The tab strip communicates the full set of available views; switching tabs swaps the content panel without a page navigation. They work best when all views share a heading, a primary action, or a common subject — tabs that have nothing to do with each other belong in separate pages.

---

## When to Use Tabs — and When Not To

| Use tabs when… | Use something else when… |
|---|---|
| 2–7 views share a common context (same record, same settings section) | There are more than 7–8 tabs — use a sidebar or section nav instead |
| Users switch between views frequently during a session | The content is sequential (use a stepper/wizard instead) |
| All tabs are equally valid entry points | One view is clearly primary — put the rest in a secondary nav or overflow |
| The views share a header or set of page-level actions | Each "tab" requires a different header and layout — use separate pages |

# UI Context and Scope

Users need to know three things at all times:
1. **Where am I?** — current location in the product hierarchy
2. **What context am I in?** — which section, record, or workspace is active
3. **What will my actions affect?** — scope of changes before committing them

When these are unclear, users make mistakes, feel lost, and lose trust in the product.

## Communicating Hierarchy with Visual Structure

### Lines and Dividers
Horizontal rules and borders signal the boundary between sections. Use them to separate content areas that belong to different contexts — not just for decoration.

# UI Density

Density describes how much information and how many interactive elements appear in a given area. The right density is not a universal standard — it depends on platform, user type, and session context.

## Platform Defaults

| Platform | Default density | Reason |
|---|---|---|
| Desktop | Medium to high | Large screen, precise input, often primary work surface |
| Tablet | Medium | Touch input, larger than phone but less than desktop |
| Mobile | Low | Small screen, touch targets need space, interrupted sessions |

Never port a dense desktop layout directly to mobile. Remove, collapse, or deprioritise features rather than shrinking them.

# User Flows and Guided Paths

Related features that belong together should be experienced as a single coherent journey — not as separate screens the user has to navigate between manually. A well-designed flow feels inevitable: each step leads naturally to the next, the user always knows where they are and what comes next, and the path fits the product's information hierarchy.

## When to Guide vs. When to Let Users Explore

| Scenario | Pattern |
|---|---|
| Linear process with a clear end goal (checkout, signup, setup) | Guided step-by-step flow or wizard |
| Complex task that benefits from breaking into stages | Wizard with progress indicator |
| Feature discovery across an existing product | Contextual tooltips or coach marks |
| User returning to complete something they started | Resume prompt with clear re-entry point |
| Open-ended exploration (dashboard, settings) | Free navigation — do not force a flow |

# Visual Emphasis and Hierarchy

Every screen has a most-important thing. Visual hierarchy is the design work that makes sure the user's eye finds it first — without requiring the user to read everything and decide for themselves.

Emphasis is achieved through **size**, **colour**, **weight**, **contrast**, and **position**. These tools work because they are relative: an element looks important because it differs from what surrounds it.

## The Hierarchy Ladder

Design every action group and content area with a clear hierarchy:

| Level | Role | Visual treatment |
|---|---|---|
| **Primary** | The one action the user should most likely take | Filled, brand colour, largest button in the group |
| **Secondary** | An alternative action of moderate importance | Outlined or ghost, neutral colour, same or slightly smaller size |

# WCAG Accessibility (EN 301 549 / European Standard)

## The Standard

The **European Accessibility Act (EAA)** requires digital products and services in the EU to meet **EN 301 549**, which references **WCAG 2.2 Level AA** as the technical baseline. This is not optional — it is a legal requirement for products operating in the EU market.

**Default: always build to WCAG 2.2 AA.** Deviating requires explicit, documented justification. Do not skip accessibility requirements because of timeline pressure or design preference.

WCAG 2.2 AA organises requirements under four principles: **Perceivable, Operable, Understandable, Robust**.

---

## Perceivable