Yoko Shiina

Sample specification: daily shift upload screen for a fictional business

This sample shows what a UX architecture specification looks like, using a fictional shop's shift schedule. To see the real project behind it, read the case study.

Saved schedule.

Current screen state

Updates as you use the screen on the right

State

Saved scheduleSAVED

The saved schedule is available. A valid upload replaces the whole selected day.

Current state in the diagram

StableProcessingInterruptedCSV upload200200 + warningsFile or date check422timeout409No schedule / EMPTYNo scheduleEMPTYSaved schedule / SAVEDSaved scheduleSAVEDPublished / PUBLISHEDPublishedPUBLISHEDRead only / READ_ONLYRead onlyREAD_ONLYChecking and updating / VALIDATINGChecking and updatingVALIDATINGUpload blocked / REJECTED_BLOCKINGUpload blockedREJECTED_BLOCKINGNeeds correction / REJECTED_ERRORSNeeds correctionREJECTED_ERRORSUpdated with warnings / APPLIED_WITH_WARNINGSUpdated with warningsAPPLIED_WITH_WARNINGSUpdate result unknown / REQUEST_FAILEDUpdate result unknownREQUEST_FAILEDEdit conflict / STALE_DATAEdit conflictSTALE_DATA

Marked states can be reached in this example. Checking and applying are combined here; the standalone implementation distinguishes them. HTTP labels describe the proposed API, not requests sent by this page.

What the specification says about this

No validation checks to show for this action. Choose a CSV example on the right to see the relevant rules here.

The full specification continues below.

Choose a CSV example to see the result and the reasoning behind it. The examples are checked against the rules described here.

Shifts / Daily shift

2026-10-15

SAVED

Staff9-1010-1111-1212-1313-1414-1515-1616-17
st_001 AnnaScheduledScheduledScheduledScheduledNot scheduledNot scheduledNot scheduledNot scheduled
st_002 BenNot scheduledScheduledScheduledScheduledScheduledNot scheduledNot scheduledNot scheduled
st_003 ClaraNot scheduledNot scheduledNot scheduledNot scheduledScheduledScheduledScheduledScheduled
st_004 DavidNot scheduledNot scheduledNot scheduledNot scheduledNot scheduledNot scheduledNot scheduledNot scheduled
st_005 ElenaScheduledScheduledScheduledNot scheduledNot scheduledNot scheduledNot scheduledNot scheduled
st_006 FelixNot scheduledNot scheduledNot scheduledScheduledScheduledScheduledScheduledScheduled
st_007 GraceNot scheduledNot scheduledScheduledScheduledScheduledScheduledNot scheduledNot scheduled
st_008 HugoNot scheduledNot scheduledNot scheduledNot scheduledNot scheduledScheduledScheduledScheduled

8 staff × 8 one-hour slots, 09:00–17:00. A valid upload replaces the whole day; rejected files leave the saved schedule unchanged.

This specification contains two kinds of notes.

Reasons from the system's side: why something takes this form, given the data and the implementation.

From the user's side
Reasons from the user's side: where people get stuck, and what the screen should do about it.

Purpose of this screen

A screen for registering and updating a shop's shifts one day at a time, from a CSV file.

Each valid upload replaces the whole day. Every current staff member needs a row, including those off duty. Missing rows and invalid values stop the update, leaving the saved schedule unchanged.

Editing happens outside the screen, in Excel or similar. This screen validates and applies.

The design follows a second principle. When an error appears, it should never leave the person unsure what to fix. Errors they can fix say where and how. Errors they cannot fix give them what they need to ask for help. Without either, people stop trying again.

The replacement method is stated first. Almost every decision in this specification follows from it. Without it, the number of checks looks excessive.

From the user's side
A screen that only says "There is an error. Please contact the person in charge" gives people no way forward. Contacting someone each time becomes a chore, and people go back to the old way. Often nobody complains; the feature simply stays unused. The checks here are designed to prevent that.

Screen structure

The table has eight staff rows and eight one-hour columns from 09:00 to 17:00. Each cell represents scheduled or not scheduled.

Validation results sit above the table. People correct the CSV outside the screen, so placing the errors below a wide, horizontally scrolling table would make them harder to find.

Staff as rows, slots as columns. Going from 8 staff to 50 adds rows without changing the structure. The other way round, every new staff member would widen the table.

Deletion and publishing are set apart from download and upload, but uploading is not harmless: it replaces a day's data. Each action has different consequences, and the specification sets safeguards for them.

User flow

Nine steps on the main path, one of which happens outside the screen. Each step pairs where people get stuck with how it is handled.

Check the target day in the month view

Sticking point
It is hard to tell which days have plans without seeing the whole month.
How it is handled
The month view shows only whether a day has a schedule. Details are in the day view. (Wider service design; not implemented in the standalone daily-shift dashboard.)

Open the day view

Sticking point
It is easy to lose track of which day is being edited.
How it is handled
The selected date is shown large at the top of the screen. Every following action is tied to that date.

Download the saved schedule as CSV

