Style Guide

🎨 Style Guide

This page outlines the visual design principles, UI/UX standards, and code style conventions used in the StateForce project. Our goal is to ensure clarity, usability, maintainability, and consistency across all parts of the system — from frontend interfaces to backend logic.

---

🧭 UI/UX Principles

• Consistency: All pages follow a unified layout grid, spacing system, and interaction behavior.
• Clarity First: Prioritize clean visual hierarchy and intuitive interfaces over excessive decoration.
• Accessibility: Comply with WCAG 2.1 (AA) for color contrast, keyboard access, and screen reader support.
• Responsiveness: The UI must adapt seamlessly to different desktop screen sizes.
• Efficiency for Operators: Interfaces are optimized for low-friction use in high-pressure environments.
• Minimalism for Critical Actions: Avoid cognitive overload during high-stress tasks.

---

🎨 Color Palette

Color Usage	HEX	Notes
Primary (Indigo)	#1E40AF	Used for main actions and UI highlights
Secondary (Pink)	#1E40AF	Used for secondary actions and UI highlights
Warning (Orange)	#F59E0B	Used for warnings, alerts, or callouts
Success (Green)	#10B981	Confirmations and success states
Danger (Red)	#EF4444	Errors and critical alerts
Background	#F9FAFB	Default background for most layouts
Neutral	#111827	High contrast for readability
Text	#6B7280	Used for muted or secondary information
Info	#6B7280	Used for content text

Custom TailwindCSS Configuration

All colors are chosen with WCAG-compliant contrast for accessibility.

Guidelines

• Use primary blue for actionable buttons and navigation.
• Use danger red only for destructive actions (e.g. delete, stop emergency unit).
• Maintain at least 4.5:1 contrast ratio for text on background.

---

✍️ Typography

• Font Family: Inter, sans-serif.
• Base Size: 16px (1rem).

• Hierarchy:

  • text-2xl → Page headers
  • text-xl → Section titles
  • text-base → Body text
  • text-sm → Captions, meta text

• Font Weight: Regular for body text, Medium/Bold for headings
• Line Height: 1.5 (default) for optimal readability

All headings should maintain semantic structure (<h1> to <h4>) and be used consistently.

---

🧩 Components

The design system includes a library of reusable components built using Tailwind CSS:

• Buttons: Primary, secondary, destructive, disabled states
• Forms: Input fields, selects, checkboxes, toggles with full error handling
• Modals: Centered, dismissable, with keyboard accessibility
• Cards: For dashboard metrics or grouped content
• Badges: For incident status indicators
• Navigation: Sidebar layout with collapse behavior and active route highlighting

---

🖼️ Icons and Imagery

• Icon Library: Lucide
• Usage Guidelines:
  • Icons should support and reinforce meaning, not replace it.
  • Use stroke icons (not filled) for consistency.
  • All icons must include descriptive aria-labels for screen readers.
• Imagery:
  • Avoid decorative images.
  • Use vector illustrations when appropriate (e.g., for empty states or error pages).
  • Ensure images scale well on all screen sizes and do not introduce visual clutter.

---

🧱 Code Style

🖥️ Frontend (Tailwind + Stimulus)

• Framework: Tailwind CSS
• CSS/Utility:
  • Utility-first approach using Tailwind
  • No custom CSS unless necessary for overrides
• Class Naming:
  • Semantic and descriptive (btn-primary, card-alert, etc.)
  • Use data-role attributes for JS bindings when needed

Stimulus controllers:

• Directory: app/javascript/controllers
• Naming: incident_controller.js, dashboard_controller.js
• Use data-action for event bindings and data-* for configuration.

⚙️ Backend (Rails)

• Follow Ruby Style Guide
• Snake_case for files, methods, and variables
• CamelCase for classes and modules
• One responsibility per model/controller/service
• All database changes must be reflected in schema.rb

🧠 JavaScript

• Use ES6+
• StimulusJS controllers for modular JS behavior
• Controller naming: data-controller="incident-map", file: incident_map_controller.js
• Avoid inline JS — use data attributes or Stimulus actions
• Prefer async/await over .then() chaining

---

🧹 Linting and Formatting

Language	Tool	Notes
Ruby / Rails	rubocop	Run via bundle exec rubocop
JavaScript	eslint	Configured for ES6
CSS / Tailwind	prettier	With Tailwind plugin
YAML	yamllint	For config files

Running Linters

bin/rails lint        # custom binstub
yarn lint             # frontend lint
rubocop -A            # auto-fix Ruby
prettier --write .    # format JS, CSS

• Git Hooks:
  • Use pre-commit hook to auto-lint and format code before pushing

---

♿ Accessibility Guidelines

• All UI must be navigable via keyboard (Tab, Enter, Escape)
• Use semantic HTML: <button>, <nav>, <main>, etc.
• Include aria-labels, aria-live regions, and descriptive alt text
• Avoid display: none on elements you intend to make accessible — use aria-hidden
• Use focus semantic colors to get the best visibility and distinguishable look

---

📚 References

• Tailwind CSS Documentation
• Lucide Icons
• WCAG Guidelines
• shadcn/ui Docs
• Ruby Style Guide
• ESLint Configs
• Prettier Rules

For major UI updates, please submit a proposal and screenshots via a GitHub issue.