Skip to content

Frontend Styling

This guide documents the current styling structure in Easy8 and the conventions we use when writing CSS and SCSS.

Choose the Right Styling Layer

Easy8 has more than one styling layer. Before adding styles, first identify which layer the feature already belongs to.

  • New reusable UI belongs in the Design System under app/frontend/src/design_system/.
  • Existing legacy screens, ERB views, and easy_ui integrations usually keep using the legacy Easy styles under app/frontend/src/shared/stylesheets/easy/.
  • Vuetify skinning and component overrides belong under app/frontend/src/shared/stylesheets/vuetify/ when that override already exists there.

Do not move a feature between styling systems just because you are touching it. Extend the existing layer unless you are doing an intentional migration.

Main Locations

  • app/frontend/src/design_system/**/stylesheets/ - component-local Design System styles.
  • app/frontend/src/design_system/shared/stylesheets/ - Design System shared variables, mixins, functions, and foundations.
  • app/frontend/src/shared/stylesheets/easy/_base.scss - main legacy Easy stylesheet entrypoint.
  • app/frontend/src/shared/stylesheets/easy/_common-assets.scss - shared legacy exports for variables, abstracts, and themes.
  • app/frontend/src/shared/stylesheets/easy/global/ - global rules and foundations.
  • app/frontend/src/shared/stylesheets/easy/patterns/ - legacy UI buckets grouped by usage area.
  • app/frontend/src/shared/stylesheets/easy/themes/ - themes and brand-related output.
  • app/frontend/src/shared/stylesheets/easy/variables/ - legacy Easy variables.
  • app/frontend/src/shared/stylesheets/vuetify/ - Vuetify overrides.

General Rules

  • Keep styles in the same layer as the feature you are editing.
  • Keep selectors as flat as possible. Prefer classes over long descendant chains.
  • Avoid !important unless you are fixing a real override problem that cannot be solved cleanly.
  • Reuse existing variables, mixins, and placeholders before introducing new values or abstractions.
  • Keep feature-specific rules close to the owning component, page, or pattern.
  • Follow naming already used in the edited area instead of forcing a new naming convention into old code.

SCSS Reuse

The codebase uses modern Sass module syntax with @use and @forward.

  • Use @mixin when the style needs configuration or reusable generated output.
  • Use placeholders with @extend %placeholder for fixed shared declaration groups.
  • Prefer extending placeholders, not concrete HTML selectors or unrelated component classes.
  • When working in legacy Easy styles, look for reusable assets in utils/abstracts/ and shared exports from _common-assets.scss.
  • Many legacy pattern files expose @mixin styles; wire them through the owning entrypoint instead of scattering duplicate imports.

Legacy Easy Styles Structure

The app/frontend/src/shared/stylesheets/easy/ tree is still important, but its folder names should be read as implementation organization, not as a required design methodology.

  • global/ - global foundations and cross-app behavior.
  • patterns/00-elements/ - low-level element styling.
  • patterns/01-fragments/ - reusable legacy fragments.
  • patterns/02-components/ - legacy component-level styling.
  • patterns/03-pages/ - page-specific legacy styling.
  • patterns/04-plugins/ - plugin-specific legacy styling.
  • themes/ - theme output and brand-specific values.
  • utils/abstracts/ - mixins, placeholders, and utility building blocks.
  • variables/ - legacy variables and icon definitions.

The numbered patterns/* folders are historical buckets. Do not use them as a reason to describe new work as Atomic Design. For current frontend architecture, prefer the actual module or component boundary you are editing.

Design System Styles

For new reusable UI:

  • Keep styles next to the Design System component under stylesheets/.
  • Reuse tokens, utilities, and foundations from app/frontend/src/design_system/shared/stylesheets/.
  • Prefer local Design System styling over patching the legacy Easy stylesheet when the component itself owns the behavior.
  • If a Design System component needs legacy compatibility, keep that bridge explicit instead of leaking legacy selectors into unrelated components.

Themes and Branding

Theme and brand customization are documented separately in Theme Configuration and custom branding.

Use that guide for:

  • brand asset overrides,
  • theme CSS variables,
  • brand fonts,
  • custom color maps,
  • client-specific visual customization.