Skip to content

feat(validation): add conservative diagnostics for selector- and condition-scoped token references #30

Description

@Hebilicious

Motivation

#25 documents a concrete example where a root-level alias references palette variables emitted only under .Another. The reference is valid only under additional DOM or external-CSS assumptions that the configuration does not communicate.

The current ResolveMap in lib.ts retains key, value, and variable, but not the selector/at-rule context in which the declaration is emitted.

Retaining that context would allow useful warnings without trying to replace the browser's cascade or solve arbitrary selector relationships.

Proposed behavior

For a root alias whose only configured source declaration is restricted to .Another, report something like:

Token theme.dark.background.primary is emitted at :root under
@media (prefers-color-scheme: dark), but its referenced token
palette.another.yellow is only emitted under .Another.

The source must be available on the element where the alias is computed.
This configuration requires .Another to match the root, or an external
source declaration at that location.

Treat this as a potential availability problem, not proof that the final application CSS is invalid. The application may deliberately supply external declarations or specific root classes.

Initial scope

  • Retain declaration context and provenance during token processing.
  • Compare straightforward cases: identical contexts, an unconditional root source consumed by a descendant, a root consumer with only a selector-restricted source, and a broader consumer with only a conditionally available source.
  • Warn for assumptions the generator cannot establish; leave arbitrary selector implication and complex media-query reasoning out of scope.
  • Reuse or extend the token metadata work in Add Style Dictionary token output #20 rather than introducing a second incompatible representation.

Acceptance criteria

  • Diagnostics include both configuration paths, generated property names, selectors, and at-rule contexts.
  • Same-context references and ordinary inheritance from unconditional root sources do not trigger false-positive scope warnings.
  • Root-to-selector-only references produce an actionable warning with the required assumptions.
  • Simple conditional-availability cases are covered without labeling every pair of different conditions incompatible.
  • External/unmapped native CSS references are preserved and handled as unknown, not categorically invalid.
  • Warnings are nonbreaking by default; an optional strict mode and a targeted suppression mechanism are documented.
  • Tests assert structured diagnostics as well as CLI output.
  • The feature remains build-time-only and does not require a Vue/React adapter.

This is separate from correcting the existing example in #25.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions