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.

• 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 screen sizes (desktop, tablet, mobile).
• 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.
• Visual Feedback: Provide clear indicators for user actions, errors, and confirmations.

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

• Use primary indigo 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.
• Use neutral colors for titles and text-heavy content.

• 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 to improve accessibility.

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.

• Use consistent padding and margin for all components.
• Maintain alignment and spacing for nested components (e.g., forms within modals).
• Ensure all components are fully keyboard and screen reader accessible.

• 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.

• 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.

• Follow Ruby Style Guide.
• Use snake_case for files, methods, and variables.
• Use CamelCase for classes and modules.
• Ensure one responsibility per model, controller, or service.
• All database changes must be reflected in schema.rb.

bin/rails lint        # Custom binstub
yarn lint             # Frontend lint
rubocop -A            # Auto-fix Ruby
prettier --write .    # Format JS, CSS

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

• Keyboard Navigation: All UI must be navigable via keyboard (Tab, Enter, Escape).
• Semantic HTML: Use semantic elements (<button>, <nav>, <main>, etc.) to enhance accessibility.
• Screen Reader Support: Include aria-labels, aria-live regions, and descriptive alt text.
• Color Contrast: Maintain WCAG-compliant contrast ratios for text and interactive elements.
• Focus States: Ensure all focus states are visually distinct and easily identifiable.

• Tailwind CSS Documentation
• Lucide Icons
• WCAG Guidelines
• Ruby Style Guide
• ESLint Configs
• Prettier Rules

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

This comprehensive guide ensures clarity, consistency, and accessibility in both the design and codebase of StateForce.