UI Elements Lab · Newcomer → Expert

Frontend UI elements — interactive school

Learn the names, jobs, states, and “agent language” for the controls that make web apps feel real. Examples draw from your Map Builder when useful, but the catalog is wider than this repo.

NEWCOMER

See it, click it, learn its name.

FLUENT

Know variants, states, and when to use which.

EXPERT

Accessibility, design systems, precise agent prompts.

How to study

Open each module. Play with every live demo.
Read the Say to an agent box — copy those phrases later.
Do the quiz. Mark progress in the sidebar (auto-saves in this browser).
Finish with Mastery Challenge.

Catalog (what’s inside)

Track	Modules
Foundations	Anatomy & states · Tokens & hierarchy
Actions	Buttons · Links vs buttons · Segmented & icon actions
Inputs	Text fields · Choice controls · Sliders · Files & colour
Feedback	Badges & chips · Progress & loading · Toasts & alerts
Containers	Tabs & accordion · Modal · Drawer · Tooltip & popover
Navigation	Nav patterns · Steps & pagination
Data & maps	Tables & toolbars · Map UI (repo-flavoured)
Expert	Accessibility · Design systems · Mastery

Mental model: every control has anatomy (parts), variants (looks), states (default/hover/focus/disabled/error/loading), and a job (what the user accomplishes). Experts talk in those four words.

Foundations · NEWCOMER

Anatomy & interactive states

Before names of widgets, learn the shared language of “how a control behaves.”

Word	Meaning	Example
Affordance	Looks like you can use it	Raised button vs plain text
Hit target	Clickable/tappable area (aim ≥44×44px on touch)	Icon button padding
Focus ring	Outline for keyboard users	Tab into a field
Feedback	UI answers your action	Toast, spinner, colour change
Hierarchy	What looks most important	Primary vs ghost button

State matrix (live)

Same button, different states — experts always specify which state they mean.

Button stateshover · focus · active · disabled · loading

Default

Hover me

Focus (Tab)

Disabled

Loading

Also learn: error, success, selected / pressed, read-only, empty.

Say to an agent“Add a loading state to the Generate map button: disable click, show spinner, keep layout width stable (no jump).”

What is a focus ring for?

Decoration only Showing keyboard users which control is active Making buttons green

Focus rings are an accessibility essential — never remove them without an equal replacement.

Foundations · FLUENT

Design tokens & visual hierarchy

Tokens are named design decisions. Hierarchy decides what the eye notices first.

Your builder-style tokens (live)

--olive primary --amber accent --paper surface --bad danger --muted

Roles beat raw hex: say “use danger token” not “make it that red.”

:root {
  --olive: #6b8e23;   /* primary action */
  --paper: #f6f5ef;   /* page surface */
  --ink: #23281f;     /* body text */
  --line: #e1dfcf;    /* borders */
}

In your repo — index.html defines these in :root. Asking agents to “keep olive/paper tokens” stops random purple themes.

Hierarchy recipe

One primary action per view region (e.g. Generate map)
Secondary for safe alternatives (Cancel, Export CSV)
Ghost/tertiary for low emphasis
Danger only for destructive actions

Say to an agent“Don’t invent new colours — extend existing CSS variables. Primary CTA uses --olive; destructive uses --bad.”

Actions · NEWCOMER

Buttons

A button performs an action on this page. Master variants first — they are half of all UI talk.

Live variants click each

Click a button — feedback appears here.

Variant	Job	Repo-ish example
Primary	Main thing to do	Generate map / Send to builder
Secondary	Alternative, safer	Export CSV, Cancel
Ghost / tertiary	Low emphasis	“Other input methods”
Danger	Destructive	Clear all pins
Icon button	Compact toolbar action	Save draft floppy, What's new bell
FAB	Floating dominant action (mobile)	Rare in your maps; common in mobile apps

Icon button & FAB

Expert: Prefer <button type="button"> inside forms so it doesn’t submit. Icon-only buttons need aria-label. Don’t use disabled to hide permission errors without explanation.

Say to an agent“Add a ghost button under the GI card labelled Other input methods that expands CSV + grid. Keep primary Add markers on map unchanged.”

How many primary buttons should a focused section usually have?

As many as possible Zero — only links About one clear primary

One primary keeps hierarchy clear. Secondaries can sit beside it.

Actions · FLUENT

Links vs buttons

Newcomers mix these up. Experts almost never do.

