Twenty UI Design System
Relevant source files
The following files were used as context for generating this wiki page:
- packages/twenty-ui/README.md
- packages/twenty-codex-plugin/references/design/front-component-ui.md
- PRODUCT.md
- packages/twenty-docs/README.md
- packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js
- packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md
Twenty UI is a comprehensive, standalone UI component library and design system powering the Twenty CRM platform. It is architected to provide a consistent, native feel across the entire ecosystem, including the core product (twenty-front) and modular extensions known as Twenty apps. The system transitions from a legacy implementation (twenty-ui-deprecated) to a modern stack based on headless components and zero-runtime CSS variables.
The design system emphasizes high-quality, professional aesthetics characterized by editorial restraint, quiet conviction, and a typography-first approach. It serves as the bridge between technical functionality and user-facing credibility, ensuring that every interface—whether a core view or a custom front component—scans quickly and maintains predictable interactions.
Sources: packages/twenty-ui/README.md:16-24, PRODUCT.md:37-45, packages/twenty-codex-plugin/references/design/front-component-ui.md:15-18
System Architecture
The modern Twenty UI architecture is built on two primary pillars: Base UI for behavioral primitives and SCSS Modules for a zero-runtime styling layer. This decoupling allows the system to remain highly customizable while maintaining a robust, accessible foundation.
Core Technology Stack
- Behavioral Foundation: Base UI (
@base-ui/react) provides unstyled, accessible primitives like Dialogs, Tooltips, and Switches. - Styling Layer: SCSS Modules (
*.module.scss) replace Linaria to eliminate runtime overhead and simplify build complexity. - State Styling: Utilizes
data-*attributes andclassName-as-function patterns provided by Base UI. - Theming: Driven by CSS variables (
--t-*) and a staticthemeCssVariablesaccessor for consistent token usage.
Sources: packages/twenty-ui/README.md:46-60, packages/twenty-ui/README.md:65-75, packages/twenty-codex-plugin/references/design/front-component-ui.md:20-25
Component Hierarchy Diagram
The following diagram illustrates the relationship between behavioral primitives and presentational components within the system.
The diagram shows how Base UI handles behavior while Twenty UI applies specific visual styling through SCSS Modules and Theme Tokens.
Sources: packages/twenty-ui/README.md:104-125, packages/twenty-ui/README.md:131-135
Design Principles and Tokens
Twenty UI follows a strict set of design rules to ensure a "CRM-native" feel. Instead of marketing-focused "hero" elements, it prioritizes density, scanability, and alignment.
Strategic Design Pillars
- Editorial Restraint: Prioritizes white space and typographic hierarchy over busy components.
- Quiet Conviction: Avoids hype-driven patterns (gradients, "bento" grids, glassmorphism) in favor of tinted neutrals and asymmetry.
- Typography-First: Hierarchy is established by scale and weight contrast using a serif/sans/mono trio.
Sources: PRODUCT.md:47-55, PRODUCT.md:65-72
Design Token Reference
The system utilizes themeCssVariables for all visual measurements to ensure consistency and facilitate theming.
| Category | Token Pattern | Application |
|---|---|---|
| Typography | themeCssVariables.font.size.* | md for body, sm for descriptions. |
| Spacing | themeCssVariables.spacing[...] | [2] for padding, [6] for icon targets. |
| Radius | themeCssVariables.border.radius.* | sm for buttons, md for cards/panels. |
| Icons | themeCssVariables.icon.size.* | md for default rows, sm for quiet chevrons. |
| Hierarchy | themeCssVariables.font.weight.* | medium for titles, regular for body. |
Sources: packages/twenty-codex-plugin/references/design/front-component-ui.md:27-38, packages/twenty-codex-plugin/references/design/front-component-ui.md:46-55
Key Components and Visual States
Front Component UI Rules
Front components are compact widgets designed for CRM surfaces. They must follow specific alignment and hierarchy rules to remain native to the Twenty environment.
- Information Hierarchy: Identifiers (Name/Object) first, followed by explanations, then metadata (Tags/Chips).
- Alignment: Repeated edges must line up. Rows use a flexible
minmax(0, 1fr)column for the primary identifier to ensure actions stay right-aligned. - Compact Sizing: Dense rows typically use
themeCssVariables.spacing[8]for custom row heights.
Sources: packages/twenty-codex-plugin/references/design/front-component-ui.md:88-100, packages/twenty-codex-plugin/references/design/front-component-ui.md:112-118
Visual State Transitions
Components must explicitly design for the full lifecycle of a user interaction.
The diagram represents the mandatory state transitions for front components.
Sources: packages/twenty-codex-plugin/references/design/front-component-ui.md:173-181
State Implementation Patterns
| State | Visual Treatment | Implementation Target |
|---|---|---|
| Loading | Skeletons | Match final content geometry and radius. |
| Empty | Callout | Icon, short title, one sentence, one action. |
| Hover | Transparent Light | themeCssVariables.background.transparent.light. |
| Selected | Selected Variant | Same shape as default row with selected color treatment. |
Sources: packages/twenty-codex-plugin/references/design/front-component-ui.md:150-158, packages/twenty-codex-plugin/references/design/front-component-ui.md:183-195
Development Workflow and Integration
Implementation Guidelines
Developers are required to use Twenty primitives over custom SVG or raw CSS values. Import logic is strictly controlled to ensure compatibility.
- Imports: Use
H2Title,H3Title,Callout,Button,Tag, andAvatarfrom the library. - Token Access: Always use
themeCssVariablesinstead of hardcoded measurements. - One Export Per File: Every helper, type, and client file in
src/must export exactly one thing.
Sources: packages/twenty-codex-plugin/references/design/front-component-ui.md:21-25, packages/twenty-codex-plugin/references/develop-app/app-structure.md:40-45
Validation and Testing
The system enforces a high quality bar through automated gates in the CI pipeline.
- Visual Parity: Uses Argos for pixel-diff regression against the legacy library.
- Accessibility (a11y): Integrated Storybook axe-core checks; violations fail CI unless explicitly overridden.
- Bundle Size:
size-limitmonitors per-entry bundle budgets. - Storybook: Comprehensive coverage for all variants, light/dark modes, and interaction tests.
Sources: packages/twenty-ui/README.md:200-210, packages/twenty-ui/README.md:235-245
Conclusion
The Twenty UI Design System provides the critical infrastructure for building scalable CRM interfaces. By combining the behavioral reliability of Base UI with a zero-runtime SCSS Modules styling layer, it achieves high performance without compromising on aesthetic precision. The system's reliance on standardized theme tokens and strict design rules ensures that whether a feature is built by core maintainers or third-party app developers, it remains cohesive within the broader Twenty ecosystem.
Sources: packages/twenty-ui/README.md:16-24, PRODUCT.md:37-45