Sticking point
It is not clear what kind of file to prepare.
How it is handled
The CSV contains the selected date, every current staff member and the saved values for all eight time slots. CSV help explains the accepted values and shift rules.

Edit in Excel or similarOutside the screen

Sticking point
Saving can change the file's format. Rows that look unnecessary get deleted.
How it is handled
Keep every staff row and all eight time fields. Correct the locations identified by row, staff member or time period.

Upload the CSV

Sticking point
It is not clear where uploads can start, or why the button cannot be pressed.
How it is handled
Uploads start only from the day view; the month view has no upload button. Without permission, the button is disabled and the reason is shown next to it.

Validate the file

Sticking point
When an error appears, it is not clear whether the person who sees it can fix it.
How it is handled
Correctable errors identify the problem using the detail that fits: a row number, staff member, time period or the value as entered. For a server failure the user cannot fix, the message includes a code to pass on when asking for help.

Apply

Sticking point
It is not clear whether anything was applied.
How it is handled
On rejection, the saved table and timestamp stay unchanged. On success, replace the whole day and show whether staffing warnings remain.

Check the content

Sticking point
The numbers can pass while the schedule still does not work in practice.
How it is handled
After saving, show periods with zero or one person as warnings. They do not undo or block the completed update.

Publish

Sticking point
Pressing publish without knowing that staff will be notified.
How it is handled
Applying and publishing are separate. Before publishing, a confirmation shows what will happen. (Wider service design; not implemented in the standalone daily-shift dashboard.)

From the user's side
Choosing yesterday's file by mistake happens. Because each upload replaces the whole day, it would go through looking like a success, and the mistake would only surface when someone else looks at the schedule. Checking the date protects the data, and it also lets the person notice their own mistake.

Editing happens outside the screen, in Excel. On-screen editing is out of scope for this specification. When the current work is done in Excel, keeping the familiar tool lowers the cost of moving over.

Between download and upload, the person leaves the screen, and someone else may edit the same day in the meantime. That step outside the screen is what makes conflict detection necessary.

Where actions are possible, and why not elsewhere

Errors come after an action. Before that, there is a layer that shows whether an action is possible at all. Three cases are used: available, unavailable, and not there at all.

SituationHow it is shownReason
Uploading from the month viewNot placedNo action is possible before a date is settled. An absent button causes less confusion than one that cannot be pressed. (Wider service design; not implemented in the standalone daily-shift dashboard.)
No permission to editDisabled, with the reasonRemoving the button would suggest the feature does not exist. It stays, with the reason it cannot be used. (Wider service design; not implemented in the standalone daily-shift dashboard.)
No schedule for the day yetDelete disabledThere is nothing to delete. The example still allows choosing a CSV and reloading.
While validatingAll actions disabledPrevents double submission. The disabled actions themselves show that processing is under way.
Editing a published dayAvailable, with a confirmation before applyingThe action is not blocked. Staff will be notified, so what happens after pressing is shown first. (Wider service design; not implemented in the standalone daily-shift dashboard.)
Not knowing how to prepare the CSVAvailable except while checking or applyingThe person can check the format before choosing an example; processing uses the same action lock as the other CSV controls.

Hiding and disabling follow a rule. Actions that do not exist in a context are not placed. Actions that exist but cannot be used right now stay, always with a reason. A disabled button without a reason cannot be told apart from a broken one.

CSV format help

The help explains the columns and rules. It is unavailable while checking or applying.

  • date, staff_id and all eight hourly columns, each required once
  • TRUE means scheduled; FALSE or blank means not scheduled. Each person is off duty or works one continuous period of at least 3 hours
  • The date in every row matches the selected day
  • A filled-in example row
  • A UTF-8 .csv file up to 1 MiB, with a row for every current staff member and all eight time fields kept even when blank

The downloaded CSV includes the selected date, all current staff and their saved time values. Keeping this structure reduces missing rows and date mistakes.

From the user's side
A button that cannot be pressed, with no reason given, leaves people unsure whether they did something wrong, lack permission, or found a fault. Left unsure, they ask someone. Once asking becomes a chore, the screen stops being used.

States

The diagram connects actions to screen states. It includes the states demonstrated here and wider design states such as publishing and permissions.

The state diagram is at the top of the page. Using the screen on the right shows the current state in the diagram.

In this example, choosing a CSV starts validation before the result is shown. File, structure and date problems stop processing before the saved schedule is replaced.

File and content errors are resolved by correcting and choosing the file again. Conflict or an unknown update result requires reloading the saved schedule before another upload. A warning is already a saved result.

The standalone implementation also distinguishes reloading, a failed load and a successful reload. A failed load does not mean that no schedule has been saved.

In the standalone implementation, successful updates are announced through a separate polite live region without moving focus. Error and recovery results focus their heading. Progress announcements are delayed so that short, completed stages do not remain queued.

From the user's side
An error shown immediately and one returned after a wait feel different. Waiting only to be told about a problem the screen could have caught makes retrying harder. Checks the front end can perform are returned before sending.

The 10 states and their identifiers