Link (<a href>)

Goes somewhere — new page, URL, download location, in-page anchor.

Example in-page link

Button (<button>)

Does something here — open modal, generate map, toggle layer.

Anti-pattern: <div onclick> pretending to be a button — breaks keyboard & screen readers. Use real elements.

Say to an agent“Open Coordinate Picker should stay a real link to coord_picker.html in a new tab. Generate map must remain a button that runs JS.”

Actions · FLUENT

Segmented controls & toggle buttons

Pick one option from a small set — like Pest Control vs Public Cleansing on your start card.

Segmented control

Selected: pest

Toolbar toggle buttons (map tools)

Repo echo: Measure & Annotate toolbar — tools are toggle buttons with pressed state.

Say to an agent“Use a segmented control for Pest vs Cleansing (not two separate pages). Pressed segment must have aria-pressed and visible selected style.”

Inputs · NEWCOMER

Text fields & forms anatomy

Label + control + helper/error text. Experts never ship a placeholder-only field.

Field anatomy

Name * Helper text — guidance before error.

Comment Textarea = multi-line text.

Type	Use
text	General words (street, landmark)
search	Query boxes (LandsD location search)
number	RAR %, counts — still validate yourself
password	Secrets (inbox token page)
email / tel / url	Hints mobile keyboards
textarea	Feedback comment, remarks

Expert: Placeholder is not a label. Required fields need visible *. Associate errors with aria-invalid and aria-describedby.

Say to an agent“Feedback form: label above each input, helper under comment, error text in --bad colour with aria-invalid on the field.”

Inputs · NEWCOMER

Checkbox, radio, switch

Three cousins — wrong choice confuses users and agents.

Live comparison

Checkbox — pick many (All Rounds, dog-entry filter) Another checkbox option

Radio — pick exactly one (RAS / GI / both) Another single choice

Switch — on/off setting (labels Aa force-on)

Control	Question it answers
Checkbox	“Which of these apply?” (0…many)
Radio	“Which one option?” (exactly one in a group)
Switch	“Is this setting on?” (immediate toggle)

Radios vs segmented control: radios for forms with labels/help; segmented for compact toolbars/filters.

GI “All Rounds” should be which?

Checkbox (can combine with other filters) Radio against every round name FAB

All Rounds is an additive filter flag — checkbox/switch territory.

Inputs · FLUENT

Sliders, steppers & numeric entry

Sliders are great for approximate values; number fields for exact ones. Sometimes you offer both.

Range slider

Map zoom (demo): 13

min / max / step are the expert attributes

Numeric stepper pattern

e.g. RAR band cut idea

Repo echo: RAR colour bands use a custom draggable strip with handles — a specialised dual-range metaphor. When talking to agents say “band cut drag handles,” not only “slider.”

Expert: Dual-range (min–max) isn’t native everywhere — often custom. Always expose typed values for precision. Keyboard: arrows should nudge step.

Say to an agent“Add a zoom preference slider 10–18 with live value label; also allow typing the number for precision.”

Inputs · FLUENT

File upload, dropzones & colour pickers

Your builder lives on CSV dropzones and colour swatches — learn the vocabulary.

Dropzone

Drop CSV here or click to choose

No file yet

Colour swatches + native picker

Custom #00897b

Repo: legend swatches recolour markers; department badge colour UI; GI area colours.

Say to an agent“Keep dashed dropzone affordance for CSV. Clicking a legend swatch opens preset colours plus a custom colour input.”

Inputs · FLUENT

Select, listbox, combobox

Different words for “choose from a list” — precision matters at expert level.

Native select

District

Term	Meaning
Select / dropdown	Native or custom single choice menu
Listbox	Visible list; often multi-select (RAR Phase listbox)
Combobox	Type-ahead + list (searchable select)
Menu	Actions list (not for choosing form data)
Autocomplete	Suggestions while typing (location search)

Repo: RAR filter “Phase” control is described as a listbox (Off / All / multi-select). LandsD search behaves like autocomplete.

Say to an agent“Phase filter should be a multi-select listbox with Off / All / individual phases — not a single native <select>.”

Feedback · NEWCOMER

Badges, chips, tags, pills

Small labeled bits. Easy to confuse — here’s the split.

Badges (status / count)

Beta Saved 3 unread Header RAS 12

Filter chips (toggle) & input tags

TP_001

