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.

Engineers

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:

CSS Custom Properties (Recommended for most 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 backgroundColor = 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 default 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.

Designers

If you're a designer

Get access to Figma UI kits

Use these files as the source of truth for components and tokens:

• React Native – Design System (components and tokens)
• Shoptet Core aka Admin – Design System (components and tokens)
• Shoptet Icons

Suggested setup in Figma:

• Enable the libraries in your working file (Assets panel).
• Insert components from the library instead of copying one-off layers.

How to work with the design system (minimal rules)

• Prefer existing components and tokens from the libraries.
• Avoid custom colors, spacing, and typography values unless you are exploring early concepts.
• If you must go custom, document why and treat it as a candidate for the system.

Support and consultation

If you are unsure how to use a component, need a recommendation, or you are designing something that is not covered by current guidance, ask in the design system team Slack channel.

Typical topics to bring there:

• Which component or variant to use for a specific use case
• Missing state, missing variant, or unclear behavior
• Icon requests or icon usage questions
• Consistency review before handoff

When asking for help, include:

• Link to the Figma frame
• Short context (what user problem you are solving)
• Screenshot or recording if interaction matters
• What you tried and why it did not work

Requesting changes and contributing

When requesting a change, include:

• The use case and where it appears (link to design)
• Why existing components or tokens do not work
• Proposed direction (even rough is fine)
• Expected impact (who benefits and how often)

What to do when the system does not fit

• Do the best workable design using existing tokens and components where possible.
• Avoid creating a “new component” in your product file unless you have already raised it with the Design System team.
• Share the gap early in Slack so it can be evaluated and, if appropriate, standardized.

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

If you think something should be added or changed in the design system, follow the contribution guidelines.

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.