Documentation

UI/UX Consistency Plan

Context

The app has grown organically and UI patterns have diverged across features. Toggles, buttons, colors, and form navigation (modal vs full-page) are inconsistent. This plan standardizes everything to create a cohesive UX.

Reference Patterns (THE STANDARD)

Tab/View Toggle — Pill Container

Source: app/views/organizations/accounts/index.html.erb lines 36-54

<div class="flex rounded-xl overflow-hidden p-0.5 bg-gray-200/60 dark:bg-[#1e2736]">
  <button class="px-4 py-2 rounded-xl text-[13px] font-semibold bg-blue-500 text-white transition-all">
    Active Tab
  </button>
  <button class="px-4 py-2 rounded-xl text-[13px] font-semibold text-gray-500 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-white/5 transition-all">
    Inactive Tab
  </button>
</div>

Rules:

  • Container: rounded-xl overflow-hidden p-0.5 bg-gray-200/60 dark:bg-[#1e2736]
  • Active: bg-blue-500 text-white
  • Inactive: text-gray-500 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-white/5
  • No emoji/icons inside toggle buttons

New/Edit — Always Turbo Modal

<%# new.html.erb / edit.html.erb %>
<%= turbo_frame_tag :modal do %>
  <%= render "shared/turbo_modal", modal_title: "Title", modal_size: "default" do %>
    <%= render "form", resource: @resource %>
  <% end %>
<% end %>

Links must have data: { turbo_frame: :modal }.

Add Button — Blue (exception: Expenses = red)

<%= link_to new_resource_path,
    class: "flex items-center gap-2 px-4 py-2.5 rounded-xl text-white text-[13px] font-semibold transition-all hover:scale-[1.02]",
    style: "background: linear-gradient(135deg, #3b82f6, #2563eb);",
    data: { turbo_frame: :modal } do %>
  Label Text
<% end %>
  • No emoji/icon spans before the label
  • Blue for everything except "New Expense" (red: #ef4444 → #dc2626)

Edit Button — SVG Icon + Helper

<%= edit_icon_button(edit_resource_path(resource)) %>

Color Semantics

  • Blue (#3b82f6) — neutral data display, primary actions
  • Green (#10b981) — positive/increasing values
  • Red (#ef4444) — negative/decreasing values
  • No purple, orange, pink, or amber for data display or primary actions

Phase 1 — Toggle Standardization

1.1 Accounts Toggle — Remove Emojis

File: app/views/organizations/accounts/index.html.erb (lines 41, 49)

  • Remove <span class="text-sm leading-none">🏦</span>
  • Remove <span class="text-sm leading-none">⏰</span>
  • Container and classes already correct

1.2 Dashboard Toggle — Remove Emojis

File: app/views/organizations/dashboard/index.html.erb (lines 7-21)

  • Remove <span class="text-sm leading-none">👤</span> from individual button
  • Remove <span class="text-sm leading-none">👪</span> from family button
  • Container and classes already correct

1.3 Birthdays List/Calendar Toggle — Restyle to Pill

File: app/views/organizations/birthdays/index.html.erb (lines 9-16)

  • Change container from rounded-lg border to pill pattern: rounded-xl overflow-hidden p-0.5 bg-gray-200/60 dark:bg-[#1e2736]
  • Change button classes to match standard active/inactive
  • Remove SVG icons from toggle buttons, use text labels only

1.4 Analytics 3-Way Toggle — Restyle to Pill

File: app/views/organizations/analytics/index.html.erb (lines 124-144)

  • Change container from bg-gray-100 dark:bg-white/[0.04] border to pill pattern
  • Apply standard active/inactive classes
  • Also update app/javascript/controllers/analytics_controller.js to use matching active/inactive class strings when switching

1.5 Goals Tab Toggle — Restyle to Pill

File: app/views/organizations/goals/index.html.erb (lines 21-32)

  • Replace current background: rgba(255,255,255,0.04) container with pill pattern
  • Apply standard active/inactive classes to both tab links

Not in scope

  • Settings ON/OFF sliding switches → keep as-is (different UI pattern)
  • Notification preference checkboxes → keep as-is
  • Gamification sidebar tabs → keep as-is (navigation pattern, not content toggle)

Phase 2 — New/Edit Modal Conversion

Convert all full-page new/edit views to turbo modals. Each conversion requires:

  1. Replace new.html.erb and edit.html.erb content with turbo_frame_tag :modal wrapper
  2. Add data: { turbo_frame: :modal } to all links pointing to new/edit
  3. Adapt the _form.html.erb cancel action if needed

2.1 Sports

  • app/views/organizations/sports/new.html.erb → modal wrapper
  • app/views/organizations/sports/edit.html.erb → modal wrapper
  • app/views/organizations/sports/index.html.erb line 12 → add data: { turbo_frame: :modal }
  • app/views/organizations/sports/show.html.erb edit link → add data: { turbo_frame: :modal }

2.2 Birthdays

  • app/views/organizations/birthdays/new.html.erb → modal wrapper
  • app/views/organizations/birthdays/edit.html.erb → modal wrapper
  • app/views/organizations/birthdays/index.html.erb lines 17, 113, 144 → add data: { turbo_frame: :modal }

2.3 Notes

  • app/views/organizations/notes/new.html.erb → modal wrapper (use modal_size: "large" for text area)
  • app/views/organizations/notes/edit.html.erb → modal wrapper (use modal_size: "large")
  • app/views/organizations/notes/index.html.erb line 14 → add data: { turbo_frame: :modal }
  • app/views/organizations/notes/show.html.erb line 31 → add data: { turbo_frame: :modal }

2.4 Countdowns

  • app/views/organizations/countdowns/new.html.erb → modal wrapper
  • app/views/organizations/countdowns/edit.html.erb → modal wrapper
  • app/views/organizations/countdowns/index.html.erb lines 7, 75 → add data: { turbo_frame: :modal }

2.5 Market Lists

  • app/views/organizations/market_lists/new.html.erb → modal wrapper
  • app/views/organizations/market_lists/edit.html.erb → modal wrapper
  • app/views/organizations/market_lists/index.html.erb line 7 → add data: { turbo_frame: :modal }
  • app/views/organizations/market_lists/show.html.erb line 20 → add data: { turbo_frame: :modal }

2.6 Construction Projects

  • app/views/organizations/construction_projects/new.html.erb → modal wrapper (modal_size: "large")
  • app/views/organizations/construction_projects/edit.html.erb → modal wrapper (modal_size: "large")
  • app/views/organizations/construction_projects/index.html.erb line 7 → add data: { turbo_frame: :modal }
  • app/views/organizations/construction_projects/show.html.erb line 16 → add data: { turbo_frame: :modal }

2.7 Construction Phases

  • app/views/organizations/construction_phases/new.html.erb → modal wrapper
  • app/views/organizations/construction_phases/edit.html.erb → modal wrapper
  • app/views/organizations/construction_projects/show.html.erb new/edit phase links → add data: { turbo_frame: :modal }

2.8 Construction Expenses

  • app/views/organizations/construction_expenses/new.html.erb → modal wrapper (modal_size: "large")
  • app/views/organizations/construction_expenses/edit.html.erb → modal wrapper (modal_size: "large")
  • app/views/organizations/construction_expenses/index.html.erb lines 12, 48 → add data: { turbo_frame: :modal }
  • app/views/organizations/construction_projects/show.html.erb new/edit expense links → add data: { turbo_frame: :modal }

2.9 Activity Logs (new only — no edit action in routes)

  • app/views/organizations/activity_logs/new.html.erb → modal wrapper
  • app/views/organizations/sports/index.html.erb line 8 → add data: { turbo_frame: :modal }

2.10 Contractors (if views exist)

  • Same pattern as construction phases/expenses

Phase 3 — Button Standardization

3.1 Add Buttons — Change to Blue, Remove Emojis

File Current Color Change Remove Emoji
accounts/index.html.erb line 19 Green #10b981 (New Registry) → Blue #3b82f6 📋
accounts/index.html.erb line 26 Blue ✓ (New Account) Keep 🏦
dashboard/index.html.erb line 26 Red ✓ (New Expense) Keep no icon
dashboard/index.html.erb line 33 Green #10b981 (New Registry) → Blue 📋
expenses/index.html.erb line 21 Red ✓ (New Expense) Keep no icon
habits/index.html.erb line 12 Purple #8B5CF6 → Blue ✅
investments/index.html.erb line 27 Blue ✓ Keep no icon
goals/index.html.erb line 11 Green #10B981 → Blue 🎯
notes/index.html.erb line 14 Amber #f59e0b → Blue SVG icon
birthdays/index.html.erb line 17 Pink #ec4899 → Blue SVG icon
sports/index.html.erb line 12 Blue ✓ Keep SVG icon
countdowns/index.html.erb line 7 Blue ✓ Keep SVG icon
market_lists/index.html.erb line 7 Green #10b981 → Blue SVG icon
construction_projects/index.html.erb line 7 Amber #f59e0b → Blue SVG icon
construction_expenses/index.html.erb line 12 Amber #f59e0b → Blue SVG icon

3.2 Edit Buttons — Standardize to SVG Icon Helper

All edit buttons should use:

<%= edit_icon_button(edit_path) %>

Files to update (replace SVG pencils or text "Edit" buttons):

  • birthdays/index.html.erb edit links
  • countdowns/index.html.erb line 75
  • construction_projects/show.html.erb lines 16, 101, 148 (project, phase, expense edits)
  • notes/show.html.erb line 31
  • market_lists/show.html.erb line 20
  • habits/_habit.html.erb (emoji/edit variations → helper)
  • sports/show.html.erb edit link

3.3 Form Submit Buttons — Align Colors

File Current Color Change
birthdays/_form.html.erb Pink #ec4899 → Blue #3b82f6
market_lists/_form.html.erb Green #10b981 → Blue #3b82f6
construction_phases/_form.html.erb Amber #f59e0b → Blue #3b82f6
construction_expenses/_form.html.erb Amber #f59e0b → Blue #3b82f6

Also change focus:ring-amber-500 → focus:ring-blue-500 in construction form fields.

Phase 4 — Analytics & Statistics Color Standardization

4.1 Analytics Page

File: app/views/organizations/analytics/index.html.erb

Line(s) Current Change
MoM badges (54-55, 72-74, 90-93) Purple #a855f7 → Blue #3b82f6
MoM positive value Purple #a855f7 → Blue #3b82f6
Média Mensal positive Purple #a855f7 → Green #10b981
Melhor Mês value Orange #f97316 → Green #10b981
Projeção patrimony Purple #a855f7 → Blue #3b82f6
Chart legend colors Teal/cyan variants → Use consistent blue shades

4.2 Habits Analytics

File: app/views/organizations/habits/analytics.html.erb

Line(s) Current Change
Stat cards (17-22) Purple #8b5cf6, Amber #f59e0b, Pink #ec4899 → Blue, Green, Blue
Category bars (175) Already blue ✓ Keep
Leaderboard podium (198) Gold/silver/bronze custom hex Keep (domain-specific)

4.3 Habits Index

File: app/views/organizations/habits/index.html.erb

Line(s) Current Change
Progress ring (27) Purple #8B5CF6 → Blue #3b82f6
Streak numbers (56-68) Orange, Amber, Purple → Green (positive), Blue (neutral)
Weekly bars today (86) Purple bg-purple-500 → Blue bg-blue-500

4.4 Sports Index — Stat Icon Backgrounds

File: app/views/organizations/sports/index.html.erb

Stat Current Change
Total time icon bg Purple rgba(139,92,246,0.1) → Blue rgba(59,130,246,0.1)

Phase 5 — Additional Consistency Improvements

5.1 Gamification Tabs

File: app/views/organizations/gamification/show.html.erb

  • If using a tab toggle pattern, align with the pill standard
  • Change text-emerald-400 to text-green-400 for consistency with helpers

5.2 Card Backgrounds

Several views use inline style="background: #161b22" which only works in dark mode. These should use bg-white dark:bg-[#161b22] with proper light mode support:

  • liquidity/index.html.erb (multiple cards)
  • construction_phases/new.html.erb, edit.html.erb
  • sports/new.html.erb, edit.html.erb (will be modals after Phase 2)

5.3 Empty State Icon Backgrounds

Standardize empty state icon backgrounds to blue rgba(59,130,246,0.08) instead of random colors (current: red for expenses is fine as it's the expense exception).

5.4 FAB (Floating Action Button) Colors

File: app/views/shared/_fab.html.erb and all FAB renders

  • Ensure FAB primary color is blue for all features except expenses (red)
  • Update FAB renders in: accounts/index.html.erb, investments/index.html.erb, goals/index.html.erb, dashboard/index.html.erb

Execution Order

Phase 1 (Toggles) ← start here, independent
Phase 3.1 (Add button colors) ← independent
Phase 2 (Modal conversions) ← per resource, independent of each other
Phase 3.2 (Edit buttons) ← after Phase 2 for each resource
Phase 3.3 (Form submit colors) ← after Phase 2
Phase 4 (Analytics colors) ← fully independent, can be done anytime
Phase 5 (Additional) ← after all others

Verification

After each phase, manually test in browser:

  • Phase 1: Visit /accounts, /dashboard, /birthdays, /analytics, /goals — verify toggles match pill pattern, no emojis
  • Phase 2: Click every "New" and "Edit" button — verify modal opens (not full page), modal closes on save, validation errors show in modal, Escape/backdrop closes modal
  • Phase 3: Verify all add buttons are blue (except expenses=red), all edit buttons use SVG icon helper, form submits are blue
  • Phase 4: Visit /analytics, /habits, /habits/analytics — verify only blue/green/red colors in data displays
  • Phase 5: Check card backgrounds in light mode, FAB colors, empty states