Name	Job
Badge	Non-click status or count
Chip / pill / tag	Compact choice, filter, or removable item
Dot / status indicator	Tiny presence (unread red dot on bell)

Your builder: unread red dot on What's new; header count badges for layers; department colour “badges” on markers.

Feedback · FLUENT

Progress, spinners, skeletons

Waiting without feedback feels broken. Experts choose the right wait pattern.

Patterns

Determinate progress

Indeterminate spinner — unknown duration

Skeleton — placeholder shapes while content loads

Say to an agent“While APP_CONFIG exports, disable the button and show a spinner on it; don’t block the whole page with a modal unless export takes >2s.”

Feedback · FLUENT

Toasts, alerts, banners, empty states

Different urgency → different furniture.

Toast (temporary)

Alerts / banners (persistent until dismissed)

ℹ️ Info: Draft not saved — refresh clears the workbench.

⚠️ Warning: Some CSV rows have coordinates outside HK bounds.

⛔ Error: Template missing /*__APP_CONFIG__*/ marker.

Empty state

🗺️

No markers yet

Add pins on the map or upload a CSV to begin.

Pattern	When
Toast / snackbar	Brief confirmation; auto-dismiss
Inline error	Next to the field that failed
Alert / banner	Page-level notice that can wait
Modal error	Must acknowledge before continuing (use sparingly)
Empty state	No data yet — teach the first action

Picker validation uses highlight + toast when required cells are missing — good pairing of inline + toast.

Containers · NEWCOMER

Tabs, accordion, disclosure

Ways to show one chunk of content at a time without leaving the page.

Tabs

Preview markers for survey phase 1.

Accordion / disclosure

CSV upload + hand-typing grid live here — progressive disclosure.

Say to an agent“Preview panel needs layer tabs (each phase, pools, GI, All) with aria-selected. Keep Other input methods as a collapsed disclosure.”

Containers · FLUENT

Drawer, sheet, side panel

Slides in from an edge — good for filters or mobile menus without full-page navigation.

Open a drawer

Name	Typical use
Drawer	Left/right panel (nav or filters)
Bottom sheet	Mobile action panel from bottom
Sticky side panel	Your builder preview — not an overlay, stays in layout

Your 40% sticky preview is a layout panel, not a drawer. Drawers overlay content; sticky panels push/share space.

Containers · FLUENT

Tooltip vs popover vs popup

Three different “floating bits” — map apps use all three meanings.

Tooltip (hover/focus hint)

Popover / menu

Term	Meaning
Tooltip	Short hint; no interactive content
Popover	Small floating panel; may contain controls
Dropdown menu	Action list in a popover
Map popup	Leaflet bindPopup — info card on a marker
Map tooltip	Leaflet bindTooltip — often permanent serial labels

Say to an agent“Basemap control should open on click/tap only (popover), not hover — collapse when the map is clicked.”

Navigation · NEWCOMER

Nav bars, sidebars, breadcrumbs

Navigation answers “where am I?” and “where can I go?”

Breadcrumbs

Pattern	Job
Top app bar	Global actions (save, import, title)
Sidebar	Persistent section list (this tutorial!)
Breadcrumbs	Hierarchy path
Tabs	Peer sections of same object
Bottom tab bar	Mobile primary destinations

Your builder is mostly a single scrolling form + sticky preview — “step list” navigation, not multi-route SPA nav.

Navigation · FLUENT

Steppers, wizards & pagination

Steppers = ordered tasks. Pagination = slices of a long list.

Stepper (wizard)

1 District

—

2 Data

—

3 Colours

—

4 Generate

Repo: builder renumbers visible steps when mode hides irrelevant ones.

Pagination

Data · FLUENT

Tables, grids & toolbars

Spreadsheets in the browser — your picker table is a classic data grid cousin.

Compact table

Camera ID	Lat	Lng
TP_001	22.450121	114.170334
TP_002	22.451002	114.168881

Toolbar

Toolbar = clustered actions for the current view

Say to an agent“Picker right pane is a data table with editable cells, row delete, and a toolbar for Copy / Export CSV / Clear. Sticky header row on scroll.”

Data · EXPERT · repo-flavoured

Map-specific UI elements

Leaflet apps add their own control vocabulary on top of normal UI.

Mini map + legend + zoom affordances

