Get started

This guide is for projects outside the Hub monorepo that want to use the design system. If you are working inside the Hub repo, use the in-repo skill and AGENTS.md instead; the packages are already wired through workspace paths.

1. Authenticate and install

The DS packages live on a private registry (npm.apkg.io/vipepc1, the Bitbucket-hosted npm), so you need read access. There is no token-free option for a private registry.

Get a token (once)

Create an Atlassian API token with the read:package:bitbucket scope at id.atlassian.com → API tokens ("Create API token with scopes"). Copy it immediately. (App passwords are deprecated; use an API token.)

Configure npm

The registry uses npm's _auth, which is base64("email:token"). Pick one approach:

Option A , env var (recommended for teams + CI). Commit this .npmrc to your repo (no secret in it):

@hub:registry=https://npm.apkg.io/vipepc1/
//npm.apkg.io/vipepc1/:_auth=${HUB_NPM_AUTH}

Then each developer and CI sets HUB_NPM_AUTH once:

export HUB_NPM_AUTH=$(printf '%s:%s' 'you@epcvip.com' 'PASTE_ATLASSIAN_TOKEN' | base64 | tr -d '\n')

Option B , per machine. Put only the scope in your repo .npmrc:

@hub:registry=https://npm.apkg.io/vipepc1/

and store auth once in your user ~/.npmrc:

npm config set //npm.apkg.io/vipepc1/:_auth "$(printf '%s:%s' 'you@epcvip.com' 'PASTE_ATLASSIAN_TOKEN' | base64 | tr -d '\n')"

Verify either way: npm whoami --registry=https://npm.apkg.io/vipepc1/ should print your email.

Install

npm i @hub/ds-components @hub/ds-tokens @hub/ds-icons
# peer deps, if your app does not already have them:
npm i @mui/material @emotion/react @emotion/styled

@hub/ds-components needs React 18+, MUI 5+, and Emotion 11+ as peers. There is no single @hub/design-system package; install the scoped ones you use.

2. Load the font

The type scale uses Montserrat. Self-host it so the components render correctly (without it, text falls back to the browser default):

npm i @fontsource/montserrat

import '@fontsource/montserrat/400.css';
import '@fontsource/montserrat/500.css';
import '@fontsource/montserrat/600.css';
import '@fontsource/montserrat/700.css';

3. Use a component

import { Button, TextField } from '@hub/ds-components';

export function SignIn() {
  return (
    <form>
      <TextField label="Email" type="email" />
      <Button variant="primary" type="submit">Sign in</Button>
    </form>
  );
}

The form components (TextField, Select, Checkbox) are built over MUI. If your app already has a MUI theme, render them inside it; otherwise they work with sensible defaults.

4. Use tokens

Import token values directly, or use the generated CSS custom properties:

import { ColorTextPrimary, Spacing4 } from '@hub/ds-tokens';

Browse the full set on the Tokens page.

5. Connect the MCP (optional, for AI-assisted work)

An MCP server exposes the live design system to AI editors so they pick the right component, look up props and tokens, and validate your code. Point your editor at the production endpoint:

https://hub.epcvip.com/resolver/api/ds/mcp

Claude Code:

claude mcp add --transport http epcvip-mcp-hub-ds https://hub.epcvip.com/resolver/api/ds/mcp

Cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "epcvip-mcp-hub-ds": { "url": "https://hub.epcvip.com/resolver/api/ds/mcp" }
  }
}

Tools available: list_components, get_component, get_token, suggest_component, validate_usage, check_accessibility.

Next