councildataproject/cdp-design

Design tokens and visual assets used by CDP websites and instances.

cdp-design

Styling and graphic design for Council Data Project websites and instances.

---

Council Data Project

Council Data Project is an open-source project dedicated to providing journalists, activists, researchers, and all members of each community we serve with the tools they need to stay informed and hold their Council Members accountable.

For more information about Council Data Project, please visit our website.

About

cdp-design is used to maintain all the styling and graphic design assets required for the various websites in the CDP ecosystem.

This means that any design changes made here propagate to:

• councildataproject.org: The primary website for the entire organization
• cdp-frontend: A library that is used by all CDP instance websites

Developer Usage

CDP Images

Images are injected as a CSS content attribute.

Logo image classes follow the specification: cdp-logo-{primaryColor}-bg-{backgroundColor}

Icon image classes follow the specification: cdp-icon-{primaryColor}-bg-{backgroundColor}-size-{int}

Example:

import "@councildataproject/cdp-design/dist/images.css";

// assume you have a component
// sets the content of this div to the CDP logo
<div className="cdp-logo-black-bg-transparent">...</div>;
// OR an icon
<div className="cdp-icon-black-bg-transparent-size-64">...</div>;

CDP Colors

Colors are simple color or background-color CSS attributes.

Content colors follow the specification: cdp-{color}

Background colors folow the specification: cdp-bg-{color}

Example:

import "@councildataproject/cdp-design/dist/colors.css";

// assume you have a component
// sets the background color of this div to dark purple
// sets the text color to white
<div className="cdp-bg-dark-purple cdp-white">Hello World!</div>;

Favicon

The most update-to-date favicon will always be found at: src/static/images/favicon.ico

Contributing

Much of this library and design system are auto-generated from a few key assets:

• src/static/css/cdp-text.css: All typography styling.
• src/static/images/icon/black-bg-transparent.png: The CDP icon, used for favicons, headers, etc. with all content of the icon in black and a transparent background.
• src/static/images/icon/white-bg-transparent.png: The CDP icon, used for favicons, headers, etc. with all content of the icon in white and a transparent background.
• src/static/images/logo/black-bg-transparent.png: The full CDP logo, used for branding with all content of the logo in black and a transparent background.
• src/static/images/logo/white-bg-transparent.png: The full CDP logo, used for branding with all content of the logo in white and a transparent background.
• generate-cdp-colors.js: The script to generate the cdp-colors.css file.

For example, if you wanted to propose a change to our logo you would:

1. Fork the cdp-design repository.
2. Clone your "forked" cdp-design repository to your local machine.
3. Replace the black-bg-transparent.png and the white-bg-transparent.png files located in the src/static/images/logo/ directory.
4. Run npm run generate from the command line to generate all the new image variants.
5. Verify that all assets have been created properly in a file browser by viewing the src/static/images/logo directory.
6. Add, commit, and push the new logo files to your fork.
7. Create a pull request from your fork to this repository.

Design Guidelines

General

Council Data Project designs should attempt to fit nicely within the Mozilla Protocol design system.

Logo

Logo proposals can be:

• Any size or dimension

Logo proposals must be:

• Created with black and white color variants
• Stored in PNG format

Icon

Icon proposals must:

• Be created with black and white color variants
• Be at least 256x256 in size
• Have square dimensions (256x256, 512x512, etc.)
• Stored in PNG format

If you are updating the icon, please also ensure that you update the favicon.ico in the src/static/images/ directory.

cdp-design's Issues

Export at least the color tokens so that they can be use in javascript too

Feature Description

Allow cdp-frontend to use the color tokens in javascript

Use Case

Most of the non-Mozilla protocol styling in cdp-frontend use CSS-in-JS (https://github.com/emotion-js/emotion) or inline styling. It would add some versatility to cdp-design if other libraries could use the color tokens in javascript too. For example, I couldn't use the dark blue color in the jump-to-sentence-cue PR because there isn't generated CSS class for border-color. We could add more CSS classes but that seems tedious to me. We would have to create a class for each CSS color property (border-left-color, border-right-color, outline-color, etc)?

Solution

Export the colors tokens to dist/colors.js (It seems the file is already generated, but it's empty).

Alternatives

More CSS classes for other color properties.

cc @JacksonMaxfield

Fix image bundling into the npm assets

The library itself can generate the needed files and the CSS gets bundled properly but the underlying images don't.

I.E. as a user I can't do:

<image class="cdp-icon-black-bg-transparent-size-32">

And have the image properly filled in for me.

To do so we will need to add webpack or some other bundler to the project / package.json scripts.
Here is a good video breaking down compilers and how to set webpack / snowpack up.

Create single webpage application to show the available assets

Currently there is no way to know what assets are contained in this package or how to use them without looking at the scripts / generated files.

Would be wonderful to publish a single page application to GH-Pages that acts as a viewer for assets + their CSS class names.