@bridge-ds/core 0.17.0 → 0.19.0

package/dist/layered-review.d.ts

@@ -84,5 +84,7 @@ export interface ProposalBodyInput {
     /** "Bridge MCP", "the bridge CLI". */
     tool?: string;
     author?: string;
+    /** Pushed from the Figma plugin: design-approved, the tier line says what happens next (docs/BUILD-REQUESTS.md). */
+    fromFigma?: boolean | undefined;
 }
 export declare function composeProposalBody(args: ProposalBodyInput): string;

package/dist/measure-status.d.ts

@@ -0,0 +1,127 @@
+import type { SpecPart, SpecVariant } from './component-spec';
+import { type FieldDiff, type MeasuredArgType, type MeasuredSpecsStory, type MeasuredState } from './measured-spec';
+export interface VariantMeasure {
+    /** Args passed to the story (`{ variant: 'danger', size: 'lg', disabled: true }`). */
+    overrides: Record<string, string | number | boolean>;
+    /** Pseudo state forced on the component; absent at rest and for disabled (an arg). */
+    state?: MeasuredState | undefined;
+}
+export interface PlanVariantOptions {
+    /** Props to vary; default every enum prop (2 to 12 options) that is not wiring (`as`, `type`, `className`...). */
+    axes?: string[] | undefined;
+    /** Exact values per prop (from a Figma mapping: variantValuesFromMapping); replaces `axes`. Booleans vary too. */
+    values?: Record<string, (string | boolean)[]> | undefined;
+    /** Exact prop combinations (variantCombosFromMapping); replaces `values` and `axes`. */
+    combos?: Record<string, string | boolean>[] | undefined;
+    /** States to measure on each combination (default rest, hover, disabled). */
+    states?: ('rest' | MeasuredState | 'disabled')[] | undefined;
+    /** At most this many measures (default 128); the axes are kept, states are dropped first. */
+    max?: number | undefined;
+}
+/**
+ * Every variant to measure for a component, from its argTypes: the cartesian product of its enum props, times the
+ * states (hover, focus and active forced in Chrome, disabled as an arg when the component has a disabled prop).
+ */
+export declare function planVariantMeasures(argTypes: Record<string, MeasuredArgType>, o?: PlanVariantOptions): VariantMeasure[];
+/**
+ * The prop combinations a Figma component's variants mean in code (State aside): the product of its VARIANT axes,
+ * each value with the props it sets (Checked=mixed sets `checked: false, indeterminate: true`). Unmapped values are left out.
+ */
+export declare function variantCombosFromMapping(mapping: PropsToFigma): Record<string, string | boolean>[];
+/**
+ * The prop combinations to measure for some axes, at most `cap`: the full product when it fits; else every value of
+ * each axis alone (the others at their first value), then every pair of axes, until the cap. `capped` says the full
+ * product was not measured.
+ */
+export declare function boundedCombos(axes: [string, (string | boolean)[]][], cap?: number): {
+    combos: Record<string, string | boolean>[];
+    capped: boolean;
+};
+/** The values to measure per prop for a Figma component: its VARIANT axes mapped to props (State aside). */
+export declare function variantValuesFromMapping(mapping: PropsToFigma): Record<string, (string | boolean)[]>;
+/** A Figma component property as the plugin reads it (componentPropertyDefinitions) or the specs write it. */
+export interface FigmaPropertyRef {
+    name: string;
+    type: 'VARIANT' | 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP' | string;
+    /** VARIANT values. */
+    values?: string[] | undefined;
+    default?: unknown;
+}
+export interface PropMapping {
+    figma: string;
+    type: FigmaPropertyRef['type'];
+    /** The code prop, or `state` for a Figma State axis (pseudo states and disabled). */
+    prop: string;
+    /** VARIANT: Figma value -> code value. Missing values are listed in `unmatchedValues`. */
+    values?: Record<string, string | boolean> | undefined;
+    /** VARIANT values that also set other props (Checked=mixed: `{ indeterminate: true }`). */
+    also?: Record<string, Record<string, string | boolean>> | undefined;
+    unmatchedValues?: string[] | undefined;
+}
+export interface PropsToFigma {
+    mapped: PropMapping[];
+    /** Figma properties with no code prop ("tone has no prop in code"). */
+    figmaOnly: string[];
+    /** Enum and boolean props with no Figma property. */
+    codeOnly: string[];
+}
+/**
+ * Maps Figma component properties to code props by name (case, spaces and dashes ignored; `is` prefixes and `Show x`
+ * booleans folded), VARIANT values to enum options the same way, and a Figma `State` axis to pseudo states and the
+ * disabled prop.
+ */
+export declare function mapPropsToFigma(argTypes: Record<string, MeasuredArgType>, figma: FigmaPropertyRef[]): PropsToFigma;
+export type ComponentCheck = 'matches' | 'differs' | 'cant-check';
+/** Why a component can't be checked yet: a closed list, so the copy stays honest. */
+export type CantCheckReason = 'no-story' | 'did-not-render' | 'no-token-variables' | 'popup-closed' | 'no-figma' | 'prop-unmapped' | 'no-story-for-variant';
+export declare const CANT_CHECK_COPY: Record<CantCheckReason, string>;
+export interface VariantCheck {
+    /** Figma variant key ("Size=md, State=Hover"). */
+    key: string;
+    status: ComponentCheck;
+    /** Story measured for it. */
+    story?: string | undefined;
+    reason?: CantCheckReason | undefined;
+    diffs?: FieldDiff[] | undefined;
+    compared?: number | undefined;
+}
+export interface ComponentStatus {
+    name: string;
+    status: ComponentCheck;
+    /** Can't check yet: why (closed list) and the sentence to show. */
+    reason?: CantCheckReason | undefined;
+    /** One sentence in designer words: the first difference, or the reason with its detail. */
+    summary: string;
+    detail?: string | undefined;
+    variants: VariantCheck[];
+    mapping?: PropsToFigma | undefined;
+    /** Share of measured values tied to a declared CSS variable. */
+    tokenShare?: number | undefined;
+}
+/** The Figma side of a component, in the spec shape: what the plugin reads from the Figma set (or the specs it was drawn from). */
+export interface FigmaComponentRef {
+    properties: FigmaPropertyRef[];
+    parts: SpecPart[];
+    variants: Pick<SpecVariant, 'props' | 'values'>[];
+}
+export interface ComponentStatusInput {
+    name: string;
+    /** The component's measured stories (any args and states). */
+    stories: MeasuredSpecsStory[];
+    argTypes?: Record<string, MeasuredArgType> | undefined;
+    figma?: FigmaComponentRef | undefined;
+    /** Token path -> resolved value in the measured page, for value-level agreement. */
+    resolve?: ((tokenPath: string) => string | number | undefined) | undefined;
+    /** No Figma set of this name, but sets drawn from it open (Dialog/Popup): named in the reason. */
+    figmaSets?: string[] | undefined;
+    /** Below this share of values tied to CSS variables, the library has no tokens to check (default 0.1). */
+    minTokenShare?: number | undefined;
+}
+/** A difference in designer words: "Left padding is 6 px in code, 8 px in Figma (label)". */
+export declare function describeDiff(d: FieldDiff): string;
+/**
+ * One component's status from its measured stories and its Figma side. The order of the checks is the order a team
+ * fixes them in: something to measure, tokens to bind, a Figma component, props that name its variants, a story per
+ * variant, then the values.
+ */
+export declare function componentStatus(input: ComponentStatusInput): ComponentStatus;

