Move all existing Twenty UI component families into
`primitives/<family>`, including components that still use their older
APIs. Reserve `components` for future app building blocks.
Replace the old family entry points with `twenty-ui/primitives/<family>`
and update workspace imports, renderer examples, documentation, and
generated exports.
Add embedded Storybook previews to all 17 Twenty UI component
documentation pages, with light and dark themes and interactive
examples.
On `main` and SDK or UI release tags, `CD Storybook UI` builds the
public Storybook, checks that the documentation's embedded story IDs
exist, and uploads the static site as a GitHub Actions artifact.
After the build, it dispatches `deploy-storybook-ui.yaml` in
`twenty-factory` with the source run ID. Factory validates the
successful source run, downloads its artifact, and publishes the static
files to Cloudflare Pages without executing the downloaded site.
Cloudflare credentials stay in factory's `storybook-ui` environment.
`main` updates the production site; release tags publish version aliases
such as `v2-42-0.twenty-ui-storybook.pages.dev`.
Merge [twenty-factory
#120](https://github.com/twentyhq/twenty-factory/pull/120) first and
complete the Cloudflare project, token, and GitHub environment setup in
its description before merging this PR. That description also covers
validating the first deployment and switching `storybook.twenty.com` to
Pages.
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/25889?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
Add a UI Library documentation section so developers can get started
with Twenty UI, customize its theme, and use its components.
The section has guides for setup, theming, design tokens, dark mode,
server rendering, and accessibility, plus a page per component (17 so
far) with usage examples and a generated props reference.
How the references are generated and kept in sync:
- `nx generate:ui twenty-docs` extracts prop types and JSDoc from the
twenty-ui components with react-docgen-typescript and the design tokens
from the token pipeline, writes them to `packages/twenty-ui/generated`,
and renders MDX snippets under
`packages/twenty-docs/snippets/ui/generated`.
- `nx check:ui twenty-docs` runs in CI Docs and fails when the data or
snippets are stale, when a page and the generated snippets disagree, or
when a guide example does not compile against the public entry points
and peer dependencies.
- Twenty UI's own props now carry JSDoc descriptions, and generation
fails on an undocumented prop.
Old `/twenty-ui/*` URLs redirect to the new pages. The pages use the
existing Crowdin translation workflow; the generated snippets are shared
across locales.
Tracked as `DOCS-01` on twentyhq/core-team-issues#2784.
### Problem
Crowdin parses `<foo>` in prose as a tag rather than literal text, so an
angle bracket placeholder is dropped or mangled in every translated
page. Curly braces `{foo}` survive the round trip.
A `no-angle-bracket-placeholders` rule used to guard against this. It
ran as `'error'` on `**/*.mdx` in the root `eslint.config.mjs` from
#15751 (Nov 2025) until #18443 migrated us to oxlint. oxlint has no
`eslint-plugin-mdx` equivalent, so the whole `**/*.mdx` block went with
it and the rule stopped running. The file was carried into
`twenty-oxlint-rules` wired to nothing, and #24535 removed it as dead
code. So the guard has been silently off for about five months, not
missing by design.
This restores it in a form that runs without a JSX AST: a plain text
scan, no new dependencies.
### Change
- `scripts/lint-mdx.ts` scans the 204 English source pages and skips
`l/` (the 2613 generated Crowdin files, not hand-editable). A violation
there is only ever a symptom of one in the source.
- The `lint` target was `{}`, an empty no-op, while the `docs-lint` CI
job invoked `nx lint twenty-docs`. So the job has been passing without
running anything. The target now runs the package's own `.oxlintrc.json`
(nothing was running that either, so `scripts/*.ts` is linted for the
first time) followed by the MDX scan.
- A `test` target plus a vitest config for the package, wired into CI.
14 tests.
### On the backtick handling
The scanner skips angle brackets inside code spans, since they are
legitimate there. The first version did this with a running backtick
parity count over the whole file, which is unsound: one unpaired
backtick in prose flips parity and silently suppresses every finding
after it in the file, while the run still prints clean.
`docker-compose.mdx` was already in that state from line 210.
Fixed in 54dff6e4: backtick runs are now paired within a line, by run
length, which is how inline code actually delimits. Three tests pin it,
all of which fail against the old counter.
### Verification
```
$ npx nx test twenty-docs
Tests 14 passed (14)
```
End to end on the real CI command. Seeding two violations into
`getting-started/introduction.mdx`:
```
$ npx nx lint twenty-docs
getting-started/introduction.mdx:78:5 <workspace-slug> reads as a tag in Crowdin, use {workspace-slug} instead
getting-started/introduction.mdx:78:34 <span> reads as a tag in Crowdin, use {span} instead
2 angle bracket placeholder(s) found in 204 MDX files.
nx lint exit=1
```
Unseeded, the tree is clean: `No angle bracket placeholders in 204 MDX
files.`
To be clear about scope: the gate catches nothing in the tree today. Of
the 83 angle brackets in the English source, 81 sit inside code spans
and 2 are a legitimate `kbd` element. It is a preventive guard, plus the
CI wiring fix above. The live corruption (a backslash before angle
brackets inside inline code in the translated output, 494 across 156
files) is a `crowdin-normalizer` concern, not something a source-side
gate can see, and is handled in a separate PR.
### Not in this PR
`DOCS-01` also covered `mdx-component-newlines` (component tags sharing
a line with prose). Deferring it, but not because the current
occurrences are settled idiom: blame shows 137 of them were authored
while that rule was live at `'error'` and only 68 after it went dark, so
it was never really enforcing. Its opening-tag branch early-returns
whenever the following text is adjacent, so a component wrapping text on
one line never tripped it. Porting it faithfully buys nothing without
redesigning what it checks, which is a separate call that stays on
#2784.
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/24540?utm_source=github"
rel="nofollow noreferrer noopener" target="_blank">``<img alt="Review
in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg">``</a>
---------
Co-authored-by: Abdul Rahman <81605929+abdulrahmancodes@users.noreply.github.com>
Co-authored-by: Abdul Rahman <ar5438376@gmail.com>
## Summary
Two robustness fixes to `docs-i18n-pull.yaml` so localized docs can't
silently drift:
1. **Prune orphan localized files.** The pull only adds/updates files,
never deletes — so localized copies of renamed/moved/deleted English
pages linger and serve dead URLs (recently ~113 of them). A new
`prune-orphan-translations` script (run with `--apply` in the workflow,
on real pulls only) removes any `l/<lang>/**` file whose English source
no longer exists.
2. **Surface per-language download failures.** The loop previously
swallowed failures with `|| echo "Warning..."`, so a language whose
Crowdin server-side build fails (e.g. `ja`, failing at 79%) was skipped
*silently* and froze indefinitely while every other language updated. We
now collect failures, still commit the languages that succeeded, and
**fail the run at the end** so a broken language is visible.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
## Summary
The Getting Started pages on the docs site (docs.twenty.com) were only
ever available in English, never translated into the other supported
languages.
**Root cause:** The Getting Started section (added in #19728) was never
added to the Crowdin source config (`crowdin-docs.yml`), so its `.mdx`
files were never uploaded for translation. Only `user-guide`,
`developers`, and `twenty-ui` were configured.
This also surfaced a related bug: because the pages had no translations,
the navigation generator fell back to the English page path for every
language, duplicating paths like `getting-started/introduction` across
all 14 language navs. Mintlify treats duplicate cross-language paths as
undefined behavior, which broke the language switcher (it always
redirected to `/getting-started/introduction`).
## Changes
- `.github/crowdin-docs.yml` — add `getting-started/**/*.mdx` as a
translation source so the pages get sent to Crowdin.
- `packages/twenty-docs/scripts/fix-translated-links.sh` — add
`getting-started` link-rewriting rules to match the other sections.
- `packages/twenty-docs/scripts/generate-docs-json.ts` — only include a
page in a non-default language when its translated file exists; drop
empty groups/tabs (removes the duplicate cross-language paths that broke
the switcher).
- `packages/twenty-docs/docs.json` — regenerated.
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/21842?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
## Scope & Context
Closes#20358.
The Apps docs were restructured into nested pages, but the generated
docs navigation source still pointed to the old flat Apps page slugs.
This made Developers > Apps navigation entries point to removed English
docs pages.
## Technical inputs
- Update `packages/twenty-docs/navigation/base-structure.json` to use
the current nested Apps docs structure.
- Regenerate `packages/twenty-docs/docs.json` and
`packages/twenty-docs/navigation/navigation.template.json` from the
updated structure.
- Update `generate-docs-json.ts` so localized navigation falls back to
the English slug when the localized `.mdx` file does not exist yet,
avoiding generated 404 links while translations catch up.
## Validation
- Parsed `docs.json`, `base-structure.json`, and
`navigation.template.json` as valid JSON.
- Checked all generated navigation page slugs against existing `.mdx`
files: `missing nav mdx 0`.
- Checked Apps navigation specifically: `missing apps nav mdx 0`.
`yarn docs:generate` could not be run in this local environment because
Yarn/Corepack is not installed here, so I regenerated the JSON files
with the same generator logic via Node.
Co-authored-by: dev111-actor <dev111-actor@users.noreply.github.com>
## Summary
- **New Getting Started section** with quickstart guide and restructured
navigation
- **Halftone-style illustrations** for User Guide and Developer
introduction cards using a Canvas 2D filter script
- **Removed hero images** (`image:` frontmatter + `<Frame><img>` blocks)
from all user-guide article pages
- **Cleaned up translations** (13 languages): removed hero images and
updated introduction cards to use halftone style
- **Cleaned up twenty-ui pages**: removed outdated hero images from
component docs
- **Deleted orphaned images**: `table.png`, `kanban.png`
- **Developer page**: fixed duplicate icon, switched to 3-column layout
## Test plan
- [ ] Verify docs site builds without errors
- [ ] Check User Guide introduction page renders halftone card images in
both light and dark mode
- [ ] Check Developer introduction page renders 3-column layout with
distinct icons
- [ ] Confirm article pages no longer show hero images at the top
- [ ] Spot-check a few translated pages to ensure hero images are
removed
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: github-actions <github-actions@twenty.com>
## Summary
- **Fix junction relation toggle not being saved**: The form schema
wasn't tracking the `settings` field, so changes to
`junctionTargetFieldId` weren't marked as dirty
- **Add type-safe documentation paths**: Generate TypeScript constants
from `base-structure.json` to prevent broken documentation links
- **Create many-to-many relations documentation**: Step-by-step guide
for building many-to-many relations using junction objects
- **Update `getDocumentationUrl`**: Now uses shared constants from
`twenty-shared` for base URL, default path, and supported languages
## Key Changes
### Junction Toggle Fix
- Added `settings` field to the form schema in
`SettingsDataModelFieldRelationForm.tsx`
- Fixed the toggle to properly merge settings when updating
`junctionTargetFieldId`
### Type-Safe Documentation Paths
- New constants in `twenty-shared/constants`:
- `DOCUMENTATION_PATHS` - All 161 documentation paths as typed constants
- `DOCUMENTATION_SUPPORTED_LANGUAGES` - 14 supported languages
- `DOCUMENTATION_BASE_URL` / `DOCUMENTATION_DEFAULT_PATH`
- Generator script: `yarn docs:generate-paths`
- CI integration: Added to `docs-i18n-pull.yaml` workflow
### Documentation
- New article:
`/user-guide/data-model/how-tos/create-many-to-many-relations`
- Updated `/user-guide/data-model/capabilities/relation-fields.mdx` with
Lab warning and link
## Test plan
- [ ] Verify junction toggle saves correctly when enabled/disabled
- [ ] Verify documentation link opens correct localized page
- [ ] Verify `yarn docs:generate-paths` regenerates paths correctly
## Summary
Fixes French documentation navigation labels and internal link redirects
to English pages.
## Changes
1. **Translated French navigation** - All tab/group labels in
`docs.json` now display in French
2. **Automated link fixing** - Created `fix-translated-links.sh` script
that adds `/fr/` prefix to internal links
3. **CI Integration** - Script runs automatically after Crowdin syncs
translations
Raphaël Bosi
