Staffbase

Guides

Contribution

As we’re in a ramp up phase of our design system we want to clarify how contributions work for now.

I found a bug 🐞

If you’ve found a bug and the fix is small and contained, go ahead and open a PR. These are usually quick to review and merge, and they help us move fast together.

If you’ve found a bug but aren’t sure what the right fix is, or you don’t have capacity to work on it yourself, please open a GitHub issue instead. A rough write-up is totally fine — we’ll pick it up from there.

I want to request a new component or pattern

Please open a GitHub issue to request it. Tracking needs as issues helps us:

  • spot recurring themes
  • identify priorities
  • keep context and decisions in one place over time

Bigger changes like new components or patterns need:

  • alignment with system standards
  • accessibility review
  • design review
  • API and long-term maintenance consideration
  • coordination across teams

Supporting this level of work requires more hands-on involvement than we can realistically offer right now. In many cases, it’s more effective for us to own and build these changes ourselves, with input from you along the way — so an issue is the best place to start the conversation.

I want to make a small improvement

Because we’re currently a small team, we’re happily accepting small, contained PRs — for example:

These are usually quick to review and merge.

I want to add an icon

  1. Obtain the icon file in SVG format from your designer.

  2. Place the SVG in the icons_raw directory. Use kebab-case for SVG filenames.

    If the icon represents a toggleable or secondary state (e.g. locked/unlocked, filled/unfilled), add both versions. Use -alt in the filename to indicate the alternate or toggled version — e.g. bookmark.svg and bookmark-alt.svg.

  3. Run pnpm generate:icons to process the raw SVG and generate the Icon component.

    index.tsx and iconList.tsx in src/icons will also be updated.

  4. Start Astro locally to preview the new icon.

    Confirm that the icon appears and looks as expected. If needed, you can fine-tune the generated icon component directly in src/icons.

  5. Add search keywords for the icon (recommended).

    The icon gallery search is powered by apps/astro/src/components/icons/iconTags.ts. Add an entry for your icon with related terms so people can find it by synonym — e.g. bin: ['delete', 'trash', 'remove']. Without it the icon still appears in the gallery, but is only findable by its exact name.

  6. Run pnpm changeset to add a changeset — a new icon is a new public export and is user-visible, so it requires one.

I want to change tokens

Token layers

Token sources live in four JSON files under packages/design/tokens/:

  • primitive.json — raw values (colors, font sizes, radii, shadows). These are the lowest-level building blocks. You’ll rarely edit these unless adding a new color scale or adjusting a base value.
  • semantic.json — reference primitive tokens. Contextual aliases that adapt to theming.
  • component.json — per-component overrides for when semantic tokens aren’t specific enough (e.g. badge.text.color.critical). Only add here if a component needs a value that doesn’t map cleanly to an existing semantic token.
  • typography-presets.json — composite typography tokens that bundle fontSize, lineHeight, and fontWeight into named presets (e.g. body.lg, title.md, label.sm).

All JSON files use the DTCG (Design Tokens Community Group) format:

primitive.json 
"blue": {
  "500": {
    "$value": "oklch(0.6388 0.1952 257.61)"
  }
}
semantic.json 
"text": {
   "color": {
      "primary": {
         "$value": "{color.blue.500}"
      }
   }
}

How it works

Running pnpm --filter @staffbase/design generate:tokens executes two scripts in sequence:

  1. tokens/sd.config.ts — runs Style Dictionary to convert the JSON tokens into CSS variables (one CSS file per layer).
  2. scripts/generateTheme.ts — generates a Tailwind v4 theme file (@theme inline) that bridges --sb-* custom properties to Tailwind utility namespaces. It also maps typography presets into Tailwind’s --text-* namespace.

This produces the following generated files (do not edit these directly):

  • src/foundation/tokens/primitive.css
  • src/foundation/tokens/semantic.css
  • src/foundation/tokens/component.css
  • src/foundation/theme.css

Workflow

  1. Edit the appropriate JSON source file in packages/design/tokens/.

  2. Run pnpm --filter @staffbase/design generate:tokens to regenerate the CSS output.

  3. Start the docs pnpm dev:astro locally to verify affected components still look correct.

  4. Run pnpm changeset to add a changeset — token changes are always user-visible and require one.