Skip to content

Update docs for twelve-ui changes #628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
formfcw wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update docs for twelve-ui changes #628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2742d5d
update private-view slots and theme example for twelve-ui changes
formfcw Apr 13, 2026
2488e71
correct deprecated slot table; document new actions:primary; add them…
formfcw May 13, 2026
8f0011b
Document visual-editor customization vars for editable-element redesi…
formfcw May 15, 2026
14b130d
Revert visual-editor overlay defaults: border-width 2px, hover/highli…
formfcw May 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions content/getting-started/10.accessibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,6 @@ Read more: https://www.tiny.cloud/docs/tinymce/6/tinymce-and-screenreaders/

### Things to keep in mind

- Visual Editor is only accessible on the Directus side — not your website. So we always need to click an edit button first, then the
overlays are accessible.
- Manual Sorting is currently not supported/accessible.
- Once focused, the code interface (Codemirror) cannot be exited using the tab key.
- The Markdown interface also doesn’t allow you to exit the field. This is because it supports tabs inside the editor’s
Expand Down
23 changes: 19 additions & 4 deletions content/guides/02.content/8.visual-editor/3.customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ The library ships with a number of built in CSS Selectors already applied to its
.directus-visual-editing-edit-button {
/* the edit button */
}
.directus-visual-editing-actions-flipped {
/* a modifier on the rect that flips the action buttons below it, applied automatically when the rect is near the top of the viewport */
}
```

## CSS Variables
Expand All @@ -48,21 +51,33 @@ The library also ships with a number of predefined CSS variables. These can be o
```css
:root {
--directus-visual-editing--overlay--z-index: 999999999;
--directus-visual-editing--rect--border-spacing: 9px;
--directus-visual-editing--rect--border-spacing: 8px;
--directus-visual-editing--rect--border-width: 2px;
--directus-visual-editing--rect--border-color: #6644ff;
--directus-visual-editing--rect--border-radius: 6px;
--directus-visual-editing--rect-hover--opacity: 0.333;
--directus-visual-editing--rect-highlight--opacity: 0.333;
--directus-visual-editing--edit-btn--width: 28px;
--directus-visual-editing--edit-btn--height: 28px;
--directus-visual-editing--edit-btn--radius: 50%;
--directus-visual-editing--actions--offset: 4px;
--directus-visual-editing--actions--focus-ring-color: #6644ff;
--directus-visual-editing--actions--focus-ring-width: 2px;
--directus-visual-editing--actions--focus-ring-offset: 2px;
--directus-visual-editing--edit-btn--width: 24px;
--directus-visual-editing--edit-btn--height: 24px;
--directus-visual-editing--edit-btn--radius: 6px;
--directus-visual-editing--edit-btn--bg-color: #6644ff;
--directus-visual-editing--edit-btn-hover--bg-color: color-mix(in srgb, #6644ff, #2e3C43 25%);
--directus-visual-editing--edit-btn--icon-bg-image: url('data:image/svg+xml,<svg>…</svg>');
--directus-visual-editing--edit-btn--icon-bg-size: 66.6%;
--directus-visual-editing--ai-btn--bg-color: #6644ff;
--directus-visual-editing--ai-btn-hover--bg-color: color-mix(in srgb, #6644ff, #2e3C43 25%);
}
```

::callout{icon="material-symbols:info-outline"}
**Defaults inside the Directus Studio**
When the visual editor runs inside the Directus Studio iframe, defaults for several variables are sourced from the active Studio theme (primary color, border radius, button size, focus-ring width/offset) rather than the compiled-in fallbacks shown above. Your own `:root` or `customClass` overrides still take precedence.
::

## Custom Classes

Finally, custom classes can be added to all or a subset of elements defined by the library’s [apply method](/guides/content/visual-editor/frontend-library#api) using the `customClass` property. This class will be applied to the `div.directus-visual-editing-overlay` element within the `div#directus-visual-editing` container.
Expand Down
55 changes: 30 additions & 25 deletions content/guides/09.extensions/3.app-extensions/5.modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,19 +23,19 @@ The `index.js` or `index.ts` file exports an object that is read by Directus. It
## Entrypoint Example

```js
import { defineInterface } from '@directus/extensions-sdk'
import ModuleComponent from './module.vue';
import { defineInterface } from "@directus/extensions-sdk";
import ModuleComponent from "./module.vue";

export default defineInterface({
id: 'custom',
name: 'Custom',
icon: 'box',
routes: [
{
path: '',
component: ModuleComponent,
},
],
id: "custom",
name: "Custom",
icon: "box",
routes: [
{
path: "",
component: ModuleComponent,
},
],
});
```

Expand All @@ -62,7 +62,6 @@ The route object uses the same syntax as Vue Router, defining each route as an o
| `path` | The route path without the leading slash. |
| `component` | A Vue component to be rendered for this route. |


The `routes` array should contain a root route with an empty path, which will load at the module's base route (the value of the module's `id`). Dynamic portions of the path can be defined using the `:param` syntax.

### Route Component
Expand All @@ -71,7 +70,7 @@ The module route component will be rendered in the Data Studio when the route is

```vue
<template>
<private-view title="My Custom Module">Content goes here...</private-view>
<private-view title="My Custom Module">Content goes here...</private-view>
</template>

<script>
Expand All @@ -82,17 +81,23 @@ export default {};
You can use the globally-registered `private-view` component to get access to Directus' page structure consisting of the module bar, navigation,
sidebar, header, and the main content area. Named slots can be used to add additional content to these areas.

| Slot | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `navigation` | Adds content to the navigation area of the Directus interface. |
| `title-outer:prepend` | Inserts content before the outer title container in the Directus header. |
| `headline` | Displays a headline above the main title in the Directus header. |
| `title` | Sets the main title in the Directus header. If not used, `title:prepend` and `title:append` can be used instead. |
| `title-outer:append` | Inserts content after the outer title container in the Directus header. |
| `actions:prepend` | Adds content before the action buttons in the Directus header. |
| `actions` | Defines the main action buttons in the Directus header. |
| `actions:append` | Adds content after the action buttons in the Directus header. |
| `splitView` | Renders content in the split view area (only if the private layout has the split-view prop set to true). |
| `sidebar` | Populates the sidebar area in the Directus interface. |
| Slot | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `navigation` | Adds content to the navigation area of the Directus interface. |
| `title-outer:prepend` | Inserts content before the outer title container in the Directus header. |
| `title-outer:append` | Inserts content after the outer title container in the Directus header. |
| `title` | Sets the main title in the Directus header. If not used, `title:prepend` and `title:append` can be used instead. |
| `actions:prepend` | Adds content before the action buttons in the Directus header. |
| `actions` | Defines secondary action buttons in the Directus header. |
| `actions:primary` | Defines the primary action button (CTA) in the Directus header. |
| `sidebar` | Populates the sidebar area in the Directus interface. |
| `splitView` | Renders content in the split view area (only if the private layout has the split-view prop set to true). |
| `headline` _(deprecated)_ | Previously rendered a headline above the title. Existing content now renders prepended to the title. |
| `actions:append` _(deprecated)_ | Previously added content after the action buttons. Existing content now renders in the secondary actions zone alongside the `actions` slot. Use `actions:primary` for primary CTAs. |

::callout{icon="material-symbols:info-outline"}
**Primary vs. secondary actions**
Use `actions:primary` for the page's main call to action — it renders with a labeled, prominent button. Use `actions` for secondary, icon-style action buttons.
::

:partial{content="extensions-app-internals"}
46 changes: 30 additions & 16 deletions content/guides/09.extensions/3.app-extensions/6.themes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,39 +14,53 @@ The `index.js` or `index.ts` file exports an object that is read by Directus. It
### Entrypoint Example

```js
import { defineTheme } from '@directus/extensions-sdk';
import { defineTheme } from "@directus/extensions-sdk";

export default defineTheme({
id: 'custom',
name: 'My Custom Theme',
appearance: 'dark',
rules: {
background: 'tomato',
}
id: "custom",
name: "My Custom Theme",
appearance: "dark",
rules: {
background: "tomato",
},
});
```

### Properties

| Property | Type | Description |
|-------------|--------|--------------------------------------------------------------------------------------------------------------------|
| `id` | string | A unique identifier for this extension. |
| `name` | string | The displayed name for this panel in the Data Studio. |
| `appearance`| string | To which appearance mode the theme belongs to - `light` or `dark`. |
| `rules` | object | A set of theming rules from the theme schema. |
| Property | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------ |
| `id` | string | A unique identifier for this extension. |
| `name` | string | The displayed name for this panel in the Data Studio. |
| `appearance` | string | To which appearance mode the theme belongs to - `light` or `dark`. |
| `rules` | object | A set of theming rules from the theme schema. |

### Available Rules

Rules that are configured in the `rules` property adhere to the rules section of the [theme schema](https://github.com/directus/directus/blob/main/packages/types/src/extensions/themes.ts).

```js{3-5}
rules: {
borderRadius: '24px',
navigation: {
shell: {
background: 'rebeccapurple'
}
}
```

::callout{icon="material-symbols:warning-rounded" color="warning"}
**Theme schema changes in Directus 12**
The studio design refresh in Directus 12 reorganized the theme schema. Custom themes referencing the removed rules will silently lose those overrides — update your theme to the new tokens:

- `navigation.background`, `navigation.backgroundAccent`, `navigation.borderWidth`, `navigation.borderColor`, `header.background`, `header.borderWidth`, and `header.borderColor` → moved to the new `shell.*` scope (e.g. `shell.background`, `shell.backgroundAccent`, `shell.borderWidth`, `shell.borderColor`). The corresponding CSS variables changed from `--theme--navigation--*` / `--theme--header--*` to `--theme--shell--*`.
- `header.headline.foreground` and `header.headline.fontFamily` were removed along with the underlying `headline` slot. The CSS variables `--theme--header--headline--foreground` and `--theme--header--headline--font-family` no longer exist.
- `borderColorFocus`, `boxShadowHover`, and `boxShadowFocus` were removed in favor of the new `focusRingColor` token. Interface extensions targeting `--theme--form--field--input--border-color-focus` or `--theme--form--field--input--box-shadow-focus` should migrate to `--theme--form--field--input--focus-ring-color`.
- `navigation.project.background`, `navigation.project.borderWidth`, and `navigation.project.borderColor` were removed and no longer have any effect.
- `section.toggle.borderWidth` and `section.toggle.borderColor` were removed in favor of section-level border tokens.
- `defineLayout()` no longer exposes `headerShadow` or `sidebarShadow`; `boxShadow` was removed from the header theme rules.

::

Any rules that are not defined will fallback to the default theme for it's appearance. See the
([`default dark theme`](https://github.com/directus/directus/blob/main/packages/themes/src/themes/dark/default.ts) and
[`default light theme`](https://github.com/directus/directus/blob/main/packages/themes/src/themes/light/default.ts)).
Expand Down Expand Up @@ -82,10 +96,10 @@ downloading it through Google Fonts. For example:

```js
// Use the locally installed font called "Comic Sans MS"
fontFamily: 'Comic Sans MS, sans-serif'
fontFamily: "Comic Sans MS, sans-serif";

// Use the Google font "Yesteryear"
fontFamily: '"Yesteryear", sans-serif'
fontFamily: '"Yesteryear", sans-serif';
```

When using a Google Font, ensure the configured weight is available for the selected font.
Loading