Vocabulary

A cohesive system of design for Creative Commons.

note: This documentation is still in draft mode.

note: At present Vocabulary is unversioned, and hyper localized to the Index Project (CreativeCommons.org). This means that apart from the global Header and Footer areas; components, elements, pieces, tokens, etc. are not adequately generalized enough to be as composable within other site/project contexts. The work to correct this is underway, caution should be exercised in the meantime.

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:

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

This enables two modes of build work.

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.

Components

Components are discrete collected elements in a semantic order that provide a coherent meaning, and can be placed in various contexts which expect them. Various presentations and/or behaviors can then be applied to them depending on the needs, rules, and use cases of various contexts.

Note: the code in this component section are meant to be examples, and not necessarily 1:1 reference to be used exactly.

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

The Global Header component contains several sub-elements.

These sub-elements are not independent and are not meant to be used outside of the Global Header component.

Expected Contexts

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

The Global Footer component contains several sub-elements.

These sub-elements are not independent and are not meant to be used outside of the Global Footer component.

Expected Contexts

Attribution List - Block

Expected Contexts



  

    
Images Attribution

    

    
    
      
  • 
        
    
          
    
            
            attribution here
          
    
        
    
      
    • 

      ...

Attention - Block

Expected Contexts



  

  
   content here

Person Snippet - Singular - Block

Expected Contexts



  

    
Name Here

    Position/Title here
    

      
    

    
Truncated bio here…

Persons Snippets - Plural - Block

Expected Contexts



  

    
Persons

    
    
      
  • 
        
    
          
    Name Here
    
          Position/Title here
          
    
            
          
    
          
    Truncated bio here…
    
         
    
      
    • 

      ...

Post - Singular - Block

Post components nested within a Posts component can be direct children or nested within an html list element (ol/ul)

Expected Contexts

Posts - Plural - Block

Posts components support a pseudo-semantic variant class of featured or related. This helps further describe what they are more specifically, but allows a semantic-ish target for their change in behavior or provided sub-elements.

Expected Contexts

Pagination - Nav

Expected Contexts

Opening Summary - Block

Expected Contexts

Closing Summary - Block

Expected Contexts

Tags listing - Block

Expected Contexts

Expected Contexts

Filter Menu - Nav

Expected Contexts

General Menu - Nav

Expected Contexts

Data Points - Singular - Block

Expected Contexts




  

    
Title

    
55+ million articles

    
Descriptive text here

Data Points - Plural - Supporting Block

Expected Contexts




  

    
    
      
  • 
        
    
          
    Title
    
          
    55+ million articles
    
          
    Descriptive text here
    
        
    
       
    • 

       ...

Case Studies - Block

Expected Contexts



  

    
Title here

    
Descriptive text

    
    
      
  • 
        
    
          
          attribution here
         
    
       
    • 

        ...

    


    

      

        
    
          
  • 
            
    
              
    Title
    
              
    55+ million articles
    
              
    Descriptive text here
    
            
    
           
    • 

           ...

Search Form - Block

Expected Contexts

Topic Summary - Block

Expected Contexts



  

    
Title

    

      iframe or img here
      attribution here.
    

    

        
Descriptive text here

        Learn more

Page Header - Region

Expected Contexts



  

    
Title Here

    by Name Here, Name Here

    
lead in paragraph
 

      
      Open Culture

Person Header - Region

Expected Contexts



  


    
Name

    position/title here
    pronouns optionally here

    

      
      attribution here
     

     

       
Bio here