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.

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.

Header - Global Area

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.

• Masthead
  • Entity Logo
  • Primary Nav Menu
  • Ancillary Nav Menu
• Explore Panel (Explore CC)
  • Optional main Index Site identity/link / blurb (used for non Index Project sites)
  • Explore Nav Menu

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

Expected Contexts

• The Header begins directly after the opening body tag, and appears only once per page, on all page levels

Skip to content


    

      
Vocabulary
        Menu
        

        
    



    


    
    

    
    



      

Footer - Global Area

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.

• main Index Project Site identity/link
• Footer Nav Menu
• Contact Information
• Social Nav Menu
• Newsletter Subscription Form
• Donation Call-to-action button
• License Information

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

Expected Contexts

• The Footer begins directly before the bottom script includes, which appear before the closing body tag, and appears only once per page, on all page levels

Attribution List - Block

Expected Contexts

• body.home-index > main > article.authored-posts > footer > article.attribution-list; on the home-index page-level
• body.blog-index > main > article.attribution-list; after referenced media; on the blog-index page-level

  

    
Images Attribution
    view

    

      

        

          

            
            attribution here
          
        
      

      ...

   
  

Attention - Block

Expected Contexts

• body.* > article.attention; after body > header; before body > main; all page-levels
• body.archive-page > aside > article.attention; as last child item, only default-page, archive-page levels

  

  
   content here

  

Person Snippet - Singular - Block

Expected Contexts

• article.persons > ul > li > article.person

  

    
Name Here
    Position/Title here
    

      
    
    
Truncated bio here…
  

Persons Snippets - Plural - Block

Expected Contexts

• body.team-index main, directly after main > header

  

    
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

• main > article.post
• main > article.posts > article.post
• article.posts ul > li > article.post

  

    

    
Title Here

    by Author Name, Author Name
    Open Culture

    
    

      
      attribution here
    
    
truncated teaser excerpt 
  

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

• main > article.posts, directly after the main > header
• body.blog-index > main > article.posts.featured, directly after the main > header
• body.blog-index > main > article.posts, directly after the main > article.posts.featured
• body.archive-page > main > article.posts, directly after the main > aside
• body.person-page > main > article.posts, directly after the main > header
• body.blog-post > main > article.posts.related, as the last child of body > main

  


  
Title Here
  
    

      

      
Title Here

      by Author Name, Author Name
      Open Culture

      
      

        
        attribution here
      
      
truncated teaser excerpt 
     

     

   

Pagination - Nav

Expected Contexts

• body.archive-page > main > nav.pagination, as the last child of body > main
• body.person-page > main > nav.pagination, as the last child of body > main
• body.search-index > main > nav.pagination, as the last child of body > main

Opening Summary - Block

Expected Contexts

• body.blog-post > main > aside.opening; optionally after main > header

Closing Summary - Block

Expected Contexts

• body.blog-post > main > aside.closing; optionally before main > span.pub-date

Tags listing - Block

Expected Contexts

• body.blog-post > main > article.tags; optionally after main > span.pubdate

  

    
Tags
    

      
open culture
      ...

    
  

Sidebar - Region

Expected Contexts

• body > aside; optionally after main > header
• body.archive-page > aside, after main > header

Filter Menu - Nav

Expected Contexts

• body.archive-page > aside > nav.filter-menu

General Menu - Nav

Expected Contexts

• body.archive-page > aside > nav

Data Points - Singular - Block

Expected Contexts

• article.case-studies > ul > li > article.data-point

  

    
Title
    
55+ million articles
    
Descriptive text here
  
 

Data Points - Plural - Supporting Block

Expected Contexts

• article.case-studies > footer > article.data-points

  

    

      

        

          
Title
          
55+ million articles
          
Descriptive text here
        
       

       ...

     
   

Case Studies - Block

Expected Contexts

• body.home-index > main > article.case-studies

  

    
Title here
    
Descriptive text
    

      

        

          
          attribution here
         
       

        ...

    

    
  

Search Form - Block

Expected Contexts

• body.search-index > main > header; directly after the main > header > h1

  

    


      

      Search
    
  

Topic Summary - Block

Expected Contexts

• body.home-index > main > article.topic-summary

  

    
Title
    

      iframe or img here
      attribution here.
    
    

        
Descriptive text here
        Learn more
    
  

Page Header - Region

Expected Contexts

• body > main > header
• body.archive-page > main > header
• body.blog-index > main > header
• body.blog-post > main > header
• body.search-index > main > header
• body.team-index > main > header

  

    
Title Here
    by Name Here, Name Here

    
lead in paragraph
 

      
      Open Culture
    
  
  

Person Header - Region

Expected Contexts

• body.person-page > main > header

  


    
Name
    position/title here
    pronouns optionally here

    

      
      attribution here
     
     

       
Bio here