Charles BochetandGitHub
7a2e397ad1
## Summary
Completes the migration of the frontend styling system from **Emotion**
(`@emotion/styled`, `@emotion/react`) to **Linaria** (`@linaria/react`,
`@linaria/core`), a zero-runtime CSS-in-JS library where styles are
extracted at build time.
This is the final step of the migration — all ~494 files across
`twenty-front`, `twenty-ui`, `twenty-website`, and `twenty-sdk` are now
fully converted.
## Changes
### Styling Migration (across ~480 component files)
- Replaced all `@emotion/styled` imports with `@linaria/react`
- Converted runtime theme access patterns (`({ theme }) => theme.x.y`)
to build-time `themeCssVariables` CSS custom properties
- Replaced `useTheme()` hook (from Emotion) with
`useContext(ThemeContext)` where runtime theme values are still needed
(e.g., passing colors to non-CSS props like icon components)
- Removed `@emotion/react` `css` helper usages in favor of Linaria
template literals
### Dependency & Configuration Changes
- **Removed**: `@emotion/react`, `@emotion/styled` from root
`package.json`
- **Added**: `@wyw-in-js/babel-preset`, `next-with-linaria` (for
twenty-website SSR support)
- Updated Nx generator defaults from `@emotion/styled` to
`@linaria/react` in `nx.json`
- Simplified `vite.config.ts` (removed Emotion-specific configuration)
- Updated `twenty-website/next.config.js` to use `next-with-linaria` for
SSR Linaria support
### Storybook & Testing
- Removed `ThemeProvider` from Emotion in Storybook previews
(`twenty-front`, `twenty-sdk`)
- Now relies solely on `ThemeContextProvider` for theme injection
### Documentation
- Removed the temporary `docs/emotion-to-linaria-migration-plan.md`
(migration complete)
- Updated `CLAUDE.md` and `README.md` to reflect Linaria as the styling
stack
- Updated frontend style guide docs across all locales
## How it works
Linaria extracts styles at build time via the `@wyw-in-js/vite` plugin.
All expressions in `styled` template literals must be **statically
evaluable** — no runtime theme objects or closures over component state.
- **Static styles** use `themeCssVariables` which map to CSS custom
properties (`var(--theme-color-x)`)
- **Runtime theme access** (for non-CSS use cases like icon `color`
props) uses `useContext(ThemeContext)` instead of Emotion's `useTheme()`
Twenty Documentation
Official documentation for Twenty CRM, powered by Mintlify.
🌐 Live Site
Visit the documentation at docs.twenty.com
📚 Content
This repository contains:
- User Guide (46 pages) - Complete guide for Twenty users
- Developers (24 pages) - Technical documentation for developers
- Twenty UI (25 pages) - UI component library documentation
🚀 Local Development
To run the documentation locally:
# From the twenty monorepo root
npx nx run twenty-docs:dev
The documentation will be available at http://localhost:3000
📝 Editing Content
Adding/Editing Pages
-
Edit MDX files in the appropriate directory:
user-guide/- User documentationdevelopers/- Developer documentationtwenty-ui/- Component documentation
-
Update
navigation/base-structure.jsonif you need to change the tab/group hierarchy or add/remove pages. This file stays in the repo and is not uploaded to Crowdin. -
Keep the translation template (
navigation/navigation.template.json) in sync by runningyarn docs:generate-navigation-templateafter editing the base structure. This template is the only file that should be pushed to Crowdin. -
For each translated locale pulled from Crowdin, ensure a
packages/twenty-docs/l/<language>/navigation.jsonfile exists. These files contain labels only; page slugs always come from the base structure. -
Run
yarn docs:generateto rebuilddocs.jsonfrom the base structure + translated labels.
MDX Format
All documentation pages use MDX format with frontmatter:
---
title: Page Title
description: Page description
image: /images/path/to/image.png
---
Your content here...
Adding Images
- Place images in the
/images/directory - Reference them in MDX:
 - Or use Mintlify Frame component:
<Frame>
<img src="/images/your-image.png" alt="Description" />
</Frame>
🔧 Configuration
navigation/base-structure.json- Source of truth for tabs, groups, icons, and page slugs (English only, not sent to Crowdin).navigation/navigation.template.json- Generated translation template (labels only) that is uploaded to Crowdin.l/<language>/navigation.json- Locale-specific label files pulled from Crowdin.docs.json- Generated Mintlify configuration (always runyarn docs:generateafter modifying navigation files).package.json- Package dependencies and scripts (docs:generate,docs:generate-navigation-template, …).project.json- Nx workspace configuration
📦 Building
# Build the documentation
npx nx run twenty-docs:build
🔗 Links
🤝 Contributing
To contribute to the documentation:
- Fork the repository
- Make your changes in the
packages/twenty-docsdirectory - Test locally with
npx nx run twenty-docs:dev - Submit a pull request
📄 License
This documentation is part of the Twenty project and is licensed under AGPL-3.0.