package/dist/measured-only.d.ts

@@ -0,0 +1,28 @@
+import { type ComponentSpecsFile } from './component-spec';
+import type { FigmaHints, FixedMeasuredSpecsFile } from './figma-fixes';
+import { type MeasuredSpecsFile } from './measured-spec';
+/** What building from the measure gave: sets, variants, and the stories it used. */
+export interface MeasuredOnlyReport {
+    sets: number;
+    variants: number;
+    stories: number;
+    /** Components with stories that gave no set (every story failed, or none at rest). */
+    skipped: string[];
+}
+/** The screenshot of the story a variant was built from (`--shots`), path relative to measured-specs.json. */
+export interface VariantShot {
+    file: string;
+    width: number;
+    height: number;
+}
+/** Set name -> variant key (variantKeyOf) -> its story's screenshot: the reference Check fidelity compares with. */
+export type MeasuredShots = Record<string, Record<string, VariantShot>>;
+/** Every set the measure can give, by component (the last segment of a story's title: "Figma variants/Radio" is Radio). */
+export declare function specsFromMeasure(file: MeasuredSpecsFile | FixedMeasuredSpecsFile, opts?: {
+    known?: ((path: string) => boolean) | undefined;
+}): {
+    specs: ComponentSpecsFile;
+    report: MeasuredOnlyReport;
+    shots: MeasuredShots;
+    hints: Record<string, FigmaHints>;
+};

