Everything you need to build consistent, accessible interfaces with the Sinter design system.
The design system is built on Base UI — unstyled, accessible component primitives from the MUI team. On top of these primitives, we use a three-tier token architecture: raw tokens (colors, spacing) feed into semantic tokens (--color-primary, --spacing-4) which drive component tokens. Changing a single semantic token updates every component that references it.
All tokens are enforced by ESLint rules — you'll get warnings if you use hardcoded colors or spacing values instead of design tokens.
The component library includes 30+ components. They live in packages/ui/src/components/ui/ and are imported via @ui/components.
import { Button, Card, Dialog, Tabs } from '@ui/components';All components use Base UI as the underlying primitive layer for accessibility, keyboard navigation, and focus management. shadcn/ui serves as a component recipe catalog — when you need a component that doesn't exist yet, you can scaffold it from shadcn's library and it will be adapted to use Base UI primitives and our design tokens.
The easiest way to add a component is to ask Claude — it will check what's available, suggest the best option, and handle the setup. If you prefer to do it manually, here's the priority order:
npx shadcn add <name>)We use Phosphor Icons — a flexible library with 9,000+ icons in 6 weights (thin, light, regular, bold, fill, duotone). We've curated a set of commonly used icons, but you can import any icon from the library.
import { Envelope, ArrowRight } from '@phosphor-icons/react';Use semantic icon size tokens instead of hardcoded pixel values. The default size for most UI elements is size-icon-md (16px).
| Token | Size | Tailwind | Use case |
|---|---|---|---|
--icon-xs | 10px | size-icon-xs | Small badges |
--icon-sm | 12px | size-icon-sm | Badges, compact UI |
--icon-md | 16px | size-icon-md | Default — buttons, inputs, nav |
--icon-lg | 20px | size-icon-lg | Large buttons, hero sections |
--icon-xl | 24px | size-icon-xl | Marketing, headings |
Use flexbox gap for spacing between icons and text — never margins. The Button component already includes inline-flex items-center gap-2, so you only need to set the icon size.
// Icon in a button — gap is built in
<Button>
<Envelope className="size-icon-md" aria-hidden="true" />
Send Email
</Button>
// Icon in inline text
<span className="inline-flex items-center gap-2 text-sm">
<CheckCircle className="size-icon-sm text-success" aria-hidden="true" />
Verified
</span>The default weight is regular. Use fill for active/selected states and navigation icons that need more visual weight. Use bold sparingly for emphasis.
<House weight="regular" /> {/* Default — most contexts */}
<House weight="fill" /> {/* Active nav item, selected state */}
<House weight="bold" /> {/* Emphasis — use sparingly */}Icons next to text are decorative — add aria-hidden="true". Icon-only buttons must have an aria-label.
// Decorative icon (has text label)
<Envelope className="size-icon-md" aria-hidden="true" />
// Icon-only button (needs aria-label)
<Button size="icon" aria-label="Close dialog">
<X className="size-icon-md" />
</Button>Any of the 9,000+ Phosphor icons can be imported directly — no configuration needed. You can ask Claude to add a specific icon (e.g. "add a shopping cart icon to the checkout button") and it will handle the import automatically. Or browse the full library at phosphoricons.com and import by name.
import { CreditCard, ShoppingCart } from '@phosphor-icons/react';When Base UI components don't cover your needs, we have approved external libraries for specialized use cases. Each is pre-configured to use our design tokens. You can ask Claude to set up any of these — it knows the installation steps and how to integrate them with the design system.
| Need | Library | Use for |
|---|---|---|
| Charts & data viz | Tremor | Line, bar, area, donut charts, KPI cards |
| Advanced tables | TanStack Table | Sorting, filtering, pagination, 10k+ rows |
| Drag & drop | dnd-kit | Kanban boards, sortable lists, reorderable grids |
| Custom interactions | React Aria | Complex accessible components from scratch |
All approved libraries are headless or Tailwind-native, MIT/Apache-2.0 licensed, and RSC compatible. See the Resources page for live examples of each library's components.
The design system targets WCAG 2.1 AA compliance. Base UI components handle most accessibility concerns (focus management, keyboard navigation, ARIA attributes), but there are a few things to keep in mind:
aria-hidden="true" when there's a text labelaria-label describing the actionSinter includes a production-ready internationalization setup using next-intl. All routing is locale-aware — URLs always include a locale prefix (e.g. /en/home), and the system handles detection, redirects, and validation automatically.
User-facing text is stored in translation files rather than hardcoded in components. When Claude builds a page or component, it automatically uses translation keys from these files. Currently Sinter ships with English, but the architecture is ready for additional languages.
// Translation keys live in packages/i18n/messages/en.json
{
"Common": {
"actions": { "save": "Save", "cancel": "Cancel" },
"errors": { "generic": "Something went wrong. Try again." }
}
}Claude also handles locale-aware navigation automatically — all internal links include the correct language prefix (e.g. /en/settings).
Ask Claude to add a language — e.g. "Add Swedish as a second language to the app" — and it will create the translation file, update the config, and set up routing. Everything needed for the new locale to work end to end.
Under the hood, this creates a new translation file (e.g. sv.json) in packages/i18n/messages/ and registers the locale in packages/i18n/config.ts. Routing, middleware, and static generation update automatically.
The full design system documentation lives in the docs/ directory of the codebase. Key references:
docs/design/patterns/ — detailed patterns for buttons, typography, icons, forms, accessibility, and moredocs/design/tokens.md — complete token architecture and referencedocs/design/ux-writing.md — comprehensive UX writing guidelinesdocs/guides/component-workflow.md — full component selection decision tree