Project Initiative: People Map Icons for Housing Scenarios

Status: Planned (Paused for Documentation Migration)
Priority: Medium
Branch: feat/component-layering (current work) → Will need separate branch for completion
Owner: TBD
Created: October 16, 2025
Target Completion: TBD (After documentation migration)

---

Executive Summary

Create a comprehensive set of 12 custom map marker icons representing different household compositions for the Pride City division housing/roommate applications. These visual markers will provide immediate visual identification of housing scenarios on interactive maps.

---

Business Context

Our housing and roommate matching applications (Homestay, Room LGBT, Stay Match, etc.) need intuitive visual markers that instantly communicate household composition:

• Single occupants
• Couples (various gender combinations)
• Families with children
• Multi-person households

Visual markers eliminate the need to read text descriptions and improve user experience on map-based search interfaces.

---

Technical Foundation

Dependencies Installed

✅ @heroicons/react (v2.2.0)

• 292 icons, solid & outline variants
• People icons: UserIcon, UserGroupIcon, UsersIcon

✅ @tabler/icons-react (v3.35.0)

• 5000+ icons including 61 people-related icons
• Gender-specific: IconMan, IconWoman, IconManFilled, IconWomanFilled
• Groups: IconUsers, IconUsersGroup

✅ Leaflet (v1.9.4) - Already integrated in Pride City division

• LeafletMap component created
• Composite marker pattern established
• 17+ working examples in Storybook

Current Implementation Status

Completed:

• ✅ LeafletMap component (packages/ui-pride-city/src/components/LeafletMap/)
• ✅ Leaflet dependencies installed at workspace root
• ✅ Composite marker SVG pattern proven (droplet + icon + colors)
• ✅ Storybook stories: 17 map marker examples
• ✅ Custom color markers: orange hotel, hot pink hotel, brand pink homestay
• ✅ Icon libraries installed and showcased in Storybook
• ✅ Documentation: 5+ markdown files covering implementation

In Progress:

• 🔄 Evil Icons removal (completed in code, awaiting commit)
• 🔄 Icon selection for 12 household compositions (user research phase)

Blocked/Paused:

• ⏸️ Awaiting user art direction for icon selection
• ⏸️ Paused for documentation migration work

---

The 12 Household Compositions

Required Markers

1. Single Man - One male occupant
2. Single Woman - One female occupant
3. Man and Woman - Couple, mixed gender
4. Two Women - Couple/roommates, both female
5. Two Men - Couple/roommates, both male
6. Two Men and a Child - Male couple with child
7. Two Women and a Child - Female couple with child
8. Man and Woman and a Child - Traditional family unit
9. Two Men and a Woman - Three-person household
10. Three Women - Three female roommates/family
11. Three Men - Three male roommates/family
12. Two Women and a Man - Three-person household

---

Design Approach

Marker Style (Geoapify-inspired)

• Droplet shape with circle top and pointed bottom
• White circular background inside droplet for icon placement
• Colored border/background specific to brand/category
• Stick/stem extending to map point
• SVG data URL for inline rendering (no external assets)

Icon Composition Strategy

For complex scenarios (2-3+ people):

1. Position multiple person icons side-by-side within circle
2. Scale down as needed to fit 2-3 figures
3. Use color differentiation for hair, clothing to distinguish individuals
4. Maintain visual clarity at 40x50px marker size

Art Direction Workflow

1. User selects base icon style from Heroicons or Tabler galleries
2. User specifies for each composition:
   • Layout/positioning of figures
   • Hair colors (hex codes)
   • Shirt/clothing colors (hex codes)
   • Marker background color (brand alignment)
   • Skin tone (if visible, or keep abstract/neutral)
3. Agent implements SVG composite marker
4. User reviews in Storybook
5. Iterate until approved
6. Repeat for all 12 compositions

---

Technical Implementation Plan

Phase 1: Icon Selection & Art Direction (Not Started)

Prerequisites: User completes icon library research

Tasks:

• User reviews Heroicons gallery in Storybook
• User reviews Tabler Icons gallery in Storybook
• User selects preferred icon style (Heroicons vs Tabler)
• User provides art direction for first marker (e.g., “Single Man”)
  • Icon choice
  • Hair color
  • Shirt color
  • Marker background color
• Create first marker as proof of concept
• User approves or provides feedback
• Replicate process for remaining 11 markers

Deliverables:

• 12 approved icon/color specifications
• 1 working prototype marker

Phase 2: Marker Creation (Not Started)

Tasks:

• Create SVG composite marker for each composition
• Add each marker as Storybook story in LeafletMap.stories.tsx
• Test rendering at various zoom levels
• Ensure visual clarity and distinctiveness between types
• Document SVG structure and color variables

Deliverables:

• 12 new Storybook stories (one per household type)
• Updated LeafletMap.stories.tsx with all scenarios
• Technical documentation of marker SVG patterns

Phase 3: Component Integration (Not Started)

Tasks:

• Create marker icon constants/config object
• Add TypeScript types for household compositions
• Create helper functions for marker selection
• Add prop to LeafletMap for household type selection
• Write unit tests for marker rendering
• Update component README with usage examples

Deliverables:

• Marker configuration module
• Updated LeafletMap component with household type support
• Tests passing
• Updated documentation

Phase 4: Documentation & Handoff (Not Started)

Tasks:

• Create comprehensive usage guide
• Document art direction decisions
• Create visual reference sheet (all 12 markers)
• Add to design system documentation
• Migration to Astro/Starlight docs (post-doc-migration)
• Train team on marker usage

Deliverables:

• Complete usage documentation
• Visual reference guide
• Design system integration
• Team training materials

---

Dependencies & Blockers

Current Blockers

