Design System Starter Kit - Token Architecture + Component Foundation
A starter Figma system with token architecture, core components, naming conventions, and auto-layout structure so teams can build on a real foundation instead of a loose UI kit.
Built for practical use
3-tier token architecture
A starter Figma system with token architecture, core components, naming conventions, and auto-layout structure so teams can build on a real foundation instead of a loose UI kit.
20 core components
A starter Figma system with token architecture, core components, naming conventions, and auto-layout structure so teams can build on a real foundation instead of a loose UI kit.
File structure guidance
A starter Figma system with token architecture, core components, naming conventions, and auto-layout structure so teams can build on a real foundation instead of a loose UI kit.
Maturity checklist
A starter Figma system with token architecture, core components, naming conventions, and auto-layout structure so teams can build on a real foundation instead of a loose UI kit.
Scope Your Design System
Define maturity, platforms, token layers, and the first components your team should standardize.
What This Resource Covers
This is a documented starter guide for building a SaaS design system from scratch. It includes:
- Design token architecture (3-tier system used by leading design systems)
- Core component inventory (20 essential components)
- Figma file structure and setup
- Naming conventions
- Integration guidance (Figma → dev handoff)
Note: The actual Figma file is distributed separately. This markdown document explains the architecture, rationale, and implementation so you can build your own starter (or understand why ours is structured the way it is).
Who this is for: Designers and design leads building a new design system, or founders evaluating what "a good design system" should include.
Part 1: Why Design Tokens Matter
The problem design tokens solve
Without tokens:
- Colors scattered across 200 screens as raw hex codes (
#3B82F6,#3B82F6,#3C82F5...) - Spacing values duplicated (
16px,16px,15px— inconsistencies creep in) - Changing the brand color requires finding-and-replacing across every file
- Dark mode requires manually duplicating every color
- Developers re-implement styles instead of using shared values
With tokens:
- One source of truth: primary brand color is defined once
- Change the token, everything updates automatically
- Themes become possible (light/dark, brand variants, accessibility modes)
- Designers and developers reference the same tokens
- Design and code stay in sync
The 3-tier token architecture
Leading design systems (Salesforce Lightning, Adobe Spectrum, IBM Carbon, Atlassian Design System) use a 3-tier architecture:
Tier 1: Primitive (Reference) Tokens Raw values. The complete palette of choices.
blue-50,blue-100, ...blue-900space-1(4px),space-2(8px), ...space-16(64px)font-size-xs(12px),font-size-sm(14px), ...font-size-4xl(48px)
Tier 2: Semantic (Alias) Tokens Named by purpose, referencing primitives.
color-primary→blue-600color-error→red-500space-sm→space-2text-body-default→font-size-sm
Tier 3: Component Tokens Named by component, referencing semantics.
button-primary-background→color-primarybutton-primary-text→color-whitecard-padding→space-md
Why 3 tiers matter:
- Change the brand color once (primitive) → everything updates
- Switch themes (dark mode) → change semantic tokens, components update
- Customize a specific component → change component tokens without affecting others
Part 2: Color Token System
Primitive color palette
Start with a neutral scale + 3-5 hue ramps:
Neutrals (critical — use 80% of the time):
- gray-0 (white, #FFFFFF)
- gray-50 through gray-950 (11 values)
- gray-1000 (black, #000000)
Primary (brand color):
- primary-50 through primary-900
Semantic hues:
- success (green): 50-900
- warning (amber/yellow): 50-900
- error (red): 50-900
- info (blue): 50-900
Each ramp should include:
- -50: Background tint (very light)
- -100, -200, -300: Light shades (backgrounds, borders)
- -400: Mid-light (disabled states)
- -500: Base (primary use)
- -600: Mid-dark (hover states)
- -700, -800, -900: Dark shades (text, high contrast)
Semantic color tokens
| Token | References | Usage |
|---|---|---|
color-background-default | gray-0 (white) | Page background |
color-background-surface | gray-50 | Cards, modals |
color-background-subtle | gray-100 | Code blocks, dividers |
color-text-primary | gray-900 | Body text |
color-text-secondary | gray-700 | Secondary text |
color-text-tertiary | gray-500 | Metadata, captions |
color-text-disabled | gray-400 | Disabled elements |
color-text-inverse | gray-0 | Text on dark backgrounds |
color-border-default | gray-200 | Default borders |
color-border-strong | gray-300 | Emphasized borders |
color-border-focus | primary-500 | Focus rings |
color-action-primary | primary-600 | Primary buttons |
color-action-primary-hover | primary-700 | Primary hover |
color-feedback-success | success-500 | Success states |
color-feedback-warning | warning-500 | Warning states |
color-feedback-error | error-500 | Error states |
color-feedback-info | info-500 | Info states |
Dark mode considerations
For dark mode, semantic tokens change but primitives stay the same:
| Token | Light Mode | Dark Mode |
|---|---|---|
color-background-default | gray-0 | gray-950 |
color-background-surface | gray-50 | gray-900 |
color-text-primary | gray-900 | gray-50 |
color-text-secondary | gray-700 | gray-200 |
color-border-default | gray-200 | gray-700 |
Dark mode gotchas:
- Pure black (#000000) is too harsh — use gray-950 (e.g., #0A0A0A)
- Shadows don't work in dark mode — use elevation through surface colors
- Primary colors often need desaturation in dark mode
- Error red in dark mode uses red-400 instead of red-500 (less harsh)
Contrast requirements
Every color token pair (background + text) must meet WCAG AA:
- Normal text (<18px): 4.5:1 contrast minimum
- Large text (18px+ or 14px+ bold): 3:1 contrast minimum
- UI components: 3:1 contrast minimum
Test tools:
- WebAIM Contrast Checker (webaim.org/resources/contrastchecker)
- Stark plugin for Figma
- Chrome DevTools Accessibility inspector
Part 3: Typography Token System
Primitive font size scale
Based on a modular scale (1.250 ratio or similar):
| Token | Size | Use Case |
|---|---|---|
font-size-xs | 12px (0.75rem) | Captions, labels |
font-size-sm | 14px (0.875rem) | Small UI text |
font-size-base | 16px (1rem) | Body text (default) |
font-size-md | 18px (1.125rem) | Large body text |
font-size-lg | 20px (1.25rem) | Subheadings |
font-size-xl | 24px (1.5rem) | H4 |
font-size-2xl | 30px (1.875rem) | H3 |
font-size-3xl | 36px (2.25rem) | H2 |
font-size-4xl | 48px (3rem) | H1 |
font-size-5xl | 60px (3.75rem) | Display |
Semantic typography tokens
| Token | Size | Weight | Line Height |
|---|---|---|---|
text-display | 48px | Bold (700) | 1.1 |
text-heading-1 | 36px | Bold (700) | 1.2 |
text-heading-2 | 30px | Semibold (600) | 1.25 |
text-heading-3 | 24px | Semibold (600) | 1.3 |
text-heading-4 | 20px | Semibold (600) | 1.4 |
text-body-lg | 18px | Regular (400) | 1.55 |
text-body | 16px | Regular (400) | 1.5 |
text-body-sm | 14px | Regular (400) | 1.45 |
text-caption | 12px | Regular (400) | 1.4 |
text-label | 14px | Medium (500) | 1.4 |
text-button | 14px | Medium (500) | 1 |
Font family recommendations
For SaaS: Inter (free, modern, excellent legibility at small sizes) Alternatives: Roboto, Manrope, DM Sans, Plus Jakarta Sans, Geist
Font weights to include:
- 400 (Regular)
- 500 (Medium)
- 600 (Semibold)
- 700 (Bold)
Avoid loading all 9 weights — most SaaS products need only 4.
Part 4: Spacing Token System
Primitive spacing scale
Based on 4px base unit:
| Token | Size | Use |
|---|---|---|
space-0 | 0px | Reset |
space-1 | 4px | Very tight spacing |
space-2 | 8px | Tight spacing |
space-3 | 12px | Small gaps |
space-4 | 16px | Default gap |
space-5 | 20px | Medium gap |
space-6 | 24px | Comfortable gap |
space-8 | 32px | Large gap |
space-10 | 40px | Extra-large gap |
space-12 | 48px | Section spacing |
space-16 | 64px | Large sections |
space-20 | 80px | Major sections |
space-24 | 96px | Page-level spacing |
Why the 8-point grid
- 8 is divisible by 2 and 4 (flexible)
- Matches common screen resolutions
- Aligns with native mobile guidelines (iOS, Android)
- Creates visual rhythm
- Industry standard (Material Design, iOS HIG, Carbon, Polaris)
Part 5: Border Radius Token System
| Token | Size | Use |
|---|---|---|
radius-none | 0px | Sharp corners |
radius-sm | 4px | Small elements (badges, tags) |
radius-md | 6-8px | Default (buttons, inputs) |
radius-lg | 12px | Cards, modals |
radius-xl | 16px | Large containers |
radius-2xl | 24px | Feature cards |
radius-full | 9999px | Pills, circular avatars |
Part 6: Shadow/Elevation Tokens
| Token | Use |
|---|---|
shadow-xs | Subtle depth (input fields) |
shadow-sm | Cards at rest |
shadow-md | Cards on hover, dropdowns |
shadow-lg | Modals, popovers |
shadow-xl | Large floating elements |
Example shadow values:
shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05)
shadow-md: 0 4px 6px rgba(0, 0, 0, 0.05), 0 2px 4px rgba(0, 0, 0, 0.06)
shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1), 0 4px 6px rgba(0, 0, 0, 0.05)Dark mode: Shadows don't work well. Use surface elevation (background color shifts) instead.
Part 7: 20 Core Components (Starter Set)
These are the minimum components needed for most SaaS products.
Foundation Components
1. Button
- Variants: Primary, Secondary, Tertiary/Ghost, Destructive
- Sizes: Small (32px), Medium (40px), Large (48px)
- States: Default, Hover, Focus, Active, Disabled, Loading
- With/without icon (left, right, icon-only)
2. Input
- Variants: Text, Email, Password, Search, Number, Textarea
- States: Default, Hover, Focus, Filled, Disabled, Error, Success
- With/without label, helper text, error message
- With/without leading icon, trailing icon
3. Select / Dropdown
- Single-select, Multi-select
- Searchable, Filterable
- With/without grouping
- States: Default, Open, Disabled, Error
4. Checkbox & Radio
- States: Unchecked, Checked, Indeterminate, Disabled
- With/without label and description
5. Switch / Toggle
- On, Off states
- Sizes: Small, Medium
- With/without label
6. Slider
- Single value, Range
- With/without labels, value display
Layout Components
7. Card
- Variants: Default, Hoverable, Clickable
- With/without header, footer
- Padding variants
8. Modal / Dialog
- Sizes: Small (400px), Medium (600px), Large (800px), Full-screen
- With/without backdrop, close button
- Action placement (bottom-right)
9. Drawer / Side Panel
- Positions: Left, Right
- Sizes: Small, Medium, Large
10. Tabs
- Variants: Horizontal, Vertical
- Sizes: Small, Medium, Large
- With/without icons
Feedback Components
11. Toast / Notification
- Variants: Success, Error, Warning, Info
- Positions: Top, Bottom, Top-right, Bottom-right
- Duration: Auto-dismiss (3-5s) or persistent
12. Alert / Banner
- Variants: Info, Success, Warning, Error
- With/without close button, action button
13. Progress Indicator
- Variants: Linear, Circular
- Determinate, Indeterminate
14. Skeleton Loader
- For cards, text lines, images, avatars
Navigation Components
15. Navigation Bar (Top)
- Logo, navigation items, user menu
- With/without search
16. Sidebar Navigation
- Collapsible, Expanded
- With sub-navigation (nested)
17. Breadcrumb
- With separators
- Truncation for long paths
18. Pagination
- Page numbers, Previous/Next
- With/without page size selector
Data Display Components
19. Table
- Sortable columns
- Row selection (single, multi)
- Pagination or infinite scroll
- Empty state, loading state
- Actions (row-level, bulk)
20. Avatar & User Display
- Variants: Image, Initials, Icon
- Sizes: XS (24px), SM (32px), MD (40px), LG (48px), XL (64px)
- With/without status indicator
Additional (Nice-to-Have)
- Tag / Chip / Badge
- Tooltip
- Popover
- Accordion / Collapse
- Stepper / Progress Stepper
- Rating / Stars
- Empty State
- Error State
Part 8: Figma File Structure
Recommended organization:
📁 Design System (Figma File)
├── 📄 01 - Getting Started (intro, guidelines)
├── 📄 02 - Tokens (colors, typography, spacing)
├── 📄 03 - Icons (icon library)
├── 📄 04 - Foundation Components (buttons, inputs, etc.)
├── 📄 05 - Layout Components (cards, modals, etc.)
├── 📄 06 - Feedback Components (toasts, alerts)
├── 📄 07 - Navigation Components (nav, tabs, breadcrumbs)
├── 📄 08 - Data Components (tables, charts, avatars)
├── 📄 09 - Patterns (login, signup, settings, dashboard)
├── 📄 10 - Templates (common page layouts)
└── 📄 99 - Changelog / RoadmapEach component page includes:
- Component example (default state)
- All variants displayed in a grid
- All states documented
- Usage guidelines (when to use, when not to use)
- Anatomy (labeled parts)
- Spec annotations (sizes, spacing)
- Related components (links to similar patterns)
Part 9: Naming Conventions
Component names: PascalCase
- Button, InputField, NavigationBar, UserAvatar
Variants: kebab-case
- primary, secondary, destructive-confirm
States: kebab-case
- default, hover, focus, active, disabled, loading, error
Tokens: kebab-case with semantic prefixes
color-background-defaultspace-mdtext-bodyradius-lgshadow-md
Figma component structure:
Button/Primary/Medium/Default
Button/Primary/Medium/Hover
Button/Primary/Medium/DisabledPart 10: Dev Handoff Integration
Figma → Code token export
Tools for syncing tokens:
- Style Dictionary (Amazon's open source tool) — exports tokens to multiple formats
- Tokens Studio (Figma plugin) — manages tokens in Figma
- Specify — Figma-to-code sync
- Supernova — Design system management
Output formats:
- CSS custom properties
- SCSS variables
- JavaScript/TypeScript constants
- Tailwind config
- iOS Swift / Android Kotlin
Component documentation for developers
Each component should have:
- Figma link
- Code example (React/Vue/Svelte)
- Props documentation
- Accessibility notes (ARIA roles, keyboard behavior)
- Browser compatibility notes
Part 11: Design System Maturity Checklist
Rate your design system:
Level 1: Starter (where most teams begin)
- Color tokens defined
- Typography scale defined
- 10-15 core components documented
- Figma file structured
Level 2: Established
- 3-tier token architecture (primitive → semantic → component)
- 20+ core components with all states
- Dark mode support
- Accessibility tested (WCAG AA)
- Documented usage guidelines
Level 3: Mature
- Tokens synced to code (Style Dictionary or similar)
- Component library in production code
- Design system team / contributors
- Versioning and changelog
- Regular audits and updates
- Training resources for new designers/developers
Level 4: World-class (few reach this)
- Multi-product consistency
- Public documentation site
- Design system metrics (adoption, contribution)
- Multi-theme support (light/dark/custom)
- Accessibility testing automated
- Design tokens part of CI/CD
Sources and References
- Salesforce Lightning Design System (public documentation)
- Atlassian Design System (design.atlassian.com)
- IBM Carbon Design System (carbondesignsystem.com)
- Adobe Spectrum (spectrum.adobe.com)
- Shopify Polaris (polaris.shopify.com)
- Material Design 3 (m3.material.io)
- Design Tokens Community Group (W3C)
- Nathan Curtis, "Design Tokens for Dummies"
- Brad Frost, "Atomic Design"
- Jina Anne, Design Systems Handbook
Created by Desisle — SaaS UI/UX Design Agency desisle.com | hello@desisle.com Free to use and share with attribution.
For a custom design system project, contact us at hello@desisle.com.
Keep Building With These Next
The UI Design Checklist - 80 Points for Pixel-Perfect Screens
A UI review checklist for typography, color systems, spacing, consistency, responsiveness, states, accessibility, and handoff readiness.
Open UI ChecklistSaaS Color System Generator - Build an Accessible Palette in Minutes
A tool concept that takes one primary brand color and expands it into a SaaS-ready, WCAG-aware system including semantic colors and export options.
Open Color System GeneratorUser Journey Mapping Template - From First Touch to Renewal
A visual template for mapping discovery, signup, onboarding, support, renewal, and referral moments with emotion tracking and friction spotting.
Open Journey MapNeed This Applied to Your Product? We'll Turn It Into Execution.
These resource pages are meant to be used hands-on. If you want the audit, plan, or framework translated into live product work, we can do that with your team.