Stable

  • 1No scheduleEMPTYWorks
  • 2Saved scheduleSAVEDWorks
  • 3PublishedPUBLISHED
  • 10Read onlyREAD_ONLY
  • 7Updated with warningsAPPLIED_WITH_WARNINGSWorks

Processing

  • 4Checking and updatingVALIDATINGWorks

Interrupted

  • 5Upload blockedREJECTED_BLOCKINGWorks
  • 6Needs correctionREJECTED_ERRORSWorks
  • 8Update result unknownREQUEST_FAILED
  • 9Edit conflictSTALE_DATA

Edge cases

Handled in three ways: stop, ask for a correction, or ask for a check only. Choose a CSV example on the right, and the matching items appear under "What the specification says about this" at the top left.

The label on the right of each item shows who defined its error code. Checks that complete on the front end were defined on the front end. Checks made on the server follow the codes the back-end engineer returns. The message shown is defined on the front end in both cases.

The "User's side" line explains how the error actually comes about and why it is returned this way. Not every item has one. Items decided purely by the system's constraints do not.

Blocking errors13 items

Stops at the first match without collecting further errors. The file cannot be used until the blocking issue is fixed, so later checks do not run. Shown as a solid red block.

13 items in detail
B1

File is not a .csv

Defined on the front end
Shown
Choose a CSV file with a .csv extension.
Behaviour
Checked when the file is chosen. Reading does not start.
Reason
Reported as soon as the file is chosen, which is quicker than failing after reading it.
B2

File exceeds 1 MiB

Defined on the front end
Shown
This file is larger than 1 MiB. Choose a smaller daily schedule CSV.
Behaviour
Reject before decoding.
Reason
The file contains only eight staff rows. A much larger file is likely unintended.
B3

File is empty

Defined on the front end
Shown
No schedule data was found in this file. Download the current CSV and try again.
Behaviour
Stopped when parsing returns no rows
Reason
An empty file would delete the whole day's schedule. Because each upload replaces the whole day, this is the most dangerous input.
User's side
The person has not noticed they chose an empty file. If it goes through, it deletes the day's schedule, and they would not even know it was gone.
B4

Required columns are missing, duplicated or unexpected

Defined on the front end
Shown
The CSV is missing required columns. Download the current CSV again and try again.
Behaviour
Check the header before staff data.
Reason
The meaning of each time value must be known before it can be validated.
B5

File is not UTF-8

Defined on the front end
Shown
This file could not be read as UTF-8. Export it as a UTF-8 CSV and try again.
Behaviour
Stopped on decoding failure
Reason
Excel can save CSV files in a regional encoding, which garbles accented names such as Müller or Łukasz.
User's side
This happens when a file is saved from Excel. What the person typed is correct, so reporting it as wrong values leaves them nothing to fix. The message says it is the file's format.
B6

The date in the file does not match the date selected on screen

Defined jointly
Shown
The file date does not match the selected day.
Behaviour
Every row's date checked; stopped
Reason
Because each upload replaces the whole day, letting it through would overwrite another day's schedule. There is no way to undo it.
User's side
Choosing yesterday's file happens. If it goes through, the person thinks it worked, and the mistake surfaces only when someone else looks at the schedule. This lets them notice on the spot.
B7

The file contains more than one date

Defined jointly
Shown
A file can contain one day only
Behaviour
Uniqueness of date checked; stopped. (The current implementation reports the first row that does not match the selected date as DATE_MISMATCH; it does not return a separate multiple-date code.)
Reason
Replacing several days at once hides the extent of the change from the user.
B8

Date out of range (past)

Defined jointly
Shown
Past schedules cannot be changed
Behaviour
Stopped. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
It would rewrite hours already worked.
User's side
People sometimes open a past date and edit it. If hours already worked are rewritten, it may only be noticed at payroll.
B9

Date out of range (more than three months ahead)

Defined jointly
Shown
Dates more than three months ahead cannot be registered
Behaviour
Stopped. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
Without a limit, a wrong year cannot be caught.
B10

Far more rows than expected

Defined on the front end
Shown
The file has too many rows
Behaviour
Stopped at parsing, based on the row count. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
192 rows is the norm. An order of magnitude more is probably the wrong file.
User's side
When the row count is off by an order of magnitude, the problem is the wrong file, not wrong values. Returning errors one by one would not help.
B11

Columns separated by semicolons, or a comma as the decimal point

Defined on the front end
Shown
This file uses semicolons between columns. Save it as CSV UTF-8 (comma delimited) and upload again
Behaviour
Detected in the header row; stopped. (The current implementation reports this as HEADER_INVALID because the required columns cannot be recognised. A dedicated separator error is an additional design option.)
Reason
Excel saves CSV this way in some regional settings. What the person typed is correct, so it must not be reported as wrong values.
User's side
Common wherever Excel uses a decimal comma. The person did nothing wrong in the content, so the message tells them how to save the file, not what to change in it.
B12

The file cannot be read

Defined on the front end
Shown
This file could not be read. Choose the file again.
Behaviour
Stopped before decoding.
Reason
Nothing in the file can be checked, so the person is asked to choose it again.
B13

