UI Component Anatomy

UI component folder structure and file names all have specific purposes. The combinations of names and file location allows us to easily automatically build the guide, understand theme support, css structure, component behavior, and guide examples.

Let's take a look at a typical guide component folder breakdown through a possible breakdown for the fictitious component <my-tabs>:

    /myTabs
        index.scss
        my.tabs.example.controller.js
        my.tabs.component.js
        my.tabs.module.js
        readme.md
        /snippets
            default.html
            modifier.example.html
        /theme
            index.scss

Let's discuss the purpose of each file.

/myTabs/index.scss

This file contains core structural CSS concerns for the my-tabs component. We would expect the contents of the file to follow BEM syntax and include the structural style under the class name of c-myTabs. See our scss writing guidelines for the appropriate class naming and css property authoring rules.

/myTabs/my.tabs.example.controller.js

This file contains an example controller for use within the examples found within the snippets. This file is should follow our controller naming conventions and class structure.

/myTabs/my.tabs.component.js

This file contains the core behavior (controller) and binding for <my-tabs>. The binding and controller should follow the standards for presentations components found on https://confluence.csgicorp.com/pages/viewpage.action?pageId=606619326

/myTabs/my.tabs.module.js

This file contains the angular module definition for the component. It also pulls in any angular dependencies as part of the module definition. The is the JavaScript file that is to be imported by the parent module.

/myTabs/readme.md

This file is the essential building block for the guide. All index.html files in the guide are generated from the readme.md files within the guide's folders.

The readme markdown files can contain any free markdown documentation that makes sense for a component. The files also contain YAML based front-matter, which the guide builder will use to pull in a few typical pieces of information. For example, our guide markdown for the my-tabs component may look something like this:

    ---
    title: My Tabs
    description: Short description of the overall component.
    variants:
    -
        name: Typical Usage
        description: A description about the typical/default use of my tabs
        snippet: ./snippets/default.html
    -
        name: Modifier
        description: A description about some modifier use of my tabs
        snippet: ./snippets/modifier.example.html
    ---
    ## Some extra markdown based documentation about my-tabs here!

/snippets/[snippet name].html

These snippet files are the example files that the guide uses to build the living + automatically documented markup. Use your example controllers and mock data within them to showcase the components states, mofidiers, and functionality. You can add any number of example variants that make sense for your component.

/theme/index.scss

This file is typically imported at the end of the index.scss file at the root of the component. It contains any themeable area support, including brand and content themeable area themeing. Older version of the theme folder may have the themes broken into discretely separate files (i.e. _brand.scss and _content.scss), but this is no longer required.

Brand theme in /theme/index.scss

This is where we define any theme that is using the brand color, which changes depending upon the application module. The brandStyling mixin will add the appropriate theme classes (i.e. t-reporting, t-care, etc) for you. You will also have access to a $brandColor variable. The css written in this file is replicated per applicaton module - therefore, it is important to only define properties in this file that need to use brandColor.

As an example, we may define the following css within theme/index.scss:

@include brandStyling() {
    .c-content {
        .c-myTabs {
            .c-myTabs-title {
                color: $brandColor;
            }
        }    
    }
}

Content theme in /theme/index.scss

Here we define all of our neutral styling that goes within the t-content theme-able area. The contentThemeStyling mixin is available to add the appropriate theme-able area classes above your descendent selectors.

Our my-tabs content theme may look something like this:

    @include contentThemeStyling() {
        .c-myTabs {
            .c-myTabs-title {
                border-color: palette(invison, border_medium);
            }
        }
    }

File Naming

The ui guide naming standard may largely appear mixed. This is because the ui guide started with a camelCase file naming standard, but most other Invision projects used the . between standard. Please adhere to the project-wide . standard for file names moving forward.

Good:

sample.snippet.html

Bad:

sampleSnippet.html

This is required for new files, and recommended for files you may be editing as part of a pr. Please use git mv to actually move files to the new name to preserve the git history on the file.