1. User Art Direction Required - Cannot proceed with marker creation until user selects icons and provides color specifications
2. Documentation Migration - Current work paused to focus on Astro/Starlight documentation consolidation
3. Storybook Component Parity - Need to complete one web + one mobile component per division first

Technical Dependencies

• ✅ Leaflet installed
• ✅ Icon libraries installed (@heroicons/react, @tabler/icons-react)
• ✅ LeafletMap component functional
• ✅ Composite marker pattern proven
• ✅ Storybook configured and building

---

Success Criteria

Functional Requirements

• All 12 household compositions have unique, identifiable markers
• Markers render correctly in Leaflet at zoom levels 10-18
• Visual distinction between all marker types at typical zoom (13-15)
• Markers work with existing LeafletMap component (no breaking changes)
• Performance: No lag when rendering 50+ markers on map

Design Requirements

• Markers align with Pride City brand identity
• Colors are accessible (WCAG AA contrast where applicable)
• Icons are culturally sensitive and inclusive
• Visual style consistent across all 12 markers
• Markers look professional at both 40x50px and scaled sizes

Documentation Requirements

• Usage guide with code examples
• Visual reference showing all 12 markers
• Art direction rationale documented
• Integration guide for developers
• Storybook stories demonstrate all use cases

---

Risks & Mitigation

Risk	Impact	Likelihood	Mitigation
Icons don’t scale well at small sizes	High	Medium	Test at multiple sizes early; use simplified designs if needed
Too many figures hard to distinguish	High	High	Limit to max 3 figures; use strong color contrast; add positioning variety
Brand colors clash with map tiles	Medium	Low	Test on multiple map tile providers; add white outlines
Art direction unclear/changes frequently	Medium	Medium	Get written approval at each phase; create visual mockups first
Performance issues with complex SVGs	Low	Low	Keep SVG paths minimal; test with 100+ markers

---

Open Questions

1. Icon Style: Heroicons (Tailwind style) vs Tabler (more detailed)? User preference?
2. Abstraction Level: Realistic clothing/hair or simplified silhouettes?
3. Child Representation: How to visually indicate children vs adults? Size difference? Position?
4. Color Palette: Use Pride City brand colors or create new palette for household types?
5. Accessibility: Do markers need text labels in addition to visual icons?
6. Internationalization: Any cultural considerations for icon design?
7. Future Expansion: Any other household types needed? (e.g., larger families, multi-generational?)

---

Timeline & Milestones

Current Session (October 16, 2025)

• ✅ Install icon libraries (Heroicons, Tabler)
• ✅ Create Storybook galleries
• ✅ Document current state
• 🎯 PRIORITY: Complete Storybook component parity (1 web + 1 mobile per division)
• 🎯 PRIORITY: Migrate documentation to Astro/Starlight (Diataxis model)

Next Session (TBD)

• User reviews icon galleries
• User provides art direction for first marker
• Create proof-of-concept marker
• Get approval to proceed

Future Milestones

• Milestone 1: First marker approved (1 session)
• Milestone 2: All 12 markers created (2-3 sessions)
• Milestone 3: Component integration complete (1 session)
• Milestone 4: Documentation & handoff (1 session)

Estimated Total Time: 5-7 development sessions (assuming efficient art direction)

---

Related Work

Current Branch

• feat/component-layering - Active work on LeafletMap and icon integration

Related Components

• packages/ui-pride-city/src/components/LeafletMap/ - Map component
• packages/storybook/stories/LeafletMap.stories.tsx - Current examples
• packages/storybook/stories/HeroiconsGallery.stories.tsx - Heroicons showcase
• packages/storybook/stories/TablerIconsGallery.stories.tsx - Tabler showcase

Related Documentation

• docs/LEAFLET_MAP_IMPLEMENTATION.md - LeafletMap component guide
• docs/COMPOSITE_MAP_MARKERS.md - Geoapify-style marker guide
• docs/MAP_PIN_ICON_SETS.md - Icon source reference
• docs/MARKER_ICONS_SUMMARY.md - Q&A format summary
• docs/ICON_LIBRARIES_INSTALLATION.md - Installation record

Post-Migration Locations

After Astro/Starlight migration, documentation will move to:

• apps/docs/src/content/docs/how-to/map-markers.mdx - Usage guide
• apps/docs/src/content/docs/design-system/map-icons.mdx - Design system entry
• apps/docs/src/content/docs/reference/leaflet-map-api.mdx - API reference

---

Resources

External References

• Geoapify Map Icons: https://www.geoapify.com/free-map-icons/
• Heroicons: https://heroicons.com/
• Tabler Icons: https://tabler.io/icons
• Leaflet Documentation: https://leafletjs.com/

Internal Resources

• Storybook: http://localhost:6006 (local)
• LeafletMap Stories: Design System → Pride City → Components → LeafletMap
• Heroicons Gallery: Design System → Heroicons Gallery
• Tabler Gallery: Design System → Tabler Icons Gallery

---

Next Actions

Immediate (This Session)

1. ✅ Create this initiative document
2. 🎯 Return focus to Storybook component parity
3. 🎯 Begin documentation migration to Astro/Starlight

Next Session (When Resuming This Project)

1. User reviews icon galleries in Storybook
2. User selects preferred icon style
3. User provides detailed art direction for “Single Man” marker
4. Agent implements first marker
5. Iterate until approved
6. Proceed with remaining 11 markers

---

Notes

• This project is paused but not abandoned - user is actively interested
• User has clear vision: visual markers for instant household identification
• Strong technical foundation already in place (LeafletMap, icon libraries, examples)
• Main blocker is user art direction time, not technical complexity
• Documentation migration takes priority this session per user directive
• Will resume after documentation work is complete

---

Document Version: 1.0
Last Updated: October 16, 2025
Next Review: When resuming project (post-documentation migration)