Style guides and rules
get_styleguide_rules
Returns the workspace’s enabled style guide rules. Use them as the reference when writing or reviewing UI copy so it complies with the team’s guidelines. Rules from a locale-scoped style guide are labeled with their locale; apply those only when writing text for that locale. Pass the project developer IDs from the repo’sditto/config.yml as projectIds to scope results to this codebase; see Scope results to your codebase.
What a style guide and a rule are: Style guides and rules. Ditto drafts a first guide from your codebase; see Get a first style guide from your scan.
Every rule comes back with an ID. When you write text that a rule shaped, cite that ID in ruleIds on the tool doing the write — create_text_items, update_text_items, create_library_components, or update_library_components — and Ditto records the rule against the text. ruleIds is set per item, so each item in a batch cites its own rules.
Only writes that change the text itself are attributed: a call that updates just a status, tags, or an assignee records nothing. Rule IDs your workspace doesn’t recognize are named back in the tool’s response rather than dropped silently, so call get_styleguide_rules again for the current IDs if that happens.
suggest_edit
Checks text against your Ditto workspace’s style guide rules and returns suggested edits — the same rule-based suggestions shown in the Ditto app. Check an existing text item by its developer ID, or check freeform text that isn’t saved as a text item yet. Results are cached per exact input; passforceNewGeneration to force a fresh check.
An empty result means the text already complies with the style guide, or that this exact suggestion was already reviewed and dismissed in the app.
list_styleguides
Lists all style guides in the workspace with their developer IDs, descriptions, sections, and rules. Use this to find a style guide’s developer ID and section IDs before callingcreate_styleguide_rules or update_styleguide.
create_styleguide
Create a new style guide (name, description, sections, whether it’s enabled by default). Sections organize rules and word list entries; if omitted, a default set of sections is used. If you provide sections, each section ID must be unique and the list must include at least one rules section and one word list section. Returns the new style guide’s developer ID. PassvariantId to scope the style guide to a single variant — because a locale in Ditto is a variant’s locale code, this is how a style guide is associated with a locale. The variant must have a locale code — for now, style guides can only be scoped to variants that have one.
update_styleguide
Update an existing style guide by developer ID (any field: name, description, enabled by default, variant, sections). Only the fields you provide are changed. Pass developer IDdefault to toggle the built-in Ditto Style Guide’s enabled-by-default setting.
Pass variantId to scope the style guide to a single variant — because a locale in Ditto is a variant’s locale code, this is how a style guide is associated with a locale — or null to unscope it so it applies to all text. The variant must have a locale code — for now, style guides can only be scoped to variants that have one.
Updating sections replaces the full list — each section ID must be unique, and the list must include at least one rules section and one word list section — rules in a removed section move automatically to the first remaining rules section.
create_styleguide_rules
Create one or more rules in a style guide section. Use the{name, description, examples, tags, enabled} shape for a ‘rules’ section, or the {term, disallowed, description, tags, enabled} shape for a ‘wordlist’ section — the shape must match the target section’s kind. Find the style guide’s developer ID and section IDs with list_styleguides; only tags returned by get_workspace_tags can be used.
Batch calls are all-or-nothing: if any rule fails, none are created.
update_styleguide_rules
Update one or more existing rules by ID (fromget_styleguide_rules or create_styleguide_rules). Only the fields you provide are changed. Use name/examples for a rule in a ‘rules’ section, or term/disallowed for a rule in a ‘wordlist’ section — the shape must match that rule’s own section.
Batch calls are all-or-nothing: if any update fails, none are applied.
delete_styleguide_rules
Permanently delete one or more rules by ID. This cannot be undone. Batch calls are all-or-nothing: if any rule ID doesn’t exist, none are deleted.Text items
search_ditto_text
Searches existing text items and/or library components by content and filters (status, tags, assignee, notes). Use it after drafting candidate text for UI to find existing text that could be reused instead of writing new copy: an exact or near-exact match means reuse the existing item by its developer ID; a partial match is worth reusing if the wording still fits.- Reads
ditto/config.ymlproject IDs the same way asget_styleguide_rules. - Searches the base language by default; pass
variants(variant developer IDs, optionally includingbase) to search translations. Uselist_variantsto look up IDs. - Pass several entries in
queriesto run independent searches in one call. Each query succeeds or fails on its own and returns its ownresults, with anerrorstring instead of failing the whole call. - Results are paged per query: when more exist, the entry includes a
cursorto pass back in a later call. - Results are trimmed to a default set of fields to keep responses small; request more with the
fieldsparameter. Requestingfigmaadds the Figma text node IDs linked to each text item, both in the project’s main Figma file and grouped by branch — useful for checking what a text item is already connected to before callinglink_figma_nodes_to_text_item.
create_text_items
Creates new text items in a project. Provide the project’s developer ID and the items to add. Each item supports text, an optional developer ID, status, tags, assignee (by email), notes, a character limit, a development-integration flag, and plural forms. Usesearch_ditto_text first to check whether equivalent text already exists to reuse.
Set ruleIds on an item to record the style guide rules you applied to its text — see get_styleguide_rules. Variant text set at creation time is attributed alongside the base text.
Batch calls are all-or-nothing: if any item in the call fails (e.g. a duplicate developer ID), none of the items are created.
update_text_items
Updates existing text items by their developer IDs. Only the fields you provide are changed; the rest are left as-is. Supports text, status, tags, assignee, notes, character limit, the development-integration flag, and plural updates. Tags are replaced wholesale — pass the full desired set. SetruleIds on an update to record the style guide rules you applied to its text — see get_styleguide_rules. The call-wide variantId decides which text the rules are recorded against, so a variant update is attributed to that variant rather than to the base text.
Batch calls are all-or-nothing: if any update in the call fails, none of the updates are applied.
translate_text_items
Translates project text items into a variant’s locale and saves each translation as that variant’s text. Provide the project’s developer ID, the variant’s developer ID (fromlist_variants), and the developer IDs of the text items to translate. The variant must have a locale code, which is targeted for translation. Rules from style guides scoped to that locale are applied.
The source is each item’s base text. Existing variant text is replaced; items that don’t have the variant yet attach it, reported as variantAttached. If the variant has plural forms, the first one is updated too. Library text item instances can’t be translated here — use translate_library_components on their component instead.
Up to 100 text items per call.
delete_text_items
Permanently deletes text items by their developer IDs. This cannot be undone, and text items that are library instances cannot be deleted.link_figma_nodes_to_text_item
Links one or more already-synced Figma text nodes to an existing Ditto text item. Usesearch_ditto_text first to find the target text item’s developer ID and pass it as textItemId; projectId is the developer ID of the Ditto project connected to the Figma file. Pass up to 50 node IDs per call in figma.nodeIds, and figma.branchId (from the branch file’s Figma URL) to link nodes in a Figma branch instead of the main file.
The tool only links nodes the Ditto Figma plugin has already synced. It returns one result per node with an outcome of linked, already_linked, not_found (sync the file or page in the plugin, then retry), not_text_node, wrong_file_or_branch, or main_component_text_node. Walkthrough: Connect Figma files.
Library components
create_library_components
Creates new components in the Ditto component library. Library components are reusable text shared across projects, as opposed to project-scoped text items. Each component supports a name, text, an optional developer ID, folder, status, tags, assignee (by email), notes, a character limit, a development-integration flag, and plural forms. Usesearch_ditto_text first to check whether equivalent text already exists to reuse.
Set ruleIds on a component to record the style guide rules you applied to its text — see get_styleguide_rules. Variant text set at creation time is attributed alongside the base text.
Batch calls are all-or-nothing: if any component in the call fails (e.g. a duplicate developer ID), none of the components are created.
update_library_components
Updates existing library components by their developer IDs. Only the fields you provide are changed; the rest are left as-is. Supports text, folder, status, tags, assignee, notes, character limit, the development-integration flag, and plural updates. Tags are replaced wholesale — pass the full desired set. SetruleIds on an update to record the style guide rules you applied to its text — see get_styleguide_rules. The call-wide variantId decides which text the rules are recorded against, so a variant update is attributed to that variant rather than to the base text.
Batch calls are all-or-nothing: if any update in the call fails, none of the updates are applied. Each component can appear only once per call — a repeated developer ID is rejected.
translate_library_components
Translates library components into a variant’s locale and saves each translation as that variant’s text on the component. Provide the variant’s developer ID (fromlist_variants) and the developer IDs of the components to translate. The variant must have a locale code, which is targeted for translation. Rules from style guides scoped to that locale are applied.
The source is each component’s base text. Existing variant text is replaced; components that don’t have the variant yet attach it, reported as variantAttached. If the variant has plural forms, the first one is updated too. The translation edit is propagated to text item instances of the component.
Up to 100 components per call.
publish_library_component
Publishes an existing project text item to the Ditto component library, turning it into a reusable library component. The text item’s current text, variables, variants, and other fields are carried over to the new component, and the text item becomes its first linked instance. The new component keeps the text item’s existing developer ID, and any text item later linked to it takes on that same developer ID, so one developer ID can end up shared across the component and every text item linked to it. The text item must not already be a library instance — uselink_text_items_to_component to attach additional items to an existing component instead. Pass folderId (from list_component_folders) to file the component in a folder; otherwise it lands at the library root.
link_text_items_to_component
Links one or more existing project text items to an existing library component by developer ID, so they share the component’s text going forward. Each linked text item takes on the component’s current text, variables, variants, and other fields, including its developer ID: the text item’s own developer ID is replaced by the component’s, so it can no longer be looked up by the old one. Text items already linked to a different component are skipped. Use this after a scan to attach design or project text to the library components created from your codebase; see Connect Figma files.unlink_text_items_from_component
Unlinks one or more text items from their library component by developer ID, turning them back into standalone project text items with a freshly generated developer ID each. The text items keep their current text; future edits to the library component no longer affect them. Every text item linked to the same component shares that component’s developer ID with its sibling instances, so a given developer ID unlinks every text item that currently carries it, not just one. PassprojectId to scope the unlink to only the instances in one project, leaving instances elsewhere untouched.
Component folders
list_component_folders
Lists all folders in your component library with their names, developer IDs, and parent folder (by developer ID; no parent means the folder sits directly under the library root). Use this to find a folder’s developer ID before filing a component into it withcreate_library_components or update_library_components, or before managing the folders themselves with create_component_folders, update_component_folders, and delete_component_folders. Folders are a separate namespace from projects — list_projects will not surface them.
create_component_folders
Creates new folders in the component library. Each folder can optionally specify a developer ID (must be unique in the workspace) and a parent folder to nest inside — omit the parent to create the folder at the library root. Batch calls are all-or-nothing: if any folder in the call fails (e.g. a duplicate developer ID), none of the folders are created.update_component_folders
Updates existing folders by their developer IDs. Only the fields you provide are changed. SetparentId to move a folder — provide null or "root" to move it to the library root, or omit to leave it in place.
To rename a folder’s developer ID, set newDeveloperId.
Batch calls are all-or-nothing: if any update in the call fails (e.g. a duplicate developer ID, or a move that would create a circular hierarchy), none of the updates are applied.
delete_component_folders
Permanently deletes folders from the component library by their developer IDs. This cannot be undone. Components and subfolders inside a deleted folder are not deleted — they’re moved up into the deleted folder’s parent folder (or the library root).Projects
list_projects
Lists all projects in your workspace with their names and developer IDs. Use this to find a project’s developer ID when you only know its name — for example, before creating, updating, or searching text items.list_project_folders
Lists all project folders in the workspace with their developer IDs, names, and parent folder (by developer ID; no parent means the folder sits directly under the workspace root). Use this to find a folder’s developer ID beforecreate_ditto_project, which takes a folderId to create the project inside a folder. Folders are a separate namespace from projects — list_projects will not surface them.
create_ditto_project
Creates a new project in the workspace. Projects hold project-scoped text items, as opposed to library components which are reusable across projects. Use the returned developer ID (orlist_projects) to reference it afterward, for example with create_text_items.
Project blocks
list_project_blocks
Lists the blocks in a Ditto project with their developer IDs and names, in display order. Blocks group text items within a project. Use this to find a block’s developer ID beforeupdate_project_blocks or delete_project_blocks.
If you only know the project’s name, call list_projects to look up its developer ID.
create_project_blocks
Creates new blocks in a Ditto project. Blocks group text items within a project. New blocks are appended to the end of the project. Use the returned developer IDs (orlist_project_blocks) to reference them afterward.
update_project_blocks
Updates existing blocks in a Ditto project by their developer IDs (find them withlist_project_blocks). Only the fields you provide are changed. To rename a block’s developer ID, set newDeveloperId — it can be combined with a name change in the same update object.
Batch calls are all-or-nothing: if any update fails (e.g. a duplicate developer ID within the project), none of the updates in the call are applied.
delete_project_blocks
Permanently deletes blocks from a Ditto project by their developer IDs (find them withlist_project_blocks). This cannot be undone. Text items in a deleted block are not deleted — they’re unassigned and moved to the end of the project’s root level.
Variables
list_variables
Lists all variables in the workspace with their developer IDs, types, and data. Use this to find a variable’s developer ID (its name) before referencing it increate_text_items or update_text_items — list the id in the variables field and reference it as a {{variable_name}} placeholder in the text.
create_variables
Creates variables in the workspace. A variable is a reusable placeholder that resolves to a different value at runtime. Each has a type that determines what it holds: astring or number variable holds an example and an optional fallback, a hyperlink holds link text and a url, a list holds the set of values the variable can take, and a map holds key-value pairs.
A variable’s name doubles as its developer ID: letters, numbers, and underscores only, and unique in the workspace. Creating a variable adds it to no text on its own — reference it from create_text_items or update_text_items by listing it in the variables field and writing it as a {{variable_name}} placeholder in the text.
Batch calls are all-or-nothing: if any variable in the call fails (for example, a name already in use), none of them are created.
update_variables
Renames variables or changes their type or value. Because a variable’s name is its developer ID, renaming one withnewName changes how it is referenced — but nothing inside Ditto is orphaned, because every {{placeholder}} using it is rewritten to match, across text items, library components, variant text, and plurals.
What breaks is outside Ditto: anything naming the old id, such as code, an integration config, or CLI output, along with later API and MCP calls. Use list_variables to find a variable’s current developer ID.
Only the fields you provide are changed, and each update must change at least one of newName, type, or data. Changing a type requires sending data alongside it, even when the value itself stays the same. How data is applied depends on the type: string, number, and hyperlink variables have fixed fields, so sending only some of them leaves the rest alone — send an empty string to clear one.
A list’s value is an array and a map’s is an object, and each is the variable’s entire content, so what you send replaces it outright.
Batch calls are all-or-nothing: if any update in the call is invalid, none of the updates are applied.
delete_variables
Permanently deletes variables from the workspace by their developer IDs (their names). This cannot be undone. A variable cannot be deleted while any text item or library component still references it, and one such variable rejects the whole batch — remove the{{placeholder}} from that text first, then retry.
Confirm the developer IDs with the user before calling.
Variants
list_variants
Lists all variants in the workspace with their developer IDs, names, descriptions, and locale codes. Use this to find a variant’s developer ID when you only know its name — for example, beforecreate_text_items or update_text_items, which take variant developer IDs to set variant-specific text. When translating text for a variant, treat its localeCode (e.g. es, fr-ca) as the authoritative target locale — do not infer the locale from the variant’s name or description.
If a variant’s localeCode is null, it is not locale-scoped; confirm the intended locale with the user rather than guessing.
create_variants
Creates variants in the workspace. A variant is a named alternative that text items and library components can each have their own text for — most often a locale to translate into, but also a tone or brand variation. Creating a variant adds no text on its own: usecreate_text_items or update_text_items with the variant’s developer ID to set a text item’s text for that variant.
Set localeCode whenever the variant represents a language, because translation tools treat it as the authoritative target locale rather than inferring one from the name; at most one variant per workspace can hold a given locale code. A developer ID is generated from the name unless you pass one explicitly, so read the developer IDs off the response rather than assuming them.
update_variants
Renames variants or changes their description, locale code, or developer ID. A variant’s name and its developer ID are independent. The name is the human-readable label shown in Ditto; the developer ID is the stable key that code, integrations, and CLI output use to refer to the variant. Renaming a variant leaves its developer ID untouched, so anything already referencing it keeps resolving — set newDeveloperId only when you want that key itself to change. Nothing inside Ditto is orphaned or rewritten by either change: text items and library components reference a variant by an internal id rather than its developer ID, so each keeps its text for the variant, and variant-scoped style guides stay attached. What breaks is outside Ditto — anything naming the old developer ID, such as CLI output, an integration config, or code, along with later API and MCP calls, which have to use the new one. Uselist_variants to find a variant’s current developer ID. At most one variant per workspace can hold a given locale code.
Changing a locale code reaches past the variant itself: variant-scoped style guides and AI translation targeting both resolve a locale to a variant, so moving a locale onto a different variant changes which style guide governs that locale’s text and where translated text is suggested. The whole batch is rejected if any update is invalid.