design_system_api 1.0.0-alpha2

The second alpha is about skin authoring for site builders. A skin is now made, checked and bound in the admin UI (Appearance » Design system) without YAML or Drush, and the contrast checker works as an assistant rather than a gate: it says what fails, why, and offers a fix.

Status: experimental. The contract vocabulary will still change while it is developed together with theme maintainers. Don't build production code on it yet.

Highlights

• A failing skin saves. Save stores any skin the config schema can hold and tells you what the checks found. Only two things stop a skin, and only at Bind: a skin that can't render, and a must miss with more contrast. Every other must miss in light or dark binds with a reason.
• Accept a miss with a reason. In the skin editor, or on the binding form, a miss in light or dark can be accepted with a reason (required). The reason is stored on the skin as a departure, shown in the skins list, in drush ds:check and in the status report. Never with more contrast: there the value has to be fixed.
• Results by cause, with a fix. Check results are grouped by the value that fails, blocking first, with every pair and rule it breaks. Each cause comes with a suggested value on the same hue (OKLCH lightness only) that meets every pair the token is in, checked again as the whole skin. Apply puts it into the edit unsaved; Accept all… departs a whole cause with one reason. When the page wouldn't show the fix (a parent sets the token, or nothing draws the step), the cause says so and offers the token too.
• A tabbed skin editor with a live preview. Basics, Palette (a swatch grid per mode with contrast badges), Fonts and icons, Departures, and YAML, all on one data model. A preview draws buttons, a form field with an error, a link, a card and status messages in light, dark and each with more contrast, as you type. Works without JavaScript (open sections, Check and Save).
• Seeds that brand every mode. "Add a skin from a seed" copies the parent's palette in light, dark and both more-contrast modes and turns the accent ramp to the seed's hue in each, so a seeded skin is your colour everywhere, not only in light.

Upgrading from 1.0.0-alpha1

• No database update. Existing skins and departures (rule, pairs, modes, reason) keep working; a departure can now also name tokens, or neither, and cover any checker rule.
• Behaviour change: skins that failed a must rule used to be refused on Save. They now save, and may be bound with a reason. If you relied on Save refusing them, check with drush ds:check --bound (it still exits 1 on a must failure).
• drush ds:bind takes --reason, and without it refuses a skin with misses. Config import imports a skin with any result and fails only when the imported binding points at a blocked skin or at a miss without a reason.
• API: CheckResult::blocks(), miss() and judgedMode(), CheckReport::blocking(), misses() and bindable(), Skin::depart(), Check\Assistant and Check\Cause, ColorMath::nearestLightness(), Palette::seedRamp() are new. CheckReport::errors() now means blocking results plus misses that aren't departed.

Fixed

• Installing a site from existing config no longer fails with "The theme default_admin does not exist or is not installed".
• drush ds:bind no longer uses Config::save()'s $has_trusted_data argument, deprecated in Drupal 11.4.
• The Stylelint rule drupal-ds/custom-properties knows the component tokens of the extension a stylesheet belongs to.

Requirements

Drupal ^11.5 || ^12, PHP 8.3 or later. Unchanged from alpha1.

The full list of changes is in CHANGELOG.md. Documentation: project.pages.drupalcode.org/design_system_api. To try it, the demo site sets everything up with DDEV.