The CSV structure is broken (quotes or number of fields)

Defined on the front end
Shown
Keep all eight time fields in every row, including blank fields.
Behaviour
Stopped at the first broken row; the row number is shown.
Reason
A missing field is not the same as a blank one. Reading it as blank would silently mark someone as off duty.

Needs correction (collected)15 items

Every row is checked and the results are shown together. These can be fixed and uploaded again, so they use the same red as blocking errors, shown as an outline instead of a solid block to signal a lower severity.

15 items in detail
A1

The ID is not in the current staff list

Defined by the back end
Shown
This ID is not in the current active staff list. Download the current CSV and check the staff ID.
Behaviour
Report the row and entered ID.
Reason
The current list does not establish whether the ID is unknown or belongs to a former member. Do not invent a cause.
User's side
A row number and the entered ID let the person locate the problem in the CSV.
A2

staff_id belongs to someone who has left

Defined by the back end
Shown
Row 7: staff ID "st_007" is no longer active
Behaviour
As A1. The current implementation reports IDs outside the active list as STAFF_NOT_ACTIVE without distinguishing unknown and former staff.
Reason
A different cause from A1. Points to an old template being reused.
User's side
A different cause from an unknown ID. It usually means an old template was reused. Saying so means next time they download a fresh one.
A3

slot_no outside 1 to 24

Defined by the back end
Shown
Row 12: slots must be between 1 and 24
Behaviour
As above. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
Stating the range removes doubt about whether numbering starts at 0 or 1.
A4

A current staff member has no row

Defined by the back end
Shown
No row in the file. Every current staff member needs a row, even when off duty.
Behaviour
Report the staff name and ID; do not replace the day.
Reason
An omitted row must not silently remove a person from the schedule.
User's side
A row that looks unnecessary may have been deleted. State that off-duty staff still need a row.
A5

A staff ID appears more than once

Defined by the back end
Shown
Staff ID “st_002” appears more than once. Keep one row for each staff member.
Behaviour
List all row numbers for that ID in one issue.
Reason
Choosing one duplicate row would hide conflicting input.
User's side
Showing only one of the duplicates leaves no way to decide which to keep. All row numbers are shown, and the person chooses.
A6

hours is not a number

Defined by the back end
Shown
Row 9: hours must be a number
Behaviour
As above. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
The input is shown back as entered. People may not remember what they typed.
A7

hours outside 0 to 0.5

Defined by the back end
Shown
Row 14: hours must be between 0 and 0.5
Behaviour
As above. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
Slots are 30 minutes, so 0.5 is the maximum. Writing 1.0 comes from misreading the unit, and is expected to be common.
User's side
Writing 1.0 for a 30-minute slot comes from misreading the unit. Showing the value as entered lets the person see what they wrote.
A8

hours has three or more decimal places

Defined by the back end
Shown
Row 21: hours can have up to two decimal places
Behaviour
As above. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
Keeps what is shown and what is stored in step. Rounding would make records disagree.
A9

Daily total exceeds the company limit

Defined by the back end
Shown
Staff "st_005" is over the daily limit (8.5 / limit 8)
Behaviour
Counted per staff member. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
Cannot be seen row by row. Only the total reveals it.
User's side
Entering one slot at a time, people are not tracking the total. Each row is valid, and only the total shows the problem, so that has to be said.
A10

More than six hours in a row without a break

Defined by the back end
Shown
Staff "st_002": more than six hours in a row with no break
Behaviour
The hours entered in consecutive occupied slots are added per staff member and compared with the company limit (6 hours in this sample). An empty or zero-hour slot breaks the run. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
The CSV cannot show when a break occurs inside a slot. This fictional rule treats empty or zero-hour slots as breaks and uses the entered hours; the user decides where to place a break.
User's side
Where to put a break depends on the shop. If the system chose, it would often be wrong. It shows the range that breaks the rule and leaves the decision to the person.
A11

Hours entered outside opening hours

Defined by the back end
Shown
Row 11: slot 24 is outside opening hours
Behaviour
As above. (Additional rule or earlier numeric-hours model; not applied to the TRUE/FALSE CSV demonstrated here.)
Reason
Changing opening hours changes which slots are valid. Catches templates that were not updated.
A14

A staff ID is missing

Defined by the back end
Shown
A staff ID is required.
Behaviour
Report the row requiring an ID.
Reason
A schedule row cannot be assigned to a person without an ID.
A15

A time cell has an invalid value

Defined by the back end
Shown
Not a valid value. Enter TRUE, FALSE, or leave the cell blank.
Behaviour
Show the row, time and entered value.
Reason
Retaining the value helps the person find the mistake; coercing it to FALSE would hide it.
A16

A work period is shorter than 3 hours

Defined jointly
Shown
Scheduled for less than 3 hours. This shop requires at least 3 consecutive hours per scheduled day.
Behaviour
Report the staff member and the period.
Reason
This shop requires at least three consecutive hours on a scheduled day.
A17

Work is split across separate periods

