Behind the system

Contribute.

Anyone on the UX team can change this site. Every change ships through a merge request with an automatic preview link, and main deploys to production on merge. Here's how to get going — the exact commands live in the CONTRIBUTING guide.

Before you start

A one-time setup.

GitLab accessAn account on gitlab.com (via Aceve SSO) and Developer access to the aceve-design-system group. Ask a maintainer to invite you.
For local workNode 20 and git, plus an SSH key on GitLab (or HTTPS + a token with read/write_repository).
For components & tokensAccess to the MiniSprout Figma file, where component values come from.

Two ways to work

Pick by the size of the change — both end in the same MR + preview.

GitLab Web IDE

Text and content edits — no local setup.
  1. Open the file in GitLab → Edit → Open in Web IDE.
  2. Make your change.
  3. Commit to a new branch and tick “Start a merge request”.
  4. Open the preview URL on the MR, check it live.
  5. Ask a maintainer to review and merge.

Local clone + push

New pages, components, anything bigger.
  1. Clone the repo, npm install, npm run dev.
  2. git checkout -b my-change.
  3. Edit, check at localhost:3000, commit.
  4. git push -u origin my-change → open the MR at the URL printed in the terminal.
  5. Same preview → review → merge as above.

Claude Code

Describe what you want — Claude handles git.
  1. Clone the repo and open it in Claude Code (claude command in the project folder).
  2. Describe your change in plain language — Claude reads CLAUDE.md and knows the conventions.
  3. Claude edits files, runs the dev server, and shows you a preview before committing.
  4. When happy: “push this and open an MR” — Claude pushes the branch and gives you the MR link.
  5. Click the link, set auto-merge, done.
Always set a reviewer when opening an MR — @vonkrogh (Mikel) or @maan (Mathias). That's what sends them a notification. Without a reviewer the MR sits silently and nothing ships.

Never commit straight to main — it's protected, and the MR preview is your safety net.

Three worked examples

The shapes you'll hit most often.

Add a page

  1. Copy a simple page as a template (e.g. VoicePage.jsx) into components/pages/.
  2. Add a 3-line route file in app/<route>/page.jsx (copy app/trust/page.jsx).
  3. Add a title + description entry in components/data/page-meta.js.
  4. Add the sidebar item in components/data/nav.js and wire the PageNav chain.
  5. Bump SPROUT_VERSION and add a CHANGELOG entry in sprout-data.js.

Add a component

  1. Add it to COMPONENTS in sprout-data.js — it appears on the coverage board.
  2. Create a component page with the Section and DemoCard primitives (copy ButtonsPage.jsx).
  3. Wire the route, metadata and nav exactly like a new page.
  4. New React primitive? Pair with a maintainer — it also gets a Code Connect mapping for Figma Dev Mode.

Add or change an icon

Icons flow from Figma through the sync pipeline — never edit SVGs by hand. The full step-by-step is on the Iconography page.

  1. Search this page first — 297 icons are already in the set.
  2. Found it in Lineicons? Drop the name in #sprout-design-system — no Figma work needed.
  3. Custom icon: open MiniSprout in Figma, add a component frame (24×24, 2px stroke, round caps, currentColor), name it in kebab-case.
  4. Tag a maintainer. They trigger the sync pipeline in sprout-tokens, which opens an MR with the new SVG.
  5. Sync MR merged → maintainer publishes a patch version → docs vendor updated → live on /icons.

Two repos, one rule

Know which one you're in.

This site

Pages, components and guidelines live in the docs repo. That's everything you reach from the sidebar. See How it works for the full pipeline.

The tokens

Colours, spacing, radii and icons live in the sprout-tokens repo and flow from Figma — never hand-edit vendor/sprout-tokens/ here. The CONTRIBUTING guide covers the token release flow.

House rules

Sentence case, verb + noun on buttons, no exclamation marks — practice what we preach.
Shipped a visible change? Add a CHANGELOG entry and bump SPROUT_VERSION.
The pipeline must be green before merge — verify tells you which file failed.
A maintainer merges; you branch and open the MR.

Questions → #sprout-design-system.

← PreviousRoadmap
Sprout · Aceve Design System · v3.12.1