Soc UI

Separation of Concerns (SoC) for UI Styling and Scripts

When to Use

Use this skill whenever you write or restructure custom CSS or frontend JavaScript in a project that spans multiple pages, regardless of framework. It applies when adding a new page, adding a reusable component (modal, card, quote block), or cleaning up a stylesheet or script that has grown too large.

Before You Start

1. Inspect the existing project structure. If the project already has a clear convention for stylesheets or scripts (e.g. CSS Modules, a components/ folder with co-located files, a hooks/ or lib/ folder), follow it instead of introducing a new one.
2. If the project uses a utility framework such as Tailwind, prefer utility classes and only write custom CSS for what utilities cannot express cleanly. The CSS rules below then apply to that custom CSS.

The Three Tiers

Both CSS (S1) and JavaScript (S2) are sorted into the same three tiers. Never put everything into a single file by default, and never duplicate the same code across several pages.

As a guideline, "short" means roughly under 30 lines. Readability of the page file matters more than an exact count. When in doubt about Tier 2, prefer a separate component file: it keeps the global file small and makes the component easy to find, move and delete.

Promotion rule

When page-specific code starts being used on a second page, move it up to Tier 2 instead of copying it. When Tier 2 code ends up on every page, move it to Tier 1.

S1: CSS Styling

• Tier 1: Layout, navigation, footer, typography, color variables and resets go into one global stylesheet, e.g. app.css, globals.css or style.css, depending on the framework.
• Tier 2: A short component style may live in the global stylesheet under a comment header (e.g. /* === Modal === */). A longer or self-contained component gets its own stylesheet, e.g. modal.css, imported only where the component is used, or from the global stylesheet if it appears on most pages.
• Tier 3: Short page styles stay on the page (a <style> block, a scoped style, or the page's CSS Module). Long page styles move into a dedicated stylesheet, e.g. pricing.css, loaded only on that page.

S2: Frontend JavaScript

• Tier 1: Behavior needed on every page (navigation toggle, theme switch, global event setup) goes into the global entry script, e.g. app.js. Shared helpers (fetch wrapper, formatting, validation) go into small modules in a utils/ or lib/ folder and are imported where needed, not attached to window.
• Tier 2: Logic for a reusable component lives in its own module, e.g. modal.js, exporting an init function (or a hook/composable in component frameworks) and imported only on pages that use it. Only very small shared behavior used on most pages may stay in app.js, grouped under a comment header.
• Tier 3: Short page logic stays with the page (the page component, or a small module script in the page). Long page logic moves into a dedicated file, e.g. pages/pricing.js, loaded only on that page.

Keep structure, style and behavior apart

• Do not use inline event handlers (onclick="...") in HTML; attach listeners in the script.
• Do not set visual styles directly from JS (el.style.display = ...) for static states; toggle CSS classes (e.g. is-open) and define the look in CSS.
• Use data-* attributes as JS hooks (e.g. data-modal-open) instead of styling classes, so renaming a class for design reasons never breaks behavior.
• Separate non-UI logic (API calls, data transformation, business rules) from DOM or rendering code, e.g. in lib/ or services/, so it can be reused and tested independently.

Pair component files

When a component has both styles and behavior, keep them together, e.g. components/modal/modal.css and components/modal/modal.js, or Modal.jsx next to Modal.module.css.

Example

A website has six pages:

• All six share the same navigation bar → its styles go into app.css, its mobile menu toggle into app.js (Tier 1).
• Three pages use a modal spanning many lines → it gets modal.css and modal.js, imported on those three pages (Tier 2). A very small modal could instead live in the global files under a /* === Modal === */ header.
• One page has a quote block with four lines of CSS and a three-line "copy quote" button handler → both stay on that page (Tier 3, short).
• Another page has a custom animation with 80 lines of CSS and a 120-line pricing calculator → they move to hero-animation.css and pricing.js, loaded only on that page (Tier 3, long).

Framework Notes

• React / Next.js: Import global styles once at the app root (root layout or _app). For components and pages, prefer co-located CSS Modules such as Modal.module.css next to Modal.jsx. Extract reusable stateful logic into custom hooks (e.g. useModal) and non-UI logic into lib/. In the Next.js App Router, keep 'use client' components as small as possible and only where interactivity is needed.
• Vue: Global styles and setup in the entry file; component and page styles in <style scoped> blocks, or a separate file for long styles. Extract reusable logic into composables (e.g. useModal).
• Laravel (Blade + Vite): Global styles and scripts in resources/css/app.css and resources/js/app.js. Component or page files live in resources/css/ and resources/js/, must be added to the input array in vite.config.js, and are loaded with @vite(...) in the view that needs them (e.g. via @push('styles') and @push('scripts')).
• Plain HTML: Link the global stylesheet and script on every page, and additional files only on the pages that use them. Load scripts with <script type="module" src="...">, which is deferred by default.

Avoid

• One monolithic stylesheet or script containing page-specific code for every page.
• Copy-pasting the same rules or functions into multiple page files.
• Inline style="..." attributes for static styling and inline on* event handlers.
• Global variables on window for sharing code between files; use module imports.
• Creating a separate file for every few lines of code, which fragments the project without benefit.