Defined jointly
Shown
Split shifts are not allowed. Use one continuous period of at least 3 hours.
Behaviour
Report the staff member and all work periods.
Reason
Adding the hours together does not satisfy the single-period rule.

Check (warning)2 items

The values are valid, but something needs checking for day-to-day operation. The upload goes through and the data is applied. It is not an error, so it is not red, and it is not a clean success either, so it is not emerald. Shown in the warning yellow.

2 items in detail
A12

Nobody is scheduled in a period

Defined by the back end
Shown
No one is scheduled.
Behaviour
Warn after saving; group adjacent zero-person slots.
Reason
Valid input can still leave a staffing gap.
User's side
Some slots are left empty on purpose. Stopping the upload as if it were a mistake would get in the way of correct use.
A13

Only one person is scheduled in a period

Defined by the back end
Shown
Only 1 person is scheduled.
Behaviour
Warn after saving; group adjacent one-person slots.
Reason
The update is valid, but the staffing level needs review.

Connection and permissions5 items

Depends on state outside the screen. The server's judgement is received and shown.

5 items in detail
S1

Connection lost during upload

Defined jointly
Shown
Connection lost. We could not confirm whether the upload was applied. Reload the schedule, check it, and upload again only if needed.
Behaviour
Do not retry automatically. Reload the day’s schedule and its revision before allowing another upload. If reloading fails, keep uploads unavailable until the latest state can be checked. On the server, replacement is atomic, but the client may not know whether it committed.
Reason
The server may have applied the upload even if its response was lost. Reloading lets the user review the latest data; the revision check prevents an outdated retry from silently overwriting newer changes. A 409 may still occur if the original request completes after the reload.
User's side
After a connection failure, the result may be unknown. Explain what to check next rather than claiming that nothing changed.
S2

Server-side validation fails

Defined by the back end
Shown
Shown in the same format as front-end errors
Behaviour
The response's error code is converted into the screen's message
Reason
Something can pass the front end and still be rejected by the server. The display format stays the same.
User's side
When something passes the front end and the server rejects it, the same file seems to give different results. Keeping the format the same stops it looking like a different kind of error.
S3

No permission to edit

Defined by the back end
Shown
Upload button disabled, with the reason shown
Behaviour
Permission checked when the screen loads. (Wider service design; not implemented in the standalone daily-shift dashboard.)
Reason
Showing that it cannot be pressed is better than refusing after it is pressed.
S4

The day’s schedule has changed since it was loaded

Defined by the back end
Shown
This day’s schedule has changed since it was loaded. Reload to review the latest version.
Behaviour
Compare the loaded revision on save; reject the upload if it no longer matches
Reason
The change may come from another user or from an earlier upload whose response was lost. The check prevents an outdated upload from silently overwriting newer data.
User's side
After a lost response, saying “another user” changed the schedule can be misleading: the earlier change may have been the user’s own.
S5

Changing a published schedule

Defined by the back end
Shown
This schedule is published. Changing it will notify staff again
Behaviour
A confirmation is shown first. (Wider service design; not implemented in the standalone daily-shift dashboard.)
Reason
Staff are affected. Actions whose effect goes beyond the screen are made clear beforehand.

Error codes and messages

Which side defines a code depends on where the check runs. The message, for every code, is defined on the front end. If the server returned the message text, every wording change and every new language would need back-end work.

With a table mapping codes to messages prepared in advance, implementers only look things up. Nobody has to write messages during implementation.

B, A and S identifiers are references within this specification. The implementation uses the corresponding result and issue codes shown in the table. They are not two different sets of validation rules.

