The most reliable WordPress design workflow treats the site as a small design system, not a pile of page-level overrides. Put shared colors, type, spacing, and responsive rules in theme.json; enable only the layout controls your CSS can support; make the editor canvas match the front end; load block CSS conditionally; and finish with an accessibility and handoff review at real viewport sizes.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
1. Make theme.json your design-system control center
theme.json is the canonical place for block-editor settings and global styles in modern WordPress. WordPress introduced it in version 5.8 as a settings mechanism. A well-structured file gives designers and developers one vocabulary for colors, type scales, spacing, and element states, while generating the classes and custom properties that blocks use in both the editor and the published site.
As an Amazon Associate I earn from qualifying purchases.
Define tokens instead of styling every block by hand
Start with a deliberately small palette and type scale. Name tokens by purpose rather than by a literal color, so a later rebrand does not require hunting through templates.
{
"version": 3,
"settings": {
"color": {
"palette": [
{ "slug": "ink", "color": "#17191C", "name": "Ink" },
{ "slug": "paper", "color": "#F5F6F7", "name": "Paper" },
{ "slug": "accent", "color": "#D64045", "name": "Accent" }
]
},
"typography": {
"fontSizes": [
{ "slug": "small", "size": "0.875rem", "name": "Small" },
{ "slug": "body", "size": "1rem", "name": "Body" },
{ "slug": "display", "size": "clamp(2.25rem, 6vw, 4.5rem)", "name": "Display" }
]
},
"spacing": {
"spacingSizes": [
{ "slug": "2xs", "size": "0.5rem", "name": "2XS" },
{ "slug": "sm", "size": "1rem", "name": "Small" },
{ "slug": "lg", "size": "3rem", "name": "Large" }
]
}
},
"styles": {
"color": { "text": "var:preset|color|ink", "background": "var:preset|color|paper" },
"elements": {
"link": { "color": { "text": "var:preset|color|accent" } }
}
}
}Presets appear in the editor as constrained choices instead of an uncontrolled color picker or dozens of near-identical font sizes. Keep the list short enough that a client can understand it. Use element styles for shared link, button, heading, and caption states; use block-specific styles only when a component genuinely differs.
#1 Best Overall
Put responsive values beside the value they change
Responsive styles let a block use different settings at different viewport sizes. WordPress documents @mobile and @tablet keys for responsive overrides, with theme-configurable viewport widths. The documented defaults are mobile at 480px and narrower, and tablet above 480px through 782px.
{
"styles": {
"blocks": {
"core/heading": {
"typography": {
"fontSize": "var:preset|font-size|display",
"@tablet": { "fontSize": "3rem" },
"@mobile": { "fontSize": "2.25rem" }
}
}
}
}
}Do not assume a mobile value inherits a tablet value. Tablet and mobile overrides are independent; if mobile should retain part of the tablet treatment, set that mobile value explicitly. Test the resulting CSS at your theme’s actual breakpoints rather than trusting a desktop preview.
2. Expose only layout controls your theme can support
Every editor control is a promise. If a theme exposes a setting that its CSS does not honor, designers can approve a layout that breaks on the front end. Opt into features deliberately and document the assumptions in the theme.
Wide and full-width alignment
The align-wide theme support flag enables alignwide and alignfull layouts. Add it only after the outer container, overflow rules, and responsive gutters have been tested.
add_action( 'after_setup_theme', function () {
add_theme_support( 'align-wide' );
} );Your content wrapper must allow a wide block to exceed the reading measure without creating a horizontal scrollbar. A full-width block should be able to reach the viewport edge while its inner text remains readable.
Responsive embeds
responsive-embeds opts embedded media into the theme’s responsive aspect-ratio behavior. Without that opt-in, an iframe or video can preserve a desktop width and overflow on a phone.
add_action( 'after_setup_theme', function () {
add_theme_support( 'responsive-embeds' );
} );Other controls to audit
| Control | Enable when | What to verify |
|---|---|---|
| Custom spacing | Your layout has a spacing scale and corresponding CSS variables. | Margins and padding collapse or stack correctly at every viewport. |
| Link colors | Your palette includes a link color with sufficient contrast. | Default, hover, focus, and visited states remain distinguishable. |
| Wide/full alignment | The container supports intentional wide and edge-to-edge compositions. | No horizontal scrolling; media and text keep sensible gutters. |
| Responsive embeds | Embedded video, maps, or social posts appear in the design. | Aspect ratio is preserved and the embed fits narrow screens. |
In a block theme, many of these capabilities belong in theme.json; in a classic theme, some still use add_theme_support(). Do not enable a feature merely because it appears in a handbook example.
3. Make the editor a trustworthy preview
A designer should not approve a page in a canvas that is materially narrower, wider, or typographically different from the published page. Add editor-styles support and enqueue an editor stylesheet that loads the same font stack, colors, line heights, and content widths as the front end.
Enable and enqueue editor styles
add_action( 'after_setup_theme', function () {
add_theme_support( 'editor-styles' );
add_editor_style( 'assets/css/editor.css' );
} );Use separate widths for the main column, wide blocks, and full-width blocks. The exact numbers belong to your composition; the important part is that the relationships match.
/* assets/css/editor.css */
.editor-styles-wrapper .wp-block {
max-width: 720px;
margin-left: auto;
margin-right: auto;
}
.editor-styles-wrapper .wp-block[data-align="wide"] {
max-width: 1100px;
}
.editor-styles-wrapper .wp-block[data-align="full"] {
max-width: none;
}
Load the same font files or a matching system stack in the editor. Check headings, buttons, lists, captions, pull quotes, tables, and images—not just a paragraph—because block margins and line wrapping often reveal a mismatch.
Rank #3
Use the editor’s preview preferences
The Preferences panel includes a “use theme styles” option. Turn it on while reviewing so the canvas resembles the published site. The editor also exposes an accessibility preference; use it during review rather than treating accessibility as a separate development pass.
4. Design responsively at the block level
Responsive work is easier to maintain when each block has an intentional base, tablet, and mobile treatment. WordPress’s responsive-style system is included in block themes and, according to its documentation, requires WordPress 7.1 or higher. A theme can customize the viewport widths, so record your chosen thresholds in the project notes.
Set a base, then override intentionally
- Choose the base state. Define the desktop or default typography, spacing, alignment, and media behavior in
theme.json. - Define tablet changes. Reduce columns, tighten gaps, or lower display sizes where the intermediate width needs it.
- Define mobile changes separately. Set mobile values explicitly; they do not automatically inherit tablet overrides.
- Inspect real content. Test long headings, translated labels, portrait images, embeds, and blocks with optional elements hidden.
Prefer fluid values such as clamp() for type or gutters when a continuous scale is appropriate, then use responsive overrides for structural changes such as switching a row to a stack. Avoid using a media query to repair a component whose intrinsic width, gap, or text measure is wrong.
5. Ship less CSS with block stylesheets
Large block systems often send every block rule to every page. WordPress’s block-stylesheet system can load a block’s CSS only when that block is present, and it can inline that CSS in the front-end head. The result is a smaller payload on pages that use only a fraction of the available blocks.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteSplit substantial block rules from theme-wide rules
Keep resets, global variables, layout primitives, and site-wide typography in the main stylesheet. Move substantial, block-specific rules into per-block files so they can be maintained and loaded conditionally.
add_action( 'init', function () {
wp_enqueue_block_style(
'core/button',
array(
'handle' => 'theme-button',
'src' => get_theme_file_uri( 'assets/css/blocks/button.css' ),
)
);
} );Audit the generated markup before splitting files. A selector that depends on a parent template, a global utility, or an editor-only class may need to remain in the shared stylesheet. Conditional loading is useful only when the resulting cascade is predictable.
Measure the change
- Confirm that a page containing no gallery, quote, or form block does not receive their large stylesheets.
- Check that critical above-the-fold styles are not delayed by an unnecessary dependency.
- Verify editor and front-end appearances after splitting files; they may use different enqueue paths.
- Remove duplicate declarations from legacy CSS instead of layering a conditional file on top of them.
6. Use the Site Editor for reusable structure
Block themes expose templates and template parts in the Site Editor. Put global structure—headers, footers, navigation, archive layouts, and single-post shells—there instead of rebuilding it page by page.
Choose the right level for a change
- Theme-wide decision: use
theme.jsonfor tokens, element states, and shared defaults. - Template decision: edit a template when the page type changes, such as an archive or single post.
- Template-part decision: edit a header, footer, or reusable section once so every template receives the change.
- Block-type decision: when a visual change should apply to every instance of a block, apply the edit to all blocks of that type. WordPress documentation records this capability as available from version 6.2.
- One-off decision: keep a local block variation or custom class limited to the page that truly needs it.
This hierarchy prevents a client handoff from producing dozens of slightly different headers or manually adjusted buttons.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
7. Keep custom CSS at the edge
A site-wide custom CSS editor is built into the Styles interface as of WordPress 6.2. The feature requires a block theme and WordPress 5.9 or newer. It is useful for an integration constraint, a temporary experiment, or a narrowly scoped exception; it is a poor place for the core design system.
When a rule represents a durable design decision, move it into theme.json, a block style, or a component stylesheet. If custom CSS is unavoidable, scope it to a stable class, add a comment explaining why it exists, and check whether the editor receives the same rule. Avoid selectors tied to autogenerated block IDs or deeply nested markup that may change after an editor update.
8. Build accessibility into the design review
Accessibility is part of the visual handoff. A polished desktop screenshot can still hide a keyboard trap, unreadable contrast, or a mobile reading order that makes no sense.
Run this review for every template and component
- Contrast: check body text, links, buttons, muted metadata, focus indicators, and text placed over images.
- Keyboard use: tab through navigation, dialogs, menus, forms, carousels, and custom controls; the focus indicator must remain visible.
- Headings: preserve a logical hierarchy and do not choose a heading level only for its visual size.
- Images: supply meaningful alternative text, empty alternative text for decorative images, and captions where context requires them.
- Content order: confirm that the reading and keyboard order still make sense when columns stack on mobile.
- Type and zoom: inspect at enlarged text and narrow widths; no essential content should disappear or overlap.
- Motion and media: provide controls, captions, and a way to pause motion where applicable.
Use the editor’s accessibility preference while reviewing, then test the published page with keyboard navigation and a screen reader. Automated checks can find common errors, but the final judgment depends on the site’s actual content and components.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →9. Choose an architecture that survives handoff
There is no universal winner between a classic theme, a block theme, and a custom block system. Choose based on how the client will edit the site and how much control the design system needs.
| Decision axis | Classic theme | Block theme | Custom block system |
|---|---|---|---|
| Global styles | Customizer settings and PHP/CSS, with theme.json where supported | Primarily theme.json and the Styles interface | Theme.json plus purpose-built block attributes and styles |
| Template editing | Usually code or theme-specific controls | Templates and template parts in the Site Editor | Site Editor plus controlled custom blocks |
| Responsive values | Theme CSS and media queries | Responsive style settings and theme CSS | Responsive settings plus component-level CSS contracts |
| Editor synchronization | Requires deliberate editor-style support | Shared global styles make alignment easier, but still test editor CSS | Requires strict parity between block editor controls and front-end rendering |
| CSS loading | Often one broad stylesheet unless you split it | Theme stylesheet plus conditional block stylesheets | Per-block stylesheets are practical and usually preferable |
| Client maintenance | Familiar to teams with established PHP workflows | Strong visual editing, with fewer code handoffs for templates | Most control, but the highest documentation and governance burden |
Whichever architecture you choose, deliver a short map of tokens, templates, reusable parts, custom classes, and intentional exceptions. A client should be able to tell which controls are safe to change and which changes require the original developer.
10. A practical pre-launch handoff sequence
- Freeze the vocabulary. Confirm palette slugs, font sizes, spacing names, content widths, and breakpoint values in
theme.json. - Exercise every exposed control. Insert wide, full-width, embedded, gallery, table, quote, and form blocks and test their supported settings.
- Compare editor and front end. Publish representative pages and compare line wrapping, widths, margins, colors, focus states, and media behavior.
- Review three viewport states. Check the base, tablet, and mobile states with real content, not only placeholder text.
- Inspect the payload. Confirm that unused block CSS is not loaded and that critical styles arrive without avoidable delays.
- Run the accessibility pass. Keyboard, contrast, headings, alternatives, focus, zoom, and content order should all be tested on the published templates.
- Document exceptions. Record every custom CSS rule, special block variation, plugin integration, and client-editing limitation.
- Test recovery. Make a copy of the production database and theme files, then verify that a staging restore preserves templates, styles, and reusable parts.
The handoff is complete when another person can edit content without accidentally bypassing the design system, and when the published result remains credible at every supported width.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
