<?php

namespace FluentCartBreakdance\Design;

defined('ABSPATH') || exit;

/**
 * The single, versioned source of truth for the --bde-fc-* design token schema (WP11A).
 *
 * Every FluentCart-for-Breakdance atom must consume these custom properties as its default
 * value before any element-level override is applied (architectuurprincipe 6, par. 3 WP11A).
 * This class is the only place a token name, family or fallback chain may be defined; the
 * generated stylesheet in assets/fcbd-tokens.css is a build artifact of self::css() and must
 * never be hand edited (see docs/tokens.md par. 5 for the regeneration command).
 *
 * Fallback-chain rule (bindend, ELITE-PLAN.md par. 3 WP11A / par. 1 principe 2 en 6):
 * a fallback chain may only reference a var(--bde-*) name that has been verified to exist in
 * the live Breakdance source (grep + file:line, see docs/tokens.md par. 4 "Bewijslog"). Every
 * token below that references a Breakdance global carries that evidence in its 'evidence' key.
 * A token family with no proven Breakdance equivalent (badges, notices, checkout section
 * panels, disabled states, error states) gets a literal fallback only, with no var() reference,
 * and its 'evidence' key records that this was verified absent rather than guessed.
 */
final class Tokens
{
    /**
     * Bump this when a token is renamed, removed, or its fallback chain changes meaning.
     * See docs/tokens.md par. 3 (migratieregels) for what a bump requires: a new token name
     * plus a deprecated alias kept for one minor release.
     */
    public const SCHEMA_VERSION = 1;

    /**
     * The families this schema is organised into. Every definition() entry must use one of
     * these slugs; tests/run-tokens.php asserts that.
     *
     * @return array<int, string>
     */
    public static function families(): array
    {
        return [
            'text',
            'headings',
            'buttons',
            'badges',
            'prices',
            'notices',
            'forms',
            'checkout',
            'drawer',
            'variations',
        ];
    }

    /**
     * Deprecated token aliases: old-name => current-name. Empty at schema_version 1 because
     * this is the first published schema. When a token is renamed in a later version, add the
     * old name here (kept for exactly one minor release, see docs/tokens.md par. 3) and the
     * generated CSS will emit the old custom property pointing at the new one via var().
     *
     * @return array<string, string>
     */
    public static function deprecatedAliases(): array
    {
        return [];
    }

