Re: [community-group] Multiple values - Array type (#239)

That's a topic we discussed a lot while building the [Specify format](https://docs.specifyapp.com/concepts/specify-design-token-format#supported-types).

My 2 cents: Array based values are necessary to express specific decisions, best is to use specific names for that matter, otherwise aliasing becomes a nightmare and users get lost.

I think, the best way to host array based value is by creating semantically meaningful types like: `gradients`, `shadows`, `spacings`, `colorList` (as proposed in #228)...
Doing so, we make sure we give users a type they can read about, and we can provide them with a clear documentation on how to use it.

On the aliasing side, let's make a simple thought experiment: we have a color token with an array of 2 values. This color token is referenced within the color property of a border token. Which color is the border going to use? So simple (and singular) types should host one value only.

As a starting point I would propose the following types:

**color**
```ts
type ColorList = Array<Color>
```

**dimension**
```ts
type Spacings = 
  | [Dimension]
  | [Dimension, Dimension] 
  | [Dimension, Dimension, Dimension] 
  | [Dimension, Dimension, Dimension, Dimension]
```

**number**
```ts
type NumberRange = [Number, Number, Number] // min, max, step
type NumberList = Array<Number>
```

**border**
```ts
type Borders = 
  | [Border]
  | [Border, Border] 
  | [Border, Border, Border] 
  | [Border, Border, Border, Border]
```

**shadow**
Related to #100
```ts
type Shadows = Array<Shadow>
```

**gradient**
```ts
type Gradients = Array<Gradient>
```

I can't think of related types for: fontFamily, fontWeight, duration, cubicBezier, strokeStyle, transition, typography.


Here how the aliasing might work:
```json
{
  "simpleBorder": {
    "$type": "border",
    "$value": {
      "color": "#000000",
      "width": "1px",
      "style": "solid"
    }
  },
  "multiBorder": {
    "$type": "borders",
    "$value": [
      "{simpleBorder}",
      {
        "color": "#FF0000",
        "width": "2px",
        "style": "dashed"
      }
    ]
  },
  "cardBorder": {
    "$type": "borders",
    "$value": "{multiBorder}"
  }
}
```
Leveraging both nested and semantic aliasing while keeping clear the role of each token.



-- 
GitHub Notification of comment by nclsndr
Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/239#issuecomment-2304100576 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Thursday, 22 August 2024 08:38:35 UTC