package/dist/measured-spec.d.ts

@@ -0,0 +1,349 @@
+import type { SpecField, SpecLayout, SpecPart, SpecValue, SpecVariant, SpecVector } from './component-spec';
+import type { ComponentStatus } from './measure-status';
+/** How a value was tied to a custom property. */
+export interface MeasuredToken {
+    /**
+     * `declared`: the winning CSS declaration uses the variable (strong). `matched`: no declaration does, but the value
+     * equals a variable defined on the root (weak: several tokens can share a value).
+     */
+    via: 'declared' | 'matched';
+    /** declared: the variable the declaration names, then what it aliases (`--button-bg`, `--color-action-primary-bg`). matched: up to 3 candidates. */
+    chain: string[];
+    /** declared: the declaration is the variable alone (`var(--x)`), not a calc() or a function of it. */
+    exact: boolean;
+    /** declared: the declaration text (`var(--space-2) var(--space-3)` piece for this side). */
+    declared?: string | undefined;
+}
+export interface MeasuredBox {
+    /** Relative to the measured root's top-left corner, CSS pixels. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MeasuredNode {
+    /** Tag name, `#text` for a text run inside an element that also holds elements. */
+    tag: string;
+    kind: 'frame' | 'text' | 'icon' | 'vector';
+    /** Width or height set by the CSS (not auto, a percentage or content-sized). */
+    sized?: {
+        width?: boolean | undefined;
+        height?: boolean | undefined;
+    } | undefined;
+    /** Inline SVG: each shape's stroke in order (rgb), as drawn. */
+    svgStrokes?: string[] | undefined;
+    /** A ::before or ::after drawn as a box (a switch knob, a checkbox's box): its tag is `::before` / `::after`. */
+    pseudo?: 'before' | 'after' | undefined;
+    classes?: string[] | undefined;
+    role?: string | undefined;
+    /** State attributes (data-state, data-variant, aria-checked...). */
+    attrs?: Record<string, string> | undefined;
+    box: MeasuredBox;
+    /** Computed values of the properties the measure reads (display, flex, padding, colors, fonts...). */
+    style: Record<string, string>;
+    /** CSS property -> the token behind its value. */
+    tokens: Record<string, MeasuredToken>;
+    /** Text layers: the characters. */
+    text?: string | undefined;
+    /** Icons and vectors: their markup when short. */
+    svg?: string | undefined;
+    media?: boolean | undefined;
+    input?: {
+        type: string;
+        value: string;
+        placeholder: string;
+        checked: boolean;
+    } | undefined;
+    /** Node or depth limit reached under this node. */
+    truncated?: boolean | undefined;
+    /** A gallery's instance (splitInstances): where its box sat in the story's root before it was re-based. */
+    at?: {
+        x: number;
+        y: number;
+    } | undefined;
+    children: MeasuredNode[];
+}
+/** A measure in the Figma pull's shape: the parts of one variant and their field values, plus what a spec leaves out. */
+/** Figma alignment of one child in its parent's auto layout, relative to the parent's direction. */
+export interface MeasuredChildAlign {
+    primary?: 'MIN' | 'CENTER' | 'MAX' | undefined;
+    counter?: 'MIN' | 'CENTER' | 'MAX' | undefined;
+}
+/** A measured auto layout: the spec layout, plus per child alignment for out-of-flow decorations rebuilt in it. */
+export interface MeasuredLayout extends SpecLayout {
+    /** Child part id -> its alignment; the parent's padding (in `values`) carries the offset. */
+    align?: Record<string, MeasuredChildAlign> | undefined;
+}
+/** A measured part: a spec part, plus what auto layout needs to rebuild margins, overlays and decorations. */
+export interface MeasuredPart extends SpecPart {
+    layout?: MeasuredLayout | undefined;
+    /** Out of flow and over its siblings or outside its parent (a popover, a badge, a focus ring): absolute in Figma, never in the size. */
+    overlay?: boolean | undefined;
+    /** Margins the part has (px, non-zero sides). */
+    margins?: {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    } | undefined;
+    /** Uneven margins between siblings: wrap the part in a frame with this padding. */
+    wrap?: {
+        padding: {
+            top?: number | undefined;
+            right?: number | undefined;
+            bottom?: number | undefined;
+            left?: number | undefined;
+        };
+    } | undefined;
+    /** The radius is half the shorter side or more: a pill or a circle (its value is 999 px, or the token it is bound to). */
+    fullRadius?: boolean | undefined;
+}
+export interface MeasuredSpec {
+    story: string;
+    parts: MeasuredPart[];
+    /** Part id -> field -> token path (declared token), number (px or unitless literal) or null (no paint). */
+    values: SpecVariant['values'];
+    /** Part id -> field -> the computed value (`rgb(31, 41, 55)`, 16). Colors without a token only live here. */
+    raw: Record<string, Partial<Record<SpecField, string | number>>>;
+    /** Part id -> field -> the token evidence (declared chain or value match). */
+    tokens: Record<string, Partial<Record<SpecField, MeasuredToken>>>;
+    /** Part id -> its measured box. */
+    boxes: Record<string, MeasuredBox>;
+    /** Fields read, and how many are tied to a declared token, to a value match, or to none. */
+    coverage: {
+        fields: number;
+        declared: number;
+        matched: number;
+        literal: number;
+    };
+    /**
+     * Part id -> the SVG an icon or vector part draws, `currentColor` resolved to the part's color, and the value of each
+     * shape's stroke in order. The pull draws it in place of an empty icon frame.
+     */
+    vectors?: Record<string, SpecVector> | undefined;
+    /** Part id -> the width and height its CSS sets (px): keep them fixed, do not hug (a 40x40 icon button around a 16 px icon). */
+    sized?: Record<string, {
+        width?: number | undefined;
+        height?: number | undefined;
+    }> | undefined;
+    /**
+     * Part id -> extra space before it in its parent's auto layout (px), when the gaps between children are not uniform
+     * (margins): the parent's itemSpacing is the smallest gap, this is what a child adds on top.
+     */
+    spacers?: Record<string, number> | undefined;
+}
+export interface FieldDiff {
+    part: string;
+    field: SpecField;
+    /** The static spec's value (token path, number, null), undefined when the static spec has no value there. */
+    static?: SpecValue | undefined;
+    /** The measured value: token path when declared, else the raw value. Undefined when the field was not measured. */
+    measured?: SpecValue | undefined;
+    /** Same token, or same resolved value. */
+    same: boolean;
+}
+export interface SpecComparison {
+    /** Static parts matched to a measured part (by CSS class, then by kind and order). */
+    partsMatched: number;
+    staticParts: number;
+    measuredParts: number;
+    /** Fields both sides have. */
+    compared: number;
+    same: number;
+    /** Fields where both name a token and it is the same token. */
+    sameToken: number;
+    diffs: FieldDiff[];
+    /** Static parts no measured part matches (hidden optional parts, or parts the static guess invented). */
+    unmatchedParts: string[];
+    /** Static fields with no measured counterpart, measured fields the static spec misses. */
+    staticOnly: number;
+    measuredOnly: number;
+    /** Width and height, root part: static (when a number) vs measured, px. */
+    rootSize?: {
+        static: {
+            width?: number | undefined;
+            height?: number | undefined;
+        };
+        measured: {
+            width: number;
+            height: number;
+        };
+    } | undefined;
+}
+/** A spec calc() of token paths (`calc(control.height.sm - border-width.default * 2)`) in px, from resolved tokens. */
+export declare function evalCalc(expr: string, resolve: (tokenPath: string) => string | number | undefined): number | undefined;
+export interface PairOptions {
+    /** The component's properties: a text part bound to a TEXT property is paired by that property's default text. */
+    properties?: {
+        name: string;
+        type: string;
+        default?: unknown;
+    }[] | undefined;
+}
+/**
+ * The parts without the wrappers the pull adds around one part (`<part>-wrapper`: a margin Figma's one gap per frame
+ * cannot give). The render has no such element: the part inside stands for it, under the wrapper's parent.
+ */
+export declare function withoutAddedWrappers(parts: SpecPart[], measured: Pick<MeasuredSpec, 'parts'>): SpecPart[];
+/**
+ * Pairs static parts with measured parts: root to root, text layers by their characters (a TEXT property's default, or
+ * fixed characters), then CSS class under the paired parent, then kind and order under the paired parent. A part whose
+ * parent the render does not show is not shown either (an error row's icon is not the checkbox's check).
+ */
+export declare function pairParts(staticParts: SpecPart[], measured: Pick<MeasuredSpec, 'parts'>, o?: PairOptions): Map<string, string>;
+export declare function compareSpecToMeasured(staticParts: SpecPart[], staticValues: SpecVariant['values'], measured: MeasuredSpec, resolve?: (tokenPath: string) => string | number | undefined, o?: PairOptions): SpecComparison;
+/** One component prop as Storybook knows it (argTypes, docgen), read in the preview page. */
+export interface MeasuredArgType {
+    /** `enum`: a closed list of options (a Figma VARIANT axis); `boolean` (a BOOLEAN property or a Disabled state); `text`; `number`; `other` (functions, nodes). */
+    kind: 'enum' | 'boolean' | 'text' | 'number' | 'other';
+    options?: string[] | undefined;
+    /** The component's default (docgen `defaultValue`, or the argType's `table.defaultValue`). */
+    default?: string | number | boolean | undefined;
+    /** Control type (`select`, `radio`, `boolean`, `text`...). */
+    control?: string | undefined;
+}
+/** The props a story rendered with: its args over the component defaults, and the component's prop list. */
+export interface MeasuredProps {
+    /** Args with the component defaults applied (`{ variant: 'primary', size: 'md', disabled: false }`). Plain values only (no null). */
+    props: Record<string, string | number | boolean>;
+    /** The story's own args (initial args plus URL overrides), plain values only. */
+    args: Record<string, string | number | boolean>;
+    argTypes: Record<string, MeasuredArgType>;
+    /** Component display name, when the story names one. */
+    component?: string | undefined;
+}
+export type MeasuredState = 'hover' | 'focus-visible' | 'active';
+export interface MeasuredSpecsStory {
+    id: string;
+    title: string;
+    name: string;
+    url: string;
+    ms: number;
+    error?: string | undefined;
+    spec?: MeasuredSpec | undefined;
+    /** The props the story rendered with (args over component defaults). */
+    props?: MeasuredProps['props'] | undefined;
+    /** Arg overrides Bridge passed to reach a variant (`{ size: 'lg', disabled: true }`); absent for the story as written. */
+    overrides?: Record<string, string | number | boolean> | undefined;
+    /** Pseudo state forced on the component (Chrome DevTools forced :hover / :focus-visible / :active). */
+    state?: MeasuredState | undefined;
+    /** The story is a gallery (several instances): `spec` is its first instance, a fallback when no single-instance story renders the variant. */
+    gallery?: boolean | undefined;
+    /** A story that renders the component several times: one spec per instance (`spec` is the first). */
+    instances?: MeasuredSpec[] | undefined;
+    /** Screenshot of the measured root (PNG, the device scale of the run), relative to measured-specs.json. */
+    shot?: {
+        file: string;
+        width: number;
+        height: number;
+    } | undefined;
+    /** Popup stories: how the popup came to show. */
+    opened?: 'already' | 'click' | 'hover' | 'focus' | 'none' | undefined;
+}
+/** Per Storybook component (title): its prop list, from the first story measured. */
+export interface MeasuredSpecsComponent {
+    title: string;
+    name: string;
+    argTypes: Record<string, MeasuredArgType>;
+    component?: string | undefined;
+    /**
+     * With --variants: the args crossed, the args left out and why (`no visual effect`: changing it from its default
+     * changed nothing the measure reads; `not taken`: the story does not pass it on), and whether the cap cut the product.
+     */
+    variantPlan?: {
+        axes: string[];
+        ignored?: Record<string, string> | undefined;
+        combos: number;
+        capped?: boolean | undefined;
+    } | undefined;
+    /** Token path -> its value in the measured page (colors `rgb()`, lengths px): the tokens the Figma side names. */
+    resolved?: Record<string, string> | undefined;
+}
+export interface MeasuredSpecsFile {
+    version: 1;
+    storybook: string;
+    measuredAt: string;
+    stories: MeasuredSpecsStory[];
+    components?: MeasuredSpecsComponent[] | undefined;
+    /** With --check: one status per component for the contract screen. */
+    statuses?: ComponentStatus[] | undefined;
+    /** Storybook titles measured to the end, for --resume. */
+    done?: string[] | undefined;
+    /** With --tokens: every CSS custom property the library defines, resolved per mode, in two tiers. */
+    tokens?: MeasuredTokens | undefined;
+}
+/** A Storybook global that switches a theme (light / dark), a brand or a density: one Figma mode per value. */
+export interface MeasuredMode {
+    /** Storybook global ("theme", "colorScheme"), or the page attribute a theme hangs on (`data-carbon-theme`). */
+    global: string;
+    /** Set when the mode is an attribute on the page root, not a Storybook global. */
+    attribute?: boolean | undefined;
+    /** Its values, the default first. */
+    values: string[];
+    default: string;
+}
+export interface MeasuredTokenProperty {
+    /** The CSS custom property (`--cds-background`). */
+    name: string;
+    /** Variable name for Figma: the property split on dashes and camel case, library prefix dropped (`background`, `color/fg/default`). */
+    path: string;
+    /** Two tiers: a literal value is a primitive; a property that is another property (`var(--x)`) is semantic. */
+    tier: 'primitive' | 'semantic';
+    /** `expression`: a calc() or a function of variables; a primitive holding its resolved value. */
+    kind: 'literal' | 'alias' | 'expression';
+    type: 'color' | 'length' | 'number' | 'string';
+    /** Declared value in the default mode (`var(--color-blue-500)`, `#0969da`, `calc(var(--a) * 2)`). */
+    raw: string;
+    /** Semantic: the property it aliases in the default mode (`--color-blue-500`). */
+    aliasOf?: string | undefined;
+    /** Resolved value in the default mode: colors `rgb()`/`rgba()`, lengths in px (number), others as written. */
+    value: string | number;
+    /** Per mode (`theme:dark`), for the globals that change this property only (every value of that global listed); `value` holds in the others. */
+    values?: Record<string, string | number> | undefined;
+    /** Per mode: what a semantic property aliases there, when it changes with the mode. */
+    aliasOfByMode?: Record<string, string> | undefined;
+    /** Selectors besides the root that declare it (a provider, a theme class): `.cds--g100`, `[data-color-mode=dark]`. */
+    scopes?: string[] | undefined;
+    /**
+     * Semantic by value: the CSS writes a literal per theme (compiled themes: Primer, Carbon), and in every mode a
+     * primitive holds that same value, so the property is an alias of those primitives.
+     */
+    inferred?: boolean | undefined;
+    /** A measured story's value is tied to it, directly or as the target of an alias it goes through. */
+    used?: boolean | undefined;
+}
+export interface MeasuredTokens {
+    /** Story the variables were read in. */
+    story: string;
+    /** Library prefix stripped from paths (`cds`, `chakra`), when one is shared by most properties. */
+    prefix?: string | undefined;
+    modes: MeasuredMode[];
+    properties: MeasuredTokenProperty[];
+    counts: {
+        properties: number;
+        primitives: number;
+        semantic: number;
+        used: number;
+        scoped: number;
+        inferred?: number | undefined;
+    };
+}
+/**
+ * Figma variable path of a custom property: dashes and camel case split into groups, a shared library prefix dropped
+ * (`--color-fg-default` -> color/fg/default, `--cds-layer-01` with prefix cds -> layer/01, `--fgColor-muted` -> fg/color/muted).
+ */
+export declare function tokenVariablePath(name: string, prefix?: string): string;
+/** The prefix most properties share (`cds`, `chakra`, `bridge`), when at least 60% of 20 or more carry it. */
+export declare function sharedTokenPrefix(names: string[]): string | undefined;
+/**
+ * Marks the properties measured stories use: every variable a value's declaration chain names, then every alias
+ * target of a used property, transitively (a semantic token needs its primitive). Returns how many are used.
+ */
+export declare function markUsedTokens(tokens: MeasuredTokens, stories: Pick<MeasuredSpecsStory, 'spec' | 'instances'>[]): number;
+export declare class MeasuredSpecsError extends Error {
+}
+/**
+ * Reads measured-specs.json (text or parsed JSON) and checks its shape: version 1, a storybook URL, stories with ids,
+ * and specs with parts and values. Throws MeasuredSpecsError with what is wrong.
+ */
+export declare function parseMeasuredSpecsFile(input: string | unknown): MeasuredSpecsFile;

