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.

```text
+--------------------------------------------------------------------------------+
| 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.