crowd-funder-for-time-pwa/doc/z-index-guide.md

Z-Index Guide — TimeSafari

Author: Development Team
Date: 2025-08-25T19:38:09-08:00
Status: 🎯 ACTIVE - Z-index layering standards

Objective

Establish consistent z-index values across the TimeSafari application to ensure proper layering of UI elements.

Result

This document defines the z-index hierarchy for all UI components.

Use/Run

Reference these values when implementing new components or modifying existing ones to maintain consistent layering.

Z-Index Hierarchy

Component	Z-Index	Usage
Map	40	Base map layer and map-related overlays
QuickNav	50	Quick navigation bottom bar
Dialogs and Modals	100	Modal dialogs, popups, and overlay content
Notifications and Toasts	120	System notifications, alerts, and toast messages

Best Practices

1. Never exceed 120 - Keep the highest z-index reserved for critical notifications
2. Use increments of 10 - Leave room for future additions between layers
3. Document exceptions - If you need a z-index outside this range, document the reason
4. Test layering - Verify z-index behavior across different screen sizes and devices

Common Pitfalls

• Avoid arbitrary values - Don't use random z-index numbers
• Don't nest high z-index - Keep child elements within their parent's z-index range
• Consider stacking context - Remember that position: relative creates new stacking contexts

Next Steps

Owner	Task	Exit Criteria	Target Date
Dev Team	Apply z-index classes to existing components	All components use defined z-index values	2025-09-01

Competence Hooks

• Why this works: Creates predictable layering hierarchy that prevents UI conflicts
• Common pitfalls: Using arbitrary z-index values or exceeding the defined range
• Next skill unlock: Learn about CSS stacking contexts and their impact on z-index
• Teach-back: Explain the z-index hierarchy to a team member without referencing this guide

Collaboration Hooks

• Reviewers: Frontend team, UI/UX designers
• Sign-off checklist:
  • All new components follow z-index guidelines
  • Existing components updated to use defined values
  • Cross-browser testing completed
  • Mobile responsiveness verified

Assumptions & Limits

• Assumes modern browser support for z-index
• Limited to 4 defined layers (expandable if needed)
• Requires team discipline to maintain consistency

References

• MDN Z-Index Documentation
• CSS Stacking Context Guide