Modules, Components and Modifiers

Synergy is just a practical application of certain theories and philosophies. One of the main philosophies includes the way UI elements are viewed. In a world of HTML and CSS, this could equate to something as simple as a "naming convention" (e.g. BEM), but in a world of abstract UI modules, an idea with more depth is needed.

Put simply, the way Synergy views a UI is a series of Modules that are composed of Components, both of which can have Modifiers.

See the Synergy Values page for more information

Synergy Modules are broken up into the following realms:

• Configuration
• Styles
• Interactions
• Interface

In Synergy, a module can be represented in each realm. A Synergy Module may resemble the following structure, taking each realm into account:

Learn more about module architecture

|-- modules
|   |-- accordion
|   |   |-- accordion.jsx
|   |   |-- configuration.json
|   |   |-- interactions.js
|   |   |-- styles.scss

Each file within the accordion directory represents the module in different realms, with the interface realm tying them together.

Learn more about Module realms

Modules

A module is a UI element that represents any isolatable part of an app/page. Modules can have modifier variants (modifiers) and contain child components.

• Modules and Configuration
• Modules and Interactions
• Modules and Styling
• Modules and Interfaces

Some common modules for a web app might include:

Accordion	Alert-Bar	Billboard
Blockquote	Breadcrumb	Button
Card	Carousel	Container
Dropdown	Footer	Form
Header	Image	List
Logo	Modal	Navigation
Overlay	Preloader	Progress-Bar
Table	Tabs	Tooltip
Scroll-Top	Search	Side-Nav

If your list of modules becomes too much, it may be worth considering looking at ways to categorise them.

View a complete example of a module

Components

Components must belong to a parent Module

A component can be thought of as a 'sub-module' of a main parent module. A component is any element within a module that has a direct relationship to the module.

Not to be confused with React Components

• Components and Configuration
• Components and Interactions
• Components and Styling
• Components and Interfaces

Examples

<Module name='accordion'>
    <Component name='panel'>
        <Component name='title' />
        <Component name='content' />
    </Component>

    <Component name='panel'>
        <Component name='title' />
        <Component name='content' />
    </Component>
</Module>

<Module name='modal'>
    <Component name='title' />
    <Component name='content' />
    <Component name='close' />
</Module>

Sub-Components

Where possible it is recommended to avoid using sub-components and stick to regular components

A Sub-Component is an element that has a direct relationship to a parent Component or parent Sub-Component.

• Sub-Components and Configuration
• Sub-Components and Interactions
• Sub-Components and Styling
• Sub-Components and Interfaces

Example

Consider the following module interface:

<Module name='header'>
    <Component name='navigation'>
        <SubComponent name='item'>...</SubComponent>
        ...
    </Component>
</Module>

Which would render:

<div class="header">
    <div class="header_navigation">
        <div class="header_navigation_item">...</div>
        ...
    </div>
</div>

This is a good use-case for Sub-Components as using <Component> instead would render:

<div class="header">
    <div class="header_navigation">
        <div class="header_item">...</div>
        ...
    </div>
</div>

...which is semantically less meaningful. Using SubComponent in the above example saves from having to do something like:

<Module name='header'>
    <Component name='navigation'>
        <Component name='navItem' />
        ...
    </Component>
</Module>

Since it's recommended to avoid using Sub-Components, the above example should ideally be refactored to make navigation its own module:

<Module name='header'>
    <Module name='navigation'>
        <Component name='item' />
        ...
    </Module>
</Module>

When to Use

It can be tempting to use sub-components, and whilst they do have their legitimate use-cases, always ask yourself if a regular component would be better. Using too many Sub-Components within a module can be a sign that your modules aren't generic enough (which can lead to issues with scalability and maintainability). Consider the following HTML rendered by a hypothetical Accordion Synergy module:

<div class="accordion">
    <div class="accordion_panel">
        <div class="accordion_panel_title">foo</div>
        <div class="accordion_content">bar</div>
    </div>
    <div class="accordion_panel">
        <div class="accordion_panel_title">fizz</div>
        <div class="accordion_panel_content">buzz</div>
    </div>
</div>

Here accordion_panel_title and accordion_panel_content are sub-components, but do they really need to be? The following HTML makes arguably just as much sense:

<div class="accordion-foo-bar">
    <div class="accordion_panel">
        <div class="accordion_title">foo</div>
        <div class="accordion_content">bar</div>
    </div>
    <div class="accordion_panel">
        <div class="accordion_title">fizz</div>
        <div class="accordion_content">buzz</div>
    </div>
</div>

...having replaced the sub-components with regular components. Unfortunately there is no hard way to determine which is more appropriate, as you may feasibly have the following HTML for an accordion:

<div class="accordion">
    <div class="accordion_title">title</div>
    <div class="accordion_panels">
        <div class="accordion_panel">
            <div class="accordion_panel_title">foo</div>
            <div class="accordion_content">bar</div>
        </div>
        <div class="accordion_panel">
            <div class="accordion_panel_title">fizz</div>
            <div class="accordion_panel_content">buzz</div>
        </div>
    </div>
</div>

...in which case you have no better choice than to use sub-components as there are two layers of title elements (one for the accordion as a whole, and one for each panel). Consider that this may be a sign that the module isn't generic enough (will all accordions really require their own title? Could the title instead be abstracted to a higher-order component?). One thing can be said for sure and that is that the above is certainly better than:

<div class="accordion">
    <div class="accordion_title">title</div>
    <div class="accordion_panels">
        <div class="accordion_panels_panel">
            <div class="accordion_panels_panel_title">foo</div>
            <div class="accordion_panels_content">bar</div>
        </div>
        <div class="accordion_panels_panel">
            <div class="accordion_panels_panel_title">fizz</div>
            <div class="accordion_panels_panel_content">buzz</div>
        </div>
    </div>
</div>

It's absolutely unnecessary to make each panel a sub-component of panels, and this goes for any singular/plural combination (item and items, feature and features, article and articles etc...).

Modifiers

A modifier can be applied to both modules and components, and allow for variants of the module to be used. Modifiers are useful for changing things like appearance, behaviour and state. There is no limit to the number of modifiers that can be applied to a module or component.

• Modifiers and Configuration
• Modifiers and Interactions
• Modifiers and Styling
• Modifiers and Interfaces

Example

<Button>Button</Button>
<Button large>Button</Button>
<Button primary>Button</Button>
<Button large primary>Button</Button>