Safe CSS Customization

Overview

KineticHub provides built-in controls for layout, typography, colors, spacing, animation, responsive behavior, and visual effects.

Use the block settings first whenever the required option is available.

Custom CSS should be used only for adjustments that cannot be achieved through:

• KineticHub block controls
• WordPress block settings
• Theme Global Styles
• Parent Group or layout settings
• Responsive controls
• Shared KineticHub dashboard settings

Targeted CSS can be useful, but broad overrides may affect several blocks or break after a plugin, theme, or WordPress update.

Do not edit KineticHub plugin files

Do not add custom CSS directly inside the KineticHub plugin directory.

Avoid editing files under paths such as:

/wp-content/plugins/kinetichub/

or the installed KineticHub PRO directory.

Plugin updates replace the installed files and will normally remove manual changes.

Editing compiled KineticHub styles can also make troubleshooting difficult because the installed code no longer matches the official release.

Store custom CSS in:

• WordPress Additional CSS
• Theme Global Styles, where supported
• A child theme stylesheet
• A trusted custom CSS plugin
• A site-specific plugin maintained by the website developer

Use built-in controls first

Before writing CSS, select the KineticHub block and review the inspector sidebar.

Check panels such as:

• Layout
• Style
• Typography
• Spacing
• Colors
• Effects
• Animation
• Responsive
• Visibility

Also inspect the parent Group, Columns, Row, Stack, or Cover block.

A width, spacing, alignment, overflow, or background issue may belong to the parent rather than the KineticHub block.

Built-in settings are normally safer because they are stored with the block and supported by its frontend rendering.

Where to add custom CSS

The available location depends on the active WordPress theme.

Block theme

Open:

Appearance → Editor → Styles

Look for the available Additional CSS option in the Styles interface.

The exact location may vary between WordPress versions and themes.

Classic theme

Open:

Appearance → Customize → Additional CSS

Add the CSS and publish the Customizer changes.

Child theme

For larger or long-term customizations, add the CSS to the active child theme.

Do not add custom code directly to a parent theme because a theme update may overwrite it.

Custom CSS plugin

A trusted custom CSS plugin can be used when the theme does not provide an appropriate CSS area.

Avoid installing several plugins that all add CSS to the same page.

Add a custom CSS class to the block

Most WordPress blocks provide an Additional CSS class(es) field.

To use it:

1. Select the KineticHub block
2. Open the block settings sidebar
3. Expand Advanced
4. Find Additional CSS class(es)
5. Enter a unique class name
6. Save or update the page

Example class:

kh-custom-feature

Do not include the period in the WordPress field.

Use:

kh-custom-feature

not:

.kh-custom-feature

The period is used only when writing the CSS selector.

When the custom class field is unavailable

Not every block exposes the Additional CSS class field.

When the field is unavailable:

1. Add a WordPress Group block
2. Place the KineticHub block inside the Group
3. Add the custom class to the Group
4. Scope the CSS through that wrapper

Example wrapper class:

kh-custom-aura-section

This is also useful when one customization should apply to several blocks inside the same section.

Use unique class names

Choose descriptive names that are unlikely to conflict with the theme or another plugin.

Good examples:

kh-home-hero

kh-pricing-marquee

kh-contact-video

kh-mobile-player

kh-feature-boxes

Avoid generic classes such as:

box

button

title

green

section

Generic names are more likely to match unrelated elements.

Scope every customization

A safe CSS rule should target only the intended block or section.

Example:

.kh-home-hero {
    margin-block: 4rem;
}

This affects only the element using the kh-home-hero class.

Avoid broad rules such as:

button {
    border-radius: 0;
}

A global selector like this can affect:

• KineticHub buttons
• WordPress buttons
• Forms
• Navigation controls
• Modal controls
• Audio controls
• Administration interfaces loaded on the frontend

Use the narrowest selector that solves the problem.

Example: custom outer spacing

Add this class to the selected block or its parent Group:

kh-custom-spacing

Then add:

.kh-custom-spacing {
    margin-block: clamp(2rem, 6vw, 6rem);
}

This changes only the outer spacing.

It does not change the internal animation or KineticHub block structure.

Example: maximum section width

Add the class:

kh-custom-width

Then use:

.kh-custom-width {
    width: min(100%, 1200px);
    margin-inline: auto;
}

Check whether the active theme already controls the content width before adding this rule.

A parent container may still limit the available width.

Example: mobile spacing

.kh-custom-spacing {
    margin-block: 5rem;
}

@media (max-width: 782px) {
    .kh-custom-spacing {
        margin-block: 2.5rem;
    }
}

The 782px value is a practical WordPress-oriented breakpoint, not a universal KineticHub requirement.

Use a breakpoint that matches the actual layout.

Example: page-specific customization

To apply a change only on one WordPress page, combine the custom class with the page body class.

Example:

.page-id-123 .kh-home-hero {
    margin-top: 2rem;
}

Replace 123 with the real page ID.

This prevents the same custom class from changing identical sections on other pages.

Prefer custom wrapper classes over internal selectors

KineticHub frontend markup contains internal classes used for layout, rendering, animation, and JavaScript initialization.

Many of these classes use a kh- prefix.

Internal classes are implementation details. They may change when a block is improved or restructured.

Whenever possible, target a custom class that you control:

.kh-custom-feature {
    margin-top: 3rem;
}

Use internal KineticHub selectors only when the required child element cannot be targeted safely in another way.

Document every internal selector used so it can be reviewed after plugin updates.

Do not rename KineticHub classes

Do not remove or rename classes generated by KineticHub.

Frontend scripts may use these classes to find:

• Block containers
• Animation layers
• Canvas elements
• Slider handles
• Media wrappers
• Modal controls
• Audio controls
• Sticky elements

Changing an initialization class can leave the block visible but non-interactive.

Add your own class instead of replacing existing classes.

Avoid changing structural properties without testing

Some CSS properties can change how KineticHub calculates or displays a block.

Use extra care when overriding:

• display
• position
• overflow
• transform
• perspective
• width
• height
• min-height
• z-index
• pointer-events
• opacity
• visibility

These properties can affect:

• Sticky positioning
• Pointer tracking
• Dragging
• Canvas dimensions
• Modal interaction
• 3D movement
• Media cropping
• Stacking contexts
• Responsive behavior

Test the block before and after each structural override.

Overflow changes

Changing a wrapper to:

overflow: hidden;

may clip:

• Glows
• Shadows
• Slider handles
• Floating controls
• Transformed content
• Animated media

Changing it to:

overflow: visible;

may break:

• Rounded image cropping
• Visual masks
• Horizontal containment
• Background effects

Identify which layer needs the overflow change rather than applying it to every KineticHub block.

Transform changes

Avoid adding custom transforms directly to an element that KineticHub already animates.

For example:

.kh-custom-block {
    transform: translateY(-20px);
}

may conflict when the same element receives an animated transform from KineticHub.

A safer structure is often:

1. Place the KineticHub block inside a Group
2. Add the custom class to the Group
3. Apply the layout transform or spacing to the Group

This keeps the custom transform separate from the animated element.

Pointer events

Do not add:

pointer-events: none;

to a wrapper containing interactive controls.

It can disable:

• Links
• Buttons
• Slider dragging
• Audio controls
• Video modal triggers
• Hover behavior

Use pointer-events: none only on a verified decorative layer that should never receive interaction.

Z-index

A high z-index does not always place an element above everything else.

The result also depends on stacking contexts created by:

• Transforms
• Opacity
• Filters
• Positioning
• Isolation
• Perspective

Avoid adding extremely large z-index values without inspecting the parent containers.

Fix the relevant stacking context rather than creating a site-wide z-index conflict.

Shared KineticHub CSS variables

KineticHub uses shared CSS variables for selected global values, including variables such as:

--kh-accent
--kh-glass-blur

These values may be used by more than one block.

Changing them globally can affect multiple KineticHub elements across the website.

Prefer the relevant KineticHub dashboard or block control when it is available.

A targeted variable override can be applied to a custom wrapper:

.kh-custom-feature {
    --kh-accent: #22c55e;
}

This works only for descendant styles that actually use that variable.

It does not automatically replace every color configured directly by a block.

Avoid global variable overrides

Use caution with:

:root {
    --kh-accent: red;
}

A root-level override can change every supported KineticHub block on the website.

Use a page or section class when the change is intended for only one location.

CSS specificity

When a custom rule does not apply, the cause may be selector specificity or stylesheet order.

Before using !important:

1. Inspect the element in browser developer tools
2. Find the rule currently winning
3. Confirm where that rule comes from
4. Increase specificity only as much as necessary
5. Check desktop and mobile states
6. Test hover, focus, and active states

Example:

.kh-home-hero.kh-custom-spacing {
    margin-top: 4rem;
}

A slightly more specific selector is safer than a broad !important override.

Use !important sparingly

!important can make future adjustments difficult.

It can also prevent:

• Responsive settings
• Hover states
• Block controls
• Theme variations
• Accessibility fallbacks

Use it only when the source rule cannot be overridden safely through normal specificity or stylesheet order.

Document why it was required.

Editor and frontend differences

Custom CSS added through the theme may appear only on the public frontend.

The WordPress editor may use:

• Different wrappers
• An iframe
• Editor-specific styles
• Theme editor styles
• Additional Gutenberg classes

