A hospital in Colombo needed to replace their attendance system. 295 staff across eight wards. Biometric devices. Rotating shifts. Holiday pay rules. Overtime calculations with no-pay deduction thresholds. A roster builder that could handle night-to-morning handoffs without double-booking a single nurse.
The kind of project that, under the old model, would consume four discovery workshops, twelve weeks of sprints, and a scope change conversation somewhere around week six when someone remembers the probation override rules.
We did it differently. We wrote the spec first.
What St. Raphael Medical Centre Actually Needed
Enterprise hospitals don’t buy software because they want software. They buy software because their current process is failing in ways that cost money, create liability, or both.
St. Raphael’s existing system couldn’t handle rotating shifts. Attendance data was reconciled manually at month-end. Shift swaps were tracked on WhatsApp. Policy enforcement was inconsistent across wards because every ward head had their own interpretation of “late.”
The brief wasn’t “build us an attendance app.” The brief was: “Give us a single source of truth for who is where, when, and whether the rules are being followed.”
HR managers, ward managers, senior nurses, and IT admins — aged 35 to 55. Task-oriented. Low tolerance for ambiguity. They want to complete their job, not discover features. Every design decision in this spec flows from that constraint.
The Specification: Before a Line of Code
Before we opened a code editor, we wrote a comprehensive UX and design specification. Not a wireframe deck. Not a user-story backlog. A complete document that described every screen, every interaction, every business rule, every edge case, and every pixel decision — with the reasons for each.
The document covered ten sections: project overview, UX principles, design system, information architecture, fourteen screen specifications, interaction patterns, business logic and validation rules, domain data reference, a rebuild prompt, and developer notes.
Every field in every form was defined. Every validation rule was documented. Every empty state had a designed CTA. Every destructive action had a confirmation flow. The spec didn’t leave gaps for engineers to fill with their best guess — because when you hand a spec with gaps to an AI agent, it fills those gaps confidently with assumptions you never approved.
A spec that leaves room for interpretation isn’t a spec. It’s a suggestion. And suggestions are expensive when your agent can write 200 lines of confident, wrong code in thirty seconds.
The principle behind every decision in this documentEight UX Principles. Not Opinions — Constraints.
We didn’t start with screens. We started with principles. Eight of them, each derived from the specific user segment — enterprise admin users aged 35–55 — and each stated with an “Apply as” instruction so no one could treat them as optional philosophy.
Clarity over cleverness. Generous sizing. Progressive disclosure. Forgiving interactions. Consistent wayfinding. Accessible contrast. Meaningful empty states. Responsive behaviour.
Each principle was a design constraint that eliminated decisions during the build. When an engineer — human or AI — faces a choice between a compact layout and a readable one, the spec already answered it. When a UI component needs a touch target size, the spec already decided. No meetings. No Slack threads. The answer is in the document.
A Design System That Reads Like Code
The design system in the spec isn’t a mood board. It’s a set of CSS-ready tokens with explicit rationale.
Typography: Lora for headings (warmth, authority, maturity), DM Sans for UI (clarity, friendliness, modern professionalism), DM Mono for data (precision, technical trust). Three fonts, each chosen for what it communicates to a 45-year-old HR manager scanning a roster at 7am.
Colour palette: Warm parchment background (#F6F4F0), deep warm navy primary, terracotta accent. Not clinical. Not cold. The spec says “warm, approachable, trustworthy” and then provides every hex value, contrast ratio, and component token to enforce it. WCAG AA confirmed — --text on --surface hits 10.2:1.
Shift types get their own colour families: morning (blue), afternoon (amber), night (purple), day off (grey). Holiday types get theirs: public (red), mercantile (amber), special (purple). Every status badge, every roster cell, every calendar dot maps to a specific token with a specific meaning. No ambiguity. No “I think this shade of blue means morning shift.”
When an AI agent builds a roster component and needs to decide what colour a night shift cell should be, it doesn’t guess. It reads --shift-night: #5B3FA0 and --shift-night-bg: #F0ECFB. The spec has already made the decision. That’s the difference between a prototype that needs three rounds of design review and one that ships the first time.
14 Screens. Every Pixel Accounted For.
The spec describes fourteen complete screens, each with layout structure, component anatomy, data specifications, interaction states, and empty states. Here’s what we covered:
Every screen specification includes the exact data to display. Not placeholder text — real names (Jessica Mukherjee, Dr. Rohan Patel, Amina Oduya), real staff IDs (MED-2022-0041), real shift patterns (M-M-M-M-OFF-OFF-A), real ward structures, real policy configurations. The prototype looks like a live system from the first render.
The Business Logic No Prompt Would Capture
This is where spec-first development earns its keep. The MediShift spec includes a complete business logic section that reads like pseudocode — because when these rules are wrong, the hospital pays staff incorrectly, violates labour law, or schedules a nurse for a seventh consecutive day.
Try capturing that in a prompt. “Build me a healthcare attendance system with no-pay deductions.” An AI agent will produce something. It will compile. It will look professional. And it will calculate deductions wrong in a way that nobody notices until payroll runs.
The spec doesn’t just describe what the system does. It describes what the system does when things go wrong — and who gets notified, in what order, with what permissions.
Shift swap validation, absence escalation, biometric re-enrolment — all specifiedFrom Spec to Working Prototype
The spec document includes a complete rebuild prompt — a section designed to be pasted directly into an AI agent to regenerate the entire HTML prototype. Every design token, every screen description, every interaction requirement, every piece of sample data, condensed into a single structured prompt.
The result: a single-file HTML prototype with all fourteen screens navigable via sidebar, functional tab switching, working wizard flows, animated biometric capture sequences, roster cell popovers, shift swap modals with policy auto-checks, and a date-range segmented control that updates summary statistics.
Not a Figma mockup. Not a clickable wireframe. A functional interactive prototype that a client can click through and immediately understand what they’re buying.
This is a sales demo for an enterprise healthcare client. It needs to communicate competence, domain understanding, and technical capability — all before a production line of code is written. The spec made this possible. Without it, building a prototype this detailed would require weeks of iteration, design review cycles, and scope clarification conversations.
What MediShift Proves About Spec-First
MediShift is not a simple app. It has rotating shift logic, cross-ward scheduling constraints, tiered deduction rules, biometric device integration, audit-logged overrides, and Sri Lankan holiday calendars with three different holiday types that affect roster behaviour differently.
A prompt-first approach to this kind of complexity produces one of two outcomes: either the prototype misses critical business logic (and the client notices in the demo), or the team spends three weeks iterating through prompt-revise cycles that converge on the same place the spec would have taken them on day one.
The spec is a fixed investment. The prototype is a near-zero marginal cost output of that investment. Every subsequent iteration — production build, testing, deployment — references the same spec. The document doesn’t rot because the spec is the source of truth. Change the spec, regenerate the output. That’s the model.
The developer notes section of the MediShift spec includes TypeScript interfaces for every entity (Employee, Device, RosterEntry, AttendanceRecord, AttendancePolicy, Holiday, ShiftSwap), a complete REST API endpoint map, an accessibility checklist, and a recommended build order. The production team that picks up this spec doesn’t need a discovery phase. They need a terminal.
If you’re building enterprise software and you want to see what your product looks like before committing to a build — not a wireframe, not a mood board, but an interactive prototype derived from a specification that captures every edge case — that’s what we do.
The spec is the product. The code is what follows.