    /**
     * The full token table.
     *
     * @return array<int, array{
     *   name: string,
     *   family: string,
     *   purpose: string,
     *   fallback: string,
     *   evidence: string,
     * }>
     */
    public static function definitions(): array
    {
        return [
            // ------------------------------------------------------------------
            // text
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-text-color',
                'family' => 'text',
                'purpose' => __('Default text inside FluentCart atoms (description, meta, labels).', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-body-text-color, #374151)',
                'evidence' => '--bde-body-text-color: plugin/global-styles/other/global-css-vars.css.twig:79',
            ],
            [
                'name' => '--bde-fc-text-muted-color',
                'family' => 'text',
                'purpose' => __('Muted text (captions, secondary meta) with no Breakdance global of its own.', 'sparkcore-commerce'),
                'fallback' => '#6b7280',
                'evidence' => 'geen bewezen Breakdance-global voor gedempte tekst; letterlijke fallback',
            ],
            // ------------------------------------------------------------------
            // headings
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-heading-color',
                'family' => 'headings',
                'purpose' => __('Color of product titles and section headings.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-headings-color, #111827)',
                'evidence' => '--bde-headings-color: plugin/global-styles/other/global-css-vars.css.twig:80',
            ],
            [
                'name' => '--bde-fc-heading-font-family',
                'family' => 'headings',
                'purpose' => __('Font family of product titles and section headings.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-heading-font-family, inherit)',
                'evidence' => '--bde-heading-font-family: plugin/global-styles/other/global-css-vars.css.twig:60-62',
            ],
            // ------------------------------------------------------------------
            // buttons (default/hover/focus-visible/disabled)
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-button-bg',
                'family' => 'buttons',
                'purpose' => __('Background of the primary action button (for example add to cart).', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-primary-background-color, #1f2937)',
                'evidence' => '--bde-button-primary-background-color: plugin/global-styles/other/global-css-vars.css.twig:342',
            ],
            [
                'name' => '--bde-fc-button-bg-hover',
                'family' => 'buttons',
                'purpose' => __('Background of the primary action button on hover.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-primary-background-color-hover, #111827)',
                'evidence' => '--bde-button-primary-background-color-hover: plugin/global-styles/other/global-css-vars.css.twig:343',
            ],
            [
                'name' => '--bde-fc-button-text-color',
                'family' => 'buttons',
                'purpose' => __('Text color of the primary action button.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-primary-text-color, #ffffff)',
                'evidence' => '--bde-button-primary-text-color: plugin/global-styles/other/global-css-vars.css.twig:122',
            ],
            [
                'name' => '--bde-fc-button-text-color-hover',
                'family' => 'buttons',
                'purpose' => __('Text color of the primary action button on hover.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-primary-text-color-hover, #ffffff)',
                'evidence' => '--bde-button-primary-text-color-hover: plugin/global-styles/other/global-css-vars.css.twig:123',
            ],
            [
                'name' => '--bde-fc-button-border-color',
                'family' => 'buttons',
                'purpose' => __('Border color of the primary action button.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-primary-border-color, transparent)',
                'evidence' => '--bde-button-primary-border-color: plugin/global-styles/other/global-css-vars.css.twig:120',
            ],
            [
                'name' => '--bde-fc-button-border-color-hover',
                'family' => 'buttons',
                'purpose' => __('Border color of the primary action button on hover.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-primary-border-color-hover, transparent)',
                'evidence' => '--bde-button-primary-border-color-hover: plugin/global-styles/other/global-css-vars.css.twig:121',
            ],
            [
                'name' => '--bde-fc-button-border-radius',
                'family' => 'buttons',
                'purpose' => __('Border radius of buttons.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-border-radius, 3px)',
                'evidence' => '--bde-button-border-radius: plugin/global-styles/other/global-css-vars.css.twig:139',
            ],
            [
                'name' => '--bde-fc-button-border-width',
                'family' => 'buttons',
                'purpose' => __('Border width of buttons.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-border-width, 1px)',
                'evidence' => '--bde-button-border-width: plugin/global-styles/other/global-css-vars.css.twig:140',
            ],
            [
                'name' => '--bde-fc-button-font-weight',
                'family' => 'buttons',
                'purpose' => __('Font weight of the button text.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-font-weight, 500)',
                'evidence' => '--bde-button-font-weight: plugin/global-styles/other/global-css-vars.css.twig:138',
            ],
            [
                'name' => '--bde-fc-button-padding',
                'family' => 'buttons',
                'purpose' => __('Padding of the default button.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-padding-base, 14px 24px)',
                'evidence' => '--bde-button-padding-base: plugin/global-styles/other/global-css-vars.css.twig:143',
            ],
            [
                'name' => '--bde-fc-button-line-height',
                'family' => 'buttons',
                'purpose' => __('Line height of the button text.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-button-line-height, 1)',
                'evidence' => '--bde-button-line-height: plugin/global-styles/other/global-css-vars.css.twig:147',
            ],
            [
                'name' => '--bde-fc-button-focus-visible-ring-color',
                'family' => 'buttons',
                'purpose' => __('Color of the focus ring on buttons during keyboard navigation.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-focused-border-color, #1f2937)',
                'evidence' => '--bde-form-input-focused-border-color: plugin/global-styles/other/global-css-vars.css.twig:372 (hergebruikt als focus-accent, geen los bde-focus-ring-token bewezen)',
            ],
            [
                'name' => '--bde-fc-button-focus-visible-ring-width',
                'family' => 'buttons',
                'purpose' => __('Width of the focus ring on buttons during keyboard navigation.', 'sparkcore-commerce'),
                'fallback' => '2px',
                'evidence' => 'geen bewezen Breakdance-global voor ringdikte; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-button-disabled-bg',
                'family' => 'buttons',
                'purpose' => __('Background of a disabled button.', 'sparkcore-commerce'),
                'fallback' => '#e5e7eb',
                'evidence' => 'alleen --bde-woo-buttons-and-links__disabled-button-color bestaat (global-css-vars.css.twig:199), maar die is WooCommerce-scoped en niet gegarandeerd aanwezig zonder Woo-element; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-button-disabled-text-color',
                'family' => 'buttons',
                'purpose' => __('Text color of a disabled button.', 'sparkcore-commerce'),
                'fallback' => '#9ca3af',
                'evidence' => 'alleen --bde-woo-buttons-and-links__disabled-button-text-color bestaat (global-css-vars.css.twig:200), WooCommerce-scoped; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-button-disabled-opacity',
                'family' => 'buttons',
                'purpose' => __('Opacity of a disabled button.', 'sparkcore-commerce'),
                'fallback' => '0.6',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            // ------------------------------------------------------------------
            // badges (sale/stock)
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-badge-sale-bg',
                'family' => 'badges',
                'purpose' => __('Background of the sale label.', 'sparkcore-commerce'),
                'fallback' => '#dc2626',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-sale-text-color',
                'family' => 'badges',
                'purpose' => __('Text color of the sale label.', 'sparkcore-commerce'),
                'fallback' => '#ffffff',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-stock-in-bg',
                'family' => 'badges',
                'purpose' => __('Background of the in-stock label.', 'sparkcore-commerce'),
                'fallback' => '#16a34a',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-stock-in-text-color',
                'family' => 'badges',
                'purpose' => __('Text color of the in-stock label.', 'sparkcore-commerce'),
                'fallback' => '#ffffff',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-stock-low-bg',
                'family' => 'badges',
                'purpose' => __('Background of the low-stock label.', 'sparkcore-commerce'),
                'fallback' => '#d97706',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-stock-low-text-color',
                'family' => 'badges',
                'purpose' => __('Text color of the low-stock label.', 'sparkcore-commerce'),
                'fallback' => '#ffffff',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-stock-out-bg',
                'family' => 'badges',
                'purpose' => __('Background of the sold-out label.', 'sparkcore-commerce'),
                'fallback' => '#6b7280',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-stock-out-text-color',
                'family' => 'badges',
                'purpose' => __('Text color of the sold-out label.', 'sparkcore-commerce'),
                'fallback' => '#ffffff',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-custom-bg',
                'family' => 'badges',
                'purpose' => __('Background of a badge from the badge builder (FC Products/FC Related Products), unless the badge item sets its own background.', 'sparkcore-commerce'),
                'fallback' => '#0f172a',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-badge-custom-text-color',
                'family' => 'badges',
                'purpose' => __('Text color of a badge from the badge builder, unless the badge item sets its own text color.', 'sparkcore-commerce'),
                'fallback' => '#ffffff',
                'evidence' => 'geen bewezen Breakdance-global voor badges; letterlijke fallback',
            ],
            // ------------------------------------------------------------------
            // prices (regular/sale/compare)
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-price-regular-color',
                'family' => 'prices',
                'purpose' => __('Color of the regular price.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-headings-color, #111827)',
                'evidence' => '--bde-headings-color: plugin/global-styles/other/global-css-vars.css.twig:80 (prijs volgt kopkleur, geen los bde-price-token bewezen)',
            ],
            [
                'name' => '--bde-fc-price-sale-color',
                'family' => 'prices',
                'purpose' => __('Color of the sale price.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-brand-primary-color, #2563eb)',
                'evidence' => '--bde-brand-primary-color: plugin/global-styles/other/global-css-vars.css.twig:43 (hergebruikt als accent, geen los bde-price-sale-token bewezen)',
            ],
            [
                'name' => '--bde-fc-price-compare-color',
                'family' => 'prices',
                'purpose' => __('Color of the struck-through compare price.', 'sparkcore-commerce'),
                'fallback' => '#9ca3af',
                'evidence' => 'geen bewezen Breakdance-global voor gedempte/vergelijkingsprijs; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-price-compare-text-decoration',
                'family' => 'prices',
                'purpose' => __('Text decoration of the compare price.', 'sparkcore-commerce'),
                'fallback' => 'line-through',
                'evidence' => 'geen var-kandidaat, functionele constante',
            ],
            // ------------------------------------------------------------------
            // notices (info/success/warning/error)
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-notice-info-bg',
                'family' => 'notices',
                'purpose' => __('Background of an info notice.', 'sparkcore-commerce'),
                'fallback' => '#eff6ff',
                'evidence' => 'geen bewezen Breakdance-global voor meldingskleuren (alleen woocommerce-info::before mask-icon, geen bg-token); letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-info-text-color',
                'family' => 'notices',
                'purpose' => __('Text color of an info notice.', 'sparkcore-commerce'),
                'fallback' => '#1e3a8a',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-info-border-color',
                'family' => 'notices',
                'purpose' => __('Border color of an info notice.', 'sparkcore-commerce'),
                'fallback' => '#bfdbfe',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-success-bg',
                'family' => 'notices',
                'purpose' => __('Background of a success notice.', 'sparkcore-commerce'),
                'fallback' => '#f0fdf4',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-success-text-color',
                'family' => 'notices',
                'purpose' => __('Text color of a success notice.', 'sparkcore-commerce'),
                'fallback' => '#14532d',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-success-border-color',
                'family' => 'notices',
                'purpose' => __('Border color of a success notice.', 'sparkcore-commerce'),
                'fallback' => '#bbf7d0',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-warning-bg',
                'family' => 'notices',
                'purpose' => __('Background of a warning notice.', 'sparkcore-commerce'),
                'fallback' => '#fffbeb',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-warning-text-color',
                'family' => 'notices',
                'purpose' => __('Text color of a warning notice.', 'sparkcore-commerce'),
                'fallback' => '#78350f',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-warning-border-color',
                'family' => 'notices',
                'purpose' => __('Border color of a warning notice.', 'sparkcore-commerce'),
                'fallback' => '#fde68a',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-error-bg',
                'family' => 'notices',
                'purpose' => __('Background of an error notice.', 'sparkcore-commerce'),
                'fallback' => '#fef2f2',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-error-text-color',
                'family' => 'notices',
                'purpose' => __('Text color of an error notice.', 'sparkcore-commerce'),
                'fallback' => '#7f1d1d',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-notice-error-border-color',
                'family' => 'notices',
                'purpose' => __('Border color of an error notice.', 'sparkcore-commerce'),
                'fallback' => '#fecaca',
                'evidence' => 'geen bewezen Breakdance-global; letterlijke fallback',
            ],
            // ------------------------------------------------------------------
            // forms/inputs (default/focus/error)
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-input-bg',
                'family' => 'forms',
                'purpose' => __('Background of an input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-background-color, #ffffff)',
                'evidence' => '--bde-form-input-background-color: plugin/global-styles/other/global-css-vars.css.twig:157',
            ],
            [
                'name' => '--bde-fc-input-text-color',
                'family' => 'forms',
                'purpose' => __('Text color of an input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-text-color, #374151)',
                'evidence' => '--bde-form-text-color: plugin/global-styles/other/global-css-vars.css.twig:169',
            ],
            [
                'name' => '--bde-fc-input-border-color',
                'family' => 'forms',
                'purpose' => __('Border color of an input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-border-color, #d1d5db)',
                'evidence' => '--bde-form-input-border-color: plugin/global-styles/other/global-css-vars.css.twig:164',
            ],
            [
                'name' => '--bde-fc-input-border-radius',
                'family' => 'forms',
                'purpose' => __('Border radius of an input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-border-radius, 3px)',
                'evidence' => '--bde-form-input-border-radius: plugin/global-styles/other/global-css-vars.css.twig:156',
            ],
            [
                'name' => '--bde-fc-input-border-width',
                'family' => 'forms',
                'purpose' => __('Border width of an input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-border-width, 1px)',
                'evidence' => '--bde-form-input-border-width: plugin/global-styles/other/global-css-vars.css.twig:163',
            ],
            [
                'name' => '--bde-fc-input-placeholder-color',
                'family' => 'forms',
                'purpose' => __('Color of the placeholder text in an input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-placeholder-color, #9ca3af)',
                'evidence' => '--bde-form-input-placeholder-color: plugin/global-styles/other/global-css-vars.css.twig:162',
            ],
            [
                'name' => '--bde-fc-input-focus-bg',
                'family' => 'forms',
                'purpose' => __('Background of a focused input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-focused-background-color, #ffffff)',
                'evidence' => '--bde-form-input-focused-background-color: plugin/global-styles/other/global-css-vars.css.twig:171',
            ],
            [
                'name' => '--bde-fc-input-focus-border-color',
                'family' => 'forms',
                'purpose' => __('Border color of a focused input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-focused-border-color, #2563eb)',
                'evidence' => '--bde-form-input-focused-border-color: plugin/global-styles/other/global-css-vars.css.twig:372',
            ],
            [
                'name' => '--bde-fc-input-focus-shadow',
                'family' => 'forms',
                'purpose' => __('Shadow of a focused input field.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-input-focused-shadow, none)',
                'evidence' => '--bde-form-input-focused-shadow: plugin/global-styles/other/global-css-vars.css.twig:373',
            ],
            [
                'name' => '--bde-fc-input-error-border-color',
                'family' => 'forms',
                'purpose' => __('Border color of an input field in an error state.', 'sparkcore-commerce'),
                'fallback' => '#dc2626',
                'evidence' => 'geen bewezen Breakdance-global voor invoerveld-foutstatus; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-input-error-text-color',
                'family' => 'forms',
                'purpose' => __('Text color of an error message below an input field.', 'sparkcore-commerce'),
                'fallback' => '#7f1d1d',
                'evidence' => 'geen bewezen Breakdance-global voor invoerveld-foutstatus; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-label-color',
                'family' => 'forms',
                'purpose' => __('Text color of field labels.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-text-color, #374151)',
                'evidence' => '--bde-form-text-color: plugin/global-styles/other/global-css-vars.css.twig:169',
            ],
            [
                'name' => '--bde-fc-label-required-color',
                'family' => 'forms',
                'purpose' => __('Color of the required-field indicator.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-label-required-color, #b91c1c)',
                'evidence' => '--bde-form-label-required-color: plugin/global-styles/other/global-css-vars.css.twig:166',
            ],
            [
                'name' => '--bde-fc-label-font-weight',
                'family' => 'forms',
                'purpose' => __('Font weight of field labels.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-label-font-weight, 500)',
                'evidence' => '--bde-form-label-font-weight: plugin/global-styles/other/global-css-vars.css.twig:165',
            ],
            [
                'name' => '--bde-fc-form-gap',
                'family' => 'forms',
                'purpose' => __('Verticale ruimte tussen formuliervelden.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-gap, 16px)',
                'evidence' => '--bde-form-gap: plugin/global-styles/other/global-css-vars.css.twig:153',
            ],
            // ------------------------------------------------------------------
            // checkout-secties
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-checkout-section-bg',
                'family' => 'checkout',
                'purpose' => __('Background of a checkout section panel (for example shipping address).', 'sparkcore-commerce'),
                'fallback' => '#ffffff',
                'evidence' => '--bde-background-color bestaat (global-css-vars.css.twig:82) maar is de paginabrede achtergrond, niet een paneel-achtergrond; hergebruik zou het paneel laten wegvallen tegen de pagina, dus letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-checkout-section-border-color',
                'family' => 'checkout',
                'purpose' => __('Border color of a checkout section panel.', 'sparkcore-commerce'),
                'fallback' => '#e5e7eb',
                'evidence' => 'geen bewezen Breakdance-global voor paneelranden; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-checkout-section-heading-color',
                'family' => 'checkout',
                'purpose' => __('Color of checkout section headings.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-headings-color, #111827)',
                'evidence' => '--bde-headings-color: plugin/global-styles/other/global-css-vars.css.twig:80',
            ],
            [
                'name' => '--bde-fc-checkout-section-gap',
                'family' => 'checkout',
                'purpose' => __('Verticale ruimte tussen checkout-secties.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-form-gap, 16px)',
                'evidence' => '--bde-form-gap: plugin/global-styles/other/global-css-vars.css.twig:153 (hergebruikt voor consistent ritme, geen los bde-checkout-token bewezen)',
            ],
            [
                'name' => '--bde-fc-checkout-payment-box-bg',
                'family' => 'checkout',
                'purpose' => __('Background of the payment method frame.', 'sparkcore-commerce'),
                'fallback' => '#f9fafb',
                'evidence' => 'alleen --bde-woo-payment-box-background-color bestaat (breakdance-woocommerce.css), WooCommerce-scoped en niet gegarandeerd aanwezig; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-checkout-payment-box-border-color',
                'family' => 'checkout',
                'purpose' => __('Border color of the payment method frame.', 'sparkcore-commerce'),
                'fallback' => '#e5e7eb',
                'evidence' => 'alleen --bde-woo-payment-box-border-color bestaat, WooCommerce-scoped; letterlijke fallback',
            ],
            // ------------------------------------------------------------------
            // drawer/mini-cart
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-drawer-bg',
                'family' => 'drawer',
                'purpose' => __('Background of the mini cart drawer.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-background-color, #ffffff)',
                'evidence' => '--bde-background-color: plugin/global-styles/other/global-css-vars.css.twig:82 (drawer is een paginabreed paneel, hergebruik is hier wel zinnig)',
            ],
            [
                'name' => '--bde-fc-drawer-text-color',
                'family' => 'drawer',
                'purpose' => __('Text color inside the mini cart drawer.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-body-text-color, #374151)',
                'evidence' => '--bde-body-text-color: plugin/global-styles/other/global-css-vars.css.twig:79',
            ],
            [
                'name' => '--bde-fc-drawer-heading-color',
                'family' => 'drawer',
                'purpose' => __('Color of the drawer heading (for example Cart).', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-headings-color, #111827)',
                'evidence' => '--bde-headings-color: plugin/global-styles/other/global-css-vars.css.twig:80',
            ],
            [
                'name' => '--bde-fc-drawer-border-color',
                'family' => 'drawer',
                'purpose' => __('Border color of the drawer and the dividers between line items.', 'sparkcore-commerce'),
                'fallback' => '#e5e7eb',
                'evidence' => 'geen bewezen Breakdance-global voor drawer-randen; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-drawer-overlay-bg',
                'family' => 'drawer',
                'purpose' => __('Background of the overlay behind an open drawer.', 'sparkcore-commerce'),
                'fallback' => 'rgba(17, 24, 39, 0.5)',
                'evidence' => 'geen bewezen Breakdance-global voor overlays; letterlijke fallback',
            ],
            [
                'name' => '--bde-fc-drawer-close-icon-color',
                'family' => 'drawer',
                'purpose' => __('Color of the drawer close icon.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-body-text-color, #374151)',
                'evidence' => '--bde-body-text-color: plugin/global-styles/other/global-css-vars.css.twig:79',
            ],
            // ------------------------------------------------------------------
            // variations (rustende/geselecteerde staat van de variatiekiezer,
            // FC_Product_Variations). Vervangt drie vars die bd-elements/
            // FC_Product_Variations/default.css al gebruikte
            // (--bde-fc-accent-color, --bde-fc-border-color,
            // --bde-fc-surface-muted-color) zonder ze ooit in dit schema te
            // registreren: ze vielen dus altijd terug op hun letterlijke
            // fallback en waren onbereikbaar voor een control. Zelfde
            // letterlijke fallback-waarden hergebruikt, alleen de naam is
            // genormaliseerd naar de --bde-fc-variation-* familie, dus de
            // visuele default-uitkomst verandert niet.
            // ------------------------------------------------------------------
            [
                'name' => '--bde-fc-variation-bg',
                'family' => 'variations',
                'purpose' => __('Background of the variation picker in its resting state (for example the toggle rail).', 'sparkcore-commerce'),
                'fallback' => '#f1f5f9',
                'evidence' => 'geen bewezen Breakdance-global voor de variatiekiezer; hergebruikt de letterlijke waarde van de voorheen ongeregistreerde --bde-fc-surface-muted-color.',
            ],
            [
                'name' => '--bde-fc-variation-text-color',
                'family' => 'variations',
                'purpose' => __('Text color of a variation option in its resting state.', 'sparkcore-commerce'),
                'fallback' => 'var(--bde-fc-text-color, #374151)',
                'evidence' => 'hergebruikt het reeds geregistreerde plugin-eigen --bde-fc-text-color (text-familie, dit schema), geen Breakdance-native global; geen dubbele tokenbetekenis nodig voor rustende tekstkleur.',
            ],
            [
                'name' => '--bde-fc-variation-border-color',
                'family' => 'variations',
                'purpose' => __('Border color of a variation option and of the dropdown fallback in their resting state.', 'sparkcore-commerce'),
                'fallback' => '#cbd5e1',
                'evidence' => 'geen bewezen Breakdance-global voor de variatiekiezer; hergebruikt de letterlijke waarde van de voorheen ongeregistreerde --bde-fc-border-color.',
            ],
            [
                'name' => '--bde-fc-variation-selected-bg',
                'family' => 'variations',
                'purpose' => __('Background of the selected/active variation option.', 'sparkcore-commerce'),
                'fallback' => '#3157d5',
                'evidence' => 'geen bewezen Breakdance-global voor de variatiekiezer; hergebruikt de letterlijke waarde van de voorheen ongeregistreerde --bde-fc-accent-color (gebruikt als achtergrond).',
            ],
            [
                'name' => '--bde-fc-variation-selected-text-color',
                'family' => 'variations',
                'purpose' => __('Text color of the selected/active variation option.', 'sparkcore-commerce'),
                'fallback' => '#ffffff',
                'evidence' => 'geen bewezen Breakdance-global voor de variatiekiezer; hergebruikt de voorheen hardcoded letterlijke waarde color:#fff van de actieve/geselecteerde staat.',
            ],
            [
                'name' => '--bde-fc-variation-selected-border-color',
                'family' => 'variations',
                'purpose' => __('Border color of the selected/active variation option.', 'sparkcore-commerce'),
                'fallback' => '#3157d5',
                'evidence' => 'geen bewezen Breakdance-global voor de variatiekiezer; hergebruikt de letterlijke waarde van de voorheen ongeregistreerde --bde-fc-accent-color (gebruikt als randkleur).',
            ],
        ];
    }

    /**
     * Renders the full :root token block plus any deprecated aliases.
     *
     * This is the single generator function: assets/fcbd-tokens.css must always be byte for
     * byte what this method returns. Regenerate it with the command in docs/tokens.md par. 5
     * after any change to definitions() or deprecatedAliases().
     */
    public static function css(): string
    {
        $lines = [];
        $lines[] = '/*';
        $lines[] = ' * SparkCore Commerce, design tokens.';
        $lines[] = ' * Gegenereerd door src/Design/Tokens.php. Niet handmatig bewerken.';
        $lines[] = ' * schema_version: ' . self::SCHEMA_VERSION;
        $lines[] = ' * Regenereren: zie docs/tokens.md par. 5.';
        $lines[] = ' */';
        $lines[] = ':root {';

        foreach (self::definitions() as $token) {
            $lines[] = '    ' . $token['name'] . ': ' . $token['fallback'] . ';';
        }

        foreach (self::deprecatedAliases() as $oldName => $currentName) {
            $lines[] = '    ' . $oldName . ': var(' . $currentName . ');';
        }

        $lines[] = '}';

        return implode("\n", $lines) . "\n";
    }
}