package/dist/measured-tokens.d.ts

@@ -0,0 +1,25 @@
+import type { MeasuredSpecsFile, MeasuredTokens } from './measured-spec';
+export interface TokenRepoFromMeasure {
+    /** Files relative to `root` (`primitives/measured.tokens.json`, `semantic/<mode>.tokens.json`). */
+    files: Record<string, string>;
+    /** bridge.config.json for them. */
+    config: Record<string, unknown>;
+    /** CSS custom property -> token path written (`--cds-layer-01` -> layer.01). */
+    paths: Map<string, string>;
+    report: {
+        primitives: number;
+        semantic: number;
+        palette: number;
+        modes: string[];
+        skipped: string[];
+    };
+}
+/** The two-tier repo for a token harvest (see the top of this file). */
+export declare function tokenRepoFromMeasure(t: MeasuredTokens): TokenRepoFromMeasure;
+/**
+ * The measured specs with their values pointing at the tokens `tokenRepoFromMeasure` wrote: a value the measure named
+ * after its CSS variable (`cds.layer.01`) becomes the written path (`layer.01`), and a field whose declaration is a
+ * variable alone (`var(--cds-button-primary, #0f62fe)`) gets the written path of the first variable of its chain. Other
+ * values are kept: a calc() of a token, or a value that only matches one, stays a literal.
+ */
+export declare function withRepoTokenPaths(file: MeasuredSpecsFile, paths: Map<string, string>): MeasuredSpecsFile;

package/dist/motion-docs.d.ts

@@ -0,0 +1,51 @@
+import { type ComponentSpec, type SpecCoverage, type SpecTransition } from './component-spec';
+/** A motion token as the page shows it: the token name (mono) and its value in words ("75 ms"). */
+export interface MotionValue {
+    token?: string | undefined;
+    value: string;
+}
+export interface MotionRow {
+    /** The part that moves, when the component has several ("Popup", "Checkbox item"). */
+    part?: string | undefined;
+    /** What makes it move, designer words ("Hover", "Open", "Check and uncheck"). */
+    when: string;
+    /** What changes ("Background and text color"). */
+    what: string;
+    duration: MotionValue;
+    easing: MotionValue | null;
+}
+export interface MotionDocs {
+    /** One sentence: what animates, or that nothing does. */
+    summary: string;
+    rows: MotionRow[];
+    /** What reduced motion does, one sentence; null when nothing animates. */
+    reduced: string | null;
+    /** Whether to show a Part column (several parts move). */
+    showPart: boolean;
+    /** Motion tokens the component's CSS uses for motion the rows do not list (a tab indicator sliding). */
+    unlisted: string[];
+}
+/** CSS properties in designer words, joined: ["background-color", "color"] -> "Background and text color". */
+export declare function propertyWords(props: string[]): string;
+/** A duration in ms, with its token. */
+export declare const durationValue: (t: Pick<SpecTransition, "duration" | "durationToken">) => MotionValue;
+/** An easing in words, with its token: motion.easing.enter -> "starts fast, lands softly". */
+export declare function easingValue(t: Pick<SpecTransition, 'easing' | 'easingToken'>): MotionValue;
+/** The part a set draws, in words: "Combobox/Popup" -> "Popup", "MenuCheckboxItem" -> "Checkbox item". */
+export declare function partLabel(spec: Pick<ComponentSpec, 'name' | 'component' | 'view'>, component: string): string;
+/** A moment a set moves: what makes it move ("Hover", "Open"), the transition, the properties it animates. */
+export interface MotionMoment {
+    when: string;
+    t: SpecTransition;
+    props: string[];
+}
+/**
+ * The moments a set moves, from its interactions and its opening and closing: one per trigger and speed (Hover,
+ * Press, Check, Uncheck, Open, Close). Instant changes are left out.
+ */
+export declare function motionMoments(spec: Pick<ComponentSpec, 'name' | 'variants' | 'interactions' | 'motion'>): MotionMoment[];
+/**
+ * The section for one component: its sets (specs whose `component`, or name, is the component), and its Figma coverage
+ * entry for the components the generator does not read (drafted, layout helpers).
+ */
+export declare function motionDocs(component: string, specs: ComponentSpec[], coverage?: Pick<SpecCoverage, 'status' | 'reason'>, codeTokens?: string[]): MotionDocs;

