note: At present Vocabulary is still 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. Caution should be exercised in the meantime.
Introduction
Vocabulary builds from a refactor and reimplementation of the original, now archived, Vocabulary Legacy project.
Both projects were informed by the CC Style Guide (2019), and incorporate or adapt its guidance into a digital context.
As of 2026, Vocabulary was refactored to include the newly selected Brand Guidelines, which overrides much of the 2019 Style Guide, the new Style Guide is not currently publicly available.
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:
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
This enables two modes of build work.
A: upstream → downstream
new functionality introduced into Vocabulary
documented and generalized
available to prototypes and implementations
B: downstream → upstream → downstream
new functionality introduced local to project prototype
documented and implemented here locally
migrated to vocabulary
documented and generalized
removed in downstream project's prototype localization
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.
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.
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 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
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
This license enables reusers to distribute, remix, adapt, and build upon the material in any medium or format, so long as attribution is given to the creator. The license allows for commercial use. CC BY includes the following elements:
note: The .topic-summary block also has several pseudo-semantic addon classes that can be added for various treatments which includes:
.focus-area
.highlight
.intro
.about
.supporters
.newsletter
These addon classes are meant to subtly describe a more specific intent for for the block, and can also be used to provide alternative visual treatments to match that altered meaning through expressed visual design.
attribution here
