A CSS framework
A kit built on a CSS framework (Bootstrap, Tailwind, Foundation, or your company's own) works in Frame as any other kit: the framework gives the look, your theme's components give the markup, and the .info.yml gives the editor the values to offer. Frame does not know about the framework. This page is what to watch when you wire one.
1. Load the framework in the theme
Add its CSS (and JS, if it has some) to a library of your subtheme and attach it to every page:
# my_theme.libraries.yml
global-styling:
css:
theme:
assets/global.css: {} # your build: the framework plus your own rules
js:
assets/framework.js: {} # only if the framework needs it# my_theme.info.yml
libraries:
- my_theme/global-stylingThe canvas of the editor is a page of your theme with every component's library attached, so the components look the same there as on the page.
2. Use the framework's markup in components
A component is the framework's markup in Twig, with the choices as props:
# components/button/button.component.yml
name: Button
group: Content
props:
type: object
properties:
label: { type: string, title: Label, examples: ['Read more'] }
url: { type: string, title: Link, format: uri-reference }
variant:
type: string
title: Variant
enum: [primary, secondary, outline]
examples: [primary]
thirdPartySettings:
frame_editor:
features: { background: false, border: false } # the framework draws them{# components/button/button.twig #}
<a {{ attributes.addClass('btn', 'btn-' ~ variant|default('primary')) }} href="{{ url }}">{{ label }}</a>Map props to classes in Twig ('btn-' ~ variant), with an enum so editors pick only what exists. Keep {{ attributes }} on the root element: the features arrive there.
To offer it instead of the base theme's Button, give it the same props and slots as frame:button and replaces: frame:button (Your components).
3. Make the tokens one
The framework has its own scales. Make the editor offer the same values:
- Copy the values of the framework's spacing, type scale, breakpoints and colours into
frame_editor: uikit:(Design tokens), and its breakpoints into<theme>.breakpoints.yml. - Or drive the framework from Frame's tokens: when the framework is configured in SCSS, set its variables from
frame.space(),frame.color()andframe.font-size()before importing it, so one YAML file feeds both.
@use 'frame/tokens' as frame;
// Set the framework's variables from the tokens, then load the framework,
// as its documentation describes for customising it.
$primary: frame.color(primary);
$spacer: frame.space(m);A framework configured in JavaScript (a Tailwind config) can read the same YAML file, or you copy the values.
4. Utility-class frameworks
With a framework of utility classes (Tailwind and similar):
- Scan the components. The build must see the class names in
components/**/*.twig(and*.component.ymlif classes are written there), or it leaves them out. - Classes made from props are not seen.
'text-' ~ sizein Twig gives a class the scanner never finds. List the full class names of every choice (anenumwith a map in Twig), or safelist them. - Editors do not type classes. There is no field for free classes: the choices are props with an
enum, and the features of Layout and style. - Frame can write utility classes of its own from the tokens (
@include frame.utilities,.frame-p-m,.frame-bg-primary…), if you want the same names in Twig as editors have in the editor. See Rules for the features.
5. Features and the framework
What an editor sets in Layout and style is printed as inline styles on the root element. They win over the framework's classes on that element:
- a margin set by an editor replaces the margin a class gives on that side;
- a background colour set by an editor covers the framework's background of that element, but not of a box inside it;
- the framework's grid classes and Frame's Width both set widths: keep Width off on grid items.
Switch off, per component, the features the framework already decides (see Your components).
6. Resets and the editor
A framework's reset (Bootstrap's Reboot, Tailwind's Preflight, a normalize) is global CSS. The editor runs in a page of your theme, so the reset reaches the editor's own buttons, labels and inputs too. If the editor looks off, scope the framework to the page markup (wrap its import in .page { … } with your build, or use the framework's own option for a prefix or a scope), or leave its reset out.
Limitations
- Frame offers only the values in the
.info.yml: a framework class that no prop or token reaches cannot be chosen. - JavaScript of the framework (dropdowns, modals, tabs) runs in the canvas. A component whose script moves or replaces its children can break the editing of its slot.
- An icon font is used for icons by its classes (
icon: 'bi bi-star'); Frame does not bundle one. - Breakpoints are Drupal's (
<theme>.breakpoints.yml), not the framework's: keep them equal by hand.