Skip to main content

Decision Log

Architectural and design decisions for the Juniro design system.

DR-001: Tailwind CSS for Styling​

Date: December 2024 Status: Accepted Context: Need a styling approach that scales across multiple apps

Decision: Use Tailwind CSS as the primary styling solution.

Rationale:

  • Utility-first approach enables rapid development
  • Built-in design tokens (spacing, colors, typography)
  • Excellent dark mode support with dark: variants
  • Tree-shaking removes unused styles
  • Consistent across all repositories

Consequences:

  • Team must learn Tailwind conventions
  • Custom components need dark: variants
  • Some complex animations require custom CSS

DR-002: Lucide React for Icons​

Date: December 2024 Status: Accepted Context: Need a consistent, accessible icon library

Decision: Use Lucide React for all icons.

Rationale:

  • MIT licensed, actively maintained
  • 1000+ icons with consistent style
  • Tree-shakeable (only import what you use)
  • Supports customization (size, color, stroke)
  • Good accessibility defaults

Alternatives Considered:

  • Heroicons - Good but fewer icons
  • Font Awesome - Larger bundle, licensing
  • Custom SVGs - Maintenance burden

DR-003: Design System Repository Structure​

Date: December 2024 Status: Accepted Context: How to organize and share components across apps

Decision: Single juniro-design repo with one-way sync to consuming apps.

Structure:

juniro-design (source of truth)
    ↓ sync
├── juniro-web-public
├── juniro-web-parents
├── juniro-web-providers
└── juniro-web-admin

Rationale:

  • Single source of truth prevents drift
  • Changes flow in one direction
  • Easier to maintain consistency
  • Storybook serves as living documentation

Consequences:

  • Can't make component changes directly in consuming apps
  • Sync process adds deployment step
  • Need clear process for proposing changes

DR-004: Component Organization​

Date: December 2024 Status: Accepted Context: How to organize components in the design system

Decision: Organize by domain/portal:

components/ui/
├── shared-core/      # Base components (Button, Input, Modal)
├── shared-customer/  # Shared customer components (Cards, Booking)
├── public/           # Public website pages
├── parent-portal/    # Parent dashboard
├── provider-portal/  # Provider dashboard
└── admin-portal/     # Admin operations

Rationale:

  • Clear ownership and boundaries
  • Easy to find components
  • Supports selective syncing
  • Prevents circular dependencies

DR-005: Dark Mode Implementation​

Date: December 2024 Status: Accepted Context: Users expect dark mode; need consistent implementation

Decision: Use Tailwind's class-based dark mode with dark: prefix.

Pattern:

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">

Rationale:

  • Native Tailwind support
  • User preference respected via prefers-color-scheme
  • Can be toggled manually
  • Works with existing component structure

Consequences:

  • Every colored element needs dark: variant
  • Must test all components in both modes
  • Some colors need adjustment (orange lighter in dark mode)

DR-006: Storybook for Documentation​

Date: December 2024 Status: Accepted Context: Need interactive component documentation

Decision: Use Storybook as the primary component documentation.

Rationale:

  • Interactive examples > static docs
  • Shows all component states and variants
  • Supports visual regression testing
  • Industry standard tool
  • Can be deployed for stakeholder review

Deployments:

  • Customer: juniro-design-customer.vercel.app
  • Admin: juniro-design-admin.vercel.app

DR-007: PLG-First Design Approach​

Date: January 2025 Status: Accepted Context: Need to maximize conversion without aggressive sales

Decision: Design all customer-facing UI with Product-Led Growth principles.

Principles:

  1. Show value before requiring signup
  2. Reduce friction in core flows (search, booking)
  3. Progressive disclosure of features
  4. Guest checkout supported
  5. Clear upgrade paths

Consequences:

  • Auth walls moved later in user journey
  • More anonymous/guest state handling
  • Booking flow works without account
  • Clear CTAs for value moments

DR-008: Mobile-First Responsive Design​

Date: December 2024 Status: Accepted Context: Most users browse on mobile

Decision: Design mobile-first, enhance for larger screens.

Pattern:

// Mobile base, then responsive overrides
<div className="p-4 md:p-6 lg:p-8">
<div className="grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">

Rationale:

  • Mobile is primary use case for parents
  • Easier to add than remove styles
  • Better performance (simpler base styles)
  • Forces prioritization of content

Template for New Decisions​

## DR-XXX: [Title]

**Date:** [Month Year]
**Status:** Proposed | Accepted | Deprecated | Superseded
**Context:** [What is the issue?]

**Decision:** [What is being decided?]

**Rationale:**
- [Why this approach?]

**Alternatives Considered:**
- [Option A] - [Why not]
- [Option B] - [Why not]

**Consequences:**
- [What are the tradeoffs?]

Decision records help future team members understand why things are built the way they are.