package/dist/node/audit.d.ts

@@ -1,6 +1,6 @@
 import { type BridgeConfig } from '../config';
 import { LayeredTokenSet } from '../layered';
-import { type CssFixEdit } from '../audit/report';
+import { type CssFixEdit, type CssFixKept } from '../audit/report';
 import { DesignSystemIndex } from '../audit/ds-index';
 import type { AllowlistEntry, AuditReport } from '../audit/types';
 export interface LoadedDesignSystem {
@@ -40,8 +40,16 @@ export interface RunAuditOptions {
 export declare function loadAllowlist(path: string): AllowlistEntry[];
 /** Audit a product folder against a design system. */
 export declare function runAudit(target: string, opts?: RunAuditOptions): AuditReport;
-/** Plan (and optionally write) the safe CSS autofix for every CSS/SCSS/Less file under `target`. */
-export declare function fixCss(target: string, ds: DesignSystemIndex, write: boolean): {
+/**
+ * Plan (and optionally write) the safe CSS autofix for every CSS/SCSS/Less file under `target`, with the audit's own
+ * rules: the files bridge.config.json excludes from the audit (audit.exclude) are left alone, and so are the values an
+ * ignore comment or the allowlist keeps (returned in `kept`).
+ */
+export declare function fixCss(target: string, ds: DesignSystemIndex, write: boolean, opts?: {
+    exclude?: string[] | undefined;
+    allowlist?: AllowlistEntry[] | undefined;
+}): {
     file: string;
     edits: CssFixEdit[];
+    kept: CssFixKept[];
 }[];

package/dist/node/index.d.ts

@@ -6,3 +6,4 @@ export * from './spec-css';
 export * from './spec-motion';
 export * from './suggestion-apply-node';
 export * from './fs-source';
+export * from './measure';