Modular Brand Library with Tokens and Version Control

I stopped chasing logos on Slack once the brand lived in a repo.

Context

Our brand was a mess. Between the marketing and product teams, we had at least 12 different logo versions floating around in random Google Drive folders. Presentation slides were being shipped with outdated color palettes, growth teams were exporting unoptimized SVGs that were slowing down our site, and our designers were spending a significant portion of their time policing the brand instead of creating new things.

The root of the problem was a lack of a single source of truth. There was no centralized place for brand assets, no clear guidelines on how to use them, and no process for updating them. It was a classic case of brand chaos, and it was costing us time, money, and brand consistency.

To solve this, I decided to treat our brand as code. I rebuilt our entire brand system from the ground up, using a combination of design tokens, a version-controlled repository, a living style guide, and a clear set of processes and Service Level Agreements (SLAs). This new system has brought order to our brand chaos and has allowed us to scale our brand with confidence.

Stack I leaned on

• Figma libraries + variables feeding Style Dictionary: Figma is our single source of truth for design. We use Figma libraries and variables to define our design tokens (colors, typography, spacing, etc.). Style Dictionary then takes these tokens and transforms them into various formats (CSS, JS, etc.) that can be used by our developers.
• GitHub repo storing tokens (tokens/), assets (assets/), and release notes: All of our brand assets, from tokens to logos to icons, are stored in a single GitHub repository. This gives us version control, a clear history of changes, and the ability to manage our brand assets like any other codebase.
• Storybook site (with Chromatic) acting as living documentation: Storybook is our living style guide. It provides a searchable, browsable, and interactive documentation for our brand assets and components. We use Chromatic to run visual regression tests on every commit, ensuring that our brand stays consistent.
• Cloudinary for CDN + dynamic delivery (format, size, crop): All of our visual assets are served through Cloudinary. This gives us a fast, reliable CDN and the ability to dynamically transform images and videos on the fly. We can resize, crop, and even change the format of an asset simply by changing the URL.
• Notion portal for non-technical stakeholders with embedded previews: To make our brand assets accessible to non-technical stakeholders, we created a portal in Notion. This portal provides a user-friendly interface for browsing and downloading assets, and it includes embedded previews from Storybook and Cloudinary.

Playbook

1. Inventory & audit existing assets; map duplicates, owner, usage.
2. Define taxonomy: naming conventions (brand.logo.primary, color.brand.moss.500).
3. Tokenize color, type, spacing, motion; convert to JSON via Figma Tokens plugin.
4. Sync to code using Style Dictionary → publish @marsala/brand-tokens package weekly.
5. Automate exports: GitHub Action pulls latest Figma components, optimizes via SVGO/Sharp, uploads to Cloudinary with version tags.
6. Document in Storybook: each component example links to tokens, usage guidelines, and download buttons.
7. Release process: every two weeks, cut a release (version semver), publish changelog, notify #brand-library.
8. Request workflow: Typeform → Linear automation; SLA 3 days for minor variants, 2 weeks for new families.

The Benefits of a Token-Based System

• A single source of truth: Design tokens provide a single, centralized source of truth for all of our brand assets. This eliminates confusion and ensures that everyone is using the most up-to-date assets.
• Improved consistency: By using tokens, we can ensure that our brand is applied consistently across all of our products and marketing materials.
• Increased efficiency: A token-based system makes it much faster and easier to update our brand. We can make a change in one place and have it automatically propagate to all of our assets.
• Better collaboration: A token-based system improves collaboration between designers and developers. Designers can work in Figma, and developers can consume the tokens in their code, without having to worry about manual handoffs.
• Scalability: A token-based system is highly scalable. We can easily add new brands, themes, and platforms without having to start from scratch.

Architecture at a Glance

1. Designers update Figma components & variables.
2. Exporter script pulls tokens + components via API.
3. GitHub stores tokens/assets + runs CI for validation, optimization, release.
4. Delivery via npm package (tokens) + Cloudinary CDN (assets).
5. Docs served via Storybook + Notion with embedded previews.

Release Pipeline

• Merge to main triggers GitHub Action:
  • Validate token schema/naming.
  • Export optimized assets (SVG/PNG/WebP) with metadata.
  • Upload to Cloudinary with semantic version tags.
  • Publish npm package + post changelog to Slack/Notion.
• Run Chromatic visual tests; deploy Storybook on success.
• Releases happen every two weeks; hotfixes use same pipeline but bump patch version.

name: brand-release
on:
  push:
    branches: [main]
jobs:
  tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run tokens:build && npm run assets:export
      - run: npm publish --access public

Request Workflow

• Typeform captures request (use case, deadline, formats).
• n8n creates Linear task, applies SLA (3 days minor, 2 weeks new family).
• Requester tracks status via Notion portal; approvals + delivery links live there.

SLA Table