Code and message table (24)
CodeDefined byjaen
FILE_TYPE (B1)Defined on the front end拡張子が.csvのCSVファイルを選択してください。Choose a CSV file with a .csv extension.
FILE_TOO_LARGE (B2)Defined on the front endこのファイルは1 MiBを超えています。より小さい日別シフトのCSVを選択してください。This file is larger than 1 MiB. Choose a smaller daily schedule CSV.
FILE_EMPTY (B3)Defined on the front endファイルに勤務表のデータがありません。現在のCSVをダウンロードして、もう一度お試しください。No schedule data was found in this file. Download the current CSV and try again.
HEADER_INVALID (B4)Defined on the front end必須の列がありません:{columns}。現在のCSVをもう一度ダウンロードして、お試しください。The CSV is missing required columns: {columns}. Download the current CSV again and try again.
FILE_ENCODING (B5)Defined on the front endこのファイルをUTF-8として読み取れませんでした。UTF-8のCSVとして書き出して、もう一度お試しください。This file could not be read as UTF-8. Export it as a UTF-8 CSV and try again.
DATE_MISMATCH (B6)Defined jointlyこのファイルは{found}のものですが、選択中の日付は{expected}です。{expected}のファイルを選択してください。This file is for {found}, but the selected day is {expected}. Choose a file for {expected}.
FILE_UNREADABLE (B12)Defined on the front endファイルを読み取れませんでした。もう一度選択してください。This file could not be read. Choose the file again.
CSV_MALFORMED (B13)Defined on the front endこの行は{actual}フィールドですが、{expected}フィールド必要です。空欄も含め、8つの時間フィールドを残してください。This row has {actual} fields; {expected} are required. Keep all eight time fields, including blank fields.
STAFF_NOT_ACTIVE (A1)Defined by the back end{row}行目 · {value}:このIDは現在のスタッフ一覧にありません。現在のCSVをダウンロードして、スタッフIDを確認してください。Row {row} · {value}: This ID is not in the current active staff list. Download the current CSV and check the staff ID.
STAFF_ROW_MISSING (A4)Defined by the back end{name}({staffId}):ファイルに行がありません。非勤務の人も含め、現在のスタッフ全員の行が必要です。{name} ({staffId}): No row in the file. Every current staff member needs a row, even when off duty.
STAFF_ROW_DUPLICATE (A5)Defined by the back end{rows}行目:スタッフID「{value}」が複数の行にあります。スタッフ1人につき1行にしてください。Rows {rows}: Staff ID “{value}” appears more than once. Keep one row for each staff member.
STAFF_ID_MISSING (A14)Defined by the back end{row}行目:スタッフIDが必要です。Row {row}: A staff ID is required.
SCHEDULE_VALUE_INVALID (A15)Defined by the back end{row}行目 · {time}:無効な値です。TRUE、FALSE、または空欄にしてください。(入力値: {value})Row {row} · {time}: Not a valid value. Enter TRUE, FALSE, or leave the cell blank. (Entered: {value})
SHIFT_TOO_SHORT (A16)Defined jointly{name} · {period}:勤務は{hours}時間です。この店舗では、勤務する日は連続3時間以上が必要です。{name} · {period}: Scheduled for {hours} hours. This shop requires at least 3 consecutive hours per scheduled day.
SPLIT_SHIFT (A17)Defined jointly{name} · {periods}:分割勤務はできません。連続3時間以上の1区間にしてください。{name} · {periods}: Split shifts are not allowed. Use one continuous period of at least 3 hours.
STALE_DATA (S4, result: conflict)Defined by the back endこの日の勤務表は読み込んだ後に変更されています。再アップロードする前に、再読み込みして最新の内容を確認してください。This day’s schedule has changed since it was loaded. Reload to review the latest version before uploading again.
FILE_EMPTY (B3; no staff rows)Defined on the front endファイルにスタッフの行がありません。現在のCSVをダウンロードして、もう一度お試しください。No staff rows were found in this file. Download the current CSV and try again.
HEADER_INVALID (B4; duplicate columns)Defined on the front end各列は1回だけ必要です。重複している列見出しを削除してください。Each CSV column must appear exactly once. Remove duplicate column headings.
HEADER_INVALID (B4; unexpected columns)Defined on the front end想定外の列があります:{columns}。ダウンロードしたCSVの列を使ってください。Unexpected columns: {columns}. Use the columns in the downloaded CSV.
DATE_MISMATCH (B6; invalid date)Defined jointlyすべての日付欄に{expected}を入力してください。日付は選択中の日と一致している必要があります。Use {expected} in every date field. The date must match the selected day.
CSV_MALFORMED (B13; text after closing quote)Defined on the front end閉じ引用符の後に余分な文字があります。Unexpected text after a closing quote.
CSV_MALFORMED (B13; misplaced quote)Defined on the front end引用符はフィールドの先頭に置くか、引用符で囲んだフィールド内でエスケープしてください。A quote must begin a CSV field or be escaped inside a quoted field.
CSV_MALFORMED (B13; unclosed quoted field)Defined on the front end引用符で囲んだフィールドが閉じていません。A quoted field was not closed.
SERVER_ERROR (proposed API)Defined by the back end処理に失敗しました。担当者にお問い合わせください(コード:{code})Something went wrong. Contact your administrator (code: {code}).

Each message says what happened and what to do next. "Invalid value" alone gives nothing to fix.

A server failure (SERVER_ERROR, in the proposed API) is not something the user can fix. Only in this case does the message include the code, so that whoever receives the support request knows where to look.

From the user's side
Errors the person can fix and errors they cannot lead to different actions: fix and try again, or ask for help. A message that does not say which leads to neither. The message should settle the next step the moment it is read.

API contract

These five endpoints are a proposed service contract. The standalone dashboard uses an in-memory gateway and does not implement these HTTP endpoints. Deletion and publishing describe wider service functions.

First, the front end sets out what data each screen needs and when. The back-end engineer checks this against the database structure and proposes what can be returned. Then the front end decides how to handle the values that come back. Each endpoint records this exchange.

1What the front end asked for

2What came back from the back end

3What was decided as a result

1. Get the day's schedule

GET /api/shifts/daily?date=2026-10-15
1

The screen needs, for each current staff member, whether they are scheduled in each of the eight slots, and the shop’s work-period rule. Names are for display; matching should use IDs.

2

Slots are stored sparsely, so as they stand they would come back with gaps. Returning every slot filled is possible.

3

Return eight boolean time values per current staff member. A person may be off duty or work one continuous period of at least three hours.

