snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/ui/getting-started.mdx

@@ -0,0 +1,93 @@
+---
+title: Getting started
+description: Install Twenty UI in a React application and use its components and themes.
+---
+
+Twenty UI is Twenty's React component library. It provides components, icons, and theme tokens with prebuilt CSS, so your application does not need a CSS-in-JS compiler.
+
+<Note>
+  Twenty UI is in alpha. Its version follows the Twenty SDK release cycle, and
+  component APIs can change between releases. In a Twenty app, keep `twenty-ui`,
+  `twenty-sdk`, and `twenty-client-sdk` on the same version.
+</Note>
+
+## Install
+
+For a standalone React application, install the library and its peer dependencies:
+
+```bash
+yarn add twenty-ui monaco-editor react@^19 react-dom@^19
+```
+
+`monaco-editor` powers the code editor components, but install it even if you never render an editor: the `twenty-ui/primitives/input`, `twenty-ui/primitives/feedback`, and `twenty-ui/primitives/navigation` entry points reference it, and bundlers fail to resolve it otherwise.
+
+If you are building a Twenty app, follow [Using Twenty UI components](/developers/extend/apps/layout/front-components#using-twenty-ui-components). The front component renderer supplies the workspace theme and has a different setup from a standalone browser application.
+
+## Load styles and provide a theme
+
+Import the component stylesheet and a theme stylesheet once at your application entry point. `ThemeProvider` applies the active theme class and makes theme values available to components.
+
+```tsx
+import { Field, Input } from 'twenty-ui/primitives/input';
+import { ThemeProvider } from 'twenty-ui/theme-constants';
+
+import 'twenty-ui/style.css';
+import 'twenty-ui/theme-light.css';
+
+export const App = () => (
+  <ThemeProvider colorScheme="light">
+    <Field.Root>
+      <Field.Label>Email</Field.Label>
+      <Input name="email" type="email" placeholder="you@example.com" />
+      <Field.Description>Use your work email address.</Field.Description>
+    </Field.Root>
+  </ThemeProvider>
+);
+```
+
+The component stylesheet includes a global reset. Review its effect when adding Twenty UI to an existing application.
+
+## Choose an entry point
+
+Import components from their public subpath to keep imports focused:
+
+Primitives are foundational controls, including compound controls such as Select,
+Menu, and AlertDialog. Shared components combine primitives into recurring
+design presets and reusable app building blocks. Both receive data and callbacks
+from the application.
+
+Use [MainButton](/ui/components/input/main-button) for prominent actions and
+[LightButton](/ui/components/input/light-button) for lightweight actions. Both
+come from `twenty-ui/components` and share the foundational
+[Button](/ui/primitives/input/button) interaction contract. Routing and page
+layout remain in the application.
+
+Each primitive family has a matching public entry point, such as
+`twenty-ui/primitives/input`.
+
+| Import                                 | Contents                                                     |
+| -------------------------------------- | ------------------------------------------------------------ |
+| `twenty-ui/components`                 | Shared design presets and reusable app building blocks       |
+| `twenty-ui/primitives/accessibility`   | Hidden elements and keyboard interaction helpers             |
+| `twenty-ui/primitives/data-display`    | Avatars, chips, tags, status indicators, and display helpers |
+| `twenty-ui/primitives/feedback`        | Toasts, banners, progress bars, and loaders                  |
+| `twenty-ui/primitives/input`           | Buttons, form controls, pickers, and code editors            |
+| `twenty-ui/primitives/json-visualizer` | JSON tree viewer                                             |
+| `twenty-ui/primitives/layout`          | Layout, animation, resizing, and section components          |
+| `twenty-ui/primitives/navigation`      | Links, list items, menus, and tabs                           |
+| `twenty-ui/primitives/surfaces`        | Cards, dialogs, menus, popovers, and tooltips                |
+| `twenty-ui/primitives/typography`      | Text, headings, labels, and typography helpers               |
+| `twenty-ui/icon`                       | Icons                                                        |
+| `twenty-ui/theme-constants`            | Theme provider, hooks, and CSS variable references           |
+
+Import individual icons, such as `IconCheck`, from `twenty-ui/icon`. The dynamic icon provider includes the full icon catalog, so reserve it for interfaces that need to look up icons at runtime.
+
+## Continue
+
+- [Theming](/ui/theming): use semantic tokens and scoped overrides.
+- [Dark mode](/ui/dark-mode): switch between light and dark palettes.
+
+## Browse the library
+
+- [Primitives](/ui/primitives/overview): foundational controls grouped by family, with usage examples and API references.
+- [Components](/ui/components/overview): shared design presets and reusable app building blocks composed from primitives.