Introduction

Vocabulary is a refactor and reimplementation of the original, now archived, Vocabulary Legacy project.

Both projects are informed by the CC Style Guide (2019), and incorporate or adapt its guidance into a digital context.

Structure & Behavior

Vocabulary is raw material design system with inherent rules and generalized implementable documentation.

Vocabulary is then implemented within a project via an upstream/downstream relationship as follow:

    Design System → Static Implementation → Dynamic Implementation
    vocabulary → prototype → final
    vocabulary -> [project]-prototype -> [project]-[implementation(s)] (*-dev-env *-theme, etc.)

In the case of the Index Project (CreativeCommons.org) it looks like this:

    vocabulary → index-prototype → vocabulary-theme

A prototype contains:

• [vocabulary]
• project source of truth implementations (contexts mostly)
• localized functionality (new contexts, etc., until moved into vocabulary) (functionality)
• patches (temp overrides, until moved into vocabulary) (fixes)

We need to maintain a way to test F/E UX absent a CMS layer. That way the static layer prototype describes the intended output the CMS would create. It becomes a form of documentation and testing. It's an expectation spec.

It's one additional layer of downstream changes, but it provides a clear and distinct documentation for how and where things are localized when vocabulary is implemented, and can offer good examples for where we can pull varied localized implementations upstream into vocabulary generally, so the localizations can then be removed.

Upstream/Downstream Change Flow

A: upstream → downstream

1. new functionality introduced into Vocabulary
2. documented and generalized
3. available to prototypes and implementations

B: downstream -> upstream -> downstream

1. new functionality introduced local to project prototype
2. documented and implemented here locally
3. migrated to vocabulary
4. documented and generalized
5. removed in downstream project's prototype localization
6. available to prototypes and implementations

Either route is valid, and has its reasons for being the more viable route. But it is generally preferred that route A be the default consideration wherever possible.

Installation

01. Get the Vocabulary Files

Download the creativecommons/vocabulary repository, rename the /src directory to /vocabulary, and move it into desired location.

Vocabulary needs to be included via CSS and JavaScript routes. Both are generally required, and recommended.

02. CSS Installation

Your project should include a “main/root” css styles file, which is included within the head element of your HTML.

Include vocabulary.css from within style.css via a CSS @layer import at the top of the file.

    
@import 'PATH/TO/vocabulary/css/vocabulary.css' layer(vocabulary);
    

Note: (for in-dev implementations) You can also include the vocabulary-tests.css file to perform basic tests against recommended and required approaches within the HTML markup.

    
@import 'PATH/TO/vocabulary/css/vocabulary.css' layer(vocabulary);
@import 'PATH/TO/vocabulary/css/vocabulary-tests.css' layer(vocabulary-tests);
    
    

Production use of the vocabulary-tests.css file is not recommended generally.

03. JS Installation

Vocabulary has a minimal JavaScript footprint, but does have some required behaviors that rely on JS.

Include the vocabulary.js file at the bottom of your HTML markup, prior to the closing body tag.

Global Header & Footer

Each CC site utilizing Vocabulary should include the global Header & Footer areas at the top and bottom of the site respectively.

Header

The Header begins directly after the opening body tag.

Skip to content


    

        
Creative Commons
        Menu
        

        
    



    


    
    

    
    



      

Footer

The Footer begins directly before the bottom script includes, which appear before the closing body tag.