Request and response shapes
{
  "date": "2026-10-15",
  "status": "draft",
  "revision": 0,
  "updatedAt": "2026-10-14T17:42:00Z",
  "businessHours": { "start": "09:00", "end": "17:00", "slotCount": 8 },
  "workRules": { "minConsecutiveHours": 3, "allowSplitShifts": false },
  "staff": [
    {
      "staffId": "st_001",
      "name": "Anna",
      "active": true,
      "slots": [true, true, true, true, false, false, false, false]
    }
  ],
  "permissions": { "canEdit": true, "canPublish": false }
}

Return the saved schedule and its revision together. Mutations send expectedRevision; the server checks it atomically before replacing the day. updatedAt is display metadata.

businessHours and workRules are returned per screen. The back end supplies the opening hours and the work-period rule, so the front end does not hard-code them.

permissions is included in the response. The front end holds no permission logic, only the server's decision, so changing the rules needs no front-end change. This shape was the back end's suggestion. Permissions and the published status belong to the wider service design.

name is for display only. The CSV uses staffId alone; names are not used for matching, since people can share a name or change it.

2. Download the saved schedule as CSV

GET /api/shifts/daily/csv?date=2026-10-15
→ text/csv

date,staff_id,09:00-10:00,10:00-11:00,11:00-12:00,12:00-13:00,13:00-14:00,14:00-15:00,15:00-16:00,16:00-17:00
2026-10-15,st_001,TRUE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,FALSE
...

The CSV comes with the date filled in. Typing it by hand makes B6 more likely.

Every current staff member is included with all eight time fields, including those off duty. Building rows by hand makes A4 frequent.

Only current staff are included, so A1 mostly happens when an old file is reused.

Return the saved schedule, not an empty template. After recovery from conflict or an unknown result, download a fresh copy and transfer any edits made to an older file.

3. Upload (validate and replace)

POST /api/shifts/daily/upload
Content-Type: multipart/form-data

date:             2026-10-15
expectedRevision: 0
file:             (CSV)
1

The screen should show which row and which value is the problem. Some errors have row numbers and some belong to a staff member or a period, so please do not force them into one shape.

2

Validation runs on the server, so the codes are defined here. Returning every error would make the response large, so there should be a cap, returning only the count beyond it.

3

Codes are defined by the back end, and the front end prepares the matching messages. Error shapes differ by unit of reporting: some carry a row number, some a staff ID and a period. In this proposed API, errors beyond a cap come as a count in truncated.omitted, and the screen shows "n more problems". The standalone dashboard returns every issue it finds.

Response shapes (200 / 422 / 409)

200 — applied

{
  "result": "applied",
  "revision": 1,
  "updatedAt": "2026-10-14T17:43:00Z",
  "warnings": [
    { "start": 0, "end": 1, "count": 1 },
    { "start": 7, "end": 8, "count": 0 }
  ]
}

422 — blocked

{
  "result": "rejected",
  "blocking": [
    { "code": "DATE_MISMATCH", "row": 2, "expected": "2026-10-15", "found": "2026-10-16" }
  ],
  "errors": [],
  "truncated": { "omitted": 0 }
}

422 — corrections needed

{
  "result": "rejected",
  "blocking": [],
  "errors": [
    { "code": "SHIFT_TOO_SHORT", "staffId": "st_001", "start": 0, "end": 2 },
    { "code": "SPLIT_SHIFT", "staffId": "st_003", "periods": [{ "start": 0, "end": 3 }, { "start": 4, "end": 7 }] },
    { "code": "SCHEDULE_VALUE_INVALID", "row": 4, "slot": 2, "value": "yes" },
    { "code": "STAFF_ROW_MISSING", "staffId": "st_002" }
  ],
  "truncated": { "omitted": 0 }
}

409 — edit conflict

{
  "result": "conflict",
  "code": "STALE_DATA",
  "revision": 1,
  "updatedAt": "2026-10-14T17:43:00Z"
}

blocking and errors are separate arrays. A blocking error stops at the first, so the array always has one item, but keeping the shape means the contract survives if several are returned later. Warning periods use start and end slot indexes: start is included, end is not, and 0 is 09:00.

Error shapes vary by item: some have row, some have staffId and a period. One shared shape would add "no row number" branches on screen. Different units of reporting get different shapes.

Replacement runs in a single transaction: it is either fully applied or not applied. A lost response leaves the client unable to tell which occurred. For S1, reload the day and its revision before another upload. If an older revision is submitted, S4 rejects the outdated write.

4. Delete

DELETE /api/shifts/daily?date=2026-10-15
expectedRevision: 0

Deletion also requires expectedRevision. It is as destructive as replacement, so conflict detection works the same way. Deletion belongs to the wider service design.

Deletion is per day only. Deleting several days at once is a separate endpoint, outside this specification. Putting actions with different reach on one endpoint would complicate permissions.

5. Change publishing status

PATCH /api/shifts/daily/status

{ "date": "2026-10-15", "status": "published", "expectedRevision": 1 }

Changing status is separate from upload. Publishing on upload would leave no way to check before publishing. Publishing belongs to the wider service design.

