@primereact/mcp 11.0.0 → 11.2.0

package/data/llms/primitive/guides/misc/internationalization.md

@@ -0,0 +1,287 @@
+# Internationalization and Localization
+
+Translating component messages and configuring regional settings such as date formats and the first day of the week.
+
+## Overview
+
+Components ship with a set of built-in messages such as filter operator labels, month names and ARIA descriptions. These messages live in a locale registry that is shared across PrimeReact, PrimeVue and PrimeNG through the `@primeuix/locale` package, and are re-exported from `@primereact/core/locale`.
+
+English is registered by default, so no configuration is required until another language is needed.
+
+Setting a language is enough for components to pick it up. No per-component prop is involved. A DatePicker then renders its month and day names in that language, with the first day of the week adjusted to match.
+
+```jsx
+import { PrimeReactProvider } from '@primereact/core';
+import { de } from 'primelocale/js/de.js';
+
+<PrimeReactProvider locale="de" locales={{ de }}>
+    <App />
+</PrimeReactProvider>;
+```
+
+## Import
+
+```js
+import { $t, $l, defineLocale, updateLocale, useLocale, Locale, LocaleService, en } from '@primereact/core/locale';
+```
+
+## Setting the Language
+
+`Locale.use` selects the active language. Every component reading a message re-renders when it changes, so this works both at startup and later in response to a language switcher.
+
+```js
+import { Locale } from '@primereact/core/locale';
+
+Locale.use('de');
+```
+
+Only `en` is built in, so any other language has to be registered first. See [Adding a Language](#adding-a-language) below.
+
+`PrimeReactProvider` also accepts a `locale` prop, which sets the initial language for the components beneath it.
+
+```jsx
+import { PrimeReactProvider } from '@primereact/core';
+
+<PrimeReactProvider locale="de">
+    <App />
+</PrimeReactProvider>;
+```
+
+## Adding a Language
+
+`defineLocale` registers a new language.
+
+```js
+import { defineLocale, Locale } from '@primereact/core/locale';
+
+defineLocale('es', {
+    clear: 'Limpiar',
+    apply: 'Aplicar',
+    accept: 'Sí',
+    reject: 'No',
+    dayNames: ['domingo', 'lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado'],
+    dayNamesShort: ['dom', 'lun', 'mar', 'mié', 'jue', 'vie', 'sáb'],
+    dayNamesMin: ['D', 'L', 'M', 'X', 'J', 'V', 'S'],
+    monthNames: ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'],
+    monthNamesShort: ['ene', 'feb', 'mar', 'abr', 'may', 'jun', 'jul', 'ago', 'sep', 'oct', 'nov', 'dic']
+});
+
+Locale.use('es');
+```
+
+A registered language must be complete. Keys that are left out resolve to `undefined` rather than falling back to English, which renders as an empty label. The practical approach is to spread the built-in English messages and override from there:
+
+```js
+import { defineLocale, en } from '@primereact/core/locale';
+
+defineLocale('es', {
+    ...en,
+    clear: 'Limpiar',
+    apply: 'Aplicar'
+});
+```
+
+The `en` object holds the built-in English messages and is exported for exactly this purpose. Ready-made translations from [PrimeLocale](#ready-made-translations) already cover every key, so spreading is only needed for hand-written translations.
+
+The provider accepts a `locales` map, which registers languages and selects one in a single step. Anything listed here is registered before `locale` is applied.
+
+```jsx
+import { PrimeReactProvider } from '@primereact/core';
+
+<PrimeReactProvider locale="es" locales={{ es: spanishMessages }}>
+    <App />
+</PrimeReactProvider>;
+```
+
+## Updating an Existing Language
+
+`updateLocale` merges new values into a language that is already registered, leaving the remaining keys untouched. It is useful for overriding a handful of labels without redefining a full translation.
+
+```js
+import { updateLocale } from '@primereact/core/locale';
+
+updateLocale('en', {
+    clear: 'Reset',
+    apply: 'Confirm'
+});
+```
+
+If the language does not exist yet, `updateLocale` registers it, behaving like `defineLocale`.
+
+## Reading Messages
+
+### In Components
+
+`useLocale` is the React hook for reading the active locale. It re-renders the calling component when the language changes.
+
+```jsx
+import { Button } from 'primereact/button';
+import { useLocale } from '@primereact/core/locale';
+
+function ClearFilterButton({ onClear }) {
+    const { t } = useLocale();
+
+    return (
+        <Button severity="secondary" onClick={onClear}>
+            {t('clear')}
+        </Button>
+    );
+}
+```
+
+| Field      | Description                                   |
+| ---------- | --------------------------------------------- |
+| `lang`     | Active language code, such as `en` or `de`.   |
+| `messages` | Full message object of the active language.   |
+| `t`        | Translates a key against the active language. |
+
+Re-rendering on a language change relies on the context published by `PrimeReactProvider`, which applications normally have at their root. A component rendered outside any provider still reads the correct messages on first render, but will not update when the language changes later.
+
+### Outside Components
+
+`$t` performs the same lookup without a React context, which suits utilities, event handlers and module-level code.
+
+```js
+import { $t } from '@primereact/core/locale';
+
+$t('clear'); // 'Clear'
+```
+
+Nested keys use dot notation.
+
+```js
+$t('aria.selectRow'); // 'Row Selected'
+```
+
+Messages containing placeholders accept replacement values. Positional placeholders such as `{0}` are filled from the argument order, while named ones are filled from an object.
+
+```js
+$t('searchMessage', 5); // '5 results are available'
+$t('selectionMessage', 3); // '3 items selected'
+$t('aria.stars', { star: 4 }); // '4 stars'
+```
+
+## Reacting to Language Changes
+
+Language changes emit a `locale:change` event. Components handle this automatically through `useLocale`; the event is only needed for code living outside React, such as syncing a third-party library.
+
+```js
+import { LocaleService } from '@primereact/core/locale';
+
+const onChange = ({ lang }) => console.log('Language is now', lang);
+
+LocaleService.on('locale:change', onChange);
+
+// remove the listener when it is no longer needed
+LocaleService.off('locale:change', onChange);
+```
+
+## Inspecting the Registry
+
+`$l` returns a facade over the registry, which helps when building a language switcher.
+
+```js
+import { $l } from '@primereact/core/locale';
+
+$l().langs; // ['en', 'es']
+$l().get('es'); // message object of the Spanish locale
+```
+
+## Message Keys
+
+These components read their labels from the active language:
+
+| Component  | Keys                                                                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DatePicker | `dayNames`, `dayNamesShort`, `dayNamesMin`, `monthNames`, `monthNamesShort`, `today`, `weekHeader`, `clear`, `am`, `pm`, `firstDayOfWeek`, `dateFormat` |
+| FileUpload | `fileSizeTypes`                                                                                                                                         |
+| Paginator  | `aria.firstPageLabel`, `aria.prevPageLabel`, `aria.nextPageLabel`, `aria.lastPageLabel`, `aria.pageLabel`                                               |
+| Sidebar    | `aria.toggleSidebar`                                                                                                                                    |
+
+The registry holds a larger set covering filter operators, password strength labels, empty-state messages and the remaining `aria` labels. Those are reserved for components that do not consume them yet, so translating them has no visible effect today.
+
+Not every entry is a string. `firstDayOfWeek` is a number, `showMonthAfterYear` is a boolean, and `dayNames`, `monthNames` and `fileSizeTypes` are arrays. `searchMessage` and similar entries carry a `{0}` placeholder.
+
+The full set with default English values is exported as `en`, which can also be inspected at runtime:
+
+```js
+import { en } from '@primereact/core/locale';
+
+Object.keys(en); // every top-level key
+```
+
+## Ready-Made Translations
+
+Writing a translation from scratch is rarely necessary. The community maintained [PrimeLocale](https://github.com/primefaces/primelocale) repository publishes complete translations for 70+ languages, shared across all Prime libraries. Each file covers every built-in message key, so nothing is left resolving to `undefined`.
+
+### Copying a File
+
+Grab the JSON file for the desired language from the repository, for example `es.json`, and place it in the project.
+
+Each file wraps its messages in a single key named after the language:
+
+```json
+{
+    "es": {
+        "clear": "Limpiar",
+        "apply": "Aplicar",
+        "aria": { "selectRow": "Seleccionar fila" }
+    }
+}
+```
+
+That wrapper has to be unwrapped before registering, otherwise every lookup resolves to `undefined`:
+
+```js
+import { defineLocale, Locale } from '@primereact/core/locale';
+import es from './locales/es.json';
+
+defineLocale('es', es.es);
+Locale.use('es');
+```
+
+The same unwrapping applies when the language is registered through the provider:
+
+```jsx
+import { PrimeReactProvider } from '@primereact/core';
+import es from './locales/es.json';
+
+<PrimeReactProvider locale="es" locales={{ es: es.es }}>
+    <App />
+</PrimeReactProvider>;
+```
+
+### Installing the Package
+
+The translations are also published to npm, which avoids maintaining copies by hand.
+
+```bash
+npm install primelocale
+```
+
+```js
+import { defineLocale, Locale } from '@primereact/core/locale';
+import { es } from 'primelocale/js/es.js';
+
+defineLocale('es', es);
+Locale.use('es');
+```
+
+The package entry points export the messages directly, so no unwrapping is needed there.
+
+Regional variants are named with an underscore in the package and a hyphen in the JSON files. Brazilian Portuguese is `primelocale/js/pt_BR.js` when imported and `pt-BR.json` when copied.
+
+### Adjusting a Translation
+
+A ready-made translation can be tuned without editing the file, by layering overrides on top of it:
+
+```js
+defineLocale('es', es.es);
+updateLocale('es', { clear: 'Borrar' });
+```
+
+Contributions of new languages and corrections are welcome in the PrimeLocale repository, and benefit every Prime library at once.
+
+## Coming from v10
+
+The locale helpers from `primereact/api` were replaced. The [migration guide](/docs/primitive/guides/migration/updating-to-v11) maps each one to its replacement.

package/data/llms/styled/add-ons/designer/ci.md

@@ -0,0 +1,273 @@
+# Figma to Theme Code CI Pipeline
+
+Automate the conversion of Figma design tokens to theme code using CI pipelines and the theme designer API.
+
+> **UI Kit v4 Users:** You may ignore this documentation and use the [PrimeUI Theme Generator](https://www.figma.com/community/plugin/1592914021886732603/primeui-theme-generator) Figma plugin instead, which provides built-in synchronization capabilities that automate the theme generation process.
+>
+> **UI Kit v3 Users:** Follow the CI pipeline configuration below to integrate with Figma via the Tokens Studio plugin.
+
+## Overview
+
+The Figma UI Kit and the theming api is fully synchronized, meaning the design tokens in Figma map to the corresponding properties in a theme preset. The Theme Designer offers a feature to create a theme by uploading a tokens.json file that is exported from the Tokens Studio plugin in Figma. Once the theme is converted, it can either be edited further in the visual editor or downloaded as a zip file to access the full code. Visit the [Figma](/docs/styled/add-ons/designer/guide#figma) section at the designer documentation for more information.
+
+Manually exporting the tokens file from Figma and uploading it to the online designer tool may quickly become tedious in active development cycles. As a solution, theme designer provides a remote API that can be integrated into your CI pipeline.
+
+![Theme Designer CI](https://fqjltiegiezfetthbags.supabase.co/storage/v1/object/public/common.images/designer/themedesigner-ci.jpg)
+
+## Video Tutorial
+
+Before diving into the implementation details, if you would like to understand the final outcome and see how the solution operates, please refer to the [video tutorial](https://www.youtube.com/watch?v=ksNPUrCYcto) for a comprehensive walkthrough and demonstration.
+
+## Designer API
+
+Theme Designer public endpoint is hosted at PrimeUI Store.
+
+```text
+https://primeui.store/api/designer/integration/theme/create
+```
+
+### Get a Secret Key
+
+1. Visit the [PrimeUI Store](https://primeui.store/designer).
+2. Purchase an Extended License of Theme Designer.
+3. Navigate to your [account settings](https://primeui.store/user/designer).
+4. Generate a secret key for CI/CD integration.
+
+### Authentication
+
+Define an _Authorization: Bearer_ request header to configure your secret key.
+
+### Parameters
+
+The request type must be _POST_.
+
+| Name                 | Type   | Required | Description                                                                         |
+| -------------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
+| `name`               | string | yes      | Name of the theme to be generated.                                                  |
+| `tokens`             | json   | yes      | Content of the json file exported from Figma.                                       |
+| `project`            | string | yes      | Name of the project, possible values are "primereact", "primeng" or "primevue".     |
+| `config.font_size`   | string | no       | Font size for theme preview in visual editor at website, defaults to "14px".        |
+| `config.font_family` | string | no       | Font family for theme preview in visual editor at website, defaults to "Inter Var". |
+
+### Example
+
+```ts
+const response = await fetch('https://primeui.store/api/designer/integration/theme/create', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, application/zip',
+        Authorization: `Bearer ${designer_secret_key}`
+    },
+    body: JSON.stringify({
+        name: 'acme-theme',
+        project: 'primereact',
+        tokens: tokensJson // JSON data
+    })
+});
+```
+
+### Response
+
+A successful response returns a zip file containing the source code of the generated theme preset. The content-type header of this type of response is _application/zip_.
+
+### Error Handling
+
+When theme generation fails, a json response is returned with _application/json_ content-type header. The response contains an error object with _code_ and _message_.
+
+```json
+{
+    "error": {
+        "code": "download_failed",
+        "message": "Failed to create archive."
+    }
+}
+```
+
+## Figma
+
+Tokens Studio in Figma is the starting point of a continuous integration pipeline. You can connect a remote repository to sync your tokens data so that changes are saved remotely instead of locally. Tokens Studio offers various remote storage options such as [GitHub](https://docs.tokens.studio/token-storage/remote/sync-git-github), [GitLab](https://docs.tokens.studio/token-storage/remote/sync-git-gitlab) and [Bitbucket](https://docs.tokens.studio/token-storage/remote/sync-git-bitbucket). Refer to these documentations based on your environment before proceeding to the integrations in the next section.
+
+## Integration
+
+Once the Tokens Studio Sync Provider is running and you have obtained a Secret Key for the Designer API, you can connect your repository to the Theme Designer API to automatically generate themes whenever the tokens file changes via your CI pipeline. For GitHub, PrimeTek provides an official GitHub Action available on the GitHub Marketplace, while for GitLab and Bitbucket, sample implementations are provided as references for building your own integration.
+
+### GitHub
+
+The [prime-figma-to-theme-code-generator](https://github.com/marketplace/actions/prime-figma-to-theme-code-generator) is a GitHub Action that is available on the marketplace.
+
+#### 1. Add Secret Key to Repository Secrets
+
+- Go to your GitHub repository.
+- Navigate to **Settings > Secrets and variables > Actions**.
+- Click **New repository secret**.
+- Give a name such as: _THEME_DESIGNER_SECRET_KEY_.
+- Value: Your API key from Prime Theme Designer.
+- Click **Add secret**.
+
+#### 2. Add the action to your `.github/workflows`
+
+Visit the [inputs](https://github.com/marketplace/actions/prime-figma-to-theme-code-generator#-inputs) documentation for more details about the parameters such as the _theme-name_.
+
+```yaml
+name: Automated Figma To Theme Code
+
+on:
+    push:
+        paths:
+            - 'tokens.json'
+
+permissions:
+    contents: write
+
+jobs:
+    generate-tokens:
+        name: Generate Theme Code
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v3
+
+            - name: Generate Prime Theme
+              uses: primefaces/theme-designer-ci@1.0.0-beta.4
+              with:
+                  designer-secret: ${{ secrets.THEME_DESIGNER_SECRET_KEY }}
+                  theme-name: 'acme'
+                  project: 'primereact'
+                  font-size: '14px'
+                  font-family: 'Inter Var'
+                  tokens-path: 'tokens.json'
+                  output-dir: './acme-theme'
+```
+
+#### 3. Test Integration
+
+Edit a token in Tokens Studio in Figma and click **Push to GitHub** button to update the tokens file in your Git repository, triggering the configured GitHub Action. The GitHub Action then sends the updated file content to the Theme Designer API, receives the generated theme code, and commits the resulting changes back to your repository. An [example repository](https://github.com/primefaces/theme-designer-ci-test) is available at GitHub that you may use as a starter.
+
+### GitLab
+
+The GitLab integration is implemented by executing a script whenever the tokens file changes.
+
+#### 1. Add Secret Key to Repository Secrets
+
+- Go to your GitLab repository.
+- Navigate to **Settings > CI/CD > Variables**.
+- Click **Add variable**.
+- Give a name such as: _THEME_DESIGNER_SECRET_KEY_.
+- Value: Your API key from Prime Theme Designer.
+- Click **Add variable**.
+
+#### 2. Add the script to your project
+
+A sample script named [figma-to-theme-converter.sh](https://gitlab.com/cagataycivici/theme-designer-ci-test/-/blob/main/figma-to-theme-converter.sh?ref_type=heads) is available as a starter, copy and paste this script to your project. You may alter the script further per your requirements.
+
+#### 3. Add the script to your `.gitlab-ci.yml`
+
+Define the configuration parameters for the Designer API and add the script to the action.
+
+```yaml
+variables:
+    # Set these as GitLab CI/CD variables for security
+    DESIGNER_SECRET: ${THEME_DESIGNER_SECRET_KEY}
+    THEME_NAME: 'my-custom-theme'
+    PROJECT: 'primereact' # or your target project
+    TOKENS_PATH: './tokens.json'
+    OUTPUT_DIR: './my-custom-theme'
+    # Optional configuration
+    FONT_SIZE: '14px'
+    FONT_FAMILY: 'Inter'
+
+stages:
+    - generate-theme
+
+generate_theme_tokens:
+    stage: generate-theme
+    image: ubuntu:22.04
+
+    before_script:
+        # Install required dependencies
+        - apt-get update -qq
+        - apt-get install -y -qq git curl python3 unzip
+        - git config --global --add safe.directory $CI_PROJECT_DIR
+        # Ensure we're on the correct branch and have latest changes
+        - git fetch origin
+        - git checkout $CI_COMMIT_REF_NAME
+        - git pull origin $CI_COMMIT_REF_NAME || true
+
+    script:
+        # Run the theme generator script
+        - ./figma-to-theme-converter.sh
+
+    artifacts:
+        paths:
+            - $OUTPUT_DIR/
+        expire_in: 1 week
+
+    rules:
+        # Run on main branch when tokens.json is modified
+        - if: $CI_COMMIT_BRANCH == "main"
+          changes:
+              - tokens.json
+        # Or run manually
+        - when: manual
+```
+
+#### 4. Test Integration
+
+Edit a token in Tokens Studio in Figma and click **Push to GitLab** button to update the tokens file in your Git repository, triggering the configured GitLab Action. The GitLab Action then sends the updated file content to the Theme Designer API, receives the generated theme code, and commits the resulting changes back to your repository. An [example repository](https://gitlab.com/cagataycivici/theme-designer-ci-test) is available at GitLab that you may use as a starter.
+
+### Bitbucket
+
+The BitBucket integration is implemented by executing a custom pipe whenever the tokens file changes.
+
+#### 1. Add Secret Key to Repository Secrets
+
+- Go to your BitBucket repository.
+- Navigate to **Repository Settings > Repository Variables**.
+- Give a name such as: _THEME_DESIGNER_SECRET_KEY_.
+- Value: Your API key from Prime Theme Designer.
+- Click **Add**.
+
+#### 2. Add the pipe configuration to your `bitbucket-pipelines.yml`
+
+Define the configuration parameters for the Designer API and add the pipe as a runnable script to the action. Notice that, the referenced [pipe](https://bitbucket.org/cagataycivici/figma-to-theme-code-generator/src/main/) is executed as a script rather than a pipe from the BitBucket pipe registry as PrimeTek currently has no intentions to maintain an official pipe for BitBucket. You may further improve this example by building a dockerized pipe that is accessible in the BitBucket Registry to refer it with the _pipe_ config in yml.
+
+```yaml
+image: atlassian/default-image:4
+
+pipelines:
+    default:
+        - step:
+              name: Generate Theme with Theme Designer
+              condition:
+                  changesets:
+                      includePaths:
+                          - 'tokens.json'
+              script:
+                  - apt-get update && apt-get install -y jq curl unzip
+                  - git clone https://bitbucket.org/cagataycivici/figma-to-theme-code-generator.git temp-pipe
+                  - cp temp-pipe/pipe.sh ./
+                  - chmod +x pipe.sh
+                  - export DESIGNER_SECRET="${THEME_DESIGNER_SECRET_KEY}"
+                  - export THEME_NAME="acme-theme"
+                  - export PROJECT="primereact"
+                  - export FONT_SIZE="14px"
+                  - export FONT_FAMILY="Inter Var"
+                  - export TOKENS_PATH="./tokens.json"
+                  - export OUTPUT_DIR="./acme-theme"
+                  - ./pipe.sh
+```
+
+#### 3. Test Integration
+
+Edit a token in Tokens Studio in Figma and click **Push to BitBucket** button to update the tokens file in your Git repository, triggering the configured BitBucket Pipe. The pipe then sends the updated file content to the Theme Designer API, receives the generated theme code, and commits the resulting changes back to your repository. An [example repository](https://bitbucket.org/cagataycivici/theme-designer-ci-test) is available at BitBucket that you may use as a starter.
+
+## Live Preview
+
+After your CI pipeline completes successfully, your theme also becomes available in the Prime UI Theme Designer.
+
+- Navigate to the Prime UI library website.
+- Click the ⚙️ icon at topbar to open up Designer Editor.
+- Sign in with your license key and pass key credentials.
+- Then select your theme from the available options to apply it across all demos and website content.
+- Note that CI-generated themes are provided in read-only mode for preview purposes only and cannot be edited within the Theme Designer. The Migration Assistant is available to identify any missing tokens in your preset; however, if tokens are missing, they must be added manually in Figma as needed.

package/data/llms/styled/add-ons/designer/guide.md

@@ -0,0 +1,99 @@
+# Designer
+
+Theme Designer is the ultimate tool to customize and design your own themes featuring a visual editor, Figma to theme code, cloud storage, and migration assistant.
+
+## Overview
+
+The [theming api](/docs/styled/guides/theming/styled) is open source and freely available with an extensive documentation. Theme Designer is a tool built on top of this theming api with important features to make theming easier. Designer consists of 4 key features; the **visual editor** provides a UI to edit the complete set of tokens. The **Figma to theme code** generator is extremely useful to automate the design to code process and integrates seamlessly with the Figma UI Kit. The themes are saved in the **cloud storage** to be accessible from anywhere and any device and finally the **migration assistant** automatically updates your themes to the latest library version.
+
+## License
+
+A license key is required to be able to use all the services provided by the designer. Without a license, the visual editor is still available for trial purposes with various options such as downloads, and cloud storage disabled. The license key can be purchased at [PrimeStore](https://primeui.store/designer), it is valid for 1 year and needs to be renewed manually after a year.
+
+## Dashboard
+
+Dashboard is the entry point of the designer. The license key can be configured at this view before getting started with the full set of features. In the **My Themes** section, you're able to create a theme, and manage existing themes. A theme can be renamed, duplicated and downloaded using the more options (⋯) button.
+
+![Designer Dashboard](https://fqjltiegiezfetthbags.supabase.co/storage/v1/object/public/common.images/designer/guide-dashboard.png)
+
+## Create Theme
+
+A theme can be initiated from one of the built-in themes or from Figma UI Kit.
+
+### Base
+
+In the new theme section, all of the built-in themes are available to use as the base. These are; _Aura_, _Material_, _Lara_ and _Nora_. Each have their own characteristics, and it is recommended to choose the one that best suits your requirements.
+
+### Figma
+
+For teams with UI designers, we recommend using PrimeOne Figma UI Kit for the design phase and utilizing the Theme Designer service to automate code generation during handoff. This workflow eliminates manual design-to-code translation, reducing implementation time and ensuring consistency between design and production.
+
+#### UI Kit v4
+
+**Automated Flow**
+
+Recommended approach is using the PrimeUI Theme Generator Figma plugin which provides built-in synchronization capabilities that automate the theme generation process. Visit [the plugin website](https://www.figma.com/community/plugin/1592914021886732603/primeui-theme-generator) to learn more about this workflow.
+
+**Manual Flow**
+
+Instead of generating themes directly from Figma using the plugin, for quick prototyping purposes, you may also choose to manually export a tokens json file and then upload it to the Theme Designer. Note that, this flow would get tedious and repetitive in active development cycles when compared to an automated flow.
+
+Open the [PrimeOne UI Kit](/docs/styled/add-ons/uikit/overview) in which you've modified tokens. In the PrimeUI Theme Generator plugin, click the _Export_ option to export all variable collections.
+
+![Figma Plugin Export](https://fqjltiegiezfetthbags.supabase.co/storage/v1/object/public/common.images/designer/figma-plugin.png)
+
+When creating a new theme at Theme Designer, choose the _Import Figma Variables_ option and import the json file.
+
+![Create Theme from Figma](https://fqjltiegiezfetthbags.supabase.co/storage/v1/object/public/common.images/designer/guide-create.png)
+
+#### UI Kit v3 (Deprecated)
+
+**CI Pipeline**
+
+Recommended approach is setting up the CI Pipeline flow as manually exporting the tokens file from Figma and uploading it to the online designer tool may quickly become tedious in active development cycles. As a solution, theme designer provides a remote API that can be integrated into your flow. Visit the [CI Pipeline](/docs/styled/add-ons/designer/ci) documentation for comprehensive information and examples for GitHub, GitLab and BitBucket.
+
+**Manual Flow**
+
+Instead of setting a CI pipeline, for quick prototyping purposes, you may also choose to manually export a tokens json file and then upload it to the designer. Note that, this flow would get tedious and repetitive in active development cycles when compared to an automated CI pipeline.
+
+Open the PrimeOne UI Kit in which you've modified tokens. In the Tokens Studio plugin, navigate to the _Tools_ menu and select _Export to file/folder._ When the Export tokens modal appears, make sure the _Single file_ tab is selected. Check the _All tokens sets_ option, then click _Export_.
+
+In case you utilize custom tokens, create a new token set named _custom_ and define your tokens under this set to make sure they are also exported to the theme code.
+
+![Tokens Studio export](https://primefaces.org/cdn/designer/tokens-studio.png)
+
+When creating a new theme at Theme Designer, choose the _Import Figma Variables_ option and import the json file.
+
+## Editor
+
+### Token Collections
+
+The theming architecture is based on primitive, semantic and components tokens. The visual editor, displays a dedicated section for each collection. For basic purposes such as customizing the primary and surface colors, primitive and semantic sections would be more than enough. The component tokens are displayed per route so navigate to the component page first to view the tokens of the specific component.
+
+### Custom Tokens
+
+Custom tokens allow bringing in your own design tokens to the theme to go beyond the built-in ones. A design token requires a name and a value where the value can be a static value like a color or another token. The name of the token should be a dot separated lowercase value e.g. `accent.color`. For example, a custom token name can be defined as `accent.color` and the value can either be a value like `#eab308` or another token such as `{yellow.50}`. Custom tokens can also refer to each other, e.g. `selection.background` custom token can define `{accent.color}` as a value.
+
+If you have created a theme from Figma, use the name **custom** as the name of your token set group. This keyword is special since the import tool will populate the custom tokens using this set in tokens json file.
+
+### Intelligent Completion
+
+The editor is packed with features for improved user experience. The input fields in the editor are capable of displaying a color preview when the value is a color, and beginning the value with a curly brace (`{`) opens up the autocompletion feature to list the available tokens to choose from. The _pi-sort-alt_ symbol over the input, transfers the token between the common tokens and color scheme specific tokens so that you are able to define tokens based on light and dark mode as well.
+
+![Editor Intelligent Completion](https://fqjltiegiezfetthbags.supabase.co/storage/v1/object/public/common.images/designer/guide-editor.png)
+
+### Typography
+
+The components are not opinionated about the typography. Important properties such as the font family, font size, and line-height do not have design tokens since they can be inherited from the document. For preview purposes, the _settings_ tab displays options to customize the base font and the font family of the document. These values are not available in the generated theme and need to be applied to your application at the document level.
+
+## Migration Assistant
+
+Prime UI libraries continue to evolve with each version. New tokens are likely to be added with each major release, in order to keep your themes up to date the migration assistant is available featuring automated migration. The **Check for Updates** option initially scans a theme for any missing tokens. This tool does not override the values of existing tokens, and only adds missing tokens if necessary. Still, it is recommended to duplicate your theme as a backup and run a preview before the migration. Depending on the result, you may choose to proceed with the migration process. In case there are missing tokens, your theme would receive them with placeholder values so it is recommended to take a note of them before migration and then visit the components to replace the placeholder values with actual values of your choice. These types of newly added tokens would be highlighted in Editor.
+
+![Migration Assistant](https://fqjltiegiezfetthbags.supabase.co/storage/v1/object/public/common.images/designer/guide-migration.png)
+
+## Limitations
+
+Current known technical limitations are listed at this section.
+
+- The border width token in Figma does not support multiple values, related [issue](https://github.com/tokens-studio/figma-plugin/issues/3237).