Element	Language to use
Basemap layers control	Tile layer switcher; click-to-expand
Marker	Point symbol; divIcon / SVG glyph
Popup	Click card on marker
Tooltip / label	Permanent serial / RAR% label
Cluster / spiderfy	Group overlaps; explode on click
Legend	Key; swatches may be interactive
Measure toolbar	Dist/Area + annotation tools
Locate control	Geolocation / “my location”
Scale bar	Distance legend on map
Hash share state	URL encodes view/filters

Exhibits: map_template.html, measure_toolbar_lab.html, coord_picker.html (65/35 map-table split).

Expert · EXPERT

Accessibility (a11y) essentials

If you can name these, agents take you seriously — and users with keyboards/screen readers survive.

Hit target size

Too small

≥44px comfort

Contrast sketch

Good on olive Good on amber Poor grey on white

Concept	What to say
Focus order	Tab moves in logical reading order
aria-label	Name for icon-only controls
aria-expanded	Disclosure / accordion open state
aria-pressed	Toggle button on/off
aria-live	Region that announces toasts/errors
Role	dialog, tablist, toolbar, menu…
Reduced motion	Respect prefers-reduced-motion

Icon-only save button needs…

Nothing — icons are universal An accessible name (aria-label or visible text) A second identical button

Screen readers need a name. Title attribute is a weak substitute.

Expert · EXPERT

Design systems & component language

A design system is a shared kit: tokens + components + rules. Your repo is a lightweight one.

Phrase	Meaning
Component	Reusable UI unit (Button, Field, Toast)
Variant	Look option (primary/secondary)
Size	sm / md / lg density
Composition	How components combine into a screen
Density	Comfortable vs compact spacing
Responsive	Adapts to viewport (your 900px breakpoint)
Progressive disclosure	Hide advanced until needed
Optimistic UI	Show success before server confirms (advanced)
Design debt	Inconsistent one-off styles

Agent prompt template

On [screen/file], change [component] to [variant/state].
Keep tokens [--olive…]. Mobile: [breakpoint behaviour].
A11y: [focus / aria]. Don’t alter [constraint].

Libraries you’ll hear: Bootstrap, Material, Ant Design, shadcn/ui, Radix — different kits, same component names you’re learning here. Your project is mostly custom plain CSS, which is fine.

Reference

UI glossary (A–Z)

Filter as you talk with agents.

Accordion: Stacked expand/collapse sections
Affordance: Cue that something is interactive
Alert / banner: Persistent page message
Autocomplete: Suggestions while typing
Badge: Status or count label
Breadcrumb: Hierarchy path links
Breakpoint: Width where layout changes
Chip / pill / tag: Compact filter or item
Combobox: Typeable select
Dialog / modal: Blocking overlay
Disclosure: Show/hide details control
Drawer / sheet: Edge-sliding panel
Dropdown: Collapsible menu or select
Empty state: UI when there’s no data
FAB: Floating action button
Focus ring: Keyboard highlight
Ghost button: Low-emphasis outlined/text button
Hit target: Clickable area size
Icon button: Action with icon, little/no text
Legend: Map key for symbols/colours
Listbox: Selectable list (often multi)
Popover: Floating panel with content
Progress: Determinate completion bar
Radio group: Choose exactly one
Range / slider: Pick value along a continuum
Segmented control: Compact mutually exclusive choices
Skeleton: Loading placeholder shapes
Snackbar / toast: Temporary feedback message
Stepper: Ordered wizard steps
Switch: Immediate on/off
Tab: Peer panel switcher
Token: Named design value
Toolbar: Cluster of actions
Tooltip: Short hover/focus hint
Variant: Style option of a component

Frontend UI elements — interactive school

How to study

Catalog (what’s inside)

Anatomy & interactive states

State matrix (live)

Design tokens & visual hierarchy

Hierarchy recipe

Buttons

Links vs buttons

Segmented controls & toggle buttons

Text fields & forms anatomy

Checkbox, radio, switch

Sliders, steppers & numeric entry

File upload, dropzones & colour pickers

Select, listbox, combobox

Badges, chips, tags, pills

Progress, spinners, skeletons

Toasts, alerts, banners, empty states

Tabs, accordion, disclosure

Modal / dialog

Drawer, sheet, side panel

Tooltip vs popover vs popup

Nav bars, sidebars, breadcrumbs

Steppers, wizards & pagination

Tables, grids & toolbars

Map-specific UI elements

Accessibility (a11y) essentials

Design systems & component language

Mastery challenge

UI glossary (A–Z)