BIZOS DESIGN SYSTEMLegacy format
This document defines the rules for designing and implementing the BizOS user interface. BizOS is a workforce and business operating system for small and mid-sized businesses. The interface must make complex operational information feel simple. The user should not feel that they are operating an ERP. They should feel: 'Everything my business needs is organized here.'
Typography
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
Every letter tells a story worth reading, and every typeface gives that story a new voice waiting to be heard.
This document defines the rules for designing and implementing the BizOS user interface. BizOS is a workforce and business operating system for small and mid-sized businesses. The interface must make complex operational information feel simple. The user should not feel that they are operating an ERP. They should feel: 'Everything my business needs is organized here.'
Components
Buttons
Cards
Card Title
Sample body text for the card component.
Card Title
Sample body text for the card component.
Elevation & Depth
Do's & Don'ts
Do
Don't
Status
Document Type: Master Design & UI Implementation Specification
Product: BizOS
Applies To: Web Admin, Owner Dashboard, Manager Dashboard, Employee Web Interfaces, Employee Mobile
Authority: Highest UI/UX implementation authority after explicit user instructions and supplied reference design files.
---
# 1. PURPOSE
This document defines the rules for designing and implementing the BizOS user interface.
BizOS is a workforce and business operating system for small and mid-sized businesses.
The interface must make complex operational information feel simple.
The user should not feel that they are operating an ERP.
They should feel:
> "Everything my business needs is organized here."
The product must prioritize:
• clarity
• speed
• consistency
• hierarchy
• trust
• simplicity
• actionability
• responsive behavior
• accessibility
• predictable interaction
---
# 2. MOST IMPORTANT DESIGN RULE
THE USER'S SUPPLIED DESIGN SYSTEM IS THE SOURCE OF TRUTH
Before implementing the final UI, the user will provide official BizOS Design System UI files, screenshots, components, or references.
Those assets have priority over assumptions in this document.
Once supplied, inspect them carefully and derive:
• color system
• typography
• spacing
• sizing
• component geometry
• border radius
• shadows
• borders
• iconography
• button styles
• card styles
• table styles
• navigation
• tabs
• dialogs
• forms
• states
• animations
• responsive behavior
• visual density
Do not replace the supplied design system with a new interpretation.
Do not "improve" the supplied design arbitrarily.
Maintain visual consistency with the reference.
---
# 3. DESIGN HIERARCHY
Follow this priority:
```text
1. Explicit user direction
2. Supplied BizOS Design System files
3. Existing approved BizOS components
4. This document
5. Industry-standard UX conventions
6. Developer preference
```
Developer preference must always come last.
---
# 4. DESIGN PHILOSOPHY
BizOS should feel:
```text
Modern
Professional
Calm
Fast
Trustworthy
Premium
Simple
Operational
```
Avoid making it feel:
```text
Cheap
Over-designed
Playful
Gimmicky
Enterprise-heavy
Visually noisy
Dense without reason
```
---
# 5. PRIMARY DESIGN PRINCIPLE
INFORMATION SHOULD BE EASY TO SCAN.
Most users will open BizOS while actively running their business.
They should not need to read large blocks of text.
Use:
• strong hierarchy
• short labels
• predictable placement
• grouped information
• meaningful whitespace
• status indicators
• concise actions
• useful summaries
---
# 6. SECONDARY DESIGN PRINCIPLE
SHOW WHAT NEEDS ATTENTION.
BizOS is exception-driven.
Instead of displaying enormous amounts of raw information, prioritize:
```text
What happened?
What is unusual?
What needs approval?
What needs action?
What changed?
```
Example:
Bad:
> 30 employee attendance records.
Better:
> 3 attendance exceptions require attention.
---
# 7. VISUAL LANGUAGE
Once the official design references are supplied, all components must derive their appearance from them.
Never independently invent:
• a new blue
• another gray
• an alternative purple
• a separate border system
• a new button radius
• a different card treatment
when an existing token/component already exists.
---
# 8. DESIGN TOKENS
Centralize all design values.
At minimum:
```text
colors
typography
spacing
radius
shadows
borders
opacity
motion
z-index
breakpoints
container sizes
control heights
```
Avoid magic values throughout component CSS.
Bad:
```text
margin: 17px;
```
Better:
```text
spacing token
```
unless the supplied design system explicitly requires a unique value.
---
# 9. COLOR SYSTEM
The exact BizOS colors must come from the supplied design system.
Do not hard-code colors throughout components.
Use semantic tokens such as:
```text
background
foreground
surface
surface-elevated
surface-hover
border
muted
muted-foreground
primary
primary-foreground
secondary
accent
success
warning
danger
info
focus
```
---
# 10. SEMANTIC COLORS
Do not use colors only for decoration.
Color should communicate meaning.
Example:
```text
Success → completed / healthy
Warning → attention
Danger → blocked / critical
Info → informational
Neutral → normal state
```
Never use red merely because it visually looks attractive.
Never use green merely because it looks positive.
Color meaning must remain consistent throughout the application.
---
# 11. DARK / LIGHT MODE
If the product supports both themes:
The design system must define both.
Do not manually invert colors.
Do not use:
```text
black → white
white → black
```
as a simplistic theme transformation.
Each semantic token must have an intentional value for every supported theme.
---
# 12. TYPOGRAPHY
Typography hierarchy must be centralized.
Define tokens for:
```text
Display
Page Title
Section Title
Card Title
Body Large
Body
Body Small
Label
Caption
Table Text
Metric
Button Text
```
The visual hierarchy must be obvious without excessive font-size variation.
Do not use too many font weights.
---
# 13. NUMBERS / METRICS
BizOS contains financial and workforce information.
Numbers must be highly scannable.
Examples:
```text
₹8.42L
1,846h
28
₹42.8L
14.2%
```
Use appropriate numeric alignment where helpful.
Financial tables should normally align numbers consistently.
---
# 14. PAGE STRUCTURE
A typical desktop page should follow:
```text
Application Shell
↓
Page Header
↓
Primary Context / Filters
↓
Main Content
↓
Secondary Content / Supporting Information
```
Do not create arbitrary layout variations between pages.
---
# 15. APPLICATION SHELL
The overall shell must remain consistent.
Typical structure:
```text
┌─────────────────────────────────────────────┐
│ Header │
├────────────┬────────────────────────────────┤
│ Sidebar │ Main Content │
│ │ │
│ Navigation │ │
│ │ │
└────────────┴────────────────────────────────┘
```
The exact structure must match the supplied UI reference.
---
# 16. SIDEBAR
Sidebar behavior must be consistent throughout the application.
Define:
• width
• collapsed width
• hierarchy
• active state
• hover state
• icon behavior
• group labels
• nested navigation
• mobile behavior
Do not create a unique sidebar for individual modules.
---
# 17. HEADER
The header must have consistent:
• height
• alignment
• typography
• actions
• search
• notifications
• organization context
• user menu
Do not move major header controls arbitrarily between pages.
---
# 18. NAVIGATION
Navigation labels must be predictable.
Recommended conceptual structure:
```text
Overview
Workforce
Employees
Teams
Locations
Time
Attendance
Timesheets
Shifts
Leave
Payroll
Business
Customers
Projects
Invoices
Payments
Reports
Settings
```
The actual navigation must follow the approved product structure and supplied design.
---
# 19. PAGE TITLE
Every major page should clearly establish:
```text
Page title
Description/context where useful
Primary action
```
Example:
```text
Employees
Manage your workforce and employment information.
[ Add employee ]
```
Do not add unnecessary descriptive text if the reference design doesn't use it.
---
# 20. PRIMARY ACTION
Each page should have one visually dominant primary action when appropriate.
Examples:
```text
Add Employee
Create Shift
Run Payroll
Create Invoice
Approve
```
Do not create five equally prominent buttons.
---
# 21. BUTTON HIERARCHY
Define consistent variants:
```text
Primary
Secondary
Outline
Ghost
Destructive
Link
Icon
```
Use each purposefully.
### Primary
Main action.
### Secondary
Supporting action.
### Destructive
Dangerous or irreversible action.
### Ghost
Low-emphasis contextual action.
Never use a destructive style for ordinary corrections.
---
# 22. BUTTON BEHAVIOR
Buttons must support:
```text
default
hover
focus
active
disabled
loading
success
error
```
Loading buttons must prevent accidental duplicate submissions.
Example:
```text
Approve Payroll
↓
Approving...
```
Do not allow repeated clicks during mutation.
---
# 23. ICONS
Use one consistent icon system.
Do not mix random icon libraries.
Icons should:
• support meaning
• remain visually consistent
• align correctly
• have predictable size
Avoid replacing meaningful labels with icons alone.
---
# 24. CARDS
Cards are containers for related information.
Do not wrap every element in a card.
Good uses:
```text
Payroll summary
Attendance metrics
Exception panel
Employee summary
Invoice summary
```
Bad use:
Every table cell or every paragraph inside its own card.
Avoid "card soup."
---
# 25. KPI CARDS
Metric cards should communicate quickly.
Example:
```text
Employees
28
+2 this month
```
or:
```text
Overtime
74h
↑ 12%
```
A KPI card should answer:
```text
What is it?
What is the value?
What changed?
```
when comparison information exists.
---
# 26. DASHBOARD DESIGN
The dashboard is not a collection of every available report.
It should prioritize:
```text
Today's status
Needs attention
Important metrics
Recent activity
Business health
```
Recommended conceptual hierarchy:
```text
Header
Today's Workforce
Attention Required
Payroll / Financial Snapshot
Activity
Business Metrics
```
Actual composition must follow approved UI references.
---
# 27. EXCEPTION DESIGN
Exceptions should be visually distinguishable but not overwhelming.
Example:
```text
Missing clock-out
Rahul Patel
Yesterday · 6:12 PM expected
[ Review ]
```
Do not make every warning a giant red alert.
Use severity appropriately.
---
# 28. TABLES
Tables are central to BizOS.
They must be:
• scannable
• aligned
• responsive
• sortable where relevant
• filterable where useful
• paginated where necessary
Common columns should have predictable widths.
---
# 29. TABLE ALIGNMENT
Text:
Left aligned.
Dates:
Consistent alignment.
Numeric values:
Right aligned where appropriate.
Status:
Consistent placement.
Actions:
Usually right aligned.
Do not randomly shift columns between pages.
---
# 30. TABLE STATES
Every table must support:
```text
Loading
Empty
Loaded
Error
Filtered-empty
Paginated
```
Never show a blank table with no explanation.
---
# 31. EMPTY STATES
A good empty state answers:
```text
What is empty?
Why is it empty?
What can I do?
```
Example:
```text
No employees yet.
Add your first employee to start tracking attendance.
[ Add employee ]
```
Avoid unnecessary illustrations unless the design system specifies them.
---
# 32. LOADING STATES
Use appropriate loading patterns:
```text
Skeleton
Spinner
Progress indicator
Optimistic update
```
Do not make the entire application flash white during every request.
Prefer localized loading.
---
# 33. ERROR STATES
Errors must be actionable.
Bad:
> Something went wrong.
Better:
> We couldn't load attendance data.
Then:
```text
[ Try again ]
```
Where safe, explain what the user can do next.
---
# 34. FORMS
Forms must be consistent.
Every field needs:
```text
Label
Control
Optional description where useful
Validation
Error state
```
Avoid placeholder-only labels.
---
# 35. FORM VALIDATION
Validation should provide:
• clear error
• field location
• useful explanation
• correction guidance
Do not validate only after the entire form is submitted when inline validation is more useful.
---
# 36. DATES
Dates must follow a consistent product format.
Avoid different date formats on different pages.
Date/time formatting should respect:
• organization timezone
• relevant location timezone
• user locale where appropriate
---
# 37. TIME DISPLAY
Attendance is time-critical.
Examples:
```text
9:07 AM
6:21 PM
8h 42m
42m overtime
```
Keep display concise.
Detailed timestamps can be shown in secondary information.
---
# 38. STATUS DESIGN
Use consistent status pills/badges.
Examples:
```text
Present
Late
Absent
On Leave
Working
On Break
Completed
Pending
Approved
Rejected
Overdue
Paid
```
The same status must visually look the same everywhere.
---
# 39. MODALS
Use modals only when focused interaction is appropriate.
Good examples:
```text
Confirm payroll approval
Add employee
Edit shift
Review correction
```
Avoid putting an entire complex application inside a modal.
---
# 40. DRAWERS
Use drawers for contextual inspection where the user should retain page context.
Good examples:
```text
Employee details
Attendance details
Invoice preview
Exception details
```
---
# 41. CONFIRMATION DIALOGS
Use confirmation dialogs for meaningful irreversible or high-impact operations.
Examples:
```text
Approve payroll
Delete employee
Cancel payroll
Void invoice
```
Do not confirm trivial actions.
---
# 42. TOASTS
Use toasts for short-lived feedback:
```text
Employee added
Clock-in successful
Correction submitted
Invoice sent
```
Do not put critical business information exclusively in a toast.
---
# 43. NOTIFICATIONS
Persistent notification systems should be used for items requiring later attention.
Examples:
```text
Payroll exception
Missing clock-out
Overdue invoice
Pending approval
```
---
# 44. ATTENDANCE UX
Attendance is the most important employee interaction.
The employee should immediately understand:
```text
Am I clocked in?
When did I start?
Am I on break?
How long have I worked?
What should I do next?
```
The primary Clock In / Clock Out action must be exceptionally clear.
---
# 45. CLOCK-IN EXPERIENCE
The employee should not navigate through multiple screens to clock in.
Preferred conceptual flow:
```text
Open app
↓
Current status visible
↓
Primary action
↓
Confirmation
```
Do not bury attendance behind menus.
---
# 46. CLOCK-IN FEEDBACK
After clock-in:
```text
Clocked in
9:07 AM
```
The interface should clearly change state.
The user must never wonder whether the action succeeded.
---
# 47. CLOCK-OUT EXPERIENCE
Same principle.
After clock-out display:
```text
Shift complete
Worked 8h 42m
```
Where useful:
```text
Regular 8h
Overtime 42m
```
---
# 48. BREAK EXPERIENCE
Break state must be visually obvious.
Example:
```text
ON BREAK
Started 1:04 PM
[ End Break ]
```
Do not allow confusing combinations such as simultaneously displaying:
```text
Working
On Break
```
---
# 49. ATTENDANCE EXCEPTIONS
Employee-facing exceptions should be understandable.
Examples:
```text
You forgot to clock out yesterday.
[ Request correction ]
```
Manager-facing:
```text
Missing clock-out
Rahul
Aug 28
```
Owner-facing:
```text
3 attendance exceptions
```
Same underlying state, different information density.
---
# 50. ROLE-BASED UI
Do not simply hide everything randomly.
The interface must reflect actual permissions.
Employee:
```text
Own attendance
Own leave
Own timesheets
Own payslips
```
Manager:
```text
Team attendance
Team approvals
Team leave
```
Owner/Admin:
```text
Organization-level management
Payroll
Reports
Settings
```
---
# 51. RESPONSIVE DESIGN
The product must be designed deliberately for:
```text
Desktop
Laptop
Tablet
Mobile
```
Do not simply shrink desktop layouts.
---
# 52. RESPONSIVE PRINCIPLE
When width decreases:
```text
Reduce complexity
↓
Prioritize primary information
↓
Move secondary information
↓
Collapse navigation
↓
Stack appropriate content
```
Do not simply reduce font size.
---
# 53. MOBILE WEB
Mobile web should remain functional.
Do not allow:
• overflowing tables
• clipped buttons
• unreadable text
• inaccessible controls
• tiny touch targets
---
# 54. MOBILE APP
The employee mobile application should prioritize:
```text
Attendance
Hours
Leave
Timesheet
Payslip
Profile
```
Do not turn the mobile application into a miniature desktop ERP.
---
# 55. TOUCH TARGETS
Interactive controls must be comfortable to tap.
Maintain sufficient target size and spacing according to accessibility standards and the supplied design system.
---
# 56. SPACING SYSTEM
Use a systematic spacing scale.
Do not create arbitrary values page-by-page.
The exact scale must come from the supplied design system.
Conceptually:
```text
xs
sm
md
lg
xl
2xl
3xl
```
All layout spacing should use the established system.
---
# 57. PAGE MARGINS
Desktop page margins must remain consistent.
Do not independently choose:
```text
24px on one page
30px on another
48px on another
```
unless explicitly required by the design.
---
# 58. CONTENT WIDTH
Major content containers should have predictable maximum widths.
Avoid layouts that stretch excessively across very wide displays unless the content benefits from it.
Tables and data-heavy screens may intentionally use wider layouts.
---
# 59. GRID
Use a predictable grid system.
Examples:
```text
4-column desktop
3-column
2-column
1-column
```
Select layouts based on content.
Do not create a 4-column layout just because the grid permits it.
---
# 60. DENSITY
BizOS has a lot of operational information.
Use a balance between:
```text
Information density
+
Readable whitespace
```
Do not make every screen extremely spacious.
Do not make every screen compressed.
The supplied design system determines the intended visual density.
---
# 61. MOTION
Animations should communicate state, not exist for decoration.
Good:
```text
button loading
modal appearing
drawer transition
tab transition
status update
sidebar collapse
```
Avoid:
• excessive parallax
• unnecessary bouncing
• continuous motion
• distracting transitions
---
# 62. MOTION TIMING
Centralize animation tokens.
Conceptually:
```text
fast
normal
slow
```
Use consistent easing.
Do not invent random durations throughout the application.
---
# 63. MICRO-INTERACTIONS
Use subtle feedback for:
```text
hover
press
success
completion
selection
navigation
```
Micro-interactions should reinforce confidence.
---
# 64. ACCESSIBILITY
Accessibility is mandatory.
Support:
• keyboard navigation
• visible focus
• semantic HTML
• labels
• screen-reader-friendly controls
• adequate contrast
• meaningful status information
• reduced-motion preferences
Do not use color as the only indication of state.
---
# 65. FOCUS STATES
Every interactive element must have a clear focus state.
Do not remove focus outlines without replacing them with an accessible equivalent.
---
# 66. ICON-ONLY CONTROLS
Icon-only actions must have accessible labels.
Example:
```text
Edit employee
Delete employee
More actions
```
Do not assume users understand unfamiliar icons.
---
# 67. TABLE ACCESSIBILITY
Data tables must retain meaningful headers and logical reading order.
Do not implement tables as purely visual grids.
---
# 68. FINANCIAL UI
Financial information requires extra care.
For:
• payroll
• invoices
• payments
• labour cost
• profit
use:
```text
clear currency
consistent decimals
consistent alignment
clear totals
clear status
strong hierarchy
```
Avoid excessive decorative styling around money.
Trust is more important than visual novelty.
---
# 69. EMPLOYEE DATA
Employee information may be sensitive.
The UI should avoid exposing information to users without permission.
Do not merely hide it visually.
Backend authorization must enforce access.
---
# 70. PERMISSION-DRIVEN ACTIONS
If a user cannot perform an action:
Prefer not to present it as an active button.
If context requires visibility, make the state clear.
Never rely only on disabled UI to enforce security.
---
# 71. SEARCH
Search should be introduced only where it provides clear value.
Good candidates:
```text
Employees
Customers
Projects
Invoices
```
Avoid adding global search just because it looks sophisticated.
---
# 72. FILTERS
Filters should be placed consistently.
Common filters:
```text
Date
Location
Department
Employee
Status
Team
```
Do not place filters randomly across pages.
---
# 73. FILTER PERSISTENCE
Where useful, preserve filter state across:
• pagination
• sorting
• navigation
• refresh
Do not over-persist filters where that creates confusion.
---
# 74. SORTING
Sorting should be visually obvious.
Display:
```text
ascending
descending
```
Do not create different sorting interactions on different tables.
---
# 75. PAGINATION
Use pagination for genuinely large datasets.
Do not paginate a 10-row list simply because a pagination component exists.
---
# 76. BULK ACTIONS
Bulk operations are useful for:
```text
Employees
Attendance
Timesheets
Invoices
```
When used:
```text
Select
↓
Show selection count
↓
Show relevant actions
```
Do not overload the screen with bulk actions when nothing is selected.
---
# 77. DELETE OPERATIONS
Use clear destructive language.
Avoid ambiguous:
```text
Proceed?
```
Prefer:
```text
Delete employee?
This action cannot be undone.
```
For recoverable entities, prefer archive/deactivate where appropriate.
---
# 78. SOFT DELETE / ARCHIVE UI
Where business logic supports it, use:
```text
Active
Inactive
Archived
```
instead of permanently deleting important business records.
---
# 79. ONBOARDING
BizOS onboarding should feel short.
Conceptual flow:
```text
Create account
↓
Business information
↓
Location
↓
Working schedule
↓
Employees
↓
Ready
```
Do not ask for every possible setting during initial onboarding.
---
# 80. PROGRESSIVE DISCLOSURE
Advanced configuration should appear when needed.
Example:
Simple:
```text
Working hours
9 AM – 6 PM
```
Advanced:
```text
Grace period
Break policy
Overtime threshold
Holiday policy
Geofence enforcement
```
Do not overwhelm first-time users.
---
# 81. SETTINGS
Settings should be organized by domain.
Example:
```text
Organization
Workforce
Attendance
Payroll
Notifications
Integrations
Security
Billing
```
Do not build one enormous settings page.
---
# 82. COMPONENT ARCHITECTURE
Reusable UI components must be centralized.
Examples:
```text
Button
Input
Select
Checkbox
Switch
Tabs
Badge
Card
Table
Dialog
Drawer
Dropdown
Tooltip
Popover
DatePicker
EmptyState
LoadingState
ErrorState
Pagination
FilterBar
MetricCard
```
Do not copy component implementations page by page.
---
# 83. COMPONENT VARIANTS
Use explicit variants.
Example:
```text
Button
primary
secondary
destructive
ghost
outline
```
Avoid one-off CSS per page.
---
# 84. COMPOSITION OVER DUPLICATION
Prefer:
```text
```
with configuration
rather than:
```text
PayrollMetricCard
AttendanceMetricCard
EmployeeMetricCard
```
unless their behaviors are genuinely different.
---
# 85. DOMAIN COMPONENTS
After foundational components, create domain-specific components.
Examples:
```text
AttendanceStatus
ClockButton
TimesheetTable
PayrollSummary
EmployeeStatus
ExceptionCard
LeaveRequestCard
InvoiceStatus
```
These should compose foundational UI components.
---
# 86. DESIGN SYSTEM DIRECTORY
Recommended structure:
```text
packages/ui/
│
├── primitives/
├── components/
├── patterns/
├── forms/
├── data-display/
├── navigation/
├── feedback/
├── domain/
├── tokens/
└── styles/
```
Adapt to the actual project architecture.
---
# 87. COMPONENT RULE
Every reusable component should define:
```text
Purpose
Props/API
Variants
States
Accessibility
Responsive behavior
Usage example
```
---
# 88. DESIGN TOKENS IN CODE
Do not scatter design constants through JSX.
Prefer a centralized token system.
Example conceptual model:
```text
tokens/
├── colors
├── typography
├── spacing
├── radius
├── shadows
├── motion
└── breakpoints
```
---
# 89. CSS ARCHITECTURE
Follow the project's approved styling architecture.
Do not randomly combine:
```text
inline styles
CSS modules
Tailwind
styled-components
global CSS
```
without a documented reason.
Use one coherent strategy.
---
# 90. RESPONSIVE COMPONENT CONTRACT
Reusable components should specify what happens when space becomes constrained.
For example:
```text
Desktop:
FilterBar = horizontal
Tablet:
FilterBar = wrapped
Mobile:
FilterBar = stacked / drawer
```
Do not leave responsive behavior to chance.
---
# 91. DATA STATES ARE PART OF DESIGN
A component is incomplete without:
```text
Loading
Empty
Error
Success
Disabled
Permission restricted
```
where relevant.
---
# 92. OPTIMISTIC UI
Use optimistic updates only when:
• action is reversible
• failure can be handled safely
• business consistency is maintained
Do not optimistically mark:
```text
Payroll approved
Invoice paid
```
unless backend confirmation semantics are clearly designed.
---
# 93. REFRESH / CACHE BEHAVIOR
UI should not unnecessarily refetch or reset state.
Respect the application's approved caching strategy.
Mutations should invalidate only relevant data.
Do not introduce random global refresh behavior.
---
# 94. NOTIFICATION UI
Notification count and state should remain consistent.
Example:
```text
3 pending approvals
```
When the user resolves an item, the count should update appropriately.
---
# 95. REAL-TIME UI
Where real-time behavior is useful:
```text
Currently working
Attendance state
Approvals
Notifications
```
Use real-time updates selectively.
Do not make the entire application real-time without a product reason.
---
# 96. CONSISTENCY RULE
If a UI pattern exists in one part of BizOS, reuse it.
For example:
If employee status appears as:
```text
[ Working ]
```
do not display the same status elsewhere as:
```text
● Active
```
unless the underlying meaning differs.
---
# 97. PAGE-TO-PAGE CONSISTENCY
Maintain consistency in:
• header position
• title
• filters
• action placement
• tabs
• table controls
• pagination
• spacing
• button placement
• status placement
• navigation
The user should always know where to look.
---
# 98. TABS
Tabs should be used for closely related views.
Examples:
```text
Employee
Overview
Attendance
Leave
Payroll
```
Do not use tabs as a substitute for navigation.
The selected state must be obvious.
---
# 99. DETAIL PAGES
Detail pages should follow a consistent hierarchy:
```text
Back / breadcrumb
Identity / title
Primary actions
Summary
Tabs / sections
Detailed information
```
Exact design follows supplied UI references.
---
# 100. BREADCRUMBS
Use breadcrumbs when hierarchy genuinely helps.
Do not add breadcrumbs to simple one-level pages.
---
# 101. TOOLTIPS
Use tooltips for:
• unfamiliar icons
• advanced controls
• truncated content
• secondary explanations
Do not use tooltips for information users need constantly.
---
# 102. TRUNCATION
When text is too long:
• truncate visually
• preserve access to full information
• use tooltip/detail view where appropriate
Never silently remove important data.
---
# 103. AVATARS
Use avatars consistently.
Where initials are used, derive them deterministically.
Do not use decorative random avatars.
---
# 104. EMPTY DATA VS NO ACCESS
These are different.
### Empty
> No employees added yet.
### No permission
> You don't have permission to view employees.
Never use an empty-state message to disguise authorization problems.
---
# 105. ERROR VS EMPTY
Do not show:
> No data found
when the API actually failed.
Differentiate:
```text
No data
```
from:
```text
Failed to load data
```
---
# 106. PERFORMANCE
Visual quality includes performance.
Avoid:
• unnecessary re-renders
• huge bundles
• loading entire datasets
• excessive animations
• massive images
• blocking UI
The interface should feel fast.
---
# 107. IMAGE USAGE
Images should be used only when they add product value.
Do not introduce decorative imagery into operational screens unless the design system requires it.
---
# 108. ICON CONSISTENCY
Maintain:
```text
stroke weight
size
alignment
visual family
```
Do not mix solid icons and outline icons arbitrarily.
---
# 109. VISUAL HIERARCHY
Hierarchy should follow:
```text
Primary information
↓
Secondary information
↓
Supporting information
↓
Metadata
```
Do not make metadata more visually prominent than the primary business result.
---
# 110. FINANCIAL TOTALS
Totals must stand out clearly.
For example:
```text
Subtotal
Taxes
Adjustments
----------------
Total
```
The final value should be visually obvious.
---
# 111. PAYROLL DESIGN
Payroll screens require high trust.
Emphasize:
```text
Pay period
Employees
Gross payroll
Adjustments
Exceptions
Approval status
Final total
```
Do not bury important warnings beneath decorative charts.
---
# 112. ATTENDANCE DASHBOARD DESIGN
Prioritize:
```text
Present
Working
Late
Absent
On leave
Missing clock-out
```
Then provide detailed data.
---
# 113. OWNER EXPERIENCE
Owner dashboards should answer:
```text
How is my business doing?
What needs my attention?
What do I need to approve?
What changed?
```
Avoid making the owner operate like an HR administrator.
---
# 114. MANAGER EXPERIENCE
Manager interfaces should answer:
```text
Who is working?
Who is absent?
Who is late?
What needs approval?
Which employees need attention?
```
---
# 115. EMPLOYEE EXPERIENCE
Employee interfaces should answer:
```text
Am I clocked in?
How long have I worked?
What is my schedule?
What is my timesheet?
Do I need to do anything?
```
---
# 116. UI SECURITY
Never treat visual hiding as security.
Example:
```text
if (!canViewPayroll) hide payroll button
```
is only a UX behavior.
The API must independently enforce:
```text
canViewPayroll
```
---
# 117. DESIGN REVIEW CHECKLIST
Before approving a page, verify:
### Structure
```text
✓ Correct shell
✓ Correct spacing
✓ Correct hierarchy
✓ Correct navigation
```
### Components
```text
✓ Existing components reused
✓ No duplicate patterns
✓ Consistent states
```
### Interaction
```text
✓ Loading
✓ Error
✓ Empty
✓ Success
✓ Disabled
✓ Permissions
```
### Responsive
```text
✓ Desktop
✓ Tablet
✓ Mobile
```
### Accessibility
```text
✓ Keyboard
✓ Focus
✓ Labels
✓ Contrast
```
---
# 118. NO ONE-OFF DESIGN
Do not create:
```text
SpecialButton
SpecialCard
SpecialTable
SpecialModal
```
for one page unless there is a genuine domain-specific requirement.
First determine whether the existing component can support the use case.
---
# 119. DESIGN SYSTEM EVOLUTION
When a new reusable pattern is discovered:
1. Determine whether it belongs in the design system.
2. Add it centrally.
3. Document it.
4. Reuse it.
Do not solve the same design problem independently ten times.
---
# 120. DESIGN DECISION RECORD
When making a significant UI/UX decision that changes the established system, record:
```text
Problem
Decision
Reason
Impact
Affected components
```
Do not silently change the design language.
---
# 121. FIGMA / DESIGN FILE HANDLING
When the user supplies:
• Figma
• screenshots
• exported components
• HTML/CSS
• design tokens
• UI reference files
inspect them before writing new UI code.
Extract the actual design language.
Do not rely on visual memory.
---
# 122. REFERENCE SCREEN RULE
If a screenshot represents an approved BizOS screen, treat it as a reference implementation.
Match:
```text
Spacing
Alignment
Typography
Hierarchy
Component placement
Control sizes
Navigation
Colors
States
```
Do not merely create a screen that "looks similar."
---
# 123. PIXEL CONSISTENCY
Where exact visual reproduction is requested, prioritize:
```text
layout geometry
spacing
alignment
sizing
component positioning
```
Avoid subjective interpretation.
---
# 124. IMPLEMENTATION ORDER FOR UI
Once the Design System has been supplied:
```text
01. Extract design tokens
02. Extract typography
03. Extract core primitives
04. Build application shell
05. Build navigation
06. Build page layout system
07. Build forms
08. Build tables
09. Build feedback states
10. Build domain components
11. Build pages
12. Build responsive variants
13. Accessibility review
14. Visual QA
15. Interaction QA
```
Do not start by making dozens of individual pages.
---
# 125. DESIGN SYSTEM FIRST
Before building individual feature screens:
Build and verify:
```text
Buttons
Inputs
Selects
Tabs
Cards
Tables
Badges
Dialogs
Drawers
Dropdowns
Toasts
Navigation
Filters
Pagination
Loading
Empty states
Error states
```
Then compose pages from them.
---
# 126. VISUAL QA
After implementation, compare the resulting screen against the supplied reference.
Check:
```text
Position
Width
Height
Spacing
Typography
Colors
Borders
Radius
Shadow
Icon
Alignment
Responsive behavior
```
Fix differences systematically.
---
# 127. DO NOT REDESIGN DURING IMPLEMENTATION
If the reference design looks unusual, reproduce it first.
Do not change:
```text
button location
sidebar width
spacing
card layout
tabs
color
```
because you personally prefer something else.
---
# 128. UX IMPROVEMENTS
A UX improvement may be proposed only when:
• the supplied design has a genuine usability problem
• the change preserves the visual language
• the change is documented
• the user approves it where materially significant
Do not make silent redesign decisions.
---
# 129. COMPONENT NAMING
Use semantic names.
Good:
```text
AttendanceStatusBadge
PayrollSummaryCard
EmployeeAvatar
ApprovalBanner
```
Avoid:
```text
Box1
Card2
Thing
BlueButton
SpecialContainer
```
---
# 130. FINAL QUALITY STANDARD
Every BizOS screen should feel like it belongs to the same product.
A user moving from:
```text
Employees
```
to:
```text
Attendance
```
to:
```text
Payroll
```
to:
```text
Invoices
```
should immediately recognize the same design system.
---
# 131. FINAL DESIGN RULES
Always remember:
```text
Consistency > novelty
Clarity > decoration
Actionability > information overload
Trust > visual gimmicks
Reusable components > one-off components
Systematic spacing > arbitrary spacing
Semantic tokens > hard-coded values
Accessible interaction > visual-only interaction
User reference > developer preference
```
---
# 132. UI IMPLEMENTATION GATE
Before beginning final BizOS UI implementation:
CHECK:
```text
Has the user provided the official BizOS Design System UI files?
```
### If NO:
Do not invent the final design system.
Do not continue full UI implementation.
Ask the user to provide the design system/reference files.
### If YES:
Perform a structured design-system extraction.
Document:
```text
Colors
Typography
Spacing
Radius
Shadows
Components
Navigation
Tables
Forms
States
Responsive behavior
Motion
```
Then implement the shared design foundation first.
---
# 133. FINAL INSTRUCTION TO GEMINI
You are not designing BizOS screen-by-screen.
You are building one coherent product design system.
Every new screen must reuse the same:
• layout logic
• components
• spacing
• typography
• states
• interaction patterns
• navigation patterns
• responsive behavior
Never allow UI drift.
When the user supplies reference UI files, treat them as the visual source of truth.
Before creating a new component, search for an existing equivalent.
Before creating a new design value, search for an existing token.
Before creating a new page pattern, search for an existing page pattern.
Before changing an established pattern, document the reason.
The final goal is:
# Every BizOS screen should look like it was designed by one highly disciplined product design team.
Use with MCP
Don't have the MCP? Install it here