Notifying staff is triggered on the server. If the front end called a notification API, publishing could succeed while notification fails.

How the front end and back end share the work

Which side checks what was agreed with the back-end engineer. This is a record of decisions: whether to keep the same check on both sides or leave it to one, reached by putting together what each side could see.

Items given to one side, and items where one side does not rely on the other's result, are shown darker.

20-item split
CheckFront endBack end
File typeB1Checked on choosing the file. Not sent—
File sizeB2Checked before parsing. Not sentChecked on receipt. Covers direct POSTs
Empty fileB3Stopped when parsing returns no rowsLast line of defence. An empty file would delete the whole day
EncodingB5Detected as a decoding failure—
Separators (additional rule; not applied to this CSV)B11Detected in the header row—
Required columnsB4Checked at once on the header rowLast line of defence
Date matchB6Compared with the selected date; blocked at onceChecked again independently. Does not rely on the front end's result
Date range (additional rule; not applied to this CSV)B8 B9Rough check on the client's clock, as a guideFinal check on the server's clock
staff_id existsA1 A14Matched against the fetched list, with row numbersFinal check. The list is as of fetching
Active status (additional rule; not applied to this CSV)A2Guide based on active status at fetch timeFinal check. May change after fetching
Time columns and staff rowsB4 B13 A4Require all eight time columns and one row for every current staff memberRevalidate the same structure before saving
Duplicate staff rowsA5List all row numbers for each repeated IDReject ambiguous staff rows before replacement
Scheduled valuesA15Accept TRUE, FALSE or blank; retain invalid input for correctionReject non-boolean schedule values before saving
One period of at least 3 hoursA16 A17Detect split shifts and periods shorter than three slotsRevalidate the same work-period rule before saving
Daily limit (additional rule; not applied to this CSV)A9Totalled per staff member using dailyLimitHoursFinal check. Source of the threshold
Consecutive hours and breaks (additional rule; not applied to this CSV)A10Adds entered hours across consecutive occupied slots using workRules.maxContinuousWorkHoursFinal check. Provides the company policy threshold in workRules
Outside opening hours (additional rule; not applied to this CSV)A11Checked against businessHoursFinal check. Source of opening hours
Staffing warningsA12 A13The standalone dashboard calculates and displays zero/one-person periods from the schedule after a successful save. With the proposed API, display the warnings returned in the success response.In the proposed API, calculate zero/one-person periods from the saved schedule and return them as warnings.
Edit conflictS4Keep the loaded revision and supply expectedRevisionReject a stale revision before replacing the saved day
Permissions (wider service design)S3Controls the UI according to permissionsJudged here. The server holds the rules

Structural checks (type, range, required, duplicates) have the same rules on both sides. The front end returns corrections quickly; the back end covers direct POSTs and gaps in the front-end implementation. The cost of keeping the rules twice is accepted.

Where the two sides can disagree (active status, date range), the front end is a guide and the back end is final, and this is stated explicitly. The back end may reject what the front end let through, and the design assumes it. S2 is treated as a normal path, not an exception, and shown in the same format as the collected errors on the front end.

The back end revalidates the date and schedule data before saving. The B6 date check also runs independently of the front end's result. Because uploads replace the whole day, this prevents data for the wrong date from being applied.

The current example uses boolean values in eight one-hour slots. It checks one continuous period of at least three hours, or no work. Daily limits and break policies belong to the wider design and are not applied to this CSV model.

In the current implementation, staffing warnings are calculated from the saved schedule after a successful commit. They are not a pre-save rejection and do not mean that saving failed.

What this specification leaves to engineering

This specification decides when things appear, where the data goes, how validation is split, and what the messages say.

How it is built stays with the engineers who build it: conditional logic, what becomes state, how components and props are structured, and code that fits the existing codebase and stays easy to read and extend.

If no one settles when and why something appears, those decisions end up being made during implementation. Agreeing on them first gives engineers a clear behaviour to build, while leaving the implementation approach to them.

About this specification and the screen on the right

I built the working screen on the right to test behaviours that are hard to judge on paper. This is how I sometimes use a prototype to refine the specification before implementation.

The examples use prepared CSV data, which is parsed and validated when selected. File selection and downloading are represented as demo actions; this page does not require local files or send data to a server.

When a project needs it, I move between Figma and working code, choosing whichever suits the question. Checking whether something can be built while designing it is what keeps a specification from staying on paper.

The mockup is for testing, not production code. Putting it into a real product would need rework, including state management, error boundaries and tests. Testing something by running it and shipping it are treated as separate things.

Used on this page

React / TypeScript / Next.js / Tailwind CSS

Used for the design

Figma (variables, component variants and properties)

Used in the implementation sample

Next.js / React / TypeScript / Tailwind CSS / Radix Primitives

This specification starts after it was decided what to build. In real projects, work more often starts before that, and what happens there is part of the job too.

The case study shows that earlier stage on a real project: what was undecided, what was put forward, and what that settled. Part of the prototype built for that project was reused in production.

Read the case study

The real project behind this sample: what was undecided, how the decisions were reached, and how they were carried through to production.

Read