UI and UX

This document defines the target interface for the Headkount build phase.

The interface gives Headkount one place to manage people, contracted work, schedules, integrations, and operating problems.

Design principles

• The Schedule is the main operating view.
• Each screen uses plain labels and visible status values.
• The interface shows all relevant records before the User applies filters.
• Important actions show their effect before they change data.
• Errors stay visible until a User resolves them.
• The interface uses the Headkount black, white, and yellow design system.

Main areas

Area	Business purpose
Schedule	Shows all planned visits, Events, blocked time, gaps, and approval state.
Beauty Educators	Manages profiles, availability, work limits, and eligibility.
Brands	Manages Contracts, commitments, required visits, and required Events.
Markets and Doors	Manages operating areas, retailer stores, and nearby Door relationships.
Integrations	Shows source health, import history, credentials, and records that need review.
Users	Manages access, roles, invitations, and account status.

Coverage, the Work Queue, activity history, and the AI Agent appear inside these areas. They do not require separate primary pages.

Schedule calendar

The Schedule uses one calendar. A User can change the calendar between Month, Week, and Day views.

The calendar has four filters:

• Market
• Beauty Educator
• Brand
• Door

The filters can work together. A filter changes only the visible cards and does not change the Schedule.

The Month view shows every relevant card for the visible month. If a date contains many cards, the date cell grows.

The calendar does not replace hidden cards with a +N count. Users apply filters to reduce large card stacks.

+--------------------------------------------------------------------------------+
| Schedule                 [Month] [Week] [Day]       <  August 2026  >  [Today] |
+--------------------------------------------------------------------------------+
| Market [All]  Beauty Educator [All]  Brand [All]  Door [All]         [Reset]   |
+------------+------------+------------+------------+------------+---------------+
| Sun 2      | Mon 3      | Tue 4      | Wed 5      | Thu 6      | Fri 7         |
|            | BRAND A    | BRAND B    | EVENT      | BRAND C    | BRAND D       |
|            | Door 101   | Door 204   | Door 318   | Door 101   | Door 402      |
|            | Alex 10–2  | Sam 11–3   | 2 BEs 1–5  | Alex 2–6   | Jordan 10–2   |
|            |------------|------------|------------|------------|---------------|
|            | BRAND E    | Time Off   | BRAND F    | BRAND G    | BRAND H       |
|            | Door 115   | Sam        | Door 318   | Door 121   | Door 402      |
|            | Alex 3–7   | All day    | Maya 10–2  | Chris 1–5  | Jordan 3–7    |
+------------+------------+------------+------------+------------+---------------+
| 148 visible cards                 9 unfilled                 Version 4 Approved |
+--------------------------------------------------------------------------------+

Each Schedule card shows the Brand, Door, beauty educator, time, work type, and current state.

Selecting a card opens its complete record. The detail shows the requirement, eligibility, booking state, Connecteam shift, and activity history.

The Week and Day views use the same cards and filters. These views give more space to exact times and blocked periods.

Schedule controls

Control	Purpose
Previous, Today, and Next	Changes the visible calendar period.
Month, Week, and Day	Changes the calendar scale without changing its data.
Generate Schedule	Creates a new Schedule Version from the current inputs.
Ask AI Agent	Opens the Agent with the current calendar context.
Approve Version	Accepts the complete visible Schedule Version.
Work Queue	Shows unfilled work, callouts, cancellations, source problems, and pending actions.

The first release shows the version number, approval state, warnings, and unfilled work. It does not include a detailed difference view.

Supporting screens

Screen	Main content	Main action
Beauty Educator directory	Status, Market, availability, capacity, and eligibility readiness	Open or create a profile
Beauty Educator profile	Profile, availability, work limits, Brands, Markets, Doors, and schedule	Update approved fields
Brand directory	Contract state, required work, scheduled work, Markets, and Doors	Open or create a Brand
Brand profile	Contracts, commitments, requirements, portal access, and schedule	Add contracted work
Market and Door directory	Location, retailer, Brands, educator capacity, and schedule state	Open or create a record
Integration view	Source status, last successful import, errors, and manual actions	Reprocess or resolve a problem
User directory	Name, email, role, and account status	Invite or update a User

Each detail screen includes its activity history. A User can see who changed a record, when it changed, and why.

Core workflows

Review and approve a Schedule

1. Open the Schedule.
2. Select the Month, Week, or Day view.
3. If the calendar contains too many cards, apply the four filters.
4. Review assignments, blocked time, warnings, and unfilled work.
5. If a change is necessary, request a new version.
6. Approve the complete version.

Resolve a work item

1. Open the Work Queue.
2. Open the affected assignment or source record.
3. Review the problem, current state, and available actions.
4. Complete one action.
5. Record the reason.
6. After the required record is correct, close the item.

Manage source data

1. Open a profile or business record.
2. Review the current value and its source.
3. Enter the approved change.
4. Save the change and its reason.

Interface states

State	Interface behavior
Loading	Shows the page structure and a clear loading state.
Empty	Explains that no records match the current view or filters.
Pending	Shows that a command is waiting for Postgres or Electric Sync.
Error	Shows the failed action and the next safe action.
Stale source	Shows the last trusted data and the time of the last successful import.
No access	Hides restricted actions and explains the required role.

Access and devices

Admins manage all records and Users. Schedulers manage schedules and daily operations.

Account Directors can view schedules and manage approved Brand information. The AI Agent receives the same access as the signed-in User.

The full calendar is a desktop-first interface. Smaller screens use horizontal scrolling and keep filters above the calendar.

All controls support keyboard use, visible focus, text labels, and clear color contrast. Color never provides the only status signal.

Result

This design gives Headkount one calendar for daily scheduling and a small set of supporting business screens.