| Request Type | Examples | SLA | |--------------|----------|-----| | Minor tweak | Color swap, copy edit | 3 business days | | New variant | Co-brand lockup, localized typography | 10 business days | | Net-new family | Rebrand, campaign identity | Custom plan reviewed in council |

SLAs are visible to stakeholders so priorities stay aligned.

Partner Access

• Agencies get Cloudinary keys scoped to read-only directories with auto-expiring tokens.
• Portal logs downloads so we can audit who used which logo variant.
• Self-serve “kit generator” lets partners download combinations (e.g., horizontal + dark background) without pinging design.

Dashboards & Observability

• Supabase + Metabase track request volume, SLA compliance, asset downloads, and brand debt backlog.
• Grafana board monitors npm token package installs (so we know which repos need updates).
• Slack alerts fire when someone uploads assets outside the pipeline (e.g., manual Cloudinary upload) so we catch rogue files.

Security & Compliance

• All source files live in GitHub with required reviewers; no more random Dropbox links.
• Cloudinary tokens rotate quarterly; revoked automatically when agencies churn.
• Access logs exported monthly for audits—helpful when legal asks “who downloaded logo v1.4?”

Implementation Timeline

• Week 1: inventory assets, define taxonomy, stand up Git repo.
• Week 2: connect Figma Tokens → Style Dictionary → npm package.
• Week 3: automate exports + Cloudinary uploads, add Storybook/Chromatic.
• Week 4: launch Notion portal, train marketing/partners, set SLAs.

Governance Model

• Publishers (Design Ops) approve merges/releases.
• Contributors (designers/devs) submit PRs.
• Consumers (marketing, growth, partners) consume via Notion + CDN.
• Access roles stored in Supabase; Cloudinary tokens scoped to read-only for partners.
• Monthly “brand council” reviews roadmap, retires outdated assets, and audits open requests. Minutes live alongside release notes so leadership always sees what changed.

SLA & Metrics

• Reduced urgent requests: Urgent asset requests have been reduced by 70%.
• Faster multi-brand updates: The time it takes to update our brand across multiple brands has been reduced from 6 hours to 45 minutes.
• Eliminated logo misuse: Incidents of logo misuse have been almost completely eliminated.
• Full token adoption: 100% of our squads have adopted the new token-based system.
• Consistent release cadence: We now have a consistent release cadence of every 14 days, which is tracked in Notion and GitHub.
• High SLA compliance: We have a 96% SLA compliance rate for asset requests.
• High partner satisfaction: Our partners have a 9.2/10 satisfaction rate with the new system, according to our quarterly survey.

Case Study: Multi-Brand Refresh

When we launched a partner program, we had to ship co-branded kits in four languages:

1. Extended tokens with partner color slots (color.partner.acme).
2. Automated export pipeline produced lockups + localized tagline graphics within 2 hours.
3. Storybook showcased combinations and accessibility contrast results.
4. Partners downloaded kits via Notion; audit logs captured who grabbed what.

Time to deliver multi-brand updates dropped from days to under an hour.

Training & Adoption

• Designers take a “token chef” workshop where they learn naming, merging, and rollback.
• Engineers get a Storybook tour showing how tokens map to Tailwind/SCSS utilities.
• Marketing + partners attend a quarterly office hour to learn portal updates and best practices.
• Everyone signs off on the “brand release checklist” before big campaigns.

Cost of the Old Way

Before this system we spent ~20 hours/week hunting files and fixing incorrect logos. A single misprinted brochure cost $3k. Investing in automation + governance paid for itself within a month.

Cost Snapshot

• Figma Organization plan already budgeted.
• Cloudinary: $50/mo for CDN + transformations.
• Chromatic: $60/mo.
• Net incremental spend <$120/mo, saving dozens of designer hours. That’s cheaper than a single rushed reprint, so finance became our biggest advocate.

Lessons Learned

• Governance matters: define who can publish and rollback.
• Embedded previews in Notion built trust quickly.
• Treat tokens like APIs: version, deprecate, communicate.
• Train everyone—engineers, marketers, agencies—on the same workflows.
• Automation > policing: scripts catch missing alt text, wrong formats, etc.

What I'm building next

I'm opening a best-practices guide for teams without dedicated design ops. Want to collaborate? let me know.

Next up: add QA bots that compare live site screenshots vs. Storybook to catch rogue hex codes before they hit production. Also experimenting with a partner API so agencies can request pre-approved assets programmatically instead of digging through portals. The better the tooling, the fewer “can you send me the logo?” Slack pings we ever receive.

FAQ

• Can non-technical teams use this? Yes—Notion portal + Cloudinary links hide Git complexity.
• What if a partner needs a bespoke version? They submit via request form; we only ship variants that live in the repo so governance stays intact.

Want me to help you replicate this module? Drop me a note and we’ll build it together.