Skip to main content

Getting started

Welcome to Shoptet’s design system​

This guide shows how to start using Shoptet’s design system—whether you design in Figma or build in code. Our system is most useful when it’s used, questioned, and improved through real feedback and iteration.

Our goal is simple: enable teams to ship reliable, coherent products with care. A healthy design system grows through real-world use and continuous iteration, so every suggestion and bug report matters. This site is organized into clear areas - foundations, components, and contribution - so you can learn, build, and help the system evolve.

If you’re a frontend engineer​

Use your package manager of choice:

npm i @shoptet/ui
pnpm add @shoptet/ui
yarn add @shoptet/ui

Import css file to your project:

import "@shoptet/ui/dist/index.css";

Then, import the components you need:

import { Button, TextInput, RadioField } from "@shoptet/ui";

Working with Design Tokens​

Design tokens are available in two formats to suit different use cases:

When you import the CSS file, all tokens become available as CSS custom properties:

.my-component {
  background-color: var(--colors-surface-primary);
  color: var(--colors-foregrounds-content-primary);
  font-size: var(--typography-bodyCopy-l-fontSize);
  border-radius: var(--borderRadius-borderRadius8);
}

JavaScript Object Format​

For programmatic access or when you need to manipulate token values in JavaScript, use the tokens object:

import { tokens } from "@shoptet/tokens";

// Access color values
const primaryColor = tokens.colors.interactive.primary.enabled; // "#14b1ef"
const surfaceColor = tokens.colors.surface.primary; // "#eff0f1"

// Access typography tokens
const headlineFont = tokens.typography.headlines.headline1.fontSize; // "36px"
const bodyLineHeight = tokens.typography.bodyCopy.l.lineHeight; // 1.5714286

// Access spacing and other tokens
const mediumSpacing = tokens.spacing.md; // "12px"
const defaultBorderRadius = tokens.borderRadius.borderRadius8; // "8px"

// Use in styled components or dynamic styles
const buttonStyle = {
  backgroundColor: tokens.colors.interactive.primary.enabled,
  color: tokens.colors.interactive.content.primary,
  padding: `${tokens.spacing.sm} ${tokens.spacing.md}`,
  borderRadius: tokens.borderRadius.borderRadius4,
};

When to use each format:

  • CSS Custom Properties: For static styles, theming support, and better performance
  • JavaScript Object: For dynamic styles, calculations, or when you need programmatic access to token values

Quality bars & contribution​

  • Accessibility: Follow our accessibility guidance (focus states, contrast, labels, keyboard flows).
  • Performance: Prefer provided components and tokens over ad-hoc CSS; fewer one-offs = smaller CSS and more consistency.
  • Feedback loop: When you hit limitations, document the use case and propose an addition or variant.

I'm already using Shoptet's design system but I have a question​

We'll help you with guidance on the usage of our design system. There is a community around using it and the design system team can help you with any questions.

Feel free to reach out:

  • Contact the design system team for component usage questions
  • Ask product designers for design guidance and best practices
  • Discuss with engineers for implementation details and technical questions

I'm already using the design system and it's not enough for my use case​

Shoptet's design system is based on real use cases from our products, but it is always evolving to accommodate more. When designing for a new or existing feature, you might need a change in the design system:

  • A new feature might need an icon that doesn't exist in our current set
  • A component might need a specific combination of state and variant that doesn't exist yet
  • You might find a bug in a component or documentation

What to do:

  1. Document your use case - Clearly describe what you're trying to achieve and why existing components don't meet your needs
  2. Propose a solution - Suggest how the design system could be extended or modified
  3. Reach out to the team - We're ready to discuss proposals for updating the design system, whether you're an engineer or a product designer
  4. Consider contributing - You are cordially invited to contribute to the design system directly when possible

We are happy to receive bug reports and will make sure these get fixed as soon as possible. If we can't fix a bug or add a new feature fast enough, we'll work with you to find interim solutions.