website: Update variables documentation & demos

[FlyersPh9]

Changes

• Add, correct, & expand upon documentation text.
• Add new demos for:
  • Durations
  • Component heights
• Add table of contents to variables page.
• Add link to https://unpkg.com/browse/@itwin/itwinui-variables/index.css for colleagues who want access to the variable values for mockups. This can possibly be removed when the last bullet point of Website: improvement #941 is addressed.
• Reorder sections to be alphabetical. This will be done after PR is approved to keep reviewing as easy as possible.

[FlyersPh9]

This demo is a bit intense. Suggestions for an alternative demo?

[mayank99]

Maybe a gentle fade?

[FlyersPh9]

I realized my animation was incorrect. It was applying the duration speed to expand AND collapse. I've added animation-direction: alternate; so now the animation is half of what it was. Still a bit intense, but better than before.

I will look into other options next time I work on this PR, with the time I have today this is the best I could do.

[mayank99]

A non-repeating animation that can be triggered by the user would be the best option. For inspiration, see https://open-props.style/#animations

[FlyersPh9]

Changed to require a user's click to trigger animation.

[mayank99]

hmm it's not working for me. did you forget to add a script?

Screen.Recording.2023-06-15.at.1.44.50.PM.mov

[mayank99]

you can fix it using this code:

DurationDemo.astro

---
import Wrapper from './_wrapper.astro';
const durations = ['0', '1', '2', '3'];
---

<Wrapper class='wrapper'>
  {
    durations.map((duration) => (
      <duration-item duration={`--iui-duration-${duration}`}>
        <button>{duration}</button>
      </duration-item>
    ))
  }
</Wrapper>

<script>
  customElements.define(
    'duration-item',
    class extends HTMLElement {
      connectedCallback() {
        const duration = getComputedStyle(this).getPropertyValue(this.getAttribute('duration'));
        const durationMs = Math.max(0.001, parseFloat(duration) * 1000);
        const button = this.querySelector('button');

        button.addEventListener('click', () => {
          button.animate([{ opacity: 0 }], { duration: durationMs });
        });
      }
    }
  );
</script>

<style>
  duration-item button {
    border: none;
    padding: var(--space-3);
    width: var(--space-8);
    height: var(--space-8);
    border-radius: var(--space-1);
    box-shadow: 0 0 4px hsl(0 0% 0% / 20%);
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: var(--iui-color-background);
    color: var(--iui-color-foreground-2);
    cursor: pointer;
  }
</style>

[FlyersPh9]

I just tested it in Brave & Safari, those both seems to be working.

Firefox however is not working. 😫

[FlyersPh9]

Thank you, the suggested code works in all browsers!

[mayank99]

Would be better to link to https://unpkg.com/@itwin/itwinui-variables/index.css as it will always redirect to latest version.

[FlyersPh9]

I linked to https://unpkg.com/browse/@itwin/[email protected]/index.css on purpose incase we were to introduce iTwinUI-Variables 3.x and we wanted to version our documentation site. But since we haven't introduced versioning to the doc site yet, maybe I'm thinking too far ahead.

[FlyersPh9]

Linking to https://unpkg.com/@itwin/itwinui-variables/index.css now that this branch is targeting dev.

[mayank99]

maybe use https://cdn.jsdelivr.net/npm/@itwin/itwinui-variables/index.css instead? every day i become less confident in unpkg because i'm seeing increasing errors and slowness

[FlyersPh9]

Ok, using this link instead.

[mayank99]

Should target dev branch, not main.

[gretanausedaite]

Should target dev branch, not main.

Should target main branch as we want to deploy it sooner than v3 changes comes. This update is needed for UX designers.

[mayank99]

Should target dev branch, not main.

Should target main branch as we want to deploy it sooner than v3 changes comes. This update is needed for UX designers.

It does not make any sense to maintain two diverging codebases with different versions of documentation when neither of them is close to finished. When we started work on v3, we decided that we will only focus on documenting the latest code. Why complicate things now and create additional work? We can give DEV url to anyone who wants to see these updates.

[adamhock]

A few grammar comments, but overall looks good!

[mayank99]

LGTM

[mayank99]

what's the benefit of alphabetically sorting? to me, it makes more sense to sort in a logical order / by importance.

[FlyersPh9]

We can take a guess as the order of importance, but alphabetical at least makes scanning the TOC easier. We have the left side nav sorted alphabetically as well.

[mayank99]

It's probably subjective but I would also like to reorder the left side nav a bit more logically - currently it can be a bit hard to find components. I think I would like to group the components into sections and have components within each section sorted alphabetically, and the sections themselves sorted logically

But we can punt on this decision and discuss it further internally, with some research and a vote. I'm ok with merging as-is for now.

cc @gretanausedaite

[gretanausedaite]

I agree with discussing it further internally.