Skip to main content

Usage Guide

This article describes how to use the Plaud Design System in both design and development.

Background​

This design system is the team's unified standard. It provides consistent, reusable design assets and guidelines to help designers and developers streamline the journey from product design to implementation, ensuring visual consistency across products and interactions.

Goals & Audience​

This design system is intended for designers, frontend developers, and product managers. It aims to meet the flexibility needs of each role while enabling efficient collaboration between AI designers and developers of varying backgrounds.

Version Naming Convention​

  • Across packages/design, packages/design-site, and packages/design-tokens, the design system version is consistently referred to as 4.0
  • When adding or updating titles, descriptions, comments, or documentation link names, use Plaud Web 4.0 Design System or Web Design System v4.0 by default
  • Previous version numbers are only allowed when describing historical information, and must be explicitly labeled as “legacy version”

Design System Structure​

  • Token layer: Color variables, typography, spacing, and border radius — ensuring the visual style matches the design spec exactly
  • Component layer: High-quality components built on Shadcn/ui + Radix UI, covering buttons, forms, dialogs, navigation, and more
  • Theme layer: Light / Dark dual themes, driven by CSS variables

Implementation Layer Convention​

@plaud/design uses a two-layer implementation:

  • src/components/ui/*
    • Retains semantic structure, DOM skeleton, and low-level interaction behavior
    • Does not carry final design system visuals directly
  • src/components/*
    • Aligned to Plaud Web 4.0 Design System
    • Responsible for size, color, border radius, border, shadow, and state visuals

When the design layer wraps a ui component, it uses unstyledVisual to disable the ui default visuals and retain only the structural skeleton. This avoids conflicts between default styles and design tokens while keeping the base box model stable.

How to Use the Design System​

  1. Designers open the design tool in Figma and directly reference components and style assets from the component library
  2. Developers use components from the @plaud/design package directly, passing props that correspond to the annotations in Figma
  3. Product managers can reference components and features when designing UI, ensuring the design structure is consistent and aligned with development

1. Using Colors​

Colors in the design system are managed through Design Tokens:

  • In Figma, all text and colors are referenced via variables; the corresponding color variables are available after opening the file
  • Colors across the entire design spec can be updated by going to “Select File → Modify Colors”

On the development side, use Tailwind classes to reference tokens:

// Using token colors
<div className="bg-[var(--Labels-Primary)] text-[var(--Labels-Reverse)]" />

// Using token spacing
<div className=”px-16 py-8 gap-8” />

2. Modifying Variables / Colors​

Tokens are defined in the @plaud/design-tokens package. After modifying a token value, all components that reference that token will update automatically:

packages/design-tokens/
├── theme/
│   ├── light.css    ← Light theme variables
│   └── dark.css     ← Dark theme variables
└── tailwind/
    └── index.css    ← Tailwind v4 integration

3. Using Typography​

  • Text sizes reference the corresponding design token variables; open the properties panel to inspect them
  • All text values used in components should follow the actual content requirements

4. Using Components​

  • Components can be dragged and dropped directly; each component in the library encapsulates its own layout and structure
  • Modify properties via the properties panel; components may have pre-configured variants or states that can be selected
import { Button } from '@plaud/design'

// Basic usage
<Button variant=”primary”>Primary</Button>
<Button variant=”secondary”>Secondary</Button>
<Button variant=”destructive”>Destructive</Button>

5. Auto Layout​

  • Auto Layout is applied to virtually all component elements, from the simplest to the most complex compositions
  • It enables automatic sizing and alignment, allowing components to adapt gracefully within their parent Layout containers