Feature: Add Support for Component Variations

[khabubuphathu]

Summary

Introduce structured support for component variations (variants) in DESIGN.md to allow more expressive, scalable, and semantically rich component definitions beyond flat key-based naming.

Motivation

Currently, component variants (e.g. hover, active, size variations) are represented as separate component entries using naming conventions:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

Proposal

Add a variants field under components to explicitly model variations:

components:
  button:
    base:
      backgroundColor: "{colors.tertiary}"
      textColor: "{colors.on-tertiary}"
      rounded: "{rounded.sm}"
      padding: 12px

    variants:
      intent:
        primary:
          backgroundColor: "{colors.tertiary}"
        secondary:
          backgroundColor: "{colors.secondary}"

      size:
        sm:
          padding: 8px
        md:
          padding: 12px
        lg:
          padding: 16px

      state:
        hover:
          backgroundColor: "{colors.tertiary-container}"
        active:
          backgroundColor: "{colors.primary}"
        disabled:
          backgroundColor: "{colors.neutral}"

[kssque]

Thanks for opening this. Adopting DESIGN.md on a Next.js project, the proposal would cover most of what I hit — size variants, pseudo-class states — cleanly. One case seems structurally different and worth flagging.

Use-case-driven states (e.g. loading, submitting). The visuals fit variants.state.loading fine, but the trigger — "async user-initiated action in progress" — is a use case concept, not a CSS pseudo-class like hover. There's no place in the schema to record what drives the transition, which means the visual half of the state is specified and the conditional half isn't.

To check this empirically, I fed a spec-compliant DESIGN.md (lint-clean, using the current sibling-key pattern — button-primary-loading as a separate component entry) to two different agents and asked each for a "schedule newsletter" page. Both reproduced the default button. But the loading behavior diverged:

• Agent A implemented the loading visuals and wrapped the click handler in a mocked setTimeout with // TODO comments for the real async wiring.
• Agent B implemented no loading behavior. No spinner, no color shift, no state handling.

One small addition to the schema could help agents reproduce the state transition more consistently, even in mockup form: a human-readable description field that anchors the state to a semantic trigger.

Not a handler (wrong layer for a declarative, framework-agnostic format), but something agents can read as "this state is meant to appear when X happens" — enough to build a demo trigger against, even when real async wiring is out of scope:

variants:
  state:
    loading:
      backgroundColor: "{colors.tertiary}"
      textOpacity: 0.6
      triggerDescription: "async user-initiated action in progress"

Context: in-house engineer, solo across roles. Reporting as usage signal, not counter-proposal.

[adamschnaare]

Thought. What about simply allowing more specificity via naming convention? I'd be leary to embed specific logic or structure, as it can begin to define intent in a very opinionated way, perhaps not suited for a spec of this nature.

Would it be possible to follow a pattern like this, simply overriding as things get more specific?

components:
    button:
        backgroundColor: "{colors.primary}"        
    button-primary:
        backgroundColor: "{colors.tertiary}"
    button-primary-hover:
        backgroundColor: "{colors.foo}"
    button-primary-active:
        backgroundColor: "{colors.bar}"
    button-primary-sm:
        backgroundColor: "{colors.foo2}"
    button-primary-sm-hover:
        backgroundColor: "{colors.bar2}"

[khabubuphathu]

It could work but want if you have compond components like a button and button group or a checbox and checkbox group. This would mean group would be a variant of checkbox/button which is wrong,

components:
    button:
        backgroundColor: "{colors.primary}"        
    button-group:
        backgroundColor: "{colors.tertiary}"
    checkbox:
        backgroundColor: "{colors.foo}"
    checkbox-group:
        backgroundColor: "{colors.bar}"

Or we could use double-colon to denote the section after the colon is a variant .ie

components:
    button:
        backgroundColor: "{colors.primary}"        
    button::primary:
        backgroundColor: "{colors.tertiary}"
    button::primary-hover:
        backgroundColor: "{colors.foo}"
    button::primary-active:
        backgroundColor: "{colors.bar}"
    button::primary-sm:
        backgroundColor: "{colors.foo2}"
    button::primary-sm-hover:
        backgroundColor: "{colors.bar2}"

[davideast]

This is really interesting. I need to take some time and consider how it would support the prose. I'll post back here over the new day or so with some ideas.