Do not assume the customization failed only because it is not identical in the editor.

Save the page and inspect the frontend.

When editor parity is essential, the custom CSS must also be loaded into the block editor through a properly developed theme or site-specific plugin.

Responsive CSS

Test custom CSS at multiple widths.

A fixed desktop value may cause problems on mobile.

Avoid:

.kh-custom-feature {
    width: 1200px;
}

Prefer flexible sizing:

.kh-custom-feature {
    width: min(100%, 1200px);
}

Also check:

• Long headings
• Button widths
• Media cropping
• Horizontal overflow
• Sticky sections
• Touch controls
• Portrait and landscape orientation

Reduced-motion CSS

KineticHub already provides reduced-motion behavior for supported effects.

When adding your own CSS animation, provide a reduced-motion fallback.

Example:

.kh-custom-pulse {
    animation: customPulse 2s ease-in-out infinite;
}

@media (prefers-reduced-motion: reduce) {
    .kh-custom-pulse {
        animation: none;
    }
}

This applies to custom animation added by the website developer, not to the built-in KineticHub engine.

Avoid injecting JavaScript through CSS workflows

A CSS field should contain CSS only.

Do not insert:

• <script> tags
• JavaScript event handlers
• PHP
• HTML markup
• External code from an unknown source

Use a properly developed plugin or child theme when custom JavaScript is genuinely required.

Comment important customizations

Add a short comment above important rules.

Example:

/* KineticHub pricing marquee: reduce outer spacing on mobile. */
@media (max-width: 782px) {
    .kh-pricing-marquee {
        margin-block: 2rem;
    }
}

Comments help future developers understand why the rule exists.

Do not store passwords, license keys, private URLs, or personal information in CSS comments.

Keep a customization record

For a client or production website, record:

• Page using the CSS
• Custom class name
• Purpose of the rule
• Date added
• KineticHub version tested
• Theme version tested
• Any internal selector used
• Any optimization exclusion required

This makes future updates safer.

Test before publishing

After adding custom CSS:

1. Save the CSS
2. Clear generated CSS and page caches
3. Reload the frontend in a private window
4. Test desktop
5. Test mobile
6. Check hover and focus states
7. Test interactive controls
8. Test reduced motion
9. Check nearby KineticHub blocks
10. Inspect the browser console
11. Confirm that no content is clipped
12. Confirm that the editor remains usable

Make one change at a time.

After a KineticHub update

Custom wrapper classes should normally remain stable because they are stored in the WordPress page content.

Internal KineticHub markup may change between releases.

After updating:

1. Clear all caches
2. Review pages using custom CSS
3. Test selectors that target internal KineticHub classes
4. Check responsive behavior
5. Test interactive states
6. Remove rules that are no longer required

Do not copy an older compiled KineticHub stylesheet back into the updated plugin.

Troubleshooting

The custom CSS does not apply

Check:

• The custom class spelling
• Whether the period was incorrectly added in the WordPress class field
• Whether the CSS was published
• Browser and page caches
• Selector specificity
• Whether the rule is loaded on the frontend
• Whether another rule uses !important
• Whether the element exists inside an editor iframe

Inspect the element with browser developer tools.

The CSS affects every KineticHub block

The selector is probably too broad.

Replace a global KineticHub or element selector with a unique wrapper class.

The block stopped animating

Check whether the custom CSS changes:

• Transform
• Display
• Visibility
• Opacity
• Position
• Pointer events
• Width or height

Remove the recent rules one at a time.

Sticky behavior stopped working

Check custom overflow and transform rules on every parent container.

A transformed or clipped ancestor can change sticky behavior.

A button or slider cannot be clicked

Inspect overlays, pseudo-elements, z-index, and pointer-events.

A visible decorative layer may be positioned above the control.

The frontend works but the editor looks different

The custom stylesheet may not be loaded inside the WordPress editor.

Confirm the frontend first.

Use a child theme or site-specific plugin when editor styles must match.

Changes disappear after an update

The CSS was probably added directly to the KineticHub plugin or parent theme.

Move the customization to:

• WordPress Additional CSS
• A child theme
• A trusted custom CSS plugin
• A site-specific plugin

Old CSS remains active

Clear:

• Page cache
• Generated CSS
• Server cache
• CDN cache
• Browser cache

Also check whether the same rule exists in more than one CSS location.

Recommended approach

Use this order:

1. KineticHub block controls
2. WordPress block and parent settings
3. Theme Global Styles
4. A unique Additional CSS class
5. Targeted CSS in WordPress or a child theme
6. Internal KineticHub selectors only when necessary

This keeps the website easier to update and troubleshoot.

Next step

The Advanced Settings section is complete.

Continue to Troubleshooting, beginning with A KineticHub Block Is Missing from the Editor.