Uplink ACSS for Meta Box

Choose ACSS colors in Meta Box fields while retaining CSS variables, color mixes, and other CSS color expressions.

Project page · Download the plugin · Releases · Report an issue

What it does

• Adds ACSS Color to Meta Box Builder's Advanced field category.
• Displays available ACSS base colors, hover colors, and shades in grouped, searchable swatches.
• Saves a selected shade as a linked variable such as var(--primary-light).
• Mixes two CSS colors with percentages in OKLCH, OKLab, sRGB, linear sRGB, HSL, LCH, or Lab.
• Accepts custom hex, RGB, HSL, HWB, OKLCH, Lab, named colors, CSS variables, and color-mix expressions supported by the editor browser.
• Uses a compact popover with Palette, Mix, and Custom CSS tabs, keyboard navigation, and a live preview.
• Keeps existing field IDs and values through updates.
• Checks published GitHub releases through WordPress's native plugin updater.

The palette is discovered from the standard ACSS color families, semantic colors, and alternates present in ACSS's generated stylesheet files. Swatches are not copied into a separate database palette.

Requirements

• WordPress 6.5 or later.
• PHP 7.4 or later.
• Automatic.css 4.x, with its variable stylesheets generated.
• Meta Box.
• Meta Box Builder for visual field creation.
• MB Term Meta for taxonomy term fields. Builder and Term Meta are included in Meta Box AIO.
• A modern browser supporting the CSS color expressions you use. Frontend browsers must support those expressions too.

The main picker and Etch data flow were checked locally with Automatic.css 4.0.1, Meta Box AIO 3.13.1, Etch 1.7.1, and WordPress 7.2 beta. This is not a claim of exhaustive testing across all supported WordPress versions or browser engines.

Install

Download acss-for-meta-box.zip from the latest GitHub release. In WordPress, open Plugins > Add Plugin > Upload Plugin, upload the ZIP, and activate it.

Use the release asset rather than GitHub's automatically generated Source code ZIP. The release ZIP has the correct WordPress plugin folder, uplink-acss-color-for-meta-box, preserving existing installations and update paths.

Add a field

1. Open Meta Box > Custom Fields and create or edit a group.
2. Add Advanced > ACSS Color.
3. Set its label and a unique field ID, for example category_color.
4. Leave Cloneable off for a single value.
5. Choose the group's location and save it.

Open a matching post or taxonomy term and click Choose color. A selection changes the field immediately. Save the post or term to persist it. There is no plugin settings page.

Registering the field in PHP works too:

add_filter( 'rwmb_meta_boxes', function ( $groups ) {
    $groups[] = array(
        'title' => 'Category colors',
        'id' => 'category-colors',
        'taxonomies' => array( 'your-taxonomy' ),
        'fields' => array(
            array(
                'name' => 'Category Color',
                'id' => 'category_color',
                'type' => 'uplink_acss_color',
            ),
        ),
    );
    return $groups;
} );

Use a saved color

The field returns a CSS expression, not necessarily a hex string. Ensure ACSS styles load wherever the variable is displayed. Consumers must accept CSS expressions and use contextual output escaping.

$color = rwmb_meta( 'category_color', array( 'object_type' => 'term' ), $term_id );
if ( is_string( $color ) && RWMB_Uplink_Acss_Color_Field::safe_value( $color ) ) {
    printf( '<span style="background-color:%s">Category</span>', esc_attr( $color ) );
}

Etch

In an Etch taxonomy loop with item name category, the field is available at:

{category.metabox.category_color}

Use it in a color declaration, for example background-color: {category.metabox.category_color};. The locally tested loop preserved ACSS variables, color-mix expressions, and OKLCH values without a separate Etch bridge.

Updates

The plugin checks the repository's latest stable GitHub release when WordPress checks for plugin updates. Release metadata is cached for up to one hour. Plugins > ACSS for Meta Box > Check for updates clears that cache and requests a fresh check.

Update notices follow WordPress's schedule. Publishing a release does not push an immediate installation to every site. Administrators can install an offered update normally or enable WordPress auto-updates for this plugin. No GitHub token is required on the WordPress site.

Only a stable release with the named acss-for-meta-box.zip asset is offered. Drafts, prereleases, missing packages, and failed requests do not produce update offers. Network failures are retried after a short cache interval.

Publish a new version

1. Update the plugin header and UPLINK_ACSS_COLOR_VERSION to the same version.
2. Add that version's entry to CHANGELOG.md. Update compatibility headers if needed.
3. Commit and push the change to main.
4. Push a matching tag, for example v1.0.1.

The release workflow runs checks, validates the tag against the plugin version, builds the installable ZIP, and publishes a GitHub release with compatibility metadata. A branch commit by itself does not publish an update.

Local checks and packaging:

php tests/run.php
node --check assets/picker.js
python3 -m unittest discover -s tests -p 'test_*.py'
python3 scripts/build.py --tag v1.0.0

Other ACSS integrations

For WordPress block editor colors, ACF, Customizer, and dashboard/login variables, we recommend ACSS Colors for WP Admin by SnippetNest.

This plugin focuses on the custom Meta Box field. It does not modify WordPress editor palettes, native Meta Box color fields, ACF pickers, Customizer controls, or global dashboard/login styles. The companion plugin is optional and is not activated automatically.

Validation and scope

The browser validates color grammar using CSS.supports('color', value). The server limits input to a safe single-value character set and rejects declarations, markup, comments, URLs, and legacy expression functions. Unsafe submissions retain the previous value. It is not a complete server-side CSS parser; direct API consumers should validate grammar separately.

Values are limited to 2,048 characters. Quoted or escaped custom identifiers and CSS comments are deliberately unsupported. Variables defined only in a frontend context may not preview in the editor.

The picker is intended for WordPress admin Meta Box fields. Frontend submission forms and third-party builder panels require separate integration testing. It does not create frontend category-badge styles automatically.

There is no telemetry or analytics. The updater contacts GitHub to retrieve public release metadata and download packages. Picker assets are bundled locally, with no Web Awesome runtime or CDN dependency.

License

GPL-2.0-or-later. See LICENSE.